🔤 ce wip

wrongly refactored in last commit

bs/docs.js

@@ -2,7 +2,7 @@
 /* jshint esversion: 11,-W097, -W040, module: true, node: true, expr: true, undef: true *//* global echo, $, pipe, s, fetch, cyclicLoop */
 echo("Building static documentation files…");
 echo("Preparing…");
-import { path_target, pages as pages_registered, styles, dispatchEvent } from "../docs_src/ssr.js";
+import { path_target, pages as pages_registered, styles, dispatchEvent, t } from "../docs_src/ssr.js";
 import { createHTMl } from "./docs/jsdom.js";
 import { register } from "../jsdom.js";
 const pkg= s.cat("package.json").xargs(JSON.parse);

dist/esm-with-signals.d.ts

@@ -1,69 +1,4 @@
-export type Signal<V, A>= (set?: V)=> V & A;
-type Action<V>= (this: { value: V, stopPropagation(): void }, ...a: any[])=> typeof signal._ | void;
-//type SymbolSignal= Symbol;
-type SymbolOnclear= symbol;
-type Actions<V>= Record<string | SymbolOnclear, Action<V>>;
-type OnListenerOptions= Pick<AddEventListenerOptions, "signal"> & { first_time?: boolean };
-interface signal{
-	_: Symbol
-	/**
-	 * Simple example:
-	 * ```js
-	 * const hello= S("Hello Signal");
-	 * ```
-	 * …simple todo signal:
-	 * ```js
-	 * const todos= S([], {
-	 * 	add(v){ this.value.push(S(v)); },
-	 * 	remove(i){ this.value.splice(i, 1); },
-	 * 	[S.symbols.onclear](){ S.clear(...this.value); },
-	 * });
-	 * ```
-	 * …computed signal:
-	 * ```js
-	 * const name= S("Jan");
-	 * const surname= S("Andrle");
-	 * const fullname= S(()=> name()+" "+surname());
-	 * ```
-	 * @param value Initial signal value. Or function computing value from other signals.
-	 * @param actions Use to define actions on the signal. Such as add item to the array.
-	 *		There is also a reserved function `S.symbol.onclear` which is called when the signal is cleared
-	 *		by `S.clear`.
-	 * */
-	<V, A extends Actions<V>>(value: V, actions?: A): Signal<V, A>;
-	/**
-	 * Computations signal. This creates a signal which is computed from other signals.
-	 * */
-	<V>(computation: ()=> V): Signal<V, {}>
-	action<S extends Signal<any, Actions<any>>, A extends (S extends Signal<any, infer A> ? A : never), N extends keyof A>(
-		signal: S,
-		name: N,
-		...params: A[N] extends (...args: infer P)=> any ? P : never
-	): void;
-	clear(...signals: Signal<any, any>[]): void;
-	on<T>(signal: Signal<T, any>, onchange: (a: T)=> void, options?: OnListenerOptions): void;
-	symbols: {
-		//signal: SymbolSignal;
-		onclear: SymbolOnclear;
-	}
-	/**
-	 * Reactive element, which is rendered based on the given signal.
-	 * ```js
-	 * S.el(signal, value=> value ? el("b", "True") : el("i", "False"));
-	 * S.el(listS, list=> list.map(li=> el("li", li)));
-	 * ```
-	 * */
-	el<S extends any>(signal: Signal<S, any>, el: (v: S)=> Element | Element[] | DocumentFragment): DocumentFragment;
-
-    observedAttributes(custom_element: HTMLElement): Record<string, Signal<any, any>>;
-}
-export const signal: signal;
-export const S: signal;
-declare global {
-	type ddeSignal<T, A= {}>= Signal<T, A>;
-	type ddeAction<V>= Action<V>
-	type ddeActions<V>= Actions<V>
-}
+declare global{ /* ddeSignal */ }
 type CustomElementTagNameMap= { '#text': Text, '#comment': Comment }
 type SupportedElement=
 	  HTMLElementTagNameMap[keyof HTMLElementTagNameMap]
@@ -80,20 +15,20 @@ type AttrsModified= {
 	/**
 	 * Use string like in HTML (internally uses `*.setAttribute("style", *)`), or object representation (like DOM API).
 	 */
-	style: string | Partial<CSSStyleDeclaration> | Signal<string, any> | Partial<{ [K in keyof CSSStyleDeclaration]: Signal<CSSStyleDeclaration[K], any> }>
+	style: string | Partial<CSSStyleDeclaration> | ddeSignal<string> | Partial<{ [K in keyof CSSStyleDeclaration]: ddeSignal<CSSStyleDeclaration[K]> }>
 	/**
 	 * Provide option to add/remove/toggle CSS clasess (index of object) using 1/0/-1. In fact `el.classList.toggle(class_name)` for `-1` and `el.classList.toggle(class_name, Boolean(...))` for others.
 	 */
-	classList: Record<string,-1|0|1|boolean|Signal<-1|0|1|boolean, any>>,
+	classList: Record<string,-1|0|1|boolean|ddeSignal<-1|0|1|boolean>>,
 	/**
 	 * By default simiral to `className`, but also supports `string[]`
 	 * */
-	className: string | (string|boolean|undefined|Signal<string|boolean|undefined, any>)[];
+	className: string | (string|boolean|undefined|ddeSignal<string|boolean|undefined>)[];
 	/**
 	 * Sets `aria-*` simiraly to `dataset`
 	 * */
-	ariaset: Record<string,string|Signal<string, any>>,
-} & Record<`=${string}` | `data${PascalCase}` | `aria${PascalCase}`, string|Signal<string, any>> & Record<`.${string}`, any>
+	ariaset: Record<string,string|ddeSignal<string>>,
+} & Record<`=${string}` | `data${PascalCase}` | `aria${PascalCase}`, string|ddeSignal<string>> & Record<`.${string}`, any>
 type _fromElsInterfaces<EL extends SupportedElement>= Omit<EL, keyof AttrsModified>;
 /**
  * Just element attributtes
@@ -103,15 +38,15 @@ type _fromElsInterfaces<EL extends SupportedElement>= Omit<EL, keyof AttrsModifi
  * There is added support for `data[A-Z].*`/`aria[A-Z].*` to be converted to the kebab-case alternatives.
  * @private
  */
