npm - @markuplint/ml-core - Versions diffs - 4.13.2 → 5.0.0-alpha.0 - Mend

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

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 (92) hide show

package/ARCHITECTURE.ja.md +524 -0
package/ARCHITECTURE.md +524 -0
package/CHANGELOG.md +52 -2
package/README.md +5 -0
package/SKILL.md +61 -0
package/docs/linting-pipeline.ja.md +307 -0
package/docs/linting-pipeline.md +307 -0
package/docs/maintenance.ja.md +210 -0
package/docs/maintenance.md +210 -0
package/docs/ml-dom/attr.ja.md +103 -0
package/docs/ml-dom/attr.md +103 -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 +199 -0
package/docs/ml-dom/node.md +199 -0
package/docs/ml-dom/others.ja.md +120 -0
package/docs/ml-dom/others.md +120 -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 +287 -0
package/docs/rule-system.md +287 -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/index.d.ts +4 -3
package/lib/index.js +1 -1
package/lib/ml-core.d.ts +37 -1
package/lib/ml-core.js +171 -82
package/lib/ml-dom/helper/accname.d.ts +8 -0
package/lib/ml-dom/helper/accname.js +71 -55
package/lib/ml-dom/helper/create-node.js +1 -0
package/lib/ml-dom/helper/get-indent.d.ts +4 -1
package/lib/ml-dom/helper/get-indent.js +21 -30
package/lib/ml-dom/node/attr.d.ts +65 -4
package/lib/ml-dom/node/attr.js +151 -53
package/lib/ml-dom/node/block.d.ts +23 -2
package/lib/ml-dom/node/block.js +24 -1
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 +25 -0
package/lib/ml-dom/node/document.d.ts +88 -7
package/lib/ml-dom/node/document.js +128 -32
package/lib/ml-dom/node/dom-token-list.js +17 -30
package/lib/ml-dom/node/element-close-tag.js +1 -0
package/lib/ml-dom/node/element.d.ts +151 -5
package/lib/ml-dom/node/element.js +242 -50
package/lib/ml-dom/node/node-store.js +6 -15
package/lib/ml-dom/node/node.d.ts +19 -1
package/lib/ml-dom/node/node.js +175 -166
package/lib/ml-dom/node/parent-node.js +14 -30
package/lib/ml-dom/node/rule-mapper.js +7 -20
package/lib/ml-dom/node/text.d.ts +19 -0
package/lib/ml-dom/node/text.js +21 -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 +59 -39
package/lib/ml-rule/create-rule.d.ts +17 -1
package/lib/ml-rule/ml-rule-context.js +7 -11
package/lib/ml-rule/ml-rule.d.ts +66 -1
package/lib/ml-rule/ml-rule.js +95 -25
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 +13 -0
package/lib/test/index.d.ts +42 -1
package/lib/test/index.js +39 -2
package/lib/types.d.ts +10 -1
package/lib/violation-collector.d.ts +33 -0
package/lib/violation-collector.js +48 -28
package/lib/virtual-rule.d.ts +72 -0
package/lib/virtual-rule.js +233 -0
package/package.json +16 -13

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

@@ -1,21 +1,8 @@
 /* global StylePropertyMap, StylePropertyMapReadOnly */
-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 _MLElement_attributes, _MLElement_fixedNodeName, _MLElement_getChildElementsAndTextNodeWithoutWhitespacesCache, _MLElement_localName, _MLElement_normalizedAttrs, _MLElement_normalizedString;
 import { resolveNamespace } from '@markuplint/ml-spec';
 import { matchSelector } from '@markuplint/selector';
 import { getAccname } from '../helper/accname.js';
 import { after, before, nextElementSibling, previousElementSibling, remove, replaceWith, } from '../manipulations/child-node-methods.js';
-import { MLToken } from '../token/token.js';
 import { MLAttr } from './attr.js';
 import { MLDomTokenList } from './dom-token-list.js';
 import { MLElementCloseTag } from './element-close-tag.js';
