eleva 1.2.17-beta → 1.2.19-beta

package/src/modules/Renderer.js

@@ -1,10 +1,26 @@
 "use strict";
 
+/**
+ * A regular expression to match hyphenated lowercase letters.
+ * @private
+ * @type {RegExp}
+ */
+const CAMEL_RE = /-([a-z])/g;
+
 /**
  * @class 🎨 Renderer
- * @classdesc A DOM renderer that handles efficient DOM updates through patching and diffing.
- * Provides methods for updating the DOM by comparing new and old structures and applying
- * only the necessary changes, minimizing layout thrashing and improving performance.
+ * @classdesc A high-performance DOM renderer that implements an optimized direct DOM diffing algorithm.
+ *
+ * Key features:
+ * - Single-pass diffing algorithm for efficient DOM updates
+ * - Key-based node reconciliation for optimal performance
+ * - Intelligent attribute handling for ARIA, data attributes, and boolean properties
+ * - Preservation of special Eleva-managed instances and style elements
+ * - Memory-efficient with reusable temporary containers
+ *
+ * The renderer is designed to minimize DOM operations while maintaining
+ * exact attribute synchronization and proper node identity preservation.
+ * It's particularly optimized for frequent updates and complex DOM structures.
  *
  * @example
  * const renderer = new Renderer();
@@ -14,47 +30,46 @@
  */
 export class Renderer {
   /**
-   * Creates a new Renderer instance with a reusable temporary container for parsing HTML.
+   * Creates a new Renderer instance.
    * @public
    */
   constructor() {
-    /** @private {HTMLElement} Reusable temporary container for parsing new HTML */
+    /**
+     * A temporary container to hold the new HTML content while diffing.
+     * @private
+     * @type {HTMLElement}
+     */
     this._tempContainer = document.createElement("div");
   }
 
   /**
-   * Patches the DOM of a container element with new HTML content.
-   * Efficiently updates the DOM by parsing new HTML into a reusable container
-   * and applying only the necessary changes.
+   * Patches the DOM of the given container with the provided HTML string.
    *
    * @public
    * @param {HTMLElement} container - The container element to patch.
-   * @param {string} newHtml - The new HTML content to apply.
+   * @param {string} newHtml - The new HTML string.
    * @returns {void}
-   * @throws {Error} If container is not an HTMLElement, newHtml is not a string, or patching fails.
+   * @throws {TypeError} If container is not an HTMLElement or newHtml is not a string.
+   * @throws {Error} If DOM patching fails.
    */
   patchDOM(container, newHtml) {
     if (!(container instanceof HTMLElement)) {
-      throw new Error("Container must be an HTMLElement");
+      throw new TypeError("Container must be an HTMLElement");
     }
     if (typeof newHtml !== "string") {
-      throw new Error("newHtml must be a string");
+      throw new TypeError("newHtml must be a string");
     }
 
     try {
-      // Directly set new HTML, replacing any existing content
       this._tempContainer.innerHTML = newHtml;
-
       this._diff(container, this._tempContainer);
-    } catch {
-      throw new Error("Failed to patch DOM");
+    } catch (error) {
+      throw new Error(`Failed to patch DOM: ${error.message}`);
     }
   }
 
   /**
-   * Diffs two DOM trees (old and new) and applies updates to the old DOM.
-   * This method recursively compares nodes and their attributes, applying only
-   * the necessary changes to minimize DOM operations.
+   * Performs a diff between two DOM nodes and patches the old node to match the new node.
    *
    * @private
    * @param {HTMLElement} oldParent - The original DOM element.
@@ -62,94 +77,127 @@ export class Renderer {
    * @returns {void}
    */
   _diff(oldParent, newParent) {
-    if (oldParent.isEqualNode(newParent)) return;
+    if (oldParent === newParent || oldParent.isEqualNode?.(newParent)) return;
 
-    const oldChildren = oldParent.childNodes;
-    const newChildren = newParent.childNodes;
-    const maxLength = Math.max(oldChildren.length, newChildren.length);
+    const oldChildren = Array.from(oldParent.childNodes);
+    const newChildren = Array.from(newParent.childNodes);
+    let oldStartIdx = 0,
+      newStartIdx = 0;
+    let oldEndIdx = oldChildren.length - 1;
+    let newEndIdx = newChildren.length - 1;
+    let oldKeyMap = null;
 
-    for (let i = 0; i < maxLength; i++) {
-      const oldNode = oldChildren[i];
-      const newNode = newChildren[i];
+    while (oldStartIdx <= oldEndIdx && newStartIdx <= newEndIdx) {
+      let oldStartNode = oldChildren[oldStartIdx];
+      let newStartNode = newChildren[newStartIdx];
 
-      if (oldNode?._eleva_instance) {
-        continue;
-      }
+      if (!oldStartNode) {
+        oldStartNode = oldChildren[++oldStartIdx];
+      } else if (this._isSameNode(oldStartNode, newStartNode)) {
+        this._patchNode(oldStartNode, newStartNode);
+        oldStartIdx++;
+        newStartIdx++;
+      } else {
+        if (!oldKeyMap) {
+          oldKeyMap = this._createKeyMap(oldChildren, oldStartIdx, oldEndIdx);
+        }
+        const key = this._getNodeKey(newStartNode);
+        const oldNodeToMove = key ? oldKeyMap.get(key) : null;
 
-      if (!oldNode && newNode) {
-        oldParent.appendChild(newNode.cloneNode(true));
-        continue;
-      }
-      if (oldNode && !newNode) {
-        if (
-          oldNode.nodeName === "STYLE" &&
-          oldNode.hasAttribute("data-e-style")
-        ) {
-          continue;
+        if (oldNodeToMove) {
+          this._patchNode(oldNodeToMove, newStartNode);
+          oldParent.insertBefore(oldNodeToMove, oldStartNode);
+          oldChildren[oldChildren.indexOf(oldNodeToMove)] = null;
+        } else {
+          oldParent.insertBefore(newStartNode.cloneNode(true), oldStartNode);
         }
-        oldParent.removeChild(oldNode);
-        continue;
+        newStartIdx++;
       }
+    }
 
-      const isSameType =
-        oldNode.nodeType === newNode.nodeType &&
-        oldNode.nodeName === newNode.nodeName;
-
-      if (!isSameType) {
-        oldParent.replaceChild(newNode.cloneNode(true), oldNode);
-        continue;
+    if (oldStartIdx > oldEndIdx) {
+      const refNode = newChildren[newEndIdx + 1]
+        ? oldChildren[oldStartIdx]
+        : null;
+      for (let i = newStartIdx; i <= newEndIdx; i++) {
+        if (newChildren[i])
+          oldParent.insertBefore(newChildren[i].cloneNode(true), refNode);
+      }
+    } else if (newStartIdx > newEndIdx) {
+      for (let i = oldStartIdx; i <= oldEndIdx; i++) {
+        if (oldChildren[i]) this._removeNode(oldParent, oldChildren[i]);
       }
+    }
+  }
 
-      if (oldNode.nodeType === Node.ELEMENT_NODE) {
-        const oldKey = oldNode.getAttribute("key");
-        const newKey = newNode.getAttribute("key");
+  /**
+   * Patches a single node.
+   *
+   * @private
+   * @param {Node} oldNode - The original DOM node.
+   * @param {Node} newNode - The new DOM node.
+   * @returns {void}
+   */
+  _patchNode(oldNode, newNode) {
+    if (oldNode?._eleva_instance) return;
 
-        if (oldKey !== newKey && (oldKey || newKey)) {
-          oldParent.replaceChild(newNode.cloneNode(true), oldNode);
-          continue;
-        }
+    if (!this._isSameNode(oldNode, newNode)) {
+      oldNode.replaceWith(newNode.cloneNode(true));
+      return;
+    }
 
-        this._updateAttributes(oldNode, newNode);
-        this._diff(oldNode, newNode);
-      } else if (
-        oldNode.nodeType === Node.TEXT_NODE &&
-        oldNode.nodeValue !== newNode.nodeValue
-      ) {
-        oldNode.nodeValue = newNode.nodeValue;
-      }
+    if (oldNode.nodeType === Node.ELEMENT_NODE) {
+      this._updateAttributes(oldNode, newNode);
+      this._diff(oldNode, newNode);
+    } else if (
+      oldNode.nodeType === Node.TEXT_NODE &&
+      oldNode.nodeValue !== newNode.nodeValue
+    ) {
+      oldNode.nodeValue = newNode.nodeValue;
     }
   }
 
   /**
-   * Updates the attributes of an element to match those of a new element.
-   * Handles special cases for ARIA attributes, data attributes, and boolean properties.
+   * Removes a node from its parent.
+   *
+   * @private
+   * @param {HTMLElement} parent - The parent element containing the node to remove.
+   * @param {Node} node - The node to remove.
+   * @returns {void}
+   */
+  _removeNode(parent, node) {
+    if (node.nodeName === "STYLE" && node.hasAttribute("data-e-style")) return;
+
+    parent.removeChild(node);
+  }
+
+  /**
+   * Updates the attributes of an element to match a new element's attributes.
    *
    * @private
-   * @param {HTMLElement} oldEl - The element to update.
-   * @param {HTMLElement} newEl - The element providing the updated attributes.
+   * @param {HTMLElement} oldEl - The original element to update.
+   * @param {HTMLElement} newEl - The new element to update.
    * @returns {void}
    */
   _updateAttributes(oldEl, newEl) {
     const oldAttrs = oldEl.attributes;
     const newAttrs = newEl.attributes;
 
-    // Update/add new attributes
-    for (const { name, value } of newAttrs) {
+    // Single pass for new/updated attributes
+    for (let i = 0; i < newAttrs.length; i++) {
+      const { name, value } = newAttrs[i];
       if (name.startsWith("@")) continue;
-
       if (oldEl.getAttribute(name) === value) continue;
-
       oldEl.setAttribute(name, value);
 
       if (name.startsWith("aria-")) {
         const prop =
-          "aria" +
-          name.slice(5).replace(/-([a-z])/g, (_, l) => l.toUpperCase());
+          "aria" + name.slice(5).replace(CAMEL_RE, (_, l) => l.toUpperCase());
         oldEl[prop] = value;
       } else if (name.startsWith("data-")) {
         oldEl.dataset[name.slice(5)] = value;
       } else {
-        const prop = name.replace(/-([a-z])/g, (_, l) => l.toUpperCase());
+        const prop = name.replace(CAMEL_RE, (_, l) => l.toUpperCase());
         if (prop in oldEl) {
           const descriptor = Object.getOwnPropertyDescriptor(
             Object.getPrototypeOf(oldEl),
@@ -159,7 +207,6 @@ export class Renderer {
             typeof oldEl[prop] === "boolean" ||
             (descriptor?.get &&
               typeof descriptor.get.call(oldEl) === "boolean");
-
           if (isBoolean) {
             oldEl[prop] =
               value !== "false" &&
@@ -171,11 +218,74 @@ export class Renderer {
       }
     }
 
-    // Remove old attributes
-    for (const { name } of oldAttrs) {
+    // Remove any attributes no longer present
+    for (let i = oldAttrs.length - 1; i >= 0; i--) {
+      const name = oldAttrs[i].name;
       if (!newEl.hasAttribute(name)) {
         oldEl.removeAttribute(name);
       }
     }
   }
+
+  /**
+   * Determines if two nodes are the same based on their type, name, and key attributes.
+   *
+   * @private
+   * @param {Node} oldNode - The first node to compare.
+   * @param {Node} newNode - The second node to compare.
+   * @returns {boolean} True if the nodes are considered the same, false otherwise.
+   */
+  _isSameNode(oldNode, newNode) {
+    if (!oldNode || !newNode) return false;
+
+    const oldKey =
+      oldNode.nodeType === Node.ELEMENT_NODE
+        ? oldNode.getAttribute("key")
+        : null;
+    const newKey =
+      newNode.nodeType === Node.ELEMENT_NODE
+        ? newNode.getAttribute("key")
+        : null;
+
+    if (oldKey && newKey) return oldKey === newKey;
+
+    return (
+      !oldKey &&
+      !newKey &&
+      oldNode.nodeType === newNode.nodeType &&
+      oldNode.nodeName === newNode.nodeName
+    );
+  }
+
+  /**
+   * Creates a key map for the children of a parent node.
+   *
+   * @private
+   * @param {Array<Node>} children - The children of the parent node.
+   * @param {number} start - The start index of the children.
+   * @param {number} end - The end index of the children.
+   * @returns {Map<string, Node>} A key map for the children.
+   */
+  _createKeyMap(children, start, end) {
+    const map = new Map();
+    for (let i = start; i <= end; i++) {
+      const child = children[i];
+      const key = this._getNodeKey(child);
+      if (key) map.set(key, child);
+    }
+    return map;
+  }
+
+  /**
+   * Extracts the key attribute from a node if it exists.
+   *
+   * @private
+   * @param {Node} node - The node to extract the key from.
+   * @returns {string|null} The key attribute value or null if not found.
+   */
+  _getNodeKey(node) {
+    return node?.nodeType === Node.ELEMENT_NODE
+      ? node.getAttribute("key")
+      : null;
+  }
 }

package/src/modules/Signal.js

@@ -5,6 +5,8 @@
  * @classdesc A reactive data holder that enables fine-grained reactivity in the Eleva framework.
  * Signals notify registered watchers when their value changes, enabling efficient DOM updates
  * through targeted patching rather than full re-renders.
+ * Updates are batched using microtasks to prevent multiple synchronous notifications.
+ * The class is generic, allowing type-safe handling of any value type T.
  *
  * @example
  * const count = new Signal(0);
@@ -17,12 +19,12 @@ export class Signal {
    * Creates a new Signal instance with the specified initial value.
    *
    * @public
-   * @param {*} value - The initial value of the signal.
+   * @param {T} value - The initial value of the signal.
    */
   constructor(value) {
-    /** @private {T} Internal storage for the signal's current value, where T is the type of the initial value */
+    /** @private {T} Internal storage for the signal's current value */
     this._value = value;
-    /** @private {Set<function(T): void>} Collection of callback functions to be notified when value changes, where T is the value type */
+    /** @private {Set<(value: T) => void>} Collection of callback functions to be notified when value changes */
     this._watchers = new Set();
     /** @private {boolean} Flag to prevent multiple synchronous watcher notifications and batch updates into microtasks */
     this._pending = false;
@@ -32,7 +34,7 @@ export class Signal {
    * Gets the current value of the signal.
    *
    * @public
-   * @returns {T} The current value, where T is the type of the initial value.
+   * @returns {T} The current value.
    */
   get value() {
     return this._value;
@@ -43,7 +45,7 @@ export class Signal {
    * The notification is batched using microtasks to prevent multiple synchronous updates.
    *
    * @public
-   * @param {T} newVal - The new value to set, where T is the type of the initial value.
+   * @param {T} newVal - The new value to set.
    * @returns {void}
    */
   set value(newVal) {
@@ -58,8 +60,8 @@ export class Signal {
    * The watcher will receive the new value as its argument.
    *
    * @public
-   * @param {function(T): void} fn - The callback function to invoke on value change, where T is the value type.
-   * @returns {function(): boolean} A function to unsubscribe the watcher.
+   * @param {(value: T) => void} fn - The callback function to invoke on value change.
+   * @returns {() => boolean} A function to unsubscribe the watcher.
    * @example
    * const unsubscribe = signal.watch((value) => console.log(value));
    * // Later...
@@ -83,6 +85,7 @@ export class Signal {
 
     this._pending = true;
     queueMicrotask(() => {
+      /** @type {(fn: (value: T) => void) => void} */
       this._watchers.forEach((fn) => fn(this._value));
       this._pending = false;
     });

package/src/modules/TemplateEngine.js

@@ -14,6 +14,7 @@
 export class TemplateEngine {
   /**
    * @private {RegExp} Regular expression for matching template expressions in the format {{ expression }}
+   * @type {RegExp}
    */
   static expressionPattern = /\{\{\s*(.*?)\s*\}\}/g;
 
@@ -24,7 +25,7 @@ export class TemplateEngine {
    * @public
    * @static
    * @param {string} template - The template string to parse.
-   * @param {Object} data - The data context for evaluating expressions.
+   * @param {Record<string, unknown>} data - The data context for evaluating expressions.
    * @returns {string} The parsed template with expressions replaced by their values.
    * @example
    * const result = TemplateEngine.parse("{{user.name}} is {{user.age}} years old", {
@@ -41,12 +42,14 @@ export class TemplateEngine {
   /**
    * Evaluates an expression in the context of the provided data object.
    * Note: This does not provide a true sandbox and evaluated expressions may access global scope.
+   * The use of the `with` statement is necessary for expression evaluation but has security implications.
+   * Expressions should be carefully validated before evaluation.
    *
    * @public
    * @static
    * @param {string} expression - The expression to evaluate.
-   * @param {Object} data - The data context for evaluation.
-   * @returns {*} The result of the evaluation, or an empty string if evaluation fails.
+   * @param {Record<string, unknown>} data - The data context for evaluation.
+   * @returns {unknown} The result of the evaluation, or an empty string if evaluation fails.
    * @example
    * const result = TemplateEngine.evaluate("user.name", { user: { name: "John" } }); // Returns: "John"
    * const age = TemplateEngine.evaluate("user.age", { user: { age: 30 } }); // Returns: 30