@repobit/dex-store-elements 1.7.3 → 2.0.0

package/dist/src/eta/template-index.d.ts

@@ -0,0 +1,285 @@
+import type { EtaTemplateIndexOptions, TemplateIndexMutation, TemplateIndexSink, TemplateOperation, TemplateOperationFactory } from './types.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 declare class EtaTemplateIndex<TContext = object> implements Iterable<TemplateOperation<TContext>>, TemplateIndexSink {
+    private readonly _operations;
+    /**
+     * 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.
+     */
+    private _nodeIndex;
+    /**
+     * 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.
+     */
+    private _attrOps;
+    /**
+     * 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.
+     */
+    private _indexedNodes;
+    private readonly factory;
+    private readonly options;
+    private readonly sources;
+    constructor(factory: TemplateOperationFactory<TContext>, options?: EtaTemplateIndexOptions);
+    /**
+     * 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: ParentNode): void;
+    /**
+     * 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: TemplateIndexMutation): boolean;
+    /**
+     * 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(): void;
+    /**
+     * 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(): void;
+    [Symbol.iterator](): Iterator<TemplateOperation<TContext>>;
+    /**
+     * 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(): number;
+    /**
+     * 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: Node): boolean;
+    /**
+     * 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(): void;
+    /**
+     * 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.
+     */
+    private _isForeignBoundary;
+    /**
+     * 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.
+     */
+    private _ownsNode;
+    private _addNode;
+    private _isIndexed;
+    private _collectAttributes;
+    /**
+     * 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.
+     */
+    private _removeNode;
+    private _updateAttribute;
+    private _updateText;
+    private _addTextOperation;
+    private _addAttributeOperation;
+    private _removeAttributeOperation;
+    /**
+     * 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.
+     */
+    private _deleteOperation;
+}