mirror of
https://github.com/jaandrle/deka-dom-el
synced 2024-11-22 16:55:23 +01:00
91 lines
4.2 KiB
JavaScript
91 lines
4.2 KiB
JavaScript
export const info= {
|
|
title: "Scopes and components",
|
|
description: "Organizing UI into components",
|
|
};
|
|
|
|
import { el } from "deka-dom-el";
|
|
import { simplePage } from "./layout/simplePage.html.js";
|
|
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);
|
|
const references= {
|
|
/** Garbage collection on MDN */
|
|
garbage_collection: {
|
|
title: "MDN documentation page for Garbage collection",
|
|
href: "https://developer.mozilla.org/en-US/docs/Glossary/Garbage_collection",
|
|
},
|
|
/** Signals */
|
|
signals: {
|
|
title: "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", ...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(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("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(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(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", ...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(code, { src: fileURL("./components/examples/scopes/imperative.js"), page_id }),
|
|
|
|
el(mnemonic)
|
|
);
|
|
}
|