@markuplint/ml-core 5.4.0 → 5.6.0

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

@@ -1,6 +1,8 @@
 import { resolveNamespace, compileDirectivePatterns, resolveDirective } from '@markuplint/ml-spec';
-import { searchIDLAttribute, suggestIDLAttribute } from '@markuplint/parser-utils';
+import { parseLiteralExpression, searchIDLAttribute, suggestIDLAttribute } from '@markuplint/parser-utils';
 import { adjustForeignAttrName } from '../helper/foreign-attr-names.js';
+import { getBooleanAttrNames, literalToString, renderLiteral } from '../helper/literal-values.js';
+import { isPretendedAttr } from '../helper/pretended-attrs.js';
 import { MLToken } from '../token/token.js';
 import { MLDomTokenList } from './dom-token-list.js';
 import { MLNode } from './node.js';
@@ -36,9 +38,13 @@ export class MLAttr extends MLNode {
      */
     isDuplicatable;
     /**
-     * Whether this attribute has a dynamic value (e.g., a template expression rather than a static string).
+     * Whether the value of this attribute is written as code (`{x}` of JSX, `:x="…"` of Vue, a value of
+     * `=` in Pug, a masked block of a template language), whatever the code is: a literal (`{true}`) or not
+     * (`{cond}`). It is a matter of syntax, which a rule that checks how the value is written reads
+     * (`attr-value-quotes`, `no-unescaped-char`), while {@link MLAttr.isDynamicValue} is a matter of the
+     * value that results.
      */
-    isDynamicValue;
+    isExpressionValue;
     #localName;
     /**
      * The token representing the attribute name, or null for spread attributes.
@@ -52,6 +58,10 @@ export class MLAttr extends MLNode {
     ownerElement;
     #potentialName;
     #potentialValue;
+    #literal = null;
+    #isPretended = false;
+    #valueType = 'string';
+    #rendering;
     /**
      * The whitespace token after the equal sign, or null if absent.
      */
@@ -72,13 +82,6 @@ export class MLAttr extends MLNode {
      * The token representing the attribute value, or null if the attribute has no value.
      */
     valueNode = null;
-    /**
-     * Returns the "string" if HTML syntax. Otherwise, returns a type in its syntax.
-     *
-     * @default "string"
-     * @implements `@markuplint/ml-core` API: `MLAttr`
-     */
-    valueType = 'string';
     /**
      * Creates a new MLAttr instance from an AST attribute token.
      *
@@ -92,12 +95,12 @@ export class MLAttr extends MLNode {
         this.ownerElement = ownElement;
         if (this._astToken.type === 'spread') {
             this.#namespaceURI = null;
-            this.valueType = 'code';
+            this.#valueType = 'code';
             this.#localName = '#spread';
             this.#potentialName = '#spread';
             this.#potentialValue = this._astToken.raw;
             this.isDirective = true;
-            this.isDynamicValue = true;
+            this.isExpressionValue = true;
             this.isDuplicatable = true;
             return;
         }
@@ -111,6 +114,9 @@ export class MLAttr extends MLNode {
         this.endQuote = new MLToken(this._astToken.endQuote);
         this.candidate = this._astToken.candidate;
         this.#potentialValue = this._astToken.potentialValue ?? this.valueNode?.raw ?? '';
+        this.#isPretended = isPretendedAttr(this._astToken);
+        // The language that the value is written in, when the value is code of a language that can be read as a literal
+        let language;
         if (this._astToken.potentialName == null) {
             // Try declarative directive pattern resolution from spec
             const patterns = ownElement.ownerMLDocument.specs.directivePatterns ?? [];
@@ -119,18 +125,20 @@ export class MLAttr extends MLNode {
                 : null;
             if (resolution) {
                 this.#potentialName = resolution.potentialName ?? this.nameNode?.raw ?? '';
-                this.isDynamicValue = resolution.isDynamicValue;
+                this.isExpressionValue = resolution.isDynamicValue;
                 this.isDirective = resolution.isDirective;
                 this.isDuplicatable = resolution.isDuplicatable ?? this._astToken.isDuplicatable;
                 if (resolution.valueType) {
-                    this.valueType = resolution.valueType;
+                    this.#valueType = resolution.valueType;
                 }
+                language = resolution.expressionLanguage;
             }
             else {
                 this.#potentialName = this.nameNode?.raw ?? '';
-                this.isDynamicValue = this._astToken.isDynamicValue;
+                this.isExpressionValue = this._astToken.isDynamicValue;
                 this.isDirective = this._astToken.isDirective;
                 this.isDuplicatable = this._astToken.isDuplicatable;
+                language = ownElement.ownerMLDocument.attrExpressionLanguage;
             }
             // IDL attribute resolution (after directivePatterns).
             // Performed in the core, not in each parser: any spec opting in via
@@ -153,12 +161,14 @@ export class MLAttr extends MLNode {
             }
         }
         else {
-            // Parser-set potentialName takes precedence
+            // Parser-set potentialName takes precedence. Its value is not the value of the attribute
+            // (a condition of `class:list`, a variable of a shorthand), so it is not read as a literal.
             this.#potentialName = this._astToken.potentialName;
-            this.isDynamicValue = this._astToken.isDynamicValue;
+            this.isExpressionValue = this._astToken.isDynamicValue;
             this.isDirective = this._astToken.isDirective;
             this.isDuplicatable = this._astToken.isDuplicatable;
         }
+        this.#literal = this.#readLiteral(language);
         // The HTML parser lower-cases the name before it adjusts a foreign attribute, so `XLINK:HREF`
         // is `xlink:href` there; a name that code sets keeps the case of its prefix.
         const prefixed = this.#potentialName.includes(':') && !this.isSetThroughDOMAPI;
@@ -172,6 +182,76 @@ export class MLAttr extends MLNode {
         const prefix = nameWithPrefix.split(':')[0];
         this.#namespaceURI = hasPrefix && ns.namespace === prefix ? ns.namespaceURI : null;
     }
+    /**
+     * Whether the framework does not output this attribute, which is known from its value being a literal
+     * that the framework drops (`disabled={false}`, `title={null}`). It is still in the list of the
+     * attributes of the element (`MLElement#attributes`), as a name that is misspelled is so whatever its
+     * value is, and a lookup by name (`getAttribute`, `hasAttribute`) does not find it, as the DOM does not.
+     * An absent attribute is {@link MLAttr.isDynamicValue} as well, so that a rule that reads the value skips it.
+     *
+     * Which rules skip it: a rule that judges the value or the presence of an attribute (the value of
+     * `aria-*`, a required attribute, a conflict between two attributes) reads what the framework outputs,
+     * and an attribute that is not output is not there to judge. A rule that judges the name (a misspelling,
+     * a deprecated or obsolete attribute, the order) judges what the author wrote, so it still reports an
+     * absent attribute.
+     */
+    get isAbsent() {
+        return this.#render().absent ? true : undefined;
+    }
+    /**
+     * Whether the value of this attribute is not known: the code is not a literal (`{cond}`), the
+     * framework renders a literal in a way that is not known (`disabled={""}`), or the attribute is
+     * not output ({@link MLAttr.isAbsent}), where there is no value to read.
+     *
+     * It is not whether the value is written as code (that is {@link MLAttr.isExpressionValue}): a
+     * literal that is written as code (`aria-busy={true}`) is rendered by the framework to a value
+     * (`"true"`), which is known.
+     *
+     * A rule that reads it to skip a value that it cannot know reads this; a rule that asks how the
+     * value is written (its quotes, its escapes) reads {@link MLAttr.isExpressionValue} instead.
+     *
+     * On a component (`elementType: "authored"`) an attribute is a prop, which is rendered where it is
+     * forwarded to, not here: a literal in it is not dynamic, and its `value` is the string form of the
+     * literal ({@link MLAttr.literal}). What the component renders is not known, and that is told by
+     * `MLElement#hasMutableChildren`, not by the attributes of the component.
+     */
+    get isDynamicValue() {
+        return this.#render().dynamic ? true : undefined;
+    }
+    /**
+     * Whether this attribute is made by a pretender (`pretenders` of a configuration): it is not in the
+     * source, so the position of its tokens is that of the element, and a fix of a violation on it
+     * would rewrite the tag.
+     *
+     * An attribute that a pretender takes over from the source (`inheritAttrs`) is not.
+     *
+     * A fix of a violation that is reported on a pretended attribute is dropped (`MLRule`), and a rule
+     * that fixes by the range of the attributes of an element (`attr-order`) leaves them out.
+     */
+    get isPretended() {
+        return this.#isPretended;
+    }
+    /**
+     * The literal that the value of this attribute is written as, when it is nothing but a literal in a
+     * language that can be read as one: `{true}`, `{"x"}`, `:x="0"`, or no value at all in the
+     * shorthand of JSX (`<div aria-hidden>` is `true`). `null` otherwise.
+     *
+     * What a literal is rendered as depends on the framework, the element and the attribute name
+     * ({@link MLAttr.value}, {@link MLAttr.isAbsent}); this is what is written.
+     */
+    get literal() {
+        return this.#literal;
+    }
+    /**
+     * Returns the "string" if HTML syntax. Otherwise, returns a type in its syntax. An attribute whose value
+     * is a literal that is resolved is "string", whichever language it is written in.
+     *
+     * @default "string"
+     * @implements `@markuplint/ml-core` API: `MLAttr`
+     */
+    get valueType() {
+        return this.#render().resolved ? 'string' : this.#valueType;
+    }
     /**
      * Returns the local name portion of the attribute (without namespace prefix).
      *
@@ -284,11 +364,12 @@ export class MLAttr extends MLNode {
      * Whether the name of this attribute reaches the DOM through the DOM API (`setAttribute`) and
      * not through the HTML parser of the browser: what the parser says of its language
      * (`MLDocument#attrNameRoute`), and for a parser that says it of a dynamic attribute only
-     * (Svelte), whether this one is dynamic.
+     * (Svelte), whether this one is written as code: how its name is set is a matter of how it is
+     * written, not of the value that results.
      */
     get isSetThroughDOMAPI() {
         const route = this.ownerElement.ownerMLDocument.attrNameRoute;
-        return route === 'dom-api' || (route === 'dom-api-when-dynamic' && this.isDynamicValue === true);
+        return route === 'dom-api' || (route === 'dom-api-when-dynamic' && this.isExpressionValue === true);
     }
     /**
      * Whether a selector matches the name of this attribute without regard to ASCII case: the DOM
@@ -300,6 +381,16 @@ export class MLAttr extends MLNode {
         const el = this.ownerElement;
         return el.elementType !== 'authored' && !el.isForeignElement;
     }
+    /**
+     * Whether the framework does not output this attribute, so that no selector matches it
+     * ({@link MLAttr.isAbsent}). It is a boolean because `SelectorAttr#absent` of `@markuplint/selector`
+     * is the one that a selector reads.
+     *
+     * @implements `SelectorAttr#absent` of `@markuplint/selector`
+     */
+    get absent() {
+        return this.isAbsent === true;
+    }
     /**
      * The name that a selector is matched with.
      *
@@ -392,7 +483,105 @@ export class MLAttr extends MLNode {
      * @see https://dom.spec.whatwg.org/#dom-attr-value
      */
     get value() {
-        return this.#potentialValue;
+        return this.#render().value;
+    }
+    /**
+     * Reads the literal that the value is written as, which is decided by the language of the
+     * code: what the parser says for the attribute it reads, what the directive pattern says for the
+     * one that a spec resolves, and always JavaScript for the one that a pretender makes.
+     *
+     * An attribute that has no value (`:disabled`, which Vue reads as `:disabled="disabled"`) is not the
+     * empty string, and a value that is not an attribute value (the condition of a directive, a
+     * `{name}` shorthand, which have a `potentialName`) is not read.
+     *
+     * @param language - The language that the parser or the pattern says
+     */
+    #readLiteral(language) {
+        if (this.isDirective || !this.valueNode) {
+            return null;
+        }
+        if (this.isExpressionValue) {
+            const isJavaScript = this.#isPretended || language === 'javascript';
+            // A value that is not written has no equal sign. A pretender's expression has none either.
+            const isWritten = this.#isPretended || this.equal?.raw !== '';
+            // `potentialValue` is the expression itself when the value of the token has more than it
+            // (Svelte's `disabled="{false}"` is the expression `false` in quotes)
+            return isJavaScript && isWritten ? parseLiteralExpression(this.#potentialValue) : null;
+        }
+        // The shorthand of JSX: an attribute without a value is `true`. An attribute that a pretender made has no
+        // tokens of a value either, and is not written in JSX.
+        const document = this.ownerElement.ownerMLDocument;
+        if (document.booleanish &&
+            !this.#isPretended &&
+            this._astToken.type === 'attr' &&
+            this._astToken.potentialName == null &&
+            this.equal?.raw === '' &&
+            this.valueNode.raw === '') {
+            return { type: 'boolean', value: true, key: 'true' };
+        }
+        return null;
+    }
+    /**
+     * What the attribute is: the value, whether it is known, and whether it is output at all.
+     * A literal is rendered as the framework renders it (see `renderLiteral`), which depends on the
+     * owner element, so it is done on first use and not by the constructor: `MLElement` makes its
+     * attributes before it knows its own type.
+     */
+    #render() {
+        if (this.#rendering) {
+            return this.#rendering;
+        }
+        const literal = this.#literal;
+        let rendering;
+        if (!literal) {
+            rendering = {
+                value: this.#potentialValue,
+                dynamic: this.isExpressionValue === true,
+                absent: false,
+                resolved: false,
+            };
+        }
+        else if (this.ownerElement.elementType === 'authored') {
+            // A component receives the literal as a prop. It is rendered by the element that the
+            // prop is forwarded to, which is not known here.
+            rendering = { value: literalToString(literal), dynamic: false, absent: false, resolved: true };
+        }
+        else {
+            const rendered = renderLiteral(literal, this.#renderingContext());
+            switch (rendered.kind) {
+                case 'value': {
+                    rendering = { value: rendered.value, dynamic: false, absent: false, resolved: true };
+                    break;
+                }
+                case 'absent': {
+                    rendering = { value: '', dynamic: true, absent: true, resolved: true };
+                    break;
+                }
+                default: {
+                    rendering = { value: '', dynamic: true, absent: false, resolved: false };
+                }
+            }
+        }
+        // Before the owner element is complete, what depends on it is not final
+        if (this.ownerElement.elementType !== undefined) {
+            this.#rendering = rendering;
+        }
+        return rendering;
+    }
+    #renderingContext() {
+        const el = this.ownerElement;
+        const document = el.ownerMLDocument;
+        const specs = document.specs;
+        const name = asciiLowerCase(this.#potentialName);
+        return {
+            name,
+            isBoolean: getBooleanAttrNames(specs).has(name),
+            // A target of a pretender is made as an element of HTML even when its name is a custom element's
+            isCustomElement: el.elementType === 'web-component' ||
+                (el.elementType === 'html' && !el.isForeignElement && el.localName.includes('-')),
+            specLiteralValues: specs.literalValues,
+            parserLiteralValues: document.literalValues,
+        };
     }
     /**
      * Returns a normalized string representation of the attribute,

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

@@ -10,10 +10,15 @@ import { MLNode } from './node.js';
  * loops (`each`), and other preprocessor directives that are not part of standard HTML.
  *
  * Serves as the bridge between template syntax and HTML content model
- * validation: transparency keeps the wrapper invisible to DOM traversal so
- * rules such as `permitted-contents` see the effective HTML children, while
- * `blockBehavior` lets `conditionalChildNodes()` enumerate every possible
- * rendering branch.
+ * validation. `isTransparent` is always true, so `parentNode` walks through
+ * every preprocessor block and an element inside a block keeps the element
+ * that contains the block as its parent.
+ *
+ * `childNodes` does not follow that. Only fragments and blocks whose
+ * `blockBehavior.type` is `each` or `end` are flattened into the parent.
+ * A conditional block stays in `childNodes` so `conditionalChildNodes()` can
+ * tell its branches apart. Flattening those branches would make elements
+ * that never render together into siblings.
  *
  * @template T - The rule configuration value type
  * @template O - The rule options type
@@ -24,8 +29,12 @@ export declare class MLBlock<T extends RuleConfigValue, O extends PlainData = un
      */
     readonly blockBehavior: MLASTBlockBehavior | null;
     /**
-     * Whether this block is transparent, meaning its children are treated
-     * as belonging to the parent node for tree traversal purposes.
+     * Whether `parentNode` walks through this block. Always true, so an
+     * element inside the block keeps the element that contains the block as
+     * its parent. This flag does not decide `childNodes` flattening: only
+     * fragments and blocks whose `blockBehavior.type` is `each` or `end` are
+     * flattened, and a conditional block stays so its branches can be told
+     * apart.
      */
     readonly isTransparent: boolean;
     /**

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

@@ -6,10 +6,15 @@ import { MLNode } from './node.js';
  * loops (`each`), and other preprocessor directives that are not part of standard HTML.
  *
  * Serves as the bridge between template syntax and HTML content model
- * validation: transparency keeps the wrapper invisible to DOM traversal so
- * rules such as `permitted-contents` see the effective HTML children, while
- * `blockBehavior` lets `conditionalChildNodes()` enumerate every possible
- * rendering branch.
+ * validation. `isTransparent` is always true, so `parentNode` walks through
+ * every preprocessor block and an element inside a block keeps the element
+ * that contains the block as its parent.
+ *
+ * `childNodes` does not follow that. Only fragments and blocks whose
+ * `blockBehavior.type` is `each` or `end` are flattened into the parent.
+ * A conditional block stays in `childNodes` so `conditionalChildNodes()` can
+ * tell its branches apart. Flattening those branches would make elements
+ * that never render together into siblings.
  *
  * @template T - The rule configuration value type
  * @template O - The rule options type
@@ -20,8 +25,12 @@ export class MLBlock extends MLNode {
      */
     blockBehavior;
     /**
-     * Whether this block is transparent, meaning its children are treated
-     * as belonging to the parent node for tree traversal purposes.
+     * Whether `parentNode` walks through this block. Always true, so an
+     * element inside the block keeps the element that contains the block as
+     * its parent. This flag does not decide `childNodes` flattening: only
+     * fragments and blocks whose `blockBehavior.type` is `each` or `end` are
+     * flattened, and a conditional block stays so its branches can be told
+     * apart.
      */
     isTransparent;
     /**
@@ -34,8 +43,8 @@ export class MLBlock extends MLNode {
     // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
     document) {
         super(astNode, document, astNode.isFragment);
-        // Always transparent: blockBehavior may restrict child treatment in the future,
-        // but currently all preprocessor blocks are transparent for tree traversal.
+        // `parentNode` walks through every block. `childNodes` flattens only
+        // `each` and `end`; see the class comment.
         this.isTransparent = true;
         this.blockBehavior = astNode.blockBehavior;
     }

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

@@ -1,11 +1,17 @@
+import type { MLElement } from './element.js';
 import type { DocumentFragmentNodeType } from './types.js';
 import type { MLASTNode } from '@markuplint/ml-ast';
 import type { PlainData, RuleConfigValue } from '@markuplint/ml-config';
 import { MLParentNode } from './parent-node.js';
 /**
  * Represents a DOM DocumentFragment node wrapper in the markuplint DOM tree.
- * Used for JSX fragments and similar constructs where a set of nodes
- * is grouped without a wrapping element.
+ *
+ * It is the `content` of an HTML `template` element, a tree of its own. markuplint does not
+ * keep it apart in the syntax tree: the children of the `template` element are the children of
+ * the fragment, as the same nodes, so the fragment is built from a copy of the AST node of the
+ * `template` element that has a uuid of its own (the node store keys nodes by uuid).
+ *
+ * It has no parent: a document fragment is a root, and `getRootNode()` of it is itself.
  *
  * @template T - The rule configuration value type
  * @template O - The rule options type
@@ -27,11 +33,17 @@ export declare class MLDocumentFragment<T extends RuleConfigValue, O extends Pla
      */
     get textContent(): string;
     /**
-     * **IT THROWS AN ERROR WHEN CALLING THIS.**
+     * A document fragment has no parent.
+     *
+     * @implements `@markuplint/ml-core` API: `MLNode`
+     */
+    get syntacticalParentNode(): null;
+    /**
+     * Finds the first element in this tree whose id is `elementId`: not in the content of a `template`
+     * element under it, which is a tree of its own.
      *
-     * @deprecated
-     * @unsupported
      * @implements DOM API: `DocumentFragment`
+     * @see https://dom.spec.whatwg.org/#dom-nonelementparentnode-getelementbyid
      */
-    getElementById(elementId: string): HTMLElement | null;
+    getElementById(elementId: string): MLElement<T, O> | null;
 }

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

@@ -1,9 +1,13 @@
 import { MLParentNode } from './parent-node.js';
-import { UnexpectedCallError } from '@markuplint/shared';
 /**
  * Represents a DOM DocumentFragment node wrapper in the markuplint DOM tree.
- * Used for JSX fragments and similar constructs where a set of nodes
- * is grouped without a wrapping element.
+ *
+ * It is the `content` of an HTML `template` element, a tree of its own. markuplint does not
+ * keep it apart in the syntax tree: the children of the `template` element are the children of
+ * the fragment, as the same nodes, so the fragment is built from a copy of the AST node of the
+ * `template` element that has a uuid of its own (the node store keys nodes by uuid).
+ *
+ * It has no parent: a document fragment is a root, and `getRootNode()` of it is itself.
  *
  * @template T - The rule configuration value type
  * @template O - The rule options type
@@ -31,13 +35,21 @@ export class MLDocumentFragment extends MLParentNode {
         return [...this.childNodes].map(child => child.textContent ?? '').join('');
     }
     /**
-     * **IT THROWS AN ERROR WHEN CALLING THIS.**
+     * A document fragment has no parent.
+     *
+     * @implements `@markuplint/ml-core` API: `MLNode`
+     */
+    get syntacticalParentNode() {
+        return null;
+    }
+    /**
+     * Finds the first element in this tree whose id is `elementId`: not in the content of a `template`
+     * element under it, which is a tree of its own.
      *
-     * @deprecated
-     * @unsupported
      * @implements DOM API: `DocumentFragment`
+     * @see https://dom.spec.whatwg.org/#dom-nonelementparentnode-getelementbyid
      */
     getElementById(elementId) {
-        throw new UnexpectedCallError('Not supported "getElementById" method');
+        return this._getElementById(elementId);
     }
 }

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

