@cssdoc/index 0.1.0 → 0.3.0

package/dist/index.d.mts

@@ -1,4 +1,5 @@
-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";
+import postcss from "postcss";
 
 //#region src/index.d.ts
 /** A 1-based line/column position (matching PostCSS). */
@@ -17,16 +18,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;
@@ -50,7 +53,7 @@ interface CssValueSites {
   usages: PropertyUsage[];
 }
 /** The kinds of record member a span can be keyed to. */
-type MemberKind = "record" | "modifier" | "part" | "property" | "function" | "animation" | "layer" | "state" | "condition";
+type MemberKind = "record" | "modifier" | "part" | "shadow-part" | "property" | "function" | "animation" | "layer" | "state" | "condition";
 /** Build a stable span key for a member. */
 declare function memberKey(kind: MemberKind, id?: string): string;
 /** One record in the index: its model entry plus source spans and the facts drift checks need. */
@@ -62,8 +65,10 @@ interface RecordInfo {
   memberSpans: Map<string, SourceSpan>;
   /** Modifier names authored via `@modifier` (used for drift detection). */
   authoredModifiers: Set<string>;
-  /** Part names authored via `@part`/`@csspart` (used for drift detection). */
+  /** Part names authored via `@part` (used for drift detection). */
   authoredParts: Set<string>;
+  /** Shadow-part names authored via `@csspart` (used for drift detection). */
+  authoredShadowParts: Set<string>;
   /** The concatenated selector text of the record's rules (used for drift detection). */
   selectorText: string;
 }
@@ -77,9 +82,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). */
@@ -88,13 +95,14 @@ declare class CssDocIndex {
   recordInfo(name: string): RecordInfo | undefined;
   modifiersFor(name: string): CssModifier[];
   partsFor(name: string): CssPart[];
+  shadowPartsFor(name: string): CssPart[];
   customPropertiesFor(name: string): CssPropertyDeclared[];
   functionsFor(name: string): CssFunction[];
   statesFor(name: string): CssState[];
   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 +137,8 @@ declare function indexFromEntries(entries: CssDocEntry[], file?: string): CssDoc
 declare function createIndex(css: string, options?: {
   file?: string;
   configuration?: CssDocConfiguration;
+  modifierConvention?: ModifierConventionInput; /** The PostCSS parser (inject a dialect parser for `.scss`/`.less`; default `postcss.parse`). */
+  parse?: (css: string) => ReturnType<typeof postcss.parse>;
 }): CssDocIndex;
 /**
  * Extract custom-property assignments (`--name: value`) and `var(--name, fallback)` references from
@@ -138,6 +148,8 @@ declare function createIndex(css: string, options?: {
  * @param css - The CSS source.
  * @returns The assignments and `var(…)` usages found.
  */
-declare function cssValueSites(css: string): CssValueSites;
+declare function cssValueSites(css: string, options?: {
+  parse?: (css: string) => ReturnType<typeof postcss.parse>;
+}): CssValueSites;
 //#endregion
 export { ClassUsage, CssDocIndex, CssDocManifest, CssValueSites, Location, MemberKind, Position, PropertyAssignment, PropertyUsage, RecordInfo, SourceSpan, createIndex, cssValueSites, indexFromEntries, memberKey };

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);
@@ -67,6 +69,9 @@ var CssDocIndex = class {
 	partsFor(name) {
 		return this.byName.get(name)?.entry.parts ?? [];
 	}
+	shadowPartsFor(name) {
+		return this.byName.get(name)?.entry.shadowParts ?? [];
+	}
 	customPropertiesFor(name) {
 		return this.byName.get(name)?.entry.cssPropertiesDeclared ?? [];
 	}
@@ -85,14 +90,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). */
@@ -135,12 +140,13 @@ function indexFromEntries(entries, file) {
 		memberSpans: /* @__PURE__ */ new Map(),
 		authoredModifiers: /* @__PURE__ */ new Set(),
 		authoredParts: /* @__PURE__ */ new Set(),
+		authoredShadowParts: /* @__PURE__ */ new Set(),
 		selectorText: ""
 	})), 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 +155,24 @@ 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);
+			for (const ps of matcher.pseudoStatesIn(selector)) set(memberKey("state", ps.name), node);
+			for (const sp of selector.matchAll(/::part\(\s*([\w-]+)\s*\)/gu)) set(memberKey("shadow-part", sp[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 el of matcher.elementsIn(bare, baseNoDot)) {
+				set(memberKey("part", el.name), node);
+				for (const m of el.modifiers) set(memberKey("modifier", m.name), node);
+			}
+			for (const st of matcher.statesIn(bare, baseNoDot)) set(memberKey("state", st.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 +185,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,10 +197,15 @@ 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,
+		parse: options.parse
+	});
 	const byName = new Map(entries.map((e) => [e.name, e]));
 	const builds = /* @__PURE__ */ new Map();
-	const root = postcss.parse(css);
+	const root = (options.parse ?? postcss.parse)(css);
 	let current;
 	for (const node of root.nodes) {
 		if (node.type === "comment") {
@@ -194,21 +219,23 @@ function createIndex(css, options = {}) {
 					memberSpans: /* @__PURE__ */ new Map(),
 					authoredModifiers: new Set(doc.modifiers.keys()),
 					authoredParts: new Set(doc.parts.keys()),
+					authoredShadowParts: new Set(doc.cssParts.keys()),
 					selectorText: ""
 				};
 				builds.set(name, current);
 				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,
 		memberSpans: /* @__PURE__ */ new Map(),
 		authoredModifiers: /* @__PURE__ */ new Set(),
 		authoredParts: /* @__PURE__ */ new Set(),
+		authoredShadowParts: /* @__PURE__ */ new Set(),
 		selectorText: ""
-	}), options.file);
+	}), options.file, matcher);
 }
 /**
 * Extract custom-property assignments (`--name: value`) and `var(--name, fallback)` references from
@@ -218,10 +245,10 @@ function createIndex(css, options = {}) {
 * @param css - The CSS source.
 * @returns The assignments and `var(…)` usages found.
 */
-function cssValueSites(css) {
+function cssValueSites(css, options = {}) {
 	const assignments = [];
 	const usages = [];
-	postcss.parse(css).walkDecls((decl) => {
+	(options.parse ?? postcss.parse)(css).walkDecls((decl) => {
 		const loc = spanOf(decl);
 		if (decl.prop.startsWith("--")) assignments.push({
 			name: decl.prop,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cssdoc/index",
-  "version": "0.1.0",
+  "version": "0.3.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.3.0"
   },
   "devDependencies": {
     "@types/node": "^24.13.3",