@cssdoc/core 0.1.0 → 0.3.0

package/dist/index.d.mts

@@ -1,3 +1,198 @@
+//#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;
+}
+/**
+ * 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[];
+  /**
+   * 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;
+  /** 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/configuration.d.ts
 /**
  * The syntactic kind of a tag, mirroring TSDoc's Block/Modifier/Inline split, plus cssdoc's own
@@ -49,7 +244,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. */
@@ -73,9 +273,9 @@ declare class CssDocConfiguration {
   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 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). */
+  /** A fresh set of the standard tag definitions (new instances on each call), built from the spec. */
   static standardTags(): CssDocTagDefinition[];
 }
 //#endregion
@@ -93,13 +293,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;
@@ -117,13 +324,23 @@ interface CssModifier {
 interface CssPart {
   /** The part class without the leading dot, e.g. `item`. */
   name: string;
-  /** Prose from a `@part` / `@csspart` doc tag, when authored. */
+  /** 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[];
 }
-/** A component state — a `:state()` / state-class the component reacts to (`@cssstate`). */
+/**
+ * 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, e.g. `open` or `selected`. */
+  /** 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;
 }
@@ -196,13 +413,14 @@ type CssRecordKind = "component" | "utility" | "rule" | "declaration";
  */
 type CssReleaseStage = "alpha" | "beta" | "experimental" | "internal" | "public";
 /**
- * A node in an authored HTML-structure tree (`@structure`): a selector for the element and its
- * children. Emitters render it as an indented tree and, via {@link toMermaid}, as a diagram.
+ * 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 selector/label, e.g. `.tabs` or `.tab.-selected` or `button`. */
+  /** The node's compound selector, e.g. `.tabs`, `.tab.-selected`, or `.list:has(.tab)`. */
   selector: string;
-  /** Child nodes (one indentation level deeper). */
+  /** Child nodes (rules nested one brace level deeper). */
   children: StructureNode[];
 }
 /** One documented CSS record: its base class plus everything derived from the CSS + doc comments. */
@@ -229,9 +447,11 @@ interface CssDocEntry {
   accessibility?: string;
   /** AST-extracted modifiers, annotated with `@modifier` prose where authored. */
   modifiers: CssModifier[];
-  /** AST-extracted sub-element parts, annotated with `@part`/`@csspart` prose where authored. */
+  /** AST-extracted sub-element parts (class-based), annotated with `@part` prose where authored. */
   parts: CssPart[];
-  /** States the component reacts to, from `@cssstate`. */
+  /** 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[];
@@ -249,8 +469,10 @@ interface CssDocEntry {
   conditions: CssCondition[];
   /** `@example` blocks, verbatim. */
   examples: string[];
-  /** The authored `@structure` HTML tree (top-level nodes), when present. */
+  /** 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). */
@@ -263,6 +485,8 @@ interface CssDocEntry {
    */
   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 {
   /**
@@ -277,6 +501,17 @@ 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 `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;
 }
 //#endregion
 //#region src/parse.d.ts
@@ -357,8 +592,10 @@ interface ParsedDoc {
   releaseStage?: CssReleaseStage;
   /** `@modifier` prose, keyed by the modifier class without its dot (e.g. `-color-secondary`). */
   modifiers: Map<string, DocModifier>;
-  /** `@part`/`@csspart` descriptions, keyed by the part name without its dot (e.g. `item`). */
+  /** `@part` descriptions, keyed by the class part name without its dot (e.g. `item`). */
   parts: 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. */
@@ -375,8 +612,10 @@ interface ParsedDoc {
   conditions: DocCondition[];
   /** `@example` blocks. */
   examples: string[];
-  /** `@structure` — the raw (indented) HTML-tree body, parsed into nodes by {@link parseStructure}. */
+  /** `@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>`. */
@@ -408,16 +647,18 @@ declare function parseDocComment(raw: string, configuration?: CssDocConfiguratio
  */
 declare function recordNameOf(commentText: string, configuration?: CssDocConfiguration): string | undefined;
 /**
- * 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.
+ * 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 {}
+ * }
  * ```
  */
 declare function parseStructure(raw: string): StructureNode[];
@@ -454,4 +695,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 CssParse, type CssPart, type CssPropertyDeclared, type CssRecordKind, type CssReleaseStage, type CssSlot, type CssState, DEFAULT_MODIFIER_CONVENTION, DEFAULT_STATE_PSEUDO_CLASSES, 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 };