-type ElementAttributes<T extends SupportedElement>= Partial<_fromElsInterfaces<T> & { [K in keyof _fromElsInterfaces<T>]: Signal<_fromElsInterfaces<T>[K], any> } & AttrsModified> & Record<string, any>;
+type ElementAttributes<T extends SupportedElement>= Partial<{ [K in keyof _fromElsInterfaces<T>]: _fromElsInterfaces<T>[K] | ddeSignal<_fromElsInterfaces<T>[K]> } & AttrsModified> & Record<string, any>;
 export function classListDeclarative<El extends SupportedElement>(element: El, classList: AttrsModified["classList"]): El
 export function assign<El extends SupportedElement>(element: El, ...attrs_array: 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;
-type textContent= string | ( (set?: string)=> string ); // TODO: for some reason `Signal<string, any>` leads to `attrs?: any`
+type textContent= string | ddeSignal<string>;
 export function el<
-	TAG extends keyof ExtendedHTMLElementTagNameMap & string,
+	TAG extends keyof ExtendedHTMLElementTagNameMap,
 	EL extends (TAG extends keyof ExtendedHTMLElementTagNameMap ? ExtendedHTMLElementTagNameMap[TAG] : HTMLElement)
 >(
 	tag_name: TAG,
@@ -121,6 +56,11 @@ export function el<
 export function el(
 	tag_name?: "<>",
 ): ddeDocumentFragment
+export function el(
+	tag_name: string,
+	attrs?: ElementAttributes<HTMLElement>,
+	...addons: ddeElementAddon<HTMLElement>[]
+): ddeHTMLElement
 
 export function el<
 	C extends (attr: ddeComponentAttributes)=> SupportedElement | ddeDocumentFragment
@@ -148,7 +88,7 @@ export function elNS(
 	EL extends ( TAG extends keyof MathMLElementTagNameMap ? MathMLElementTagNameMap[TAG] : MathMLElement ),
 >(
 	tag_name: TAG,
-	attrs?: string | textContent | Partial<{ [key in keyof EL]: EL[key] | Signal<EL[key], any> | string | number | boolean }>,
+	attrs?: string | textContent | Partial<{ [key in keyof EL]: EL[key] | ddeSignal<EL[key]> | string | number | boolean }>,
 	...addons: ddeElementAddon<EL>[]
 )=> ddeMathMLElement
 export function elNS(
@@ -189,7 +129,7 @@ interface On{
 		EE extends ddeElementAddon<SupportedElement>,
 		El extends ( EE extends ddeElementAddon<infer El> ? El : never )
 		>(
-			listener: (this: El, event: CustomEvent<void>) => any,
+			listener: (this: El, event: CustomEvent<El>) => any,
 			options?: AddEventListenerOptions
 		) : EE;
 	/** Listens to the element is disconnected from the live DOM. In case of custom elements uses [`disconnectedCallback`](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements#custom_element_lifecycle_callbacks), or {@link MutationObserver} else where */
@@ -224,7 +164,7 @@ export const scope: {
 	 * It can be also used to register Addon(s) (functions to be called when component is initized)
 	 * — `scope.host(on.connected(console.log))`.
 	 * */
-	host: (...addons: ddeElementAddon<any>[])=> HTMLElement,
+	host: (...addons: ddeElementAddon<SupportedElement>[])=> HTMLElement,
 	
 	state: Scope[],
 	/** Adds new child scope. All attributes are inherited by default. */
@@ -237,15 +177,15 @@ export const scope: {
 
 export function customElementRender<
 	EL extends HTMLElement,
-	P extends any = Record<string, any>
+	P extends any = Record<string, string | ddeSignal<string>>
 >(
 	custom_element: EL,
 	target: ShadowRoot | EL,
-	render: (props: P)=> SupportedElement,
-	props?: P | ((...args: any[])=> P)
+	render: (props: P)=> SupportedElement | DocumentFragment,
+	props?: P | ((el: EL)=> P)
 ): EL
-export function customElementWithDDE<EL extends HTMLElement>(custom_element: EL): EL
-export function lifecyclesToEvents<EL extends HTMLElement>(custom_element: EL): EL
+export function customElementWithDDE<EL extends (new ()=> HTMLElement)>(custom_element: EL): EL
+export function lifecyclesToEvents<EL extends (new ()=> HTMLElement)>(custom_element: EL): EL
 export function observedAttributes(custom_element: HTMLElement): Record<string, string>
 
 /* TypeScript MEH */
@@ -525,4 +465,70 @@ interface ddeSVGTextPathElement extends SVGTextPathElement{ append: ddeAppend<dd
 interface ddeSVGTitleElement extends SVGTitleElement{ append: ddeAppend<ddeSVGTitleElement>; }
 interface ddeSVGTSpanElement extends SVGTSpanElement{ append: ddeAppend<ddeSVGTSpanElement>; }
 interface ddeSVGUseElement extends SVGUseElement{ append: ddeAppend<ddeSVGUseElement>; }
-interface ddeSVGViewElement extends SVGViewElement{ append: ddeAppend<ddeSVGViewElement>; }
+interface ddeSVGViewElement extends SVGViewElement{ append: ddeAppend<ddeSVGViewElement>; }
+export type Signal<V, A>= (set?: V)=> V & A;
+type Action<V>= (this: { value: V, stopPropagation(): void }, ...a: any[])=> typeof signal._ | void;
+//type SymbolSignal= Symbol;
+type SymbolOnclear= symbol;
+type Actions<V>= Record<string | SymbolOnclear, Action<V>>;
+type OnListenerOptions= Pick<AddEventListenerOptions, "signal"> & { first_time?: boolean };
+interface signal{
+	_: Symbol
+	/**
+	 * Computations signal. This creates a signal which is computed from other signals.
+	 * */
+	<V extends ()=> any>(computation: V): Signal<ReturnType<V>, {}>
+	/**
+	 * Simple example:
+	 * ```js
+	 * const hello= S("Hello Signal");
+	 * ```
+	 * …simple todo signal:
+	 * ```js
+	 * const todos= S([], {
+	 * 	add(v){ this.value.push(S(v)); },
+	 * 	remove(i){ this.value.splice(i, 1); },
+	 * 	[S.symbols.onclear](){ S.clear(...this.value); },
+	 * });
+	 * ```
+	 * …computed signal:
+	 * ```js
+	 * const name= S("Jan");
+	 * const surname= S("Andrle");
+	 * const fullname= S(()=> name()+" "+surname());
+	 * ```
+	 * @param value Initial signal value. Or function computing value from other signals.
+	 * @param actions Use to define actions on the signal. Such as add item to the array.
+	 *		There is also a reserved function `S.symbol.onclear` which is called when the signal is cleared
+	 *		by `S.clear`.
+	 * */
+	<V, A extends Actions<V>>(value: V, actions?: A): Signal<V, A>;
+	action<S extends Signal<any, Actions<any>>, A extends (S extends Signal<any, infer A> ? A : never), N extends keyof A>(
+		signal: S,
+		name: N,
+		...params: A[N] extends (...args: infer P)=> any ? P : never
+	): void;
+	clear(...signals: Signal<any, any>[]): void;
+	on<T>(signal: Signal<T, any>, onchange: (a: T)=> void, options?: OnListenerOptions): void;
+	symbols: {
+		//signal: SymbolSignal;
+		onclear: SymbolOnclear;
+	}
+	/**
+	 * Reactive element, which is rendered based on the given signal.
+	 * ```js
+	 * S.el(signal, value=> value ? el("b", "True") : el("i", "False"));
+	 * S.el(listS, list=> list.map(li=> el("li", li)));
+	 * ```
+	 * */
+	el<S extends any>(signal: Signal<S, any>, el: (v: S)=> Element | Element[] | DocumentFragment): DocumentFragment;
+
+    observedAttributes(custom_element: HTMLElement): Record<string, Signal<string, {}>>;
+}
+export const signal: signal;
+export const S: signal;
+declare global {
+	type ddeSignal<T, A= {}>= Signal<T, A>;
+	type ddeAction<V>= Action<V>
+	type ddeActions<V>= Actions<V>
+}

dist/esm.d.ts

@@ -1,69 +1,4 @@
-export type Signal<V, A>= (set?: V)=> V & A;
-type Action<V>= (this: { value: V, stopPropagation(): void }, ...a: any[])=> typeof signal._ | void;
-//type SymbolSignal= Symbol;
-type SymbolOnclear= symbol;
-type Actions<V>= Record<string | SymbolOnclear, Action<V>>;
-type OnListenerOptions= Pick<AddEventListenerOptions, "signal"> & { first_time?: boolean };
-interface signal{
-	_: Symbol
-	/**
-	 * Simple example:
-	 * ```js
-	 * const hello= S("Hello Signal");
-	 * ```
-	 * …simple todo signal:
-	 * ```js
-	 * const todos= S([], {
-	 * 	add(v){ this.value.push(S(v)); },
-	 * 	remove(i){ this.value.splice(i, 1); },
-	 * 	[S.symbols.onclear](){ S.clear(...this.value); },
-	 * });
-	 * ```
-	 * …computed signal:
-	 * ```js
-	 * const name= S("Jan");
-	 * const surname= S("Andrle");
-	 * const fullname= S(()=> name()+" "+surname());
-	 * ```
-	 * @param value Initial signal value. Or function computing value from other signals.
-	 * @param actions Use to define actions on the signal. Such as add item to the array.
-	 *		There is also a reserved function `S.symbol.onclear` which is called when the signal is cleared
-	 *		by `S.clear`.
-	 * */
-	<V, A extends Actions<V>>(value: V, actions?: A): Signal<V, A>;
-	/**
-	 * Computations signal. This creates a signal which is computed from other signals.
-	 * */
-	<V>(computation: ()=> V): Signal<V, {}>
-	action<S extends Signal<any, Actions<any>>, A extends (S extends Signal<any, infer A> ? A : never), N extends keyof A>(
-		signal: S,
-		name: N,
-		...params: A[N] extends (...args: infer P)=> any ? P : never
-	): void;
-	clear(...signals: Signal<any, any>[]): void;
-	on<T>(signal: Signal<T, any>, onchange: (a: T)=> void, options?: OnListenerOptions): void;
-	symbols: {
-		//signal: SymbolSignal;
-		onclear: SymbolOnclear;
-	}
-	/**
-	 * Reactive element, which is rendered based on the given signal.
-	 * ```js
-	 * S.el(signal, value=> value ? el("b", "True") : el("i", "False"));
-	 * S.el(listS, list=> list.map(li=> el("li", li)));
-	 * ```
-	 * */
-	el<S extends any>(signal: Signal<S, any>, el: (v: S)=> Element | Element[] | DocumentFragment): DocumentFragment;
-
-    observedAttributes(custom_element: HTMLElement): Record<string, Signal<any, any>>;
-}
-export const signal: signal;
-export const S: signal;
-declare global {
-	type ddeSignal<T, A= {}>= Signal<T, A>;
-	type ddeAction<V>= Action<V>
-	type ddeActions<V>= Actions<V>
-}
+declare global{ /* ddeSignal */ }
 type CustomElementTagNameMap= { '#text': Text, '#comment': Comment }
 type SupportedElement=
 	  HTMLElementTagNameMap[keyof HTMLElementTagNameMap]
@@ -80,20 +15,20 @@ type AttrsModified= {
 	/**
 	 * Use string like in HTML (internally uses `*.setAttribute("style", *)`), or object representation (like DOM API).
 	 */
-	style: string | Partial<CSSStyleDeclaration> | Signal<string, any> | Partial<{ [K in keyof CSSStyleDeclaration]: Signal<CSSStyleDeclaration[K], any> }>
+	style: string | Partial<CSSStyleDeclaration> | ddeSignal<string> | Partial<{ [K in keyof CSSStyleDeclaration]: ddeSignal<CSSStyleDeclaration[K]> }>
 	/**
 	 * Provide option to add/remove/toggle CSS clasess (index of object) using 1/0/-1. In fact `el.classList.toggle(class_name)` for `-1` and `el.classList.toggle(class_name, Boolean(...))` for others.
 	 */
-	classList: Record<string,-1|0|1|boolean|Signal<-1|0|1|boolean, any>>,
+	classList: Record<string,-1|0|1|boolean|ddeSignal<-1|0|1|boolean>>,
 	/**
 	 * By default simiral to `className`, but also supports `string[]`
 	 * */
-	className: string | (string|boolean|undefined|Signal<string|boolean|undefined, any>)[];
+	className: string | (string|boolean|undefined|ddeSignal<string|boolean|undefined>)[];
 	/**
 	 * Sets `aria-*` simiraly to `dataset`
 	 * */
-	ariaset: Record<string,string|Signal<string, any>>,
-} & Record<`=${string}` | `data${PascalCase}` | `aria${PascalCase}`, string|Signal<string, any>> & Record<`.${string}`, any>
+	ariaset: Record<string,string|ddeSignal<string>>,
+} & Record<`=${string}` | `data${PascalCase}` | `aria${PascalCase}`, string|ddeSignal<string>> & Record<`.${string}`, any>
 type _fromElsInterfaces<EL extends SupportedElement>= Omit<EL, keyof AttrsModified>;
 /**
  * Just element attributtes
@@ -103,15 +38,15 @@ type _fromElsInterfaces<EL extends SupportedElement>= Omit<EL, keyof AttrsModifi
  * There is added support for `data[A-Z].*`/`aria[A-Z].*` to be converted to the kebab-case alternatives.
  * @private
  */
-type ElementAttributes<T extends SupportedElement>= Partial<_fromElsInterfaces<T> & { [K in keyof _fromElsInterfaces<T>]: Signal<_fromElsInterfaces<T>[K], any> } & AttrsModified> & Record<string, any>;
+type ElementAttributes<T extends SupportedElement>= Partial<{ [K in keyof _fromElsInterfaces<T>]: _fromElsInterfaces<T>[K] | ddeSignal<_fromElsInterfaces<T>[K]> } & AttrsModified> & Record<string, any>;
 export function classListDeclarative<El extends SupportedElement>(element: El, classList: AttrsModified["classList"]): El
 export function assign<El extends SupportedElement>(element: El, ...attrs_array: 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;
-type textContent= string | ( (set?: string)=> string ); // TODO: for some reason `Signal<string, any>` leads to `attrs?: any`
+type textContent= string | ddeSignal<string>;
 export function el<
-	TAG extends keyof ExtendedHTMLElementTagNameMap & string,
+	TAG extends keyof ExtendedHTMLElementTagNameMap,
 	EL extends (TAG extends keyof ExtendedHTMLElementTagNameMap ? ExtendedHTMLElementTagNameMap[TAG] : HTMLElement)
 >(
 	tag_name: TAG,
@@ -121,6 +56,11 @@ export function el<
 export function el(
 	tag_name?: "<>",
 ): ddeDocumentFragment
+export function el(
+	tag_name: string,
+	attrs?: ElementAttributes<HTMLElement>,
+	...addons: ddeElementAddon<HTMLElement>[]
+): ddeHTMLElement
 
 export function el<
 	C extends (attr: ddeComponentAttributes)=> SupportedElement | ddeDocumentFragment
@@ -148,7 +88,7 @@ export function elNS(
 	EL extends ( TAG extends keyof MathMLElementTagNameMap ? MathMLElementTagNameMap[TAG] : MathMLElement ),
 >(
 	tag_name: TAG,
-	attrs?: string | textContent | Partial<{ [key in keyof EL]: EL[key] | Signal<EL[key], any> | string | number | boolean }>,
+	attrs?: string | textContent | Partial<{ [key in keyof EL]: EL[key] | ddeSignal<EL[key]> | string | number | boolean }>,
 	...addons: ddeElementAddon<EL>[]
 )=> ddeMathMLElement
 export function elNS(
@@ -189,7 +129,7 @@ interface On{
 		EE extends ddeElementAddon<SupportedElement>,
 		El extends ( EE extends ddeElementAddon<infer El> ? El : never )
 		>(
-			listener: (this: El, event: CustomEvent<void>) => any,
+			listener: (this: El, event: CustomEvent<El>) => any,
 			options?: AddEventListenerOptions
 		) : EE;
 	/** Listens to the element is disconnected from the live DOM. In case of custom elements uses [`disconnectedCallback`](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements#custom_element_lifecycle_callbacks), or {@link MutationObserver} else where */
@@ -224,7 +164,7 @@ export const scope: {
 	 * It can be also used to register Addon(s) (functions to be called when component is initized)
 	 * — `scope.host(on.connected(console.log))`.
 	 * */
-	host: (...addons: ddeElementAddon<any>[])=> HTMLElement,
+	host: (...addons: ddeElementAddon<SupportedElement>[])=> HTMLElement,
 	
 	state: Scope[],
 	/** Adds new child scope. All attributes are inherited by default. */
@@ -237,15 +177,15 @@ export const scope: {
 
 export function customElementRender<
 	EL extends HTMLElement,
-	P extends any = Record<string, any>
+	P extends any = Record<string, string | ddeSignal<string>>
 >(
 	custom_element: EL,
 	target: ShadowRoot | EL,
-	render: (props: P)=> SupportedElement,
-	props?: P | ((...args: any[])=> P)
+	render: (props: P)=> SupportedElement | DocumentFragment,
+	props?: P | ((el: EL)=> P)
 ): EL
-export function customElementWithDDE<EL extends HTMLElement>(custom_element: EL): EL
-export function lifecyclesToEvents<EL extends HTMLElement>(custom_element: EL): EL
+export function customElementWithDDE<EL extends (new ()=> HTMLElement)>(custom_element: EL): EL
+export function lifecyclesToEvents<EL extends (new ()=> HTMLElement)>(custom_element: EL): EL
 export function observedAttributes(custom_element: HTMLElement): Record<string, string>
 
 /* TypeScript MEH */

docs_src/components/examples/customElement/customElementWithDDE.js

@@ -0,0 +1,23 @@
+import { customElementWithDDE, el, on } from "deka-dom-el";
+export class HTMLCustomElement extends HTMLElement{
+	static tagName= "custom-element";
+	connectedCallback(){
+		this.append(
+			el("p", "Hello from custom element!")
+		);
+	}
+}
+customElementWithDDE(HTMLCustomElement);
+customElements.define(HTMLCustomElement.tagName, HTMLCustomElement);
+
+const instance= el(HTMLCustomElement.tagName);
+on.connected( // preffered
+	e=> console.log("Element connected to the DOM (v1):", e)
+)(instance);
+instance.addEventListener(
+	"dde:connected",
+	e=> console.log("Element connected to the DOM (v2):", e)
+);
+document.body.append(
+	instance,
+);

docs_src/components/examples/customElement/dde.js

@@ -0,0 +1,33 @@
+import {
+	customElementRender,
+	customElementWithDDE,
+} from "deka-dom-el";
+export class HTMLCustomElement extends HTMLElement{
+	static tagName= "custom-element";
+	static observedAttributes= [ "attr" ];
+	connectedCallback(){
+		customElementRender(
+			this,
+			this.attachShadow({ mode: "open" }),
+			ddeComponent
+		);
+	}
+	set attr(value){ this.setAttribute("attr", value); }
+	get attr(){ return this.getAttribute("attr"); }
+}
+
+import { el, on, scope } from "deka-dom-el";
+function ddeComponent({ attr }){
+	scope.host(
+		on.connected(e=> console.log(e.target.outerHTML)),
+	);
+	return el().append(
+		el("p", `Hello from Custom Element with attribute '${attr}'`)
+	);
+}
+customElementWithDDE(HTMLCustomElement);
+customElements.define(HTMLCustomElement.tagName, HTMLCustomElement);
+
+document.body.append(
+	el(HTMLCustomElement.tagName, { attr: "Attribute" })
+);

docs_src/components/examples/customElement/native-basic.js

@@ -1,5 +1,5 @@
-class CustomHTMLElement extends HTMLElement{
-	static tagName = "custom-element"; // just suggestion, we can use `el(CustomHTMLElement.tagName)`
+export class HTMLCustomElement extends HTMLElement{
+	static tagName= "custom-element"; // just suggestion, we can use `el(HTMLCustomElement.tagName)`
 	static observedAttributes= [ "custom-attribute" ];
 	constructor(){
 		super();
@@ -18,4 +18,4 @@ class CustomHTMLElement extends HTMLElement{
 	get customAttribute(){ return this.getAttribute("custom-attribute"); }
 	set customAttribute(value){ this.setAttribute("custom-attribute", value); }
 }
-customElements.define(CustomHTMLElement.tagName, CustomHTMLElement);
+customElements.define(HTMLCustomElement.tagName, HTMLCustomElement);

docs_src/components/examples/customElement/observedAttributes.js

@@ -0,0 +1,42 @@
+import {
+	customElementRender,
+	customElementWithDDE,
+	observedAttributes,
+	el, on, scope 
+} from "deka-dom-el";
+import { S } from "deka-dom-el/signals";
+export class HTMLCustomElement extends HTMLElement{
+	static tagName= "custom-element";
+	static observedAttributes= [ "attr" ];
+	connectedCallback(){
+		console.log(observedAttributes(this));
+		customElementRender(
+			this,
+			this.attachShadow({ mode: "open" }),
+			ddeComponent,
+			S.observedAttributes
+		);
+	}
+	set attr(value){ this.setAttribute("attr", value); }
+	get attr(){ return this.getAttribute("attr"); }
+}
+
+/** @param {{ attr: ddeSignal<string, {}> }} props */
+function ddeComponent({ attr }){
+	scope.host(
+		on.connected(e=> console.log(e.target.outerHTML)),
+	);
+	return el().append(
+		el("p", S(()=> `Hello from Custom Element with attribute '${attr()}'`))
+	);
+}
+customElementWithDDE(HTMLCustomElement);
+customElements.define(HTMLCustomElement.tagName, HTMLCustomElement);
+
+document.body.append(
+	el(HTMLCustomElement.tagName, { attr: "Attribute" })
+);
+setTimeout(
+	()=> document.querySelector(HTMLCustomElement.tagName).setAttribute("attr", "New Value"),
+	3*750
+);

docs_src/components/examples/introducing/3ps.js

@@ -0,0 +1,6 @@
+// pseudo code!
+const onchage=
+	event=>
+		console.log("Reacting to the:", event); // A
+input.addEventListener("change", onchange); // B
+input.dispatchEvent(new Event("change")); // C

docs_src/components/examples/introducing/helloWorld.js

@@ -1,15 +1,15 @@
 import { el } from "deka-dom-el";
 import { S } from "deka-dom-el/signals";
-const clicks= S(0);
+const clicks= S(0); // A
 document.body.append(
 	el().append(
 		el("p", S(()=>
-			"Hello World "+"🎉".repeat(clicks())
+			"Hello World "+"🎉".repeat(clicks()) // B
 		)),
 		el("button", {
 			type: "button",
-			onclick: ()=> clicks(clicks()+1),
-			textContent: "Fire"
+			onclick: ()=> clicks(clicks()+1), // C
+			textContent: "Fire",
 		})
 	)
 );

docs_src/components/mnemonic/customElement-init.js

@@ -4,7 +4,7 @@ import { mnemonicUl } from "../mnemonicUl.html.js";
 export function mnemonic(){
 	return mnemonicUl().append(
 		el("li").append(
-			el("code", "customElementRender(<custom-element>, <render-function>[, <properties>])"), " — use function to render DOM structure for given <custom-element>",
+			el("code", "customElementRender(<custom-element>, <connect-target>, <render-function>[, <properties>])"), " — use function to render DOM structure for given <custom-element>",
 		),
 		el("li").append(
 			el("code", "customElementWithDDE(<custom-element>)"), " — register <custom-element> to DDE library, see also `lifecyclesToEvents`, can be also used as decorator",

docs_src/index.html.js

@@ -1,41 +1,62 @@
+import { t, T } from "./utils/index.js";
 export const info= {
 	href: "./",
-	title: "Introduction",
-	description: "Introducing a library.",
+	title: t`Introduction`,
+	description: t`Introducing a library.`,
 };
 
 import { el } from "deka-dom-el";
 import { simplePage } from "./layout/simplePage.html.js";
+import { h3 } from "./components/pageUtils.html.js";
 import { example } from "./components/example.html.js";
+import { code } from "./components/code.html.js";
+/** @param {string} url */
+const fileURL= url=> new URL(url, import.meta.url);
+const references= {
+	w_mvv:{
+		title: t`Wikipedia: Model–view–viewmodel`,
+		href: "https://en.wikipedia.org/wiki/Model%E2%80%93view%E2%80%93viewmodel",
+	},
+	w_mvc: {
+		title: t`Wikipedia: Model–view–controller`,
+		href: "https://en.wikipedia.org/wiki/Model%E2%80%93view%E2%80%93controller",
+	},
+};
 /** @param {import("./types.d.ts").PageAttrs} attrs */
 export function page({ pkg, info }){
 	const page_id= info.id;
 	return el(simplePage, { info, pkg }).append(
-		el("p", "The library tries to provide pure JavaScript tool(s) to create reactive interfaces."),
-		el("p").append(
-			"We start with creating and modifying a static elements and end up with UI templates.",
-			" ",
-			el("i").append(
-				"From ", el("code", "document.createElement"), " to ", el("code", "el"), "."
-			),
-			" ",
-			"Then we go through the native events system and the way to include it declaratively in UI templates.",
-			" ",
-			el("i").append(
-				"From ", el("code", "element.addEventListener"), " to ", el("code", "on"), "."
-			),
-		),
-		el("p").append(
-			"Next step is providing interactivity not only for our UI templates.",
-			" ",
-			"We introduce signals (", el("code", "S"), ") and how them incorporate to UI templates.",
-		),
-		el("p").append(
-			"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 ",
-			el("code", "scope"), "s. We will look at how they work in components represented ",
-			"in JavaScript by functions."
-		),
-		el(example, { src: new URL("./components/examples/helloWorld.js", import.meta.url), page_id }),
+		el("p", t`The library tries to provide pure JavaScript tool(s) to create reactive interfaces using …`),
+		
+		el(h3, t`Event-driven programming (3 parts separation ≡ 3PS)`),
+		el("p").append(t`
+			Let's introduce the basic principle on which the library is built. We'll use the JavaScript listener as
+			a starting point.
+		`),
+		el(code, { src: fileURL("./components/examples/introducing/3ps.js"), page_id }),
+		el("p").append(...T`
+			As we can see, in the code at location “A” we define ${el("em", t`how to react`)} when the function
+			is called with any event as an argument. At that moment, we ${el("em", t`don't care who/why/how`)}
+			the function was called. Similarly, at point “B”, we reference to a function to be called on the event
+			${el("em", t`without caring`)} what the function will do at that time. Finally, at point “C”, we tell
+			the application that a change has occurred, in the input, and we ${el("em", t`don't care if/how someone`)}
+			is listening for the event.
+		`),
+		el(example, { src: fileURL("./components/examples/introducing/helloWorld.js"), page_id }),
+		el("p").append(...T`
+			The library introduces a new “type” of variable/constant called ${el("em", t`signal`)} allowing us to
+			to use introduced 3PS pattern in our applications. As you can see it in the example above.
+		`),
+		el("p").append(...T`
+			Also please notice that there is very similar 3PS pattern used for separate creation of UI and
+			business logic.
+		`),
+		el("p").append(...T`
+			The 3PS is very simplified definition of the pattern. There are more deep/academic definitions more precisely
+			describe usage in specific situations, see for example ${el("a", { textContent: t`MVVM`, ...references.w_mvv })}
+			or ${el("a", { textContent: t`MVC`, ...references.w_mvc })}.
+		`),
+		
+		el(h3, t`Organization of the documentation`),
 	);
 }

docs_src/p02-elements.html.js

@@ -1,6 +1,7 @@
+import { T, t } from "./utils/index.js";
 export const info= {
-	title: "Elements",
-	description: "Basic concepts of elements modifications and creations.",
+	title: t`Elements`,
+	description: t`Basic concepts of elements modifications and creations.`,
 };
 
 import { el } from "deka-dom-el";
@@ -11,113 +12,142 @@ import { mnemonic } from "./components/mnemonic/elements-init.js";
 import { code } from "./components/code.html.js";
 /** @param {string} url */
 const fileURL= url=> new URL(url, import.meta.url);
+const references= {
+	/** document.createElement() */
+	mdn_create: {
+		title: t`MDN documentation page for document.createElement()`,
+		href: "https://developer.mozilla.org/en-US/docs/Web/API/Document/createElement",
+	},
+	/** Interface Description Language (`el.textContent`) */
+	mdn_idl: {
+		title: t`MDN page about Interface Description Language`,
+		href: "https://developer.mozilla.org/en-US/docs/Glossary/IDL",
+	},
+	/** HTMLElement */
+	mdn_el: {
+		title: t`MDN documentation page for HTMLElement`,
+		href: "https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement"
+	},
+	/** HTMLParagraphElement */
+	mdn_p: {
+		title: t`MDN documentation page for HTMLParagraphElement (\`p\` tag)`,
+		href: "https://developer.mozilla.org/en-US/docs/Web/API/HTMLParagraphElement"
+	},
+	/** `[a, b] = [1, 2]` */
+	mdn_destruct: {
+		title: t`MDN page about destructuring assignment syntax (e.g. \`[a, b] = [1, 2]\`)`,
+		href: "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Destructuring_assignment",
+	},
+	/** document.createElementNS() */
+	mdn_ns: {
+		title: t`MDN documentation page for document.createElementNS() (e.g. for SVG elements)`,
+		href: "https://developer.mozilla.org/en-US/docs/Web/API/Document/createElementNS",
+	}
+};
 /** @param {import("./types.d.ts").PageAttrs} attrs */
 export function page({ pkg, info }){
 	const page_id= info.id;
 	return el(simplePage, { info, pkg }).append(
-		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("h2", t`Native JavaScript DOM elements creations`),
+		el("p", t`
+			Let’s go through all patterns we would like to use and what needs to be improved for better experience.
+		`),
 
 		el(code, { src: fileURL("./components/examples/elements/intro.js"), page_id }),
 		
-		el(h3, "Creating element(s) (with custom attributes)"),
-		el("p").append(
-			"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("code", "document.createElement()")
-			), ". ",
-			"It is also possible to provide a some attribute(s) declaratively using ", el("code", "Object.assign()"), ". ",
-			"More precisely, this way you can sets some ",
-			el("a", {
-				href: "https://developer.mozilla.org/en-US/docs/Glossary/IDL",
-				title: "MDN page about Interface Description Language"
-			}).append(
-				el("abbr", { textContent: "IDL", title: "Interface Description Language" })
-			), " also known as a JavaScript property."
-		),
+		el(h3, t`Creating element(s) (with custom attributes)`),
+		el("p").append(...T`
+			You can create a native DOM element by using the ${el("a", references.mdn_create).append(
+			el("code", "document.createElement()") )}. It is also possible to provide a some attribute(s) declaratively
+			using ${el("code", "Object.assign()")}. More precisely, this way you can sets some
+			${el("a", references.mdn_idl).append( el("abbr", { textContent: "IDL", title: "Interface Description Language" }))}
+			also known as a JavaScript property.
+		`),
 		el(example, { src: fileURL("./components/examples/elements/nativeCreateElement.js"), page_id }),
-		el("p").append(
-			"To make this easier, you can use the ", el("code", "el"), " function. ",
-			"Internally in basic examples, it is wrapper around ", el("code", "assign(document.createElement(…), { … })"), "."
-		),
+		el("p").append(...T`
+			To make this easier, you can use the ${el("code", "el")} function. Internally in basic examples,
+			it is wrapper around ${el("code", "assign(document.createElement(…), { … })")}.
+		`),
 		el(example, { src: fileURL("./components/examples/elements/dekaCreateElement.js"), page_id }),
-		el("p").append(
-			"The ", el("code", "assign"), " function provides improved behaviour of ", el("code", "Object.assign()"), ". ",
-			"You can declaratively sets any IDL and attribute of the given element. ",
-			"Function prefers IDL and fallback to the ", el("code", "element.setAttribute"), " if there is no writable property in the element prototype."
-		),
-		el("p").append(
-			"You can study all JavaScript elements interfaces to the corresponding HTML elements. ",
-			"All HTML elements inherits from ", el("a", { textContent: "HTMLElement", href: "https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement" }), ". ",
-			"To see all available IDLs for example for paragraphs, see ", el("a", { textContent: "HTMLParagraphElement", href: "https://developer.mozilla.org/en-US/docs/Web/API/HTMLParagraphElement" }), ". ",
-			"Moreover, the ", el("code", "assign"), " provides a way to sets declaratively some convenient properties:"
-		),
+		el("p").append(...T`
+			The ${el("code", "assign")} function provides improved behaviour of ${el("code", "Object.assign()")}.
+			You can declaratively sets any IDL and attribute of the given element. Function prefers IDL and fallback
+			to the ${el("code", "element.setAttribute")} if there is no writable property in the element prototype.
+		`),
+		el("p").append(...T`
+			You can study all JavaScript elements interfaces to the corresponding HTML elements. All HTML elements
+			inherits from ${el("a", { textContent: "HTMLElement", ...references.mdn_el })}. To see
+			all available IDLs for example for paragraphs, see ${el("a", { textContent: "HTMLParagraphElement", ...references.mdn_p })}.
+			Moreover, the ${el("code", "assign")} provides a way to sets declaratively some convenient properties:
+		`),
 		el("ul").append(
-			el("li").append(
-				"It is possible to sets ", el("code", "data-*"), "/", el("code", "aria-*"), " attributes using object notation."
-			),
-			el("li").append(
-				"In opposite, it is also possible to sets ", el("code", "data-*"), "/", el("code", "aria-*"), " attribute using camelCase notation."
-			),
-			el("li").append(
-				"You can use string or object as a value for ", el("code", "style"), " property."
-			),
-			el("li").append(
-				el("code", "className"), " (IDL – preffered)/", el("code", "class"), " are ways to add CSS class to the element. ",
-				"You can use string (similarly to ", el("code", "class=\"…\"") ," syntax in  HTML) or array of strings. ",
-				"This is handy to concat conditional classes."
-			),
-			el("li").append(
-				"Use ", el("code", "classList"), " to toggle specific classes. This will be handy later when the reactivity via signals is beeing introduced.",
-			),
-			el("li").append(
-				"The ", el("code", "assign"), " also accepts the ", el("code", "undefined"), " as a 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. ",
-				el("em").append(
-					"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(
-			"For processing, the ", el("code", "assign"), " internally uses ", el("code", "assignAttribute"), " and ", el("code", "classListDeclarative"), "."
+			el("li").append(...T`
+				It is possible to sets ${el("code", "data-*")}/${el("code", "aria-*")} attributes using object notation.
+			`),
+			el("li").append(...T`
+				In opposite, it is also possible to sets ${el("code", "data-*")}/${el("code", "aria-*")} attribute
+				using camelCase notation.
+			`),
+			el("li").append(...T`You can use string or object as a value for ${el("code", "style")} property.`),
+			el("li").append(...T`
+				${el("code", "className")} (IDL – preffered)/${el("code", "class")} are ways to add CSS classes
+				to the element. You can use string (similarly to ${el("code", "class=\"…\"")} syntax in  HTML) or
+				array of strings. This is handy to concat conditional classes.
+			`),
+			el("li").append(...T`
+				Use ${el("code", "classList")} to toggle specific classes. This will be handy later when
+				the reactivity via signals is beeing introduced.
+			`),
+			el("li").append(...T`
+				The ${el("code", "assign")} also accepts the ${el("code", "undefined")} as a 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. ${el("em").append(...T`For example, natievly the element’s ${el("code", "id")}
+				is removed by setting the IDL to an empty string.`)}
+			`),
+			el("li").append(...T`
+				You can use ${el("code", "=")} or ${el("code", ".")} to force processing given key as attribute/property
+				of the element.
+			`)
 		),
+		el("p").append(...T`
+			For processing, the ${el("code", "assign")} internally uses ${el("code", "assignAttribute")} and
+			${el("code", "classListDeclarative")}.
+		`),
 		el(example, { src: fileURL("./components/examples/elements/dekaAssign.js"), page_id }),
 		
-		el(h3, "Native JavaScript templating"),
-		el("p", "By default, the native JS has no good way to define HTML template using DOM API:"),
+		el(h3, t`Native JavaScript templating`),
+		el("p", t`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("p").append(
-			"This library therefore overwrites the ", el("code", "append"), " method of created elements to always return parent element."
-		),
+		el("p").append(...T`
+			This library therefore overwrites the ${el("code", "append")} method of created elements to always return
+			parent element.
+		`),
 		el(example, { src: fileURL("./components/examples/elements/dekaAppend.js"), page_id }),
 		
 		
-		el(h3, "Basic (state-less) components"),
-		el("p").append(
-			"You can use functions for encapsulation (repeating) logic. ",
-			"The ", el("code", "el"), " accepts function as first argument. ",
-			"In that case, the function should return dom elements and the second argument for ", el("code", "el"), " is argument for given element."
-		),
+		el(h3, t`Basic (state-less) components`),
+		el("p").append(...T`
+			You can use functions for encapsulation (repeating) logic. The ${el("code", "el")} accepts function
+			as first argument. In that case, the function should return dom elements and the second argument for
+			${el("code", "el")} is argument for given element.
+		`),
 		el(example, { src: fileURL("./components/examples/elements/dekaBasicComponent.js"), page_id }),
-		el("p").append(
-			"As you can see, in case of state-less/basic components there is no difference",
-			" between calling component function directly or using ", el("code", "el"), " function.",
-		),
-		el("p", { className: "notice" }).append(
-			"It is nice to use similar naming convention as native DOM API. ",
-			"This allows us to use ", el("a", { textContent: "the destructuring assignment syntax", href: "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Destructuring_assignment", title: "Destructuring assignment | MDN" }),
-			" and keep track of the native API (things are best remembered through regular use).",
-		),
+		el("p").append(...T`
+			As you can see, in case of state-less/basic components there is no difference between calling component
+			function directly or using ${el("code", "el")} function.
+		`),
+		el("p", { className: "notice" }).append(...T`
+			It is nice to use similar naming convention as native DOM API. This allows us to use
+			${el("a", { textContent: t`the destructuring assignment syntax`, ...references.mdn_destruct })} and keep
+			track of the native API (things are best remembered through regular use).
+		`),
 
-		el(h3, "Creating non-HTML elements"),
-		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",
-			" we need to tell JavaScript which kind of the element to create.",
-			" We can use the ", el("code", "elNS"), " function:"
-		),
+		el(h3, t`Creating non-HTML elements`),
+		el("p").append(...T`
+			Similarly to the native DOM API (${el("a", references.mdn_ns).append(el("code", "document.createElementNS"))})
+			for non-HTML elements we need to tell JavaScript which kind of the element to create. We can use
+			the ${el("code", "elNS")} function:
+		`),
 		el(example, { src: fileURL("./components/examples/elements/dekaElNS.js"), page_id }),
 		
 		el(mnemonic)

docs_src/p03-events.html.js

@@ -1,6 +1,7 @@
+import { T, t } from "./utils/index.js";
 export const info= {
-	title: "Events and Addons",
-	description: "Using not only events in UI declaratively.",
+	title: t`Events and Addons`,
+	description: t`Using not only events in UI declaratively.`,
 };
 
 import { el } from "deka-dom-el";
@@ -11,121 +12,136 @@ import { mnemonic } from "./components/mnemonic/events-init.js";
 import { code } from "./components/code.html.js";
 /** @param {string} url */
 const fileURL= url=> new URL(url, import.meta.url);
+const references= {
+	/** element.addEventListener() */
+	mdn_listen: {
+		title: t`MDN documentation page for elemetn.addEventListener`,
+		href: "https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener",
+	},
+	/** AbortSignal+element.addEventListener */
+	mdn_abortListener: {
+		title: t`MDN documentation page for using AbortSignal with element.addEventListener`,
+		href: "https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener#signal",
+	},
+	/** comparison listening options by WebReflection */
+	web_events: {
+		href: "https://gist.github.com/WebReflection/b404c36f46371e3b1173bf5492acc944",
+	},
+	/** Custom Element lifecycle callbacks */
+	mdn_customElement: {
+		href: "https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements#custom_element_lifecycle_callbacks" 
+	},
+	/** MutationObserver */
+	mdn_mutation: {
+		href: "https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver",
+	},
+	/** Readding the element to the DOM fix by Vue */
+	vue_fix: {
+		title: t`Vue and Web Components, lifecycle implementation readding the element to the DOM`,
+		href: "https://vuejs.org/guide/extras/web-components.html#lifecycle",
+	}
+};
 /** @param {import("./types.d.ts").PageAttrs} attrs */
 export function page({ pkg, info }){
 	const page_id= info.id;
 	return el(simplePage, { info, pkg }).append(
-		el("h2", "Listenning to the native DOM events and other Addons"),
-		el("p").append(
-			"We quickly introduce helper to listening to the native DOM events.",
-			" ",
-			"And library syntax/pattern so-called ", el("em", "Addon"), " to",
-			" incorporate not only this in UI templates declaratively."
-		),
+		el("h2", t`Listenning to the native DOM events and other Addons`),
+		el("p").append(...T`
+			We quickly introduce helper to listening to the native DOM events. And library syntax/pattern so-called
+			${el("em", t`Addon`)} to incorporate not only this in UI templates declaratively.
+		`),
 		
 		el(code, { src: fileURL("./components/examples/events/intro.js"), page_id }),
 		
-		el(h3, "Events and listenners"),
-		el("p").append(
-			"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("code", "element.addEventListener(type, listener, options)")
-			), ".",
-			" ",
-			"The library provides an alternative (", el("code", "on"), ") accepting the differen order",
-			" of the arguments:"
-		),
+		el(h3, t`Events and listenners`),
+		el("p").append(...T`
+			In JavaScript you can listen to the native DOM events of the given element by using
+			${el("a", references.mdn_listen).append( el("code", "element.addEventListener(type, listener, options)") )}.
+			The library provides an alternative (${el("code", "on")}) accepting the differen order of the arguments:
+		`),
 		el(example, { src: fileURL("./components/examples/events/compare.js"), page_id }),
-		el("p").append(
-			"…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)."
-		),
-		el("p", { className: "notice" }).append(
-			"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" }),
-			":"
-		),
+		el("p").append(...T`
+			…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).
+		`),
+		el("p", { className: "notice" }).append(...T`
+			The other difference is that there is ${el("strong", "no")} ${el("code", "off")} function. You can remove
+			listener declaratively using ${el("a", { textContent: "AbortSignal", ...references.mdn_abortListener })}:
+		`),
 		el(example, { src: fileURL("./components/examples/events/abortSignal.js"), page_id }),
 		el("div", { className: "notice" }).append(
-			el("p", "So, there are (typically) three ways to handle events. You can use:"),
+			el("p", t`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(
-				"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("p").append(...T`
+				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", t`Side note:
+				this can be useful in case of SSR.`)} To study difference, you can read a nice summary here:
+				${el("a", { textContent: "GIST @WebReflection/web_events.md", ...references.web_events })}.
+			`)
 		),
 
-		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."
-		),
-		el("p").append(
-			"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:"
-		),
+		el(h3, t`Addons`),
+		el("p").append(...T`
+			From practical point of view, ${el("em", t`Addons`)} are just functions that accept any HTML element as
+			their first parameter. You can see that the ${el("code", "on(…)")} fullfills this requirement.
+		`),
+		el("p").append(...T`
+			You can use Addons as ≥3rd argument of ${el("code", "el")} function. This way is possible to extends your
+			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("p").append(
-			"As the example shows, you can also provide types in JSDoc+TypeScript by using global type ", el("code", "ddeElementAddon"), ".",
-			" ",
-			"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("p").append(...T`
+			As the example shows, you can also provide types in JSDoc+TypeScript by using global type
+			${el("code", "ddeElementAddon")}. Also notice, you can use Addons to get element reference.
+		`),
+		el(h3, t`Life-cycle events`),
+		el("p").append(...T`
+			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(...T`
+			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("p").append(...T`
+			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: t`Custom element lifecycle callbacks | MDN`, ...references.mdn_customElement })}).
+		`),
+		el("p").append(...T`
+			But, in case of regular elemnets the ${el("a", references.mdn_mutation).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("p").append(
-			"To provide intuitive behaviour, similar also to how the life-cycle events works in other",
-			" frameworks/libraries, deka-dom-el library ensures that ", el("code", "on.connected"),
-			" and ", el("code", "on.disconnected"), " are called only once and only when the element",
-			" is (dis)connected to live DOM. The solution is inspired by ", el("a", { textContent: "Vue", href: "https://vuejs.org/guide/extras/web-components.html#lifecycle", title: "Vue and Web Components | Lifecycle" }), ".",
-			" For using native behaviour re-(dis)connecting element, use:"
+			el("li").append(...T`
+				To proper listener registration, you need to use ${el("code", "on.*")} not \`on("dde:*", …)\`!
+			`),
+			el("li").append(...T`
+				Use sparingly! Internally, library must loop of all registered events and fires event properly.
+				${el("strong", t`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", t`host`)} syntax to
+				register, clean up procedures when the component is removed from the app.
+			`),
 		),
+		el("p").append(...T`
+			To provide intuitive behaviour, similar also to how the life-cycle events works in other
+			frameworks/libraries, deka-dom-el library ensures that ${el("code", "on.connected")} and
+			${el("code", "on.disconnected")} are called only once and only when the element, is (dis)connected to
+			live DOM. The solution is inspired by ${el("a", { textContent: "Vue", ...references.vue_fix })}. For using
+			native behaviour re-(dis)connecting element, use:
+		`),
 		el("ul").append(
-			el("li").append("custom ", el("code", "MutationObserver"), " or logic in (dis)", el("code", "connectedCallback"), " or…"),
-			el("li").append("re-add ", el("code", "on.connected"), " or ", el("code", "on.disconnected"), " listeners.")
+			el("li").append(...T`custom ${el("code", "MutationObserver")} or logic in (dis)${el("code", "connectedCallback")} or…`),
+			el("li").append(...T`re-add ${el("code", "on.connected")} or ${el("code", "on.disconnected")} listeners.`)
 		),
 
-		el(h3, "Final notes"),
-		el("p", "The library also provides a method to dispatch the events."),
+		el(h3, t`Final notes`),
+		el("p", t`The library also provides a method to dispatch the events.`),
 		el(example, { src: fileURL("./components/examples/events/compareDispatch.js"), page_id }),
 		
 		el(mnemonic)

docs_src/p04-signals.html.js

@@ -1,6 +1,7 @@
+import { T, t } from "./utils/index.js";
 export const info= {
-	title: "Signals and reactivity",
-	description: "Handling reactivity in UI via signals.",
+	title: t`Signals and reactivity`,
+	description: t`Handling reactivity in UI via signals.`,
 };
 
 import { el } from "deka-dom-el";
@@ -11,95 +12,115 @@ import { mnemonic } from "./components/mnemonic/signals-init.js";
 import { code } from "./components/code.html.js";
 /** @param {string} url */
 const fileURL= url=> new URL(url, import.meta.url);
-
+const references= {
+	/** Event-driven programming */
+	wiki_event_driven: {
+		title: t`Wikipedia: Event-driven programming`,
+		href: "https://en.wikipedia.org/wiki/Event-driven_programming",
+	},
+	/** Publish–subscribe pattern */
+	wiki_pubsub: {
+		title: t`Wikipedia: Publish–subscribe pattern`,
+		href: "https://en.wikipedia.org/wiki/Publish%E2%80%93subscribe_pattern",
+	},
+	/** NPM package: fpubsub */
+	fpubsub: {
+		title: t`NPM package: fpubsub`,
+		href: "https://www.npmjs.com/package/fpubsub",
+	},
+	/** JS Primitives | MDN */
+	mdn_primitive: {
+		title: t`Primitive | MDN`,
+		href: "https://developer.mozilla.org/en-US/docs/Glossary/Primitive",
+	},
+	/** useReducer */
+	mdn_use_reducer: {
+		title: t`useReducer hook | React docs`,
+		href: "https://react.dev/reference/react/useReducer",
+	}
+};
 /** @param {import("./types.d.ts").PageAttrs} attrs */
 export function page({ pkg, info }){
 	const page_id= info.id;
 	return el(simplePage, { info, pkg }).append(
-		el("h2", "Using signals to manage reactivity"),
-		el("p").append(
-			"How a program responds to variable data or user",
-			" interactions is one of the fundamental problems of programming.",
-			" If we desire to solve the issue in a declarative manner,",
-			" signals may be a viable approach.",
-		),
+		el("h2", t`Using signals to manage reactivity`),
+		el("p").append(...T`
+			How a program responds to variable data or user interactions is one of the fundamental problems of
+			programming. If we desire to solve the issue in a declarative manner, signals may be a viable approach.
+		`),
 		el(code, { src: fileURL("./components/examples/signals/intro.js"), page_id }),
 		
-		el(h3, "Introducing signals"),
-		el("p").append(
-			"Using signals, we split program logic into the three parts.",
-			" Firstly (α), we create a variable (constant) representing reactive",
-			" value. Somewhere later, we can register (β) a logic reacting",
-			" to the signal value changes. Similarly, in a remaining part (γ), we",
-			" can update the signal value."
-		),
+		el(h3, t`Introducing signals`),
+		el("p").append(...T`
+			Let’s re-introduce
+			${el("a", { textContent: t`3PS principle`, href: "./#h-event-driven-programming--parts-separation--ps" })}.
+		`),
+		el("p").append(...T`
+			Using signals, we split program logic into the three parts. Firstly (α), we create a variable (constant)
+			representing reactive value. Somewhere later, we can register (β) a logic reacting to the signal value
+			changes. Similarly, in a remaining part (γ), we can update the signal value.
+		`),
 		el(example, { src: fileURL("./components/examples/signals/signals.js"), page_id }),
-		el("p").append(
-			"All this is just an example of ",
-			el("a", { textContent: "Event-driven programming", href: "https://en.wikipedia.org/wiki/Event-driven_programming", title: "Wikipedia: Event-driven programming" }),
-			" and ",
-			el("a", { textContent: "Publish–subscribe pattern", href: "https://en.wikipedia.org/wiki/Publish%E2%80%93subscribe_pattern", title: "Wikipedia: Publish–subscribe pattern" }),
-			" (compare for example with ", el("a", { textContent: "fpubsub library", href: "https://www.npmjs.com/package/fpubsub", title: "NPM package: fpubsub" }), ").",
-			" All three parts can be in some manner independent and still connected",
-			" to the same reactive entity."
-		),
-		el("p").append(
-			"Signals are implemented in the library as functions. To see current value",
-			" of signal, just call it without any arguments ", el("code", "console.log(signal())"), ".",
-			" To update the signal value, pass any argument ", el("code", "signal('a new value')"), ".",
-			" For listenning the signal value changes, use ", el("code", "S.on(signal, console.log)"), "."
-		),
-		el("p").append(
-			"Similarly to the ", el("code", "on"), " function to register DOM events listener.",
-			" You can use ", el("code", "AbortController"), "/", el("code", "AbortSignal"), " to",
-			" ", el("em", "off"), "/stop listenning. In example, you also found the way for representing",
-			" “live” piece of code computation pattern (derived signal):"
-		),
+		el("p").append(...T`
+			All this is just an example of 
+			${el("a", { textContent: t`Event-driven programming`, ...references.wiki_event_driven })} and
+			${el("a", { textContent: t`Publish–subscribe pattern`, ...references.wiki_pubsub })} (compare for example
+			with ${el("a", { textContent: t`fpubsub library`, ...references.fpubsub })}). All three parts can be in
+			some manner independent and still connected to the same reactive entity.
+		`),
+		el("p").append(...T`
+			Signals are implemented in the library as functions. To see current value of signal, just call it without
+			any arguments ${el("code", "console.log(signal())")}. To update the signal value, pass any argument
+			${el("code", `signal('${t`a new value`}')`)}. For listenning the signal value changes, use
+			${el("code", "S.on(signal, console.log)")}.
+		`),
+		el("p").append(...T`
+			Similarly to the ${el("code", "on")} function to register DOM events listener. You can use
+			${el("code", "AbortController")}/${el("code", "AbortSignal")} to ${el("em", "off")}/stop listenning. In
+			example, you also found the way for representing “live” piece of code computation pattern (derived signal):
+		`),
 		el(example, { src: fileURL("./components/examples/signals/computations-abort.js"), page_id }),
 
-		el(h3, "Signals and actions"),
-		el("p").append(
-			el("code", "S(/* primitive */)"), " allows you to declare simple reactive variables, typically",
-			" around ", el("em", "immutable"), " ", el("a", { textContent: "primitive types", title: "Primitive | MDN", href: "https://developer.mozilla.org/en-US/docs/Glossary/Primitive" }), ".",
-			" ",
-			"However, it may also be necessary to use reactive arrays, objects, or other complex reactive structures."
-		),
+		el(h3, t`Signals and actions`),
+		el("p").append(...T`
+			${el("code", `S(/* ${t`primitive`} */)`)} allows you to declare simple reactive variables, typically, around
+			${el("em", t`immutable`)} ${el("a", { textContent: t`primitive types`, ...references.mdn_primitive })}.
+			However, it may also be necessary to use reactive arrays, objects, or other complex reactive structures.
+		`),
 		el(example, { src: fileURL("./components/examples/signals/actions-demo.js"), page_id }),
-		el("p", "…but typical user-case is object/array (maps, sets and other mutable objects):"),
+		el("p", t`…but typical user-case is object/array (maps, sets and other mutable objects):`),
 		el(example, { src: fileURL("./components/examples/signals/actions-todos.js"), page_id }),
-		el("p").append(
-			"In some way, you can compare it with ", el("a", { textContent: "useReducer", href: "https://react.dev/reference/react/useReducer", title: "useReducer hook | React docs" }),
-			" hook from React. So, the ", el("code", "S(<data>, <actions>)"), " pattern creates",
-			" a store “machine”. We can then invoke (dispatch) registered action by calling",
-			" ", el("code", "S.action(<signal>, <name>, ...<args>)"), " after the action call",
-			" the signal calls all its listeners. This can be stopped by calling ", el("code", "this.stopPropagation()"),
-			" in the method representing the given action. As it can be seen in examples, the “store” value is",
-			" available also in the function for given action (", el("code", "this.value"), ")."
-		),
+		el("p").append(...T`
+			In some way, you can compare it with ${el("a", { textContent: "useReducer", ...references.mdn_use_reducer })}
+			hook from React. So, the ${el("code", "S(<data>, <actions>)")} pattern creates a store “machine”. We can
+			then invoke (dispatch) registered action by calling ${el("code", "S.action(<signal>, <name>, ...<args>)")}
+			after the action call the signal calls all its listeners. This can be stopped by calling
+			${el("code", "this.stopPropagation()")} in the method representing the given action. As it can be seen in
+			examples, the “store” value is available also in the function for given action (${el("code", "this.value")}).
+		`),
 
-		el(h3, "Reactive DOM attributes and elements"),
-		el("p", "There are on basic level two distinc situation to mirror dynamic value into the DOM/UI"),
+		el(h3, t`Reactive DOM attributes and elements`),
+		el("p", t`There are on basic level two distinc situation to mirror dynamic value into the DOM/UI`),
 		el("ol").append(
-			el("li", "to change some attribute(s) of existing element(s)"),
-			el("li", "to generate elements itself dynamically – this covers conditions and loops")
+			el("li", t`to change some attribute(s) of existing element(s)`),
+			el("li", t`to generate elements itself dynamically – this covers conditions and loops`)
 		),
 		el(example, { src: fileURL("./components/examples/signals/dom-attrs.js"), page_id }),
-		el("p").append(
-			"To derived attribute based on value of signal variable just use the signal as",
-			" a value of the attribute (", el("code", "assign(element, { attribute: S('value') })"), ").",
-			" ", el("code", "assign"), "/", el("code", "el"), " provides ways to glue reactive attributes/classes",
-			" more granularly into the DOM. Just use dedicated build-in attributes ", el("code", "dataset"), ", ",
-			el("code", "ariaset"), " and ", el("code", "classList"), "."
-		),
-		el("p").append(
-			"For computation, you can use the “derived signal” (see above) like ", el("code", "assign(element, { textContent: S(()=> 'Hello '+WorldSignal()) })"), ".",
-			" ",
-			"This is read-only signal its value is computed based on given function and updated when any signal used in the function changes."
-		),
-		el("p").append(
-			"To represent part of the template filled dynamically based on the signal value use ", el("code", "S.el(signal, DOMgenerator)"), ".",
-			" This was already used in the todo example above or see:"
-		),
+		el("p").append(...T`
+			To derived attribute based on value of signal variable just use the signal as a value of the attribute
+			(${el("code", "assign(element, { attribute: S('value') })")}). ${el("code", "assign")}/${el("code", "el")}
+			 provides ways to glue reactive attributes/classes more granularly into the DOM. Just use dedicated build-in
+			 attributes ${el("code", "dataset")}, ${el("code", "ariaset")} and ${el("code", "classList")}.
+		`),
+		el("p").append(...T`
+			For computation, you can use the “derived signal” (see above) like
+			${el("code", "assign(element, { textContent: S(()=> 'Hello '+WorldSignal()) })")}. This is read-only signal
+			its value is computed based on given function and updated when any signal used in the function changes.
+		`),
+		el("p").append(...T`
+			To represent part of the template filled dynamically based on the signal value use
+			${el("code", "S.el(signal, DOMgenerator)")}. This was already used in the todo example above or see:
+		`),
 		el(example, { src: fileURL("./components/examples/signals/dom-el.js"), page_id }),
 
 		el(mnemonic)

docs_src/p05-scopes.html.js

@@ -1,6 +1,7 @@
+import { T, t } from "./utils/index.js";
 export const info= {
-	title: "Scopes and components",
-	description: "Organizing UI into components",
+	title: t`Scopes and components`,
+	description: t`Organizing UI into components`,
 };
 
 import { el } from "deka-dom-el";
@@ -11,67 +12,74 @@ import { mnemonic } from "./components/mnemonic/scopes-init.js";
 import { code } from "./components/code.html.js";
 /** @param {string} url */
 const fileURL= url=> new URL(url, import.meta.url);
-
+const references= {
+	/** Garbage collection on MDN */
+	garbage_collection: {
+		title: t`MDN documentation page for Garbage collection`,
+		href: "https://developer.mozilla.org/en-US/docs/Glossary/Garbage_collection",
+	},
+	/** Signals */
+	signals: {
+		title: t`Signals section on this library`,
+		href: "./p04-signals#h-introducing-signals",
+	}
+};
 /** @param {import("./types.d.ts").PageAttrs} attrs */
 export function page({ pkg, info }){
 	const page_id= info.id;
 	return el(simplePage, { info, pkg }).append(
-		el("h2", "Using functions as UI components"),
-		el("p").append(
-			"For state-less components we can use functions as UI components (see “Elements” page).",
-			" But in real life, we may need to handle the component live-cycle and provide",
-			" JavaScript the way to properly use the ", el("a", { textContent: "Garbage collection", href: "https://developer.mozilla.org/en-US/docs/Glossary/Garbage_collection", title: "Garbage collection | MDN" }), "."
-		),
+		el("h2", t`Using functions as UI components`),
+		el("p").append(...T`
+			For state-less components we can use functions as UI components (see “Elements” page). But in real life,
+			we may need to handle the component live-cycle and provide JavaScript the way to properly use
+			the ${el("a", { textContent: t`Garbage collection`, ...references.garbage_collection })}.
+		`),
 		el(code, { src: fileURL("./components/examples/scopes/intro.js"), page_id }),
-		el("p").append(
-			"The library therefore use ", el("em", "scopes"), " to provide these functionalities.",
-		),
+		el("p").append(...T`The library therefore use ${el("em", t`scopes`)} to provide these functionalities.`),
 		
-		el(h3, "Scopes and hosts"),
-		el("p").append(
-			"The ", el("strong", "host"), " is the name for the element representing the component.",
-			" This is typically element returned by function. To get reference, you can use ",
-			el("code", "scope.host()"), " to applly addons just use ", el("code", "scope.host(...<addons>)"), "."
-		),
+		el(h3, t`Scopes and hosts`),
+		el("p").append(...T`
+			The ${el("strong", "host")} is the name for the element representing the component. This is typically
+			element returned by function. To get reference, you can use ${el("code", "scope.host()")} to applly addons
+			just use ${el("code", "scope.host(...<addons>)")}.
+		`),
 		el(example, { src: fileURL("./components/examples/scopes/scopes-and-hosts.js"), page_id }),
-		el("p").append(
-			"To better understanding we implement function ", el("code", "elClass"), " helping to create",
-			" component as class instances."
-		),
+		el("p").append(...T`
+			To better understanding we implement function ${el("code", "elClass")} helping to create component as
+			class instances.
+		`),
 		el(example, { src: fileURL("./components/examples/scopes/class-component.js"), page_id }),
-		el("p").append(
-			"As you can see, the ", el("code", "scope.host()"), " is stored temporarily and synchronously.",
-			" Therefore, at least in the beginning of using library, it is the good practise to store",
-			" ", el("code", "host"), " in the root of your component. As it may be changed, typically when",
-			" there is asynchronous code in the component."
-		),
+		el("p").append(...T`
+			As you can see, the ${el("code", "scope.host()")} is stored temporarily and synchronously. Therefore, at
+			least in the beginning of using library, it is the good practise to store ${el("code", "host")} in the root
+			of your component. As it may be changed, typically when there is asynchronous code in the component.
+		`),
 		el(code, { src: fileURL("./components/examples/scopes/good-practise.js"), page_id }),
 
-		el(h3, "Scopes, signals and cleaning magic"),
-		el("p").append(
-			"The ", el("code", "host"), " is internally used to register the cleaning procedure,",
-			" when the component (", el("code", "host"), " element) is removed from the DOM."
-		),
+		el(h3, t`Scopes, signals and cleaning magic`),
+		el("p").append(...T`
+			The ${el("code", "host")} is internally used to register the cleaning procedure, when the component
+			(${el("code", "host")} element) is removed from the DOM.
+		`),
 		el(example, { src: fileURL("./components/examples/scopes/cleaning.js"), page_id }),
-		el("p").append(
-			"The text content of the paragraph is changing when the value of the signal ", el("code", "textContent"),
-			" is changed. Internally, there is association between ", el("code", "textContent"), " and the paragraph",
-			" similar to using ", el("code", "S.on(textContent, /* update the paragraph */)"), "."
-		),
-		el("p").append(
-			"This listener must be removed when the component is removed from the DOM. To do it, the library",
-			" assign internally ", el("code", "on.disconnected(/* remove the listener */)(host())"), " to the host element."
-		),
-		el("p", { className: "notice" }).append(
-			"The library DOM API and signals works ideally when used declaratively.",
-			" It means, you split your app logic into three parts as it was itroduced in ", el("a", { textContent: "Signals", href: "http://localhost:40911/docs/p04-signals#h-introducing-signals" }), "."
-		),
+		el("p").append(...T`
+			The text content of the paragraph is changing when the value of the signal ${el("code", "textContent")}
+			is changed. Internally, there is association between ${el("code", "textContent")} and the paragraph,
+			similar to using ${el("code", `S.on(textContent, /* ${t`update the paragraph`} */)`)}.
+		`),
+		el("p").append(...T`
+			This listener must be removed when the component is removed from the DOM. To do it, the library assign
+			internally ${el("code", `on.disconnected(/* ${t`remove the listener`} */)(host())`)} to the host element.
+		`),
+		el("p", { className: "notice" }).append(...T`
+			The library DOM API and signals works ideally when used declaratively. It means, you split your app logic
+			into three parts as it was itroduced in ${el("a", { textContent: "Signals", ...references.signals })}.
+		`),
 		el(code, { src: fileURL("./components/examples/scopes/declarative.js"), page_id }),
-		el("p").append(
-			"Strictly speaking, the imperative way of using the library is not prohibited.",
-			" Just be careful (rather avoid) mixing declarative approach (using signals)",
-			" and imperative manipulation of elements.",
-		),
+		el("p").append(...T`
+			Strictly speaking, the imperative way of using the library is not prohibited. Just be careful (rather avoid)
+			mixing declarative approach (using signals) and imperative manipulation of elements.
+		`),
 		el(code, { src: fileURL("./components/examples/scopes/imperative.js"), page_id }),
 
 		el(mnemonic)

docs_src/p06-customElement.html.js

@@ -1,6 +1,7 @@
+import { T, t } from "./utils/index.js";
 export const info= {
-	title: "Custom elements",
-	description: "Using custom elements in combinantion with DDE",
+	title: t`Web Components`,
+	description: t`Using custom elements in combinantion with DDE`,
 };
 
 import { el } from "deka-dom-el";
@@ -11,25 +12,96 @@ import { mnemonic } from "./components/mnemonic/customElement-init.js";
 import { code } from "./components/code.html.js";
 /** @param {string} url */
 const fileURL= url=> new URL(url, import.meta.url);
-
+const references= {
+	/** Web Components on MDN */
+	mdn_web_components: {
+		title: t`MDN documentation page for Web Components`,
+		href: "https://developer.mozilla.org/en-US/docs/Web/API/Web_components",
+	},
+	/** observedAttributes on MDN */
+	mdn_observedAttributes: {
+		title: t`MDN documentation page for observedAttributes`,
+		href: "https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements#responding_to_attribute_changes",
+	},
+	/** Custom Elements on MDN */
+	mdn_custom_elements: {
+		title: t`MDN documentation page for Custom Elements`,
+		href: "https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements",
+	},
+	/** Custom Elements tips from WebReflection */
+	custom_elements_tips: {
+		title: t`Ideas and tips from WebReflection`,
+		href: "https://gist.github.com/WebReflection/ec9f6687842aa385477c4afca625bbf4",
+	},
+	/** Shallow DOM on mdn */
+	mdn_shadow_dom_depth: {
+		title: t`MDN documentation page for Shadow DOM`,
+		href: "https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_shadow_DOM",
+	},
+	/** Shallow DOM */
+	shadow_dom_depth: {
+		title: t`Everything you need to know about Shadow DOM (github repo praveenpuglia/shadow-dom-in-depth)`,
+		href: "https://github.com/praveenpuglia/shadow-dom-in-depth",
+	},
+};
 /** @param {import("./types.d.ts").PageAttrs} attrs */
 export function page({ pkg, info }){
 	const page_id= info.id;
 	return el(simplePage, { info, pkg }).append(
-		el("h2", "Using custom elements in combinantion with DDE"),
-		el("p").append(
-
-		),
+		el("h2", t`Using web components in combinantion with DDE`),
+		el("p").append(...T`
+			The DDE library allows for use within ${el("a", references.mdn_web_components).append( el("strong", "Web Components") )}
+			for dom-tree generation. However, in order to be able to use signals (possibly mapping to registered
+			${el("a", references.mdn_observedAttributes).append( el("code", "observedAttributes") )}) and additional
+			functionality is (unfortunately) required to use helpers provided by the library.
+		`),
 		el(code, { src: fileURL("./components/examples/customElement/intro.js"), page_id }),
 
-		el(h3, "Custom Elements Introduction"),
-		el("p").append(
-			el("a", { textContent: "Using custom elements", href: "https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements", title: "Article about custom elements on MDN" })
-		),
+		el(h3, t`Custom Elements Introduction`),
+		el("p").append(...T`
+			To start with, let’s see how to use native Custom Elements. As starting point please read
+			${el("a", references.mdn_custom_elements).append( el("strong", "Using Custom Elements"), " on MDN" )}.
+			To sum up and for mnemonic see following code overview:
+		`),
 		el(code, { src: fileURL("./components/examples/customElement/native-basic.js"), page_id }),
-		el("p").append(
-			el("a", { textContent: "Handy Custom Elements' Patterns", href: "https://gist.github.com/WebReflection/ec9f6687842aa385477c4afca625bbf4", title: "Ideas and tips from WebReflection" })
-		),
+		el("p").append(...T`
+			For more advanced use of Custom Elements, the summary ${el("a", references.custom_elements_tips)
+			.append( el("strong", t`Handy Custom Elements' Patterns`) )} may be useful. Especially pay attention to
+			linking HTML attributes and defining setters/getters, this is very helpful to use in combination with
+			the library (${el("code", "el(HTMLCustomElement.tagName, { customAttribute: \"new-value\" });")}).
+		`),
+		el("p").append(...T`
+			Also see the Life Cycle Events sections, very similarly we would like to use
+			${el("a", { textContent: t`DDE events`, href: "./p03-events.html", title: t`See events part of the library documentation` })}.
+			To do it, the library provides function ${el("code", "customElementWithDDE")}…
+		`),
+		el(example, { src: fileURL("./components/examples/customElement/customElementWithDDE.js"), page_id }),
+
+		el("h3", t`Custom Elements with DDE`),
+		el("p").append(...T`
+			The ${el("code", "customElementWithDDE")} function is only (small) part of the inregration of the library.
+			More important for coexistence is render component function as a body of the Custom Element. For that, you
+			can use ${el("code", "customElementRender")} with arguments instance reference, target for connection,
+			render function and optional properties (will be passed to the render function) see later…
+		`),
+		el(example, { src: fileURL("./components/examples/customElement/dde.js"), page_id }),
+		el("p").append(...T`
+			…as you can see, you can use components created based on the documentation previously introduced. To unlock
+			full potential, use with combination ${el("code", "customElementWithDDE")} (allows to use livecycle events)
+			and ${el("code", "observedAttributes")} (converts attributes to render function arguments —
+			${el("em", "default")}) or ${el("code", "S.observedAttributes")} (converts attributes to signals).
+		`),
+		el(example, { src: fileURL("./components/examples/customElement/observedAttributes.js"), page_id }),
+
+
+		el(h3, t`Shadow DOM`),
+		el("p").append(...T`
+			Regarding to ${el("code", "this.attachShadow({ mode: 'open' })")} see quick overview
+			${el("a", { textContent: t`Using Shadow DOM`, ...references.mdn_shadow_dom_depth })}. An another source of
+			information can be ${el("a", { textContent: t`Shadow DOM in Depth`, ...references.shadow_dom_depth })}. To
+			sum up, there in basic three ways to render component body:
+		`),
+
 
 		el(mnemonic)
 	);

docs_src/ssr.js

@@ -1,3 +1,4 @@
+export { t } from "./utils/index.js";
 export const path_target= {
 	root: "docs/",
 	css: "docs/"

docs_src/utils/index.js

@@ -0,0 +1,52 @@
+/**
+ * This is helper to write texts in code more readable
+ * and doesn’t inpact the finally generated text in HTML.
+ *
+ * ```js
+ * t`
+ *		Hello ${el("b", "world")}!
+ *		How are you?
+ * ` === "Hello <b>world</b>! How are you?"
+ * ```
+ *
+ * In future, this can be expanded to allow translations.
+ *
+ * ```js
+ * t(key)`text`; // for example
+ * ```
+ *
+ * @param {TemplateStringsArray} strings
+ * @param {...(string|Node)} values
+ * @returns {(string|Node)[]}
+ * */
+export function T(strings, ...values){
+	const out= [];
+	tT(s=> out.push(s), strings, ...values);
+	return out;
+}
+/**
+ * Similarly to {@link T}, but for only strings.
+ * @param {TemplateStringsArray} strings
+ * @param {...string} values
+ * @returns {string}
+ * */
+export function t(strings, ...values){
+	let out= "";
+	tT(s=> out+= s, strings, ...values);
+	return out;
+}
+
+/**
+ * @param {(input: string|Node)=> void} callback
+ * @param {TemplateStringsArray} strings
+ * @param {...(string|Node)} values
+ * */
+function tT(callback, strings, ...values){
+	const { length }= strings;
+	const last= length-1;
+	for(let i= 0; i<length; i++){
+		const out= strings[i].replace(/\n\s+/g, " ");
+		callback(!i ? out.trimStart() : i===last ? out.trimEnd() : out);
+		if(i<values.length) callback(values[i]);
+	}
+}

index.d.ts

@@ -177,12 +177,12 @@ export const scope: {
 
 export function customElementRender<
 	EL extends HTMLElement,
-	P extends any = Record<string, any>
+	P extends any = Record<string, string | ddeSignal<string>>
 >(
 	custom_element: EL,
 	target: ShadowRoot | EL,
 	render: (props: P)=> SupportedElement | DocumentFragment,
-	props?: P | ((...args: any[])=> P)
+	props?: P | ((el: EL)=> P)
 ): EL
 export function customElementWithDDE<EL extends (new ()=> HTMLElement)>(custom_element: EL): EL
 export function lifecyclesToEvents<EL extends (new ()=> HTMLElement)>(custom_element: EL): EL

signals.d.ts

@@ -55,7 +55,7 @@ interface signal{
 	 * */
 	el<S extends any>(signal: Signal<S, any>, el: (v: S)=> Element | Element[] | DocumentFragment): DocumentFragment;
 
-    observedAttributes(custom_element: HTMLElement): Record<string, Signal<any, any>>;
+    observedAttributes(custom_element: HTMLElement): Record<string, Signal<string, {}>>;
 }
 export const signal: signal;
 export const S: signal;