From f8646f08a7ea51e59120211cb9afbdd0c1fa01c8 Mon Sep 17 00:00:00 2001 From: Jan Andrle Date: Tue, 4 Jun 2024 15:57:52 +0200 Subject: [PATCH] :abc: small docs refact --- docs/index.html | 2 +- docs/p02-elements.html | 2 +- docs/p03-events.html | 2 +- docs/p04-signals.html | 2 +- docs/p05-scopes.html | 4 ++-- docs_src/index.html.js | 5 ++++- docs_src/p02-elements.html.js | 18 ++++++------------ docs_src/p03-events.html.js | 18 ++++++------------ docs_src/p04-signals.html.js | 15 +++++---------- docs_src/p05-scopes.html.js | 6 ++---- 10 files changed, 29 insertions(+), 45 deletions(-) diff --git a/docs/index.html b/docs/index.html index 450cbf6..a463c02 100644 --- a/docs/index.html +++ b/docs/index.html @@ -1,4 +1,4 @@ -`deka-dom-el` — Introduction

`deka-dom-el` — Introduction

Introducing a library.

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

# Event-driven programming (3 parts separation ≡ 3PS)

Let's introduce the basic principle on which the library is built. We'll use the JavaScript listener as a starting point.

// pseudo code! +`deka-dom-el` — Introduction

`deka-dom-el` — Introduction

Introducing a library.

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

# Event-driven programming (3 parts separation ≡ 3PS)

Let's introduce the basic principle on which the library is built. We'll use the JavaScript listener as a starting point.

// pseudo code! const onchage= event=> console.log("Reacting to the:", event); // A diff --git a/docs/p02-elements.html b/docs/p02-elements.html index 412eb2d..0109f67 100644 --- a/docs/p02-elements.html +++ b/docs/p02-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.

// use NPM or for example https://cdn.jsdelivr.net/gh/jaandrle/deka-dom-el/dist/esm.js +`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.

// use NPM or for example https://cdn.jsdelivr.net/gh/jaandrle/deka-dom-el/dist/esm.js import { assign, el, createElement, diff --git a/docs/p03-events.html b/docs/p03-events.html index 7d3bdec..3d13d08 100644 --- a/docs/p03-events.html +++ b/docs/p03-events.html @@ -1,4 +1,4 @@ -`deka-dom-el` — Events and Addons

`deka-dom-el` — Events and Addons

Using not only events in UI declaratively.

Listenning to the native DOM events and other Addons

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

// use NPM or for example https://cdn.jsdelivr.net/gh/jaandrle/deka-dom-el/dist/esm.js +`deka-dom-el` — Events and Addons

`deka-dom-el` — Events and Addons

Using not only events in UI declaratively.

Listenning to the native DOM events and other Addons

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

// 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} */ diff --git a/docs/p04-signals.html b/docs/p04-signals.html index 24ced16..8548737 100644 --- a/docs/p04-signals.html +++ b/docs/p04-signals.html @@ -1,4 +1,4 @@ -`deka-dom-el` — Signals and reactivity

`deka-dom-el` — Signals and reactivity

Handling reactivity in UI via signals.

Using signals to manage reactivity

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.

// use NPM or for example https://cdn.jsdelivr.net/gh/jaandrle/deka-dom-el/dist/esm-with-signals.js +`deka-dom-el` — Signals and reactivity

`deka-dom-el` — Signals and reactivity

Handling reactivity in UI via signals.

Using signals to manage reactivity

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.

// 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} */ diff --git a/docs/p05-scopes.html b/docs/p05-scopes.html index 598ef0c..843559c 100644 --- a/docs/p05-scopes.html +++ b/docs/p05-scopes.html @@ -1,4 +1,4 @@ -`deka-dom-el` — Scopes and components

`deka-dom-el` — Scopes and components

Organizing UI into components

Using functions as UI components

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 Garbage collection.

// use NPM or for example https://cdn.jsdelivr.net/gh/jaandrle/deka-dom-el/dist/esm-with-signals.js +`deka-dom-el` — Scopes and components

`deka-dom-el` — Scopes and components

Organizing UI into components

Using functions as UI components

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 Garbage collection.

// 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} */

The library therefore use scopes to provide these functionalities.

# Scopes and hosts

The host is the name for the element representing the component. This is typically element returned by function. To get reference, you can use scope.host() to applly addons just use scope.host(...<addons>).

