@markuplint/ml-core 4.13.2 → 4.18.0

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

@@ -15,22 +15,61 @@ import { MLToken } from '../token/token.js';
 import { MLDomTokenList } from './dom-token-list.js';
 import { MLNode } from './node.js';
 import { UnexpectedCallError } from './unexpected-call-error.js';
+/**
+ * Represents a DOM Attr (attribute) node wrapper in the markuplint DOM tree.
+ * Wraps an AST attribute token and provides access to the attribute's name, value,
+ * tokens (name, equal sign, quotes, value), and metadata such as whether
+ * the attribute is a directive or has a dynamic value.
+ *
+ * @template T - The rule configuration value type
+ * @template O - The rule options type
+ */
 export class MLAttr extends MLNode {
+    /**
+     * Creates a new MLAttr instance from an AST attribute token.
+     *
+     * @param astToken - The AST attribute token to wrap
+     * @param ownElement - The element that owns this attribute
+     */
     constructor(astToken, 
     // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
     ownElement) {
         super(astToken, ownElement.ownerMLDocument);
+        /**
+         * The end quote token of the attribute value, or null if the attribute has no value or quotes.
+         */
         this.endQuote = null;
+        /**
+         * The equal sign token between the attribute name and value, or null if absent.
+         */
         this.equal = null;
         _MLAttr_localName.set(this, void 0);
+        /**
+         * The token representing the attribute name, or null for spread attributes.
+         */
         this.nameNode = null;
         _MLAttr_namespaceURI.set(this, void 0);
         _MLAttr_potentialName.set(this, void 0);
         _MLAttr_potentialValue.set(this, void 0);
+        /**
+         * The whitespace token after the equal sign, or null if absent.
+         */
         this.spacesAfterEqual = null;
+        /**
+         * The whitespace token before the equal sign, or null if absent.
+         */
         this.spacesBeforeEqual = null;
+        /**
+         * The whitespace token before the attribute name, or null if absent.
+         */
         this.spacesBeforeName = null;
+        /**
+         * The start quote token of the attribute value, or null if the attribute has no value or quotes.
+         */
         this.startQuote = null;
+        /**
+         * The token representing the attribute value, or null if the attribute has no value.
+         */
         this.valueNode = null;
         /**
          * Returns the "string" if HTML syntax. Otherwise, returns a type in its syntax.
@@ -70,9 +109,8 @@ export class MLAttr extends MLNode {
         __classPrivateFieldSet(this, _MLAttr_namespaceURI, ns.namespaceURI, "f");
     }
     /**
-     * **IT THROWS AN ERROR WHEN CALLING THIS.**
+     * Returns the local name portion of the attribute (without namespace prefix).
      *
-     * @unsupported
      * @implements DOM API: `Attr`
      * @see https://dom.spec.whatwg.org/#ref-for-dom-attr-localname
      */
@@ -80,6 +118,7 @@ export class MLAttr extends MLNode {
         return __classPrivateFieldGet(this, _MLAttr_localName, "f");
     }
     /**
+     * Returns the qualified attribute name (the potential name resolved by the parser).
      *
      * @implements DOM API: `Attr`
      * @see https://dom.spec.whatwg.org/#dom-attr-name
@@ -88,9 +127,8 @@ export class MLAttr extends MLNode {
         return __classPrivateFieldGet(this, _MLAttr_potentialName, "f");
     }
     /**
-     * **IT THROWS AN ERROR WHEN CALLING THIS.**
+     * Returns the namespace URI of this attribute, resolved from the attribute name.
      *
-     * @unsupported
      * @implements DOM API: `Attr`
      * @see https://dom.spec.whatwg.org/#ref-for-dom-attr-namespaceuri
      */
@@ -111,6 +149,12 @@ export class MLAttr extends MLNode {
     get nodeType() {
         return this.ATTRIBUTE_NODE;
     }
+    /**
+     * Returns the attribute value, equivalent to the `value` property.
+     *
+     * @implements DOM API: `Attr`
+     * @see https://dom.spec.whatwg.org/#dom-node-nodevalue
+     */
     get nodeValue() {
         return this.value;
     }
@@ -173,7 +217,12 @@ export class MLAttr extends MLNode {
         this.valueNode?.fix(raw);
     }
     /**
+     * Returns a normalized string representation of the attribute,
+     * stripping extraneous whitespace around the name, equal sign, and value tokens.
+     * Falls back to the raw string if any token is missing.
+     *
      * @implements `@markuplint/ml-core` API: `MLAttr`
+     * @returns The normalized attribute string
      */
     toNormalizeString() {
         if (this.nameNode && this.equal && this.startQuote && this.valueNode && this.endQuote) {

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

@@ -4,9 +4,30 @@ import type { MarkuplintPreprocessorBlockType } from './types.js';
 import type { MLASTPreprocessorSpecificBlock, MLASTPreprocessorSpecificBlockConditionalType } from '@markuplint/ml-ast';
 import type { PlainData, RuleConfigValue } from '@markuplint/ml-config';
 import { MLNode } from './node.js';
+/**
+ * Represents a preprocessor-specific block node in the markuplint DOM tree.
+ * These nodes correspond to template engine constructs such as conditionals (`if`/`else`),
+ * loops (`each`), and other preprocessor directives that are not part of standard HTML.
+ *
+ * @template T - The rule configuration value type
+ * @template O - The rule options type
+ */
 export declare class MLBlock<T extends RuleConfigValue, O extends PlainData = undefined> extends MLNode<T, O, MLASTPreprocessorSpecificBlock> {
+    /**
+     * The type of conditional this block represents (e.g., `if`, `each`, `switch:case`).
+     */
     readonly conditionalType: MLASTPreprocessorSpecificBlockConditionalType;
+    /**
+     * Whether this block is transparent, meaning its children are treated
+     * as belonging to the parent node for tree traversal purposes.
+     */
     readonly isTransparent: boolean;
+    /**
+     * Creates a new MLBlock instance.
+     *
+     * @param astNode - The AST preprocessor block node to wrap
+     * @param document - The owning document
+     */
     constructor(astNode: MLASTPreprocessorSpecificBlock, document: MLDocument<T, O>);
     /**
      * Returns a string appropriate for the type of node as `MLBlock`

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

@@ -1,6 +1,20 @@
 import { after, before, remove, replaceWith } from '../manipulations/child-node-methods.js';
 import { MLNode } from './node.js';
+/**
+ * Represents a preprocessor-specific block node in the markuplint DOM tree.
+ * These nodes correspond to template engine constructs such as conditionals (`if`/`else`),
+ * loops (`each`), and other preprocessor directives that are not part of standard HTML.
+ *
+ * @template T - The rule configuration value type
+ * @template O - The rule options type
+ */
 export class MLBlock extends MLNode {
+    /**
+     * Creates a new MLBlock instance.
+     *
+     * @param astNode - The AST preprocessor block node to wrap
+     * @param document - The owning document
+     */
     constructor(astNode, 
     // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
     document) {

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

@@ -15,4 +15,13 @@ import type { PlainData, RuleConfigValue } from '@markuplint/ml-config';
  * @see https://dom.spec.whatwg.org/#idl-index
  */
 export type MLChildNode<T extends RuleConfigValue, O extends PlainData = undefined> = MLDocumentType<T, O> | MLCharacterData<T, O> | MLElement<T, O> | MLBlock<T, O>;
+/**
+ * Determines whether the given node is a child node type
+ * (DocumentType, CDATA, Comment, Text, Element, or preprocessor block).
+ *
+ * @template T - The rule configuration value type
+ * @template O - The rule options type
+ * @param node - The node to check
+ * @returns True if the node is one of the child node types
+ */
 export declare function isChildNode<T extends RuleConfigValue, O extends PlainData = undefined>(node: MLNode<T, O>): node is MLChildNode<T, O>;

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

@@ -1,3 +1,12 @@
+/**
+ * Determines whether the given node is a child node type
+ * (DocumentType, CDATA, Comment, Text, Element, or preprocessor block).
+ *
+ * @template T - The rule configuration value type
+ * @template O - The rule options type
+ * @param node - The node to check
+ * @returns True if the node is one of the child node types
+ */
 export function isChildNode(
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
 node) {

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

@@ -2,6 +2,13 @@ import type { CommentNodeType } from './types.js';
 import type { MLASTComment } from '@markuplint/ml-ast';
 import type { PlainData, RuleConfigValue } from '@markuplint/ml-config';
 import { MLCharacterData } from './character-data.js';
+/**
+ * Represents a DOM Comment node wrapper in the markuplint DOM tree.
+ * Wraps an AST comment token and implements the standard DOM `Comment` interface.
+ *
+ * @template T - The rule configuration value type
+ * @template O - The rule options type
+ */
 export declare class MLComment<T extends RuleConfigValue, O extends PlainData = undefined> extends MLCharacterData<T, O, MLASTComment> implements Comment {
     /**
      * Returns a string appropriate for the type of node as `Attr`

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

@@ -1,4 +1,11 @@
 import { MLCharacterData } from './character-data.js';
+/**
+ * Represents a DOM Comment node wrapper in the markuplint DOM tree.
+ * Wraps an AST comment token and implements the standard DOM `Comment` interface.
+ *
+ * @template T - The rule configuration value type
+ * @template O - The rule options type
+ */
 export class MLComment extends MLCharacterData {
     /**
      * Returns a string appropriate for the type of node as `Attr`

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

@@ -2,6 +2,14 @@ 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.
+ *
+ * @template T - The rule configuration value type
+ * @template O - The rule options type
+ */
 export declare class MLDocumentFragment<T extends RuleConfigValue, O extends PlainData = undefined> extends MLParentNode<T, O, MLASTNode> implements DocumentFragment {
     /**
      * Returns a string appropriate for the type of node as `DocumentFragment`

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

@@ -1,5 +1,13 @@
 import { MLParentNode } from './parent-node.js';
 import { UnexpectedCallError } from './unexpected-call-error.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.
+ *
+ * @template T - The rule configuration value type
+ * @template O - The rule options type
+ */
 export class MLDocumentFragment extends MLParentNode {
     /**
      * Returns a string appropriate for the type of node as `DocumentFragment`

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

@@ -4,10 +4,32 @@ import type { DocumentTypeNodeType } from './types.js';
 import type { MLASTDoctype } from '@markuplint/ml-ast';
 import type { PlainData, RuleConfigValue } from '@markuplint/ml-config';
 import { MLNode } from './node.js';
+/**
+ * Represents a DOM DocumentType node wrapper in the markuplint DOM tree.
+ * Wraps the `<!DOCTYPE ...>` declaration and implements the standard DOM `DocumentType` interface.
+ *
+ * @template T - The rule configuration value type
+ * @template O - The rule options type
+ */
 export declare class MLDocumentType<T extends RuleConfigValue, O extends PlainData = undefined> extends MLNode<T, O, MLASTDoctype> implements DocumentType {
+    /**
+     * The name of the document type (e.g., `"html"`).
+     */
     readonly name: string;
+    /**
+     * The public identifier of the document type, or an empty string if not specified.
+     */
     readonly publicId: string;
+    /**
+     * The system identifier of the document type, or an empty string if not specified.
+     */
     readonly systemId: string;
+    /**
+     * Creates a new MLDocumentType instance.
+     *
+     * @param astNode - The AST doctype node to wrap
+     * @param document - The owning document
+     */
     constructor(astNode: MLASTDoctype, document: MLDocument<T, O>);
     /**
      * Returns a string appropriate for the type of node as `DocumentType`

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

@@ -1,6 +1,19 @@
 import { after, before, remove, replaceWith } from '../manipulations/child-node-methods.js';
 import { MLNode } from './node.js';
+/**
+ * Represents a DOM DocumentType node wrapper in the markuplint DOM tree.
+ * Wraps the `<!DOCTYPE ...>` declaration and implements the standard DOM `DocumentType` interface.
+ *
+ * @template T - The rule configuration value type
+ * @template O - The rule options type
+ */
 export class MLDocumentType extends MLNode {
+    /**
+     * Creates a new MLDocumentType instance.
+     *
+     * @param astNode - The AST doctype node to wrap
+     * @param document - The owning document
+     */
     constructor(astNode, 
     // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
     document) {

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

@@ -14,6 +14,15 @@ import type { EndTagType, MLASTDocument } from '@markuplint/ml-ast';
 import type { PlainData, Pretender, RuleConfigValue } from '@markuplint/ml-config';
 import type { ARIAVersion, MLMLSpec } from '@markuplint/ml-spec';
 import { MLParentNode } from './parent-node.js';
+/**
+ * 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 declare class MLDocument<T extends RuleConfigValue, O extends PlainData = undefined> extends MLParentNode<T, O> implements Document {
     #private;
     /**
@@ -30,7 +39,9 @@ export declare class MLDocument<T extends RuleConfigValue, O extends PlainData =
      */
     readonly booleanish: boolean;
     /**
-     *
+     * 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.
      */
     currentRule: Readonly<MLRule<T, O>> | null;
     /**
@@ -40,11 +51,13 @@ export declare class MLDocument<T extends RuleConfigValue, O extends PlainData =
      */
     readonly endTag: EndTagType;
     /**
-     *
+     * Whether this document represents a fragment rather than a complete document.
+     * Fragment documents may lack root-level elements like `<html>`, `<head>`, or `<body>`.
      */
     readonly isFragment: boolean;
     /**
-     * An array of markuplint DOM nodes
+     * A flat, ordered array of all markuplint DOM nodes in the document,
+     * used for sequential traversal and token-level operations.
      */
     readonly nodeList: ReadonlyArray<MLNode<T, O>>;
     readonly ontouchcancel?: ((this: GlobalEventHandlers, ev: TouchEvent) => any) | null | undefined;
@@ -52,9 +65,14 @@ export declare class MLDocument<T extends RuleConfigValue, O extends PlainData =
     readonly ontouchmove?: ((this: GlobalEventHandlers, ev: TouchEvent) => any) | null | undefined;
     readonly ontouchstart?: ((this: GlobalEventHandlers, ev: TouchEvent) => any) | null | undefined;
     /**
-     *
+     * The ML specification data used for element/attribute lookups, ARIA role resolution,
+     * and other spec-driven computations.
      */
     readonly specs: MLMLSpec;
+    /**
+     * Whether tag name comparisons should be case-sensitive.
+     * When false (default for HTML), tag names are compared case-insensitively.
+     */
     readonly tagNameCaseSensitive: boolean;
     /**
      *
@@ -82,6 +100,14 @@ export declare class MLDocument<T extends RuleConfigValue, O extends PlainData =
      * @implements DOM API: `Document`
      */
     get activeElement(): Element | null;
+    /**
+     * **IT THROWS AN ERROR WHEN CALLING THIS.**
+     *
+     * @deprecated
+     * @unsupported
+     * @implements DOM API: `Document`
+     */
+    get activeViewTransition(): ViewTransition | null;
     /**
      * **IT THROWS AN ERROR WHEN CALLING THIS.**
      *
@@ -179,6 +205,14 @@ export declare class MLDocument<T extends RuleConfigValue, O extends PlainData =
      * @implements DOM API: `Document`
      */
     get currentScript(): HTMLOrSVGScriptElement | null;
+    /**
+     * **IT THROWS AN ERROR WHEN CALLING THIS.**
+     *
+     * @deprecated
+     * @unsupported
+     * @implements DOM API: `Document`
+     */
+    get customElementRegistry(): CustomElementRegistry | null;
     /**
      * Window object for calling the `getComputedStyle` and the `getPropertyValue` that
      * are needed by **Accessible Name and Description Computation**.
@@ -494,6 +528,14 @@ export declare class MLDocument<T extends RuleConfigValue, O extends PlainData =
      * @implements DOM API: `Document`
      */
     get onclose(): ((this: GlobalEventHandlers, ev: Event) => any) | null;
+    /**
+     * **IT THROWS AN ERROR WHEN CALLING THIS.**
+     *
+     * @deprecated
+     * @unsupported
+     * @implements DOM API: `Document`
+     */
+    get oncommand(): ((this: GlobalEventHandlers, ev: Event) => any) | null;
     /**
      * **IT THROWS AN ERROR WHEN CALLING THIS.**
      *
@@ -1435,7 +1477,11 @@ export declare class MLDocument<T extends RuleConfigValue, O extends PlainData =
      */
     createTreeWalker(root: Node, whatToShow?: number, filter?: NodeFilter | null): TreeWalker;
     /**
+     * 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(): string[];
     /**
@@ -1488,6 +1534,15 @@ export declare class MLDocument<T extends RuleConfigValue, O extends PlainData =
      * @implements DOM API: `Document`
      */
     exitPointerLock(): void;
+    /**
+     * 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(node: MLNode<T, O>, ariaVersion?: ARIAVersion): AccessibilityProperties | null;
     /**
      * **IT THROWS AN ERROR WHEN CALLING THIS.**
@@ -1536,7 +1591,11 @@ export declare class MLDocument<T extends RuleConfigValue, O extends PlainData =
      */
     getSelection(): Selection | null;
     /**
+     * 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(): readonly MLToken<import("@markuplint/ml-ast").MLASTToken>[];
     /**
@@ -1623,11 +1682,20 @@ export declare class MLDocument<T extends RuleConfigValue, O extends PlainData =
      */
     requestStorageAccess(): Promise<void>;
     /**
+     * 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: number, col: number): MLNode<T, O, import("@markuplint/ml-ast").MLASTNode> | 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: Readonly<MLRule<T, O>> | null): void;
     /**
@@ -1638,11 +1706,25 @@ export declare class MLDocument<T extends RuleConfigValue, O extends PlainData =
      */
     startViewTransition(callbackOptions?: ViewTransitionUpdateCallback): ViewTransition;
     /**
+     * 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?: boolean): string;
     /**
+     * Walks the document tree, visiting nodes of the specified type and invoking
+     * the walker callback for each one. Supports walking Element, Text, Comment,
+     * Attr, and ElementCloseTag node types.
+     *
      * @implements `@markuplint/ml-core` API: `MLDocument`
+     * @param type - The node type to walk over
+     * @param walker - The callback to invoke for each matching node
+     * @param skipWhenRuleIsDisabled - When true, skips nodes where the current rule is disabled
+     * @returns A promise that resolves when all matching nodes have been visited
      */
     walkOn(type: 'Element', walker: Walker<T, O, MLElement<T, O>>, skipWhenRuleIsDisabled?: boolean): Promise<void>;
     walkOn(type: 'Text', walker: Walker<T, O, MLText<T, O>>, skipWhenRuleIsDisabled?: boolean): Promise<void>;
@@ -1663,6 +1745,18 @@ export declare class MLDocument<T extends RuleConfigValue, O extends PlainData =
      * @implements DOM API: `Document`
      */
     writeln(...text: readonly string[]): void;
+    /**
+     * Initializes pretender contexts for all element nodes in the document.
+     *
+     * @param pretenders - Optional pretender configurations from the document options
+     */
     private _pretending;
+    /**
+     * 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
+     */
     private _ruleMapping;
 }