@cssdoc/core 0.1.0 → 0.2.0

package/dist/index.d.mts

@@ -1,3 +1,116 @@
+//#region src/modifier.d.ts
+/**
+ * The modifier convention — how a component's modifier variations are spelled in CSS, and the one
+ * place that spelling is turned into (and back out of) selectors. cssdoc is framework-agnostic, so it
+ * doesn't assume any single scheme: BEM (`.button--primary`, the default), rscss (`.button.-color-x`),
+ * bare/OOCSS chained classes (`.button.primary`), CUBE data-attribute exceptions
+ * (`.card[data-variant="ghost"]`), and anything expressible as the three structural forms below.
+ *
+ * {@link ModifierMatcher} is the single owner of modifier matching, prop/value analysis, and
+ * selector rendering — both `parse.ts` and `index.ts` route through it, so their notions of "what is a
+ * modifier" can't drift.
+ *
+ * @module
+ */
+/**
+ * How a modifier attaches to a component's base class.
+ *
+ * - `chained` — a separate class on the base element: `.base.primary` (bare/OOCSS), `.base.-mod`
+ *   (rscss), `.base.is-open` (state). `separator` is the required class prefix (`""` = any chained
+ *   class, `-`, `is-`).
+ * - `suffix` — appended into the base class name itself: `.button--primary` (BEM/SUIT). `separator` is
+ *   the delimiter between the base and the modifier body (`--`).
+ * - `attribute` — an attribute selector on the base element: `.card[data-variant="ghost"]` (CUBE).
+ *   `separator` is the required attribute-name prefix (`data-`; `""` = any attribute).
+ */
+interface ModifierConvention {
+  /** The structural form. An open union — further forms may be added without a breaking change. */
+  structure: "chained" | "suffix" | "attribute";
+  /** The prefix/delimiter, interpreted per {@link ModifierConvention.structure}. */
+  separator: string;
+  /**
+   * Split the modifier body into `prop`/`value` on {@link ModifierConvention.propValueSeparator}?
+   * Defaults to `false`. Ignored for `attribute` (which always derives `prop` from the attribute name
+   * and `value` from the attribute value).
+   */
+  propValue?: boolean;
+  /** The separator for the `prop`/`value` split. Defaults to `-`. */
+  propValueSeparator?: string;
+}
+/** The built-in convention presets. Other schemes use the custom object (see the docs). */
+declare const MODIFIER_PRESETS: {
+  /** BEM / SUIT — `.button--primary`. The default. */readonly bem: {
+    readonly structure: "suffix";
+    readonly separator: "--";
+    readonly propValue: false;
+  }; /** rscss — `.button.-color-secondary`, split into `prop`/`value`. */
+  readonly rscss: {
+    readonly structure: "chained";
+    readonly separator: "-";
+    readonly propValue: true;
+    readonly propValueSeparator: "-";
+  }; /** OOCSS / bare chained classes — `.button.primary` (any class chained to the base). */
+  readonly bare: {
+    readonly structure: "chained";
+    readonly separator: "";
+    readonly propValue: false;
+  };
+};
+/** A preset name, or a full custom {@link ModifierConvention}. */
+type ModifierConventionInput = keyof typeof MODIFIER_PRESETS | ModifierConvention;
+/** The default convention: BEM. */
+declare const DEFAULT_MODIFIER_CONVENTION: ModifierConvention;
+/**
+ * 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.
+ */
+declare function resolveModifierConvention(input?: ModifierConventionInput): ModifierConvention;
+/** One modifier found on a selector: its canonical name plus the derived `prop`/`value`. */
+interface ModifierHit {
+  /** The modifier as written, minus outer punctuation — `button--primary`, `-color-secondary`,
+   *  `primary`, or `data-variant="ghost"`. Render it back with {@link ModifierMatcher.selectorFor}. */
+  name: string;
+  /** The property segment (a grouping key). */
+  prop: string;
+  /** The value segment; absent for boolean modifiers. */
+  value?: string;
+}
+/**
+ * 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.
+ */
+declare class ModifierMatcher {
+  readonly convention: ModifierConvention;
+  private readonly sepEsc;
+  constructor(convention: ModifierConvention);
+  /**
+   * 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: string, baseNoDot: string): ModifierHit[];
+  /** Derive `prop`/`value` for a modifier `name` (as returned by {@link modifiersIn} or authored). */
+  analyze(name: string): {
+    prop: string;
+    value?: string;
+  };
+  /** Render a modifier `name` as the selector fragment it denotes (`.name` or `[name]`). */
+  selectorFor(name: string): string;
+  /** Normalize a member token/expression to its canonical `name` key (the inverse of authoring noise). */
+  normalizeMember(token: string): string;
+  /**
+   * 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: string, baseNoDot?: string): boolean;
+  /** Canonicalize an attribute expression (bracket-inner): normalize quotes to double, trim. */
+  private normalizeAttribute;
+  /** Does an attribute-expression's name carry the convention's required prefix? */
+  private attributeMatches;
+}
+//#endregion
 //#region src/configuration.d.ts
 /**
  * The syntactic kind of a tag, mirroring TSDoc's Block/Modifier/Inline split, plus cssdoc's own
@@ -49,7 +162,12 @@ declare class CssDocConfiguration {
   private readonly _tagDefinitions;
   private readonly _byName;
   private readonly _supported;
+  private _modifierConvention;
   constructor();
+  /** The resolved modifier convention this configuration parses with (defaults to BEM). */
+  get modifierConvention(): ModifierConvention;
+  /** Set the modifier convention from a preset name or a custom {@link ModifierConvention}. */
+  setModifierConvention(input: ModifierConventionInput): void;
   /** Every registered tag definition, in registration order. */
   get tagDefinitions(): readonly CssDocTagDefinition[];
   /** Only the tag definitions that are currently supported. */
