jaandrle/deka-dom-el
1
0
Fork 0
mirror of https://github.com/jaandrle/deka-dom-el synced 2024-11-23 00:59:38 +01:00
Code Packages Releases Activity

Compare commits

base: jaandrle:c0fdec1e1e19a726f13e4b91ac95dabeb253b0b8
Branches Tags
jaandrle:main
jaandrle:dev-refact
...
compare: jaandrle:a2b4e19d1b7df9c9596e80c1b5e6ad59efd6c061
Branches Tags
jaandrle:dev-refact
jaandrle:main

3 Commits
c0fdec1e1e ... a2b4e19d1b

Author SHA1 Message Date
Jan Andrle
a2b4e19d1b
🐛 docs 2023-11-21 17:24:40 +01:00
Jan Andrle
96c84227e9
v0.7.1 (dispatchEvent, docs) 2023-11-21 17:19:59 +01:00
Jan Andrle
ae0455f913
🔨 docs+addons 2023-11-21 14:37:57 +01:00
23 changed files with 340 additions and 188 deletions
Show Stats Expand all files Collapse all files

2
dist/dde-with-signals.js vendored
View File

File diff suppressed because one or more lines are too long

2
dist/dde.js vendored
View File

File diff suppressed because one or more lines are too long

96
dist/esm-with-signals.d.ts vendored
View File

