classname-variants 1.5.0 → 1.7.0

package/README.md

@@ -188,6 +188,49 @@ import { styled } from "classname-variants/react";
 const Button = styled("button", "bg-transparent border p-2");
 ```
 
+### Default props
+
+If your underlying element (or custom component) expects props that you want to
+provide automatically, you can use the `defaultProps` option. All defaulted
+props become optional in TypeScript – even when you later render the component
+with a polymorphic `as` prop.
+
+```tsx
+const Button = styled("button", {
+  base: "inline-flex items-center gap-2",
+  defaultProps: {
+    type: "button",
+  },
+});
+
+// `type` is optional but still overridable
+<Button />;
+<Button type="submit" />;
+
+// Works together with `as`
+<Button as="a" href="/docs" />;
+```
+
+### Forwarding props
+
+When a variant mirrors an existing prop (such as `disabled` on a button), add
+it to `forwardProps` so the resolved value is passed through to the rendered
+element or custom component.
+
+```tsx
+const Button = styled("button", {
+  variants: {
+    disabled: {
+      true: "cursor-not-allowed",
+    },
+  },
+  forwardProps: ["disabled"],
+});
+
+// Renders with both the class name and the DOM `disabled` prop applied.
+<Button disabled />;
+```
+
 ### Styling custom components
 
 You can style any custom React/Preact component as long as they accept a `className` prop (or `class` in case of Preact).
@@ -270,17 +313,17 @@ const button = variants({
 });
 ```
 
