@cssdoc/index 0.5.4 → 0.6.0

package/dist/index.d.mts

@@ -53,7 +53,7 @@ interface CssValueSites {
   usages: PropertyUsage[];
 }
 /** The kinds of record member a span can be keyed to. */
-type MemberKind = "record" | "modifier" | "part" | "shadow-part" | "property" | "function" | "animation" | "layer" | "state" | "condition";
+type MemberKind = "record" | "modifier" | "part" | "shadow-part" | "pseudo-element" | "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. */
@@ -84,9 +84,20 @@ declare class CssDocIndex {
   readonly records: readonly RecordInfo[];
   /** The modifier matcher for this index's convention — how members are matched and rendered. */
   readonly matcher: ModifierMatcher;
+  /** Every custom property's effective value (`--x: value` declarations and `@property` initial-values). */
+  readonly customPropertyValues: ReadonlyMap<string, string>;
   private readonly byName;
   private readonly byClass;
-  constructor(records: RecordInfo[], file?: string, matcher?: ModifierMatcher);
+  constructor(records: RecordInfo[], file?: string, matcher?: ModifierMatcher, customPropertyValues?: ReadonlyMap<string, string>);
+  /**
+   * A custom property's declared value and its fully resolved value — following `var()` references
+   * through the index to a terminal literal, the way browser dev tools do. `resolved` is omitted when
+   * nothing was followed (no `var()`, or the chain couldn't be resolved further).
+   */
+  resolveCustomProperty(name: string): {
+    declared?: string;
+    resolved?: string;
+  };
   /** Every documented record's model entry. */
   get entries(): CssDocEntry[];
   /** The record whose base class matches `className` (with or without a leading dot). */

package/dist/index.mjs

@@ -34,23 +34,66 @@ const spanOf = (node) => {
 		}
 	};
 };
+/**
+* Follow the `var()` references in `value` through `values` to a terminal literal — the resolution a
+* browser's dev tools show. Uses a `var(--x, fallback)` fallback when `--x` is undefined, and leaves a
+* reference in place on an unknown property or a cycle (so the output degrades to the furthest it could
+* reach rather than looping).
+*/
+function resolveValue(value, values, seen) {
+	if (!value.includes("var(")) return value;
+	const parsed = valueParser(value);
+	parsed.walk((node) => {
+		if (node.type !== "function" || node.value !== "var") return void 0;
+		const ref = node.nodes.find((n) => n.type === "word")?.value;
+		if (!ref?.startsWith("--")) return false;
+		const comma = node.nodes.findIndex((n) => n.type === "div" && n.value === ",");
+		const fallback = comma >= 0 ? valueParser.stringify(node.nodes.slice(comma + 1)).trim() : void 0;
+		const declared = seen.has(ref) ? void 0 : values.get(ref);
+		const replacement = declared !== void 0 ? resolveValue(declared, values, /* @__PURE__ */ new Set([...seen, ref])) : fallback !== void 0 ? resolveValue(fallback, values, seen) : void 0;
+		if (replacement !== void 0) {
+			node.type = "word";
+			node.value = replacement;
+			node.nodes = [];
+		}
+		return false;
+	});
+	return valueParser.stringify(parsed.nodes);
+}
 /** A queryable view over the parsed records. */
 var CssDocIndex = class {
 	file;
 	records;
 	/** The modifier matcher for this index's convention — how members are matched and rendered. */
 	matcher;
+	/** Every custom property's effective value (`--x: value` declarations and `@property` initial-values). */
+	customPropertyValues;
 	byName = /* @__PURE__ */ new Map();
 	byClass = /* @__PURE__ */ new Map();
-	constructor(records, file, matcher) {
+	constructor(records, file, matcher, customPropertyValues = /* @__PURE__ */ new Map()) {
 		this.records = records;
 		this.file = file;
 		this.matcher = matcher ?? new ModifierMatcher(DEFAULT_MODIFIER_CONVENTION);
+		this.customPropertyValues = customPropertyValues;
 		for (const record of records) {
 			this.byName.set(record.entry.name, record);
 			this.byClass.set(stripDot(record.entry.className), record);
 		}
 	}
+	/**
+	* A custom property's declared value and its fully resolved value — following `var()` references
+	* through the index to a terminal literal, the way browser dev tools do. `resolved` is omitted when
+	* nothing was followed (no `var()`, or the chain couldn't be resolved further).
+	*/
+	resolveCustomProperty(name) {
+		const declared = this.customPropertyValues.get(name);
+		if (declared === void 0) return {};
+		const resolved = resolveValue(declared, this.customPropertyValues, /* @__PURE__ */ new Set([name]));
+		return {
+			declared,
+			resolved: resolved === declared ? void 0 : resolved
+		};
+	}
 	/** Every documented record's model entry. */
 	get entries() {
 		return this.records.map((r) => r.entry);
@@ -159,6 +202,7 @@ function scanNodes(nodes, build, base, matcher) {
 			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);
+			for (const pe of matcher.pseudoElementsIn(selector)) set(memberKey("pseudo-element", pe.name), node);
 			const bare = selector.replace(/::?[\w-]+(\([^)]*\))?/gu, "");
 			const modNames = /* @__PURE__ */ new Set();
 			for (const mod of matcher.modifiersIn(bare, baseNoDot)) {
@@ -229,14 +273,25 @@ function createIndex(css, options = {}) {
 		}
 		if (current) scanNodes([node], current, current.entry.className, matcher);
 	}
-	return new CssDocIndex(entries.map((entry) => builds.get(entry.name) ?? {
+	const records = 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, matcher);
+	});
+	const customPropertyValues = /* @__PURE__ */ new Map();
+	root.walkAtRules("property", (at) => {
+		const name = at.params.trim();
+		at.walkDecls("initial-value", (d) => {
+			customPropertyValues.set(name, d.value);
+		});
+	});
+	root.walkDecls((d) => {
+		if (d.prop.startsWith("--")) customPropertyValues.set(d.prop, d.value);
+	});
+	return new CssDocIndex(records, options.file, matcher, customPropertyValues);
 }
 /**
 * Extract custom-property assignments (`--name: value`) and `var(--name, fallback)` references from

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cssdoc/index",
-  "version": "0.5.4",
+  "version": "0.6.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.19",
     "postcss-value-parser": "^4.2.0",
-    "@cssdoc/core": "0.5.4"
+    "@cssdoc/core": "0.6.0"
   },
   "devDependencies": {
     "@types/node": "^24.13.3",