@ -10,9 +10,11 @@ type SupportedElement=
| CustomElementTagNameMap[keyof CustomElementTagNameMap] | CustomElementTagNameMap[keyof CustomElementTagNameMap]
| ddePublicElementTagNameMap[keyof ddePublicElementTagNameMap]; | ddePublicElementTagNameMap[keyof ddePublicElementTagNameMap];
declare global { declare global {
type ddeComponentAttributes= Record<any, any> | undefined | string; type ddeComponentAttributes= Record<any, any> | undefined;
type ddeElementModifier<El extends SupportedElement | DocumentFragment>= (element: El)=> El; type ddeElementAddon<El extends SupportedElement | DocumentFragment>= (element: El)=> El | void;
} }
type PascalCase=
`${Capitalize<string>}${string}`;
type AttrsModified= { type AttrsModified= {
/** /**
* Use string like in HTML (internally uses `*.setAttribute("style", *)`), or object representation (like DOM API). * Use string like in HTML (internally uses `*.setAttribute("style", *)`), or object representation (like DOM API).
@ -30,7 +32,7 @@ type AttrsModified= {
* Sets `aria-*` simiraly to `dataset` * Sets `aria-*` simiraly to `dataset`
* */ * */
ariaset: Record<string,string>, ariaset: Record<string,string>,
} } & Record<`=${string}` | `data${PascalCase}` | `aria${PascalCase}`, string> & Record<`.${string}`, any>
/** /**
* Just element attributtes * Just element attributtes
* *
@ -40,89 +42,105 @@ type AttrsModified= {
* @private * @private
*/ */
type ElementAttributes<T extends SupportedElement>= Omit<T,keyof AttrsModified> & AttrsModified; 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 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 type ExtendedHTMLElementTagNameMap= HTMLElementTagNameMap & CustomElementTagNameMap & ddePublicElementTagNameMap
export function el<TAG extends keyof ExtendedHTMLElementTagNameMap>( export function el<TAG extends keyof ExtendedHTMLElementTagNameMap>(
tag_name: TAG, tag_name: TAG,
attrs?: string | Partial<ElementAttributes<ExtendedHTMLElementTagNameMap[TAG]>>, attrs?: string | Partial<ElementAttributes<ExtendedHTMLElementTagNameMap[TAG]>>,
...modifiers: ddeElementModifier<ExtendedHTMLElementTagNameMap[TAG]>[] ...addons: ddeElementAddon<ExtendedHTMLElementTagNameMap[TAG]>[]
): ExtendedHTMLElementTagNameMap[TAG] ): ExtendedHTMLElementTagNameMap[TAG]
export function el<T>( export function el<T>(
tag_name?: "<>", tag_name?: "<>",
): DocumentFragment ): DocumentFragment
export function el< export function el<
A extends ddeComponentAttributes, A extends ddeComponentAttributes,
C extends (attr: A)=> SupportedElement | DocumentFragment>( C extends (attr: Partial<A>)=> SupportedElement | DocumentFragment>(
fComponent: C, fComponent: C,
attrs?: A, attrs?: A | string,
...modifiers: ddeElementModifier<ReturnType<C>>[] ...addons: ddeElementAddon<ReturnType<C>>[]
): ReturnType<C> ): ReturnType<C>
export function el( export function el(
tag_name: string, tag_name: string,
attrs?: string | Record<string, any>, attrs?: string | Record<string, any>,
...modifiers: ddeElementModifier<HTMLElement>[] ...addons: ddeElementAddon<HTMLElement>[]
): HTMLElement ): HTMLElement
export function elNS( export function elNS(
namespace: "http://www.w3.org/2000/svg" namespace: "http://www.w3.org/2000/svg"
): <TAG extends keyof SVGElementTagNameMap, KEYS extends keyof SVGElementTagNameMap[TAG] & { d: string }>( ): <TAG extends keyof SVGElementTagNameMap, KEYS extends keyof SVGElementTagNameMap[TAG] & { d: string }>(
tag_name: TAG, tag_name: TAG,
attrs?: string | Partial<{ [key in KEYS]: SVGElementTagNameMap[TAG][key] | string | number | boolean }>, attrs?: string | Partial<{ [key in KEYS]: SVGElementTagNameMap[TAG][key] | string | number | boolean }>,
...modifiers: ddeElementModifier<SVGElementTagNameMap[TAG]>[] ...addons: ddeElementAddon<SVGElementTagNameMap[TAG]>[]
)=> SVGElementTagNameMap[TAG] )=> SVGElementTagNameMap[TAG]
export function elNS( export function elNS(
namespace: "http://www.w3.org/1998/Math/MathML" namespace: "http://www.w3.org/1998/Math/MathML"
): <TAG extends keyof MathMLElementTagNameMap, KEYS extends keyof MathMLElementTagNameMap[TAG] & { d: string }>( ): <TAG extends keyof MathMLElementTagNameMap, KEYS extends keyof MathMLElementTagNameMap[TAG] & { d: string }>(
tag_name: TAG, tag_name: TAG,
attrs?: string | Partial<{ [key in KEYS]: MathMLElementTagNameMap[TAG][key] | string | number | boolean }>, attrs?: string | Partial<{ [key in KEYS]: MathMLElementTagNameMap[TAG][key] | string | number | boolean }>,
...modifiers: ddeElementModifier<MathMLElementTagNameMap[TAG]>[] ...addons: ddeElementAddon<MathMLElementTagNameMap[TAG]>[]
)=> MathMLElementTagNameMap[TAG] )=> MathMLElementTagNameMap[TAG]
export function elNS( export function elNS(
namespace: string namespace: string
): ( ): (
tag_name: string, tag_name: string,
attrs?: string | Record<string, any>, attrs?: string | Record<string, any>,
...modifiers: ddeElementModifier<SupportedElement>[] ...addons: ddeElementAddon<SupportedElement>[]
)=> SupportedElement )=> SupportedElement
export function chainableAppend<EL extends SupportedElement>(el: EL): EL; export function chainableAppend<EL extends SupportedElement>(el: EL): EL;
export function dispatchEvent(element: SupportedElement, name: keyof DocumentEventMap): void;
export function dispatchEvent(element: SupportedElement, name: string, data: any): void; export function dispatchEvent(name: keyof DocumentEventMap | string, options?: EventInit):
(element: SupportedElement, data?: any)=> void;
interface On{ interface On{
/** Listens to the DOM event. See {@link Document.addEventListener} */ /** Listens to the DOM event. See {@link Document.addEventListener} */
< <
EE extends ddeElementModifier<SupportedElement>, EE extends ddeElementAddon<SupportedElement>,
El extends ( EE extends ddeElementModifier<infer El> ? El : never ), El extends ( EE extends ddeElementAddon<infer El> ? El : never ),
Event extends keyof DocumentEventMap>( Event extends keyof DocumentEventMap>(
type: Event, type: Event,
listener: (this: El, ev: DocumentEventMap[Event]) => any, listener: (this: El, ev: DocumentEventMap[Event]) => any,
options?: AddEventListenerOptions options?: AddEventListenerOptions
) : EE; ) : 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 */ /** 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< connected<
EE extends ddeElementModifier<SupportedElement>, EE extends ddeElementAddon<SupportedElement>,
El extends ( EE extends ddeElementModifier<infer El> ? El : never ) El extends ( EE extends ddeElementAddon<infer El> ? El : never )
>( >(
listener: (el: El) => any, listener: (this: El, event: CustomEvent<void>) => any,
options?: AddEventListenerOptions options?: AddEventListenerOptions
) : EE; ) : 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 */ /** 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< disconnected<
EE extends ddeElementModifier<SupportedElement>, EE extends ddeElementAddon<SupportedElement>,
El extends ( EE extends ddeElementModifier<infer El> ? El : never ) El extends ( EE extends ddeElementAddon<infer El> ? El : never )
>( >(
listener: (el: El) => any, listener: (this: El, event: CustomEvent<void>) => any,
options?: AddEventListenerOptions options?: AddEventListenerOptions
) : EE; ) : 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 */ /** 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< attributeChanged<
EE extends ddeElementModifier<SupportedElement>, EE extends ddeElementAddon<SupportedElement>,
El extends ( EE extends ddeElementModifier<infer El> ? El : never ) El extends ( EE extends ddeElementAddon<infer El> ? El : never )
>( >(
listener: (el: El) => any, listener: (this: El, event: CustomEvent<[ string, string ]>) => any,
options?: AddEventListenerOptions options?: AddEventListenerOptions
) : EE; ) : EE;
} }
export const on: On; export const on: On;
type Scope= { scope: Node | Function | Object, host: ddeElementModifier<any>, custom_element: false | HTMLElement, prevent: boolean }
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}) */ /** Current scope created last time the `el(Function)` was invoke. (Or {@link scope.push}) */
export const scope: { export const scope: {
current: Scope, current: Scope,
@ -132,10 +150,10 @@ export const scope: {
preventDefault<T extends boolean>(prevent: T): T, preventDefault<T extends boolean>(prevent: T): T,
/** /**
* This represents reference to the current host element — `scope.host()`. * This represents reference to the current host element — `scope.host()`.
* It can be also used to register Modifier (function to be called when component is initized) * It can be also used to register Addon (function to be called when component is initized)
* — `scope.host(on.connected(console.log))`. * — `scope.host(on.connected(console.log))`.
* */ * */
host: ddeElementModifier<any>, host: ddeElementAddon<any>,
state: Scope[], state: Scope[],
/** Adds new child scope. All attributes are inherited by default. */ /** Adds new child scope. All attributes are inherited by default. */
@ -145,29 +163,7 @@ export const scope: {
/** Removes last/current child scope. */ /** Removes last/current child scope. */
pop(): ReturnType<Array<Scope>["pop"]>, 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; type ddeAppend<el>= (...nodes: (Node | string)[])=> el;
declare global{ declare global{
interface HTMLAnchorElement{ interface HTMLAnchorElement{

2
dist/esm-with-signals.js vendored
View File

File diff suppressed because one or more lines are too long

96
dist/esm.d.ts vendored
View File

@ -10,9 +10,11 @@ type SupportedElement=
| CustomElementTagNameMap[keyof CustomElementTagNameMap] | CustomElementTagNameMap[keyof CustomElementTagNameMap]
| ddePublicElementTagNameMap[keyof ddePublicElementTagNameMap]; | ddePublicElementTagNameMap[keyof ddePublicElementTagNameMap];
declare global { declare global {
type ddeComponentAttributes= Record<any, any> | undefined | string; type ddeComponentAttributes= Record<any, any> | undefined;
type ddeElementModifier<El extends SupportedElement | DocumentFragment>= (element: El)=> El; type ddeElementAddon<El extends SupportedElement | DocumentFragment>= (element: El)=> El | void;
} }
type PascalCase=
`${Capitalize<string>}${string}`;
type AttrsModified= { type AttrsModified= {
/** /**
* Use string like in HTML (internally uses `*.setAttribute("style", *)`), or object representation (like DOM API). * Use string like in HTML (internally uses `*.setAttribute("style", *)`), or object representation (like DOM API).
@ -30,7 +32,7 @@ type AttrsModified= {
* Sets `aria-*` simiraly to `dataset` * Sets `aria-*` simiraly to `dataset`
* */ * */
ariaset: Record<string,string>, ariaset: Record<string,string>,
} } & Record<`=${string}` | `data${PascalCase}` | `aria${PascalCase}`, string> & Record<`.${string}`, any>
/** /**
* Just element attributtes * Just element attributtes
* *
@ -40,89 +42,105 @@ type AttrsModified= {
* @private * @private
*/ */
type ElementAttributes<T extends SupportedElement>= Omit<T,keyof AttrsModified> & AttrsModified; 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 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 type ExtendedHTMLElementTagNameMap= HTMLElementTagNameMap & CustomElementTagNameMap & ddePublicElementTagNameMap
export function el<TAG extends keyof ExtendedHTMLElementTagNameMap>( export function el<TAG extends keyof ExtendedHTMLElementTagNameMap>(
tag_name: TAG, tag_name: TAG,
attrs?: string | Partial<ElementAttributes<ExtendedHTMLElementTagNameMap[TAG]>>, attrs?: string | Partial<ElementAttributes<ExtendedHTMLElementTagNameMap[TAG]>>,
...modifiers: ddeElementModifier<ExtendedHTMLElementTagNameMap[TAG]>[] ...addons: ddeElementAddon<ExtendedHTMLElementTagNameMap[TAG]>[]
): ExtendedHTMLElementTagNameMap[TAG] ): ExtendedHTMLElementTagNameMap[TAG]
export function el<T>( export function el<T>(
tag_name?: "<>", tag_name?: "<>",
): DocumentFragment ): DocumentFragment
export function el< export function el<
A extends ddeComponentAttributes, A extends ddeComponentAttributes,
C extends (attr: A)=> SupportedElement | DocumentFragment>( C extends (attr: Partial<A>)=> SupportedElement | DocumentFragment>(
fComponent: C, fComponent: C,
attrs?: A, attrs?: A | string,
...modifiers: ddeElementModifier<ReturnType<C>>[] ...addons: ddeElementAddon<ReturnType<C>>[]
): ReturnType<C> ): ReturnType<C>
export function el( export function el(
tag_name: string, tag_name: string,
attrs?: string | Record<string, any>, attrs?: string | Record<string, any>,
...modifiers: ddeElementModifier<HTMLElement>[] ...addons: ddeElementAddon<HTMLElement>[]
): HTMLElement ): HTMLElement
export function elNS( export function elNS(
namespace: "http://www.w3.org/2000/svg" namespace: "http://www.w3.org/2000/svg"
): <TAG extends keyof SVGElementTagNameMap, KEYS extends keyof SVGElementTagNameMap[TAG] & { d: string }>( ): <TAG extends keyof SVGElementTagNameMap, KEYS extends keyof SVGElementTagNameMap[TAG] & { d: string }>(
tag_name: TAG, tag_name: TAG,
attrs?: string | Partial<{ [key in KEYS]: SVGElementTagNameMap[TAG][key] | string | number | boolean }>, attrs?: string | Partial<{ [key in KEYS]: SVGElementTagNameMap[TAG][key] | string | number | boolean }>,
...modifiers: ddeElementModifier<SVGElementTagNameMap[TAG]>[] ...addons: ddeElementAddon<SVGElementTagNameMap[TAG]>[]
)=> SVGElementTagNameMap[TAG] )=> SVGElementTagNameMap[TAG]
export function elNS( export function elNS(
namespace: "http://www.w3.org/1998/Math/MathML" namespace: "http://www.w3.org/1998/Math/MathML"
): <TAG extends keyof MathMLElementTagNameMap, KEYS extends keyof MathMLElementTagNameMap[TAG] & { d: string }>( ): <TAG extends keyof MathMLElementTagNameMap, KEYS extends keyof MathMLElementTagNameMap[TAG] & { d: string }>(
tag_name: TAG, tag_name: TAG,
attrs?: string | Partial<{ [key in KEYS]: MathMLElementTagNameMap[TAG][key] | string | number | boolean }>, attrs?: string | Partial<{ [key in KEYS]: MathMLElementTagNameMap[TAG][key] | string | number | boolean }>,
...modifiers: ddeElementModifier<MathMLElementTagNameMap[TAG]>[] ...addons: ddeElementAddon<MathMLElementTagNameMap[TAG]>[]
)=> MathMLElementTagNameMap[TAG] )=> MathMLElementTagNameMap[TAG]
export function elNS( export function elNS(
namespace: string namespace: string
): ( ): (
tag_name: string, tag_name: string,
attrs?: string | Record<string, any>, attrs?: string | Record<string, any>,
...modifiers: ddeElementModifier<SupportedElement>[] ...addons: ddeElementAddon<SupportedElement>[]
)=> SupportedElement )=> SupportedElement
export function chainableAppend<EL extends SupportedElement>(el: EL): EL; export function chainableAppend<EL extends SupportedElement>(el: EL): EL;
export function dispatchEvent(element: SupportedElement, name: keyof DocumentEventMap): void;
export function dispatchEvent(element: SupportedElement, name: string, data: any): void; export function dispatchEvent(name: keyof DocumentEventMap | string, options?: EventInit):
(element: SupportedElement, data?: any)=> void;
interface On{ interface On{
/** Listens to the DOM event. See {@link Document.addEventListener} */ /** Listens to the DOM event. See {@link Document.addEventListener} */
< <
EE extends ddeElementModifier<SupportedElement>, EE extends ddeElementAddon<SupportedElement>,
El extends ( EE extends ddeElementModifier<infer El> ? El : never ), El extends ( EE extends ddeElementAddon<infer El> ? El : never ),
Event extends keyof DocumentEventMap>( Event extends keyof DocumentEventMap>(
type: Event, type: Event,
listener: (this: El, ev: DocumentEventMap[Event]) => any, listener: (this: El, ev: DocumentEventMap[Event]) => any,
options?: AddEventListenerOptions options?: AddEventListenerOptions
) : EE; ) : 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 */ /** 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< connected<
EE extends ddeElementModifier<SupportedElement>, EE extends ddeElementAddon<SupportedElement>,
El extends ( EE extends ddeElementModifier<infer El> ? El : never ) El extends ( EE extends ddeElementAddon<infer El> ? El : never )
>( >(
listener: (el: El) => any, listener: (this: El, event: CustomEvent<void>) => any,
options?: AddEventListenerOptions options?: AddEventListenerOptions
) : EE; ) : 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 */ /** 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< disconnected<
EE extends ddeElementModifier<SupportedElement>, EE extends ddeElementAddon<SupportedElement>,
El extends ( EE extends ddeElementModifier<infer El> ? El : never ) El extends ( EE extends ddeElementAddon<infer El> ? El : never )
>( >(
listener: (el: El) => any, listener: (this: El, event: CustomEvent<void>) => any,
options?: AddEventListenerOptions options?: AddEventListenerOptions
) : EE; ) : 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 */ /** 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< attributeChanged<
EE extends ddeElementModifier<SupportedElement>, EE extends ddeElementAddon<SupportedElement>,
El extends ( EE extends ddeElementModifier<infer El> ? El : never ) El extends ( EE extends ddeElementAddon<infer El> ? El : never )
>( >(
listener: (el: El) => any, listener: (this: El, event: CustomEvent<[ string, string ]>) => any,
options?: AddEventListenerOptions options?: AddEventListenerOptions
) : EE; ) : EE;
} }
export const on: On; export const on: On;
type Scope= { scope: Node | Function | Object, host: ddeElementModifier<any>, custom_element: false | HTMLElement, prevent: boolean }
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}) */ /** Current scope created last time the `el(Function)` was invoke. (Or {@link scope.push}) */
export const scope: { export const scope: {
current: Scope, current: Scope,
@ -132,10 +150,10 @@ export const scope: {
preventDefault<T extends boolean>(prevent: T): T, preventDefault<T extends boolean>(prevent: T): T,
/** /**
* This represents reference to the current host element — `scope.host()`. * This represents reference to the current host element — `scope.host()`.
* It can be also used to register Modifier (function to be called when component is initized) * It can be also used to register Addon (function to be called when component is initized)
* — `scope.host(on.connected(console.log))`. * — `scope.host(on.connected(console.log))`.
* */ * */
host: ddeElementModifier<any>, host: ddeElementAddon<any>,
state: Scope[], state: Scope[],
/** Adds new child scope. All attributes are inherited by default. */ /** Adds new child scope. All attributes are inherited by default. */
@ -145,29 +163,7 @@ export const scope: {
/** Removes last/current child scope. */ /** Removes last/current child scope. */
pop(): ReturnType<Array<Scope>["pop"]>, 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; type ddeAppend<el>= (...nodes: (Node | string)[])=> el;
declare global{ declare global{
interface HTMLAnchorElement{ interface HTMLAnchorElement{

2
dist/esm.js vendored
View File

File diff suppressed because one or more lines are too long

30
docs/elements.html
View File

@ -1,4 +1,4 @@
<!DOCTYPE html><html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><meta name="description" content="Basic concepts of elements modifications and creations."><title>`deka-dom-el` — Elements</title><!--<dde:mark type="component" name="metaAuthor" host="this" ssr/>--><meta name="author" content="Jan Andrle"><link type="text/plain" rel="author" href="https://jaandrle.github.io/humans.txt"><meta name="generator" content="deka-dom-el"><!--<dde:mark type="component" name="metaTwitter" host="this" ssr/>--><meta name="twitter:card" content="summary_large_image"><meta name="twitter:url" content="https://github.com/jaandrle/deka-dom-el"><meta name="twitter:title" content="deka-dom-el"><meta name="twitter:description" content="A low-code library that simplifies the creation of native DOM elements/components using small wrappers and tweaks."><meta name="twitter:creator" content="@jaandrle"><!--<dde:mark type="component" name="metaFacebook" host="this" ssr/>--><meta name="og:url" content="https://github.com/jaandrle/deka-dom-el"><meta name="og:title" content="deka-dom-el"><meta name="og:description" content="A low-code library that simplifies the creation of native DOM elements/components using small wrappers and tweaks."><meta name="og:creator" content="@jaandrle"><script src="https://flems.io/flems.html" type="text/javascript" charset="utf-8"></script><link rel="stylesheet" href="global.css"></head><body><!--<dde:mark type="component" name="page" host="this" ssr/>--><!--<dde:mark type="component" name="header" host="this" ssr/>--><header><h1>`deka-dom-el` — Elements</h1><p>Basic concepts of elements modifications and creations.</p></header><nav><a href="https://github.com/jaandrle/deka-dom-el"><svg class="icon" viewBox="0 0 32 32"><!--<dde:mark type="component" name="iconGitHub" host="parentElement" ssr/>--><path d="M 16,0.395c -8.836,0 -16,7.163 -16,16c 0,7.069 4.585,13.067 10.942,15.182c 0.8,0.148 1.094,-0.347 1.094,-0.77c 0,-0.381 -0.015,-1.642 -0.022,-2.979c -4.452,0.968 -5.391,-1.888 -5.391,-1.888c -0.728,-1.849 -1.776,-2.341 -1.776,-2.341c -1.452,-0.993 0.11,-0.973 0.11,-0.973c 1.606,0.113 2.452,1.649 2.452,1.649c 1.427,2.446 3.743,1.739 4.656,1.33c 0.143,-1.034 0.558,-1.74 1.016,-2.14c -3.554,-0.404 -7.29,-1.777 -7.29,-7.907c 0,-1.747 0.625,-3.174 1.649,-4.295c -0.166,-0.403 -0.714,-2.03 0.155,-4.234c 0,0 1.344,-0.43 4.401,1.64c 1.276,-0.355 2.645,-0.532 4.005,-0.539c 1.359,0.006 2.729,0.184 4.008,0.539c 3.054,-2.07 4.395,-1.64 4.395,-1.64c 0.871,2.204 0.323,3.831 0.157,4.234c 1.026,1.12 1.647,2.548 1.647,4.295c 0,6.145 -3.743,7.498 -7.306,7.895c 0.574,0.497 1.085,1.47 1.085,2.963c 0,2.141 -0.019,3.864 -0.019,4.391c 0,0.426 0.288,0.925 1.099,0.768c 6.354,-2.118 10.933,-8.113 10.933,-15.18c 0,-8.837 -7.164,-16 -16,-16Z"></path></svg>GitHub</a><a href="./" title="Introducing a&nbsp;library.">1. Introduction</a><a href="elements" title="Basic concepts of elements modifications and creations." class="current">2. Elements</a><a href="events" title="Using not only events in UI declaratively.">3. Events and Modifiers</a></nav><main><h2>Native JavaScript DOM elements creations</h2><p>Let’s go through all patterns we would like to use and what needs to be improved for better experience.</p><h3>Creating element(s) (with custom attributes)</h3><p>You can create a native DOM element by using the <a href="https://developer.mozilla.org/en-US/docs/Web/API/Document/createElement" title="MDN documentation for document.createElement()"><code>document.createElement()</code></a>. It is also possible to provide a&nbsp;some attribute(s) declaratively using <code>Object.assign()</code>. More precisely, this way you can sets some <a href="https://developer.mozilla.org/en-US/docs/Glossary/IDL" title="MDN page about Interface Description Language"><abbr title="Interface Description Language">IDL</abbr></a> also known as a JavaScript property.</p><!--<dde:mark type="component" name="example" host="this" ssr/>--><div id="code-lhg00" class="example"><!--<dde:mark type="component" name="code" host="parentElement" ssr/>--><code class="language-js">document.body.append( <!DOCTYPE html><html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><meta name="description" content="Basic concepts of elements modifications and creations."><title>`deka-dom-el` — Elements</title><!--<dde:mark type="component" name="metaAuthor" host="this" ssr/>--><meta name="author" content="Jan Andrle"><link type="text/plain" rel="author" href="https://jaandrle.github.io/humans.txt"><meta name="generator" content="deka-dom-el"><!--<dde:mark type="component" name="metaTwitter" host="this" ssr/>--><meta name="twitter:card" content="summary_large_image"><meta name="twitter:url" content="https://github.com/jaandrle/deka-dom-el"><meta name="twitter:title" content="deka-dom-el"><meta name="twitter:description" content="A low-code library that simplifies the creation of native DOM elements/components using small wrappers and tweaks."><meta name="twitter:creator" content="@jaandrle"><!--<dde:mark type="component" name="metaFacebook" host="this" ssr/>--><meta name="og:url" content="https://github.com/jaandrle/deka-dom-el"><meta name="og:title" content="deka-dom-el"><meta name="og:description" content="A low-code library that simplifies the creation of native DOM elements/components using small wrappers and tweaks."><meta name="og:creator" content="@jaandrle"><script src="https://flems.io/flems.html" type="text/javascript" charset="utf-8"></script><link rel="stylesheet" href="global.css"></head><body><!--<dde:mark type="component" name="page" host="this" ssr/>--><!--<dde:mark type="component" name="header" host="this" ssr/>--><header><h1>`deka-dom-el` — Elements</h1><p>Basic concepts of elements modifications and creations.</p></header><nav><a href="https://github.com/jaandrle/deka-dom-el"><svg class="icon" viewBox="0 0 32 32"><!--<dde:mark type="component" name="iconGitHub" host="parentElement" ssr/>--><path d="M 16,0.395c -8.836,0 -16,7.163 -16,16c 0,7.069 4.585,13.067 10.942,15.182c 0.8,0.148 1.094,-0.347 1.094,-0.77c 0,-0.381 -0.015,-1.642 -0.022,-2.979c -4.452,0.968 -5.391,-1.888 -5.391,-1.888c -0.728,-1.849 -1.776,-2.341 -1.776,-2.341c -1.452,-0.993 0.11,-0.973 0.11,-0.973c 1.606,0.113 2.452,1.649 2.452,1.649c 1.427,2.446 3.743,1.739 4.656,1.33c 0.143,-1.034 0.558,-1.74 1.016,-2.14c -3.554,-0.404 -7.29,-1.777 -7.29,-7.907c 0,-1.747 0.625,-3.174 1.649,-4.295c -0.166,-0.403 -0.714,-2.03 0.155,-4.234c 0,0 1.344,-0.43 4.401,1.64c 1.276,-0.355 2.645,-0.532 4.005,-0.539c 1.359,0.006 2.729,0.184 4.008,0.539c 3.054,-2.07 4.395,-1.64 4.395,-1.64c 0.871,2.204 0.323,3.831 0.157,4.234c 1.026,1.12 1.647,2.548 1.647,4.295c 0,6.145 -3.743,7.498 -7.306,7.895c 0.574,0.497 1.085,1.47 1.085,2.963c 0,2.141 -0.019,3.864 -0.019,4.391c 0,0.426 0.288,0.925 1.099,0.768c 6.354,-2.118 10.933,-8.113 10.933,-15.18c 0,-8.837 -7.164,-16 -16,-16Z"></path></svg>GitHub</a><a href="./" title="Introducing a&nbsp;library.">1. Introduction</a><a href="elements" title="Basic concepts of elements modifications and creations." class="current">2. Elements</a><a href="events" title="Using not only events in UI declaratively.">3. Events and Addons</a></nav><main><h2>Native JavaScript DOM elements creations</h2><p>Let’s go through all patterns we would like to use and what needs to be improved for better experience.</p><h3 id="h-creating-elements-with-custom-attributes"><!--<dde:mark type="component" name="h3" host="parentElement" ssr/>--><a href="#h-creating-elements-with-custom-attributes" tabindex="-1">§</a> Creating element(s) (with custom attributes)</h3><p>You can create a native DOM element by using the <a href="https://developer.mozilla.org/en-US/docs/Web/API/Document/createElement" title="MDN documentation for document.createElement()"><code>document.createElement()</code></a>. It is also possible to provide a&nbsp;some attribute(s) declaratively using <code>Object.assign()</code>. More precisely, this way you can sets some <a href="https://developer.mozilla.org/en-US/docs/Glossary/IDL" title="MDN page about Interface Description Language"><abbr title="Interface Description Language">IDL</abbr></a> also known as a JavaScript property.</p><!--<dde:mark type="component" name="example" host="this" ssr/>--><div id="code-hjxg9" class="example"><!--<dde:mark type="component" name="code" host="parentElement" ssr/>--><code class="language-js">document.body.append(
document.createElement("div") document.createElement("div")
); );
console.log( console.log(
@ -12,7 +12,7 @@ document.body.append(
{ textContent: "Element’s text content.", style: "color: coral;" } { textContent: "Element’s text content.", style: "color: coral;" }
) )
); );
</code></div><script>Flems(document.getElementById("code-lhg00"), JSON.parse("{\"files\":[{\"name\":\".js\",\"content\":\"document.body.append(\\n\\tdocument.createElement(\\\"div\\\")\\n);\\nconsole.log(\\n\\t\\\"Emty div is generated inside <body>:\\\",\\n\\tdocument.body.innerHTML.includes(\\\"<div></div>\\\")\\n);\\n\\ndocument.body.append(\\n\\tObject.assign(\\n\\t\\tdocument.createElement(\\\"p\\\"),\\n\\t\\t{ textContent: \\\"Element’s text content.\\\", style: \\\"color: coral;\\\" }\\n\\t)\\n);\\n\"}],\"toolbar\":false}"));</script><p>To make this easier, you can use the <code>el</code> function. Internally in basic examples, it is wrapper around <code>assign(document.createElement(…), { … })</code>.</p><!--<dde:mark type="component" name="example" host="this" ssr/>--><div id="code-6xfh4" class="example"><!--<dde:mark type="component" name="code" host="parentElement" ssr/>--><code class="language-js">import { el, assign } from "https://cdn.jsdelivr.net/gh/jaandrle/deka-dom-el/dist/esm-with-signals.js"; </code></div><script>Flems(document.getElementById("code-hjxg9"), JSON.parse("{\"files\":[{\"name\":\".js\",\"content\":\"document.body.append(\\n\\tdocument.createElement(\\\"div\\\")\\n);\\nconsole.log(\\n\\t\\\"Emty div is generated inside <body>:\\\",\\n\\tdocument.body.innerHTML.includes(\\\"<div></div>\\\")\\n);\\n\\ndocument.body.append(\\n\\tObject.assign(\\n\\t\\tdocument.createElement(\\\"p\\\"),\\n\\t\\t{ textContent: \\\"Element’s text content.\\\", style: \\\"color: coral;\\\" }\\n\\t)\\n);\\n\"}],\"toolbar\":false}"));</script><p>To make this easier, you can use the <code>el</code> function. Internally in basic examples, it is wrapper around <code>assign(document.createElement(…), { … })</code>.</p><!--<dde:mark type="component" name="example" host="this" ssr/>--><div id="code-uxspq" class="example"><!--<dde:mark type="component" name="code" host="parentElement" ssr/>--><code class="language-js">import { el, assign } from "https://cdn.jsdelivr.net/gh/jaandrle/deka-dom-el/dist/esm-with-signals.js";
const color= "lightcoral"; const color= "lightcoral";
document.body.append( document.body.append(
el("p", { textContent: "Hello (first time)", style: { color } }) el("p", { textContent: "Hello (first time)", style: { color } })
@ -23,18 +23,25 @@ document.body.append(
{ textContent: "Hello (second time)", style: { color } } { textContent: "Hello (second time)", style: { color } }
) )
); );
</code></div><script>Flems(document.getElementById("code-6xfh4"), JSON.parse("{\"files\":[{\"name\":\".js\",\"content\":\"import { el, assign } from \\\"https://cdn.jsdelivr.net/gh/jaandrle/deka-dom-el/dist/esm-with-signals.js\\\";\\nconst color= \\\"lightcoral\\\";\\ndocument.body.append(\\n\\tel(\\\"p\\\", { textContent: \\\"Hello (first time)\\\", style: { color } })\\n);\\ndocument.body.append(\\n\\tassign(\\n\\t\\tdocument.createElement(\\\"p\\\"),\\n\\t\\t{ textContent: \\\"Hello (second time)\\\", style: { color } }\\n\\t)\\n);\\n\"}],\"toolbar\":false}"));</script><p>The <code>assign</code> function provides improved behaviour of <code>Object.assign()</code>. You can declaratively sets any IDL and attribute of the given element. Function prefers IDL and fallback to the <code>element.setAttribute</code> if there is no writable property in the element prototype.</p><p>You can study all JavaScript elements interfaces to the corresponding HTML elements. All HTML elements inherits from <a href="https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement">HTMLElement</a>. To see all available IDLs for example for paragraphs, see <a href="https://developer.mozilla.org/en-US/docs/Web/API/HTMLParagraphElement">HTMLParagraphElement</a>. Moreover, the <code>assign</code> provides a&nbsp;way to sets declaratively some convenient properties:</p><ul><li>It is possible to sets <code>data-*</code>/<code>aria-*</code> attributes using object notation.</li><li>In opposite, it is also possible to sets <code>data-*</code>/<code>aria-*</code> attribute using camelCase notation.</li><li>You can use string or object as a&nbsp;value for <code>style</code> property.</li><li><code>className</code> (IDL – preffered)/<code>class</code> are ways to add CSS class to the element. You can use string (similarly to <code>class="…"</code> syntax in HTML) or array of strings. This is handy to concat conditional classes.</li><li>Use <code>classList</code> to toggle specific classes. This will be handy later when the reactivity via signals is beeing introduced.</li><li>The <code>assign</code> also accepts the <code>undefined</code> as a&nbsp;value for any property to remove it from the element declaratively. Also for some IDL the corresponding attribute is removed as it can be confusing. <em>For example, natievly the element’s <code>id</code> is removed by setting the IDL to an empty string.</em></li></ul><p>For processing, the <code>assign</code> internally uses <code>assignAttribute</code> and <code>classListDeclarative</code>.</p><!--<dde:mark type="component" name="example" host="this" ssr/>--><div id="code-snjsx" class="example"><!--<dde:mark type="component" name="code" host="parentElement" ssr/>--><code class="language-js">import { assignAttribute, classListDeclarative } from "https://cdn.jsdelivr.net/gh/jaandrle/deka-dom-el/dist/esm-with-signals.js"; </code></div><script>Flems(document.getElementById("code-uxspq"), JSON.parse("{\"files\":[{\"name\":\".js\",\"content\":\"import { el, assign } from \\\"https://cdn.jsdelivr.net/gh/jaandrle/deka-dom-el/dist/esm-with-signals.js\\\";\\nconst color= \\\"lightcoral\\\";\\ndocument.body.append(\\n\\tel(\\\"p\\\", { textContent: \\\"Hello (first time)\\\", style: { color } })\\n);\\ndocument.body.append(\\n\\tassign(\\n\\t\\tdocument.createElement(\\\"p\\\"),\\n\\t\\t{ textContent: \\\"Hello (second time)\\\", style: { color } }\\n\\t)\\n);\\n\"}],\"toolbar\":false}"));</script><p>The <code>assign</code> function provides improved behaviour of <code>Object.assign()</code>. You can declaratively sets any IDL and attribute of the given element. Function prefers IDL and fallback to the <code>element.setAttribute</code> if there is no writable property in the element prototype.</p><p>You can study all JavaScript elements interfaces to the corresponding HTML elements. All HTML elements inherits from <a href="https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement">HTMLElement</a>. To see all available IDLs for example for paragraphs, see <a href="https://developer.mozilla.org/en-US/docs/Web/API/HTMLParagraphElement">HTMLParagraphElement</a>. Moreover, the <code>assign</code> provides a&nbsp;way to sets declaratively some convenient properties:</p><ul><li>It is possible to sets <code>data-*</code>/<code>aria-*</code> attributes using object notation.</li><li>In opposite, it is also possible to sets <code>data-*</code>/<code>aria-*</code> attribute using camelCase notation.</li><li>You can use string or object as a&nbsp;value for <code>style</code> property.</li><li><code>className</code> (IDL – preffered)/<code>class</code> are ways to add CSS class to the element. You can use string (similarly to <code>class="…"</code> syntax in HTML) or array of strings. This is handy to concat conditional classes.</li><li>Use <code>classList</code> to toggle specific classes. This will be handy later when the reactivity via signals is beeing introduced.</li><li>The <code>assign</code> also accepts the <code>undefined</code> as a&nbsp;value for any property to remove it from the element declaratively. Also for some IDL the corresponding attribute is removed as it can be confusing. <em>For example, natievly the element’s <code>id</code> is removed by setting the IDL to an empty string.</em></li><li>You can use <code>=</code> or <code>.</code> to force processing given key as attribute/property of the element.</li></ul><p>For processing, the <code>assign</code> internally uses <code>assignAttribute</code> and <code>classListDeclarative</code>.</p><!--<dde:mark type="component" name="example" host="this" ssr/>--><div id="code-4fa3z" class="example"><!--<dde:mark type="component" name="code" host="parentElement" ssr/>--><code class="language-js">import { assign, assignAttribute, classListDeclarative } from "https://cdn.jsdelivr.net/gh/jaandrle/deka-dom-el/dist/esm-with-signals.js";
const paragraph= document.createElement("p"); const paragraph= document.createElement("p");
assignAttribute(paragraph, "textContent", "Hello, world!"); assignAttribute(paragraph, "textContent", "Hello, world!");
assignAttribute(paragraph, "style", "color: red; font-weight: bold;");
assignAttribute(paragraph, "style", { color: "navy" }); assignAttribute(paragraph, "style", { color: "navy" });
assignAttribute(paragraph, "dataTest1", "v1"); assignAttribute(paragraph, "dataTest1", "v1");
assignAttribute(paragraph, "dataset", { test2: "v2" }); assignAttribute(paragraph, "dataset", { test2: "v2" });
assignAttribute(paragraph, "ariaLabel", "v1"); assign(paragraph, { //textContent and style see above
assignAttribute(paragraph, "ariaset", { role: "none" }); ariaLabel: "v1", //data* see above
ariaset: { role: "none" }, // dataset see above
"=onclick": "console.log(event)",
onmouseout: console.info,
".something": "something",
classList: {} //see below
});
classListDeclarative(paragraph, { classListDeclarative(paragraph, {
classAdd: true, classAdd: true,
@ -45,10 +52,11 @@ classListDeclarative(paragraph, {
}); });
console.log(paragraph.outerHTML); console.log(paragraph.outerHTML);
console.log("paragraph.something=", paragraph.something);
document.body.append( document.body.append(
paragraph paragraph
); );
</code></div><script>Flems(document.getElementById("code-snjsx"), JSON.parse("{\"files\":[{\"name\":\".js\",\"content\":\"import { assignAttribute, classListDeclarative } from \\\"https://cdn.jsdelivr.net/gh/jaandrle/deka-dom-el/dist/esm-with-signals.js\\\";\\nconst paragraph= document.createElement(\\\"p\\\");\\n\\nassignAttribute(paragraph, \\\"textContent\\\", \\\"Hello, world!\\\");\\nassignAttribute(paragraph, \\\"style\\\", { color: \\\"navy\\\" });\\n\\nassignAttribute(paragraph, \\\"dataTest1\\\", \\\"v1\\\");\\nassignAttribute(paragraph, \\\"dataset\\\", { test2: \\\"v2\\\" });\\n\\nassignAttribute(paragraph, \\\"ariaLabel\\\", \\\"v1\\\");\\nassignAttribute(paragraph, \\\"ariaset\\\", { role: \\\"none\\\" });\\n\\n\\nclassListDeclarative(paragraph, {\\n\\tclassAdd: true,\\n\\tclassRemove: false,\\n\\tclassAdd1: 1,\\n\\tclassRemove1: 0,\\n\\tclassToggle: -1\\n});\\n\\nconsole.log(paragraph.outerHTML);\\ndocument.body.append(\\n\\tparagraph\\n);\\n\"}],\"toolbar\":false}"));</script><h3>Native JavaScript templating</h3><p>By default, the native JS has no good way to define HTML template using DOM API:</p><!--<dde:mark type="component" name="example" host="this" ssr/>--><div id="code-fd7xz" class="example"><!--<dde:mark type="component" name="code" host="parentElement" ssr/>--><code class="language-js">document.body.append( </code></div><script>Flems(document.getElementById("code-4fa3z"), JSON.parse("{\"files\":[{\"name\":\".js\",\"content\":\"import { assign, assignAttribute, classListDeclarative } from \\\"https://cdn.jsdelivr.net/gh/jaandrle/deka-dom-el/dist/esm-with-signals.js\\\";\\nconst paragraph= document.createElement(\\\"p\\\");\\n\\nassignAttribute(paragraph, \\\"textContent\\\", \\\"Hello, world!\\\");\\n\\nassignAttribute(paragraph, \\\"style\\\", \\\"color: red; font-weight: bold;\\\");\\nassignAttribute(paragraph, \\\"style\\\", { color: \\\"navy\\\" });\\n\\nassignAttribute(paragraph, \\\"dataTest1\\\", \\\"v1\\\");\\nassignAttribute(paragraph, \\\"dataset\\\", { test2: \\\"v2\\\" });\\n\\nassign(paragraph, { //textContent and style see above\\n\\tariaLabel: \\\"v1\\\", //data* see above\\n\\tariaset: { role: \\\"none\\\" }, // dataset see above\\n\\t\\\"=onclick\\\": \\\"console.log(event)\\\",\\n\\tonmouseout: console.info,\\n\\t\\\".something\\\": \\\"something\\\",\\n\\tclassList: {} //see below\\n});\\n\\nclassListDeclarative(paragraph, {\\n\\tclassAdd: true,\\n\\tclassRemove: false,\\n\\tclassAdd1: 1,\\n\\tclassRemove1: 0,\\n\\tclassToggle: -1\\n});\\n\\nconsole.log(paragraph.outerHTML);\\nconsole.log(\\\"paragraph.something=\\\", paragraph.something);\\ndocument.body.append(\\n\\tparagraph\\n);\\n\"}],\"toolbar\":false}"));</script><h3 id="h-native-javascript-templating"><!--<dde:mark type="component" name="h3" host="parentElement" ssr/>--><a href="#h-native-javascript-templating" tabindex="-1">§</a> Native JavaScript templating</h3><p>By default, the native JS has no good way to define HTML template using DOM API:</p><!--<dde:mark type="component" name="example" host="this" ssr/>--><div id="code-iezhk" class="example"><!--<dde:mark type="component" name="code" host="parentElement" ssr/>--><code class="language-js">document.body.append(
document.createElement("div"), document.createElement("div"),
document.createElement("span"), document.createElement("span"),
document.createElement("main") document.createElement("main")
@ -59,7 +67,7 @@ const template= document.createElement("main").append(
document.createElement("span"), document.createElement("span"),
); );
console.log(typeof template==="undefined"); console.log(typeof template==="undefined");
</code></div><script>Flems(document.getElementById("code-fd7xz"), JSON.parse("{\"files\":[{\"name\":\".js\",\"content\":\"document.body.append(\\n\\tdocument.createElement(\\\"div\\\"),\\n\\tdocument.createElement(\\\"span\\\"),\\n\\tdocument.createElement(\\\"main\\\")\\n);\\nconsole.log(document.body.innerHTML.includes(\\\"<div></div><span></span><main></main>\\\"));\\nconst template= document.createElement(\\\"main\\\").append(\\n\\tdocument.createElement(\\\"div\\\"),\\n\\tdocument.createElement(\\\"span\\\"),\\n);\\nconsole.log(typeof template===\\\"undefined\\\");\\n\"}],\"toolbar\":false}"));</script><p>This library therefore overwrites the <code>append</code> method of created elements to always return parent element.</p><!--<dde:mark type="component" name="example" host="this" ssr/>--><div id="code-ijpat" class="example"><!--<dde:mark type="component" name="code" host="parentElement" ssr/>--><code class="language-js">import { el } from "https://cdn.jsdelivr.net/gh/jaandrle/deka-dom-el/dist/esm-with-signals.js"; </code></div><script>Flems(document.getElementById("code-iezhk"), JSON.parse("{\"files\":[{\"name\":\".js\",\"content\":\"document.body.append(\\n\\tdocument.createElement(\\\"div\\\"),\\n\\tdocument.createElement(\\\"span\\\"),\\n\\tdocument.createElement(\\\"main\\\")\\n);\\nconsole.log(document.body.innerHTML.includes(\\\"<div></div><span></span><main></main>\\\"));\\nconst template= document.createElement(\\\"main\\\").append(\\n\\tdocument.createElement(\\\"div\\\"),\\n\\tdocument.createElement(\\\"span\\\"),\\n);\\nconsole.log(typeof template===\\\"undefined\\\");\\n\"}],\"toolbar\":false}"));</script><p>This library therefore overwrites the <code>append</code> method of created elements to always return parent element.</p><!--<dde:mark type="component" name="example" host="this" ssr/>--><div id="code-3fjsw" class="example"><!--<dde:mark type="component" name="code" host="parentElement" ssr/>--><code class="language-js">import { el } from "https://cdn.jsdelivr.net/gh/jaandrle/deka-dom-el/dist/esm-with-signals.js";
document.head.append( document.head.append(
el("style").append( el("style").append(
"tr, td{ border: 1px solid red; padding: 1em; }", "tr, td{ border: 1px solid red; padding: 1em; }",
@ -94,7 +102,7 @@ document.body.append(
) )
) )
); );
</code></div><script>Flems(document.getElementById("code-ijpat"), JSON.parse("{\"files\":[{\"name\":\".js\",\"content\":\"import { el } from \\\"https://cdn.jsdelivr.net/gh/jaandrle/deka-dom-el/dist/esm-with-signals.js\\\";\\ndocument.head.append(\\n\\tel(\\\"style\\\").append(\\n\\t\\t\\\"tr, td{ border: 1px solid red; padding: 1em; }\\\",\\n\\t\\t\\\"table{ border-collapse: collapse; }\\\"\\n\\t)\\n);\\ndocument.body.append(\\n\\tel(\\\"p\\\", \\\"Example of a complex template. Using for example nesting lists:\\\"),\\n\\tel(\\\"ul\\\").append(\\n\\t\\tel(\\\"li\\\", \\\"List item 1\\\"),\\n\\t\\tel(\\\"li\\\").append(\\n\\t\\t\\tel(\\\"ul\\\").append(\\n\\t\\t\\t\\tel(\\\"li\\\", \\\"Nested list item 1\\\"),\\n\\t\\t\\t)\\n\\t\\t)\\n\\t),\\n\\tel(\\\"table\\\").append(\\n\\t\\tel(\\\"tr\\\").append(\\n\\t\\t\\tel(\\\"td\\\", \\\"Row 1 – Col 1\\\"),\\n\\t\\t\\tel(\\\"td\\\", \\\"Row 1 – Col 2\\\")\\n\\t\\t)\\n\\t)\\n);\\n\\nimport { chainableAppend } from \\\"https://cdn.jsdelivr.net/gh/jaandrle/deka-dom-el/dist/esm-with-signals.js\\\";\\n/** @param {keyof HTMLElementTagNameMap} tag */\\nconst createElement= tag=> chainableAppend(document.createElement(tag));\\ndocument.body.append(\\n\\tcreateElement(\\\"p\\\").append(\\n\\t\\tcreateElement(\\\"em\\\").append(\\n\\t\\t\\t\\\"You can also use `chainableAppend`!\\\"\\n\\t\\t)\\n\\t)\\n);\\n\"}],\"toolbar\":false}"));</script><h3>Basic (state-less) components</h3><p>You can use functions for encapsulation (repeating) logic. The <code>el</code> accepts function as first argument. In that case, the function should return dom elements and the second argument for <code>el</code> is argument for given element.</p><!--<dde:mark type="component" name="example" host="this" ssr/>--><div id="code-p4164" class="example"><!--<dde:mark type="component" name="code" host="parentElement" ssr/>--><code class="language-js">import { el } from "https://cdn.jsdelivr.net/gh/jaandrle/deka-dom-el/dist/esm-with-signals.js"; </code></div><script>Flems(document.getElementById("code-3fjsw"), JSON.parse("{\"files\":[{\"name\":\".js\",\"content\":\"import { el } from \\\"https://cdn.jsdelivr.net/gh/jaandrle/deka-dom-el/dist/esm-with-signals.js\\\";\\ndocument.head.append(\\n\\tel(\\\"style\\\").append(\\n\\t\\t\\\"tr, td{ border: 1px solid red; padding: 1em; }\\\",\\n\\t\\t\\\"table{ border-collapse: collapse; }\\\"\\n\\t)\\n);\\ndocument.body.append(\\n\\tel(\\\"p\\\", \\\"Example of a complex template. Using for example nesting lists:\\\"),\\n\\tel(\\\"ul\\\").append(\\n\\t\\tel(\\\"li\\\", \\\"List item 1\\\"),\\n\\t\\tel(\\\"li\\\").append(\\n\\t\\t\\tel(\\\"ul\\\").append(\\n\\t\\t\\t\\tel(\\\"li\\\", \\\"Nested list item 1\\\"),\\n\\t\\t\\t)\\n\\t\\t)\\n\\t),\\n\\tel(\\\"table\\\").append(\\n\\t\\tel(\\\"tr\\\").append(\\n\\t\\t\\tel(\\\"td\\\", \\\"Row 1 – Col 1\\\"),\\n\\t\\t\\tel(\\\"td\\\", \\\"Row 1 – Col 2\\\")\\n\\t\\t)\\n\\t)\\n);\\n\\nimport { chainableAppend } from \\\"https://cdn.jsdelivr.net/gh/jaandrle/deka-dom-el/dist/esm-with-signals.js\\\";\\n/** @param {keyof HTMLElementTagNameMap} tag */\\nconst createElement= tag=> chainableAppend(document.createElement(tag));\\ndocument.body.append(\\n\\tcreateElement(\\\"p\\\").append(\\n\\t\\tcreateElement(\\\"em\\\").append(\\n\\t\\t\\t\\\"You can also use `chainableAppend`!\\\"\\n\\t\\t)\\n\\t)\\n);\\n\"}],\"toolbar\":false}"));</script><h3 id="h-basic-state-less-components"><!--<dde:mark type="component" name="h3" host="parentElement" ssr/>--><a href="#h-basic-state-less-components" tabindex="-1">§</a> Basic (state-less) components</h3><p>You can use functions for encapsulation (repeating) logic. The <code>el</code> accepts function as first argument. In that case, the function should return dom elements and the second argument for <code>el</code> is argument for given element.</p><!--<dde:mark type="component" name="example" host="this" ssr/>--><div id="code-t93qt" class="example"><!--<dde:mark type="component" name="code" host="parentElement" ssr/>--><code class="language-js">import { el } from "https://cdn.jsdelivr.net/gh/jaandrle/deka-dom-el/dist/esm-with-signals.js";
document.head.append( document.head.append(
el("style").append( el("style").append(
".class1{ font-weight: bold; }", ".class1{ font-weight: bold; }",
@ -111,7 +119,7 @@ function component({ className, textContent }){
el("p", textContent) el("p", textContent)
); );
} }
</code></div><script>Flems(document.getElementById("code-p4164"), JSON.parse("{\"files\":[{\"name\":\".js\",\"content\":\"import { el } from \\\"https://cdn.jsdelivr.net/gh/jaandrle/deka-dom-el/dist/esm-with-signals.js\\\";\\ndocument.head.append(\\n\\tel(\\\"style\\\").append(\\n\\t\\t\\\".class1{ font-weight: bold; }\\\",\\n\\t\\t\\\".class2{ color: purple; }\\\"\\n\\t)\\n);\\ndocument.body.append(\\n\\tel(component, { className: \\\"class2\\\", textContent: \\\"Hello World!\\\" }),\\n\\tcomponent({ className: \\\"class2\\\", textContent: \\\"Hello World!\\\" })\\n);\\n\\nfunction component({ className, textContent }){\\n\\treturn el(\\\"div\\\", { className: [ \\\"class1\\\", className ] }).append(\\n\\t\\tel(\\\"p\\\", textContent)\\n\\t);\\n}\\n\"}],\"toolbar\":false}"));</script><p>As you can see, in case of state-less/basic components there is no difference between calling component function directly or using <code>el</code> function.</p><p class="notice">It is nice to use similar naming convention as native DOM API. This allows us to use <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Destructuring_assignment" title="Destructuring assignment | MDN">the destructuring assignment syntax</a> and keep track of the native API (things are best remembered through regular use).</p><h3>Creating non-HTML elements</h3><p>Similarly to the native DOM API (<a href="https://developer.mozilla.org/en-US/docs/Web/API/Document/createElementNS" title="MDN"><code>document.createElementNS</code></a>) for non-HTML elements we need to tell JavaScript which kind of the element to create. We can use the <code>elNS</code> function:</p><!--<dde:mark type="component" name="example" host="this" ssr/>--><div id="code-ynjtj" class="example"><!--<dde:mark type="component" name="code" host="parentElement" ssr/>--><code class="language-js">import { elNS, assign } from "https://cdn.jsdelivr.net/gh/jaandrle/deka-dom-el/dist/esm-with-signals.js"; </code></div><script>Flems(document.getElementById("code-t93qt"), JSON.parse("{\"files\":[{\"name\":\".js\",\"content\":\"import { el } from \\\"https://cdn.jsdelivr.net/gh/jaandrle/deka-dom-el/dist/esm-with-signals.js\\\";\\ndocument.head.append(\\n\\tel(\\\"style\\\").append(\\n\\t\\t\\\".class1{ font-weight: bold; }\\\",\\n\\t\\t\\\".class2{ color: purple; }\\\"\\n\\t)\\n);\\ndocument.body.append(\\n\\tel(component, { className: \\\"class2\\\", textContent: \\\"Hello World!\\\" }),\\n\\tcomponent({ className: \\\"class2\\\", textContent: \\\"Hello World!\\\" })\\n);\\n\\nfunction component({ className, textContent }){\\n\\treturn el(\\\"div\\\", { className: [ \\\"class1\\\", className ] }).append(\\n\\t\\tel(\\\"p\\\", textContent)\\n\\t);\\n}\\n\"}],\"toolbar\":false}"));</script><p>As you can see, in case of state-less/basic components there is no difference between calling component function directly or using <code>el</code> function.</p><p class="notice">It is nice to use similar naming convention as native DOM API. This allows us to use <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Destructuring_assignment" title="Destructuring assignment | MDN">the destructuring assignment syntax</a> and keep track of the native API (things are best remembered through regular use).</p><h3 id="h-creating-non-html-elements"><!--<dde:mark type="component" name="h3" host="parentElement" ssr/>--><a href="#h-creating-non-html-elements" tabindex="-1">§</a> Creating non-HTML elements</h3><p>Similarly to the native DOM API (<a href="https://developer.mozilla.org/en-US/docs/Web/API/Document/createElementNS" title="MDN"><code>document.createElementNS</code></a>) for non-HTML elements we need to tell JavaScript which kind of the element to create. We can use the <code>elNS</code> function:</p><!--<dde:mark type="component" name="example" host="this" ssr/>--><div id="code-h9nd7" class="example"><!--<dde:mark type="component" name="code" host="parentElement" ssr/>--><code class="language-js">import { elNS, assign } from "https://cdn.jsdelivr.net/gh/jaandrle/deka-dom-el/dist/esm-with-signals.js";
const elSVG= elNS("http://www.w3.org/2000/svg"); const elSVG= elNS("http://www.w3.org/2000/svg");
const elMath= elNS("http://www.w3.org/1998/Math/MathML"); const elMath= elNS("http://www.w3.org/1998/Math/MathML");
document.body.append( document.body.append(
@ -122,4 +130,4 @@ document.body.append(
console.log( console.log(
document.body.innerHTML.includes("&lt;svg&gt;&lt;/svg&gt;&lt;math&gt;&lt;/math&gt;") document.body.innerHTML.includes("&lt;svg&gt;&lt;/svg&gt;&lt;math&gt;&lt;/math&gt;")
) )
</code></div><script>Flems(document.getElementById("code-ynjtj"), JSON.parse("{\"files\":[{\"name\":\".js\",\"content\":\"import { elNS, assign } from \\\"https://cdn.jsdelivr.net/gh/jaandrle/deka-dom-el/dist/esm-with-signals.js\\\";\\nconst elSVG= elNS(\\\"http://www.w3.org/2000/svg\\\");\\nconst elMath= elNS(\\\"http://www.w3.org/1998/Math/MathML\\\");\\ndocument.body.append(\\n\\telSVG(\\\"svg\\\"), // see https://developer.mozilla.org/en-US/docs/Web/SVG and https://developer.mozilla.org/en-US/docs/Web/API/SVGElement\\n\\telMath(\\\"math\\\") // see https://developer.mozilla.org/en-US/docs/Web/MathML and https://developer.mozilla.org/en-US/docs/Web/MathML/Global_attributes\\n);\\n\\nconsole.log(\\n\\tdocument.body.innerHTML.includes(\\\"<svg></svg><math></math>\\\")\\n)\\n\"}],\"toolbar\":false}"));</script><div class="prevNext"><!--<dde:mark type="component" name="prevNext" host="parentElement" ssr/>--><a rel="prev" href="./" title="Introducing a&nbsp;library."><!--<dde:mark type="component" name="pageLink" host="parentElement" ssr/>-->Introduction (previous)</a><a rel="next" href="events" title="Using not only events in UI declaratively."><!--<dde:mark type="component" name="pageLink" host="parentElement" ssr/>-->(next) Events and Modifiers</a></div></main></body></html> </code></div><script>Flems(document.getElementById("code-h9nd7"), JSON.parse("{\"files\":[{\"name\":\".js\",\"content\":\"import { elNS, assign } from \\\"https://cdn.jsdelivr.net/gh/jaandrle/deka-dom-el/dist/esm-with-signals.js\\\";\\nconst elSVG= elNS(\\\"http://www.w3.org/2000/svg\\\");\\nconst elMath= elNS(\\\"http://www.w3.org/1998/Math/MathML\\\");\\ndocument.body.append(\\n\\telSVG(\\\"svg\\\"), // see https://developer.mozilla.org/en-US/docs/Web/SVG and https://developer.mozilla.org/en-US/docs/Web/API/SVGElement\\n\\telMath(\\\"math\\\") // see https://developer.mozilla.org/en-US/docs/Web/MathML and https://developer.mozilla.org/en-US/docs/Web/MathML/Global_attributes\\n);\\n\\nconsole.log(\\n\\tdocument.body.innerHTML.includes(\\\"<svg></svg><math></math>\\\")\\n)\\n\"}],\"toolbar\":false}"));</script><div class="prevNext"><!--<dde:mark type="component" name="prevNext" host="parentElement" ssr/>--><a rel="prev" href="./" title="Introducing a&nbsp;library."><!--<dde:mark type="component" name="pageLink" host="parentElement" ssr/>-->Introduction (previous)</a><a rel="next" href="events" title="Using not only events in UI declaratively."><!--<dde:mark type="component" name="pageLink" host="parentElement" ssr/>-->(next) Events and Addons</a></div></main></body></html>

42
docs/events.html
View File

@ -1,4 +1,4 @@
<!DOCTYPE html><html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><meta name="description" content="Using not only events in UI declaratively."><title>`deka-dom-el` — Events and Modifiers</title><!--<dde:mark type="component" name="metaAuthor" host="this" ssr/>--><meta name="author" content="Jan Andrle"><link type="text/plain" rel="author" href="https://jaandrle.github.io/humans.txt"><meta name="generator" content="deka-dom-el"><!--<dde:mark type="component" name="metaTwitter" host="this" ssr/>--><meta name="twitter:card" content="summary_large_image"><meta name="twitter:url" content="https://github.com/jaandrle/deka-dom-el"><meta name="twitter:title" content="deka-dom-el"><meta name="twitter:description" content="A low-code library that simplifies the creation of native DOM elements/components using small wrappers and tweaks."><meta name="twitter:creator" content="@jaandrle"><!--<dde:mark type="component" name="metaFacebook" host="this" ssr/>--><meta name="og:url" content="https://github.com/jaandrle/deka-dom-el"><meta name="og:title" content="deka-dom-el"><meta name="og:description" content="A low-code library that simplifies the creation of native DOM elements/components using small wrappers and tweaks."><meta name="og:creator" content="@jaandrle"><script src="https://flems.io/flems.html" type="text/javascript" charset="utf-8"></script><link rel="stylesheet" href="global.css"></head><body><!--<dde:mark type="component" name="page" host="this" ssr/>--><!--<dde:mark type="component" name="header" host="this" ssr/>--><header><h1>`deka-dom-el` — Events and Modifiers</h1><p>Using not only events in UI declaratively.</p></header><nav><a href="https://github.com/jaandrle/deka-dom-el"><svg class="icon" viewBox="0 0 32 32"><!--<dde:mark type="component" name="iconGitHub" host="parentElement" ssr/>--><path d="M 16,0.395c -8.836,0 -16,7.163 -16,16c 0,7.069 4.585,13.067 10.942,15.182c 0.8,0.148 1.094,-0.347 1.094,-0.77c 0,-0.381 -0.015,-1.642 -0.022,-2.979c -4.452,0.968 -5.391,-1.888 -5.391,-1.888c -0.728,-1.849 -1.776,-2.341 -1.776,-2.341c -1.452,-0.993 0.11,-0.973 0.11,-0.973c 1.606,0.113 2.452,1.649 2.452,1.649c 1.427,2.446 3.743,1.739 4.656,1.33c 0.143,-1.034 0.558,-1.74 1.016,-2.14c -3.554,-0.404 -7.29,-1.777 -7.29,-7.907c 0,-1.747 0.625,-3.174 1.649,-4.295c -0.166,-0.403 -0.714,-2.03 0.155,-4.234c 0,0 1.344,-0.43 4.401,1.64c 1.276,-0.355 2.645,-0.532 4.005,-0.539c 1.359,0.006 2.729,0.184 4.008,0.539c 3.054,-2.07 4.395,-1.64 4.395,-1.64c 0.871,2.204 0.323,3.831 0.157,4.234c 1.026,1.12 1.647,2.548 1.647,4.295c 0,6.145 -3.743,7.498 -7.306,7.895c 0.574,0.497 1.085,1.47 1.085,2.963c 0,2.141 -0.019,3.864 -0.019,4.391c 0,0.426 0.288,0.925 1.099,0.768c 6.354,-2.118 10.933,-8.113 10.933,-15.18c 0,-8.837 -7.164,-16 -16,-16Z"></path></svg>GitHub</a><a href="./" title="Introducing a&nbsp;library.">1. Introduction</a><a href="elements" title="Basic concepts of elements modifications and creations.">2. Elements</a><a href="events" title="Using not only events in UI declaratively." class="current">3. Events and Modifiers</a></nav><main><h2>Listenning to the native DOM events and other Modifiers</h2><p>We quickly introduce helper to listening to the native DOM events. And library syntax/pattern so-called <em>Modifier</em> to incorporate not only this in UI templates declaratively.</p><h3>Events and listenners</h3><p>In JavaScript you can listen to the native DOM events of the given element by using <a href="https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener" title="addEventListener on MDN"><code>element.addEventListener(type, listener, options)</code></a>. The library provides an alternative (<code>on</code>) accepting the differen order of the arguments:</p><!--<dde:mark type="component" name="example" host="this" ssr/>--><div id="code-syy9m" class="example"><!--<dde:mark type="component" name="code" host="parentElement" ssr/>--><code class="language-js">import { el, on } from "https://cdn.jsdelivr.net/gh/jaandrle/deka-dom-el/dist/esm-with-signals.js"; <!DOCTYPE html><html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><meta name="description" content="Using not only events in UI declaratively."><title>`deka-dom-el` — Events and Addons</title><!--<dde:mark type="component" name="metaAuthor" host="this" ssr/>--><meta name="author" content="Jan Andrle"><link type="text/plain" rel="author" href="https://jaandrle.github.io/humans.txt"><meta name="generator" content="deka-dom-el"><!--<dde:mark type="component" name="metaTwitter" host="this" ssr/>--><meta name="twitter:card" content="summary_large_image"><meta name="twitter:url" content="https://github.com/jaandrle/deka-dom-el"><meta name="twitter:title" content="deka-dom-el"><meta name="twitter:description" content="A low-code library that simplifies the creation of native DOM elements/components using small wrappers and tweaks."><meta name="twitter:creator" content="@jaandrle"><!--<dde:mark type="component" name="metaFacebook" host="this" ssr/>--><meta name="og:url" content="https://github.com/jaandrle/deka-dom-el"><meta name="og:title" content="deka-dom-el"><meta name="og:description" content="A low-code library that simplifies the creation of native DOM elements/components using small wrappers and tweaks."><meta name="og:creator" content="@jaandrle"><script src="https://flems.io/flems.html" type="text/javascript" charset="utf-8"></script><link rel="stylesheet" href="global.css"></head><body><!--<dde:mark type="component" name="page" host="this" ssr/>--><!--<dde:mark type="component" name="header" host="this" ssr/>--><header><h1>`deka-dom-el` — Events and Addons</h1><p>Using not only events in UI declaratively.</p></header><nav><a href="https://github.com/jaandrle/deka-dom-el"><svg class="icon" viewBox="0 0 32 32"><!--<dde:mark type="component" name="iconGitHub" host="parentElement" ssr/>--><path d="M 16,0.395c -8.836,0 -16,7.163 -16,16c 0,7.069 4.585,13.067 10.942,15.182c 0.8,0.148 1.094,-0.347 1.094,-0.77c 0,-0.381 -0.015,-1.642 -0.022,-2.979c -4.452,0.968 -5.391,-1.888 -5.391,-1.888c -0.728,-1.849 -1.776,-2.341 -1.776,-2.341c -1.452,-0.993 0.11,-0.973 0.11,-0.973c 1.606,0.113 2.452,1.649 2.452,1.649c 1.427,2.446 3.743,1.739 4.656,1.33c 0.143,-1.034 0.558,-1.74 1.016,-2.14c -3.554,-0.404 -7.29,-1.777 -7.29,-7.907c 0,-1.747 0.625,-3.174 1.649,-4.295c -0.166,-0.403 -0.714,-2.03 0.155,-4.234c 0,0 1.344,-0.43 4.401,1.64c 1.276,-0.355 2.645,-0.532 4.005,-0.539c 1.359,0.006 2.729,0.184 4.008,0.539c 3.054,-2.07 4.395,-1.64 4.395,-1.64c 0.871,2.204 0.323,3.831 0.157,4.234c 1.026,1.12 1.647,2.548 1.647,4.295c 0,6.145 -3.743,7.498 -7.306,7.895c 0.574,0.497 1.085,1.47 1.085,2.963c 0,2.141 -0.019,3.864 -0.019,4.391c 0,0.426 0.288,0.925 1.099,0.768c 6.354,-2.118 10.933,-8.113 10.933,-15.18c 0,-8.837 -7.164,-16 -16,-16Z"></path></svg>GitHub</a><a href="./" title="Introducing a&nbsp;library.">1. Introduction</a><a href="elements" title="Basic concepts of elements modifications and creations.">2. Elements</a><a href="events" title="Using not only events in UI declaratively." class="current">3. Events and Addons</a></nav><main><h2>Listenning to the native DOM events and other Addons</h2><p>We quickly introduce helper to listening to the native DOM events. And library syntax/pattern so-called <em>Addon</em> to incorporate not only this in UI templates declaratively.</p><h3 id="h-events-and-listenners"><!--<dde:mark type="component" name="h3" host="parentElement" ssr/>--><a href="#h-events-and-listenners" tabindex="-1">§</a> Events and listenners</h3><p>In JavaScript you can listen to the native DOM events of the given element by using <a href="https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener" title="addEventListener on MDN"><code>element.addEventListener(type, listener, options)</code></a>. The library provides an alternative (<code>on</code>) accepting the differen order of the arguments:</p><!--<dde:mark type="component" name="example" host="this" ssr/>--><div id="code-bfax7" class="example"><!--<dde:mark type="component" name="code" host="parentElement" ssr/>--><code class="language-js">import { el, on } from "https://cdn.jsdelivr.net/gh/jaandrle/deka-dom-el/dist/esm-with-signals.js";
const log= mark=&gt; console.log.bind(console, mark); const log= mark=&gt; console.log.bind(console, mark);
const button= el("button", "Test click"); const button= el("button", "Test click");
@ -8,7 +8,7 @@ on("click", log("`on`"), { once: true })(button);
document.body.append( document.body.append(
button button
); );
</code></div><script>Flems(document.getElementById("code-syy9m"), JSON.parse("{\"files\":[{\"name\":\".js\",\"content\":\"import { el, on } from \\\"https://cdn.jsdelivr.net/gh/jaandrle/deka-dom-el/dist/esm-with-signals.js\\\";\\nconst log= mark=> console.log.bind(console, mark);\\n\\nconst button= el(\\\"button\\\", \\\"Test click\\\");\\nbutton.addEventListener(\\\"click\\\", log(\\\"`addEventListener`\\\"), { once: true });\\non(\\\"click\\\", log(\\\"`on`\\\"), { once: true })(button);\\n\\ndocument.body.append(\\n\\tbutton\\n);\\n\"}],\"toolbar\":false}"));</script><p>…this is actually one of the two differences. The another one is that<code>on</code> accepts only object as the <code>options</code> (but it is still optional).</p><p>The other difference is that there is <strong>no</strong> <code>off</code> function. You can remove listener declaratively using <a href="https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener#signal" title="part of addEventListener on MDN">AbortSignal</a>:</p><!--<dde:mark type="component" name="example" host="this" ssr/>--><div id="code-c27m6" class="example"><!--<dde:mark type="component" name="code" host="parentElement" ssr/>--><code class="language-js">import { el, on } from "https://cdn.jsdelivr.net/gh/jaandrle/deka-dom-el/dist/esm-with-signals.js"; </code></div><script>Flems(document.getElementById("code-bfax7"), JSON.parse("{\"files\":[{\"name\":\".js\",\"content\":\"import { el, on } from \\\"https://cdn.jsdelivr.net/gh/jaandrle/deka-dom-el/dist/esm-with-signals.js\\\";\\nconst log= mark=> console.log.bind(console, mark);\\n\\nconst button= el(\\\"button\\\", \\\"Test click\\\");\\nbutton.addEventListener(\\\"click\\\", log(\\\"`addEventListener`\\\"), { once: true });\\non(\\\"click\\\", log(\\\"`on`\\\"), { once: true })(button);\\n\\ndocument.body.append(\\n\\tbutton\\n);\\n\"}],\"toolbar\":false}"));</script><p>…this is actually one of the two differences. The another one is that <code>on</code> accepts only object as the <code>options</code> (but it is still optional).</p><p class="notice">The other difference is that there is <strong>no</strong> <code>off</code> function. You can remove listener declaratively using <a href="https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener#signal" title="part of addEventListener on MDN">AbortSignal</a>:</p><!--<dde:mark type="component" name="example" host="this" ssr/>--><div id="code-5nr0f" class="example"><!--<dde:mark type="component" name="code" host="parentElement" ssr/>--><code class="language-js">import { el, on } from "https://cdn.jsdelivr.net/gh/jaandrle/deka-dom-el/dist/esm-with-signals.js";
const log= mark=&gt; console.log.bind(console, mark); const log= mark=&gt; console.log.bind(console, mark);
const abort_controller= new AbortController(); const abort_controller= new AbortController();
@ -21,10 +21,10 @@ on("click", log("`on`"), { signal })(button);
document.body.append( document.body.append(
button, " ", el("button", { textContent: "Off", onclick: ()=&gt; abort_controller.abort() }) button, " ", el("button", { textContent: "Off", onclick: ()=&gt; abort_controller.abort() })
); );
</code></div><script>Flems(document.getElementById("code-c27m6"), JSON.parse("{\"files\":[{\"name\":\".js\",\"content\":\"import { el, on } from \\\"https://cdn.jsdelivr.net/gh/jaandrle/deka-dom-el/dist/esm-with-signals.js\\\";\\nconst log= mark=> console.log.bind(console, mark);\\n\\nconst abort_controller= new AbortController();\\nconst { signal }= abort_controller;\\n\\nconst button= el(\\\"button\\\", \\\"Test click\\\");\\nbutton.addEventListener(\\\"click\\\", log(\\\"`addEventListener`\\\"), { signal });\\non(\\\"click\\\", log(\\\"`on`\\\"), { signal })(button);\\n\\ndocument.body.append(\\n\\tbutton, \\\" \\\", el(\\\"button\\\", { textContent: \\\"Off\\\", onclick: ()=> abort_controller.abort() })\\n);\\n\"}],\"toolbar\":false}"));</script><h3>Modifiers</h3><p>From practical point of view, <em>Modifiers</em> are just functions that accept any html element as their first parameter. You can see that the <code>on(…)</code> fullfills this requirement.</p><p>You can use Modifiers as ≥3rd argument of <code>el</code> function. This way is possible to extends you templates by additional (3rd party) functionalities. But for now mainly, you can add events listeners:</p><!--<dde:mark type="component" name="example" host="this" ssr/>--><div id="code-63xwf" class="example"><!--<dde:mark type="component" name="code" host="parentElement" ssr/>--><code class="language-js">import { el, on } from "https://cdn.jsdelivr.net/gh/jaandrle/deka-dom-el/dist/esm-with-signals.js"; </code></div><script>Flems(document.getElementById("code-5nr0f"), JSON.parse("{\"files\":[{\"name\":\".js\",\"content\":\"import { el, on } from \\\"https://cdn.jsdelivr.net/gh/jaandrle/deka-dom-el/dist/esm-with-signals.js\\\";\\nconst log= mark=> console.log.bind(console, mark);\\n\\nconst abort_controller= new AbortController();\\nconst { signal }= abort_controller;\\n\\nconst button= el(\\\"button\\\", \\\"Test click\\\");\\nbutton.addEventListener(\\\"click\\\", log(\\\"`addEventListener`\\\"), { signal });\\non(\\\"click\\\", log(\\\"`on`\\\"), { signal })(button);\\n\\ndocument.body.append(\\n\\tbutton, \\\" \\\", el(\\\"button\\\", { textContent: \\\"Off\\\", onclick: ()=> abort_controller.abort() })\\n);\\n\"}],\"toolbar\":false}"));</script><div class="notice"><p>So, there are (typically) three ways to handle events. You can use:</p><ul><li><code>el("button", { textContent: "click me", "=onclick": "console.log(event)" })</code></li><li><code>el("button", { textContent: "click me", onclick: console.log })</code></li><li><code>el("button", { textContent: "click me" }, on("click", console.log))</code></li></ul><p>In the first example we force to use HTML attribute (it corresponds to <code>&lt;button onclick="console.log(event)"&gt;click me&lt;/button&gt;</code>). <em>Side note: this can be useful in case of SSR.</em> To study difference, you can read a nice summary here: <a href="https://gist.github.com/WebReflection/b404c36f46371e3b1173bf5492acc944">GIST @WebReflection/web_events.md</a>.</p></div><h3 id="h-addons"><!--<dde:mark type="component" name="h3" host="parentElement" ssr/>--><a href="#h-addons" tabindex="-1">§</a> Addons</h3><p>From practical point of view, <em>Addons</em> are just functions that accept any html element as their first parameter. You can see that the <code>on(…)</code> fullfills this requirement.</p><p>You can use Addons as ≥3rd argument of <code>el</code> function. This way is possible to extends you templates by additional (3rd party) functionalities. But for now mainly, you can add events listeners:</p><!--<dde:mark type="component" name="example" host="this" ssr/>--><div id="code-719th" class="example"><!--<dde:mark type="component" name="code" host="parentElement" ssr/>--><code class="language-js">import { el, on } from "https://cdn.jsdelivr.net/gh/jaandrle/deka-dom-el/dist/esm-with-signals.js";
const abort_controller= new AbortController(); const abort_controller= new AbortController();
const { signal }= abort_controller; const { signal }= abort_controller;
/** @type {ddeElementModifier&lt;HTMLButtonElement&gt;} */ /** @type {ddeElementAddon&lt;HTMLButtonElement&gt;} */
const onclickOff= on("click", ()=&gt; abort_controller.abort(), { signal }); const onclickOff= on("click", ()=&gt; abort_controller.abort(), { signal });
/** @type {(ref?: HTMLOutputElement)=&gt; HTMLOutputElement | null} */ /** @type {(ref?: HTMLOutputElement)=&gt; HTMLOutputElement | null} */
const ref= (store=&gt; ref=&gt; ref ? (store= ref) : store)(null); const ref= (store=&gt; ref=&gt; ref ? (store= ref) : store)(null);
@ -45,4 +45,36 @@ function update(event){
"\n" "\n"
); );
} }
</code></div><script>Flems(document.getElementById("code-63xwf"), JSON.parse("{\"files\":[{\"name\":\".js\",\"content\":\"import { el, on } from \\\"https://cdn.jsdelivr.net/gh/jaandrle/deka-dom-el/dist/esm-with-signals.js\\\";\\nconst abort_controller= new AbortController();\\nconst { signal }= abort_controller;\\n/** @type {ddeElementModifier<HTMLButtonElement>} */\\nconst onclickOff= on(\\\"click\\\", ()=> abort_controller.abort(), { signal });\\n/** @type {(ref?: HTMLOutputElement)=> HTMLOutputElement | null} */\\nconst ref= (store=> ref=> ref ? (store= ref) : store)(null);\\n\\ndocument.body.append(\\n\\tel(\\\"button\\\", \\\"Test `on`\\\",\\n\\t\\ton(\\\"click\\\", console.log, { signal }),\\n\\t\\ton(\\\"click\\\", update, { signal }),\\n\\t\\ton(\\\"mouseup\\\", update, { signal })),\\n\\t\\\" \\\",\\n\\tel(\\\"button\\\", \\\"Off\\\", onclickOff),\\n\\tel(\\\"output\\\", { style: { display: \\\"block\\\", whiteSpace: \\\"pre\\\" } }, ref)\\n);\\n/** @param {MouseEvent} event @this {HTMLButtonElement} */\\nfunction update(event){\\n\\tref().append(\\n\\t\\tevent.type,\\n\\t\\t\\\"\\\\n\\\"\\n\\t);\\n}\\n\"}],\"toolbar\":false}"));</script><p>As the example shows, you can also provide types in JSDoc+TypeScript by using global type <code>ddeElementModifier</code>. Also notice, you can use Modifiers to get element reference.</p><h3>Life cycle events</h3><p>Modifiers are called immediately when the element is created, event it is not connected to live DOM yet.</p><div class="prevNext"><!--<dde:mark type="component" name="prevNext" host="parentElement" ssr/>--><a rel="prev" href="elements" title="Basic concepts of elements modifications and creations."><!--<dde:mark type="component" name="pageLink" host="parentElement" ssr/>-->Elements (previous)</a><!--<dde:mark type="component" name="pageLink" host="this" ssr/>--></div></main></body></html> </code></div><script>Flems(document.getElementById("code-719th"), JSON.parse("{\"files\":[{\"name\":\".js\",\"content\":\"import { el, on } from \\\"https://cdn.jsdelivr.net/gh/jaandrle/deka-dom-el/dist/esm-with-signals.js\\\";\\nconst abort_controller= new AbortController();\\nconst { signal }= abort_controller;\\n/** @type {ddeElementAddon<HTMLButtonElement>} */\\nconst onclickOff= on(\\\"click\\\", ()=> abort_controller.abort(), { signal });\\n/** @type {(ref?: HTMLOutputElement)=> HTMLOutputElement | null} */\\nconst ref= (store=> ref=> ref ? (store= ref) : store)(null);\\n\\ndocument.body.append(\\n\\tel(\\\"button\\\", \\\"Test `on`\\\",\\n\\t\\ton(\\\"click\\\", console.log, { signal }),\\n\\t\\ton(\\\"click\\\", update, { signal }),\\n\\t\\ton(\\\"mouseup\\\", update, { signal })),\\n\\t\\\" \\\",\\n\\tel(\\\"button\\\", \\\"Off\\\", onclickOff),\\n\\tel(\\\"output\\\", { style: { display: \\\"block\\\", whiteSpace: \\\"pre\\\" } }, ref)\\n);\\n/** @param {MouseEvent} event @this {HTMLButtonElement} */\\nfunction update(event){\\n\\tref().append(\\n\\t\\tevent.type,\\n\\t\\t\\\"\\\\n\\\"\\n\\t);\\n}\\n\"}],\"toolbar\":false}"));</script><p>As the example shows, you can also provide types in JSDoc+TypeScript by using global type <code>ddeElementAddon</code>. Also notice, you can use Addons to get element reference.</p><h3 id="h-life-cycle-events"><!--<dde:mark type="component" name="h3" host="parentElement" ssr/>--><a href="#h-life-cycle-events" tabindex="-1">§</a> Life-cycle events</h3><p>Addons are called immediately when the element is created, even it is not connected to live DOM yet. Therefore, you can understand the Addon to be “oncreate” event.</p><p>The library provide three additional live-cycle events corresponding to how they are named in a case of custom elements: <code>on.connected</code>, <code>on.disconnected</code> and <code>on.attributeChanged</code>.</p><!--<dde:mark type="component" name="example" host="this" ssr/>--><div id="code-8y0r4" class="example"><!--<dde:mark type="component" name="code" host="parentElement" ssr/>--><code class="language-js">import { el, on } from "https://cdn.jsdelivr.net/gh/jaandrle/deka-dom-el/dist/esm-with-signals.js";
const paragraph= el("p", "See live-cycle events in console.",
el=&gt; log({ type: "dde:created", detail: el }),
on.connected(log),
on.disconnected(log),
on.attributeChanged(log));
document.body.append(
paragraph,
el("button", "Update attribute", on("click", ()=&gt; paragraph.setAttribute("test", Math.random().toString()))),
" ",
el("button", "Remove", on("click", ()=&gt; paragraph.remove()))
);
/** @param {Partial&lt;CustomEvent&gt;} event */
function log({ type, detail }){
console.log({ _this: this, type, detail });
}
</code></div><script>Flems(document.getElementById("code-8y0r4"), JSON.parse("{\"files\":[{\"name\":\".js\",\"content\":\"import { el, on } from \\\"https://cdn.jsdelivr.net/gh/jaandrle/deka-dom-el/dist/esm-with-signals.js\\\";\\nconst paragraph= el(\\\"p\\\", \\\"See live-cycle events in console.\\\",\\n\\tel=> log({ type: \\\"dde:created\\\", detail: el }),\\n\\ton.connected(log),\\n\\ton.disconnected(log),\\n\\ton.attributeChanged(log));\\n\\ndocument.body.append(\\n\\tparagraph,\\n\\tel(\\\"button\\\", \\\"Update attribute\\\", on(\\\"click\\\", ()=> paragraph.setAttribute(\\\"test\\\", Math.random().toString()))),\\n\\t\\\" \\\",\\n\\tel(\\\"button\\\", \\\"Remove\\\", on(\\\"click\\\", ()=> paragraph.remove()))\\n);\\n\\n/** @param {Partial<CustomEvent>} event */\\nfunction log({ type, detail }){\\n\\tconsole.log({ _this: this, type, detail });\\n}\\n\"}],\"toolbar\":false}"));</script><p>For Custom elements, we will later introduce a way to replace <code>*Callback</code> syntax with <code>dde:*</code> events. The <code>on.*</code> functions then listen to the appropriate Custom Elements events (see <a href="https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements#custom_element_lifecycle_callbacks">Custom element lifecycle callbacks | MDN</a>).</p><p>But, in case of regular elemnets the <a href="https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver"><code>MutationObserver</code> | MDN</a> is internaly used to track these events. Therefore, there are some drawbacks:</p><ul><li>To proper listener registration, you need to use <code>on.*</code> not `on("dde:*", …)`!</li><li>Use sparingly! Internally, library must loop of all registered events and fires event properly. <strong>It is good practice to use the fact that if an element is removed, its children are also removed!</strong> In this spirit, we will introduce later the <strong>host</strong> syntax to register clean up procedures when the component is removed from the app.</li></ul><h3 id="h-final-notes"><!--<dde:mark type="component" name="h3" host="parentElement" ssr/>--><a href="#h-final-notes" tabindex="-1">§</a> Final notes</h3><p>The library also provides a&nbsp;method to dispatch the events.</p><!--<dde:mark type="component" name="example" host="this" ssr/>--><div id="code-a7ggk" class="example"><!--<dde:mark type="component" name="code" host="parentElement" ssr/>--><code class="language-js">import { el, on, dispatchEvent } from "https://cdn.jsdelivr.net/gh/jaandrle/deka-dom-el/dist/esm-with-signals.js";
document.body.append(
el("p", "Listenning to `test` event.", on("test", console.log)).append(
el("br"),
el("button", "native", on("click", native)),
" ",
el("button", "dde", on("click", dde)),
" ",
el("button", "dde with options", on("click", ddeOptions))
)
);
function native(){ this.dispatchEvent(new CustomEvent("test", { bubbles: true, detail: "hi" })); }
function dde(){ dispatchEvent("test")(this.parentElement, "hi"); }
function ddeOptions(){ dispatchEvent("test", { bubbles: true })(this, "hi"); }
</code></div><script>Flems(document.getElementById("code-a7ggk"), JSON.parse("{\"files\":[{\"name\":\".js\",\"content\":\"import { el, on, dispatchEvent } from \\\"https://cdn.jsdelivr.net/gh/jaandrle/deka-dom-el/dist/esm-with-signals.js\\\";\\ndocument.body.append(\\n\\tel(\\\"p\\\", \\\"Listenning to `test` event.\\\", on(\\\"test\\\", console.log)).append(\\n\\t\\tel(\\\"br\\\"),\\n\\t\\tel(\\\"button\\\", \\\"native\\\", on(\\\"click\\\", native)),\\n\\t\\t\\\" \\\",\\n\\t\\tel(\\\"button\\\", \\\"dde\\\", on(\\\"click\\\", dde)),\\n\\t\\t\\\" \\\",\\n\\t\\tel(\\\"button\\\", \\\"dde with options\\\", on(\\\"click\\\", ddeOptions))\\n\\t)\\n);\\nfunction native(){ this.dispatchEvent(new CustomEvent(\\\"test\\\", { bubbles: true, detail: \\\"hi\\\" })); }\\nfunction dde(){ dispatchEvent(\\\"test\\\")(this.parentElement, \\\"hi\\\"); }\\nfunction ddeOptions(){ dispatchEvent(\\\"test\\\", { bubbles: true })(this, \\\"hi\\\"); }\\n\"}],\"toolbar\":false}"));</script><div class="prevNext"><!--<dde:mark type="component" name="prevNext" host="parentElement" ssr/>--><a rel="prev" href="elements" title="Basic concepts of elements modifications and creations."><!--<dde:mark type="component" name="pageLink" host="parentElement" ssr/>-->Elements (previous)</a><!--<dde:mark type="component" name="pageLink" host="this" ssr/>--></div></main></body></html>

4
docs/index.html
View File

@ -1,4 +1,4 @@
<!DOCTYPE html><html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><meta name="description" content="Introducing a&nbsp;library."><title>`deka-dom-el` — Introduction</title><!--<dde:mark type="component" name="metaAuthor" host="this" ssr/>--><meta name="author" content="Jan Andrle"><link type="text/plain" rel="author" href="https://jaandrle.github.io/humans.txt"><meta name="generator" content="deka-dom-el"><!--<dde:mark type="component" name="metaTwitter" host="this" ssr/>--><meta name="twitter:card" content="summary_large_image"><meta name="twitter:url" content="https://github.com/jaandrle/deka-dom-el"><meta name="twitter:title" content="deka-dom-el"><meta name="twitter:description" content="A low-code library that simplifies the creation of native DOM elements/components using small wrappers and tweaks."><meta name="twitter:creator" content="@jaandrle"><!--<dde:mark type="component" name="metaFacebook" host="this" ssr/>--><meta name="og:url" content="https://github.com/jaandrle/deka-dom-el"><meta name="og:title" content="deka-dom-el"><meta name="og:description" content="A low-code library that simplifies the creation of native DOM elements/components using small wrappers and tweaks."><meta name="og:creator" content="@jaandrle"><script src="https://flems.io/flems.html" type="text/javascript" charset="utf-8"></script><link rel="stylesheet" href="global.css"></head><body><!--<dde:mark type="component" name="page" host="this" ssr/>--><!--<dde:mark type="component" name="header" host="this" ssr/>--><header><h1>`deka-dom-el` — Introduction</h1><p>Introducing a&nbsp;library.</p></header><nav><a href="https://github.com/jaandrle/deka-dom-el"><svg class="icon" viewBox="0 0 32 32"><!--<dde:mark type="component" name="iconGitHub" host="parentElement" ssr/>--><path d="M 16,0.395c -8.836,0 -16,7.163 -16,16c 0,7.069 4.585,13.067 10.942,15.182c 0.8,0.148 1.094,-0.347 1.094,-0.77c 0,-0.381 -0.015,-1.642 -0.022,-2.979c -4.452,0.968 -5.391,-1.888 -5.391,-1.888c -0.728,-1.849 -1.776,-2.341 -1.776,-2.341c -1.452,-0.993 0.11,-0.973 0.11,-0.973c 1.606,0.113 2.452,1.649 2.452,1.649c 1.427,2.446 3.743,1.739 4.656,1.33c 0.143,-1.034 0.558,-1.74 1.016,-2.14c -3.554,-0.404 -7.29,-1.777 -7.29,-7.907c 0,-1.747 0.625,-3.174 1.649,-4.295c -0.166,-0.403 -0.714,-2.03 0.155,-4.234c 0,0 1.344,-0.43 4.401,1.64c 1.276,-0.355 2.645,-0.532 4.005,-0.539c 1.359,0.006 2.729,0.184 4.008,0.539c 3.054,-2.07 4.395,-1.64 4.395,-1.64c 0.871,2.204 0.323,3.831 0.157,4.234c 1.026,1.12 1.647,2.548 1.647,4.295c 0,6.145 -3.743,7.498 -7.306,7.895c 0.574,0.497 1.085,1.47 1.085,2.963c 0,2.141 -0.019,3.864 -0.019,4.391c 0,0.426 0.288,0.925 1.099,0.768c 6.354,-2.118 10.933,-8.113 10.933,-15.18c 0,-8.837 -7.164,-16 -16,-16Z"></path></svg>GitHub</a><a href="./" title="Introducing a&nbsp;library." class="current">1. Introduction</a><a href="elements" title="Basic concepts of elements modifications and creations.">2. Elements</a><a href="events" title="Using not only events in UI declaratively.">3. Events and Modifiers</a></nav><main><p>The library tries to provide pure JavaScript tool(s) to create reactive interfaces.</p><p>We start with creating and modifying a&nbsp;static elements and end up with UI templates. <i>From <code>document.createElement</code> to <code>el</code>.</i> Then we go through the native events system and the way to include it declaratively in UI templates. <i>From <code>element.addEventListener</code> to <code>on</code>.</i></p><p>Next step is providing interactivity not only for our UI templates. We introduce signals (<code>S</code>) and how them incorporate to UI templates.</p><p>Now we will clarify how the signals are incorporated into our templates with regard to application performance. This is not the only reason the library uses <code>scope</code>s. We will look at how they work in components represented in JavaScript by functions.</p><!--<dde:mark type="component" name="example" host="this" ssr/>--><div id="code-1pn55" class="example"><!--<dde:mark type="component" name="code" host="parentElement" ssr/>--><code class="language-js">import { el } from "https://cdn.jsdelivr.net/gh/jaandrle/deka-dom-el/dist/esm-with-signals.js"; <!DOCTYPE html><html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><meta name="description" content="Introducing a&nbsp;library."><title>`deka-dom-el` — Introduction</title><!--<dde:mark type="component" name="metaAuthor" host="this" ssr/>--><meta name="author" content="Jan Andrle"><link type="text/plain" rel="author" href="https://jaandrle.github.io/humans.txt"><meta name="generator" content="deka-dom-el"><!--<dde:mark type="component" name="metaTwitter" host="this" ssr/>--><meta name="twitter:card" content="summary_large_image"><meta name="twitter:url" content="https://github.com/jaandrle/deka-dom-el"><meta name="twitter:title" content="deka-dom-el"><meta name="twitter:description" content="A low-code library that simplifies the creation of native DOM elements/components using small wrappers and tweaks."><meta name="twitter:creator" content="@jaandrle"><!--<dde:mark type="component" name="metaFacebook" host="this" ssr/>--><meta name="og:url" content="https://github.com/jaandrle/deka-dom-el"><meta name="og:title" content="deka-dom-el"><meta name="og:description" content="A low-code library that simplifies the creation of native DOM elements/components using small wrappers and tweaks."><meta name="og:creator" content="@jaandrle"><script src="https://flems.io/flems.html" type="text/javascript" charset="utf-8"></script><link rel="stylesheet" href="global.css"></head><body><!--<dde:mark type="component" name="page" host="this" ssr/>--><!--<dde:mark type="component" name="header" host="this" ssr/>--><header><h1>`deka-dom-el` — Introduction</h1><p>Introducing a&nbsp;library.</p></header><nav><a href="https://github.com/jaandrle/deka-dom-el"><svg class="icon" viewBox="0 0 32 32"><!--<dde:mark type="component" name="iconGitHub" host="parentElement" ssr/>--><path d="M 16,0.395c -8.836,0 -16,7.163 -16,16c 0,7.069 4.585,13.067 10.942,15.182c 0.8,0.148 1.094,-0.347 1.094,-0.77c 0,-0.381 -0.015,-1.642 -0.022,-2.979c -4.452,0.968 -5.391,-1.888 -5.391,-1.888c -0.728,-1.849 -1.776,-2.341 -1.776,-2.341c -1.452,-0.993 0.11,-0.973 0.11,-0.973c 1.606,0.113 2.452,1.649 2.452,1.649c 1.427,2.446 3.743,1.739 4.656,1.33c 0.143,-1.034 0.558,-1.74 1.016,-2.14c -3.554,-0.404 -7.29,-1.777 -7.29,-7.907c 0,-1.747 0.625,-3.174 1.649,-4.295c -0.166,-0.403 -0.714,-2.03 0.155,-4.234c 0,0 1.344,-0.43 4.401,1.64c 1.276,-0.355 2.645,-0.532 4.005,-0.539c 1.359,0.006 2.729,0.184 4.008,0.539c 3.054,-2.07 4.395,-1.64 4.395,-1.64c 0.871,2.204 0.323,3.831 0.157,4.234c 1.026,1.12 1.647,2.548 1.647,4.295c 0,6.145 -3.743,7.498 -7.306,7.895c 0.574,0.497 1.085,1.47 1.085,2.963c 0,2.141 -0.019,3.864 -0.019,4.391c 0,0.426 0.288,0.925 1.099,0.768c 6.354,-2.118 10.933,-8.113 10.933,-15.18c 0,-8.837 -7.164,-16 -16,-16Z"></path></svg>GitHub</a><a href="./" title="Introducing a&nbsp;library." class="current">1. Introduction</a><a href="elements" title="Basic concepts of elements modifications and creations.">2. Elements</a><a href="events" title="Using not only events in UI declaratively.">3. Events and Addons</a></nav><main><p>The library tries to provide pure JavaScript tool(s) to create reactive interfaces.</p><p>We start with creating and modifying a&nbsp;static elements and end up with UI templates. <i>From <code>document.createElement</code> to <code>el</code>.</i> Then we go through the native events system and the way to include it declaratively in UI templates. <i>From <code>element.addEventListener</code> to <code>on</code>.</i></p><p>Next step is providing interactivity not only for our UI templates. We introduce signals (<code>S</code>) and how them incorporate to UI templates.</p><p>Now we will clarify how the signals are incorporated into our templates with regard to application performance. This is not the only reason the library uses <code>scope</code>s. We will look at how they work in components represented in JavaScript by functions.</p><!--<dde:mark type="component" name="example" host="this" ssr/>--><div id="code-wy063" class="example"><!--<dde:mark type="component" name="code" host="parentElement" ssr/>--><code class="language-js">import { el } from "https://cdn.jsdelivr.net/gh/jaandrle/deka-dom-el/dist/esm-with-signals.js";
import { S } from "https://cdn.jsdelivr.net/gh/jaandrle/deka-dom-el/dist/esm-with-signals.js"; import { S } from "https://cdn.jsdelivr.net/gh/jaandrle/deka-dom-el/dist/esm-with-signals.js";
const clicks= S(0); const clicks= S(0);
document.body.append( document.body.append(
@ -13,4 +13,4 @@ document.body.append(
}) })
) )
); );
</code></div><script>Flems(document.getElementById("code-1pn55"), JSON.parse("{\"files\":[{\"name\":\".js\",\"content\":\"import { el } from \\\"https://cdn.jsdelivr.net/gh/jaandrle/deka-dom-el/dist/esm-with-signals.js\\\";\\nimport { S } from \\\"https://cdn.jsdelivr.net/gh/jaandrle/deka-dom-el/dist/esm-with-signals.js\\\";\\nconst clicks= S(0);\\ndocument.body.append(\\n\\tel().append(\\n\\t\\tel(\\\"p\\\", S(()=>\\n\\t\\t\\t\\\"Hello World \\\"+\\\"🎉\\\".repeat(clicks())\\n\\t\\t)),\\n\\t\\tel(\\\"button\\\", {\\n\\t\\t\\ttype: \\\"button\\\",\\n\\t\\t\\tonclick: ()=> clicks(clicks()+1),\\n\\t\\t\\ttextContent: \\\"Fire\\\"\\n\\t\\t})\\n\\t)\\n);\\n\"}],\"toolbar\":false}"));</script><div class="prevNext"><!--<dde:mark type="component" name="prevNext" host="parentElement" ssr/>--><!--<dde:mark type="component" name="pageLink" host="this" ssr/>--><a rel="next" href="elements" title="Basic concepts of elements modifications and creations."><!--<dde:mark type="component" name="pageLink" host="parentElement" ssr/>-->(next) Elements</a></div></main></body></html> </code></div><script>Flems(document.getElementById("code-wy063"), JSON.parse("{\"files\":[{\"name\":\".js\",\"content\":\"import { el } from \\\"https://cdn.jsdelivr.net/gh/jaandrle/deka-dom-el/dist/esm-with-signals.js\\\";\\nimport { S } from \\\"https://cdn.jsdelivr.net/gh/jaandrle/deka-dom-el/dist/esm-with-signals.js\\\";\\nconst clicks= S(0);\\ndocument.body.append(\\n\\tel().append(\\n\\t\\tel(\\\"p\\\", S(()=>\\n\\t\\t\\t\\\"Hello World \\\"+\\\"🎉\\\".repeat(clicks())\\n\\t\\t)),\\n\\t\\tel(\\\"button\\\", {\\n\\t\\t\\ttype: \\\"button\\\",\\n\\t\\t\\tonclick: ()=> clicks(clicks()+1),\\n\\t\\t\\ttextContent: \\\"Fire\\\"\\n\\t\\t})\\n\\t)\\n);\\n\"}],\"toolbar\":false}"));</script><div class="prevNext"><!--<dde:mark type="component" name="prevNext" host="parentElement" ssr/>--><!--<dde:mark type="component" name="pageLink" host="this" ssr/>--><a rel="next" href="elements" title="Basic concepts of elements modifications and creations."><!--<dde:mark type="component" name="pageLink" host="parentElement" ssr/>-->(next) Elements</a></div></main></body></html>

16
docs_src/components/examples/elements/dekaAssign.js
View File

@ -1,15 +1,22 @@
import { assignAttribute, classListDeclarative } from "deka-dom-el"; import { assign, assignAttribute, classListDeclarative } from "deka-dom-el";
const paragraph= document.createElement("p"); const paragraph= document.createElement("p");
assignAttribute(paragraph, "textContent", "Hello, world!"); assignAttribute(paragraph, "textContent", "Hello, world!");
assignAttribute(paragraph, "style", "color: red; font-weight: bold;");
assignAttribute(paragraph, "style", { color: "navy" }); assignAttribute(paragraph, "style", { color: "navy" });
assignAttribute(paragraph, "dataTest1", "v1"); assignAttribute(paragraph, "dataTest1", "v1");
assignAttribute(paragraph, "dataset", { test2: "v2" }); assignAttribute(paragraph, "dataset", { test2: "v2" });
assignAttribute(paragraph, "ariaLabel", "v1"); assign(paragraph, { //textContent and style see above
assignAttribute(paragraph, "ariaset", { role: "none" }); ariaLabel: "v1", //data* see above
ariaset: { role: "none" }, // dataset see above
"=onclick": "console.log(event)",
onmouseout: console.info,
".something": "something",
classList: {} //see below
});
classListDeclarative(paragraph, { classListDeclarative(paragraph, {
classAdd: true, classAdd: true,
@ -20,6 +27,7 @@ classListDeclarative(paragraph, {
}); });
console.log(paragraph.outerHTML); console.log(paragraph.outerHTML);
console.log("paragraph.something=", paragraph.something);
document.body.append( document.body.append(
paragraph paragraph
); );

14
docs_src/components/examples/events/compareDispatch.js Normal file
View File

@ -0,0 +1,14 @@
import { el, on, dispatchEvent } from "deka-dom-el";
document.body.append(
el("p", "Listenning to `test` event.", on("test", console.log)).append(
el("br"),
el("button", "native", on("click", native)),
" ",
el("button", "dde", on("click", dde)),
" ",
el("button", "dde with options", on("click", ddeOptions))
)
);
function native(){ this.dispatchEvent(new CustomEvent("test", { bubbles: true, detail: "hi" })); }
function dde(){ dispatchEvent("test")(this.parentElement, "hi"); }
function ddeOptions(){ dispatchEvent("test", { bubbles: true })(this, "hi"); }

18
docs_src/components/examples/events/live-cycle.js Normal file
View File

@ -0,0 +1,18 @@
import { el, on } from "deka-dom-el";
const paragraph= el("p", "See live-cycle events in console.",
el=> log({ type: "dde:created", detail: el }),
on.connected(log),
on.disconnected(log),
on.attributeChanged(log));
document.body.append(
paragraph,
el("button", "Update attribute", on("click", ()=> paragraph.setAttribute("test", Math.random().toString()))),
" ",
el("button", "Remove", on("click", ()=> paragraph.remove()))
);
/** @param {Partial<CustomEvent>} event */
function log({ type, detail }){
console.log({ _this: this, type, detail });
}

2
docs_src/components/examples/events/templateWithListeners.js
View File

@ -1,7 +1,7 @@
import { el, on } from "deka-dom-el"; import { el, on } from "deka-dom-el";
const abort_controller= new AbortController(); const abort_controller= new AbortController();
const { signal }= abort_controller; const { signal }= abort_controller;
/** @type {ddeElementModifier<HTMLButtonElement>} */ /** @type {ddeElementAddon<HTMLButtonElement>} */
const onclickOff= on("click", ()=> abort_controller.abort(), { signal }); const onclickOff= on("click", ()=> abort_controller.abort(), { signal });
/** @type {(ref?: HTMLOutputElement)=> HTMLOutputElement | null} */ /** @type {(ref?: HTMLOutputElement)=> HTMLOutputElement | null} */
const ref= (store=> ref=> ref ? (store= ref) : store)(null); const ref= (store=> ref=> ref ? (store= ref) : store)(null);

12
docs_src/components/prevNext.html.js → docs_src/components/pageUtils.html.js
View File

@ -15,6 +15,18 @@ styles.scope(prevNext).css`
} }
`; `;
import { el } from "../../index.js"; import { el } from "../../index.js";
/**
* @param {Object} attrs
* @param {string} attrs.textContent
* @param {string} [attrs.id]
* */
export function h3({ textContent, id }){
if(!id) id= "h-"+textContent.toLowerCase().replaceAll(/\s/g, "-").replaceAll(/[^a-z-]/g, "");
return el("h3", { id }).append(
el("a", { textContent: "§", href: "#"+id, tabIndex: -1 }),
" ", textContent
);
}
/** /**
* @param {import("../types.d.ts").Info} page * @param {import("../types.d.ts").Info} page
* */ * */

17
docs_src/elements.html.js
View File

@ -1,11 +1,13 @@
import "./global.css.js"; import "./global.css.js";
import { el } from "deka-dom-el"; import { el } from "deka-dom-el";
import { header } from "./layout/head.html.js";
import { example } from "./components/example.html.js"; import { example } from "./components/example.html.js";
import { h3, prevNext } from "./components/pageUtils.html.js";
/** @param {string} url */ /** @param {string} url */
const fileURL= url=> new URL(url, import.meta.url); const fileURL= url=> new URL(url, import.meta.url);
import { header } from "./layout/head.html.js";
import { prevNext } from "./components/prevNext.html.js";
/** @param {import("./types.d.ts").PageAttrs} attrs */ /** @param {import("./types.d.ts").PageAttrs} attrs */
export function page({ pkg, info }){ export function page({ pkg, info }){
const page_id= info.id; const page_id= info.id;
@ -15,7 +17,7 @@ export function page({ pkg, info }){
el("h2", "Native JavaScript DOM elements creations"), el("h2", "Native JavaScript DOM elements creations"),
el("p", "Let’s go through all patterns we would like to use and what needs to be improved for better experience."), el("p", "Let’s go through all patterns we would like to use and what needs to be improved for better experience."),
el("h3", "Creating element(s) (with custom attributes)"), el(h3, "Creating element(s) (with custom attributes)"),
el("p").append( el("p").append(
"You can create a native DOM element by using the ", "You can create a native DOM element by using the ",
el("a", { href: "https://developer.mozilla.org/en-US/docs/Web/API/Document/createElement", title: "MDN documentation for document.createElement()" }).append( el("a", { href: "https://developer.mozilla.org/en-US/docs/Web/API/Document/createElement", title: "MDN documentation for document.createElement()" }).append(
@ -71,6 +73,9 @@ export function page({ pkg, info }){
el("em").append( el("em").append(
"For example, natievly the element’s ", el("code", "id"), " is removed by setting the IDL to an empty string." "For example, natievly the element’s ", el("code", "id"), " is removed by setting the IDL to an empty string."
) )
),
el("li").append(
"You can use ", el("code", "="), " or ", el("code", "."), " to force processing given key as attribute/property of the element."
) )
), ),
el("p").append( el("p").append(
@ -78,7 +83,7 @@ export function page({ pkg, info }){
), ),
el(example, { src: fileURL("./components/examples/elements/dekaAssign.js"), page_id }), el(example, { src: fileURL("./components/examples/elements/dekaAssign.js"), page_id }),
el("h3", "Native JavaScript templating"), el(h3, "Native JavaScript templating"),
el("p", "By default, the native JS has no good way to define HTML template using DOM API:"), el("p", "By default, the native JS has no good way to define HTML template using DOM API:"),
el(example, { src: fileURL("./components/examples/elements/nativeAppend.js"), page_id }), el(example, { src: fileURL("./components/examples/elements/nativeAppend.js"), page_id }),
el("p").append( el("p").append(
@ -87,7 +92,7 @@ export function page({ pkg, info }){
el(example, { src: fileURL("./components/examples/elements/dekaAppend.js"), page_id }), el(example, { src: fileURL("./components/examples/elements/dekaAppend.js"), page_id }),
el("h3", "Basic (state-less) components"), el(h3, "Basic (state-less) components"),
el("p").append( el("p").append(
"You can use functions for encapsulation (repeating) logic. ", "You can use functions for encapsulation (repeating) logic. ",
"The ", el("code", "el"), " accepts function as first argument. ", "The ", el("code", "el"), " accepts function as first argument. ",
@ -104,7 +109,7 @@ export function page({ pkg, info }){
" and keep track of the native API (things are best remembered through regular use).", " and keep track of the native API (things are best remembered through regular use).",
), ),
el("h3", "Creating non-HTML elements"), el(h3, "Creating non-HTML elements"),
el("p").append( el("p").append(
"Similarly to the native DOM API (", el("a", { href: "https://developer.mozilla.org/en-US/docs/Web/API/Document/createElementNS", title: "MDN" }).append(el("code", "document.createElementNS")), ") for non-HTML elements", "Similarly to the native DOM API (", el("a", { href: "https://developer.mozilla.org/en-US/docs/Web/API/Document/createElementNS", title: "MDN" }).append(el("code", "document.createElementNS")), ") for non-HTML elements",
" we need to tell JavaScript which kind of the element to create.", " we need to tell JavaScript which kind of the element to create.",

84
docs_src/events.html.js
View File

@ -1,26 +1,28 @@
import "./global.css.js"; import "./global.css.js";
import { el } from "deka-dom-el"; import { el } from "deka-dom-el";
import { header } from "./layout/head.html.js";
import { example } from "./components/example.html.js"; import { example } from "./components/example.html.js";
import { h3, prevNext } from "./components/pageUtils.html.js";
/** @param {string} url */ /** @param {string} url */
const fileURL= url=> new URL(url, import.meta.url); const fileURL= url=> new URL(url, import.meta.url);
import { header } from "./layout/head.html.js";
import { prevNext } from "./components/prevNext.html.js";
/** @param {import("./types.d.ts").PageAttrs} attrs */ /** @param {import("./types.d.ts").PageAttrs} attrs */
export function page({ pkg, info }){ export function page({ pkg, info }){
const page_id= info.id; const page_id= info.id;
return el().append( return el().append(
el(header, { info, pkg }), el(header, { info, pkg }),
el("main").append( el("main").append(
el("h2", "Listenning to the native DOM events and other Modifiers"), el("h2", "Listenning to the native DOM events and other Addons"),
el("p").append( el("p").append(
"We quickly introduce helper to listening to the native DOM events.", "We quickly introduce helper to listening to the native DOM events.",
" ", " ",
"And library syntax/pattern so-called ", el("em", "Modifier"), " to", "And library syntax/pattern so-called ", el("em", "Addon"), " to",
" incorporate not only this in UI templates declaratively." " incorporate not only this in UI templates declaratively."
), ),
el("h3", "Events and listenners"), el(h3, "Events and listenners"),
el("p").append( el("p").append(
"In JavaScript you can listen to the native DOM events of the given element by using ", "In JavaScript you can listen to the native DOM events of the given element by using ",
el("a", { href: "https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener", title: "addEventListener on MDN" }).append( el("a", { href: "https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener", title: "addEventListener on MDN" }).append(
@ -32,37 +34,85 @@ export function page({ pkg, info }){
), ),
el(example, { src: fileURL("./components/examples/events/compare.js"), page_id }), el(example, { src: fileURL("./components/examples/events/compare.js"), page_id }),
el("p").append( el("p").append(
"…this is actually one of the two differences. The another one is that", el("code", "on"), "…this is actually one of the two differences. The another one is that ", el("code", "on"),
" accepts only object as the ", el("code", "options"), " (but it is still optional)." " accepts only object as the ", el("code", "options"), " (but it is still optional)."
), ),
el("p").append( el("p", { className: "notice" }).append(
"The other difference is that there is ", el("strong", "no"), " ", el("code", "off"), " function.", "The other difference is that there is ", el("strong", "no"), " ", el("code", "off"), " function.",
" ", " ",
"You can remove listener declaratively using ", el("a", { textContent: "AbortSignal", href: "https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener#signal", title: "part of addEventListener on MDN" }), "You can remove listener declaratively using ", el("a", { textContent: "AbortSignal", href: "https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener#signal", title: "part of addEventListener on MDN" }),
":" ":"
), ),
el(example, { src: fileURL("./components/examples/events/abortSignal.js"), page_id }), el(example, { src: fileURL("./components/examples/events/abortSignal.js"), page_id }),
el("div", { className: "notice" }).append(
el("h3", "Modifiers"), el("p", "So, there are (typically) three ways to handle events. You can use:"),
el("ul").append(
el("li").append( el("code", `el("button", { textContent: "click me", "=onclick": "console.log(event)" })`)),
el("li").append( el("code", `el("button", { textContent: "click me", onclick: console.log })`)),
el("li").append( el("code", `el("button", { textContent: "click me" }, on("click", console.log))`))
),
el("p").append( el("p").append(
"From practical point of view, ", el("em", "Modifiers"), " are just functions that accept any html element", "In the first example we force to use HTML attribute (it corresponds to ", el("code", `<button onclick="console.log(event)">click me</button>`), ").",
" ",
el("em", "Side note: this can be useful in case of SSR."),
" ",
"To study difference, you can read a nice summary here: ", el("a", { href: "https://gist.github.com/WebReflection/b404c36f46371e3b1173bf5492acc944", textContent: "GIST @WebReflection/web_events.md" }), "."
)
),
el(h3, "Addons"),
el("p").append(
"From practical point of view, ", el("em", "Addons"), " are just functions that accept any html element",
" as their first parameter. You can see that the ", el("code", "on(…)"), " fullfills this requirement." " as their first parameter. You can see that the ", el("code", "on(…)"), " fullfills this requirement."
), ),
el("p").append( el("p").append(
"You can use Modifiers as ≥3rd argument of ", el("code", "el"), " function. This way is possible to extends", "You can use Addons as ≥3rd argument of ", el("code", "el"), " function. This way is possible to extends",
" you templates by additional (3rd party) functionalities. But for now mainly, you can add events listeners:" " you templates by additional (3rd party) functionalities. But for now mainly, you can add events listeners:"
), ),
el(example, { src: fileURL("./components/examples/events/templateWithListeners.js"), page_id }), el(example, { src: fileURL("./components/examples/events/templateWithListeners.js"), page_id }),
el("p").append( el("p").append(
"As the example shows, you can also provide types in JSDoc+TypeScript by using global type ", el("code", "ddeElementModifier"), ".", "As the example shows, you can also provide types in JSDoc+TypeScript by using global type ", el("code", "ddeElementAddon"), ".",
" ", " ",
"Also notice, you can use Modifiers to get element reference.", "Also notice, you can use Addons to get element reference.",
),
el(h3, "Life-cycle events"),
el("p").append(
"Addons are called immediately when the element is created, even it is not connected to live DOM yet.",
" ",
"Therefore, you can understand the Addon to be “oncreate” event."
),
el("p").append(
"The library provide three additional live-cycle events corresponding to how they are named in",
" a case of custom elements: ", el("code", "on.connected"), ", ", el("code", "on.disconnected"),
" and ", el("code", "on.attributeChanged"), "."
),
el(example, { src: fileURL("./components/examples/events/live-cycle.js"), page_id }),
el("p").append(
"For Custom elements, we will later introduce a way to replace ", el("code", "*Callback"),
" syntax with ", el("code", "dde:*"), " events. The ", el("code", "on.*"), " functions then",
" listen to the appropriate Custom Elements events (see ", el("a", { textContent: "Custom element lifecycle callbacks | MDN", href: "https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements#custom_element_lifecycle_callbacks" }), ")."
),
el("p").append(
"But, in case of regular elemnets the ", el("a", { href: "https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver" }).append(el("code", "MutationObserver"), " | MDN"),
" is internaly used to track these events. Therefore, there are some drawbacks:",
),
el("ul").append(
el("li").append(
"To proper listener registration, you need to use ", el("code", "on.*"), " not `on(\"dde:*\", …)`!"
),
el("li").append(
"Use sparingly! Internally, library must loop of all registered events and fires event properly.",
" ",
el("strong", "It is good practice to use the fact that if an element is removed, its children are also removed!"),
" ",
"In this spirit, we will introduce later the ", el("strong", "host"), " syntax to register",
" clean up procedures when the component is removed from the app."
),
), ),
el("h3", "Life cycle events"),
el("p", "Modifiers are called immediately when the element is created, event it is not connected to live DOM yet."),
// todo
// dispatchEvent el(h3, "Final notes"),
el("p", "The library also provides a method to dispatch the events."),
el(example, { src: fileURL("./components/examples/events/compareDispatch.js"), page_id }),
el(prevNext, info) el(prevNext, info)
) )

7
docs_src/index.html.js
View File

@ -1,9 +1,10 @@
import { el } from "deka-dom-el";
import "./global.css.js"; import "./global.css.js";
import { example } from "./components/example.html.js"; import { el } from "deka-dom-el";
import { header } from "./layout/head.html.js"; import { header } from "./layout/head.html.js";
import { prevNext } from "./components/prevNext.html.js"; import { example } from "./components/example.html.js";
import { prevNext } from "./components/pageUtils.html.js";
/** @param {import("./types.d.ts").PageAttrs} attrs */ /** @param {import("./types.d.ts").PageAttrs} attrs */
export function page({ pkg, info }){ export function page({ pkg, info }){
const page_id= info.id; const page_id= info.id;

2
docs_src/ssr.js
View File

@ -5,7 +5,7 @@ export const path_target= {
export const pages= [ export const pages= [
{ id: "index", href: "./", title: "Introduction", description: "Introducing a library." }, { id: "index", href: "./", title: "Introduction", description: "Introducing a library." },
{ id: "elements", href: "elements", title: "Elements", description: "Basic concepts of elements modifications and creations." }, { id: "elements", href: "elements", title: "Elements", description: "Basic concepts of elements modifications and creations." },
{ id: "events", href: "events", title: "Events and Modifiers", description: "Using not only events in UI declaratively." }, { id: "events", href: "events", title: "Events and Addons", description: "Using not only events in UI declaratively." },
]; ];
/** /**
* @typedef registerClientFile * @typedef registerClientFile

2
examples/components/todosComponent.js
View File

@ -67,7 +67,7 @@ function todoComponent({ textContent, value }){
const value= Number(event.target.value); const value= Number(event.target.value);
event.preventDefault(); event.preventDefault();
event.stopPropagation(); event.stopPropagation();
dispatchEvent(host(), "remove", value); dispatchEvent("remove")(host(), value);
}); });
const is_editable= S(false); const is_editable= S(false);
const onedited= on("change", ev=> { const onedited= on("change", ev=> {

64
index.d.ts vendored
View File

@ -10,9 +10,10 @@ type SupportedElement=
| CustomElementTagNameMap[keyof CustomElementTagNameMap] | CustomElementTagNameMap[keyof CustomElementTagNameMap]
| ddePublicElementTagNameMap[keyof ddePublicElementTagNameMap]; | ddePublicElementTagNameMap[keyof ddePublicElementTagNameMap];
declare global { declare global {
type ddeComponentAttributes= Record<any, any> | undefined | string; type ddeComponentAttributes= Record<any, any> | undefined;
type ddeElementModifier<El extends SupportedElement | DocumentFragment>= (element: El)=> El; type ddeElementAddon<El extends SupportedElement | DocumentFragment>= (element: El)=> El | void;
} }
type PascalCase= `${Capitalize<string>}${string}`;
type AttrsModified= { type AttrsModified= {
/** /**
* Use string like in HTML (internally uses `*.setAttribute("style", *)`), or object representation (like DOM API). * Use string like in HTML (internally uses `*.setAttribute("style", *)`), or object representation (like DOM API).
@ -30,7 +31,7 @@ type AttrsModified= {
* Sets `aria-*` simiraly to `dataset` * Sets `aria-*` simiraly to `dataset`
* */ * */
ariaset: Record<string,string>, ariaset: Record<string,string>,
} } & Record<`=${string}` | `data${PascalCase}` | `aria${PascalCase}`, string> & Record<`.${string}`, any>
/** /**
* Just element attributtes * Just element attributtes
* *
@ -40,13 +41,15 @@ type AttrsModified= {
* @private * @private
*/ */
type ElementAttributes<T extends SupportedElement>= Omit<T,keyof AttrsModified> & AttrsModified; 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 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 type ExtendedHTMLElementTagNameMap= HTMLElementTagNameMap & CustomElementTagNameMap & ddePublicElementTagNameMap
export function el<TAG extends keyof ExtendedHTMLElementTagNameMap>( export function el<TAG extends keyof ExtendedHTMLElementTagNameMap>(
tag_name: TAG, tag_name: TAG,
attrs?: string | Partial<ElementAttributes<ExtendedHTMLElementTagNameMap[TAG]>>, attrs?: string | Partial<ElementAttributes<ExtendedHTMLElementTagNameMap[TAG]>>,
...modifiers: ddeElementModifier<ExtendedHTMLElementTagNameMap[TAG]>[] ...addons: ddeElementAddon<ExtendedHTMLElementTagNameMap[TAG]>[]
): ExtendedHTMLElementTagNameMap[TAG] ): ExtendedHTMLElementTagNameMap[TAG]
export function el<T>( export function el<T>(
tag_name?: "<>", tag_name?: "<>",
@ -54,16 +57,16 @@ export function el<T>(
export function el< export function el<
A extends ddeComponentAttributes, A extends ddeComponentAttributes,
C extends (attr: A)=> SupportedElement | DocumentFragment>( C extends (attr: Partial<A>)=> SupportedElement | DocumentFragment>(
fComponent: C, fComponent: C,
attrs?: A, attrs?: A | string,
...modifiers: ddeElementModifier<ReturnType<C>>[] ...addons: ddeElementAddon<ReturnType<C>>[]
): ReturnType<C> ): ReturnType<C>
export function el( export function el(
tag_name: string, tag_name: string,
attrs?: string | Record<string, any>, attrs?: string | Record<string, any>,
...modifiers: ddeElementModifier<HTMLElement>[] ...addons: ddeElementAddon<HTMLElement>[]
): HTMLElement ): HTMLElement
export function elNS( export function elNS(
@ -71,65 +74,72 @@ export function elNS(
): <TAG extends keyof SVGElementTagNameMap, KEYS extends keyof SVGElementTagNameMap[TAG] & { d: string }>( ): <TAG extends keyof SVGElementTagNameMap, KEYS extends keyof SVGElementTagNameMap[TAG] & { d: string }>(
tag_name: TAG, tag_name: TAG,
attrs?: string | Partial<{ [key in KEYS]: SVGElementTagNameMap[TAG][key] | string | number | boolean }>, attrs?: string | Partial<{ [key in KEYS]: SVGElementTagNameMap[TAG][key] | string | number | boolean }>,
...modifiers: ddeElementModifier<SVGElementTagNameMap[TAG]>[] ...addons: ddeElementAddon<SVGElementTagNameMap[TAG]>[]
)=> SVGElementTagNameMap[TAG] )=> SVGElementTagNameMap[TAG]
export function elNS( export function elNS(
namespace: "http://www.w3.org/1998/Math/MathML" namespace: "http://www.w3.org/1998/Math/MathML"
): <TAG extends keyof MathMLElementTagNameMap, KEYS extends keyof MathMLElementTagNameMap[TAG] & { d: string }>( ): <TAG extends keyof MathMLElementTagNameMap, KEYS extends keyof MathMLElementTagNameMap[TAG] & { d: string }>(
tag_name: TAG, tag_name: TAG,
attrs?: string | Partial<{ [key in KEYS]: MathMLElementTagNameMap[TAG][key] | string | number | boolean }>, attrs?: string | Partial<{ [key in KEYS]: MathMLElementTagNameMap[TAG][key] | string | number | boolean }>,
...modifiers: ddeElementModifier<MathMLElementTagNameMap[TAG]>[] ...addons: ddeElementAddon<MathMLElementTagNameMap[TAG]>[]
)=> MathMLElementTagNameMap[TAG] )=> MathMLElementTagNameMap[TAG]
export function elNS( export function elNS(
namespace: string namespace: string
): ( ): (
tag_name: string, tag_name: string,
attrs?: string | Record<string, any>, attrs?: string | Record<string, any>,
...modifiers: ddeElementModifier<SupportedElement>[] ...addons: ddeElementAddon<SupportedElement>[]
)=> SupportedElement )=> SupportedElement
export function chainableAppend<EL extends SupportedElement>(el: EL): EL; export function chainableAppend<EL extends SupportedElement>(el: EL): EL;
export function dispatchEvent(element: SupportedElement, name: keyof DocumentEventMap): void; export function dispatchEvent(name: keyof DocumentEventMap | string, options?: EventInit):
export function dispatchEvent(element: SupportedElement, name: string, data: any): void; (element: SupportedElement, data?: any)=> void;
interface On{ interface On{
/** Listens to the DOM event. See {@link Document.addEventListener} */ /** Listens to the DOM event. See {@link Document.addEventListener} */
< <
EE extends ddeElementModifier<SupportedElement>, EE extends ddeElementAddon<SupportedElement>,
El extends ( EE extends ddeElementModifier<infer El> ? El : never ), El extends ( EE extends ddeElementAddon<infer El> ? El : never ),
Event extends keyof DocumentEventMap>( Event extends keyof DocumentEventMap>(
type: Event, type: Event,
listener: (this: El, ev: DocumentEventMap[Event]) => any, listener: (this: El, ev: DocumentEventMap[Event]) => any,
options?: AddEventListenerOptions options?: AddEventListenerOptions
) : EE; ) : 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 */ /** 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< connected<
EE extends ddeElementModifier<SupportedElement>, EE extends ddeElementAddon<SupportedElement>,
El extends ( EE extends ddeElementModifier<infer El> ? El : never ) El extends ( EE extends ddeElementAddon<infer El> ? El : never )
>( >(
listener: (el: El) => any, listener: (this: El, event: CustomEvent<void>) => any,
options?: AddEventListenerOptions options?: AddEventListenerOptions
) : EE; ) : 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 */ /** 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< disconnected<
EE extends ddeElementModifier<SupportedElement>, EE extends ddeElementAddon<SupportedElement>,
El extends ( EE extends ddeElementModifier<infer El> ? El : never ) El extends ( EE extends ddeElementAddon<infer El> ? El : never )
>( >(
listener: (el: El) => any, listener: (this: El, event: CustomEvent<void>) => any,
options?: AddEventListenerOptions options?: AddEventListenerOptions
) : EE; ) : 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 */ /** 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< attributeChanged<
EE extends ddeElementModifier<SupportedElement>, EE extends ddeElementAddon<SupportedElement>,
El extends ( EE extends ddeElementModifier<infer El> ? El : never ) El extends ( EE extends ddeElementAddon<infer El> ? El : never )
>( >(
listener: (el: El) => any, listener: (this: El, event: CustomEvent<[ string, string ]>) => any,
options?: AddEventListenerOptions options?: AddEventListenerOptions
) : EE; ) : EE;
} }
export const on: On; export const on: On;
type Scope= { scope: Node | Function | Object, host: ddeElementModifier<any>, custom_element: false | HTMLElement, prevent: boolean } 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}) */ /** Current scope created last time the `el(Function)` was invoke. (Or {@link scope.push}) */
export const scope: { export const scope: {
current: Scope, current: Scope,
@ -139,10 +149,10 @@ export const scope: {
preventDefault<T extends boolean>(prevent: T): T, preventDefault<T extends boolean>(prevent: T): T,
/** /**
* This represents reference to the current host element — `scope.host()`. * This represents reference to the current host element — `scope.host()`.
* It can be also used to register Modifier (function to be called when component is initized) * It can be also used to register Addon (function to be called when component is initized)
* — `scope.host(on.connected(console.log))`. * — `scope.host(on.connected(console.log))`.
* */ * */
host: ddeElementModifier<any>, host: ddeElementAddon<any>,
state: Scope[], state: Scope[],
/** Adds new child scope. All attributes are inherited by default. */ /** Adds new child scope. All attributes are inherited by default. */

2
package.json
View File

@ -1,6 +1,6 @@
{ {
"name": "deka-dom-el", "name": "deka-dom-el",
"version": "0.7.0", "version": "0.7.1",
"description": "A low-code library that simplifies the creation of native DOM elements/components using small wrappers and tweaks.", "description": "A low-code library that simplifies the creation of native DOM elements/components using small wrappers and tweaks.",
"author": "Jan Andrle <andrle.jan@centrum.cz>", "author": "Jan Andrle <andrle.jan@centrum.cz>",
"license": "MIT", "license": "MIT",

6
src/dom.js
View File

@ -30,7 +30,7 @@ export const scope= {
function append(...els){ this.appendOriginal(...els); return this; } function append(...els){ this.appendOriginal(...els); return this; }
export function chainableAppend(el){ if(el.append===append) return el; el.appendOriginal= el.append; el.append= append; return el; } export function chainableAppend(el){ if(el.append===append) return el; el.appendOriginal= el.append; el.append= append; return el; }
let namespace; let namespace;
export function createElement(tag, attributes, ...modifiers){ export function createElement(tag, attributes, ...addons){
/* jshint maxcomplexity: 15 */ /* jshint maxcomplexity: 15 */
const s= signals(this); const s= signals(this);
let scoped= 0; let scoped= 0;
@ -41,7 +41,7 @@ export function createElement(tag, attributes, ...modifiers){
switch(true){ switch(true){
case typeof tag==="function": { case typeof tag==="function": {
scoped= 1; scoped= 1;
scope.push({ scope: tag, host: (...c)=> c.length ? (scoped===1 ? modifiers.unshift(...c) : c.forEach(c=> c(el_host)), undefined) : el_host }); scope.push({ scope: tag, host: (...c)=> c.length ? (scoped===1 ? addons.unshift(...c) : c.forEach(c=> c(el_host)), undefined) : el_host });
el= tag(attributes || undefined); el= tag(attributes || undefined);
const is_fragment= el instanceof DocumentFragment; const is_fragment= el instanceof DocumentFragment;
if(el.nodeName==="#comment") break; if(el.nodeName==="#comment") break;
@ -61,7 +61,7 @@ export function createElement(tag, attributes, ...modifiers){
} }
chainableAppend(el); chainableAppend(el);
if(!el_host) el_host= el; if(!el_host) el_host= el;
modifiers.forEach(c=> c(el_host)); addons.forEach(c=> c(el_host));
if(scoped) scope.pop(); if(scoped) scope.pop();
scoped= 2; scoped= 2;
return el; return el;

6
src/events.js
View File

@ -1,8 +1,10 @@
export { registerReactivity } from './signals-common.js'; export { registerReactivity } from './signals-common.js';
export function dispatchEvent(element, name, ...d){ export function dispatchEvent(name, options= {}){
const event= d.length ? new CustomEvent(name, { detail: d[0] }) : new Event(name); return function dispatch(element, ...d){
const event= d.length ? new CustomEvent(name, Object.assign({ detail: d[0] }, options)) : new Event(name, options);
return element.dispatchEvent(event); return element.dispatchEvent(event);
};
} }
export function on(event, listener, options){ export function on(event, listener, options){
return function registerElement(element){ return function registerElement(element){