tailwind-styled-v4 1.0.1 → 5.0.0

package/README.md

@@ -1,608 +0,0 @@
-# 🎨 tailwind-styled-v4
-
-> **styled-components meets Tailwind CSS** — dengan type safety penuh, zero DOM pollution, dan zero-runtime build output.
-
-```tsx
-const Button = tw.button({
-  base: "px-4 py-2 rounded-lg font-medium transition",
-  variants: {
-    variant: {
-      primary: "bg-blue-500 text-white hover:bg-blue-600",
-      ghost:   "bg-transparent border hover:bg-zinc-800",
-    },
-    size: { sm: "h-8 text-sm", lg: "h-12 text-base" },
-  },
-  defaultVariants: { variant: "primary", size: "sm" },
-})
-
-<Button variant="primary" size="lg" p={4} rounded="card" />
-```
-
----
-
-## ✨ Fitur Utama
-
-| Fitur | Keterangan |
-|-------|------------|
-| 🧱 **styled-components API** | Familiar, chainable, SSR-safe |
-| 🎭 **Variant System** | `variants`, `compoundVariants`, `defaultVariants` |
-| 📐 **Responsive Props** | `p={{ sm: 2, lg: 8 }}` — responsive object syntax |
-| 🎨 **Design Tokens** | `bg="primary"` → `bg-blue-600` via theme store |
-| ⚡ **Zero-Runtime** | Build-time transform → static `className` strings |
-| 🔌 **Plugin System** | Register custom prop resolvers |
-| 🛡️ **Type Safe** | Full TypeScript generics & inference |
-| 🚫 **Zero DOM Pollution** | Props tidak bocor ke HTML attributes |
-
----
-
-## 📦 Instalasi
-
-```bash
-npm install tailwind-styled-v4 styled-components tailwind-merge
-```
-
----
-
-## 🚀 Quick Start
-
-### 1️⃣ Template Literal (paling simpel)
-
-```tsx
-import { tw } from "tailwind-styled-v4"
-
-const Box   = tw.div`p-4 bg-zinc-900 rounded-xl`
-const Title = tw.h1`text-2xl font-bold text-white`
-const Badge = tw.span`px-2 py-1 rounded-full text-xs bg-blue-500 text-white`
-```
-
-### 2️⃣ Object Config + Variants
-
-```tsx
-const Button = tw.button({
-  base: "inline-flex items-center font-medium transition rounded-lg",
-  variants: {
-    variant: {
-      primary: "bg-blue-500 text-white hover:bg-blue-600",
-      ghost:   "bg-transparent border border-zinc-700 hover:bg-zinc-800",
-      danger:  "bg-red-500 text-white hover:bg-red-600",
-    },
-    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-500/30" },
-  ],
-  defaultVariants: { variant: "primary", size: "md" },
-})
-
-// Usage
-<Button variant="ghost" size="lg" />
-<Button variant="danger" />
-```
-
-### 3️⃣ Prop Shorthand (responsive-ready)
-
-```tsx
-// Scalar
-<Box p={4} bg="zinc-900" rounded="xl" flex />
-
-// Responsive object
-<Box p={{ base: 2, md: 4, lg: 8 }} cols={{ sm: 1, md: 2, lg: 3 }} />
-
-// Design token
-<Box bg="primary" text="foreground" rounded="card" shadow="modal" />
-```
-
-### 4️⃣ Extend Component
-
-```tsx
-const Card    = tw.div`p-6 rounded-2xl bg-zinc-900`
-const HeroCard = Card.extend`shadow-2xl ring-1 ring-zinc-700`
-const DarkCard = Card.withVariants({
-  variants: { elevated: { true: "shadow-2xl", false: "" } }
-})
-```
-
-### 5️⃣ Wrap Komponen Apapun
-
-```tsx
-// shadcn/ui, Radix, komponen custom
-const TwButton  = withTw(Button, "px-4 py-2")
-const TwDialog  = tw(Dialog.Content)`p-6 rounded-2xl`
-
-<TwButton p={4} rounded="xl" bg="zinc-900" />
-```
-
----
-
-## 🎭 Variant System
-
-### Basic Variants
-
-```tsx
-const Alert = tw.div({
-  base: "p-4 rounded-lg border",
-  variants: {
-    status: {
-      info:    "bg-sky-50    border-sky-200   text-sky-800",
-      success: "bg-emerald-50 border-emerald-200 text-emerald-800",
-      warning: "bg-amber-50  border-amber-200  text-amber-800",
-      danger:  "bg-red-50    border-red-200    text-red-800",
-    },
-  },
-  defaultVariants: { status: "info" },
-})
-```
-
-### Compound Variants
-
-```tsx
-// Class tambahan ketika 2+ variant aktif bersamaan
-compoundVariants: [
-  { variant: "primary", size: "lg", class: "shadow-lg shadow-blue-500/30" },
-  { variant: "ghost",   size: "sm", class: "opacity-70" },
-]
-```
-
-### withVariants — tambah variant ke komponen existing
-
-```tsx
-const EnhancedButton = Button.withVariants({
-  variants: {
-    loading: { true: "opacity-50 cursor-not-allowed", false: "" }
-  }
-})
-```
-
----
-
-## 📐 Prop Engine
-
-Semua prop otomatis di-convert ke Tailwind class. Tidak perlu `className="..."`.
-
-### Spacing
-```tsx
-<Box p={4} px={6} py={2} m="auto" mx={4} gap={3} />
-// → p-4 px-6 py-2 m-auto mx-4 gap-3
-```
-
-### Flexbox & Grid
-```tsx
-<Box flex items="center" justify="between" wrap />
-<Box cols={3} rows={2} colSpan={2} gap={4} />
-// → flex items-center justify-between flex-wrap
-// → grid-cols-3 grid-rows-2 col-span-2 gap-4
-```
-
-### Colors & Typography
-```tsx
-<Box bg="zinc-900" text="white" border ring="blue-500" />
-<Box fontSize="heading" font="sans" leading="relaxed" tracking="tight" />
-```
-
-### Layout & Position
-```tsx
-<Box pos="absolute" top={0} right={0} z={50} inset="x-4" />
-<Box overflow="hidden" rounded="xl" shadow="card" opacity={90} />
-```
-
-### Responsive Object
-```tsx
-// Semua prop mendukung responsive object
-<Box
-  p={{ base: 2, sm: 4, md: 6, lg: 8 }}
-  cols={{ base: 1, md: 2, lg: 3 }}
-  hidden={{ base: true, md: false }}
-/>
-```
-
----
-
-## 🎨 Theme & Design Tokens
-
-### Setup
-
-```tsx
-// app/layout.tsx
-import { loadDefaultTheme } from "tailwind-styled-v4"
-loadDefaultTheme()
-```
-
-### Custom Theme
-
-```tsx
-import { setTheme } from "tailwind-styled-v4"
-
-setTheme({
-  colors: {
-    primary:    "blue-600",
-    secondary:  "violet-600",
-    brand:      "cyan-400",
-    background: "zinc-950",
-    surface:    "zinc-900",
-    muted:      "zinc-500",
-  },
-  radius: {
-    card:   "2xl",
-    button: "lg",
-    badge:  "full",
-    input:  "md",
-  },
-  spacing: {
-    section: "16",
-    page:    "24",
-  },
-  duration: {
-    fast:   "150",
-    normal: "200",
-    slow:   "300",
-  },
-})
-```
-
-### Penggunaan Token
-
-```tsx
-// Token otomatis di-resolve
-<Box bg="primary" />          // → bg-blue-600
-<Box rounded="card" />        // → rounded-2xl
-<Box p="section" />           // → p-16
-<Box duration="fast" />       // → duration-150
-```
-
----
-
-## 🎯 cv() — Standalone Class Variants
-
-Cocok untuk **shadcn/ui**, **Radix UI**, atau komponen headless apapun tanpa styled-components.
-
-```tsx
-import { cv } from "tailwind-styled-v4"
-
-const buttonVariants = cv({
-  base: "inline-flex items-center rounded-lg font-medium transition",
-  variants: {
-    variant: {
-      primary: "bg-blue-500 text-white hover:bg-blue-600",
-      ghost:   "bg-transparent border hover:bg-zinc-800",
-    },
-    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" }
-  ],
-  defaultVariants: { variant: "primary", size: "md" },
-})
-
-// Pakai di komponen apapun
-function Button({ variant, size, className, ...props }) {
-  return <button className={buttonVariants({ variant, size, className })} {...props} />
-}
-```
-
----
-
-## 🔌 Plugin System
-
-### Built-in Plugins
-
-```tsx
-import { loadBuiltinPlugins } from "tailwind-styled-v4"
-loadBuiltinPlugins()
-
-// Setelah load, props berikut tersedia:
-<Box motionSafe backdropBlur="md" gradientFrom="blue-500" gradientTo="purple-500" />
-<Box scrollSmooth printHidden autoRows="fr" />
-```
-
-### Tailwind v4 Plugins
-
-```tsx
-import { loadAllV4Plugins } from "tailwind-styled-v4"
-loadAllV4Plugins()
-
-// Typography
-<article prose="lg" proseDark proseMaxW={false} />
-// → prose prose-lg dark:prose-invert max-w-none
-
-// Forms
-<input formInput />
-<select formSelect />
-
-// Aspect Ratio
-<div aspectRatio="video" />    // → aspect-video
-<div aspectRatio="square" />   // → aspect-square
-
-// Animations
-<div enterAnim="fade-up" />    // → animate-in fade-in slide-in-from-bottom-4
-<div exitAnim="fade" />        // → animate-out fade-out
-
-// Interactivity
-<button hoverBg="zinc-800" hoverScale focusRing="blue-500" activeScale />
-
-// Container Queries
-<div cqContainer />            // → @container
-```
-
-### Custom Plugin
-
-```tsx
-import { registerPlugin } from "tailwind-styled-v4"
-
-registerPlugin({
-  name: "glass",
-  props: {
-    glass: (v) => v === true
-      ? "backdrop-blur-md bg-white/10 border border-white/20"
-      : `backdrop-blur-${v} bg-white/10`,
-  },
-})
-
-// Langsung bisa dipakai
-<Box glass />
-<Box glass="xl" />
-```
-
----
-
-## ⚡ Zero-Runtime Mode
-
-### Next.js
-
-```ts
-// next.config.ts
-import { withTailwindStyled } from "tailwind-styled-v4/compiler"
-
-export default withTailwindStyled({
-  mode: "zero-runtime",   // transform tw.div`...` → static className
-  addDataAttr: true,       // tambah data-tw="hash" untuk DevTools
-})(nextConfig)
-```
-
-### Vite
-
-```ts
-// vite.config.ts
-import { tailwindStyledPlugin } from "tailwind-styled-v4/compiler"
-
-export default defineConfig({
-  plugins: [
-    react(),
-    tailwindStyledPlugin({ mode: "zero-runtime" }),
-  ],
-})
-```
-
-**Before:**
-```tsx
-const Box = tw.div`p-4 bg-zinc-900 rounded-xl`
-```
-
-**After (build output):**
-```tsx
-const Box = styled.div.attrs(() => ({ className: "p-4 bg-zinc-900 rounded-xl" }))``
-```
-
-> 🚀 Nol JS runtime cost — `className` jadi static string, bukan computed di setiap render.
-
----
-
-## 🛡️ shouldForwardProp
-
-Semua tw props **otomatis diblokir** dari forwarding ke DOM. Tidak ada warning `Unknown prop` di console.
-
-```tsx
-// ✅ Tidak ada warning di DOM
-<Box p={4} flex cols={3} bg="zinc-900" />
-
-// Transient props ($) selalu di-forward
-<Box $isActive={true} />
-
-// Manual block/allow
-import { blockProp, allowProp } from "tailwind-styled-v4"
-blockProp("customProp")
-allowProp("size")  // kalau mau size sampai ke DOM
-```
-
----
-
-## 🧪 Validation (Dev Only)
-
-```tsx
-import { validateVariantProps, buildSchema } from "tailwind-styled-v4"
-
-const schema = buildSchema("button", {
-  variant: { primary: "...", ghost: "..." },
-  size:    { sm: "...", lg: "..." },
-})
-
-validateVariantProps({ variant: "invalid" }, schema)
-// [tw-error] Invalid prop "variant"="invalid" on <button>
-//   Expected one of: "primary" | "ghost"
-//   Got: "invalid"
-//   Hint: Add "invalid" to the variants config, or fix the typo.
-```
-
-> ⚠️ Validation hanya aktif di `NODE_ENV !== "production"` — **zero overhead di production**.
-
----
-
-## 🔧 Utils
-
-### cx / cxm
-
-```tsx
-import { cx, cxm } from "tailwind-styled-v4"
-
-// cx — lightweight class joiner
-cx("p-4", isActive && "bg-blue-500", ["rounded", "shadow"])
-cx({ "p-4": true, "hidden": false })
-
-// cxm — cx + tailwind-merge (conflict resolution)
-cxm("p-2", "p-4")   // → "p-4"  (p-2 dihapus)
-```
-
-### Class Parser
-
-```tsx
-import { parseClassString, splitModifiers, groupByModifier } from "tailwind-styled-v4"
-
-splitModifiers("p-4 hover:bg-blue-500 md:p-8")
-// → { base: ["p-4"], modifiers: ["hover:bg-blue-500", "md:p-8"] }
-
-groupByModifier("p-4 hover:bg-blue-500 hover:text-white")
-// → { "": ["p-4"], hover: ["bg-blue-500", "text-white"] }
-```
-
-### Safelist Generator
-
-```tsx
-import { generateSafelist } from "tailwind-styled-v4/compiler"
-
-generateSafelist({
-  cwd: process.cwd(),
-  scanDirs: ["src", "app", "components"],
-  outputPath: "tailwind.safelist.json",
-})
-// ✓ Safelist: 247 classes → /project/tailwind.safelist.json
-```
-
----
-
-## 📁 Struktur Engine
-
-```
-src/
-├── core/
-│   ├── tw.ts              🎯 Proxy-free tw object (v2 fix)
-│   ├── createComponent.ts 🏗️  Single styled-chain factory
-│   ├── templateParser.ts  📝 Tagged template literal parser
-│   ├── cv.ts              🎭 Standalone class variants
-│   ├── withTw.ts          🔌 HOC wrapper untuk komponen apapun
-│   └── styledFactory.ts   🏭 Thin styled-components wrapper
-│
-├── runtime/
-│   ├── propEngine.ts      ⚙️  80+ prop → class resolvers
-│   ├── variantEngine.ts   🎭 Variant resolution
-│   ├── compoundVariant.ts 🔀 Compound variant resolution
-│   ├── responsiveEngine.ts📐 Responsive object handler
-│   └── classResolver.ts   🔗 Full pipeline orchestrator
-│
-├── theme/
-│   ├── themeStore.ts      🎨 Global token store
-│   ├── tokenResolver.ts   🔑 Token → class segment resolver
-│   └── defaultTheme.ts    📦 Ready-to-use semantic tokens
-│
-├── plugins/
-│   ├── pluginEngine.ts    🔌 Plugin registry & resolver
-│   ├── registerPlugin.ts  📋 Public plugin registration API
-│   ├── builtinPlugins.ts  🧰 Animation, grid, backdrop, gradient
-│   └── tailwindV4Plugins.ts 🆕 Typography, forms, aspect, animations
-│
-├── compiler/
-│   ├── astTransform.ts    🔄 Source code transformer (zero-runtime)
-│   ├── transformTw.ts     🛠️  Transform orchestrator
-│   ├── vitePlugin.ts      ⚡ Vite/Rollup plugin
-│   ├── swcPlugin.ts       🔧 Next.js SWC transform
-│   ├── webpackLoader.ts   📦 Webpack loader
-│   └── classExtractor.ts  🔍 Class extraction for safelist
-│
-├── validation/
-│   └── propValidator.ts   🛡️  Dev-only prop validation
-│
-└── utils/
-    ├── cx.ts              🔗 Lightweight class joiner
-    ├── classParser.ts     🔤 Class string utilities
-    ├── hash.ts            #️⃣  Stable hash generator
-    ├── merge.ts           🔀 twMerge wrapper
-    └── isObject.ts        🔍 Type guard utility
-```
-
----
-
-## 🧪 Test Coverage
-
-```
-228 tests — 228 pass ✅
-
-🔵 templateParser       9/9
-🔵 themeStore           7/7
-🔵 tokenResolver        7/7
-🔵 defaultTheme         2/2
-🔵 responsiveEngine     7/7
-🔵 variantEngine        5/5
-🔵 compoundVariant      5/5
-🔵 propEngine          15/15
-🔵 classResolver        2/2
-🔵 pluginEngine         4/4
-🔵 registerPlugin       3/3
-🔵 builtinPlugins       7/7
-🔵 tailwindV4Plugins   14/14
-🔵 cv                   4/4
-🔵 propValidator        6/6
-🔵 astTransform        10/10
-🔵 utils                9/9
-🔵 withTw               5/5
-🔵 styledFactory        6/6
-🔵 classParser         10/10
-🔵 cx / cxm             8/8
-🔵 classExtractor       4/4
-🔵 generateSafelist     4/4
-🔵 barrel exports      67/67
-🔵 end-to-end           5/5
-```
-
----
-
-## 📋 Changelog v2
-
-### 🔴 Bug Fixes
-
-**`tw` undefined setelah bundle split (Vite/tsup)**
-```
-BEFORE: export const tw = new Proxy(fn, { get })
-        → Proxy + tsup splitting = tw undefined di Next.js/Vite
-
-AFTER:  Object.assign(twCallable, { div, button, ... })
-        → Plain object, transparan ke semua bundler
-```
-
-**Double wrap SSR hydration mismatch**
-```
-BEFORE: styled(tag)`` → styled(BaseStyled).attrs()``
-        → Double wrap = SSR hydration mismatch + SC v6 error
-
-AFTER:  styled(tag).withConfig().attrs()``
-        → Single chain, satu SC instance per component
-```
-
-**shouldForwardProp hardcoded**
-```
-BEFORE: Hanya blokir variant names yang hardcoded
-        → User variant keys bocor ke DOM
-
-AFTER:  Built dynamically dari variant keys aktual
-        → Zero DOM pollution apapun nama variant-nya
-```
-
-**TypeScript generic inference**
-```
-BEFORE: TwTagFactory tidak generic
-        → "Binding element '$isHover' implicitly has 'any' type"
-
-AFTER:  TwTagFactory<P> generic function
-        → Full type inference di template interpolations
-```
-
----
-
-## 📝 License
-
-MIT © tailwind-styled-v4