windctrl 0.0.1

package/LICENSE

@@ -0,0 +1,20 @@
+This software is released under the MIT license:
+
+Copyright (c) 2025 Masaki Morishita (@morishxt)
+
+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,154 @@
+# WindCtrl
+
+> Advanced variant API for Tailwind CSS with stackable traits and interpolated dynamic styles.
+
+**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.
+
+## 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).
+- ⚡ **JIT Optimized** - Prevents CSS bundle bloat by intelligently routing arbitrary values to 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.
+
+## Installation
+
+```bash
+npm install windctrl
+```
+
+## Quick Start
+
+```typescript
+import { windCtrl } from "windctrl";
+
+const button = windCtrl({
+  base: "rounded px-4 py-2 font-medium transition",
+  variants: {
+    intent: {
+      primary: "bg-blue-500 text-white hover:bg-blue-600",
+      secondary: "bg-gray-500 text-gray-900 hover:bg-gray-600",
+    },
+    size: {
+      sm: "text-sm",
+      md: "text-base",
+      lg: "text-lg",
+    },
+  },
+  traits: {
+    loading: "opacity-50 cursor-wait",
+    glass: "backdrop-blur bg-white/10",
+  },
+  dynamic: {
+    w: (val) =>
+      typeof val === "number" ? { style: { width: `${val}px` } } : `w-${val}`,
+  },
+  defaultVariants: {
+    intent: "primary",
+    size: "md",
+  },
+});
+
+// Usage
+const { className, style } = button({
+  intent: "primary",
+  size: "lg",
+  traits: ["loading", "glass"],
+  w: 200,
+});
+```
+
+## Core Concepts
+
+### Dynamic Props (Interpolated Variants)
+
+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.
+
+```typescript
+const button = windCtrl({
+  dynamic: {
+    w: (val) =>
+      typeof val === "number" ? { style: { width: `${val}px` } } : `w-${val}`,
+    h: (val) =>
+      typeof val === "number" ? { style: { height: `${val}px` } } : `h-${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
+```
+
+### Traits
+
+Traits are stackable, non-exclusive states. Unlike variants, multiple traits can be active simultaneously, solving the combinatorial explosion problem of `compoundVariants`.
+
+```typescript
+const button = windCtrl({
+  traits: {
+    loading: "opacity-50 cursor-wait",
+    glass: "backdrop-blur bg-white/10",
+    disabled: "pointer-events-none",
+  },
+});
+
+// Usage - Array form
+button({ traits: ["loading", "glass"] });
+
+// Usage - Object form
+button({ traits: { loading: true, glass: true, disabled: false } });
+```
+
+### Scopes
+
+Scopes provide context-aware styling without React Context, making it fully compatible with Server Components (RSC).
+
+```typescript
+const button = windCtrl({
+  scopes: {
+    header: "text-sm",
+    footer: "text-xs",
+  },
+});
+
+// Usage - Wrap elements with data-scope attribute
+<div data-scope="header" className="group/wind-scope">
+  <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.
+
+### 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.
+
+```typescript
+const button = windCtrl({
+  variants: {
+    intent: {
+      primary: "bg-blue-500",
+      secondary: "bg-gray-500",
+    },
+    size: {
+      sm: "text-sm",
+      md: "text-base",
+      lg: "text-lg",
+    },
+  },
+});
+
+// Usage
+button({ intent: "primary", size: "lg" });
+```
+
+## License
+
+The MIT License (MIT)
+
+Copyright (c) 2025 Masaki Morishita

package/dist/index.d.ts

@@ -0,0 +1,30 @@
+import { type ClassValue } from "clsx";
+type CSSProperties = Record<string, string | number>;
+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;
+    variants?: TVariants;
+    traits?: TTraits;
+    dynamic?: TDynamic;
+    scopes?: TScopes;
+    defaultVariants?: {
+        [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> = {}> = {
+    [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 = {
+    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 {};

package/dist/index.js

@@ -0,0 +1,100 @@
+import { clsx } from "clsx";
+import { twMerge } from "tailwind-merge";
+function mergeStyles(...styles) {
+    return Object.assign({}, ...styles.filter(Boolean));
+}
+function processTraits(traits, propsTraits) {
+    if (!propsTraits)
+        return [];
+    if (Array.isArray(propsTraits)) {
+        return propsTraits
+            .filter((key) => key in traits)
+            .map((key) => traits[key]);
+    }
+    if (typeof propsTraits === "object") {
+        return Object.entries(propsTraits)
+            .filter(([key, value]) => value && key in traits)
+            .map(([key]) => traits[key]);
+    }
+    return [];
+}
+function processDynamic(dynamic, props) {
+    const classNameParts = [];
+    const styles = [];
+    for (const [key, resolver] of Object.entries(dynamic)) {
+        const value = props[key];
+        if (value !== undefined && value !== null) {
+            const result = resolver(value);
+            if (typeof result === "string") {
+                classNameParts.push(result);
+            }
+            else {
+                if (result.className) {
+                    classNameParts.push(result.className);
+                }
+                if (result.style) {
+                    styles.push(result.style);
+                }
+            }
+        }
+    }
+    return {
+        className: classNameParts,
+        style: mergeStyles(...styles),
+    };
+}
+function processScopes(scopes) {
+    return Object.entries(scopes).map(([scopeName, scopeClasses]) => {
+        const classesStr = typeof scopeClasses === "string" ? scopeClasses : clsx(scopeClasses);
+        return classesStr
+            .split(/\s+/)
+            .filter(Boolean)
+            .map((cls) => `group-data-[scope=${scopeName}]/wind-scope:${cls}`)
+            .join(" ");
+    });
+}
+export function windCtrl(config) {
+    const { base, variants = {}, traits = {}, dynamic = {}, scopes = {}, defaultVariants = {}, } = config;
+    return (props = {}) => {
+        const classNameParts = [];
+        let mergedStyle = {};
+        // 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);
+        }
+        // 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]);
+                }
+            }
+        }
+        // 3. Traits (higher priority than variants)
+        if (traits && props.traits) {
+            const traitClasses = processTraits(traits, props.traits);
+            classNameParts.push(...traitClasses);
+        }
+        // 4. Dynamic (highest priority for className)
+        if (dynamic) {
+            const dynamicResult = processDynamic(dynamic, 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);
+        }
+        const finalClassName = twMerge(clsx(classNameParts));
+        const hasStyle = Object.keys(mergedStyle).length > 0;
+        return {
+            className: finalClassName,
+            ...(hasStyle && { style: mergedStyle }),
+        };
+    };
+}

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "windctrl",
+  "version": "0.0.1",
+  "description": "Advanced variant API for Tailwind CSS with stackable traits and interpolated dynamic styles.",
+  "license": "MIT",
+  "author": "Masaki Morishita (@morishxt)",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "tailwind",
+    "tailwindcss",
+    "variants",
+    "cva",
+    "styling",
+    "clsx",
+    "tailwind-merge",
+    "rsc",
+    "css-in-js",
+    "traits",
+    "interpolation"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/morishxt/windctrl.git"
+  },
+  "bugs": {
+    "url": "https://github.com/morishxt/windctrl/issues"
+  },
+  "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 .",
+    "format:check": "prettier --check .",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "devDependencies": {
+    "@types/node": "^25.0.3",
+    "@types/react": "^19.2.7",
+    "prettier": "^3.7.4",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.16"
+  },
+  "dependencies": {
+    "clsx": "^2.1.1",
+    "tailwind-merge": "^3.4.0"
+  },
+  "peerDependencies": {
+    "tailwindcss": "^4.0.0"
+  }
+}