@@ -24,30 +11,123 @@ 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 {
+    #attributes;
+    /**
+     * The closing tag for this element, or null if the element is self-closing or void.
+     */
+    closeTag;
+    /**
+     * Element type
+     *
+     * - `html`: From native HTML Standard
+     * - `web-component`: As the Web Component according to HTML Standard
+     * - `authored`:  Authored element (JSX Element etc.) through the view framework or the template engine.
+     */
+    elementType;
+    #fixedNodeName;
+    #getChildElementsAndTextNodeWithoutWhitespacesCache = null;
+    /**
+     * Whether this element belongs to a non-HTML namespace (e.g., SVG or MathML).
+     */
+    isForeignElement;
+    /**
+     * Whether this element was implicitly created (e.g., an omitted `<body>` tag in HTML).
+     */
+    isOmitted;
+    #localName;
+    /**
+     * The namespace URI of this element (e.g., `http://www.w3.org/1999/xhtml` for HTML elements).
+     */
+    namespaceURI;
+    /**
+     * Memoization cache for the accessible name computation, keyed by ARIA version.
+     *
+     * ## Why this cache exists
+     *
+     * Multiple rules and the `:aria(has name)` selector evaluate the accessible name
+     * of every element during a single lint pass. Without caching, the same
+     * expensive tree-walking algorithm (AccName Computation 1.2) runs repeatedly
+     * for the same element — once per consumer. Benchmarks on a 500-element page
+     * show **14,626 total calls** of which **11,573 (79%) are cache hits**,
+     * eliminating redundant computation.
+     *
+     * ## Why memoization is safe
+     *
+     * The MLDOM is **immutable** once constructed — no attributes or child nodes
+     * change during a lint pass. Therefore the accessible name for a given ARIA
+     * version is deterministic and will never become stale. No invalidation
+     * logic is needed. The cache is garbage-collected together with the
+     * MLElement instance when the document is released.
+     *
+     * ## Consumers that benefit
+     *
+     * - `require-accessible-name` rule (direct call)
+     * - `wai-aria` rule via `:aria(has name)` selector
+     * - `neighbor-popovers` rule
+     * - `landmark-roles` rule
+     * - `MLDocument.getAccessibilityProp()` (accessibility tree builder)
+     *
+     * Introduced to resolve {@link https://github.com/markuplint/markuplint/issues/2179 | #2179}
+     * (AccName performance bottleneck).
+     *
+     * @see {@link getAccessibleName} — the public method that reads/writes this cache
+     */
+    #accessibleNameCache = new Map();
+    #normalizedAttrs = new Map();
+    #normalizedString = null;
+    ontouchcancel;
+    ontouchend;
+    ontouchmove;
+    ontouchstart;
+    /**
+     * The pretender context if this element is participating in pretender behavior,
+     * or null if it is not a pretender or pretended element.
+     */
+    pretenderContext = null;
+    /**
+     * Block behavior associated with this element, if any.
+     */
+    blockBehavior;
+    /**
+     * The tag close character string (e.g., `>` or `/>` or `%>`).
+     */
+    tagCloseChar;
+    /**
+     * The tag open character string (e.g., `<` or `<%`).
+     */
+    tagOpenChar;
+    /**
+     * 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) {
         super(astNode, document, astNode.isFragment);
-        _MLElement_attributes.set(this, void 0);
-        _MLElement_fixedNodeName.set(this, void 0);
-        _MLElement_getChildElementsAndTextNodeWithoutWhitespacesCache.set(this, null);
-        _MLElement_localName.set(this, void 0);
-        _MLElement_normalizedAttrs.set(this, new Map());
-        _MLElement_normalizedString.set(this, null);
-        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;
+        this.#attributes = astNode.attributes.map(attr => new MLAttr(attr, this));
         this.closeTag = astNode.pairNode ? new MLElementCloseTag(astNode.pairNode, document, this) : null;
         const ns = resolveNamespace(astNode.nodeName, astNode.namespace);
-        this.namespaceURI = ns.namespaceURI;
+        this.namespaceURI = astNode.namespace;
         this.elementType = astNode.elementType;
-        __classPrivateFieldSet(this, _MLElement_localName, ns.localName, "f");
+        this.#localName = ns.localName;
         this.isForeignElement = this.namespaceURI !== HTML_NAMESPACE;
-        __classPrivateFieldSet(this, _MLElement_fixedNodeName, astNode.nodeName, "f");
+        this.#fixedNodeName = astNode.nodeName;
         this.isOmitted = astNode.isGhost;
         this.tagOpenChar = astNode.tagOpenChar;
         this.tagCloseChar = astNode.tagCloseChar;
+        this.blockBehavior = astNode.blockBehavior;
     }
     /**
      * **IT THROWS AN ERROR WHEN CALLING THIS.**
@@ -589,6 +669,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');
     }
@@ -597,9 +683,9 @@ export class MLElement extends MLParentNode {
      * @see https://dom.spec.whatwg.org/#dom-element-attributes
      */
     get attributes() {
-        const origin = this.pretenderContext?.type === 'pretender' ? __classPrivateFieldGet(this.pretenderContext.as, _MLElement_attributes, "f") : __classPrivateFieldGet(this, _MLElement_attributes, "f");
-        if (__classPrivateFieldGet(this, _MLElement_normalizedAttrs, "f").has(origin)) {
-            return __classPrivateFieldGet(this, _MLElement_normalizedAttrs, "f").get(origin);
+        const origin = this.pretenderContext?.type === 'pretender' ? this.pretenderContext.as.#attributes : this.#attributes;
+        if (this.#normalizedAttrs.has(origin)) {
+            return this.#normalizedAttrs.get(origin);
         }
         const names = new Set();
         const attrs = [];
@@ -615,7 +701,7 @@ export class MLElement extends MLParentNode {
             attrs.push(attr);
         }
         const map = toNamedNodeMap(attrs);
-        __classPrivateFieldGet(this, _MLElement_normalizedAttrs, "f").set(origin, map);
+        this.#normalizedAttrs.set(origin, map);
         return map;
     }
     /**
@@ -765,13 +851,19 @@ 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");
+        return this.#fixedNodeName;
     }
+    /**
+     * 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');
+        return this.#attributes.some(attr => attr.localName === '#spread');
     }
     /**
      * **IT THROWS AN ERROR WHEN CALLING THIS.**
@@ -871,12 +963,12 @@ export class MLElement extends MLParentNode {
             return this.pretenderContext.as.localName;
         }
         if (this.isForeignElement || this.elementType !== 'html') {
-            return __classPrivateFieldGet(this, _MLElement_localName, "f");
+            return this.#localName;
         }
         if (this.ownerMLDocument.tagNameCaseSensitive) {
-            return __classPrivateFieldGet(this, _MLElement_localName, "f");
+            return this.#localName;
         }
-        return __classPrivateFieldGet(this, _MLElement_localName, "f").toLowerCase();
+        return this.#localName.toLowerCase();
     }
     /**
      * The element immediately following the specified one in its parent's children list.
@@ -2000,6 +2092,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 +2111,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,8 +2385,14 @@ 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");
+        this.#fixedNodeName = name;
     }
     /**
      * **IT THROWS AN ERROR WHEN CALLING THIS.**
@@ -2303,10 +2407,34 @@ export class MLElement extends MLParentNode {
         throw new UnexpectedCallError('Not supported "focus" method');
     }
     /**
+     * Returns the accessible name of this element, with per-element memoization.
+     *
+     * On the first call for a given ARIA version the full AccName Computation
+     * algorithm runs (tree walk, `aria-labelledby` resolution, `<label>` lookup,
+     * etc.) and the result is stored in {@link #accessibleNameCache}.
+     * Subsequent calls for the same version return the cached value in O(1).
+     *
+     * **All callers that need the accessible name of an MLElement should use
+     * this method** rather than importing `getAccname()` directly, so that
+     * every consumer benefits from the shared cache. This includes the
+     * `:aria(has name)` selector in `@markuplint/selector`, which uses
+     * duck-typing to detect and call this method.
+     *
+     * Added as part of the fix for {@link https://github.com/markuplint/markuplint/issues/2179 | #2179}
+     * to eliminate redundant AccName computation across rules.
+     *
      * @implements `@markuplint/ml-core` API: `MLElement`
+     * @param version - The ARIA specification version to use for computation
+     * @returns The computed accessible name string (may be empty)
      */
     getAccessibleName(version) {
-        return getAccname(this, version);
+        const cached = this.#accessibleNameCache.get(version);
+        if (cached != null) {
+            return cached;
+        }
+        const name = getAccname(this, version);
+        this.#accessibleNameCache.set(version, name);
+        return name;
     }
     /**
      * **IT THROWS AN ERROR WHEN CALLING THIS.**
@@ -2367,10 +2495,15 @@ 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")) {
+        for (const attr of this.#attributes) {
             if (attr.name.toLowerCase() === attrName.toLowerCase()) {
                 return attr.value;
             }
@@ -2378,7 +2511,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,10 +2529,14 @@ 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"));
+        return Object.freeze(this.pretenderContext?.type === 'pretender' ? this.pretenderContext.as.#attributes : this.#attributes);
     }
     /**
      * **IT THROWS AN ERROR WHEN CALLING THIS.**
@@ -2406,9 +2548,16 @@ 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");
+        if (this.#getChildElementsAndTextNodeWithoutWhitespacesCache) {
+            return this.#getChildElementsAndTextNodeWithoutWhitespacesCache;
         }
         const filteredNodes = [];
         for (const node of this.childNodes) {
@@ -2425,7 +2574,7 @@ export class MLElement extends MLParentNode {
                 filteredNodes.push(node);
             }
         }
-        __classPrivateFieldSet(this, _MLElement_getChildElementsAndTextNodeWithoutWhitespacesCache, filteredNodes, "f");
+        this.#getChildElementsAndTextNodeWithoutWhitespacesCache = filteredNodes;
         return filteredNodes;
     }
     /**
@@ -2481,7 +2630,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 +2667,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,14 +2685,18 @@ 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()) {
             if (child.is(child.MARKUPLINT_PREPROCESSOR_BLOCK)) {
-                if (child.conditionalType) {
+                if (child.blockBehavior) {
                     continue;
                 }
                 return true;
@@ -2611,7 +2771,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 +2792,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 +2815,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 +2847,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));
@@ -2685,7 +2867,7 @@ export class MLElement extends MLParentNode {
             return;
         }
         let nodeName;
-        let namespace = 'html';
+        let namespace = 'http://www.w3.org/1999/xhtml';
         const attributes = [];
         let aria;
         if (typeof pretenderElement === 'string') {
@@ -2693,7 +2875,7 @@ export class MLElement extends MLParentNode {
         }
         else {
             nodeName = pretenderElement.element;
-            namespace = pretenderElement.namespace ?? namespace;
+            namespace = pretenderElement.namespace === 'svg' ? 'http://www.w3.org/2000/svg' : namespace;
             if (pretenderElement.inheritAttrs) {
                 attributes.push(...this._astToken.attributes);
             }
@@ -2967,11 +3149,16 @@ 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")) {
-            return __classPrivateFieldGet(this, _MLElement_normalizedString, "f");
+        if (this.#normalizedString) {
+            return this.#normalizedString;
         }
         const children = this.getChildElementsAndTextNodeWithoutWhitespaces();
         const attrs = this.attributes.map(attr => attr.toNormalizeString());
@@ -2985,11 +3172,17 @@ export class MLElement extends MLParentNode {
         });
         const endTag = `</${this.nodeName}>`;
         const normalizedString = `${startTag}${childNodes.join('')}${endTag}`;
-        __classPrivateFieldSet(this, _MLElement_normalizedString, normalizedString, "f");
+        this.#normalizedString = normalizedString;
         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) {
@@ -3061,4 +3254,3 @@ export class MLElement extends MLParentNode {
         throw new UnexpectedCallError('Not supported "webkitMatchesSelector" method');
     }
 }
-_MLElement_attributes = new WeakMap(), _MLElement_fixedNodeName = new WeakMap(), _MLElement_getChildElementsAndTextNodeWithoutWhitespacesCache = new WeakMap(), _MLElement_localName = new WeakMap(), _MLElement_normalizedAttrs = new WeakMap(), _MLElement_normalizedString = new WeakMap();

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

@@ -1,29 +1,21 @@
-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 _NodeStore_store;
 import { TargetParserError } from '@markuplint/parser-utils';
 import { log } from '../../debug.js';
 const nodeStoreLog = log.extend('node-store');
 const nodeStoreError = nodeStoreLog.extend('error');
 class NodeStore {
-    constructor() {
-        _NodeStore_store.set(this, new Map());
-    }
+    #store = new Map();
     getNode(astNode) {
         // console.log(`Get: ${astNode.uuid} -> ${astNode.raw.trim()}(${astNode.type})`);
-        const node = __classPrivateFieldGet(this, _NodeStore_store, "f").get(astNode.uuid);
+        const node = this.#store.get(astNode.uuid);
         if (!node) {
             nodeStoreError('Ref ID: %s (%s: "%s")', astNode.uuid, astNode.nodeName, astNode.raw);
-            nodeStoreError('Map: %O', [...__classPrivateFieldGet(this, _NodeStore_store, "f").entries()].map(([id, node]) => ({
+            nodeStoreError('Map: %O', [...this.#store.entries()].map(([id, node]) => ({
                 id,
                 name: node.nodeName,
             })));
             throw new TargetParserError('Broke mapping nodes.', {
-                line: astNode.startLine,
-                col: astNode.startCol,
+                line: astNode.line,
+                col: astNode.col,
                 raw: astNode.raw,
                 nodeName: astNode.nodeName,
             });
@@ -41,10 +33,9 @@ class NodeStore {
             nodeStoreError('Invalid node: %O', node);
         }
         nodeStoreLog('Mapped: %s (%s: "%s")', astNode.uuid, astNode.nodeName, astNode.raw.replaceAll('\n', '⏎').replaceAll('\t', '→'));
-        __classPrivateFieldGet(this, _NodeStore_store, "f").set(astNode.uuid, node);
+        this.#store.set(astNode.uuid, node);
     }
 }
-_NodeStore_store = new WeakMap();
 /**
  * `NodeStore` Singleton
  */

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;
     /**
@@ -127,6 +136,8 @@ export declare abstract class MLNode<T extends RuleConfigValue, O extends PlainD
     get baseURI(): string;
     /**
      * The list of child nodes that contains `Element`, `Text`, and `Comment`.
+     * Fragment nodes and preprocessor blocks with `each` or `end` block behavior
+     * are transparent — their child nodes are flattened into this list.
      *
      * @readonly
      * @implements DOM API: `Node`
@@ -201,6 +212,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.
@@ -360,7 +378,7 @@ export declare abstract class MLNode<T extends RuleConfigValue, O extends PlainD
     /**
      * Returns an array of NodeLists representing the conditional child nodes of the current node.
      * Conditional child nodes are nodes that are nested within
-     * **preprocessor blocks** such as `if`, `each`, or `switch`.
+     * **preprocessor blocks** such as `if` or `switch`.
      * Each NodeList represents a branch of conditional child nodes.
      *
      * Note: NodeList doesn't include whitespace nodes.