jaandrle/deka-dom-el
1
0
Fork 0
mirror of https://github.com/jaandrle/deka-dom-el synced 2025-07-01 04:12:14 +02:00
Code Packages Releases Activity

⚡ Docs

Browse Source
This commit is contained in:
Jan Andrle
2024-11-22 11:00:15 +01:00
parent e157d2843e
commit 0f91166811
78 changed files with 17 additions and 34032 deletions
Download Patch File Download Diff File Expand all files Collapse all files

63
docs/components/code.html.js Normal file
View File

@ -0,0 +1,63 @@
import { registerClientFile, styles } from "../ssr.js";
const host= "."+code.name;
styles.css`
${host}{
--shiki-color-text: #e9eded;
--shiki-color-background: #212121;
--shiki-token-constant: #82b1ff;
--shiki-token-string: #c3e88d;
--shiki-token-comment: #546e7a;
--shiki-token-keyword: #c792ea;
--shiki-token-parameter: #AA0000;
--shiki-token-function: #80cbae;
--shiki-token-string-expression: #c3e88d;
--shiki-token-punctuation: var(--code);
--shiki-token-link: #EE0000;
white-space: pre;
tab-size: 2; /* TODO: allow custom tab size?! */
overflow: scroll;
}
${host}[data-js=todo]{
border: 1px solid var(--border);
border-radius: var(--standard-border-radius);
margin-bottom: 1rem;
margin-top: 18.4px; /* to fix shift when → dataJS=done */
padding: 1rem 1.4rem;
}
`;
import { el } from "deka-dom-el";
/**
* Prints code to the page and registers flems to make it interactive.
* @param {object} attrs
* @param {string} [attrs.id]
* @param {string} [attrs.className]
* @param {URL} [attrs.src] Example code file path
* @param {string} [attrs.content] Example code
* @param {"js"|"ts"|"html"|"css"} [attrs.language="js"] Language of the code
* @param {string} [attrs.page_id] ID of the page, if setted it registers shiki
* */
export function code({ id, src, content, language= "js", className= host.slice(1), page_id }){
if(src) content= s.cat(src);
let dataJS;
if(page_id){
registerClientPart(page_id);
dataJS= "todo";
}
return el("div", { id, className, dataJS }).append(
el("code", { className: "language-"+language, textContent: content })
);
}
let is_registered= {};
/** @param {string} page_id */
function registerClientPart(page_id){
if(is_registered[page_id]) return;
document.head.append(
el("script", { src: "https://cdn.jsdelivr.net/npm/shiki@0.9", defer: true }),
);
registerClientFile(
new URL("./code.js.js", import.meta.url),
el("script", { type: "module" })
);
is_registered[page_id]= true;
}

0
docs/code.js.js → docs/components/code.js.js
View File

68
docs/components/example.html.js Normal file
View File

@ -0,0 +1,68 @@
import { styles } from "../ssr.js";
const host= "."+example.name;
styles.css`
${host}{
grid-column: full-main;
width: 100%;
max-width: calc(9/5 * var(--body-max-width));
height: calc(3/5 * var(--body-max-width));
margin-inline: auto;
}
.CodeMirror, .CodeMirror-gutters {
background: #212121 !important;
border: 1px solid white;
}
`;
const dde_content= s.cat(new URL("../../dist/esm-with-signals.js", import.meta.url)).toString();
import { el } from "deka-dom-el";
import { code } from "./code.html.js";
import { relative } from "node:path";
/**
* Prints code to the page and registers flems to make it interactive.
* @param {object} attrs
* @param {URL} attrs.src Example code file path
* @param {"js"|"ts"|"html"|"css"} [attrs.language="js"] Language of the code
* @param {string} attrs.page_id ID of the page
* */
export function example({ src, language= "js", page_id }){
registerClientPart(page_id);
const content= s.cat(src).toString()
.replaceAll(/ from "deka-dom-el(\/signals)?";/g, ' from "./esm-with-signals.js";');
const id= "code-example-"+generateCodeId(src);
return el().append(
el(code, { id, content, language, className: example.name }),
elCode({ id, content, extension: "."+language })
);
}
function elCode({ id, content, extension: name }){
const options= JSON.stringify({
files: [{ name, content }, { name: "esm-with-signals.js", content: dde_content }],
toolbar: false
});
return el("script", `Flems(document.getElementById("${id}"), JSON.parse(${JSON.stringify(options)}));`);
}
let is_registered= {};
/** @param {string} page_id */
function registerClientPart(page_id){
if(is_registered[page_id]) return;
document.head.append(
el("script", { src: "https://flems.io/flems.html", type: "text/javascript", charset: "utf-8" }),
);
is_registered[page_id]= true;
}
const store_prev= new Map();
/** @param {URL} src */
function generateCodeId(src){
const candidate= parseInt(relative((new URL("..", import.meta.url)).pathname, src.pathname)
.split("")
.map(ch=> ch.charCodeAt(0))
.join(""), 10)
.toString(36)
.replace(/000+/g, "");
const count= 1 + ( store_prev.get(candidate) || 0 );
store_prev.set(candidate, count);
return count.toString()+"-"+candidate;
}

23
docs/components/examples/customElement/customElementWithDDE.js Normal file
View File

@ -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,
);

33
docs/components/examples/customElement/dde.js Normal file
View File

@ -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" })
);

12
docs/components/examples/customElement/intro.js Normal file
View File

@ -0,0 +1,12 @@
// use NPM or for example https://cdn.jsdelivr.net/gh/jaandrle/deka-dom-el/dist/esm-with-signals.js
import {
customElementRender,
customElementWithDDE,
observedAttributes,
} from "deka-dom-el";
/** @type {ddePublicElementTagNameMap} */
import { S } from "deka-dom-el/signals";
S.observedAttributes;
// “internal” utils
import { lifecyclesToEvents } from "deka-dom-el";

21
docs/components/examples/customElement/native-basic.js Normal file
View File

@ -0,0 +1,21 @@
export class HTMLCustomElement extends HTMLElement{
static tagName= "custom-element"; // just suggestion, we can use `el(HTMLCustomElement.tagName)`
static observedAttributes= [ "custom-attribute" ];
constructor(){
super();
// nice place to prepare custom element
}
connectedCallback(){
// nice place to render custom element
}
attributeChangedCallback(name, oldValue, newValue){
// listen to attribute changes (see `observedAttributes`)
}
disconnectedCallback(){
// nice place to clean up
}
// for example, we can mirror get/set prop to attribute
get customAttribute(){ return this.getAttribute("custom-attribute"); }
set customAttribute(value){ this.setAttribute("custom-attribute", value); }
}
customElements.define(HTMLCustomElement.tagName, HTMLCustomElement);

42
docs/components/examples/customElement/observedAttributes.js Normal file
View File

@ -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
);

69
docs/components/examples/customElement/shadowRoot.js Normal file
View File

@ -0,0 +1,69 @@
import {
el,
customElementRender,
customElementWithDDE,
} from "deka-dom-el";
function ddeComponent(){
return el().append(
el("style", `
.red{ color: firebrick; }
`),
el("p", { className: "red" }).append(
"Hello from ", el("slot", "Custom Element"), "!"
)
);
}
export class A extends HTMLElement{
static tagName= "custom-element-without";
connectedCallback(){
customElementRender(
this,
this,
ddeComponent
);
}
}
customElementWithDDE(A);
customElements.define(A.tagName, A);
export class B extends HTMLElement{
static tagName= "custom-element-open";
connectedCallback(){
customElementRender(
this,
this.attachShadow({ mode: "open" }),
ddeComponent
);
}
}
customElementWithDDE(B);
customElements.define(B.tagName, B);
export class C extends HTMLElement{
static tagName= "custom-element-closed";
connectedCallback(){
customElementRender(
this,
this.attachShadow({ mode: "closed" }),
ddeComponent
);
}
}
customElementWithDDE(C);
customElements.define(C.tagName, C);
document.body.append(
el(A.tagName).append("Without shadowRoot"),
el("hr"),
el(B.tagName).append("Open shadowRoot"),
el("hr"),
el(C.tagName).append("Closed shadowRoot"),
el("style", `
.red{ color: crimson; }
`),
);
console.log(A.tagName, "expect modifications");
document.body.querySelector(A.tagName).querySelector("p").textContent+= " (editable with JS)";
console.log(B.tagName, "expect modifications");
document.body.querySelector(B.tagName).shadowRoot.querySelector("p").textContent+= " (editable with JS)";
console.log(C.tagName, "expect error ↓");
document.body.querySelector(C.tagName).querySelector("p").textContent+= " (editable with JS)";

41
docs/components/examples/customElement/simulateSlots.js Normal file
View File

@ -0,0 +1,41 @@
import {
customElementRender,
customElementWithDDE,
el,
simulateSlots
} from "deka-dom-el";
export class HTMLCustomElement extends HTMLElement{
static tagName= "custom-slotting";
connectedCallback(){
const c= ()=> simulateSlots(this, ddeComponent());
customElementRender(this, this, c);
}
}
customElementWithDDE(HTMLCustomElement);
customElements.define(HTMLCustomElement.tagName, HTMLCustomElement);
document.body.append(
el(HTMLCustomElement.tagName),
el(HTMLCustomElement.tagName).append(
"Slot"
),
el(ddeComponentSlot),
el(ddeComponentSlot).append(
"Slot"
),
);
function ddeComponent(){
return el().append(
el("p").append(
"Hello ", el("slot", "World")
)
);
}
function ddeComponentSlot(){
return simulateSlots(el().append(
el("p").append(
"Hello ", el("slot", "World")
)
));
}

