@webtides/element-js 1.2.12 → 1.3.1

package/docs/features/templates.md

@@ -158,27 +158,36 @@ const attributeString = spreadAttributes(attrs);
 
 ##### Writing custom directives
 
-Directives in `element-js` are just functions. They accept parameters and return values that manipulate or produce templates or strings.
+The built-in directives above are plain functions that return a value for an attribute or a child position. A directive that works on the element itself sits inside the opening tag, between the attributes. It is a class that extends `Directive`, wrapped with `defineDirective()`:
 
-To write a custom directive:
-
-    Define a Function: This function will describe what your directive does. The function should return either a template, string, or another function based on its parameters.
+- `update(...values)` runs in the browser on every render, `this.node` is the element the directive sits on.
+- `stringify(...values)` runs when the template is rendered to a string, for example on the server, and returns what is written into the opening tag.
 
 ```javascript
-const visibility = (isVisible) => {
-    return isVisible ? '' : 'style="display: none;"';
-};
+import { Directive, defineDirective } from '@webtides/element-js';
+
+class HighlightDirective extends Directive {
+    update(active) {
+        this.node.toggleAttribute('data-highlight', active);
+    }
+
+    stringify(active) {
+        return active ? 'data-highlight' : '';
+    }
+}
+
+const highlight = defineDirective(HighlightDirective);
 ```
 
-Use your custom directive in your templates.
+`defineDirective()` returns the function to call in templates, its arguments are passed on to `update()` and `stringify()`:
 
 ```javascript
 function template() {
-    return html` <div ${visibility(false)}>This div will be hidden.</div> `;
+    return html` <div ${highlight(this.active)}>Highlighted while active.</div> `;
 }
 ```
 
-Remember, the power of directives is in their simplicity. They allow you to encapsulate logic in a function and reuse that logic across multiple templates.
+A plain function at this position throws, the renderer only accepts a directive created with `defineDirective()`. The `about` tab of `examples/showcase/` uses this directive.
 
 #### Slots
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@webtides/element-js",
-    "version": "1.2.12",
+    "version": "1.3.1",
     "module": "index.js",
     "main": "index.js",
     "type": "module",
@@ -36,12 +36,12 @@
         "element-js",
         "shadow-dom"
     ],
