windctrl 0.1.1 → 0.2.1

package/README.md

@@ -4,14 +4,15 @@
 
 **WindCtrl** is a next-generation styling utility that unifies static Tailwind classes and dynamic inline styles into a single, type-safe interface.
 
-It evolves the concept of Variant APIs (like [cva](https://cva.style/)) by introducing **Stackable Traits** to solve combinatorial explosion and **Interpolated Variants** for seamless dynamic value handling—all while maintaining a minimal runtime footprint optimized for Tailwind's JIT compiler.
+It builds on existing variant APIs (like [cva](https://cva.style/)) and introduces **Stackable Traits** to avoid combinatorial explosion, as well as **Interpolated Variants** for seamless dynamic styling.
+All of this is achieved with a minimal runtime footprint and full compatibility with Tailwind's JIT compiler.
 
 ## Features
 
-- 🎨 **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).
+- 🎨 **Unified API** - Seamlessly blends static Tailwind classes and dynamic inline styles into one cohesive interface.
 - ⚡ **JIT Conscious** - Designed for Tailwind JIT: utilities stay as class strings, while truly dynamic values can be expressed as inline styles.
+- 🎯 **Scoped Styling** - Context-aware styling using data attributes - no React Context required (RSC friendly).
 - 🔒 **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,7 +25,7 @@ npm install windctrl
 ## Quick Start
 
 ```typescript
-import { windctrl } from "windctrl";
+import { windctrl, dynamic as d } from "windctrl";
 
 const button = windctrl({
   base: "rounded px-4 py-2 font-medium transition duration-200",
@@ -44,8 +45,7 @@ const button = windctrl({
     glass: "backdrop-blur-md bg-white/10 border border-white/20 shadow-xl",
   },
   dynamic: {
-    w: (val) =>
-      typeof val === "number" ? { style: { width: `${val}px` } } : val,
+    w: d.px("width"),
   },
   defaultVariants: {
     intent: "primary",
@@ -70,34 +70,33 @@ button({ w: "w-full" });
 
 ## Core Concepts
 
-### 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:
-
-- a **Tailwind class string** (static utility), or
-- an object containing **className and/or style** (inline styles and optional utilities)
+### Variants
 
-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.
+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({
-  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` } } : val,
+  variants: {
+    intent: {
+      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 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({ w: "w-full" }); // -> className includes "w-full" (static utility)
-button({ w: 200 }); // -> style includes { width: "200px" } (dynamic value)
+button({ intent: "primary", size: "lg" });
 ```
 
-> **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 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`.
@@ -123,55 +122,141 @@ button({ traits: ["loading", "glass"] });
 button({ traits: { loading: isLoading, glass: true } });
 ```
 
-### Scopes (RSC Support)
+### Slots (Compound Components)
 
-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.
+Slots allow you to define styles for **sub-elements** (e.g., icon, label) within a single component definition. Each slot returns its own class string, enabling clean compound component patterns.
+
+Slots are completely optional and additive. You can start with a single-root component and introduce slots only when needed.
+If a slot is never defined, it simply won't appear in the result.
 
 ```typescript
 const button = windctrl({
-  scopes: {
-    header: "text-sm py-1",
-    footer: "text-xs text-gray-500",
+  base: {
+    root: "inline-flex items-center gap-2 rounded px-4 py-2",
+    slots: {
+      icon: "shrink-0",
+      label: "truncate",
+    },
+  },
+  variants: {
+    size: {
+      sm: {
+        root: "h-8 text-sm",
+        slots: { icon: "h-3 w-3" },
+      },
+      md: {
+        root: "h-10 text-base",
+        slots: { icon: "h-4 w-4" },
+      },
+    },
+  },
+  traits: {
+    loading: {
+      root: "opacity-70 pointer-events-none",
+      slots: { icon: "animate-spin" },
+    },
   },
+  defaultVariants: { size: "md" },
 });
 
 // Usage
-// 1. Wrap the parent with `data-windctrl-scope` and `group/windctrl-scope`
-// 2. The button automatically adapts its style based on the parent
-<div data-windctrl-scope="header" className="group/windctrl-scope">
-  <button className={button().className}>Header Button</button>
-</div>
+const { className, slots } = button({ size: "sm", traits: ["loading"] });
+
+// Apply to elements
+<button className={className}>
+  <Icon className={slots?.icon} />
+  <span className={slots?.label}>Click me</span>
+</button>
 ```
 
-The scope classes are automatically prefixed with `group-data-[windctrl-scope=...]/windctrl-scope:` to target the parent's data attribute.
+Slots follow the same priority rules as root classes: **Base < Variants < Traits**, with `tailwind-merge` handling conflicts.
 
-### Variants
+Unlike slot-based APIs that require declaring all slots upfront, WindCtrl allows slots to emerge naturally from variants and traits.
 
-Variants represent mutually exclusive design choices (e.g., `primary` vs `secondary`). They serve as the foundation of your component's design system.
+### 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:
+
+- 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.
+
+#### Dynamic Presets
+
+WindCtrl provides built-in presets for common dynamic patterns:
+
+```typescript
+import { windctrl, dynamic as d } from "windctrl";
+
+const box = windctrl({
+  dynamic: {
+    // d.px() - pixel values (width, height, top, left, etc.)
+    w: d.px("width"),
+    h: d.px("height"),
+
+    // d.num() - unitless numbers (zIndex, flexGrow, order, etc.)
+    z: d.num("zIndex"),
+
+    // d.opacity() - opacity values
+    fade: d.opacity(),
+
+    // d.var() - CSS custom properties
+    x: d.var("--translate-x", { unit: "px" }),
+  },
+});
+
+// Usage
+box({ w: 200 }); // -> style: { width: "200px" }
+box({ w: "w-full" }); // -> className: "w-full"
+box({ z: 50 }); // -> style: { zIndex: 50 }
+box({ fade: 0.5 }); // -> style: { opacity: 0.5 }
+box({ x: 10 }); // -> style: { "--translate-x": "10px" }
+```
+
+#### Custom Resolvers
+
+You can also write custom resolvers for more complex logic:
 
 ```typescript
 const button = windctrl({
-  variants: {
-    intent: {
-      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 h-8 px-3",
-      md: "text-base h-10 px-4",
-      lg: "text-lg h-12 px-6",
-    },
+  dynamic: {
+    // Custom resolver example
+    w: (val) =>
+      typeof val === "number" ? { style: { width: `${val}px` } } : val,
   },
-  defaultVariants: {
-    intent: "primary",
-    size: "md",
+});
+
+// Usage
+button({ w: "w-full" }); // -> className includes "w-full" (static utility)
+button({ w: 200 }); // -> style includes { width: "200px" } (dynamic value)
+```
+
+> **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.
+
+### Scopes (RSC Support)
+
+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({
+  scopes: {
+    header: "text-sm py-1",
+    footer: "text-xs text-gray-500",
   },
 });
 
 // Usage
-button({ intent: "primary", size: "lg" });
+// 1. Wrap the parent with `data-windctrl-scope` and `group/windctrl-scope`
+// 2. The button automatically adapts its style based on the parent
+<div data-windctrl-scope="header" className="group/windctrl-scope">
+  <button className={button().className}>Header Button</button>
+</div>
 ```
 
+The scope classes are automatically prefixed with `group-data-[windctrl-scope=...]/windctrl-scope:` to target the parent's data attribute.
+
 ## Gotchas
 
 - **Tailwind JIT:** Tailwind only generates CSS for class names it can statically detect. Avoid constructing class strings dynamically unless you safelist them.

package/dist/index.d.ts

@@ -4,9 +4,29 @@ type DynamicResolverResult = string | {
     className?: string;
     style?: CSSProperties;
 };
-type DynamicResolver = (value: any) => DynamicResolverResult;
-type Config<TVariants extends Record<string, Record<string, ClassValue>> = {}, TTraits extends Record<string, ClassValue> = {}, TDynamic extends Record<string, DynamicResolver> = {}, TScopes extends Record<string, ClassValue> = {}> = {
-    base?: ClassValue;
+type DynamicResolver<T = any> = (value: T) => DynamicResolverResult;
+type PxProp = "width" | "height" | "minWidth" | "maxWidth" | "minHeight" | "maxHeight" | "top" | "right" | "bottom" | "left";
+type NumProp = "zIndex" | "flexGrow" | "flexShrink" | "order";
+type VarUnit = "px" | "%" | "deg" | "ms";
+declare function px(prop: PxProp): DynamicResolver<number | string>;
+declare function num(prop: NumProp): DynamicResolver<number | string>;
+declare function opacity(): DynamicResolver<number | string>;
+declare function cssVar(name: `--${string}`, options?: {
+    unit?: VarUnit;
+}): DynamicResolver<number | string>;
+export declare const dynamic: {
+    px: typeof px;
+    num: typeof num;
+    opacity: typeof opacity;
+    var: typeof cssVar;
+};
+type SlotAwareObject = {
+    root?: ClassValue;
+    slots?: Record<string, ClassValue>;
+};
+type SlotAwareValue = ClassValue | SlotAwareObject;
+type Config<TVariants extends Record<string, Record<string, SlotAwareValue>> = {}, TTraits extends Record<string, SlotAwareValue> = {}, TDynamic extends Record<string, DynamicResolver> = {}, TScopes extends Record<string, ClassValue> = {}> = {
+    base?: SlotAwareValue;
     variants?: TVariants;
     traits?: TTraits;
     dynamic?: TDynamic;
@@ -15,17 +35,24 @@ type Config<TVariants extends Record<string, Record<string, ClassValue>> = {}, T
         [K in keyof TVariants]?: keyof TVariants[K] extends string ? keyof TVariants[K] : never;
     };
 };
-type Props<TVariants extends Record<string, Record<string, ClassValue>> = {}, TTraits extends Record<string, ClassValue> = {}, TDynamic extends Record<string, DynamicResolver> = {}> = {
+type Props<TVariants extends Record<string, Record<string, SlotAwareValue>> = {}, TTraits extends Record<string, SlotAwareValue> = {}, TDynamic extends Record<string, DynamicResolver> = {}> = {
     [K in keyof TVariants]?: keyof TVariants[K] extends string ? keyof TVariants[K] : never;
 } & {
     traits?: Array<keyof TTraits extends string ? keyof TTraits : never> | Partial<Record<keyof TTraits extends string ? keyof TTraits : never, boolean>>;
 } & {
     [K in keyof TDynamic]?: Parameters<TDynamic[K]>[0];
 };
-type Result = {
+type SlotsOfValue<V> = V extends {
+    slots?: infer S;
+} ? S extends Record<string, any> ? keyof S : never : never;
+type VariantOptionValues<T> = T extends Record<string, Record<string, infer V>> ? V : never;
+type TraitValues<T> = T extends Record<string, infer V> ? V : never;
+type SlotKeys<TBase, TVariants extends Record<string, Record<string, any>>, TTraits extends Record<string, any>> = Extract<SlotsOfValue<TBase> | SlotsOfValue<VariantOptionValues<TVariants>> | SlotsOfValue<TraitValues<TTraits>>, string>;
+type Result<TSlotKeys extends string = never> = {
     className: string;
     style?: CSSProperties;
+    slots?: Partial<Record<TSlotKeys, string>>;
 };
-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, SlotAwareValue>> = {}, TTraits extends Record<string, SlotAwareValue> = {}, TDynamic extends Record<string, DynamicResolver> = {}, TScopes extends Record<string, ClassValue> = {}>(config: Config<TVariants, TTraits, TDynamic, TScopes>): (props?: Props<TVariants, TTraits, TDynamic>) => Result<SlotKeys<typeof config.base, TVariants, TTraits>>;
 export declare const wc: typeof windctrl;
 export {};

package/dist/index.js

@@ -1,22 +1,99 @@
 import { clsx } from "clsx";
 import { twMerge } from "tailwind-merge";
+function px(prop) {
+    return (value) => {
+        if (typeof value === "number") {
+            return { style: { [prop]: `${value}px` } };
+        }
+        return value;
+    };
+}
+function num(prop) {
+    return (value) => {
+        if (typeof value === "number") {
+            return { style: { [prop]: value } };
+        }
+        return value;
+    };
+}
+function opacity() {
+    return (value) => {
+        if (typeof value === "number") {
+            return { style: { opacity: value } };
+        }
+        return value;
+    };
+}
+function cssVar(name, options) {
+    return (value) => {
+        if (typeof value === "number") {
+            if (options?.unit) {
+                return { style: { [name]: `${value}${options.unit}` } };
+            }
+            return { style: { [name]: String(value) } };
+        }
+        return { style: { [name]: value } };
+    };
+}
+export const dynamic = {
+    px,
+    num,
+    opacity,
+    var: cssVar,
+};
 function mergeStyles(...styles) {
     return Object.assign({}, ...styles.filter(Boolean));
 }
-function processTraits(traits, propsTraits) {
+function isSlotAwareValue(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return false;
+    }
+    const obj = value;
+    const hasRoot = "root" in obj;
+    const hasSlots = "slots" in obj && typeof obj.slots === "object" && obj.slots !== null;
+    return hasRoot || hasSlots;
+}
+function addSlotClasses(slotParts, slots) {
+    for (const [slotName, slotClasses] of Object.entries(slots)) {
+        if (!slotParts[slotName]) {
+            slotParts[slotName] = [];
+        }
+        slotParts[slotName].push(slotClasses);
+    }
+}
+function processTraits(traits, propsTraits, slotParts) {
     if (!propsTraits)
         return [];
+    const rootClasses = [];
+    const processTraitKey = (key) => {
+        if (!(key in traits))
+            return;
+        const traitValue = traits[key];
+        if (isSlotAwareValue(traitValue)) {
+            if (traitValue.root) {
+                rootClasses.push(traitValue.root);
+            }
+            if (traitValue.slots && slotParts) {
+                addSlotClasses(slotParts, traitValue.slots);
+            }
+        }
+        else {
+            rootClasses.push(traitValue);
+        }
+    };
     if (Array.isArray(propsTraits)) {
-        return propsTraits
-            .filter((key) => key in traits)
-            .map((key) => traits[key]);
+        for (const key of propsTraits) {
+            processTraitKey(key);
+        }
     }
-    if (typeof propsTraits === "object") {
-        return Object.entries(propsTraits)
-            .filter(([key, value]) => value && key in traits)
-            .map(([key]) => traits[key]);
+    else if (typeof propsTraits === "object") {
+        for (const [key, value] of Object.entries(propsTraits)) {
+            if (value) {
+                processTraitKey(key);
+            }
+        }
     }
-    return [];
+    return rootClasses;
 }
 function processDynamicEntries(entries, props) {
     const classNameParts = [];
@@ -61,23 +138,45 @@ export function windctrl(config) {
     return (props = {}) => {
         const classNameParts = [];
         let mergedStyle = {};
+        const slotParts = {};
         // Priority order: Base < Variants < Traits < Dynamic
         // (Higher priority classes are added later, so tailwind-merge will keep them)
         // 1. Base classes (lowest priority)
         if (base) {
-            classNameParts.push(base);
+            if (isSlotAwareValue(base)) {
+                if (base.root) {
+                    classNameParts.push(base.root);
+                }
+                if (base.slots) {
+                    addSlotClasses(slotParts, base.slots);
+                }
+            }
+            else {
+                classNameParts.push(base);
+            }
         }
         // 2. Variants (with defaultVariants fallback)
         for (const [variantKey, variantOptions] of resolvedVariants) {
             const propValue = props[variantKey] ??
                 defaultVariants[variantKey];
             if (propValue && variantOptions[propValue]) {
-                classNameParts.push(variantOptions[propValue]);
+                const optionValue = variantOptions[propValue];
+                if (isSlotAwareValue(optionValue)) {
+                    if (optionValue.root) {
+                        classNameParts.push(optionValue.root);
+                    }
+                    if (optionValue.slots) {
+                        addSlotClasses(slotParts, optionValue.slots);
+                    }
+                }
+                else {
+                    classNameParts.push(optionValue);
+                }
             }
         }
         // 3. Traits (higher priority than variants)
         if (props.traits) {
-            classNameParts.push(...processTraits(traits, props.traits));
+            classNameParts.push(...processTraits(traits, props.traits, slotParts));
         }
         // 4. Dynamic (highest priority for className)
         if (resolvedDynamicEntries.length) {
@@ -91,9 +190,27 @@ export function windctrl(config) {
         }
         const finalClassName = twMerge(clsx(classNameParts));
         const hasStyle = Object.keys(mergedStyle).length > 0;
+        let finalSlots;
+        const slotNames = Object.keys(slotParts);
+        if (slotNames.length > 0) {
+            const out = {};
+            for (const slotName of slotNames) {
+                const parts = slotParts[slotName];
+                if (!parts)
+                    continue;
+                const merged = twMerge(clsx(parts));
+                if (merged) {
+                    out[slotName] = merged;
+                }
+            }
+            if (Object.keys(out).length > 0) {
+                finalSlots = out;
+            }
+        }
         return {
             className: finalClassName,
             ...(hasStyle && { style: mergedStyle }),
+            ...(finalSlots && { slots: finalSlots }),
         };
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "windctrl",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "description": "Advanced variant API for Tailwind CSS with stackable traits and interpolated dynamic styles.",
   "license": "MIT",
   "author": "Masaki Morishita (@morishxt)",