@markuplint/selector 4.7.7 → 5.0.0-alpha.0

package/lib/selector.js

@@ -1,15 +1,3 @@
-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 _Selector_ruleset, _Ruleset_selectorGroup, _StructuredSelector_edge, _StructuredSelector_selector, _SelectorTarget_combinedFrom, _SelectorTarget_extended, _SelectorTarget_isAdded;
 import { resolveNamespace } from '@markuplint/ml-spec';
 import parser from 'postcss-selector-parser';
 import { compareSpecificity } from './compare-specificity.js';
@@ -18,16 +6,28 @@ import { InvalidSelectorError } from './invalid-selector-error.js';
 import { isElement, isNonDocumentTypeChildNode, isPureHTMLElement } from './is.js';
 const selLog = coreLog.extend('selector');
 const resLog = coreLog.extend('result');
+/**
+ * CSS selector matcher that parses a selector string and matches it against nodes.
+ *
+ * Use {@link createSelector} to create cached instances with extended pseudo-class support.
+ */
 export class Selector {
+    #ruleset;
+    /**
+     * @param selector - The CSS selector string to parse
+     * @param extended - Extended pseudo-class handlers to register
+     */
     constructor(selector, extended = {}) {
-        _Selector_ruleset.set(this, void 0);
-        __classPrivateFieldSet(this, _Selector_ruleset, Ruleset.parse(selector, extended), "f");
+        this.#ruleset = Ruleset.parse(selector, extended);
     }
-    match(
-    // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
-    el, 
-    // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
-    scope) {
+    /**
+     * Tests whether the given node matches this selector.
+     *
+     * @param el - The node to test
+     * @param scope - The scope node for `:scope` pseudo-class resolution
+     * @returns The specificity of the first matching selector, or `false` if none matched
+     */
+    match(el, scope) {
         scope = scope ?? (isElement(el) ? el : null);
         const results = this.search(el, scope);
         for (const result of results) {
@@ -37,16 +37,19 @@ export class Selector {
         }
         return false;
     }
-    search(
-    // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
-    el, 
-    // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
-    scope) {
+    /**
+     * Evaluates all comma-separated selectors against the given node
+     * and returns each result (matched or unmatched).
+     *
+     * @param el - The node to test
+     * @param scope - The scope node for `:scope` pseudo-class resolution
+     * @returns An array of results, one per comma-separated selector alternative
+     */
+    search(el, scope) {
         scope = scope ?? (isElement(el) ? el : null);
-        return __classPrivateFieldGet(this, _Selector_ruleset, "f").match(el, scope);
+        return this.#ruleset.match(el, scope);
     }
 }
-_Selector_ruleset = new WeakMap();
 class Ruleset {
     static parse(selector, extended) {
         const selectors = [];
@@ -63,27 +66,24 @@ class Ruleset {
         }
         return new Ruleset(selectors, extended, 0);
     }
+    headCombinator;
+    #selectorGroup = [];
     constructor(selectors, extended, depth) {
-        _Ruleset_selectorGroup.set(this, []);
-        __classPrivateFieldGet(this, _Ruleset_selectorGroup, "f").push(...selectors.map(selector => new StructuredSelector(selector, depth, extended)));
-        const head = __classPrivateFieldGet(this, _Ruleset_selectorGroup, "f")[0];
+        this.#selectorGroup.push(...selectors.map(selector => new StructuredSelector(selector, depth, extended)));
+        const head = this.#selectorGroup[0];
         this.headCombinator = head?.headCombinator ?? null;
         if (this.headCombinator && depth <= 0) {
-            if (__classPrivateFieldGet(this, _Ruleset_selectorGroup, "f")[0]?.selector) {
-                throw new InvalidSelectorError(__classPrivateFieldGet(this, _Ruleset_selectorGroup, "f")[0]?.selector);
+            if (this.#selectorGroup[0]?.selector) {
+                throw new InvalidSelectorError(this.#selectorGroup[0]?.selector);
             }
             throw new Error('Combinated selector depth is not expected');
         }
     }
-    match(
-    // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
-    el, 
-    // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
-    scope) {
+    match(el, scope) {
         if (coreLog.enabled) {
             coreLog('<%s> (%s)', isElement(el) ? el.localName : el.nodeName, scope ? (isElement(scope) ? scope.localName : scope.nodeName) : null);
         }
-        return __classPrivateFieldGet(this, _Ruleset_selectorGroup, "f").map(selector => {
+        return this.#selectorGroup.map(selector => {
             if (selLog.enabled) {
                 selLog('"%s"', selector.selector);
             }
@@ -95,16 +95,16 @@ class Ruleset {
         });
     }
 }
-_Ruleset_selectorGroup = new WeakMap();
 class StructuredSelector {
+    #edge;
+    headCombinator;
+    #selector;
     constructor(selector, depth, extended) {
-        _StructuredSelector_edge.set(this, void 0);
-        _StructuredSelector_selector.set(this, void 0);
-        __classPrivateFieldSet(this, _StructuredSelector_selector, selector, "f");
-        __classPrivateFieldSet(this, _StructuredSelector_edge, new SelectorTarget(extended, depth), "f");
+        this.#selector = selector;
+        this.#edge = new SelectorTarget(extended, depth);
         this.headCombinator =
-            __classPrivateFieldGet(this, _StructuredSelector_selector, "f").nodes[0]?.type === 'combinator' ? (__classPrivateFieldGet(this, _StructuredSelector_selector, "f").nodes[0].value ?? null) : null;
-        const nodes = [...__classPrivateFieldGet(this, _StructuredSelector_selector, "f").nodes];
+            this.#selector.nodes[0]?.type === 'combinator' ? (this.#selector.nodes[0].value ?? null) : null;
+        const nodes = [...this.#selector.nodes];
         if (0 < depth && this.headCombinator) {
             nodes.unshift(parser.pseudo({ value: ':scope' }));
         }
@@ -112,8 +112,8 @@ class StructuredSelector {
             switch (node.type) {
                 case 'combinator': {
                     const combinedTarget = new SelectorTarget(extended, depth);
-                    combinedTarget.from(__classPrivateFieldGet(this, _StructuredSelector_edge, "f"), node);
-                    __classPrivateFieldSet(this, _StructuredSelector_edge, combinedTarget, "f");
+                    combinedTarget.from(this.#edge, node);
+                    this.#edge = combinedTarget;
                     break;
                 }
                 case 'root':
@@ -127,38 +127,34 @@ class StructuredSelector {
                     throw new Error(`Unsupported comment in selector: ${selector.toString()}`);
                 }
                 default: {
-                    __classPrivateFieldGet(this, _StructuredSelector_edge, "f").add(node);
+                    this.#edge.add(node);
                 }
             }
         }
     }
     get selector() {
-        return __classPrivateFieldGet(this, _StructuredSelector_selector, "f").nodes.join('');
+        return this.#selector.nodes.join('');
     }
-    match(
-    // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
-    el, 
-    // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
-    scope) {
-        return __classPrivateFieldGet(this, _StructuredSelector_edge, "f").match(el, scope, 0);
+    match(el, scope) {
+        return this.#edge.match(el, scope, 0);
     }
 }
-_StructuredSelector_edge = new WeakMap(), _StructuredSelector_selector = new WeakMap();
 class SelectorTarget {
+    attr = [];
+    class = [];
+    #combinedFrom = null;
+    depth;
+    #extended;
+    id = [];
+    #isAdded = false;
+    pseudo = [];
+    tag = null;
     constructor(extended, depth) {
-        this.attr = [];
-        this.class = [];
-        _SelectorTarget_combinedFrom.set(this, null);
-        _SelectorTarget_extended.set(this, void 0);
-        this.id = [];
-        _SelectorTarget_isAdded.set(this, false);
-        this.pseudo = [];
-        this.tag = null;
-        __classPrivateFieldSet(this, _SelectorTarget_extended, extended, "f");
+        this.#extended = extended;
         this.depth = depth;
     }
     add(selector) {
-        __classPrivateFieldSet(this, _SelectorTarget_isAdded, true, "f");
+        this.#isAdded = true;
         switch (selector.type) {
             case 'tag':
             case 'universal': {
@@ -184,17 +180,13 @@ class SelectorTarget {
         }
     }
     from(target, combinator) {
-        __classPrivateFieldSet(this, _SelectorTarget_combinedFrom, { target, combinator }, "f");
+        this.#combinedFrom = { target, combinator };
     }
-    match(
-    // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
-    el, 
-    // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
-    scope, count) {
+    match(el, scope, count) {
         const result = this._match(el, scope, count);
         if (selLog.enabled) {
             const nodeName = el.nodeName;
-            const selector = __classPrivateFieldGet(this, _SelectorTarget_combinedFrom, "f")?.target.toString() ?? this.toString();
+            const selector = this.#combinedFrom?.target.toString() ?? this.toString();
             const combinator = result.combinator ? ` ${result.combinator}` : '';
             selLog('The %s element by "%s" => %s (%d)', nodeName, `${selector}${combinator}`, result.matched, count);
             if (selector === ':scope') {
@@ -213,22 +205,18 @@ class SelectorTarget {
             this.pseudo.map(pseudo => pseudo.value).join(''),
         ].join('');
     }
-    _match(
-    // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
-    el, 
-    // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
-    scope, count) {
+    _match(el, scope, count) {
         const unitCheck = this._matchWithoutCombineChecking(el, scope);
         if (!unitCheck.matched) {
             return unitCheck;
         }
-        if (!__classPrivateFieldGet(this, _SelectorTarget_combinedFrom, "f")) {
+        if (!this.#combinedFrom) {
             return unitCheck;
         }
         if (!isNonDocumentTypeChildNode(el)) {
             return unitCheck;
         }
-        const { target, combinator } = __classPrivateFieldGet(this, _SelectorTarget_combinedFrom, "f");
+        const { target, combinator } = this.#combinedFrom;
         switch (combinator.value) {
             // Descendant combinator
             case ' ': {
@@ -424,7 +412,7 @@ class SelectorTarget {
                 throw new Error('Unsupported column combinator yet. If you want it, please request it as the issue (https://github.com/markuplint/markuplint/issues/new).');
             }
             default: {
-                throw new Error(`Unsupported ${__classPrivateFieldGet(this, _SelectorTarget_combinedFrom, "f").combinator.value} combinator in selector`);
+                throw new Error(`Unsupported ${this.#combinedFrom.combinator.value} combinator in selector`);
             }
         }
     }
@@ -436,11 +424,7 @@ class SelectorTarget {
      * @param scope
      * @private
      */
-    _matchWithoutCombineChecking(
-    // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
-    el, 
-    // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
-    scope) {
+    _matchWithoutCombineChecking(el, scope) {
         const specificity = [0, 0, 0];
         if (!isElement(el)) {
             return {
@@ -472,7 +456,7 @@ class SelectorTarget {
             }
         }
         let matched = true;
-        if (!__classPrivateFieldGet(this, _SelectorTarget_isAdded, "f") && !isScope(el, scope)) {
+        if (!this.#isAdded && !isScope(el, scope)) {
             matched = false;
         }
         if (matched && !this.id.every(id => id.value === el.id)) {
@@ -501,7 +485,7 @@ class SelectorTarget {
         specificity[1] += this.attr.length;
         if (matched) {
             for (const pseudo of this.pseudo) {
-                const pseudoRes = pseudoMatch(pseudo, el, scope, __classPrivateFieldGet(this, _SelectorTarget_extended, "f"), this.depth);
+                const pseudoRes = pseudoMatch(pseudo, el, scope, this.#extended, this.depth);
                 specificity[0] += pseudoRes.specificity[0];
                 specificity[1] += pseudoRes.specificity[1];
                 specificity[2] += pseudoRes.specificity[2];
@@ -517,19 +501,18 @@ class SelectorTarget {
         if (matched) {
             return {
                 specificity,
-                matched,
+                matched: true,
                 nodes: [el],
                 has,
             };
         }
         return {
             specificity,
-            matched,
+            matched: false,
             not,
         };
     }
 }
-_SelectorTarget_combinedFrom = new WeakMap(), _SelectorTarget_extended = new WeakMap(), _SelectorTarget_isAdded = new WeakMap();
 function attrMatch(attr, 
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
 el) {
@@ -594,9 +577,7 @@ el) {
 }
 function pseudoMatch(pseudo, 
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
-el, 
-// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
-scope, extended, depth) {
+el, scope, extended, depth) {
     switch (pseudo.value) {
         //
         /**
@@ -803,9 +784,7 @@ scope, extended, depth) {
 }
 function isScope(
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
-el, 
-// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
-scope) {
+el, scope) {
     return el === scope || el.parentNode === null;
 }
 function getDescendants(

package/lib/types.d.ts

@@ -1,24 +1,112 @@
+/**
+ * Minimal attribute representation for selector matching.
+ * Pure data — no methods, no class instances.
+ *
+ * In Rust this maps directly to a struct.
+ */
+export interface SelectorAttr {
+    readonly name: string;
+    readonly localName: string;
+    readonly value: string;
+    readonly namespaceURI: string | null;
+}
+/**
+ * Minimal node representation for selector matching.
+ * Pure data with tree-navigation references.
+ *
+ * In Rust this maps to a trait backed by arena indices.
+ */
+export interface SelectorNode {
+    readonly nodeType: number;
+    readonly nodeName: string;
+    readonly parentNode: SelectorNode | null;
+}
+/**
+ * Minimal element representation for CSS selector matching.
+ * Captures **only** the properties the selector engine actually reads.
+ *
+ * DOM `Element` and `MLElement` both satisfy this interface,
+ * but plain objects can satisfy it too — enabling Rust interop
+ * and unit-testing without a full DOM.
+ *
+ * In Rust this maps to a struct + trait.
+ */
+export interface SelectorElement extends SelectorNode {
+    readonly localName: string;
+    readonly id: string;
+    readonly namespaceURI: string | null;
+    readonly classList: {
+        contains(className: string): boolean;
+    };
+    readonly attributes: Iterable<SelectorAttr>;
+    readonly parentElement: SelectorElement | null;
+    readonly previousElementSibling: SelectorElement | null;
+    readonly nextElementSibling: SelectorElement | null;
+    readonly children: Iterable<SelectorElement>;
+}
+/**
+ * A CSS specificity tuple: `[id, class, type]`.
+ * Each component counts selectors of the corresponding category.
+ */
 export type Specificity = readonly [number, number, number];
+/**
+ * The result of evaluating a parsed selector against a node.
+ */
 export type SelectorResult = SelectorMatchedResult | SelectorUnmatchedResult;
+/**
+ * A successful selector match result, including the specificity,
+ * the matched nodes, and any `:has()` sub-match results.
+ */
 export type SelectorMatchedResult = {
+    /** The computed specificity of the matched selector */
     readonly specificity: Specificity;
     readonly matched: true;
-    readonly nodes: readonly (Element | Text)[];
+    /** The elements that were matched */
+    readonly nodes: readonly SelectorElement[];
+    /** Results from `:has()` pseudo-class sub-matches */
     readonly has: readonly SelectorMatchedResult[];
 };
+/**
+ * An unsuccessful selector match result.
+ */
 export type SelectorUnmatchedResult = {
+    /** The computed specificity of the unmatched selector */
     readonly specificity: Specificity;
     readonly matched: false;
+    /** Results from `:not()` pseudo-class sub-matches that did match */
     readonly not?: readonly SelectorMatchedResult[];
 };
+/**
+ * A regex-based selector that matches elements by node name and/or attribute
+ * patterns using regular expressions. Supports combinators for chained matching.
+ */
 export type RegexSelector = RegexSelectorWithoutCombination & {
+    /** An optional chained selector with a combinator */
     readonly combination?: {
         readonly combinator: RegexSelectorCombinator;
     } & RegexSelector;
 };
+/**
+ * CSS combinator types supported by regex selectors.
+ *
+ * - `' '`      – Descendant combinator
+ * - `'>'`      – Child combinator
+ * - `'+'`      – Next-sibling combinator
+ * - `'~'`      – Subsequent-sibling combinator
+ * - `':has(+)'`– Previous-sibling combinator (via `:has()`)
+ * - `':has(~)'`– Previous subsequent-sibling combinator (via `:has()`)
+ */
 export type RegexSelectorCombinator = ' ' | '>' | '+' | '~' | ':has(+)' | ':has(~)';
+/**
+ * The non-combinatorial part of a regex selector.
+ * Matches against the element's node name, attribute name, and/or attribute value
+ * using regular expression patterns.
+ */
 export type RegexSelectorWithoutCombination = {
+    /** Regex pattern to match against the element's local name */
     readonly nodeName?: string;
+    /** Regex pattern to match against attribute names */
     readonly attrName?: string;
+    /** Regex pattern to match against attribute values */
     readonly attrValue?: string;
 };

package/package.json

@@ -1,10 +1,13 @@
 {
 	"name": "@markuplint/selector",
-	"version": "4.7.7",
+	"version": "5.0.0-alpha.0",
 	"description": "Extended W3C Selectors matcher",
 	"repository": "git@github.com:markuplint/markuplint.git",
 	"author": "Yusuke Hirao <yusukehirao@me.com>",
 	"license": "MIT",
+	"engines": {
+		"node": ">=22"
+	},
 	"type": "module",
 	"exports": {
 		".": {
@@ -24,15 +27,15 @@
 		"clean": "tsc --build --clean tsconfig.build.json"
 	},
 	"dependencies": {
-		"@markuplint/ml-spec": "4.10.1",
+		"@markuplint/ml-spec": "5.0.0-alpha.0",
 		"@types/debug": "4.1.12",
 		"debug": "4.4.3",
-		"postcss-selector-parser": "7.1.0",
-		"type-fest": "4.41.0"
+		"postcss-selector-parser": "7.1.1",
+		"type-fest": "5.4.4"
 	},
 	"devDependencies": {
-		"@types/jsdom": "21.1.7",
-		"jsdom": "26.1.0"
+		"@types/jsdom": "27.0.0",
+		"jsdom": "28.1.0"
 	},
-	"gitHead": "6213ea30269ef404f030e67bbcc7fc7443ec1060"
+	"gitHead": "13dcfc84ec83d87360c720e253383b60767e1b56"
 }