tailwind-styled-v4 1.0.0

package/dist/compiler/index.d.ts

@@ -0,0 +1,214 @@
+/**
+ * tailwind-styled-v4 — AST Transform Core
+ *
+ * Pure-string AST-like transformer yang menganalisis source code dan
+ * mengubah semua tw.tag`...` / tw.tag({...}) calls menjadi static
+ * className strings (zero-runtime output).
+ *
+ * Dipakai oleh:
+ *   - swcPlugin.ts    → SWC/Next.js transform
+ *   - vitePlugin.ts   → Vite/Rollup transform
+ *   - nextPlugin.ts   → Next.js webpack loader
+ *   - postcssPlugin.ts → PostCSS safelist generation
+ *
+ * Zero-runtime berarti output akhirnya adalah:
+ *   BEFORE: const Box = tw.div`p-4 bg-zinc-900`
+ *   AFTER:  const Box = styled.div``.attrs(()=>({className:"p-4 bg-zinc-900"}))``)
+ *
+ * Untuk kasus yang pure static (tidak ada dynamic expr),
+ * output bisa di-inline langsung sebagai string literal:
+ *   AFTER: const Box = styled.div.attrs(()=>({className:"p-4 bg-zinc-900"}))``)
+ */
+interface TransformOptions {
+    /**
+     * "runtime"     → keep tw.tag, resolve at runtime (default dev mode)
+     * "zero-runtime"→ transform to styled.tag with static className
+     * "extract-only"→ do not transform, only extract class names
+     */
+    mode?: "runtime" | "zero-runtime" | "extract-only";
+    /** Add data-tw attribute for debugging in dev tools */
+    addDataAttr?: boolean;
+    /** Generate unique stable hash per component for CSS layer naming */
+    generateHash?: boolean;
+    /** Tailwind prefix (if configured in tailwind.config.ts) */
+    prefix?: string;
+    /** Filename being transformed — used for source maps */
+    filename?: string;
+}
+interface TransformResult {
+    code: string;
+    classes: string[];
+    map?: string;
+    changed: boolean;
+}
+declare function transformSource(source: string, opts?: TransformOptions): TransformResult;
+declare function extractAllClasses(source: string): string[];
+declare function transformBatch(files: Array<{
+    path: string;
+    source: string;
+}>, opts?: TransformOptions): {
+    results: Array<TransformResult & {
+        path: string;
+    }>;
+    allClasses: string[];
+};
+
+/**
+ * tailwind-styled-v4 — transformTw
+ *
+ * Low-level transform used by all build plugins.
+ * Wraps astTransform with file-type filtering and source-map passthrough.
+ */
+
+/**
+ * Transform a single file's source code.
+ * Returns unchanged code for non-JS/TS files.
+ */
+declare function transformTw(source: string, opts?: TransformOptions & {
+    filepath?: string;
+}): TransformResult;
+/**
+ * Extract all Tailwind classes from source without transforming.
+ * Used for safelist generation.
+ */
+declare function extractTwClasses(source: string): string[];
+/**
+ * Check whether a file should be processed by the transform.
+ */
+declare function shouldProcess(filepath: string): boolean;
+
+/**
+ * tailwind-styled-v4 — SWC Plugin / Next.js Transform
+ *
+ * Integrates with Next.js compiler (SWC-based) via next.config.ts.
+ * Supports both Webpack and Turbopack (Next.js 15.3+).
+ *
+ * Usage in next.config.ts:
+ * ─────────────────────────────────────────────────────────────
+ * import { withTailwindStyled } from "tailwind-styled-v4/compiler"
+ *
+ * const nextConfig = withTailwindStyled({
+ *   mode: "zero-runtime",
+ *   addDataAttr: true,
+ *   generateHash: true,
+ * })({
+ *   // ...your Next.js config
+ * })
+ *
+ * export default nextConfig
+ * ─────────────────────────────────────────────────────────────
+ *
+ * What it does at build time:
+ *   BEFORE: const Box = tw.div`p-4 bg-zinc-900 rounded-xl`
+ *   AFTER:  const Box = styled.div.attrs(()=>({className:"p-4 bg-zinc-900 rounded-xl"}))`
+ *
+ * Turbopack support (Next.js 15.3+):
+ * ─────────────────────────────────────────────────────────────
+ * Turbopack does not support webpack loaders. Instead it uses
+ * experimental.turbopack.rules. withTailwindStyled automatically
+ * detects and configures both bundlers.
+ */
+
+interface SwcPluginOptions extends TransformOptions {
+    /**
+     * Directories to scan for class extraction (safelist generation).
+     * Defaults to ["src", "app", "pages", "components"]
+     */
+    scanDirs?: string[];
+    /**
+     * Output path for generated safelist JSON.
+     * Defaults to "tailwind.safelist.json"
+     */
+    safelistOutput?: string;
+    /**
+     * Whether to generate the safelist file on each build.
+     * Defaults to true
+     */
+    generateSafelist?: boolean;
+}
+declare function turbopackTransform(source: string, resourcePath: string, opts?: TransformOptions): {
+    code: string;
+};
+declare function withTailwindStyled(pluginOpts?: SwcPluginOptions): (nextConfig?: Record<string, any>) => Record<string, any>;
+declare function swcTransformFile(source: string, filepath: string, opts?: TransformOptions): string;
+interface SafelistOptions {
+    scanDirs: string[];
+    outputPath: string;
+    cwd: string;
+}
+declare function runSafelistGeneration(opts: SafelistOptions): void;
+declare function swcPlugin(source: string, opts?: TransformOptions): string;
+
+/**
+ * tailwind-styled-v4 — Vite Plugin
+ *
+ * Usage in vite.config.ts:
+ * ─────────────────────────────────────────────────────────────
+ * import { tailwindStyledPlugin } from "tailwind-styled-v4/compiler"
+ *
+ * export default defineConfig({
+ *   plugins: [
+ *     react(),
+ *     tailwindStyledPlugin({
+ *       mode: "zero-runtime",
+ *       addDataAttr: true,
+ *     }),
+ *   ],
+ * })
+ * ─────────────────────────────────────────────────────────────
+ *
+ * Compatible with: Vite 4+, Remix, SvelteKit (JS files only)
+ */
+
+interface VitePluginOptions extends TransformOptions {
+    /** Include patterns. Default: all .tsx/.ts/.jsx/.js */
+    include?: RegExp;
+    /** Exclude patterns. Default: node_modules */
+    exclude?: RegExp;
+    /** Directories to scan for safelist generation */
+    scanDirs?: string[];
+    /** Output path for safelist JSON */
+    safelistOutput?: string;
+    /** Generate safelist on build end */
+    generateSafelist?: boolean;
+}
+declare function tailwindStyledPlugin(opts?: VitePluginOptions): any;
+
+/**
+ * tailwind-styled-v4 — Safelist Generator
+ *
+ * Scans your entire src/ directory and extracts every Tailwind class
+ * used via tw.tag`...`, className="...", cn(), etc.
+ *
+ * The output JSON can be referenced in your tailwind.config.ts:
+ *
+ * ─────────────────────────────────────────────────────────────
+ * // tailwind.config.ts
+ * import safelist from "./tailwind.safelist.json"
+ *
+ * export default {
+ *   safelist: safelist.safelist,
+ *   // ...
+ * }
+ * ─────────────────────────────────────────────────────────────
+ *
+ * Run manually:  npx ts-node src/build/generateSafelist.ts
+ * Or via script: npm run build:safelist
+ */
+interface SafelistConfig {
+    /** Root directory of your project */
+    cwd: string;
+    /** Directories to scan (relative to cwd) */
+    scanDirs: string[];
+    /** File extensions to scan */
+    extensions: RegExp;
+    /** Directories to skip */
+    excludeDirs: string[];
+    /** Output file path (relative to cwd) */
+    outputPath: string;
+    /** Include Tailwind pattern annotations in output */
+    verbose: boolean;
+}
+declare function generateSafelist(userConfig?: Partial<SafelistConfig>): void;
+
+export { type SwcPluginOptions, type TransformOptions, type TransformResult, type VitePluginOptions, extractAllClasses, extractTwClasses, generateSafelist, runSafelistGeneration, shouldProcess, swcPlugin, swcTransformFile, tailwindStyledPlugin, transformBatch, transformSource, transformTw, turbopackTransform, withTailwindStyled };