import { el, on, scope } from "./esm-with-signals.js"; @@ -180,4 +180,4 @@ function component(){ * // UNEXPECTEDLY REMOVED!!! * */ } -

# Mnemonic

  • el(<function>, <function-argument(s)>)[.append(...)]: <element-returned-by-function> — using component represented by function
  • scope.host() — get current component reference
  • scope.host(...<addons>) — use addons to current component
\ No newline at end of file +

# Mnemonic

  • el(<function>, <function-argument(s)>)[.append(...)]: <element-returned-by-function> — using component represented by function
  • scope.host() — get current component reference
  • scope.host(...<addons>) — use addons to current component
\ No newline at end of file diff --git a/docs_src/index.html.js b/docs_src/index.html.js index 47472c6..fa8140a 100644 --- a/docs_src/index.html.js +++ b/docs_src/index.html.js @@ -27,6 +27,7 @@ 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 @@ -47,13 +48,15 @@ export function page({ pkg, info }){ 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. + 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`), ); } diff --git a/docs_src/p02-elements.html.js b/docs_src/p02-elements.html.js index b26a158..78660a0 100644 --- a/docs_src/p02-elements.html.js +++ b/docs_src/p02-elements.html.js @@ -13,33 +13,27 @@ 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: { + mdn_create: { /** document.createElement() */ 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: { + mdn_idl: { /** Interface Description Language (`el.textContent`) */ title: t`MDN page about Interface Description Language`, href: "https://developer.mozilla.org/en-US/docs/Glossary/IDL", }, - /** HTMLElement */ - mdn_el: { + mdn_el: { /** HTMLElement */ title: t`MDN documentation page for HTMLElement`, href: "https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement" }, - /** HTMLParagraphElement */ - mdn_p: { + mdn_p: { /** HTMLParagraphElement */ 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: { + mdn_destruct: { /** `[a, b] = [1, 2]` */ 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: { + mdn_ns: { /** document.createElementNS() */ 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", } diff --git a/docs_src/p03-events.html.js b/docs_src/p03-events.html.js index 9652936..38fcf64 100644 --- a/docs_src/p03-events.html.js +++ b/docs_src/p03-events.html.js @@ -13,30 +13,24 @@ 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: { + mdn_listen: { /** element.addEventListener() */ 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: { + mdn_abortListener: { /** AbortSignal+element.addEventListener */ 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: { + web_events: { /** comparison listening options by WebReflection */ href: "https://gist.github.com/WebReflection/b404c36f46371e3b1173bf5492acc944", }, - /** Custom Element lifecycle callbacks */ - mdn_customElement: { + mdn_customElement: { /** Custom Element lifecycle callbacks */ href: "https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements#custom_element_lifecycle_callbacks" }, - /** MutationObserver */ - mdn_mutation: { + mdn_mutation: { /** MutationObserver */ href: "https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver", }, - /** Readding the element to the DOM fix by Vue */ - vue_fix: { + vue_fix: { /** Readding the element to the DOM fix by Vue */ title: t`Vue and Web Components, lifecycle implementation readding the element to the DOM`, href: "https://vuejs.org/guide/extras/web-components.html#lifecycle", } diff --git a/docs_src/p04-signals.html.js b/docs_src/p04-signals.html.js index 6cfedc8..97683ef 100644 --- a/docs_src/p04-signals.html.js +++ b/docs_src/p04-signals.html.js @@ -13,28 +13,23 @@ 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: { + wiki_event_driven: { /** Event-driven programming */ title: t`Wikipedia: Event-driven programming`, href: "https://en.wikipedia.org/wiki/Event-driven_programming", }, - /** Publish–subscribe pattern */ - wiki_pubsub: { + wiki_pubsub: { /** Publish–subscribe pattern */ title: t`Wikipedia: Publish–subscribe pattern`, href: "https://en.wikipedia.org/wiki/Publish%E2%80%93subscribe_pattern", }, - /** NPM package: fpubsub */ - fpubsub: { + fpubsub: { /** NPM package: fpubsub */ title: t`NPM package: fpubsub`, href: "https://www.npmjs.com/package/fpubsub", }, - /** JS Primitives | MDN */ - mdn_primitive: { + mdn_primitive: { /** JS Primitives | MDN */ title: t`Primitive | MDN`, href: "https://developer.mozilla.org/en-US/docs/Glossary/Primitive", }, - /** useReducer */ - mdn_use_reducer: { + mdn_use_reducer: { /** useReducer */ title: t`useReducer hook | React docs`, href: "https://react.dev/reference/react/useReducer", } diff --git a/docs_src/p05-scopes.html.js b/docs_src/p05-scopes.html.js index d104ffd..e1719e2 100644 --- a/docs_src/p05-scopes.html.js +++ b/docs_src/p05-scopes.html.js @@ -13,13 +13,11 @@ 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: { + garbage_collection: { /** Garbage collection on MDN */ title: t`MDN documentation page for Garbage collection`, href: "https://developer.mozilla.org/en-US/docs/Glossary/Garbage_collection", }, - /** Signals */ - signals: { + signals: { /** Signals */ title: t`Signals section on this library`, href: "./p04-signals#h-introducing-signals", }