@cssdoc/core 0.4.1 → 0.5.0

package/dist/lite-BJ1h869i.d.mts

@@ -0,0 +1,749 @@
+//#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}. May be a single
+   * string or several — any one of which marks a modifier. Separators are matched literally.
+   */
+  separator: string | string[];
+  /**
+   * The delimiter that marks a **BEM-style element** inside the base class name (e.g. `"__"` in
+   * `.block__element`). When set (`suffix` structure only), a matching class is recorded as a
+   * {@link https://cssdoc.dev part} rather than a modifier. Its own modifiers
+   * (`.block__element--mod`) are captured as part of the element name for now.
+   */
+  elementSeparator?: string | string[];
+  /**
+   * Class prefixes that mark a **state** rather than a modifier (e.g. `["is-", "has-"]`). A class
+   * chained to the base whose name starts with one of these is recorded as a state, and is never
+   * treated as a modifier. Opt-in; no preset sets it by default.
+   */
+  statePrefixes?: string[];
+  /**
+   * Native pseudo-classes (without the `:`) to recognize as states when they appear on the base,
+   * e.g. `["disabled", "checked"]`. Defaults to {@link DEFAULT_STATE_PSEUDO_CLASSES} — a curated set
+   * of form/UI states, deliberately excluding ubiquitous interaction pseudos (`:hover`, `:focus`).
+   */
+  statePseudoClasses?: 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 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.
+ */
+declare const DEFAULT_STATE_PSEUDO_CLASSES: readonly string[];
+/** The built-in convention presets. Other schemes use the custom object (see the docs). */
+declare const MODIFIER_PRESETS: {
+  /** BEM / SUIT — `.button--primary`, with `.button__element` sub-elements. The default. */readonly bem: {
+    readonly structure: "suffix";
+    readonly separator: "--";
+    readonly elementSeparator: "__";
+    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;
+  /** Set when the name is a `*` family (e.g. `-icon-*`, derived from a `[class*="-icon-"]` selector). */
+  pattern?: boolean;
+}
+/**
+ * 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;
+  /** The separator(s), longest-first so overlapping prefixes (e.g. `--` before `-`) match greedily. */
+  private readonly separators;
+  /** The separators as a non-capturing regex alternation, e.g. `(?:is-|has-)` (or `(?:)` when empty). */
+  private readonly sepAlt;
+  /** BEM-style element separators (longest-first), or empty when the convention has none. */
+  private readonly elementSeparators;
+  /** The element separators as a non-capturing alternation, or `""` when there are none. */
+  private readonly elementSepAlt;
+  /** State-class prefixes (longest-first), or empty when the convention has none. */
+  private readonly statePrefixes;
+  /** Native pseudo-classes (no `:`) recognized as states. */
+  private readonly statePseudoClasses;
+  constructor(convention: ModifierConvention);
+  /** Does a class name (no leading dot) start with one of the convention's state prefixes? */
+  private isStateClass;
+  /** Strip a leading chained-class separator from `name` (the longest that matches), else return it. */
+  private stripPrefix;
+  /** Return the suffix body — the part after the first (longest) non-empty separator occurrence. */
+  private stripToBody;
+  /**
+   * 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[];
+  /**
+   * 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.
+   */
+  private classAttrFamilies;
+  /** Derive a modifier name from a `[class OP value]` selector, or `undefined` when it isn't one. */
+  private classAttrFamily;
+  /**
+   * 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: string, baseNoDot: string): {
+    name: string;
+    modifiers: ModifierHit[];
+  }[];
+  /**
+   * 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.
+   */
+  private splitElementModifier;
+  /**
+   * 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: string, baseNoDot: string): {
+    name: string;
+  }[];
+  /**
+   * 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: string): {
+    name: string;
+  }[];
+  /** 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;
+  /**
+   * 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: string, used: string): boolean;
+  /** 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;
+  /**
+   * 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: string, baseNoDot?: string): "modifier" | "state" | "element" | undefined;
+  /** Canonicalize an attribute expression (bracket-inner): normalize quotes to double, trim. */
+  private normalizeAttribute;
+  /** Does an attribute-expression's name carry one of the convention's required prefixes? */
+  private attributeMatches;
+}
+//#endregion
+//#region src/model.d.ts
+/**
+ * The serializable CSS-documentation model — the output-agnostic IR produced by {@link parseCssDocs}.
+ * Emitters (markdown, JSON, …) consume this; it carries no assumptions about any particular project,
+ * class prefix, or output format.
+ *
+ * The model documents the modern CSSOM surface a stylesheet exposes: modifiers and parts, registered
+ * custom properties (`@property`), custom functions (`@function`), animations (`@keyframes`), cascade
+ * layers (`@layer`), conditional-support blocks (`@container`/`@supports`/`@media`), states, and slots.
+ * Facts that can be derived from the CSS AST are derived (so they can't drift); doc-comment tags supply
+ * the prose.
+ *
+ * @module
+ */
+/**
+ * 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 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 — a grouping key derived from the modifier (e.g. `color`, `variant`, `primary`). */
+  prop: string;
+  /** The value segment, e.g. `secondary` or `ghost`; absent for boolean/flag modifiers. */
+  value?: string;
+  /**
+   * Set when this is a `*` family (e.g. `-icon-*`) rather than a single modifier — authored as
+   * `@modifier -icon-*` and/or derived from a `[class*="-icon-"]` selector. Concrete usages
+   * (`-icon-arrow`) are matched against it as instances.
+   */
+  pattern?: boolean;
+  /** Prose from a `@modifier` doc tag, when authored. */
+  description?: string;
+  /**
+   * Set when the modifier is deprecated. `canonical` (from an AST alias marker) is the modifier class
+   * to use instead; `note` (from an authored inline deprecation tag on the `@modifier` line) is
+   * free-text replacement guidance for cases where the replacement isn't itself a modifier.
+   */
+  deprecated?: {
+    canonical?: string;
+    note?: string;
+  };
+}
+/** A sub-element ("part") of a component — a scoped child class like `.item` or `.tip`. */
+interface CssPart {
+  /** The part class without the leading dot, e.g. `item`. */
+  name: string;
+  /** Prose from a `@part` doc tag, when authored. */
+  description?: string;
+  /** The part's own modifiers, e.g. `.block__element--active` on a BEM element. Present when non-empty. */
+  modifiers?: CssModifier[];
+}
+/**
+ * How a component state is spelled — the CSSOM custom state `:state(x)`, a native pseudo-class
+ * (`:disabled`), or a state class from the convention's `statePrefixes` (`.is-open`). Only `custom`
+ * maps to a Custom Elements Manifest `cssStates` entry.
+ */
+type CssStateKind = "custom" | "pseudo-class" | "class";
+/** A component state — from `:state()`, a native pseudo-class, or a state class (`@cssstate`). */
+interface CssState {
+  /** The state name without its punctuation, e.g. `open`, `selected`, or `disabled`. */
+  name: string;
+  /** How the state is expressed in CSS. */
+  kind: CssStateKind;
+  /** Prose from a `@cssstate` doc tag, when authored. */
+  description?: string;
+}
+/** A named slot a component shell exposes (`@slot`, Custom Elements Manifest). */
+interface CssSlot {
+  /** The slot name (empty string for the default slot). */
+  name: string;
+  /** Prose from a `@slot` doc tag, when authored. */
+  description?: string;
+}
+/** A custom property the component declares (`@property`) or documents (`@cssproperty`). */
+interface CssPropertyDeclared {
+  /** The custom-property name, e.g. `--value`. */
+  name: string;
+  /** The `@property` `syntax` descriptor, e.g. `<number>`, when known. */
+  syntax?: string;
+  /** The `@property` `inherits` flag, when declared. */
+  inherits?: boolean;
+  /** The default value (`@property` `initial-value`, or an authored `@defaultValue`), when known. */
+  defaultValue?: string;
+  /** Prose from a `@cssproperty` doc tag, when authored. */
+  description?: string;
+}
+/** A CSS custom function (`@function --name`) the stylesheet defines. */
+interface CssFunction {
+  /** The function name, e.g. `--negate`. */
+  name: string;
+  /** The declared parameters, e.g. `["--value"]`, when derivable from the `@function` at-rule. */
+  parameters: string[];
+  /** The `result` descriptor/type, when declared. */
+  result?: string;
+  /** Prose from a `@function` doc tag, when authored. */
+  description?: string;
+}
+/** An animation the component exposes (`@keyframes` at-rule / `@animation` doc tag). */
+interface CssAnimation {
+  /** The animation (keyframes) name. */
+  name: string;
+  /** Prose from an `@animation`/`@keyframes` doc tag, when authored. */
+  description?: string;
+}
+/** A cascade layer the stylesheet participates in (`@layer`). */
+interface CssLayer {
+  /** The layer name, possibly dotted (e.g. `theme.dark`). */
+  name: string;
+  /** Prose from a `@layer` doc tag, when authored. */
+  description?: string;
+}
+/** A conditional-support block the component's rules sit under. */
+interface CssCondition {
+  /** Which at-rule expressed the condition. */
+  type: "container" | "supports" | "media";
+  /** The condition text, e.g. `(min-width: 40rem)` or `(display: grid)`. */
+  query: string;
+  /** A container name, for `@container` blocks that target a named container. */
+  containerName?: string;
+  /** Prose from a `@container`/`@supports`/`@media`/`@responsive` doc tag, when authored. */
+  description?: string;
+}
+/**
+ * What kind of CSS surface a record documents. `component` is a namespaced component class with
+ * `-modifier`s and parts; `utility` a single-purpose class family; `rule` bare-element/reset styling;
+ * `declaration` a custom-property / `@property` registration layer. The record-opening tag chooses it
+ * (`@component`/`@utility`/`@rule`/`@declaration`); `@name` is an alias for `component`.
+ */
+type CssRecordKind = "component" | "utility" | "rule" | "declaration";
+/**
+ * A release stage from a modifier (flag) tag — `@alpha`, `@beta`, `@experimental`, `@internal`, or
+ * `@public` — mirroring TSDoc's release-tag semantics.
+ */
+type CssReleaseStage = "alpha" | "beta" | "experimental" | "internal" | "public";
+/**
+ * A node in an authored structure tree (`@structure`), written as nested CSS: a compound selector for
+ * the element and its children (the rules nested inside it). Emitters render the tree and, via
+ * {@link toMermaid}, a diagram.
+ */
+interface StructureNode {
+  /** The node's compound selector, e.g. `.tabs`, `.tab.-selected`, or `.list:has(.tab)`. */
+  selector: string;
+  /**
+   * How often the child may appear, from a trailing pseudo on the selector: `:optional`/`:opt` (0..1),
+   * `:many` (0..n), or `:one-or-more`/`:more` (1..n). Absent means the child is required (present when
+   * the component is used). A pseudo, not a `/* … *\/` comment, because `@structure` lives inside a doc
+   * comment where comments can't nest; an unknown pseudo is valid selector syntax and is stripped from
+   * the stored selector.
+   */
+  cardinality?: "optional" | "many" | "one-or-more";
+  /** Child nodes (rules nested one brace level deeper). */
+  children: StructureNode[];
+}
+/**
+ * A design token the component consumes via `var(--*)`. The set is derived from the CSS; an authored
+ * `@tokens` tag annotates one with prose (and may add a token not literally found via `var()`). Type and
+ * resolved value are not modeled here — an emitter resolves them via its own token source (e.g. a
+ * `resolveToken` hook).
+ */
+interface CssTokenConsumed {
+  /** The custom-property name, e.g. `--color-primary`. */
+  name: string;
+  /** Prose from an `@tokens` doc tag, when authored. */
+  description?: string;
+}
+/** A related component cross-reference (`@related`). */
+interface CssRelated {
+  /** The related record's name, e.g. `card`. */
+  name: string;
+  /** Prose from the `@related` tag, when authored. */
+  description?: string;
+}
+/** Where a record was authored, for source links. Positions are 1-based, matching PostCSS. */
+interface CssSource {
+  /** The file the record was parsed from, when {@link ParseOptions.fileName} was supplied. */
+  file?: string;
+  /** The 1-based line of the record's opening doc comment. */
+  line?: number;
+  /** The 1-based column of the record's opening doc comment. */
+  column?: number;
+}
+/** One documented CSS record: its base class plus everything derived from the CSS + doc comments. */
+interface CssDocEntry {
+  /** The record name from `@component`/`@utility`/`@rule`/`@declaration`/`@name`, e.g. `button`. */
+  name: string;
+  /** Which kind of CSS surface this documents (defaults to `component`). */
+  kind: CssRecordKind;
+  /** The base class selector, e.g. `.button` (inferred from the first bare-class rule). */
+  className: string;
+  /** One-line summary from `@summary`. */
+  summary?: string;
+  /** Extended prose from `@remarks`. */
+  remarks?: string;
+  /** Internal-only prose from `@privateRemarks` (emitters may choose to omit it from public output). */
+  privateRemarks?: string;
+  /** The release stage from a modifier flag tag (`@alpha`/`@beta`/`@experimental`/`@internal`/`@public`). */
+  releaseStage?: CssReleaseStage;
+  /** Version introduced, from `@since`. */
+  since?: string;
+  /** A documentation group/category, from `@group`/`@category`. */
+  group?: string;
+  /** Accessibility guidance, from `@a11y`/`@accessibility`. */
+  accessibility?: string;
+  /** AST-extracted modifiers, annotated with `@modifier` prose where authored. */
+  modifiers: CssModifier[];
+  /** AST-extracted sub-element parts (class-based), annotated with `@part` prose where authored. */
+  parts: CssPart[];
+  /** Shadow-DOM exposed parts (`::part(name)`), from `@csspart` or a `::part()` selector. */
+  shadowParts: CssPart[];
+  /** States the component reacts to, from `@cssstate`, `:state()`, pseudo-classes, or state classes. */
+  states: CssState[];
+  /** Named slots the component shell exposes, from `@slot`. */
+  slots: CssSlot[];
+  /**
+   * Design tokens this component consumes: every `--*` custom property referenced via `var(...)` inside
+   * its rules, each annotated with `@tokens` prose where authored (and including any `@tokens`-declared
+   * token not literally found via `var()`).
+   */
+  cssPropertiesConsumed: CssTokenConsumed[];
+  /** Custom properties this component declares (`@property`) or documents (`@cssproperty`). */
+  cssPropertiesDeclared: CssPropertyDeclared[];
+  /** CSS custom functions (`@function`) this component defines. */
+  functions: CssFunction[];
+  /** Animations (`@keyframes`) this component exposes. */
+  animations: CssAnimation[];
+  /** Cascade layers (`@layer`) this component participates in. */
+  layers: CssLayer[];
+  /** Conditional-support blocks (`@container`/`@supports`/`@media`) the rules sit under. */
+  conditions: CssCondition[];
+  /** `@example` blocks, verbatim. */
+  examples: string[];
+  /** The authored `@structure` element tree (top-level nodes), when present. */
+  structure?: StructureNode[];
+  /** An optional prose description leading the `@structure` body, when authored. */
+  structureDescription?: string;
+  /** `@demo <spec>` (e.g. `self:button`), when authored. */
+  demo?: string;
+  /** Component-level deprecation replacement text, when authored (the argument to a `@deprecated` tag). */
+  deprecated?: string;
+  /** `@see <ref>` cross-references. */
+  see: string[];
+  /** Usage prose from `@usage` — how to include the stylesheet / use the component. */
+  usage?: string;
+  /** Browser-support / feature-compatibility notes from `@compat`. */
+  compat: string[];
+  /** Related components from `@related`. */
+  related: CssRelated[];
+  /** Where the record was authored, when position info is available (for source links). */
+  source?: CssSource;
+  /**
+   * Content of registered custom (block) tags, keyed by tag name without its `@`. Populated only for
+   * tags added via configuration; unregistered unknown tags are ignored. Absent when none were found.
+   */
+  customBlocks?: Record<string, string[]>;
+}
+/** A PostCSS parse function — turns a source string into a Root. Inject one to read a non-CSS dialect. */
+type CssParse = (css: string) => import("postcss").Root;
+/** Options for {@link parseCssDocs}. */
+interface ParseOptions {
+  /**
+   * How records are delimited. By default a new record begins at any doc comment (`/** … *\/`) that
+   * carries an `@component` or `@name` tag, which is the recommended, framework-agnostic convention.
+   * Supply a custom test to split on something else (e.g. a per-component header comment).
+   */
+  isRecordBoundary?: (commentText: string) => string | undefined;
+  /**
+   * The tag configuration (standard + custom tags, and which are supported). Defaults to a fresh
+   * {@link CssDocConfiguration} with every standard tag enabled — i.e. the full built-in vocabulary.
+   * 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 `ModifierConvention` for SUIT/CUBE/etc.). Overrides the
+   * `configuration`'s convention when both are given.
+   */
+  modifierConvention?: ModifierConventionInput;
+  /**
+   * The PostCSS parser to read `css` with. Defaults to `postcss.parse` (plain CSS). Inject a dialect
+   * parser (e.g. `postcss-scss`/`postcss-less` via `@cssdoc/dialects`) to document `.scss`/`.less`.
+   */
+  parse?: CssParse;
+  /**
+   * The source file name to record on each entry's {@link CssSource}, enabling source links. The parser
+   * always records line/column; supply this to also record the file.
+   */
+  fileName?: string;
+}
+//#endregion
+//#region src/configuration.d.ts
+/**
+ * The syntactic kind of a tag, mirroring TSDoc's Block/Modifier/Inline split, plus cssdoc's own
+ * `record` kind for the tags that open a documentation record (`@component`, `@utility`, …).
+ */
+type CssDocSyntaxKind = "record" | "block" | "modifier" | "inline";
+/** Options for constructing a {@link CssDocTagDefinition}. */
+interface CssDocTagDefinitionOptions {
+  /** The tag name, with or without a leading `@` (e.g. `@modifier` or `modifier`). */
+  tagName: string;
+  /** The tag's syntactic kind. */
+  syntaxKind: CssDocSyntaxKind;
+  /** Whether the tag may appear more than once in a comment (defaults to `false`). */
+  allowMultiple?: boolean;
+  /** For `record` tags, the {@link CssRecordKind} the tag selects. */
+  recordKind?: CssRecordKind;
+  /** The canonical tag (without `@`) this tag is an alias of, e.g. `@csspart` aliases `part`. */
+  aliasFor?: string;
+}
+/** One tag in the vocabulary: its name, kind, and how it may be used. */
+declare class CssDocTagDefinition {
+  /** The normalized tag name, always with a leading `@` (e.g. `@modifier`). */
+  readonly tagName: string;
+  /** The tag name without its leading `@` (e.g. `modifier`). */
+  readonly tagNameWithoutAt: string;
+  readonly syntaxKind: CssDocSyntaxKind;
+  readonly allowMultiple: boolean;
+  readonly recordKind?: CssRecordKind;
+  /** The canonical tag name (without `@`) this aliases, if any; otherwise its own name. */
+  readonly aliasFor?: string;
+  constructor(options: CssDocTagDefinitionOptions);
+  /** The tag this definition resolves to when handled — its alias target, or itself. */
+  get canonicalName(): string;
+}
+/**
+ * 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 });
+ * ```
+ */
+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. */
+  get supportedTagDefinitions(): readonly CssDocTagDefinition[];
+  /**
+   * 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: CssDocTagDefinition, supported?: boolean): void;
+  /** Register several tag definitions. */
+  addTagDefinitions(definitions: readonly CssDocTagDefinition[], supported?: boolean): void;
+  /** Look up a tag definition by name (with or without a leading `@`). */
+  tryGetTagDefinition(tagName: string): CssDocTagDefinition | undefined;
+  /** Whether a tag definition is supported. */
+  isTagSupported(definition: CssDocTagDefinition): boolean;
+  /** Enable or disable support for a tag. */
+  setSupportForTag(definition: CssDocTagDefinition, supported: boolean): void;
+  /** Enable or disable support for several tags. */
+  setSupportForTags(definitions: readonly CssDocTagDefinition[], supported: boolean): void;
+  /** Disable support for every standard tag (custom tags added later remain supported). */
+  setNoStandardTags(): void;
+  /** The names (without `@`) of every standard tag — the canonical vocabulary from `@cssdoc/spec`. */
+  static readonly standardTagNames: readonly string[];
+  /** A fresh set of the standard tag definitions (new instances on each call), built from the spec. */
+  static standardTags(): CssDocTagDefinition[];
+}
+//#endregion
+//#region src/grammar.d.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.
+ */
+declare const RECORD_TAGS: Record<string, CssRecordKind>;
+/** A custom property documented by a `@cssproperty` tag. */
+interface DocCssProperty {
+  name: string;
+  syntax?: string;
+  defaultValue?: string;
+  description?: string;
+}
+/** The prose a `@modifier` tag contributes: a description and/or an inline deprecation replacement note. */
+interface DocModifier {
+  description?: string;
+  /** Set when the modifier carries a bare `@deprecated` (no note and no canonical link). */
+  deprecatedFlag?: boolean;
+  /** Free-text replacement guidance from an inline `deprecated` tag on the modifier line. */
+  deprecated?: string;
+  /**
+   * The canonical modifier this one deprecates, from a `{@link -canonical}` in the deprecation note
+   * (e.g. `@deprecated {@link -color-danger}`). Stored without its leading dot, matching the AST-derived
+   * `deprecated.canonical`, so an authored alias and a generated one resolve to the same reference.
+   */
+  deprecatedCanonical?: string;
+}
+/** An authored conditional-support tag (`@container`/`@supports`/`@media`/`@responsive`). */
+interface DocCondition {
+  type: "container" | "supports" | "media";
+  query: string;
+  description?: string;
+}
+/** The structured content extracted from one doc-comment block. */
+interface ParsedDoc {
+  /** `@component`/`@utility`/`@rule`/`@declaration`/`@name` — the record name. Marks a record boundary. */
+  component?: string;
+  /** The record kind chosen by the opening tag (`component` unless `@utility`/`@rule`/`@declaration`). */
+  kind?: CssRecordKind;
+  /** `@class` — an explicit base class selector (otherwise inferred from the CSS). */
+  className?: string;
+  /** `@summary` — one-line intro. */
+  summary?: string;
+  /** `@remarks` — extended prose. */
+  remarks?: string;
+  /** `@privateRemarks` — internal-only prose. */
+  privateRemarks?: string;
+  /** `@since` — version introduced. */
+  since?: string;
+  /** `@group`/`@category` — a documentation group. */
+  group?: string;
+  /** `@a11y`/`@accessibility` — accessibility guidance. */
+  accessibility?: string;
+  /** The release stage from a modifier flag tag (`@alpha`/`@beta`/…). */
+  releaseStage?: CssReleaseStage;
+  /** `@modifier` prose, keyed by the modifier class without its dot (e.g. `-color-secondary`). */
+  modifiers: Map<string, DocModifier>;
+  /** `@part` descriptions, keyed by the class part name without its dot (e.g. `item`). */
+  parts: Map<string, string>;
+  /** `@tokens` descriptions, keyed by custom-property name (e.g. `--color-primary`). */
+  tokens: Map<string, string>;
+  /** `@csspart` descriptions (shadow-DOM `::part()`), keyed by the bare part name (e.g. `header`). */
+  cssParts: Map<string, string>;
+  /** `@cssproperty` declarations. */
+  cssProperties: DocCssProperty[];
+  /** `@cssstate` descriptions, keyed by state name. */
+  cssStates: Map<string, string>;
+  /** `@slot` descriptions, keyed by slot name (empty string for the default slot). */
+  slots: Map<string, string>;
+  /** `@function` descriptions, keyed by function name (e.g. `--negate`). */
+  functions: Map<string, string>;
+  /** `@keyframes`/`@animation` descriptions, keyed by animation name. */
+  animations: Map<string, string>;
+  /** `@layer` descriptions, keyed by layer name. */
+  layers: Map<string, string>;
+  /** `@container`/`@supports`/`@media`/`@responsive` authored conditions. */
+  conditions: DocCondition[];
+  /** `@example` blocks. */
+  examples: string[];
+  /** `@structure` — the nested-CSS body, parsed into a selector tree by {@link parseStructure}. */
+  structure?: StructureNode[];
+  /** An optional prose description leading the `@structure` body. */
+  structureDescription?: string;
+  /** The `<replacement>` argument from a `@deprecated` tag. */
+  deprecated?: string;
+  /** `@demo <spec>`. */
+  demo?: string;
+  /** `@see <ref>` entries. */
+  see: string[];
+  /** `@usage` prose — how to include the stylesheet / use the component. */
+  usage?: string;
+  /** `@compat` browser-support / feature-compatibility notes. */
+  compat: string[];
+  /** `@related` component cross-references. */
+  related: CssRelated[];
+  /** Content of registered custom (block) tags, keyed by tag name without its `@`. */
+  customBlocks: Map<string, string[]>;
+}
+/** Strip the comment framing (`/**`, `*\/`, and leading ` * `) from a raw block-comment body. */
+declare function stripCommentFraming(raw: string): string;
+/**
+ * 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.
+ */
+declare function parseDocComment(raw: string, configuration?: CssDocConfiguration, parse?: CssParse): ParsedDoc;
+/**
+ * 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`.
+ */
+declare function recordNameOf(commentText: string, configuration?: CssDocConfiguration): string | undefined;
+declare function parseStructure(raw: string, parse?: CssParse): StructureNode[];
+//#endregion
+//#region src/mermaid.d.ts
+/**
+ * Convert a structure tree to a Mermaid `flowchart` definition. Each node gets a stable id (`n0`, `n1`,
+ * …) in depth-first order; edges connect a parent to each child.
+ *
+ * @param roots - Top-level {@link StructureNode}s (an authored `@structure`).
+ * @param options - `direction` sets the flowchart orientation (default `TD`, top-down).
+ * @returns Mermaid source, or an empty string when there are no nodes.
+ *
+ * @example
+ * ```ts
+ * toMermaid([{ selector: ".tabs", children: [{ selector: ".panel", children: [] }] }]);
+ * // flowchart TD
+ * //   n0[".tabs"]
+ * //   n1[".panel"]
+ * //   n0 --> n1
+ * ```
+ */
+declare function toMermaid(roots: StructureNode[], options?: {
+  direction?: "TD" | "LR";
+}): string;
+//#endregion
+//#region src/lite.d.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.
+ */
+declare function toJson(model: CssDocEntry[]): string;
+//#endregion
+export { CssState as A, ModifierMatcher as B, CssPart as C, CssReleaseStage as D, CssRelated as E, DEFAULT_STATE_PSEUDO_CLASSES as F, MODIFIER_PRESETS as I, ModifierConvention as L, ParseOptions as M, StructureNode as N, CssSlot as O, DEFAULT_MODIFIER_CONVENTION as P, ModifierConventionInput as R, CssParse as S, CssRecordKind as T, resolveModifierConvention as V, CssCondition as _, DocModifier as a, CssLayer as b, parseDocComment as c, stripCommentFraming as d, CssDocConfiguration as f, CssAnimation as g, CssDocTagDefinitionOptions as h, DocCssProperty as i, CssTokenConsumed as j, CssSource as k, parseStructure as l, CssDocTagDefinition as m, toMermaid as n, ParsedDoc as o, CssDocSyntaxKind as p, DocCondition as r, RECORD_TAGS as s, toJson as t, recordNameOf as u, CssDocEntry as v, CssPropertyDeclared as w, CssModifier as x, CssFunction as y, ModifierHit as z };