@markuplint/ml-core 5.4.0 → 5.6.0

package/lib/ml-dom/node/node.d.ts

@@ -149,9 +149,14 @@ export declare abstract class MLNode<T extends RuleConfigValue, O extends PlainD
      */
     get baseURI(): string;
     /**
-     * The list of child nodes that contains `Element`, `Text`, and `Comment`.
-     * Fragment nodes and preprocessor blocks with `each` or `end` block behavior
-     * are transparent — their child nodes are flattened into this list.
+     * The list of child nodes. Fragment nodes and preprocessor blocks whose
+     * `blockBehavior.type` is `each` or `end` are flattened into this list.
+     * Conditional blocks (`if`, `switch`, `await`, and their clauses) and
+     * `each:empty` stay in this list: flattening a conditional block would
+     * present elements that never render together as siblings, and would
+     * remove the block nodes `conditionalChildNodes()` uses to enumerate
+     * each branch. A loop body is not an alternative branch, so `each` and
+     * `end` are flattened.
      *
      * @readonly
      * @implements DOM API: `Node`
@@ -244,9 +249,30 @@ export declare abstract class MLNode<T extends RuleConfigValue, O extends PlainD
      * @see https://dom.spec.whatwg.org/#ref-for-dom-node-parentelement%E2%91%A0
      */
     get parentElement(): MLElement<T, O> | null;
+    /**
+     * The parent element in the tree of this node, which is what the DOM calls `parentElement`: `null`
+     * for what is at the top of the content of an HTML `template` element or of a declarative shadow
+     * root, whose {@link MLNode.parentElement} is the `template` element, as the syntax tree has it.
+     * A `template` element that is in no tree has none either.
+     *
+     * The selector engine and `closest()` read it, so that `section p` does not match a `p` in the
+     * content of a `template` in a `section`. {@link MLNode.parentElement} does not stop at that
+     * boundary because the content model of a `template` element is validated against what is in it.
+     *
+     * `getTreeParentElement` of `@markuplint/ml-spec`, which cannot use this getter, derives the same
+     * answer from `getRootNode()` for the algorithms of that package: a change of the boundary here
+     * belongs to it too.
+     *
+     * @implements `@markuplint/ml-core` API: `MLNode`
+     */
+    get treeParentElement(): MLElement<T, O> | null;
     /**
      * The parent node that may be `Element`, `Document`, `DocumentFragment`, and `null`.
      *
+     * A block of a template language is walked through (`MLBlock#isTransparent`): a node in a block
+     * has the node that contains the block as its parent. A node at the top of a fragment document
+     * has none.
+     *
      * ## HTML:
      *
      * ```html
@@ -267,10 +293,10 @@ export declare abstract class MLNode<T extends RuleConfigValue, O extends PlainD
      *
      * ```jsx
      * <> // => null
-     *   <div> // => #document-fragment
+     *   <div> // => <>
      *     {items.map(item => {
      *       return (
-     *         <span /> // => null
+     *         <span /> // => <div>
      *       )
      *     })}
      *   </div>
@@ -284,7 +310,7 @@ export declare abstract class MLNode<T extends RuleConfigValue, O extends PlainD
      * div
      *   //- <div>
      *   if foo
-     *     //- null
+     *     //- <div>
      *     span
      * ```
      *
@@ -334,7 +360,7 @@ export declare abstract class MLNode<T extends RuleConfigValue, O extends PlainD
      *
      * ```jsx
      * <> // => #document
-     *   <div> // => #document-fragment
+     *   <div> // => <>
      *     {items.map(item => {
      *       return (
      *         <span /> // => #ml-block
@@ -425,6 +451,13 @@ export declare abstract class MLNode<T extends RuleConfigValue, O extends PlainD
     /**
      * Returns true if other is an inclusive descendant of node; otherwise false.
      *
+     * What an HTML `template` element holds is its `content`, a tree of its own, so the element does
+     * not contain it, and an element does not contain the content of a `template` under it, so
+     * `contains()` asked of what is outside a template about what is inside it is `false` as well.
+     * That differs from {@link MLNode.parentElement}, which stays the one of the syntax
+     * tree (the `template` element) because the content model of a `template` element is validated
+     * against what the syntax tree puts in it.
+     *
      * @implements DOM API: `Node`
      * @see https://dom.spec.whatwg.org/#ref-for-dom-node-contains%E2%91%A0
      */
