windctrl 0.0.1 → 0.1.0

package/README.md

@@ -11,7 +11,7 @@ It evolves the concept of Variant APIs (like [cva](https://cva.style/)) by intro
 - 🎨 **Unified API** - Seamlessly blends static Tailwind classes and dynamic inline styles into one cohesive interface.
 - 🧩 **Trait System** - Solves combinatorial explosion by treating states as stackable, non-exclusive layers.
 - 🎯 **Scoped Styling** - Context-aware styling using data attributes - no React Context required (RSC friendly).
-- ⚡ **JIT Optimized** - Prevents CSS bundle bloat by intelligently routing arbitrary values to inline styles.
+- ⚡ **JIT Conscious** - Designed for Tailwind JIT: utilities stay as class strings, while truly dynamic values can be expressed as inline styles.
 - 🔒 **Type-Safe** - Best-in-class TypeScript support with automatic prop inference.
 - 📦 **Minimal Overhead** - Ultra-lightweight runtime with only `clsx` and `tailwind-merge` as dependencies.
 
@@ -24,28 +24,28 @@ npm install windctrl
 ## Quick Start
 
 ```typescript
-import { windCtrl } from "windctrl";
+import { windctrl } from "windctrl";
 
-const button = windCtrl({
-  base: "rounded px-4 py-2 font-medium transition",
+const button = windctrl({
+  base: "rounded px-4 py-2 font-medium transition duration-200",
   variants: {
     intent: {
       primary: "bg-blue-500 text-white hover:bg-blue-600",
-      secondary: "bg-gray-500 text-gray-900 hover:bg-gray-600",
+      secondary: "bg-gray-200 text-gray-900 hover:bg-gray-300",
     },
     size: {
-      sm: "text-sm",
-      md: "text-base",
-      lg: "text-lg",
+      sm: "text-sm h-8",
+      md: "text-base h-10",
+      lg: "text-lg h-12",
     },
   },
   traits: {
-    loading: "opacity-50 cursor-wait",
-    glass: "backdrop-blur bg-white/10",
+    loading: "opacity-70 cursor-wait pointer-events-none",
+    glass: "backdrop-blur-md bg-white/10 border border-white/20 shadow-xl",
   },
   dynamic: {
     w: (val) =>
-      typeof val === "number" ? { style: { width: `${val}px` } } : `w-${val}`,
+      typeof val === "number" ? { style: { width: `${val}px` } } : val,
   },
   defaultVariants: {
     intent: "primary",
@@ -53,100 +53,132 @@ const button = windCtrl({
   },
 });
 
-// Usage
-const { className, style } = button({
-  intent: "primary",
-  size: "lg",
-  traits: ["loading", "glass"],
-  w: 200,
-});
+// Usage Example
+
+// 1. Standard usage
+button({ intent: "primary", size: "lg" });
+
+// 2. Using Traits (Stackable states)
+button({ traits: ["glass", "loading"] });
+
+// 3. Unified API for dynamic values
+// Pass a number for arbitrary px value (Inline Style)
+button({ w: 350 });
+// Pass a string for Tailwind utility (Static Class)
+button({ w: "w-full" });
 ```
 
 ## Core Concepts
 
-### Dynamic Props (Interpolated Variants)
+### Interpolated Variants (Dynamic Props)
+
+Interpolated variants provide a **Unified API** that bridges static Tailwind classes and dynamic inline styles. A dynamic resolver can return either:
 
-Dynamic props allow you to pass arbitrary values that can resolve to either Tailwind classes or inline styles, bridging the gap between static classes and dynamic styles.
+- a **Tailwind class string** (static utility), or
+- an object containing **className and/or style** (inline styles and optional utilities)
+
+This is **JIT-friendly by design**, as long as the class strings you return are statically enumerable (i.e. appear in your source code).
+For truly unbounded values (e.g. pixel sizes), prefer returning style to avoid relying on arbitrary-value class generation.
 
 ```typescript
-const button = windCtrl({
+const button = windctrl({
   dynamic: {
+    // Recommended pattern:
+    // - Numbers -> inline styles (unbounded values)
+    // - Strings -> Tailwind utilities (must be statically enumerable for JIT)
     w: (val) =>
-      typeof val === "number" ? { style: { width: `${val}px` } } : `w-${val}`,
-    h: (val) =>
-      typeof val === "number" ? { style: { height: `${val}px` } } : `h-${val}`,
+      typeof val === "number" ? { style: { width: `${val}px` } } : val,
   },
 });
 
 // Usage
-button({ w: "full" }); // Returns className: "w-full"
-button({ w: 200 }); // Returns style: { width: "200px" }
-button({ w: 200, h: 100 }); // Returns both className and style
+button({ w: "w-full" }); // -> className includes "w-full" (static utility)
+button({ w: 200 }); // -> style includes { width: "200px" } (dynamic value)
 ```
 
-### Traits
+> **Note on Tailwind JIT**: Tailwind only generates CSS for class names it can statically detect in your source. Avoid constructing class strings dynamically (e.g. "`w-`" + `size`) unless you safelist them in your Tailwind config.
+
+### Traits (Stackable States)
 
-Traits are stackable, non-exclusive states. Unlike variants, multiple traits can be active simultaneously, solving the combinatorial explosion problem of `compoundVariants`.
+Traits are non-exclusive, stackable layers of state. Unlike `variants` (which are mutually exclusive), multiple traits can be active simultaneously. This declarative approach solves the "combinatorial explosion" problem often seen with `compoundVariants`.
+
+Traits are **non-exclusive, stackable modifiers**. Unlike variants (mutually exclusive design choices), multiple traits can be active at the same time. This is a practical way to model boolean-like component states (e.g. `loading`, `disabled`, `glass`) without exploding compoundVariants.
+
+When multiple traits generate conflicting utilities, Tailwind’s “last one wins” rule applies (via `tailwind-merge`).
+If ordering matters, prefer the **array form** to make precedence explicit.
 
 ```typescript
-const button = windCtrl({
+const button = windctrl({
   traits: {
     loading: "opacity-50 cursor-wait",
-    glass: "backdrop-blur bg-white/10",
-    disabled: "pointer-events-none",
+    glass: "backdrop-blur-md bg-white/10 border border-white/20",
+    disabled: "pointer-events-none grayscale",
   },
 });
 
-// Usage - Array form
+// Usage - Array form (explicit precedence; recommended when conflicts are possible)
 button({ traits: ["loading", "glass"] });
 
-// Usage - Object form
-button({ traits: { loading: true, glass: true, disabled: false } });
+// Usage - Object form (convenient for boolean props; order is not intended to be meaningful)
+button({ traits: { loading: isLoading, glass: true } });
 ```
 
-### Scopes
+### Scopes (RSC Support)
 
-Scopes provide context-aware styling without React Context, making it fully compatible with Server Components (RSC).
+Scopes enable **context-aware styling** without relying on React Context or client-side JavaScript. This makes them fully compatible with React Server Components (RSC). They utilize Tailwind's group modifier logic under the hood.
 
 ```typescript
-const button = windCtrl({
+const button = windctrl({
   scopes: {
-    header: "text-sm",
-    footer: "text-xs",
+    header: "text-sm py-1",
+    footer: "text-xs text-gray-500",
   },
 });
 
-// Usage - Wrap elements with data-scope attribute
+// Usage
+// 1. Wrap the parent with `data-scope` and `group/wind-scope`
+// 2. The button automatically adapts its style based on the parent
 <div data-scope="header" className="group/wind-scope">
-  <button className={button({}).className}>Header Button</button>
+  <button className={button().className}>Header Button</button>
 </div>
 ```
 
-The scope classes are automatically prefixed with `group-data-[scope=...]/wind-scope:` to work with Tailwind's group modifier.
+The scope classes are automatically prefixed with `group-data-[scope=...]/wind-scope:` to target the parent's data attribute.
 
 ### Variants
 
-Variants are mutually exclusive options. Each variant dimension can have multiple options, but only one option per dimension can be active at a time.
+Variants represent mutually exclusive design choices (e.g., `primary` vs `secondary`). They serve as the foundation of your component's design system.
 
 ```typescript
-const button = windCtrl({
+const button = windctrl({
   variants: {
     intent: {
-      primary: "bg-blue-500",
-      secondary: "bg-gray-500",
+      primary: "bg-blue-500 text-white hover:bg-blue-600",
+      secondary: "bg-gray-100 text-gray-900 hover:bg-gray-200",
     },
     size: {
-      sm: "text-sm",
-      md: "text-base",
-      lg: "text-lg",
+      sm: "text-sm h-8 px-3",
+      md: "text-base h-10 px-4",
+      lg: "text-lg h-12 px-6",
     },
   },
+  defaultVariants: {
+    intent: "primary",
+    size: "md",
+  },
 });
 
 // Usage
 button({ intent: "primary", size: "lg" });
 ```
 
+## Gotchas
+
+- **Tailwind JIT:** Tailwind only generates CSS for class names it can statically detect. Avoid constructing class strings dynamically unless you safelist them.
+- **Traits precedence:** If trait order matters, use the array form (`traits: ["a", "b"]`) to make precedence explicit.
+- **SSR/RSC:** Keep dynamic resolvers pure (same input → same output) to avoid hydration mismatches.
+- **Static config:** `windctrl` configuration is treated as static/immutable. Mutating the config object after creation is not supported.
+
 ## License
 
 The MIT License (MIT)

package/dist/index.d.ts

@@ -26,5 +26,6 @@ type Result = {
     className: string;
     style?: CSSProperties;
 };
-export declare function windCtrl<TVariants extends Record<string, Record<string, ClassValue>> = {}, TTraits extends Record<string, ClassValue> = {}, TDynamic extends Record<string, DynamicResolver> = {}, TScopes extends Record<string, ClassValue> = {}>(config: Config<TVariants, TTraits, TDynamic, TScopes>): (props?: Props<TVariants, TTraits, TDynamic>) => Result;
+export declare function windctrl<TVariants extends Record<string, Record<string, ClassValue>> = {}, TTraits extends Record<string, ClassValue> = {}, TDynamic extends Record<string, DynamicResolver> = {}, TScopes extends Record<string, ClassValue> = {}>(config: Config<TVariants, TTraits, TDynamic, TScopes>): (props?: Props<TVariants, TTraits, TDynamic>) => Result;
+export declare const wc: typeof windctrl;
 export {};

package/dist/index.js

@@ -18,10 +18,10 @@ function processTraits(traits, propsTraits) {
     }
     return [];
 }
-function processDynamic(dynamic, props) {
+function processDynamicEntries(entries, props) {
     const classNameParts = [];
     const styles = [];
-    for (const [key, resolver] of Object.entries(dynamic)) {
+    for (const [key, resolver] of entries) {
         const value = props[key];
         if (value !== undefined && value !== null) {
             const result = resolver(value);
@@ -53,8 +53,11 @@ function processScopes(scopes) {
             .join(" ");
     });
 }
-export function windCtrl(config) {
+export function windctrl(config) {
     const { base, variants = {}, traits = {}, dynamic = {}, scopes = {}, defaultVariants = {}, } = config;
+    const resolvedVariants = Object.entries(variants);
+    const resolvedDynamicEntries = Object.entries(dynamic);
+    const resolvedScopeClasses = processScopes(scopes);
     return (props = {}) => {
         const classNameParts = [];
         let mergedStyle = {};
@@ -65,30 +68,26 @@ export function windCtrl(config) {
             classNameParts.push(base);
         }
         // 2. Variants (with defaultVariants fallback)
-        if (variants) {
-            for (const [variantKey, variantOptions] of Object.entries(variants)) {
-                const propValue = props[variantKey] ??
-                    defaultVariants[variantKey];
-                if (propValue && variantOptions[propValue]) {
-                    classNameParts.push(variantOptions[propValue]);
-                }
+        for (const [variantKey, variantOptions] of resolvedVariants) {
+            const propValue = props[variantKey] ??
+                defaultVariants[variantKey];
+            if (propValue && variantOptions[propValue]) {
+                classNameParts.push(variantOptions[propValue]);
             }
         }
         // 3. Traits (higher priority than variants)
-        if (traits && props.traits) {
-            const traitClasses = processTraits(traits, props.traits);
-            classNameParts.push(...traitClasses);
+        if (props.traits) {
+            classNameParts.push(...processTraits(traits, props.traits));
         }
         // 4. Dynamic (highest priority for className)
-        if (dynamic) {
-            const dynamicResult = processDynamic(dynamic, props);
+        if (resolvedDynamicEntries.length) {
+            const dynamicResult = processDynamicEntries(resolvedDynamicEntries, props);
             classNameParts.push(...dynamicResult.className);
             mergedStyle = mergeStyles(mergedStyle, dynamicResult.style);
         }
         // 5. Scopes (always applied, but don't conflict with other classes)
-        if (scopes) {
-            const scopeClasses = processScopes(scopes);
-            classNameParts.push(...scopeClasses);
+        if (resolvedScopeClasses.length) {
+            classNameParts.push(...resolvedScopeClasses);
         }
         const finalClassName = twMerge(clsx(classNameParts));
         const hasStyle = Object.keys(mergedStyle).length > 0;
@@ -98,3 +97,4 @@ export function windCtrl(config) {
         };
     };
 }
+export const wc = windctrl;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "windctrl",
-  "version": "0.0.1",
+  "version": "0.1.0",
   "description": "Advanced variant API for Tailwind CSS with stackable traits and interpolated dynamic styles.",
   "license": "MIT",
   "author": "Masaki Morishita (@morishxt)",
@@ -34,7 +34,7 @@
   ],
   "repository": {
     "type": "git",
-    "url": "https://github.com/morishxt/windctrl.git"
+    "url": "git+https://github.com/morishxt/windctrl.git"
   },
   "bugs": {
     "url": "https://github.com/morishxt/windctrl/issues"
@@ -42,8 +42,6 @@
   "homepage": "https://github.com/morishxt/windctrl#readme",
   "scripts": {
     "test": "vitest",
-    "test:watch": "vitest --watch",
-    "test:coverage": "vitest --coverage",
     "build": "tsc",
     "dev": "tsc --watch",
     "format": "prettier --write .",