@cssdoc/core 0.5.0 → 0.5.2

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { A as CssState, B as ModifierMatcher, C as CssPart, D as CssReleaseStage, E as CssRelated, F as DEFAULT_STATE_PSEUDO_CLASSES, I as MODIFIER_PRESETS, L as ModifierConvention, M as ParseOptions, N as StructureNode, O as CssSlot, P as DEFAULT_MODIFIER_CONVENTION, R as ModifierConventionInput, S as CssParse, T as CssRecordKind, V as resolveModifierConvention, _ as CssCondition, a as DocModifier, b as CssLayer, c as parseDocComment, d as stripCommentFraming, f as CssDocConfiguration, g as CssAnimation, h as CssDocTagDefinitionOptions, i as DocCssProperty, j as CssTokenConsumed, k as CssSource, l as parseStructure, m as CssDocTagDefinition, n as toMermaid, o as ParsedDoc, p as CssDocSyntaxKind, r as DocCondition, s as RECORD_TAGS, t as toJson, u as recordNameOf, v as CssDocEntry, w as CssPropertyDeclared, x as CssModifier, y as CssFunction, z as ModifierHit } from "./lite-BJ1h869i.mjs";
+import { A as CssState, B as ModifierMatcher, C as CssPart, D as CssReleaseStage, E as CssRelated, F as DEFAULT_STATE_PSEUDO_CLASSES, I as MODIFIER_PRESETS, L as ModifierConvention, M as ParseOptions, N as StructureNode, O as CssSlot, P as DEFAULT_MODIFIER_CONVENTION, R as ModifierConventionInput, S as CssParse, T as CssRecordKind, V as resolveModifierConvention, _ as CssCondition, a as DocModifier, b as CssLayer, c as parseDocComment, d as stripCommentFraming, f as CssDocConfiguration, g as CssAnimation, h as CssDocTagDefinitionOptions, i as DocCssProperty, j as CssTokenConsumed, k as CssSource, l as parseStructure, m as CssDocTagDefinition, n as toMermaid, o as ParsedDoc, p as CssDocSyntaxKind, r as DocCondition, s as RECORD_TAGS, t as toJson, u as recordNameOf, v as CssDocEntry, w as CssPropertyDeclared, x as CssModifier, y as CssFunction, z as ModifierHit } from "./lite-DtKEwRkS.mjs";
 
 //#region src/parse.d.ts
 /**

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import { a as parseStructure, c as CssDocConfiguration, d as DEFAULT_STATE_PSEUDO_CLASSES, f as MODIFIER_PRESETS, i as parseDocComment, l as CssDocTagDefinition, m as resolveModifierConvention, n as toMermaid, o as recordNameOf, p as ModifierMatcher, r as RECORD_TAGS, s as stripCommentFraming, t as toJson, u as DEFAULT_MODIFIER_CONVENTION } from "./lite-CNHsXy8P.mjs";
+import { a as parseStructure, c as CssDocConfiguration, d as DEFAULT_STATE_PSEUDO_CLASSES, f as MODIFIER_PRESETS, i as parseDocComment, l as CssDocTagDefinition, m as resolveModifierConvention, n as toMermaid, o as recordNameOf, p as ModifierMatcher, r as RECORD_TAGS, s as stripCommentFraming, t as toJson, u as DEFAULT_MODIFIER_CONVENTION } from "./lite-HEYG01Eo.mjs";
 import postcss from "postcss";
 //#region src/parse.ts
 /**

package/dist/{lite-BJ1h869i.d.mts → lite-DtKEwRkS.d.mts}

@@ -715,26 +715,48 @@ declare function recordNameOf(commentText: string, configuration?: CssDocConfigu
 declare function parseStructure(raw: string, parse?: CssParse): StructureNode[];
 //#endregion
 //#region src/mermaid.d.ts
+/** Resolve a bare class name (no leading dot) to the sibling component it is the base class of. */
+type ResolveStructureComponent = (className: string) => {
+  name: string;
+  href?: string;
+} | undefined;
+/** Options for {@link toMermaid}. */
+interface MermaidOptions {
+  /** Flowchart orientation (default `"TD"`, top-down). */
+  direction?: "TD" | "LR";
+  /**
+   * The current record's base class, no leading dot (e.g. `alert`). Its top-level node renders as the
+   * diagram root; a descendant that references the same class stays a part, never a sibling component.
+   */
+  self?: string;
+  /**
+   * Classify a bare class as a *sibling component* — a child that is itself a documented record. Such
+   * nodes get the stadium shape, are labelled by component name, and (when an `href` is returned) link
+   * to that component's page. Absent → every non-slot, non-root node is a plain part.
+   */
+  resolveComponent?: ResolveStructureComponent;
+}
 /**
  * Convert a structure tree to a Mermaid `flowchart` definition. Each node gets a stable id (`n0`, `n1`,
- * …) in depth-first order; edges connect a parent to each child.
+ * …) in depth-first order; a parent connects to each child with an edge carrying the child's
+ * cardinality. Nodes are shaped + classed by kind ({@link classify}); sibling components with an href
+ * get a `click` link.
  *
  * @param roots - Top-level {@link StructureNode}s (an authored `@structure`).
- * @param options - `direction` sets the flowchart orientation (default `TD`, top-down).
+ * @param options - {@link MermaidOptions}.
  * @returns Mermaid source, or an empty string when there are no nodes.
  *
  * @example
  * ```ts
- * toMermaid([{ selector: ".tabs", children: [{ selector: ".panel", children: [] }] }]);
+ * toMermaid([{ selector: ".tabs", children: [{ selector: ".panel", cardinality: "many", children: [] }] }]);
  * // flowchart TD
- * //   n0[".tabs"]
- * //   n1[".panel"]
- * //   n0 --> n1
+ * //   n0[".tabs"]:::cssdoc-root
+ * //   n1(".panel"):::cssdoc-part
+ * //   n0 -->|0..n| n1
+ * //   classDef cssdoc-root …
  * ```
  */
