@ntatoud/styra 0.1.0

package/README.md

@@ -0,0 +1,57 @@
+# styra
+
+Type-safe class variance builder — a maintained, boosted CVA replacement.
+
+## Usage
+
+```ts
+import { styra } from "styra";
+
+const button = styra("btn")
+  .variants({
+    size: { sm: "text-sm", md: "text-md", lg: "text-lg" },
+    color: { red: "bg-red", blue: "bg-blue" },
+  })
+  .defaults({ size: "md" })
+  .compound([{ size: "sm", color: "red", class: "ring-red" }]);
+
+button({ color: "red" }); // 'btn text-md bg-red'
+button({ size: "sm", color: "red" }); // 'btn text-sm bg-red ring-red'
+```
+
+### With a custom merge function (e.g. `tailwind-merge`)
+
+```ts
+import { createStyra } from "styra";
+import { twMerge } from "tailwind-merge";
+
+export const { styra } = createStyra({ merge: twMerge });
+```
+
+### Negation in compound rules
+
+```ts
+const btn = styra("btn")
+  .variants({ size: { sm: "text-sm", lg: "text-lg" }, disabled: { yes: "opacity-50", no: "" } })
+  .compound([{ disabled: { not: "yes" }, class: "hover:opacity-80" }]);
+```
+
+## Development
+
+- Install dependencies:
+
+```bash
+vp install
+```
+
+- Run the unit tests:
+
+```bash
+vp test
+```
+
+- Build the library:
+
+```bash
+vp pack
+```

package/dist/index.d.mts

@@ -0,0 +1,82 @@
+//#region src/types.d.ts
+type MergeFn = (...classes: string[]) => string;
+/**
+ * A map of variant keys to their possible values and classes.
+ * Values can be a `Record<string, string>` (explicit map) or a plain `string`
+ * (boolean shorthand — applied when the prop is `true`, skipped when `false`/`undefined`).
+ */
+type VariantMap = Record<string, Record<string, string> | string>;
+/** Resolve the call-site prop type for a single variant value definition. */
+type PropTypeOf<V> = V extends string ? boolean : keyof V;
+/** Partial defaults for a given variant map. */
+type DefaultsOf<V extends VariantMap> = Partial<{ [K in keyof V]: PropTypeOf<V[K]> }>;
+/** A single negation condition. */
+type Not<T> = {
+  not: T;
+};
+/** Per-key condition in a compound rule: exact value or negation. */
+type CompoundCondition<V extends VariantMap> = { [K in keyof V]?: PropTypeOf<V[K]> | Not<PropTypeOf<V[K]>> };
+/** A compound variant rule: conditions + the class to apply when they match. */
+type CompoundRule<V extends VariantMap> = CompoundCondition<V> & {
+  class: string;
+};
+/**
+ * Infer call-site props from a variant map and its defaults.
+ * - Variants with a default → optional
+ * - Variants without a default → required
+ */
+type InferProps<V extends VariantMap, D extends DefaultsOf<V>> = { [K in keyof V as K extends keyof D ? never : K]: PropTypeOf<V[K]> } & { [K in keyof V as K extends keyof D ? K : never]?: PropTypeOf<V[K]> } & {
+  class?: string;
+  className?: string | ((...args: never[]) => string | undefined);
+};
+/** A callable builder that also exposes `.variants()`, `.defaults()`, `.compound()`. */
+interface StyraBuilder<V extends VariantMap, D extends DefaultsOf<V>> {
+  (props: keyof V extends never ? {
+    class?: string;
+    className?: string | ((...args: never[]) => string | undefined);
+  } : InferProps<V, D>): string;
+  /**
+   * Define variant keys and their class mappings.
+   * Can only be called once — throws at runtime if called again.
+   */
+  variants<NV extends VariantMap>(v: NV): StyraBuilder<NV, Record<never, never>>;
+  /** Set default values for variants, making them optional at call-site. */
+  defaults<ND extends DefaultsOf<V>>(d: ND): StyraBuilder<V, ND>;
+  /** Add compound variant rules applied when multiple variant conditions are met. */
+  compound(rules: Array<CompoundRule<V>>): StyraBuilder<V, D>;
+}
+/** Custom class merge function, e.g. `twMerge` from tailwind-merge. */
+interface StyraOptions {
+  merge?: MergeFn;
+}
+/**
+ * Extract the variant props from a `StyraBuilder`, stripping `class` and `className`.
+ *
+ * @example
+ * ```ts
+ * const buttonVariants = styra("btn").variants({ size: { sm: "...", md: "..." } });
+ * type ButtonVariantProps = VariantProps<typeof buttonVariants>;
+ * // → { size: "sm" | "md" }
+ * ```
+ */
+type VariantProps<T extends (...args: never[]) => string> = Omit<Parameters<T>[0], "class" | "className">;
+//#endregion
+//#region src/index.d.ts
+/**
+ * Create a configured `styra` factory.
+ *
+ * @example
+ * ```ts
+ * import { createStyra } from 'styra'
+ * import { twMerge } from 'tailwind-merge'
+ *
+ * export const { styra } = createStyra({ merge: twMerge })
+ * ```
+ */
+declare function createStyra(options?: StyraOptions): {
+  styra: (base: string) => StyraBuilder<Record<never, never>, Record<never, never>>;
+};
+/** Default `styra` instance with no custom merge function. */
+declare const styra: (base: string) => StyraBuilder<Record<never, never>, Record<never, never>>;
+//#endregion
+export { type CompoundRule, type InferProps, type StyraBuilder, type StyraOptions, type VariantMap, type VariantProps, createStyra, styra };

package/dist/index.mjs

