praxis-kit 3.1.1 → 4.0.1

package/dist/vite-plugin/index.d.ts

@@ -1,7 +1,144 @@
 import { Plugin } from 'vite';
-import { Cardinality, ChildRulePosition, Severity } from '@praxis-kit/core';
+import { Except, Simplify } from 'type-fest';
 import ts from 'typescript';
 
+type StringMap<T = unknown> = Record<string, T>;
+type AnyRecord = StringMap<unknown>;
+
+declare enum DiagnosticCategory {
+    Contract = 0,
+    HTML = 1,
+    ARIA = 2,
+    Composition = 3,
+    Rendering = 4,
+    Accessibility = 5,
+    Performance = 6,
+    Internal = 7,
+    Deprecation = 8,
+    Lint = 9
+}
+
+declare enum DiagnosticCode {
+    MissingRequiredChild = "COMP1001",
+    InvalidParent = "COMP1002",
+    InvalidChild = "COMP1003",
+    UnexpectedChild = "COMP1004",
+    AmbiguousChild = "COMP1005",
+    CardinalityMin = "COMP1006",
+    CardinalityMax = "COMP1007",
+    PositionViolation = "COMP1008",
+    AllowedAsViolation = "COMP1009",
+    SlotExclusive = "SLOT1001",
+    SlotSingleChild = "SLOT1002",
+    SlotDiscardedChildren = "SLOT1003",
+    SlotRenderFn = "SLOT1004",
+    MissingAriaRelationship = "ARIA2001",
+    AriaViolation = "ARIA2002",
+    AriaAttributeInvalid = "ARIA2003",
+    AriaMissingLiveRegion = "ARIA2004",
+    AriaMissingAtomic = "ARIA2005",
+    AriaRelevantInvalidToken = "ARIA2006",
+    AriaRelevantSuperseded = "ARIA2007",
+    AriaInvalidRole = "ARIA2008",
+    AriaMissingAccessibleName = "ARIA2009",
+    AriaAttributeOnPresentational = "ARIA2010",
+    AriaHiddenOnFocusable = "ARIA2011",
+    AriaRequiredProperty = "ARIA2012",
+    AriaInvalidAttributeValue = "ARIA2013",
+    AriaRedundantLevelAttribute = "ARIA2014",
+    InvalidHeadingHierarchy = "HTML3001",
+    HtmlEmptyRole = "HTML3002",
+    HtmlImplicitRoleRedundant = "HTML3003",
+    HtmlImplicitRoleOverride = "HTML3004",
+    HtmlStandaloneRegionOverride = "HTML3005",
+    HtmlLandmarkRoleOverride = "HTML3006",
+    HtmlInvalidChild = "HTML3007",
+    InvalidRenderingTarget = "RENDER4001",
+    LintDeadCompoundKey = "LINT5001",
+    LintDeadCompoundValue = "LINT5002",
+    LintDeadCompoundNonLiteral = "LINT5003",
+    LintMissingStrict = "LINT5004",
+    LintInvalidDefaultKey = "LINT5005",
+    LintInvalidDefaultValue = "LINT5006",
+    LintInvalidDefaultNonLiteral = "LINT5007",
+    LintNegativeMin = "LINT5008",
+    LintNegativeMax = "LINT5009",
+    LintMaxLessThanMin = "LINT5010",
+    LintZeroMax = "LINT5011",
+    LintMultipleFirst = "LINT5012",
+    LintMultipleLast = "LINT5013",
+    LintMinSumExceedsCapacity = "LINT5014",
+    LintCardinalityViolation = "LINT5015",
+    LintAriaTagOverride = "LINT5016",
+    ContractUnknownVariantDim = "COMP1010",
+    ContractUnknownVariantValue = "COMP1011",
+    ContractUnknownRecipeKey = "COMP1012",
+    ContractInvalidVariantValue = "COMP1013",
+    TailwindMultipleDisplayProps = "CSS6001",
+    TailwindReservedLayoutLiteral = "CSS6002",
+    TailwindDeadVariantClass = "CSS6003",
+    PluginInvalidShape = "PLUGIN7001",
+    PluginPipelineReturnType = "PLUGIN7002",
+    InternalError = "INTERNAL9000"
+}
+
+interface SourcePosition {
+    line: number;
+    col: number;
+}
+interface SourceLocation {
+    file: string;
+    start: SourcePosition;
+    end?: SourcePosition;
+}
+
+declare enum Severity$1 {
+    Debug = 0,
+    Info = 1,
+    Warning = 2,
+    Error = 3,
+    Fatal = 4
+}
+
+interface DiagnosticSuggestion {
+    title: string;
+    description?: string;
+    fix?: string;
+}
+
+type Context = AnyRecord;
+type Metadata = AnyRecord;
+interface Diagnostic$1 {
+    code: DiagnosticCode;
+    severity: Severity$1;
+    category: DiagnosticCategory;
+    message: string;
+    rationale?: string;
+    component?: string;
+    contract?: string;
+    location?: SourceLocation;
+    suggestions?: DiagnosticSuggestion[];
+    context?: Context;
+    metadata?: Metadata;
+}
+
+type DiagnosticInput = Except<Diagnostic$1, 'severity'>;
+
+type MinMax = {
+    min: number;
+    max: number;
+};
+/** Unboundedness is encoded in the type, not a sentinel value, enabling exhaustive switches. */
+type Cardinality = Simplify<{
+    kind: 'bounded';
+} & MinMax> | {
+    kind: 'unbounded';
+};
+
+type ChildRulePosition = 'first' | 'last' | 'any';
+
+type Severity = 'error' | 'warning' | (string & {});
+
 /**
  * One enforcement.children rule whose cardinality is statically extractable
  * from the factory call AST. The `Cardinality` discriminated union matches the
@@ -34,7 +171,7 @@ type ComponentConstraint = {
 
 /** A diagnostic produced by the static analysis pass. */
 type Diagnostic = {
-    message: string;
+    diagnostic: DiagnosticInput;
     /** 1-based line number in the source file. */
     line: number;
     /** 1-based column number. */
@@ -62,6 +199,78 @@ type PluginOptions = {
     severity?: Severity;
 };
 
+/**
+ * Pure analysis entry point. Parses `code` as TypeScript/TSX, extracts
+ * enforcement.children constraints from factory calls, and validates JSX usage
+ * sites in the same file.
+ *
+ * Statically-analyzable scope:
+ * - Single file: component must be defined and used in the same source file.
+ * - Literal-only children: JSX sites that include any JSX expression ({...})
+ *   are skipped — their child count is unknowable at build time.
+ * - Named const declarations: `export const X = factory(...)` and destructured
+ *   patterns are not collected; cross-file analysis is future work.
+ */
+declare function analyze(code: string, filename: string, options?: PluginOptions): Diagnostic[];
+
+/**
+ * Compile-time variant class precomputation.
+ *
+ * Extracts `styling.variants`, `styling.defaults`, and `styling.compounds` from
+ * factory call ASTs, enumerates all statically-known prop combinations, computes
+ * the variant class string for each, and injects the resulting map as
+ * `styling.precomputedClasses` directly into the source.
+ *
+ * At runtime, `VariantClassResolver` checks `precomputedClasses` before
+ * calling CVA — a plain object lookup replaces a CVA invocation + LRU cache
+ * write for every covered combination.
+ *
+ * **Skipped when any of the following are true:**
+ * - `styling.variants` is absent or contains non-literal values
+ * - `styling.compounds` contains non-literal conditions or class values
+ * - The total number of combinations exceeds MAX_COMBINATIONS
+ * - The styling object already has a `precomputedClasses` property
+ */
+
+/**
+ * Builds a precomputed class map for the given styling object literal.
+ *
+ * Returns null when static extraction is not possible (non-literal values,
+ * no variants, or combination count exceeds MAX_COMBINATIONS).
+ */
+declare function buildPrecomputedClasses(stylingObj: ts.ObjectLiteralExpression): Record<string, string> | null;
+/**
+ * Injects precomputed variant class maps into all factory calls in the given
+ * source file that have fully-static `styling.variants` configurations.
+ *
+ * Returns null when no factory calls with injectable variants are found.
+ */
+declare function injectPrecomputedClasses(source: ts.SourceFile, calleeNames: ReadonlySet<string>): string | null;
+
+/**
+ * Compile-time dead compound variant pruning.
+ *
+ * Removes entries from `styling.compounds` whose conditions can never fire:
+ *   - condition key is not in `styling.variants`
+ *   - condition value (string) is not a valid value for that variant key
+ *   - condition value (array) has no element that is a valid value
+ *
+ * Only entries whose conditions are all statically evaluable (string/array
+ * literals throughout) are candidates for pruning — dynamic conditions (variable
+ * references, computed values) are left unchanged.
+ *
+ * Returns null if no factory calls with `styling.compounds` are found, or if
+ * every compound in every factory call passes the validity check.
+ */
+
+/**
+ * Applies dead-compound pruning to the given TypeScript source file.
+ *
+ * Returns null when the file has no factory calls with `styling.compounds`, or
+ * when every compound entry passes validity — i.e., when no pruning is needed.
+ */
+declare function pruneDeadCompounds(source: ts.SourceFile, calleeNames: ReadonlySet<string>): string | null;
+
 type ComponentTokens = {
     base: string[];
     variantClasses: string[];
@@ -80,6 +289,7 @@ type DesignTokenManifest = {
  * destructured patterns fall through (same scope as `collectConstraints`).
  */
 declare function collectFileTokens(source: ts.SourceFile, calleeNames: ReadonlySet<string>): Map<string, ComponentTokens>;
+/** Builds a DesignTokenManifest from the accumulated per-component token maps, including a flat sorted `allClasses` union. */
 declare function buildManifest(allTokens: Map<string, ComponentTokens>): DesignTokenManifest;
 type DesignTokensOptions = {
     /**
@@ -108,6 +318,22 @@ type DesignTokensOptions = {
  */
 declare function designTokensPlugin(options?: DesignTokensOptions): Plugin;
 
+type ImportBinding = {
+    /** The exported name in the source module (the name before `as`, if any). */
+    readonly importedName: string;
+    /** The module specifier string (e.g. `'./Button'`). */
+    readonly specifier: string;
+};
+
+/**
+ * Applies the asChild → render-prop transform to the given TypeScript source
+ * file and returns the printed output.
+ *
+ * Returns null if no `asChild` attribute is found in the source (fast path —
+ * avoids parsing overhead for files that don't use the pattern).
+ */
+declare function transformAsChild(source: ts.SourceFile): string | null;
+
 /**
  * Compile-time static composition transform.
  *
@@ -169,125 +395,6 @@ declare function extractStaticComponents(source: ts.SourceFile, calleeNames: Rea
  */
 declare function composeStatically(source: ts.SourceFile, calleeNames: ReadonlySet<string>, importedComponents?: ReadonlyMap<string, StaticComponent>): string | null;
 
-type ImportBinding = {
-    /** The exported name in the source module (the name before `as`, if any). */
-    readonly importedName: string;
-    /** The module specifier string (e.g. `'./Button'`). */
-    readonly specifier: string;
-};
-
-/**
- * Pure analysis entry point. Parses `code` as TypeScript/TSX, extracts
- * enforcement.children constraints from factory calls, and validates JSX usage
- * sites in the same file.
- *
- * Statically-analyzable scope:
- * - Single file: component must be defined and used in the same source file.
- * - Literal-only children: JSX sites that include any JSX expression ({...})
- *   are skipped — their child count is unknowable at build time.
- * - Named const declarations: `export const X = factory(...)` and destructured
- *   patterns are not collected; cross-file analysis is future work.
- */
-declare function analyze(code: string, filename: string, options?: PluginOptions): Diagnostic[];
-
-/**
- * Compile-time asChild → render-prop transform.
- *
- * Rewrites JSX usage sites of the form:
- *   <Component asChild ...props>
- *     <childTag ...childProps>children</childTag>
- *   </Component>
- *
- * to the render-prop form:
- *   <Component render={(_p) => <childTag ...childProps {..._p} />} ...props />
- *
- * The render-prop form eliminates the Slot/cloneElement/mergeProps path at
- * runtime — resolved props are passed directly to the render callback with no
- * element cloning.
- *
- * **Safety conditions** — the transform is skipped if any of these are true:
- *   1. The child has a dynamic `className` expression (cannot merge safely).
- *      A string-literal `className` IS handled: the transform generates
- *      `{..._p, className: _p.className + ' childCls'}`.
- *   2. The child has a bare `style` or `on*` attribute without an initializer.
- *      Static object-literal and expression-valued `style` props are merged:
- *      `style={{..._p.style, ...childStyle}}`.  Event handlers are composed:
- *      `onClick={(_e) => { (childHandler)(_e); _p.onClick?.(_e); }}`.
- *   3. The component name starts with a lowercase letter (HTML intrinsic — not
- *      a polymorphic component).
- *   4. There are zero or more than one meaningful child elements.
- *
- * The transform is conservative: any condition that is not statically clear
- * causes the node to be left unchanged.
- */
-
-/**
- * Applies the asChild → render-prop transform to the given TypeScript source
- * file and returns the printed output.
- *
- * Returns null if no `asChild` attribute is found in the source (fast path —
- * avoids parsing overhead for files that don't use the pattern).
- */
-declare function transformAsChild(source: ts.SourceFile): string | null;
-
-/**
- * Compile-time dead compound variant pruning.
- *
- * Removes entries from `styling.compounds` whose conditions can never fire:
- *   - condition key is not in `styling.variants`
- *   - condition value (string) is not a valid value for that variant key
- *   - condition value (array) has no element that is a valid value
- *
- * Only entries whose conditions are all statically evaluable (string/array
- * literals throughout) are candidates for pruning — dynamic conditions (variable
- * references, computed values) are left unchanged.
- *
- * Returns null if no factory calls with `styling.compounds` are found, or if
- * every compound in every factory call passes the validity check.
- */
-
-/**
- * Applies dead-compound pruning to the given TypeScript source file.
- *
- * Returns null when the file has no factory calls with `styling.compounds`, or
- * when every compound entry passes validity — i.e., when no pruning is needed.
- */
-declare function pruneDeadCompounds(source: ts.SourceFile, calleeNames: ReadonlySet<string>): string | null;
-
-/**
- * Compile-time variant class precomputation.
- *
- * Extracts `styling.variants`, `styling.defaults`, and `styling.compounds` from
- * factory call ASTs, enumerates all statically-known prop combinations, computes
- * the variant class string for each, and injects the resulting map as
- * `styling.precomputedClasses` directly into the source.
- *
- * At runtime, `VariantClassResolver` checks `precomputedClasses` before
- * calling CVA — a plain object lookup replaces a CVA invocation + LRU cache
- * write for every covered combination.
- *
- * **Skipped when any of the following are true:**
- * - `styling.variants` is absent or contains non-literal values
- * - `styling.compounds` contains non-literal conditions or class values
- * - The total number of combinations exceeds MAX_COMBINATIONS
- * - The styling object already has a `precomputedClasses` property
- */
-
-/**
- * Builds a precomputed class map for the given styling object literal.
- *
- * Returns null when static extraction is not possible (non-literal values,
- * no variants, or combination count exceeds MAX_COMBINATIONS).
- */
-declare function buildPrecomputedClasses(stylingObj: ts.ObjectLiteralExpression): Record<string, string> | null;
-/**
- * Injects precomputed variant class maps into all factory calls in the given
- * source file that have fully-static `styling.variants` configurations.
- *
- * Returns null when no factory calls with injectable variants are found.
- */
-declare function injectPrecomputedClasses(source: ts.SourceFile, calleeNames: ReadonlySet<string>): string | null;
-
 /**
  * Vite plugin that performs static enforcement.children cardinality checks at
  * build time for components created with createContractComponent.