35
docs/components/examples/elements/dekaAppend.js Normal file
View File

@ -0,0 +1,35 @@
import { el } from "deka-dom-el";
document.head.append(
el("style").append(
"tr, td{ border: 1px solid red; padding: 1em; }",
"table{ border-collapse: collapse; }"
)
);
document.body.append(
el("p", "Example of a complex template. Using for example nesting lists:"),
el("ul").append(
el("li", "List item 1"),
el("li").append(
el("ul").append(
el("li", "Nested list item 1"),
)
)
),
el("table").append(
el("tr").append(
el("td", "Row 1 – Col 1"),
el("td", "Row 1 – Col 2")
)
)
);
import { chainableAppend } from "deka-dom-el";
/** @param {keyof HTMLElementTagNameMap} tag */
const createElement= tag=> chainableAppend(document.createElement(tag));
document.body.append(
createElement("p").append(
createElement("em").append(
"You can also use `chainableAppend`!"
)
)
);

33
docs/components/examples/elements/dekaAssign.js Normal file
View File

@ -0,0 +1,33 @@
import { assign, assignAttribute, classListDeclarative } from "deka-dom-el";
const paragraph= document.createElement("p");
assignAttribute(paragraph, "textContent", "Hello, world!");
assignAttribute(paragraph, "style", "color: red; font-weight: bold;");
assignAttribute(paragraph, "style", { color: "navy" });
assignAttribute(paragraph, "dataTest1", "v1");
assignAttribute(paragraph, "dataset", { test2: "v2" });
assign(paragraph, { //textContent and style see above
ariaLabel: "v1", //data* see above
ariaset: { role: "none" }, // dataset see above
"=onclick": "console.log(event)",
onmouseout: console.info,
".something": "something",
classList: {} //see below
});
classListDeclarative(paragraph, {
classAdd: true,
classRemove: false,
classAdd1: 1,
classRemove1: 0,
classToggle: -1
});
console.log(paragraph.outerHTML);
console.log("paragraph.something=", paragraph.something);
document.body.append(
paragraph
);

17
docs/components/examples/elements/dekaBasicComponent.js Normal file
View File

@ -0,0 +1,17 @@
import { el } from "deka-dom-el";
document.head.append(
el("style").append(
".class1{ font-weight: bold; }",
".class2{ color: purple; }"
)
);
document.body.append(
el(component, { className: "class2", textContent: "Hello World!" }),
component({ className: "class2", textContent: "Hello World!" })
);
function component({ className, textContent }){
return el("div", { className: [ "class1", className ] }).append(
el("p", textContent)
);
}

11
docs/components/examples/elements/dekaCreateElement.js Normal file
View File

@ -0,0 +1,11 @@
import { el, assign } from "deka-dom-el";
const color= "lightcoral";
document.body.append(
el("p", { textContent: "Hello (first time)", style: { color } })
);
document.body.append(
assign(
document.createElement("p"),
{ textContent: "Hello (second time)", style: { color } }
)
);

11
docs/components/examples/elements/dekaElNS.js Normal file
View File

@ -0,0 +1,11 @@
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(
elSVG("svg"), // see https://developer.mozilla.org/en-US/docs/Web/SVG and https://developer.mozilla.org/en-US/docs/Web/API/SVGElement
elMath("math") // see https://developer.mozilla.org/en-US/docs/Web/MathML and https://developer.mozilla.org/en-US/docs/Web/MathML/Global_attributes
);
console.log(
document.body.innerHTML.includes("<svg></svg><math></math>")
)

14
docs/components/examples/elements/intro.js Normal file
View File

@ -0,0 +1,14 @@
// use NPM or for example https://cdn.jsdelivr.net/gh/jaandrle/deka-dom-el/dist/esm.js
import {
assign,
el, createElement,
elNS, createElementNS
} from "deka-dom-el";
el===createElement
elNS===createElementNS
// “internal” utils
import {
assignAttribute,
classListDeclarative,
chainableAppend
} from "deka-dom-el";

11
docs/components/examples/elements/nativeAppend.js Normal file
View File

@ -0,0 +1,11 @@
document.body.append(
document.createElement("div"),
document.createElement("span"),
document.createElement("main")
);
console.log(document.body.innerHTML.includes("<div></div><span></span><main></main>"));
const template= document.createElement("main").append(
document.createElement("div"),
document.createElement("span"),
);
console.log(typeof template==="undefined");

14
docs/components/examples/elements/nativeCreateElement.js Normal file
View File

@ -0,0 +1,14 @@
document.body.append(
document.createElement("div")
);
console.log(
"Emty div is generated inside <body>:",
document.body.innerHTML.includes("<div></div>")
);
document.body.append(
Object.assign(
document.createElement("p"),
{ textContent: "Element’s text content.", style: "color: coral;" }
)
);

13
docs/components/examples/events/abortSignal.js Normal file
View File

@ -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() })
);

10
docs/components/examples/events/compare.js Normal file
View File

@ -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
);

24
docs/components/examples/events/compareDispatch.js Normal file
View File

@ -0,0 +1,24 @@
import { el, on, dispatchEvent } from "deka-dom-el";
document.body.append(
el("p", "Listenning to `test` event.", on("test", console.log)).append(
el("br"),
el("button", "native", on("click", native)),
" ",
el("button", "dde", on("click", dde)),
" ",
el("button", "dde with options", on("click", ddeOptions))
)
);
function native(){
this.dispatchEvent(
new CustomEvent("test",
{ bubbles: true, detail: "hi" }
)
);
}
function dde(){
dispatchEvent("test")(this.parentElement, "hi");
}
function ddeOptions(){
dispatchEvent("test", { bubbles: true })(this, "hi");
}

4
docs/components/examples/events/intro.js Normal file
View File

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

18
docs/components/examples/events/live-cycle.js Normal file
View File

@ -0,0 +1,18 @@
import { el, on } from "deka-dom-el";
const paragraph= el("p", "See live-cycle events in console.",
el=> log({ type: "dde:created", detail: el }),
on.connected(log),
on.disconnected(log),
on.attributeChanged(log));
document.body.append(
paragraph,
el("button", "Update attribute", on("click", ()=> paragraph.setAttribute("test", Math.random().toString()))),
" ",
el("button", "Remove", on("click", ()=> paragraph.remove()))
);
/** @param {Partial<CustomEvent>} event */
function log({ type, detail }){
console.log({ _this: this, type, detail });
}

24
docs/components/examples/events/templateWithListeners.js Normal file
View File

@ -0,0 +1,24 @@
import { el, on } from "deka-dom-el";
const abort_controller= new AbortController();
const { signal }= abort_controller;
/** @type {ddeElementAddon<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"
);
}

6
docs/components/examples/introducing/3ps.js Normal file
View File

@ -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

15
docs/components/examples/introducing/helloWorld.js Normal file
View File

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

44
docs/components/examples/scopes/class-component.js Normal file
View File

@ -0,0 +1,44 @@
import { el } 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" })
);
import { chainableAppend, scope } from "deka-dom-el";
function elClass(_class, attributes, ...addons){
let element, element_host;
scope.push({
scope: _class, //just informative purposes
host: (...addons_append)=> addons_append.length
? (
!element
? addons.unshift(...addons_append)
: addons_append.forEach(c=> c(element_host))
, undefined)
: element_host
});
const instance= new _class(attributes);
element= instance.render();
const is_fragment= element instanceof DocumentFragment;
const el_mark= el.mark({ //this creates html comment `<dde:mark …/>`
type: "class-component",
name: _class.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;
}

18
docs/components/examples/scopes/cleaning.js Normal file
View File

@ -0,0 +1,18 @@
import { el, empty, on } from "deka-dom-el";
document.body.append(
el(component),
el("button", {
textContent: "Remove",
onclick: ()=> empty(document.body),
type: "button"
})
);
import { S } from "deka-dom-el/signals";
function component(){
const textContent= S("Click to change text.");
const onclickChange= on("click", function redispatch(){
textContent("Text changed! "+(new Date()).toString())
});
return el("p", textContent, onclickChange);
}

35
docs/components/examples/scopes/declarative.js Normal file
View File

@ -0,0 +1,35 @@
/* PSEUDO-CODE!!! */
import { el } from "deka-dom-el";
import { S } from "deka-dom-el/signals";
function component(){
/* prepare changeable data */
const dataA= S("data");
const dataB= S("data");
/* define data flow (can be asynchronous) */
fetchAPI().then(data_new=> dataA(data_new));
setTimeout(()=> dataB("DATA"));
/* declarative UI */
return el().append(
el("h1", {
textContent: "Example",
/* declarative attribute(s) */
classList: { declarative: dataB }
}),
el("ul").append(
/* declarative element(s) */
S.el(dataA, data=> data.map(d=> el("li", d)))
),
el("ul").append(
/* declarative component(s) */
S.el(dataA, data=> data.map(d=> el(subcomponent, d)))
)
);
}
function subcomponent({ id }){
/* prepare changeable data */
const textContent= S("…");
/* define data flow (can be asynchronous) */
fetchAPI(id).then(text=> textContent(text));
/* declarative UI */
return el("li", { textContent, dataId: id });
}

18
docs/components/examples/scopes/good-practise.js Normal file
View File