@@ -93,13 +211,20 @@ declare class CssDocConfiguration {
  *
  * @module
  */
-/** A `-<prop>-<value>` (or boolean `-<flag>`) modifier on a component's base class. */
+/**
+ * A modifier variation on a component's base class. How modifiers are spelled is configurable (see
+ * {@link ParseOptions.modifierConvention}); the default is BEM (`.button--primary`).
+ */
 interface CssModifier {
-  /** The modifier class without the leading dot, e.g. `-color-secondary` or `-condensed`. */
+  /**
+   * The modifier as written, minus its outer punctuation — its exact spelling depends on the
+   * convention: `button--primary` (BEM, the default), `-color-secondary` (rscss), `primary`
+   * (bare/OOCSS), or `data-variant="ghost"` (CUBE attribute).
+   */
   name: string;
-  /** The property segment, e.g. `color` (the text after the first `-`, up to the next `-`). */
+  /** The property segment — a grouping key derived from the modifier (e.g. `color`, `variant`, `primary`). */
   prop: string;
-  /** The value segment, e.g. `secondary`; absent for boolean modifiers. */
+  /** The value segment, e.g. `secondary` or `ghost`; absent for boolean/flag modifiers. */
   value?: string;
   /** Prose from a `@modifier` doc tag, when authored. */
   description?: string;
@@ -277,6 +402,12 @@ interface ParseOptions {
    * Supply one (e.g. from `@cssdoc/config`) to register custom tags or disable standard ones.
    */
   configuration?: CssDocConfiguration;
+  /**
+   * The modifier convention — how modifier classes are spelled (BEM `.button--primary` by default;
+   * `rscss`, `bare`, or a custom {@link import("./modifier.ts").ModifierConvention} for SUIT/CUBE/etc.).
+   * Overrides the `configuration`'s convention when both are given.
+   */
+  modifierConvention?: ModifierConventionInput;
 }
 //#endregion
 //#region src/parse.d.ts
@@ -454,4 +585,4 @@ declare function toMermaid(roots: StructureNode[], options?: {
  */
 declare function toJson(model: CssDocEntry[]): string;
 //#endregion
-export { type CssAnimation, type CssCondition, CssDocConfiguration, type CssDocEntry, type CssDocSyntaxKind, CssDocTagDefinition, type CssDocTagDefinitionOptions, type CssFunction, type CssLayer, type CssModifier, type CssPart, type CssPropertyDeclared, type CssRecordKind, type CssReleaseStage, type CssSlot, type CssState, type DocCondition, type DocCssProperty, type DocModifier, type ParseOptions, type ParsedDoc, RECORD_TAGS, type StructureNode, parseCssDocs, parseDocComment, parseStructure, recordNameOf, stripCommentFraming, toJson, toMermaid };
+export { type CssAnimation, type CssCondition, CssDocConfiguration, type CssDocEntry, type CssDocSyntaxKind, CssDocTagDefinition, type CssDocTagDefinitionOptions, type CssFunction, type CssLayer, type CssModifier, type CssPart, type CssPropertyDeclared, type CssRecordKind, type CssReleaseStage, type CssSlot, type CssState, DEFAULT_MODIFIER_CONVENTION, type DocCondition, type DocCssProperty, type DocModifier, MODIFIER_PRESETS, type ModifierConvention, type ModifierConventionInput, type ModifierHit, ModifierMatcher, type ParseOptions, type ParsedDoc, RECORD_TAGS, type StructureNode, parseCssDocs, parseDocComment, parseStructure, recordNameOf, resolveModifierConvention, stripCommentFraming, toJson, toMermaid };

package/dist/index.mjs

@@ -1,4 +1,165 @@
 import postcss from "postcss";
+//#region src/modifier.ts
+/** The built-in convention presets. Other schemes use the custom object (see the docs). */
+const MODIFIER_PRESETS = {
+	/** BEM / SUIT — `.button--primary`. The default. */
+	bem: {
+		structure: "suffix",
+		separator: "--",
+		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,
+		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;
+	sepEsc;
+	constructor(convention) {
+		this.convention = convention;
+		this.sepEsc = escapeRe(convention.separator);
+	}
+	/**
+	* 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.sepEsc}[\\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.sepEsc}[\\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]);
+		return hits;
+	}
+	/** 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: attr.startsWith(this.convention.separator) ? attr.slice(this.convention.separator.length) : 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;
+		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.convention.structure === "suffix") {
+			if (baseNoDot) return name.startsWith(`${baseNoDot}${this.convention.separator}`);
+			return this.convention.separator !== "" && name.includes(this.convention.separator);
+		}
+		if (baseNoDot && name === baseNoDot) return false;
+		return name.startsWith(this.convention.separator);
+	}
+	/** 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 the convention's required prefix? */
+	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);
+	}
+};
+//#endregion
 //#region src/configuration.ts
 const TAG_NAME_RE = /^@?[a-zA-Z][a-zA-Z0-9-]*$/u;
 /** One tag in the vocabulary: its name, kind, and how it may be used. */
@@ -47,9 +208,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;
@@ -420,12 +590,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 ?? "" };
@@ -649,16 +820,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 +843,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 +903,27 @@ 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] });
 				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);
 				}
 				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 +935,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));
