slot-variants 1.3.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`:
@@ -668,7 +735,17 @@ The `postProcess` function is applied to each slot's final class string independ
 
 ### Caching
 
-Results are cached automatically for performance. The default cache size is **256** entries. Calls with `class` or `className` props bypass the cache.
+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', {
@@ -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,20 +976,30 @@ Class values inside the config (`base`, `variants`, `slots`, and `compound*` `cl
 
 ### Rules
 
-- **`slot-variants/no-duplicate-classes`** — flags class name tokens that will appear more than once in the output of an `sv()` or `cn()` call. For `sv()`, detects duplicates 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 any token that appears in more than one always-present source — across args, inside arrays, template literals, or within a single literal.
+- **`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.
+- **`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-duplicate-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.
+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.
 
 ### ESLint (flat config)
 
+Use the `recommended` preset to enable every rule at `error` in one line:
+
+```js
+import svPlugin from 'slot-variants/eslint-plugin';
+
+export default [svPlugin.configs.recommended];
+```
+
+Or wire each rule by hand if you want per-rule control:
+
 ```js
 import svPlugin from 'slot-variants/eslint-plugin';
 
@@ -917,7 +1007,7 @@ export default [
   {
     plugins: { 'slot-variants': svPlugin },
     rules: {
-      'slot-variants/no-duplicate-classes': 'error',
+      'slot-variants/no-conflicting-classes': 'error',
       'slot-variants/no-dynamic-classes': 'error',
       'slot-variants/no-empty-classes': 'error',
       'slot-variants/no-redundant-spaces': 'error',
@@ -933,7 +1023,7 @@ export default [
 {
   "jsPlugins": ["slot-variants/eslint-plugin"],
   "rules": {
-    "slot-variants/no-duplicate-classes": "error",
+    "slot-variants/no-conflicting-classes": "error",
     "slot-variants/no-dynamic-classes": "error",
     "slot-variants/no-empty-classes": "error",
     "slot-variants/no-redundant-spaces": "error",
@@ -960,7 +1050,7 @@ const button = sv({
 cn('flex items-center', 'flex'); // 'flex' duplicated across args
 ```
 
-`no-duplicate-classes` reports `flex` on the `base` literal and on both variant values; for the `cn()` call, both occurrences of `'flex'` are flagged. Move the shared class into `base` — or use compound variants — so each class has a single source.
+`no-conflicting-classes` reports `flex` on the `base` literal and on both variant values; for the `cn()` call, both occurrences of `'flex'` are flagged. Move the shared class into `base` — or use compound variants — so each class has a single source.
 
 ```typescript
 import { sv, cn } from 'slot-variants';
@@ -1000,7 +1090,7 @@ sv({ slots: { body: 'p-4 ' } });               // trailing space
 cn(`flex\titems-center`);                      // tab between tokens
 ```
 
-`no-redundant-spaces` reports each literal whose whitespace deviates from the canonical "tokens separated by exactly one space" form. Trim and collapse the strings — or split them into array entries — so the stored class output is byte-stable and easy to scan in diffs.
+`no-redundant-spaces` reports each literal whose whitespace deviates from the canonical "tokens separated by exactly one space" form. Trim and collapse the strings — or split them into array entries — so the stored class output is byte-stable and easy to scan in diffs. Run `eslint --fix` to apply the canonical form automatically; the fixer rewrites the literal in place using the original quote style.
 
 ```typescript
 import { sv } from 'slot-variants';
@@ -1070,7 +1160,7 @@ module.exports = {
       size: { sm: 'text-sm', lg: 'text-lg' },
       intent: { primary: 'bg-blue-500', danger: 'bg-red-500' }
     },
-    defaultVariants: { size: 'md' },
+    defaultVariants: { size: 'sm' },
     compoundVariants: [
       { size: 'lg', intent: 'primary', class: 'uppercase' }
     ]
@@ -1093,7 +1183,7 @@ Everything else works identically — the config shape, `class`/`className` over
     variants: {
       size: { sm: 'text-sm', lg: 'text-lg' }
     },
-    defaultVariants: { size: 'md' }
+    defaultVariants: { size: 'sm' }
   });
 ```
 
@@ -1101,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

package/SKILL.md

