✏️ docs (🔨 examples, 🚧 events)

docs_src/components/example.html.js

@@ -24,7 +24,7 @@ import { code } from "./code.html.js";
 export function example({ src, language= "js", page_id }){
 	registerClientPart(page_id);
 	const content= s.cat(src).toString()
-		.replaceAll(' from "../../../index-with-signals.js";', ' from "https://cdn.jsdelivr.net/gh/jaandrle/deka-dom-el/dist/esm-with-signals.js";');
+		.replaceAll(/ from "deka-dom-el(\/signals)?";/g, ' from "https://cdn.jsdelivr.net/gh/jaandrle/deka-dom-el/dist/esm-with-signals.js";');
 	const id= "code-"+Math.random().toString(36).slice(2, 7);
 	return el().append(
 		el(code, { id, content, language, className: example.name }),

docs_src/components/examples/elements/dekaAppend.js

@@ -1,4 +1,4 @@
-import { el } from "../../../index-with-signals.js";
+import { el } from "deka-dom-el";
 document.head.append(
 	el("style").append(
 		"tr, td{ border: 1px solid red; padding: 1em; }",

docs_src/components/examples/elements/dekaAssign.js

@@ -1,4 +1,4 @@
-import { assignAttribute, classListDeclarative } from "../../../index-with-signals.js";
+import { assignAttribute, classListDeclarative } from "deka-dom-el";
 const paragraph= document.createElement("p");
 
 assignAttribute(paragraph, "textContent", "Hello, world!");

docs_src/components/examples/elements/dekaBasicComponent.js

@@ -1,4 +1,4 @@
-import { el } from "../../../index-with-signals.js";
+import { el } from "deka-dom-el";
 document.head.append(
 	el("style").append(
 		".class1{ font-weight: bold; }",

docs_src/components/examples/elements/dekaCreateElement.js

@@ -1,4 +1,4 @@
-import { el, assign } from "../../../index-with-signals.js";
+import { el, assign } from "deka-dom-el";
 const color= "lightcoral";
 document.body.append(
 	el("p", { textContent: "Hello (first time)", style: { color } })

docs_src/components/examples/elements/dekaElNS.js

@@ -1,4 +1,4 @@
-import { elNS, assign } from "../../../index-with-signals.js";
+import { elNS, assign } from "deka-dom-el";
 const elSVG= elNS("http://www.w3.org/2000/svg");
 const elMath= elNS("http://www.w3.org/1998/Math/MathML");
 document.body.append(

docs_src/components/examples/events/abortSignal.js

@@ -0,0 +1,13 @@
+import { el, on } from "deka-dom-el";
+const log= mark=> console.log.bind(console, mark);
+
+const abort_controller= new AbortController();
+const { signal }= abort_controller;
+
+const button= el("button", "Test click");
+button.addEventListener("click", log("`addEventListener`"), { signal });
+on("click", log("`on`"), { signal })(button);
+
+document.body.append(
+	button, " ", el("button", { textContent: "Off", onclick: ()=> abort_controller.abort() })
+);

docs_src/components/examples/events/compare.js

@@ -0,0 +1,10 @@
+import { el, on } from "deka-dom-el";
+const log= mark=> console.log.bind(console, mark);
+
+const button= el("button", "Test click");
+button.addEventListener("click", log("`addEventListener`"), { once: true });
+on("click", log("`on`"), { once: true })(button);
+
+document.body.append(
+	button
+);

docs_src/components/examples/events/templateWithListeners.js

@@ -0,0 +1,24 @@
+import { el, on } from "deka-dom-el";
+const abort_controller= new AbortController();
+const { signal }= abort_controller;
+/** @type {ddeElementModifier<HTMLButtonElement>} */
+const onclickOff= on("click", ()=> abort_controller.abort(), { signal });
+/** @type {(ref?: HTMLOutputElement)=> HTMLOutputElement | null} */
+const ref= (store=> ref=> ref ? (store= ref) : store)(null);
+
+document.body.append(
+	el("button", "Test `on`",
+		on("click", console.log, { signal }),
+		on("click", update, { signal }),
+		on("mouseup", update, { signal })),
+	" ",
+	el("button", "Off", onclickOff),
+	el("output", { style: { display: "block", whiteSpace: "pre" } }, ref)
+);
+/** @param {MouseEvent} event @this {HTMLButtonElement} */
+function update(event){
+	ref().append(
+		event.type,
+		"\n"
+	);
+}

docs_src/components/examples/helloWorld.js

@@ -1,4 +1,5 @@
-import { el, S } from "../../../index-with-signals.js";
+import { el } from "deka-dom-el";
+import { S } from "deka-dom-el/signals";
 const clicks= S(0);
 document.body.append(
 	el().append(

docs_src/elements.html.js

@@ -30,12 +30,12 @@ export function page({ pkg, info }){
 					el("abbr", { textContent: "IDL", title: "Interface Description Language" })
 				), " also known as a JavaScript property."
 			),
-			el(example, { src: fileURL("./components/examples/nativeCreateElement.js"), page_id }),
+			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(example, { src: fileURL("./components/examples/dekaCreateElement.js"), page_id }),
+			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. ",
@@ -76,15 +76,15 @@ export function page({ pkg, info }){
 			el("p").append(
 				"For processing, the ", el("code", "assign"), " internally uses ", el("code", "assignAttribute"), " and ", el("code", "classListDeclarative"), "."
 			),
-			el(example, { src: fileURL("./components/examples/dekaAssign.js"), page_id }),
+			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(example, { src: fileURL("./components/examples/nativeAppend.js"), page_id }),
+			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(example, { src: fileURL("./components/examples/dekaAppend.js"), page_id }),
+			el(example, { src: fileURL("./components/examples/elements/dekaAppend.js"), page_id }),
 			
 			
 			el("h3", "Basic (state-less) components"),
@@ -93,7 +93,7 @@ export function page({ pkg, info }){
 				"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/dekaBasicComponent.js"), page_id }),
+			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.",
@@ -110,7 +110,7 @@ export function page({ pkg, info }){
 				" 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/dekaElNS.js"), page_id }),
+			el(example, { src: fileURL("./components/examples/elements/dekaElNS.js"), page_id }),
 
 			el(prevNext, info)
 		)

docs_src/events.html.js

@@ -20,9 +20,49 @@ export function page({ pkg, info }){
 				" incorporate not only this in UI templates declaratively."
 			),
 			
-			el("h3", "Add events listeners"),
+			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(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").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(example, { src: fileURL("./components/examples/events/abortSignal.js"), page_id }),
+
+			el("h3", "Modifiers"),
+			el("p").append(
+				"From practical point of view, ", el("em", "Modifiers"), " 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 Modifiers 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(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", "ddeElementModifier"), ".",
+				" ",
+				"Also notice, you can use Modifiers to get element reference.",
+			),
+			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(prevNext, info)
 		)

docs_src/index.html.js

@@ -12,7 +12,7 @@ export function page({ pkg, info }){
 		el("main").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 elemnets and end up with UI templates.",
+				"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"), "."