@ -0,0 +1,18 @@
import { el, scope, on, dispatchEvent } from "deka-dom-el";
document.body.append(
el(component)
);
function component(){
const { host }= scope; // good practise!
host(
console.log,
on("click", function redispatch(){
// this `host` ↘ still corresponds to the host ↖ of the component
dispatchEvent("redispatch")(host());
})
);
// this `host` ↘ still corresponds to the host ↖ of the component
setTimeout(()=> dispatchEvent("timeout")(host()), 750)
return el("p", "Clickable paragraph!");
}

31
docs/components/examples/scopes/imperative.js Normal file
View File

@ -0,0 +1,31 @@
/* PSEUDO-CODE!!! */
import { el, on, scope } from "deka-dom-el";
function component(){
const { host }= scope;
const ul= el("ul");
const ac= new AbortController();
fetchAPI({ signal: ac.signal }).then(data=> {
data.forEach(d=> ul.append(el("li", d)));
});
host(
/* element was remove before data fetched */
on.disconnected(()=> ac.abort())
);
return ul;
/**
* NEVER EVER!!
* let data;
* fetchAPI().then(d=> data= O(d));
*
* OR NEVER EVER!!
* const ul= el("ul");
* fetchAPI().then(d=> {
* const data= O("data");
* ul.append(el("li", data));
* });
*
* // THE HOST IS PROBABLY DIFFERENT THAN
* // YOU EXPECT AND OBSERVABLES MAY BE
* // UNEXPECTEDLY REMOVED!!!
* */
}

3
docs/components/examples/scopes/intro.js Normal file
View File

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

33
docs/components/examples/scopes/scopes-and-hosts.js Normal file
View File

@ -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")
);
}

18
docs/components/examples/signals/actions-demo.js Normal file
View File

@ -0,0 +1,18 @@
import { S } from "deka-dom-el/signals";
const signal= S(0, {
increaseOnlyOdd(add){
console.info(add);
if(add%2 === 0) return this.stopPropagation();
this.value+= add;
}
});
S.on(signal, console.log);
const oninterval= ()=>
S.action(signal, "increaseOnlyOdd", Math.floor(Math.random()*100));
const interval= 5*1000;
setTimeout(
clearInterval,
10*interval,
setInterval(oninterval, interval)
);

56
docs/components/examples/signals/actions-todos.js Normal file
View File

@ -0,0 +1,56 @@
import { S } from "deka-dom-el/signals";
const todos= S([], {
push(item){
this.value.push(S(item));
},
pop(){
const removed= this.value.pop();
if(removed) S.clear(removed);
},
[S.symbols.onclear](){ // this covers `O.clear(todos)`
S.clear(...this.value);
}
});
import { el, on } from "deka-dom-el";
/** @type {ddeElementAddon<HTMLFormElement>} */
const onsubmit= on("submit", function(event){
event.preventDefault();
const data= new FormData(this);
switch (data.get("op")){
case "A"/*dd*/:
S.action(todos, "push", data.get("todo"));
break;
case "E"/*dit*/: {
const last= todos().at(-1);
if(!last) break;
last(data.get("todo"));
break;
}
case "R"/*emove*/:
S.action(todos, "pop");
break;
}
});
document.body.append(
el("ul").append(
S.el(todos, todos=>
todos.map(textContent=> el("li", textContent)))
),
el("form", null, onsubmit).append(
el("input", { type: "text", name: "todo", placeholder: "Todo’s text" }),
el(radio, { textContent: "Add", checked: true }),
el(radio, { textContent: "Edit last" }),
el(radio, { textContent: "Remove" }),
el("button", "Submit")
)
);
document.head.append(
el("style", "form{ display: flex; flex-flow: column nowrap; }")
);
function radio({ textContent, checked= false }){
return el("label").append(
el("input", { type: "radio", name: "op", value: textContent[0], checked }),
" ",textContent
)
}

16
docs/components/examples/signals/computations-abort.js Normal file
View File

@ -0,0 +1,16 @@
import { S } from "deka-dom-el/signals";
const signal= S(0);
// computation pattern
const double= S(()=> 2*signal());
const ac= new AbortController();
S.on(signal, v=> console.log("signal", v), { signal: ac.signal });
S.on(double, v=> console.log("double", v), { signal: ac.signal });
signal(signal()+1);
const interval= 5 * 1000;
const id= setInterval(()=> signal(signal()+1), interval);
ac.signal.addEventListener("abort",
()=> setTimeout(()=> clearInterval(id), 2*interval));
setTimeout(()=> ac.abort(), 3*interval)

15
docs/components/examples/signals/dom-attrs.js Normal file
View File

@ -0,0 +1,15 @@
import { S } from "deka-dom-el/signals";
const count= S(0);
import { el } from "deka-dom-el";
document.body.append(
el("p", S(()=> "Currently: "+count())),
el("p", { classList: { red: S(()=> count()%2) }, dataset: { count }, textContent: "Attributes example" })
);
document.head.append(
el("style", ".red { color: red; }")
);
const interval= 5 * 1000;
setTimeout(clearInterval, 10*interval,
setInterval(()=> count(count()+1), interval));

26
docs/components/examples/signals/dom-el.js Normal file
View File

@ -0,0 +1,26 @@
import { S } from "deka-dom-el/signals";
const count= S(0, {
add(){ this.value= this.value + Math.round(Math.random()*10); }
});
const numbers= S([ count() ], {
push(next){ this.value.push(next); }
});
import { el } from "deka-dom-el";
document.body.append(
S.el(count, count=> count%2
? el("p", "Last number is odd.")
: el()
),
el("p", "Lucky numbers:"),
el("ul").append(
S.el(numbers, numbers=> numbers.toReversed()
.map(n=> el("li", n)))
)
);
const interval= 5*1000;
setTimeout(clearInterval, 10*interval, setInterval(function(){
S.action(count, "add");
S.action(numbers, "push", count());
}, interval));

6
docs/components/examples/signals/intro.js Normal file
View File

@ -0,0 +1,6 @@
// use NPM or for example https://cdn.jsdelivr.net/gh/jaandrle/deka-dom-el/dist/esm-with-signals.js
import { S, signal } from "deka-dom-el/signals";
S===signal
/** @type {ddeSignal} */
/** @type {ddeAction} */
/** @type {ddeActions} */

12
docs/components/examples/signals/signals.js Normal file
View File

@ -0,0 +1,12 @@
import { S } from "deka-dom-el/signals";
// α — `signal` represents a reactive value
const signal= S(0);
// β — just reacts on signal changes
S.on(signal, console.log);
// γ — just updates the value
const update= ()=> signal(signal()+1);
update();
const interval= 5*1000;
setTimeout(clearInterval, 10*interval,
setInterval(update, interval));

28
docs/components/mnemonic/customElement-init.js Normal file
View File

@ -0,0 +1,28 @@
import { el } from "deka-dom-el";
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>])"), " — 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",
),
el("li").append(
el("code", "observedAttributes(<custom-element>)"), " — returns record of observed attributes (keys uses camelCase)",
),
el("li").append(
el("code", "S.observedAttributes(<custom-element>)"), " — returns record of observed attributes (keys uses camelCase and values are signals)",
),
el("li").append(
el("code", "lifecyclesToEvents(<class-declaration>)"), " — convert lifecycle methods to events, can be also used as decorator",
),
el("li").append(
el("code", "simulateSlots(<class-instance>, <body>[, <mapper>])"), " — simulate slots for Custom Elements without shadow DOM",
),
el("li").append(
el("code", "simulateSlots(<dde-component>[, <mapper>])"), " — simulate slots for “dde”/functional components",
),
);
}

25
docs/components/mnemonic/elements-init.js Normal file
View File

@ -0,0 +1,25 @@
import { el } from "deka-dom-el";
import { mnemonicUl } from "../mnemonicUl.html.js";
export function mnemonic(){
return mnemonicUl().append(
el("li").append(
el("code", "assign(<element>, ...<idl-objects>): <element>"), " — assign properties to the element",
),
el("li").append(
el("code", "el(<tag-name>, <primitive>)[.append(...)]: <element-from-tag-name>"), " — simple element containing only text",
),
el("li").append(
el("code", "el(<tag-name>, <idl-object>)[.append(...)]: <element-from-tag-name>"), " — element with more properties",
),
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", "el(<...>, <...>, ...<addons>)"), " — see following page"
),
el("li").append(
el("code", "elNS(<namespace>)(<as-el-see-above>)[.append(...)]: <element-based-on-arguments>"), " — typically SVG elements",
)
);
}

20
docs/components/mnemonic/events-init.js Normal file
View File

@ -0,0 +1,20 @@
import { el } from "deka-dom-el";
import { mnemonicUl } from "../mnemonicUl.html.js";
export function mnemonic(){
return mnemonicUl().append(
el("li").append(
el("code", "on(<event>, <listener>[, <options>])(<element>)"), " — just ", el("code", "<element>.addEventListener(<event>, <listener>[, <options>])")
),
el("li").append(
el("code", "on.<live-cycle>(<event>, <listener>[, <options>])(<element>)"), " — corresponds to custom elemnets callbacks ", el("code", "<live-cycle>Callback(...){...}"),
". To connect to custom element see following page, else it is simulated by MutationObserver."
),
el("li").append(
el("code", "dispatchEvent(<event>[, <options>])(element)"), " — just ", el("code", "<element>.dispatchEvent(new Event(<event>[, <options>]))")
),
el("li").append(
el("code", "dispatchEvent(<event>[, <options>])(element, detail)"), " — just ", el("code", "<element>.dispatchEvent(new CustomEvent(<event>, { detail, ...<options> }))")
),
);
}

