praxis-kit 3.1.1 → 4.0.0

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

@@ -1,5 +1,6 @@
 import { Plugin } from 'vite';
 import { Cardinality, ChildRulePosition, Severity } from '@praxis-kit/core';
+import { DiagnosticInput } from '@praxis-kit/diagnostics';
 import ts from 'typescript';
 
 /**
@@ -34,7 +35,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 +63,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 +153,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 +182,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 +259,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.