@cssdoc/providers 0.3.2 → 0.4.0

package/dist/index.d.mts

@@ -57,6 +57,22 @@ interface Completion {
 interface Hover {
   contents: string;
 }
+/**
+ * How much a component hover card shows. `compact` is the header, summary, deprecation, and a facet
+ * count line; `full` expands every facet that has content into a labelled section; `custom` takes a
+ * per-section {@link HoverSections} map. A shippable stand-in for VS Code's not-yet-stable
+ * hover-verbosity control.
+ */
+type HoverDetail = "compact" | "full" | "custom";
+/**
+ * Per-section visibility for the `custom` hover detail. `auto` shows the section only when it has
+ * content (what `full` does for every section); `on` always shows it (empty sections render a
+ * placeholder); `off` hides it. Keys are the card's section names — see {@link HOVER_SECTION_KEYS}.
+ */
+type HoverSectionMode = "on" | "off" | "auto";
+type HoverSections = Record<string, HoverSectionMode>;
+/** The card's section keys, in 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"];
 /** Options that tune usage checks. */
 interface UsageOptions {
   /**
@@ -131,7 +147,7 @@ declare function applyDirectives(diagnostics: Diagnostic[], source: string): Dia
 declare const record: {
   model(index: CssDocIndex, naming?: ResolvedNaming, structureIgnore?: readonly string[]): Diagnostic[];
   completions(index: CssDocIndex): Completion[];
-  hover(base: string, index: CssDocIndex): Hover | undefined;
+  hover(base: string, index: CssDocIndex, detail?: HoverDetail, sections?: HoverSections): Hover | undefined;
   definition(base: string, index: CssDocIndex): Location$1 | undefined;
 };
 declare const modifier: {
@@ -185,8 +201,8 @@ declare function completeClasses(base: string | undefined, index: CssDocIndex):
 declare function completeCustomProperties(index: CssDocIndex): Completion[];
 /** Completions for a value position: the custom functions. */
 declare function completeFunctions(index: CssDocIndex): Completion[];
-/** Hover for a class token: the modifier's docs, else the component's. */
-declare function hoverForClass(base: string, token: string, index: CssDocIndex): Hover | undefined;
+/** 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): Hover | undefined;
 /** Hover for a `var(--…)` custom property. */
 declare function hoverForCustomProperty(name: string, index: CssDocIndex): Hover | undefined;
 /** Hover for a custom function. */
@@ -198,4 +214,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, 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, lintModel, matchesSyntax, modifier, parseDirectives, part, partUsage, record, resolveNaming, resolveRuleSeverities, stateUsage };
+export { ASPECTS, Completion, CompletionKind, DEFAULT_RULE_SEVERITIES, Diagnostic, HOVER_SECTION_KEYS, Hover, HoverDetail, HoverSectionMode, 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, lintModel, matchesSyntax, modifier, parseDirectives, part, partUsage, record, resolveNaming, resolveRuleSeverities, stateUsage };

package/dist/index.mjs

@@ -69,6 +69,19 @@ const globMatch = (pattern, value) => {
 	if (!pattern.includes("*")) return pattern === value;
 	return new RegExp(`^${pattern.replace(/[.+?^${}()|[\]\\]/gu, "\\$&").replace(/\*/gu, ".*")}$`, "u").test(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.
+*/
+const renderStructureTree = (nodes, depth = 0) => nodes.flatMap((n) => {
+	const pad = "  ".repeat(depth);
+	return n.children.length ? [
+		`${pad}${n.selector} {`,
+		...renderStructureTree(n.children, depth + 1),
+		`${pad}}`
+	] : [`${pad}${n.selector}`];
+});
 const record = {
 	model(index, naming, structureIgnore = []) {
 		const out = [];
@@ -130,23 +143,96 @@ const record = {
 			deprecated: Boolean(entry.deprecated)
 		}));
 	},
-	hover(base, index) {
+	hover(base, index, detail = "full", sections) {
 		const entry = index.componentForClass(base);
 		if (!entry) return void 0;
-		const lines = [`\`${entry.className}\` — ${entry.kind}`];
-		if (entry.summary) lines.push("", entry.summary);
-		if (entry.remarks) lines.push("", entry.remarks);
-		const facets = [
-			entry.modifiers.length && `${entry.modifiers.length} modifiers`,
-			entry.parts.length && `${entry.parts.length} parts`,
-			entry.shadowParts.length && `${entry.shadowParts.length} shadow parts`,
-			entry.states.length && `${entry.states.length} states`,
-			entry.cssPropertiesDeclared.length && `${entry.cssPropertiesDeclared.length} custom properties`,
-			entry.functions.length && `${entry.functions.length} functions`,
-			entry.conditions.length && `${entry.conditions.length} conditions`
-		].filter(Boolean);
-		if (facets.length) lines.push("", facets.join(" · "));
-		if (entry.deprecated) lines.push("", `**Deprecated** — ${entry.deprecated}`);
+		const selectorFor = (name) => index.matcher.selectorFor(name);
+		const warnHtml = (label) => `<span style="color:var(--vscode-editorWarning-foreground);">${label}</span>`;
+		const styled = (text, kind) => `<code style="color:var(--vscode-symbolIcon-${kind}Foreground);">${text}</code>`;
+		const dash = (d) => d ? ` — ${d}` : "";
+		const head = [`$(symbol-class) ${styled(entry.className, "class")}`, entry.kind];
+		if (entry.releaseStage) head.push(entry.releaseStage);
+		if (entry.since) head.push(`since ${entry.since}`);
+		const lines = [head.join(" · ")];
+		const deprecatedLine = entry.deprecated ? `$(warning) ${warnHtml("Deprecated")} — ${entry.deprecated}` : void 0;
+		if (detail === "compact") {
+			if (entry.summary) lines.push("", entry.summary);
+			if (deprecatedLine) lines.push("", deprecatedLine);
+			const facets = [
+				entry.modifiers.length && `${entry.modifiers.length} modifiers`,
+				entry.parts.length && `${entry.parts.length} parts`,
+				entry.shadowParts.length && `${entry.shadowParts.length} shadow parts`,
+				entry.states.length && `${entry.states.length} states`,
+				entry.cssPropertiesDeclared.length && `${entry.cssPropertiesDeclared.length} custom properties`,
+				entry.functions.length && `${entry.functions.length} functions`,
+				entry.conditions.length && `${entry.conditions.length} conditions`
+			].filter(Boolean);
+			if (facets.length) lines.push("", facets.join(" · "));
+			return { contents: lines.join("\n") };
+		}
+		const want = (key, has) => {
+			const mode = detail === "custom" ? sections?.[key] ?? "auto" : "auto";
+			if (mode === "off") return "skip";
+			return has ? "content" : mode === "on" ? "empty" : "skip";
+		};
+		const prose = (key, prefix, text) => {
+			const w = want(key, Boolean(text?.trim()));
+			if (w !== "skip") lines.push("", `${prefix}${w === "content" ? text : "_—_"}`);
+		};
+		const list = (key, icon, label, rows) => {
+			const w = want(key, rows.length > 0);
+			if (w !== "skip") lines.push("", `**$(${icon}) ${label}**`, ...w === "content" ? rows : ["_—_"]);
+		};
+		prose("summary", "", entry.summary);
+		{
+			const w = want("deprecated", Boolean(entry.deprecated));
+			if (w !== "skip") lines.push("", w === "content" ? deprecatedLine : `$(warning) ${warnHtml("Deprecated")}`);
+		}
+		prose("remarks", "", entry.remarks);
+		prose("accessibility", "$(accessibility) ", entry.accessibility);
+		list("modifiers", "symbol-property", "Modifiers", entry.modifiers.map((m) => {
+			const sel = styled(selectorFor(m.name), "field");
+			if (m.deprecated) {
+				const to = m.deprecated.canonical ? ` → ${styled(selectorFor(m.deprecated.canonical), "field")}` : dash(m.deprecated.note);
+				return `- ${sel} — ${warnHtml("deprecated")}${to}`;
+			}
+			return `- ${sel}${dash(m.description)}`;
+		}));
+		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("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 ? `: \`${p.syntax}\`` : "";
+			const def = p.defaultValue ? ` (default \`${p.defaultValue}\`)` : "";
+			return `- ${styled(p.name, "variable")}${syntax}${def}${dash(p.description)}`;
+		}));
+		list("functions", "symbol-method", "Functions", entry.functions.map((f) => `- ${styled(`${f.name}()`, "method")}${dash(f.description)}`));
+		list("slots", "symbol-parameter", "Slots", entry.slots.map((s) => `- ${styled(s.name, "field")}${dash(s.description)}`));
+		list("animations", "play", "Animations", entry.animations.map((a) => `- ${styled(a.name, "method")}${dash(a.description)}`));
+		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}`));
+		{
+			const w = want("structure", Boolean(entry.structure?.length));
+			if (w !== "skip") {
+				lines.push("", "**$(list-tree) Structure**");
+				if (w === "content") {
+					if (entry.structureDescription) lines.push("", entry.structureDescription);
+					lines.push("", "```css", ...renderStructureTree(entry.structure ?? []), "```");
+				} else lines.push("", "_—_");
+			}
+		}
+		{
+			const w = want("examples", entry.examples.length > 0);
+			if (w !== "skip") {
+				lines.push("", `**$(book) Example${entry.examples.length > 1 ? "s" : ""}**`);
+				if (w === "content") for (const e of entry.examples) {
+					const ex = e.trim();
+					lines.push("", ex.startsWith("```") ? ex : `\`\`\`${ex.includes("<") ? "html" : "css"}\n${ex}\n\`\`\``);
+				}
+				else lines.push("", "_—_");
+			}
+		}
 		return { contents: lines.join("\n") };
 	},
 	definition(base, index) {
@@ -464,6 +550,26 @@ function resolveRuleSeverities(overrides) {
 	}
 	return resolved;
 }
