@markuplint/ml-core 4.13.2 → 5.0.0-alpha.0

package/lib/ml-dom/helper/get-indent.js

@@ -1,19 +1,10 @@
-var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
-    if (kind === "m") throw new TypeError("Private method is not writable");
-    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
-    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
-    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
-};
-var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
-    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
-    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
-    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
-};
-var _MLDOMIndentation_fixed, _MLDOMIndentation_node, _MLDOMIndentation_parent;
 /**
+ * Computes the indentation preceding the given node by analyzing
+ * the whitespace in adjacent text nodes.
  *
  * @deprecated
- * @param node
+ * @param node - The node whose indentation to determine
+ * @returns An indentation object describing the whitespace, or null if no indentation is found
  */
 export function getIndent(
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
@@ -59,52 +50,52 @@ node) {
     return null;
 }
 class MLDOMIndentation {
+    #fixed;
+    line;
+    #node;
+    #parent;
     constructor(
     // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
     originTextNode, raw, line, 
     // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
     parentNode) {
-        _MLDOMIndentation_fixed.set(this, void 0);
-        _MLDOMIndentation_node.set(this, void 0);
-        _MLDOMIndentation_parent.set(this, void 0);
         this.line = line;
-        __classPrivateFieldSet(this, _MLDOMIndentation_node, originTextNode, "f");
-        __classPrivateFieldSet(this, _MLDOMIndentation_parent, parentNode, "f");
-        __classPrivateFieldSet(this, _MLDOMIndentation_fixed, raw, "f");
+        this.#node = originTextNode;
+        this.#parent = parentNode;
+        this.#fixed = raw;
     }
     get raw() {
-        if (!__classPrivateFieldGet(this, _MLDOMIndentation_parent, "f").is(__classPrivateFieldGet(this, _MLDOMIndentation_parent, "f").TEXT_NODE) && this.line !== __classPrivateFieldGet(this, _MLDOMIndentation_node, "f").endLine) {
+        if (!this.#parent.is(this.#parent.TEXT_NODE) && this.line !== this.#node.endLine) {
             return '';
         }
-        return __classPrivateFieldGet(this, _MLDOMIndentation_fixed, "f");
+        return this.#fixed;
     }
     get type() {
-        if (!__classPrivateFieldGet(this, _MLDOMIndentation_parent, "f").is(__classPrivateFieldGet(this, _MLDOMIndentation_parent, "f").TEXT_NODE) && this.line !== __classPrivateFieldGet(this, _MLDOMIndentation_node, "f").endLine) {
+        if (!this.#parent.is(this.#parent.TEXT_NODE) && this.line !== this.#node.endLine) {
             return 'none';
         }
-        const raw = __classPrivateFieldGet(this, _MLDOMIndentation_fixed, "f");
+        const raw = this.#fixed;
         return raw === '' ? 'none' : /^\t+$/.test(raw) ? 'tab' : /^[^\t]+$/.test(raw) ? 'space' : 'mixed';
     }
     get width() {
-        if (!__classPrivateFieldGet(this, _MLDOMIndentation_parent, "f").is(__classPrivateFieldGet(this, _MLDOMIndentation_parent, "f").TEXT_NODE) && this.line !== __classPrivateFieldGet(this, _MLDOMIndentation_node, "f").endLine) {
+        if (!this.#parent.is(this.#parent.TEXT_NODE) && this.line !== this.#node.endLine) {
             return 0;
         }
-        return __classPrivateFieldGet(this, _MLDOMIndentation_fixed, "f").length;
+        return this.#fixed.length;
     }
     fix(raw) {
-        const current = __classPrivateFieldGet(this, _MLDOMIndentation_fixed, "f");
-        __classPrivateFieldSet(this, _MLDOMIndentation_fixed, raw, "f");
-        const node = __classPrivateFieldGet(this, _MLDOMIndentation_node, "f");
+        const current = this.#fixed;
+        this.#fixed = raw;
+        const node = this.#node;
         const line = node.startLine;
         const lines = node.raw.split(/\r?\n/);
         const index = this.line - line;
         if (lines[index] != null) {
-            lines[index] = lines[index].replace(current, __classPrivateFieldGet(this, _MLDOMIndentation_fixed, "f"));
+            lines[index] = lines[index].replace(current, this.#fixed);
         }
         node.fix(lines.join('\n'));
     }
 }
-_MLDOMIndentation_fixed = new WeakMap(), _MLDOMIndentation_node = new WeakMap(), _MLDOMIndentation_parent = new WeakMap();
 function isFirstToken(
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
 node) {

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

@@ -5,24 +5,69 @@ import type { PlainData, RuleConfigValue } from '@markuplint/ml-config';
 import { MLToken } from '../token/token.js';
 import { MLDomTokenList } from './dom-token-list.js';
 import { MLNode } from './node.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 declare class MLAttr<T extends RuleConfigValue, O extends PlainData = undefined> extends MLNode<T, O, MLASTAttr> implements Attr {
     #private;
+    /**
+     * A candidate attribute name suggested by the parser, if available.
+     */
     readonly candidate?: string;
+    /**
+     * The end quote token of the attribute value, or null if the attribute has no value or quotes.
+     */
     readonly endQuote: MLToken | null;
+    /**
+     * The equal sign token between the attribute name and value, or null if absent.
+     */
     readonly equal: MLToken | null;
+    /**
+     * Whether this attribute is a directive (e.g., framework-specific attributes like `v-if` or `@click`).
+     */
     readonly isDirective?: true;
+    /**
+     * Whether this attribute can be duplicated on the same element.
+     */
     readonly isDuplicatable: boolean;
+    /**
+     * Whether this attribute has a dynamic value (e.g., a template expression rather than a static string).
+     */
     readonly isDynamicValue?: true;
+    /**
+     * The token representing the attribute name, or null for spread attributes.
+     */
     readonly nameNode: MLToken | null;
     /**
      * @implements DOM API: `Attr`
      * @see https://dom.spec.whatwg.org/#ref-for-dom-node-previoussibling%E2%91%A0
      */
     readonly ownerElement: MLElement<T, O>;
+    /**
+     * The whitespace token after the equal sign, or null if absent.
+     */
     readonly spacesAfterEqual: MLToken | null;
+    /**
+     * The whitespace token before the equal sign, or null if absent.
+     */
     readonly spacesBeforeEqual: MLToken | null;
+    /**
+     * The whitespace token before the attribute name, or null if absent.
+     */
     readonly spacesBeforeName: MLToken | null;
+    /**
+     * The start quote token of the attribute value, or null if the attribute has no value or quotes.
+     */
     readonly startQuote: MLToken | null;
+    /**
+     * The token representing the attribute value, or null if the attribute has no value.
+     */
     readonly valueNode: MLToken | null;
     /**
      * Returns the "string" if HTML syntax. Otherwise, returns a type in its syntax.
@@ -31,25 +76,30 @@ export declare class MLAttr<T extends RuleConfigValue, O extends PlainData = und
      * @implements `@markuplint/ml-core` API: `MLAttr`
      */
     readonly valueType: 'string' | 'number' | 'boolean' | 'code';
+    /**
+     * 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: MLASTAttr, ownElement: MLElement<T, O>);
     /**
-     * **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
      */
     get localName(): string;
     /**
+     * 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
      */
     get name(): string;
     /**
-     * **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
      */
@@ -64,6 +114,12 @@ export declare class MLAttr<T extends RuleConfigValue, O extends PlainData = und
      * Returns a number appropriate for the type of `Attr`
      */
     get nodeType(): AttributeNodeType;
+    /**
+     * Returns the attribute value, equivalent to the `value` property.
+     *
+     * @implements DOM API: `Attr`
+     * @see https://dom.spec.whatwg.org/#dom-node-nodevalue
+     */
     get nodeValue(): string;
     /**
      * **IT THROWS AN ERROR WHEN CALLING THIS.**
@@ -106,7 +162,12 @@ export declare class MLAttr<T extends RuleConfigValue, O extends PlainData = und
      */
     fix(raw: string): void;
     /**
+     * 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(): string;
     /**

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

@@ -1,51 +1,100 @@
-var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
-    if (kind === "m") throw new TypeError("Private method is not writable");
-    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
-    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
-    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
-};
-var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
-    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
-    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
-    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
-};
-var _MLAttr_localName, _MLAttr_namespaceURI, _MLAttr_potentialName, _MLAttr_potentialValue;
-import { resolveNamespace } from '@markuplint/ml-spec';
+import { resolveNamespace, compileDirectivePatterns, resolveDirective } from '@markuplint/ml-spec';
+import { searchIDLAttribute } from '@markuplint/parser-utils';
 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 {
+    /**
+     * A candidate attribute name suggested by the parser, if available.
+     */
+    candidate;
+    /**
+     * The end quote token of the attribute value, or null if the attribute has no value or quotes.
+     */
+    endQuote = null;
+    /**
+     * The equal sign token between the attribute name and value, or null if absent.
+     */
+    equal = null;
+    /**
+     * Whether this attribute is a directive (e.g., framework-specific attributes like `v-if` or `@click`).
+     */
+    isDirective;
+    /**
+     * Whether this attribute can be duplicated on the same element.
+     */
+    isDuplicatable;
+    /**
+     * Whether this attribute has a dynamic value (e.g., a template expression rather than a static string).
+     */
+    isDynamicValue;
+    #localName;
+    /**
+     * The token representing the attribute name, or null for spread attributes.
+     */
+    nameNode = null;
+    #namespaceURI;
+    /**
+     * @implements DOM API: `Attr`
+     * @see https://dom.spec.whatwg.org/#ref-for-dom-node-previoussibling%E2%91%A0
+     */
+    ownerElement;
+    #potentialName;
+    #potentialValue;
+    /**
+     * The whitespace token after the equal sign, or null if absent.
+     */
+    spacesAfterEqual = null;
+    /**
+     * The whitespace token before the equal sign, or null if absent.
+     */
+    spacesBeforeEqual = null;
+    /**
+     * The whitespace token before the attribute name, or null if absent.
+     */
+    spacesBeforeName = null;
+    /**
+     * The start quote token of the attribute value, or null if the attribute has no value or quotes.
+     */
+    startQuote = null;
+    /**
+     * The token representing the attribute value, or null if the attribute has no value.
+     */
+    valueNode = null;
+    /**
+     * Returns the "string" if HTML syntax. Otherwise, returns a type in its syntax.
+     *
+     * @default "string"
+     * @implements `@markuplint/ml-core` API: `MLAttr`
+     */
+    valueType = 'string';
+    /**
+     * Creates a new MLAttr instance from an AST attribute token.
+     *
+     * @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);
-        this.endQuote = null;
-        this.equal = null;
-        _MLAttr_localName.set(this, void 0);
-        this.nameNode = null;
-        _MLAttr_namespaceURI.set(this, void 0);
-        _MLAttr_potentialName.set(this, void 0);
-        _MLAttr_potentialValue.set(this, void 0);
-        this.spacesAfterEqual = null;
-        this.spacesBeforeEqual = null;
-        this.spacesBeforeName = null;
-        this.startQuote = null;
-        this.valueNode = null;
-        /**
-         * Returns the "string" if HTML syntax. Otherwise, returns a type in its syntax.
-         *
-         * @default "string"
-         * @implements `@markuplint/ml-core` API: `MLAttr`
-         */
-        this.valueType = 'string';
         this.ownerElement = ownElement;
         if (this._astToken.type === 'spread') {
-            __classPrivateFieldSet(this, _MLAttr_namespaceURI, ownElement.namespaceURI, "f");
+            this.#namespaceURI = ownElement.namespaceURI;
             this.valueType = 'code';
-            __classPrivateFieldSet(this, _MLAttr_localName, '#spread', "f");
-            __classPrivateFieldSet(this, _MLAttr_potentialName, '#spread', "f");
-            __classPrivateFieldSet(this, _MLAttr_potentialValue, this._astToken.raw, "f");
+            this.#localName = '#spread';
+            this.#potentialName = '#spread';
+            this.#potentialValue = this._astToken.raw;
             this.isDirective = true;
             this.isDynamicValue = true;
             this.isDuplicatable = true;
@@ -59,43 +108,82 @@ export class MLAttr extends MLNode {
         this.startQuote = new MLToken(this._astToken.startQuote);
         this.valueNode = new MLToken(this._astToken.value);
         this.endQuote = new MLToken(this._astToken.endQuote);
-        this.isDynamicValue = this._astToken.isDynamicValue;
-        this.isDirective = this._astToken.isDirective;
         this.candidate = this._astToken.candidate;
-        __classPrivateFieldSet(this, _MLAttr_potentialName, this._astToken.potentialName ?? this.nameNode?.raw ?? '', "f");
-        __classPrivateFieldSet(this, _MLAttr_potentialValue, this._astToken.potentialValue ?? this.valueNode?.raw ?? '', "f");
-        this.isDuplicatable = this._astToken.isDuplicatable;
-        const ns = resolveNamespace(__classPrivateFieldGet(this, _MLAttr_potentialName, "f"), ownElement.namespaceURI);
-        __classPrivateFieldSet(this, _MLAttr_localName, ns.localName, "f");
-        __classPrivateFieldSet(this, _MLAttr_namespaceURI, ns.namespaceURI, "f");
+        this.#potentialValue = this._astToken.potentialValue ?? this.valueNode?.raw ?? '';
+        if (this._astToken.potentialName == null) {
+            // Try declarative directive pattern resolution from spec
+            const patterns = ownElement.ownerMLDocument.specs.directivePatterns ?? [];
+            const resolution = patterns.length > 0
+                ? resolveDirective(this.nameNode?.raw ?? '', compileDirectivePatterns(patterns))
+                : null;
+            if (resolution) {
+                this.#potentialName = resolution.potentialName ?? this.nameNode?.raw ?? '';
+                this.isDynamicValue = resolution.isDynamicValue;
+                this.isDirective = resolution.isDirective;
+                this.isDuplicatable = resolution.isDuplicatable ?? this._astToken.isDuplicatable;
+                if (resolution.valueType) {
+                    this.valueType = resolution.valueType;
+                }
+            }
+            else {
+                this.#potentialName = this.nameNode?.raw ?? '';
+                this.isDynamicValue = this._astToken.isDynamicValue;
+                this.isDirective = this._astToken.isDirective;
+                this.isDuplicatable = this._astToken.isDuplicatable;
+            }
+            // IDL attribute resolution (after directivePatterns)
+            if (ownElement.ownerMLDocument.specs.useIDLAttributeNames && !this.isDirective) {
+                const { contentAttrName, idlPropName } = searchIDLAttribute(this.#potentialName);
+                if (contentAttrName && contentAttrName !== this.#potentialName) {
+                    this.#potentialName = contentAttrName;
+                }
+                // Set candidate for IDL naming suggestions (e.g., tabindex → tabIndex in JSX).
+                // Only when no directive pattern transformed the name.
+                if (!resolution && idlPropName) {
+                    const rawName = this.nameNode?.raw ?? '';
+                    if (rawName !== idlPropName) {
+                        this.candidate = idlPropName;
+                    }
+                }
+            }
+        }
+        else {
+            // Parser-set potentialName takes precedence
+            this.#potentialName = this._astToken.potentialName;
+            this.isDynamicValue = this._astToken.isDynamicValue;
+            this.isDirective = this._astToken.isDirective;
+            this.isDuplicatable = this._astToken.isDuplicatable;
+        }
+        const ns = resolveNamespace(this.#potentialName, ownElement.namespaceURI);
+        this.#localName = ns.localName;
+        this.#namespaceURI = ns.namespaceURI;
     }
     /**
-     * **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
      */
     get localName() {
-        return __classPrivateFieldGet(this, _MLAttr_localName, "f");
+        return this.#localName;
     }
     /**
+     * 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
      */
     get name() {
-        return __classPrivateFieldGet(this, _MLAttr_potentialName, "f");
+        return this.#potentialName;
     }
     /**
-     * **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
      */
     get namespaceURI() {
-        return __classPrivateFieldGet(this, _MLAttr_namespaceURI, "f");
+        return this.#namespaceURI;
     }
     /**
      * Returns a string appropriate for the type of node as `Attr`
@@ -111,6 +199,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;
     }
@@ -155,7 +249,7 @@ export class MLAttr extends MLNode {
      * @see https://dom.spec.whatwg.org/#dom-attr-value
      */
     get value() {
-        return __classPrivateFieldGet(this, _MLAttr_potentialValue, "f");
+        return this.#potentialValue;
     }
     /**
      * Fixes the attribute value.
@@ -173,7 +267,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) {
@@ -208,4 +307,3 @@ export class MLAttr extends MLNode {
         return tokens.join('');
     }
 }
-_MLAttr_localName = new WeakMap(), _MLAttr_namespaceURI = new WeakMap(), _MLAttr_potentialName = new WeakMap(), _MLAttr_potentialValue = new WeakMap();

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

@@ -1,12 +1,33 @@
 import type { MLDocument } from './document.js';
 import type { MLElement } from './element.js';
 import type { MarkuplintPreprocessorBlockType } from './types.js';
-import type { MLASTPreprocessorSpecificBlock, MLASTPreprocessorSpecificBlockConditionalType } from '@markuplint/ml-ast';
+import type { MLASTPreprocessorSpecificBlock, MLASTBlockBehavior } 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> {
-    readonly conditionalType: MLASTPreprocessorSpecificBlockConditionalType;
+    /**
+     * Block behavior associated with this block, if any.
+     */
+    readonly blockBehavior: MLASTBlockBehavior | null;
+    /**
+     * 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,13 +1,36 @@
 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 {
+    /**
+     * Block behavior associated with this block, if any.
+     */
+    blockBehavior;
+    /**
+     * Whether this block is transparent, meaning its children are treated
+     * as belonging to the parent node for tree traversal purposes.
+     */
+    isTransparent;
+    /**
+     * 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) {
         super(astNode, document, astNode.isFragment);
         // TODO:
         this.isTransparent = true;
-        this.conditionalType = astNode.conditionalType;
+        this.blockBehavior = astNode.blockBehavior;
     }
     /**
      * Returns a string appropriate for the type of node as `MLBlock`

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`