16
docs/components/mnemonic/scopes-init.js Normal file
View File

@ -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",
)
);
}

28
docs/components/mnemonic/signals-init.js Normal file
View File

@ -0,0 +1,28 @@
import { el } from "deka-dom-el";
import { mnemonicUl } from "../mnemonicUl.html.js";
export function mnemonic(){
return mnemonicUl().append(
el("li").append(
el("code", "S(<value>)"), " — signal: reactive value",
),
el("li").append(
el("code", "S(()=> <computation>)"), " — read-only signal: reactive value dependent on calculation using other signals",
),
el("li").append(
el("code", "S.on(<signal>, <listener>[, <options>])"), " — listen to the signal value changes",
),
el("li").append(
el("code", "S.clear(...<signals>)"), " — off and clear signals",
),
el("li").append(
el("code", "S(<value>, <actions>)"), " — signal: pattern to create complex reactive objects/arrays",
),
el("li").append(
el("code", "S.action(<signal>, <action-name>, ...<action-arguments>)"), " — invoke an action for given signal"
),
el("li").append(
el("code", "S.el(<signal>, <function-returning-dom>)"), " — render partial dom structure (template) based on the current signal value",
)
);
}

19
docs/components/mnemonicUl.html.js Normal file
View File

@ -0,0 +1,19 @@
import { styles } from "../ssr.js";
import { h3 } from "./pageUtils.html.js";
const host= ".notice";
styles.css`
${host} h3{
margin-top: 0;
}
`;
import { el, simulateSlots } from "deka-dom-el";
/** @param {Object} [props] @param {string} [props.textContent] */
export function mnemonicUl({ textContent= "" }= {}){
if(textContent) textContent= " – "+textContent
return simulateSlots(el("div", { className: "notice" }).append(
el(h3, "Mnemonic"+textContent),
el("ul").append(
el("slot")
)
));
}

54
docs/components/pageUtils.html.js Normal file
View File

@ -0,0 +1,54 @@
import { pages, styles } from "../ssr.js";
const host= "."+prevNext.name;
styles.css`
${host}{
display: grid;
grid-template-columns: 1fr 2fr 1fr;
margin-top: 1rem;
border-top: 1px solid var(--border);
}
${host} [rel=prev]{
grid-column: 1;
}
${host} [rel=next]{
grid-column: 3;
text-align: right;
}
`;
import { el } from "../../index.js";
/**
* @param {Object} attrs
* @param {string} attrs.textContent
* @param {string} [attrs.id]
* */
export function h3({ textContent, id }){
if(!id) id= "h-"+textContent.toLowerCase().replaceAll(/\s/g, "-").replaceAll(/[^a-z-]/g, "");
return el("h3", { id }).append(
el("a", { textContent: "#", href: "#"+id, tabIndex: -1 }),
" ", textContent
);
}
/**
* @param {import("../types.d.ts").Info} page
* */
export function prevNext(page){
const page_index= pages.indexOf(page);
return el("div", { className: prevNext.name }).append(
el(pageLink, { rel: "prev", page: pages[page_index-1] }),
el(pageLink, { rel: "next", page: pages[page_index+1] })
);
}
/**
* @param {Object} attrs
* @param {"prev"|"next"} attrs.rel
* @param {import("../types.d.ts").Info} [attrs.page]
* */
function pageLink({ rel, page }){
if(!page) return el();
let { href, title, description }= page;
return el("a", { rel, href, title: description }).append(
rel==="next" ?"(next) " : "",
title,
rel==="prev" ? " (previous)" : "",
);
}

1081
docs/flems.html
View File

File diff suppressed because one or more lines are too long

15
docs/flems_soubory/commandline.html
View File

@ -1,15 +0,0 @@
<!DOCTYPE html>
<html class="TridactylOwnNamespace TridactylThemeDark"><head>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<meta charset="utf-8">
<title>Tridactyl commandline</title>
<link rel="stylesheet" href="commandline_data/cleanslate.css">
<link rel="stylesheet" href="commandline_data/commandline.css">
</head>
<body>
<div id="completions"></div>
<div id="command-line-holder"><span id="tridactyl-colon"></span><input id="tridactyl-input"></div>
<script src="commandline_data/commandline_frame.js"></script>
</body></html>

449
docs/flems_soubory/commandline_data/cleanslate.css
View File

