🎉 docs/p05-scopes

docs_src/components/examples/scopes/class-component.js

@@ -0,0 +1,41 @@
+import { chainableAppend, el, scope } from "deka-dom-el";
+class Test {
+	constructor(params){
+		this._params= params;
+	}
+	render(){
+		return el("div").append(
+			this._params.textContent
+		);
+	}
+}
+document.body.append(
+	elClass(Test, { textContent: "Hello World" })
+);
+
+function elClass(c, props, ...addons){
+	let element, element_host;
+	scope.push({
+		scope: c, //just informative purposes
+		host: (...c)=> c.length
+		? (!element
+			? addons.unshift(...c)
+			: c.forEach(c=> c(element_host)), undefined)
+		: element_host
+	});
+	const C= new c(props);
+	element= C.render();
+	const is_fragment= el instanceof DocumentFragment;
+	const el_mark= el.mark({ //this creates html comment `<dde:mark …/>`
+		type: "class-component",
+		name: C.name,
+		host: is_fragment ? "this" : "parentElement",
+	});
+	element.prepend(el_mark);
+	if(is_fragment) element_host= el_mark;
+	
+	chainableAppend(element);
+	addons.forEach(c=> c(element_host));
+	scope.pop();
+	return element;
+}

docs_src/components/examples/scopes/intro.js

@@ -0,0 +1,3 @@
+// use NPM or for example https://cdn.jsdelivr.net/gh/jaandrle/deka-dom-el/dist/esm-with-observables.js
+import { scope, el, on } from "deka-dom-el";
+/** @type {ddeElementAddon} */

docs_src/components/examples/scopes/scopes-and-hosts.js

@@ -0,0 +1,33 @@
+import { el, on, scope } from "deka-dom-el";
+const { host }= scope;
+host(
+	element=> console.log(
+		"This represents Addon/oninit for root",
+		element.outerHTML
+	)
+);
+console.log(
+	"This represents the reference to the host element of root",
+	host().outerHTML
+);
+document.body.append(
+	el(component)
+);
+function component(){
+	const { host }= scope;
+	host(
+		element=> console.log(
+			"This represents Addon/oninit for the component",
+			element.outerHTML
+		)
+	);
+	const onclick= on("click", function(ev){
+		console.log(
+			"This represents the reference to the host element of the component",
+			host().outerHTML
+		);
+	})
+	return el("div", null, onclick).append(
+		el("strong", "Component")
+	);
+}

docs_src/components/mnemonic/scopes-init.js

@@ -0,0 +1,16 @@
+import { el } from "deka-dom-el";
+import { mnemonicUl } from "../mnemonicUl.html.js";
+
+export function mnemonic(){
+	return mnemonicUl().append(
+		el("li").append(
+			el("code", "el(<function>, <function-argument(s)>)[.append(...)]: <element-returned-by-function>"), " — using component represented by function",
+		),
+		el("li").append(
+			el("code", "scope.host()"), " — get current component reference"
+		),
+		el("li").append(
+			el("code", "scope.host(...<addons>)"), " — use addons to current component",
+		)
+	);
+}

docs_src/p05-scopes.html.js

@@ -0,0 +1,41 @@
+import { simplePage } from "./layout/simplePage.html.js";
+
+import { el } from "deka-dom-el";
+import { example } from "./components/example.html.js";
+import { h3 } from "./components/pageUtils.html.js";
+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);
+
+/** @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(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(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(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(example, { src: fileURL("./components/examples/scopes/class-component.js"), page_id }),
+
+		el(mnemonic)
+	);
+}

docs_src/ssr.js

@@ -7,6 +7,7 @@ export const pages= [
 	{ id: "p02-elements", href: "p02-elements", title: "Elements", description: "Basic concepts of elements modifications and creations." },
 	{ id: "p03-events", href: "p03-events", title: "Events and Addons", description: "Using not only events in UI declaratively." },
 	{ id: "p04-observables", href: "p04-observables", title: "Observables and reactivity", description: "Handling reactivity in UI via observables." },
+	{ id: "p05-scopes", href: "p05-scopes", title: "Scopes and components", description: "Organizing UI into components" },
 ];
 /**
  * @typedef registerClientFile