@cssdoc/core 0.1.0

package/dist/index.mjs

@@ -0,0 +1,1004 @@
+import postcss from "postcss";
+//#region src/configuration.ts
+const TAG_NAME_RE = /^@?[a-zA-Z][a-zA-Z0-9-]*$/u;
+/** One tag in the vocabulary: its name, kind, and how it may be used. */
+var CssDocTagDefinition = class {
+	/** The normalized tag name, always with a leading `@` (e.g. `@modifier`). */
+	tagName;
+	/** The tag name without its leading `@` (e.g. `modifier`). */
+	tagNameWithoutAt;
+	syntaxKind;
+	allowMultiple;
+	recordKind;
+	/** The canonical tag name (without `@`) this aliases, if any; otherwise its own name. */
+	aliasFor;
+	constructor(options) {
+		const raw = options.tagName.trim();
+		if (!TAG_NAME_RE.test(raw)) throw new Error(`Invalid CSS-doc tag name: ${JSON.stringify(options.tagName)}`);
+		this.tagNameWithoutAt = raw.replace(/^@/u, "");
+		this.tagName = `@${this.tagNameWithoutAt}`;
+		this.syntaxKind = options.syntaxKind;
+		this.allowMultiple = options.allowMultiple ?? false;
+		this.recordKind = options.recordKind;
+		this.aliasFor = options.aliasFor;
+	}
+	/** The tag this definition resolves to when handled — its alias target, or itself. */
+	get canonicalName() {
+		return this.aliasFor ?? this.tagNameWithoutAt;
+	}
+};
+function def(options) {
+	return new CssDocTagDefinition(options);
+}
+/**
+* A parse configuration: the set of tag definitions plus which are supported. Construct one to get the
+* full standard vocabulary, then add custom tags or disable standard ones.
+*
+* @example
+* ```ts
+* import { CssDocConfiguration, CssDocTagDefinition, parseCssDocs } from "@cssdoc/core";
+*
+* const config = new CssDocConfiguration();
+* config.addTagDefinition(new CssDocTagDefinition({ tagName: "@token", syntaxKind: "block" }), true);
+* const model = parseCssDocs(css, { configuration: config });
+* ```
+*/
+var CssDocConfiguration = class CssDocConfiguration {
+	_tagDefinitions = [];
+	_byName = /* @__PURE__ */ new Map();
+	_supported = /* @__PURE__ */ new Set();
+	constructor() {
+		this.addTagDefinitions(CssDocConfiguration.standardTags(), true);
+	}
+	/** Every registered tag definition, in registration order. */
+	get tagDefinitions() {
+		return this._tagDefinitions;
+	}
+	/** Only the tag definitions that are currently supported. */
+	get supportedTagDefinitions() {
+		return this._tagDefinitions.filter((d) => this._supported.has(d));
+	}
+	/**
+	* Register a tag definition. Re-registering a tag name replaces the earlier definition.
+	*
+	* @param definition - The tag to add.
+	* @param supported - Whether it is supported (defaults to `true`).
+	*/
+	addTagDefinition(definition, supported = true) {
+		const existing = this._byName.get(definition.tagNameWithoutAt);
+		if (existing) {
+			this._tagDefinitions.splice(this._tagDefinitions.indexOf(existing), 1);
+			this._supported.delete(existing);
+		}
+		this._tagDefinitions.push(definition);
+		this._byName.set(definition.tagNameWithoutAt, definition);
+		if (supported) this._supported.add(definition);
+	}
+	/** Register several tag definitions. */
+	addTagDefinitions(definitions, supported = true) {
+		for (const definition of definitions) this.addTagDefinition(definition, supported);
+	}
+	/** Look up a tag definition by name (with or without a leading `@`). */
+	tryGetTagDefinition(tagName) {
+		return this._byName.get(tagName.replace(/^@/u, ""));
+	}
+	/** Whether a tag definition is supported. */
+	isTagSupported(definition) {
+		return this._supported.has(definition);
+	}
+	/** Enable or disable support for a tag. */
+	setSupportForTag(definition, supported) {
+		if (supported) this._supported.add(definition);
+		else this._supported.delete(definition);
+	}
+	/** Enable or disable support for several tags. */
+	setSupportForTags(definitions, supported) {
+		for (const definition of definitions) this.setSupportForTag(definition, supported);
+	}
+	/** Disable support for every standard tag (custom tags added later remain supported). */
+	setNoStandardTags() {
+		this.setSupportForTags(CssDocConfiguration.standardTagNames.map((n) => this._byName.get(n)), false);
+	}
+	/** The names (without `@`) of every standard tag. */
+	static standardTagNames = [
+		"component",
+		"name",
+		"utility",
+		"rule",
+		"declaration",
+		"class",
+		"summary",
+		"remarks",
+		"privateRemarks",
+		"deprecated",
+		"example",
+		"see",
+		"since",
+		"group",
+		"category",
+		"defaultValue",
+		"modifier",
+		"part",
+		"csspart",
+		"cssproperty",
+		"property",
+		"cssstate",
+		"slot",
+		"function",
+		"keyframes",
+		"animation",
+		"layer",
+		"container",
+		"supports",
+		"media",
+		"responsive",
+		"a11y",
+		"accessibility",
+		"structure",
+		"demo",
+		"alpha",
+		"beta",
+		"experimental",
+		"internal",
+		"public",
+		"link",
+		"inheritDoc",
+		"label"
+	];
+	/** A fresh set of the standard tag definitions (new instances on each call). */
+	static standardTags() {
+		return [
+			def({
+				tagName: "component",
+				syntaxKind: "record",
+				recordKind: "component"
+			}),
+			def({
+				tagName: "name",
+				syntaxKind: "record",
+				recordKind: "component"
+			}),
+			def({
+				tagName: "utility",
+				syntaxKind: "record",
+				recordKind: "utility"
+			}),
+			def({
+				tagName: "rule",
+				syntaxKind: "record",
+				recordKind: "rule"
+			}),
+			def({
+				tagName: "declaration",
+				syntaxKind: "record",
+				recordKind: "declaration"
+			}),
+			def({
+				tagName: "class",
+				syntaxKind: "block"
+			}),
+			def({
+				tagName: "summary",
+				syntaxKind: "block"
+			}),
+			def({
+				tagName: "remarks",
+				syntaxKind: "block"
+			}),
+			def({
+				tagName: "privateRemarks",
+				syntaxKind: "block"
+			}),
+			def({
+				tagName: "deprecated",
+				syntaxKind: "block"
+			}),
+			def({
+				tagName: "example",
+				syntaxKind: "block",
+				allowMultiple: true
+			}),
+			def({
+				tagName: "see",
+				syntaxKind: "block",
+				allowMultiple: true
+			}),
+			def({
+				tagName: "since",
+				syntaxKind: "block"
+			}),
+			def({
+				tagName: "group",
+				syntaxKind: "block"
+			}),
+			def({
+				tagName: "category",
+				syntaxKind: "block",
+				aliasFor: "group"
+			}),
+			def({
+				tagName: "defaultValue",
+				syntaxKind: "block"
+			}),
+			def({
+				tagName: "modifier",
+				syntaxKind: "block",
+				allowMultiple: true
+			}),
+			def({
+				tagName: "part",
+				syntaxKind: "block",
+				allowMultiple: true
+			}),
+			def({
+				tagName: "csspart",
+				syntaxKind: "block",
+				allowMultiple: true,
+				aliasFor: "part"
+			}),
+			def({
+				tagName: "cssproperty",
+				syntaxKind: "block",
+				allowMultiple: true
+			}),
+			def({
+				tagName: "property",
+				syntaxKind: "block",
+				allowMultiple: true,
+				aliasFor: "cssproperty"
+			}),
+			def({
+				tagName: "cssstate",
+				syntaxKind: "block",
+				allowMultiple: true
+			}),
+			def({
+				tagName: "slot",
+				syntaxKind: "block",
+				allowMultiple: true
+			}),
+			def({
+				tagName: "function",
+				syntaxKind: "block",
+				allowMultiple: true
+			}),
+			def({
+				tagName: "keyframes",
+				syntaxKind: "block",
+				allowMultiple: true
+			}),
+			def({
+				tagName: "animation",
+				syntaxKind: "block",
+				allowMultiple: true,
+				aliasFor: "keyframes"
+			}),
+			def({
+				tagName: "layer",
+				syntaxKind: "block",
+				allowMultiple: true
+			}),
+			def({
+				tagName: "container",
+				syntaxKind: "block",
+				allowMultiple: true
+			}),
+			def({
+				tagName: "supports",
+				syntaxKind: "block",
+				allowMultiple: true
+			}),
+			def({
+				tagName: "media",
+				syntaxKind: "block",
+				allowMultiple: true
+			}),
+			def({
+				tagName: "responsive",
+				syntaxKind: "block",
+				allowMultiple: true,
+				aliasFor: "media"
+			}),
+			def({
+				tagName: "a11y",
+				syntaxKind: "block",
+				allowMultiple: true
+			}),
+			def({
+				tagName: "accessibility",
+				syntaxKind: "block",
+				allowMultiple: true,
+				aliasFor: "a11y"
+			}),
+			def({
+				tagName: "structure",
+				syntaxKind: "block"
+			}),
+			def({
+				tagName: "demo",
+				syntaxKind: "block"
+			}),
+			def({
+				tagName: "alpha",
+				syntaxKind: "modifier"
+			}),
+			def({
+				tagName: "beta",
+				syntaxKind: "modifier"
+			}),
+			def({
+				tagName: "experimental",
+				syntaxKind: "modifier"
+			}),
+			def({
+				tagName: "internal",
+				syntaxKind: "modifier"
+			}),
+			def({
+				tagName: "public",
+				syntaxKind: "modifier"
+			}),
+			def({
+				tagName: "link",
+				syntaxKind: "inline"
+			}),
+			def({
+				tagName: "inheritDoc",
+				syntaxKind: "inline"
+			}),
+			def({
+				tagName: "label",
+				syntaxKind: "inline"
+			})
+		];
+	}
+};
+//#endregion
+//#region src/grammar.ts
+/**
+* The CSS doc-comment grammar — an expansive, TSDoc-shaped tag vocabulary parsed out of `/** … *\/`
+* block comments. The tags describe a CSS surface (a component's base class, modifiers, parts, custom
+* properties, functions, animations, layers, conditions, states, slots) and adopt the Custom Elements
+* Manifest names (`@cssproperty`, `@csspart`, `@cssstate`) where they exist, so the vocabulary is
+* standards-aligned.
+*
+* The grammar is specified formally in `grammar/CssDoc.grammarkdown` (RFC-style, modeling TSDoc's
+* `DeclarationReference.grammarkdown`); the functions here are hand-written to conform to those
+* productions, and `tests/grammar.test.ts` keeps the spec valid. Which tags are active — and which
+* custom tags to capture — is governed by a {@link CssDocConfiguration}.
+*
+* A block looks like:
+* ```css
+* /**
+*  * @component button
+*  * @summary The primary action control.
+*  * @modifier -color-secondary — A lower-emphasis action.
+*  * @part .icon — A leading glyph.
+*  * @cssproperty --value <number> — The 0–100 fill.
+*  * @demo self:button
+*  *\/
+* ```
+*
+* @module
+*/
+/**
+* The record-opening tags and the {@link CssRecordKind} each selects, as the default boundary map.
+* A doc comment carrying one of these opens a new record; `@name` is an alias for `@component`. A
+* {@link CssDocConfiguration} may add more record tags.
+*/
+const RECORD_TAGS = {
+	component: "component",
+	name: "component",
+	utility: "utility",
+	rule: "rule",
+	declaration: "declaration"
+};
+/** Split a tag's argument into `head` (a selector/name/token) and `description` on ` — ` or ` - `. */
+function splitDesc(rest) {
+	const m = rest.match(/^(\S+)\s+(?:—|-{1,2})\s+(.*)$/u);
+	if (m) return {
+		head: m[1],
+		description: m[2].trim()
+	};
+	return { head: rest.trim() || rest };
+}
+/** Split any argument into `query` (everything before the first ` — `/` - `) and `description`. */
+function splitQuery(rest) {
+	const m = rest.match(/^([\s\S]*?)\s+(?:—|-{1,2})\s+([\s\S]*)$/u);
+	if (m) return {
+		query: m[1].trim(),
+		description: m[2].trim()
+	};
+	return { query: rest.trim() };
+}
+/** Strip the comment framing (`/**`, `*\/`, and leading ` * `) from a raw block-comment body. */
+function stripCommentFraming(raw) {
+	return raw.replace(/^\/\*\*?/, "").replace(/\*\/$/, "").split("\n").map((line) => line.replace(/^\s*\*\s?/, "")).join("\n").trim();
+}
+/** Parse the inner body of a `@modifier` line's argument into a {@link DocModifier}. */
+function parseModifierBody(description) {
+	const dep = description?.match(/^@deprecated\b\s*([\s\S]*)$/u);
+	if (dep) {
+		const rawNote = dep[1].trim();
+		const link = rawNote.match(/\{@link\s+\.?(-[\w-]+)\s*\}/u);
+		const note = rawNote.replace(/\{@link\s+[^}]*\}/u, "").trim();
+		if (!note && !link) return { deprecatedFlag: true };
+		return {
+			deprecated: note || void 0,
+			deprecatedCanonical: link?.[1]
+		};
+	}
+	return { description: description ?? "" };
+}
+/**
+* Parse a doc-comment's INNER text (already stripped of `/* *\/` framing, or a raw block — both are
+* handled) into a {@link ParsedDoc}. The `configuration` decides which tags are active and which custom
+* tags to capture; unknown or unsupported tags are ignored, so the grammar degrades gracefully.
+*
+* @param raw - The comment text (with or without `/** … *\/` framing).
+* @param configuration - The active tag configuration (defaults to the full standard vocabulary).
+* @returns The structured tags.
+*/
+function parseDocComment(raw, configuration = new CssDocConfiguration()) {
+	const body = stripCommentFraming(raw);
+	const doc = {
+		modifiers: /* @__PURE__ */ new Map(),
+		parts: /* @__PURE__ */ new Map(),
+		cssProperties: [],
+		cssStates: /* @__PURE__ */ new Map(),
+		slots: /* @__PURE__ */ new Map(),
+		functions: /* @__PURE__ */ new Map(),
+		animations: /* @__PURE__ */ new Map(),
+		layers: /* @__PURE__ */ new Map(),
+		conditions: [],
+		examples: [],
+		see: [],
+		customBlocks: /* @__PURE__ */ new Map()
+	};
+	const blocks = [];
+	for (const line of body.split("\n")) if (/^\s*@[a-zA-Z]/u.test(line)) blocks.push(line.trim());
+	else if (blocks.length) blocks[blocks.length - 1] += `\n${line}`;
+	for (const block of blocks) {
+		const m = block.match(/^@([a-zA-Z][\w-]*)\s*([\s\S]*)$/u);
+		if (!m) continue;
+		const tagName = m[1];
+		const rest = m[2].trim();
+		const definition = configuration.tryGetTagDefinition(tagName);
+		if (!definition || !configuration.isTagSupported(definition)) continue;
+		if (definition.syntaxKind === "record") {
+			doc.component = rest.split(/\s/u)[0];
+			doc.kind = definition.recordKind;
+			continue;
+		}
+		if (definition.syntaxKind === "modifier") {
+			doc.releaseStage = definition.canonicalName;
+			continue;
+		}
+		if (definition.syntaxKind === "inline") continue;
+		applyBlockTag(doc, definition.canonicalName, definition.tagNameWithoutAt, rest);
+	}
+	return doc;
+}
+/** Apply one supported block tag (resolved to its canonical name) to the accumulating {@link ParsedDoc}. */
+function applyBlockTag(doc, canonical, tagName, rest) {
+	switch (canonical) {
+		case "class":
+			doc.className = rest.split(/\s/u)[0];
+			break;
+		case "summary":
+			doc.summary = rest.replace(/\s+/gu, " ").trim();
+			break;
+		case "remarks":
+			doc.remarks = rest.trim();
+			break;
+		case "privateRemarks":
+			doc.privateRemarks = rest.trim();
+			break;
+		case "since":
+			doc.since = rest.trim();
+			break;
+		case "group":
+			doc.group = rest.trim();
+			break;
+		case "a11y":
+			doc.accessibility = rest.trim();
+			break;
+		case "structure":
+			doc.structure = parseStructure(rest);
+			break;
+		case "modifier": {
+			const { head, description } = splitDesc(rest);
+			doc.modifiers.set(head.replace(/^\./u, ""), parseModifierBody(description));
+			break;
+		}
+		case "part": {
+			const { head, description } = splitDesc(rest);
+			doc.parts.set(head.replace(/^\./u, ""), description ?? "");
+			break;
+		}
+		case "cssproperty": {
+			const propMatch = rest.match(/^(--[\w-]+)\s*(<[^>]+>)?\s*(?:(?:—|-{1,2})\s*(.*))?$/u);
+			if (propMatch) doc.cssProperties.push({
+				name: propMatch[1],
+				syntax: propMatch[2],
+				description: propMatch[3]?.trim() || void 0
+			});
+			break;
+		}
+		case "defaultValue": {
+			const last = doc.cssProperties.at(-1);
+			if (last) last.defaultValue = rest.trim();
+			break;
+		}
+		case "cssstate": {
+			const { head, description } = splitDesc(rest);
+			doc.cssStates.set(head, description ?? "");
+			break;
+		}
+		case "slot": {
+			const { head, description } = splitDesc(rest);
+			doc.slots.set(head.replace(/^\./u, ""), description ?? "");
+			break;
+		}
+		case "function": {
+			const nameMatch = rest.match(/^(--[\w-]+)/u);
+			const { description } = splitDesc(rest);
+			if (nameMatch) doc.functions.set(nameMatch[1], description ?? "");
+			break;
+		}
+		case "keyframes": {
+			const { head, description } = splitDesc(rest);
+			doc.animations.set(head, description ?? "");
+			break;
+		}
+		case "layer": {
+			const { head, description } = splitDesc(rest);
+			doc.layers.set(head, description ?? "");
+			break;
+		}
+		case "container":
+		case "supports":
+		case "media": {
+			const { query, description } = splitQuery(rest);
+			doc.conditions.push({
+				type: canonical,
+				query,
+				description
+			});
+			break;
+		}
+		case "example":
+			doc.examples.push(rest);
+			break;
+		case "deprecated":
+			doc.deprecated = rest;
+			break;
+		case "demo":
+			doc.demo = rest.split(/\s/u)[0];
+			break;
+		case "see":
+			doc.see.push(rest);
+			break;
+		default: {
+			const list = doc.customBlocks.get(tagName) ?? [];
+			list.push(rest);
+			doc.customBlocks.set(tagName, list);
+			break;
+		}
+	}
+}
+/**
+* Whether a comment's text opens a record — i.e. carries a record tag. Uses the `configuration`'s
+* record tags when given, else the default {@link RECORD_TAGS}.
+*
+* @param commentText - The comment body.
+* @param configuration - The active configuration (optional).
+* @returns The record name, or `undefined`.
+*/
+function recordNameOf(commentText, configuration) {
+	const tagNames = configuration ? configuration.supportedTagDefinitions.filter((d) => d.syntaxKind === "record").map((d) => d.tagNameWithoutAt) : Object.keys(RECORD_TAGS);
+	if (tagNames.length === 0) return void 0;
+	return commentText.match(new RegExp(`@(?:${tagNames.join("|")})\\s+(\\S+)`, "u"))?.[1];
+}
+/**
+* Parse a `@structure` body — an indentation-nested list of element selectors — into a
+* {@link StructureNode} tree. Indentation depth (any consistent width) sets nesting; blank lines are
+* ignored.
+*
+* @example
+* ```
+* .tabs
+*   .list
+*     .tab
+*   .panel
+* ```
+*/
+function parseStructure(raw) {
+	const roots = [];
+	const stack = [];
+	for (const line of raw.split("\n")) {
+		if (!line.trim()) continue;
+		const indent = line.length - line.trimStart().length;
+		const node = {
+			selector: line.trim(),
+			children: []
+		};
+		while (stack.length && stack[stack.length - 1].indent >= indent) stack.pop();
+		if (stack.length) stack[stack.length - 1].node.children.push(node);
+		else roots.push(node);
+		stack.push({
+			indent,
+			node
+		});
+	}
+	return roots;
+}
+//#endregion
+//#region src/parse.ts
+/**
+* The PostCSS-based parser: turn a CSS string into a {@link CssDocEntry}[] documentation model.
+*
+* It is AST-first — the machine facts (base class, modifiers, parts, consumed/declared custom
+* properties, custom functions, animations, cascade layers, conditional-support blocks, states, and
+* deprecated-alias links) are derived from the actual selectors and at-rules, so they can't drift from
+* the shipping CSS. Authored `/** … *\/` doc comments (parsed by {@link parseDocComment}) supply only
+* prose (summaries, descriptions) and demo/see links, and delimit one component from the next.
+*
+* @module
+*/
+/** Matches a `var(--name` reference; group 1 is the custom-property name. */
+const VAR_RE = /var\(\s*(--[\w-]+)/gu;
+const unquote = (value) => value.trim().replace(/^["']|["']$/gu, "");
+/** Split a `-<prop>-<value>` (or boolean `-<flag>`) modifier into its prop/value segments. */
+function splitModifier(name) {
+	const body = name.replace(/^-/u, "");
+	const dash = body.indexOf("-");
+	if (dash === -1) return { prop: body };
+	return {
+		prop: body.slice(0, dash),
+		value: body.slice(dash + 1)
+	};
+}
+/** Record a conditional-support block, de-duplicating by type + query. */
+function addCondition(acc, condition) {
+	if (!acc.conditions.some((c) => c.type === condition.type && c.query === condition.query)) acc.conditions.push(condition);
+}
+/** Derive a CSS custom function from an `@function` at-rule. */
+function collectFunction(node, acc) {
+	const params = node.params.trim();
+	const nameMatch = params.match(/^(--[\w-]+)/u);
+	if (!nameMatch) return;
+	const paren = params.match(/\(([^)]*)\)/u);
+	const parameters = paren ? [...paren[1].matchAll(/(--[\w-]+)/gu)].map((m) => m[1]) : [];
+	let result = params.match(/\breturns\b\s+(.+)$/iu)?.[1]?.trim();
+	if (!result) {
+		const resultDecl = node.nodes?.find((n) => n.type === "decl" && n.prop === "result");
+		if (resultDecl && "value" in resultDecl) result = resultDecl.value.trim();
+	}
+	acc.functions.set(nameMatch[1], {
+		name: nameMatch[1],
+		parameters,
+		result
+	});
+}
+/** Extract every fact from one record's nodes into `acc`. */
+function collect(nodes, acc, baseEsc, prefixNoDot, inScope) {
+	const modRe = new RegExp(`(?:${baseEsc}|:scope)((?:\\.-[\\w-]+)+)`, "gu");
+	let pendingCanonical;
+	for (const node of nodes) {
+		if (node.type === "comment") {
+			const dep = node.text.match(/@deprecated.*?use\s+\.(-[\w-]+)/u);
+			if (dep) pendingCanonical = dep[1];
+			continue;
+		}
+		if (node.type === "decl") {
+			for (const m of node.value.matchAll(VAR_RE)) acc.consumed.add(m[1]);
+			continue;
+		}
+		if (node.type === "atrule") {
+			if (node.name === "property") {
+				const name = node.params.trim();
+				const decl = (prop) => {
+					const d = node.nodes?.find((n) => n.type === "decl" && n.prop === prop);
+					return d && "value" in d ? d.value : void 0;
+				};
+				const inherits = decl("inherits");
+				const initial = decl("initial-value");
+				const syntax = decl("syntax");
+				acc.declared.set(name, {
+					name,
+					syntax: syntax === void 0 ? void 0 : unquote(syntax),
+					inherits: inherits === void 0 ? void 0 : /^true$/iu.test(inherits.trim()),
+					defaultValue: initial === void 0 ? void 0 : initial.trim()
+				});
+			} else if (node.name === "function") collectFunction(node, acc);
+			else if (node.name === "keyframes") {
+				const animName = node.params.trim();
+				if (animName) acc.animations.set(animName, { name: animName });
+			} else if (node.name === "layer") for (const raw of node.params.split(",")) {
+				const layerName = raw.trim();
+				if (layerName) acc.layers.set(layerName, { name: layerName });
+			}
+			else if (node.name === "container") {
+				const params = node.params.trim();
+				let containerName;
+				let query = params;
+				if (params && !params.startsWith("(")) {
+					const sp = params.indexOf(" ");
+					if (sp > 0) {
+						containerName = params.slice(0, sp);
+						query = params.slice(sp + 1).trim();
+					}
+				}
+				addCondition(acc, {
+					type: "container",
+					query,
+					containerName
+				});
+			} else if (node.name === "supports") addCondition(acc, {
+				type: "supports",
+				query: node.params.trim()
+			});
+			else if (node.name === "media") addCondition(acc, {
+				type: "media",
+				query: node.params.trim()
+			});
+			if (node.nodes) collect(node.nodes, acc, baseEsc, prefixNoDot, inScope || node.name === "scope");
+			continue;
+		}
+		if (node.type === "rule") {
+			for (const selector of node.selector.split(",")) {
+				for (const s of selector.matchAll(/:state\(\s*([\w-]+)\s*\)/gu)) if (!acc.states.has(s[1])) acc.states.set(s[1], { name: s[1] });
+				const bare = selector.replace(/::?[\w-]+(\([^)]*\))?/gu, "");
+				for (const m of bare.matchAll(modRe)) for (const mod of m[1].matchAll(/\.(-[\w-]+)/gu)) {
+					const modName = mod[1];
+					const existing = acc.modifiers.get(modName);
+					const { prop, value } = splitModifier(modName);
+					const entry = existing ?? {
+						name: modName,
+						prop,
+						value
+					};
+					if (pendingCanonical) entry.deprecated = { canonical: pendingCanonical };
+					acc.modifiers.set(modName, entry);
+				}
+				if (inScope) for (const m of bare.matchAll(/\.([a-z][\w-]*)/gu)) {
+					const part = m[1];
+					if (prefixNoDot && part.startsWith(prefixNoDot)) continue;
+					if (!acc.parts.has(part)) acc.parts.set(part, { name: part });
+				}
+			}
+			for (const child of node.nodes ?? []) if (child.type === "decl") for (const m of child.value.matchAll(VAR_RE)) acc.consumed.add(m[1]);
+			pendingCanonical = void 0;
+		}
+	}
+}
+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) {
+	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));
+		const nameEsc = name.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
+		const endsWithName = new RegExp(`(?:^|-)${nameEsc}$`, "u");
+		className = bare.find((sel) => endsWithName.test(sel.slice(1))) ?? bare[0] ?? "";
+	}
+	if (!className) className = `.${name}`;
+	const acc = {
+		className,
+		modifiers: /* @__PURE__ */ new Map(),
+		parts: /* @__PURE__ */ new Map(),
+		states: /* @__PURE__ */ new Map(),
+		consumed: /* @__PURE__ */ new Set(),
+		declared: /* @__PURE__ */ new Map(),
+		functions: /* @__PURE__ */ new Map(),
+		animations: /* @__PURE__ */ new Map(),
+		layers: /* @__PURE__ */ new Map(),
+		conditions: []
+	};
+	collect(nodes, acc, className.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&"), className.endsWith(name) ? className.slice(1, className.length - name.length) : "", false);
+	for (const [modName, mdoc] of doc.modifiers) {
+		const existing = acc.modifiers.get(modName);
+		const dep = mdoc.deprecated || mdoc.deprecatedCanonical || mdoc.deprecatedFlag ? {
+			...mdoc.deprecated ? { note: mdoc.deprecated } : {},
+			...mdoc.deprecatedCanonical ? { canonical: mdoc.deprecatedCanonical } : {}
+		} : void 0;
+		if (existing) {
+			if (mdoc.description) existing.description = mdoc.description;
+			if (dep) existing.deprecated = {
+				...existing.deprecated,
+				...dep
+			};
+		} else {
+			const { prop, value } = splitModifier(modName);
+			acc.modifiers.set(modName, {
+				name: modName,
+				prop,
+				value,
+				description: mdoc.description,
+				deprecated: dep
+			});
+		}
+	}
+	for (const [part, description] of doc.parts) {
+		const existing = acc.parts.get(part);
+		if (existing) existing.description = description || existing.description;
+		else acc.parts.set(part, {
+			name: part,
+			description
+		});
+	}
+	for (const [state, description] of doc.cssStates) {
+		const existing = acc.states.get(state);
+		if (existing) existing.description = description || existing.description;
+		else acc.states.set(state, {
+			name: state,
+			description: description || void 0
+		});
+	}
+	for (const prop of doc.cssProperties) {
+		const existing = acc.declared.get(prop.name);
+		acc.declared.set(prop.name, {
+			name: prop.name,
+			syntax: prop.syntax ?? existing?.syntax,
+			inherits: existing?.inherits,
+			defaultValue: prop.defaultValue ?? existing?.defaultValue,
+			description: prop.description ?? existing?.description
+		});
+	}
+	for (const [fnName, description] of doc.functions) {
+		const existing = acc.functions.get(fnName);
+		if (existing) existing.description = description || existing.description;
+		else acc.functions.set(fnName, {
+			name: fnName,
+			parameters: [],
+			description: description || void 0
+		});
+	}
+	for (const [animName, description] of doc.animations) {
+		const existing = acc.animations.get(animName);
+		if (existing) existing.description = description || existing.description;
+		else acc.animations.set(animName, {
+			name: animName,
+			description: description || void 0
+		});
+	}
+	for (const [layerName, description] of doc.layers) {
+		const existing = acc.layers.get(layerName);
+		if (existing) existing.description = description || existing.description;
+		else acc.layers.set(layerName, {
+			name: layerName,
+			description: description || void 0
+		});
+	}
+	for (const cond of doc.conditions) {
+		const existing = acc.conditions.find((c) => c.type === cond.type && c.query === cond.query);
+		if (existing) existing.description = cond.description || existing.description;
+		else acc.conditions.push({
+			type: cond.type,
+			query: cond.query,
+			description: cond.description
+		});
+	}
+	const modifiers = [...acc.modifiers.values()].sort((a, b) => a.prop.localeCompare(b.prop) || (a.value ?? "").localeCompare(b.value ?? ""));
+	return {
+		name,
+		kind: doc.kind ?? "component",
+		className,
+		summary: doc.summary,
+		remarks: doc.remarks,
+		privateRemarks: doc.privateRemarks,
+		releaseStage: doc.releaseStage,
+		since: doc.since,
+		group: doc.group,
+		accessibility: doc.accessibility,
+		modifiers,
+		parts: [...acc.parts.values()].sort(byName),
+		states: [...acc.states.values()].sort(byName),
+		slots: [...doc.slots].map(([slotName, description]) => ({
+			name: slotName,
+			description: description || void 0
+		})).sort(byName),
+		cssPropertiesConsumed: [...acc.consumed].sort(),
+		cssPropertiesDeclared: [...acc.declared.values()].sort(byName),
+		functions: [...acc.functions.values()].sort(byName),
+		animations: [...acc.animations.values()].sort(byName),
+		layers: [...acc.layers.values()].sort(byName),
+		conditions: acc.conditions,
+		examples: doc.examples,
+		structure: doc.structure,
+		demo: doc.demo,
+		deprecated: doc.deprecated,
+		see: doc.see,
+		...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
+* record tag (`@component`/`@name` by default; override via {@link ParseOptions.isRecordBoundary});
+* everything from one boundary comment to the next belongs to that record.
+*
+* @param css - The CSS source (a generated stylesheet, with authored doc comments).
+* @param options - {@link ParseOptions}.
+* @returns One {@link CssDocEntry} per record, in document order.
+*
+* @example
+* ```ts
+* import { parseCssDocs } from "@cssdoc/core";
+*
+* const [badge] = parseCssDocs(badgeCssWithDocComments);
+* badge.modifiers.map((m) => m.name); // ["-color-danger", "-color-success", …]
+* ```
+*/
+function parseCssDocs(css, options = {}) {
+	const configuration = options.configuration ?? new CssDocConfiguration();
+	const boundary = options.isRecordBoundary ?? ((text) => recordNameOf(text, configuration));
+	const root = postcss.parse(css);
+	const records = [];
+	let current = null;
+	for (const node of root.nodes) {
+		if (node.type === "comment") {
+			const name = boundary(node.text);
+			if (name) {
+				current = {
+					name,
+					doc: parseDocComment(node.text, configuration),
+					nodes: []
+				};
+				records.push(current);
+				continue;
+			}
+		}
+		if (current) current.nodes.push(node);
+	}
+	return records.map((r) => buildEntry(r.name, r.doc, r.nodes));
+}
+//#endregion
+//#region src/mermaid.ts
+/** Escape a selector label for a Mermaid node body (quoted to allow dots, brackets, and spaces). */
+const label = (selector) => `"${selector.replace(/"/gu, "&quot;")}"`;
+/**
+* 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.
+*
+* @param roots - Top-level {@link StructureNode}s (an authored `@structure`).
+* @param options - `direction` sets the flowchart orientation (default `TD`, top-down).
+* @returns Mermaid source, or an empty string when there are no nodes.
+*
+* @example
+* ```ts
+* toMermaid([{ selector: ".tabs", children: [{ selector: ".panel", children: [] }] }]);
+* // flowchart TD
+* //   n0[".tabs"]
+* //   n1[".panel"]
+* //   n0 --> n1
+* ```
+*/
+function toMermaid(roots, options = {}) {
+	if (!roots.length) return "";
+	const lines = [`flowchart ${options.direction ?? "TD"}`];
+	const edges = [];
+	let counter = 0;
+	const walk = (node) => {
+		const id = `n${counter++}`;
+		lines.push(`  ${id}[${label(node.selector)}]`);
+		for (const child of node.children) edges.push(`  ${id} --> ${walk(child)}`);
+		return id;
+	};
+	for (const root of roots) walk(root);
+	return [...lines, ...edges].join("\n");
+}
+//#endregion
+//#region src/index.ts
+/**
+* Serialize a documentation model to pretty JSON (the raw, emitter-agnostic artifact — like TypeDoc's
+* `--json`).
+*
+* @param model - The entries from {@link parseCssDocs}.
+* @returns A JSON string.
+*/
+function toJson(model) {
+	return `${JSON.stringify(model, null, 2)}\n`;
+}
+//#endregion
+export { CssDocConfiguration, CssDocTagDefinition, RECORD_TAGS, parseCssDocs, parseDocComment, parseStructure, recordNameOf, stripCommentFraming, toJson, toMermaid };