@markuplint/ml-core 5.4.0 → 5.6.0

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

@@ -1,12 +1,13 @@
 import { exchangeValueOnRule, mergeRule } from '@markuplint/ml-config';
-import { schemaToSpec, getComputedRole, mayBeFocusable, getComputedAriaProps, isExposed, getSpecByTagName, ARIA_RECOMMENDED_VERSION, } from '@markuplint/ml-spec';
+import { schemaToSpec, getComputedRole, mayBeFocusable, getComputedAriaProps, isExposed, isShadowRoot, getSpecByTagName, ARIA_RECOMMENDED_VERSION, } from '@markuplint/ml-spec';
 import { ConfigParserError, isComponentName } from '@markuplint/parser-utils';
 import { InvalidSelectorError } from '@markuplint/selector';
 import { log as coreLog } from '../../debug.js';
+import { searchNodeAtLocation } from '../../utils/search-node-at-location.js';
 import { createNode } from '../helper/create-node.js';
 import { nodeListToDebugMaps } from '../helper/debug.js';
 import { sequentialWalker, syncWalk } from '../helper/walkers.js';
-import { nodeListToHTMLCollection } from './node-list.js';
+import { nodeListToHTMLCollection, toHTMLCollection } from './node-list.js';
 import { MLParentNode } from './parent-node.js';
 import { RuleMapper } from './rule-mapper.js';
 import { UnexpectedCallError } from '@markuplint/shared';