+/** The card's section keys, in render order — the `custom` map is keyed by these. */
+const HOVER_SECTION_KEYS = [
+	"summary",
+	"deprecated",
+	"remarks",
+	"accessibility",
+	"modifiers",
+	"parts",
+	"shadowParts",
+	"states",
+	"customProperties",
+	"functions",
+	"slots",
+	"animations",
+	"layers",
+	"conditions",
+	"see",
+	"structure",
+	"examples"
+];
 /** The built-in name-case patterns, tested against a class name without its leading dot. */
 const NAME_CASE_PRESETS = {
 	pascalCase: /^[A-Z][A-Za-z0-9]*$/u,
@@ -651,9 +757,9 @@ function completeCustomProperties(index) {
 function completeFunctions(index) {
 	return func.completions(index);
 }
-/** Hover for a class token: the modifier's docs, else the component's. */
-function hoverForClass(base, token, index) {
-	return modifier.hover(base, token, index) ?? record.hover(base, index);
+/** Hover for a class token: the modifier's docs, else the component's card (at the given detail). */
+function hoverForClass(base, token, index, detail = "full", sections) {
+	return modifier.hover(base, token, index) ?? record.hover(base, index, detail, sections);
 }
 /** Hover for a `var(--…)` custom property. */
 function hoverForCustomProperty(name, index) {
@@ -676,4 +782,4 @@ function definitionForFunction(name, index) {
 	return func.definition(name, index);
 }
 //#endregion
-export { ASPECTS, DEFAULT_RULE_SEVERITIES, NAME_CASE_PRESETS, applyDirectives, checkClassUsage, checkPropertyAssignments, checkPropertyUsage, completeClasses, completeCustomProperties, completeFunctions, cssPart, customProperty, definitionForClass, definitionForCustomProperty, definitionForFunction, func, hoverForClass, hoverForCustomProperty, hoverForFunction, lintModel, matchesSyntax, 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, lintModel, matchesSyntax, modifier, parseDirectives, part, partUsage, record, resolveNaming, resolveRuleSeverities, stateUsage };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cssdoc/providers",
-  "version": "0.3.2",
+  "version": "0.4.0",
   "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.3.2",
-    "@cssdoc/index": "0.3.2"
+    "@cssdoc/core": "0.4.0",
+    "@cssdoc/index": "0.4.0"
   },
   "devDependencies": {
     "@types/css-tree": "^2.3.11",