@ -1,449 +0,0 @@
/*!
* CleanSlate
* github.com/premasagar/cleanslate
*
*//*
An extreme CSS reset stylesheet, for normalising the styling of a container element and its children.
by Premasagar Rose
dharmafly.com
license
opensource.org/licenses/mit-license.php
**
v0.9.3
*/
/* == BLANKET RESET RULES == */
/* HTML 4.01 */
.cleanslate, .cleanslate h1, .cleanslate h2, .cleanslate h3, .cleanslate h4, .cleanslate h5, .cleanslate h6, .cleanslate p, .cleanslate td, .cleanslate dl, .cleanslate tr, .cleanslate dt, .cleanslate ol, .cleanslate form, .cleanslate select, .cleanslate option, .cleanslate pre, .cleanslate div, .cleanslate table, .cleanslate th, .cleanslate tbody, .cleanslate tfoot, .cleanslate caption, .cleanslate thead, .cleanslate ul, .cleanslate li, .cleanslate address, .cleanslate blockquote, .cleanslate dd, .cleanslate fieldset, .cleanslate li, .cleanslate iframe, .cleanslate strong, .cleanslate legend, .cleanslate em, .cleanslate summary, .cleanslate cite, .cleanslate span, .cleanslate input, .cleanslate sup, .cleanslate label, .cleanslate dfn, .cleanslate object, .cleanslate big, .cleanslate q, .cleanslate samp, .cleanslate acronym, .cleanslate small, .cleanslate img, .cleanslate strike, .cleanslate code, .cleanslate sub, .cleanslate ins, .cleanslate textarea, .cleanslate button, .cleanslate var, .cleanslate a, .cleanslate abbr, .cleanslate applet, .cleanslate del, .cleanslate kbd, .cleanslate tt, .cleanslate b, .cleanslate i, .cleanslate hr,
/* HTML5 - Sept 2013 taken from MDN https://developer.mozilla.org/en-US/docs/Web/Guide/HTML/HTML5/HTML5_element_list */
.cleanslate article, .cleanslate aside, .cleanslate figure, .cleanslate figcaption, .cleanslate footer, .cleanslate header, .cleanslate menu, .cleanslate nav, .cleanslate section, .cleanslate time, .cleanslate mark, .cleanslate audio, .cleanslate video, .cleanslate abbr, .cleanslate address, .cleanslate area, .cleanslate blockquote, .cleanslate canvas, .cleanslate caption, .cleanslate cite, .cleanslate code, .cleanslate colgroup, .cleanslate col, .cleanslate datalist, .cleanslate fieldset, .cleanslate main, .cleanslate map, .cleanslate meta, .cleanslate optgroup, .cleanslate output, .cleanslate progress {
background-attachment:scroll !important;
background-color:transparent !important;
background-image:none !important; /* This rule affects the use of pngfix JavaScript http://dillerdesign.com/experiment/DD_BelatedPNG for IE6, which is used to force the browser to recognise alpha-transparent PNGs files that replace the IE6 lack of PNG transparency. (The rule overrides the VML image that is used to replace the given CSS background-image). If you don't know what that means, then you probably haven't used the pngfix script, and this comment may be ignored :) */
background-position:0 0 !important;
background-repeat:repeat !important;
border-color:black !important;
border-color:currentColor !important; /* `border-color` should match font color. Modern browsers (incl. IE9) allow the use of "currentColor" to match the current font 'color' value <http://www.w3.org/TR/css3-color/#currentcolor>. For older browsers, a default of 'black' is given before this rule. Guideline to support older browsers: if you haven't already declared a border-color for an element, be sure to do so, e.g. when you first declare the border-width. */
border-radius:0 !important;
border-style:none !important;
border-width:medium !important;
bottom:auto !important;
clear:none !important;
clip:auto !important;
color:inherit !important;
counter-increment:none !important;
counter-reset:none !important;
cursor:auto !important;
direction:inherit !important;
display:inline !important;
float:none !important;
font-family: inherit !important; /* As with other inherit values, this needs to be set on the root container element */
font-size: inherit !important;
font-style:inherit !important;
font-variant:normal !important;
font-weight:inherit !important;
height:auto !important;
left:auto !important;
letter-spacing:normal !important;
line-height:inherit !important;
list-style-type: inherit !important; /* Could set list-style-type to none */
list-style-position: outside !important;
list-style-image: none !important;
margin:0 !important;
max-height:none !important;
max-width:none !important;
min-height:0 !important;
min-width:0 !important;
opacity:1;
outline:invert none medium !important;
overflow:visible !important;
padding:0 !important;
position:static !important;
quotes: "" "" !important;
right:auto !important;
table-layout:auto !important;
text-align:inherit !important;
text-decoration:inherit !important;
text-indent:0 !important;
text-transform:none !important;
top:auto !important;
unicode-bidi:normal !important;
vertical-align:baseline !important;
visibility:inherit !important;
white-space:normal !important;
width:auto !important;
word-spacing:normal !important;
z-index:auto !important;
/* CSS3 */
/* Including all prefixes according to http://caniuse.com/ */
/* CSS Animations don't cascade, so don't require resetting */
-webkit-background-origin: padding-box !important;
background-origin: padding-box !important;
-webkit-background-clip: border-box !important;
background-clip: border-box !important;
-webkit-background-size: auto !important;
-moz-background-size: auto !important;
background-size: auto !important;
-webkit-border-image: none !important;
-moz-border-image: none !important;
-o-border-image: none !important;
border-image: none !important;
-webkit-border-radius:0 !important;
-moz-border-radius:0 !important;
border-radius: 0 !important;
-webkit-box-shadow: none !important;
box-shadow: none !important;
-webkit-box-sizing: content-box !important;
-moz-box-sizing: content-box !important;
box-sizing: content-box !important;
-webkit-column-count: auto !important;
-moz-column-count: auto !important;
column-count: auto !important;
-webkit-column-gap: normal !important;
-moz-column-gap: normal !important;
column-gap: normal !important;
-webkit-column-rule: medium none black !important;
-moz-column-rule: medium none black !important;
column-rule: medium none black !important;
-webkit-column-span: 1 !important;
-moz-column-span: 1 !important; /* doesn't exist yet but probably will */
column-span: 1 !important;
-webkit-column-width: auto !important;
-moz-column-width: auto !important;
column-width: auto !important;
font-feature-settings: normal !important;
overflow-x: visible !important;
overflow-y: visible !important;
-webkit-hyphens: manual !important;
-moz-hyphens: manual !important;
hyphens: manual !important;
-webkit-perspective: none !important;
-moz-perspective: none !important;
-ms-perspective: none !important;
-o-perspective: none !important;
perspective: none !important;
-webkit-perspective-origin: 50% 50% !important;
-moz-perspective-origin: 50% 50% !important;
-ms-perspective-origin: 50% 50% !important;
-o-perspective-origin: 50% 50% !important;
perspective-origin: 50% 50% !important;
-webkit-backface-visibility: visible !important;
-moz-backface-visibility: visible !important;
-ms-backface-visibility: visible !important;
-o-backface-visibility: visible !important;
backface-visibility: visible !important;
text-shadow: none !important;
-webkit-transition: all 0s ease 0s !important;
transition: all 0s ease 0s !important;
-webkit-transform: none !important;
-moz-transform: none !important;
-ms-transform: none !important;
-o-transform: none !important;
transform: none !important;
-webkit-transform-origin: 50% 50% !important;
-moz-transform-origin: 50% 50% !important;
-ms-transform-origin: 50% 50% !important;
-o-transform-origin: 50% 50% !important;
transform-origin: 50% 50% !important;
-webkit-transform-style: flat !important;
-moz-transform-style: flat !important;
-ms-transform-style: flat !important;
-o-transform-style: flat !important;
transform-style: flat !important;
word-break: normal !important;
}
/* == BLOCK-LEVEL == */
/* Actually, some of these should be inline-block and other values, but block works fine (TODO: rigorously verify this) */
/* HTML 4.01 */
.cleanslate, .cleanslate h3, .cleanslate h5, .cleanslate p, .cleanslate h1, .cleanslate dl, .cleanslate dt, .cleanslate h6, .cleanslate ol, .cleanslate form, .cleanslate option, .cleanslate pre, .cleanslate div, .cleanslate h2, .cleanslate caption, .cleanslate h4, .cleanslate ul, .cleanslate address, .cleanslate blockquote, .cleanslate dd, .cleanslate fieldset, .cleanslate hr,
/* HTML5 new elements */
.cleanslate article, .cleanslate dialog, .cleanslate figure, .cleanslate footer, .cleanslate header, .cleanslate hgroup, .cleanslate menu, .cleanslate nav, .cleanslate section, .cleanslate audio, .cleanslate video, .cleanslate address, .cleanslate blockquote, .cleanslate colgroup, .cleanslate main, .cleanslate progress, .cleanslate summary {
display:block !important;
}
.cleanslate h1, .cleanslate h2, .cleanslate h3, .cleanslate h4, .cleanslate h5, .cleanslate h6 {
font-weight: bold !important;
}
.cleanslate h1 {
font-size: 2em !important;
padding: .67em 0 !important;
}
.cleanslate h2 {
font-size: 1.5em !important;
padding: .83em 0 !important;
}
.cleanslate h3 {
font-size: 1.17em !important;
padding: .83em 0 !important;
}
.cleanslate h4 {
font-size: 1em !important;
}
.cleanslate h5 {
font-size: .83em !important;
}
.cleanslate p {
margin: 1em 0 !important;
}
.cleanslate table {
display: table !important;
}
.cleanslate thead {
display: table-header-group !important;
}
.cleanslate tbody {
display: table-row-group !important;
}
.cleanslate tfoot {
display: table-footer-group !important;
}
.cleanslate tr {
display: table-row !important;
}
.cleanslate th, .cleanslate td {
display: table-cell !important;
padding: 2px !important;
}
/* == SPECIFIC ELEMENTS == */
/* Some of these are browser defaults; some are just useful resets */
.cleanslate ol, .cleanslate ul {
margin: 1em 0 !important;
}
.cleanslate ul li, .cleanslate ul ul li, .cleanslate ul ul ul li, .cleanslate ol li, .cleanslate ol ol li, .cleanslate ol ol ol li, .cleanslate ul ol ol li, .cleanslate ul ul ol li, .cleanslate ol ul ul li, .cleanslate ol ol ul li {
list-style-position: inside !important;
margin-top: .08em !important;
}
.cleanslate ol ol, .cleanslate ol ol ol, .cleanslate ul ul, .cleanslate ul ul ul, .cleanslate ol ul, .cleanslate ol ul ul, .cleanslate ol ol ul, .cleanslate ul ol, .cleanslate ul ol ol, .cleanslate ul ul ol {
padding-left: 40px !important;
margin: 0 !important;
}
/* helper for general navigation */
.cleanslate nav ul, .cleanslate nav ol {
list-style-type:none !important;
}
.cleanslate ul, .cleanslate menu {
list-style-type:disc !important;
}
.cleanslate ol {
list-style-type:decimal !important;
}
.cleanslate ol ul, .cleanslate ul ul, .cleanslate menu ul, .cleanslate ol menu, .cleanslate ul menu, .cleanslate menu menu {
list-style-type:circle !important;
}
.cleanslate ol ol ul, .cleanslate ol ul ul, .cleanslate ol menu ul, .cleanslate ol ol menu, .cleanslate ol ul menu, .cleanslate ol menu menu, .cleanslate ul ol ul, .cleanslate ul ul ul, .cleanslate ul menu ul, .cleanslate ul ol menu, .cleanslate ul ul menu, .cleanslate ul menu menu, .cleanslate menu ol ul, .cleanslate menu ul ul, .cleanslate menu menu ul, .cleanslate menu ol menu, .cleanslate menu ul menu, .cleanslate menu menu menu {
list-style-type:square !important;
}
.cleanslate li {
display:list-item !important;
/* Fixes IE7 issue with positioning of nested bullets */
min-height:auto !important;
min-width:auto !important;
padding-left: 20px !important; /* replace -webkit-padding-start: 40px; */
}
.cleanslate strong {
font-weight:bold !important;
}
.cleanslate em {
font-style:italic !important;
}
.cleanslate kbd, .cleanslate samp, .cleanslate code {
font-family:monospace !important;
}
.cleanslate a {
color: blue !important;
text-decoration: underline !important;s
}
.cleanslate a:visited {
color: #529 !important;
}
.cleanslate a, .cleanslate a *, .cleanslate input[type=submit], .cleanslate input[type=radio], .cleanslate input[type=checkbox], .cleanslate select {
cursor:pointer !important;
}
.cleanslate button, .cleanslate input[type=submit] {
text-align: center !important;
padding: 2px 6px 3px !important;
border-radius: 4px !important;
text-decoration: none !important;
font-family: arial, helvetica, sans-serif !important;
font-size: small !important;
background: white !important;
-webkit-appearance: push-button !important;
color: buttontext !important;
border: 1px #a6a6a6 solid !important;
background: lightgrey !important; /* Old browsers */
background: rgb(255,255,255); /* Old browsers */
background: -moz-linear-gradient(top, rgba(255,255,255,1) 0%, rgba(221,221,221,1) 100%, rgba(209,209,209,1) 100%, rgba(221,221,221,1) 100%) !important; /* FF3.6+ */
background: -webkit-gradient(linear, left top, left bottom, color-stop(0%,rgba(255,255,255,1)), color-stop(100%,rgba(221,221,221,1)), color-stop(100%,rgba(209,209,209,1)), color-stop(100%,rgba(221,221,221,1))) !important; /* Chrome,Safari4+ */
background: -webkit-linear-gradient(top, rgba(255,255,255,1) 0%,rgba(221,221,221,1) 100%,rgba(209,209,209,1) 100%,rgba(221,221,221,1) 100%) !important; /* Chrome10+,Safari5.1+ */
background: -o-linear-gradient(top, rgba(255,255,255,1) 0%,rgba(221,221,221,1) 100%,rgba(209,209,209,1) 100%,rgba(221,221,221,1) 100%) !important; /* Opera 11.10+ */
background: -ms-linear-gradient(top, rgba(255,255,255,1) 0%,rgba(221,221,221,1) 100%,rgba(209,209,209,1) 100%,rgba(221,221,221,1) 100%) !important; /* IE10+ */
background: linear-gradient(to bottom, rgba(255,255,255,1) 0%,rgba(221,221,221,1) 100%,rgba(209,209,209,1) 100%,rgba(221,221,221,1) 100%) !important; /* W3C */
filter: progid:DXImageTransform.Microsoft.gradient( startColorstr='#ffffff', endColorstr='#dddddd',GradientType=0 ) !important; /* IE6-9 */
-webkit-box-shadow: 1px 1px 0px #eee !important;
-moz-box-shadow: 1px 1px 0px #eee !important;
-o-box-shadow: 1px 1px 0px #eee !important;
box-shadow: 1px 1px 0px #eee !important;
outline: initial !important;
}
.cleanslate button {
padding: 1px 6px 2px 6px !important;
margin-right: 5px !important;
}
.cleanslate input[type=hidden] {
display:none !important;
}
/* restore form defaults */
.cleanslate textarea {
-webkit-appearance: textarea !important;
background: white !important;
padding: 2px !important;
margin-left: 4px !important;
word-wrap: break-word !important;
white-space: pre-wrap !important;
font-size: 11px !important;
font-family: arial, helvetica, sans-serif !important;
line-height: 13px !important;
resize: both !important;
}
.cleanslate select, .cleanslate textarea, .cleanslate input {
border:1px solid #ccc !important;
}
.cleanslate select {
font-size: 11px !important;
font-family: helvetica, arial, sans-serif !important;
display: inline-block;
}
.cleanslate textarea:focus, .cleanslate input:focus {
outline: auto 5px -webkit-focus-ring-color !important;
outline: initial !important;
}
.cleanslate input[type=text] {
background: white !important;
padding: 1px !important;
font-family: initial !important;
font-size: small !important;
}
.cleanslate input[type=checkbox], .cleanslate input[type=radio] {
border: 1px #2b2b2b solid !important;
border-radius: 4px !important;
}
.cleanslate input[type=checkbox], .cleanslate input[type=radio] {
outline: intial !important;
}
.cleanslate input[type=radio] {
margin: 2px 2px 3px 2px !important;
}
.cleanslate input[type=submit]:active, .cleanslate button:active {
background: rgb(59,103,158) !important; /* Old browsers */
background: -moz-linear-gradient(top, rgba(59,103,158,1) 0%, rgba(43,136,217,1) 50%, rgba(32,124,202,1) 51%, rgba(125,185,232,1) 100%) !important; /* FF3.6+ */
background: -webkit-gradient(linear, left top, left bottom, color-stop(0%,rgba(59,103,158,1)), color-stop(50%,rgba(43,136,217,1)), color-stop(51%,rgba(32,124,202,1)), color-stop(100%,rgba(125,185,232,1))) !important; /* Chrome,Safari4+ */
background: -webkit-linear-gradient(top, rgba(59,103,158,1) 0%,rgba(43,136,217,1) 50%,rgba(32,124,202,1) 51%,rgba(125,185,232,1) 100%) !important; /* Chrome10+,Safari5.1+ */
background: -o-linear-gradient(top, rgba(59,103,158,1) 0%,rgba(43,136,217,1) 50%,rgba(32,124,202,1) 51%,rgba(125,185,232,1) 100%) !important; /* Opera 11.10+ */
background: -ms-linear-gradient(top, rgba(59,103,158,1) 0%,rgba(43,136,217,1) 50%,rgba(32,124,202,1) 51%,rgba(125,185,232,1) 100%) !important; /* IE10+ */
background: linear-gradient(to bottom, rgba(59,103,158,1) 0%,rgba(43,136,217,1) 50%,rgba(32,124,202,1) 51%,rgba(125,185,232,1) 100%) !important; /* W3C */
border-color: #5259b0 !important;
}
.cleanslate abbr[title], .cleanslate acronym[title], .cleanslate dfn[title] {
cursor:help !important;
border-bottom-width:1px !important;
border-bottom-style:dotted !important;
}
.cleanslate ins {
background-color:#ff9 !important;
color:black !important;
}
.cleanslate del {
text-decoration: line-through !important;
}
.cleanslate blockquote, .cleanslate q {
quotes:none !important; /* HTML5 */
}
.cleanslate blockquote:before, .cleanslate blockquote:after, .cleanslate q:before, .cleanslate q:after, .cleanslate li:before, .cleanslate li:after {
content:"" !important;
}
.cleanslate input, .cleanslate select {
vertical-align:middle !important;
}
.cleanslate table {
border-collapse:collapse !important;
border-spacing:0 !important;
}
.cleanslate hr {
display:block !important;
height:1px !important;
border:0 !important;
border-top:1px solid #ccc !important;
margin:1em 0 !important;
}
.cleanslate *[dir=rtl] {
direction: rtl !important;
}
.cleanslate mark {
background-color:#ff9 !important;
color:black !important;
font-style:italic !important;
font-weight:bold !important;
}
.cleanslate menu {
padding-left: 40px !important;
padding-top: 8px !important;
}
/* additional helpers */
.cleanslate [hidden],
.cleanslate template {
display: none !important;
}
.cleanslate abbr[title] {
border-bottom: 1px dotted !important;
}
.cleanslate sub, .cleanslate sup {
font-size: 75% !important;
line-height: 0 !important;
position: relative !important;
vertical-align: baseline !important;
}
.cleanslate sup {
top: -0.5em !important;
}
.cleanslate sub {
bottom: -0.25em !important;
}
.cleanslate img {
border: 0 !important;
}
.cleanslate figure {
margin: 0 !important;
}
.cleanslate textarea {
overflow: auto !important;
vertical-align: top !important;
}
/* == ROOT CONTAINER ELEMENT == */
/* This contains default values for child elements to inherit */
.cleanslate {
font-size: medium !important;
line-height: 1 !important;
direction:ltr !important;
text-align: left !important; /* for IE, Opera */
text-align: start !important; /* recommended W3C Spec */
font-family: "Times New Roman", Times, serif !important; /* Override this with whatever font-family is required */
color: black !important;
font-style:normal !important;
font-weight:normal !important;
text-decoration:none !important;
list-style-type:disc !important;
}

