🔤 Improves and updates docs

- customElementRender
- introduction example

README.md

@@ -8,12 +8,17 @@
 
 ```javascript
 document.body.append(
-	el(HelloWorldComponent)
+	el(HelloWorldComponent, { initial: "🚀" })
 );
-function HelloWorldComponent(){
+/** @typedef {"🎉" | "🚀"} Emoji */
+/** @param {{ initial: Emoji }} attrs */
+function HelloWorldComponent({ initial }){
 	const clicks= S(0);
-	const emoji= S("🚀");
+	const emoji= S(initial);
-	const isSelected= el=> (el.selected= el.value===emoji());
+	/** @param {HTMLOptionElement} el */
+	const isSelected= el=> (el.selected= el.value===initial);
+	// @ts-expect-error 2339: The <select> has only two options with {@link Emoji}
+	const onChange= on("change", event=> emoji(event.target.value));
 
 	return el().append(
 		el("p", {
@@ -27,11 +32,9 @@ function HelloWorldComponent(){
 			on("click", ()=> clicks(clicks() + 1)),
 			on("keyup", ()=> clicks(clicks() - 2)),
 		),
-		el("select", {
+		el("select", null, onChange).append(
-			onchange: event=> emoji(event.target.value),
+			el(OptionComponent, "🎉", isSelected),//OR { textContent: "🎉" }
-		}).append(
+			el(OptionComponent, "🚀", isSelected),//OR { textContent: "🚀" }
-			el(OptionComponent, "🎉", isSelected),
-			el(OptionComponent, "🚀", isSelected),
 		)
 	);
 }

dist/esm-with-signals.d.ts

@@ -227,7 +227,6 @@ export function customElementRender<
 	EL extends HTMLElement,
 	P extends any = Record<string, string | ddeSignal<string>>
 >(
-	custom_element: EL,
 	target: ShadowRoot | EL,
 	render: (props: P)=> SupportedElement | DocumentFragment,
 	props?: P | ((el: EL)=> P)

dist/esm.d.ts

@@ -227,7 +227,6 @@ export function customElementRender<
 	EL extends HTMLElement,
 	P extends any = Record<string, string | ddeSignal<string>>
 >(
-	custom_element: EL,
 	target: ShadowRoot | EL,
 	render: (props: P)=> SupportedElement | DocumentFragment,
 	props?: P | ((el: EL)=> P)

docs/components/examples/customElement/dde.js

@@ -7,7 +7,6 @@ export class HTMLCustomElement extends HTMLElement{
 	static observedAttributes= [ "attr" ];
 	connectedCallback(){
 		customElementRender(
-			this,
 			this.attachShadow({ mode: "open" }),
 			ddeComponent
 		);

docs/components/examples/customElement/observedAttributes.js

@@ -11,7 +11,6 @@ export class HTMLCustomElement extends HTMLElement{
 	connectedCallback(){
 		console.log(observedAttributes(this));
 		customElementRender(
-			this,
 			this.attachShadow({ mode: "open" }),
 			ddeComponent,
 			S.observedAttributes

docs/components/examples/customElement/shadowRoot.js

@@ -17,11 +17,7 @@ function ddeComponent(){
 export class A extends HTMLElement{
 	static tagName= "custom-element-without";
 	connectedCallback(){
-		customElementRender(
+		customElementRender(this, ddeComponent);
-			this,
-			this,
-			ddeComponent
-		);
 	}
 }
 customElementWithDDE(A);
@@ -30,7 +26,6 @@ export class B extends HTMLElement{
 	static tagName= "custom-element-open";
 	connectedCallback(){
 		customElementRender(
-			this,
 			this.attachShadow({ mode: "open" }),
 			ddeComponent
 		);
@@ -42,7 +37,6 @@ export class C extends HTMLElement{
 	static tagName= "custom-element-closed";
 	connectedCallback(){
 		customElementRender(
-			this,
 			this.attachShadow({ mode: "closed" }),
 			ddeComponent
 		);

docs/components/examples/customElement/simulateSlots.js

@@ -8,7 +8,7 @@ export class HTMLCustomElement extends HTMLElement{
 	static tagName= "custom-slotting";
 	connectedCallback(){
 		const c= ()=> simulateSlots(this, ddeComponent());
-		customElementRender(this, this, c);
+		customElementRender(this, c);
 	}
 }
 customElementWithDDE(HTMLCustomElement);

docs/components/examples/introducing/helloWorld.js

@@ -1,18 +1,36 @@
-import { el } from "deka-dom-el";
+import { el, on } from "deka-dom-el";
 import { S } from "deka-dom-el/signals";
 document.body.append(
-	el(HelloWorldComponent)
+	el(HelloWorldComponent, { initial: "🚀" })
 );
-function HelloWorldComponent(){
+/** @typedef {"🎉" | "🚀"} Emoji */
-	const clicksS= S(0); // A
+/** @param {{ initial: Emoji }} attrs */
+function HelloWorldComponent({ initial }){
+	const clicks= S(0);
+	const emoji= S(initial);
+	/** @param {HTMLOptionElement} el */
+	const isSelected= el=> (el.selected= el.value===initial);
+	// @ts-expect-error 2339: The <select> has only two options with {@link Emoji}
+	const onChange= on("change", event=> emoji(event.target.value));
+
 	return el().append(
-		el("p", S(()=>
+		el("p", {
-			"Hello World "+"🎉".repeat(clicksS()) // B
+			textContent: S(() => `Hello World ${emoji().repeat(clicks())}`),
-		)),
+			className: "example",
-		el("button", {
+			ariaLive: "polite", //OR ariaset: { live: "polite" },
-			type: "button",
+			dataset: { example: "Example" }, //OR dataExample: "Example",
-			onclick: ()=> clicksS(clicksS()+1), // C
+		}),
-			textContent: "Fire",
+		el("button",
-		})
+			{ textContent: "Fire", type: "button" },
-	)
+			on("click", ()=> clicks(clicks() + 1)),
+			on("keyup", ()=> clicks(clicks() - 2)),
+		),
+		el("select", null, onChange).append(
+			el(OptionComponent, "🎉", isSelected),//OR { textContent: "🎉" }
+			el(OptionComponent, "🚀", isSelected),//OR { textContent: "🚀" }
+		)
+	);
+}
+function OptionComponent({ textContent }){
+	return el("option", { value: textContent, textContent })
 }

docs/components/mnemonic/customElement-init.js

@@ -4,8 +4,8 @@ import { mnemonicUl } from "../mnemonicUl.html.js";
 export function mnemonic(){
 	return mnemonicUl().append(
 		el("li").append(
-			el("code", "customElementRender(<custom-element>, <connect-target>, <render-function>[, <properties>])"),
+			el("code", "customElementRender(<connect-target>, <render-function>[, <properties>])"),
-			" — use function to render DOM structure for given <custom-element>",
+			" — use function to render DOM structure for given custom element (or its Shadow DOM)",
 		),
 		el("li").append(
 			el("code", "customElementWithDDE(<custom-element>)"),
@@ -24,7 +24,7 @@ export function mnemonic(){
 			" — convert lifecycle methods to events, can be also used as decorator",
 		),
 		el("li").append(
-			el("code", "simulateSlots(<class-instance>, <body>[, <mapper>])"),
+			el("code", "simulateSlots(<class-instance>, <body>)"),
 			" — simulate slots for Custom Elements without shadow DOM",
 		),
 		el("li").append(

index.d.ts

@@ -227,7 +227,6 @@ export function customElementRender<
 	EL extends HTMLElement,
 	P extends any = Record<string, string | ddeSignal<string>>
 >(
-	custom_element: EL,
 	target: ShadowRoot | EL,
 	render: (props: P)=> SupportedElement | DocumentFragment,
 	props?: P | ((el: EL)=> P)

src/dom.js

@@ -1,6 +1,7 @@
 import { signals } from "./signals-common.js";
 import { enviroment as env } from './dom-common.js';
 
+//TODO: add type, docs ≡ make it public
 export function queue(promise){ return env.q(promise); }
 /** @type {{ scope: object, prevent: boolean, host: function }[]} */
 const scopes= [ {

src/events.js

@@ -8,6 +8,7 @@ export function dispatchEvent(name, options, host){
 			d.unshift(element);
 			element= typeof host==="function"? host() : host;
 		}
+		//TODO: what about re-emmitting?
 		const event= d.length ? new CustomEvent(name, Object.assign({ detail: d[0] }, options)) : new Event(name, options);
 		return element.dispatchEvent(event);
 	};