@cssdoc/core 0.3.2 → 0.4.0

package/README.md

@@ -83,12 +83,16 @@ interface CssDocEntry {
     deprecated?: { canonical: string };
   }[];
   parts: { name: string; description?: string }[];
-  cssPropertiesConsumed: string[];
+  cssPropertiesConsumed: { name: string; description?: string }[];
   cssPropertiesDeclared: { name: string; syntax?: string; description?: string }[];
   examples: string[];
   demo?: string;
   deprecated?: string;
   see: string[];
+  usage?: string;
+  compat: string[];
+  related: { name: string; description?: string }[];
+  source?: { file?: string; line?: number; column?: number };
 }
 ```
 

package/dist/index.d.mts

@@ -423,6 +423,34 @@ interface StructureNode {
   /** Child nodes (rules nested one brace level deeper). */
   children: StructureNode[];
 }
+/**
+ * A design token the component consumes via `var(--*)`. The set is derived from the CSS; an authored
+ * `@tokens` tag annotates one with prose (and may add a token not literally found via `var()`). Type and
+ * resolved value are not modeled here — an emitter resolves them via its own token source (e.g. a
+ * `resolveToken` hook).
+ */
+interface CssTokenConsumed {
+  /** The custom-property name, e.g. `--color-primary`. */
+  name: string;
+  /** Prose from an `@tokens` doc tag, when authored. */
+  description?: string;
+}
+/** A related component cross-reference (`@related`). */
+interface CssRelated {
+  /** The related record's name, e.g. `card`. */
+  name: string;
+  /** Prose from the `@related` tag, when authored. */
+  description?: string;
+}
+/** Where a record was authored, for source links. Positions are 1-based, matching PostCSS. */
+interface CssSource {
+  /** The file the record was parsed from, when {@link ParseOptions.fileName} was supplied. */
+  file?: string;
+  /** The 1-based line of the record's opening doc comment. */
+  line?: number;
+  /** The 1-based column of the record's opening doc comment. */
+  column?: number;
+}
 /** One documented CSS record: its base class plus everything derived from the CSS + doc comments. */
 interface CssDocEntry {
   /** The record name from `@component`/`@utility`/`@rule`/`@declaration`/`@name`, e.g. `button`. */
@@ -455,8 +483,12 @@ interface CssDocEntry {
   states: CssState[];
   /** Named slots the component shell exposes, from `@slot`. */
   slots: CssSlot[];
-  /** Every `--*` custom property referenced via `var(...)` inside this component's rules. */
-  cssPropertiesConsumed: string[];
+  /**
+   * Design tokens this component consumes: every `--*` custom property referenced via `var(...)` inside
+   * its rules, each annotated with `@tokens` prose where authored (and including any `@tokens`-declared
+   * token not literally found via `var()`).
+   */
+  cssPropertiesConsumed: CssTokenConsumed[];
   /** Custom properties this component declares (`@property`) or documents (`@cssproperty`). */
   cssPropertiesDeclared: CssPropertyDeclared[];
   /** CSS custom functions (`@function`) this component defines. */
@@ -479,6 +511,14 @@ interface CssDocEntry {
   deprecated?: string;
   /** `@see <ref>` cross-references. */
   see: string[];
+  /** Usage prose from `@usage` — how to include the stylesheet / use the component. */
+  usage?: string;
+  /** Browser-support / feature-compatibility notes from `@compat`. */
+  compat: string[];
+  /** Related components from `@related`. */
+  related: CssRelated[];
+  /** Where the record was authored, when position info is available (for source links). */
+  source?: CssSource;
   /**
    * Content of registered custom (block) tags, keyed by tag name without its `@`. Populated only for
    * tags added via configuration; unregistered unknown tags are ignored. Absent when none were found.
@@ -512,11 +552,16 @@ interface ParseOptions {
    * parser (e.g. `postcss-scss`/`postcss-less` via `@cssdoc/dialects`) to document `.scss`/`.less`.
    */
   parse?: CssParse;
+  /**
+   * The source file name to record on each entry's {@link CssSource}, enabling source links. The parser
+   * always records line/column; supply this to also record the file.
+   */
+  fileName?: string;
 }
 //#endregion
 //#region src/parse.d.ts
 /**
- * Parse a CSS string into a documentation model. Records are delimited by doc comments carrying a
+ * Parse a CSS string into a documentation model. Records are delimited by `/**` doc comments carrying a
  * record tag (`@component`/`@name` by default; override via {@link ParseOptions.isRecordBoundary});
  * everything from one boundary comment to the next belongs to that record.
  *
@@ -594,6 +639,8 @@ interface ParsedDoc {
   modifiers: Map<string, DocModifier>;
   /** `@part` descriptions, keyed by the class part name without its dot (e.g. `item`). */
   parts: Map<string, string>;