@@ -0,0 +1,200 @@
+# slot-variants — AI Agent Guide
+
+## Overview
+
+`slot-variants` is a lightweight, zero-dependency, type-safe library for managing CSS class name variants with slots support.
+
+```typescript
+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 by default, or reconfigurable functions (like in `tv`) when listed in `multiSlots`. 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
+sv({ base: 'btn', variants: { size: { sm: 'text-sm', lg: 'text-lg' } } });
+
+// 2. Base + config
+sv('btn', { 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
+
+Define classes in base and variants so they don't overlap; use compound variants for intersecting classes. Don't repeat a token across every variant value — lift it into `base`.
+
+### 2. Use Boolean Shorthand for Simple States
+
+For boolean variants (on/off), use shorthand instead of a verbose `{ true, false }` record:
+
+```typescript
+const button = sv('btn', {
+	variants: { disabled: 'opacity-50 cursor-not-allowed' }
+});
+
+button({ disabled: true });
+```
+
+### 3. Use Required Variants for Mandatory Props
+
+List a variant in `requiredVariants: ['intent']` to make it mandatory — `button()` throws when it is missing.
+
+### 4. Use Slots for Multi-Element Components
+
+For components with multiple elements (card, dialog, etc.), use slots:
+
+```typescript
+const card = sv('border rounded-lg', {
+	slots: { header: 'font-semibold px-4', body: 'px-4 py-4', footer: 'px-4 border-t' }
+});
+
+const { base, header, body, footer } = card();
+```
+
+Variant values can target slots: `size: { sm: { base: 'p-2', header: 'text-sm' } }`. Use `compoundSlots` to apply classes to multiple slots at once.
+
+### 5. Use VariantProps Type for Component Props
+
+```typescript
+type ButtonProps = VariantProps<typeof button>;
+// Exclude internal variants from props:
+type InternalButtonProps = VariantProps<typeof button, 'internalState'>;
+```
+
+### 6. Use Compound Variants for Conditional Combinations
+
+Apply classes when multiple conditions are met:
+
+```typescript
+compoundVariants: [
+	{ size: 'lg', intent: 'primary', class: 'font-bold uppercase' }
+]
+```
+
+### 7. Use Function-Based Default Variants for Dynamic Defaults
+
+A default can be a function of the other variant values:
+
+```typescript
+defaultVariants: {
+	size: 'sm',
+	intent: (props) => {
+		if (props.size === 'lg') return 'danger';
+		return 'primary';
+	}
+}
+```
+
+Prefer static defaults — function-based defaults run on every invocation.
+
+### 8. Use Post-Processing with tailwind-merge
+
+For Tailwind projects, pass `postProcess` to resolve class conflicts:
+
+```typescript
+import { twMerge } from 'tailwind-merge';
+
+sv('px-4 py-2', { variants: { size: { lg: 'px-6 py-3' } }, postProcess: twMerge });
+```
+
+### 9. Leverage Caching for Performance
+
+The library caches results automatically (default 256 entries). Each cache entry is one distinct combination of resolved variant values:
+
+```
+maxEntries = (values₁ + 1) × (values₂ + 1) × ... × (valuesₙ + 1)
+```
+
+The `+ 1` counts the variant being left unset. Raise `cacheSize` only when `maxEntries` exceeds 256 — below that the cache never evicts. Cache inspection methods (`getCacheSize`, `clearCache`) are only exposed when `introspection: true`.
+
+### 10. Use Presets for Reusable Variant Combinations
+
+```typescript
+const button = sv('btn', {
+	variants: { size: { sm: 'text-sm', lg: 'text-lg' }, intent: { primary: 'bg-blue-500', danger: 'bg-red-500' } },
+	presets: { cta: { size: 'lg', intent: 'primary' } }
+});
+
+button({ preset: 'cta' }); // applies size: 'lg', intent: 'primary'
+```
+
+### 11. Use Introspection for Single Source of Truth
+
+Set `introspection: true` to expose configuration and cache members on the returned function (off by default): `variantKeys`, `variants`, `slotKeys`, `slots`, `defaultVariants`, `requiredVariants`, `presetKeys`, `presets`, `getVariantValues(key)`, `getCacheSize()`, and `clearCache()`.
+
+Without `introspection: true`, accessing these is a type error. Use it to centralize variant/slot definitions and reuse them across the codebase.
+
+## Common Patterns
+
+### React Component Pattern
+
+```typescript
+import { sv, type VariantProps } from 'slot-variants';
+
+const button = sv('btn font-medium rounded-lg', {
+	variants: {
+		size: { sm: 'text-sm px-3', md: 'text-base px-4', lg: 'text-lg px-6' },
+		intent: { primary: 'bg-blue-500 text-white', danger: 'bg-red-500 text-white' }
+	},
+	defaultVariants: { size: 'md', intent: 'primary' }
+});
+
+export type ButtonProps = VariantProps<typeof button>;
+
+export const Button = ({ class: className, ...props }: ButtonProps & { class?: string }) => {
+	return <button className={button({ ...props, class: className })} />;
+};
+```
+
+### Multi-Element Component Pattern
+
+```typescript
+const card = sv('border rounded-lg', {
+	slots: { header: 'font-semibold px-4 border-b', body: 'px-4 py-4', footer: 'px-4 border-t' },
+	variants: {
+		size: { sm: { base: 'p-2', header: 'text-sm' }, md: { base: 'p-4', header: 'text-base' } },
+		elevated: { true: { base: 'shadow-lg' }, false: { base: 'shadow-sm' } }
+	},
+	compoundSlots: [{ slots: ['header', 'footer'], class: 'text-gray-600' }]
+});
+
+const { base, header, body, footer } = card({ size: 'md' });
+```
+
+## Configuration Reference
+
+Class values inside the config (`base`, `variants` values, `slots` values, and `compound*` `class`/`className`) accept only `string`, `string[]`, or `undefined`. Dynamic class values (objects, booleans, nested arrays) belong on the `class`/`className` runtime prop, not in the config.
+
+| Option             | Type                                 | Description                       |
+| ------------------ | ------------------------------------ | --------------------------------- |
+| `base`             | `string \| string[]`                 | Additional base classes           |
+| `variants`         | `Record<string, VariantConfig>`      | Variant definitions               |
+| `slots`            | `Record<string, string \| string[]>` | Named slot definitions            |
+| `compoundVariants` | `CompoundVariant[]`                  | Conditional class combinations    |
+| `compoundSlots`    | `CompoundSlot[]`                     | Multi-slot conditional classes    |
+| `defaultVariants`  | `Record<string, Value>`              | Static or function-based defaults |
+| `requiredVariants` | `string[] \| boolean`                | Mandatory variant names           |
+| `multiSlots`       | `string[] \| boolean`                | Slots exposed as reconfigurable functions |
+| `presets`          | `Record<string, Partial<Props>>`     | Named preset combinations         |
+| `postProcess`      | `(className: string) => string`      | Class transformation              |
+| `cacheSize`        | `number`                             | Cache size (default: 256)         |
+| `introspection`    | `boolean`                            | Expose introspection and cache methods (default: false) |
+
+## Exported Types
+
+- `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
+
+Functions are imported as named values; types via `import type { ... } from 'slot-variants'`.