@cssdoc/core 0.4.2 → 0.5.1

package/dist/lite-HEYG01Eo.mjs

@@ -0,0 +1,933 @@
+import { CSSDOC_TAGS, CSSDOC_TAG_NAMES } from "@cssdoc/spec";
+//#region src/modifier.ts
+/**
+* The pseudo-classes cssdoc treats as component states by default — form and UI states a component
+* meaningfully declares. Ubiquitous interaction pseudos (`:hover`, `:focus`, `:active`) are omitted so
+* incidental rules don't become documented states; add them via `statePseudoClasses` if you want them.
+*/
+const DEFAULT_STATE_PSEUDO_CLASSES = [
+	"checked",
+	"disabled",
+	"enabled",
+	"indeterminate",
+	"default",
+	"open",
+	"placeholder-shown",
+	"read-only",
+	"read-write",
+	"required",
+	"optional",
+	"valid",
+	"invalid",
+	"in-range",
+	"out-of-range"
+];
+/** The built-in convention presets. Other schemes use the custom object (see the docs). */
+const MODIFIER_PRESETS = {
+	/** BEM / SUIT — `.button--primary`, with `.button__element` sub-elements. The default. */
+	bem: {
+		structure: "suffix",
+		separator: "--",
+		elementSeparator: "__",
+		propValue: false
+	},
+	/** rscss — `.button.-color-secondary`, split into `prop`/`value`. */
+	rscss: {
+		structure: "chained",
+		separator: "-",
+		propValue: true,
+		propValueSeparator: "-"
+	},
+	/** OOCSS / bare chained classes — `.button.primary` (any class chained to the base). */
+	bare: {
+		structure: "chained",
+		separator: "",
+		propValue: false
+	}
+};
+/** The default convention: BEM. */
+const DEFAULT_MODIFIER_CONVENTION = MODIFIER_PRESETS.bem;
+/**
+* Resolve a preset name or custom object into a fully-populated {@link ModifierConvention} (defaults
+* filled in). No argument resolves to the {@link DEFAULT_MODIFIER_CONVENTION} (BEM).
+*
+* @throws If given an unknown preset name.
+*/
+function resolveModifierConvention(input) {
+	let base;
+	if (input === void 0) base = DEFAULT_MODIFIER_CONVENTION;
+	else if (typeof input === "string") base = MODIFIER_PRESETS[input];
+	else base = input;
+	if (!base) throw new Error(`Unknown modifier convention preset: ${JSON.stringify(input)}`);
+	return {
+		structure: base.structure,
+		separator: base.separator,
+		...base.elementSeparator !== void 0 ? { elementSeparator: base.elementSeparator } : {},
+		...base.statePrefixes !== void 0 ? { statePrefixes: base.statePrefixes } : {},
+		statePseudoClasses: base.statePseudoClasses ?? [...DEFAULT_STATE_PSEUDO_CLASSES],
+		propValue: base.propValue ?? false,
+		propValueSeparator: base.propValueSeparator ?? "-"
+	};
+}
+/** Escape a string for literal use inside a `RegExp`. */
+const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
+/** Strip one layer of matching quotes from an attribute value. */
+const unquote = (v) => v.trim().replace(/^(["'])([\s\S]*)\1$/u, "$2");
+/**
+* The single owner of modifier recognition for one convention: finds modifiers on selectors, derives
+* `prop`/`value`, renders a modifier name back to a selector fragment, and answers "does this host-doc
+* token look like a modifier usage?". Constructed once per parse from the resolved convention.
+*/
+var ModifierMatcher = class {
+	convention;
+	/** The separator(s), longest-first so overlapping prefixes (e.g. `--` before `-`) match greedily. */
+	separators;
+	/** The separators as a non-capturing regex alternation, e.g. `(?:is-|has-)` (or `(?:)` when empty). */
+	sepAlt;
+	/** BEM-style element separators (longest-first), or empty when the convention has none. */
+	elementSeparators;
+	/** The element separators as a non-capturing alternation, or `""` when there are none. */
+	elementSepAlt;
+	/** State-class prefixes (longest-first), or empty when the convention has none. */
+	statePrefixes;
+	/** Native pseudo-classes (no `:`) recognized as states. */
+	statePseudoClasses;
+	constructor(convention) {
+		this.convention = convention;
+		const longestFirst = (value) => (Array.isArray(value) ? value : [value]).slice().sort((a, b) => b.length - a.length);
+		this.separators = longestFirst(convention.separator);
+		this.sepAlt = `(?:${this.separators.map(escapeRe).join("|")})`;
+		this.elementSeparators = convention.elementSeparator ? longestFirst(convention.elementSeparator).filter((s) => s !== "") : [];
+		this.elementSepAlt = this.elementSeparators.length ? `(?:${this.elementSeparators.map(escapeRe).join("|")})` : "";
+		this.statePrefixes = (convention.statePrefixes ?? []).filter((p) => p !== "").slice().sort((a, b) => b.length - a.length);
+		this.statePseudoClasses = new Set(convention.statePseudoClasses ?? []);
+	}
+	/** Does a class name (no leading dot) start with one of the convention's state prefixes? */
+	isStateClass(name) {
+		return this.statePrefixes.some((p) => name.startsWith(p));
+	}
+	/** Strip a leading chained-class separator from `name` (the longest that matches), else return it. */
+	stripPrefix(name) {
+		for (const s of this.separators) if (name.startsWith(s)) return name.slice(s.length);
+		return name;
+	}
+	/** Return the suffix body — the part after the first (longest) non-empty separator occurrence. */
+	stripToBody(name) {
+		for (const s of this.separators) {
+			if (s === "") continue;
+			const at = name.indexOf(s);
+			if (at !== -1) return name.slice(at + s.length);
+		}
+		return name;
+	}
+	/**
+	* Every modifier attached to `baseNoDot` within one selector. `selector` should have its pseudos
+	* already dropped (as `parse.ts`/`index.ts` do); the base is given without its leading dot.
+	*/
+	modifiersIn(selector, baseNoDot) {
+		const baseEsc = escapeRe(baseNoDot);
+		const hits = [];
+		const seen = /* @__PURE__ */ new Set();
+		const push = (name) => {
+			if (seen.has(name)) return;
+			seen.add(name);
+			hits.push({
+				name,
+				...this.analyze(name),
+				...name.includes("*") ? { pattern: true } : {}
+			});
+		};
+		if (this.convention.structure === "suffix") {
+			const re = new RegExp(`\\.(${baseEsc}${this.sepAlt}[\\w-]+)`, "gu");
+			for (const m of selector.matchAll(re)) push(m[1]);
+			for (const name of this.classAttrFamilies(selector, baseEsc)) push(name);
+			return hits;
+		}
+		if (this.convention.structure === "attribute") {
+			const chain = new RegExp(`(?:\\.${baseEsc}|:scope)((?:\\[[^\\]]*\\])+)`, "gu");
+			for (const m of selector.matchAll(chain)) for (const a of m[1].matchAll(/\[([^\]]*)\]/gu)) {
+				const name = this.normalizeAttribute(a[1]);
+				if (name && this.attributeMatches(name)) push(name);
+			}
+			return hits;
+		}
+		const cls = `\\.${this.sepAlt}[\\w-]+`;
+		const chain = new RegExp(`(?:\\.${baseEsc}|:scope)((?:${cls})+)`, "gu");
+		const inner = new RegExp(`\\.(${this.sepAlt}[\\w-]+)`, "gu");
+		for (const m of selector.matchAll(chain)) for (const c of m[1].matchAll(inner)) if (!this.isStateClass(c[1])) push(c[1]);
+		for (const name of this.classAttrFamilies(selector, baseEsc)) push(name);
+		return hits;
+	}
+	/**
+	* Family modifiers declared by a `class` attribute selector on the base — `.base[class*="-icon-"]`
+	* yields the `*` family `-icon-*`. The operator maps to the wildcard position: `*=`/`|=` and (rare)
+	* exact `~=`/`=` derive a prefix family or a concrete name, `$=` a suffix family; `^=` is skipped
+	* (it anchors to the start of the whole class attribute — the base class — not a chained modifier).
+	* The value must begin with a convention separator to count (so `[class*="-icon-"]` does, `[dir]` and
+	* `[class*="grid"]` don't), and carry a literal core beyond the separator.
+	*/
+	classAttrFamilies(selector, baseEsc) {
+		const out = [];
+		const chain = new RegExp(`(?:\\.${baseEsc}|:scope)((?:\\[[^\\]]*\\])+)`, "gu");
+		const attr = /\[\s*class\s*([~^$*|]?)=\s*(?:"([^"]*)"|'([^']*)'|([^\]\s]*))\s*\]/gu;
+		for (const m of selector.matchAll(chain)) for (const a of m[1].matchAll(attr)) {
+			const value = (a[2] ?? a[3] ?? a[4] ?? "").trim();
+			const name = this.classAttrFamily(a[1], value);
+			if (name) out.push(name);
+		}
+		return out;
+	}
+	/** Derive a modifier name from a `[class OP value]` selector, or `undefined` when it isn't one. */
+	classAttrFamily(op, value) {
+		const sep = this.separators.find((s) => s !== "" && value.startsWith(s));
+		if (sep === void 0 && this.separators.every((s) => s !== "")) return void 0;
+		if (value.length <= (sep?.length ?? 0)) return void 0;
+		if (op === "^") return void 0;
+		if (op === "$") return `*${value}`;
+		if (op === "" || op === "~") return value;
+		return `${value}*`;
+	}
+	/**
+	* Every BEM-style element attached to `baseNoDot` within one selector (`.base<elementSep><name>`),
+	* as parts, each with any element-scoped modifiers (`.base__element--mod` → element `base__element`
+	* with modifier `mod`). Only meaningful for `suffix` conventions with an `elementSeparator`.
+	*/
+	elementsIn(selector, baseNoDot) {
+		if (this.convention.structure !== "suffix" || this.elementSepAlt === "") return [];
+		const baseEsc = escapeRe(baseNoDot);
+		const re = new RegExp(`\\.(${baseEsc}${this.elementSepAlt}[\\w-]+)`, "gu");
+		const byName = /* @__PURE__ */ new Map();
+		for (const m of selector.matchAll(re)) {
+			const { element, modifier } = this.splitElementModifier(m[1], baseNoDot);
+			const mods = byName.get(element) ?? [];
+			if (modifier && !mods.some((x) => x.name === modifier.name)) mods.push(modifier);
+			byName.set(element, mods);
+		}
+		return [...byName].map(([name, modifiers]) => ({
+			name,
+			modifiers
+		}));
+	}
+	/**
+	* Split `.base__element--mod`-style tokens into the element class (`base__element`) and, if a
+	* modifier separator follows the element name, the element-scoped modifier.
+	*/
+	splitElementModifier(token, baseNoDot) {
+		const elsep = this.elementSeparators.find((s) => token.startsWith(baseNoDot + s));
+		if (!elsep) return { element: token };
+		const afterElement = baseNoDot.length + elsep.length;
+		let at = -1;
+		for (const sep of this.separators) {
+			if (sep === "") continue;
+			const i = token.indexOf(sep, afterElement);
+			if (i !== -1 && (at === -1 || i < at)) at = i;
+		}
+		if (at === -1) return { element: token };
+		return {
+			element: token.slice(0, at),
+			modifier: {
+				name: token,
+				...this.analyze(token)
+			}
+		};
+	}
+	/**
+	* Every state class chained to `baseNoDot` within one selector — a class whose name starts with one
+	* of the convention's {@link ModifierConvention.statePrefixes} (e.g. `.tabs.is-open` → `is-open`).
+	* Empty when the convention sets no state prefixes.
+	*/
+	statesIn(selector, baseNoDot) {
+		if (this.statePrefixes.length === 0) return [];
+		const baseEsc = escapeRe(baseNoDot);
+		const prefixAlt = `(?:${this.statePrefixes.map(escapeRe).join("|")})`;
+		const chain = new RegExp(`(?:\\.${baseEsc}|:scope)((?:\\.[\\w-]+)+)`, "gu");
+		const inner = new RegExp(`\\.(${prefixAlt}[\\w-]+)`, "gu");
+		const seen = /* @__PURE__ */ new Set();
+		const out = [];
+		for (const m of selector.matchAll(chain)) for (const c of m[1].matchAll(inner)) if (!seen.has(c[1])) {
+			seen.add(c[1]);
+			out.push({ name: c[1] });
+		}
+		return out;
+	}
+	/**
+	* Every native pseudo-class on the selector recognized as a state — a `:name` whose `name` is in the
+	* convention's {@link ModifierConvention.statePseudoClasses} (e.g. `.tab:disabled` → `disabled`).
+	* Pseudo-elements (`::part`) and pseudos not in the set are ignored.
+	*/
+	pseudoStatesIn(selector) {
+		if (this.statePseudoClasses.size === 0) return [];
+		const seen = /* @__PURE__ */ new Set();
+		const out = [];
+		for (const m of selector.matchAll(/(?<!:):([\w-]+)/gu)) {
+			const name = m[1];
+			if (this.statePseudoClasses.has(name) && !seen.has(name)) {
+				seen.add(name);
+				out.push({ name });
+			}
+		}
+		return out;
+	}
+	/** Derive `prop`/`value` for a modifier `name` (as returned by {@link modifiersIn} or authored). */
+	analyze(name) {
+		if (name.includes("*")) {
+			const body = this.convention.structure === "suffix" ? this.stripToBody(name) : this.stripPrefix(name);
+			return { prop: body.replace(/\*/gu, "").replace(/-+$/u, "") || body };
+		}
+		if (this.convention.structure === "attribute") {
+			const canonical = this.normalizeAttribute(name);
+			const eq = canonical.indexOf("=");
+			const attr = eq === -1 ? canonical : canonical.slice(0, eq);
+			return {
+				prop: this.stripPrefix(attr),
+				value: eq === -1 ? void 0 : unquote(canonical.slice(eq + 1))
+			};
+		}
+		const body = this.convention.structure === "suffix" ? this.stripToBody(name) : this.stripPrefix(name);
+		if (!this.convention.propValue) return { prop: body };
+		const sep = this.convention.propValueSeparator ?? "-";
+		const at = body.indexOf(sep);
+		if (at === -1) return { prop: body };
+		return {
+			prop: body.slice(0, at),
+			value: body.slice(at + sep.length)
+		};
+	}
+	/** Render a modifier `name` as the selector fragment it denotes (`.name` or `[name]`). */
+	selectorFor(name) {
+		return this.convention.structure === "attribute" ? `[${name}]` : `.${name}`;
+	}
+	/**
+	* Whether a used class `used` is an instance of the documented modifier `name` — an exact match, or,
+	* when `name` is a `*` family (e.g. `-icon-*`), a glob match (`*` → any `[\w-]` run). Used consumer-side
+	* so `-icon-arrow` resolves to the documented `-icon-*` family.
+	*/
+	matchesModifier(name, used) {
+		if (name === used) return true;
+		if (!name.includes("*")) return false;
+		return new RegExp(`^${name.split("*").map(escapeRe).join("[\\w-]*")}$`, "u").test(used);
+	}
+	/** Normalize a member token/expression to its canonical `name` key (the inverse of authoring noise). */
+	normalizeMember(token) {
+		if (this.convention.structure === "attribute") {
+			const inner = token.replace(/^\[/u, "").replace(/\]$/u, "");
+			return this.normalizeAttribute(inner);
+		}
+		return token.replace(/^\./u, "");
+	}
+	/**
+	* Does a token/expression seen in a host document (an HTML class token, or an attribute expression)
+	* look like a modifier usage of `baseNoDot`? Replaces the old `startsWith("-")` gate.
+	*/
+	looksLikeUsage(token, baseNoDot) {
+		if (this.convention.structure === "attribute") return this.attributeMatches(this.normalizeMember(token));
+		const name = token.replace(/^\./u, "");
+		if (this.isStateClass(name)) return false;
+		if (this.convention.structure === "suffix") {
+			if (baseNoDot) return this.separators.some((s) => name.startsWith(`${baseNoDot}${s}`));
+			return this.separators.some((s) => s !== "" && name.includes(s));
+		}
+		if (baseNoDot && name === baseNoDot) return false;
+		return this.separators.some((s) => name.startsWith(s));
+	}
+	/**
+	* Classify a host-document class token relative to `baseNoDot`: a `modifier` usage, a `state` class
+	* (a `statePrefixes` prefix), a BEM `element` class (`base<elementSep>…`), or `undefined` if it's
+	* none of those. Consumer-side linting routes each kind to the right "unknown-…" check.
+	*/
+	usageKind(token, baseNoDot) {
+		if (this.convention.structure === "attribute") return this.looksLikeUsage(token, baseNoDot) ? "modifier" : void 0;
+		const name = token.replace(/^\./u, "");
+		if (this.isStateClass(name)) return "state";
+		if (baseNoDot && this.convention.structure === "suffix" && this.elementSeparators.some((s) => name.startsWith(`${baseNoDot}${s}`))) return "element";
+		return this.looksLikeUsage(token, baseNoDot) ? "modifier" : void 0;
+	}
+	/** Canonicalize an attribute expression (bracket-inner): normalize quotes to double, trim. */
+	normalizeAttribute(inner) {
+		const trimmed = inner.trim();
+		const eq = trimmed.indexOf("=");
+		if (eq === -1) return trimmed;
+		return `${trimmed.slice(0, eq + 1)}"${unquote(trimmed.slice(eq + 1))}"`;
+	}
+	/** Does an attribute-expression's name carry one of the convention's required prefixes? */
+	attributeMatches(name) {
+		const eq = name.indexOf("=");
+		const attr = (eq === -1 ? name : name.slice(0, eq)).replace(/[~|^$*]$/u, "");
+		return attr.length > 0 && this.separators.some((s) => attr.startsWith(s));
+	}
+};
+//#endregion
+//#region src/configuration.ts
+/**
+* The tag-definition registry — cssdoc's analog to `@microsoft/tsdoc`'s `TSDocConfiguration` /
+* `TSDocTagDefinition`. It names the vocabulary a parse understands: the built-in **standard** tags
+* (seeded automatically) plus any **custom** tags registered on top (typically loaded from a
+* `cssdoc.json` by `@cssdoc/config`). The parser consults the configuration to decide which record
+* tags open a boundary, which standard tags are active, and which unknown tags to capture as custom
+* blocks rather than ignore.
+*
+* The vocabulary is expansive and modeled on TSDoc's kind taxonomy — `record` / `block` / `modifier` /
+* `inline` — and covers the modern CSSOM surface. See `@cssdoc/spec`'s `grammar/CssDoc.grammarkdown`
+* for the formal shape of each tag.
+*
+* @module
+*/
+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();
+	_modifierConvention = DEFAULT_MODIFIER_CONVENTION;
+	constructor() {
+		this.addTagDefinitions(CssDocConfiguration.standardTags(), true);
+	}
+	/** The resolved modifier convention this configuration parses with (defaults to BEM). */
+	get modifierConvention() {
+		return this._modifierConvention;
+	}
+	/** Set the modifier convention from a preset name or a custom {@link ModifierConvention}. */
+	setModifierConvention(input) {
+		this._modifierConvention = resolveModifierConvention(input);
+	}
+	/** 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 — the canonical vocabulary from `@cssdoc/spec`. */
+	static standardTagNames = CSSDOC_TAG_NAMES;
+	/** A fresh set of the standard tag definitions (new instances on each call), built from the spec. */
+	static standardTags() {
+		return CSSDOC_TAGS.map((tag) => def({
+			tagName: tag.name,
+			syntaxKind: tag.kind,
+			...tag.recordKind ? { recordKind: tag.recordKind } : {},
+			...tag.aliasFor ? { aliasFor: tag.aliasFor } : {},
+			...tag.allowMultiple ? { allowMultiple: true } : {}
+		}));
+	}
+};
+//#endregion
+//#region src/grammar.ts
+/**
+* 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 canonical = link?.[1].replace(/^\./u, "").replace(/^\[/u, "").replace(/\]$/u, "");
+		const note = rawNote.replace(/\{@link\s+[^}]*\}/u, "").trim();
+		if (!note && !link) return { deprecatedFlag: true };
+		return {
+			deprecated: note || void 0,
+			deprecatedCanonical: canonical
+		};
+	}
+	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(), parse) {
+	const body = stripCommentFraming(raw);
+	const doc = {
+		modifiers: /* @__PURE__ */ new Map(),
+		parts: /* @__PURE__ */ new Map(),
+		tokens: /* @__PURE__ */ new Map(),
+		cssParts: /* @__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: [],
+		compat: [],
+		related: [],
+		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, parse);
+	}
+	return doc;
+}
+/** Apply one supported block tag (resolved to its canonical name) to the accumulating {@link ParsedDoc}. */
+function applyBlockTag(doc, canonical, tagName, rest, parse) {
+	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": {
+			const { description, css } = splitStructureBody(rest);
+			doc.structure = parseStructure(css, parse);
+			if (description) doc.structureDescription = description;
+			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 "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 ?? "");
+			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;
+		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);
+			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];
+}
+/**
+* Peel an optional leading prose description off a `@structure` body. The nested CSS begins at the
+* first line that opens a rule (contains `{`); any prose before it is the description. If the body
+* begins with a selector — including a multi-line selector like `.a,\n.b {` — there is no description
+* and the whole body is CSS.
+*
+* @param raw - The `@structure` body (description and/or nested CSS).
+* @returns The split `description` (when present) and the `css` to parse.
+*/
+function splitStructureBody(raw) {
+	const lines = raw.split("\n");
+	const braceLine = lines.findIndex((l) => l.includes("{"));
+	if (braceLine <= 0) return { css: raw };
+	const lead = lines.slice(0, braceLine);
+	if (/^\s*[.#:[*&>+~]/u.test(lead[0])) return { css: raw };
+	const description = lead.join("\n").trim();
+	return description ? {
+		description,
+		css: lines.slice(braceLine).join("\n")
+	} : { css: raw };
+}
+/**
+* Parse a `@structure` body — nested CSS (brace-delimited rules) — into a {@link StructureNode} tree.
+* Each rule's selector becomes a node; nested rules become its children. Because a node is a real
+* compound selector, `:has()` (contains), `:is()` / selector-lists (one-of), and `:not()` (not) express
+* relationships natively. Leaf nodes are written as empty rules (`.tab {}`). A malformed body parses to
+* an empty tree rather than throwing.
+*
+* @example
+* ```
+* .tabs {
+*   .list { .tab {} }
+*   .panel {}
+* }
+* ```
+*
+* @param raw - The nested-CSS structure body.
+* @param parse - The CSS parser to build the tree with (the same one `parseCssDocs` uses, or a dialect
+*   parser). Injected so this module carries no runtime CSS-parser dependency; without it the tree is empty.
+*/
+const CARDINALITY = {
+	optional: "optional",
+	opt: "optional",
+	many: "many",
+	"one-or-more": "one-or-more",
+	more: "one-or-more"
+};
+const CARD_RE = /:(optional|opt|one-or-more|more|many)\s*$/u;
+function parseStructure(raw, parse) {
+	if (!parse) return [];
+	const build = (nodes) => {
+		const out = [];
+		for (const rule of nodes) {
+			if (rule.type !== "rule") continue;
+			const selector = rule.selector.trim();
+			const card = selector.match(CARD_RE);
+			const node = {
+				selector: card ? selector.slice(0, card.index).trim() : selector,
+				children: build(rule.nodes ?? [])
+			};
+			if (card) node.cardinality = CARDINALITY[card[1]];
+			out.push(node);
+		}
+		return out;
+	};
+	try {
+		return build(parse(raw).nodes);
+	} catch {
+		return [];
+	}
+}
+//#endregion
+//#region src/mermaid.ts
+/** 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;
+/** 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, "&quot;");
+/** 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; 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 - {@link MermaidOptions}.
+* @returns Mermaid source, or an empty string when there are no nodes.
+*
+* @example
+* ```ts
+* toMermaid([{ selector: ".tabs", children: [{ selector: ".panel", cardinality: "many", children: [] }] }]);
+* // flowchart TD
+* //   n0[".tabs"]:::cssdoc-root
+* //   n1(".panel"):::cssdoc-part
+* //   n0 -->|0..n| n1
+* //   classDef cssdoc-root …
+* ```
+*/
+function toMermaid(roots, options = {}) {
+	if (!roots.length) return "";
+	const nodes = [];
+	const edges = [];
+	const links = [];
+	let counter = 0;
+	const walk = (node, isRoot) => {
+		const id = `n${counter++}`;
+		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, true);
+	return [
+		`flowchart ${options.direction ?? "TD"}`,
+		...nodes,
+		...edges,
+		...links,
+		...CLASS_DEFS.map((d) => `  ${d}`)
+	].join("\n");
+}
+//#endregion
+//#region src/lite.ts
+/**
+* Serialize a documentation model to pretty JSON (the raw, emitter-agnostic artifact — like TypeDoc's
+* `--json`).
+*
+* @param model - The entries from `parseCssDocs`.
+* @returns A JSON string.
+*/
+function toJson(model) {
+	return `${JSON.stringify(model, null, 2)}\n`;
+}
+//#endregion
+export { parseStructure as a, CssDocConfiguration as c, DEFAULT_STATE_PSEUDO_CLASSES as d, MODIFIER_PRESETS as f, parseDocComment as i, CssDocTagDefinition as l, resolveModifierConvention as m, toMermaid as n, recordNameOf as o, ModifierMatcher as p, RECORD_TAGS as r, stripCommentFraming as s, toJson as t, DEFAULT_MODIFIER_CONVENTION as u };