@markuplint/ml-core 4.13.2 → 4.18.0

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

@@ -24,7 +24,22 @@ import { toHTMLCollection } from './node-list.js';
 import { MLParentNode } from './parent-node.js';
 import { UnexpectedCallError } from './unexpected-call-error.js';
 const HTML_NAMESPACE = 'http://www.w3.org/1999/xhtml';
+/**
+ * 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 class MLElement extends MLParentNode {
+    /**
+     * 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, 
     // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
     document) {
@@ -35,6 +50,10 @@ export class MLElement extends MLParentNode {
         _MLElement_localName.set(this, void 0);
         _MLElement_normalizedAttrs.set(this, new Map());
         _MLElement_normalizedString.set(this, null);
+        /**
+         * The pretender context if this element is participating in pretender behavior,
+         * or null if it is not a pretender or pretended element.
+         */
         this.pretenderContext = null;
         __classPrivateFieldSet(this, _MLElement_attributes, astNode.attributes.map(attr => new MLAttr(attr, this)), "f");
         this.selfClosingSolidus = astNode.selfClosingSolidus ? new MLToken(astNode.selfClosingSolidus) : null;
@@ -589,6 +608,12 @@ export class MLElement extends MLParentNode {
     get assignedSlot() {
         throw new UnexpectedCallError('Not supported "assignedSlot" property');
     }
+    /**
+     * **IT THROWS AN ERROR WHEN CALLING THIS.**
+     *
+     * @unsupported
+     * @implements DOM API: `Element`
+     */
     get attributeStyleMap() {
         throw new UnexpectedCallError('Not supported "attributeStyleMap" property');
     }
@@ -724,6 +749,16 @@ export class MLElement extends MLParentNode {
     get currentCSSZoom() {
         throw new UnexpectedCallError('Not supported "currentCSSZoom" property');
     }
+    /**
+     * **IT THROWS AN ERROR WHEN CALLING THIS.**
+     *
+     * @deprecated
+     * @unsupported
+     * @implements DOM API: `Element`
+     */
+    get customElementRegistry() {
+        throw new UnexpectedCallError('Not supported "customElementRegistry" property');
+    }
     /**
      * **IT THROWS AN ERROR WHEN CALLING THIS.**
      *
@@ -765,11 +800,17 @@ export class MLElement extends MLParentNode {
         throw new UnexpectedCallError('Not supported "enterKeyHint" property');
     }
     /**
+     * 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() {
         return __classPrivateFieldGet(this, _MLElement_fixedNodeName, "f");
     }
+    /**
+     * Whether this element has any spread attributes (e.g., `{...props}` in JSX).
+     */
     get hasSpreadAttr() {
         return __classPrivateFieldGet(this, _MLElement_attributes, "f").some(attr => attr.localName === '#spread');
     }
@@ -1128,6 +1169,16 @@ export class MLElement extends MLParentNode {
     get onclose() {
         throw new UnexpectedCallError('Not supported "onclose" property');
     }
+    /**
+     * **IT THROWS AN ERROR WHEN CALLING THIS.**
+     *
+     * @deprecated
+     * @unsupported
+     * @implements DOM API: `Element`
+     */
+    get oncommand() {
+        throw new UnexpectedCallError('Not supported "oncommand" property');
+    }
     /**
      * **IT THROWS AN ERROR WHEN CALLING THIS.**
      *
@@ -2000,6 +2051,9 @@ export class MLElement extends MLParentNode {
         return previousElementSibling(this);
     }
     /**
+     * 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() {
@@ -2016,6 +2070,9 @@ export class MLElement extends MLParentNode {
         throw new UnexpectedCallError('Not supported "role" property');
     }
     /**
+     * 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() {
@@ -2287,6 +2344,12 @@ export class MLElement extends MLParentNode {
     computedStyleMap() {
         throw new UnexpectedCallError('Not supported "computedStyleMap" method');
     }
+    /**
+     * 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) {
         __classPrivateFieldSet(this, _MLElement_fixedNodeName, name, "f");
     }
@@ -2303,7 +2366,12 @@ export class MLElement extends MLParentNode {
         throw new UnexpectedCallError('Not supported "focus" method');
     }
     /**
+     * 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) {
         return getAccname(this, version);
@@ -2367,7 +2435,12 @@ export class MLElement extends MLParentNode {
         throw new UnexpectedCallError('Not supported "getAttributeNodeNS" method');
     }
     /**
+     * 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) {
         for (const attr of __classPrivateFieldGet(this, _MLElement_attributes, "f")) {
@@ -2378,7 +2451,12 @@ export class MLElement extends MLParentNode {
         return 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) {
         const attrs = [];
@@ -2391,7 +2469,11 @@ export class MLElement extends MLParentNode {
         return attrs;
     }
     /**
+     * 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() {
         return Object.freeze(this.pretenderContext?.type === 'pretender' ? __classPrivateFieldGet(this.pretenderContext.as, _MLElement_attributes, "f") : __classPrivateFieldGet(this, _MLElement_attributes, "f"));
@@ -2406,6 +2488,13 @@ export class MLElement extends MLParentNode {
     getBoundingClientRect() {
         throw new UnexpectedCallError('Not supported "getBoundingClientRect" method');
     }
+    /**
+     * 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() {
         if (__classPrivateFieldGet(this, _MLElement_getChildElementsAndTextNodeWithoutWhitespacesCache, "f")) {
             return __classPrivateFieldGet(this, _MLElement_getChildElementsAndTextNodeWithoutWhitespacesCache, "f");
@@ -2481,7 +2570,10 @@ export class MLElement extends MLParentNode {
         throw new UnexpectedCallError('Does not implement "getHTML" method yet');
     }
     /**
+     * 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() {
         return {
@@ -2515,7 +2607,11 @@ export class MLElement extends MLParentNode {
         return this.attributes.length > 0;
     }
     /**
+     * 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() {
         for (const attr of this.attributes) {
@@ -2529,9 +2625,13 @@ export class MLElement extends MLParentNode {
         return false;
     }
     /**
-     * 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 = false) {
         for (const child of this.getPureChildNodes()) {
@@ -2611,7 +2711,12 @@ export class MLElement extends MLParentNode {
         throw new UnexpectedCallError('Does not implement "insertAdjacentText" method yet');
     }
     /**
+     * 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) {
         let el = this.parentElement;
@@ -2627,7 +2732,11 @@ export class MLElement extends MLParentNode {
         return false;
     }
     /**
+     * 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() {
         for (const childNode of this.childNodes) {
@@ -2637,15 +2746,20 @@ export class MLElement extends MLParentNode {
         }
         return true;
     }
-    /**
-     * @implements DOM API: `Element`
-     * @see https://dom.spec.whatwg.org/#ref-for-dom-element-matches%E2%91%A0
-     */
     matches(selector, 
     // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
     scope) {
         return this.matchMLSelector(selector, scope).matched;
     }
+    /**
+     * 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, 
     // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
     scope) {
@@ -2669,7 +2783,11 @@ export class MLElement extends MLParentNode {
         return matched;
     }
     /**
-     * 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) {
         const pretenderConfig = pretenders?.find(option => this.matches(option.selector));
@@ -2967,7 +3085,12 @@ export class MLElement extends MLParentNode {
         throw new UnexpectedCallError('Not supported "showPopover" method');
     }
     /**
+     * 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() {
         if (__classPrivateFieldGet(this, _MLElement_normalizedString, "f")) {
@@ -2989,7 +3112,13 @@ export class MLElement extends MLParentNode {
         return normalizedString;
     }
     /**
+     * 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 = false) {
         if (!fixed) {

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

@@ -8,6 +8,15 @@ import type { RuleInfo } from '../../index.js';
 import type { MLASTNode } from '@markuplint/ml-ast';
 import type { AnyRule, PlainData, RuleConfigValue } from '@markuplint/ml-config';
 import { MLToken } from '../token/token.js';
+/**
+ * Abstract base class for all markuplint DOM node wrappers.
+ * Extends `MLToken` with DOM `Node` interface compliance, tree traversal,
+ * rule configuration access, and child node management.
+ *
+ * @template T - The rule configuration value type
+ * @template O - The rule options type
+ * @template A - The underlying AST node type
+ */
 export declare abstract class MLNode<T extends RuleConfigValue, O extends PlainData = undefined, A extends MLASTNode = MLASTNode> extends MLToken<A> implements Node {
     #private;
     /**
@@ -201,6 +210,13 @@ export declare abstract class MLNode<T extends RuleConfigValue, O extends PlainD
      * @see https://dom.spec.whatwg.org/#ref-for-dom-node-ownerdocument%E2%91%A0
      */
     get ownerDocument(): any;
+    /**
+     * The owning `MLDocument` instance with proper generic types,
+     * providing type-safe access to the document without the `any` type
+     * used by the DOM-compatible `ownerDocument`.
+     *
+     * @implements `@markuplint/ml-core` API: `MLNode`
+     */
     get ownerMLDocument(): MLDocument<T, O>;
     /**
      * The parent element.
@@ -423,6 +439,13 @@ export declare abstract class MLNode<T extends RuleConfigValue, O extends PlainD
      * @see https://dom.spec.whatwg.org/#dom-node-insertbefore
      */
     insertBefore<T extends Node>(node: T, child: Node | null): T;
+    /**
+     * **IT THROWS AN ERROR WHEN CALLING THIS.**
+     *
+     * @unsupported
+     * @implements DOM API: `Node`
+     */
+    moveBefore(node: Node, child: Node | null): Node;
     /**
      * @implements `@markuplint/ml-core` API: `MLNode`
      */

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

@@ -16,6 +16,15 @@ import { isChildNode } from './child-node.js';
 import { toNodeList } from './node-list.js';
 import { nodeStore } from './node-store.js';
 import { UnexpectedCallError } from './unexpected-call-error.js';
+/**
+ * Abstract base class for all markuplint DOM node wrappers.
+ * Extends `MLToken` with DOM `Node` interface compliance, tree traversal,
+ * rule configuration access, and child node management.
+ *
+ * @template T - The rule configuration value type
+ * @template O - The rule options type
+ * @template A - The underlying AST node type
+ */
 export class MLNode extends MLToken {
     constructor(astNode, 
     // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
@@ -271,6 +280,13 @@ export class MLNode extends MLToken {
     get ownerDocument() {
         return __classPrivateFieldGet(this, _MLNode_ownerDocument, "f");
     }
+    /**
+     * The owning `MLDocument` instance with proper generic types,
+     * providing type-safe access to the document without the `any` type
+     * used by the DOM-compatible `ownerDocument`.
+     *
+     * @implements `@markuplint/ml-core` API: `MLNode`
+     */
     get ownerMLDocument() {
         return __classPrivateFieldGet(this, _MLNode_ownerDocument, "f");
     }
@@ -743,6 +759,19 @@ export class MLNode extends MLToken {
     child) {
         throw new UnexpectedCallError('Not supported "insertBefore" method');
     }
+    /**
+     * **IT THROWS AN ERROR WHEN CALLING THIS.**
+     *
+     * @unsupported
+     * @implements DOM API: `Node`
+     */
+    moveBefore(
+    // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+    node, 
+    // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+    child) {
+        throw new UnexpectedCallError('Not supported "moveBefore" method');
+    }
     /**
      * @implements `@markuplint/ml-core` API: `MLNode`
      */

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

@@ -2,6 +2,14 @@ import type { TextNodeType } from './types.js';
 import type { MLASTText } from '@markuplint/ml-ast';
 import type { PlainData, RuleConfigValue } from '@markuplint/ml-config';
 import { MLCharacterData } from './character-data.js';
+/**
+ * Represents a DOM Text node wrapper in the markuplint DOM tree.
+ * Wraps an AST text token and provides text-specific operations such as
+ * detecting raw text element content and whitespace-only nodes.
+ *
+ * @template T - The rule configuration value type
+ * @template O - The rule options type
+ */
 export declare class MLText<T extends RuleConfigValue, O extends PlainData = undefined> extends MLCharacterData<T, O, MLASTText> implements Text {
     /**
      * **IT THROWS AN ERROR WHEN CALLING THIS.**
@@ -33,10 +41,14 @@ export declare class MLText<T extends RuleConfigValue, O extends PlainData = und
      *
      * @implements `@markuplint/ml-core` API: `MLText`
      * @see https://html.spec.whatwg.org/multipage/syntax.html#raw-text-elements
+     * @returns True if this text node is the content of a raw text element
      */
     isRawTextElementContent(): boolean;
     /**
+     * Checks whether this text node contains only whitespace characters.
+     *
      * @implements `@markuplint/ml-core` API: `MLText`
+     * @returns True if the raw content is composed entirely of whitespace
      */
     isWhitespace(): boolean;
     /**

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

@@ -6,6 +6,14 @@ import { UnexpectedCallError } from './unexpected-call-error.js';
  * @see https://html.spec.whatwg.org/multipage/syntax.html#raw-text-elements
  */
 const rawTextElements = new Set(['script', 'style']);
+/**
+ * Represents a DOM Text node wrapper in the markuplint DOM tree.
+ * Wraps an AST text token and provides text-specific operations such as
+ * detecting raw text element content and whitespace-only nodes.
+ *
+ * @template T - The rule configuration value type
+ * @template O - The rule options type
+ */
 export class MLText extends MLCharacterData {
     /**
      * **IT THROWS AN ERROR WHEN CALLING THIS.**
@@ -45,12 +53,16 @@ export class MLText extends MLCharacterData {
      *
      * @implements `@markuplint/ml-core` API: `MLText`
      * @see https://html.spec.whatwg.org/multipage/syntax.html#raw-text-elements
+     * @returns True if this text node is the content of a raw text element
      */
     isRawTextElementContent() {
         return this.parentElement ? rawTextElements.has(this.parentElement.nodeName.toLowerCase()) : false;
     }
     /**
+     * Checks whether this text node contains only whitespace characters.
+     *
      * @implements `@markuplint/ml-core` API: `MLText`
+     * @returns True if the raw content is composed entirely of whitespace
      */
     isWhitespace() {
         return /^\s+$/.test(this.raw);

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

@@ -9,30 +9,91 @@ import type { MLText } from './text.js';
 import type { MLToken } from '../token/token.js';
 import type { MLASTAttr, MLASTComment, MLASTDoctype, MLASTElement, MLASTInvalid, MLASTParentNode, MLASTPreprocessorSpecificBlock, MLASTText, MLASTToken as MLASTToken } from '@markuplint/ml-ast/';
 import type { PlainData, PretenderARIA, RuleConfigValue } from '@markuplint/ml-config';
+/**
+ * Maps an AST node type to its corresponding markuplint DOM node wrapper type.
+ *
+ * @template N - The AST node type to map from
+ * @template T - The rule configuration value type
+ * @template O - The rule options type
+ */
 export type MappedNode<N, T extends RuleConfigValue, O extends PlainData = undefined> = N extends MLASTElement ? MLElement<T, O> : N extends MLASTParentNode ? MLElement<T, O> : N extends MLASTComment ? MLComment<T, O> : N extends MLASTText ? MLText<T, O> : N extends MLASTDoctype ? MLDocumentType<T, O> : N extends MLASTPreprocessorSpecificBlock ? MLBlock<T, O> : N extends MLASTAttr ? MLAttr<T, O> : N extends MLASTInvalid ? MLText<T, O> : N extends MLASTToken ? MLToken : never;
+/**
+ * Resolves a numeric node type constant to its corresponding markuplint DOM node class type.
+ * Used for type narrowing via the `is()` method on nodes.
+ *
+ * @template NT - The numeric node type constant
+ * @template T - The rule configuration value type
+ * @template O - The rule options type
+ */
 export type NodeTypeOf<NT extends NodeType, T extends RuleConfigValue, O extends PlainData = undefined> = NT extends ElementNodeType ? MLElement<T, O> : NT extends CommentNodeType ? MLComment<T, O> : NT extends TextNodeType ? MLText<T, O> : NT extends DocumentNodeType ? MLDocument<T, O> : NT extends DocumentTypeNodeType ? MLDocumentType<T, O> : NT extends DocumentFragmentNodeType ? MLDocumentFragment<T, O> : NT extends MarkuplintPreprocessorBlockType ? MLBlock<T, O> : NT extends AttributeNodeType ? MLAttr<T, O> : never;
+/** Numeric constant representing an Element node (corresponds to DOM `Node.ELEMENT_NODE`). */
 export type ElementNodeType = 1;
+/** Numeric constant representing an Attribute node (corresponds to DOM `Node.ATTRIBUTE_NODE`). */
 export type AttributeNodeType = 2;
+/** Numeric constant representing a Text node (corresponds to DOM `Node.TEXT_NODE`). */
 export type TextNodeType = 3;
+/** Numeric constant representing a CDATA Section node (corresponds to DOM `Node.CDATA_SECTION_NODE`). */
 export type CDATASectionNodeType = 4;
+/** Numeric constant representing a Processing Instruction node (corresponds to DOM `Node.PROCESSING_INSTRUCTION_NODE`). */
 export type ProcessingInstructionNodeType = 7;
+/** Numeric constant representing a Comment node (corresponds to DOM `Node.COMMENT_NODE`). */
 export type CommentNodeType = 8;
+/** Numeric constant representing a Document node (corresponds to DOM `Node.DOCUMENT_NODE`). */
 export type DocumentNodeType = 9;
+/** Numeric constant representing a DocumentType node (corresponds to DOM `Node.DOCUMENT_TYPE_NODE`). */
 export type DocumentTypeNodeType = 10;
+/** Numeric constant representing a DocumentFragment node (corresponds to DOM `Node.DOCUMENT_FRAGMENT_NODE`). */
 export type DocumentFragmentNodeType = 11;
+/** Numeric constant representing a markuplint preprocessor block node, used for template engine constructs. */
 export type MarkuplintPreprocessorBlockType = 101;
+/**
+ * Union of all supported node type constants in the markuplint DOM,
+ * including standard DOM node types and the markuplint-specific preprocessor block type.
+ */
 export type NodeType = ElementNodeType | AttributeNodeType | TextNodeType | CDATASectionNodeType | ProcessingInstructionNodeType | CommentNodeType | DocumentNodeType | DocumentTypeNodeType | DocumentFragmentNodeType | MarkuplintPreprocessorBlockType;
+/**
+ * Represents the pretender context for an element, which can be either
+ * a pretender (an element acting as another) or a pretended element (the original).
+ *
+ * @template N - The element type
+ * @template T - The rule configuration value type
+ * @template O - The rule options type
+ */
 export type PretenderContext<N extends MLElement<T, O>, T extends RuleConfigValue, O extends PlainData = undefined> = PretenderContextPretender<N, T, O> | PretenderContextPretended<N, T, O>;
+/**
+ * Context for an element that is pretending to be another element.
+ * Contains the target element it is pretending to be and optional ARIA overrides.
+ *
+ * @template N - The element type
+ * @template T - The rule configuration value type
+ * @template O - The rule options type
+ */
 export type PretenderContextPretender<N extends MLElement<T, O>, T extends RuleConfigValue, O extends PlainData = undefined> = {
     readonly type: 'pretender';
     readonly as: N;
     readonly aria?: PretenderARIA;
 };
+/**
+ * Context for the original element that has been pretended by another element.
+ * Contains a reference back to the pretending origin element.
+ *
+ * @template N - The element type
+ * @template T - The rule configuration value type
+ * @template O - The rule options type
+ */
 export type PretenderContextPretended<N extends MLElement<T, O>, T extends RuleConfigValue, O extends PlainData = undefined> = {
     readonly type: 'origin';
     readonly origin: N;
 };
+/**
+ * Represents the computed accessibility properties for a node,
+ * which may be clearly resolved or unknown.
+ */
 export type AccessibilityProperties = ClearlyAccessibilityProperties | UnknownAccessibilityProperties;
+/**
+ * Resolved accessibility properties for a node, including its ARIA role,
+ * accessible name, focusability, and related ARIA property values.
+ */
 export type ClearlyAccessibilityProperties = {
     unknown: false;
     exposedToTree: boolean;
@@ -46,9 +107,16 @@ export type ClearlyAccessibilityProperties = {
     focusable?: boolean;
     props?: Record<string, AccessibilityProperty>;
 };
+/**
+ * Represents accessibility properties that could not be resolved,
+ * typically when the element or its role is not recognized.
+ */
 export type UnknownAccessibilityProperties = {
     unknown: true;
 };
+/**
+ * A single ARIA property with its computed value and whether it is required for the role.
+ */
 export type AccessibilityProperty = {
     value: string | null;
     required: boolean;

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

@@ -1,47 +1,89 @@
 import type { MLASTToken } from '@markuplint/ml-ast';
+/**
+ * Represents a single token in the markuplint AST.
+ * Wraps an AST token with positional information (line, column, offset)
+ * and provides both raw and fixed string representations.
+ *
+ * @template A - The AST token type this token wraps
+ */
 export declare class MLToken<A extends MLASTToken = MLASTToken> {
     #private;
+    /**
+     * The unique identifier for this token.
+     */
     readonly uuid: string;
+    /**
+     * The underlying AST token that this token wraps.
+     */
     protected readonly _astToken: A;
+    /**
+     * Creates a new MLToken instance from an AST token.
+     *
+     * @param astToken - The AST token to wrap
+     */
     constructor(astToken: A);
     /**
+     * The ending column number (1-based) of this token in the source.
+     *
      * @implements `@markuplint/ml-core` API: `MLDOMToken`
      */
     get endCol(): number;
     /**
+     * The ending line number (1-based) of this token in the source.
+     *
      * @implements `@markuplint/ml-core` API: `MLDOMToken`
      */
     get endLine(): number;
     /**
+     * The ending character offset (0-based) of this token in the source.
+     *
      * @implements `@markuplint/ml-core` API: `MLDOMToken`
      */
     get endOffset(): number;
     /**
+     * The fixed (potentially modified) string content of this token.
+     *
      * @implements `@markuplint/ml-core` API: `MLDOMToken`
      */
     get fixed(): string;
     /**
+     * The original raw string content of this token from the source.
+     *
      * @implements `@markuplint/ml-core` API: `MLDOMToken`
      */
     get raw(): string;
     /**
+     * The starting column number (1-based) of this token in the source.
+     *
      * @implements `@markuplint/ml-core` API: `MLDOMToken`
      */
     get startCol(): number;
     /**
+     * The starting line number (1-based) of this token in the source.
+     *
      * @implements `@markuplint/ml-core` API: `MLDOMToken`
      */
     get startLine(): number;
     /**
+     * The starting character offset (0-based) of this token in the source.
+     *
      * @implements `@markuplint/ml-core` API: `MLDOMToken`
      */
     get startOffset(): number;
     /**
+     * Replaces the fixed content of this token with the given string,
+     * used when applying lint fixes.
+     *
      * @implements `@markuplint/ml-core` API: `MLDOMToken`
+     * @param raw - The new string content to set as the fixed value
      */
     fix(raw: string): void;
     /**
+     * Returns the string representation of this token.
+     *
      * @implements `@markuplint/ml-core` API: `MLDOMToken`
+     * @param fixed - When true, returns the fixed content; otherwise returns the original raw content
+     * @returns The string content of this token
      */
     toString(fixed?: boolean): string;
 }