From 398cc38c88aed258c5c54171a8f5a1875cdfcceb Mon Sep 17 00:00:00 2001 From: Jan Andrle Date: Sat, 18 Nov 2023 14:23:18 +0100 Subject: [PATCH] :pencil2: docs (:hammer: examples, :construction: events) --- docs/elements.html | 16 +++--- docs/events.html | 49 ++++++++++++++++++- docs/index.html | 5 +- docs_src/components/example.html.js | 2 +- .../examples/{ => elements}/dekaAppend.js | 2 +- .../examples/{ => elements}/dekaAssign.js | 2 +- .../{ => elements}/dekaBasicComponent.js | 2 +- .../{ => elements}/dekaCreateElement.js | 2 +- .../examples/{ => elements}/dekaElNS.js | 2 +- .../examples/{ => elements}/nativeAppend.js | 0 .../{ => elements}/nativeCreateElement.js | 0 .../components/examples/events/abortSignal.js | 13 +++++ .../components/examples/events/compare.js | 10 ++++ .../examples/events/templateWithListeners.js | 24 +++++++++ docs_src/components/examples/helloWorld.js | 3 +- docs_src/elements.html.js | 14 +++--- docs_src/events.html.js | 42 +++++++++++++++- docs_src/index.html.js | 2 +- 18 files changed, 163 insertions(+), 27 deletions(-) rename docs_src/components/examples/{ => elements}/dekaAppend.js (90%) rename docs_src/components/examples/{ => elements}/dekaAssign.js (86%) rename docs_src/components/examples/{ => elements}/dekaBasicComponent.js (88%) rename docs_src/components/examples/{ => elements}/dekaCreateElement.js (80%) rename docs_src/components/examples/{ => elements}/dekaElNS.js (88%) rename docs_src/components/examples/{ => elements}/nativeAppend.js (100%) rename docs_src/components/examples/{ => elements}/nativeCreateElement.js (100%) create mode 100644 docs_src/components/examples/events/abortSignal.js create mode 100644 docs_src/components/examples/events/compare.js create mode 100644 docs_src/components/examples/events/templateWithListeners.js diff --git a/docs/elements.html b/docs/elements.html index b9f34d2..71571c8 100644 --- a/docs/elements.html +++ b/docs/elements.html @@ -1,4 +1,4 @@ -`deka-dom-el` — Elements

`deka-dom-el` — Elements

Basic concepts of elements modifications and creations.

Native JavaScript DOM elements creations

Let’s go through all patterns we would like to use and what needs to be improved for better experience.

Creating element(s) (with custom attributes)

You can create a native DOM element by using the document.createElement(). It is also possible to provide a some attribute(s) declaratively using Object.assign(). More precisely, this way you can sets some IDL also known as a JavaScript property.

