@cssdoc/core 0.1.0 → 0.3.0

package/dist/index.mjs

@@ -1,5 +1,332 @@
 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`, 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$1 = (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)
+			});
+		};
+		if (this.convention.structure === "suffix") {
+			const re = new RegExp(`\\.(${baseEsc}${this.sepAlt}[\\w-]+)`, "gu");
+			for (const m of selector.matchAll(re)) push(m[1]);
+			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]);
+		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") {
+			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$1(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}`;
+	}
+	/** 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$1(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 {
@@ -47,9 +374,18 @@ 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;
@@ -99,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
@@ -362,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:
@@ -420,12 +515,13 @@ 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 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: link?.[1]
+			deprecatedCanonical: canonical
 		};
 	}
 	return { description: description ?? "" };
@@ -444,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(),
@@ -503,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));
@@ -516,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({
@@ -601,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
@@ -649,16 +768,6 @@ function parseStructure(raw) {
 /** 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);
@@ -682,13 +791,12 @@ function collectFunction(node, acc) {
 	});
 }
 /** 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");
+function collect(nodes, acc, matcher, baseNoDot, prefixNoDot, inScope) {
 	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];
+			const dep = node.text.match(/@deprecated.*?use\s+(\.[\w-]+|\[[^\]]*\])/u);
+			if (dep) pendingCanonical = matcher.normalizeMember(dep[1]);
 			continue;
 		}
 		if (node.type === "decl") {
@@ -743,27 +851,51 @@ function collect(nodes, acc, baseEsc, prefixNoDot, inScope) {
 				type: "media",
 				query: node.params.trim()
 			});
-			if (node.nodes) collect(node.nodes, acc, baseEsc, prefixNoDot, inScope || node.name === "scope");
+			if (node.nodes) collect(node.nodes, acc, matcher, baseNoDot, 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] });
+				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, "");
-				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
+				const mods = matcher.modifiersIn(bare, baseNoDot);
+				const modNames = new Set(mods.map((mod) => mod.name));
+				for (const mod of mods) {
+					const entry = acc.modifiers.get(mod.name) ?? {
+						name: mod.name,
+						prop: mod.prop,
+						value: mod.value
 					};
 					if (pendingCanonical) entry.deprecated = { canonical: pendingCanonical };
-					acc.modifiers.set(modName, entry);
+					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;
 					if (prefixNoDot && part.startsWith(prefixNoDot)) continue;
 					if (!acc.parts.has(part)) acc.parts.set(part, { name: part });
 				}
@@ -775,7 +907,7 @@ function collect(nodes, acc, baseEsc, prefixNoDot, inScope) {
 }
 const byName = (a, b) => a.name.localeCompare(b.name);
 /** Build one entry from its record name, doc comment, and nodes. */
-function buildEntry(name, doc, nodes) {
+function buildEntry(name, doc, nodes, matcher) {
 	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));
@@ -788,6 +920,7 @@ function buildEntry(name, doc, nodes) {
 		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(),
@@ -796,7 +929,7 @@ function buildEntry(name, doc, nodes) {
 		layers: /* @__PURE__ */ new Map(),
 		conditions: []
 	};
-	collect(nodes, acc, className.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&"), className.endsWith(name) ? className.slice(1, className.length - name.length) : "", false);
+	collect(nodes, acc, matcher, className.replace(/^\./u, ""), 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 ? {
@@ -810,7 +943,7 @@ function buildEntry(name, doc, nodes) {
 				...dep
 			};
 		} else {
-			const { prop, value } = splitModifier(modName);
+			const { prop, value } = matcher.analyze(modName);
 			acc.modifiers.set(modName, {
 				name: modName,
 				prop,
@@ -828,11 +961,22 @@ function buildEntry(name, doc, nodes) {
 			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
 		});
 	}
@@ -893,7 +1037,11 @@ function buildEntry(name, doc, nodes) {
 		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,
@@ -907,6 +1055,7 @@ function buildEntry(name, doc, nodes) {
 		conditions: acc.conditions,
 		examples: doc.examples,
 		structure: doc.structure,
+		structureDescription: doc.structureDescription,
 		demo: doc.demo,
 		deprecated: doc.deprecated,
 		see: doc.see,
@@ -932,8 +1081,9 @@ function buildEntry(name, doc, nodes) {
 */
 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) {
@@ -951,7 +1101,7 @@ function parseCssDocs(css, options = {}) {
 		}
 		if (current) current.nodes.push(node);
 	}
-	return records.map((r) => buildEntry(r.name, r.doc, r.nodes));
+	return records.map((r) => buildEntry(r.name, r.doc, r.nodes, matcher));
 }
 //#endregion
 //#region src/mermaid.ts
@@ -1001,4 +1151,4 @@ function toJson(model) {
 	return `${JSON.stringify(model, null, 2)}\n`;
 }
 //#endregion
-export { CssDocConfiguration, CssDocTagDefinition, RECORD_TAGS, parseCssDocs, parseDocComment, parseStructure, recordNameOf, 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 };