slot-variants 1.4.0 → 1.5.0

package/README.md

@@ -384,6 +384,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 +612,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`:
@@ -670,6 +737,16 @@ The `postProcess` function is applied to each slot's final class string independ
 
 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 +796,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
 ```
@@ -884,7 +963,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 +976,15 @@ 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.
 
 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.
 
@@ -1111,11 +1191,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` |
 
-**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