@@ -796,7 +956,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 +970,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,
@@ -932,6 +1092,7 @@ 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 records = [];
@@ -951,7 +1112,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 +1162,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, MODIFIER_PRESETS, ModifierMatcher, RECORD_TAGS, parseCssDocs, parseDocComment, parseStructure, recordNameOf, resolveModifierConvention, stripCommentFraming, toJson, toMermaid };

package/grammar/CssDoc.grammarkdown

@@ -81,12 +81,28 @@ Identifier ::
 RecordName ::
     Identifier
 
-// A `-<prop>` boolean modifier, or a `-<prop>-<value>` modifier. `Prop` is the segment up to the
-// first interior hyphen; `Value` is the remainder (which may itself contain hyphens).
+// How a modifier is spelled is configurable (see the `ModifierConvention` in `@cssdoc/core`); the
+// DEFAULT is BEM — the modifier is conjoined onto the base class with `--`, e.g. `.button--primary`.
+// Other conventions:
+//   rscss       — `.button.-color-secondary` (a chained `-`-prefixed class, split into Prop/Value)
+//   bare / OOCSS — `.button.primary`          (any class chained to the base)
+//   CUBE        — `.card[data-variant="ghost"]` (a data-attribute exception on the base)
+// The default (BEM) form:
 ModifierName ::
+    Identifier `--` Identifier
+
+// The rscss form: a `-<prop>` boolean modifier, or a `-<prop>-<value>` modifier. `Prop` is the segment
+// up to the first interior hyphen; `Value` is the remainder (which may itself contain hyphens).
+RscssModifierName ::
     `-` Prop
     `-` Prop `-` Value
 
+// The CUBE form: an attribute-selector exception on the base, e.g. `[data-variant="ghost"]`. The
+// value is a quoted string; shown here as an identifier for brevity.
+AttributeModifier ::
+    `[` Identifier `]`
+    `[` Identifier `=` Identifier `]`
+
 Prop ::
     > an identifier segment of letters and digits, containing no hyphen
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cssdoc/core",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "A generic CSS documentation extractor: parse doc-comments + the CSS AST into a serializable model (TSDoc, for CSS).",
   "keywords": [
     "css",