@csszyx/cli 0.3.0 → 0.4.0

package/README.md

@@ -40,10 +40,22 @@ npx csszyx audit
 
 ### `generate-types`
 
-Generate TypeScript definitions from your `tailwind.config.js`.
+> **Not applicable for Tailwind v4 projects.**
+>
+> CSSzyx requires Tailwind v4, which replaces `tailwind.config.js` with `@theme {}` blocks
+> in CSS. This command uses Tailwind v3's `resolveConfig()` API to parse JS config files —
+> that API does not exist in v4.
+>
+> For v4 projects, use the plugin's `build.scanCss` option instead. See
+> [Plugin Config docs](/docs/reference/config).
+>
+> This command is kept for potential future Tailwind v3 compatibility support.
+> If your project needs it, open an issue.
 
 ```bash
 npx csszyx generate-types
+npx csszyx generate-types --config ./path/to/tailwind.config.js
+npx csszyx generate-types --output ./src/csszyx.d.ts
 ```
 
 ### `migrate`

package/dist/index.d.ts

@@ -158,4 +158,81 @@ declare function writeDeclarationFile(content: string, outputPath: string): Prom
  */
 declare function generateAndWriteTypes(theme: ResolvedTheme, options?: GeneratorOptions): Promise<string>;
 
-export { type GenerateTypesOptions, type GeneratorOptions, type ResolvedTheme, type ScanResult, extractScreenKeys, extractSpacingKeys, findConfigFile, flattenColors, generateAndWriteTypes, generateTypeDeclarations, generateTypes, scanTailwindConfig, writeDeclarationFile };
+/**
+ * A single entry in .csszyx-todo.json. Possible values:
+ *   - `Record<string, unknown>` — direct sz object mapping ({ p: 4, bg: 'blue-500' })
+ *   - `string` — Tailwind class string to auto-convert, or a "sz:" directive
+ *                ('sz:todo' | 'sz:keep' | 'sz:remove')
+ *   - `null | false` — treated as 'sz:todo' (unresolved, for backwards compat)
+ */
+type CsszyxTodoEntry = Record<string, unknown> | string | null | false;
+/**
+ * Shape of .csszyx-todo.json — a map from Tailwind class names to resolution entries.
+ */
+type CsszyxTodoMap = Record<string, CsszyxTodoEntry>;
+/**
+ * Convert a full className string into a single merged sz object.
+ * Returns the sz object plus any unrecognized classes and classes to keep in className.
+ *
+ * @param {string} className - The full Tailwind class string
+ * @param {CsszyxTodoMap} [customMap] - Optional csszyx-todo.json mapping
+ * @returns {{ szObject, unrecognized, keepInClassName }} Merged sz object, unrecognized, and "sz:keep" classes
+ */
+declare function classNameToSzObject(className: string, customMap?: CsszyxTodoMap): {
+    szObject: Record<string, unknown>;
+    unrecognized: string[];
+    keepInClassName: string[];
+};
+
+/**
+ * AST Transformer: Replaces className attributes with sz props.
+ *
+ * Phase 2: Uses Babel AST traversal for JSX/TSX files. Supports:
+ * - Static className="..." (string literals)
+ * - className={'...'} (string in expression container)
+ * - className={clsx(...)} / cn(...) / twMerge(...)
+ * - className={cond ? 'a' : 'b'} (ternary)
+ * - className={cond && 'a'} (logical AND)
+ * - className={`static ${dynamic}`} (template literals)
+ *
+ * HTML files use regex (Babel doesn't parse HTML).
+ *
+ * @module
+ */
+
+/**
+ * Result of source transformation.
+ */
+interface TransformResult {
+    code: string;
+    changed: boolean;
+    warnings: string[];
+    stats: {
+        classNamesTransformed: number;
+        classNamesSkipped: number;
+        classesUnrecognized: string[];
+    };
+    /** Imports that may be unused after migration (e.g., clsx, cn). */
+    potentiallyUnusedImports: string[];
+}
+/**
+ * Options for source transformation.
+ */
+interface TransformOptions {
+    /** If true, injects {/* @sz-todo *\/} comments above nodes with unrecognized classes */
+    injectTodos?: boolean;
+    /** Map of custom classes to sz objects, used to override unrecognized classes */
+    customMap?: CsszyxTodoMap;
+}
+/**
+ * Transform a JSX/TSX source file, replacing className with sz props.
+ * Uses Babel AST for accurate, context-aware transformation.
+ *
+ * @param source - Source file content string.
+ * @param filePath - Path to the source file (for error messages).
+ * @param options - Transformation options.
+ * @returns {TransformResult} Transformed code and stats.
+ */
+declare function transformSource(source: string, filePath: string, options?: TransformOptions): TransformResult;
+
+export { type CsszyxTodoEntry, type CsszyxTodoMap, type GenerateTypesOptions, type GeneratorOptions, type TransformResult as MigrateResult, type ResolvedTheme, type ScanResult, classNameToSzObject, extractScreenKeys, extractSpacingKeys, findConfigFile, flattenColors, generateAndWriteTypes, generateTypeDeclarations, generateTypes, transformSource as migrateSource, scanTailwindConfig, writeDeclarationFile };