slot-variants 1.1.0 → 1.2.0

package/AGENTS.md

@@ -10,6 +10,30 @@
 import { sv, cn, type VariantProps } from 'slot-variants';
 ```
 
+`sv()` is a drop-in replacement for CVA (`cva` → `sv`) and covers the core feature set of tailwind-variants (`tv`) with a simpler API. Slots return strings directly (not functions like in `tv`). Features not in CVA/TV: `requiredVariants`, `presets`, `cacheSize`, `postProcess`, function-based `defaultVariants`, and variadic base args.
+
+## Calling Conventions
+
+`sv()` supports three calling conventions:
+
+```typescript
+// 1. Config-only (like tailwind-variants' tv())
+const button = sv({
+	base: 'btn font-medium',
+	variants: { size: { sm: 'text-sm', lg: 'text-lg' } }
+});
+
+// 2. Base + config (like CVA's cva())
+const button = sv('btn font-medium', {
+	variants: { size: { sm: 'text-sm', lg: 'text-lg' } }
+});
+
+// 3. Class name merging (like cn())
+sv('flex', 'items-center', 'gap-2'); // 'flex items-center gap-2'
+```
+
+The `base` config field merges with base arguments and `slots.base`: `cn(baseArgs..., config.base, slots.base)`.
+
 ## Best Practices
 
 ### 1. Keep CSS Classes Mutually Exclusive
@@ -243,14 +267,16 @@ const button = sv('btn', {
 	}
 });
 
-button.variantKeys; // ['size', 'intent']
-button.variants; // { size: { sm: 'text-sm', lg: 'text-lg' }, intent: { ... } }
-button.slotKeys; // ['base', 'icon']
-button.slots; // { icon: 'w-4 h-4' }
-button.defaultVariants; // { size: 'sm' }
-button.requiredVariants; // ['intent']
-button.presetKeys; // ['cta']
-button.presets; // { cta: { size: 'lg', intent: 'primary' } }
+button.variantKeys;                // ['size', 'intent']
+button.variants;                   // { size: { sm: 'text-sm', lg: 'text-lg' }, intent: { ... } }
+button.slotKeys;                   // ['base', 'icon']
+button.slots;                      // { icon: 'w-4 h-4' }
+button.defaultVariants;            // { size: 'sm' }
+button.requiredVariants;           // ['intent']
+button.presetKeys;                 // ['cta']
+button.presets;                    // { cta: { size: 'lg', intent: 'primary' } }
+button.getVariantValues('size');   // ['sm', 'lg']
+button.getVariantValues('intent'); // ['primary', 'danger']
 ```
 
 Use introspection to share variant/slot definitions with other parts of your codebase:
@@ -376,6 +402,7 @@ export const Card = (props: CardProps) => {
 
 | Option             | Type                             | Description                       |
 | ------------------ | -------------------------------- | --------------------------------- |
+| `base`             | `ClassValue`                     | Additional base classes            |
 | `variants`         | `Record<string, VariantConfig>`  | Variant definitions               |
 | `slots`            | `Record<string, ClassValue>`     | Named slot definitions            |
 | `compoundVariants` | `CompoundVariant[]`              | Conditional class combinations    |
@@ -390,6 +417,8 @@ export const Card = (props: CardProps) => {
 
 - `ClassValue` - Valid input for `cn()` (string, array, object, boolean, null, undefined)
 - `VariantProps<T, E>` - Extract variant props from an `sv()` return, optionally excluding keys
+- `VariantValue<T, K>` - Extract the value union for a single variant key, without `undefined`
+- `SlotClassProps<T>` - Extract the per-slot class injection shape from an `sv()` return type
 
 ## Imports
 
@@ -398,7 +427,7 @@ export const Card = (props: CardProps) => {
 import { sv, cn } from 'slot-variants';
 
 // Types only
-import type { VariantProps, ClassValue } from 'slot-variants';
+import type { VariantProps, VariantValue, SlotClassProps, ClassValue } from 'slot-variants';
 ```
 
 ## Performance Notes

package/README.md

@@ -17,6 +17,8 @@ npm install slot-variants
 - **`sv()`** - creates variant-based class name generators with optional slots
 - **`cn()`** - a utility for conditionally merging class names
 
+`sv()` is a drop-in replacement for [CVA](https://cva.style/) (just rename `cva` to `sv`) and covers the core feature set of [tailwind-variants](https://www.tailwind-variants.org/) (`tv`) with a simpler API. See [Migrating from CVA / tailwind-variants](#migrating-from-cva--tailwind-variants) for details.
+
 ## Quick Start
 
 ```typescript
@@ -84,14 +86,67 @@ cn('foo', null, undefined, false, 'bar');     // 'foo bar'
 
 ## `sv()` - Slot Variants
 
-### Base Only (No Config)
+`sv()` supports three calling conventions:
+
+### Class Name Merging (No Config)
+
+When called without a config object, `sv()` works like `cn()` — it accepts any number of `ClassValue` arguments and returns a merged class string:
+
+```typescript
+sv('btn btn-primary');                       // 'btn btn-primary'
+sv('flex', 'items-center', 'gap-2');         // 'flex items-center gap-2'
+sv(['btn', 'btn-primary']);                  // 'btn btn-primary'
+sv({ btn: true, disabled: false });          // 'btn'
+sv('flex', ['items-center'], { gap: true }); // 'flex items-center gap'
+```
+
+### Config-Only Call
+
+When called with a single config object (no separate base argument), `sv()` returns a variant function. Use the `base` field inside the config:
+
+```typescript
+const button = sv({
+  base: 'btn font-medium',
+  variants: {
+    size: {
+      sm: 'text-sm',
+      lg: 'text-lg'
+    }
+  }
+});
+
+button({ size: 'sm' }); // 'btn font-medium text-sm'
+```
+
+### Base + Config Call
+
+When the last argument is a config object preceded by one or more `ClassValue` arguments, the leading arguments are merged as the base:
+
+```typescript
+const button = sv('btn font-medium', {
+  variants: {
+    size: {
+      sm: 'text-sm',
+      lg: 'text-lg'
+    }
+  }
+});
+```
 
-When called without a config object, `sv()` processes the base classes through `cn()` and returns a string:
+The `base` field in the config is merged with the base arguments: `cn(baseArgs..., config.base, slots.base)`:
 
 ```typescript
-sv('btn btn-primary');              // 'btn btn-primary'
-sv(['btn', 'btn-primary']);         // 'btn btn-primary'
-sv({ btn: true, disabled: false }); // 'btn'
+const button = sv('btn', {
+  base: 'font-medium',
+  variants: {
+    size: {
+      sm: 'text-sm',
+      lg: 'text-lg'
+    }
+  }
+});
+
+button({ size: 'sm' }); // 'btn font-medium text-sm'
 ```
 
 ### Variants
@@ -659,14 +714,16 @@ const button = sv('btn', {
   }
 });
 
-button.variantKeys;      // ['size', 'intent']
-button.variants;         // { size: { sm: 'text-sm', lg: 'text-lg' }, intent: { ... } }
-button.slotKeys;         // ['base', 'icon']
-button.slots;            // { icon: 'w-4 h-4' }
-button.defaultVariants;  // { size: 'sm' }
-button.requiredVariants; // ['intent']
-button.presetKeys;       // ['cta']
-button.presets;          // { cta: { size: 'lg', intent: 'primary' } }
+button.variantKeys;                 // ['size', 'intent']
+button.variants;                    // { size: { sm: 'text-sm', lg: 'text-lg' }, intent: { ... } }
+button.slotKeys;                    // ['base', 'icon']
+button.slots;                       // { icon: 'w-4 h-4' }
+button.defaultVariants;             // { size: 'sm' }
+button.requiredVariants;            // ['intent']
+button.presetKeys;                  // ['cta']
+button.presets;                     // { cta: { size: 'lg', intent: 'primary' } }
+button.getVariantValues('size');    // ['sm', 'lg']
+button.getVariantValues('intent');  // ['primary', 'danger']
 ```
 
 ## TypeScript
@@ -728,12 +785,84 @@ type ButtonProps = VariantProps<typeof button, 'internalState' | 'intent'>;
 // { size?: 'sm' | 'lg' | undefined }
 ```
 
+### Extracting a Single Variant's Values
+
+`VariantValue` extracts the value union for a specific variant key. Unlike indexing into `VariantProps`, it always returns a clean union without `undefined`:
+
+```typescript
+import { sv, type VariantValue } from 'slot-variants';
+
+const button = sv('btn', {
+  variants: {
+    size: {
+      sm: 'text-sm',
+      md: 'text-base',
+      lg: 'text-lg'
+    },
+    intent: {
+      primary: 'bg-blue-500',
+      danger: 'bg-red-500'
+    }
+  },
+  requiredVariants: ['intent']
+});
+
+type SizeValue = VariantValue<typeof button, 'size'>;
+// 'sm' | 'md' | 'lg'  (no undefined, even though size is optional)
+
+type IntentValue = VariantValue<typeof button, 'intent'>;
+// 'primary' | 'danger'
+```
+
+This is useful when a component only needs to forward a single variant as a typed prop:
+
+```typescript
+type ButtonGroupProps = {
+  size?: VariantValue<typeof button, 'size'>;
+};
+```
+
+### Slot Class Injection Props
+
+`SlotClassProps<T>` extracts the per-slot class injection shape from an `sv()` return type. This is useful when building wrapper components that expose a typed prop for consumers to pass additional classes into specific slots:
+
+```typescript
+import { sv, type SlotClassProps, type VariantProps } from 'slot-variants';
+
+const card = sv('border rounded-lg', {
+  slots: {
+    header: 'font-bold',
+    body: 'py-4',
+    footer: 'border-t'
+  },
+  variants: {
+    size: { sm: 'text-sm', lg: 'text-lg' }
+  }
+});
+
+type CardClassProps = SlotClassProps<typeof card>;
+// { base?: ClassValue; header?: ClassValue; body?: ClassValue; footer?: ClassValue }
+
+type CardProps = VariantProps<typeof card> & {
+  classNames?: SlotClassProps<typeof card>;
+};
+
+function Card({ classNames, ...variants }: CardProps) {
+  const { base, header, body, footer } = card({ ...variants, class: classNames });
+  // ...
+}
+```
+
+When used on an `sv()` definition without slots, `SlotClassProps` resolves to `{ base?: ClassValue }`.
+
 ### Exported Types
 
 | Type | Description |
 | --- | --- |
 | `ClassValue` | Valid input types for `cn()` |
 | `VariantProps<T, E>` | Extracts variant props from an `sv()` return type, optionally excluding keys in `E` |
+| `VariantValue<T, K>` | Extracts the value union for a single variant key `K`, without `undefined` |
+| `SlotClassProps<T>` | Extracts the per-slot class injection shape from an `sv()` return type |
 
 ### Return Type
 
@@ -744,6 +873,7 @@ type ButtonProps = VariantProps<typeof button, 'internalState' | 'intent'>;
 
 | Option | Type | Description |
 | --- | --- | --- |
+| `base` | `ClassValue` | Additional base classes merged with the base argument and `slots.base` |
 | `variants` | `SVVariants` | Variant definitions mapping variant names to their possible values |
 | `slots` | `SVSlots` | Named slot definitions for multi-element components |
 | `compoundVariants` | `Array` | Additional classes applied when multiple variant conditions match |
@@ -752,4 +882,80 @@ type ButtonProps = VariantProps<typeof button, 'internalState' | 'intent'>;
 | `requiredVariants` | `string[]` | Variant names that must be provided at call time |
 | `presets` | `Record<string, Partial<VariantProps>>` | Named combinations of variant values selectable via `preset` prop |
 | `postProcess` | `(className: string) => string` | Custom transformation applied to final class strings |
-| `cacheSize` | `number` | Maximum number of cached results (default: `256`) |
+| `cacheSize` | `number` | Maximum number of cached results (default: `256`) |
+
+## Migrating from CVA / tailwind-variants
+
+### From CVA
+
+`sv()` is a drop-in replacement for CVA. Rename `cva` to `sv` and `VariantProps` import source:
+
+```diff
+- import { cva, type VariantProps } from 'class-variance-authority';
++ import { sv, type VariantProps } from 'slot-variants';
+
+- const button = cva('btn font-medium', {
++ const button = sv('btn font-medium', {
+    variants: {
+      size: { sm: 'text-sm', lg: 'text-lg' },
+      intent: { primary: 'bg-blue-500', danger: 'bg-red-500' }
+    },
+    defaultVariants: { size: 'md' },
+    compoundVariants: [
+      { size: 'lg', intent: 'primary', class: 'uppercase' }
+    ]
+  });
+```
+
+Everything else works identically — the config shape, `class`/`className` override, `VariantProps` extraction, and variant prop handling are all compatible.
+
+### From tailwind-variants
+
+`sv()` covers the core feature set of tailwind-variants with a simpler API. The config-only calling convention matches `tv()`:
+
+```diff
+- import { tv, type VariantProps } from 'tailwind-variants';
++ import { sv, type VariantProps } from 'slot-variants';
+
+- const button = tv({
++ const button = sv({
+    base: 'btn font-medium',
+    variants: {
+      size: { sm: 'text-sm', lg: 'text-lg' }
+    },
+    defaultVariants: { size: 'md' }
+  });
+```
+
+Key differences to be aware of:
+
+| Feature | tailwind-variants | slot-variants |
+| --- | --- | --- |
+| Slot return type | Functions: `slot({ class: '...' })` | Strings: `slot` is already a `string` |
+| `extend` (composition) | Supported | Not supported |
+| Built-in `twMerge` | Enabled by default | Use `postProcess: twMerge` |
+
+**Slot return type** is the most significant difference. In `tv()`, each slot returns a function that can accept additional props. In `sv()`, slots resolve to strings directly — use the `class` prop with a slot object for per-slot overrides:
+
+```typescript
+// tailwind-variants
+const { base, icon } = component({ size: 'sm' });
+base({ class: 'extra' }); // slot is a function
+
+// slot-variants
+const { base, icon } = component({ size: 'sm', class: { base: 'extra' } });
+base; // slot is a string
+```
+
+**tailwind-merge** is not built-in but can be added via `postProcess`:
+
+```typescript
+import { sv } from 'slot-variants';
+import { twMerge } from 'tailwind-merge';
+
+const button = sv({
+  base: 'px-4 py-2',
+  variants: { size: { sm: 'px-2 py-1' } },
+  postProcess: twMerge
+});
+```

package/dist/index.cjs

@@ -56,6 +56,19 @@ function cn(...args) {
 // src/sv.ts
 var { isArray: isArray2 } = Array;
 var { assign, entries, keys: keys2 } = Object;
+var configKeys = /* @__PURE__ */ new Set([
+  "base",
+  "variants",
+  "slots",
+  "compoundVariants",
+  "compoundSlots",
+  "defaultVariants",
+  "requiredVariants",
+  "presets",
+  "cacheSize",
+  "postProcess"
+]);
+var isConfig = (value) => !!value && typeof value === "object" && !isArray2(value) && keys2(value).every((key) => configKeys.has(key));
 var looseEquals = (first, second) => first === second || `${first}` === `${second}`;
 var matchesCompound = (props, compound) => {
   for (const compoundKey of keys2(compound)) {
@@ -74,11 +87,24 @@ var matchesCompound = (props, compound) => {
   }
   return true;
 };
-function sv(base, config) {
+function sv(...args) {
+  const lastArg = args[args.length - 1];
+  let base;
+  let config;
+  if (args.length >= 2 && isConfig(lastArg)) {
+    config = lastArg;
+    base = args.length > 2 ? args.slice(0, -1) : args[0];
+  } else if (args.length === 1 && isConfig(lastArg)) {
+    config = lastArg;
+    base = void 0;
+  } else {
+    base = args;
+  }
   if (!config) {
-    return cn(base);
+    return cn(...args);
   }
   const {
+    base: configBase,
     variants = {},
     slots = {},
     compoundVariants = [],
@@ -103,7 +129,8 @@ function sv(base, config) {
     return value;
   };
   const { base: baseSlot, ...otherSlots } = slots;
-  const baseClassValue = cn(base, baseSlot);
+  const baseArgs = isArray2(base) ? base : [base];
+  const baseClassValue = cn(...baseArgs, configBase, baseSlot);
   const slotKeys = new Set(keys2(otherSlots));
   const normalizedVariants = {};
   for (const [variantKey, variantValue] of entries(variants)) {
@@ -263,6 +290,18 @@ function sv(base, config) {
     }
     return cacheReturn(cacheKey, result);
   };
+  const getVariantValues = (key) => keys2(normalizedVariants[key] ?? {}).map((value) => {
+    if (value === "true") {
+      return true;
+    }
+    if (value === "false") {
+      return false;
+    }
+    if (value !== "" && !Number.isNaN(Number(value))) {
+      return Number(value);
+    }
+    return value;
+  });
   return assign(variantFn, {
     variants,
     variantKeys: keys2(variants),
@@ -272,6 +311,7 @@ function sv(base, config) {
     requiredVariants,
     presets,
     presetKeys: keys2(presets),
+    getVariantValues,
     clearCache: () => cache.clear(),
     getCacheSize: () => cache.size
   });

package/dist/index.d.ts

@@ -53,6 +53,7 @@ type PresetProp<P extends Record<string, unknown> | undefined> = P extends Recor
 } : unknown;
 type SVProps<S extends SVSlots | undefined, V extends SVVariants<S> | undefined, RV extends StringKeyof<V>[], P extends SVPresets<S, V> | undefined> = V extends undefined ? ClassProp<S> : P extends Record<string, unknown> ? Prettify<PartialUndefined<SVVariantProps<S, V>>> & ClassProp<S> & PresetProp<P> : Prettify<Pick<SVVariantProps<S, V>, RV[number]> & Omit<PartialUndefined<SVVariantProps<S, V>>, RV[number]>> & ClassProp<S>;
 type SVConfig<S extends SVSlots | undefined, V extends SVVariants<S> | undefined, RV extends StringKeyof<V>[], P extends SVPresets<S, V> | undefined> = {
+    base?: ClassValue | undefined;
     variants?: V | undefined;
     slots?: S | undefined;
     compoundVariants?: SVCompoundVariants<S, V> | undefined;
@@ -74,15 +75,19 @@ type SVReturnType<S extends SVSlots | undefined, V extends SVVariants<S> | undef
     requiredVariants: RV;
     presets: P;
     presetKeys: P extends Record<string, unknown> ? StringKeyof<P>[] : [];
+    getVariantValues: V extends SVVariants<S> ? <K extends StringKeyof<V>>(key: K) => SVVariantPropType<V[K], S>[] : (key: never) => never[];
     clearCache: () => void;
     getCacheSize: () => number;
 };
 type VariantProps<T extends (...args: any[]) => unknown, E extends string = never> = Prettify<Omit<Exclude<Parameters<T>[0], undefined>, 'class' | 'className' | 'preset' | E>>;
+type VariantValue<T extends (...args: any[]) => unknown, K extends keyof VariantProps<T>> = NonNullable<VariantProps<T>[K]>;
+type SlotClassProps<T extends (...args: any[]) => unknown> = ReturnType<T> extends string ? Partial<Record<'base', ClassValue>> : Prettify<Partial<Record<Extract<keyof ReturnType<T>, string>, ClassValue>>>;
 /**
  * Creates variant-based class name generator with optional slots support.
  * Inspired by CVA and tailwind-variants.
  */
-declare function sv(base: ClassValue): string;
-declare function sv<S extends SVSlots | undefined = undefined, V extends SVVariants<S> | undefined = undefined, RV extends StringKeyof<V>[] | [] = [], P extends SVPresets<S, V> | undefined = undefined>(base: ClassValue, config: SVConfig<S, V, RV, P>): SVReturnType<S, V, RV, P>;
+declare function sv<S extends SVSlots | undefined = undefined, V extends SVVariants<S> | undefined = undefined, RV extends StringKeyof<V>[] | [] = [], P extends SVPresets<S, V> | undefined = undefined>(config: SVConfig<S, V, RV, P>): SVReturnType<S, V, RV, P>;
+declare function sv<S extends SVSlots | undefined = undefined, V extends SVVariants<S> | undefined = undefined, RV extends StringKeyof<V>[] | [] = [], P extends SVPresets<S, V> | undefined = undefined>(...args: [...ClassValue[], SVConfig<S, V, RV, P>]): SVReturnType<S, V, RV, P>;
+declare function sv(...args: ClassValue[]): string;
 
-export { type ClassValue, type VariantProps, cn, sv };
+export { type ClassValue, type SlotClassProps, type VariantProps, type VariantValue, cn, sv };

package/dist/index.js

@@ -29,6 +29,19 @@ function cn(...args) {
 // src/sv.ts
 var { isArray: isArray2 } = Array;
 var { assign, entries, keys: keys2 } = Object;
+var configKeys = /* @__PURE__ */ new Set([
+  "base",
+  "variants",
+  "slots",
+  "compoundVariants",
+  "compoundSlots",
+  "defaultVariants",
+  "requiredVariants",
+  "presets",
+  "cacheSize",
+  "postProcess"
+]);
+var isConfig = (value) => !!value && typeof value === "object" && !isArray2(value) && keys2(value).every((key) => configKeys.has(key));
 var looseEquals = (first, second) => first === second || `${first}` === `${second}`;
 var matchesCompound = (props, compound) => {
   for (const compoundKey of keys2(compound)) {
@@ -47,11 +60,24 @@ var matchesCompound = (props, compound) => {
   }
   return true;
 };
-function sv(base, config) {
+function sv(...args) {
+  const lastArg = args[args.length - 1];
+  let base;
+  let config;
+  if (args.length >= 2 && isConfig(lastArg)) {
+    config = lastArg;
+    base = args.length > 2 ? args.slice(0, -1) : args[0];
+  } else if (args.length === 1 && isConfig(lastArg)) {
+    config = lastArg;
+    base = void 0;
+  } else {
+    base = args;
+  }
   if (!config) {
-    return cn(base);
+    return cn(...args);
   }
   const {
+    base: configBase,
     variants = {},
     slots = {},
     compoundVariants = [],
@@ -76,7 +102,8 @@ function sv(base, config) {
     return value;
   };
   const { base: baseSlot, ...otherSlots } = slots;
-  const baseClassValue = cn(base, baseSlot);
+  const baseArgs = isArray2(base) ? base : [base];
+  const baseClassValue = cn(...baseArgs, configBase, baseSlot);
   const slotKeys = new Set(keys2(otherSlots));
   const normalizedVariants = {};
   for (const [variantKey, variantValue] of entries(variants)) {
@@ -236,6 +263,18 @@ function sv(base, config) {
     }
     return cacheReturn(cacheKey, result);
   };
+  const getVariantValues = (key) => keys2(normalizedVariants[key] ?? {}).map((value) => {
+    if (value === "true") {
+      return true;
+    }
+    if (value === "false") {
+      return false;
+    }
+    if (value !== "" && !Number.isNaN(Number(value))) {
+      return Number(value);
+    }
+    return value;
+  });
   return assign(variantFn, {
     variants,
     variantKeys: keys2(variants),
@@ -245,6 +284,7 @@ function sv(base, config) {
     requiredVariants,
     presets,
     presetKeys: keys2(presets),
+    getVariantValues,
     clearCache: () => cache.clear(),
     getCacheSize: () => cache.size
   });

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "slot-variants",
-	"version": "1.1.0",
+	"version": "1.2.0",
 	"description": "Type-safe class name variants with slots",
 	"type": "module",
 	"exports": {