299
docs/flems_soubory/commandline_data/commandline.css
View File

@ -1,299 +0,0 @@
@import url("../themes/auto/auto.css");
body {
overflow: hidden;
margin: 0;
position: absolute;
/* CSS is pants. Move the bar down a tiny bit to cover up the gap. */
top: 1px;
width: 100%;
display: flex;
flex-direction: column;
}
#command-line-holder {
background: var(--tridactyl-cmdl-bg);
color: var(--tridactyl-cmdl-fg);
font-family: var(--tridactyl-cmdl-font-family);
font-size: 9pt;
/* reduce the padding added by the colon so that the command line shows up roughly where it used to be */
padding-left: 0.125ex;
}
input {
width: 97%;
font-family: var(--tridactyl-cmdl-font-family);
font-size: var(--tridactyl-cmdl-font-size);
line-height: var(--tridactyl-cmdl-line-height);
color: var(--tridactyl-cmdl-fg);
background: var(--tridactyl-cmdl-bg);
border: unset;
/* reduce the padding from the colon */
/* margin-left: -0.25ex; */
/* we currently have a border from the completions */
/* border-top: solid 1px lightgray; */
}
input:focus {
outline: none;
}
#tridactyl-colon::before {
content: ":";
}
/* COMPLETIONS */
#completions {
--option-height: var(--tridactyl-cmplt-option-height);
color: var(--tridactyl-cmplt-fg);
background: var(--tridactyl-cmplt-bg);
display: inline-block;
font-size: var(--tridactyl-cmplt-font-size);
font-family: var(--tridactyl-cmplt-font-family);
overflow: hidden;
width: 100%;
border-top: var(--tridactyl-cmplt-border-top);
}
/* Olie doesn't know how CSS inheritance works */
#completions > div {
max-height: calc(20 * var(--option-height));
min-height: calc(10 * var(--option-height));
}
#completions > div > table {
width: 100%;
font-size: 9pt;
border-spacing: 0;
table-layout: fixed;
}
#completions table tr td.prefix {
width: 3.2em;
padding-left: 0.5em;
text-align: center;
}
#completions table tr td.container,
#completions table tr td.icon,
#completions table tr td.privatewindow {
width: 1.5em;
}
#completions table tr td.tabcount {
width: 6em;
}
#completions table tr td.tgroup {
width: 10em;
padding-left: 0.5em;
text-align: right;
}
#completions table tr td.tgroup:empty {
display: none;
}
/* #completions table tr td:nth-of-type(3) { width: 5em; } */
#completions table tr td.content {
width: 50%;
}
/* Accroding to src/completions/TabHistory.ts formatTimeSpan,
* max-width should be 14 characters (14ex), 20ex for more tolorance. */
#completions table tr td.time {
width: 20ex;
text-align: right;
padding-right: 2ex;
}
#completions table tr {
white-space: nowrap;
overflow: hidden;
}
#completions table tr td {
overflow: hidden;
}
#completions img {
display: inline;
vertical-align: middle;
height: 1em;
width: 1em;
}
#completions .sectionHeader {
background: linear-gradient(
var(--tridactyl-header-first-bg),
var(--tridactyl-header-second-bg),
var(--tridactyl-header-third-bg)
);
font-size: var(--tridactyl-header-font-size);
font-weight: var(--tridactyl-header-font-weight);
border-bottom: var(--tridactyl-header-border-bottom);
padding-left: 0.5ex;
}
#completions .sectionHeader,
#completions .option {
height: var(--option-height);
line-height: var(--option-height);
}
.url {
text-decoration: var(--tridactyl-url-text-decoration);
}
.option:not(.focused) .url {
color: var(--tridactyl-url-fg);
background: var(--tridactyl-url-bg);
}
a.url:hover {
cursor: var(--tridactyl-url-cursor);
text-decoration: underline;
}
/* Hide the URLs if the screen is small */
@media all and (max-width: 500px) {
.url {
display: none;
}
}
.FindCompletionOption .match {
font-weight: bold;
}
.hidden {
display: none;
}
/* Pick the .url out especially because otherwise its link styles dominate. */
.focused,
.focused .url {
color: var(--tridactyl-of-fg);
background: var(--tridactyl-of-bg);
}
.option.incognito .privatewindow {
background-image: var(--tridactyl-private-window-icon-url);
}
/* Still completions, but container-related stuff */
.option .container {
mask-size: 1em;
mask-repeat: no-repeat;
mask-position: center;
}
.option .privatewindow {
background-size: 1em;
background-repeat: no-repeat;
background-position: center;
}
.option.container_blue .container {
background-color: var(--tridactyl-container-color-blue);
}
.option.container_turquoise .container {
background-color: var(--tridactyl-container-color-turquoise);
}
.option.container_green .container {
background-color: var(--tridactyl-container-color-green);
}
.option.container_yellow .container {
background-color: var(--tridactyl-container-color-yellow);
}
.option.container_orange .container {
background-color: var(--tridactyl-container-color-orange);
}
.option.container_red .container {
background-color: var(--tridactyl-container-color-red);
}
.option.container_pink .container {
background-color: var(--tridactyl-container-color-pink);
}
.option.container_purple .container {
background-color: var(--tridactyl-container-color-purple);
}
.option.container_fingerprint .container {
mask-image: var(--tridactyl-container-fingerprint-url);
}
.option.container_briefcase .container {
mask-image: var(--tridactyl-container-briefcase-url);
}
.option.container_dollar .container {
mask-image: var(--tridactyl-container-dollar-url);
}
.option.container_cart .container {
mask-image: var(--tridactyl-container-cart-url);
}
.option.container_circle .container {
mask-image: var(--tridactyl-container-circle-url);
}
.option.container_gift .container {
mask-image: var(--tridactyl-container-gift-url);
}
.option.container_vacation .container {
mask-image: var(--tridactyl-container-vacation-url);
}
.option.container_food .container {
mask-image: var(--tridactyl-container-food-url);
}
.option.container_fruit .container {
mask-image: var(--tridactyl-container-fruit-url);
}
.option.container_pet .container {
mask-image: var(--tridactyl-container-pet-url);
}
.option.container_tree .container {
mask-image: var(--tridactyl-container-tree-url);
}
.option.container_chill .container {
mask-image: var(--tridactyl-container-chill-url);
}
.ExcmdCompletionOption td.excmd {
padding-left: 0.5em;
width: 20%;
}
.ExcmdCompletionOption td.documentation {
width: 100%;
}
.SettingsCompletionOption td.title {
padding-left: 0.5em;
}
#completions .SettingsCompletionOption td.title,
#completions .SettingsCompletionOption td.content,
#completions .SettingsCompletionOption td.type {
width: 15%;
text-overflow: ellipsis;
}
#completions .TabGroupCompletionOption td.title {
width: 15%;
}
#completions .TabGroupCompletionOption td.content {
width: auto;
}
.HelpCompletionOption td.name {
width: 25%;
}
#completions .SessionCompletionOption td.type {
width: 1ch !important;
padding: 0px 3pt;
}
#completions .SessionCompletionOption td.time {
width: 5ch !important;
padding: 0px 3pt;
text-align: right;
}
#completions .WindowCompletionOption td.id {
width: 6ch !important;
text-align: right;
padding: 0px 8pt;
}

