css-variants 2.0.6 → 2.0.8

package/README.md

@@ -1,5 +1,3 @@
-![Logo](.github/assets/logo.png)
-
 [![test](https://github.com/timphandev/css-variants/actions/workflows/ci.yml/badge.svg)](https://github.com/timphandev/css-variants/actions/workflows/ci.yml)
 [![license](https://img.shields.io/github/license/timphandev/css-variants)](https://github.com/timphandev/css-variants/blob/main/LICENSE)
 [![npm](https://img.shields.io/npm/dm/css-variants)](https://npmjs.com/package/css-variants)
@@ -7,470 +5,365 @@
 
 # css-variants
 
-A lightweight, flexible API for managing CSS class variants in JavaScript and TypeScript projects.
+A lightweight, flexible API for managing CSS class variants and inline styles in JavaScript and TypeScript projects.
 
 ## Features
 
-- 🎨 Dynamic class name generation based on variants
-- 🔧 Support for inline styles alongside class names
-- 🧩 Slot-based variant system for complex components
+- 🎨 Dynamic class name generation with variant support
+- 💅 First-class inline styles support alongside class names  
+- 🧩 Powerful slot-based variant system for complex components
 - 📦 Zero dependencies
 - 🔒 Fully type-safe with TypeScript
 - 🚀 Framework-agnostic
-
-## Overview
-
-`css-variants` provides a simple yet powerful way to handle dynamic class names and inline styles based on component props or state. It's designed to work seamlessly with modern JavaScript frameworks and CSS methodologies, offering a type-safe approach to styling your UI components.
-
-`css-variants` is heavily inspired by the following excellent packages:
-
-- [CVA (Class Variance Authority)](https://github.com/joe-bell/cva): A powerful utility for creating dynamic class names with variants.
-- [Tailwind Variants](https://github.com/nextui-org/tailwind-variants): A flexible and reusable variant system for Tailwind CSS.
-- [Panda CSS](https://github.com/chakra-ui/panda): A CSS-in-JS solution with a focus on developer experience and performance.
-
-Thank you to the authors and contributors of these projects for their innovative work.
-
-## Table of Contents
-* [Installation](#installation)
-* [Variants](#variants)
-  * [Adding variants](#adding-variants)
-  * [Multiple variants](#multiple-variants)
-  * [Boolean variants](#boolean-variants)
-  * [Compound variants](#compound-variants)
-  * [Default variants](#default-variants)
-* [Slots](#events)
-  * [Basic Usage](#basic-usage)
-  * [Slots with variants](#slots-with-variants)
-* [Overriding styles](#overriding-styles)
-  * [Overriding styles on a single component](#overriding-styles-on-a-single-component)
-  * [Overriding styles on a component with slots](#overriding-styles-on-a-component-with-slots)
-* [Custom function to resolve class names](#custom-function-to-resolve-class-names)
-* [TypeScript](#typeScript)
-* [Contribute](#contribute)
-* [License](#license)
-
+- 🪶 Lightweight (~2KB gzipped)
+- 🔥 Strong tree-shaking support
+- ⚡️ Optimal runtime performance
 
 ## Installation
 
-To use `css-variants` in your project, you can install it as a dependency:
+```bash
+# npm
+npm install css-variants
 
-```sh
+# yarn
 yarn add css-variants
+
+# pnpm 
+pnpm add css-variants
 ```
 
-## Variants
+## Core Utilities
 
-Variants allows you to create multiple versions of the same component.
+css-variants provides four main utilities:
 
-### Adding variants
+- [cv](#class-variants-cv) - Class Variants for managing single component class names
+- [sv](#style-variants-sv) - Style Variants for managing single component inline styles
+- [scv](#slot-class-variants-scv) - Slot Class Variants for managing multiple slot class names
+- [ssv](#slot-style-variants-ssv) - Slot Style Variants for managing multiple slot inline styles
+- [cx](#class-merger-cx) - Utility for composing class names conditionally.
 
-You can add variants by using the `variants` key. There's no limit to how many variants you can add.
+### Class Variants ([cv](./src/cv.ts))
+For managing class names for a single component:
 
 ```ts
 import { cv } from 'css-variants'
- 
+
 const button = cv({
-  base: 'font-bold rounded-sm',
+  base: 'font-bold rounded-lg',
   variants: {
     color: {
-      primary: 'bg-blue-500 hover:bg-blue-700',
-      secondary: 'bg-purple-500 hover:bg-purple-700',
-      success: 'hover:bg-green-700',
+      primary: 'bg-blue-500 text-white',
+      secondary: 'bg-gray-500 text-white' 
     },
+    size: {
+      sm: 'text-sm px-2 py-1',
+      lg: 'text-lg px-4 py-2'
+    }
   },
+  compoundVariants: [
+    {
+      color: 'primary',
+      size: 'lg',  
+      className: 'uppercase'
+    }
+  ],
+  defaultVariants: {
+    color: 'primary',
+    size: 'sm'
+  }
 })
 
-button({ color: 'secondary' })
-// => 'font-bold rounded-sm bg-purple-500 hover:bg-purple-700'
+// Usage
+button() // => 'font-bold rounded-lg bg-blue-500 text-white text-sm px-2 py-1'
+
+button({ size: 'lg' }) // => 'font-bold rounded-lg bg-blue-500 text-white text-lg px-4 py-2 uppercase'
+
+button({ size: 'lg', className: 'custom' }) // => 'font-bold rounded-lg bg-blue-500 text-white text-lg px-4 py-2 uppercase custom'
 ```
 
+### Style Variants ([sv](./src/sv.ts))
+
+For managing inline styles:
+
 ```ts
 import { sv } from 'css-variants'
- 
+
 const button = sv({
   base: {
-    fontWeight: 700,
+    fontWeight: 'bold',
+    borderRadius: '8px'
   },
   variants: {
     color: {
       primary: {
-        color: 'blue',
+        backgroundColor: 'blue',
+        color: 'white'
       },
       secondary: {
-        color: 'red',
-      },
-      success: {
-        color: 'green',
-      },
-    },
-  },
+        backgroundColor: 'gray',
+        color: 'white'
+      }
+    }
+  }
 })
 
-button({ color: 'secondary' })
-// => { fontWeight: 700, color: 'red' }
+// Usage
+button({ color: 'primary' })
+// => { fontWeight: 'bold', borderRadius: '8px', backgroundColor: 'blue', color: 'white' }
+
+button({
+  color: 'secondary',
+  style: { padding: '4px' },
+})
+// => { fontWeight: 'bold', borderRadius: '8px', backgroundColor: 'gray', color: 'white', padding: '4px' }
 ```
 
-### Multiple variants
+### Slot Class Variants ([scv](./src/scv.ts))
 
-You can add multiple variants to a single component.
+For managing class names across multiple slots/elements:
 
 ```ts
-import { cv } from 'css-variants'
+import { scv } from 'css-variants'
 
-const button = cv({
-  base: 'font-bold',
+const card = scv({
+  slots: ['root', 'title', 'content'],
+  base: {
+    root: 'rounded-lg shadow',
+    title: 'text-xl font-bold',
+    content: 'mt-2'
+  },
   variants: {
-    color: {
-      primary: 'bg-blue-500 hover:bg-blue-700',
-      secondary: 'bg-purple-500 hover:bg-purple-700',
-      success: 'bg-green-500 hover:bg-green-700'
-    },
     size: {
-      sm: 'text-sm p-2',
-      md: 'text-md p-4',
-      lg: 'text-lg p-6',
-    },
-  },
+      sm: {
+        root: 'p-4',
+        title: 'text-base'
+      },
+      lg: {
+        root: 'p-6', 
+        title: 'text-2xl'
+      }
+    }
+  }
 })
 
-button({ color: 'success', size: 'lg' })
-// => 'font-bold bg-green-500 hover:bg-green-700 text-lg p-6'
+// Usage
+card({ size: 'sm' })
+// => {
+//   root: 'rounded-lg shadow p-4',
+//   title: 'text-xl font-bold text-base',
+//   content: 'mt-2'
+// }
+
+card({
+  size: 'lg',
+  classNames: {
+    content: 'custom',
+  },
+})
+// => {
+//   root: 'rounded-lg shadow p-6',
+//   title: 'text-xl font-bold text-2xl',
+//   content: 'mt-2 custom'
+// }
 ```
 
+### Slot Style Variants ([ssv](./src/ssv.ts))
+
+For managing inline styles across multiple slots:
+
 ```ts
-import { sv } from 'css-variants'
+import { ssv } from 'css-variants'
 
-const button = sv({
+const card = ssv({
+  slots: ['root', 'title'],
   base: {
-    fontWeight: 700,
+    root: { padding: '1rem' },
+    title: { fontWeight: 'bold' }
   },
   variants: {
     size: {
-      small: { fontSize: '12px' },
-      large: { fontSize: '24px' },
-    },
-    color: {
-      red: { color: 'red' },
-      blue: { color: 'blue' },
-    },
-  },
+      sm: {
+        root: { maxWidth: '300px' },
+        title: { fontSize: '14px' }
+      },
+      lg: {
+        root: { maxWidth: '600px' },
+        title: { fontSize: '18px' }
+      }
+    }
+  }
 })
 
-button({ size: 'small', color: 'blue' })
-// => { fontWeight: 700, fontSize: '12px', color: 'blue' }
-```
-
-### Boolean variants
-
-You can also add boolean variants to a component. This is useful when you want to add a state variant e.g. `disabled`.
+// Usage
+card({ size: 'sm' })
+// => {
+//   root: { padding: '1rem', maxWidth: '300px' },
+//   title: { fontWeight: 'bold', fontSize: '14px' }
+// }
 
-```ts
-import { cv } from 'css-variants'
- 
-const button = cv({
-  variants: {
-    color: {
-      primary: 'bg-blue-500 hover:bg-blue-700',
-      secondary: 'bg-purple-500 hover:bg-purple-700',
-      success: 'bg-green-500 hover:bg-green-700'
-    },
-    disabled: {
-      true: 'opacity-50 pointer-events-none',
+card({
+  size: 'lg',
+  styles: {
+    title: {
+      color: 'red',
     },
   },
 })
+// => {
+//   root: { padding: '1rem', maxWidth: '600px' },
+//   title: { fontWeight: 'bold', fontSize: '18px', color: 'red' }
+// }
+```
+
+### Class Merger ([cx](./src/cx.ts))
 
-button({ disabled: true })
-// => 'opacity-50 pointer-events-none'
+Similar to `clsx/classnames` but with better TypeScript support.
+
+```tsx
+import { cx } from 'css-variants'
+
+// Basic usage
+cx('foo', 'bar') // => 'foo bar'
+
+// With conditions
+cx('foo', { 
+  'bar': true,
+  'baz': false 
+}) // => 'foo bar'
+
+// With arrays
+cx('foo', ['bar', 'baz']) // => 'foo bar baz'
+
+// With nested structures
+cx('foo', {
+  bar: true,
+  baz: [
+    'qux',
+    { quux: true }
+  ]
+}) // => 'foo bar qux quux'
+
+// With falsy values (they're ignored)
+cx('foo', null, undefined, false, 0, '') // => 'foo'
 ```
 
-### Compound variants
+## Advanced Features
+
+### Boolean Variants
 
-Sometimes you might want to add a variant that depends on another variant. This is possible by using the `compoundVariants` key.
+Support for boolean variants to toggle styles conditionally:
 
 ```ts
 import { cv } from 'css-variants'
- 
+
 const button = cv({
   variants: {
-    size: {
-      sm: 'text-sm p-2',
-      md: 'text-md p-4',
-      lg: 'text-lg',
-    },
     disabled: {
-      true: 'opacity-50 pointer-events-none',
-    },
-  },
-  compoundVariants: [
-    {
-      size: 'lg', // You can also use the values as an array
-      disabled: true,
-      className: 'uppercase',
+      true: 'opacity-50 cursor-not-allowed'
     }
-  ],
+  }
 })
 
-button({ size: 'lg', disabled: true })
-// => 'text-lg p-6 opacity-50 pointer-events-none uppercase'
+button({ disabled: true }) // => 'opacity-50 cursor-not-allowed'
 ```
 
-### Default variants
+### Compound Variants
 
-You can also add a default variant to a component. This is useful when you want to add a predefined variants values to a component.
+Apply styles based on combinations of variants:
 
 ```ts
 import { cv } from 'css-variants'
- 
+
 const button = cv({
-  base: 'font-bold rounded-sm',
   variants: {
     color: {
-      primary: 'bg-blue-500 hover:bg-blue-700',
-      secondary: 'bg-purple-500 hover:bg-purple-700',
-      success: 'bg-green-500 hover:bg-green-700'
+      primary: 'bg-blue-500',
+      danger: 'bg-red-500'  
     },
+    size: {
+      sm: 'text-sm',
+      lg: 'text-lg'
+    }
   },
-  defaultVariants: {
-    color: 'primary',
-  },
+  compoundVariants: [
+    {
+      color: 'danger',
+      size: 'lg',
+      className: 'animate-pulse'
+    }
+  ]
 })
 
-button()
-// => 'font-bold rounded-sm bg-blue-500 hover:bg-blue-700'
+button({ color: 'danger', size: 'lg' }) // => 'bg-red-500 text-lg animate-pulse'
 ```
 
-## Slots
-
-Slots allows you to separate a component into multiple parts.
-
-### Basic Usage
-
-You can add `slots` by using the slots key. There's no limit to how many slots you can add.
-
-```ts
-import { scv } from 'css-variants'
-
-const notification = scv({
-  slots: ['root', 'title'],
-  base: {
-    root: 'root',
-    title: 'title',
-  },
-})
+### Default Variants
 
-notification()
-/**
- * Result:
- * {
- *    root: 'root',
- *    title: 'title',
- * }
- */
-```
+Specify default variant values:
 
 ```ts
-import { ssv } from 'css-variants'
+import { cv } from 'css-variants'
 
-const notification = ssv({
-  slots: ['root', 'title'],
-  base: {
-    root: {
-      fontWeight: 'bold',
-    },
-    title: {
-      fontSize: '20px',
+const button = cv({
+  variants: {
+    size: {
+      sm: 'text-sm',
+      lg: 'text-lg'  
     }
   },
+  defaultVariants: {
+    size: 'sm'
+  }
 })
 
-notification()
-/**
- * Result:
- * {
- *    root: { fontWeight: 'bold' },
- *    title: { fontSize: '20px' },
- * }
- */
+button() // => 'text-sm'
 ```
 
-### Slots with variants
+### Custom Class Name Resolver
 
-You can also change the entire component and its slots by using the variants.
+Use your preferred class name utility:
 
 ```ts
-import { csv } from 'css-variants'
+import { cv } from 'css-variants'
+import { clsx } from 'clsx'
 
-const notification = cv({
-  slots: ['root', 'title', 'content'],
-  base: {
-    root: 'root',
-    title: 'title',
-    content: 'content',
-  },
+const button = cv({
+  base: 'btn',
   variants: {
     color: {
-      primary: {
-        root: 'root-primary',
-        title: 'title-primary',
-        content: 'content-primary',
-      },
-      secondary: {
-        title: 'title-secondary',
-        content: 'content-secondary',
-      },
+      primary: 'btn-primary'
     }
   },
+  classNameResolver: clsx
 })
-
-notification({ color: 'primary' })
-/**
- * Result:
- * {
- *    root: 'root root-primary',
- *    title: 'title title-primary',
- *    content: 'content content-primary',
- * }
- */
-
-notification({ color: 'secondary' })
-/**
- * Result:
- * {
- *    root: 'root',
- *    title: 'title title-secondary',
- *    content: 'content content-secondary',
- * }
- */
 ```
 
-## Overriding styles
-
-`css-variants` allows you to override or extend the styles of your components. This feature is useful when you need to add custom styles or modify existing ones without changing the original component definition.
+## TypeScript Support
 
-### Overriding styles on a single component
-
-You can override or extend styles for a single component by passing additional `className` and `style` properties when calling the component function. These will be merged with the existing styles.
+Full TypeScript support with automatic type inference:
 
 ```ts
 import { cv } from 'css-variants'
- 
-const button = cv({
-  base: 'font-semibold',
-  variants: {
-    color: {
-      primary: 'bg-blue-500 hover:bg-blue-700',
-      secondary: 'bg-purple-500 hover:bg-purple-700',
-    }
-  }
-})
- 
-button({
-  color: 'secondary',
-  className: 'border-purple-600',
-})
-// => 'bg-purple-500 hover:bg-purple-700 border-purple-600'
-```
 
-```ts
-import { sv } from 'css-variants'
- 
 const button = cv({
-  base: {
-    fontWeight: 700,
-  },
   variants: {
-    color: {
-      primary: {
-        color: 'blue',
-      },
-      secondary: {
-        color: 'purple',
-      },
+    size: {
+      sm: 'text-sm',
+      lg: 'text-lg'
     }
   }
 })
- 
-button({
-  color: 'secondary',
-  style: { color: 'red' },
-})
-// => { fontWeight: 700, color: 'red' }
-```
-
-### Overriding styles on a component with slots
-
-For components with slots, you can override styles using the `classNames` and `styles` properties. These allow you to target specific slots and apply custom classes or inline styles.
-
-```ts
-import { csv } from 'css-variants'
-
-const notification = cv({
-  slots: ['root', 'title'],
-  base: {
-    root: 'root',
-    title: 'title',
-  },
-})
-
-notification({
-  classNames: {
-    root: 'root-custom-class',
-  },
-})
-/**
- * Result:
- * {
- *    root: 'root root-custom-class',
- *    title: 'title',
- * }
- */
 
+type ButtonProps = Parameters<typeof button>[0]
+// => { size?: 'sm' | 'lg' | undefined }
 ```
 
-## Custom function to resolve class names
-
-Default is the internal 'cx' function. The resolver function should accept multiple class name arguments and return a single concatenated string.
-
-You can use this to integrate with class name utilities like clsx, classnames, or your own custom class name resolution logic.
-
-```ts
-import { clsx } from 'clsx'
-import { cv as _cv, scv as _scv } from 'css-variants'
-
-export const cv: typeof _cv = (config) => {
-  return _cv({
-    ...config,
-    classNameResolver: clsx,
-  })
-}
-
-export const scv: typeof _scv = (config) => {
-  return _scv({
-    ...config,
-    classNameResolver: clsx,
-  })
-}
-```
+## Inspiration
 
-## TypeScript
+This library is inspired by several excellent projects:
 
-### Extracting Variant Types
-
-```tsx
-import { cv } from 'css-variants'
- 
-export const button = cv({
-  variants: {
-    color: {
-      primary: 'bg-blue-500 text-white',
-      secondary: 'bg-purple-500 text-white',
-    },
-  },
-})
-
-export type ButtonProps = Parameters<typeof button>[0]
-```
+- [CVA (Class Variance Authority)](https://github.com/joe-bell/cva)
+- [Panda CSS](https://github.com/chakra-ui/panda)
 
 ## Contribute
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "css-variants",
-  "version": "2.0.6",
+  "version": "2.0.8",
   "description": "A lightweight, flexible API for managing CSS class variants.",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",