@markuplint/selector 4.7.7 → 5.0.0-alpha.0

package/lib/index.d.ts

@@ -1,5 +1,8 @@
 export { compareSpecificity } from './compare-specificity.js';
-export { matchSelector, SelectorMatches } from './match-selector.js';
+export { matchSelector } from './match-selector.js';
+export type { SelectorMatches } from './match-selector.js';
 export { createSelector } from './create-selector.js';
+export { Selector } from './selector.js';
+export type { ExtendedPseudoClass } from './selector.js';
 export { InvalidSelectorError } from './invalid-selector-error.js';
-export * from './types.js';
+export type * from './types.js';

package/lib/index.js

@@ -1,5 +1,5 @@
 export { compareSpecificity } from './compare-specificity.js';
 export { matchSelector } from './match-selector.js';
 export { createSelector } from './create-selector.js';
+export { Selector } from './selector.js';
 export { InvalidSelectorError } from './invalid-selector-error.js';
-export * from './types.js';

package/lib/invalid-selector-error.d.ts

@@ -1,5 +1,13 @@
+/**
+ * Error thrown when a CSS selector string cannot be parsed.
+ */
 export declare class InvalidSelectorError extends Error {
     name: string;
+    /** The invalid selector string that caused this error */
     selector: string;
+    /**
+     * @param selector - The invalid selector string
+     * @param message - An optional custom error message
+     */
     constructor(selector: string, message?: string);
 }

package/lib/invalid-selector-error.js

@@ -1,7 +1,16 @@
+/**
+ * Error thrown when a CSS selector string cannot be parsed.
+ */
 export class InvalidSelectorError extends Error {
+    name = 'InvalidSelectorError';
+    /** The invalid selector string that caused this error */
+    selector;
+    /**
+     * @param selector - The invalid selector string
+     * @param message - An optional custom error message
+     */
     constructor(selector, message) {
         super(message ?? `Invalid selector: "${selector}"`);
-        this.name = 'InvalidSelectorError';
         this.selector = selector;
     }
 }

package/lib/is.d.ts

@@ -1,12 +1,26 @@
-export declare function isElement(node: Node): node is Element;
-export declare function isNonDocumentTypeChildNode(node: Node): node is Element | CharacterData;
+import type { SelectorElement, SelectorNode } from './types.js';
+/**
+ * Checks whether the given node is an Element node.
+ *
+ * @param node - The node to check
+ * @returns `true` if the node is an Element
+ */
+export declare function isElement(node: SelectorNode): node is SelectorElement;
+/**
+ * Checks whether the given node is a non-DocumentType child node
+ * (i.e., has `previousElementSibling` and `nextElementSibling` properties).
+ *
+ * @param node - The node to check
+ * @returns `true` if the node is an Element or CharacterData
+ */
+export declare function isNonDocumentTypeChildNode(node: SelectorNode): node is SelectorElement;
 /**
  * Checks if the given element is a pure HTML element.
  *
  * If a pure HTML element, `localName` returns lowercase,
  * `nodeName` returns uppercase.
  *
- * @param el The element to check.
- * @returns Returns true if the element is a pure HTML element, otherwise returns false.
+ * @param el - The element to check
+ * @returns `true` if the element is a pure HTML element, `false` otherwise
  */
-export declare function isPureHTMLElement(el: Element): boolean;
+export declare function isPureHTMLElement(el: SelectorElement): boolean;

package/lib/is.js

