@markuplint/ml-core 4.13.2 → 4.18.0

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

@@ -25,6 +25,15 @@ import { UnexpectedCallError } from './unexpected-call-error.js';
 const log = coreLog.extend('ml-dom');
 const docLog = log.extend('document');
 const ruleLog = docLog.extend('rule');
+/**
+ * Represents a DOM Document node wrapper in the markuplint DOM tree.
+ * Serves as the root node of the parsed document, managing the node list,
+ * rule mappings, pretender initialization, accessibility computation,
+ * and document-level configuration (end tag handling, booleanish values, etc.).
+ *
+ * @template T - The rule configuration value type
+ * @template O - The rule options type
+ */
 export class MLDocument extends MLParentNode {
     /**
      *
@@ -35,11 +44,13 @@ export class MLDocument extends MLParentNode {
         // @ts-ignore
         super(ast, null);
         /**
-         *
+         * The rule currently being evaluated during a lint pass.
+         * Set by the linting engine before rule evaluation begins and used by nodes
+         * to retrieve their rule configuration. Null when no rule is being evaluated.
          */
         this.currentRule = null;
         /**
-         *
+         * The file path of the source document, if available.
          */
         _MLDocument_filename.set(this, void 0);
         _MLDocument_tokenList.set(this, null);
@@ -89,6 +100,16 @@ export class MLDocument extends MLParentNode {
     get activeElement() {
         throw new UnexpectedCallError('Not supported "activeElement" property');
     }
+    /**
+     * **IT THROWS AN ERROR WHEN CALLING THIS.**
+     *
+     * @deprecated
+     * @unsupported
+     * @implements DOM API: `Document`
+     */
+    get activeViewTransition() {
+        throw new UnexpectedCallError('Not supported "activeViewTransition" property');
+    }
     /**
      * **IT THROWS AN ERROR WHEN CALLING THIS.**
      *
@@ -212,6 +233,16 @@ export class MLDocument extends MLParentNode {
     get currentScript() {
         throw new UnexpectedCallError('Not supported "currentScript" property');
     }
+    /**
+     * **IT THROWS AN ERROR WHEN CALLING THIS.**
+     *
+     * @deprecated
+     * @unsupported
+     * @implements DOM API: `Document`
+     */
+    get customElementRegistry() {
+        throw new UnexpectedCallError('Not supported "customElementRegistry" property');
+    }
     /**
      * Window object for calling the `getComputedStyle` and the `getPropertyValue` that
      * are needed by **Accessible Name and Description Computation**.
@@ -628,6 +659,16 @@ export class MLDocument extends MLParentNode {
     get onclose() {
         throw new UnexpectedCallError('Not supported "onclose" property');
     }
+    /**
+     * **IT THROWS AN ERROR WHEN CALLING THIS.**
+     *
+     * @deprecated
+     * @unsupported
+     * @implements DOM API: `Document`
+     */
+    get oncommand() {
+        throw new UnexpectedCallError('Not supported "oncommand" property');
+    }
     /**
      * **IT THROWS AN ERROR WHEN CALLING THIS.**
      *
@@ -1833,7 +1874,11 @@ export class MLDocument extends MLParentNode {
         throw new UnexpectedCallError('Not supported "createTreeWalker" method');
     }
     /**
+     * Returns a debug-friendly string array representing the structure of the document's
+     * node list, useful for debugging and test assertions.
+     *
      * @implements `@markuplint/ml-core` API: `MLDocument`
+     * @returns An array of strings describing each node in the document
      */
     debugMap() {
         return nodeListToDebugMaps(this.nodeList, true);
@@ -1908,6 +1953,15 @@ export class MLDocument extends MLParentNode {
     exitPointerLock() {
         throw new UnexpectedCallError('Not supported "exitPointerLock" method');
     }
+    /**
+     * Computes the accessibility properties for the given node, including its
+     * ARIA role, accessible name, focusability, and ARIA property values.
+     * Returns null for non-element nodes.
+     *
+     * @param node - The node to compute accessibility properties for
+     * @param ariaVersion - The ARIA specification version to use for computation
+     * @returns The computed accessibility properties, or null for non-element nodes
+     */
     getAccessibilityProp(
     // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
     node, ariaVersion = ARIA_RECOMMENDED_VERSION) {
@@ -2022,7 +2076,11 @@ export class MLDocument extends MLParentNode {
         throw new UnexpectedCallError('Not supported "getSelection" method');
     }
     /**
+     * Returns a flat, offset-sorted list of all tokens in the document,
+     * including element close tags. The result is cached after the first call.
+     *
      * @implements `@markuplint/ml-core` API: `MLDocument`
+     * @returns A frozen array of tokens sorted by their starting offset
      */
     getTokenList() {
         if (__classPrivateFieldGet(this, _MLDocument_tokenList, "f")) {
@@ -2145,7 +2203,12 @@ export class MLDocument extends MLParentNode {
         throw new UnexpectedCallError('Not supported "requestStorageAccess" method');
     }
     /**
+     * Searches for a node at the given source location (line and column).
+     *
      * @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) {
@@ -2156,7 +2219,11 @@ export class MLDocument extends MLParentNode {
         return null;
     }
     /**
+     * Sets the currently active rule for this document. Called by the linting engine
+     * before each rule evaluation pass.
+     *
      * @implements `@markuplint/ml-core` API: `MLDocument`
+     * @param rule - The rule to set as current, or null to clear
      */
     setRule(rule) {
         this.currentRule = rule;
@@ -2171,7 +2238,13 @@ export class MLDocument extends MLParentNode {
         throw new UnexpectedCallError('Not supported "startViewTransition" method');
     }
     /**
+     * Returns a string representation of the entire document. When `fixed` is true,
+     * returns the document with all lint fixes applied by substituting
+     * fixed token content at the appropriate offsets.
+     *
      * @implements `@markuplint/ml-core` API: `MLDocument`
+     * @param fixed - When true, returns the fixed content; otherwise returns the original raw content
+     * @returns The string content of the document
      */
     toString(fixed = false) {
         if (!fixed) {
@@ -2229,6 +2302,11 @@ export class MLDocument extends MLParentNode {
     writeln(...text) {
         throw new UnexpectedCallError('Not supported "writeln" method');
     }
+    /**
+     * Initializes pretender contexts for all element nodes in the document.
+     *
+     * @param pretenders - Optional pretender configurations from the document options
+     */
     _pretending(pretenders) {
         if (docLog.enabled) {
             docLog('Pretending: %O', pretenders);
@@ -2239,6 +2317,13 @@ export class MLDocument extends MLParentNode {
             }
         }
     }
+    /**
+     * Maps the ruleset configuration to each node in the document.
+     * Applies global rules, node-specific rules (by selector), and
+     * child-node rules to build the per-node rule configuration.
+     *
+     * @param ruleset - The ruleset containing rules, nodeRules, and childNodeRules
+     */
     _ruleMapping(ruleset) {
         if (docLog.enabled) {
             docLog('Rule Mapping: %O', Object.keys(ruleset.rules));

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

@@ -12,8 +12,20 @@ import { MLAttr } from './attr.js';
 import { MLDomTokenList } from './dom-token-list.js';
 import { MLElementCloseTag } from './element-close-tag.js';
 import { MLParentNode } from './parent-node.js';
+/**
+ * Represents a DOM Element node wrapper in the markuplint DOM tree.
+ * Provides access to element attributes, tag names, namespace, ARIA properties,
+ * accessibility information, pretender context, and CSS selector matching.
+ * This is the primary class used for linting HTML elements.
+ *
+ * @template T - The rule configuration value type
+ * @template O - The rule options type
+ */
 export declare class MLElement<T extends RuleConfigValue, O extends PlainData = undefined> extends MLParentNode<T, O, MLASTElement> implements Element, HTMLOrSVGElement, HTMLElement {
     #private;
+    /**
+     * The closing tag for this element, or null if the element is self-closing or void.
+     */
     readonly closeTag: MLElementCloseTag<T, O> | null;
     /**
      * Element type
@@ -23,17 +35,45 @@ export declare class MLElement<T extends RuleConfigValue, O extends PlainData =
      * - `authored`:  Authored element (JSX Element etc.) through the view framework or the template engine.
      */
     readonly elementType: ElementType;
+    /**
+     * Whether this element belongs to a non-HTML namespace (e.g., SVG or MathML).
+     */
     readonly isForeignElement: boolean;
+    /**
+     * Whether this element was implicitly created (e.g., an omitted `<body>` tag in HTML).
+     */
     readonly isOmitted: boolean;
+    /**
+     * The namespace URI of this element (e.g., `http://www.w3.org/1999/xhtml` for HTML elements).
+     */
     readonly namespaceURI: NamespaceURI;
     readonly ontouchcancel?: ((this: GlobalEventHandlers, ev: TouchEvent) => any) | null | undefined;
     readonly ontouchend?: ((this: GlobalEventHandlers, ev: TouchEvent) => any) | null | undefined;
     readonly ontouchmove?: ((this: GlobalEventHandlers, ev: TouchEvent) => any) | null | undefined;
     readonly ontouchstart?: ((this: GlobalEventHandlers, ev: TouchEvent) => any) | null | undefined;
+    /**
+     * The pretender context if this element is participating in pretender behavior,
+     * or null if it is not a pretender or pretended element.
+     */
     pretenderContext: PretenderContext<MLElement<T, O>, T, O> | null;
+    /**
+     * The self-closing solidus token (`/`), or null if the element is not self-closing.
+     */
     readonly selfClosingSolidus: MLToken | null;
+    /**
+     * The tag close character string (e.g., `>` or `/>` or `%>`).
+     */
     readonly tagCloseChar: string;
+    /**
+     * The tag open character string (e.g., `<` or `<%`).
+     */
     readonly tagOpenChar: string;
+    /**
+     * Creates a new MLElement instance from an AST element node.
+     *
+     * @param astNode - The AST element node to wrap
+     * @param document - The owning document
+     */
     constructor(astNode: MLASTElement, document: MLDocument<T, O>);
     /**
      * **IT THROWS AN ERROR WHEN CALLING THIS.**
@@ -146,7 +186,7 @@ export declare class MLElement<T extends RuleConfigValue, O extends PlainData =
      * @unsupported
      * @implements DOM API: `Element`
      */
-    get ariaControlsElements(): readonly MLElement<T, O>[];
+    get ariaControlsElements(): readonly MLElement<T, O>[] | null;
     /**
      * **IT THROWS AN ERROR WHEN CALLING THIS.**
      *
@@ -162,7 +202,7 @@ export declare class MLElement<T extends RuleConfigValue, O extends PlainData =
      * @unsupported
      * @implements DOM API: `Element`
      */
-    get ariaDescribedByElements(): readonly MLElement<T, O>[];
+    get ariaDescribedByElements(): readonly MLElement<T, O>[] | null;
     /**
      * **IT THROWS AN ERROR WHEN CALLING THIS.**
      *
@@ -178,7 +218,7 @@ export declare class MLElement<T extends RuleConfigValue, O extends PlainData =
      * @unsupported
      * @implements DOM API: `Element`
      */
-    get ariaDetailsElements(): readonly MLElement<T, O>[];
+    get ariaDetailsElements(): readonly MLElement<T, O>[] | null;
     /**
      * **IT THROWS AN ERROR WHEN CALLING THIS.**
      *
@@ -194,7 +234,7 @@ export declare class MLElement<T extends RuleConfigValue, O extends PlainData =
      * @unsupported
      * @implements DOM API: `Element`
      */
-    get ariaErrorMessageElements(): readonly MLElement<T, O>[];
+    get ariaErrorMessageElements(): readonly MLElement<T, O>[] | null;
     /**
      * **IT THROWS AN ERROR WHEN CALLING THIS.**
      *
@@ -210,7 +250,7 @@ export declare class MLElement<T extends RuleConfigValue, O extends PlainData =
      * @unsupported
      * @implements DOM API: `Element`
      */
-    get ariaFlowToElements(): readonly MLElement<T, O>[];
+    get ariaFlowToElements(): readonly MLElement<T, O>[] | null;
     /**
      * **IT THROWS AN ERROR WHEN CALLING THIS.**
      *
@@ -258,7 +298,7 @@ export declare class MLElement<T extends RuleConfigValue, O extends PlainData =
      * @unsupported
      * @implements DOM API: `Element`
      */
-    get ariaLabelledByElements(): readonly MLElement<T, O>[];
+    get ariaLabelledByElements(): readonly MLElement<T, O>[] | null;
     /**
      * **IT THROWS AN ERROR WHEN CALLING THIS.**
      *
@@ -314,7 +354,7 @@ export declare class MLElement<T extends RuleConfigValue, O extends PlainData =
      * @unsupported
      * @implements DOM API: `Element`
      */
-    get ariaOwnsElements(): readonly MLElement<T, O>[];
+    get ariaOwnsElements(): readonly MLElement<T, O>[] | null;
     /**
      * **IT THROWS AN ERROR WHEN CALLING THIS.**
      *
@@ -467,6 +507,12 @@ export declare class MLElement<T extends RuleConfigValue, O extends PlainData =
      * @see https://dom.spec.whatwg.org/#dom-slotable-assignedslot
      */
     get assignedSlot(): HTMLSlotElement | null;
+    /**
+     * **IT THROWS AN ERROR WHEN CALLING THIS.**
+     *
+     * @unsupported
+     * @implements DOM API: `Element`
+     */
     get attributeStyleMap(): StylePropertyMap;
     /**
      * @implements DOM API: `Element`
@@ -555,6 +601,14 @@ export declare class MLElement<T extends RuleConfigValue, O extends PlainData =
      * @implements DOM API: `Element`
      */
     get currentCSSZoom(): number;
+    /**
+     * **IT THROWS AN ERROR WHEN CALLING THIS.**
+     *
+     * @deprecated
+     * @unsupported
+     * @implements DOM API: `Element`
+     */
+    get customElementRegistry(): CustomElementRegistry | null;
     /**
      * **IT THROWS AN ERROR WHEN CALLING THIS.**
      *
@@ -588,9 +642,15 @@ export declare class MLElement<T extends RuleConfigValue, O extends PlainData =
      */
     get enterKeyHint(): string;
     /**
+     * Returns the fixed (potentially corrected) node name, which may differ from the
+     * original node name after lint fixes such as case normalization.
+     *
      * @implements `@markuplint/ml-core` API: `MLElement`
      */
     get fixedNodeName(): string;
+    /**
+     * Whether this element has any spread attributes (e.g., `{...props}` in JSX).
+     */
     get hasSpreadAttr(): boolean;
     /**
      * **IT THROWS AN ERROR WHEN CALLING THIS.**
@@ -695,7 +755,7 @@ export declare class MLElement<T extends RuleConfigValue, O extends PlainData =
      * @unsupported
      * @implements DOM API: `Element`
      */
-    get nonce(): string | undefined;
+    get nonce(): string;
     /**
      * **IT THROWS AN ERROR WHEN CALLING THIS.**
      *
@@ -864,6 +924,14 @@ export declare class MLElement<T extends RuleConfigValue, O extends PlainData =
      * @implements DOM API: `Element`
      */
     get onclose(): ((this: GlobalEventHandlers, ev: Event) => any) | null;
+    /**
+     * **IT THROWS AN ERROR WHEN CALLING THIS.**
+     *
+     * @deprecated
+     * @unsupported
+     * @implements DOM API: `Element`
+     */
+    get oncommand(): ((this: GlobalEventHandlers, ev: Event) => any) | null;
     /**
      * **IT THROWS AN ERROR WHEN CALLING THIS.**
      *
@@ -1560,6 +1628,9 @@ export declare class MLElement<T extends RuleConfigValue, O extends PlainData =
      */
     get previousElementSibling(): MLElement<T, O> | null;
     /**
+     * Returns the original raw element name exactly as it appears in the AST,
+     * without any case normalization or pretender resolution.
+     *
      * @implements `@markuplint/ml-core` API: `MLElement`
      */
     get rawName(): string;
@@ -1572,6 +1643,9 @@ export declare class MLElement<T extends RuleConfigValue, O extends PlainData =
      */
     get role(): string;
     /**
+     * Returns the rule configuration for this element, respecting the pretender context.
+     * If the element is a pretended origin, returns the rule from the pretending element.
+     *
      * @implements `@markuplint/ml-core` API: `MLNode`
      */
     get rule(): RuleInfo<T, O>;
@@ -1762,6 +1836,12 @@ export declare class MLElement<T extends RuleConfigValue, O extends PlainData =
      * @implements DOM API: `Element`
      */
     computedStyleMap(): StylePropertyMapReadOnly;
+    /**
+     * Overrides the fixed node name for this element, used when the element's
+     * tag name needs to be corrected during linting (e.g., case normalization).
+     *
+     * @param name - The new node name to set
+     */
     fixNodeName(name: string): void;
     /**
      * **IT THROWS AN ERROR WHEN CALLING THIS.**
@@ -1772,7 +1852,12 @@ export declare class MLElement<T extends RuleConfigValue, O extends PlainData =
      */
     focus(options?: FocusOptions): void;
     /**
+     * Computes the accessible name of this element according to the
+     * Accessible Name and Description Computation algorithm.
+     *
      * @implements `@markuplint/ml-core` API: `MLElement`
+     * @param version - The ARIA specification version to use for computation
+     * @returns The computed accessible name string
      */
     getAccessibleName(version: ARIAVersion): string;
     /**
@@ -1815,15 +1900,29 @@ export declare class MLElement<T extends RuleConfigValue, O extends PlainData =
      */
     getAttributeNodeNS(namespace: string | null, localName: string): Attr | null;
     /**
+     * Gets the attribute value from the original (non-pretended) attributes list,
+     * bypassing any pretender context that might be active.
+     *
      * @implements `@markuplint/ml-core` API: `MLElement`
+     * @param attrName - The attribute name to look up (case-insensitive)
+     * @returns The attribute value, or null if the attribute is not found
      */
     getAttributePretended(attrName: string): string | null;
     /**
+     * Returns all attribute tokens matching the given name, including duplicates.
+     * Unlike `getAttribute`, this returns the full `MLAttr` token objects.
+     *
      * @implements `@markuplint/ml-core` API: `MLElement`
+     * @param attrName - The attribute name to look up (case-insensitive)
+     * @returns An array of matching attribute tokens
      */
     getAttributeToken(attrName: string): MLAttr<T, O>[];
     /**
+     * Returns all attribute tokens for this element, respecting the pretender context.
+     * If the element is pretending to be another, returns the pretender's attributes.
+     *
      * @implements `@markuplint/ml-core` API: `MLElement`
+     * @returns A frozen array of all attribute tokens
      */
     getAttributeTokens(): readonly MLAttr<T, O>[];
     /**
@@ -1834,6 +1933,13 @@ export declare class MLElement<T extends RuleConfigValue, O extends PlainData =
      * @see https://www.w3.org/TR/cssom-view-1/#ref-for-dom-element-getboundingclientrect-1
      */
     getBoundingClientRect(): DOMRect;
+    /**
+     * Returns child elements and non-whitespace text nodes, skipping omitted elements
+     * by flattening their children into the result. Results are cached for performance.
+     *
+     * @implements `@markuplint/ml-core` API: `MLElement`
+     * @returns An array of child elements and non-whitespace text nodes
+     */
     getChildElementsAndTextNodeWithoutWhitespaces(): (MLElement<T, O> | MLText<T, O>)[];
     /**
      * **IT THROWS AN ERROR WHEN CALLING THIS.**
@@ -1870,7 +1976,10 @@ export declare class MLElement<T extends RuleConfigValue, O extends PlainData =
      */
     getHTML(options?: any): string;
     /**
+     * Returns the source location of the element's tag name (excluding the opening `<` character).
+     *
      * @implements `@markuplint/ml-core` API: `MLElement`
+     * @returns An object with `offset`, `line`, and `col` properties indicating where the name starts
      */
     getNameLocation(): {
         offset: number;
@@ -1896,13 +2005,21 @@ export declare class MLElement<T extends RuleConfigValue, O extends PlainData =
      */
     hasAttributes(): boolean;
     /**
+     * Checks whether this element has any mutable attributes, such as spread
+     * attributes or attributes with dynamic values from template expressions.
+     *
      * @implements `@markuplint/ml-core` API: `MLElement`
+     * @returns True if any attribute is dynamic or lacks a name node (spread)
      */
     hasMutableAttributes(): boolean;
     /**
-     * This element has "Preprocessor Specific Block". In other words, Its children are potentially mutable.
+     * Checks whether this element has children that are potentially mutable,
+     * such as preprocessor-specific blocks, slot elements, or (optionally) elements
+     * with dynamic attributes.
      *
      * @implements `@markuplint/ml-core` API: `MLElement`
+     * @param attr - When true, also considers children with mutable attributes as mutable
+     * @returns True if this element has potentially mutable children
      */
     hasMutableChildren(attr?: boolean): boolean;
     /**
@@ -1946,21 +2063,46 @@ export declare class MLElement<T extends RuleConfigValue, O extends PlainData =
      */
     insertAdjacentText(where: InsertPosition, data: string): void;
     /**
+     * Checks whether this element is a descendant of any element whose UUID
+     * is in the given list, by walking up the parent element chain.
+     *
      * @implements `@markuplint/ml-core` API: `MLElement`
+     * @param uuidList - A list of element UUIDs to check against
+     * @returns True if any ancestor element's UUID is in the list
      */
     isDescendantByUUIDList(uuidList: readonly string[]): boolean;
     /**
+     * Checks whether this element has no meaningful child content
+     * (only whitespace-only text nodes or no children at all).
+     *
      * @implements `@markuplint/ml-core` API: `MLElement`
+     * @returns True if the element has no non-whitespace child content
      */
     isEmpty(): boolean;
     /**
      * @implements DOM API: `Element`
      * @see https://dom.spec.whatwg.org/#ref-for-dom-element-matches%E2%91%A0
      */
-    matches(selector: string, scope?: MLParentNode<T, O>): boolean;
+    matches<K extends keyof HTMLElementTagNameMap>(selectors: K): this is HTMLElementTagNameMap[K];
+    matches<K extends keyof SVGElementTagNameMap>(selectors: K): this is SVGElementTagNameMap[K];
+    matches<K extends keyof MathMLElementTagNameMap>(selectors: K): this is MathMLElementTagNameMap[K];
+    matches(selectors: string, scope?: MLParentNode<T, O>): boolean;
+    /**
+     * Matches this element against a CSS selector or regex selector pattern,
+     * returning detailed match results. When the element is a pretender,
+     * it attempts to match both as the pretender and as the original element.
+     *
+     * @param selector - The CSS selector string or regex selector to match against
+     * @param scope - An optional scope node for scoped selector matching
+     * @returns The detailed match result including captured groups from regex selectors
+     */
     matchMLSelector(selector: string | RegexSelector | undefined, scope?: MLParentNode<T, O>): SelectorMatches;
     /**
-     * Pretenders Initialization
+     * Initializes the pretender context for this element based on the given pretender
+     * configurations. If a matching pretender is found or the element has an `as` attribute,
+     * sets up the pretender/pretended relationship between elements.
+     *
+     * @param pretenders - Optional array of pretender configurations to match against
      */
     pretending(pretenders?: readonly Pretender[]): void;
     /**
@@ -2108,11 +2250,22 @@ export declare class MLElement<T extends RuleConfigValue, O extends PlainData =
      */
     showPopover(): void;
     /**
+     * Returns a normalized string representation of this element including its tag name,
+     * attributes, and child content. Whitespace-only text nodes are excluded.
+     * The result is cached for repeated calls.
+     *
      * @implements `@markuplint/ml-core` API: `MLElement`
+     * @returns The normalized HTML string of this element
      */
     toNormalizeString(): string;
     /**
+     * Returns a string representation of this element. When `fixed` is true,
+     * returns the element with any lint fixes applied to the tag name,
+     * attributes, and embedded comment nodes.
+     *
      * @implements `@markuplint/ml-core` API: `MLElement`
+     * @param fixed - When true, returns the fixed content; otherwise returns the original raw content
+     * @returns The string content of this element
      */
     toString(fixed?: boolean): string;
     /**