npm - @markuplint/ml-core - Versions diffs - 4.13.1 → 4.13.3 - Mend

@markuplint/ml-core 4.13.1 → 4.13.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (80) hide show

package/ARCHITECTURE.ja.md +467 -0
package/ARCHITECTURE.md +467 -0
package/CHANGELOG.md +5 -1
package/README.md +5 -0
package/SKILL.md +61 -0
package/docs/linting-pipeline.ja.md +303 -0
package/docs/linting-pipeline.md +303 -0
package/docs/maintenance.ja.md +210 -0
package/docs/maintenance.md +210 -0
package/docs/ml-dom/attr.ja.md +95 -0
package/docs/ml-dom/attr.md +95 -0
package/docs/ml-dom/block.ja.md +272 -0
package/docs/ml-dom/block.md +272 -0
package/docs/ml-dom/document.ja.md +141 -0
package/docs/ml-dom/document.md +141 -0
package/docs/ml-dom/element.ja.md +176 -0
package/docs/ml-dom/element.md +176 -0
package/docs/ml-dom/helpers.ja.md +203 -0
package/docs/ml-dom/helpers.md +203 -0
package/docs/ml-dom/node.ja.md +200 -0
package/docs/ml-dom/node.md +200 -0
package/docs/ml-dom/others.ja.md +119 -0
package/docs/ml-dom/others.md +119 -0
package/docs/ml-dom/overview.ja.md +102 -0
package/docs/ml-dom/overview.md +102 -0
package/docs/ml-dom/pretender.ja.md +269 -0
package/docs/ml-dom/pretender.md +269 -0
package/docs/ml-dom/rule-mapping.ja.md +371 -0
package/docs/ml-dom/rule-mapping.md +371 -0
package/docs/ml-dom.ja.md +18 -0
package/docs/ml-dom.md +18 -0
package/docs/rule-system.ja.md +270 -0
package/docs/rule-system.md +270 -0
package/lib/convert-ruleset.d.ts +7 -0
package/lib/convert-ruleset.js +7 -0
package/lib/debug.d.ts +4 -0
package/lib/debug.js +4 -0
package/lib/ml-core.d.ts +36 -0
package/lib/ml-core.js +29 -0
package/lib/ml-dom/helper/get-indent.d.ts +4 -1
package/lib/ml-dom/helper/get-indent.js +4 -1
package/lib/ml-dom/node/attr.d.ts +65 -4
package/lib/ml-dom/node/attr.js +53 -4
package/lib/ml-dom/node/block.d.ts +21 -0
package/lib/ml-dom/node/block.js +14 -0
package/lib/ml-dom/node/child-node.d.ts +9 -0
package/lib/ml-dom/node/child-node.js +9 -0
package/lib/ml-dom/node/comment.d.ts +7 -0
package/lib/ml-dom/node/comment.js +7 -0
package/lib/ml-dom/node/document-fragment.d.ts +8 -0
package/lib/ml-dom/node/document-fragment.js +8 -0
package/lib/ml-dom/node/document-type.d.ts +22 -0
package/lib/ml-dom/node/document-type.js +13 -0
package/lib/ml-dom/node/document.d.ts +74 -4
package/lib/ml-dom/node/document.js +57 -2
package/lib/ml-dom/node/element.d.ts +136 -2
package/lib/ml-dom/node/element.js +115 -2
package/lib/ml-dom/node/node.d.ts +16 -0
package/lib/ml-dom/node/node.js +16 -0
package/lib/ml-dom/node/text.d.ts +12 -0
package/lib/ml-dom/node/text.js +12 -0
package/lib/ml-dom/node/types.d.ts +68 -0
package/lib/ml-dom/token/token.d.ts +42 -0
package/lib/ml-dom/token/token.js +36 -0
package/lib/ml-rule/create-rule.d.ts +9 -0
package/lib/ml-rule/create-rule.js +9 -0
package/lib/ml-rule/ml-rule.d.ts +33 -0
package/lib/ml-rule/ml-rule.js +30 -0
package/lib/ml-rule/types.d.ts +41 -0
package/lib/plugin/plugin.d.ts +8 -0
package/lib/plugin/plugin.js +8 -0
package/lib/plugin/types.d.ts +21 -0
package/lib/ruleset/index.d.ts +10 -0
package/lib/ruleset/index.js +7 -0
package/lib/test/index.d.ts +42 -1
package/lib/test/index.js +35 -1
package/lib/types.d.ts +8 -0
package/lib/violation-collector.d.ts +33 -0
package/lib/violation-collector.js +33 -0
package/package.json +13 -13

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

@@ -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.**
@@ -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`
@@ -588,9 +634,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.**
@@ -1560,6 +1612,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 +1627,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 +1820,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 +1836,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 +1884,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 +1917,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 +1960,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 +1989,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,11 +2047,20 @@ 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;
     /**
@@ -1958,9 +2068,22 @@ export declare class MLElement<T extends RuleConfigValue, O extends PlainData =
      * @see https://dom.spec.whatwg.org/#ref-for-dom-element-matches%E2%91%A0
      */
     matches(selector: 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 +2231,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;
     /**

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

@@ -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');
     }
@@ -765,11 +790,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');
     }
@@ -2000,6 +2031,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 +2050,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 +2324,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 +2346,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 +2415,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 +2431,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 +2449,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 +2468,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 +2550,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 +2587,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 +2605,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 +2691,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 +2712,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) {
@@ -2646,6 +2735,15 @@ export class MLElement extends MLParentNode {
     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 +2767,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 +3069,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 +3096,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 CHANGED Viewed

@@ -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.

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

@@ -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");
     }

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

@@ -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 CHANGED Viewed

@@ -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);