@@ -10,7 +10,7 @@ import type { Ruleset } from '../../ruleset/index.js';
 import type { MLSchema } from '../../types.js';
 import type { Walker } from '../helper/walkers.js';
 import type { MLToken } from '../token/token.js';
-import type { AttrNameRoute, EndTagType, MLASTDocument, MLASTNodeTreeItem, MLASTParseError } from '@markuplint/ml-ast';
+import type { AttrNameRoute, EndTagType, ExpressionLanguage, LiteralValueDeclaration, MLASTDocument, MLASTNodeTreeItem, MLASTParseError } from '@markuplint/ml-ast';
 import type { PlainData, Pretender, RuleCommonSettings, RuleConfigValue } from '@markuplint/ml-config';
 import type { ARIAVersion, MLMLSpec } from '@markuplint/ml-spec';
 import { MLParentNode } from './parent-node.js';
@@ -38,6 +38,23 @@ export declare class MLDocument<T extends RuleConfigValue, O extends PlainData =
      * @default false
      */
     readonly booleanish: boolean;
+    /**
+     * 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).
+     */
+    readonly attrExpressionLanguage?: ExpressionLanguage;
+    /**
+     * 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.
+     */
+    readonly literalValues?: LiteralValueDeclaration;
+    /**
+     * 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.
+     */
+    readonly slotElement: 'html' | 'framework';
     /**
      * The rule currently being evaluated during a lint pass.
      * Set by the linting engine before rule evaluation begins and used by nodes
@@ -137,6 +154,9 @@ export declare class MLDocument<T extends RuleConfigValue, O extends PlainData =
         readonly filename?: string;
         readonly endTag?: 'xml' | 'omittable' | 'never';
         readonly booleanish?: boolean;
+        readonly attrExpressionLanguage?: ExpressionLanguage;
+        readonly literalValues?: LiteralValueDeclaration;
+        readonly slotElement?: 'html' | 'framework';
         readonly tagNameCaseSensitive?: boolean;
         readonly componentNameVariants?: boolean;
         readonly isComponentName?: (name: string) => boolean;
@@ -1641,14 +1661,17 @@ export declare class MLDocument<T extends RuleConfigValue, O extends PlainData =
      */
     getAnimations(): Animation[];
     /**
+     * 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: string): MLElement<T, O> | null;
     /**
-     * **IT THROWS AN ERROR WHEN CALLING THIS.**
-     *
-     * @unsupported
      * @implements DOM API: `Document`
+     * @see https://dom.spec.whatwg.org/#concept-getelementsbyclassname
      */
     getElementsByClassName(classNames: string): HTMLCollectionOf<MLElement<T, O>>;
     /**
@@ -1659,10 +1682,12 @@ export declare class MLDocument<T extends RuleConfigValue, O extends PlainData =
      */
     getElementsByName(elementName: string): NodeListOf<HTMLElement>;
     /**
-     * **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: string): HTMLCollectionOf<MLElement<T, O>>;
     /**
@@ -1765,12 +1790,16 @@ export declare class MLDocument<T extends RuleConfigValue, O extends PlainData =
     /**
      * 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: number, col: number): MLNode<T, O, import("@markuplint/ml-ast").MLASTNode> | null;
+    searchNodeByLocation(line: number, col: number): MLNode<T, O> | null;
     /**
      * Sets the currently active rule for this document. Called by the linting engine
      * before each rule evaluation pass.