slot-variants 1.5.0 → 1.6.1

package/README.md

@@ -12,10 +12,11 @@ npm install slot-variants
 
 ## Overview
 
-`slot-variants` exports two functions:
+`slot-variants` exports three functions:
 
 - **`sv()`** - creates variant-based class name generators with optional slots
 - **`cn()`** - a utility for conditionally merging class names
+- **`createSV()`** - builds a pre-configured `sv()` with shared config defaults
 
 `sv()` is a drop-in replacement for [CVA](https://cva.style/) (just rename `cva` to `sv`) and covers the core feature set of [tailwind-variants](https://www.tailwind-variants.org/) (`tv`) with a simpler API. See [Migrating from CVA / tailwind-variants](#migrating-from-cva--tailwind-variants) for details.
 
@@ -68,7 +69,7 @@ cn(['foo', ['bar', 'baz']]);                  // 'foo bar baz'
 cn({ foo: true, bar: false, baz: true });     // 'foo baz'
 
 // Mixed
-cn('base', ['responsive'], { active: true }); // 'base active responsive'
+cn('base', ['responsive'], { active: true }); // 'base responsive active'
 
 // Falsy values are filtered out
 cn('foo', null, undefined, false, 'bar');     // 'foo bar'
@@ -733,6 +734,52 @@ const button = sv('px-4 py-2 bg-blue-500', {
 
 The `postProcess` function is applied to each slot's final class string independently.
 
+### 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:
+
+```typescript
+import { createSV } from 'slot-variants';
+import { twMerge } from 'tailwind-merge';
+
+export const customSV = createSV({
+  postProcess: twMerge,
+  cacheSize: 512
+});
+
+// twMerge is applied without restating it per component
+const button = customSV('px-4 py-2 bg-blue-500', {
+  variants: {
+    size: {
+      sm: 'px-2 py-1 text-sm',
+      lg: 'px-6 py-3 text-lg'
+    }
+  }
+});
+```
+
+`defaults` accepts **any** config option (`base`, `variants`, `slots`, `compoundVariants`, `cacheSize`, `introspection`, `postProcess`, …). The merge is shallow and **a per-call value always wins** over the matching default — there is no deep merging of variants or compound rules:
+
+```typescript
+const customSV = createSV({ postProcess: twMerge });
+
+// This component opts out of twMerge entirely
+const raw = customSV('btn', {
+  variants: { size: { sm: 'text-sm' } },
+  postProcess: (className) => className // overrides the default
+});
+```
+
+Calls with no config object are forwarded straight to `cn()`-style merging and never see the defaults:
+
+```typescript
+const customSV = createSV({ postProcess: (c) => c.toUpperCase() });
+
+customSV('flex', 'items-center'); // 'flex items-center' — defaults are skipped
+```
+
+A factory-level `introspection: true` is reflected in each component's return type, so the [introspection](#introspection) API is available without setting the flag on every config. A per-call `introspection: false` opts an individual component back out.
+
 ### Caching
 
 Results are cached automatically for performance. The default cache size is **256** entries.
@@ -945,6 +992,7 @@ When used on an `sv()` definition without slots, `SlotClassProps` resolves to `{
 | `VariantProps<T, E>` | Extracts variant props from an `sv()` return type, optionally excluding keys in `E` |
 | `VariantValue<T, K>` | Extracts the value union for a single variant key `K`, without `undefined` |
 | `SlotClassProps<T>` | Extracts the per-slot class injection shape from an `sv()` return type |
+| `SV<DI>` | The shape of an `sv()` function, with the factory's introspection default `DI`; the return type of `createSV()` |
 
 ### Return Type
 
@@ -986,6 +1034,8 @@ Class values inside the config (`base`, `variants`, `slots`, and `compound*` `cl
 
 - **`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.
 
+- **`slot-variants/require-top-level-config`** — flags `sv()` calls made with a config object that aren't at the module top level. The config form compiles the variant function and seeds its cache once; nesting it inside a function (a component body, an arrow, an object method, etc.) rebuilds that work — and throws away the variant cache — on every call, so the config form belongs at module scope. The cn-style calling convention of `sv()` (and every `cn()` call) carries no config and is left alone, as are calls inside top-level blocks or conditionals, which still run only at module load.
+
 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)
@@ -1011,7 +1061,8 @@ export default [
       'slot-variants/no-dynamic-classes': 'error',
       'slot-variants/no-empty-classes': 'error',
       'slot-variants/no-redundant-spaces': 'error',
-      'slot-variants/no-shared-tokens': 'error'
+      'slot-variants/no-shared-tokens': 'error',
+      'slot-variants/require-top-level-config': 'error'
     }
   }
 ];
@@ -1027,7 +1078,8 @@ export default [
     "slot-variants/no-dynamic-classes": "error",
     "slot-variants/no-empty-classes": "error",
     "slot-variants/no-redundant-spaces": "error",
-    "slot-variants/no-shared-tokens": "error"
+    "slot-variants/no-shared-tokens": "error",
+    "slot-variants/require-top-level-config": "error"
   }
 }
 ```
@@ -1193,7 +1245,7 @@ Key differences to be aware of:
 | --- | --- | --- |
 | 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` |
+| Built-in `twMerge` | Enabled by default | Use `postProcess: twMerge`, globally via `createSV` |
 
 **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:
 
@@ -1219,3 +1271,13 @@ const button = sv({
   postProcess: twMerge
 });
 ```
+
+To enable it globally — the closest equivalent to `tv`'s default `twMerge` — wrap it once with [`createSV()`](#shared-defaults-with-createsv) and import the result everywhere:
+
+```typescript
+// custom-sv.ts
+import { createSV } from 'slot-variants';
+import { twMerge } from 'tailwind-merge';
+
+export const customSV = createSV({ postProcess: twMerge });
+```

package/SKILL.md

@@ -107,6 +107,15 @@ import { twMerge } from 'tailwind-merge';
 sv('px-4 py-2', { variants: { size: { lg: 'px-6 py-3' } }, postProcess: twMerge });
 ```
 
+To avoid restating `postProcess` (or any config default) per component, wrap `sv` once with `createSV`. Defaults are shallow merged into every config-based call and a per-call value always wins:
+
+```typescript
+import { createSV } from 'slot-variants';
+import { twMerge } from 'tailwind-merge';
+
+const customSV = createSV({ postProcess: twMerge, cacheSize: 512 });
+```
+
 ### 9. Leverage Caching for Performance
 
 The library caches results automatically (default 256 entries). Each cache entry is one distinct combination of resolved variant values:
@@ -196,5 +205,6 @@ Class values inside the config (`base`, `variants` values, `slots` values, and `
 - `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
+- `SV<DI>` — The shape of an `sv()` function (the return type of `createSV()`), carrying the factory's introspection default `DI`
 
 Functions are imported as named values; types via `import type { ... } from 'slot-variants'`.

package/dist/eslint-plugin.cjs

@@ -1215,12 +1215,47 @@ var noEmptyClasses = {
     });
   }
 };
+var isInsideFunctionScope = (scope) => {
+  let current = scope;
+  while (current) {
+    if (current.type === "function") {
+      return true;
+    }
+    current = current.upper;
+  }
+  return false;
+};
+var requireTopLevelConfig = {
+  meta: {
+    type: "problem",
+    docs: {
+      description: "Require sv() calls with a config object to be at the module top level",
+      recommended: true,
+      url: DOCS_URL
+    },
+    schema: [],
+    messages: {
+      nested: "sv() with a config object must be called at the module top level, not nested inside a function \u2014 otherwise its compiled config and variant cache are rebuilt on every call."
+    }
+  },
+  create(context) {
+    return createTrackedCallListeners(context, (node, call) => {
+      if (!call.config) {
+        return;
+      }
+      if (isInsideFunctionScope(context.sourceCode.getScope(node))) {
+        context.report({ node, messageId: "nested" });
+      }
+    });
+  }
+};
 var rules = {
   "no-conflicting-classes": noConflictingClasses,
   "no-dynamic-classes": noDynamicClasses,
   "no-empty-classes": noEmptyClasses,
   "no-redundant-spaces": noRedundantSpaces,
-  "no-shared-tokens": noSharedTokens
+  "no-shared-tokens": noSharedTokens,
+  "require-top-level-config": requireTopLevelConfig
 };
 var meta = { name: "slot-variants" };
 var recommendedRules = {};

package/dist/eslint-plugin.d.ts

@@ -9,6 +9,7 @@ declare const rules: {
     'no-empty-classes': Rule.RuleModule;
     'no-redundant-spaces': Rule.RuleModule;
     'no-shared-tokens': Rule.RuleModule;
+    'require-top-level-config': Rule.RuleModule;
 };
 declare const plugin: {
     meta: {
@@ -20,6 +21,7 @@ declare const plugin: {
         'no-empty-classes': Rule.RuleModule;
         'no-redundant-spaces': Rule.RuleModule;
         'no-shared-tokens': Rule.RuleModule;
+        'require-top-level-config': Rule.RuleModule;
     };
     configs: Record<string, Linter.Config>;
 };

package/dist/eslint-plugin.js

@@ -1190,12 +1190,47 @@ var noEmptyClasses = {
     });
   }
 };
+var isInsideFunctionScope = (scope) => {
+  let current = scope;
+  while (current) {
+    if (current.type === "function") {
+      return true;
+    }
+    current = current.upper;
+  }
+  return false;
+};
+var requireTopLevelConfig = {
+  meta: {
+    type: "problem",
+    docs: {
+      description: "Require sv() calls with a config object to be at the module top level",
+      recommended: true,
+      url: DOCS_URL
+    },
+    schema: [],
+    messages: {
+      nested: "sv() with a config object must be called at the module top level, not nested inside a function \u2014 otherwise its compiled config and variant cache are rebuilt on every call."
+    }
+  },
+  create(context) {
+    return createTrackedCallListeners(context, (node, call) => {
+      if (!call.config) {
+        return;
+      }
+      if (isInsideFunctionScope(context.sourceCode.getScope(node))) {
+        context.report({ node, messageId: "nested" });
+      }
+    });
+  }
+};
 var rules = {
   "no-conflicting-classes": noConflictingClasses,
   "no-dynamic-classes": noDynamicClasses,
   "no-empty-classes": noEmptyClasses,
   "no-redundant-spaces": noRedundantSpaces,
-  "no-shared-tokens": noSharedTokens
+  "no-shared-tokens": noSharedTokens,
+  "require-top-level-config": requireTopLevelConfig
 };
 var meta = { name: "slot-variants" };
 var recommendedRules = {};

package/dist/index.cjs

@@ -21,6 +21,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   cn: () => cn,
+  createSV: () => createSV,
   sv: () => sv
 });
 module.exports = __toCommonJS(index_exports);
@@ -34,6 +35,13 @@ var append = (result, value) => {
   }
   return `${result} ${value}`;
 };
+var appendArray = (result, array) => {
+  const flattened = cn(...array);
+  if (flattened) {
+    return append(result, flattened);
+  }
+  return result;
+};
 var appendRecord = (result, record) => {
   let current = result;
   for (const key of keys(record)) {
@@ -44,11 +52,8 @@ var appendRecord = (result, record) => {
   return current;
 };
 function cn(...args) {
-  let index = 0;
   let result = "";
-  while (index < args.length) {
-    const item = args[index];
-    index++;
+  for (const item of args) {
     if (!item) {
       continue;
     }
@@ -57,7 +62,7 @@ function cn(...args) {
       continue;
     }
     if (isArray(item)) {
-      args.push(...item);
+      result = appendArray(result, item);
       continue;
     }
     if (typeof item === "object") {
@@ -674,12 +679,15 @@ var runVariantResult = (config, props) => {
   }
   return applyMultiSlots(config, props, result);
 };
-function sv(...args) {
+var sv = ((...args) => {
   const last = args.at(-1);
   if (!isConfig(last)) {
     return cn(...args);
   }
   const config = compileConfig(args.slice(0, -1), last);
+  return createVariantFn(config);
+});
+var createVariantFn = (config) => {
   const variantFn = (props = {}) => runVariantResult(config, props);
   if (!config.introspection) {
     return variantFn;
@@ -701,9 +709,24 @@ function sv(...args) {
     clearCache: () => config.cache.clear(),
     getCacheSize: () => config.cache.size
   });
-}
+};
+var createSV = (defaults = {}) => {
+  const configuredSv = (...args) => {
+    const last = args.at(-1);
+    if (!isConfig(last)) {
+      return cn(...args);
+    }
+    const config = compileConfig(args.slice(0, -1), {
+      ...defaults,
+      ...last
+    });
+    return createVariantFn(config);
+  };
+  return configuredSv;
+};
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   cn,
+  createSV,
   sv
 });

package/dist/index.d.ts

@@ -108,6 +108,18 @@ type VariantFn<S extends MaybeSlots, V extends MaybeVariants<S>, RV extends Requ
     (...args: [RequiredVariantKeys<V, RV>] extends [never] ? [props?: Prettify<Props<S, V, RV, P>> | undefined] : [props: Prettify<Props<S, V, RV, P>>]): ReturnValue<S, V, MS>;
 } & (I extends true ? Prettify<IntrospectionValues<S, V, RV, P, MS>> : unknown);
 type NonConfigClassArg<T> = T extends Record<string, unknown> ? Exclude<StringKeyof<T>, ConfigKey> extends never ? never : T : T;
+/**
+ * The shape of an `sv()` function. Mirrors the overloads of the exported `sv`,
+ * with the introspection default `DI` baked in by `createSV()` so configs that
+ * omit `introspection` inherit the factory default in their return type.
+ */
+type SV<DI extends boolean = false> = {
+    <S extends MaybeSlots = undefined, V extends MaybeVariants<S> = undefined, RV extends RequiredVariants<V> = false, P extends MaybePresets<S, V> = undefined, MS extends MultiSlots<S> = false, I extends boolean = DI>(config: Config<S, V, RV, P, MS, I>): VariantFn<S, V, RV, P, MS, I>;
+    <S extends MaybeSlots = undefined, V extends MaybeVariants<S> = undefined, RV extends RequiredVariants<V> = false, P extends MaybePresets<S, V> = undefined, MS extends MultiSlots<S> = false, I extends boolean = DI>(...args: [...ClassValue[], Config<S, V, RV, P, MS, I>]): VariantFn<S, V, RV, P, MS, I>;
+    <const T extends ClassValue[]>(...args: T & {
+        [K in keyof T]: NonConfigClassArg<T[K]>;
+    }): string;
+};
 /**
  * Extracts the variant props object from an `sv()` return type
  *
@@ -215,10 +227,28 @@ type SlotClassProps<T extends AnyFn> = ReturnType<T> extends string ? Partial<Re
  * const { base, header, body } = card();
  * ```
  */
-declare function sv<S extends MaybeSlots = undefined, V extends MaybeVariants<S> = undefined, RV extends RequiredVariants<V> = false, P extends MaybePresets<S, V> = undefined, MS extends MultiSlots<S> = false, I extends boolean = false>(config: Config<S, V, RV, P, MS, I>): VariantFn<S, V, RV, P, MS, I>;
-declare function sv<S extends MaybeSlots = undefined, V extends MaybeVariants<S> = undefined, RV extends RequiredVariants<V> = false, P extends MaybePresets<S, V> = undefined, MS extends MultiSlots<S> = false, I extends boolean = false>(...args: [...ClassValue[], Config<S, V, RV, P, MS, I>]): VariantFn<S, V, RV, P, MS, I>;
-declare function sv<const T extends ClassValue[]>(...args: T & {
-    [K in keyof T]: NonConfigClassArg<T[K]>;
-}): string;
+declare const sv: SV;
+type RawConfig = Config<MaybeSlots, MaybeVariants<MaybeSlots>, RequiredVariants<MaybeVariants<MaybeSlots>>, MaybePresets<MaybeSlots, MaybeVariants<MaybeSlots>>, MultiSlots<MaybeSlots>, boolean>;
+/**
+ * Builds a pre-configured `sv()` function whose `defaults` are applied to every
+ * config-based call. The defaults accept any config option and are shallow
+ * merged so a per-call value always wins; calls with no config are forwarded
+ * to `cn()`-style merging untouched.
+ *
+ * @example
+ * ```ts
+ * import { twMerge } from 'tailwind-merge';
+ *
+ * const customSV = createSV({ postProcess: twMerge, cacheSize: 512 });
+ *
+ * // twMerge is applied without restating it per component
+ * const button = customSV('px-4 py-2', {
+ *   variants: { size: { sm: 'px-2', lg: 'px-6' } }
+ * });
+ * ```
+ */
+declare const createSV: <I extends boolean = false>(defaults?: RawConfig & {
+    introspection?: I | undefined;
+}) => SV<I>;
 
-export { type ClassValue, type SlotClassProps, type VariantProps, type VariantValue, cn, sv };
+export { type ClassValue, type SV, type SlotClassProps, type VariantProps, type VariantValue, cn, createSV, sv };

package/dist/index.js

@@ -7,6 +7,13 @@ var append = (result, value) => {
   }
   return `${result} ${value}`;
 };
+var appendArray = (result, array) => {
+  const flattened = cn(...array);
+  if (flattened) {
+    return append(result, flattened);
+  }
+  return result;
+};
 var appendRecord = (result, record) => {
   let current = result;
   for (const key of keys(record)) {
@@ -17,11 +24,8 @@ var appendRecord = (result, record) => {
   return current;
 };
 function cn(...args) {
-  let index = 0;
   let result = "";
-  while (index < args.length) {
-    const item = args[index];
-    index++;
+  for (const item of args) {
     if (!item) {
       continue;
     }
@@ -30,7 +34,7 @@ function cn(...args) {
       continue;
     }
     if (isArray(item)) {
-      args.push(...item);
+      result = appendArray(result, item);
       continue;
     }
     if (typeof item === "object") {
@@ -647,12 +651,15 @@ var runVariantResult = (config, props) => {
   }
   return applyMultiSlots(config, props, result);
 };
-function sv(...args) {
+var sv = ((...args) => {
   const last = args.at(-1);
   if (!isConfig(last)) {
     return cn(...args);
   }
   const config = compileConfig(args.slice(0, -1), last);
+  return createVariantFn(config);
+});
+var createVariantFn = (config) => {
   const variantFn = (props = {}) => runVariantResult(config, props);
   if (!config.introspection) {
     return variantFn;
@@ -674,8 +681,23 @@ function sv(...args) {
     clearCache: () => config.cache.clear(),
     getCacheSize: () => config.cache.size
   });
-}
+};
+var createSV = (defaults = {}) => {
+  const configuredSv = (...args) => {
+    const last = args.at(-1);
+    if (!isConfig(last)) {
+      return cn(...args);
+    }
+    const config = compileConfig(args.slice(0, -1), {
+      ...defaults,
+      ...last
+    });
+    return createVariantFn(config);
+  };
+  return configuredSv;
+};
 export {
   cn,
+  createSV,
   sv
 };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "slot-variants",
-	"version": "1.5.0",
+	"version": "1.6.1",
 	"description": "Type-safe class name variants with slots",
 	"type": "module",
 	"exports": {