+  /** `@tokens` descriptions, keyed by custom-property name (e.g. `--color-primary`). */
+  tokens: Map<string, string>;
   /** `@csspart` descriptions (shadow-DOM `::part()`), keyed by the bare part name (e.g. `header`). */
   cssParts: Map<string, string>;
   /** `@cssproperty` declarations. */
@@ -622,6 +669,12 @@ interface ParsedDoc {
   demo?: string;
   /** `@see <ref>` entries. */
   see: string[];
+  /** `@usage` prose — how to include the stylesheet / use the component. */
+  usage?: string;
+  /** `@compat` browser-support / feature-compatibility notes. */
+  compat: string[];
+  /** `@related` component cross-references. */
+  related: CssRelated[];
   /** Content of registered custom (block) tags, keyed by tag name without its `@`. */
   customBlocks: Map<string, string[]>;
 }

package/dist/index.mjs

@@ -540,6 +540,7 @@ function parseDocComment(raw, configuration = new CssDocConfiguration()) {
 	const doc = {
 		modifiers: /* @__PURE__ */ new Map(),
 		parts: /* @__PURE__ */ new Map(),
+		tokens: /* @__PURE__ */ new Map(),
 		cssParts: /* @__PURE__ */ new Map(),
 		cssProperties: [],
 		cssStates: /* @__PURE__ */ new Map(),
@@ -550,6 +551,8 @@ function parseDocComment(raw, configuration = new CssDocConfiguration()) {
 		conditions: [],
 		examples: [],
 		see: [],
+		compat: [],
+		related: [],
 		customBlocks: /* @__PURE__ */ new Map()
 	};
 	const blocks = [];
@@ -616,6 +619,11 @@ function applyBlockTag(doc, canonical, tagName, rest) {
 			doc.parts.set(head.replace(/^\./u, ""), description ?? "");
 			break;
 		}
+		case "tokens": {
+			const { head, description } = splitDesc(rest);
+			doc.tokens.set(head, description ?? "");
+			break;
+		}
 		case "csspart": {
 			const { head, description } = splitDesc(rest);
 			doc.cssParts.set(head.replace(/^\./u, ""), description ?? "");
@@ -684,6 +692,20 @@ function applyBlockTag(doc, canonical, tagName, rest) {
 		case "see":
 			doc.see.push(rest);
 			break;
+		case "usage":
+			doc.usage = rest.trim();
+			break;
+		case "compat":
+			doc.compat.push(rest.trim());
+			break;
+		case "related": {
+			const { head, description } = splitDesc(rest);
+			doc.related.push({
+				name: head.replace(/^\./u, ""),
+				description
+			});
+			break;
+		}
 		default: {
 			const list = doc.customBlocks.get(tagName) ?? [];
 			list.push(rest);
@@ -907,7 +929,7 @@ function collect(nodes, acc, matcher, baseNoDot, prefixNoDot, inScope) {
 }
 const byName = (a, b) => a.name.localeCompare(b.name);
 /** Build one entry from its record name, doc comment, and nodes. */
-function buildEntry(name, doc, nodes, matcher) {
+function buildEntry(name, doc, nodes, matcher, source) {
 	let className = doc.className ?? "";
 	if (!className) {
 		const bare = nodes.filter((n) => n.type === "rule").map((n) => n.selector.trim()).filter((sel) => /^\.[a-z][\w-]*$/u.test(sel));
@@ -1025,6 +1047,16 @@ function buildEntry(name, doc, nodes, matcher) {
 		});
 	}
 	const modifiers = [...acc.modifiers.values()].sort((a, b) => a.prop.localeCompare(b.prop) || (a.value ?? "").localeCompare(b.value ?? ""));
+	const consumedTokens = /* @__PURE__ */ new Map();
+	for (const tokenName of acc.consumed) consumedTokens.set(tokenName, { name: tokenName });
+	for (const [tokenName, description] of doc.tokens) {
+		const existing = consumedTokens.get(tokenName);
+		if (existing) existing.description = description || existing.description;
+		else consumedTokens.set(tokenName, {
+			name: tokenName,
+			description: description || void 0
+		});
+	}
 	return {
 		name,
 		kind: doc.kind ?? "component",
@@ -1047,7 +1079,7 @@ function buildEntry(name, doc, nodes, matcher) {
 			name: slotName,
 			description: description || void 0
 		})).sort(byName),
-		cssPropertiesConsumed: [...acc.consumed].sort(),
+		cssPropertiesConsumed: [...consumedTokens.values()].sort(byName),
 		cssPropertiesDeclared: [...acc.declared.values()].sort(byName),
 		functions: [...acc.functions.values()].sort(byName),
 		animations: [...acc.animations.values()].sort(byName),
@@ -1059,11 +1091,26 @@ function buildEntry(name, doc, nodes, matcher) {
 		demo: doc.demo,
 		deprecated: doc.deprecated,
 		see: doc.see,
+		usage: doc.usage,
+		compat: doc.compat,
+		related: doc.related,
+		...source ? { source } : {},
 		...doc.customBlocks.size > 0 ? { customBlocks: Object.fromEntries(doc.customBlocks) } : {}
 	};
 }
 /**
-* Parse a CSS string into a documentation model. Records are delimited by doc comments carrying a
+* A cssdoc record is opened only by a JSDoc-style doc comment (its opener is `/**`) — never a plain
+* block comment. PostCSS doesn't distinguish the two, so an ordinary comment that merely mentions
+* `@component` (a TODO, a banner) would otherwise mint a phantom, summary-less record. We check the raw
+* source at the comment's offset for the `/**` opener, falling back to the leftover `*` that a `/**`
+* leaves at the start of the comment body when no offset is available.
+*/
+function isDocComment(node, source) {
+	const offset = node.source?.start?.offset;
+	return offset === void 0 ? node.text.startsWith("*") : source.startsWith("/**", offset);
+}
+/**
+* Parse a CSS string into a documentation model. Records are delimited by `/**` doc comments carrying a
 * record tag (`@component`/`@name` by default; override via {@link ParseOptions.isRecordBoundary});
 * everything from one boundary comment to the next belongs to that record.
 *
@@ -1087,13 +1134,20 @@ function parseCssDocs(css, options = {}) {
 	const records = [];
 	let current = null;
 	for (const node of root.nodes) {
-		if (node.type === "comment") {
+		if (node.type === "comment" && isDocComment(node, css)) {
 			const name = boundary(node.text);
 			if (name) {
+				const start = node.source?.start;
+				const source = options.fileName || start ? {
+					file: options.fileName,
+					line: start?.line,
+					column: start?.column
+				} : void 0;
 				current = {
 					name,
 					doc: parseDocComment(node.text, configuration),
-					nodes: []
+					nodes: [],
+					source
 				};
 				records.push(current);
 				continue;
@@ -1101,7 +1155,7 @@ function parseCssDocs(css, options = {}) {
 		}
 		if (current) current.nodes.push(node);
 	}
-	return records.map((r) => buildEntry(r.name, r.doc, r.nodes, matcher));
+	return records.map((r) => buildEntry(r.name, r.doc, r.nodes, matcher, r.source));
 }
 //#endregion
 //#region src/mermaid.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cssdoc/core",
-  "version": "0.3.2",
+  "version": "0.4.0",
   "description": "A generic CSS documentation extractor: parse doc-comments + the CSS AST into a serializable model (TSDoc, for CSS).",
   "keywords": [
     "css",
@@ -30,8 +30,8 @@
     "access": "public"
   },
   "dependencies": {
-    "postcss": "^8.5.16",
-    "@cssdoc/spec": "0.3.2"
+    "postcss": "^8.5.17",
+    "@cssdoc/spec": "0.4.0"
   },
   "devDependencies": {
     "@types/node": "^24.13.3",