1
0
mirror of https://github.com/jaandrle/deka-dom-el synced 2024-11-21 15:39:36 +01:00
deka-dom-el/index.d.ts
2023-11-21 21:22:04 +01:00

462 lines
22 KiB
TypeScript
Raw Blame History

This file contains invisible Unicode characters

This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

type CustomElementTagNameMap= { '#text': Text, '#comment': Comment }
declare global {
interface ddePublicElementTagNameMap{
}
}
type SupportedElement=
HTMLElementTagNameMap[keyof HTMLElementTagNameMap]
| SVGElementTagNameMap[keyof SVGElementTagNameMap]
| MathMLElementTagNameMap[keyof MathMLElementTagNameMap]
| CustomElementTagNameMap[keyof CustomElementTagNameMap]
| ddePublicElementTagNameMap[keyof ddePublicElementTagNameMap];
declare global {
type ddeComponentAttributes= Record<any, any> | undefined;
type ddeElementAddon<El extends SupportedElement | DocumentFragment>= (element: El)=> El | void;
}
type PascalCase= `${Capitalize<string>}${string}`;
type AttrsModified= {
/**
* Use string like in HTML (internally uses `*.setAttribute("style", *)`), or object representation (like DOM API).
*/
style: string | Partial<CSSStyleDeclaration>
/**
* Provide option to add/remove/toggle CSS clasess (index of object) using 1/0/-1. In fact `el.classList.toggle(class_name)` for `-1` and `el.classList.toggle(class_name, Boolean(...))` for others.
*/
classList: Record<string,-1|0|1|boolean>,
/**
* By default simiral to `className`, but also supports `string[]`
* */
className: string | (string|boolean|undefined)[];
/**
* Sets `aria-*` simiraly to `dataset`
* */
ariaset: Record<string,string>,
} & Record<`=${string}` | `data${PascalCase}` | `aria${PascalCase}`, string> & Record<`.${string}`, any>
/**
* Just element attributtes
*
* In most cases, you can use native propertie such as [MDN WEB/API/Element](https://developer.mozilla.org/en-US/docs/Web/API/Element) and so on (e.g. [`Text`](https://developer.mozilla.org/en-US/docs/Web/API/Text)).
*
* There is added support for `data[A-Z].*`/`aria[A-Z].*` to be converted to the kebab-case alternatives.
* @private
*/
type ElementAttributes<T extends SupportedElement>= Omit<T,keyof AttrsModified> & AttrsModified;
export function classListDeclarative<El extends SupportedElement>(element: El, classList: AttrsModified["classList"]): El
export function assign<El extends SupportedElement>(element: El, ...attrs_array: Partial<ElementAttributes<El>>[]): El
export function assignAttribute<El extends SupportedElement, ATT extends keyof ElementAttributes<El>>(element: El, attr: ATT, value: ElementAttributes<El>[ATT]): ElementAttributes<El>[ATT]
type ExtendedHTMLElementTagNameMap= HTMLElementTagNameMap & CustomElementTagNameMap & ddePublicElementTagNameMap
export function el<TAG extends keyof ExtendedHTMLElementTagNameMap>(
tag_name: TAG,
attrs?: string | Partial<ElementAttributes<ExtendedHTMLElementTagNameMap[TAG]>>,
...addons: ddeElementAddon<ExtendedHTMLElementTagNameMap[TAG]>[]
): ExtendedHTMLElementTagNameMap[TAG]
export function el<T>(
tag_name?: "<>",
): DocumentFragment
export function el<
A extends ddeComponentAttributes,
C extends (attr: Partial<A>)=> SupportedElement | DocumentFragment>(
fComponent: C,
attrs?: A | string,
...addons: ddeElementAddon<ReturnType<C>>[]
): ReturnType<C>
export function el(
tag_name: string,
attrs?: string | Record<string, any>,
...addons: ddeElementAddon<HTMLElement>[]
): HTMLElement
export function elNS(
namespace: "http://www.w3.org/2000/svg"
): <TAG extends keyof SVGElementTagNameMap, KEYS extends keyof SVGElementTagNameMap[TAG] & { d: string }>(
tag_name: TAG,
attrs?: string | Partial<{ [key in KEYS]: SVGElementTagNameMap[TAG][key] | string | number | boolean }>,
...addons: ddeElementAddon<SVGElementTagNameMap[TAG]>[]
)=> SVGElementTagNameMap[TAG]
export function elNS(
namespace: "http://www.w3.org/1998/Math/MathML"
): <TAG extends keyof MathMLElementTagNameMap, KEYS extends keyof MathMLElementTagNameMap[TAG] & { d: string }>(
tag_name: TAG,
attrs?: string | Partial<{ [key in KEYS]: MathMLElementTagNameMap[TAG][key] | string | number | boolean }>,
...addons: ddeElementAddon<MathMLElementTagNameMap[TAG]>[]
)=> MathMLElementTagNameMap[TAG]
export function elNS(
namespace: string
): (
tag_name: string,
attrs?: string | Record<string, any>,
...addons: ddeElementAddon<SupportedElement>[]
)=> SupportedElement
export function chainableAppend<EL extends SupportedElement>(el: EL): EL;
export function dispatchEvent(name: keyof DocumentEventMap | string, options?: EventInit):
(element: SupportedElement, data?: any)=> void;
export function dispatchEvent(name: keyof DocumentEventMap | string, options: EventInit | null, element: SupportedElement | (()=> SupportedElement)):
(data?: any)=> void;
interface On{
/** Listens to the DOM event. See {@link Document.addEventListener} */
<
EE extends ddeElementAddon<SupportedElement>,
El extends ( EE extends ddeElementAddon<infer El> ? El : never ),
Event extends keyof DocumentEventMap>(
type: Event,
listener: (this: El, ev: DocumentEventMap[Event]) => any,
options?: AddEventListenerOptions
) : EE;
<
EE extends ddeElementAddon<SupportedElement>,
El extends ( EE extends ddeElementAddon<infer El> ? El : never )>(
type: string,
listener: (this: El, ev: Event | CustomEvent ) => any,
options?: AddEventListenerOptions
) : EE;
/** Listens to the element is connected to the live DOM. In case of custom elements uses [`connectedCallback`](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements#custom_element_lifecycle_callbacks), or {@link MutationObserver} else where */
connected<
EE extends ddeElementAddon<SupportedElement>,
El extends ( EE extends ddeElementAddon<infer El> ? El : never )
>(
listener: (this: El, event: CustomEvent<void>) => any,
options?: AddEventListenerOptions
) : EE;
/** Listens to the element is disconnected from the live DOM. In case of custom elements uses [`disconnectedCallback`](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements#custom_element_lifecycle_callbacks), or {@link MutationObserver} else where */
disconnected<
EE extends ddeElementAddon<SupportedElement>,
El extends ( EE extends ddeElementAddon<infer El> ? El : never )
>(
listener: (this: El, event: CustomEvent<void>) => any,
options?: AddEventListenerOptions
) : EE;
/** Listens to the element attribute changes. In case of custom elements uses [`attributeChangedCallback`](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements#custom_element_lifecycle_callbacks), or {@link MutationObserver} else where */
attributeChanged<
EE extends ddeElementAddon<SupportedElement>,
El extends ( EE extends ddeElementAddon<infer El> ? El : never )
>(
listener: (this: El, event: CustomEvent<[ string, string ]>) => any,
options?: AddEventListenerOptions
) : EE;
}
export const on: On;
type Scope= { scope: Node | Function | Object, host: ddeElementAddon<any>, custom_element: false | HTMLElement, prevent: boolean }
/** Current scope created last time the `el(Function)` was invoke. (Or {@link scope.push}) */
export const scope: {
current: Scope,
/** Stops all automatizations. E. g. signals used as attributes in current scope
* registers removing these listeners (and clean signal if no other listeners are detected)
* on `disconnected` event. */
preventDefault<T extends boolean>(prevent: T): T,
/**
* This represents reference to the current host element — `scope.host()`.
* It can be also used to register Addon (function to be called when component is initized)
* — `scope.host(on.connected(console.log))`.
* */
host: ddeElementAddon<any>,
state: Scope[],
/** Adds new child scope. All attributes are inherited by default. */
push(scope: Partial<Scope>): ReturnType<Array<Scope>["push"]>,
/** Adds root scope as a child of the current scope. */
pushRoot(): ReturnType<Array<Scope>["push"]>,
/** Removes last/current child scope. */
pop(): ReturnType<Array<Scope>["pop"]>,
};
/*
* TODO TypeScript HACK (better way?)
* this doesnt works
* ```ts
* interface element<el> extends Node{
* prototype: el;
* append(...els: (SupportedElement | DocumentFragment | string | element<SupportedElement | DocumentFragment>)[]): el
* }
* export function el<T>(
* tag_name?: "<>",
* ): element<DocumentFragment>
* ```
* …as its complains here
* ```ts
* const d= el("div");
* const f= (a: HTMLDivElement)=> a;
* f(d); //←
* document.head.append( //←
* el("script", { src: "https://flems.io/flems.html", type: "text/javascript", charset: "utf-8" }),
* );
* ```
* TODO for SVG
* */
type ddeAppend<el>= (...nodes: (Node | string)[])=> el;
declare global{
interface HTMLAnchorElement{
/** Elements returned by {@link el} return parent element for `.append` method. **Regullarly created elements are untouched.** */
append: ddeAppend<HTMLAnchorElement>;
}
interface HTMLElement{
/** Elements returned by {@link el} return parent element for `.append` method. **Regullarly created elements are untouched.** */
append: ddeAppend<HTMLElement>;
}
interface HTMLAreaElement{
/** Elements returned by {@link el} return parent element for `.append` method. **Regullarly created elements are untouched.** */
append: ddeAppend<HTMLAreaElement>;
}
interface HTMLAudioElement{
/** Elements returned by {@link el} return parent element for `.append` method. **Regullarly created elements are untouched.** */
append: ddeAppend<HTMLAudioElement>;
}
interface HTMLBaseElement{
/** Elements returned by {@link el} return parent element for `.append` method. **Regullarly created elements are untouched.** */
append: ddeAppend<HTMLBaseElement>;
}
interface HTMLQuoteElement{
/** Elements returned by {@link el} return parent element for `.append` method. **Regullarly created elements are untouched.** */
append: ddeAppend<HTMLQuoteElement>;
}
interface HTMLBodyElement{
/** Elements returned by {@link el} return parent element for `.append` method. **Regullarly created elements are untouched.** */
append: ddeAppend<HTMLBodyElement>;
}
interface HTMLBRElement{
/** Elements returned by {@link el} return parent element for `.append` method. **Regullarly created elements are untouched.** */
append: ddeAppend<HTMLBRElement>;
}
interface HTMLButtonElement{
/** Elements returned by {@link el} return parent element for `.append` method. **Regullarly created elements are untouched.** */
append: ddeAppend<HTMLButtonElement>;
}
interface HTMLCanvasElement{
/** Elements returned by {@link el} return parent element for `.append` method. **Regullarly created elements are untouched.** */
append: ddeAppend<HTMLCanvasElement>;
}
interface HTMLTableCaptionElement{
/** Elements returned by {@link el} return parent element for `.append` method. **Regullarly created elements are untouched.** */
append: ddeAppend<HTMLTableCaptionElement>;
}
interface HTMLTableColElement{
/** Elements returned by {@link el} return parent element for `.append` method. **Regullarly created elements are untouched.** */
append: ddeAppend<HTMLTableColElement>;
}
interface HTMLTableColElement{
/** Elements returned by {@link el} return parent element for `.append` method. **Regullarly created elements are untouched.** */
append: ddeAppend<HTMLTableColElement>;
}
interface HTMLDataElement{
/** Elements returned by {@link el} return parent element for `.append` method. **Regullarly created elements are untouched.** */
append: ddeAppend<HTMLDataElement>;
}
interface HTMLDataListElement{
/** Elements returned by {@link el} return parent element for `.append` method. **Regullarly created elements are untouched.** */
append: ddeAppend<HTMLDataListElement>;
}
interface HTMLModElement{
/** Elements returned by {@link el} return parent element for `.append` method. **Regullarly created elements are untouched.** */
append: ddeAppend<HTMLModElement>;
}
interface HTMLDetailsElement{
/** Elements returned by {@link el} return parent element for `.append` method. **Regullarly created elements are untouched.** */
append: ddeAppend<HTMLDetailsElement>;
}
interface HTMLDialogElement{
/** Elements returned by {@link el} return parent element for `.append` method. **Regullarly created elements are untouched.** */
append: ddeAppend<HTMLDialogElement>;
}
interface HTMLDivElement{
/** Elements returned by {@link el} return parent element for `.append` method. **Regullarly created elements are untouched.** */
append: ddeAppend<HTMLDivElement>;
}
interface HTMLDListElement{
/** Elements returned by {@link el} return parent element for `.append` method. **Regullarly created elements are untouched.** */
append: ddeAppend<HTMLDListElement>;
}
interface HTMLEmbedElement{
/** Elements returned by {@link el} return parent element for `.append` method. **Regullarly created elements are untouched.** */
append: ddeAppend<HTMLEmbedElement>;
}
interface HTMLFieldSetElement{
/** Elements returned by {@link el} return parent element for `.append` method. **Regullarly created elements are untouched.** */
append: ddeAppend<HTMLFieldSetElement>;
}
interface HTMLFormElement{
/** Elements returned by {@link el} return parent element for `.append` method. **Regullarly created elements are untouched.** */
append: ddeAppend<HTMLFormElement>;
}
interface HTMLHeadingElement{
/** Elements returned by {@link el} return parent element for `.append` method. **Regullarly created elements are untouched.** */
append: ddeAppend<HTMLHeadingElement>;
}
interface HTMLHeadElement{
/** Elements returned by {@link el} return parent element for `.append` method. **Regullarly created elements are untouched.** */
append: ddeAppend<HTMLHeadElement>;
}
interface HTMLHRElement{
/** Elements returned by {@link el} return parent element for `.append` method. **Regullarly created elements are untouched.** */
append: ddeAppend<HTMLHRElement>;
}
interface HTMLHtmlElement{
/** Elements returned by {@link el} return parent element for `.append` method. **Regullarly created elements are untouched.** */
append: ddeAppend<HTMLHtmlElement>;
}
interface HTMLIFrameElement{
/** Elements returned by {@link el} return parent element for `.append` method. **Regullarly created elements are untouched.** */
append: ddeAppend<HTMLIFrameElement>;
}
interface HTMLImageElement{
/** Elements returned by {@link el} return parent element for `.append` method. **Regullarly created elements are untouched.** */
append: ddeAppend<HTMLImageElement>;
}
interface HTMLInputElement{
/** Elements returned by {@link el} return parent element for `.append` method. **Regullarly created elements are untouched.** */
append: ddeAppend<HTMLInputElement>;
}
interface HTMLLabelElement{
/** Elements returned by {@link el} return parent element for `.append` method. **Regullarly created elements are untouched.** */
append: ddeAppend<HTMLLabelElement>;
}
interface HTMLLegendElement{
/** Elements returned by {@link el} return parent element for `.append` method. **Regullarly created elements are untouched.** */
append: ddeAppend<HTMLLegendElement>;
}
interface HTMLLIElement{
/** Elements returned by {@link el} return parent element for `.append` method. **Regullarly created elements are untouched.** */
append: ddeAppend<HTMLLIElement>;
}
interface HTMLLinkElement{
/** Elements returned by {@link el} return parent element for `.append` method. **Regullarly created elements are untouched.** */
append: ddeAppend<HTMLLinkElement>;
}
interface HTMLMapElement{
/** Elements returned by {@link el} return parent element for `.append` method. **Regullarly created elements are untouched.** */
append: ddeAppend<HTMLMapElement>;
}
interface HTMLMenuElement{
/** Elements returned by {@link el} return parent element for `.append` method. **Regullarly created elements are untouched.** */
append: ddeAppend<HTMLMenuElement>;
}
interface HTMLMetaElement{
/** Elements returned by {@link el} return parent element for `.append` method. **Regullarly created elements are untouched.** */
append: ddeAppend<HTMLMetaElement>;
}
interface HTMLMeterElement{
/** Elements returned by {@link el} return parent element for `.append` method. **Regullarly created elements are untouched.** */
append: ddeAppend<HTMLMeterElement>;
}
interface HTMLObjectElement{
/** Elements returned by {@link el} return parent element for `.append` method. **Regullarly created elements are untouched.** */
append: ddeAppend<HTMLObjectElement>;
}
interface HTMLOListElement{
/** Elements returned by {@link el} return parent element for `.append` method. **Regullarly created elements are untouched.** */
append: ddeAppend<HTMLOListElement>;
}
interface HTMLOptGroupElement{
/** Elements returned by {@link el} return parent element for `.append` method. **Regullarly created elements are untouched.** */
append: ddeAppend<HTMLOptGroupElement>;
}
interface HTMLOptionElement{
/** Elements returned by {@link el} return parent element for `.append` method. **Regullarly created elements are untouched.** */
append: ddeAppend<HTMLOptionElement>;
}
interface HTMLOutputElement{
/** Elements returned by {@link el} return parent element for `.append` method. **Regullarly created elements are untouched.** */
append: ddeAppend<HTMLOutputElement>;
}
interface HTMLParagraphElement{
/** Elements returned by {@link el} return parent element for `.append` method. **Regullarly created elements are untouched.** */
append: ddeAppend<HTMLParagraphElement>;
}
interface HTMLPictureElement{
/** Elements returned by {@link el} return parent element for `.append` method. **Regullarly created elements are untouched.** */
append: ddeAppend<HTMLPictureElement>;
}
interface HTMLPreElement{
/** Elements returned by {@link el} return parent element for `.append` method. **Regullarly created elements are untouched.** */
append: ddeAppend<HTMLPreElement>;
}
interface HTMLProgressElement{
/** Elements returned by {@link el} return parent element for `.append` method. **Regullarly created elements are untouched.** */
append: ddeAppend<HTMLProgressElement>;
}
interface HTMLScriptElement{
/** Elements returned by {@link el} return parent element for `.append` method. **Regullarly created elements are untouched.** */
append: ddeAppend<HTMLScriptElement>;
}
interface HTMLSelectElement{
/** Elements returned by {@link el} return parent element for `.append` method. **Regullarly created elements are untouched.** */
append: ddeAppend<HTMLSelectElement>;
}
interface HTMLSlotElement{
/** Elements returned by {@link el} return parent element for `.append` method. **Regullarly created elements are untouched.** */
append: ddeAppend<HTMLSlotElement>;
}
interface HTMLSourceElement{
/** Elements returned by {@link el} return parent element for `.append` method. **Regullarly created elements are untouched.** */
append: ddeAppend<HTMLSourceElement>;
}
interface HTMLSpanElement{
/** Elements returned by {@link el} return parent element for `.append` method. **Regullarly created elements are untouched.** */
append: ddeAppend<HTMLSpanElement>;
}
interface HTMLStyleElement{
/** Elements returned by {@link el} return parent element for `.append` method. **Regullarly created elements are untouched.** */
append: ddeAppend<HTMLStyleElement>;
}
interface HTMLTableElement{
/** Elements returned by {@link el} return parent element for `.append` method. **Regullarly created elements are untouched.** */
append: ddeAppend<HTMLTableElement>;
}
interface HTMLTableSectionElement{
/** Elements returned by {@link el} return parent element for `.append` method. **Regullarly created elements are untouched.** */
append: ddeAppend<HTMLTableSectionElement>;
}
interface HTMLTableCellElement{
/** Elements returned by {@link el} return parent element for `.append` method. **Regullarly created elements are untouched.** */
append: ddeAppend<HTMLTableCellElement>;
}
interface HTMLTemplateElement{
/** Elements returned by {@link el} return parent element for `.append` method. **Regullarly created elements are untouched.** */
append: ddeAppend<HTMLTemplateElement>;
}
interface HTMLTextAreaElement{
/** Elements returned by {@link el} return parent element for `.append` method. **Regullarly created elements are untouched.** */
append: ddeAppend<HTMLTextAreaElement>;
}
interface HTMLTableCellElement{
/** Elements returned by {@link el} return parent element for `.append` method. **Regullarly created elements are untouched.** */
append: ddeAppend<HTMLTableCellElement>;
}
interface HTMLTimeElement{
/** Elements returned by {@link el} return parent element for `.append` method. **Regullarly created elements are untouched.** */
append: ddeAppend<HTMLTimeElement>;
}
interface HTMLTitleElement{
/** Elements returned by {@link el} return parent element for `.append` method. **Regullarly created elements are untouched.** */
append: ddeAppend<HTMLTitleElement>;
}
interface HTMLTableRowElement{
/** Elements returned by {@link el} return parent element for `.append` method. **Regullarly created elements are untouched.** */
append: ddeAppend<HTMLTableRowElement>;
}
interface HTMLTrackElement{
/** Elements returned by {@link el} return parent element for `.append` method. **Regullarly created elements are untouched.** */
append: ddeAppend<HTMLTrackElement>;
}
interface HTMLUListElement{
/** Elements returned by {@link el} return parent element for `.append` method. **Regullarly created elements are untouched.** */
append: ddeAppend<HTMLUListElement>;
}
interface HTMLVideoElement{
/** Elements returned by {@link el} return parent element for `.append` method. **Regullarly created elements are untouched.** */
append: ddeAppend<HTMLVideoElement>;
}
interface DocumentFragment{
/** Elements returned by {@link el} return parent element for `.append` method. **Regullarly created elements are untouched.** */
append: ddeAppend<DocumentFragment>;
}
interface SVGElement{
/** Elements returned by {@link el} return parent element for `.append` method. **Regullarly created elements are untouched.** */
append: ddeAppend<SVGElement>;
}
}