@cssdoc/index 0.1.0 → 0.2.0

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { CssAnimation, CssCondition, CssDocConfiguration, CssDocEntry, CssFunction, CssModifier, CssPart, CssPropertyDeclared, CssState, StructureNode } from "@cssdoc/core";
+import { CssAnimation, CssCondition, CssDocConfiguration, CssDocEntry, CssFunction, CssModifier, CssPart, CssPropertyDeclared, CssState, ModifierConventionInput, ModifierMatcher, StructureNode } from "@cssdoc/core";
 
 //#region src/index.d.ts
 /** A 1-based line/column position (matching PostCSS). */
@@ -17,16 +17,18 @@ interface Location {
   span: SourceSpan;
 }
 /**
- * A class-attribute usage: the classes on one element, the specific `token` under inspection, and the
- * resolved `base` component class (when one of the tokens names a documented component). Producers for
- * HTML, JSX, and CSS selectors all emit this shape.
+ * A member usage on one element: the classes on the element, the specific `token` under inspection,
+ * and the resolved `base` component class (when one of the tokens names a documented component).
+ * `token` is normally a class token, but for attribute conventions (CUBE) it may be an attribute
+ * expression like `data-variant="ghost"`. Producers for HTML, JSX, and CSS selectors all emit this
+ * shape.
  */
 interface ClassUsage {
   /** The base component class among the tokens, if any (e.g. `.button` → `button`). */
   base?: string;
   /** Every class token on the element. */
   tokens: string[];
-  /** The specific token this usage is about (e.g. a `-modifier`). */
+  /** The specific token/expression this usage is about (a modifier candidate). */
   token: string;
   /** Where the token sits in the host document. */
   loc?: SourceSpan;
@@ -77,9 +79,11 @@ interface CssDocManifest {
 declare class CssDocIndex {
   readonly file?: string;
   readonly records: readonly RecordInfo[];
+  /** The modifier matcher for this index's convention — how members are matched and rendered. */
+  readonly matcher: ModifierMatcher;
   private readonly byName;
   private readonly byClass;
-  constructor(records: RecordInfo[], file?: string);
+  constructor(records: RecordInfo[], file?: string, matcher?: ModifierMatcher);
   /** Every documented record's model entry. */
   get entries(): CssDocEntry[];
   /** The record whose base class matches `className` (with or without a leading dot). */
@@ -94,7 +98,7 @@ declare class CssDocIndex {
   conditionsFor(name: string): CssCondition[];
   animationsFor(name: string): CssAnimation[];
   structureFor(name: string): StructureNode[] | undefined;
-  /** Whether `modifier` (with or without a leading dot) is a documented modifier of `base`. */
+  /** Whether `modifier` (a class token or attribute expression) is a documented modifier of `base`. */
   isModifier(base: string, modifier: string): boolean;
   /** The deprecation of a modifier on `base`, if it is deprecated. */
   deprecationOf(base: string, modifier: string): {
@@ -129,6 +133,7 @@ declare function indexFromEntries(entries: CssDocEntry[], file?: string): CssDoc
 declare function createIndex(css: string, options?: {
   file?: string;
   configuration?: CssDocConfiguration;
+  modifierConvention?: ModifierConventionInput;
 }): CssDocIndex;
 /**
  * Extract custom-property assignments (`--name: value`) and `var(--name, fallback)` references from

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import { parseCssDocs, parseDocComment, recordNameOf } from "@cssdoc/core";
+import { DEFAULT_MODIFIER_CONVENTION, ModifierMatcher, parseCssDocs, parseDocComment, recordNameOf, resolveModifierConvention } from "@cssdoc/core";
 import postcss from "postcss";
 import valueParser from "postcss-value-parser";
 //#region src/index.ts
@@ -18,7 +18,6 @@ import valueParser from "postcss-value-parser";
 function memberKey(kind, id = "") {
 	return id ? `${kind}:${id}` : kind;
 }
-const escapeRe = (value) => value.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
 const stripDot = (name) => name.replace(/^\./u, "");
 const spanOf = (node) => {
 	const { source } = node;
@@ -39,11 +38,14 @@ const spanOf = (node) => {
 var CssDocIndex = class {
 	file;
 	records;
+	/** The modifier matcher for this index's convention — how members are matched and rendered. */
+	matcher;
 	byName = /* @__PURE__ */ new Map();
 	byClass = /* @__PURE__ */ new Map();
-	constructor(records, file) {
+	constructor(records, file, matcher) {
 		this.records = records;
 		this.file = file;
+		this.matcher = matcher ?? new ModifierMatcher(DEFAULT_MODIFIER_CONVENTION);
 		for (const record of records) {
 			this.byName.set(record.entry.name, record);
 			this.byClass.set(stripDot(record.entry.className), record);
@@ -85,14 +87,14 @@ var CssDocIndex = class {
 	structureFor(name) {
 		return this.byName.get(name)?.entry.structure;
 	}
-	/** Whether `modifier` (with or without a leading dot) is a documented modifier of `base`. */
+	/** Whether `modifier` (a class token or attribute expression) is a documented modifier of `base`. */
 	isModifier(base, modifier) {
-		const wanted = stripDot(modifier);
+		const wanted = this.matcher.normalizeMember(modifier);
 		return this.byClass.get(stripDot(base))?.entry.modifiers.some((m) => m.name === wanted) ?? false;
 	}
 	/** The deprecation of a modifier on `base`, if it is deprecated. */
 	deprecationOf(base, modifier) {
-		const wanted = stripDot(modifier);
+		const wanted = this.matcher.normalizeMember(modifier);
 		return this.byClass.get(stripDot(base))?.entry.modifiers.find((m) => m.name === wanted)?.deprecated;
 	}
 	/** Every declared custom property, paired with the record that declares it (for `var(...)` completion). */
@@ -139,8 +141,8 @@ function indexFromEntries(entries, file) {
 	})), file);
 }
 /** Scan a record's nodes for member spans, recording each member's first occurrence. */
-function scanNodes(nodes, build, base) {
-	const modRe = new RegExp(`(?:${escapeRe(base)}|:scope)((?:\\.-[\\w-]+)+)`, "gu");
+function scanNodes(nodes, build, base, matcher) {
+	const baseNoDot = stripDot(base);
 	const set = (key, node) => {
 		const span = spanOf(node);
 		if (span && !build.memberSpans.has(key)) build.memberSpans.set(key, span);
@@ -149,10 +151,17 @@ function scanNodes(nodes, build, base) {
 		build.selectorText += ` ${node.selector}`;
 		if (`.${stripDot(node.selector.trim())}` === base && !build.span) build.span = spanOf(node);
 		for (const selector of node.selector.split(",")) {
-			for (const m of selector.matchAll(modRe)) for (const mod of m[1].matchAll(/\.(-[\w-]+)/gu)) set(memberKey("modifier", mod[1]), node);
 			for (const s of selector.matchAll(/:state\(\s*([\w-]+)\s*\)/gu)) set(memberKey("state", s[1]), node);
 			const bare = selector.replace(/::?[\w-]+(\([^)]*\))?/gu, "");
-			for (const p of bare.matchAll(/\.([a-z][\w-]*)/gu)) set(memberKey("part", p[1]), node);
+			const modNames = /* @__PURE__ */ new Set();
+			for (const mod of matcher.modifiersIn(bare, baseNoDot)) {
+				modNames.add(mod.name);
+				set(memberKey("modifier", mod.name), node);
+			}
+			for (const p of bare.matchAll(/\.([a-z][\w-]*)/gu)) {
+				if (modNames.has(p[1])) continue;
+				set(memberKey("part", p[1]), node);
+			}
 		}
 	} else if (node.type === "atrule") {
 		if (node.name === "property") set(memberKey("property", node.params.trim()), node);
@@ -165,7 +174,7 @@ function scanNodes(nodes, build, base) {
 			if (layer) set(memberKey("layer", layer), node);
 		}
 		else if (node.name === "container" || node.name === "supports" || node.name === "media") set(memberKey("condition", `${node.name}:${node.params.trim()}`), node);
-		if (node.nodes) scanNodes(node.nodes, build, base);
+		if (node.nodes) scanNodes(node.nodes, build, base, matcher);
 	}
 }
 /**
@@ -177,7 +186,11 @@ function scanNodes(nodes, build, base) {
 * @returns The index.
 */
 function createIndex(css, options = {}) {
-	const entries = parseCssDocs(css, { configuration: options.configuration });
+	const matcher = new ModifierMatcher(resolveModifierConvention(options.modifierConvention ?? options.configuration?.modifierConvention));
+	const entries = parseCssDocs(css, {
+		configuration: options.configuration,
+		modifierConvention: options.modifierConvention
+	});
 	const byName = new Map(entries.map((e) => [e.name, e]));
 	const builds = /* @__PURE__ */ new Map();
 	const root = postcss.parse(css);
@@ -200,7 +213,7 @@ function createIndex(css, options = {}) {
 				continue;
 			}
 		}
-		if (current) scanNodes([node], current, current.entry.className);
+		if (current) scanNodes([node], current, current.entry.className, matcher);
 	}
 	return new CssDocIndex(entries.map((entry) => builds.get(entry.name) ?? {
 		entry,
@@ -208,7 +221,7 @@ function createIndex(css, options = {}) {
 		authoredModifiers: /* @__PURE__ */ new Set(),
 		authoredParts: /* @__PURE__ */ new Set(),
 		selectorText: ""
-	}), options.file);
+	}), options.file, matcher);
 }
 /**
 * Extract custom-property assignments (`--name: value`) and `var(--name, fallback)` references from

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cssdoc/index",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "A queryable semantic index over the @cssdoc/core model, plus a host-agnostic Usage abstraction and source spans — the shared data layer for cssdoc's linters and language server.",
   "keywords": [
     "css",
@@ -30,7 +30,7 @@
   "dependencies": {
     "postcss": "^8.5.16",
     "postcss-value-parser": "^4.2.0",
-    "@cssdoc/core": "0.1.0"
+    "@cssdoc/core": "0.2.0"
   },
   "devDependencies": {
     "@types/node": "^24.13.3",