document.body.append( +`deka-dom-el` — Elements

`deka-dom-el` — Elements

Basic concepts of elements modifications and creations.

Native JavaScript DOM elements creations

Let’s go through all patterns we would like to use and what needs to be improved for better experience.

Creating element(s) (with custom attributes)

You can create a native DOM element by using the document.createElement(). It is also possible to provide a some attribute(s) declaratively using Object.assign(). More precisely, this way you can sets some IDL also known as a JavaScript property.

document.body.append( document.createElement("div") ); console.log( @@ -12,7 +12,7 @@ document.body.append( { textContent: "Element’s text content.", style: "color: coral;" } ) ); -

To make this easier, you can use the el function. Internally in basic examples, it is wrapper around assign(document.createElement(…), { … }).

import { el, assign } from "https://cdn.jsdelivr.net/gh/jaandrle/deka-dom-el/dist/esm-with-signals.js"; +

To make this easier, you can use the el function. Internally in basic examples, it is wrapper around assign(document.createElement(…), { … }).

import { el, assign } from "https://cdn.jsdelivr.net/gh/jaandrle/deka-dom-el/dist/esm-with-signals.js"; const color= "lightcoral"; document.body.append( el("p", { textContent: "Hello (first time)", style: { color } }) @@ -23,7 +23,7 @@ document.body.append( { textContent: "Hello (second time)", style: { color } } ) ); -

The assign function provides improved behaviour of Object.assign(). You can declaratively sets any IDL and attribute of the given element. Function prefers IDL and fallback to the element.setAttribute if there is no writable property in the element prototype.

You can study all JavaScript elements interfaces to the corresponding HTML elements. All HTML elements inherits from HTMLElement. To see all available IDLs for example for paragraphs, see HTMLParagraphElement. Moreover, the assign provides a way to sets declaratively some convenient properties:

  • It is possible to sets data-*/aria-* attributes using object notation.
  • In opposite, it is also possible to sets data-*/aria-* attribute using camelCase notation.
  • You can use string or object as a value for style property.
  • className (IDL – preffered)/class are ways to add CSS class to the element. You can use string (similarly to class="…" syntax in HTML) or array of strings. This is handy to concat conditional classes.
  • Use classList to toggle specific classes. This will be handy later when the reactivity via signals is beeing introduced.
  • The assign also accepts the 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. For example, natievly the element’s id is removed by setting the IDL to an empty string.

For processing, the assign internally uses assignAttribute and classListDeclarative.

import { assignAttribute, classListDeclarative } from "https://cdn.jsdelivr.net/gh/jaandrle/deka-dom-el/dist/esm-with-signals.js"; +

The assign function provides improved behaviour of Object.assign(). You can declaratively sets any IDL and attribute of the given element. Function prefers IDL and fallback to the element.setAttribute if there is no writable property in the element prototype.

You can study all JavaScript elements interfaces to the corresponding HTML elements. All HTML elements inherits from HTMLElement. To see all available IDLs for example for paragraphs, see HTMLParagraphElement. Moreover, the assign provides a way to sets declaratively some convenient properties:

  • It is possible to sets data-*/aria-* attributes using object notation.
  • In opposite, it is also possible to sets data-*/aria-* attribute using camelCase notation.
  • You can use string or object as a value for style property.
  • className (IDL – preffered)/class are ways to add CSS class to the element. You can use string (similarly to class="…" syntax in HTML) or array of strings. This is handy to concat conditional classes.
  • Use classList to toggle specific classes. This will be handy later when the reactivity via signals is beeing introduced.
  • The assign also accepts the 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. For example, natievly the element’s id is removed by setting the IDL to an empty string.

For processing, the assign internally uses assignAttribute and classListDeclarative.

import { assignAttribute, classListDeclarative } from "https://cdn.jsdelivr.net/gh/jaandrle/deka-dom-el/dist/esm-with-signals.js"; const paragraph= document.createElement("p"); assignAttribute(paragraph, "textContent", "Hello, world!"); @@ -48,7 +48,7 @@ console.log(paragraph.outerHTML); document.body.append( paragraph ); -

Native JavaScript templating

By default, the native JS has no good way to define HTML template using DOM API:

document.body.append( +

Native JavaScript templating

By default, the native JS has no good way to define HTML template using DOM API:

document.body.append( document.createElement("div"), document.createElement("span"), document.createElement("main") @@ -59,7 +59,7 @@ const template= document.createElement("main").append( document.createElement("span"), ); console.log(typeof template==="undefined"); -

This library therefore overwrites the append method of created elements to always return parent element.

import { el } from "https://cdn.jsdelivr.net/gh/jaandrle/deka-dom-el/dist/esm-with-signals.js"; +

This library therefore overwrites the append method of created elements to always return parent element.

import { el } from "https://cdn.jsdelivr.net/gh/jaandrle/deka-dom-el/dist/esm-with-signals.js"; document.head.append( el("style").append( "tr, td{ border: 1px solid red; padding: 1em; }", @@ -83,7 +83,7 @@ document.body.append( ) ) ); -

Basic (state-less) components

You can use functions for encapsulation (repeating) logic. The el accepts function as first argument. In that case, the function should return dom elements and the second argument for el is argument for given element.

import { el } from "https://cdn.jsdelivr.net/gh/jaandrle/deka-dom-el/dist/esm-with-signals.js"; +

Basic (state-less) components

You can use functions for encapsulation (repeating) logic. The el accepts function as first argument. In that case, the function should return dom elements and the second argument for el is argument for given element.

import { el } from "https://cdn.jsdelivr.net/gh/jaandrle/deka-dom-el/dist/esm-with-signals.js"; document.head.append( el("style").append( ".class1{ font-weight: bold; }", @@ -100,7 +100,7 @@ function component({ className, textContent }){ el("p", textContent) ); } -

As you can see, in case of state-less/basic components there is no difference between calling component function directly or using el function.

It is nice to use similar naming convention as native DOM API. This allows us to use the destructuring assignment syntax and keep track of the native API (things are best remembered through regular use).

Creating non-HTML elements

Similarly to the native DOM API (document.createElementNS) for non-HTML elements we need to tell JavaScript which kind of the element to create. We can use the elNS function:

import { elNS, assign } from "https://cdn.jsdelivr.net/gh/jaandrle/deka-dom-el/dist/esm-with-signals.js"; +

As you can see, in case of state-less/basic components there is no difference between calling component function directly or using el function.

It is nice to use similar naming convention as native DOM API. This allows us to use the destructuring assignment syntax and keep track of the native API (things are best remembered through regular use).

Creating non-HTML elements

Similarly to the native DOM API (document.createElementNS) for non-HTML elements we need to tell JavaScript which kind of the element to create. We can use the elNS function:

import { elNS, assign } from "https://cdn.jsdelivr.net/gh/jaandrle/deka-dom-el/dist/esm-with-signals.js"; const elSVG= elNS("http://www.w3.org/2000/svg"); const elMath= elNS("http://www.w3.org/1998/Math/MathML"); document.body.append( @@ -111,4 +111,4 @@ document.body.append( console.log( document.body.innerHTML.includes("<svg></svg><math></math>") ) -
\ No newline at end of file +
\ No newline at end of file diff --git a/docs/events.html b/docs/events.html index 1a4343f..cad88bb 100644 --- a/docs/events.html +++ b/docs/events.html @@ -1 +1,48 @@ -`deka-dom-el` — Events and Modifiers

`deka-dom-el` — Events and Modifiers

Using not only events in UI declaratively.

Listenning to the native DOM events and other Modifiers

We quickly introduce helper to listening to the native DOM events. And library syntax/pattern so-called Modifier to incorporate not only this in UI templates declaratively.

Add events listeners

\ No newline at end of file +`deka-dom-el` — Events and Modifiers

`deka-dom-el` — Events and Modifiers

Using not only events in UI declaratively.

Listenning to the native DOM events and other Modifiers

We quickly introduce helper to listening to the native DOM events. And library syntax/pattern so-called Modifier to incorporate not only this in UI templates declaratively.

Events and listenners

In JavaScript you can listen to the native DOM events of the given element by using element.addEventListener(type, listener, options). The library provides an alternative (on) accepting the differen order of the arguments:

import { el, on } from "https://cdn.jsdelivr.net/gh/jaandrle/deka-dom-el/dist/esm-with-signals.js"; +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 +); +

…this is actually one of the two differences. The another one is thaton accepts only object as the options (but it is still optional).

The other difference is that there is no off function. You can remove listener declaratively using AbortSignal:

import { el, on } from "https://cdn.jsdelivr.net/gh/jaandrle/deka-dom-el/dist/esm-with-signals.js"; +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() }) +); +

Modifiers

From practical point of view, Modifiers are just functions that accept any html element as their first parameter. You can see that the on(…) fullfills this requirement.

You can use Modifiers as ≥3rd argument of el function. This way is possible to extends you templates by additional (3rd party) functionalities. But for now mainly, you can add events listeners:

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

As the example shows, you can also provide types in JSDoc+TypeScript by using global type ddeElementModifier. Also notice, you can use Modifiers to get element reference.

Life cycle events

Modifiers are called immediately when the element is created, event it is not connected to live DOM yet.

\ No newline at end of file diff --git a/docs/index.html b/docs/index.html index db41075..ce62432 100644 --- a/docs/index.html +++ b/docs/index.html @@ -1,4 +1,5 @@ -`deka-dom-el` — Introduction

`deka-dom-el` — Introduction

Introducing a library.

The library tries to provide pure JavaScript tool(s) to create reactive interfaces.

We start with creating and modifying a static elemnets and end up with UI templates. From document.createElement to el. Then we go through the native events system and the way to include it declaratively in UI templates. From element.addEventListener to on.

Next step is providing interactivity not only for our UI templates. We introduce signals (S) and how them incorporate to UI templates.

Now we will clarify how the signals are incorporated into our templates with regard to application performance. This is not the only reason the library uses scopes. We will look at how they work in components represented in JavaScript by functions.

import { el, S } from "https://cdn.jsdelivr.net/gh/jaandrle/deka-dom-el/dist/esm-with-signals.js"; +`deka-dom-el` — Introduction

`deka-dom-el` — Introduction

Introducing a library.

The library tries to provide pure JavaScript tool(s) to create reactive interfaces.

We start with creating and modifying a static elements and end up with UI templates. From document.createElement to el. Then we go through the native events system and the way to include it declaratively in UI templates. From element.addEventListener to on.

Next step is providing interactivity not only for our UI templates. We introduce signals (S) and how them incorporate to UI templates.

Now we will clarify how the signals are incorporated into our templates with regard to application performance. This is not the only reason the library uses scopes. We will look at how they work in components represented in JavaScript by functions.

import { el } from "https://cdn.jsdelivr.net/gh/jaandrle/deka-dom-el/dist/esm-with-signals.js"; +import { S } from "https://cdn.jsdelivr.net/gh/jaandrle/deka-dom-el/dist/esm-with-signals.js"; const clicks= S(0); document.body.append( el().append( @@ -12,4 +13,4 @@ document.body.append( }) ) ); -
\ No newline at end of file +
\ No newline at end of file diff --git a/docs_src/components/example.html.js b/docs_src/components/example.html.js index 71e7bd5..56305ad 100644 --- a/docs_src/components/example.html.js +++ b/docs_src/components/example.html.js @@ -24,7 +24,7 @@ import { code } from "./code.html.js"; export function example({ src, language= "js", page_id }){ registerClientPart(page_id); const content= s.cat(src).toString() - .replaceAll(' from "../../../index-with-signals.js";', ' from "https://cdn.jsdelivr.net/gh/jaandrle/deka-dom-el/dist/esm-with-signals.js";'); + .replaceAll(/ from "deka-dom-el(\/signals)?";/g, ' from "https://cdn.jsdelivr.net/gh/jaandrle/deka-dom-el/dist/esm-with-signals.js";'); const id= "code-"+Math.random().toString(36).slice(2, 7); return el().append( el(code, { id, content, language, className: example.name }), diff --git a/docs_src/components/examples/dekaAppend.js b/docs_src/components/examples/elements/dekaAppend.js similarity index 90% rename from docs_src/components/examples/dekaAppend.js rename to docs_src/components/examples/elements/dekaAppend.js index 967242e..7786acf 100644 --- a/docs_src/components/examples/dekaAppend.js +++ b/docs_src/components/examples/elements/dekaAppend.js @@ -1,4 +1,4 @@ -import { el } from "../../../index-with-signals.js"; +import { el } from "deka-dom-el"; document.head.append( el("style").append( "tr, td{ border: 1px solid red; padding: 1em; }", diff --git a/docs_src/components/examples/dekaAssign.js b/docs_src/components/examples/elements/dekaAssign.js similarity index 86% rename from docs_src/components/examples/dekaAssign.js rename to docs_src/components/examples/elements/dekaAssign.js index a9896c2..2477732 100644 --- a/docs_src/components/examples/dekaAssign.js +++ b/docs_src/components/examples/elements/dekaAssign.js @@ -1,4 +1,4 @@ -import { assignAttribute, classListDeclarative } from "../../../index-with-signals.js"; +import { assignAttribute, classListDeclarative } from "deka-dom-el"; const paragraph= document.createElement("p"); assignAttribute(paragraph, "textContent", "Hello, world!"); diff --git a/docs_src/components/examples/dekaBasicComponent.js b/docs_src/components/examples/elements/dekaBasicComponent.js similarity index 88% rename from docs_src/components/examples/dekaBasicComponent.js rename to docs_src/components/examples/elements/dekaBasicComponent.js index 7e742fa..50870c1 100644 --- a/docs_src/components/examples/dekaBasicComponent.js +++ b/docs_src/components/examples/elements/dekaBasicComponent.js @@ -1,4 +1,4 @@ -import { el } from "../../../index-with-signals.js"; +import { el } from "deka-dom-el"; document.head.append( el("style").append( ".class1{ font-weight: bold; }", diff --git a/docs_src/components/examples/dekaCreateElement.js b/docs_src/components/examples/elements/dekaCreateElement.js similarity index 80% rename from docs_src/components/examples/dekaCreateElement.js rename to docs_src/components/examples/elements/dekaCreateElement.js index 8b8d584..f46d7b9 100644 --- a/docs_src/components/examples/dekaCreateElement.js +++ b/docs_src/components/examples/elements/dekaCreateElement.js @@ -1,4 +1,4 @@ -import { el, assign } from "../../../index-with-signals.js"; +import { el, assign } from "deka-dom-el"; const color= "lightcoral"; document.body.append( el("p", { textContent: "Hello (first time)", style: { color } }) diff --git a/docs_src/components/examples/dekaElNS.js b/docs_src/components/examples/elements/dekaElNS.js similarity index 88% rename from docs_src/components/examples/dekaElNS.js rename to docs_src/components/examples/elements/dekaElNS.js index 745dbd2..45e7816 100644 --- a/docs_src/components/examples/dekaElNS.js +++ b/docs_src/components/examples/elements/dekaElNS.js @@ -1,4 +1,4 @@ -import { elNS, assign } from "../../../index-with-signals.js"; +import { elNS, assign } from "deka-dom-el"; const elSVG= elNS("http://www.w3.org/2000/svg"); const elMath= elNS("http://www.w3.org/1998/Math/MathML"); document.body.append( diff --git a/docs_src/components/examples/nativeAppend.js b/docs_src/components/examples/elements/nativeAppend.js similarity index 100% rename from docs_src/components/examples/nativeAppend.js rename to docs_src/components/examples/elements/nativeAppend.js diff --git a/docs_src/components/examples/nativeCreateElement.js b/docs_src/components/examples/elements/nativeCreateElement.js similarity index 100% rename from docs_src/components/examples/nativeCreateElement.js rename to docs_src/components/examples/elements/nativeCreateElement.js diff --git a/docs_src/components/examples/events/abortSignal.js b/docs_src/components/examples/events/abortSignal.js new file mode 100644 index 0000000..a8ea2a2 --- /dev/null +++ b/docs_src/components/examples/events/abortSignal.js @@ -0,0 +1,13 @@ +import { el, on } from "deka-dom-el"; +const log= mark=> console.log.bind(console, mark); + +const abort_controller= new AbortController(); +const { signal }= abort_controller; + +const button= el("button", "Test click"); +button.addEventListener("click", log("`addEventListener`"), { signal }); +on("click", log("`on`"), { signal })(button); + +document.body.append( + button, " ", el("button", { textContent: "Off", onclick: ()=> abort_controller.abort() }) +); diff --git a/docs_src/components/examples/events/compare.js b/docs_src/components/examples/events/compare.js new file mode 100644 index 0000000..1aefa6a --- /dev/null +++ b/docs_src/components/examples/events/compare.js @@ -0,0 +1,10 @@ +import { el, on } from "deka-dom-el"; +const log= mark=> console.log.bind(console, mark); + +const button= el("button", "Test click"); +button.addEventListener("click", log("`addEventListener`"), { once: true }); +on("click", log("`on`"), { once: true })(button); + +document.body.append( + button +); diff --git a/docs_src/components/examples/events/templateWithListeners.js b/docs_src/components/examples/events/templateWithListeners.js new file mode 100644 index 0000000..8216e2b --- /dev/null +++ b/docs_src/components/examples/events/templateWithListeners.js @@ -0,0 +1,24 @@ +import { el, on } from "deka-dom-el"; +const abort_controller= new AbortController(); +const { signal }= abort_controller; +/** @type {ddeElementModifier} */ +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" + ); +} diff --git a/docs_src/components/examples/helloWorld.js b/docs_src/components/examples/helloWorld.js index c20c0db..37d13b1 100644 --- a/docs_src/components/examples/helloWorld.js +++ b/docs_src/components/examples/helloWorld.js @@ -1,4 +1,5 @@ -import { el, S } from "../../../index-with-signals.js"; +import { el } from "deka-dom-el"; +import { S } from "deka-dom-el/signals"; const clicks= S(0); document.body.append( el().append( diff --git a/docs_src/elements.html.js b/docs_src/elements.html.js index d76d672..f69239c 100644 --- a/docs_src/elements.html.js +++ b/docs_src/elements.html.js @@ -30,12 +30,12 @@ export function page({ pkg, info }){ el("abbr", { textContent: "IDL", title: "Interface Description Language" }) ), " also known as a JavaScript property." ), - el(example, { src: fileURL("./components/examples/nativeCreateElement.js"), page_id }), + el(example, { src: fileURL("./components/examples/elements/nativeCreateElement.js"), page_id }), el("p").append( "To make this easier, you can use the ", el("code", "el"), " function. ", "Internally in basic examples, it is wrapper around ", el("code", "assign(document.createElement(…), { … })"), "." ), - el(example, { src: fileURL("./components/examples/dekaCreateElement.js"), page_id }), + el(example, { src: fileURL("./components/examples/elements/dekaCreateElement.js"), page_id }), el("p").append( "The ", el("code", "assign"), " function provides improved behaviour of ", el("code", "Object.assign()"), ". ", "You can declaratively sets any IDL and attribute of the given element. ", @@ -76,15 +76,15 @@ export function page({ pkg, info }){ el("p").append( "For processing, the ", el("code", "assign"), " internally uses ", el("code", "assignAttribute"), " and ", el("code", "classListDeclarative"), "." ), - el(example, { src: fileURL("./components/examples/dekaAssign.js"), page_id }), + el(example, { src: fileURL("./components/examples/elements/dekaAssign.js"), page_id }), el("h3", "Native JavaScript templating"), el("p", "By default, the native JS has no good way to define HTML template using DOM API:"), - el(example, { src: fileURL("./components/examples/nativeAppend.js"), page_id }), + el(example, { src: fileURL("./components/examples/elements/nativeAppend.js"), page_id }), el("p").append( "This library therefore overwrites the ", el("code", "append"), " method of created elements to always return parent element." ), - el(example, { src: fileURL("./components/examples/dekaAppend.js"), page_id }), + el(example, { src: fileURL("./components/examples/elements/dekaAppend.js"), page_id }), el("h3", "Basic (state-less) components"), @@ -93,7 +93,7 @@ export function page({ pkg, info }){ "The ", el("code", "el"), " accepts function as first argument. ", "In that case, the function should return dom elements and the second argument for ", el("code", "el"), " is argument for given element." ), - el(example, { src: fileURL("./components/examples/dekaBasicComponent.js"), page_id }), + el(example, { src: fileURL("./components/examples/elements/dekaBasicComponent.js"), page_id }), el("p").append( "As you can see, in case of state-less/basic components there is no difference", " between calling component function directly or using ", el("code", "el"), " function.", @@ -110,7 +110,7 @@ export function page({ pkg, info }){ " we need to tell JavaScript which kind of the element to create.", " We can use the ", el("code", "elNS"), " function:" ), - el(example, { src: fileURL("./components/examples/dekaElNS.js"), page_id }), + el(example, { src: fileURL("./components/examples/elements/dekaElNS.js"), page_id }), el(prevNext, info) ) diff --git a/docs_src/events.html.js b/docs_src/events.html.js index a19b4d1..a1026aa 100644 --- a/docs_src/events.html.js +++ b/docs_src/events.html.js @@ -20,9 +20,49 @@ export function page({ pkg, info }){ " incorporate not only this in UI templates declaratively." ), - el("h3", "Add events listeners"), + el("h3", "Events and listenners"), el("p").append( + "In JavaScript you can listen to the native DOM events of the given element by using ", + el("a", { href: "https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener", title: "addEventListener on MDN" }).append( + el("code", "element.addEventListener(type, listener, options)") + ), ".", + " ", + "The library provides an alternative (", el("code", "on"), ") accepting the differen order", + " of the arguments:" ), + el(example, { src: fileURL("./components/examples/events/compare.js"), page_id }), + el("p").append( + "…this is actually one of the two differences. The another one is that", el("code", "on"), + " accepts only object as the ", el("code", "options"), " (but it is still optional)." + ), + el("p").append( + "The other difference is that there is ", el("strong", "no"), " ", el("code", "off"), " function.", + " ", + "You can remove listener declaratively using ", el("a", { textContent: "AbortSignal", href: "https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener#signal", title: "part of addEventListener on MDN" }), + ":" + ), + el(example, { src: fileURL("./components/examples/events/abortSignal.js"), page_id }), + + el("h3", "Modifiers"), + el("p").append( + "From practical point of view, ", el("em", "Modifiers"), " are just functions that accept any html element", + " as their first parameter. You can see that the ", el("code", "on(…)"), " fullfills this requirement." + ), + el("p").append( + "You can use Modifiers as ≥3rd argument of ", el("code", "el"), " function. This way is possible to extends", + " you templates by additional (3rd party) functionalities. But for now mainly, you can add events listeners:" + ), + el(example, { src: fileURL("./components/examples/events/templateWithListeners.js"), page_id }), + el("p").append( + "As the example shows, you can also provide types in JSDoc+TypeScript by using global type ", el("code", "ddeElementModifier"), ".", + " ", + "Also notice, you can use Modifiers to get element reference.", + ), + el("h3", "Life cycle events"), + el("p", "Modifiers are called immediately when the element is created, event it is not connected to live DOM yet."), + // todo + + // dispatchEvent el(prevNext, info) ) diff --git a/docs_src/index.html.js b/docs_src/index.html.js index 25ef0fb..c7a8abd 100644 --- a/docs_src/index.html.js +++ b/docs_src/index.html.js @@ -12,7 +12,7 @@ export function page({ pkg, info }){ el("main").append( el("p", "The library tries to provide pure JavaScript tool(s) to create reactive interfaces."), el("p").append( - "We start with creating and modifying a static elemnets and end up with UI templates.", + "We start with creating and modifying a static elements and end up with UI templates.", " ", el("i").append( "From ", el("code", "document.createElement"), " to ", el("code", "el"), "."