@repobit/dex-store-elements 1.7.2 → 2.0.0

package/dist/src/eta/template-index.js

@@ -0,0 +1,642 @@
+// src/eta/template-index.ts
+import { createEtaTemplateSourceRegistry } from './source-registry.js';
+/**
+ * The EtaTemplateIndex maintains the set of renderable operations for a
+ * scoped boundary.
+ *
+ * It is Eta-agnostic. Discovery is delegated to a TemplateOperationFactory
+ * which returns either an operation or `undefined`. The index simply stores
+ * whatever the factory produces and looks it up by node for incremental
+ * updates.
+ *
+ * Three views of the data are kept in sync:
+ *
+ * - `operations` — a flat Set of operations iterated during render.
+ * - `nodeIndex` — a WeakMap from owning node (Element or Text) to the
+ *   operations that own it, used for O(1) removal.
+ * - `attrOps` — a WeakMap from Element to a Map of `attributeName` to the
+ *   single operation that targets that attribute. Needed because Attr
+ *   identity is unstable across `setAttribute` calls — looking up by the
+ *   current Attr reference would never find the previous operation.
+ *
+ * Boundary handling is configurable through an injected predicate
+ * (`EtaTemplateIndexOptions.isBoundaryElement`). The index itself does
+ * not own boundary semantics — it asks the host/controller for a
+ * decision. That makes boundary detection work consistently across
+ * controllers that share the same root but own different indices.
+ *
+ * Source preservation is delegated to an
+ * `EtaTemplateSourceRegistry` so the factory can re-read original
+ * template sources after a render has overwritten the DOM value.
+ *
+ * **Cross-scope source registry limitation.** Each `EtaTemplateIndex`
+ * owns the source registry it created in its constructor
+ * (`createEtaTemplateSourceRegistry()`). Moving a rendered
+ * template node from one scope to another loses the original
+ * template source — the destination index's registry has no
+ * record of it, so the factory falls back to the live DOM value,
+ * which now holds the rendered string rather than the template
+ * literal. The destination index cannot recreate the operation
+ * without discovering the new template content externally.
+ *
+ * Applications that need to reparent rendered template nodes
+ * across scopes should share a single
+ * `EtaTemplateSourceRegistry` between the affected indices.
+ * Because the factory is stateless at the call site (the
+ * registry is threaded through every call via
+ * `TemplateOperationContext`), two indices can share one factory
+ * safely — each just passes the shared registry as the
+ * `sources` field on every call. The v4 review recommends
+ * keeping this limitation documented unless cross-scope DOM
+ * moves become a real use case — at which point the
+ * index/controller can grow a `sourceRegistry` option that
+ * overrides the per-index `createEtaTemplateSourceRegistry()`
+ * default.
+ */
+export class EtaTemplateIndex {
+    constructor(factory, options = {}) {
+        this._operations = new Set();
+        /**
+         * Per-node operation lookup.
+         *
+         * Reassignable so `clear()` can fully reset the index even though
+         * `WeakMap` cannot be cleared. The old map is reclaimed by the GC
+         * as soon as no caller holds it.
+         */
+        this._nodeIndex = new WeakMap();
+        /**
+         * Per-element, per-attribute-name operation lookup.
+         *
+         * `Attr` identity is not stable across DOM mutations (`setAttribute`
+         * removes the old Attr and inserts a new one), so we cannot key attribute
+         * operations by their Attr reference. Instead we key by the owning
+         * element + the attribute's qualified name. Each (element, name) pair
+         * owns at most one operation because the factory only ever produces one
+         * AttributeOperation per attribute.
+         */
+        this._attrOps = new WeakMap();
+        /**
+         * Tracks nodes that have at least one operation associated with them.
+         *
+         * `WeakSet` cannot be iterated and cannot be cleared, so it is
+         * reassigned by `clear()`. It only needs `add` / `has` / `delete`,
+         * which `WeakSet` supports.
+         */
+        this._indexedNodes = new WeakSet();
+        this.factory = factory;
+        this.options = options;
+        this.sources = createEtaTemplateSourceRegistry();
+        // The source registry is threaded through every factory call
+        // via the `TemplateOperationContext` parameter, NOT wired into
+        // the factory itself. That keeps the factory stateless at the
+        // call site and makes factory reuse across indices safe — the
+        // last constructor to call a registry setter no longer wins,
+        // because there is no setter to call. See `_addNode`,
+        // `_collectAttributes`, `_updateAttribute`, and `_updateText`
+        // for the call sites that pass `{ sources: this.sources }`.
+    }
+    /**
+     * Walks the subtree of `root` and indexes every node that contains a
+     * template.
+     *
+     * The walk is implemented by `_addNode`, which descends into
+     * descendants and respects the `isBoundaryElement` predicate. The
+     * root element is added first so a root element's own attribute
+     * templates are indexed even when it has no child nodes.
+     *
+     * Boundary semantics:
+     *
+     * - If `root` itself matches `isBoundaryElement`, it is still
+     *   indexed as the local boundary. Its own attribute templates and
+     *   its owned descendants are collected.
+     * - If a nested element matches `isBoundaryElement`, the walk
+     *   neither collects the foreign boundary's own attributes nor
+     *   descends into the foreign boundary's subtree. Outer
+     *   controllers leave that subtree entirely to the boundary's
+     *   own controller.
+     *
+     * ⚠️ **Stable-on-raw-DOM invariant for nested boundaries.**
+     * When `initialize` encounters a nested boundary element, the
+     * `isBoundaryElement` predicate MUST classify it as a foreign
+     * boundary **without** relying on prototype-side state such as
+     * `instanceof BdScopedElement` or a runtime brand. The parent
+     * index may scan a subtree before a nested custom element has
+     * upgraded; in that window the nested element has not yet been
+     * augmented with the brand, and a brand-only predicate would
+     * fail to classify it as a boundary. No DOM mutation fires when
+     * the upgrade completes, so the parent index would keep the
+     * wrong operations for the lifetime of the page. Prefer
+     * tag-name or marker-attribute checks so the classification is
+     * stable from the moment the element is parsed. See
+     * `EtaTemplateIndexOptions.isBoundaryElement` for full
+     * rationale and example patterns.
+     *
+     * ⚠️ **Source preservation trust boundary.** `initialize()`
+     * assumes external DOM edits have been observed while the
+     * index was online. During normal operation the
+     * `MutationObserver` keeps the `EtaTemplateSourceRegistry` in
+     * sync via `syncTextSource()` / `syncAttributeSource()`. If
+     * external code mutates already-rendered template nodes while
+     * the controller is disconnected or the index has been cleared
+     * (for example between two `clear()` / `initialize()` cycles),
+     * the registry can hand back a stale preserved source and the
+     * next render will re-emit the old template literal instead of
+     * the new DOM value. Callers in that situation should `reset()`
+     * (which also clears the source registry) before
+     * re-initializing, or otherwise clear the registry themselves.
+     */
+    initialize(root) {
+        this.clear();
+        this._addNode(root);
+    }
+    /**
+     * Applies a single mutation to the index.
+     *
+     * Returns `true` when the index actually changed as a result of
+     * the mutation (an operation was added, replaced, or removed);
+     * `false` when the mutation was a no-op for this index because
+     * the node was outside the root, inside a foreign boundary, or
+     * did not contain a template.
+     *
+     * Mutation semantics:
+     *
+     * - `add` walks the node and its descendants.
+     * - `remove` drops every operation whose owner is the node or one of its
+     *   descendants.
+     * - `attribute` re-runs attribute discovery on a single attribute of an
+     *   element that is already part of the index.
+     * - `text` re-runs text discovery on a text node that is already part
+     *   of the index.
+     */
+    apply(mutation) {
+        switch (mutation.type) {
+            case 'add':
+                return this._addNode(mutation.node);
+            case 'remove':
+                return this._removeNode(mutation.node);
+            case 'attribute':
+                return this._updateAttribute(mutation.element, mutation.attribute);
+            case 'text':
+                return this._updateText(mutation.node);
+            // Exhaustive guard: if a new mutation variant is added,
+            // TypeScript flags this `_exhaustive` assignment as a
+            // type error until the new variant is handled here.
+            default: {
+                const _exhaustive = mutation;
+                return _exhaustive;
+            }
+        }
+    }
+    /**
+     * Drops every operation from the index and forgets every node.
+     *
+     * Every internal structure — including the `WeakMap` / `WeakSet`
+     * instances — is reassigned so the index returns to a fully empty
+     * state. The old `WeakMap` / `WeakSet` references become unreachable
+     * as soon as `clear()` returns and the GC reclaims them.
+     *
+     * **Source registry is intentionally preserved.** The
+     * `EtaTemplateSourceRegistry` keeps the original template source
+     * strings for the live DOM nodes so the factory can re-render the
+     * same nodes after a render has overwritten their text / attribute
+     * values. Clearing the registry here would make
+     * `clear()` + `initialize()` destructive on already-rendered
+     * DOM — the next render would see plain text instead of the
+     * original template literal. Callers that explicitly want a
+     * fully destructive reset should use `reset()` instead, which
+     * also clears the source registry.
+     */
+    clear() {
+        for (const op of this._operations) {
+            op.dispose();
+        }
+        this._operations.clear();
+        this._nodeIndex = new WeakMap();
+        this._attrOps = new WeakMap();
+        this._indexedNodes = new WeakSet();
+    }
+    /**
+     * Fully destructive reset — equivalent to `clear()` plus clearing
+     * the `EtaTemplateSourceRegistry`.
+     *
+     * Use this when the live DOM no longer reflects the original
+     * template sources (for example, because external code mutated
+     * already-rendered nodes while the index was offline, or the
+     * caller is switching to a completely different template set).
+     *
+     * After `reset()`, the next `initialize(root)` walks the subtree
+     * from scratch using whatever is in the DOM at that moment —
+     * the registry will not serve a stale preserved source.
+     *
+     * For normal `clear()` + `initialize()` cycles where the source
+     * strings are still valid, prefer `clear()` so the registry
+     * survives re-indexing.
+     */
+    reset() {
+        this.clear();
+        this.sources.clear();
+    }
+    [Symbol.iterator]() {
+        return this._operations.values();
+    }
+    /**
+     * Number of operations currently held by the index.
+     *
+     * Useful for tests and diagnostics. The renderer iterates operations
+     * directly and does not need this.
+     */
+    get size() {
+        return this._operations.size;
+    }
+    /**
+     * Whether the given node has any operation associated with it.
+     *
+     * Used by the controller to decide if a mutation is interesting.
+     *
+     * For text nodes this checks whether any operation is keyed on the node.
+     * For elements this returns true if the element owns any operation
+     * directly (e.g. its attributes) — `hasNode(element)` does NOT imply
+     * "this element has been fully indexed", only "this element owns at
+     * least one operation".
+     */
+    hasNode(node) {
+        if (this._indexedNodes.has(node)) {
+            return true;
+        }
+        if (node.nodeType === Node.ELEMENT_NODE) {
+            return this._attrOps.has(node);
+        }
+        return false;
+    }
+    /**
+     * Disposes every operation currently held by the index.
+     *
+     * The default operations are no-ops for dispose, but custom
+     * operations may need to release observers. Calling this from the
+     * controller's teardown keeps the lifecycle clean.
+     *
+     * Delegates to `clear()` so disposal and reset happen through one
+     * well-defined code path; this also avoids disposing each
+     * operation twice.
+     */
+    disposeAll() {
+        this.clear();
+    }
+    /**
+     * Returns `true` when `element` matches the configured
+     * `isBoundaryElement` predicate AND is a foreign boundary (i.e. is
+     * not the index's own root).
+     *
+     * The root itself is always walked; only nested boundaries stop the
+     * traversal.
+     */
+    _isForeignBoundary(element) {
+        if (this.options.root !== undefined &&
+            element === this.options.root) {
+            return false;
+        }
+        return (this.options.isBoundaryElement?.(element) === true);
+    }
+    /**
+     * Returns `true` when `node` belongs to this index's root.
+     *
+     * The walk climbs ancestors looking for either `root` or a foreign
+     * boundary. If the walk reaches `root` without hitting a foreign
+     * boundary, the node is owned. If the walk hits a foreign boundary
+     * first, the node is not owned.
+     *
+     * When `root` is not configured, the index accepts every mutation
+     * it receives — callers that wire a parent observer MUST set
+     * `root` to prevent nested-scope leakage.
+     *
+     * Foreign-boundary element itself: when the target `node` is a
+     * boundary element other than the index's own `root`, it is owned
+     * by another controller. The check is performed up-front so the
+     * ancestor loop only handles descendants and the `current !==
+     * node` guard it used to need can go away.
+     */
+    _ownsNode(node) {
+        const root = this.options.root;
+        if (root === undefined) {
+            return true;
+        }
+        // Shadow-DOM index: a node belongs to this index when the
+        // ancestor chain reaches the configured shadow root before
+        // climbing out at the shadow host.
+        //
+        // `getRootNode()` alone is not sufficient because a foreign
+        // boundary element nested deeper inside the shadow can sit
+        // between `node` and the shadow root — the foreign boundary
+        // belongs to a different controller, so this index must not
+        // claim it. Walking `parentNode` upward also catches the
+        // shadow-host case: the host's `parentNode` chain leaves the
+        // shadow tree entirely, so the walk terminates at `null`
+        // without ever reaching `root`.
+        //
+        // Foreign-boundary predicates are also consulted at each
+        // step so a nested element whose `getRootNode()` is still
+        // `root` but which `isBoundaryElement` classifies as a
+        // foreign boundary is correctly excluded — matching the
+        // light-DOM branch's behaviour below.
+        if (root instanceof ShadowRoot) {
+            let current = node;
+            while (current !== null) {
+                if (current === root) {
+                    return true;
+                }
+                // Foreign boundary nested inside this shadow — owned by
+                // another controller even though `getRootNode()` still
+                // returns this shadow root. `current` is narrowed to
+                // `Element` here and `root` is a `ShadowRoot` (we are in
+                // the `root instanceof ShadowRoot` branch), so the two
+                // are disjoint types — the explicit `current !== root`
+                // check is unnecessary and would be flagged as
+                // unintentional.
+                if (current instanceof Element &&
+                    this.options.isBoundaryElement?.(current) === true) {
+                    return false;
+                }
+                current = current.parentNode;
+            }
+            return false;
+        }
+        if (node instanceof Element &&
+            node !== root &&
+            this.options.isBoundaryElement?.(node) === true) {
+            return false;
+        }
+        let current = node;
+        while (current) {
+            if (current === root) {
+                return true;
+            }
+            if (current instanceof Element &&
+                current !== root &&
+                this.options.isBoundaryElement?.(current) === true) {
+                return false;
+            }
+            current = current.parentNode;
+        }
+        return false;
+    }
+    _addNode(node) {
+        // Refuse to walk into nodes that are not part of the root's owned
+        // subtree. Observer feedback can deliver `add` mutations for
+        // nested scope elements or sibling trees that the parent index
+        // does not own — the index must ignore them.
+        if (!this._ownsNode(node)) {
+            return false;
+        }
+        if (this._isIndexed(node)) {
+            // Already indexed. Avoid double-processing the same node.
+            return false;
+        }
+        if (node.nodeType === Node.TEXT_NODE) {
+            const op = this.factory.createTextOperation(node, { sources: this.sources });
+            if (op) {
+                this._addTextOperation(node, op);
+                return true;
+            }
+            return false;
+        }
+        // `ShadowRoot` (and any `DocumentFragment`-shaped root passed
+        // to `initialize()`) is not itself a template target — it is
+        // a container. Descend into its children and index each one.
+        if (node instanceof DocumentFragment) {
+            for (const child of Array.from(node.childNodes)) {
+                this._addNode(child);
+            }
+            return false;
+        }
+        if (node.nodeType !== Node.ELEMENT_NODE) {
+            return false;
+        }
+        const element = node;
+        // Foreign-boundary check happens BEFORE attribute collection so a
+        // nested boundary element is fully skipped. The boundary's own
+        // controller owns both its attributes and its descendants — a
+        // parent index must not collect either.
+        if (this._isForeignBoundary(element)) {
+            return false;
+        }
+        const beforeSize = this._operations.size;
+        this._collectAttributes(element);
+        for (const child of Array.from(element.childNodes)) {
+            this._addNode(child);
+        }
+        return this._operations.size !== beforeSize;
+    }
+    _isIndexed(node) {
+        if (this._indexedNodes.has(node)) {
+            return true;
+        }
+        if (node.nodeType === Node.ELEMENT_NODE) {
+            return this._attrOps.has(node);
+        }
+        return false;
+    }
+    _collectAttributes(element) {
+        const context = { sources: this.sources };
+        for (const attr of Array.from(element.attributes)) {
+            const op = this.factory.createAttributeOperation(element, attr, context);
+            if (!op) {
+                continue;
+            }
+            this._addAttributeOperation(element, attr.name, op);
+        }
+    }
+    /**
+     * Removes every operation that targets `node` or one of its descendants.
+     *
+     * The walk mirrors `_addNode` but does not need to consult the factory.
+     * Returns `true` when at least one operation was disposed by the
+     * call.
+     */
+    _removeNode(node) {
+        let removed = false;
+        const owned = this._nodeIndex.get(node);
+        if (owned) {
+            for (const op of owned) {
+                if (this._deleteOperation(op)) {
+                    removed = true;
+                }
+            }
+            this._nodeIndex.delete(node);
+        }
+        this._indexedNodes.delete(node);
+        if (node.nodeType === Node.ELEMENT_NODE) {
+            const element = node;
+            // Drop any attribute operations owned by this element. The
+            // per-attribute map is authoritative for attribute lookup, so we
+            // must clear it here.
+            const byName = this._attrOps.get(element);
+            if (byName) {
+                for (const op of byName.values()) {
+                    if (this._deleteOperation(op)) {
+                        removed = true;
+                    }
+                }
+                this._attrOps.delete(element);
+            }
+            for (const child of Array.from(element.childNodes)) {
+                if (this._removeNode(child)) {
+                    removed = true;
+                }
+            }
+        }
+        return removed;
+    }
+    _updateAttribute(element, attribute) {
+        if (!this._ownsNode(element)) {
+            return false;
+        }
+        // Sync the registry with the current DOM value before re-running
+        // discovery so an external mutation that turned a template into
+        // plain text is reflected (the registry must not serve a stale
+        // preserved source).
+        this.sources.syncAttributeSource(element, attribute);
+        // Drop the previous operation for this (element, name) pair. The
+        // Attr reference is unstable across mutations, so we key by element
+        // + name via `_attrOps` rather than by Attr. We capture the return
+        // value because the contract for `apply()` requires this method
+        // to report the index actually changed — even if no replacement
+        // attribute is found, removing the old operation IS a change.
+        const removed = this._removeAttributeOperation(element, attribute);
+        // Resolve the current Attr for the new value. If the attribute was
+        // removed entirely there is nothing to re-create.
+        const attr = element.attributes.getNamedItem(attribute);
+        if (!attr) {
+            return removed;
+        }
+        const op = this.factory.createAttributeOperation(element, attr, { sources: this.sources });
+        if (!op) {
+            // The new attribute value is not a template (e.g. external
+            // code replaced `{{ url }}` with plain text). The old
+            // operation, if any, was already removed above — return
+            // whether that removal actually happened so callers see an
+            // accurate dirty signal.
+            return removed;
+        }
+        this._addAttributeOperation(element, attribute, op);
+        return true;
+    }
+    _updateText(node) {
+        if (!this._ownsNode(node)) {
+            return false;
+        }
+        // Sync the registry with the current DOM value before re-running
+        // discovery. External mutations that turn a template into plain
+        // text must not leave the registry holding a stale preserved
+        // source.
+        this.sources.syncTextSource(node);
+        // Capture whether the previous text operation was actually
+        // removed. The contract for `apply()` requires this method to
+        // report the index actually changed — even if no replacement
+        // text operation is created, dropping the old one IS a change.
+        let removed = false;
+        const owned = this._nodeIndex.get(node);
+        if (owned) {
+            for (const op of owned) {
+                if (op.kind === 'text') {
+                    if (this._deleteOperation(op)) {
+                        removed = true;
+                    }
+                }
+            }
+            const remaining = new Set();
+            for (const op of owned) {
+                if (this._operations.has(op)) {
+                    remaining.add(op);
+                }
+            }
+            if (remaining.size === 0) {
+                this._nodeIndex.delete(node);
+                this._indexedNodes.delete(node);
+            }
+            else {
+                this._nodeIndex.set(node, remaining);
+            }
+        }
+        const op = this.factory.createTextOperation(node, { sources: this.sources });
+        if (!op) {
+            // The new value is not a template (e.g. external code replaced
+            // `{{ name }}` with plain text). The previous text operation,
+            // if any, was already removed above — return whether that
+            // removal actually happened so callers see an accurate dirty
+            // signal.
+            return removed;
+        }
+        this._addTextOperation(node, op);
+        return true;
+    }
+    _addTextOperation(node, operation) {
+        this._operations.add(operation);
+        const owned = this._nodeIndex.get(node) ??
+            new Set();
+        owned.add(operation);
+        this._nodeIndex.set(node, owned);
+        this._indexedNodes.add(node);
+    }
+    _addAttributeOperation(element, name, operation) {
+        this._operations.add(operation);
+        // Register the operation under both the element and the
+        // (element, name) pair. `_nodeIndex` lets `hasNode(element)` and
+        // `_removeNode(element)` find the operation via element identity;
+        // `_attrOps` lets `_updateAttribute` find the previous op by name
+        // even after the Attr reference changes.
+        const owned = this._nodeIndex.get(element) ??
+            new Set();
+        owned.add(operation);
+        this._nodeIndex.set(element, owned);
+        this._indexedNodes.add(element);
+        let byName = this._attrOps.get(element);
+        if (!byName) {
+            byName = new Map();
+            this._attrOps.set(element, byName);
+        }
+        byName.set(name, operation);
+    }
+    _removeAttributeOperation(element, name) {
+        const byName = this._attrOps.get(element);
+        if (!byName) {
+            return false;
+        }
+        const op = byName.get(name);
+        if (!op) {
+            return false;
+        }
+        this._deleteOperation(op);
+        byName.delete(name);
+        if (byName.size === 0) {
+            this._attrOps.delete(element);
+        }
+        const owned = this._nodeIndex.get(element);
+        if (owned) {
+            owned.delete(op);
+            if (owned.size === 0) {
+                this._nodeIndex.delete(element);
+                this._indexedNodes.delete(element);
+            }
+        }
+        return true;
+    }
+    /**
+     * Removes `operation` from the live `_operations` set and calls its
+     * `dispose()` hook.
+     *
+     * Returns `true` when the operation was actually present and
+     * removed, `false` when it had already been removed by a previous
+     * path (idempotent removal).
+     *
+     * Single entry point used by every removal path so the disposal
+     * contract is honoured uniformly.
+     */
+    _deleteOperation(operation) {
+        if (!this._operations.delete(operation)) {
+            return false;
+        }
+        operation.dispose();
+        return true;
+    }
+}
+//# sourceMappingURL=template-index.js.map