@cssdoc/core 0.2.0 → 0.3.0

package/dist/index.mjs

@@ -1,11 +1,35 @@
 import postcss from "postcss";
+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`. The default. */
+	/** 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`. */
@@ -39,6 +63,9 @@ function resolveModifierConvention(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 ?? "-"
 	};
@@ -54,10 +81,45 @@ const unquote$1 = (v) => v.trim().replace(/^(["'])([\s\S]*)\1$/u, "$2");
 */
 var ModifierMatcher = class {
 	convention;
-	sepEsc;
+	/** 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;
-		this.sepEsc = escapeRe(convention.separator);
+		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
@@ -76,7 +138,7 @@ var ModifierMatcher = class {
 			});
 		};
 		if (this.convention.structure === "suffix") {
-			const re = new RegExp(`\\.(${baseEsc}${this.sepEsc}[\\w-]+)`, "gu");
+			const re = new RegExp(`\\.(${baseEsc}${this.sepAlt}[\\w-]+)`, "gu");
 			for (const m of selector.matchAll(re)) push(m[1]);
 			return hits;
 		}
@@ -88,12 +150,93 @@ var ModifierMatcher = class {
 			}
 			return hits;
 		}
-		const cls = `\\.${this.sepEsc}[\\w-]+`;
+		const cls = `\\.${this.sepAlt}[\\w-]+`;
 		const chain = new RegExp(`(?:\\.${baseEsc}|:scope)((?:${cls})+)`, "gu");
-		const inner = new RegExp(`\\.(${this.sepEsc}[\\w-]+)`, "gu");
-		for (const m of selector.matchAll(chain)) for (const c of m[1].matchAll(inner)) push(c[1]);
+		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]);
 		return hits;
 	}
+	/**
+	* 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 (this.convention.structure === "attribute") {
@@ -101,15 +244,11 @@ var ModifierMatcher = class {
 			const eq = canonical.indexOf("=");
 			const attr = eq === -1 ? canonical : canonical.slice(0, eq);
 			return {
-				prop: attr.startsWith(this.convention.separator) ? attr.slice(this.convention.separator.length) : attr,
+				prop: this.stripPrefix(attr),
 				value: eq === -1 ? void 0 : unquote$1(canonical.slice(eq + 1))
 			};
 		}
-		let body;
-		if (this.convention.structure === "suffix") {
-			const at = name.indexOf(this.convention.separator);
-			body = at === -1 ? name : name.slice(at + this.convention.separator.length);
-		} else body = this.convention.separator && name.startsWith(this.convention.separator) ? name.slice(this.convention.separator.length) : name;
+		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);
@@ -138,12 +277,25 @@ var ModifierMatcher = class {
 	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 name.startsWith(`${baseNoDot}${this.convention.separator}`);
-			return this.convention.separator !== "" && name.includes(this.convention.separator);
+			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 name.startsWith(this.convention.separator);
+		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) {
@@ -152,15 +304,29 @@ var ModifierMatcher = class {
 		if (eq === -1) return trimmed;
 		return `${trimmed.slice(0, eq + 1)}"${unquote$1(trimmed.slice(eq + 1))}"`;
 	}
-	/** Does an attribute-expression's name carry the convention's required prefix? */
+	/** 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 && attr.startsWith(this.convention.separator);
+		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 {
@@ -269,258 +435,17 @@ var CssDocConfiguration = class CssDocConfiguration {
 	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). */
+	/** 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 [
-			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"
-			})
-		];
+		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
@@ -532,9 +457,9 @@ var CssDocConfiguration = class CssDocConfiguration {
 * 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
+* The grammar is specified formally in `@cssdoc/spec`'s `grammar/CssDoc.grammarkdown` (RFC-style,
+* modeling TSDoc's `DeclarationReference.grammarkdown`); the functions here are hand-written to conform
+* to those productions, and a test in `@cssdoc/spec` keeps the spec valid. Which tags are active — and which
 * custom tags to capture — is governed by a {@link CssDocConfiguration}.
 *
 * A block looks like:
@@ -615,6 +540,7 @@ function parseDocComment(raw, configuration = new CssDocConfiguration()) {
 	const doc = {
 		modifiers: /* @__PURE__ */ new Map(),
 		parts: /* @__PURE__ */ new Map(),
+		cssParts: /* @__PURE__ */ new Map(),
 		cssProperties: [],
 		cssStates: /* @__PURE__ */ new Map(),
 		slots: /* @__PURE__ */ new Map(),
@@ -674,9 +600,12 @@ function applyBlockTag(doc, canonical, tagName, rest) {
 		case "a11y":
 			doc.accessibility = rest.trim();
 			break;
-		case "structure":
-			doc.structure = parseStructure(rest);
+		case "structure": {
+			const { description, css } = splitStructureBody(rest);
+			doc.structure = parseStructure(css);
+			if (description) doc.structureDescription = description;
 			break;
+		}
 		case "modifier": {
 			const { head, description } = splitDesc(rest);
 			doc.modifiers.set(head.replace(/^\./u, ""), parseModifierBody(description));
@@ -687,6 +616,11 @@ function applyBlockTag(doc, canonical, tagName, rest) {
 			doc.parts.set(head.replace(/^\./u, ""), 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({
@@ -772,37 +706,51 @@ function recordNameOf(commentText, configuration) {
 	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.
+* 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
+* .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
-		});
+	const build = (nodes) => nodes.filter((n) => n.type === "rule").map((rule) => ({
+		selector: rule.selector.trim(),
+		children: build(rule.nodes ?? [])
+	}));
+	try {
+		return build(postcss.parse(raw).nodes);
+	} catch {
+		return [];
 	}
-	return roots;
 }
 //#endregion
 //#region src/parse.ts
@@ -908,7 +856,15 @@ function collect(nodes, acc, matcher, baseNoDot, prefixNoDot, inScope) {
 		}
 		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] });
+				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],
+					kind: "custom"
+				});
+				for (const ps of matcher.pseudoStatesIn(selector)) if (!acc.states.has(ps.name)) acc.states.set(ps.name, {
+					name: ps.name,
+					kind: "pseudo-class"
+				});
+				for (const sp of selector.matchAll(/::part\(\s*([\w-]+)\s*\)/gu)) if (!acc.shadowParts.has(sp[1])) acc.shadowParts.set(sp[1], { name: sp[1] });
 				const bare = selector.replace(/::?[\w-]+(\([^)]*\))?/gu, "");
 				const mods = matcher.modifiersIn(bare, baseNoDot);
 				const modNames = new Set(mods.map((mod) => mod.name));
@@ -921,6 +877,22 @@ function collect(nodes, acc, matcher, baseNoDot, prefixNoDot, inScope) {
 					if (pendingCanonical) entry.deprecated = { canonical: pendingCanonical };
 					acc.modifiers.set(mod.name, entry);
 				}
+				for (const el of matcher.elementsIn(bare, baseNoDot)) {
+					const part = acc.parts.get(el.name) ?? { name: el.name };
+					for (const m of el.modifiers) {
+						part.modifiers ??= [];
+						if (!part.modifiers.some((x) => x.name === m.name)) part.modifiers.push({
+							name: m.name,
+							prop: m.prop,
+							value: m.value
+						});
+					}
+					acc.parts.set(el.name, part);
+				}
+				for (const st of matcher.statesIn(bare, baseNoDot)) if (!acc.states.has(st.name)) acc.states.set(st.name, {
+					name: st.name,
+					kind: "class"
+				});
 				if (inScope) for (const m of bare.matchAll(/\.([a-z][\w-]*)/gu)) {
 					const part = m[1];
 					if (modNames.has(part)) continue;
@@ -948,6 +920,7 @@ function buildEntry(name, doc, nodes, matcher) {
 		className,
 		modifiers: /* @__PURE__ */ new Map(),
 		parts: /* @__PURE__ */ new Map(),
+		shadowParts: /* @__PURE__ */ new Map(),
 		states: /* @__PURE__ */ new Map(),
 		consumed: /* @__PURE__ */ new Set(),
 		declared: /* @__PURE__ */ new Map(),
@@ -988,11 +961,22 @@ function buildEntry(name, doc, nodes, matcher) {
 			description
 		});
 	}
-	for (const [state, description] of doc.cssStates) {
+	for (const [part, description] of doc.cssParts) {
+		const existing = acc.shadowParts.get(part);
+		if (existing) existing.description = description || existing.description;
+		else acc.shadowParts.set(part, {
+			name: part,
+			description: description || void 0
+		});
+	}
+	for (const [rawState, description] of doc.cssStates) {
+		const isPseudo = rawState.startsWith(":");
+		const state = isPseudo ? rawState.slice(1) : rawState;
 		const existing = acc.states.get(state);
 		if (existing) existing.description = description || existing.description;
 		else acc.states.set(state, {
 			name: state,
+			kind: isPseudo ? "pseudo-class" : "custom",
 			description: description || void 0
 		});
 	}
@@ -1053,7 +1037,11 @@ function buildEntry(name, doc, nodes, matcher) {
 		group: doc.group,
 		accessibility: doc.accessibility,
 		modifiers,
-		parts: [...acc.parts.values()].sort(byName),
+		parts: [...acc.parts.values()].sort(byName).map((p) => p.modifiers ? {
+			...p,
+			modifiers: [...p.modifiers].sort(byName)
+		} : p),
+		shadowParts: [...acc.shadowParts.values()].sort(byName),
 		states: [...acc.states.values()].sort(byName),
 		slots: [...doc.slots].map(([slotName, description]) => ({
 			name: slotName,
@@ -1067,6 +1055,7 @@ function buildEntry(name, doc, nodes, matcher) {
 		conditions: acc.conditions,
 		examples: doc.examples,
 		structure: doc.structure,
+		structureDescription: doc.structureDescription,
 		demo: doc.demo,
 		deprecated: doc.deprecated,
 		see: doc.see,
@@ -1094,7 +1083,7 @@ function parseCssDocs(css, options = {}) {
 	const configuration = options.configuration ?? new CssDocConfiguration();
 	const matcher = new ModifierMatcher(resolveModifierConvention(options.modifierConvention ?? configuration.modifierConvention));
 	const boundary = options.isRecordBoundary ?? ((text) => recordNameOf(text, configuration));
-	const root = postcss.parse(css);
+	const root = (options.parse ?? postcss.parse)(css);
 	const records = [];
 	let current = null;
 	for (const node of root.nodes) {
@@ -1162,4 +1151,4 @@ function toJson(model) {
 	return `${JSON.stringify(model, null, 2)}\n`;
 }
 //#endregion
-export { CssDocConfiguration, CssDocTagDefinition, DEFAULT_MODIFIER_CONVENTION, MODIFIER_PRESETS, ModifierMatcher, RECORD_TAGS, parseCssDocs, parseDocComment, parseStructure, recordNameOf, resolveModifierConvention, stripCommentFraming, toJson, toMermaid };
+export { CssDocConfiguration, CssDocTagDefinition, DEFAULT_MODIFIER_CONVENTION, DEFAULT_STATE_PSEUDO_CLASSES, MODIFIER_PRESETS, ModifierMatcher, RECORD_TAGS, parseCssDocs, parseDocComment, parseStructure, recordNameOf, resolveModifierConvention, stripCommentFraming, toJson, toMermaid };