windctrl 0.2.0 → 0.2.2

package/README.md

@@ -257,6 +257,61 @@ const button = windctrl({
 
 The scope classes are automatically prefixed with `group-data-[windctrl-scope=...]/windctrl-scope:` to target the parent's data attribute.
 
+## Merging External `className` Safely (`wcn()`)
+
+WindCtrl resolves Tailwind class conflicts **inside** `windctrl()` using `tailwind-merge`.
+However, in real applications you often need to merge **additional `className` values** at the component boundary.
+
+A simple string concat can reintroduce conflicts:
+
+```tsx
+// ⚠️ Can cause subtle Tailwind conflicts (e.g. p-2 vs p-4)
+className={`${result.className} ${className}`}
+```
+
+WindCtrl exports a small helper for this use case:
+
+```tsx
+import { wcn } from "windctrl";
+
+// ✅ Conflict-safe merge
+className={wcn(result.className, className)}
+```
+
+`wcn()` is equivalent to `twMerge(clsx(...))` and matches WindCtrl’s internal conflict resolution behavior.
+This keeps the “last one wins” behavior consistent across both generated and user-supplied classes.
+
+## Type Helpers (`StyleProps`)
+
+When building reusable components, you often want to expose the exact style-related props inferred from a `windctrl()` definition.
+
+WindCtrl exports a small type helper for this purpose:
+
+```typescript
+import type { StyleProps } from "windctrl";
+```
+
+`StyleProps<typeof styles>` extracts all variant, trait, and dynamic props from a WindCtrl instance — similar to `VariantProps` in cva.
+
+```typescript
+const button = windctrl({ ... });
+
+type ButtonProps<T extends ElementType = "button"> = {
+  as?: T;
+} & Omit<ComponentPropsWithoutRef<T>, keyof StyleProps<typeof button>>
+  & StyleProps<typeof button>;
+```
+
+This lets you:
+
+- Avoid manually duplicating variant/trait prop definitions
+- Keep component props automatically in sync with styling config
+- Refactor styles without touching component typings
+
+> `StyleProps` is optional - you can always define props manually if you prefer.
+
+> `wcProps` is provided as an alias of `StyleProps` for convenience.
+
 ## 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/dynamic.d.ts

@@ -0,0 +1,22 @@
+export type CSSProperties = Record<string, string | number>;
+export type DynamicResolverResult = string | {
+    className?: string;
+    style?: CSSProperties;
+};
+export 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;
+};
+export {};

package/dist/dynamic.js

@@ -0,0 +1,41 @@
+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,
+};

package/dist/index.d.ts

@@ -1,25 +1,6 @@
 import { type ClassValue } from "clsx";
-type CSSProperties = Record<string, string | number>;
-type DynamicResolverResult = string | {
-    className?: string;
-    style?: CSSProperties;
-};
-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;
-};
+import type { CSSProperties, DynamicResolver } from "./dynamic";
+export { dynamic, type CSSProperties, type DynamicResolver } from "./dynamic";
 type SlotAwareObject = {
     root?: ClassValue;
     slots?: Record<string, ClassValue>;
@@ -55,4 +36,6 @@ type Result<TSlotKeys extends string = never> = {
 };
 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 {};
+export declare function wcn(...inputs: ClassValue[]): string;
+export type StyleProps<T> = T extends (props?: infer P) => any ? P : never;
+export type wcProps<T> = StyleProps<T>;

package/dist/index.js

@@ -1,46 +1,6 @@
 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,
-};
+export { dynamic } from "./dynamic";
 function mergeStyles(...styles) {
     return Object.assign({}, ...styles.filter(Boolean));
 }
@@ -193,15 +153,18 @@ export function windctrl(config) {
         let finalSlots;
         const slotNames = Object.keys(slotParts);
         if (slotNames.length > 0) {
-            finalSlots = {};
+            const out = {};
             for (const slotName of slotNames) {
-                const merged = twMerge(clsx(slotParts[slotName]));
+                const parts = slotParts[slotName];
+                if (!parts)
+                    continue;
+                const merged = twMerge(clsx(parts));
                 if (merged) {
-                    finalSlots[slotName] = merged;
+                    out[slotName] = merged;
                 }
             }
-            if (Object.keys(finalSlots).length === 0) {
-                finalSlots = undefined;
+            if (Object.keys(out).length > 0) {
+                finalSlots = out;
             }
         }
         return {
@@ -212,3 +175,6 @@ export function windctrl(config) {
     };
 }
 export const wc = windctrl;
+export function wcn(...inputs) {
+    return twMerge(clsx(inputs));
+}

package/package.json

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