@@ -0,0 +1,133 @@
+//#region src/index.ts
+function matchesCompound(rule, resolved) {
+	for (const key in rule) {
+		if (key === "class") continue;
+		const rawCondition = rule[key];
+		const value = resolved[key];
+		if (rawCondition !== null && typeof rawCondition === "object" && "not" in rawCondition) {
+			if (value === (toKey(rawCondition.not) ?? rawCondition.not)) return false;
+		} else if (value !== (toKey(rawCondition) ?? rawCondition)) return false;
+	}
+	return true;
+}
+/** Resolve a className prop that may be a string or a render-prop function. */
+function resolveClassName(v) {
+	if (typeof v === "string") return v || void 0;
+	if (typeof v === "function") return v() || void 0;
+}
+/** Coerce a prop value to its string key for map lookup (handles booleans from boolean shorthand). */
+function toKey(v) {
+	if (v === void 0 || v === null) return void 0;
+	if (v === true) return "true";
+	if (v === false) return "false";
+	return v;
+}
+function makeBuilder(base, variantMap, defaultMap, compoundRules, customMerge, variantsLocked) {
+	const defaultMapRaw = defaultMap;
+	const resolvers = Object.keys(variantMap).map((key) => {
+		const raw = variantMap[key];
+		const map = typeof raw === "string" ? {
+			true: raw,
+			false: ""
+		} : raw;
+		const def = defaultMapRaw[key];
+		return {
+			key,
+			map,
+			def: def === true ? "true" : def === false ? "false" : def
+		};
+	});
+	const hasCompound = compoundRules.length > 0;
+	function call(props) {
+		if (customMerge) {
+			const classes = [base];
+			if (hasCompound) {
+				const resolved = {};
+				for (let i = 0; i < resolvers.length; i++) {
+					const { key, map, def } = resolvers[i];
+					const value = toKey(props[key]) ?? def;
+					resolved[key] = value;
+					if (value !== void 0) {
+						const cls = map[value];
+						if (cls) classes.push(cls);
+					}
+				}
+				for (let i = 0; i < compoundRules.length; i++) if (matchesCompound(compoundRules[i], resolved)) classes.push(compoundRules[i].class);
+			} else for (let i = 0; i < resolvers.length; i++) {
+				const { key, map, def } = resolvers[i];
+				const value = toKey(props[key]) ?? def;
+				if (value !== void 0) {
+					const cls = map[value];
+					if (cls) classes.push(cls);
+				}
+			}
+			const extra = resolveClassName(props["class"]);
+			if (extra) classes.push(extra);
+			const extraCn = resolveClassName(props["className"]);
+			if (extraCn) classes.push(extraCn);
+			return customMerge(...classes);
+		}
+		let result = base;
+		if (hasCompound) {
+			const resolved = {};
+			for (let i = 0; i < resolvers.length; i++) {
+				const { key, map, def } = resolvers[i];
+				const value = toKey(props[key]) ?? def;
+				resolved[key] = value;
+				if (value !== void 0) {
+					const cls = map[value];
+					if (cls) result = result ? result + " " + cls : cls;
+				}
+			}
+			for (let i = 0; i < compoundRules.length; i++) if (matchesCompound(compoundRules[i], resolved)) {
+				const cls = compoundRules[i].class;
+				result = result ? result + " " + cls : cls;
+			}
+		} else for (let i = 0; i < resolvers.length; i++) {
+			const { key, map, def } = resolvers[i];
+			const value = toKey(props[key]) ?? def;
+			if (value !== void 0) {
+				const cls = map[value];
+				if (cls) result = result ? result + " " + cls : cls;
+			}
+		}
+		const extra = resolveClassName(props["class"]);
+		if (extra) result = result ? result + " " + extra : extra;
+		const extraCn = resolveClassName(props["className"]);
+		if (extraCn) result = result ? result + " " + extraCn : extraCn;
+		return result;
+	}
+	call.variants = function(v) {
+		if (variantsLocked) throw new Error("styra: .variants() can only be called once per builder");
+		return makeBuilder(base, v, {}, [], customMerge, true);
+	};
+	call.defaults = function(d) {
+		return makeBuilder(base, variantMap, d, compoundRules, customMerge, variantsLocked);
+	};
+	call.compound = function(rules) {
+		return makeBuilder(base, variantMap, defaultMap, rules, customMerge, variantsLocked);
+	};
+	return call;
+}
+/**
+* Create a configured `styra` factory.
+*
+* @example
+* ```ts
+* import { createStyra } from 'styra'
+* import { twMerge } from 'tailwind-merge'
+*
+* export const { styra } = createStyra({ merge: twMerge })
+* ```
+*/
+function createStyra(options) {
+	const customMerge = options?.merge;
+	function styra(base) {
+		return makeBuilder(base, {}, {}, [], customMerge, false);
+	}
+	return { styra };
+}
+/** Default `styra` instance with no custom merge function. */
+const { styra } = createStyra();
+//#endregion
+export { createStyra, styra };

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@ntatoud/styra",
+  "version": "0.1.0",
+  "description": "Type-safe class variance builder — a maintained, boosted CVA replacement.",
+  "keywords": [
+    "class-variance-authority",
+    "cva",
+    "tailwind",
+    "typescript",
+    "variants"
+  ],
+  "homepage": "https://github.com/ntatoud/styra#readme",
+  "bugs": {
+    "url": "https://github.com/ntatoud/styra/issues"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ntatoud/styra.git"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "vp pack",
+    "dev": "vp pack --watch",
+    "test": "vp test",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@arethetypeswrong/core": "catalog:",
+    "@types/node": "^25.5.0",
+    "typescript": "^6.0.2",
+    "vite-plus": "catalog:",
+    "vitest": "catalog:"
+  }
+}