-declare function toMermaid(roots: StructureNode[], options?: {
-  direction?: "TD" | "LR";
-}): string;
+declare function toMermaid(roots: StructureNode[], options?: MermaidOptions): string;
 //#endregion
 //#region src/lite.d.ts
 /**

package/dist/{lite-CNHsXy8P.mjs → lite-HEYG01Eo.mjs}

@@ -819,50 +819,103 @@ function parseStructure(raw, parse) {
 }
 //#endregion
 //#region src/mermaid.ts
-const CARDINALITY_LABEL = {
-	optional: " (optional)",
-	many: " (0..n)",
-	"one-or-more": " (1..n)"
-};
+/** Match a `slot` / `slot[name="x"]` node (a light-DOM content region → the default/named slot). */
 const SLOT_NODE = /^slot(?:\[\s*name\s*=\s*["']?([\w-]+)["']?\s*\])?$/u;
-/**
-* A node's label: its selector (a `slot` node shown as ‹content›) plus a cardinality suffix, quoted for a
-* Mermaid node body (quoting allows dots, brackets, and spaces).
-*/
-const label = (node) => {
-	const slot = node.selector.match(SLOT_NODE);
-	return `"${`${slot ? slot[1] ? `‹content: ${slot[1]}›` : "‹content›" : node.selector}${node.cardinality ? CARDINALITY_LABEL[node.cardinality] : ""}`.replace(/"/gu, """)}"`;
+/** The child edge for each cardinality (dashed + `0..1` for optional; a count label for the ranges). */
+const EDGE = {
+	required: "-->",
+	optional: "-.->|0..1|",
+	many: "-->|0..n|",
+	"one-or-more": "-->|1..n|"
 };
+/** Wrap a node's label in the shape mermaid draws for its class. */
+const SHAPE = {
+	"cssdoc-root": (id, l) => `${id}["${l}"]`,
+	"cssdoc-part": (id, l) => `${id}("${l}")`,
+	"cssdoc-slot": (id, l) => `${id}[/"${l}"/]`,
+	"cssdoc-component": (id, l) => `${id}(["${l}"])`
+};
+/** The classDef palette — a readable standalone default; hosts restyle by class name. */
+const CLASS_DEFS = [
+	"classDef cssdoc-root fill:#eef2ff,stroke:#6366f1,color:#1e1b4b;",
+	"classDef cssdoc-part fill:#f8fafc,stroke:#94a3b8,color:#0f172a;",
+	"classDef cssdoc-slot fill:#f0fdf4,stroke:#4ade80,color:#14532d;",
+	"classDef cssdoc-component fill:#fff7ed,stroke:#fb923c,color:#7c2d12;"
+];
+/** The leading bare class of a compound selector, e.g. `.item.-selected` → `item`. */
+const firstClass = (selector) => selector.match(/\.([\w-]+)/u)?.[1];
+/** Escape a label for a quoted Mermaid node body. */
+const esc = (text) => text.replace(/"/gu, """);
+/** Classify one node: slot → root → sibling component → plain part. */
+function classify(node, isRoot, options) {
+	const slot = node.selector.match(SLOT_NODE);
+	if (slot) return {
+		klass: "cssdoc-slot",
+		label: slot[1] ? `‹content: ${slot[1]}›` : "‹content›"
+	};
+	if (isRoot) return {
+		klass: "cssdoc-root",
+		label: node.selector
+	};
+	const primary = firstClass(node.selector);
+	if (primary && primary !== options.self) {
+		const component = options.resolveComponent?.(primary);
+		if (component) return {
+			klass: "cssdoc-component",
+			label: component.name,
+			href: component.href
+		};
+	}
+	return {
+		klass: "cssdoc-part",
+		label: node.selector
+	};
+}
 /**
 * Convert a structure tree to a Mermaid `flowchart` definition. Each node gets a stable id (`n0`, `n1`,
-* …) in depth-first order; edges connect a parent to each child.
+* …) in depth-first order; a parent connects to each child with an edge carrying the child's
+* cardinality. Nodes are shaped + classed by kind ({@link classify}); sibling components with an href
+* get a `click` link.
 *
 * @param roots - Top-level {@link StructureNode}s (an authored `@structure`).
-* @param options - `direction` sets the flowchart orientation (default `TD`, top-down).
+* @param options - {@link MermaidOptions}.
 * @returns Mermaid source, or an empty string when there are no nodes.
 *
 * @example
 * ```ts
-* toMermaid([{ selector: ".tabs", children: [{ selector: ".panel", children: [] }] }]);
+* toMermaid([{ selector: ".tabs", children: [{ selector: ".panel", cardinality: "many", children: [] }] }]);
 * // flowchart TD
-* //   n0[".tabs"]
-* //   n1[".panel"]
-* //   n0 --> n1
+* //   n0[".tabs"]:::cssdoc-root
+* //   n1(".panel"):::cssdoc-part
+* //   n0 -->|0..n| n1
+* //   classDef cssdoc-root …
 * ```
 */
 function toMermaid(roots, options = {}) {
 	if (!roots.length) return "";
-	const lines = [`flowchart ${options.direction ?? "TD"}`];
+	const nodes = [];
 	const edges = [];
+	const links = [];
 	let counter = 0;
-	const walk = (node) => {
+	const walk = (node, isRoot) => {
 		const id = `n${counter++}`;
-		lines.push(`  ${id}[${label(node)}]`);
-		for (const child of node.children) edges.push(`  ${id} --> ${walk(child)}`);
+		const { klass, label, href } = classify(node, isRoot, options);
+		nodes.push(`  ${SHAPE[klass](id, esc(label))}:::${klass}`);
+		if (href) links.push(`  click ${id} "${href}"`);
+		for (const child of node.children) {
+			const childId = walk(child, false);
+			edges.push(`  ${id} ${EDGE[child.cardinality ?? "required"]} ${childId}`);
+		}
 		return id;
 	};
-	for (const root of roots) walk(root);
-	return [...lines, ...edges].join("\n");
+	for (const root of roots) walk(root, true);
+	return [
+		`flowchart ${options.direction ?? "TD"}`,
+		...nodes,
+		...edges,
+		...links,
+		...CLASS_DEFS.map((d) => `  ${d}`)
+	].join("\n");
 }
 //#endregion
 //#region src/lite.ts

package/dist/lite.d.mts

@@ -1,2 +1,2 @@
-import { A as CssState, B as ModifierMatcher, C as CssPart, D as CssReleaseStage, E as CssRelated, F as DEFAULT_STATE_PSEUDO_CLASSES, I as MODIFIER_PRESETS, L as ModifierConvention, M as ParseOptions, N as StructureNode, O as CssSlot, P as DEFAULT_MODIFIER_CONVENTION, R as ModifierConventionInput, S as CssParse, T as CssRecordKind, V as resolveModifierConvention, _ as CssCondition, a as DocModifier, b as CssLayer, c as parseDocComment, d as stripCommentFraming, f as CssDocConfiguration, g as CssAnimation, h as CssDocTagDefinitionOptions, i as DocCssProperty, j as CssTokenConsumed, k as CssSource, l as parseStructure, m as CssDocTagDefinition, n as toMermaid, o as ParsedDoc, p as CssDocSyntaxKind, r as DocCondition, s as RECORD_TAGS, t as toJson, u as recordNameOf, v as CssDocEntry, w as CssPropertyDeclared, x as CssModifier, y as CssFunction, z as ModifierHit } from "./lite-BJ1h869i.mjs";
+import { A as CssState, B as ModifierMatcher, C as CssPart, D as CssReleaseStage, E as CssRelated, F as DEFAULT_STATE_PSEUDO_CLASSES, I as MODIFIER_PRESETS, L as ModifierConvention, M as ParseOptions, N as StructureNode, O as CssSlot, P as DEFAULT_MODIFIER_CONVENTION, R as ModifierConventionInput, S as CssParse, T as CssRecordKind, V as resolveModifierConvention, _ as CssCondition, a as DocModifier, b as CssLayer, c as parseDocComment, d as stripCommentFraming, f as CssDocConfiguration, g as CssAnimation, h as CssDocTagDefinitionOptions, i as DocCssProperty, j as CssTokenConsumed, k as CssSource, l as parseStructure, m as CssDocTagDefinition, n as toMermaid, o as ParsedDoc, p as CssDocSyntaxKind, r as DocCondition, s as RECORD_TAGS, t as toJson, u as recordNameOf, v as CssDocEntry, w as CssPropertyDeclared, x as CssModifier, y as CssFunction, z as ModifierHit } from "./lite-DtKEwRkS.mjs";
 export { type CssAnimation, type CssCondition, CssDocConfiguration, type CssDocEntry, type CssDocSyntaxKind, CssDocTagDefinition, type CssDocTagDefinitionOptions, type CssFunction, type CssLayer, type CssModifier, type CssParse, type CssPart, type CssPropertyDeclared, type CssRecordKind, type CssRelated, type CssReleaseStage, type CssSlot, type CssSource, type CssState, type CssTokenConsumed, DEFAULT_MODIFIER_CONVENTION, DEFAULT_STATE_PSEUDO_CLASSES, type DocCondition, type DocCssProperty, type DocModifier, MODIFIER_PRESETS, type ModifierConvention, type ModifierConventionInput, type ModifierHit, ModifierMatcher, type ParseOptions, type ParsedDoc, RECORD_TAGS, type StructureNode, parseDocComment, parseStructure, recordNameOf, resolveModifierConvention, stripCommentFraming, toJson, toMermaid };

package/dist/lite.mjs

@@ -1,2 +1,2 @@
-import { a as parseStructure, c as CssDocConfiguration, d as DEFAULT_STATE_PSEUDO_CLASSES, f as MODIFIER_PRESETS, i as parseDocComment, l as CssDocTagDefinition, m as resolveModifierConvention, n as toMermaid, o as recordNameOf, p as ModifierMatcher, r as RECORD_TAGS, s as stripCommentFraming, t as toJson, u as DEFAULT_MODIFIER_CONVENTION } from "./lite-CNHsXy8P.mjs";
+import { a as parseStructure, c as CssDocConfiguration, d as DEFAULT_STATE_PSEUDO_CLASSES, f as MODIFIER_PRESETS, i as parseDocComment, l as CssDocTagDefinition, m as resolveModifierConvention, n as toMermaid, o as recordNameOf, p as ModifierMatcher, r as RECORD_TAGS, s as stripCommentFraming, t as toJson, u as DEFAULT_MODIFIER_CONVENTION } from "./lite-HEYG01Eo.mjs";
 export { CssDocConfiguration, CssDocTagDefinition, DEFAULT_MODIFIER_CONVENTION, DEFAULT_STATE_PSEUDO_CLASSES, MODIFIER_PRESETS, ModifierMatcher, RECORD_TAGS, parseDocComment, parseStructure, recordNameOf, resolveModifierConvention, stripCommentFraming, toJson, toMermaid };

package/package.json

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