slot-variants 1.4.0 → 1.6.0

package/README.md

@@ -12,10 +12,11 @@ npm install slot-variants
 
 ## Overview
 
-`slot-variants` exports two functions:
+`slot-variants` exports three functions:
 
 - **`sv()`** - creates variant-based class name generators with optional slots
 - **`cn()`** - a utility for conditionally merging class names
+- **`createSV()`** - builds a pre-configured `sv()` with shared config defaults
 
 `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.
 
@@ -68,7 +69,7 @@ cn(['foo', ['bar', 'baz']]);                  // 'foo bar baz'
 cn({ foo: true, bar: false, baz: true });     // 'foo baz'
 
 // Mixed
-cn('base', ['responsive'], { active: true }); // 'base active responsive'
+cn('base', ['responsive'], { active: true }); // 'base responsive active'
 
 // Falsy values are filtered out
 cn('foo', null, undefined, false, 'bar');     // 'foo bar'
@@ -384,6 +385,21 @@ button({ intent: 'primary', size: 'lg' });  // OK
 button({ size: 'lg' });                     // Throws: Missing required variant: "intent"
 ```
 
+Pass `true` to make every variant required, or `false` to require none:
+
+```typescript
+const button = sv('btn', {
+  variants: {
+    size: { sm: 'text-sm', lg: 'text-lg' },
+    intent: { primary: 'bg-blue-500', danger: 'bg-red-500' }
+  },
+  requiredVariants: true
+});
+
+button({ size: 'sm', intent: 'primary' });  // OK
+button({ size: 'sm' });                     // Throws: Missing required variant: "intent"
+```
+
 ### Presets
 
 Presets are predefined named combinations of variant values. Use them to create reusable variant shortcuts:
@@ -597,6 +613,58 @@ compoundSlots: [
 ]
 ```
 
+### Multi Slots
+
+By default each slot in the result object is a plain class string. The
+`multiSlots` option turns the listed slots into reconfigurable functions
+instead. A slot function accepts variant prop overrides and a
+`class`/`className` override, and returns that slot's class string.
+
+This is designed for cases where a single slot is rendered multiple times
+with different props — for example a list of items where each item needs
+its own variant values — so the same slot can be re-evaluated per use
+without recreating the whole variant function:
+
+```typescript
+const card = sv('border', {
+  slots: {
+    header: 'font-bold',
+    body: 'py-4'
+  },
+  variants: {
+    size: {
+      sm: { base: 'p-2', header: 'text-sm' },
+      lg: { base: 'p-6', header: 'text-lg' }
+    }
+  },
+  multiSlots: ['header']
+});
+
+const result = card({ size: 'sm' });
+// result.base   -> 'border p-2'        (plain string)
+// result.body   -> 'py-4'              (plain string)
+// result.header -> function
+
+result.header();                  // 'font-bold text-sm'
+result.header({ size: 'lg' });    // 'font-bold text-lg'
+result.header({ class: 'mt-2' }); // 'font-bold text-sm mt-2'
+```
+
+Slots not listed in `multiSlots` stay plain strings. Pass `true` to make
+every slot a function, or `false` (the default) to keep them all strings:
+
+```typescript
+const card = sv('border', {
+  slots: { header: 'font-bold', body: 'py-4' },
+  multiSlots: true
+});
+
+const { base, header, body } = card();
+base();   // 'border'
+header(); // 'font-bold'
+body();   // 'py-4'
+```
+
 ### Class Override at Runtime
 
 Append additional classes at call time using `class` or `className`:
@@ -666,10 +734,66 @@ const button = sv('px-4 py-2 bg-blue-500', {
 
 The `postProcess` function is applied to each slot's final class string independently.
 
+### Shared Defaults with `createSV()`
+
+`createSV(defaults)` returns a pre-configured `sv()` that merges `defaults` into every config-based call. This avoids repeating the same options — most commonly `postProcess: twMerge` — across every component:
+
+```typescript
+import { createSV } from 'slot-variants';
+import { twMerge } from 'tailwind-merge';
+
+export const customSV = createSV({
+  postProcess: twMerge,
+  cacheSize: 512
+});
+
+// twMerge is applied without restating it per component
+const button = customSV('px-4 py-2 bg-blue-500', {
+  variants: {
+    size: {
+      sm: 'px-2 py-1 text-sm',
+      lg: 'px-6 py-3 text-lg'
+    }
+  }
+});
+```
+
+`defaults` accepts **any** config option (`base`, `variants`, `slots`, `compoundVariants`, `cacheSize`, `introspection`, `postProcess`, …). The merge is shallow and **a per-call value always wins** over the matching default — there is no deep merging of variants or compound rules:
+
+```typescript
+const customSV = createSV({ postProcess: twMerge });
+
+// This component opts out of twMerge entirely
+const raw = customSV('btn', {
+  variants: { size: { sm: 'text-sm' } },
+  postProcess: (className) => className // overrides the default
+});
+```
+
+Calls with no config object are forwarded straight to `cn()`-style merging and never see the defaults:
+
+```typescript
+const customSV = createSV({ postProcess: (c) => c.toUpperCase() });
+
+customSV('flex', 'items-center'); // 'flex items-center' — defaults are skipped
+```
+
+A factory-level `introspection: true` is reflected in each component's return type, so the [introspection](#introspection) API is available without setting the flag on every config. A per-call `introspection: false` opts an individual component back out.
+
 ### Caching
 
 Results are cached automatically for performance. The default cache size is **256** entries.
 
+Each cache entry corresponds to one distinct combination of resolved variant values. The largest number of combinations a config can produce is the product, over every variant, of its value count plus one — the `+ 1` counts the variant being left unset:
+
+```
+maxEntries = (values₁ + 1) × (values₂ + 1) × ... × (valuesₙ + 1)
+```
+
+For example, four variants with three values each yield `(3 + 1) ** 4 = 256` combinations — exactly the default. A config whose `maxEntries` is at or below its `cacheSize` never evicts, so raising `cacheSize` past that point has no effect.
+
+The `+ 1` is dropped for any variant that cannot actually be left unset — one listed in `requiredVariants` (or all of them when `requiredVariants` is `true`), or one with a static `defaultVariants` value that always fills it in. A function-based default keeps the `+ 1`, since it may return `undefined`. The `getMaxEntries()` introspection method computes this exact count for a given config — see [Introspection](#introspection).
+
 ```typescript
 const button = sv('btn', {
   variants: {
@@ -719,10 +843,12 @@ button.slotKeys;                    // ['base', 'icon']
 button.slots;                       // { icon: 'w-4 h-4' }
 button.defaultVariants;             // { size: 'sm' }
 button.requiredVariants;            // ['intent']
+button.multiSlots;                  // [] (slot names exposed as functions)
 button.presetKeys;                  // ['cta']
 button.presets;                     // { cta: { size: 'lg', intent: 'primary' } }
 button.getVariantValues('size');    // ['sm', 'lg']
 button.getVariantValues('intent');  // ['primary', 'danger']
+button.getMaxEntries();             // 4 — distinct variant combinations
 button.getCacheSize();              // current number of cached entries
 button.clearCache();                // clear all cached entries
 ```
@@ -866,6 +992,7 @@ When used on an `sv()` definition without slots, `SlotClassProps` resolves to `{
 | `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 |
+| `SV<DI>` | The shape of an `sv()` function, with the factory's introspection default `DI`; the return type of `createSV()` |
 
 ### Return Type
 
@@ -884,7 +1011,8 @@ Class values inside the config (`base`, `variants`, `slots`, and `compound*` `cl
 | `compoundVariants` | `Array` | Additional classes applied when multiple variant conditions match |
 | `compoundSlots` | `Array` | Classes applied to multiple slots based on variant conditions |
 | `defaultVariants` | `Object` | Default values for variants (static values or functions) |
-| `requiredVariants` | `string[]` | Variant names that must be provided at call time |
+| `requiredVariants` | `string[] \| boolean` | Variant names that must be provided at call time; `true` makes every variant required, `false` none |
+| `multiSlots` | `string[] \| boolean` | Slot names exposed as reconfigurable functions instead of strings; `true` makes every slot a function, `false` none |
 | `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`) |
@@ -896,15 +1024,17 @@ Class values inside the config (`base`, `variants`, `slots`, and `compound*` `cl
 
 ### Rules
 
-- **`slot-variants/no-conflicting-classes`** — flags class tokens that collide within the output of an `sv()` or `cn()` call: both exact-duplicate tokens that will appear more than once and distinct tokens that target the same Tailwind-style utility namespace (e.g. `w-100` and `w-200`). For `sv()`, detects collisions within `base`, across different variant keys, inside compound variants and compound slots, between `base` and a variant value, and within a single literal. For `cn()` (and the cn-style calling convention of `sv()` without a config), flags collisions across args, inside arrays, template literals, or within a single literal. Tokens with different variant prefixes (`w-100` vs `hover:w-200`) don't conflict, the trailing `!` important marker is ignored when computing the namespace, and tokens that only co-occur across mutually-exclusive variant values are skipped.
+- **`slot-variants/no-conflicting-classes`** — flags class tokens that collide within the output of an `sv()` or `cn()` call: both exact-duplicate tokens that will appear more than once and distinct tokens that target the same Tailwind-style utility namespace (e.g. `w-100` and `w-200`). For `sv()`, detects collisions within `base`, across different variant keys, inside compound variants and compound slots, between `base` and a variant value, and within a single literal. For `cn()` (and the cn-style calling convention of `sv()` without a config), flags collisions across args, inside arrays, template literals, or within a single literal. Tokens with different variant prefixes (`w-100` vs `hover:w-200`) don't conflict, a leading or trailing `!` important marker (`!w-100`, `w-100!`) is ignored when computing the namespace, and tokens that only co-occur across mutually-exclusive variant values are skipped.
 
-- **`slot-variants/no-dynamic-classes`** — flags class-bearing positions in `sv()` and `cn()` calls that aren't statically inferrable. Only string literals, template literals without expressions, flat arrays of those in config, and explicit `undefined` config class values are accepted, and config objects must use static keys (no spreads, no computed keys). Identifiers, member access, calls, spreads, non-string literals, templates with expressions, nested config arrays, and runtime conditional records are reported. Non-class-bearing config keys (`defaultVariants`, `presets`, `requiredVariants`, `cacheSize`, `postProcess`, `introspection`) are not validated, and runtime variant matchers inside compound entries are left alone — only the `class`/`className` value (and the `slots` array of `compoundSlots`) is checked.
+- **`slot-variants/no-dynamic-classes`** — flags class-bearing positions in `sv()` and `cn()` calls that aren't statically inferrable. Only string literals, template literals without expressions, flat arrays of those in config, and explicit `undefined` config class values are accepted, and config objects must use static keys (no spreads, no computed keys). Identifiers, member access, calls, spreads, non-string literals, templates with expressions, nested config arrays, and runtime conditional records are reported. Non-class-bearing config keys (`defaultVariants`, `presets`, `requiredVariants`, `multiSlots`, `cacheSize`, `postProcess`, `introspection`) are not validated, and runtime variant matchers inside compound entries are left alone — only the `class`/`className` value (and the `slots` array of `compoundSlots`) is checked.
 
-- **`slot-variants/no-empty-classes`** — flags empty class values — empty strings, empty arrays, and empty objects — at any class-bearing position reachable from an `sv()` or `cn()` call, plus zero-argument `sv()` / `cn()` calls themselves (which always produce an empty class string). Reports empties in positional arguments (and inside arrays nested in those), in `base`, in variants including slot-keyed variant branches, in the `class`/`className` of `compoundVariants` and `compoundSlots` entries, and in the top-level `slots`, `variants`, `compoundVariants`, and `compoundSlots` containers themselves. Inside an `sv()` config, an empty string is still allowed as a direct `slots[key]` value — declaring a slot with no default classes is a valid use case.
+- **`slot-variants/no-empty-classes`** — flags empty class values — empty strings, empty arrays, and empty objects — at any class-bearing position reachable from an `sv()` or `cn()` call, plus zero-argument `sv()` / `cn()` calls themselves (which always produce an empty class string). Reports empties in positional arguments (and inside arrays nested in those), in `base`, in variants including slot-keyed variant branches, in the `class`/`className` of `compoundVariants` and `compoundSlots` entries, and in the top-level `slots`, `variants`, `compoundVariants`, and `compoundSlots` containers themselves. Inside an `sv()` config, an empty string is still allowed as a direct `slots[key]` value — declaring a slot with no default classes is a valid use case. **Partially auto-fixable**: `eslint --fix` removes an empty positional argument, an empty class-array element, or an empty top-level config property (`base`, `slots`, `variants`, `compoundVariants`, `compoundSlots`), along with its comma, when other items remain in that list or config; empties at other positions are reported without a fix.
 
 - **`slot-variants/no-redundant-spaces`** — flags class strings whose whitespace isn't canonical. Inside a class string, whitespace is canonical only as a single ASCII space between two non-whitespace tokens, so leading or trailing whitespace, repeated spaces, and non-space whitespace (tabs, newlines, etc.) are reported. The rule walks every string and expressionless template literal reachable from a call's arguments — including values nested inside arrays and objects — and bails silently on dynamic expressions. **Auto-fixable**: `eslint --fix` rewrites each offending literal in place, preserving its original quote style.
 
-- **`slot-variants/no-shared-tokens`** — flags class tokens that appear in every value of an exhaustively-covered variant, where “exhaustive” means the variant has a statically defined default value or is listed in `requiredVariants`. Those tokens are constant in the rendered output, so they belong in `base` or the corresponding `slots[slot]` entry rather than being repeated in every variant value. The rule only analyzes `sv()` calls with a config, compares tokens per-slot, skips non-exhaustive variants, single-value variants, boolean shorthand, undefined or dynamic defaults, and dynamic or partially-analyzable variant value records, and reports every repeated occurrence that should be lifted out.
+- **`slot-variants/no-shared-tokens`** — flags class tokens that appear in every value of an exhaustively-covered variant, where “exhaustive” means the variant has a statically defined default value, is listed in `requiredVariants`, or `requiredVariants` is `true` (every variant required). Those tokens are constant in the rendered output, so they belong in `base` or the corresponding `slots[slot]` entry rather than being repeated in every variant value. The rule only analyzes `sv()` calls with a config, compares tokens per-slot, skips non-exhaustive variants, single-value variants, boolean shorthand, undefined or dynamic defaults, and dynamic or partially-analyzable variant value records, and reports every repeated occurrence that should be lifted out.
+
+- **`slot-variants/require-top-level-config`** — flags `sv()` calls made with a config object that aren't at the module top level. The config form compiles the variant function and seeds its cache once; nesting it inside a function (a component body, an arrow, an object method, etc.) rebuilds that work — and throws away the variant cache — on every call, so the config form belongs at module scope. The cn-style calling convention of `sv()` (and every `cn()` call) carries no config and is left alone, as are calls inside top-level blocks or conditionals, which still run only at module load.
 
 Only calls where `sv` or `cn` is a named import from `'slot-variants'` are analyzed. `no-conflicting-classes` skips dynamic inputs silently to avoid false positives; `no-dynamic-classes` is the opposite — it flags exactly those positions so the static analyzer can fully reason about every call. `no-shared-tokens` sits between them: it needs a fully statically analyzable, exhaustive variant before it can prove a token is constant across every value. `no-empty-classes` and `no-redundant-spaces` are independent and complement the structural rules: they cover empty and badly-shaped literals reachable from a call's arguments, regardless of whether the surrounding call is fully static.
 
@@ -931,7 +1061,8 @@ export default [
       'slot-variants/no-dynamic-classes': 'error',
       'slot-variants/no-empty-classes': 'error',
       'slot-variants/no-redundant-spaces': 'error',
-      'slot-variants/no-shared-tokens': 'error'
+      'slot-variants/no-shared-tokens': 'error',
+      'slot-variants/require-top-level-config': 'error'
     }
   }
 ];
@@ -947,7 +1078,8 @@ export default [
     "slot-variants/no-dynamic-classes": "error",
     "slot-variants/no-empty-classes": "error",
     "slot-variants/no-redundant-spaces": "error",
-    "slot-variants/no-shared-tokens": "error"
+    "slot-variants/no-shared-tokens": "error",
+    "slot-variants/require-top-level-config": "error"
   }
 }
 ```
@@ -1111,11 +1243,11 @@ Key differences to be aware of:
 
 | Feature | tailwind-variants | slot-variants |
 | --- | --- | --- |
-| Slot return type | Functions: `slot({ class: '...' })` | Strings: `slot` is already a `string` |
+| Slot return type | Always functions: `slot({ class: '...' })` | Strings by default; functions for slots listed in `multiSlots` |
 | `extend` (composition) | Supported | Not supported |
-| Built-in `twMerge` | Enabled by default | Use `postProcess: twMerge` |
+| Built-in `twMerge` | Enabled by default | Use `postProcess: twMerge`, globally via `createSV` |
 
-**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:
+**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, or list a slot in [`multiSlots`](#multi-slots) to expose it as a `tv`-style reconfigurable function:
 
 ```typescript
 // tailwind-variants
@@ -1139,3 +1271,13 @@ const button = sv({
   postProcess: twMerge
 });
 ```
+
+To enable it globally — the closest equivalent to `tv`'s default `twMerge` — wrap it once with [`createSV()`](#shared-defaults-with-createsv) and import the result everywhere:
+
+```typescript
+// custom-sv.ts
+import { createSV } from 'slot-variants';
+import { twMerge } from 'tailwind-merge';
+
+export const customSV = createSV({ postProcess: twMerge });
+```