@cssdoc/providers 0.3.3 → 0.4.1

package/dist/index.d.mts

@@ -71,8 +71,16 @@ type HoverDetail = "compact" | "full" | "custom";
  */
 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. */
+/** 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"];
+/** One hover-card section name. */
+type HoverSectionKey = (typeof HOVER_SECTION_KEYS)[number];
+/**
+ * The order sections render in the hover card, and which ones render. Defaults to
+ * {@link HOVER_SECTION_KEYS}; supply a subset/reordering to move or drop sections (unlisted sections are
+ * omitted). The fixed header (name · kind · release stage · since) always leads.
+ */
+type HoverSectionOrder = readonly HoverSectionKey[];
 /** Options that tune usage checks. */
 interface UsageOptions {
   /**
@@ -121,12 +129,36 @@ interface SyntaxMatch {
  */
 declare function matchesSyntax(syntax: string, value: string): SyntaxMatch;
 //#endregion
+//#region src/mdn.d.ts
+/**
+ * MDN links for CSS value types. A `@property` `syntax` descriptor (e.g. `<color>`, `<length-percentage>`)
+ * names value types that MDN documents; this maps each `<type>` to its reference page so hovers and the
+ * docs playground can link them. Format-agnostic: {@link linkSyntax} takes a `renderLink` callback so
+ * each caller wraps a link in its own output format (a markdown `[…](…)` for hovers, an `<a>` for HTML).
+ *
+ * @module
+ */
+/** The MDN reference URL for a bare CSS value-type name (e.g. `color`, `length-percentage`). */
+declare function mdnUrlForType(type: string): string;
+/**
+ * Rewrite each `<type>` token in a `syntax` descriptor via `renderLink`, leaving the rest untouched.
+ * `renderLink` receives the bare type name and its MDN URL and returns the replacement for `<type>`
+ * (including the angle brackets). Non-`<type>` text (e.g. `|`, `+`, `#`) passes through verbatim.
+ *
+ * @param syntax - The `@property` syntax descriptor, e.g. `<color> | <length>`.
+ * @param renderLink - Builds the replacement for one `<type>` token.
+ * @returns The descriptor with each `<type>` replaced.
+ */
+declare function linkSyntax(syntax: string, renderLink: (type: string, url: string) => string): string;
+//#endregion
 //#region src/directives.d.ts
 type DirectiveKind = "disable" | "enable" | "disable-line" | "disable-next-line" | "expect-error";
 interface Directive {
   kind: DirectiveKind;
   /** Rule ids the directive scopes to, or `null` for every rule. */
   rules: string[] | null;
+  /** The author's justification, from a trailing ` - <reason>` on the directive, when present. */
+  reason?: string;
   /** 1-based line the comment starts / ends on. */
   startLine: number;
   endLine: number;
@@ -147,7 +179,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, detail?: HoverDetail, sections?: HoverSections): Hover | undefined;
+  hover(base: string, index: CssDocIndex, detail?: HoverDetail, sections?: HoverSections, sectionOrder?: HoverSectionOrder): Hover | undefined;
   definition(base: string, index: CssDocIndex): Location$1 | undefined;
 };
 declare const modifier: {
@@ -202,7 +234,7 @@ 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 card (at the given detail). */
-declare function hoverForClass(base: string, token: string, index: CssDocIndex, detail?: HoverDetail, sections?: HoverSections): Hover | undefined;
+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 custom function. */
@@ -214,4 +246,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, 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 };
+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 };

package/dist/index.mjs

@@ -1,5 +1,32 @@
 import { memberKey } from "@cssdoc/index";
 import { fork } from "css-tree";