14035
docs/flems_soubory/commandline_data/commandline_frame.js
View File

File diff suppressed because it is too large Load Diff

16971
docs/flems_soubory/page-script.js
View File

File diff suppressed because it is too large Load Diff

53
docs/global.css → docs/global.css.js
View File

@ -1,3 +1,5 @@
import { styles } from "./ssr.js";
styles.css`
@import url(https://cdn.simplecss.org/simple.min.css);
:root{
--body-max-width: 45rem;
@ -119,53 +121,4 @@ main > *{
font-size: .9rem;
font-style: italic;
}
.prevNext{
display: grid;
grid-template-columns: 1fr 2fr 1fr;
margin-top: 1rem;
border-top: 1px solid var(--border);
}
.prevNext [rel=prev]{
grid-column: 1;
}
.prevNext [rel=next]{
grid-column: 3;
text-align: right;
}
.code{
--shiki-color-text: #e9eded;
--shiki-color-background: #212121;
--shiki-token-constant: #82b1ff;
--shiki-token-string: #c3e88d;
--shiki-token-comment: #546e7a;
--shiki-token-keyword: #c792ea;
--shiki-token-parameter: #AA0000;
--shiki-token-function: #80cbae;
--shiki-token-string-expression: #c3e88d;
--shiki-token-punctuation: var(--code);
--shiki-token-link: #EE0000;
white-space: pre;
tab-size: 2; /* TODO: allow custom tab size?! */
overflow: scroll;
}
.code[data-js=todo]{
border: 1px solid var(--border);
border-radius: var(--standard-border-radius);
margin-bottom: 1rem;
margin-top: 18.4px; /* to fix shift when → dataJS=done */
padding: 1rem 1.4rem;
}
.example{
grid-column: full-main;
width: 100%;
max-width: calc(9/5 * var(--body-max-width));
height: calc(3/5 * var(--body-max-width));
margin-inline: auto;
}
.CodeMirror, .CodeMirror-gutters {
background: #212121 !important;
border: 1px solid white;
}
.notice h3{
margin-top: 0;
}
`;

22
docs/index.html
View File

File diff suppressed because one or more lines are too long

62
docs/index.html.js Normal file
View File

@ -0,0 +1,62 @@
import { t, T } from "./utils/index.js";
export const info= {
href: "./",
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", 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`),
);
}

11
docs/jsconfig.json Normal file
View File

@ -0,0 +1,11 @@
{
"include": [ "*.js", "**/*.js", "../node_modules/nodejsscript/index.d.ts" ],
"compilerOptions": {
"module": "NodeNext",
"noEmit": true,
"allowJs": true,
"checkJs": true,
"downlevelIteration": true,
"maxNodeModuleJsDepth": 1
}
}

102
docs/layout/head.html.js Normal file
View File

@ -0,0 +1,102 @@
import { el, elNS } from "deka-dom-el";
import { pages } from "../ssr.js";
/**
* @param {object} def
* @param {import("../types.d.ts").Info} def.info
* @param {import("../types.d.ts").Pkg} def.pkg Package information.
* */
export function header({ info: { href, title, description }, pkg }){
title= `\`${pkg.name}\` — ${title}`;
document.head.append(
head({ title, description, pkg })
);
return el().append(
el("header").append(
el("h1", title),
el("p", description)
),
el("nav").append(
el("a", { href: pkg.homepage }).append(
el(iconGitHub),
"GitHub"
),
...pages.map((p, i)=> el("a", {
href: p.href==="index" ? "./" : p.href,
textContent: (i+1) + ". " + p.title,
title: p.description,
classList: { current: p.href===href }
}))
)
);
}
function head({ title, description, pkg }){
return el().append(
el("meta", { name: "viewport", content: "width=device-width, initial-scale=1" }),
el("meta", { name: "description", content: description }),
el("title", title),
el(metaAuthor),
el(metaTwitter, pkg),
el(metaFacebook, pkg),
);
}
function metaAuthor(){
return el().append(
el("meta", { name: "author", content: "Jan Andrle" }),
el("link", { type: "text/plain", rel: "author", href: "https://jaandrle.github.io/humans.txt" }),
el("meta", { name: "generator", content: "deka-dom-el" }),
);
}
function metaTwitter({ name, description, homepage }){
return el().append(
el("meta", { name: "twitter:card", content: "summary_large_image" }),
//el("meta", { name: "twitter:domain", content: "" }),
el("meta", { name: "twitter:url", content: homepage }),
el("meta", { name: "twitter:title", content: name }),
el("meta", { name: "twitter:description", content: description }),
//el("meta", { name: "twitter:image", content: "" }),
el("meta", { name: "twitter:creator", content: "@jaandrle" }),
);
}
function metaFacebook({ name, description, homepage }){
return el().append(
el("meta", { name: "og:url", content: homepage }),
el("meta", { name: "og:title", content: name }),
el("meta", { name: "og:description", content: description }),
//el("meta", { name: "og:image", content: "" }),
el("meta", { name: "og:creator", content: "@jaandrle" }),
);
}
function iconGitHub(){
const el= elNS("http://www.w3.org/2000/svg");
return el("svg", { className: "icon", viewBox: "0 0 32 32" }).append(
el("path", { d: [ //see https://svg-path-visualizer.netlify.app/#M16%200.395c-8.836%200-16%207.163-16%2016%200%207.069%204.585%2013.067%2010.942%2015.182%200.8%200.148%201.094-0.347%201.094-0.77%200-0.381-0.015-1.642-0.022-2.979-4.452%200.968-5.391-1.888-5.391-1.888-0.728-1.849-1.776-2.341-1.776-2.341-1.452-0.993%200.11-0.973%200.11-0.973%201.606%200.113%202.452%201.649%202.452%201.649%201.427%202.446%203.743%201.739%204.656%201.33%200.143-1.034%200.558-1.74%201.016-2.14-3.554-0.404-7.29-1.777-7.29-7.907%200-1.747%200.625-3.174%201.649-4.295-0.166-0.403-0.714-2.030%200.155-4.234%200%200%201.344-0.43%204.401%201.64%201.276-0.355%202.645-0.532%204.005-0.539%201.359%200.006%202.729%200.184%204.008%200.539%203.054-2.070%204.395-1.64%204.395-1.64%200.871%202.204%200.323%203.831%200.157%204.234%201.026%201.12%201.647%202.548%201.647%204.295%200%206.145-3.743%207.498-7.306%207.895%200.574%200.497%201.085%201.47%201.085%202.963%200%202.141-0.019%203.864-0.019%204.391%200%200.426%200.288%200.925%201.099%200.768%206.354-2.118%2010.933-8.113%2010.933-15.18%200-8.837-7.164-16-16-16z
"M 16,0.395",
"c -8.836,0 -16,7.163 -16,16",
"c 0,7.069 4.585,13.067 10.942,15.182",
"c 0.8,0.148 1.094,-0.347 1.094,-0.77",
"c 0,-0.381 -0.015,-1.642 -0.022,-2.979",
"c -4.452,0.968 -5.391,-1.888 -5.391,-1.888",
"c -0.728,-1.849 -1.776,-2.341 -1.776,-2.341",
"c -1.452,-0.993 0.11,-0.973 0.11,-0.973",
"c 1.606,0.113 2.452,1.649 2.452,1.649",
"c 1.427,2.446 3.743,1.739 4.656,1.33",
"c 0.143,-1.034 0.558,-1.74 1.016,-2.14",
"c -3.554,-0.404 -7.29,-1.777 -7.29,-7.907",
"c 0,-1.747 0.625,-3.174 1.649,-4.295",
"c -0.166,-0.403 -0.714,-2.03 0.155,-4.234",
"c 0,0 1.344,-0.43 4.401,1.64",
"c 1.276,-0.355 2.645,-0.532 4.005,-0.539",
"c 1.359,0.006 2.729,0.184 4.008,0.539",
"c 3.054,-2.07 4.395,-1.64 4.395,-1.64",
"c 0.871,2.204 0.323,3.831 0.157,4.234",
"c 1.026,1.12 1.647,2.548 1.647,4.295",
"c 0,6.145 -3.743,7.498 -7.306,7.895",
"c 0.574,0.497 1.085,1.47 1.085,2.963",
"c 0,2.141 -0.019,3.864 -0.019,4.391",
"c 0,0.426 0.288,0.925 1.099,0.768",
"c 6.354,-2.118 10.933,-8.113 10.933,-15.18",
"c 0,-8.837 -7.164,-16 -16,-16",
"Z"
].join("") })
);
}

