svd-kit 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Eduardo Carvalho
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,99 @@
+# svd-kit
+Styling decomposition system supporting base styles, variants, modifiers, and compound variants.
+
+
+## What is SVD?
+SVD (Styling Variance Decomposition) is a utility built to easily define and consume complex styling configurations.
+It addresses the limitations of standard variance systems by introducing flexible multi-slot mapping, base styles, boolean modifiers, and compound variants.
+
+This utility comes in extremely handy when:
+
+- Building scalable design systems with flexible slot mapping and granular component control.
+- Developing highly customizable UI components requiring deep structural decomposition.
+- Eliminating type boilerplate while retaining deep TypeScript autocomplete and safety.
+
+
+## Key Features
+
+**svd-kit** was highly inspired by [SVDM](https://github.com/lilingxi01/svdm) (Styling Variance Decomposition Module).
+
+While SVDM introduced multi-slot object decomposition, **svd-kit** was built to solve real-world architectural scenarios that SVDM can't handle, such as:
+
+- **Merged or Split Usage:** Use the full `styles` block or extract isolated slots (e.g., `styles.variants.size`).
+- **`className` Merging**: External `className` props can be automatically appended to the end of the chain.
+- **Boolean Modifiers**: Accepts both simple strings and full `{ true: "...", false: "..." }` boolean objects.
+- **Compounded Variants**: Create styles that apply when multiple variant or modifier conditions are met.
+- **`.resolved` Property:** Exposes final values after merging inputs with defaults, perfect for `data-*` attributes.
+
+
+## Installation
+It is very easy to install `svd-kit`. You can install it with any package manager.
+
+```bash
+pnpm install svd-kit
+```
+
+
+## How to Use SVD
+Here you can find a very simple example of how to define styling configurations and use them in your components.
+More examples can be found in the [documentation](https://github.com/eduardoepc/svd-kit/tree/main/docs).
+
+### Definition and Structure
+Every field (`base`, `variants`, `modifiers`, `compound`, `defaults`) is optional, use only what you need.
+
+```typescript
+import { svd } from "svd-kit"
+
+const buttonStyles = svd({
+  base: { layout: "flex gap-1", content: "text-sm" },
+  variants: {
+    variant: {
+      primary: { container: "bg-primary", content: "text-on-primary" },
+      secondary: { container: "bg-secondary", content: "text-on-secondary" },
+    },
+    size: { md: "h-8 px-2", sm: "h-7 px-1" },
+  },
+  modifiers: {
+    pill: { true: "rounded-full", false: "rounded-md" },
+    disabled: "opacity-50",
+  },
+  compound: [
+    { size: "sm", pill: true, className: "px-3" },
+  ],
+  defaults: {
+    variants: { variant: "primary", size: "md" },
+    modifiers: { pill: true },
+  }
+});
+```
+
+### Applying on Components
+Either pass the entire instance to merge everything or destructure the individual slots for granular layout control.
+
+```typescript
+import { type SVDProps, splitProps } from "svd-kit"
+import { cn } from "@/lib/utils"
+
+type ButtonProps = ButtonPrimitive.Props & SVDProps<typeof buttonStyles>;
+
+export function Button(props: ButtonProps) {
+  const [stylingProps, buttonProps] = splitProps(props, buttonStyles);
+  const styles = buttonStyles(stylingProps);
+
+  return (
+    <ButtonPrimitive
+      data-variant={styles.resolved.variants.variant}
+    
+      {...buttonProps}
+  
+      className={cn(styles)}
+    />
+  )
+}
+```
+
+
+## Built Out of Necessity
+**svd-kit** was born out of necessity to solve the messy, unpredictable styling challenges that design systems face.
+
+Its greatest strength is flexibility. Whether you're building a massive UI library or just quick conditional flags for a simple button, **svd-kit** works without getting in your way.

package/dist/index.cjs

@@ -0,0 +1,133 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region src/utils.ts
+function splitProps(props, styleFn) {
+	const filter = new Set([...styleFn({}).keys, "className"]);
+	const matched = {}, rest = {};
+	for (const key in props) (filter.has(key) ? matched : rest)[key] = props[key];
+	return [matched, rest];
+}
+//#endregion
+//#region src/index.ts
+function processBase(base) {
+	const parts = [];
+	const keys = {};
+	if (base) if (typeof base === "string") parts.push(base);
+	else for (const key in base) {
+		keys[key] = base[key];
+		if (base[key]) parts.push(base[key]);
+	}
+	return Object.assign(parts, keys);
+}
+function processVariants(variants, resolved) {
+	const parts = [];
+	const keys = {};
+	for (const vKey in variants) {
+		const activeOption = resolved[vKey];
+		const variantGroup = variants[vKey]?.[activeOption] ?? "";
+		if (typeof variantGroup === "string") {
+			keys[vKey] = variantGroup;
+			if (variantGroup) parts.push(variantGroup);
+		} else if (variantGroup && typeof variantGroup === "object") {
+			const variantSlotsParts = [];
+			const variantSlotsKeys = {};
+			for (const slotKey in variantGroup) {
+				if (variantGroup[slotKey]) {
+					parts.push(variantGroup[slotKey]);
+					variantSlotsParts.push(variantGroup[slotKey]);
+				}
+				variantSlotsKeys[slotKey] = variantGroup[slotKey];
+			}
+			keys[vKey] = Object.assign(variantSlotsParts, variantSlotsKeys);
+		}
+	}
+	return Object.assign(parts, keys);
+}
+function processModifiers(modifiers, resolved) {
+	const parts = [];
+	const keys = {};
+	for (const mKey in modifiers) {
+		const modifierConfig = modifiers[mKey];
+		const isTrue = resolved[mKey];
+		let activeClass = "";
+		if (typeof modifierConfig === "string") activeClass = isTrue ? modifierConfig : "";
+		else if (modifierConfig && typeof modifierConfig === "object") activeClass = (isTrue ? modifierConfig.true : modifierConfig.false) ?? "";
+		keys[mKey] = activeClass;
+		if (activeClass) parts.push(activeClass);
+	}
+	return Object.assign(parts, keys);
+}
+function processCompounds(compounds, resolvedState) {
+	const parts = [];
+	if (!compounds) return parts;
+	for (const compoundConfig of compounds) {
+		let matchesAll = true;
+		const currentCompound = compoundConfig;
+		for (const key in currentCompound) {
+			if (key === "className") continue;
+			const expectedValue = currentCompound[key];
+			const actualValue = resolvedState[key];
+			if (Array.isArray(expectedValue)) {
+				if (!expectedValue.includes(actualValue)) {
+					matchesAll = false;
+					break;
+				}
+			} else if (expectedValue !== actualValue) {
+				matchesAll = false;
+				break;
+			}
+		}
+		if (matchesAll && compoundConfig.className) if (typeof compoundConfig.className === "string") parts.push(compoundConfig.className);
+		else {
+			const slotsRecord = compoundConfig.className;
+			for (const slotKey in slotsRecord) {
+				const slotClass = slotsRecord[slotKey];
+				if (slotClass) parts.push(slotClass);
+			}
+		}
+	}
+	return parts;
+}
+function svd(config) {
+	const stylesGenerator = (props) => {
+		const resolvedVariants = {};
+		for (const key in config.variants) {
+			const firstAvailableKey = Object.keys(config.variants[key] || {})[0];
+			resolvedVariants[key] = props[key] ?? config.defaults?.variants?.[key] ?? firstAvailableKey;
+		}
+		const resolvedModifiers = {};
+		for (const key in config.modifiers || {}) resolvedModifiers[key] = props[key] ?? config.defaults?.modifiers?.[key] ?? false;
+		const baseResult = processBase(config.base);
+		const variantsResult = processVariants(config.variants || {}, resolvedVariants);
+		const modifiersResult = processModifiers(config.modifiers || {}, resolvedModifiers);
+		const mergedState = {
+			...resolvedVariants,
+			...resolvedModifiers
+		};
+		const compoundResult = processCompounds(config.compound, mergedState);
+		const totalParts = [
+			...baseResult,
+			...variantsResult,
+			...modifiersResult,
+			...compoundResult
+		];
+		if (props.className) totalParts.push(props.className);
+		const variantKeys = Object.keys(config.variants ?? {});
+		const modifierKeys = Object.keys(config.modifiers ?? {});
+		return Object.assign(totalParts, {
+			keys: [...variantKeys, ...modifierKeys],
+			base: baseResult,
+			variants: variantsResult,
+			modifiers: modifiersResult,
+			compound: compoundResult,
+			resolved: {
+				variants: resolvedVariants,
+				modifiers: resolvedModifiers
+			}
+		});
+	};
+	stylesGenerator.config = config;
+	return stylesGenerator;
+}
+//#endregion
+exports.splitProps = splitProps;
+exports.svd = svd;

package/dist/index.d.cts

@@ -0,0 +1,52 @@
+//#region src/types.d.ts
+type Slots = Record<string, string>;
+type ModifierValue = string | {
+  true?: string;
+  false?: string;
+};
+type SVDProps<T extends (...args: never[]) => unknown> = Parameters<T>[0];
+type KeyProviderFn = (...args: never[]) => {
+  keys: string[];
+};
+type KnownKeys<T> = { [K in keyof T]: string extends K ? never : number extends K ? never : K }[keyof T];
+type ComputeSVDProps<TVariants, TModifiers> = { [K in KnownKeys<TVariants>]?: keyof TVariants[K] } & { [K in KnownKeys<TModifiers>]?: boolean } & {
+  className?: string;
+};
+type MaybeArray<T> = T | readonly T[];
+type CompoundConditions<TVariants, TModifiers> = { [K in keyof TVariants]?: MaybeArray<keyof TVariants[K]> } & { [K in keyof TModifiers]?: MaybeArray<boolean> };
+type SVDCompound<TVariants, TModifiers, TBase> = CompoundConditions<TVariants, TModifiers> & {
+  className: TBase extends Slots ? string | Partial<Record<keyof TBase, string>> : string;
+};
+interface SVDConfig<TBase extends string | Slots, TVariants extends Record<string, Record<string, string | Slots>>, TModifiers extends Record<string, ModifierValue>> {
+  base?: TBase;
+  variants?: TVariants;
+  modifiers?: TModifiers;
+  compound?: readonly SVDCompound<TVariants, TModifiers, TBase>[];
+  defaults?: {
+    variants?: { [K in keyof TVariants]?: keyof TVariants[K] };
+    modifiers?: { [K in keyof TModifiers]?: boolean };
+  };
+}
+type SVDGeneratorResult<TBase extends string | Slots, TVariants, TModifiers> = {
+  keys: string[];
+  base: TBase extends string ? string & string[] : TBase & string[];
+  variants: { [K in keyof TVariants]: TVariants[K][keyof TVariants[K]] } & string[];
+  modifiers: { [K in keyof TModifiers]: string } & string[];
+  compound: string[];
+  resolved: {
+    variants: { [K in keyof TVariants]: string };
+    modifiers: { [K in keyof TModifiers]: boolean };
+  };
+} & string[];
+//#endregion
+//#region src/utils.d.ts
+declare function splitProps<TProps extends object>(props: TProps, styleFn: KeyProviderFn): [Parameters<typeof styleFn>[0] & {
+  className?: string;
+}, Omit<TProps, keyof Parameters<typeof styleFn>[0] | "className">];
+//#endregion
+//#region src/index.d.ts
+declare function svd<TBase extends string | Slots, TVariants extends Record<string, Record<string, string | Slots>> = Record<string, never>, TModifiers extends Record<string, ModifierValue> = Record<string, never>>(config: SVDConfig<TBase, TVariants, TModifiers>): ((props: ComputeSVDProps<TVariants, TModifiers>) => SVDGeneratorResult<TBase, TVariants, TModifiers>) & {
+  config: SVDConfig<TBase, TVariants, TModifiers>;
+};
+//#endregion
+export { type SVDProps, splitProps, svd };

package/dist/index.d.mts

@@ -0,0 +1,52 @@
+//#region src/types.d.ts
+type Slots = Record<string, string>;
+type ModifierValue = string | {
+  true?: string;
+  false?: string;
+};
+type SVDProps<T extends (...args: never[]) => unknown> = Parameters<T>[0];
+type KeyProviderFn = (...args: never[]) => {
+  keys: string[];
+};
+type KnownKeys<T> = { [K in keyof T]: string extends K ? never : number extends K ? never : K }[keyof T];
+type ComputeSVDProps<TVariants, TModifiers> = { [K in KnownKeys<TVariants>]?: keyof TVariants[K] } & { [K in KnownKeys<TModifiers>]?: boolean } & {
+  className?: string;
+};
+type MaybeArray<T> = T | readonly T[];
+type CompoundConditions<TVariants, TModifiers> = { [K in keyof TVariants]?: MaybeArray<keyof TVariants[K]> } & { [K in keyof TModifiers]?: MaybeArray<boolean> };
+type SVDCompound<TVariants, TModifiers, TBase> = CompoundConditions<TVariants, TModifiers> & {
+  className: TBase extends Slots ? string | Partial<Record<keyof TBase, string>> : string;
+};
+interface SVDConfig<TBase extends string | Slots, TVariants extends Record<string, Record<string, string | Slots>>, TModifiers extends Record<string, ModifierValue>> {
+  base?: TBase;
+  variants?: TVariants;
+  modifiers?: TModifiers;
+  compound?: readonly SVDCompound<TVariants, TModifiers, TBase>[];
+  defaults?: {
+    variants?: { [K in keyof TVariants]?: keyof TVariants[K] };
+    modifiers?: { [K in keyof TModifiers]?: boolean };
+  };
+}
+type SVDGeneratorResult<TBase extends string | Slots, TVariants, TModifiers> = {
+  keys: string[];
+  base: TBase extends string ? string & string[] : TBase & string[];
+  variants: { [K in keyof TVariants]: TVariants[K][keyof TVariants[K]] } & string[];
+  modifiers: { [K in keyof TModifiers]: string } & string[];
+  compound: string[];
+  resolved: {
+    variants: { [K in keyof TVariants]: string };
+    modifiers: { [K in keyof TModifiers]: boolean };
+  };
+} & string[];
+//#endregion
+//#region src/utils.d.ts
+declare function splitProps<TProps extends object>(props: TProps, styleFn: KeyProviderFn): [Parameters<typeof styleFn>[0] & {
+  className?: string;
+}, Omit<TProps, keyof Parameters<typeof styleFn>[0] | "className">];
+//#endregion
+//#region src/index.d.ts
+declare function svd<TBase extends string | Slots, TVariants extends Record<string, Record<string, string | Slots>> = Record<string, never>, TModifiers extends Record<string, ModifierValue> = Record<string, never>>(config: SVDConfig<TBase, TVariants, TModifiers>): ((props: ComputeSVDProps<TVariants, TModifiers>) => SVDGeneratorResult<TBase, TVariants, TModifiers>) & {
+  config: SVDConfig<TBase, TVariants, TModifiers>;
+};
+//#endregion
+export { type SVDProps, splitProps, svd };

package/dist/index.mjs

@@ -0,0 +1,131 @@
+//#region src/utils.ts
+function splitProps(props, styleFn) {
+	const filter = new Set([...styleFn({}).keys, "className"]);
+	const matched = {}, rest = {};
+	for (const key in props) (filter.has(key) ? matched : rest)[key] = props[key];
+	return [matched, rest];
+}
+//#endregion
+//#region src/index.ts
+function processBase(base) {
+	const parts = [];
+	const keys = {};
+	if (base) if (typeof base === "string") parts.push(base);
+	else for (const key in base) {
+		keys[key] = base[key];
+		if (base[key]) parts.push(base[key]);
+	}
+	return Object.assign(parts, keys);
+}
+function processVariants(variants, resolved) {
+	const parts = [];
+	const keys = {};
+	for (const vKey in variants) {
+		const activeOption = resolved[vKey];
+		const variantGroup = variants[vKey]?.[activeOption] ?? "";
+		if (typeof variantGroup === "string") {
+			keys[vKey] = variantGroup;
+			if (variantGroup) parts.push(variantGroup);
+		} else if (variantGroup && typeof variantGroup === "object") {
+			const variantSlotsParts = [];
+			const variantSlotsKeys = {};
+			for (const slotKey in variantGroup) {
+				if (variantGroup[slotKey]) {
+					parts.push(variantGroup[slotKey]);
+					variantSlotsParts.push(variantGroup[slotKey]);
+				}
+				variantSlotsKeys[slotKey] = variantGroup[slotKey];
+			}
+			keys[vKey] = Object.assign(variantSlotsParts, variantSlotsKeys);
+		}
+	}
+	return Object.assign(parts, keys);
+}
+function processModifiers(modifiers, resolved) {
+	const parts = [];
+	const keys = {};
+	for (const mKey in modifiers) {
+		const modifierConfig = modifiers[mKey];
+		const isTrue = resolved[mKey];
+		let activeClass = "";
+		if (typeof modifierConfig === "string") activeClass = isTrue ? modifierConfig : "";
+		else if (modifierConfig && typeof modifierConfig === "object") activeClass = (isTrue ? modifierConfig.true : modifierConfig.false) ?? "";
+		keys[mKey] = activeClass;
+		if (activeClass) parts.push(activeClass);
+	}
+	return Object.assign(parts, keys);
+}
+function processCompounds(compounds, resolvedState) {
+	const parts = [];
+	if (!compounds) return parts;
+	for (const compoundConfig of compounds) {
+		let matchesAll = true;
+		const currentCompound = compoundConfig;
+		for (const key in currentCompound) {
+			if (key === "className") continue;
+			const expectedValue = currentCompound[key];
+			const actualValue = resolvedState[key];
+			if (Array.isArray(expectedValue)) {
+				if (!expectedValue.includes(actualValue)) {
+					matchesAll = false;
+					break;
+				}
+			} else if (expectedValue !== actualValue) {
+				matchesAll = false;
+				break;
+			}
+		}
+		if (matchesAll && compoundConfig.className) if (typeof compoundConfig.className === "string") parts.push(compoundConfig.className);
+		else {
+			const slotsRecord = compoundConfig.className;
+			for (const slotKey in slotsRecord) {
+				const slotClass = slotsRecord[slotKey];
+				if (slotClass) parts.push(slotClass);
+			}
+		}
+	}
+	return parts;
+}
+function svd(config) {
+	const stylesGenerator = (props) => {
+		const resolvedVariants = {};
+		for (const key in config.variants) {
+			const firstAvailableKey = Object.keys(config.variants[key] || {})[0];
+			resolvedVariants[key] = props[key] ?? config.defaults?.variants?.[key] ?? firstAvailableKey;
+		}
+		const resolvedModifiers = {};
+		for (const key in config.modifiers || {}) resolvedModifiers[key] = props[key] ?? config.defaults?.modifiers?.[key] ?? false;
+		const baseResult = processBase(config.base);
+		const variantsResult = processVariants(config.variants || {}, resolvedVariants);
+		const modifiersResult = processModifiers(config.modifiers || {}, resolvedModifiers);
+		const mergedState = {
+			...resolvedVariants,
+			...resolvedModifiers
+		};
+		const compoundResult = processCompounds(config.compound, mergedState);
+		const totalParts = [
+			...baseResult,
+			...variantsResult,
+			...modifiersResult,
+			...compoundResult
+		];
+		if (props.className) totalParts.push(props.className);
+		const variantKeys = Object.keys(config.variants ?? {});
+		const modifierKeys = Object.keys(config.modifiers ?? {});
+		return Object.assign(totalParts, {
+			keys: [...variantKeys, ...modifierKeys],
+			base: baseResult,
+			variants: variantsResult,
+			modifiers: modifiersResult,
+			compound: compoundResult,
+			resolved: {
+				variants: resolvedVariants,
+				modifiers: resolvedModifiers
+			}
+		});
+	};
+	stylesGenerator.config = config;
+	return stylesGenerator;
+}
+//#endregion
+export { splitProps, svd };

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "svd-kit",
+  "version": "1.1.0",
+  "description": "Styling variance decomposition kit supporting base styles, variants, modifiers, and compound variants.",
+  "keywords": [
+    "svd",
+    "cva",
+    "styling",
+    "variants",
+    "modifiers",
+    "design-system",
+    "typescript"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": {
+        "import": "./dist/index.d.mts",
+        "require": "./dist/index.d.cts"
+      },
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsdown",
+    "prepublishOnly": "pnpm build",
+    "test": "vitest run"
+  },
+  "author": "Eduardo Carvalho",
+  "license": "MIT",
+  "packageManager": "pnpm@10.33.0",
+  "devDependencies": {
+    "@types/node": "^25.9.1",
+    "clsx": "^2.1.1",
+    "tailwind-merge": "^3.6.0",
+    "tsdown": "^0.22.1",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.7"
+  }
+}