+//#region src/mdn.ts
+/**
+* MDN links for CSS value types. A `@property` `syntax` descriptor (e.g. `<color>`, `<length-percentage>`)
+* names value types that MDN documents; this maps each `<type>` to its reference page so hovers and the
+* docs playground can link them. Format-agnostic: {@link linkSyntax} takes a `renderLink` callback so
+* each caller wraps a link in its own output format (a markdown `[…](…)` for hovers, an `<a>` for HTML).
+*
+* @module
+*/
+const MDN_URL = { color: "https://developer.mozilla.org/en-US/docs/Web/CSS/color_value" };
+/** The MDN reference URL for a bare CSS value-type name (e.g. `color`, `length-percentage`). */
+function mdnUrlForType(type) {
+	return MDN_URL[type] ?? `https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Values/${type}`;
+}
+/**
+* Rewrite each `<type>` token in a `syntax` descriptor via `renderLink`, leaving the rest untouched.
+* `renderLink` receives the bare type name and its MDN URL and returns the replacement for `<type>`
+* (including the angle brackets). Non-`<type>` text (e.g. `|`, `+`, `#`) passes through verbatim.
+*
+* @param syntax - The `@property` syntax descriptor, e.g. `<color> | <length>`.
+* @param renderLink - Builds the replacement for one `<type>` token.
+* @returns The descriptor with each `<type>` replaced.
+*/
+function linkSyntax(syntax, renderLink) {
+	return syntax.replace(/<([a-z][\w-]*)>/gu, (_m, type) => renderLink(type, mdnUrlForType(type)));
+}
+//#endregion
 //#region src/syntax.ts
 /**
 * Match a CSS value against a registered custom property's `@property` `syntax` descriptor, using
@@ -55,7 +82,96 @@ function matchesSyntax(syntax, value) {
 	};
 }
 //#endregion
+//#region src/types.ts
+/**
+* The default rule severities. `unknown-modifier` defaults to `warn` — safe under the BEM default's
+* strong `--` signal; lower it to `off` for weak-signal conventions (bare/OOCSS) where every chained
+* class is a candidate. `unknown-custom-property` stays `off` (it needs an opt-in `propertyPrefix`).
+*/
+const DEFAULT_RULE_SEVERITIES = {
+	"missing-summary": "warn",
+	"undocumented-modifier": "warn",
+	"deprecated-requires-canonical": "warn",
+	"name-not-in-css": "warn",
+	"unknown-modifier": "warn",
+	"deprecated-modifier": "warn",
+	"unknown-state": "warn",
+	"unknown-part": "warn",
+	"undocumented-part": "warn",
+	"undocumented-css-part": "warn",
+	"component-name-case": "warn",
+	"part-name-case": "warn",
+	"structure-unknown-selector": "warn",
+	"invalid-default-value": "warn",
+	"invalid-property-value": "warn",
+	"invalid-fallback-value": "warn",
+	"unknown-custom-property": "off",
+	"cssdoc-directive": "warn"
+};
+/**
+* Merge per-rule overrides over {@link DEFAULT_RULE_SEVERITIES}. A `boolean` override is accepted for
+* back-compat: `false` → `off`, `true` → the rule's default.
+*/
+function resolveRuleSeverities(overrides) {
+	const resolved = { ...DEFAULT_RULE_SEVERITIES };
+	if (!overrides) return resolved;
+	for (const [rule, value] of Object.entries(overrides)) {
+		if (value === void 0) continue;
+		if (typeof value === "boolean") resolved[rule] = value ? DEFAULT_RULE_SEVERITIES[rule] : "off";
+		else resolved[rule] = value;
+	}
+	return resolved;
+}
+/** The card's section keys, in default 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,
+	camelCase: /^[a-z][A-Za-z0-9]*$/u,
+	lowercase: /^[a-z][a-z0-9-]*$/u
+};
+/** Compile one {@link NameCase} to a regex: a preset, else the string as a custom pattern. */
+function compileNameCase(spec) {
+	if (!spec) return void 0;
+	if (spec in NAME_CASE_PRESETS) return NAME_CASE_PRESETS[spec];
+	try {
+		return new RegExp(spec, "u");
+	} catch {
+		return;
+	}
+}
+/** Compile {@link NamingRules} to regexes once, for the record/part name-case checks. */
+function resolveNaming(naming) {
+	return {
+		component: compileNameCase(naming?.component),
+		part: compileNameCase(naming?.part)
+	};
+}
+//#endregion
 //#region src/aspects.ts