16
docs/layout/simplePage.html.js Normal file
View File

@ -0,0 +1,16 @@
import "../global.css.js";
import { el, simulateSlots } from "deka-dom-el";
import { header } from "./head.html.js";
import { prevNext } from "../components/pageUtils.html.js";
/** @param {Pick<import("../types.d.ts").PageAttrs, "pkg" | "info">} attrs */
export function simplePage({ pkg, info }){
return simulateSlots(el().append(
el(header, { info, pkg }),
el("main").append(
el("slot"),
el(prevNext, info)
)
));
}

147
docs/p02-elements.html
View File

File diff suppressed because one or more lines are too long

155
docs/p02-elements.html.js Normal file
View File

@ -0,0 +1,155 @@
import { T, t } from "./utils/index.js";
export const info= {
title: t`Elements`,
description: t`Basic concepts of elements modifications and creations.`,
};
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/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", 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, 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(...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(...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(...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, 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(...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, 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(...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, 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)
);
}

94
docs/p03-events.html
View File

File diff suppressed because one or more lines are too long

149
docs/p03-events.html.js Normal file
View File

@ -0,0 +1,149 @@
import { T, t } from "./utils/index.js";
export const info= {
title: t`Events and Addons`,
description: t`Using not only events in UI declaratively.`,
};
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/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", 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, 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(...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", 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(...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, 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(...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(...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(...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(...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, 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)
);
}

150
docs/p04-observables.html
View File

File diff suppressed because one or more lines are too long

150
docs/p04-signals.html
View File

File diff suppressed because one or more lines are too long

128
docs/p04-signals.html.js Normal file
View File

@ -0,0 +1,128 @@
import { T, t } from "./utils/index.js";
export const info= {
title: t`Signals and reactivity`,
description: t`Handling reactivity in UI via signals.`,
};
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/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", 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, 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(...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, 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", 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(...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, 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", 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(...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)
);
}

183
docs/p05-scopes.html
View File

File diff suppressed because one or more lines are too long

87
docs/p05-scopes.html.js Normal file
View File

@ -0,0 +1,87 @@
import { T, t } from "./utils/index.js";
export const info= {
title: t`Scopes and components`,
description: t`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: 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", 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(...T`The library therefore use ${el("em", t`scopes`)} to provide these functionalities.`),
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(...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(...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, 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(...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(...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)
);
}

242
docs/p06-customElement.html
View File

File diff suppressed because one or more lines are too long

144
docs/p06-customElement.html.js Normal file
View File

@ -0,0 +1,144 @@
import { T, t } from "./utils/index.js";
export const info= {
title: t`Web Components`,
description: t`Using custom elements in combinantion with DDE`,
};
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/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 on mdn */
mdn_shadow_dom_slot: {
title: t`MDN documentation page for <slot>`,
href: "https://developer.mozilla.org/en-US/docs/Web/HTML/Element/slot",
},
/** 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", 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", t`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, t`Custom Elements Introduction`),
el("p").append(...T`
Web Components, specifically Custom Elements, are a set of web platform APIs that allow you to create
new HTML tags with custom functionality encapsulated within them. This allows for the creation of reusable
components that can be used across web applications.
`),
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", t`Using Custom Elements`), t` 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(...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: "${t`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`
Shadow DOM is a web platform feature that allows for the encapsulation of a component’s internal DOM tree
from the rest of the document. This means that styles and scripts applied to the document will not affect
the component’s internal DOM, and vice versa.
`),
el(example, { src: fileURL("./components/examples/customElement/shadowRoot.js"), page_id }),
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 })}.
`),
el("p").append(...T`
Besides the encapsulation, the Shadow DOM allows for using the ${el("a", references.mdn_shadow_dom_slot).append(
el("strong", t`<slot>`), t` element(s)`)}. You can simulate this feature using ${el("code", "simulateSlots")}:
`),
el(example, { src: fileURL("./components/examples/customElement/simulateSlots.js"), page_id }),
el("p").append(...T`
To sum up:
`),
el("ul").append(
el("li").append(...T`
The use of shadow DOM to encapsulate the internal structure of the custom element, which affects how
the custom element can be styled and modified using JavaScript and CSS.
`),
el("li").append(...T`
The ability to access and modify the internal structure of the custom element using JavaScript, which
is affected by the use of shadow DOM and the mode of the shadow DOM.
`),
el("li").append(...T`
The use of slots to allow for the insertion of content from the parent document into the custom
element, which is affected by the use of shadow DOM and the mode of the shadow DOM.
`),
),
el(mnemonic)
);
}

62
docs/ssr.js Normal file
View File

@ -0,0 +1,62 @@
export { t } from "./utils/index.js";
export const path_target= {
root: "dist/docs/",
css: "dist/docs/"
};
/**
* This variable will be filled with the list of pages during the build process (see `bs/docs.js`).
* @type {import("./types.d.ts").Info[]}
* */
export let pages= [];
/**
* @typedef registerClientFile
* @type {function}
* @param {URL} url
* @param {HTMLScriptElement|HTMLLinkElement} [element_head]
* */
export function registerClientFile(url, element_head){
const file_name= url.pathname.split("/").pop();
s.cat(url).to(path_target.root+file_name);
if(!element_head) return;
element_head[element_head instanceof HTMLScriptElement ? "src" : "href"]= file_name;
document.head.append(
element_head
);
}
const events= {
oneachrender: new Set(),
onssrend: new Set()
};
/** @param {keyof typeof events} name @param {function} listener */
export function addEventListener(name, listener){
events[name].add(listener);
}
/** @param {keyof typeof events} name @param {any} a */
export function dispatchEvent(name, a){
const ls= events[name];
ls.forEach(l=> l(a));
if(name!=="oneachrender")
ls.clear();
}
export const styles= {
element: null,
name: "global.css",
get location(){ return path_target.css.replace(path_target.root, "")+this.name; },
content: "",
/** @param {Parameters<typeof String.raw>} a */
css(...a){
let c= css(...a);
if(this.content) this.content+= "\n";
this.content+= c;
return this;
}
};
addEventListener("oneachrender", ()=> document.head.append(
Object.assign(document.createElement("link"), { rel: "stylesheet", href: styles.location })
));
/** @type {typeof String.raw} */
function css(...a){ return String.raw(...a).trim(); }

29
docs/types.d.ts vendored Normal file
View File

@ -0,0 +1,29 @@
/** See `package.json` */
export type Pkg= Record<string, string>
export type Info= {
id: string,
href: string,
title: string,
description: string,
}
export type Pages=Info[];
export type PathTarget= {
root: string,
css: string
}
export type registerClientFile= import("../bs/docs.js").registerClientFile;
export type PageAttrs= {
pkg: Pkg,
info: Info,
pages: Pages,
path_target: PathTarget,
registerClientFile: registerClientFile
}
import type { CustomHTMLTestElement } from "../examples/components/webComponent.js";
declare global{
interface ddePublicElementTagNameMap{
["custom-test"]: CustomHTMLTestElement;
}
function test(): ddeHTMLParagraphElement
}

52
docs/utils/index.js Normal file
View File

@ -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]);
}
}