Merge branch 'main' of https://github.com/efflore/ui-element into main

Author: estherbrunner

README.md

@@ -2,6 +2,8 @@
 
 UIElement - the "look ma, no JS framework!" library bringing signals-based reactivity to vanilla Web Components
 
+Version 0.6.2
+
 ## What is UIElement?
 
 `UIElement` is a base class for your reactive Web Components. It extends the native `HTMLElement` class and adds a public property and a few methods that allow you to implement inter- and intra-component reactivity with ease. You extend the base class `UIElement` and call the static `define()` method on it to register a tag name in the `CustomElementsRegistry`.
@@ -10,19 +12,19 @@ UIElement - the "look ma, no JS framework!" library bringing signals-based react
 
 `UIElement` implements a `Map`-like interface on top of `HTMLElement` to access and modify reactive states. The method names `this.has()`, `this.get()`, `this.set()` and `this.delete()` feel familar to JavaScript developers and mirror what you already know.
 
-In the `connectedCallback()` you setup references to inner elements, add event listeners and pass reactive states to sub-components (`this.pass()`). Additionally, for every independent reactive state you define what happens when it changes in the callback of `this.effect()`. `UIElement` will automatically trigger these effects and bundle the surgical DOM updates when the browser refreshes the view on the next animation frame.
+In the `connectedCallback()` you setup references to inner elements, add event listeners and pass reactive states to sub-components (`this.pass()`). Additionally, for every independent reactive state you define what happens when it changes in the callback of `this.effect()`. `UIElement` will automatically trigger these effects and bundle the fine-grained DOM updates when the browser refreshes the view on the next animation frame.
 
-`UIElement` is fast. In fact, faster than any JavaScript framework. Only direct surgical DOM updates in vanilla JavaScript can beat its performance. But then, you have no loose coupling of components and need to parse attributes and track changes yourself. This tends to get tedious and messy rather quickly. `UIElement` provides a structured way to keep your components simple, consistent and self-contained.
+`UIElement` is fast. In fact, faster than any JavaScript framework. Only direct fine-grained DOM updates in vanilla JavaScript can beat its performance. But then, you have no loose coupling of components and need to parse attributes and track changes yourself. This tends to get tedious and messy rather quickly. `UIElement` provides a structured way to keep your components simple, consistent and self-contained.
 
-`UIElement` is tiny. 681 bytes gzipped over the wire. And it has zero dependiences. If you want to understand how it works, you have to study the source code of [one single file](./index.js).
+`UIElement` is tiny. 685 bytes gzipped over the wire. And it has zero dependiences. If you want to understand how it works, you have to study the source code of [one single file](./index.js).
 
 That's all.
 
 ## What is UIElement intentionally not?
 
 `UIElement` does not do many of the things JavaScript frameworks do.
 
