tailwind-styled-v4 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,75 @@
+# Changelog
+
+All notable changes to `tailwind-styled-v4` will be documented here.
+
+## [1.0.0] — Initial Release
+
+### Added
+
+#### Core Engine
+- `tw` proxy — template literal & object config syntax
+- `tw.tag\`classes\`` — template literal API
+- `tw.tag({ base, variants, compoundVariants, defaultVariants })` — object config API
+- `tw(Component)\`classes\`` — wrap any existing component
+- `Component.extend\`extra-classes\`` — chain extra classes
+- `Component.withVariants(config)` — merge new variants
+
+#### Runtime Engines
+- **propEngine** — 80+ props (padding, margin, sizing, colors, flex, grid, layout, effects, animation, interaction)
+- **responsiveEngine** — `{ base, sm, md, lg, xl, 2xl }` responsive objects
+- **variantEngine** — CVA-style variants with `defaultVariants` support
+- **compoundVariant** — multi-condition compound variants
+- **classResolver** — central resolver combining all engines via `tailwind-merge`
+
+#### Standalone APIs
+- `cv()` — standalone class variants function (shadcn/ui & Radix compatible)
+- `withTw(Component, base?)` — HOC untuk wrap third-party components
+- `cls\`...\`` — tagged template for static class strings
+- `cx(...inputs)` — lightweight class joiner (~100b, zero-dep)
+- `cxm(...inputs)` — cx + tailwind-merge deduplication
+
+#### Plugin System
+- `registerPlugin({ name, props })` — custom prop resolver plugins
+- `loadBuiltinPlugins()` — 6 built-in plugins: animation, grid, backdrop, gradient, scroll, print
+- `listPlugins()` / `getPlugin(name)` — plugin introspection
+
+#### Theme System
+- `setTheme(tokens)` — deep-merge semantic tokens
+- `replaceTheme(tokens)` — replace entire theme
+- `getTheme()` / `getThemeNamespace(key)` — read current theme
+- `onThemeChange(listener)` — subscription API
+- `loadDefaultTheme()` — semantic token preset (primary, surface, muted, etc.)
+- `loadDarkTheme()` — fintech/crypto/Web3 dark preset
+
+#### Zero-Runtime Compiler
+- `withTailwindStyled(opts)(nextConfig)` — Next.js HOC wrapper
+- `tailwindStyledPlugin(opts)` — Vite plugin
+- Webpack loader (`tailwind-styled-v4/webpack-loader`)
+- Static transform: `tw.div\`p-4\`` → `styled.div.attrs(()=>({className:"p-4"}))\`\``
+- Dynamic guard: skips interpolated templates (`${}`) safely
+- `data-tw="tw-xxxxx"` attribute injection for DevTools (dev mode)
+
+#### Build Tools
+- `generateTailwindTypes.ts` — generates **58.055** Tailwind class type unions
+- `generateSafelist.ts` — scans src/ and outputs `tailwind.safelist.json`
+- `extractAllClasses(source)` — extract classes from any source string
+
+#### IntelliSense
+- **58.055 class definitions** in `tailwind.generated.ts`
+- Coverage: all colors (21 palettes × 11 shades), spacing, sizing, flexbox, grid, effects, transitions, animations, responsive prefixes (sm/md/lg/xl/2xl), state prefixes (hover/focus/active/disabled/dark/group-hover/peer-hover/focus-visible/focus-within)
+
+#### Developer Experience
+- `shouldForwardProp` — tw props tidak bocor ke DOM attributes
+- `blockProp(name)` / `allowProp(name)` — fine-grained forwarding control
+- `hashClass(input)` → `"tw-xxxxx"` — stable component hash
+- `componentName(tag, classes)` — display name generator for React DevTools
+- Source maps enabled in all builds
+
+#### Stack Compatibility
+- Next.js 15/16 (App Router + Pages Router)
+- React 18/19
+- Tailwind CSS v3/v4
+- styled-components v5/v6
+- TypeScript 4.9/5.x
+- shadcn/ui, Radix UI, Headless UI
+- Vite 4/5, Webpack 4/5

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 tailwind-styled-v4
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,330 @@
+# tailwind-styled-v4
+
+**PRO Engine** — styled-components + Tailwind CSS v4, zero-runtime compile option, variant system, responsive props, plugin ecosystem.
+
+> Melampaui `twin.macro` dengan tetap kompatibel penuh terhadap Next.js 16 · React 19 · Tailwind CSS v4 · styled-components v6 · TypeScript 5 · shadcn/ui.
+
+---
+
+## Installation
+
+```bash
+npm install tailwind-styled-v4
+# peerDependencies
+npm install styled-components tailwind-merge clsx
+```
+
+---
+
+## Quick Start
+
+### Template Literal (sederhana)
+
+```tsx
+import { tw } from "tailwind-styled-v4"
+
+const Card = tw.div`
+  p-6
+  bg-zinc-900
+  rounded-2xl
+  border border-zinc-800
+`
+
+// Responsive props inline
+<Card p={{ base: 4, md: 6, lg: 8 }} />
+// → p-4 md:p-6 lg:p-8
+```
+
+### Object Config (full power)
+
+```tsx
+const Button = tw.button({
+  base: "inline-flex items-center justify-center rounded-lg font-medium transition",
+  variants: {
+    variant: {
+      primary: "bg-blue-600 text-white hover:bg-blue-700",
+      ghost:   "bg-transparent border border-zinc-700 hover:bg-zinc-800",
+      danger:  "bg-red-600 text-white hover:bg-red-700",
+    },
+    size: {
+      sm: "h-8  px-3 text-sm",
+      md: "h-10 px-4 text-sm",
+      lg: "h-12 px-6 text-base",
+    },
+  },
+  compoundVariants: [
+    { variant: "primary", size: "lg", class: "shadow-lg shadow-blue-600/30" },
+  ],
+  defaultVariants: { variant: "primary", size: "md" },
+})
+
+// Usage
+<Button variant="primary" size="lg">Click me</Button>
+<Button variant="ghost" size="sm">Cancel</Button>
+```
+
+### Extend existing component
+
+```tsx
+const HeroCard = Card.extend`shadow-2xl ring-1 ring-zinc-700/50`
+```
+
+### Wrap any component (shadcn/ui, Radix, dll)
+
+```tsx
+import { withTw, tw } from "tailwind-styled-v4"
+import { Button } from "@/components/ui/button"   // shadcn
+import Link from "next/link"
+
+const TwButton = withTw(Button, "px-4 py-2")
+const NavLink  = tw(Link)`text-zinc-400 hover:text-zinc-100 transition-colors`
+```
+
+### Standalone class variants (headless/shadcn compatible)
+
+```tsx
+import { cv } from "tailwind-styled-v4"
+
+const badgeCv = cv({
+  base: "inline-flex items-center rounded-full px-2.5 py-0.5 text-xs font-medium",
+  variants: {
+    color: {
+      blue:  "bg-blue-100 text-blue-800",
+      green: "bg-green-100 text-green-800",
+      red:   "bg-red-100 text-red-800",
+    }
+  },
+  defaultVariants: { color: "blue" }
+})
+
+// Use anywhere
+<span className={badgeCv({ color: "green" })}>Active</span>
+```
+
+---
+
+## Responsive Props
+
+Semua props mendukung responsive object:
+
+```tsx
+<Box
+  p={{ base: 2, sm: 4, md: 6, lg: 8 }}
+  cols={{ base: 1, sm: 2, lg: 3 }}
+  gap={{ base: 3, md: 4 }}
+  display="grid"
+/>
+// → p-2 sm:p-4 md:p-6 lg:p-8 grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 gap-3 md:gap-4
+```
+
+### Available Props
+
+| Category | Props |
+|----------|-------|
+| **Padding** | `p` `px` `py` `pt` `pb` `pl` `pr` |
+| **Margin** | `m` `mx` `my` `mt` `mb` `ml` `mr` |
+| **Gap** | `gap` `gapX` `gapY` `spaceX` `spaceY` |
+| **Sizing** | `w` `h` `size` `minW` `maxW` `minH` `maxH` |
+| **Colors** | `bg` `text` `border` `ring` `fill` `stroke` |
+| **Typography** | `font` `fontSize` `leading` `tracking` `align` `truncate` `lineClamp` |
+| **Flexbox** | `flex` `flexDir` `items` `justify` `wrap` `grow` `shrink` `basis` `self` |
+| **Grid** | `cols` `rows` `colSpan` `rowSpan` `colStart` `colEnd` |
+| **Layout** | `display` `overflow` `pos` `z` `top` `right` `bottom` `left` `inset` |
+| **Border** | `rounded` `roundedT` `roundedB` `borderStyle` `outline` |
+| **Effects** | `opacity` `shadow` `blur` `brightness` `contrast` `grayscale` `backdrop` |
+| **Motion** | `transition` `duration` `ease` `delay` `animate` |
+| **Interaction** | `cursor` `select` `pointer` `touch` |
+
+---
+
+## Zero-Runtime (Next.js)
+
+Di production build, semua `tw.tag\`...\`` dikompilasi menjadi static string — zero JS runtime overhead.
+
+```ts
+// next.config.ts
+import { withTailwindStyled } from "tailwind-styled-v4/compiler"
+
+export default withTailwindStyled({
+  mode: "zero-runtime",    // "runtime" di dev, "zero-runtime" di production
+  addDataAttr: true,        // data-tw="tw-3f2a1" untuk DevTools
+  generateSafelist: true,   // auto-generate tailwind.safelist.json
+})(/** nextConfig */ {})
+```
+
+**Before (source):**
+```tsx
+const Box = tw.div`p-4 bg-zinc-900 rounded-xl`
+```
+
+**After (compiled output):**
+```tsx
+const Box = styled.div.attrs(() => ({ className: "p-4 bg-zinc-900 rounded-xl" }))``
+```
+
+Runtime cost: **0 bytes** untuk class resolution.
+
+---
+
+## Zero-Runtime (Vite)
+
+```ts
+// vite.config.ts
+import { tailwindStyledPlugin } from "tailwind-styled-v4/compiler"
+
+export default defineConfig({
+  plugins: [react(), tailwindStyledPlugin({ mode: "zero-runtime" })],
+})
+```
+
+---
+
+## Plugin System
+
+```tsx
+import { registerPlugin } from "tailwind-styled-v4"
+
+// Custom plugin
+registerPlugin({
+  name: "glass",
+  props: {
+    glass:   v => v === true ? "bg-white/10 backdrop-blur-xl border border-white/10" : "",
+    frosted: v => v === true ? "bg-white/5 backdrop-blur-md saturate-150" : "",
+  }
+})
+
+// Usage
+<Box glass />     // → bg-white/10 backdrop-blur-xl border border-white/10
+<Box frosted />   // → bg-white/5 backdrop-blur-md saturate-150
+```
+
+### Built-in Plugins
+
+```tsx
+import { loadBuiltinPlugins } from "tailwind-styled-v4"
+loadBuiltinPlugins()  // animation, grid, backdrop, gradient, scroll, print
+```
+
+---
+
+## Theme System
+
+```tsx
+import { setTheme, loadDefaultTheme, loadDarkTheme } from "tailwind-styled-v4"
+
+// Preset themes
+loadDefaultTheme()  // semantic tokens: primary, surface, muted, dll
+loadDarkTheme()     // fintech/crypto/Web3 dark preset
+
+// Custom tokens
+setTheme({
+  colors: {
+    brand:    "blue-600",
+    "brand-hover": "blue-700",
+    surface:  "zinc-900",
+  },
+  radius: {
+    card:   "2xl",
+    button: "lg",
+  },
+})
+
+// Now works everywhere
+<Box bg="brand" rounded="card" />
+// → bg-blue-600 rounded-2xl
+```
+
+---
+
+## Safelist Generation
+
+```bash
+npm run build:safelist
+```
+
+Menghasilkan `tailwind.safelist.json` yang bisa direferensikan di `tailwind.config.ts`:
+
+```ts
+// tailwind.config.ts
+import safelist from "./tailwind.safelist.json"
+
+export default {
+  safelist: safelist.safelist,
+  // ...
+}
+```
+
+---
+
+## IntelliSense (VSCode)
+
+Library ini menyertakan **58.055 class definitions** di `src/types/tailwind.generated.ts` untuk autocomplete penuh di VSCode termasuk semua modifier:
+
+```
+bg-blue-500          ← base class
+hover:bg-blue-500    ← hover state
+md:bg-blue-500       ← responsive
+dark:bg-blue-500     ← dark mode
+dark:hover:bg-blue-500 ← combined
+```
+
+Tambahkan ke `.vscode/settings.json`:
+```json
+{
+  "tailwindCSS.experimental.classRegex": [
+    ["tw\\.\\w+`([^`]*)`", "([^`]*)"],
+    ["tw\\.\\w+\\(([^)]*)\\)", "\"([^\"]*)\""],
+    ["cv\\(([^)]*)\\)", "\"([^\"]*)\""]
+  ]
+}
+```
+
+---
+
+## Scripts
+
+```bash
+npm run build           # build library
+npm run build:types     # regenerate 58k class types
+npm run build:safelist  # scan src/ dan generate safelist
+npm run dev             # watch mode
+npm run test            # run all tests
+```
+
+---
+
+## Comparison
+
+| Feature | tailwind-styled-v4 | twin.macro | CVA | Stitches |
+|---------|--------------------|------------|-----|----------|
+| Template literal | ✅ | ✅ | ❌ | ❌ |
+| Object config + variants | ✅ | ❌ | ✅ | ✅ |
+| Compound variants | ✅ | ❌ | ✅ | ✅ |
+| Responsive props | ✅ | ❌ | ❌ | ❌ |
+| Zero-runtime | ✅ | ✅ | ❌ | ✅ |
+| Plugin system | ✅ | ❌ | ❌ | ❌ |
+| styled-components compat | ✅ | ✅ | ❌ | ❌ |
+| shadcn/ui compat | ✅ | ❌ | ✅ | ❌ |
+| Theme/token system | ✅ | ❌ | ❌ | ✅ |
+| IntelliSense 58k classes | ✅ | ✅ | ❌ | ❌ |
+| Wrap any component | ✅ | ❌ | ❌ | ❌ |
+
+---
+
+## Stack Compatibility
+
+- **Next.js** 15 / 16 (App Router + Pages Router)
+- **React** 18 / 19 (Server Components compatible)
+- **Tailwind CSS** v3 / v4
+- **styled-components** v5 / v6
+- **TypeScript** 4.9 / 5.x
+- **shadcn/ui** (semua komponen)
+- **Radix UI** (via `withTw()`)
+- **Vite** 4 / 5
+- **Webpack** 4 / 5
+
+---
+
+## License
+
+MIT

package/dist/compiler/index.d.mts

@@ -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 };