@@ -36,6 +37,23 @@ export class MLDocument extends MLParentNode {
      * @default false
      */
     booleanish;
+    /**
+     * The language of the code that an attribute value is written in when it is written as code
+     * (`MLParser#attrExpressionLanguage`). Absent when the parser does not say; then no attribute
+     * value of the document is read as a literal (a pretender's attribute is, whatever it says).
+     */
+    attrExpressionLanguage;
+    /**
+     * How the framework of the parser renders a literal in an attribute value, where it differs from
+     * the default (`MLParser#literalValues`). What the spec says (`MLMLSpec#literalValues`) wins over
+     * this.
+     */
+    literalValues;
+    /**
+     * What the `slot` element is in the language of the document (`MLParser#slotElement`): the HTML
+     * element, or the placeholder of a framework's component, whose slot assignment is not computed.
+     */
+    slotElement;
     /**
      * The rule currently being evaluated during a lint pass.
      * Set by the linting engine before rule evaluation begins and used by nodes
@@ -145,6 +163,9 @@ export class MLDocument extends MLParentNode {
         this.isFragment = ast.isFragment;
         this.specs = schemaToSpec(schemas);
         this.booleanish = options?.booleanish ?? false;
+        this.attrExpressionLanguage = options?.attrExpressionLanguage;
+        this.literalValues = options?.literalValues;
+        this.slotElement = options?.slotElement ?? 'html';
         this.endTag = options?.endTag ?? 'omittable';
         this.#filename = options?.filename;
         this.tagNameCaseSensitive = options?.tagNameCaseSensitive ?? false;
@@ -165,8 +186,10 @@ export class MLDocument extends MLParentNode {
             return createNode(astNode, this);
         })
             .filter((n) => !!n));
-        this.#pretending(options?.pretenders);
+        // A selector of the configuration is matched here, by a pretender and by a rule, so an
+        // invalid one is the fault of the configuration in both.
         try {
+            this.#pretending(options?.pretenders);
             this.#ruleMapping(ruleset);
         }
         catch (error) {
@@ -2119,7 +2142,16 @@ export class MLDocument extends MLParentNode {
         const focusable = mayBeFocusable(node, node.ownerMLDocument.specs);
         const nameRequired = role.role?.accessibleNameRequired ?? false;
         const nameProhibited = role.role?.accessibleNameProhibited ?? false;
-        const hasSlot = !!node.querySelector('slot');
+        // A slot whose assignment is known is read by `getAccessibleName` above. The slot of a shadow root is in
+        // a tree of its own, so every tree is searched, except the content of an ordinary `template` element,
+        // which is not rendered where it is written.
+        const hasSlot = node.deepQuerySelectorAll('slot').some(slot => {
+            if (slot.getAssignedNodes() !== null) {
+                return false;
+            }
+            const root = slot.getRootNode();
+            return isShadowRoot(root) || !root.is(root.DOCUMENT_FRAGMENT_NODE);
+        });
         aria.role = role.role?.name;
         aria.nameRequired = nameRequired;
         aria.nameProhibited = nameProhibited;
@@ -2154,19 +2186,29 @@ export class MLDocument extends MLParentNode {
         throw new UnexpectedCallError('Not supported "getAnimations" method');
     }
     /**
+     * The first element of the tree of the document whose id is `elementId`, with the character
+     * references in the markup resolved: not in the content of an HTML `template` element, which is a
+     * tree of its own.
+     *
      * @implements DOM API: `Document`
+     * @see https://dom.spec.whatwg.org/#dom-nonelementparentnode-getelementbyid
      */
     getElementById(elementId) {
-        return this.querySelector(`#${elementId}`);
+        return this._getElementById(elementId);
     }
     /**
-     * **IT THROWS AN ERROR WHEN CALLING THIS.**
-     *
-     * @unsupported
      * @implements DOM API: `Document`
+     * @see https://dom.spec.whatwg.org/#concept-getelementsbyclassname
      */
     getElementsByClassName(classNames) {
-        return nodeListToHTMLCollection(this.querySelectorAll(classNames));
+        const names = classNames.split(/[\t\n\f\r ]+/).filter(Boolean);
+        return toHTMLCollection(names.length === 0
+            ? []
+            : this._descendantsToArray(node => {
+                if (node.is(node.ELEMENT_NODE) && names.every(name => node.classList.contains(name))) {
+                    return node;
+                }
+            }));
     }
     /**
      * **IT THROWS AN ERROR WHEN CALLING THIS.**
@@ -2178,10 +2220,12 @@ export class MLDocument extends MLParentNode {
         throw new UnexpectedCallError('Not supported "getElementsByName" method');
     }
     /**
-     * **IT THROWS AN ERROR WHEN CALLING THIS.**
+     * The elements of the tree of the document that a type selector of that name matches, so that a
+     * name is compared as a selector compares it in the language of the document (the case, and a
+     * component that a pretender stands for), not as the DOM compares a tag name.
      *
-     * @unsupported
      * @implements DOM API: `Document`
+     * @see https://dom.spec.whatwg.org/#concept-getelementsbytagname
      */
     getElementsByTagName(qualifiedName) {
         return nodeListToHTMLCollection(this.querySelectorAll(qualifiedName));
@@ -2312,18 +2356,17 @@ export class MLDocument extends MLParentNode {
     /**
      * Searches for a node at the given source location (line and column).
      *
+     * The node is the innermost one whose source range, from its start, included,
+     * to its end, excluded, holds the position; a position in an end tag is its
+     * element. The rule is `searchNodeAtLocation`'s.
+     *
      * @implements `@markuplint/ml-core` API: `MLDocument`
      * @param line - The 1-based line number to search at
      * @param col - The 1-based column number to search at
      * @returns The node at the given location, or null if not found
      */
     searchNodeByLocation(line, col) {
-        for (const node of this.nodeList) {
-            if (node.startLine <= line && line <= node.endLine && node.startCol <= col && col <= node.endCol) {
-                return node;
-            }
-        }
-        return null;
+        return searchNodeAtLocation(this.nodeList, line, col);
     }
     /**
      * Sets the currently active rule for this document. Called by the linting engine

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

@@ -114,14 +114,39 @@ export class MLDomTokenList extends Array {
             if (startOffset === -1) {
                 continue;
             }
+            // The value is what code results in (`{"a b"}`), not the text of the source: an offset in it is the offset in
+            // the source only for a string of the same characters in quotes, where the quote is one character before the
+            // value. For an escape, a wrapper or another notation, the token is reported at the start of the value.
+            const base = ownerAttr.valueNode;
+            let shift = 0;
+            if (ownerAttr.isExpressionValue && ownerAttr.valueNode) {
+                const raw = ownerAttr.valueNode.raw;
+                const quote = raw[0];
+                const isPlainString = raw.length >= 2 &&
+                    (quote === '"' || quote === "'" || quote === '`') &&
+                    raw.endsWith(quote) &&
+                    raw.slice(1, -1) === this.#origin;
+                if (!isPlainString) {
+                    return {
+                        raw: token,
+                        startOffset: ownerAttr.valueNode.startOffset,
+                        startLine: ownerAttr.valueNode.startLine,
+                        startCol: ownerAttr.valueNode.startCol,
+                        rule: ownerAttr.rule,
+                        _searchedIndex: startOffset,
+                    };
+                }
+                shift = 1;
+            }
             const position = getPosition(this.#origin, startOffset);
             const startLine = position.line;
             const startCol = position.column;
             return {
                 raw: token,
-                startOffset: (ownerAttr.valueNode?.startOffset ?? 0) + startOffset,
-                startLine: (ownerAttr.valueNode?.startLine ?? 0) + (startLine - 1),
-                startCol: (ownerAttr.valueNode?.startCol ?? 0) + (startCol - 1),
+                startOffset: (base?.startOffset ?? 0) + shift + startOffset,
+                startLine: (base?.startLine ?? 0) + (startLine - 1),
+                // What starts the value (the quote) is before a token on the first line only: the column on a later line is the column in the line
+                startCol: startLine > 1 ? startCol : (base?.startCol ?? 0) + shift + (startCol - 1),
                 rule: ownerAttr.rule,
                 _searchedIndex: startOffset,
             };

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

@@ -1,3 +1,5 @@
+import type { DeclarativeShadowRootAttachment } from '../helper/tree-scope.js';
+import type { MLChildNode } from './child-node.js';
 import type { MLDocument } from './document.js';
 import type { MLNamedNodeMap } from './named-node-map.js';
 import type { MLNode } from './node.js';
@@ -8,9 +10,11 @@ import type { PlainData, Pretender, RegexSelector, RuleConfigValue, RuleInfo } f
 import type { AccnameSource, AccnameVisit, ARIAVersion } from '@markuplint/ml-spec';
 import type { SelectorMatches } from '@markuplint/selector';
 import { MLAttr } from './attr.js';
+import { MLDocumentFragment } from './document-fragment.js';
 import { MLDomTokenList } from './dom-token-list.js';
 import { MLElementCloseTag } from './element-close-tag.js';
 import { MLParentNode } from './parent-node.js';
+import { MLShadowRoot } from './shadow-root.js';
 /**
  * Represents a DOM Element node wrapper in the markuplint DOM tree.
  * Provides access to element attributes, tag names, namespace, ARIA properties,
@@ -601,9 +605,10 @@ export declare class MLElement<T extends RuleConfigValue, O extends PlainData =
      */
     get ariaValueText(): string | null;
     /**
-     * **IT THROWS AN ERROR WHEN CALLING THIS.**
+     * The slot of an open declarative shadow root that this element is assigned to, or `null` when no
+     * slot takes it, the root is closed (the DOM does not expose it), or the assignment is not known
+     * (see {@link MLElement.getFlatTreeSlot}).
      *
-     * @unsupported
      * @implements DOM API: `Element`
      * @see https://dom.spec.whatwg.org/#dom-slotable-assignedslot
      */
@@ -664,7 +669,7 @@ export declare class MLElement<T extends RuleConfigValue, O extends PlainData =
      *
      * @unsupported
      * @implements DOM API: `Element`
-     * @see https://www.w3.org/TR/cssom-view-1/#ref-for-dom-element-clientheight-1
+     * @see https://www.w3.org/TR/cssom-view-1/#dom-element-clientheight
      */
     get clientHeight(): number;
     /**
@@ -672,7 +677,7 @@ export declare class MLElement<T extends RuleConfigValue, O extends PlainData =
      *
      * @unsupported
      * @implements DOM API: `Element`
-     * @see https://www.w3.org/TR/cssom-view-1/#ref-for-dom-element-clientleft-1
+     * @see https://www.w3.org/TR/cssom-view-1/#dom-element-clientleft
      */
     get clientLeft(): number;
     /**
@@ -680,7 +685,7 @@ export declare class MLElement<T extends RuleConfigValue, O extends PlainData =
      *
      * @unsupported
      * @implements DOM API: `Element`
-     * @see https://www.w3.org/TR/cssom-view-1/#ref-for-dom-element-clienttop-1
+     * @see https://www.w3.org/TR/cssom-view-1/#dom-element-clienttop
      */
     get clientTop(): number;
     /**
@@ -688,7 +693,7 @@ export declare class MLElement<T extends RuleConfigValue, O extends PlainData =
      *
      * @unsupported
      * @implements DOM API: `Element`
-     * @see https://www.w3.org/TR/cssom-view-1/#ref-for-dom-element-clientwidth-1
+     * @see https://www.w3.org/TR/cssom-view-1/#dom-element-clientwidth
      */
     get clientWidth(): number;
     /**
@@ -770,7 +775,7 @@ export declare class MLElement<T extends RuleConfigValue, O extends PlainData =
      * @deprecated
      * @unsupported
      * @implements DOM API: `Element`
-     * @see https://html.spec.whatwg.org/multipage/interaction.html#dom-inert
+     * @see https://html.spec.whatwg.org/multipage/dom.html#dom-inert
      */
     get inert(): boolean;
     /**
@@ -778,7 +783,7 @@ export declare class MLElement<T extends RuleConfigValue, O extends PlainData =
      *
      * @unsupported
      * @implements DOM API: `Element`
-     * @see https://w3c.github.io/DOM-Parsing/#dom-innerhtml-innerhtml
+     * @see https://w3c.github.io/DOM-Parsing/#dom-innerhtml
      */
     get innerHTML(): string;
     /**
@@ -1756,7 +1761,7 @@ export declare class MLElement<T extends RuleConfigValue, O extends PlainData =
      *
      * @unsupported
      * @implements DOM API: `Element`
-     * @see https://www.w3.org/TR/cssom-view-1/#ref-for-dom-element-scrollheight-1
+     * @see https://www.w3.org/TR/cssom-view-1/#dom-element-scrollheight
      */
     get scrollHeight(): number;
     /**
@@ -1764,7 +1769,7 @@ export declare class MLElement<T extends RuleConfigValue, O extends PlainData =
      *
      * @unsupported
      * @implements DOM API: `Element`
-     * @see https://www.w3.org/TR/cssom-view-1/#ref-for-dom-element-scrollleft-1
+     * @see https://www.w3.org/TR/cssom-view-1/#dom-element-scrollleft
      */
     get scrollLeft(): number;
     /**
@@ -1772,7 +1777,7 @@ export declare class MLElement<T extends RuleConfigValue, O extends PlainData =
      *
      * @unsupported
      * @implements DOM API: `Element`
-     * @see https://www.w3.org/TR/cssom-view-1/#ref-for-dom-element-scrolltop-1
+     * @see https://www.w3.org/TR/cssom-view-1/#dom-element-scrolltop
      */
     get scrollTop(): number;
     /**
@@ -1780,17 +1785,73 @@ export declare class MLElement<T extends RuleConfigValue, O extends PlainData =
      *
      * @unsupported
      * @implements DOM API: `Element`
-     * @see https://www.w3.org/TR/cssom-view-1/#ref-for-dom-element-scrollwidth-1
+     * @see https://www.w3.org/TR/cssom-view-1/#dom-element-scrollwidth
      */
     get scrollWidth(): number;
     /**
-     * **IT THROWS AN ERROR WHEN CALLING THIS.**
+     * The shadow root that a `template` element with `shadowrootmode="open"` declares on this element:
+     * `null` for a `closed` one, which the DOM does not expose, and when there is none. See
+     * {@link MLElement.declarativeShadowRoot} for one of either mode.
      *
-     * @unsupported
      * @implements DOM API: `Element`
      * @see https://dom.spec.whatwg.org/#ref-for-dom-element-shadowroot%E2%91%A0
      */
-    get shadowRoot(): ShadowRoot | null;
+    get shadowRoot(): MLShadowRoot<T, O> | null;
+    /**
+     * Whether this element is an HTML `template` element, which holds its children in {@link MLElement.content},
+     * a tree of its own. A `template` of a framework that puts the children in the element itself
+     * (`templateContent: 'in-place'` in the spec: React, Vue), a fragment, and a `template` with a
+     * directive of a template engine are not.
+     *
+     * The getters about trees (this one, {@link MLElement.declarativeShadowRootAttachment},
+     * {@link MLElement.content}, `getRootNode()` and the id lookups) keep what they first return: they
+     * depend on the pretenders, the spec and the whole syntax tree, which are all in place once the
+     * document is built, and the document does not change after that.
+     *
+     * @implements `@markuplint/ml-core` API: `MLElement`
+     * @see https://html.spec.whatwg.org/multipage/scripting.html#the-template-element
+     */
+    get isHTMLTemplateElement(): boolean;
+    /**
+     * Whether this element is in no tree: an HTML `template` element that a declarative shadow root is
+     * attached to, or that may have one (see {@link DeclarativeShadowRootAttachment}). The parser inserts
+     * such an element into no tree, so it has no parent in a tree, is its own root, and is found by no
+     * query of a tree. Unknown is treated as in no tree, as markuplint does not count what it cannot tell.
+     *
+     * @implements `@markuplint/ml-core` API: `MLElement`
+     */
+    get isInNoTree(): boolean;
+    /**
+     * The mode that the `shadowrootmode` attribute of an HTML `template` element asks for. `null` when the
+     * element is not one, the attribute is missing or invalid, or its value is dynamic.
+     *
+     * @implements `@markuplint/ml-core` API: `MLElement`
+     */
+    get declarativeShadowRootMode(): 'open' | 'closed' | null;
+    /**
+     * Whether the HTML parser attaches a declarative shadow root to the parent of this `template`
+     * element (see {@link DeclarativeShadowRootAttachment}).
+     *
+     * @implements `@markuplint/ml-core` API: `MLElement`
+     */
+    get declarativeShadowRootAttachment(): DeclarativeShadowRootAttachment;
+    /**
+     * The content of an HTML `template` element: a document fragment that is a tree of its own, holding
+     * the same nodes as the children of the element. When a declarative shadow root is attached to the
+     * parent of the `template`, it is the shadow root. `null` for an element that is not an HTML
+     * `template` element.
+     *
+     * @implements DOM API: `HTMLTemplateElement`
+     * @see https://html.spec.whatwg.org/multipage/scripting.html#dom-template-content
+     */
+    get content(): MLDocumentFragment<T, O> | null;
+    /**
+     * The shadow root that a `template` element declares on this element, whatever its mode.
+     *
+     * @implements `@markuplint/ml-core` API: `MLElement`
+     * @returns The shadow root, or `null` when none is attached to this element
+     */
+    get declarativeShadowRoot(): MLShadowRoot<T, O> | null;
     /**
      * @implements DOM API: `Element`
      * @see https://dom.spec.whatwg.org/#ref-for-dom-element-slot%E2%91%A0
@@ -1879,9 +1940,35 @@ export declare class MLElement<T extends RuleConfigValue, O extends PlainData =
      */
     animate(keyframes: Keyframe[] | PropertyIndexedKeyframes | null, options?: number | KeyframeAnimationOptions): Animation;
     /**
+     * The nodes this `slot` places, in tree order, or with `flatten` what it renders in the flat tree. It
+     * is empty when the assignment is not known; use {@link MLElement.getAssignedNodes} to tell the two apart.
+     *
+     * @implements DOM API: `HTMLSlotElement`
      * @see https://html.spec.whatwg.org/multipage/scripting.html#dom-slot-assignednodes
      */
-    assignedNodes(): never[];
+    assignedNodes(options?: AssignedNodesOptions): MLChildNode<T, O>[];
+    /**
+     * The nodes this `slot` places, by the named slot assignment of the declarative shadow root it is in.
+     * A slot that takes none has `[]`, and renders its own children. `null` when the assignment is not
+     * known; what makes it so is in the module comment of `helper/slot-assignment.ts`.
+     *
+     * @implements `@markuplint/ml-core` API: `MLElement`
+     * @see https://dom.spec.whatwg.org/#find-slotables
+     */
+    getAssignedNodes(): readonly MLChildNode<T, O>[] | null;
+    /**
+     * The slot that places this element in the flat tree: the slot of the shadow root of its parent that
+     * takes it. `null` when its parent is a shadow host and no slot takes it, so that it is not rendered;
+     * `undefined` when its parent is not a shadow host, or the assignment is not known
+     * (see {@link MLElement.getAssignedNodes}).
+     *
+     * `getComposedParentElement` of `@markuplint/ml-spec` reads it as the parent that the accessibility
+     * tree has for the element.
+     *
+     * @implements `@markuplint/ml-core` API: `MLElement`
+     * @see https://dom.spec.whatwg.org/#find-a-slot
+     */
+    getFlatTreeSlot(): MLElement<T, O> | null | undefined;
     /**
      * **IT THROWS AN ERROR WHEN CALLING THIS.**
      *
@@ -2064,7 +2151,8 @@ export declare class MLElement<T extends RuleConfigValue, O extends PlainData =
     getAttributePretended(attrName: string): string | null;
     /**
      * Returns all attribute tokens matching the given name, including duplicates.
-     * Unlike `getAttribute`, this returns the full `MLAttr` token objects.
+     * Unlike `getAttribute`, this returns the full `MLAttr` token objects. An attribute that the
+     * framework does not output (`MLAttr#isAbsent`) is not one of them, as it is not for `getAttribute`.
      *
      * @implements `@markuplint/ml-core` API: `MLElement`
      * @param attrName - The attribute name to look up (see {@link MLAttr.isNamedBy} for how its case is compared)
@@ -2074,6 +2162,9 @@ export declare class MLElement<T extends RuleConfigValue, O extends PlainData =
     /**
      * Returns all attribute tokens for this element, respecting the pretender context.
      * If the element is pretending to be another, returns the pretender's attributes.
+     * It lists every attribute that is written, those that the framework does not output
+     * (`MLAttr#isAbsent`) too, as a name that is misspelled is so whatever its value is; what is asked
+     * of the DOM by name (`getAttributeToken`, `getAttribute`) does not find them.
      *
      * @implements `@markuplint/ml-core` API: `MLElement`
      * @returns A frozen array of all attribute tokens
@@ -2084,7 +2175,7 @@ export declare class MLElement<T extends RuleConfigValue, O extends PlainData =
      *
      * @unsupported
      * @implements DOM API: `Element`
-     * @see https://www.w3.org/TR/cssom-view-1/#ref-for-dom-element-getboundingclientrect-1
+     * @see https://www.w3.org/TR/cssom-view-1/#dom-element-getboundingclientrect
      */
     getBoundingClientRect(): DOMRect;
     /**
@@ -2100,7 +2191,7 @@ export declare class MLElement<T extends RuleConfigValue, O extends PlainData =
      *
      * @unsupported
      * @implements DOM API: `Element`
-     * @see https://www.w3.org/TR/cssom-view-1/#ref-for-dom-element-getclientrects-1
+     * @see https://www.w3.org/TR/cssom-view-1/#dom-element-getclientrects
      */
     getClientRects(): DOMRectList;
     /**
@@ -2166,10 +2257,25 @@ export declare class MLElement<T extends RuleConfigValue, O extends PlainData =
      * @returns True if any attribute is dynamic or lacks a name node (spread)
      */
     hasMutableAttributes(): boolean;
+    /**
+     * Checks whether this element is a component whose rendered output is not known: the
+     * parser sees it as a component (`elementType` is `'authored'`) and no pretender stands
+     * for an element of HTML, which includes a pretender whose own target is a component
+     * (the chain of `pretenders.auto` stopped at `Tabs.Root`).
+     *
+     * A web component is not one: it is the element that it is written as. The criterion of
+     * `isTreatedAsCustom` in `@markuplint/rules` (`permitted-contents`) includes it, because
+     * a content model accepts a custom element wherever it accepts flow content; change them
+     * together.
+     *
+     * @implements `@markuplint/ml-core` API: `MLElement`
+     * @returns True if what this element renders is not known
+     */
+    isUnresolvedComponent(): boolean;
     /**
      * Checks whether this element has children that are potentially mutable,
      * such as preprocessor-specific blocks, slot elements, or (optionally) elements
-     * with dynamic attributes.
+     * with dynamic attributes and components that no pretender resolved.
      *
      * Blocks that carry a `blockBehavior` are not treated as mutable because
      * their branches are deterministically enumerable via
@@ -2177,11 +2283,29 @@ export declare class MLElement<T extends RuleConfigValue, O extends PlainData =
      * like `{value}`) can produce arbitrary content, so the children are
      * considered mutable.
      *
+     * A component that no pretender resolved renders something that is not known, however its
+     * attributes are written (`size={size}`, `size={16}` and `size="16"` tell the same): a rule that
+     * asks about what the descendants are or have (the accessible name, the owned elements) cannot decide
+     * on it, so it is mutable when `attr` is true ({@link MLElement.isUnresolvedComponent}). A component
+     * that a pretender resolved is the element that it renders, which the rules read themselves.
+     *
+     * A rule that asks which children an element has (the required children, the elements that
+     * satisfy a query) does not pass `attr`: an attribute that cannot be known does not decide whether
+     * a child exists. It looks for the unresolved components among the children itself.
+     *
+     * Every `slot` is mutable by default, as a `slot` that is not in a declarative shadow root renders what
+     * is given to it, and a rule that reads the children as they are written (`require-datetime`) cannot
+     * know it. A rule that reads what a slot of a shadow root renders by `MLElement#getAssignedNodes` says
+     * which slots are with `isMutableSlot`.
+     *
+     *
      * @implements `@markuplint/ml-core` API: `MLElement`
-     * @param attr - When true, also considers children with mutable attributes as mutable
+     * @param attr - When true, also considers children with mutable attributes, and components that no
+     * pretender resolved, as mutable
+     * @param isMutableSlot - Whether a `slot` among the descendants may render what is not known
      * @returns True if this element has potentially mutable children
      */
-    hasMutableChildren(attr?: boolean): boolean;
+    hasMutableChildren(attr?: boolean, isMutableSlot?: (slot: MLElement<T, O>) => boolean): boolean;
     /**
      * **IT THROWS AN ERROR WHEN CALLING THIS.**
      *
@@ -2211,7 +2335,7 @@ export declare class MLElement<T extends RuleConfigValue, O extends PlainData =
      *
      * @unsupported
      * @implements DOM API: `Element`
-     * @see https://w3c.github.io/DOM-Parsing/#widl-Element-insertAdjacentHTML-void-DOMString-position-DOMString-text
+     * @see https://w3c.github.io/DOM-Parsing/#dom-element-insertadjacenthtml
      */
     insertAdjacentHTML(position: InsertPosition, text: string): void;
     /**
@@ -2323,7 +2447,7 @@ export declare class MLElement<T extends RuleConfigValue, O extends PlainData =
      *
      * @unsupported
      * @implements DOM API: `Element`
-     * @see https://w3c.github.io/pointerlock/#dom-element-requestpointerlock
+     * @see https://www.w3.org/TR/pointerlock-2/#dom-element-requestpointerlock
      */
     requestPointerLock(options?: any): Promise<void>;
     /**