slot-variants 1.2.0 → 1.3.0

package/AGENTS.md

@@ -211,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
@@ -241,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', {
@@ -264,7 +262,8 @@ const button = sv('btn', {
 	requiredVariants: ['intent'],
 	presets: {
 		cta: { size: 'lg', intent: 'primary' }
-	}
+	},
+	introspection: true
 });
 
 button.variantKeys;                // ['size', 'intent']
@@ -277,8 +276,12 @@ 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
@@ -299,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
@@ -313,7 +317,8 @@ const card = sv('card', {
   slots: {
     header: 'font-bold',
     body: 'py-4'
-  }
+  },
+  introspection: true
 });
 
 // Dynamically render all slots
@@ -400,11 +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`             | `ClassValue`                     | Additional base classes            |
+| `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 |
@@ -412,6 +419,7 @@ 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
 
@@ -430,6 +438,90 @@ import { sv, cn } 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

package/README.md

@@ -172,15 +172,14 @@ badge({ color: 'green', size: 'sm' });
 // 'badge bg-green-100 text-green-800 text-xs px-2 py-0.5'
 ```
 
-Variant values can be strings, arrays, or objects:
+Variant values accept a string or an array of strings:
 
 ```typescript
 const button = sv('btn', {
   variants: {
     size: {
-      sm: ['px-2', 'py-1', 'text-sm'],                    // array
-      lg: 'px-6 py-3 text-lg',                            // string
-      xl: { 'px-8': true, 'py-4': true, 'text-xl': true } // object
+      sm: ['px-2', 'py-1', 'text-sm'], // array of strings
+      lg: 'px-6 py-3 text-lg'          // string
     }
   }
 });
@@ -679,16 +678,15 @@ const button = sv('btn', {
       lg: 'text-lg'
     }
   },
-  cacheSize: 512        // customize the cache size
+  cacheSize: 512  // customize the cache size
 });