-    "dependencies": {},
     "devDependencies": {
         "@babel/eslint-parser": "^7.23.3",
         "@open-wc/testing": "^4.0.0",
         "@web/dev-server": "^0.4.6",
         "@web/test-runner": "^0.19.0",
+        "@web/test-runner-commands": "^0.9.0",
         "babel-eslint": "^10.1.0",
         "eslint": "8.55.0",
         "eslint-config-prettier": "^9.1.0",
@@ -60,6 +60,9 @@
     "scripts": {
         "lint": "eslint index.js 'src/**/*.js'",
         "test": "web-test-runner test/**/*.test.{html,js} --node-resolve",
+        "bench": "node benchmark/run.mjs",
+        "bench:compare": "node benchmark/run.mjs --base main",
+        "bench:ui": "web-dev-server --root-dir . --open /benchmark/",
         "test:coverage": "web-test-runner test/**/*.test.{html,js} --node-resolve --coverage",
         "test:watch": "web-test-runner test/**/*.test.{html,js} --node-resolve --watch",
         "start": "web-dev-server --config web-dev-server.config.mjs"

package/src/TemplateElement.js

@@ -55,10 +55,12 @@ class TemplateElement extends StyledElement {
      * This will attach a shadow DOM if the element is supposed to render in shadow DOM.
      */
     renderTemplate() {
-        const firstRender = this._options.shadowRender && !this.shadowRoot;
-        if (firstRender) {
+        if (this._options.shadowRender && !this.shadowRoot) {
             this.attachShadow({ mode: 'open' });
-            // init external stylesheets
+        }
+        // the first render adopts the style sheets, also into a declarative shadow root that the parser attached
+        if (this._options.shadowRender && !this._stylesAdopted) {
+            this._stylesAdopted = true;
             this.initStyleAdoption();
         }
 

package/src/dom-parts/AttributePart.js

@@ -1,16 +1,30 @@
 import { Part } from './Part.js';
 
+// marks the first update: it compares with the attribute in the DOM once, so a fresh clone, which carries the
+// placeholder, gets written and server rendered markup that fits already is left alone
+const NOT_SET = Symbol('not set');
+
 /**
  * @param {Element} node
  * @param {String} name
- * @param {Boolean} oldValue
  * @return {(function(*): void)|*}
  */
-const processBooleanAttribute = (node, name, oldValue) => {
+const processBooleanAttribute = (node, name) => {
+    let oldValue = NOT_SET;
     return (newValue) => {
         const value = !!newValue?.valueOf() && newValue !== 'false';
+        if (oldValue === NOT_SET && node.getAttribute(name) === (value ? '' : null)) {
+            oldValue = value;
+            return;
+        }
         if (oldValue !== value) {
-            node.toggleAttribute(name, (oldValue = !!value));
+            oldValue = value;
+            // not toggleAttribute(): server rendered markup may carry `name="false"`, true has to become `name=""`
+            if (value) {
+                node.setAttribute(name, '');
+            } else {
+                node.removeAttribute(name);
+            }
         }
     };
 };
@@ -49,9 +63,13 @@ const processEventAttribute = (node, name) => {
  * @return {(function(*): void)|*}
  */
 const processAttribute = (node, name) => {
-    let oldValue;
+    let oldValue = NOT_SET;
     return (newValue) => {
         const value = newValue?.valueOf();
+        if (oldValue === NOT_SET && node.getAttribute(name) === (value == null ? null : String(value))) {
+            oldValue = value;
+            return;
+        }
         if (oldValue !== value) {
             oldValue = value;
             if (value == null) {
@@ -74,7 +92,7 @@ const attributePartsCache = new WeakMap();
 export const processAttributePart = (node, name) => {
     // boolean attribute: ?boolean=${...}
     if (name.startsWith('?')) {
-        return processBooleanAttribute(node, name.slice(1), false);
+        return processBooleanAttribute(node, name.slice(1));
     }
 
     // property attribute: .property=${...}
@@ -82,11 +100,23 @@ export const processAttributePart = (node, name) => {
         return processPropertyAttribute(node, name.slice(1));
     }
 
-    // event attribute: @event=${...} || "old school" event attribute: onevent=${...}
-    if (name.startsWith('@') || name.startsWith('on')) {
+    // event attribute: @event=${...}
+    if (name.startsWith('@')) {
         return processEventAttribute(node, name);
     }
 
+    // "old school" event attribute: onevent=${...}. A function is the listener, any other value is written as an
+    // attribute: `on="${state}"` or `once="${flag}"` are attributes of the element that happen to start with "on"
+    if (name.startsWith('on')) {
+        const listener = processEventAttribute(node, name);
+        const attribute = processAttribute(node, name);
+        return (value) => {
+            const isListener = typeof value === 'function';
+            listener(isListener ? value : undefined);
+            attribute(isListener ? undefined : value);
+        };
+    }
+
     // normal "string" attribute: attribute=${...}
     return processAttribute(node, name);
 };

package/src/dom-parts/ChildNodePart.js

@@ -1,4 +1,4 @@
-import { COMMENT_NODE, ELEMENT_NODE } from '../util/DOMHelper.js';
+import { COMMENT_NODE, TEXT_NODE } from '../util/DOMHelper.js';
 import { Part } from './Part.js';
 import { TemplateResult } from './TemplateResult.js';
 import { TemplatePart } from './TemplatePart.js';
@@ -69,42 +69,54 @@ export const getNodesBetweenComments = (commentNode, includeComments = false) =>
 };
 
 /**
- * @param {Node[]} newChildNodes
- * @param {Comment} anchorNode
+ * A node that is not in the DOM yet takes over an equal node that is in place: a fresh text node leaves the text node
+ * that is there alone. The nodes of a template clone still sit in their fragment and never take over, they replace
+ * what the server rendered in their place.
+ * @param {Node} node
+ * @param {Node} newChildNode
+ * @return {boolean}
  */
-const diffChildNodes = function (newChildNodes, anchorNode) {
-    const parentNode = anchorNode.parentNode;
-    const oldChildNodes = getNodesBetweenComments(anchorNode);
-
-    const length = Math.max(oldChildNodes.length, newChildNodes.length);
-    // Diff each node in the child node lists
-    for (let index = 0; index < length; index++) {
-        let oldChildNode = oldChildNodes[index];
-        let newChildNode = newChildNodes[index];
+const takesOver = (node, newChildNode) => !newChildNode.parentNode && node.isEqualNode(newChildNode);
 
-        if (newChildNode && !newChildNode.nodeType) {
+/**
+ * Brings the nodes between the markers in line with newChildNodes, in that order. Walks the live DOM with a cursor:
+ * a node that is at the cursor already stays, stale nodes at the cursor are removed, anything else is inserted in
+ * front of the cursor, which moves a node that is in the DOM further back, for example a hydrated template behind a
+ * server rendered text. Nodes that are in place are never touched, so focus and element lifecycles survive.
+ * @param {Node[]} newChildNodes
+ * @param {Comment} startNode - the start marker
+ * @param {Comment} endNode - the end marker
+ */
+const diffChildNodes = (newChildNodes, startNode, endNode) => {
+    const parentNode = endNode.parentNode;
+    // the set of new nodes tells a stale node from one that is needed further on. It is only built when the nodes
+    // deviate from what is there, a list whose nodes are all in place never pays for it
+    let keep;
+    let current = startNode.nextSibling;
+    for (let index = 0; index < newChildNodes.length; index++) {
+        const newChildNode = newChildNodes[index];
+        if (!newChildNode?.nodeType) {
             throw new Error('ChildNodePart: newChildNode is not a node');
         }
-
-        // If the DOM node doesn't exist, append/copy the new node
-        if (oldChildNode === undefined) {
-            parentNode.insertBefore(newChildNode, anchorNode);
-            continue;
-        }
-
-        // If the new node doesn't exist, remove the node in the DOM
-        if (newChildNode === undefined) {
-            parentNode.removeChild(oldChildNode);
-            continue;
+        if (current !== newChildNode && current !== endNode) {
+            keep ??= new Set(newChildNodes);
+            while (current !== endNode && !keep.has(current) && !takesOver(current, newChildNode)) {
+                const next = current.nextSibling;
+                parentNode.removeChild(current);
+                current = next;
+            }
         }
-
-        // If DOM node is equal to the new node, don't do anything in the DOM
-        if (oldChildNode === newChildNode || oldChildNode.isEqualNode(newChildNode)) {
-            continue;
+        if (current === newChildNode || (current !== endNode && !keep.has(current))) {
+            // in place already, or a stale node the new one takes over
+            current = current.nextSibling;
+        } else {
+            parentNode.insertBefore(newChildNode, current);
         }
-
-        // Everything else is somehow different and can be replaced
-        parentNode.replaceChild(newChildNode, oldChildNode);
+    }
+    while (current !== endNode) {
+        const next = current.nextSibling;
+        parentNode.removeChild(current);
+        current = next;
     }
 };
 
@@ -116,16 +128,13 @@ function getType(value) {
     return 'text';
 }
 
-// TODO: handle funcitons?! Should be handled in parseArray!!!
+// the parsed items of an array as the child nodes to diff: template parts contribute their nodes, primitives become
+// text nodes, DOM nodes pass through
 const unwrapArray = (nodes) => {
-    // we have to unwrap any complex objects inside the array so that we can diff arrays of childNodes
     return nodes.flatMap((value) => {
         if (value instanceof TemplatePart) {
             return value.childNodes;
         }
-        if (Array.isArray(value)) {
-            return unwrapArray(value);
-        }
         if (typeof value === 'boolean' || typeof value === 'number' || typeof value === 'string') {
             return document.createTextNode(value);
         }
@@ -134,76 +143,72 @@ const unwrapArray = (nodes) => {
 };
 
 /**
- * @param {Comment} comment
- * @param {TemplatePart | any[] | any} initialValue
- * @param {boolean} serverSideRendered
- * @return {(function(*): void)|*}
+ * Array items get the same treatment as a single value: functions are resolved completely, arrays nested in the array
+ * are flattened and null or undefined items are dropped, which is the list the server renders. An array that needs
+ * none of it is returned as is.
+ * @param {any[]} values
+ * @return {any[]}
+ */
+const resolveArrayItems = (values) => {
+    if (!values.some((value) => typeof value === 'function' || Array.isArray(value) || value == null)) {
+        return values;
+    }
+    return values.flatMap((item) => {
+        let value = item;
+        while (typeof value === 'function') value = value();
+        if (Array.isArray(value)) return resolveArrayItems(value);
+        return value == null ? [] : [value];
+    });
+};
+
+/**
+ * Creates the processor that writes a parsed value between the markers of a child node part.
+ * @param {PartMarkers} markers - the start and end marker of the part
+ * @return {(function(TemplatePart | any[] | any, boolean=): void)}
  */
-export const processNodePart = (comment, initialValue, serverSideRendered = false) => {
+export const processNodePart = ({ startNode, endNode }) => {
     let oldValueType = 'empty';
     let oldValue = undefined;
-    // this is for string values to be inserted into the DOM. A cached TextNode will be used so that we don't have to constantly create new DOM nodes.
-    // TODO: when server side rendered, we need to get the text node from the DOM no?!
+    // string values are rendered into one text node that is reused across updates. Hydration takes over the server
+    // rendered text node as that node
     let cachedTextNode = globalThis.document?.createTextNode('');
 
-    if (serverSideRendered) {
-        oldValueType = getType(initialValue);
-        oldValue = initialValue instanceof TemplatePart ? initialValue.strings : initialValue;
-    }
-
-    const processNodeValue = (newValue) => {
-        let newValueType = getType(newValue);
+    return (newValue, hydrate = false) => {
+        const newValueType = getType(newValue);
 
         if (oldValueType === newValueType && oldValue === newValue) return;
 
-        if (oldValueType !== newValueType) {
-            if (newValueType === 'empty') {
-                removeNodesBetweenComments(comment);
+        if (newValueType === 'empty') {
+            removeNodesBetweenComments(endNode);
+        } else if (newValueType === 'text') {
+            if (oldValueType !== 'text') {
+                const serverTextNode = startNode.nextSibling;
+                if (hydrate && serverTextNode.nodeType === TEXT_NODE && serverTextNode.nextSibling === endNode) {
+                    cachedTextNode = serverTextNode;
+                } else {
+                    replaceNodesBetweenComments(endNode, [cachedTextNode]);
+                }
+            }
+            if (cachedTextNode.data !== String(newValue)) cachedTextNode.data = newValue;
+        } else if (newValueType === 'templatePart') {
+            // a template part bound to server rendered DOM (hydration) is in place already and is left alone
+            if (newValue.childNodes[0].parentNode !== endNode.parentNode) {
+                replaceNodesBetweenComments(endNode, newValue.childNodes);
+            }
+        } else {
+            const nodes = newValueType === 'array' ? unwrapArray(newValue) : [newValue];
+            // a type change replaces what is there. Server rendered nodes (hydration) go through the diff instead,
+            // nodes that are in place already, for example a focused input, stay untouched
+            if (oldValueType !== newValueType && !hydrate) {
+                replaceNodesBetweenComments(endNode, nodes);
             } else {
-                const getNodesForType = (value, type) => {
-                    if (type === 'templatePart') return value.childNodes;
-                    if (type === 'array') return unwrapArray(value);
-                    if (type === 'node') return [value];
-
-                    // Every else falls back to rendering a text node
-                    cachedTextNode.data = value;
-                    return [cachedTextNode];
-                };
-                replaceNodesBetweenComments(comment, getNodesForType(newValue, newValueType));
+                diffChildNodes(nodes, startNode, endNode);
             }
-
-            oldValueType = newValueType;
-            oldValue = newValue;
-            return;
-        }
-
-        if (newValueType === 'text') {
-            cachedTextNode.data = newValue;
-
-            oldValue = newValue;
-            return;
-        }
-
-        if (newValueType === 'array') {
-            diffChildNodes(unwrapArray(newValue), comment);
-
-            oldValue = newValue;
-            return;
         }
 
-        if (newValueType === 'node') {
-            diffChildNodes([newValue], comment);
-
-            oldValue = newValue;
-        }
+        oldValueType = newValueType;
+        oldValue = newValue;
     };
-
-    if (!serverSideRendered) {
-        // initial rendering
-        processNodeValue(initialValue);
-    }
-
-    return processNodeValue;
 };
 
 /**
@@ -216,17 +221,16 @@ export class ChildNodePart extends Part {
     /** @type {TemplatePart|undefined} */
     templatePart;
 
-    /** @type {Part[]} */
+    /** @type {TemplatePart[]} indexed like the items of an array value, only template items have a part */
     arrayParts = [];
 
     /**
      * @param {Node} startNode - the start comment marker node
-     * @param {any | any[]} value
      */
-    constructor(startNode, value) {
+    constructor(startNode) {
         if (!startNode || startNode?.nodeType !== COMMENT_NODE) {
             throw new Error(
-                startNode ? 'ChildNodePart: startNode is undefined' : 'ChildNodePart: startNode is not a comment node',
+                startNode ? 'ChildNodePart: startNode is not a comment node' : 'ChildNodePart: startNode is undefined',
             );
         }
 
@@ -234,70 +238,63 @@ export class ChildNodePart extends Part {
 
         startNode.__part = this; // add Part to comment node for debugging in the browser
         this.markers = PartMarkers.createFromStartNode(startNode);
-
-        // value can become array | TemplatePart | any
-        const initialValue = this.parseValue(value);
-
-        this.processor = processNodePart(this.markers?.endNode, initialValue, this.markers?.serverSideRendered);
+        this.processor = processNodePart(this.markers);
     }
 
     /**
-     * @param {any} value
-     * @return {*}
+     * @param {TemplateResult | any[] | any} value
+     * @param {boolean} [hydrate] - bind nested template parts to the server rendered markers instead of cloning
      */
-    update(value) {
-        const parsedValue = this.parseValue(value);
-
-        if (value instanceof TemplateResult || Array.isArray(value)) {
-            this.updateParts(value);
-        }
-
-        this.processor?.(parsedValue);
+    update(value, hydrate = false) {
+        // functions are resolved completely and array items are normalized, parsing and updating have to work on the
+        // same value
+        let resolvedValue = value;
+        while (typeof resolvedValue === 'function') resolvedValue = resolvedValue();
+        if (Array.isArray(resolvedValue)) resolvedValue = resolveArrayItems(resolvedValue);
+        const parsedValue = this.parseValue(resolvedValue, hydrate);
+        this.updateParts(resolvedValue, hydrate);
+        this.processor(parsedValue, hydrate);
     }
 
     /**
-     * @param {TemplateResult | any[]} value
+     * @param {TemplateResult | any[] | any} value
+     * @param {boolean} [hydrate]
      */
-    updateParts(value) {
+    updateParts(value, hydrate = false) {
         if (value instanceof TemplateResult) {
-            this.templatePart.update(value);
+            this.templatePart.update(value, hydrate);
         }
         if (Array.isArray(value)) {
             for (let index = 0; index < value.length; index++) {
-                this.arrayParts[index]?.update(value[index]);
+                if (value[index] instanceof TemplateResult) this.arrayParts[index].update(value[index], hydrate);
             }
         }
     }
 
     /**
+     * Creates the nested parts for a value. When hydrating, nested template parts are bound to the server rendered
+     * template-part markers between this part's markers.
      * @param {TemplateResult | any[] | any} value
+     * @param {boolean} hydrate
      * @return {TemplatePart | Node | string | Array<TemplatePart | Node | string>}
      */
-    parseValue(value) {
+    parseValue(value, hydrate = false) {
         if (value instanceof TemplateResult) {
             if (!this.templatePart) {
-                this.templatePart = new TemplatePart(this.markers?.findNestedStartNode('template-part'), value);
-                if (!this.markers?.serverSideRendered) {
-                    // INFO: this is similar to TemplateResult#237
-                    replaceNodesBetweenComments(this.markers?.endNode, this.templatePart.childNodes);
-                }
+                const startNode = hydrate ? this.markers.findNestedStartNode('template-part') : undefined;
+                this.templatePart = new TemplatePart(startNode, value);
             } else if (this.templatePart.strings !== value.strings) {
                 // this means we have a different TemplateResult here with maybe different parts also
                 this.templatePart = new TemplatePart(undefined, value);
-                // INFO: this is similar to TemplateResult#237
-                replaceNodesBetweenComments(this.markers?.endNode, this.templatePart.childNodes);
             }
             return this.templatePart;
         }
         if (Array.isArray(value)) {
-            return this.parseArray(value);
+            return this.parseArray(value, hydrate);
         }
         if (value?.nodeType) {
             return value;
         }
-        if (typeof value === 'function') {
-            return this.parseValue(value());
-        }
         if (value === null || value === undefined) {
             return value;
         }
@@ -306,44 +303,32 @@ export class ChildNodePart extends Part {
     }
 
     /**
-     * Nested TemplateResults values need to be unrolled in order for update functions to be able to process them
+     * Creates the template parts for the template items of an array, indexed like the items. A different template at
+     * an index gets a new part, the nodes of the part that was there go away with the diff. Other items (text, nodes)
+     * pass through, functions and nested arrays are resolved before, see update().
      * @param {any[]} values
-     * @return {any[]}
+     * @param {boolean} hydrate
+     * @return {Array<TemplatePart | Node | string>}
      */
-    parseArray(values) {
+    parseArray(values, hydrate = false) {
         const parsedValues = [];
-        for (let index = 0; index < values.length; index++) {
-            let value = values[index];
-
-            // TODO: it would be better to use this.parseValue() here!!!
+        // the server rendered template-part markers directly between this part's markers, one per nested template.
+        // Other values (text, nodes) have no marker, so the templates are counted separately
+        const nestedStartNodes = hydrate ? this.markers.findNestedStartNodes('template-part') : [];
+        let nestedIndex = 0;
 
+        for (let index = 0; index < values.length; index++) {
+            const value = values[index];
             if (value instanceof TemplateResult) {
-                // TODO this is probably wrong. Should only be taken from parts cache if it has the same type (eg. template vs string, mixed types arrays)
                 let templatePart = this.arrayParts[index];
-                if (!templatePart) {
-                    const templatePartCommentNodes = this.markers?.childNodes?.filter(
-                        (node) => node && node.nodeType === COMMENT_NODE && node.data === 'template-part',
-                    );
-                    const startNode = templatePartCommentNodes[index];
-                    templatePart = new TemplatePart(startNode, value);
+                if (!templatePart || templatePart.strings !== value.strings) {
+                    templatePart = new TemplatePart(nestedStartNodes[nestedIndex], value);
                     this.arrayParts[index] = templatePart;
                 }
+                nestedIndex++;
                 parsedValues[index] = templatePart;
-            } else if (Array.isArray(value)) {
-                let childNodePart = this.arrayParts[index];
-                if (!childNodePart) {
-                    // TODO: this seems not correct :( (maybe Template vs DOM Parts !?)
-                    const templatePartCommentNodes = this.markers?.childNodes?.filter(
-                        (node) => node && node.nodeType === COMMENT_NODE && node.data === 'template-part',
-                    );
-                    const startNode = templatePartCommentNodes[index];
-                    childNodePart = new ChildNodePart(startNode, value);
-                    this.arrayParts[index] = childNodePart;
-                }
-                parsedValues[index] = childNodePart;
             } else {
-                // TODO: what if the value from the function is a TemplatePart or an array?! Should we do this first thing?!
-                parsedValues[index] = typeof value === 'function' ? value() : value;
+                parsedValues[index] = value;
             }
         }
 

package/src/dom-parts/Part.js

@@ -5,8 +5,10 @@ export class Part {
     processor = undefined;
 
     /**
+     * Applies a value to the DOM.
      * @abstract
      * @param {TemplateResult | any[] | any} value
+     * @param {boolean} [hydrate] - first update of server rendered DOM, nested parts bind to the server rendered markers
      */
-    update(value) {}
+    update(value, hydrate = false) {}
 }