slot-variants 1.1.0 → 1.3.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
@@ -187,12 +211,10 @@ const button = sv('btn', {
 	},
 	cacheSize: 512 // increase cache for complex components
 });
-
-// Access cache methods
-button.getCacheSize();
-button.clearCache();
 ```
 
+Cache inspection methods (`getCacheSize`, `clearCache`) are only exposed when `introspection: true` is set — see rule 11.
+
 Note: Using `class` or `className` prop bypasses caching.
 
 ### 10. Use Presets for Reusable Variant Combinations
@@ -217,7 +239,7 @@ button({ preset: 'cta' });
 
 ### 11. Use Introspection for Single Source of Truth
 
-The returned function exposes configuration properties for runtime introspection. Use these to access variant/slot definitions and reuse them elsewhere, avoiding duplication:
+Set `introspection: true` in the config to expose configuration properties and cache methods on the returned function. Introspection is **off by default** — opt in only when you need runtime access to variant/slot definitions or cache controls:
 
 ```typescript
 const button = sv('btn', {
@@ -240,19 +262,26 @@ const button = sv('btn', {
 	requiredVariants: ['intent'],
 	presets: {
 		cta: { size: 'lg', intent: 'primary' }
-	}
+	},
+	introspection: true
 });
 
-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']
+button.getCacheSize();             // current cache size
+button.clearCache();               // clear the cache
 ```
 
+Without `introspection: true`, only the variant function itself is returned — accessing these properties is a type error.
+
 Use introspection to share variant/slot definitions with other parts of your codebase:
 
 ```typescript
@@ -273,7 +302,8 @@ export const button = sv('btn font-medium rounded-lg', {
   defaultVariants: {
     size: 'md',
     intent: 'primary'
-  }
+  },
+  introspection: true
 });
 
 // Reuse variant keys for form validation
@@ -287,7 +317,8 @@ const card = sv('card', {
   slots: {
     header: 'font-bold',
     body: 'py-4'
-  }
+  },
+  introspection: true
 });
 
 // Dynamically render all slots
