tailwind-variants 3.2.1 → 3.3.0

package/README.md

@@ -24,57 +24,30 @@
 - Composition support
 - Fully typed
 - Framework agnostic
-- Automatic conflict resolution
-- Tailwindcss V4 support
+- Built-in conflict resolution
+- Tailwind CSS v4 support
 
-## Documentation
-
-For full documentation, visit [tailwind-variants.org](https://tailwind-variants.org)
-
-> ❕ Note: `Tailwindcss V4` no longer supports the `config.content.transform` so we remove the `responsive variants` feature
->
-> If you want to use `responsive variants`, you need to add it manually to your classname.
-
-## Quick Start
-
-1. Installation:
-   To use Tailwind Variants in your project, you can install it as a dependency:
+## Installation
 
 ```bash
-yarn add tailwind-variants
-# or
 npm i tailwind-variants
 # or
-pnpm add tailwind-variants
-```
-
-**Optional:** If you want automatic conflict resolution, also install `tailwind-merge`:
-
-```bash
-yarn add tailwind-merge
-# or
-npm i tailwind-merge
+yarn add tailwind-variants
 # or
-pnpm add tailwind-merge
+pnpm add tailwind-variants
 ```
 
-> **⚠️ Compatibility Note:** Supports Tailwind CSS v4.x (requires `tailwind-merge` v3.x). If you use Tailwind CSS v3.x, use tailwind-variants v0.x with [tailwind-merge v2.6.0](https://github.com/dcastil/tailwind-merge/tree/v2.6.0).
+**Lite mode:** import from `tailwind-variants/lite` for a smaller bundle without conflict resolution.
 
-> **💡 Lite mode (v3):** For smaller bundle size and faster runtime without conflict resolution, use the `/lite` import:
->
-> ```js
-> import {tv} from "tailwind-variants/lite";
-> ```
+**Upgrading?**
 
-> **⚠️ Upgrading?**
->
-> - From v2 to v3: See the [v3 migration guide](./MIGRATION-V3.md)
-> - From v1 to v2: See the [v2 migration guide](./MIGRATION-V2.md)
+- v2 → v3: [migration guide](./.docs/migrations/v2-to-v3.md)
+- v1 → v2: [migration guide](./.docs/migrations/v1-to-v2.md)
 
-2. Usage:
+## Quick Start
 
 ```js
-import {tv} from "tailwind-variants";
+import { tv } from "tailwind-variants";
 
 const button = tv({
   base: "font-medium bg-blue-500 text-white rounded-full active:opacity-80",
@@ -101,20 +74,113 @@ const button = tv({
   },
 });
 
-return <button className={button({size: "sm", color: "secondary"})}>Click me</button>;
+button({ size: "sm", color: "secondary" });
+// => "font-medium rounded-full active:opacity-80 bg-purple-500 text-white text-sm px-3 py-1"
+```
+
+> **Note:** Tailwind CSS v4 no longer supports `config.content.transform`, so responsive variants
+> were removed. Add responsive classes to your class names manually if needed.
+
+## Conflict Resolution
+
+Conflict resolution is built into the default entry — no extra package is required. It is available
+on `tv`, `createTV`, `cn`, and `cnMerge` (`cx` and `/lite` do not merge).
+
+```js
+import { tv, cn } from "tailwind-variants";
+
+cn("px-2", "px-4"); // => "px-4"
+
+tv({ base: "px-2", variants: { size: { lg: "px-4" } } })({ size: "lg" }); // => "px-4"
 ```
 
+### Custom configuration
+
+Pass `twMergeConfig` to teach the resolver about custom utilities. Prefer `{ extend, override }` —
+`extend` appends to the defaults, `override` replaces them:
+
+```ts
+import { cnMerge, createTV, tv, type TWMergeConfig } from "tailwind-variants";
+
+const twMergeConfig = {
+  extend: {
+    classGroups: {
+      elevation: ["elevation-low", "elevation-high"],
+    },
+  },
+} satisfies TWMergeConfig;
+
+tv({ base: "elevation-low", variants: { raised: { true: "elevation-high" } } }, { twMergeConfig });
+createTV({ twMergeConfig });
+cnMerge("elevation-low", "elevation-high")({ twMergeConfig }); // => "elevation-high"
+```
+
+Disable merging with `{ twMerge: false }` on `tv`, `createTV`, or `cnMerge`.
+
+### Reusing a `tailwind-merge` config
+
+If you already configure `extendTailwindMerge`, reuse the same config object as `twMergeConfig`
+(pass the object — not the returned merge function):
+
+```ts
+import { extendTailwindMerge } from "tailwind-merge";
+import { createTV, type TWMergeConfig } from "tailwind-variants";
+
+const mergeConfig = {
+  extend: {
+    classGroups: {
+      elevation: ["elevation-low", "elevation-high"],
+    },
+  },
+} satisfies TWMergeConfig;
+
+extendTailwindMerge(mergeConfig);
+createTV({ twMergeConfig: mergeConfig });
+```
+
+For `createTailwindMerge`, move the custom parts of the factory into `{ extend, override }` and pass
+that object. Merge functions and full default configs cannot be passed directly.
+
+## Utility Functions
+
+| Function  | Behavior                                             |
+| --------- | ---------------------------------------------------- |
+| `cx`      | Concatenate class names (no merging)                 |
+| `cn`      | Concatenate and merge with the default config        |
+| `cnMerge` | Concatenate and merge, with optional per-call config |
+
+```js
+import { cx, cn, cnMerge } from "tailwind-variants";
+
+cx("px-2", "px-4"); // => "px-2 px-4"
+cn("px-2", "px-4"); // => "px-4"
+cnMerge("px-2", "px-4")({ twMerge: false }); // => "px-2 px-4"
+```
+
+## Documentation
+
+For full documentation, visit [tailwind-variants.org](https://tailwind-variants.org).
+
 ## Acknowledgements
 
 - [**cva**](https://github.com/joe-bell/cva) ([Joe Bell](https://github.com/joe-bell))
-  This project as started as an extension of Joe's work on `cva` – a great tool for generating variants for a single element with Tailwind CSS. Big shoutout to [Joe Bell](https://github.com/joe-bell) and [contributors](https://github.com/joe-bell/cva/graphs/contributors) you guys rock! 🤘 - we recommend to use `cva` if don't need any of the **Tailwind Variants** features listed [here](https://www.tailwind-variants.org/docs/comparison).
+  This project started as an extension of Joe's work on `cva` — a great tool for generating variants
+  for a single element with Tailwind CSS. Big shoutout to [Joe Bell](https://github.com/joe-bell) and
+  [contributors](https://github.com/joe-bell/cva/graphs/contributors)! If you don't need the
+  **Tailwind Variants** features listed
+  [here](https://www.tailwind-variants.org/docs/comparison), we recommend `cva`.
 
-- [**Stitches**](https://stitches.dev/) ([Modulz](https://modulz.app))  
-  The pioneers of the `variants` API movement. Inmense thanks to [Modulz](https://modulz.app) for their work on Stitches and the community around it. 🙏
+- [**Stitches**](https://stitches.dev/) ([Modulz](https://modulz.app))
+  The pioneers of the `variants` API movement. Immense thanks to [Modulz](https://modulz.app) for
+  their work on Stitches and the community around it.
+
+- [**tailwind-merge**](https://github.com/dcastil/tailwind-merge), [**clsx**](https://github.com/lukeed/clsx), and [**cnfast**](https://github.com/aidenybai/cnfast)
+  Conflict resolution draws on ideas and MIT-licensed work from these projects.
 
 ## Community
 
-We're excited to see the community adopt HeroUI, raise issues, and provide feedback. Whether it's a feature request, bug report, or a project to showcase, please get involved!
+We're excited to see the community adopt HeroUI, raise issues, and provide feedback. Whether it's a
+feature request, bug report, or a project to showcase, please get involved!
 
 - [Discord](https://discord.gg/9b6yyZKmH4)
 - [Twitter](https://twitter.com/getnextui)
@@ -124,17 +190,15 @@ We're excited to see the community adopt HeroUI, raise issues, and provide feedb
 
 Contributions are always welcome!
 
-Please follow our [contributing guidelines](./CONTRIBUTING.md).
-
-Please adhere to this project's [CODE_OF_CONDUCT](./CODE_OF_CONDUCT.md).
+- [Contributing guidelines](./CONTRIBUTING.md)
+- [Code of conduct](./CODE_OF_CONDUCT.md)
+- [Security policy](./SECURITY.md)
 
 ## Authors
 
-- Junior garcia ([@jrgarciadev](https://github.com/jrgaciadev))
+- Junior Garcia ([@jrgarciadev](https://github.com/jrgarciadev))
 - Tianen Pang ([@tianenpang](https://github.com/tianenpang))
 
 ## License
 
-Licensed under the MIT License.
-
-See [LICENSE](./LICENSE.md) for more information.
+Licensed under the MIT License. See [LICENSE](./LICENSE.md) for more information.

package/dist/chunk-2BFDQGZN.cjs

@@ -0,0 +1,160 @@
+'use strict';
+
+// src/internal/join-class-value.ts
+var isArray = Array.isArray;
+var joinClassValue = (value) => {
+  if (!value && value !== 0 && value !== 0n) return "";
+  if (typeof value === "string") return value;
+  if (typeof value === "number") {
+    if (value !== value) return "";
+    return "" + value;
+  }
+  if (typeof value === "bigint") return "" + value;
+  let result = "";
+  if (isArray(value)) {
+    const length = value.length;
+    for (let index = 0; index < length; index++) {
+      const item = value[index];
+      if (!item && item !== 0 && item !== 0n) continue;
+      const resolved = typeof item === "string" ? item : joinClassValue(item);
+      if (resolved) {
+        if (result) result += " ";
+        result += resolved;
+      }
+    }
+    return result;
+  }
+  if (typeof value === "object") {
+    for (const key in value) {
+      if (value[key]) {
+        if (result) result += " ";
+        result += key;
+      }
+    }
+  }
+  return result;
+};
+
+// src/utils.ts
+var SPACE_REGEX = /\s+/g;
+var isArray2 = Array.isArray;
+var removeExtraSpaces = (str) => {
+  if (typeof str !== "string" || !str) return str;
+  return str.replace(SPACE_REGEX, " ").trim();
+};
+var stringNeedsNormalize = (str) => {
+  const len = str.length;
+  if (len === 0) return false;
+  const first = str.charCodeAt(0);
+  const last = str.charCodeAt(len - 1);
+  if (first === 32 || last === 32 || first >= 9 && first <= 13 || first === 160 || last >= 9 && last <= 13 || last === 160) {
+    return true;
+  }
+  for (let i = 0; i < len; i++) {
+    const code = str.charCodeAt(i);
+    if (code >= 9 && code <= 13 || code === 160) return true;
+    if (code === 32 && i + 1 < len && str.charCodeAt(i + 1) === 32) return true;
+  }
+  return false;
+};
+var cx = (...classnames) => {
+  const result = joinClassValue(classnames);
+  if (!result) return void 0;
+  return stringNeedsNormalize(result) ? removeExtraSpaces(result) : result;
+};
+var falsyToString = (value) => value === false ? "false" : value === true ? "true" : value === 0 ? "0" : value;
+var isEmptyObject = (obj) => {
+  if (!obj || typeof obj !== "object") return true;
+  for (const _ in obj) return false;
+  return true;
+};
+var isEqual = (obj1, obj2) => {
+  if (obj1 === obj2) return true;
+  if (!obj1 || !obj2) return false;
+  const record1 = obj1;
+  const record2 = obj2;
+  const keys1 = Object.keys(record1);
+  const keys2 = Object.keys(record2);
+  if (keys1.length !== keys2.length) return false;
+  for (let i = 0; i < keys1.length; i++) {
+    const key = keys1[i];
+    if (!keys2.includes(key)) return false;
+    if (record1[key] !== record2[key]) return false;
+  }
+  return true;
+};
+var isBoolean = (value) => value === true || value === false;
+var joinObjects = (obj1, obj2) => {
+  const target = obj1;
+  for (const key in obj2) {
+    if (Object.hasOwn(obj2, key)) {
+      const val2 = obj2[key];
+      if (key in target) {
+        target[key] = cx(target[key], val2);
+      } else {
+        target[key] = val2;
+      }
+    }
+  }
+  return obj1;
+};
+var flat = (arr, target) => {
+  for (let i = 0; i < arr.length; i++) {
+    const el = arr[i];
+    if (isArray2(el)) flat(el, target);
+    else if (el) target.push(el);
+  }
+};
+function flatArray(arr) {
+  const flattened = [];
+  flat(arr, flattened);
+  return flattened;
+}
+var flatMergeArrays = (...arrays) => {
+  const result = [];
+  flat(arrays, result);
+  const filtered = [];
+  for (let i = 0; i < result.length; i++) {
+    if (result[i]) filtered.push(result[i]);
+  }
+  return filtered;
+};
+var mergeObjects = (obj1, obj2) => {
+  const record1 = obj1;
+  const record2 = obj2;
+  const result = {};
+  for (const key in record1) {
+    const val1 = record1[key];
+    if (key in record2) {
+      const val2 = record2[key];
+      if (isArray2(val1) || isArray2(val2)) {
+        result[key] = flatMergeArrays(val2, val1);
+      } else if (typeof val1 === "object" && typeof val2 === "object" && val1 && val2) {
+        result[key] = mergeObjects(val1, val2);
+      } else {
+        result[key] = val2 + " " + val1;
+      }
+    } else {
+      result[key] = val1;
+    }
+  }
+  for (const key in record2) {
+    if (!(key in record1)) {
+      result[key] = record2[key];
+    }
+  }
+  return result;
+};
+
+exports.cx = cx;
+exports.falsyToString = falsyToString;
+exports.flat = flat;
+exports.flatArray = flatArray;
+exports.flatMergeArrays = flatMergeArrays;
+exports.isBoolean = isBoolean;
+exports.isEmptyObject = isEmptyObject;
+exports.isEqual = isEqual;
+exports.joinClassValue = joinClassValue;
+exports.joinObjects = joinObjects;
+exports.mergeObjects = mergeObjects;
+exports.removeExtraSpaces = removeExtraSpaces;