@cssdoc/providers 0.5.4 → 0.6.1

package/dist/index.d.mts

@@ -80,7 +80,7 @@ type HoverDetail = "compact" | "full" | "custom";
 type HoverSectionMode = "on" | "off" | "auto";
 type HoverSections = Record<string, HoverSectionMode>;
 /** The card's section keys, in default render order — the `custom` map is keyed by these. */
-declare const HOVER_SECTION_KEYS: readonly ["summary", "deprecated", "remarks", "accessibility", "modifiers", "parts", "shadowParts", "states", "customProperties", "functions", "slots", "animations", "layers", "conditions", "see", "structure", "examples"];
+declare const HOVER_SECTION_KEYS: readonly ["summary", "deprecated", "remarks", "accessibility", "modifiers", "parts", "shadowParts", "pseudoElements", "states", "customProperties", "functions", "slots", "animations", "layers", "conditions", "see", "todos", "structure", "examples"];
 /** One hover-card section name. */
 type HoverSectionKey = (typeof HOVER_SECTION_KEYS)[number];
 /**
@@ -184,6 +184,15 @@ declare function parseDirectives(source: string): Directive[];
 declare function applyDirectives(diagnostics: Diagnostic[], source: string): Diagnostic[];
 //#endregion
 //#region src/aspects.d.ts
+/**
+ * Whether `selectorText` (the record's concatenated selectors) defines the modifier/part `selector`
+ * (`.name`, where `name` may be a `*` glob for a family like `.-icon-*`; a name with no `*` is exact).
+ * Beyond a literal class token, `class` attribute selectors count with their real CSS operator
+ * semantics — `[class~=v]`/`[class=v]` (exact word), `[class*=v]` (substring), and `[class$=v]` (suffix)
+ * can define a chained modifier; `[class^=v]` cannot, since `^=` anchors to the start of the whole
+ * attribute (the base class), never a chained modifier.
+ */
+declare const selectorDefines: (selectorText: string, selector: string) => boolean;
 declare const record: {
   model(index: CssDocIndex, naming?: ResolvedNaming, structureIgnore?: readonly string[], siblingIndex?: CssDocIndex): Diagnostic[];
   completions(index: CssDocIndex): Completion[];
@@ -212,7 +221,7 @@ declare const customProperty: {
   assignment(a: PropertyAssignment, index: CssDocIndex): Diagnostic[];
   propertyUsage(usage: PropertyUsage, index: CssDocIndex, options: UsageOptions): Diagnostic[];
   completions(index: CssDocIndex): Completion[];
-  hover(name: string, index: CssDocIndex): Hover | undefined;
+  hover(name: string, index: CssDocIndex, valueIndex?: CssDocIndex): Hover | undefined;
   definition(name: string, index: CssDocIndex): Location$1 | undefined;
 };
 declare const func: {
@@ -243,8 +252,11 @@ declare function completeCustomProperties(index: CssDocIndex): Completion[];
 declare function completeFunctions(index: CssDocIndex): Completion[];
 /** Hover for a class token: the modifier's docs, else the component's card (at the given detail). */
 declare function hoverForClass(base: string, token: string, index: CssDocIndex, detail?: HoverDetail, sections?: HoverSections, sectionOrder?: HoverSectionOrder): Hover | undefined;
-/** Hover for a `var(--…)` custom property. */
-declare function hoverForCustomProperty(name: string, index: CssDocIndex): Hover | undefined;
+/**
+ * Hover for a `var(--…)` custom property. `valueIndex` (default `index`) supplies the value graph for
+ * `var()` resolution — pass a project-wide index so a chain that runs through other sheets resolves.
+ */
+declare function hoverForCustomProperty(name: string, index: CssDocIndex, valueIndex?: CssDocIndex): Hover | undefined;
 /** Hover for a custom function. */
 declare function hoverForFunction(name: string, index: CssDocIndex): Hover | undefined;
 /** Definition of a class token: the modifier's rule, else the component's. */
@@ -254,4 +266,4 @@ declare function definitionForCustomProperty(name: string, index: CssDocIndex):
 /** Definition of a custom function (its `@function` rule). */
 declare function definitionForFunction(name: string, index: CssDocIndex): Location$1 | undefined;
 //#endregion
-export { ASPECTS, Completion, CompletionKind, DEFAULT_RULE_SEVERITIES, Diagnostic, HOVER_SECTION_KEYS, Hover, HoverDetail, HoverSectionKey, HoverSectionMode, HoverSectionOrder, HoverSections, type Location, NAME_CASE_PRESETS, NameCase, NamingRules, ResolvedNaming, RuleId, RuleSeverities, RuleSeverity, Severity, type SourceSpan, SyntaxMatch, UsageOptions, applyDirectives, checkClassUsage, checkPropertyAssignments, checkPropertyUsage, completeClasses, completeCustomProperties, completeFunctions, cssPart, customProperty, definitionForClass, definitionForCustomProperty, definitionForFunction, func, hoverForClass, hoverForCustomProperty, hoverForFunction, linkSyntax, lintModel, matchesSyntax, mdnUrlForType, modifier, parseDirectives, part, partUsage, record, resolveNaming, resolveRuleSeverities, stateUsage };
+export { ASPECTS, Completion, CompletionKind, DEFAULT_RULE_SEVERITIES, Diagnostic, HOVER_SECTION_KEYS, Hover, HoverDetail, HoverSectionKey, HoverSectionMode, HoverSectionOrder, HoverSections, type Location, NAME_CASE_PRESETS, NameCase, NamingRules, ResolvedNaming, RuleId, RuleSeverities, RuleSeverity, Severity, type SourceSpan, SyntaxMatch, UsageOptions, applyDirectives, checkClassUsage, checkPropertyAssignments, checkPropertyUsage, completeClasses, completeCustomProperties, completeFunctions, cssPart, customProperty, definitionForClass, definitionForCustomProperty, definitionForFunction, func, hoverForClass, hoverForCustomProperty, hoverForFunction, linkSyntax, lintModel, matchesSyntax, mdnUrlForType, modifier, parseDirectives, part, partUsage, record, resolveNaming, resolveRuleSeverities, selectorDefines, stateUsage };

package/dist/index.mjs

@@ -131,6 +131,7 @@ const HOVER_SECTION_KEYS = [
 	"modifiers",
 	"parts",
 	"shadowParts",
+	"pseudoElements",
 	"states",
 	"customProperties",
 	"functions",
@@ -139,6 +140,7 @@ const HOVER_SECTION_KEYS = [
 	"layers",
 	"conditions",
 	"see",
+	"todos",
 	"structure",
 	"examples"
 ];
@@ -220,15 +222,17 @@ const globMatch = (pattern, value) => {
 /**
 * Serialize an authored `@structure` tree back to nested CSS for a syntax-highlighted hover block. Leaf
 * selectors are left bare (no `{}`) — VS Code's CSS grammar still colours them, and it reads like the
-* authored `@structure` declaration; only nesting keeps braces.
+* authored `@structure` declaration; only nesting keeps braces. A node's authored prose (`@wrapper`)
+* trails its selector as a CSS comment.
 */
 const renderStructureTree = (nodes, depth = 0) => nodes.flatMap((n) => {
 	const pad = "  ".repeat(depth);
+	const note = n.description ? ` /* ${n.description} */` : "";
 	return n.children.length ? [
-		`${pad}${n.selector} {`,
+		`${pad}${n.selector} {${note}`,
 		...renderStructureTree(n.children, depth + 1),
 		`${pad}}`
-	] : [`${pad}${n.selector}`];
+	] : [`${pad}${n.selector}${note}`];
 });
 const record = {
 	model(index, naming, structureIgnore = [], siblingIndex = index) {
@@ -262,6 +266,10 @@ const record = {
 					...info.entry.modifiers.map((m) => m.name),
 					...info.entry.slots.map((s) => s.name)
 				]);
+				const selfClass = stripDot(info.entry.className);
+				const classesOf = (sel) => [...sel.matchAll(/\.([\w-]+)/gu)].map((m) => m[1]);
+				const hasSelfBelow = (nodes) => nodes.some((n) => classesOf(n.selector).includes(selfClass) || hasSelfBelow(n.children));
+				for (const root of info.entry.structure) if (hasSelfBelow(root.children)) for (const c of classesOf(root.selector)) known.add(c);
 				const own = stripDot(info.entry.className);
 				const prefix = info.entry.name && own.endsWith(info.entry.name) ? own.slice(0, own.length - info.entry.name.length) : "";
 				const isSibling = (cls) => prefix !== "" && cls.startsWith(prefix) && siblingNames.has(cls.slice(prefix.length));
@@ -317,6 +325,7 @@ const record = {
 				entry.modifiers.length && `${entry.modifiers.length} modifiers`,
 				entry.parts.length && `${entry.parts.length} parts`,
 				entry.shadowParts.length && `${entry.shadowParts.length} shadow parts`,
+				entry.pseudoElements.length && `${entry.pseudoElements.length} pseudo-elements`,
 				entry.states.length && `${entry.states.length} states`,
 				entry.cssPropertiesDeclared.length && `${entry.cssPropertiesDeclared.length} custom properties`,
 				entry.functions.length && `${entry.functions.length} functions`,
@@ -360,6 +369,7 @@ const record = {
 		}));
 		list("parts", "symbol-field", "Parts", entry.parts.map((p) => `- ${styled(`.${p.name}`, "field")}${dash(p.description)}`));
 		list("shadowParts", "symbol-namespace", "Shadow parts", entry.shadowParts.map((p) => `- ${styled(`::part(${p.name})`, "field")}${dash(p.description)}`));
+		list("pseudoElements", "symbol-misc", "Pseudo-elements", entry.pseudoElements.map((p) => `- ${styled(`::${p.name}`, "field")}${dash(p.description)}`));
 		list("states", "symbol-event", "States", entry.states.map((s) => `- ${styled(s.kind === "custom" ? `:state(${s.name})` : `:${s.name}`, "variable")}${dash(s.description)}`));
 		list("customProperties", "symbol-variable", "Custom properties", entry.cssPropertiesDeclared.map((p) => {
 			const syntax = p.syntax ? `: ${linkedSyntax(p.syntax)}` : "";
@@ -372,6 +382,7 @@ const record = {
 		list("layers", "layers", "Layers", entry.layers.map((l) => `- ${styled(l.name, "class")}${dash(l.description)}`));
 		list("conditions", "filter", "Conditions", entry.conditions.map((c) => `- \`@${c.type} ${c.query}\`${dash(c.description)}`));
 		list("see", "references", "See also", entry.see.map((s) => `- ${s}`));
+		list("todos", "checklist", "To do", entry.todos.map((t) => `- ${t}`));
 		{
 			const w = want("structure", Boolean(entry.structure?.length));
 			if (w !== "skip") {
@@ -645,13 +656,16 @@ const customProperty = {
 			documentation: property.description
 		}));
 	},
-	hover(name, index) {
+	hover(name, index, valueIndex = index) {
 		const found = findProperty(index, name);
-		if (!found) return void 0;
-		const p = found.record.entry.cssPropertiesDeclared[found.index];
-		const lines = [`\`${p.name}\`${p.syntax ? ` — ${linkedSyntax(p.syntax)}` : ""}`];
-		if (p.defaultValue) lines.push("", `Default: \`${p.defaultValue}\``);
-		if (p.description) lines.push("", p.description);
+		const { declared, resolved } = valueIndex.resolveCustomProperty(name);
+		if (!found && declared === void 0) return void 0;
+		const p = found?.record.entry.cssPropertiesDeclared[found.index];
+		const lines = [`\`${name}\`${p?.syntax ? ` — ${linkedSyntax(p.syntax)}` : ""}`];
+		const value = declared ?? p?.defaultValue;
+		if (value) lines.push("", `Value: \`${value}\``);
+		if (resolved) lines.push("", `Resolves to: \`${resolved}\``);
+		if (p?.description) lines.push("", p.description);
 		return { contents: lines.join("\n") };
 	},
 	definition(name, index) {
@@ -851,9 +865,12 @@ function completeFunctions(index) {
 function hoverForClass(base, token, index, detail = "full", sections, sectionOrder) {
 	return modifier.hover(base, token, index) ?? record.hover(base, index, detail, sections, sectionOrder);
 }
-/** Hover for a `var(--…)` custom property. */
-function hoverForCustomProperty(name, index) {
-	return customProperty.hover(name, index);
+/**
+* Hover for a `var(--…)` custom property. `valueIndex` (default `index`) supplies the value graph for
+* `var()` resolution — pass a project-wide index so a chain that runs through other sheets resolves.
+*/
+function hoverForCustomProperty(name, index, valueIndex = index) {
+	return customProperty.hover(name, index, valueIndex);
 }
 /** Hover for a custom function. */
 function hoverForFunction(name, index) {
@@ -872,4 +889,4 @@ function definitionForFunction(name, index) {
 	return func.definition(name, index);
 }
 //#endregion
-export { ASPECTS, DEFAULT_RULE_SEVERITIES, HOVER_SECTION_KEYS, NAME_CASE_PRESETS, applyDirectives, checkClassUsage, checkPropertyAssignments, checkPropertyUsage, completeClasses, completeCustomProperties, completeFunctions, cssPart, customProperty, definitionForClass, definitionForCustomProperty, definitionForFunction, func, hoverForClass, hoverForCustomProperty, hoverForFunction, linkSyntax, lintModel, matchesSyntax, mdnUrlForType, modifier, parseDirectives, part, partUsage, record, resolveNaming, resolveRuleSeverities, stateUsage };
+export { ASPECTS, DEFAULT_RULE_SEVERITIES, HOVER_SECTION_KEYS, NAME_CASE_PRESETS, applyDirectives, checkClassUsage, checkPropertyAssignments, checkPropertyUsage, completeClasses, completeCustomProperties, completeFunctions, cssPart, customProperty, definitionForClass, definitionForCustomProperty, definitionForFunction, func, hoverForClass, hoverForCustomProperty, hoverForFunction, linkSyntax, lintModel, matchesSyntax, mdnUrlForType, modifier, parseDirectives, part, partUsage, record, resolveNaming, resolveRuleSeverities, selectorDefines, stateUsage };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cssdoc/providers",
-  "version": "0.5.4",
+  "version": "0.6.1",
   "description": "Host-agnostic aspect providers over the @cssdoc/index — diagnostics, completions, hover, and definitions for modifiers, custom properties, structure, functions, states, and conditions.",
   "keywords": [
     "css",
@@ -29,8 +29,8 @@
   },
   "dependencies": {
     "css-tree": "^3.2.1",
-    "@cssdoc/core": "0.5.4",
-    "@cssdoc/index": "0.5.4"
+    "@cssdoc/core": "0.6.1",
+    "@cssdoc/index": "0.6.1"
   },
   "devDependencies": {
     "@types/css-tree": "^2.3.11",