@@ -438,7 +471,9 @@ export declare abstract class MLNode<T extends RuleConfigValue, O extends PlainD
      */
     dispatchEvent(event: Event): boolean;
     /**
-     * Finds subsequent nodes that match the given selector.
+     * Finds subsequent nodes that match the given selector, in the tree of this node: what follows in
+     * the markup but is in another tree (the content of an HTML `template` element) is not subsequent
+     * to it.
      *
      * @implements `@markuplint/ml-core` API: `MLNode`
      * @param selector - Optional selector to filter the nodes.
@@ -451,9 +486,16 @@ export declare abstract class MLNode<T extends RuleConfigValue, O extends PlainD
      */
     getPureChildNodes(): NodeListOf<MLChildNode<T, O>>;
     /**
-     * **IT THROWS AN ERROR WHEN CALLING THIS.**
+     * The root of the tree of this node: the document, the content of the nearest HTML `template`
+     * element above it (a declarative shadow root when one is attached to the parent of the `template`),
+     * or this node itself for a document fragment, and for a `template` element that is in no tree.
+     * The syntax tree is followed through what a template engine renders away, so a block of a
+     * template language between the `template` element and this node does not hide the `template`.
      *
-     * @unsupported
+     * With `composed`, a shadow root is followed to its host.
+     *
+     * @param options - `composed` follows a shadow root to its host
+     * @returns The root of the tree
      * @implements DOM API: `Node`
      * @see https://dom.spec.whatwg.org/#ref-for-dom-node-getrootnode%E2%91%A0
      */
@@ -502,6 +544,9 @@ export declare abstract class MLNode<T extends RuleConfigValue, O extends PlainD
      */
     isEqualNode(otherNode: Node | null): boolean;
     /**
+     * Whether the document of this node is a fragment of a document (a partial, a component) and
+     * not a whole one. The parser of the document decides it (`MLDocument#isFragment`).
+     *
      * @implements `@markuplint/ml-core` API: `MLNode`
      */
     isInFragmentDocument(): boolean;

package/lib/ml-dom/node/node.js