-You can then add the following line to your `settings.json`:
-
-```
-"tailwindCSS.experimental.classRegex": ["tw`(.+?)`"]
-```
+You can then set the _Tailwind CSS: Class Functions_ option to `tw`.
 
 > [!NOTE]
 > The `tw` helper function is just an alias for [`String.raw()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/raw) which has the nice side effect backslashes are not treated as [escape character in JSX](https://tailwindcss.com/docs/adding-custom-styles#handling-whitespace).
 
 In order to get type coverage even for your Tailwind classes, you can use a tool like [tailwind-ts](https://github.com/mathieutu/tailwind-ts).
 
+# For AI Assistants
+
+For comprehensive technical documentation optimized for LLMs, see [`llms.txt`](./llms.txt).
+
 # License
 
 MIT

package/biome.json

@@ -0,0 +1,49 @@
+{
+  "$schema": "./node_modules/@biomejs/biome/configuration_schema.json",
+  "vcs": {
+    "enabled": true,
+    "clientKind": "git",
+    "useIgnoreFile": true
+  },
+  "formatter": {
+    "enabled": true,
+    "indentStyle": "space",
+    "indentWidth": 2
+  },
+  "linter": {
+    "enabled": true,
+    "rules": {
+      "recommended": true,
+      "correctness": {
+        "noUnusedImports": {
+          "options": {},
+          "level": "warn",
+          "fix": "safe"
+        }
+      },
+      "complexity": {
+        "noBannedTypes": "off"
+      },
+      "style": {
+        "noNonNullAssertion": "off"
+      },
+      "suspicious": {
+        "noExplicitAny": "off"
+      }
+    }
+  },
+  "javascript": {
+    "formatter": {
+      "quoteStyle": "double"
+    }
+  },
+  "assist": {
+    "enabled": true,
+    "actions": {
+      "source": {
+        "organizeImports": "on",
+        "useSortedAttributes": "on"
+      }
+    }
+  }
+}

package/lib/example/index.js

@@ -1,8 +1,8 @@
+import { h, render } from "preact";
 import { createElement } from "react";
 import { createRoot } from "react-dom/client";
-import { render, h } from "preact";
-import { ReactApp } from "./react";
 import { PreactApp } from "./preact";
+import { ReactApp } from "./react";
 const root = createRoot(document.getElementById("react-root"));
 root.render(createElement(ReactApp));
 render(h(PreactApp, {}), document.getElementById("preact-root"));

package/lib/example/preact.js

@@ -1,11 +1,17 @@
 /** @jsx h */
-import { styled } from "../preact";
+// biome-ignore lint/correctness/noUnusedImports: Preact JSX pragma requires importing h
 import { h } from "preact";
+import { styled } from "../preact";
 function CustomComponent({ title, ...props }) {
     return h("div", { ...props }, title);
 }
 const Card = styled("div", "bg-white p-4 border-2 rounded-lg");
-const TitleCard = styled(CustomComponent, "bg-white p-4 border-2 rounded-lg");
+const TitleCard = styled(CustomComponent, {
+    base: "bg-white p-4 border-2 rounded-lg",
+    defaultProps: {
+        title: "Default Title",
+    },
+});
 const Button = styled("button", {
     base: "px-5 py-2 text-white disabled:bg-gray-400 disabled:text-gray-300",
     variants: {
@@ -24,6 +30,9 @@ const Button = styled("button", {
             true: "rounded-full",
             false: "rounded-sm",
         },
+        disabled: {
+            true: "cursor-not-allowed",
+        },
     },
     compoundVariants: [
         {
@@ -34,6 +43,10 @@ const Button = styled("button", {
     defaultVariants: {
         color: "neutral",
     },
+    defaultProps: {
+        type: "button",
+    },
+    forwardProps: ["disabled"],
 });
 export const ExpectErrors = styled("div", {
     variants: {
@@ -53,20 +66,25 @@ export const ExpectErrors = styled("div", {
         //@ts-expect-error
         outlined: true,
     },
+    forwardProps: [
+        //@ts-expect-error
+        "outlined",
+    ],
 });
 export function WithErrors() {
     return (h("div", null,
         h(Button, { foo: true, size: "medium" }, "unknown property"),
         h(Card, { foo: true }, "Unknown property"),
-        h(Button, { size: "medium", color: "foo" }, "Invalid variant"),
+        h(Button, { color: "foo", size: "medium" }, "Invalid variant"),
         h(Button, null, "Missing size")));
 }
 export function PreactApp() {
     return (h("div", { className: "flex justify-center items-center pt-8 gap-4 flex-wrap" },
-        h(Button, { size: "medium", onClick: console.log }, "Accent"),
-        h(Button, { size: "medium", rounded: true }, "Neutral + Rounded"),
-        h(Button, { size: "medium", color: "accent", outlined: true }, "Accent + Outlined"),
-        h(Button, { size: "medium", color: "accent", disabled: true }, "Disabled"),
+        h(Button, { onClick: console.log, size: "medium" }, "Neutral"),
+        h(Button, { rounded: true, size: "medium" }, "Neutral + Rounded"),
+        h(Button, { color: "accent", outlined: true, size: "medium" }, "Accent + Outlined"),
+        h(Button, { color: "accent", disabled: true, size: "medium" }, "Disabled"),
+        h(TitleCard, null),
         h(TitleCard, { title: "Hello" }),
         h(Card, null,
             h("h1", null, "Hello"),

package/lib/example/react.d.ts

@@ -1,8 +1,14 @@
 import React from "react";
-export declare const ExpectErrors: <As extends React.ElementType<any> = "div">(props: {
+export declare const StyledWithoutVariants: <As extends React.ElementType<any, keyof React.JSX.IntrinsicElements> = "div">(props: {
+    as?: As | undefined;
+} & Omit<React.ComponentProps<As>, "as"> & {} & {}) => React.ReactElement<any, string | React.JSXElementConstructor<any>> | null;
+export declare const TestBaseOnly: <As extends React.ElementType<any, keyof React.JSX.IntrinsicElements> = "div">(props: {
+    as?: As | undefined;
+} & Omit<React.ComponentProps<As>, "as"> & {} & {}) => React.ReactElement<any, string | React.JSXElementConstructor<any>> | null;
+export declare const ExpectErrors: <As extends React.ElementType<any, keyof React.JSX.IntrinsicElements> = "div">(props: {
     as?: As | undefined;
 } & Omit<React.ComponentProps<As>, "as" | "color"> & {
     color: "neutral" | "accent";
 } & {}) => React.ReactElement<any, string | React.JSXElementConstructor<any>> | null;
-export declare function WithErrors(): JSX.Element;
-export declare function ReactApp(): JSX.Element;
+export declare function WithErrors(): React.JSX.Element;
+export declare function ReactApp(): React.JSX.Element;

package/lib/example/react.js

@@ -1,10 +1,17 @@
+// biome-ignore lint/correctness/noUnusedImports: React import required for JSX runtime configuration
 import React from "react";
 import { styled } from "../react";
 function CustomComponent({ title, ...props }) {
     return React.createElement("div", { ...props }, title);
 }
 const Card = styled("div", "bg-white p-4 border-2 rounded-lg");
-const TitleCard = styled(CustomComponent, "bg-white p-4 border-2 rounded-lg");
+const _cardAsShouldBeGeneric = "a";
+const TitleCard = styled(CustomComponent, {
+    base: "bg-white p-4 border-2 rounded-lg",
+    defaultProps: {
+        title: "Default Title",
+    },
+});
 const Button = styled("button", {
     base: "px-5 py-2 text-white disabled:bg-gray-400 disabled:text-gray-300",
     variants: {
@@ -23,6 +30,9 @@ const Button = styled("button", {
             true: "rounded-full",
             false: "rounded-sm",
         },
+        disabled: {
+            true: "cursor-not-allowed",
+        },
     },
     compoundVariants: [
         {
@@ -33,6 +43,16 @@ const Button = styled("button", {
     defaultVariants: {
         color: "neutral",
     },
+    defaultProps: {
+        type: "button",
+    },
+    forwardProps: ["disabled"],
+});
+export const StyledWithoutVariants = styled("div", {
+    base: "bg-white",
+});
+export const TestBaseOnly = styled("div", {
+    base: "text-red-500 font-bold",
 });
 export const ExpectErrors = styled("div", {
     variants: {
@@ -52,21 +72,26 @@ export const ExpectErrors = styled("div", {
         //@ts-expect-error
         outlined: true,
     },
+    forwardProps: [
+        //@ts-expect-error
+        "outlined",
+    ],
 });
 export function WithErrors() {
     return (React.createElement("div", null,
         React.createElement(Button, { foo: true, size: "medium" }, "unknown property"),
         React.createElement(Card, { foo: true }, "Unknown property"),
-        React.createElement(Button, { size: "medium", color: "foo" }, "Invalid variant"),
+        React.createElement(Button, { color: "foo", size: "medium" }, "Invalid variant"),
         React.createElement(Button, null, "Missing size"),
         React.createElement(Card, { as: "b", href: "https://example.com" }, "B tags don't have a href attribute")));
 }
 export function ReactApp() {
     return (React.createElement("div", { className: "flex justify-center items-center pt-8 gap-4 flex-wrap" },
-        React.createElement(Button, { size: "medium", onClick: console.log }, "Accent"),
-        React.createElement(Button, { size: "medium", rounded: true }, "Neutral + Rounded"),
-        React.createElement(Button, { size: "medium", color: "accent", outlined: true }, "Accent + Outlined"),
-        React.createElement(Button, { size: "medium", color: "accent", disabled: true }, "Disabled"),
+        React.createElement(Button, { onClick: console.log, size: "medium" }, "Neutral"),
+        React.createElement(Button, { rounded: true, size: "medium" }, "Neutral + Rounded"),
+        React.createElement(Button, { color: "accent", outlined: true, size: "medium" }, "Accent + Outlined"),
+        React.createElement(Button, { color: "accent", disabled: true, size: "medium" }, "Disabled"),
+        React.createElement(TitleCard, null),
         React.createElement(TitleCard, { title: "Hello" }),
         React.createElement(Card, null,
             React.createElement("h1", null, "Hello"),

package/lib/index.d.ts

@@ -21,6 +21,7 @@ export interface VariantsConfig<V extends Variants = {}> {
     variants: V;
     compoundVariants?: CompoundVariant<V>[];
     defaultVariants?: Partial<OptionsOf<V>>;
+    forwardProps?: ReadonlyArray<Extract<keyof V, string>>;
 }
 /**
  * Rules for class names that are applied for certain variant combinations.

package/lib/index.js

@@ -14,12 +14,12 @@ export function variants(config) {
             var _a, _b;
             return (_b = (_a = props[name]) !== null && _a !== void 0 ? _a : defaultVariants === null || defaultVariants === void 0 ? void 0 : defaultVariants[name]) !== null && _b !== void 0 ? _b : (isBooleanVariant(name) ? false : undefined);
         };
-        for (let name in variants) {
+        for (const name in variants) {
             const selected = getSelected(name);
             if (selected !== undefined)
                 classes.push((_a = variants[name]) === null || _a === void 0 ? void 0 : _a[selected]);
         }
-        for (let { variants, className } of compoundVariants !== null && compoundVariants !== void 0 ? compoundVariants : []) {
+        for (const { variants, className } of compoundVariants !== null && compoundVariants !== void 0 ? compoundVariants : []) {
             const isSelected = (name) => getSelected(name) === variants[name];
             if (Object.keys(variants).every(isSelected)) {
                 classes.push(className);

package/lib/index.test.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/index.test.js

@@ -0,0 +1,93 @@
+import { describe, expect, it } from "vitest";
+import { classNames, tw, variants } from "./index.js";
+describe("classNames.combine", () => {
+    it("joins truthy values with spaces", () => {
+        expect(classNames.combine("foo", undefined, "bar", false, "baz")).toBe("foo bar baz");
+    });
+    it("returns empty string for falsy input", () => {
+        expect(classNames.combine(undefined, null, false, 0)).toBe("");
+    });
+});
+describe("tw helper", () => {
+    it("returns raw template strings", () => {
+        expect(tw `foo`).toBe("foo");
+        const dynamic = "bar";
+        expect(tw `foo-${dynamic}`).toBe("foo-bar");
+    });
+});
+describe("variants factory", () => {
+    const config = {
+        base: "btn",
+        variants: {
+            tone: {
+                neutral: "text-neutral",
+                accent: "text-accent",
+            },
+            size: {
+                small: "text-sm",
+                large: "text-lg",
+            },
+            disabled: {
+                true: "opacity-50",
+                false: "opacity-100",
+            },
+        },
+        defaultVariants: {
+            tone: "neutral",
+            size: "small",
+        },
+        compoundVariants: [
+            {
+                variants: { tone: "accent", size: "large" },
+                className: "text-accent-large",
+            },
+            {
+                variants: { disabled: true },
+                className: "pointer-events-none",
+            },
+        ],
+    };
+    const button = variants(config);
+    it("includes base class", () => {
+        expect(button({ tone: "neutral", size: "small" })).toContain("btn");
+    });
+    it("uses default variants when omitted", () => {
+        const result = button({});
+        expect(result).toContain("text-neutral");
+        expect(result).toContain("text-sm");
+        expect(result).not.toContain("text-lg");
+    });
+    it("applies boolean variants with false default", () => {
+        const result = button({});
+        expect(result).toContain("opacity-100");
+    });
+    it("prefers explicit props over defaults", () => {
+        const result = button({ tone: "accent", size: "large" });
+        expect(result).toContain("text-accent");
+        expect(result).toContain("text-lg");
+        expect(result).not.toContain("text-neutral");
+        expect(result).not.toContain("text-sm");
+    });
+    it("handles boolean true variants", () => {
+        const result = button({ disabled: true });
+        expect(result).toContain("opacity-50");
+        expect(result).toContain("pointer-events-none");
+    });
+    it("runs compound variants only when all predicates match", () => {
+        const accentLarge = button({ tone: "accent", size: "large" });
+        expect(accentLarge).toContain("text-accent-large");
+        const accentSmall = button({ tone: "accent", size: "small" });
+        expect(accentSmall).not.toContain("text-accent-large");
+    });
+    it("accepts boolean variants via explicit false", () => {
+        const result = button({ disabled: false });
+        expect(result).toContain("opacity-100");
+        expect(result).not.toContain("pointer-events-none");
+    });
+    it("keeps default class when variant explicitly undefined", () => {
+        const result = button({ tone: undefined, size: "large" });
+        expect(result).toContain("text-lg");
+        expect(result).toContain("text-neutral");
+        expect(result).not.toContain("text-accent");
+    });
+});

package/lib/preact.d.ts

@@ -1,6 +1,6 @@
-import type { JSX, ComponentType, ComponentProps, VNode } from "preact";
+import type { ComponentProps, ComponentType, JSX, VNode } from "preact";
 type ElementType<P = any> = keyof JSX.IntrinsicElements | ComponentType<P>;
-import { Variants, VariantsConfig, VariantOptions, Simplify } from "./index.js";
+import { type Simplify, type VariantOptions, type Variants, type VariantsConfig } from "./index.js";
 /**
  * Utility type to infer the first argument of a variantProps function.
  */
@@ -12,15 +12,40 @@ type VariantProps<C extends VariantsConfig<V>, V extends Variants = C["variants"
     class?: string;
     className?: string;
 };
+type ForwardedVariantKeys<C> = C extends {
+    forwardProps?: ReadonlyArray<infer K>;
+    variants: infer V;
+} ? Extract<K, keyof V> : never;
+type VariantPropKeys<C> = C extends {
+    variants: infer V;
+} ? keyof V : never;
+type ForwardedVariantProps<C extends VariantsConfig<any>> = Pick<VariantOptions<C>, ForwardedVariantKeys<C>>;
 export declare function variantProps<C extends VariantsConfig<V>, V extends Variants = C["variants"]>(config: Simplify<C>): <P extends VariantProps<C, C["variants"]>>(props: P) => {
     class: string;
-} & Omit<P, keyof C["variants"]>;
-type VariantsOf<T, V> = T extends VariantsConfig ? V : {};
+} & Omit<P, VariantPropKeys<C>> & ForwardedVariantProps<C>;
+type VariantsOf<T> = T extends {
+    variants: infer TV;
+} ? TV extends Variants ? TV : {} : {};
 type AsProps<T extends ElementType = ElementType> = {
     as?: T;
 };
+type CleanDefaults<Defaults> = Exclude<Defaults, undefined>;
+type DefaultedKeys<Props, Defaults> = Extract<keyof CleanDefaults<Defaults>, keyof Props>;
+type WithDefaultProps<Props, Defaults> = [CleanDefaults<Defaults>] extends [
+    never
+] ? Props : Omit<Props, DefaultedKeys<Props, Defaults>> & Partial<Pick<Props, DefaultedKeys<Props, Defaults>>>;
 type PolymorphicComponentProps<V, T extends ElementType> = AsProps<T> & Omit<ComponentProps<T>, "as" | keyof V> & V;
-export declare function styled<T extends ElementType, C extends VariantsConfig<V>, V extends Variants = VariantsOf<C, C["variants"]>>(type: T, config: string | Simplify<C>): <As extends ElementType<any> = T>(props: PolymorphicComponentProps<VariantOptions<C, C["variants"]>, As>) => VNode | null;
+export declare function styled<T extends ElementType, C extends VariantsConfig<V>, V extends Variants = VariantsOf<C>, Defaults extends Partial<ComponentProps<T>> | undefined = undefined>(type: T, config: string | {
+    base: string;
+    defaultProps?: Defaults;
+} | (Simplify<C> & {
+    defaultProps?: Defaults;
+})): <As extends ElementType = T>(props: WithDefaultProps<PolymorphicComponentProps<typeof config extends string ? {} : typeof config extends {
+    base: string;
+    variants?: undefined;
+    compoundVariants?: undefined;
+    defaultVariants?: undefined;
+} ? {} : VariantOptions<C>, As>, Defaults>) => VNode | null;
 /**
  * No-op function to mark template literals as tailwind strings.
  */

package/lib/preact.js

@@ -1,16 +1,31 @@
 import { h } from "preact";
 import { forwardRef } from "preact/compat";
-import { variants, classNames, } from "./index.js";
+import { classNames, variants, } from "./index.js";
 export function variantProps(config) {
     const variantClassName = variants(config);
     return (props) => {
         const result = {};
         // Pass-through all unrelated props
-        for (let prop in props) {
+        for (const prop in props) {
             if (config.variants && !(prop in config.variants)) {
                 result[prop] = props[prop];
             }
         }
+        if (config.forwardProps) {
+            for (const name of config.forwardProps) {
+                if (!config.variants || !(name in config.variants))
+                    continue;
+                if (Object.hasOwn(props, name)) {
+                    result[name] = props[name];
+                    continue;
+                }
+                if (config.defaultVariants &&
+                    Object.hasOwn(config.defaultVariants, name)) {
+                    result[name] =
+                        config.defaultVariants[name];
+                }
+            }
+        }
         // Add the optionally passed class/className prop for chaining
         result.class = classNames.combine(variantClassName(props), props.class, props.className);
         return result;
@@ -19,9 +34,28 @@ export function variantProps(config) {
 export function styled(type, config) {
     const styledProps = typeof config === "string"
         ? variantProps({ base: config, variants: {} })
-        : variantProps(config);
+        : "variants" in config
+            ? variantProps(config)
+            : variantProps({
+                base: config
+                    .base,
+                variants: {},
+            });
+    const defaultProps = typeof config === "string" ? undefined : config.defaultProps;
+    const toRecord = (value) => value && typeof value === "object"
+        ? value
+        : {};
+    const readClass = (value) => typeof value === "string" ? value : undefined;
     const Component = forwardRef(({ as, ...props }, ref) => {
-        return h(as !== null && as !== void 0 ? as : type, { ...styledProps(props), ref });
+        const defaultsRecord = toRecord(defaultProps);
+        const propsRecord = props;
+        const merged = {
+            ...defaultsRecord,
+            ...propsRecord,
+        };
+        merged.class = classNames.combine(readClass(defaultsRecord.class), readClass(propsRecord.class));
+        merged.className = classNames.combine(readClass(defaultsRecord.className), readClass(propsRecord.className));
+        return h(as !== null && as !== void 0 ? as : type, { ...styledProps(merged), ref });
     });
     return Component;
 }

package/lib/preact.test.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/preact.test.js

@@ -0,0 +1,52 @@
+import { describe, expect, it } from "vitest";
+import { variantProps } from "./preact.js";
+describe("preact adapter forwardProps", () => {
+    it("forwards explicit variant values", () => {
+        const config = {
+            base: "btn",
+            variants: {
+                disabled: {
+                    true: "opacity-50",
+                },
+                size: {
+                    small: "text-sm",
+                    large: "text-lg",
+                },
+            },
+            defaultVariants: {
+                size: "small",
+            },
+            forwardProps: ["disabled"],
+        };
+        const mapProps = variantProps(config);
+        const result = mapProps({
+            disabled: true,
+            size: "large",
+            class: "custom",
+        });
+        expect(result.disabled).toBe(true);
+        expect(result.class).toContain("btn");
+        expect(result.class).toContain("opacity-50");
+        expect(result.class).toContain("text-lg");
+        expect(result.class).toContain("custom");
+        expect("size" in result).toBe(false);
+    });
+    it("uses default variant values when forwarding", () => {
+        const config = {
+            base: "btn",
+            variants: {
+                disabled: {
+                    true: "opacity-50",
+                },
+            },
+            defaultVariants: {
+                disabled: true,
+            },
+            forwardProps: ["disabled"],
+        };
+        const mapProps = variantProps(config);
+        const result = mapProps({});
+        expect(result.disabled).toBe(true);
+        expect(result.class).toContain("opacity-50");
+    });
+});

package/lib/react.d.ts

@@ -1,5 +1,5 @@
-import { ComponentProps, ElementType, ReactElement } from "react";
-import { Variants, VariantsConfig, VariantOptions, Simplify } from "./index.js";
+import { type ComponentProps, type ElementType, type ReactElement } from "react";
+import { type Simplify, type VariantOptions, type Variants, type VariantsConfig } from "./index.js";
 /**
  * Utility type to infer the first argument of a variantProps function.
  */
@@ -10,15 +10,40 @@ export type VariantPropsOf<T> = T extends (props: infer P) => any ? P : never;
 type VariantProps<C extends VariantsConfig<V>, V extends Variants = C["variants"]> = VariantOptions<C> & {
     className?: string;
 };
+type ForwardedVariantKeys<C> = C extends {
+    forwardProps?: ReadonlyArray<infer K>;
+    variants: infer V;
+} ? Extract<K, keyof V> : never;
+type VariantPropKeys<C> = C extends {
+    variants: infer V;
+} ? keyof V : never;
+type ForwardedVariantProps<C extends VariantsConfig<any>> = Pick<VariantOptions<C>, ForwardedVariantKeys<C>>;
 export declare function variantProps<C extends VariantsConfig<V>, V extends Variants = C["variants"]>(config: Simplify<C>): <P extends VariantProps<C, C["variants"]>>(props: P) => {
     className: string;
-} & Omit<P, keyof C["variants"]>;
-type VariantsOf<T, V> = T extends VariantsConfig ? V : {};
+} & Omit<P, VariantPropKeys<C>> & ForwardedVariantProps<C>;
+type VariantsOf<T> = T extends {
+    variants: infer TV;
+} ? TV extends Variants ? TV : {} : {};
 type AsProps<T extends ElementType = ElementType> = {
     as?: T;
 };
+type CleanDefaults<Defaults> = Exclude<Defaults, undefined>;
+type DefaultedKeys<Props, Defaults> = Extract<keyof CleanDefaults<Defaults>, keyof Props>;
+type WithDefaultProps<Props, Defaults> = [CleanDefaults<Defaults>] extends [
+    never
+] ? Props : Omit<Props, DefaultedKeys<Props, Defaults>> & Partial<Pick<Props, DefaultedKeys<Props, Defaults>>>;
 type PolymorphicComponentProps<V, T extends ElementType> = AsProps<T> & Omit<ComponentProps<T>, "as" | keyof V> & V;
-export declare function styled<T extends ElementType, C extends VariantsConfig<V>, V extends Variants = VariantsOf<C, C["variants"]>>(type: T, config: string | Simplify<C>): <As extends ElementType<any> = T>(props: PolymorphicComponentProps<VariantOptions<C, C["variants"]>, As>) => ReactElement | null;
+export declare function styled<T extends ElementType, C extends VariantsConfig<V>, V extends Variants = VariantsOf<C>, Defaults extends Partial<ComponentProps<T>> | undefined = undefined>(type: T, config: string | {
+    base: string;
+    defaultProps?: Defaults;
+} | (Simplify<C> & {
+    defaultProps?: Defaults;
+})): <As extends ElementType = T>(props: WithDefaultProps<PolymorphicComponentProps<typeof config extends string ? {} : typeof config extends {
+    base: string;
+    variants?: undefined;
+    compoundVariants?: undefined;
+    defaultVariants?: undefined;
+} ? {} : VariantOptions<C>, As>, Defaults>) => ReactElement | null;
 /**
  * No-op function to mark template literals as tailwind strings.
  */

package/lib/react.js

@@ -1,15 +1,30 @@
 import { createElement, forwardRef, } from "react";
-import { variants, classNames, } from "./index.js";
+import { classNames, variants, } from "./index.js";
 export function variantProps(config) {
     const variantClassName = variants(config);
     return (props) => {
         const result = {};
         // Pass-through all unrelated props
-        for (let prop in props) {
+        for (const prop in props) {
             if (config.variants && !(prop in config.variants)) {
                 result[prop] = props[prop];
             }
         }
+        if (config.forwardProps) {
+            for (const name of config.forwardProps) {
+                if (!config.variants || !(name in config.variants))
+                    continue;
+                if (Object.hasOwn(props, name)) {
+                    result[name] = props[name];
+                    continue;
+                }
+                if (config.defaultVariants &&
+                    Object.hasOwn(config.defaultVariants, name)) {
+                    result[name] =
+                        config.defaultVariants[name];
+                }
+            }
+        }
         // Add the optionally passed className prop for chaining
         result.className = classNames.combine(variantClassName(props), props.className);
         return result;
@@ -18,9 +33,27 @@ export function variantProps(config) {
 export function styled(type, config) {
     const styledProps = typeof config === "string"
         ? variantProps({ base: config, variants: {} })
-        : variantProps(config);
+        : "variants" in config
+            ? variantProps(config)
+            : variantProps({
+                base: config
+                    .base,
+                variants: {},
+            });
+    const defaultProps = typeof config === "string" ? undefined : config.defaultProps;
+    const toRecord = (value) => value && typeof value === "object"
+        ? value
+        : {};
+    const readClassName = (value) => typeof value === "string" ? value : undefined;
     const Component = forwardRef(({ as, ...props }, ref) => {
-        return createElement(as !== null && as !== void 0 ? as : type, { ...styledProps(props), ref });
+        const defaultsRecord = toRecord(defaultProps);
+        const propsRecord = props;
+        const merged = {
+            ...defaultsRecord,
+            ...propsRecord,
+        };
+        merged.className = classNames.combine(readClassName(defaultsRecord.className), readClassName(propsRecord.className));
+        return createElement(as !== null && as !== void 0 ? as : type, { ...styledProps(merged), ref });
     });
     return Component;
 }

package/lib/react.test.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/react.test.js

@@ -0,0 +1,78 @@
+import * as React from "react";
+import { renderToStaticMarkup } from "react-dom/server";
+import { describe, expect, it } from "vitest";
+import { styled, variantProps } from "./react.js";
+describe("react adapter forwardProps", () => {
+    it("forwards explicit variant values", () => {
+        const config = {
+            base: "btn",
+            variants: {
+                disabled: {
+                    true: "opacity-50",
+                },
+                tone: {
+                    neutral: "text-slate-700",
+                    accent: "text-teal-600",
+                },
+            },
+            defaultVariants: {
+                tone: "neutral",
+            },
+            forwardProps: ["disabled"],
+        };
+        const mapProps = variantProps(config);
+        const result = mapProps({
+            disabled: true,
+            tone: "accent",
+            className: "custom",
+        });
+        expect(result.disabled).toBe(true);
+        expect(result.className).toContain("btn");
+        expect(result.className).toContain("opacity-50");
+        expect(result.className).toContain("text-teal-600");
+        expect(result.className).toContain("custom");
+        expect("tone" in result).toBe(false);
+    });
+    it("uses default variant values when forwarding", () => {
+        const config = {
+            base: "btn",
+            variants: {
+                disabled: {
+                    true: "opacity-50",
+                },
+            },
+            defaultVariants: {
+                disabled: true,
+            },
+            forwardProps: ["disabled"],
+        };
+        const mapProps = variantProps(config);
+        const result = mapProps({});
+        expect(result.disabled).toBe(true);
+        expect(result.className).toContain("opacity-50");
+    });
+    it("renders forwarded props through styled components", () => {
+        const buttonConfig = {
+            base: "btn",
+            variants: {
+                disabled: {
+                    true: "opacity-50",
+                },
+            },
+            forwardProps: ["disabled"],
+        };
+        const Button = styled("button", buttonConfig);
+        const markup = renderToStaticMarkup(React.createElement(Button, {
+            className: "custom",
+            disabled: true,
+        }));
+        const host = document.createElement("div");
+        host.innerHTML = markup;
+        const button = host.querySelector("button");
+        expect(button).not.toBeNull();
+        expect(button.hasAttribute("disabled")).toBe(true);
+        expect(button.className).toContain("btn");
+        expect(button.className).toContain("opacity-50");
+        expect(button.className).toContain("custom");
+    });
+});

package/llms.txt

@@ -0,0 +1,203 @@
+# classname-variants
+
+A TypeScript library for creating type-safe variant-based className generators for React, Preact, and vanilla DOM.
+
+## Project Overview
+
+This library provides a variant API for generating class names based on component props. It's designed to work with CSS frameworks like Tailwind CSS but supports any class naming system. The core concept is defining variants (different states/styles) and having the library generate the appropriate class names based on provided props.
+
+## Architecture
+
+### Core Module (src/index.ts)
+- `variants()` - Core function that creates a className generator based on variant configuration
+- `VariantsConfig` - TypeScript interface defining the structure of variant configurations
+- `classNames.combine` - Default strategy for combining class names (can be overridden with tools like tailwind-merge)
+- `tw` - Tagged template literal helper for Tailwind CSS IntelliSense
+
+### Framework Integrations
+- `src/react.ts` - React-specific bindings with `styled()` and `variantProps()` functions, including runtime merging and type inference for `defaultProps`
+- `src/preact.ts` - Preact-specific bindings (similar to React but uses Preact's JSX) with equivalent `defaultProps` support
+
+### Key Features
+- Type-safe variant definitions with full TypeScript inference
+- Support for required and optional variants
+- Boolean variants (true/false)
+- Default variants
+- Compound variants (combinations of multiple variant states)
+- Forwarding variant values via `forwardProps`
+- Polymorphic components with "as" prop
+- Optional `defaultProps` with strong typing (defaulted props become optional while respecting polymorphic `as`)
+- Custom class name combination strategies
+
+## File Structure
+
+```
+src/
+├── index.ts          # Core variant logic and types
+├── react.ts          # React bindings (styled, variantProps)
+├── preact.ts         # Preact bindings (similar to React)
+└── example/          # Example implementations
+    ├── index.ts      # Vanilla example
+    ├── react.tsx     # React example
+    └── preact.tsx    # Preact example
+```
+
+## Package Structure
+
+- ESM modules only
+- Multiple entry points: main, react, preact
+- Fully typed with TypeScript declarations
+
+## Key Concepts
+
+### Variant Configuration
+```ts
+{
+  base?: string,                    // Always applied classes
+  variants: {                       // Variant definitions
+    [variantName]: {
+      [optionName]: "class-names"
+    }
+  },
+  defaultVariants?: {...},          // Default values
+  defaultProps?: {...},             // Defaulted non-variant props (e.g. { type: "button" })
+  compoundVariants?: [...]          // Conditional class combinations
+  forwardProps?: ["disabled", ...]  // Variant keys to pass through as real props
+}
+```
+
+### TypeScript Magic
+The library uses advanced TypeScript features to:
+- Infer variant prop types from configuration
+- Make variants required unless they have defaults or are boolean
+- Convert "true"/"false" keys to boolean props
+- Infer optionality for props supplied via `defaultProps` while preserving `as` polymorphism
+- Provide full autocomplete and type checking
+- Preserve variant prop ergonomics when using `forwardProps`; forwarded keys remain strongly typed and emitted alongside the generated className
+
+## Usage Examples
+
+### NPM Installation & Imports
+```bash
+npm install classname-variants
+```
+
+```ts
+// Vanilla/core
+import { variants, tw } from "classname-variants"
+
+// React
+import { styled, tw } from "classname-variants/react"
+
+// Preact  
+import { styled, tw } from "classname-variants/preact"
+
+// Low-level API (rarely used directly)
+import { variantProps } from "classname-variants/react"
+import { variantProps } from "classname-variants/preact"
+```
+
+### Styled Components Without Variants
+Simple string-based styling for components that don't need variants:
+
+```tsx
+const Card = styled("div", "bg-white p-4 border-2 rounded-lg");
+const CustomCard = styled(CustomComponent, "bg-white p-4 border-2 rounded-lg");
+```
+
+### Default Props in Styled Components
+Provide defaults for non-variant props while keeping TypeScript happy:
+
+```tsx
+const Button = styled("button", {
+  base: "inline-flex items-center gap-2",
+  defaultProps: {
+    type: "button",
+  },
+});
+
+<Button />;             // `type` inferred as optional
+<Button type="submit" />; // Still overridable
+<Button as="a" href="/docs" />; // Works with polymorphic `as`
+```
+
+### Forwarding Variant Values
+Mirror a variant onto the rendered element to toggle native behaviour:
+
+```tsx
+const Button = styled("button", {
+  base: "inline-flex items-center gap-2",
+  variants: {
+    disabled: {
+      true: "opacity-50",
+    },
+  },
+  forwardProps: ["disabled"],
+});
+
+// Applies the class names *and* the DOM `disabled` prop
+<Button disabled />;
+```
+
+### Polymorphic Components with "as" Prop
+Change the underlying element/component while keeping the same styles:
+
+```tsx
+const Button = styled("button", { variants: {...} });
+
+// Usage
+<Button>I'm a button</Button>
+<Button as="a" href="/">I'm a link!</Button>
+<Button as={Link} to="/">I'm a router Link</Button>
+```
+
+### Tailwind CSS Integration
+
+#### Using tailwind-merge for Conflict Resolution
+```ts
+import { classNames } from "classname-variants";
+import { twMerge } from "tailwind-merge";
+
+// Override default combination strategy
+classNames.combine = twMerge;
+```
+
+#### IDE Support with Tagged Templates
+```ts
+import { variants, tw } from "classname-variants";
+
+const button = variants({
+  base: tw`px-5 py-2 text-white`,
+  variants: {
+    color: {
+      neutral: tw`bg-slate-500 hover:bg-slate-400`,
+      accent: tw`bg-teal-500 hover:bg-teal-400`,
+    },
+  },
+});
+```
+
+Add to VS Code settings.json:
+```json
+"tailwindCSS.experimental.classRegex": ["tw`(.+?)`"]
+```
+
+## Advantages vs Alternatives
+
+### vs clsx/classnames
+- **Type Safety**: Full TypeScript inference for variant props
+- **Variant System**: Built-in support for component variants vs manual conditional logic
+- **Default Values**: Automatic handling of default variants
+- **Compound Variants**: Built-in support for variant combinations
+
+### vs class-variance-authority (cva)
+- **Zero Dependencies**: No external dependencies vs cva's clsx dependency
+- **Framework Integration**: Built-in React/Preact components with `styled()` API
+- **Polymorphic Support**: Native "as" prop support for component flexibility
+- **TypeScript Focus**: Designed TypeScript-first with advanced type inference
+
+## Dependencies
+
+- Zero runtime dependencies
+- Development dependencies: React, Preact, TypeScript
+- Designed to work with any CSS framework (Tailwind, CSS modules, etc.)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "classname-variants",
-  "version": "1.5.0",
+  "version": "1.7.0",
   "description": "Variant API for plain class names",
   "author": "Felix Gnass <fgnass@gmail.com>",
   "license": "MIT",
@@ -37,8 +37,11 @@
   },
   "scripts": {
     "build": "tsc",
+    "lint": "biome check .",
+    "lint:fix": "biome check --write --unsafe .",
     "start": "npx vite",
-    "prepublishOnly": "npm run build"
+    "test": "vitest",
+    "prepublishOnly": "npm run build && npm test"
   },
   "keywords": [
     "tailwind",
@@ -49,11 +52,14 @@
     "preact"
   ],
   "devDependencies": {
+    "@biomejs/biome": "^2.2.6",
     "@types/react": "^18.0.26",
     "@types/react-dom": "^18.0.9",
+    "happy-dom": "^20.0.5",
     "preact": "^10.20.2",
     "react": "^18.2.0",
     "react-dom": "^18.2.0",
-    "typescript": "^4.9.4"
+    "typescript": "^4.9.4",
+    "vitest": "^3.2.4"
   }
 }

package/vitest.config.ts

@@ -0,0 +1,9 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    environment: "happy-dom",
+    globals: true,
+    include: ["src/**/*.{test,spec}.{ts,tsx}"],
+  },
+});