@cssdoc/core 0.2.0 → 0.3.1

package/dist/index.d.mts

@@ -26,8 +26,30 @@
 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;
+  /**
+   * 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
@@ -37,11 +59,18 @@ interface ModifierConvention {
   /** 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`. The default. */readonly bem: {
+  /** 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: {
@@ -84,13 +113,60 @@ interface ModifierHit {
  */
 declare class ModifierMatcher {
   readonly convention: ModifierConvention;
-  private readonly sepEsc;
+  /** 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;
@@ -105,9 +181,15 @@ declare class ModifierMatcher {
    * 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 the convention's required prefix? */
+  /** Does an attribute-expression's name carry one of the convention's required prefixes? */
   private attributeMatches;
 }
 //#endregion
@@ -191,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
@@ -242,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;
 }
@@ -321,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. */
@@ -354,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[];
@@ -374,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). */
@@ -388,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 {
   /**
@@ -404,10 +503,15 @@ interface ParseOptions {
   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.
+   * `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
@@ -488,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. */
@@ -506,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>`. */
@@ -539,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[];
@@ -585,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, 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 };
+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 };