@@ -174,9 +174,14 @@ export class MLNode extends MLToken {
         throw new UnexpectedCallError('Not supported "baseURI" property');
     }
     /**
-     * The list of child nodes that contains `Element`, `Text`, and `Comment`.
-     * Fragment nodes and preprocessor blocks with `each` or `end` block behavior
-     * are transparent — their child nodes are flattened into this list.
+     * The list of child nodes. Fragment nodes and preprocessor blocks whose
+     * `blockBehavior.type` is `each` or `end` are flattened into this list.
+     * Conditional blocks (`if`, `switch`, `await`, and their clauses) and
+     * `each:empty` stay in this list: flattening a conditional block would
+     * present elements that never render together as siblings, and would
+     * remove the block nodes `conditionalChildNodes()` uses to enumerate
+     * each branch. A loop body is not an alternative branch, so `each` and
+     * `end` are flattened.
      *
      * @readonly
      * @implements DOM API: `Node`
@@ -321,9 +326,39 @@ export class MLNode extends MLToken {
         }
         return null;
     }
+    /**
+     * The parent element in the tree of this node, which is what the DOM calls `parentElement`: `null`
+     * for what is at the top of the content of an HTML `template` element or of a declarative shadow
+     * root, whose {@link MLNode.parentElement} is the `template` element, as the syntax tree has it.
+     * A `template` element that is in no tree has none either.
+     *
+     * The selector engine and `closest()` read it, so that `section p` does not match a `p` in the
+     * content of a `template` in a `section`. {@link MLNode.parentElement} does not stop at that
+     * boundary because the content model of a `template` element is validated against what is in it.
+     *
+     * `getTreeParentElement` of `@markuplint/ml-spec`, which cannot use this getter, derives the same
+     * answer from `getRootNode()` for the algorithms of that package: a change of the boundary here
+     * belongs to it too.
+     *
+     * @implements `@markuplint/ml-core` API: `MLNode`
+     */
+    get treeParentElement() {
+        const parent = this.parentElement;
+        if (!parent || parent.isHTMLTemplateElement) {
+            return null;
+        }
+        if (this.is(this.ELEMENT_NODE) && this.isInNoTree) {
+            return null;
+        }
+        return parent;
+    }
     /**
      * The parent node that may be `Element`, `Document`, `DocumentFragment`, and `null`.
      *
+     * A block of a template language is walked through (`MLBlock#isTransparent`): a node in a block
+     * has the node that contains the block as its parent. A node at the top of a fragment document
+     * has none.
+     *
      * ## HTML:
      *
      * ```html
@@ -344,10 +379,10 @@ export class MLNode extends MLToken {
      *
      * ```jsx
      * <> // => null
-     *   <div> // => #document-fragment
+     *   <div> // => <>
      *     {items.map(item => {
      *       return (
-     *         <span /> // => null
+     *         <span /> // => <div>
      *       )
      *     })}
      *   </div>
@@ -361,7 +396,7 @@ export class MLNode extends MLToken {
      * div
      *   //- <div>
      *   if foo
-     *     //- null
+     *     //- <div>
      *     span
      * ```
      *
@@ -480,7 +515,7 @@ export class MLNode extends MLToken {
      *
      * ```jsx
      * <> // => #document
-     *   <div> // => #document-fragment
+     *   <div> // => <>
      *     {items.map(item => {
      *       return (
      *         <span /> // => #ml-block
@@ -655,12 +690,22 @@ export class MLNode extends MLToken {
     /**
      * Returns true if other is an inclusive descendant of node; otherwise false.
      *
+     * What an HTML `template` element holds is its `content`, a tree of its own, so the element does
+     * not contain it, and an element does not contain the content of a `template` under it, so
+     * `contains()` asked of what is outside a template about what is inside it is `false` as well.
+     * That differs from {@link MLNode.parentElement}, which stays the one of the syntax
+     * tree (the `template` element) because the content model of a `template` element is validated
+     * against what the syntax tree puts in it.
+     *
      * @implements DOM API: `Node`
      * @see https://dom.spec.whatwg.org/#ref-for-dom-node-contains%E2%91%A0
      */
     contains(
     // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
     other) {
+        if (this.is(this.ELEMENT_NODE) && this.isHTMLTemplateElement) {
+            return false;
+        }
         for (const childNode of this.childNodes) {
             if (other?.uuid === childNode.uuid || childNode.contains(other)) {
                 return true;
@@ -681,7 +726,9 @@ export class MLNode extends MLToken {
         throw new UnexpectedCallError('Not supported "dispatchEvent" method');
     }
     /**
-     * Finds subsequent nodes that match the given selector.
+     * Finds subsequent nodes that match the given selector, in the tree of this node: what follows in
+     * the markup but is in another tree (the content of an HTML `template` element) is not subsequent
+     * to it.
      *
      * @implements `@markuplint/ml-core` API: `MLNode`
      * @param selector - Optional selector to filter the nodes.
@@ -689,6 +736,7 @@ export class MLNode extends MLToken {
      */
     findSubsequentNodes(selector) {
         const matched = [];
+        const root = this.getRootNode();
         for (const node of this.ownerMLDocument.nodeList) {
             if (node.endOffset <= this.endOffset) {
                 continue;
@@ -696,6 +744,9 @@ export class MLNode extends MLToken {
             if (this.contains(node)) {
                 continue;
             }
+            if (node.getRootNode() !== root) {
+                continue;
+            }
             if (selector) {
                 if (node.is(node.ELEMENT_NODE) && node.matches(selector)) {
                     matched.push(node);
@@ -750,19 +801,50 @@ export class MLNode extends MLToken {
         return this.#pureChildNodesCache;
     }
     /**
-     * **IT THROWS AN ERROR WHEN CALLING THIS.**
+     * The root of the tree of this node: the document, the content of the nearest HTML `template`
+     * element above it (a declarative shadow root when one is attached to the parent of the `template`),
+     * or this node itself for a document fragment, and for a `template` element that is in no tree.
+     * The syntax tree is followed through what a template engine renders away, so a block of a
+     * template language between the `template` element and this node does not hide the `template`.
      *
-     * @unsupported
+     * With `composed`, a shadow root is followed to its host.
+     *
+     * @param options - `composed` follows a shadow root to its host
+     * @returns The root of the tree
      * @implements DOM API: `Node`
      * @see https://dom.spec.whatwg.org/#ref-for-dom-node-getrootnode%E2%91%A0
      */
     getRootNode(
     // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
     options) {
-        if (options) {
-            throw new UnexpectedCallError('Not supported options');
+        const root = this.#getTreeRoot();
+        if (options?.composed && root.is(root.DOCUMENT_FRAGMENT_NODE) && 'host' in root) {
+            return root.host.getRootNode(options);
+        }
+        return root;
+    }
+    #treeRoot;
+    #getTreeRoot() {
+        if (this.#treeRoot) {
+            return this.#treeRoot;
+        }
+        this.#treeRoot = this.#findTreeRoot();
+        return this.#treeRoot;
+    }
+    #findTreeRoot() {
+        if (this.is(this.DOCUMENT_NODE) || this.is(this.DOCUMENT_FRAGMENT_NODE)) {
+            return this;
+        }
+        if (this.is(this.ELEMENT_NODE) && this.isInNoTree) {
+            return this;
+        }
+        let ancestor = this.syntacticalParentNode;
+        while (ancestor && !ancestor.is(ancestor.DOCUMENT_NODE)) {
+            if (ancestor.is(ancestor.ELEMENT_NODE) && ancestor.isHTMLTemplateElement) {
+                return ancestor.content ?? this.#ownerDocument;
+            }
+            ancestor = ancestor.syntacticalParentNode;
         }
-        // The original DOM API returns a document fragment if the element is a fragment.
         return this.#ownerDocument;
     }
     /**
@@ -829,6 +911,9 @@ export class MLNode extends MLToken {
         throw new UnexpectedCallError('Not supported "isEqualNode" method');
     }
     /**
+     * Whether the document of this node is a fragment of a document (a partial, a component) and
+     * not a whole one. The parser of the document decides it (`MLDocument#isFragment`).
+     *
      * @implements `@markuplint/ml-core` API: `MLNode`
      */
     isInFragmentDocument() {

package/lib/ml-dom/node/parent-node.d.ts

@@ -15,17 +15,17 @@ export declare abstract class MLParentNode<T extends RuleConfigValue, O extends
     get childElementCount(): number;
     /**
      * @implements DOM API: `Element`, `Document`, `DocumentFragment`
-     * @see https://dom.spec.whatwg.org/#ref-for-dom-parentnode-children%E2%91%A0
+     * @see https://dom.spec.whatwg.org/#dom-parentnode-children
      */
     get children(): HTMLCollectionOf<MLElement<T, O>>;
     /**
      * @implements DOM API: `Element`, `Document`, `DocumentFragment`
-     * @see https://dom.spec.whatwg.org/#ref-for-dom-parentnode-firstelementchild%E2%91%A0
+     * @see https://dom.spec.whatwg.org/#dom-parentnode-firstelementchild
      */
     get firstElementChild(): MLElement<T, O> | null;
     /**
      * @implements DOM API: `Element`, `Document`, `DocumentFragment`
-     * @see https://dom.spec.whatwg.org/#ref-for-dom-parentnode-lastelementchild%E2%91%A0
+     * @see https://dom.spec.whatwg.org/#dom-parentnode-lastelementchild
      */
     get lastElementChild(): MLElement<T, O> | null;
     /**
@@ -33,7 +33,7 @@ export declare abstract class MLParentNode<T extends RuleConfigValue, O extends
      *
      * @unsupported
      * @implements DOM API: `Element`, `Document`, `DocumentFragment`
-     * @see https://dom.spec.whatwg.org/#ref-for-dom-parentnode-append%E2%91%A0
+     * @see https://dom.spec.whatwg.org/#dom-parentnode-append
      */
     append(...nodes: (string | Node)[]): void;
     /**
@@ -41,26 +41,57 @@ export declare abstract class MLParentNode<T extends RuleConfigValue, O extends
      *
      * @unsupported
      * @implements DOM API: `Element`, `Document`, `DocumentFragment`
-     * @see https://dom.spec.whatwg.org/#ref-for-dom-parentnode-prepend%E2%91%A0
+     * @see https://dom.spec.whatwg.org/#dom-parentnode-prepend
      */
     prepend(...nodes: (string | Node)[]): void;
     /**
      * @implements DOM API: `Element`, `Document`, `DocumentFragment`
-     * @see https://dom.spec.whatwg.org/#ref-for-dom-parentnode-queryselector%E2%91%A0
+     * @see https://dom.spec.whatwg.org/#dom-parentnode-queryselector
      */
     querySelector(selectors: string): MLElement<T, O> | null;
     /**
+     * Selects the descendants in the tree order, within the tree of this node: not the elements in
+     * the content of an HTML `template` element, which belong to a tree of their own.
+     *
      * @implements DOM API: `Element`, `Document`, `DocumentFragment`
-     * @see https://dom.spec.whatwg.org/#ref-for-dom-parentnode-queryselectorall%E2%91%A0
+     * @see https://dom.spec.whatwg.org/#dom-parentnode-queryselectorall
      */
     querySelectorAll(selectors: string): NodeListOf<MLElement<T, O>>;
+    /**
+     * Selects the descendants in every tree under this node: the content of an HTML `template`
+     * element (and a declarative shadow root) at any depth as well, and a `template` element that is in
+     * no tree. A selector is matched in the tree of each element, so `section p` does not match a `p`
+     * in the content of a `template` that is in a `section`.
+     *
+     * It is for a rule that must look at every element whatever tree it is in (a restricted element,
+     * a table, a line break), where `querySelectorAll` would leave the content of a `template`
+     * unchecked.
+     *
+     * @implements `@markuplint/ml-core` API: `MLParentNode`
+     * @param selectors - A selector
+     * @returns The matched elements in the order of the markup
+     */
+    deepQuerySelectorAll(selectors: string): readonly MLElement<T, O>[];
+    /**
+     * The first element of the tree whose `id` is `elementId` (the string that the DOM has, with
+     * character references resolved), found through a map that is built once: a rule resolves one
+     * reference per attribute.
+     *
+     * @param elementId - The id
+     * @returns The element, or `null`
+     */
+    protected _getElementById(elementId: string): MLElement<T, O> | null;
     /**
      * **IT THROWS AN ERROR WHEN CALLING THIS.**
      *
      * @unsupported
      * @implements DOM API: `Element`, `Document`, `DocumentFragment`
-     * @see https://dom.spec.whatwg.org/#ref-for-dom-parentnode-replacechildren%E2%91%A0
+     * @see https://dom.spec.whatwg.org/#dom-parentnode-replacechildren
      */
     replaceChildren(...nodes: (string | Node)[]): void;
+    /**
+     * The descendants in the tree order, within the tree of this node (see {@link walkTree}). An
+     * HTML `template` element has none: what it holds is its `content`, a tree of its own.
+     */
     protected _descendantsToArray<N extends MLNode<T, O>>(filter?: (node: MLNode<T, O>) => N | null | void): ReadonlyArray<N>;
 }

package/lib/ml-dom/node/parent-node.js

@@ -1,4 +1,5 @@
-import { syncWalk } from '../helper/walkers.js';
+import { getDOMValue } from '../helper/tree-scope.js';
+import { walkTree } from '../helper/walkers.js';
 import { getChildren } from '../manipulations/get-children.js';
 import { toNodeList } from './node-list.js';
 import { MLNode } from './node.js';
@@ -10,6 +11,8 @@ import { UnexpectedCallError } from '@markuplint/shared';
 export class MLParentNode extends MLNode {
     #children = null;
     #selectedElements = new Map();
+    #deepSelectedElements = new Map();
+    #idMap = null;
     /**
      * @implements DOM API: `Element`, `Document`, `DocumentFragment`
      * @see https://dom.spec.whatwg.org/#dom-parentnode-childelementcount
@@ -19,7 +22,7 @@ export class MLParentNode extends MLNode {
     }
     /**
      * @implements DOM API: `Element`, `Document`, `DocumentFragment`
-     * @see https://dom.spec.whatwg.org/#ref-for-dom-parentnode-children%E2%91%A0
+     * @see https://dom.spec.whatwg.org/#dom-parentnode-children
      */
     get children() {
         if (this.#children) {
@@ -31,24 +34,24 @@ export class MLParentNode extends MLNode {
     }
     /**
      * @implements DOM API: `Element`, `Document`, `DocumentFragment`
-     * @see https://dom.spec.whatwg.org/#ref-for-dom-parentnode-firstelementchild%E2%91%A0
+     * @see https://dom.spec.whatwg.org/#dom-parentnode-firstelementchild
      */
     get firstElementChild() {
-        return this.children[0] ?? null;
+        return this.children.item(0);
     }
     /**
      * @implements DOM API: `Element`, `Document`, `DocumentFragment`
-     * @see https://dom.spec.whatwg.org/#ref-for-dom-parentnode-lastelementchild%E2%91%A0
+     * @see https://dom.spec.whatwg.org/#dom-parentnode-lastelementchild
      */
     get lastElementChild() {
-        return this.children[0] ?? null;
+        return this.children.item(this.children.length - 1);
     }
     /**
      * **IT THROWS AN ERROR WHEN CALLING THIS.**
      *
      * @unsupported
      * @implements DOM API: `Element`, `Document`, `DocumentFragment`
-     * @see https://dom.spec.whatwg.org/#ref-for-dom-parentnode-append%E2%91%A0
+     * @see https://dom.spec.whatwg.org/#dom-parentnode-append
      */
     append(
     // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
@@ -60,7 +63,7 @@ export class MLParentNode extends MLNode {
      *
      * @unsupported
      * @implements DOM API: `Element`, `Document`, `DocumentFragment`
-     * @see https://dom.spec.whatwg.org/#ref-for-dom-parentnode-prepend%E2%91%A0
+     * @see https://dom.spec.whatwg.org/#dom-parentnode-prepend
      */
     prepend(
     // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
@@ -69,15 +72,18 @@ export class MLParentNode extends MLNode {
     }
     /**
      * @implements DOM API: `Element`, `Document`, `DocumentFragment`
-     * @see https://dom.spec.whatwg.org/#ref-for-dom-parentnode-queryselector%E2%91%A0
+     * @see https://dom.spec.whatwg.org/#dom-parentnode-queryselector
      */
     querySelector(selectors) {
         const selected = this.querySelectorAll(selectors);
         return selected[0] ?? null;
     }
     /**
+     * Selects the descendants in the tree order, within the tree of this node: not the elements in
+     * the content of an HTML `template` element, which belong to a tree of their own.
+     *
      * @implements DOM API: `Element`, `Document`, `DocumentFragment`
-     * @see https://dom.spec.whatwg.org/#ref-for-dom-parentnode-queryselectorall%E2%91%A0
+     * @see https://dom.spec.whatwg.org/#dom-parentnode-queryselectorall
      */
     querySelectorAll(selectors) {
         const selected = this.#selectedElements.get(selectors);
@@ -92,21 +98,82 @@ export class MLParentNode extends MLNode {
         this.#selectedElements.set(selectors, elements);
         return elements;
     }
+    /**
+     * Selects the descendants in every tree under this node: the content of an HTML `template`
+     * element (and a declarative shadow root) at any depth as well, and a `template` element that is in
+     * no tree. A selector is matched in the tree of each element, so `section p` does not match a `p`
+     * in the content of a `template` that is in a `section`.
+     *
+     * It is for a rule that must look at every element whatever tree it is in (a restricted element,
+     * a table, a line break), where `querySelectorAll` would leave the content of a `template`
+     * unchecked.
+     *
+     * @implements `@markuplint/ml-core` API: `MLParentNode`
+     * @param selectors - A selector
+     * @returns The matched elements in the order of the markup
+     */
+    deepQuerySelectorAll(selectors) {
+        const selected = this.#deepSelectedElements.get(selectors);
+        if (selected) {
+            return selected;
+        }
+        const elements = [];
+        walkTree([...this.childNodes], node => {
+            if (node.is(node.ELEMENT_NODE) && node.matches(selectors, this)) {
+                elements.push(node);
+            }
+        }, true);
+        const result = Object.freeze(elements);
+        this.#deepSelectedElements.set(selectors, result);
+        return result;
+    }
+    /**
+     * The first element of the tree whose `id` is `elementId` (the string that the DOM has, with
+     * character references resolved), found through a map that is built once: a rule resolves one
+     * reference per attribute.
+     *
+     * @param elementId - The id
+     * @returns The element, or `null`
+     */
+    _getElementById(elementId) {
+        if (!this.#idMap) {
+            const idMap = new Map();
+            for (const el of this._descendantsToArray(node => {
+                if (node.is(node.ELEMENT_NODE)) {
+                    return node;
+                }
+            })) {
+                const id = getDOMValue(el.getAttributeNode('id'));
+                if (id != null && id !== '' && !idMap.has(id)) {
+                    idMap.set(id, el);
+                }
+            }
+            this.#idMap = idMap;
+        }
+        return this.#idMap.get(elementId) ?? null;
+    }
     /**
      * **IT THROWS AN ERROR WHEN CALLING THIS.**
      *
      * @unsupported
      * @implements DOM API: `Element`, `Document`, `DocumentFragment`
-     * @see https://dom.spec.whatwg.org/#ref-for-dom-parentnode-replacechildren%E2%91%A0
+     * @see https://dom.spec.whatwg.org/#dom-parentnode-replacechildren
      */
     replaceChildren(
     // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
     ...nodes) {
         throw new UnexpectedCallError('Not supported "replaceChildren" method');
     }
+    /**
+     * The descendants in the tree order, within the tree of this node (see {@link walkTree}). An
+     * HTML `template` element has none: what it holds is its `content`, a tree of its own.
+     */
     _descendantsToArray(filter) {
+        if (this.is(this.ELEMENT_NODE) && this.isHTMLTemplateElement) {
+            return Object.freeze([]);
+        }
         const nodeList = [];
-        syncWalk([...this.childNodes], node => {
+        walkTree([...this.childNodes], node => {
             if (filter) {
                 const filtered = filter(node);
                 if (filtered) {