slot-variants 1.6.1 → 1.6.2

package/README.md

@@ -711,7 +711,9 @@ card({ class: { base: 'shadow-xl', header: 'text-blue-700', body: 'min-h-24' } }
 // base: 'border shadow-xl', header: 'font-bold text-blue-700', body: 'py-4 min-h-24'
 ```
 
-Both `class` and `className` are supported, but `class` is prioritized when both are used in the same time.
+Both `class` and `className` are supported, but `class` takes priority when both are passed at the same time.
+
+The runtime `class`/`className` override is not part of the cache key — it is merged on top of the cached variant result on every call (and `postProcess`, if set, is re-applied to the merged output). Two calls with identical variants but different `class` values therefore share the same cached base result.
 
 ### Post-Processing
 
@@ -734,6 +736,10 @@ const button = sv('px-4 py-2 bg-blue-500', {
 
 The `postProcess` function is applied to each slot's final class string independently.
 
+`sv()` and `cn()` concatenate classes in order without deduplicating or resolving conflicts — a class repeated across `base` and a variant value appears twice in the output, and conflicting Tailwind utilities are both kept. Use `postProcess: twMerge` when you need duplicates collapsed and later utilities to win at runtime.
+
+For statically-defined classes, the bundled [ESLint / oxlint plugin](#eslint--oxlint-plugin) catches most duplication at lint time — before it ever reaches the output: `no-conflicting-classes` flags duplicate and same-namespace tokens within a call, and `no-shared-tokens` flags a class repeated across every value of a variant (which belongs in `base` instead). The two approaches complement each other — the plugin keeps your source clean, while `postProcess: twMerge` handles duplicates that only arise from dynamic, runtime-supplied classes.
+
 ### 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:
@@ -806,6 +812,8 @@ const button = sv('btn', {
 });
 ```
 
+Setting `cacheSize` to `0` (or a negative number) disables caching entirely — every call recomputes its result. This is useful when variant combinations are effectively unbounded and you'd rather not retain any entries.
+
 Cache inspection and control methods (`getCacheSize`, `clearCache`) are exposed on the returned function only when `introspection: true` is set — see [Introspection](#introspection).
 
 ### Introspection
@@ -855,6 +863,36 @@ 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.
 
+### Errors & Validation
+
+`sv()` validates both the config and the runtime props, throwing an `Error` on misconfiguration. TypeScript prevents most of these statically, but they still guard against untyped runtime input (e.g. a value coming from a form or API).
+
+**Config-time** — thrown when `sv(config)` is evaluated (at module load, when the variant function is built):
+
+| Message | Cause |
+| --- | --- |
+| `Required variant "X" is not defined in variants` | `requiredVariants` lists a variant that doesn't exist |
+| `Required variant "X" cannot have a default value` | A variant is both in `requiredVariants` and `defaultVariants` |
+| `Default variant "X" is not defined in variants` | `defaultVariants` references an unknown variant |
+| `Default variant "X" has invalid value "V"` | A static default value isn't one of the variant's values |
+| `Preset "P" references unknown variant "X"` | A preset references an unknown variant |
+| `Preset "P" has invalid value "V" for variant "X"` | A preset value isn't one of the variant's values |
+| `Compound matcher references unknown variant "X"` | A compound variant/slot matches on an unknown variant |
+| `Compound matcher for variant "X" has invalid value "V"` | A compound matcher value isn't one of the variant's values |
+| `Compound variant must define "class" or "className"` | A `compoundVariants` entry has no class value |
+| `Compound slot must define "class" or "className"` | A `compoundSlots` entry has no class value |
+| `Compound slot must define at least one slot` | A `compoundSlots` entry has an empty `slots` array |
+| `Compound slot references unknown slot "S"` | A `compoundSlots` entry targets an undefined slot |
+| `Multi slot references unknown slot "S"` | `multiSlots` lists a slot that doesn't exist |
+
+**Runtime** — thrown when the returned variant function is called:
+
+| Message | Cause |
+| --- | --- |
+| `Missing required variant: "X"` | A required variant wasn't provided (by prop or preset) |
+| `Invalid value "V" for variant "X"` | A prop value isn't one of the variant's defined values |
+| `Invalid preset "P"` | The `preset` prop names a preset that doesn't exist |
+
 ## TypeScript
 
 `slot-variants` is fully typed. Variant props are inferred from your config:
@@ -876,7 +914,7 @@ const button = sv('btn', {
   requiredVariants: ['intent']
 });
 
-// Extract the variant props type (excludes class/className)
+// Extract the variant props type (excludes class, className, and preset)
 type ButtonProps = VariantProps<typeof button>;
 // { size?: 'sm' | 'lg' | undefined; intent: 'primary' | 'danger' }
 ```
@@ -1015,7 +1053,7 @@ Class values inside the config (`base`, `variants`, `slots`, and `compound*` `cl
 | `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`) |
+| `cacheSize` | `number` | Maximum number of cached results (default: `256`); `0` or a negative value disables caching |
 | `introspection` | `boolean` | When `true`, exposes variant/slot/preset introspection and cache methods on the returned function (default: `false`) |
 
 ## ESLint / oxlint Plugin

package/SKILL.md

@@ -121,10 +121,10 @@ const customSV = createSV({ postProcess: twMerge, cacheSize: 512 });
 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)