-Most importantly, it does not render components. We suggest, you render components (eighter Light DOM children or Declarative Shadow DOM) on the server side. There are existing solutions like [WebC](https://github.com/11ty/webc) or [Enhance](https://github.com/enhance-dev/enhance) that allow you to declare and render Web Components on the server side with (almost) pure HTML, CSS and JavaScript. `UIElement` is proven to work with either WebC or Enhance. But you could use any tech stack able to render HTML. There is no magic involved besides the building blocks of any website: HTML, CSS and JavaScript. `UIElement` does not make any assumptions about the structure of the inner HTML. In fact, it is up to you to reference inner elements and do surgical DOM updates in effects. This also means, there is no new language or format to learn. HTML, CSS and modern JavaScript (ES6) is all you need to know to develop your own web components with `UIElement`.
+Most importantly, it does not render components. We suggest, you render components (eighter Light DOM children or Declarative Shadow DOM) on the server side. There are existing solutions like [WebC](https://github.com/11ty/webc) or [Enhance](https://github.com/enhance-dev/enhance) that allow you to declare and render Web Components on the server side with (almost) pure HTML, CSS and JavaScript. `UIElement` is proven to work with either WebC or Enhance. But you could use any tech stack able to render HTML. There is no magic involved besides the building blocks of any website: HTML, CSS and JavaScript. `UIElement` does not make any assumptions about the structure of the inner HTML. In fact, it is up to you to reference inner elements and do fine-grained DOM updates in effects. This also means, there is no new language or format to learn. HTML, CSS and modern JavaScript (ES6) is all you need to know to develop your own web components with `UIElement`.
 
 `UIElement` does no routing. It is strictly for single-page applications or reactive islands. But of course, you can reuse the same components on many different pages, effectively creating tailored single-page applications for every page you want to enhance with rich interactivity. We believe, this is the most efficient way to build rich multi-page applications, as only the scripts for the elements used on the current page are loaded, not a huge bundle for the whole app.
 
@@ -160,11 +162,31 @@ Make sure the import of `UIElement` on the first line points to your installed p
 import UIElement from '@efflore/ui-element';
 ```
 
+If you use Debug Element as your base class for custom elements, you may call `super.connectedCallback();` (and the other lifecycle callbacks) to log when your element connects to the DOM.
+
+To log when some DOM features of child elements are updated in effects, you need to enqueue all fine-grained DOM updated like this:
+
+```js
+// in connectedCallback()
+this.effect(queue => queue(this.querySelector('span'), (el, text) => (el.textContent = text), this.get('value')));
+```
+
+Otherwise Debug Element only knows which effect runs in which component, but not the exact elements targeted by your effect.
+
+Enqueueing fine-grained DOM updates is always possible. It's a bit more verbose, but it ensures all updates of your effect happen at the same time. `autoEffects()` from DOM Utils (see next section) does this by default. All DOM utility functions receive the target element as first parameter, making it possible to use this shorter notation:
+
+```js
+import { setText } from './lib/dom-utils';
+
+// in connectedCallback()
+this.effect(queue => queue(this.querySelector('span'), setText, this.get('value')));
+```
+
 [Source](./lib/debug-element.js)
 
 ### DOM Utils
 
-A few utility functions for surgical DOM updates in `effect()`s that streamline the interface and save tedious existance and change checks:
+A few utility functions for fine-grained DOM updates in `effect()`s that streamline the interface and save tedious existance and change checks:
 
 - `setText()` preserves comment nodes in contrast to `element.textContent` assignments
 - `setProp()` sets or deletes a property on an element
@@ -184,7 +206,7 @@ With all key/value pair attributes, you can provide several separated by `;`. Ea
 
 Auto-Effects will be be applied to the Shadow DOM, if your component uses it; otherwise to the Light DOM sub-tree. The `ui-*` attributes will be removed from the DOM once your component is connected and the effects are set up. If you load a partial from the server containing these attributes, you will have to call `autoEffects()` again to have the effects auto-applied to the newly loaded partial as well.
 
- By using these declarative attributes you can considerably reduce the amount of simple effects in your component's JavaScript. Almost all surgical DOM updates can be done this way. You gain Locality of Behavior (LoB) in your markup and can decide per case where effects shall be applied. On the other hand, you lose Separation of Concerns (SoC) - if you care about it. It's the same trade-off as with JSX, but in pure HTML.
+ By using these declarative attributes you can considerably reduce the amount of simple effects in your component's JavaScript. Almost all fine-grained DOM updates can be done this way. You gain Locality of Behavior (LoB) in your markup and can decide per case where effects shall be applied. On the other hand, you lose Separation of Concerns (SoC) - if you care about it. It's the same trade-off as with JSX, but in pure HTML.
 
 As not all users like the sort of magic of Auto-Effects, it's an optional opt-in and not part of the core `UIElement` library. Copy the source code and adapt it to your needs, if you like it.
 
@@ -237,7 +259,7 @@ Where has the JavaScript gone? – It almost disappeared. To explain the magic:
 6. `UIElement` **auto-runs** the effect you did not even write again with a new `'value'` value
 7. `autoEffects()` knows which element's `textContent` to **auto-update**
 
-By always following this pattern of data-flow, that is close to an optimal implementation in vanilla JavaScript, we can drastrically reduce need JavaScrpt both on the library side (`UIElement` + `dom-utils` ca. 1.3 kB gzipped) and on userland side.
+By always following this pattern of data-flow, that is close to an optimal implementation in vanilla JavaScript, we can drastrically reduce need JavaScrpt both on the library side (`UIElement` + `dom-utils` ca. 1.4 kB gzipped) and on userland side.
 
 [Source](./lib/dom-utils.js)
 

index.js

@@ -173,21 +173,37 @@ export default class extends HTMLElement {
    */
   effect(fn) {
     fn.targets = new Map();
-    const scheduled = (/** @type {Element} */ element, /** @type {(...args: any []) => any} */ domFn) => {
+
+    /**
+     * @since 0.6.1
+     * 
+     * @param {Element} element 
+     * @param {import("./types").DOMUpdater} domFn 
+     * @param  {any} key
+     * @param  {any} value
+     * @returns {Map<any, any>}
+     */
+    const queue = (element, domFn, key, value) => {
       !fn.targets.has(element) && fn.targets.set(element, new Map());
       const domFns = fn.targets.get(element);
-      !domFns.has(domFn) && domFns.set(domFn, new Set());
-      return domFns.get(domFn);
+      !domFns.has(domFn) && domFns.set(domFn, new Map());
+      const argsMap = domFns.get(domFn);
+      key && argsMap.set(key, value);
+      return argsMap;
     };
+
+    // effect callback function
     const next = () => {
       queueMicrotask(() => {
         const prev = active;
         active = next;
-        const cleanup = fn(scheduled);
+        const cleanup = fn(queue);
         active = prev;
+
+        // flush all queued effects
         for (const [el, domFns] of fn.targets.entries()) {
-          for (const [domFn, argsSet] of domFns.entries()) {
-            for (const args of argsSet.keys()) domFn(el, ...args);
+          for (const [domFn, argsMap] of domFns.entries()) {
+            for (const [key, value] of argsMap.entries()) domFn(el, key, value);
           }
         }
         // @ts-ignore

index.min.js

@@ -92,9 +92,9 @@ export default class extends UIElement {
   effect(fn) {
     if (!this.debug) return super.effect(fn);
     (typeof fn !== 'function') && this.error(new TypeError(`Effect handler in ${elementName(this)} is not a function`));
-    const spy = (/** @type {import("../types").DOMEffects} */ scheduled) => {
+    const spy = (/** @type {import("../types").DOMEffects} */ queue) => {
       fn.targets = new Map();
-      fn(scheduled);
+      fn(queue);
       if (spy.targets.size) {
         const elements = [];
         for (const el of spy.targets.keys()) elements.push(elementName(el));

lib/debug-element.js

@@ -21,17 +21,20 @@ const _check = (element, value, old) => (element && value !== null) && (value !=
 /**
  * Update text content of an element while preserving comments (unlike element.textContent assignment)
  * 
+ * @type {import("../types").DOMUpdater}
  * @param {Element} element - element to update
+ * @param {any} _ - unused
  * @param {any} content - new text content
  */
-const t = (element, content) => {
+const t = (element, _, content) => {
   Array.from(element.childNodes).filter(node => node.nodeType !== Node.COMMENT_NODE).forEach(node => node.remove());
   element.append(document.createTextNode(content));
 };
 
 /**
  * Update property of an element
  * 
+ * @type {import("../types").DOMUpdater}
  * @param {Element} element - element to update
  * @param {PropertyKey} key - property to update
  * @param {any} value - new property value
@@ -43,6 +46,7 @@ const p = (element, key, value) => _defined(value)
 /**
  * Update attribute of an element
  * 
+ * @type {import("../types").DOMUpdater}
  * @param {Element} element - element to update
  * @param {string} name - attribute to update
  * @param {string|boolean|undefined} value 
@@ -56,6 +60,7 @@ const a = (element, name, value) => typeof value === 'boolean'
 /**
  * Update class token of an element
  * 
+ * @type {import("../types").DOMUpdater}
  * @param {Element} element - element to update
  * @param {string} token - class token to update
  * @param {boolean|undefined} force - whether to add or remove the token; if `undefined` the token will be toggled
@@ -65,6 +70,7 @@ const c = (element, token, force) => element.classList.toggle(token, force);
 /**
  * Update style property of an element
  * 
+ * @type {import("../types").DOMUpdater}
  * @param {HTMLElement} element - element to update
  * @param {string} name - style property to update
  * @param {string} value - new style property value
@@ -77,15 +83,18 @@ const s = (element, name, value) => _defined(value) ? element.style.setProperty(
  * Update text content of an element while preserving comments
  * 
  * @since 0.6.0
+ * @type {import("../types").DOMUpdater}
  * @param {Element} element - element to be updated
+ * @param {any} key - ignored, but used for consistency; if third parameter is omitted, second parameter will be used as content
  * @param {string|null} content - new text content; `null` for opt-out of update
  */
-const setText = (element, content) => _check(element, content, element.textContent) && t(element, content);
+const setText = (element, key, content = key) => _check(element, content, element.textContent) && t(element, true, content);
 
 /**
  * Update property of an element
  * 
  * @since 0.6.0
+ * @type {import("../types").DOMUpdater}
  * @param {Element} element - element to be updated
  * @param {PropertyKey} key - property to be updated
  * @param {any} value - new property value; `''` or `true` for boolean attribute; `null` for opt-out of update; `undefined` or `false` will delete existing property
@@ -96,6 +105,7 @@ const setProp = (element, key, value) => _check(element, value, element[key]) &&
  * Update attribute of an element
  * 
  * @since 0.6.0
+ * @type {import("../types").DOMUpdater}
  * @param {Element} element - element to be updated
  * @param {string} name - attribute to be updated
  * @param {string|null} value - new attribute value; `null` for opt-out of update; `undefined` will remove existing attribute
@@ -106,6 +116,7 @@ const setAttr = (element, name, value) => _check(element, value, element.getAttr
  * Toggle class on an element
  * 
  * @since 0.6.0
+ * @type {import("../types").DOMUpdater}
  * @param {Element} element - element to be toggled
  * @param {string} token - class token to be toggled
  * @param {boolean|null|undefined} force - force toggle condition `true` or `false`; `null` for opt-out of update; `undefined` will toggle existing class
@@ -115,7 +126,8 @@ const setClass = (element, token, force) => _check(element, force, element.class
 /**
  * Update style property of an element
  * 
- * @since 0.5.0
+ * @since 0.6.0
+ * @type {import("../types").DOMUpdater}
  * @param {HTMLElement} element - element to be updated
  * @param {string} property - style property to be updated
  * @param {string|null|undefined} value - new style property value; `null` for opt-out of update; `undefined` will remove existing style property
@@ -139,12 +151,12 @@ const autoEffects = (/** @type {import("../types").UIElement} */ element) => {
       // update text content
       if (attr === TEXT_ATTR) {
         const key = node.getAttribute(attr);
-        const fallback = node.textContent;
+        const fallback = node.textContent || '';
         element.set(key, fallback, false);
-        element.effect((/** @type {import("../types").DOMEffects} */ scheduled) => {
+        element.effect((/** @type {import("../types").DOMEffects} */ queue) => {
           if (element.has(key)) {
             const content = element.get(key);
-            scheduled(node, t).add([_defined(content) ? content : fallback]);
+            queue(node, t, true, _defined(content) ? content : fallback);
           }
         });
 
@@ -169,8 +181,8 @@ const autoEffects = (/** @type {import("../types").UIElement} */ element) => {
           let [name, value] = key.split(':').map(s => s.trim());
           !value && (value = name);
           element.set(value, fallback(attr, node, name), false);
-          element.effect((/** @type {(element: Element, fn: (...args: any[]) => any) => Set<any[]>} */ scheduled) => {
-            element.has(value) && scheduled(node, setter[attr]).add([name, element.get(value)]);
+          element.effect((/** @type {import("../types").DOMEffects} */ queue) => {
+            element.has(value) && queue(node, setter[attr], name, element.get(value));
           });
         });
       }