refactor: split cn into cn and cnMerge functions (#286)

- Split cn function into two separate functions to avoid Proxy complexity
- cn: simple function that returns string directly with default twMerge config
- cnMerge: function that supports custom twMerge config via second call
- Update core.js to use cnMerge for config-based calls
- Update tests to reflect new API
- Update README with utility functions documentation
- Available from v3.2.2

Author: jrgarciadev

README.md

@@ -104,6 +104,59 @@ const button = tv({
 return <button className={button({size: "sm", color: "secondary"})}>Click me</button>;
 ```
 
+## Utility Functions
+
+Tailwind Variants provides several utility functions for combining and merging class names:
+
+### `cx` - Simple Concatenation
+
+Combines class names without merging conflicting classes (similar to `clsx`):
+
+```js
+import {cx} from "tailwind-variants";
+
+cx("text-xl", "font-bold"); // => "text-xl font-bold"
+cx("px-2", "px-4"); // => "px-2 px-4" (no merging)
+```
+
+### `cn` - Merge with Default Config
+
+> **Updated in v3.2.2** - Now returns a string directly (no function call needed)
+
+Combines class names and merges conflicting Tailwind CSS classes using the default `tailwind-merge` config. Returns a string directly:
+
+```js
+import {cn} from "tailwind-variants";
+
+cn("bg-red-500", "bg-blue-500"); // => "bg-blue-500"
+cn("px-2", "px-4", "py-2"); // => "px-4 py-2"
+```
+
+### `cnMerge` - Merge with Custom Config
+
+> **Available from v3.2.2**
+
+Combines class names and merges conflicting Tailwind CSS classes with support for custom `twMerge` configuration via a second function call:
+
+```js
+import {cnMerge} from "tailwind-variants";
+
+// Disable merging
+cnMerge("px-2", "px-4")({twMerge: false}) // => "px-2 px-4"
+
+// Enable merging explicitly
+cnMerge("bg-red-500", "bg-blue-500")({twMerge: true}) // => "bg-blue-500"
+
+// Use custom twMergeConfig
+cnMerge("px-2", "px-4")({twMergeConfig: {...}}) // => merged with custom config
+```
+
+**When to use which:**
+
+- Use `cx` when you want simple concatenation without any merging
+- Use `cn` for most cases when you want automatic conflict resolution with default settings
+- Use `cnMerge` when you need to customize the merge behavior (disable merging, custom config, etc.)
+
 ## Acknowledgements
 
 - [**cva**](https://github.com/joe-bell/cva) ([Joe Bell](https://github.com/joe-bell))

src/__tests__/cn.test.ts

@@ -1,6 +1,6 @@
 import {expect, describe, test} from "@jest/globals";
 
-import {cn as cnWithMerge, cx as cxFull} from "../index";
+import {cn, cnMerge, cx as cxFull} from "../index";
 import {cn as cnLite, cx as cxLite} from "../lite";
 import {cx as cxUtils} from "../utils";
 
@@ -85,127 +85,183 @@ describe("cn function from lite (simple concatenation)", () => {
 });
 
 describe("cn function with tailwind-merge (main index)", () => {
-  test("should merge conflicting tailwind classes when twMerge is true", () => {
-    const result = cnWithMerge("px-2", "px-4", "py-2")({twMerge: true});
+  test("should merge conflicting tailwind classes by default", () => {
+    const result = cn("px-2", "px-4", "py-2");
 
     expect(result).toBe("px-4 py-2");
   });
 
-  test("should not merge classes when twMerge is false", () => {
-    const result = cnWithMerge("px-2", "px-4", "py-2")({twMerge: false});
-
-    expect(result).toBe("px-2 px-4 py-2");
-  });
-
-  test("should merge text color classes", () => {
-    const result = cnWithMerge("text-red-500", "text-blue-500")({twMerge: true});
+  test("should merge text color classes by default", () => {
+    const result = cn("text-red-500", "text-blue-500");
 
     expect(result).toBe("text-blue-500");
   });
 
-  test("should merge background color classes", () => {
-    const result = cnWithMerge("bg-red-500", "bg-blue-500")({twMerge: true});
+  test("should merge background color classes by default", () => {
+    const result = cn("bg-red-500", "bg-blue-500");
 
     expect(result).toBe("bg-blue-500");
   });
 
   test("should merge multiple conflicting classes", () => {
-    const result = cnWithMerge("px-2 py-1 text-sm", "px-4 py-2 text-lg")({twMerge: true});
+    const result = cn("px-2 py-1 text-sm", "px-4 py-2 text-lg");
 
     expect(result).toBe("px-4 py-2 text-lg");
   });
 
   test("should handle non-conflicting classes", () => {
-    const result = cnWithMerge("px-2", "py-2", "text-sm")({twMerge: true});
+    const result = cn("px-2", "py-2", "text-sm");
 
     expect(result).toBe("px-2 py-2 text-sm");
   });
 
   test("should return undefined when no classes provided", () => {
-    const result = cnWithMerge()({twMerge: true});
+    const result = cn();
 
     expect(result).toBeUndefined();
   });
 
   test("should handle arrays with tailwind-merge", () => {
-    const result = cnWithMerge(["px-2", "px-4"], "py-2")({twMerge: true});
+    const result = cn(["px-2", "px-4"], "py-2");
 
     expect(result).toBe("px-4 py-2");
   });
 
   test("should handle objects with tailwind-merge", () => {
-    const result = cnWithMerge({"px-2": true, "px-4": true, "py-2": true})({twMerge: true});
+    const result = cn({"px-2": true, "px-4": true, "py-2": true});
 
     expect(result).toBe("px-4 py-2");
   });
 
-  test("should merge when config is undefined (default behavior)", () => {
-    const result = cnWithMerge("px-2", "px-4")({twMerge: true});
+  test("should handle complex className with conditional object classes", () => {
+    const selectedZoom: string = "a";
+    const key: string = "b";
 
-    expect(result).toBe("px-4");
+    const result = cn(
+      "text-foreground ease-in-out-quad absolute left-1/2 top-1/2 origin-center -translate-x-1/2 -translate-y-1/2 scale-75 text-[21px] font-medium opacity-0 transition-[scale,opacity] duration-[300ms] ease-[cubic-bezier(0.33,1,0.68,1)] data-[selected=true]:scale-100 data-[selected=true]:opacity-100 data-[selected=true]:delay-200",
+      {
+        "sr-only": selectedZoom !== key,
+      },
+    );
+
+    expect(result).toContain("text-foreground");
+    expect(result).toContain("sr-only");
+    expect(typeof result).toBe("string");
   });
 
-  test("should merge classes by default when called directly without ()", () => {
-    const result = cnWithMerge("px-2", "px-4", "py-2");
+  test("should handle conditional object classes when condition is false", () => {
+    const selectedZoom: string = "a";
+    const key: string = "a";
 
-    // Should work as a string in template literals and string coercion
-    expect(String(result)).toBe("px-4 py-2");
-    expect(`${result}`).toBe("px-4 py-2");
+    const result = cn("text-xl font-bold", {
+      "sr-only": selectedZoom !== key,
+    });
+
+    expect(result).toBe("text-xl font-bold");
+    expect(result).not.toContain("sr-only");
   });
+});
 
-  test("should merge classes by default when no config is provided", () => {
-    const result = cnWithMerge("px-2", "px-4", "py-2")();
+describe("cnMerge function with tailwind-merge config", () => {
+  test("should merge conflicting tailwind classes when twMerge is true", () => {
+    const result = cnMerge("px-2", "px-4", "py-2")({twMerge: true});
 
     expect(result).toBe("px-4 py-2");
   });
 
-  test("should merge text color classes by default when called directly", () => {
-    const result = cnWithMerge("text-red-500", "text-blue-500");
+  test("should not merge classes when twMerge is false", () => {
+    const result = cnMerge("px-2", "px-4", "py-2")({twMerge: false});
 
-    expect(String(result)).toBe("text-blue-500");
+    expect(result).toBe("px-2 px-4 py-2");
   });
 
-  test("should merge text color classes by default when no config is provided", () => {
-    const result = cnWithMerge("text-red-500", "text-blue-500")();
+  test("should merge text color classes", () => {
+    const result = cnMerge("text-red-500", "text-blue-500")({twMerge: true});
 
     expect(result).toBe("text-blue-500");
   });
 
-  test("should merge background color classes by default when called directly", () => {
-    const result = cnWithMerge("bg-red-500", "bg-blue-500");
+  test("should merge background color classes", () => {
+    const result = cnMerge("bg-red-500", "bg-blue-500")({twMerge: true});
 
-    expect(String(result)).toBe("bg-blue-500");
+    expect(result).toBe("bg-blue-500");
   });
 
-  test("should merge background color classes by default when no config is provided", () => {
-    const result = cnWithMerge("bg-red-500", "bg-blue-500")();
+  test("should merge multiple conflicting classes", () => {
+    const result = cnMerge("px-2 py-1 text-sm", "px-4 py-2 text-lg")({twMerge: true});
 
-    expect(result).toBe("bg-blue-500");
+    expect(result).toBe("px-4 py-2 text-lg");
   });
 
-  test("should not merge classes when twMerge is explicitly false", () => {
-    const result = cnWithMerge("px-2", "px-4", "py-2")({twMerge: false});
+  test("should handle non-conflicting classes", () => {
+    const result = cnMerge("px-2", "py-2", "text-sm")({twMerge: true});
 
-    expect(result).toBe("px-2 px-4 py-2");
+    expect(result).toBe("px-2 py-2 text-sm");
   });
 
-  test("should merge classes when twMerge is explicitly true (backward compatibility)", () => {
-    const result = cnWithMerge("px-2", "px-4", "py-2")({twMerge: true});
+  test("should return undefined when no classes provided", () => {
+    const result = cnMerge()({twMerge: true});
+
+    expect(result).toBeUndefined();
+  });
+
+  test("should handle arrays with tailwind-merge", () => {
+    const result = cnMerge(["px-2", "px-4"], "py-2")({twMerge: true});
 
     expect(result).toBe("px-4 py-2");
   });
 
-  test("should merge classes when config is empty object (defaults to true)", () => {
-    const result = cnWithMerge("px-2", "px-4", "py-2")({});
+  test("should handle objects with tailwind-merge", () => {
+    const result = cnMerge({"px-2": true, "px-4": true, "py-2": true})({twMerge: true});
+
+    expect(result).toBe("px-4 py-2");
+  });
+
+  test("should merge classes by default when no config is provided", () => {
+    const result = cnMerge("px-2", "px-4", "py-2")();
 
     expect(result).toBe("px-4 py-2");
   });
 
   test("should merge classes when config is undefined", () => {
-    const result = cnWithMerge("px-2", "px-4", "py-2")(undefined);
+    const result = cnMerge("px-2", "px-4", "py-2")(undefined);
+
+    expect(result).toBe("px-4 py-2");
+  });
+
+  test("should merge classes when config is empty object (defaults to true)", () => {
+    const result = cnMerge("px-2", "px-4", "py-2")({});
+
+    expect(result).toBe("px-4 py-2");
+  });
+
+  test("should not merge classes when twMerge is explicitly false", () => {
+    const result = cnMerge("px-2", "px-4", "py-2")({twMerge: false});
+
+    expect(result).toBe("px-2 px-4 py-2");
+  });
+
+  test("should merge classes when twMerge is explicitly true", () => {
+    const result = cnMerge("px-2", "px-4", "py-2")({twMerge: true});
 
     expect(result).toBe("px-4 py-2");
   });
+
+  test("should handle complex className with conditional object classes", () => {
+    const selectedZoom: string = "a";
+    const key: string = "b";
+
+    const result = cnMerge(
+      "text-foreground ease-in-out-quad absolute left-1/2 top-1/2 origin-center -translate-x-1/2 -translate-y-1/2 scale-75 text-[21px] font-medium opacity-0 transition-[scale,opacity] duration-[300ms] ease-[cubic-bezier(0.33,1,0.68,1)] data-[selected=true]:scale-100 data-[selected=true]:opacity-100 data-[selected=true]:delay-200",
+      {
+        "sr-only": selectedZoom !== key,
+      },
+    )();
+
+    expect(result).toContain("text-foreground");
+    expect(result).toContain("sr-only");
+    expect(typeof result).toBe("string");
+  });
 });
 
 describe.each(cxVariants)("cx function - $name", ({cx}) => {

src/__tests__/tv.test.ts

@@ -1,6 +1,6 @@
 import {expect, describe, test} from "@jest/globals";
 
-import {tv, cn} from "../index";
+import {tv, cnMerge} from "../index";
 
 const COMMON_UNITS = ["small", "medium", "large"];
 
@@ -2475,10 +2475,10 @@ describe("Tailwind Variants (TV) - Extends", () => {
     const tvResult = ["w-fit", "h-fit"];
     const custom = ["w-full"];
 
-    const resultWithoutMerge = cn(tvResult.concat(custom))({twMerge: false});
-    const resultWithMerge = cn(tvResult.concat(custom))({twMerge: true});
-    const emptyResultWithoutMerge = cn([].concat([]))({twMerge: false});
-    const emptyResultWithMerge = cn([].concat([]))({twMerge: true});
+    const resultWithoutMerge = cnMerge(tvResult.concat(custom))({twMerge: false});
+    const resultWithMerge = cnMerge(tvResult.concat(custom))({twMerge: true});
+    const emptyResultWithoutMerge = cnMerge([].concat([]))({twMerge: false});
+    const emptyResultWithMerge = cnMerge([].concat([]))({twMerge: true});
 
     expect(resultWithoutMerge).toBe("w-fit h-fit w-full");
     expect(resultWithMerge).toBe("h-fit w-full");

src/index.d.ts

@@ -22,34 +22,40 @@ export type * from "./types.d.ts";
 export declare const cx: <T extends CnOptions>(...classes: T) => CnReturn;
 
 /**
- * Type representing a callable function that can also be coerced to a string.
- * This allows `cn` to work both as a function and directly in template literals.
+ * Combines class names and merges conflicting Tailwind CSS classes using `tailwind-merge`.
+ * Uses default twMerge config. For custom config, use `cnMerge` instead.
+ * @param classes - Class names to combine (strings, arrays, objects, etc.)
+ * @returns A merged class string, or `undefined` if no valid classes are provided
+ * @example
+ * ```ts
+ * // Simple usage with default twMerge config
+ * cn('bg-red-500', 'bg-blue-500') // => 'bg-blue-500'
+ * cn('px-2', 'px-4', 'py-2') // => 'px-4 py-2'
+ *
+ * // For custom twMerge config, use cnMerge instead
+ * cnMerge('px-2', 'px-4')({twMerge: false}) // => 'px-2 px-4'
+ * ```
  */
-type CnCallable = ((config?: TWMConfig) => CnReturn) & {
-  toString(): string;
-  valueOf(): CnReturn;
-  [Symbol.toPrimitive](hint: "string" | "number" | "default"): string | CnReturn;
-} & string;
+export declare const cn: <T extends CnOptions>(...classes: T) => CnReturn;
 
 /**
  * Combines class names and merges conflicting Tailwind CSS classes using `tailwind-merge`.
+ * Supports custom twMerge config via the second function call.
  * @param classes - Class names to combine (strings, arrays, objects, etc.)
- * @returns A callable function that returns the merged class string. Works directly in template literals (coerces to string) or can be called with optional config.
+ * @returns A function that accepts optional twMerge config and returns the merged class string
  * @example
  * ```ts
- * // twMerge defaults to true - works directly in template literals
- * `${cn('bg-red-500', 'bg-blue-500')}` // => 'bg-blue-500'
- * String(cn('bg-red-500', 'bg-blue-500')) // => 'bg-blue-500'
- *
- * // Can still be called with config for explicit control
- * cn('bg-red-500', 'bg-blue-500')() // => 'bg-blue-500'
+ * // With custom config
+ * cnMerge('bg-red-500', 'bg-blue-500')({twMerge: true}) // => 'bg-blue-500'
+ * cnMerge('px-2', 'px-4')({twMerge: false}) // => 'px-2 px-4'
  *
- * // Note: If you need simple concatenation without merging, use `cx` instead:
- * // Instead of: cn('bg-red-500', 'bg-blue-500')({ twMerge: false })
- * // Use: cx('bg-red-500', 'bg-blue-500') // => 'bg-red-500 bg-blue-500'
+ * // With twMergeConfig
+ * cnMerge('px-2', 'px-4')({twMergeConfig: {...}}) // => merged with custom config
  * ```
  */
-export declare const cn: <T extends CnOptions>(...classes: T) => CnCallable;
+export declare const cnMerge: <T extends CnOptions>(
+  ...classes: T
+) => (config?: TWMConfig) => CnReturn;
 
 /**
  * Creates a variant-aware component function with Tailwind CSS classes.

src/index.js

@@ -1,8 +1,8 @@
 import {getTailwindVariants} from "./core.js";
-import {cn} from "./tw-merge.js";
+import {cn, cnMerge} from "./tw-merge.js";
 import {cx} from "./utils.js";
 import {defaultConfig} from "./config.js";
 
-export const {createTV, tv} = getTailwindVariants(cn);
+export const {createTV, tv} = getTailwindVariants(cnMerge);
 
-export {cn, cx, defaultConfig};
+export {cn, cnMerge, cx, defaultConfig};