+maxEntries = factor₁ × factor₂ × ... × factorₙ
 ```
 
-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`.
+A variant's factor is its value count `+ 1` (the `+ 1` counts the variant being left unset). The `+ 1` is dropped — factor is just the value count — when the variant is required or has a static default, since it can never be unset. Function-based defaults still count as unset-able, so they keep the `+ 1`. Raise `cacheSize` only when `maxEntries` exceeds 256 — below that the cache never evicts. With `introspection: true`, `getMaxEntries()` returns this exact number, and `getCacheSize()`/`clearCache()` inspect the live cache.
 
 ### 10. Use Presets for Reusable Variant Combinations
 
@@ -139,7 +139,7 @@ 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()`.
+Set `introspection: true` to expose configuration and cache members on the returned function (off by default): `variantKeys`, `variants`, `slotKeys`, `slots`, `defaultVariants`, `requiredVariants`, `multiSlots`, `presetKeys`, `presets`, `getVariantValues(key)`, `getMaxEntries()`, `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.
 
@@ -201,7 +201,7 @@ Class values inside the config (`base`, `variants` values, `slots` values, and `
 
 ## Exported Types
 
-- `ClassValue` — Valid input for `cn()` (string, array, object, boolean, null, undefined)
+- `ClassValue` — Valid input for `cn()` (string, number, bigint, 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

package/dist/eslint-plugin.cjs

@@ -254,17 +254,54 @@ var pushStringLiteralTokens = (node, slot, source, entries, sourceCode) => {
   }
 };
 var isStaticStringNode = (node) => getStaticStringText(node) !== null;
-var extractTokens = (node, slot, source, slotNames, entries, sourceCode) => {
+var pushRecordKeyTokens = (prop, slot, source, entries, sourceCode) => {
+  const { key } = prop;
+  if (key.type === "Literal" && typeof key.value === "string") {
+    pushStringLiteralTokens(key, slot, source, entries, sourceCode);
+    return;
+  }
+  const token = getKeyName(prop);
+  if (token === null) {
+    return;
+  }
+  const [start, end] = sourceCode.getRange(key);
+  entries.push({ source, slot, token, start, end });
+};
+var extractRecordTokens = (node, slot, source, entries, sourceCode) => {
+  for (const prop of node.properties) {
+    if (prop.type !== "Property" || prop.computed) {
+      continue;
+    }
+    pushRecordKeyTokens(prop, slot, source, entries, sourceCode);
+  }
+};
+var extractTokens = (node, slot, source, slotNames, entries, sourceCode, cnStyle = false) => {
   if (isStaticStringNode(node)) {
     pushStringLiteralTokens(node, slot, source, entries, sourceCode);
     return;
   }
+  if (cnStyle && isLogicalClassStaticString(node)) {
+    pushStringLiteralTokens(node.right, slot, source, entries, sourceCode);
+    return;
+  }
   if (node.type === "ArrayExpression") {
     forEachStaticItem(node.elements, (element) => {
-      extractTokens(element, slot, source, slotNames, entries, sourceCode);
+      extractTokens(
+        element,
+        slot,
+        source,
+        slotNames,
+        entries,
+        sourceCode,
+        cnStyle
+      );
     });
     return;
   }
+  if (cnStyle && node.type === "ObjectExpression") {
+    extractRecordTokens(node, slot, source, entries, sourceCode);
+    return;
+  }
   const slotKeyedProps = collectSlotKeyedProperties(node, slotNames);
   if (!slotKeyedProps) {
     return;
@@ -356,7 +393,7 @@ var collectConfigEntries = (config, slotNames, baseArgs, sourceCode) => {
     extract(slotValue, slotKey, baseSource);
   }
   for (const arg of baseArgs) {
-    extract(arg, "base", baseSource);
+    extractTokens(arg, "base", baseSource, slotNames, entries, sourceCode, true);
   }
   const base = config.get("base");
   if (base) {
@@ -378,6 +415,7 @@ var reportDynamic = (context, node) => {
   context.report({ node, messageId: "dynamic" });
 };
 var isUndefinedIdentifier = (node) => node.type === "Identifier" && node.name === "undefined";
+var isLogicalClassStaticString = (node) => node.type === "LogicalExpression" && node.operator === "&&" && isStaticStringNode(node.right);
 var forEachItemReportingSpread = (context, items, visit) => {
   for (const item of items) {
     if (!item) {
@@ -397,6 +435,9 @@ var checkClassValueIsStatic = (context, node, options = {}) => {
   if (isStaticStringNode(node)) {
     return;
   }
+  if (options.allowLogicalString && isLogicalClassStaticString(node)) {
+    return;
+  }
   if (node.type === "ArrayExpression") {
     forEachItemReportingSpread(context, node.elements, (element) => {
       if (options.allowNestedArrays === false) {
@@ -405,10 +446,17 @@ var checkClassValueIsStatic = (context, node, options = {}) => {
           return;
         }
       }
-      checkClassValueIsStatic(context, element);
+      checkClassValueIsStatic(context, element, {
+        allowLogicalString: options.allowLogicalString === true,
+        allowClassRecord: options.allowClassRecord === true
+      });
     });
     return;
   }
+  if (options.allowClassRecord && node.type === "ObjectExpression") {
+    checkClassRecordKeys(context, node);
+    return;
+  }
   reportDynamic(context, node);
 };
 var checkConfigClassValueIsStatic = (context, node) => {
@@ -430,6 +478,10 @@ var forEachStaticProperty = (context, node, visit) => {
     visit(prop);
   }
 };
+var checkClassRecordKeys = (context, node) => {
+  forEachStaticProperty(context, node, () => {
+  });
+};
 var checkClassValueRecord = (context, node) => {
   if (node.type !== "ObjectExpression") {
     reportDynamic(context, node);
@@ -551,7 +603,10 @@ var checkSvConfig = (context, configNode) => {
 };
 var checkCnArguments = (context, args) => {
   forEachItemReportingSpread(context, args, (arg) => {
-    checkClassValueIsStatic(context, arg);
+    checkClassValueIsStatic(context, arg, {
+      allowLogicalString: true,
+      allowClassRecord: true
+    });
   });
 };
 var getImportedName = (specifier) => {
@@ -829,7 +884,8 @@ var analyzeCnForRule = (context, args) => {
       baseSource,
       EMPTY_SLOT_NAMES,
       entries,
-      context.sourceCode
+      context.sourceCode,
+      true
     );
   }
   const tokenMap = indexEntriesBySlotAndToken(entries).get("base");

package/dist/eslint-plugin.js

@@ -229,17 +229,54 @@ var pushStringLiteralTokens = (node, slot, source, entries, sourceCode) => {
   }
 };
 var isStaticStringNode = (node) => getStaticStringText(node) !== null;
-var extractTokens = (node, slot, source, slotNames, entries, sourceCode) => {
+var pushRecordKeyTokens = (prop, slot, source, entries, sourceCode) => {
+  const { key } = prop;
+  if (key.type === "Literal" && typeof key.value === "string") {
+    pushStringLiteralTokens(key, slot, source, entries, sourceCode);
+    return;
+  }
+  const token = getKeyName(prop);
+  if (token === null) {
+    return;
+  }
+  const [start, end] = sourceCode.getRange(key);
+  entries.push({ source, slot, token, start, end });
+};
+var extractRecordTokens = (node, slot, source, entries, sourceCode) => {
+  for (const prop of node.properties) {
+    if (prop.type !== "Property" || prop.computed) {
+      continue;
+    }
+    pushRecordKeyTokens(prop, slot, source, entries, sourceCode);
+  }
+};
+var extractTokens = (node, slot, source, slotNames, entries, sourceCode, cnStyle = false) => {
   if (isStaticStringNode(node)) {
     pushStringLiteralTokens(node, slot, source, entries, sourceCode);
     return;
   }
+  if (cnStyle && isLogicalClassStaticString(node)) {
+    pushStringLiteralTokens(node.right, slot, source, entries, sourceCode);
+    return;
+  }
   if (node.type === "ArrayExpression") {
     forEachStaticItem(node.elements, (element) => {
-      extractTokens(element, slot, source, slotNames, entries, sourceCode);
+      extractTokens(
+        element,
+        slot,
+        source,
+        slotNames,
+        entries,
+        sourceCode,
+        cnStyle
+      );
     });
     return;
   }
+  if (cnStyle && node.type === "ObjectExpression") {
+    extractRecordTokens(node, slot, source, entries, sourceCode);
+    return;
+  }
   const slotKeyedProps = collectSlotKeyedProperties(node, slotNames);
   if (!slotKeyedProps) {
     return;
@@ -331,7 +368,7 @@ var collectConfigEntries = (config, slotNames, baseArgs, sourceCode) => {
     extract(slotValue, slotKey, baseSource);
   }
   for (const arg of baseArgs) {
-    extract(arg, "base", baseSource);
+    extractTokens(arg, "base", baseSource, slotNames, entries, sourceCode, true);
   }
   const base = config.get("base");
   if (base) {
@@ -353,6 +390,7 @@ var reportDynamic = (context, node) => {
   context.report({ node, messageId: "dynamic" });
 };
 var isUndefinedIdentifier = (node) => node.type === "Identifier" && node.name === "undefined";
+var isLogicalClassStaticString = (node) => node.type === "LogicalExpression" && node.operator === "&&" && isStaticStringNode(node.right);
 var forEachItemReportingSpread = (context, items, visit) => {
   for (const item of items) {
     if (!item) {
@@ -372,6 +410,9 @@ var checkClassValueIsStatic = (context, node, options = {}) => {
   if (isStaticStringNode(node)) {
     return;
   }
+  if (options.allowLogicalString && isLogicalClassStaticString(node)) {
+    return;
+  }
   if (node.type === "ArrayExpression") {
     forEachItemReportingSpread(context, node.elements, (element) => {
       if (options.allowNestedArrays === false) {
@@ -380,10 +421,17 @@ var checkClassValueIsStatic = (context, node, options = {}) => {
           return;
         }
       }
-      checkClassValueIsStatic(context, element);
+      checkClassValueIsStatic(context, element, {
+        allowLogicalString: options.allowLogicalString === true,
+        allowClassRecord: options.allowClassRecord === true
+      });
     });
     return;
   }
+  if (options.allowClassRecord && node.type === "ObjectExpression") {
+    checkClassRecordKeys(context, node);
+    return;
+  }
   reportDynamic(context, node);
 };
 var checkConfigClassValueIsStatic = (context, node) => {
@@ -405,6 +453,10 @@ var forEachStaticProperty = (context, node, visit) => {
     visit(prop);
   }
 };
+var checkClassRecordKeys = (context, node) => {
+  forEachStaticProperty(context, node, () => {
+  });
+};
 var checkClassValueRecord = (context, node) => {
   if (node.type !== "ObjectExpression") {
     reportDynamic(context, node);
@@ -526,7 +578,10 @@ var checkSvConfig = (context, configNode) => {
 };
 var checkCnArguments = (context, args) => {
   forEachItemReportingSpread(context, args, (arg) => {
-    checkClassValueIsStatic(context, arg);
+    checkClassValueIsStatic(context, arg, {
+      allowLogicalString: true,
+      allowClassRecord: true
+    });
   });
 };
 var getImportedName = (specifier) => {
@@ -804,7 +859,8 @@ var analyzeCnForRule = (context, args) => {
       baseSource,
       EMPTY_SLOT_NAMES,
       entries,
-      context.sourceCode
+      context.sourceCode,
+      true
     );
   }
   const tokenMap = indexEntriesBySlotAndToken(entries).get("base");

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "slot-variants",
-	"version": "1.6.1",
+	"version": "1.6.2",
 	"description": "Type-safe class name variants with slots",
 	"type": "module",
 	"exports": {
@@ -54,6 +54,7 @@
 		"@types/estree": "1.0.9",
 		"class-variance-authority": "0.7.1",
 		"classnames": "2.5.1",
+		"clsx": "2.1.1",
 		"eslint": "10.3.0",
 		"fallow": "^2.62.0",
 		"jiti": "2.7.0",