-
-button.getCacheSize();  // current number of cached entries
-button.clearCache();    // clear all cached entries
 ```
 
+Cache inspection and control methods (`getCacheSize`, `clearCache`) are exposed on the returned function only when `introspection: true` is set — see [Introspection](#introspection).
+
 ### Introspection
 
-The returned function exposes configuration properties for runtime introspection:
+Set `introspection: true` in the config to expose configuration properties and cache controls on the returned function for runtime inspection. Introspection is **disabled by default** to keep the returned function lean; opt in only when you need it:
 
 ```typescript
 const button = sv('btn', {
@@ -711,7 +709,8 @@ const button = sv('btn', {
   requiredVariants: ['intent'],
   presets: {
     cta: { size: 'lg', intent: 'primary' }
-  }
+  },
+  introspection: true
 });
 
 button.variantKeys;                 // ['size', 'intent']
@@ -724,8 +723,12 @@ button.presetKeys;                  // ['cta']
 button.presets;                     // { cta: { size: 'lg', intent: 'primary' } }
 button.getVariantValues('size');    // ['sm', 'lg']
 button.getVariantValues('intent');  // ['primary', 'danger']
+button.getCacheSize();              // current number of cached entries
+button.clearCache();                // clear all cached entries
 ```
 
+Without `introspection: true`, only the variant function itself is returned — accessing introspection or cache properties is a type error.
+
 ## TypeScript
 
 `slot-variants` is fully typed. Variant props are inferred from your config:
@@ -871,11 +874,13 @@ When used on an `sv()` definition without slots, `SlotClassProps` resolves to `{
 
 ## Config Reference
 
+Class values inside the config (`base`, `variants`, `slots`, and `compound*` `class`/`className`) accept `string`, `string[]`, or `undefined`. Dynamic class values (objects, booleans, nested arrays) are only accepted at call time via the `class`/`className` prop.
+
 | 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 |
+| `base` | `string \| string[]` | Additional base classes merged with the base argument and `slots.base` |
+| `variants` | `Record<string, Record<string \| number, string \| string[]>>` | Variant definitions mapping variant names to their possible values |
+| `slots` | `Record<string, string \| string[]>` | Named slot definitions for multi-element components |
 | `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) |
@@ -883,6 +888,171 @@ When used on an `sv()` definition without slots, `SlotClassProps` resolves to `{
 | `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`) |
+| `introspection` | `boolean` | When `true`, exposes variant/slot/preset introspection and cache methods on the returned function (default: `false`) |
+
+## ESLint / oxlint Plugin
+
+`slot-variants` ships an ESLint-compatible plugin at the `slot-variants/eslint-plugin` subpath. It runs under ESLint v9+ (flat config) and under [oxlint](https://oxc.rs/docs/guide/usage/linter/js-plugins) via its `jsPlugins` API. The plugin is a separate entry point with no runtime imports — consuming it doesn't pull any library code into your bundle.
+
+### 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-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-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-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-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.
+
+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.
+
+### ESLint (flat 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'
+    }
+  }
+];
+```
+
+### oxlint
+
+```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"
+  }
+}
+```
+
+### Example
+
+```typescript
+import { sv, cn } from 'slot-variants';
+
+const button = sv({
+  base: 'flex items-center',
+  variants: {
+    orientation: {
+      row: ['flex', 'flex-row'], // 'flex' duplicates base
+      col: ['flex', 'flex-col']  // 'flex' duplicates base
+    }
+  }
+});
+
+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.
+
+```typescript
+import { sv, cn } from 'slot-variants';
+
+const extra = getDynamicClass();
+
+sv({ base: extra });                   // dynamic base
+sv({ base: `text-sm ${size}` });       // template with expression
+sv({ ...rest, variants: {} });         // spread inside config
+sv({ variants: { [key]: 'x' } });      // computed variant key
+sv({ slots: { body: ['p-4', ...rest] } }); // spread inside slot array
+cn(extra, 'flex');                     // identifier argument
+```
+
+`no-dynamic-classes` reports each of the dynamic positions above. Replace dynamic class strings with static ones (or move them to the runtime `class` / `className` prop on the returned function, which is intentionally outside the analyzer's scope) so every call can be statically verified.
+
+```typescript
+import { sv, cn } from 'slot-variants';
+
+sv({ base: '' });                              // empty base
+sv({ base: [] });                              // empty array
+sv({ variants: { size: { sm: '' } } });        // empty variant value
+sv({ compoundVariants: [{ size: 'lg', class: '' }] }); // empty compound class
+cn('flex', '');                                // empty cn arg
+sv();                                          // zero-arg call
+cn();                                          // zero-arg call
+```
+
+`no-empty-classes` reports each empty class value — strings, arrays, or objects — plus zero-argument `sv()` / `cn()` calls (they always produce an empty string). The one exception is a direct empty string at `slots[key]`, which is allowed because declaring a slot with no default classes is a real use case (`sv({ slots: { extra: '' } })`). Either remove the empty value or replace it with a meaningful class string.
+
+```typescript
+import { sv, cn } from 'slot-variants';
+
+sv({ base: ' flex items-center' });            // leading space
+sv({ base: 'flex  items-center' });            // double space
+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.
+
+```typescript
+import { sv } from 'slot-variants';
+
+const button = sv({
+  variants: {
+    size: {
+      sm: 'rounded text-sm',
+      lg: 'rounded text-lg'
+    }
+  },
+  defaultVariants: { size: 'sm' }
+});
+
+const card = sv({
+  slots: { root: 'flex', body: 'p-4' },
+  variants: {
+    size: {
+      sm: { root: 'rounded text-sm', body: 'p-1' },
+      lg: { root: 'rounded text-lg', body: 'p-2' }
+    }
+  },
+  requiredVariants: ['size']
+});
+```
+
+`no-shared-tokens` reports `rounded` in both `button` variant values and in both `card` `root` slot values, because the token is present in every value of an exhaustive variant. Lift that class into `base` — or into `slots.root` for slot-based variants — so each variant value contains only the classes that actually vary.
+
+## IntelliSense Setup (Optional)
+
+If you're using Tailwind CSS, you can opt into class autocompletion and automatic class sorting inside `sv()` and `cn()` calls.
+
+### VSCode
+
+The [Tailwind CSS IntelliSense](https://marketplace.visualstudio.com/items?itemName=bradlc.vscode-tailwindcss) extension recognizes calls listed in `tailwindCSS.classFunctions`. Add `cn` and `sv` to your workspace or user settings:
+
+```json
+{
+  "tailwindCSS.classFunctions": ["cn", "sv"]
+}
+```
+
+### Prettier
+
+The [`prettier-plugin-tailwindcss`](https://github.com/tailwindlabs/prettier-plugin-tailwindcss) plugin sorts Tailwind classes inside the functions listed in `tailwindFunctions`:
+
+```js
+module.exports = {
+  plugins: [require('prettier-plugin-tailwindcss')],
+  tailwindFunctions: ['cn', 'sv']
+};
+```
 
 ## Migrating from CVA / tailwind-variants
 
@@ -958,4 +1128,4 @@ const button = sv({
   variants: { size: { sm: 'px-2 py-1' } },
   postProcess: twMerge
 });
-```
+```