@@ -1,11 +1,21 @@
-export function isElement(
-// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
-node) {
-    return node.nodeType === node.ELEMENT_NODE;
+const ELEMENT_NODE = 1;
+/**
+ * Checks whether the given node is an Element node.
+ *
+ * @param node - The node to check
+ * @returns `true` if the node is an Element
+ */
+export function isElement(node) {
+    return node.nodeType === ELEMENT_NODE;
 }
-export function isNonDocumentTypeChildNode(
-// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
-node) {
+/**
+ * Checks whether the given node is a non-DocumentType child node
+ * (i.e., has `previousElementSibling` and `nextElementSibling` properties).
+ *
+ * @param node - The node to check
+ * @returns `true` if the node is an Element or CharacterData
+ */
+export function isNonDocumentTypeChildNode(node) {
     return 'previousElementSibling' in node && 'nextElementSibling' in node;
 }
 /**
@@ -14,8 +24,8 @@ node) {
  * If a pure HTML element, `localName` returns lowercase,
  * `nodeName` returns uppercase.
  *
- * @param el The element to check.
- * @returns Returns true if the element is a pure HTML element, otherwise returns false.
+ * @param el - The element to check
+ * @returns `true` if the element is a pure HTML element, `false` otherwise
  */
 export function isPureHTMLElement(
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types

package/lib/match-selector.d.ts

@@ -1,5 +1,9 @@
-import type { Specificity, RegexSelector } from './types.js';
+import type { SelectorNode, Specificity, RegexSelector } from './types.js';
 import type { MLMLSpec } from '@markuplint/ml-spec';
+/**
+ * The result of matching a selector against a node.
+ * Either a successful match with specificity and captured data, or an unsuccessful match.
+ */
 export type SelectorMatches = SelectorMatched | SelectorUnmatched;
 type SelectorMatched = {
     readonly matched: true;
@@ -10,5 +14,17 @@ type SelectorMatched = {
 type SelectorUnmatched = {
     readonly matched: false;
 };
-export declare function matchSelector(el: Node, selector: string | RegexSelector | undefined, scope?: ParentNode | null, specs?: MLMLSpec): SelectorMatches;
+/**
+ * Matches a CSS selector or regex selector against a node.
+ *
+ * Supports both standard CSS selectors (as strings) and markuplint's
+ * {@link RegexSelector} for pattern-based matching with captured groups.
+ *
+ * @param el - The node to test
+ * @param selector - A CSS selector string, a regex selector object, or `undefined`
+ * @param scope - The scope element for `:scope` pseudo-class resolution
+ * @param specs - The HTML/ARIA specification data for extended pseudo-classes
+ * @returns A match result with specificity and captured data, or `{ matched: false }`
+ */
+export declare function matchSelector(el: SelectorNode, selector: string | RegexSelector | undefined, scope?: SelectorNode | null, specs?: MLMLSpec): SelectorMatches;
 export {};

package/lib/match-selector.js

@@ -1,23 +1,19 @@
-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 _SelectorTarget_combinedFrom, _SelectorTarget_selector;
 import { isElement, isNonDocumentTypeChildNode, isPureHTMLElement } from './is.js';
 import { regexSelectorMatches } from './regex-selector-matches.js';
 import { createSelector } from './create-selector.js';
-export function matchSelector(
-// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
-el, selector, 
-// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
-scope, specs) {
+/**
+ * Matches a CSS selector or regex selector against a node.
+ *
+ * Supports both standard CSS selectors (as strings) and markuplint's
+ * {@link RegexSelector} for pattern-based matching with captured groups.
+ *
+ * @param el - The node to test
+ * @param selector - A CSS selector string, a regex selector object, or `undefined`
+ * @param scope - The scope element for `:scope` pseudo-class resolution
+ * @param specs - The HTML/ARIA specification data for extended pseudo-classes
+ * @returns A match result with specificity and captured data, or `{ matched: false }`
+ */
+export function matchSelector(el, selector, scope, specs) {
     if (selector == null || selector === '') {
         return {
             matched: false,
@@ -39,9 +35,7 @@ scope, specs) {
     }
     return regexSelect(el, selector);
 }
-function regexSelect(
-// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
-el, selector) {
+function regexSelect(el, selector) {
     let edge = new SelectorTarget(selector);
     let edgeSelector = selector.combination;
     while (edgeSelector) {
@@ -53,28 +47,26 @@ el, selector) {
     return edge.match(el);
 }
 class SelectorTarget {
+    #combinedFrom = null;
+    #selector;
     constructor(selector) {
-        _SelectorTarget_combinedFrom.set(this, null);
-        _SelectorTarget_selector.set(this, void 0);
-        __classPrivateFieldSet(this, _SelectorTarget_selector, selector, "f");
+        this.#selector = selector;
     }
     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) {
+    match(el) {
         const unitCheck = this._matchWithoutCombineChecking(el);
         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) {
             // Descendant combinator
             case ' ': {
@@ -149,20 +141,15 @@ class SelectorTarget {
                 return { matched: false };
             }
             default: {
-                throw new Error(`Unsupported ${__classPrivateFieldGet(this, _SelectorTarget_combinedFrom, "f").combinator} combinator in selector`);
+                throw new Error(`Unsupported ${this.#combinedFrom.combinator} combinator in selector`);
             }
         }
     }
-    _matchWithoutCombineChecking(
-    // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
-    el) {
-        return uncombinedRegexSelect(el, __classPrivateFieldGet(this, _SelectorTarget_selector, "f"));
+    _matchWithoutCombineChecking(el) {
+        return uncombinedRegexSelect(el, this.#selector);
     }
 }
-_SelectorTarget_combinedFrom = new WeakMap(), _SelectorTarget_selector = new WeakMap();
-function uncombinedRegexSelect(
-// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
-el, selector) {
+function uncombinedRegexSelect(el, selector) {
     if (!isElement(el)) {
         return {
             matched: false,
@@ -227,13 +214,13 @@ el, selector) {
     specificity[1] += specifiedAttr.size;
     if (matched) {
         return {
-            matched,
+            matched: true,
             selector: `${tagSelector}${attrSelector}`,
             specificity,
             data,
         };
     }
-    return { matched };
+    return { matched: false };
 }
 function mergeMatches(a, b, sep, close = false) {
     return {

package/lib/regex-selector-matches.d.ts

@@ -1,3 +1,15 @@
+/**
+ * Tests a raw string value against a regex selector pattern and returns
+ * the captured groups if matched.
+ *
+ * Plain strings are treated as exact-match patterns (`^pattern$`).
+ * Regex literals (`/pattern/flags`) are used as-is.
+ *
+ * @param reg - The regex pattern string, or `undefined` to skip matching
+ * @param raw - The raw string value to test against the pattern
+ * @param ignoreCase - Whether to perform case-insensitive matching
+ * @returns An object of captured groups (`$0`, `$1`, ... and named groups), or `null` if unmatched or `reg` is `undefined`
+ */
 export declare function regexSelectorMatches(reg: string | undefined, raw: string, ignoreCase: boolean): {
     [x: string]: string;
 } | null;

package/lib/regex-selector-matches.js

@@ -1,3 +1,15 @@
+/**
+ * Tests a raw string value against a regex selector pattern and returns
+ * the captured groups if matched.
+ *
+ * Plain strings are treated as exact-match patterns (`^pattern$`).
+ * Regex literals (`/pattern/flags`) are used as-is.
+ *
+ * @param reg - The regex pattern string, or `undefined` to skip matching
+ * @param raw - The raw string value to test against the pattern
+ * @param ignoreCase - Whether to perform case-insensitive matching
+ * @returns An object of captured groups (`$0`, `$1`, ... and named groups), or `null` if unmatched or `reg` is `undefined`
+ */
 export function regexSelectorMatches(reg, raw, ignoreCase) {
     if (!reg) {
         return null;

package/lib/selector.d.ts

@@ -1,9 +1,39 @@
-import type { SelectorResult, Specificity } from './types.js';
-type ExtendedPseudoClass = Readonly<Record<string, (content: string) => (el: Element) => SelectorResult>>;
+import type { SelectorElement, SelectorNode, SelectorResult, Specificity } from './types.js';
+/**
+ * Registry of extended pseudo-class handlers keyed by pseudo-class name.
+ *
+ * Each handler is a curried function: given the pseudo-class content string,
+ * it returns a matcher that tests a {@link SelectorElement} and produces
+ * a {@link SelectorResult}.
+ */
+export type ExtendedPseudoClass = Readonly<Record<string, (content: string) => (el: SelectorElement) => SelectorResult>>;
+/**
+ * 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 declare class Selector {
     #private;
+    /**
+     * @param selector - The CSS selector string to parse
+     * @param extended - Extended pseudo-class handlers to register
+     */
     constructor(selector: string, extended?: ExtendedPseudoClass);
-    match(el: Node, scope?: ParentNode | null): Specificity | false;
-    search(el: Node, scope?: ParentNode | null): SelectorResult[];
+    /**
+     * 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: SelectorNode, scope?: SelectorNode | null): Specificity | false;
+    /**
+     * 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: SelectorNode, scope?: SelectorNode | null): SelectorResult[];
 }
-export {};