@@ -374,10 +405,13 @@ export const Card = (props: CardProps) => {
 
 ## 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, ClassValue>`     | Named slot 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 |
@@ -385,11 +419,14 @@ export const Card = (props: CardProps) => {
 | `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
 
 ## Imports
 
@@ -398,9 +435,93 @@ 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';
 ```
 
+## ESLint / oxlint Plugin
+
+Subpath export `slot-variants/eslint-plugin` ships five rules that statically analyze `sv()` and `cn()` calls. Works under ESLint v9+ (flat config) and under oxlint via its `jsPlugins` config. The plugin is a separate entry point — it adds no runtime code to the library bundle.
+
+```js
+// eslint.config.js
+import svPlugin from 'slot-variants/eslint-plugin';
+
+export default [{
+  plugins: { 'slot-variants': svPlugin },
+  rules: {
+    'slot-variants/no-duplicate-classes': 'error',
+    'slot-variants/no-dynamic-classes': 'error',
+    'slot-variants/no-empty-classes': 'error',
+    'slot-variants/no-redundant-spaces': 'error',
+    'slot-variants/no-shared-tokens': 'error'
+  }
+}];
+```
+
+```json
+// .oxlintrc.json
+{
+  "jsPlugins": ["slot-variants/eslint-plugin"],
+  "rules": {
+    "slot-variants/no-duplicate-classes": "error",
+    "slot-variants/no-dynamic-classes": "error",
+    "slot-variants/no-empty-classes": "error",
+    "slot-variants/no-redundant-spaces": "error",
+    "slot-variants/no-shared-tokens": "error"
+  }
+}
+```
+
+All rules only analyze calls where `sv` or `cn` is a **named import** from `'slot-variants'`. Default, namespace, and aliased-to-other-identifier imports are ignored.
+
+### `slot-variants/no-duplicate-classes`
+
+Reports class tokens that will appear more than once in the output of an `sv()` or `cn()` call.
+
+- For `sv()` with a config, flags a token as duplicated when two of its sources can both be active at runtime: base + any variant, base + compound, two variants with different keys, two compound entries, or the same literal token repeated inside a single source.
+- Does **not** flag the same token appearing in different values of the **same** variant key (those are mutually exclusive).
+- For `cn()` (and `sv()` called without a config — the cn-style calling convention), flags any token that appears in more than one always-present source: across args, inside arrays, template literals without expressions, or within a single literal.
+- Bails out silently on dynamic inputs (identifiers, spreads, computed keys, template literals with expressions, cn-style `{ cls: condition }` records) — no false positives for code it can't statically resolve.
+
+### `slot-variants/no-dynamic-classes`
+
+Reports class-bearing positions in `sv()` and `cn()` calls that aren't statically inferrable. Pair this rule with `no-duplicate-classes` to guarantee every call is fully analyzable.
+
+- Accepts only string literals, template literals without expressions, and arrays of those as class values. Identifiers, member access, calls, spreads, non-string literals, templates with expressions, and object records are reported.
+- For `sv()` config, validates `base`, `slots` values, `variants` values (both record form and boolean shorthand), and the `class` / `className` of `compoundVariants` / `compoundSlots` entries. The `slots` array of `compoundSlots` must be a static array of string literals.
+- Top-level config keys must be statically known — spreads and computed keys cause the call to fall through to the cn-style path, which then reports the entire object as dynamic.
+- Non-class-bearing config keys (`defaultVariants`, `presets`, `requiredVariants`, `cacheSize`, `postProcess`, `introspection`) are not validated. Runtime variant matchers inside compound entries are also left alone — only the class value (and `compoundSlots`' `slots` array) is checked.
+- Move dynamic class strings to the runtime `class` / `className` prop on the function returned by `sv()` — that call site is intentionally outside the analyzer's scope.
+
+### `slot-variants/no-empty-classes`
+
+Reports 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 (which always produce an empty class string).
+
+- Reports empty literals as positional arguments to `cn()` and `sv()` (cn-style or as base args alongside a config), as well as empty literals nested inside class arrays.
+- Inside an `sv()` config, reports empty values at `base`, in `variants` value records and boolean-shorthand values, and in the `class`/`className` of `compoundVariants` / `compoundSlots` entries. Also reports empty top-level `slots`, `variants`, `compoundVariants`, and `compoundSlots` containers.
+- A direct empty string at `slots[key]` is allowed — declaring a slot with no default classes is a real use case (`sv({ slots: { extra: '' } })`). Empty strings inside slot-value arrays are still reported.
+- Reports `sv()` / `cn()` invocations with zero arguments — they always return an empty string and have no effect.
+- Recurses into arrays but not into objects: values inside cn-style `{ cls: condition }` records are conditions, not class values, so they are left alone.
+
+### `slot-variants/no-redundant-spaces`
+
+Reports class strings whose whitespace isn't canonical — that is, whose value differs from `value.split(/\s+/).filter(Boolean).join(' ')`.
+
+- Flags leading or trailing whitespace, repeated spaces, and non-space whitespace (tabs, newlines, etc.) inside any string literal or expressionless template literal reachable from the call's arguments.
+- Walks recursively into arrays and objects, so values nested inside `slots`, `variants` records, `compoundVariants`, `compoundSlots`, `defaultVariants`, `presets`, etc. are all inspected.
+- Bails silently on dynamic expressions and non-string literals — false positives are impossible by construction.
+- Reports once per offending literal at the whole-node location. Fix by trimming and collapsing the string, or by splitting it into array entries.
+
+### `slot-variants/no-shared-tokens`
+
+Reports class tokens that appear in every value of an exhaustively-covered variant — the token is constant in the rendered output and belongs in `base` or the corresponding `slots[slot]` entry rather than being repeated across every variant value.
+
+- Only analyzes `sv()` calls with a config; `cn()` calls and cn-style `sv()` calls are ignored.
+- Treats a variant as exhaustive when it has a `defaultVariants` entry or is listed in `requiredVariants`.
+- Compares tokens per slot, so slot-based variants are checked against the specific slot they affect rather than only against `base`.
+- Skips non-exhaustive variants, single-value variants, boolean shorthand, slot-keyed boolean shorthand, and dynamic or partially-uninspectable variant value records.
+- Reports every repeated occurrence that should be lifted out of the variant so each value only contains classes that actually vary.
+
 ## Performance Notes
 
 1. **Caching is automatic** - Results are cached by default