+/** Render a `@property` syntax descriptor with each `<type>` linked to its MDN reference page. */
+const linkedSyntax = (syntax) => {
+	const linked = linkSyntax(syntax, (type, url) => `[\`<${type}>\`](${url})`);
+	return linked === syntax ? `\`${syntax}\`` : linked;
+};
 const stripDot = (name) => name.replace(/^\./u, "");
 const warn = (d) => ({
 	...d,
@@ -143,7 +259,7 @@ const record = {
 			deprecated: Boolean(entry.deprecated)
 		}));
 	},
-	hover(base, index, detail = "full", sections) {
+	hover(base, index, detail = "full", sections, sectionOrder) {
 		const entry = index.componentForClass(base);
 		if (!entry) return void 0;
 		const selectorFor = (name) => index.matcher.selectorFor(name);
@@ -175,18 +291,23 @@ const record = {
 			if (mode === "off") return "skip";
 			return has ? "content" : mode === "on" ? "empty" : "skip";
 		};
+		const fragments = {};
 		const prose = (key, prefix, text) => {
 			const w = want(key, Boolean(text?.trim()));
-			if (w !== "skip") lines.push("", `${prefix}${w === "content" ? text : "_—_"}`);
+			if (w !== "skip") fragments[key] = ["", `${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 : ["_—_"]);
+			if (w !== "skip") fragments[key] = [
+				"",
+				`**$(${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")}`);
+			if (w !== "skip") fragments.deprecated = ["", w === "content" ? deprecatedLine : `$(warning) ${warnHtml("Deprecated")}`];
 		}
 		prose("remarks", "", entry.remarks);
 		prose("accessibility", "$(accessibility) ", entry.accessibility);
@@ -202,7 +323,7 @@ const record = {
 		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 syntax = p.syntax ? `: ${linkedSyntax(p.syntax)}` : "";
 			const def = p.defaultValue ? ` (default \`${p.defaultValue}\`)` : "";
 			return `- ${styled(p.name, "variable")}${syntax}${def}${dash(p.description)}`;
 		}));
@@ -215,24 +336,30 @@ const record = {
 		{
 			const w = want("structure", Boolean(entry.structure?.length));
 			if (w !== "skip") {
-				lines.push("", "**$(list-tree) Structure**");
+				const frag = ["", "**$(list-tree) Structure**"];
 				if (w === "content") {
-					if (entry.structureDescription) lines.push("", entry.structureDescription);
-					lines.push("", "```css", ...renderStructureTree(entry.structure ?? []), "```");
-				} else lines.push("", "_—_");
+					if (entry.structureDescription) frag.push("", entry.structureDescription);
+					frag.push("", "```css", ...renderStructureTree(entry.structure ?? []), "```");
+				} else frag.push("", "_—_");
+				fragments.structure = frag;
 			}
 		}
 		{
 			const w = want("examples", entry.examples.length > 0);
 			if (w !== "skip") {
-				lines.push("", `**$(book) Example${entry.examples.length > 1 ? "s" : ""}**`);
+				const frag = ["", `**$(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\`\`\``);
+					frag.push("", ex.startsWith("```") ? ex : `\`\`\`${ex.includes("<") ? "html" : "css"}\n${ex}\n\`\`\``);
 				}
-				else lines.push("", "_—_");
+				else frag.push("", "_—_");
+				fragments.examples = frag;
 			}
 		}
+		for (const key of sectionOrder ?? HOVER_SECTION_KEYS) {
+			const frag = fragments[key];
+			if (frag) lines.push(...frag);
+		}
 		return { contents: lines.join("\n") };
 	},
 	definition(base, index) {
@@ -478,7 +605,7 @@ const customProperty = {
 		const found = findProperty(index, name);
 		if (!found) return void 0;
 		const p = found.record.entry.cssPropertiesDeclared[found.index];
-		const lines = [`\`${p.name}\`${p.syntax ? ` — \`${p.syntax}\`` : ""}`];
+		const lines = [`\`${p.name}\`${p.syntax ? ` — ${linkedSyntax(p.syntax)}` : ""}`];
 		if (p.defaultValue) lines.push("", `Default: \`${p.defaultValue}\``);
 		if (p.description) lines.push("", p.description);
 		return { contents: lines.join("\n") };
@@ -510,90 +637,6 @@ const func = {
 	}
 };
 //#endregion
-//#region src/types.ts
-/**
-* The default rule severities. `unknown-modifier` defaults to `warn` — safe under the BEM default's
-* strong `--` signal; lower it to `off` for weak-signal conventions (bare/OOCSS) where every chained
-* class is a candidate. `unknown-custom-property` stays `off` (it needs an opt-in `propertyPrefix`).
-*/
-const DEFAULT_RULE_SEVERITIES = {
-	"missing-summary": "warn",
-	"undocumented-modifier": "warn",
-	"deprecated-requires-canonical": "warn",
-	"name-not-in-css": "warn",
-	"unknown-modifier": "warn",
-	"deprecated-modifier": "warn",
-	"unknown-state": "warn",
-	"unknown-part": "warn",
-	"undocumented-part": "warn",
-	"undocumented-css-part": "warn",
-	"component-name-case": "warn",
-	"part-name-case": "warn",
-	"structure-unknown-selector": "warn",
-	"invalid-default-value": "warn",
-	"invalid-property-value": "warn",
-	"invalid-fallback-value": "warn",
-	"unknown-custom-property": "off",
-	"cssdoc-directive": "warn"
-};
-/**
-* Merge per-rule overrides over {@link DEFAULT_RULE_SEVERITIES}. A `boolean` override is accepted for
-* back-compat: `false` → `off`, `true` → the rule's default.
-*/
-function resolveRuleSeverities(overrides) {
-	const resolved = { ...DEFAULT_RULE_SEVERITIES };
-	if (!overrides) return resolved;
-	for (const [rule, value] of Object.entries(overrides)) {
-		if (value === void 0) continue;
-		if (typeof value === "boolean") resolved[rule] = value ? DEFAULT_RULE_SEVERITIES[rule] : "off";
-		else resolved[rule] = value;
-	}
-	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,
-	camelCase: /^[a-z][A-Za-z0-9]*$/u,
-	lowercase: /^[a-z][a-z0-9-]*$/u
-};
-/** Compile one {@link NameCase} to a regex: a preset, else the string as a custom pattern. */
-function compileNameCase(spec) {
-	if (!spec) return void 0;
-	if (spec in NAME_CASE_PRESETS) return NAME_CASE_PRESETS[spec];
-	try {
-		return new RegExp(spec, "u");
-	} catch {
-		return;
-	}
-}
-/** Compile {@link NamingRules} to regexes once, for the record/part name-case checks. */
-function resolveNaming(naming) {
-	return {
-		component: compileNameCase(naming?.component),
-		part: compileNameCase(naming?.part)
-	};
-}
-//#endregion
 //#region src/directives.ts
 const DIRECTIVE_RE = /\/\*\s*cssdoc-(disable-next-line|disable-line|disable|enable|expect-error)\b([^*]*?)\*\//gu;
 const lineAt = (source, index) => {
@@ -606,10 +649,13 @@ function parseDirectives(source) {
 	const out = [];
 	for (const m of source.matchAll(DIRECTIVE_RE)) {
 		const at = m.index ?? 0;
-		const rest = m[2].trim();
+		const reasonAt = m[2].search(/\s-\s/u);
+		const rulesPart = (reasonAt === -1 ? m[2] : m[2].slice(0, reasonAt)).trim();
+		const reason = reasonAt === -1 ? void 0 : m[2].slice(reasonAt).replace(/^\s-\s/u, "").trim();
 		out.push({
 			kind: m[1],
-			rules: rest ? rest.split(/[\s,]+/u).filter(Boolean) : null,
+			rules: rulesPart ? rulesPart.split(/[\s,]+/u).filter(Boolean) : null,
+			reason: reason || void 0,
 			startLine: lineAt(source, at),
 			endLine: lineAt(source, at + m[0].length - 1)
 		});
@@ -758,8 +804,8 @@ function completeFunctions(index) {
 	return func.completions(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);
+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) {
@@ -782,4 +828,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, 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, linkSyntax, lintModel, matchesSyntax, mdnUrlForType, modifier, parseDirectives, part, partUsage, record, resolveNaming, resolveRuleSeverities, stateUsage };

package/package.json

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