classname-variants 1.4.1 → 1.6.0

package/.claude/settings.local.json

@@ -0,0 +1,12 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(npm run build:*)",
+      "Bash(npx tsc:*)",
+      "Bash(rm:*)",
+      "Bash(node:*)"
+    ],
+    "deny": [],
+    "ask": []
+  }
+}

package/README.md

@@ -7,7 +7,8 @@ Library to create type-safe components that render their class name based on a s
 - ⚛️ Supports React, Preact and vanilla DOM
 - 🛡️ Fully type-safe and excellent auto completion support
 - ✅ Supports both optional and required variants
-- 🪶 Light-weight without any dependencies
+- 🔗 Supports custom strategies like [tailwind-merge](https://www.npmjs.com/package/tailwind-merge)
+- 🪶 [Light-weight](https://bundlephobia.com/package/classname-variants) without any dependencies
 
 ![npm bundle size](https://img.shields.io/bundlephobia/minzip/classname-variants)
 
@@ -232,6 +233,23 @@ The component can then be rendered as button or as anchor or even as custom comp
 </>
 ```
 
+### Using a custom strategy to combine class names
+
+The built-in strategy for combining multiple class names into one string is simple and straightforward:
+
+```ts
+(classes) => classes.filter(Boolean).join(" ");
+```
+
+If you [want](https://github.com/dcastil/tailwind-merge/blob/main/docs/when-and-how-to-use-it.md), you can use a custom strategy like tailwind-merge instead:
+
+```ts
+import { classNames } from "classname-variants";
+import { twMerge } from "tailwind-merge";
+
+classNames.combine = twMerge;
+```
+
 # Tailwind IntelliSense
 
 In order to get auto-completion for the CSS classes themselves, you can use the [Tailwind CSS IntelliSense](https://github.com/tailwindlabs/tailwindcss-intellisense) plugin for VS Code. In order to make it recognize the strings inside your variants-config, you have to somehow mark them and configure the plugin accordingly.
@@ -263,6 +281,10 @@ You can then add the following line to your `settings.json`:
 
 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/lib/example/preact.js

@@ -63,7 +63,7 @@ export function WithErrors() {
 }
 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", onClick: console.log }, "Neutral"),
         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"),

package/lib/example/react.d.ts

@@ -1,4 +1,10 @@
 import React from "react";
+export declare const StyledWithoutVariants: <As extends React.ElementType<any> = "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> = "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> = "div">(props: {
     as?: As | undefined;
 } & Omit<React.ComponentProps<As>, "as" | "color"> & {

package/lib/example/react.js

@@ -34,6 +34,12 @@ const Button = styled("button", {
         color: "neutral",
     },
 });
+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: {
         color: {
@@ -63,7 +69,7 @@ export function WithErrors() {
 }
 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", onClick: console.log }, "Neutral"),
         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"),

package/lib/index.d.ts

@@ -101,6 +101,9 @@ export type VariantOptions<C extends VariantsConfig<V>, V extends Variants = C["
 export type Simplify<T> = {
     [K in keyof T]: T[K];
 };
+export declare const classNames: {
+    combine: (...classes: Array<string | undefined | null | false | 0>) => string;
+};
 export declare function variants<C extends VariantsConfig<V>, V extends Variants = C["variants"]>(config: Simplify<C>): (props: VariantOptions<C>) => string;
 /**
  * No-op function to mark template literals as tailwind strings.

package/lib/index.js

@@ -1,3 +1,6 @@
+export const classNames = {
+    combine: (...classes) => classes.filter(Boolean).join(" "),
+};
 export function variants(config) {
     const { base, variants, compoundVariants, defaultVariants } = config;
     const isBooleanVariant = (name) => {
@@ -6,7 +9,7 @@ export function variants(config) {
     };
     return (props) => {
         var _a;
-        const res = [base];
+        const classes = base ? [base] : [];
         const getSelected = (name) => {
             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);
@@ -14,15 +17,15 @@ export function variants(config) {
         for (let name in variants) {
             const selected = getSelected(name);
             if (selected !== undefined)
-                res.push((_a = variants[name]) === null || _a === void 0 ? void 0 : _a[selected]);
+                classes.push((_a = variants[name]) === null || _a === void 0 ? void 0 : _a[selected]);
         }
         for (let { variants, className } of compoundVariants !== null && compoundVariants !== void 0 ? compoundVariants : []) {
             const isSelected = (name) => getSelected(name) === variants[name];
             if (Object.keys(variants).every(isSelected)) {
-                res.push(className);
+                classes.push(className);
             }
         }
-        return res.filter(Boolean).join(" ");
+        return classNames.combine(...classes);
     };
 }
 /**

package/lib/preact.d.ts

@@ -20,7 +20,14 @@ type AsProps<T extends ElementType = ElementType> = {
     as?: T;
 };
 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, C["variants"]>>(type: T, config: string | {
+    base: string;
+} | Simplify<C>): <As extends ElementType = T>(props: PolymorphicComponentProps<typeof config extends string ? {} : typeof config extends {
+    base: string;
+    variants?: undefined;
+    compoundVariants?: undefined;
+    defaultVariants?: undefined;
+} ? {} : VariantOptions<C>, As>) => VNode | null;
 /**
  * No-op function to mark template literals as tailwind strings.
  */

package/lib/preact.js

@@ -1,6 +1,6 @@
 import { h } from "preact";
 import { forwardRef } from "preact/compat";
-import { variants, } from "./index.js";
+import { variants, classNames, } from "./index.js";
 export function variantProps(config) {
     const variantClassName = variants(config);
     return (props) => {
@@ -12,16 +12,16 @@ export function variantProps(config) {
             }
         }
         // Add the optionally passed class/className prop for chaining
-        result.class = [variantClassName(props), props.class, props.className]
-            .filter(Boolean)
-            .join(" ");
+        result.class = classNames.combine(variantClassName(props), props.class, props.className);
         return result;
     };
 }
 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 Component = forwardRef(({ as, ...props }, ref) => {
         return h(as !== null && as !== void 0 ? as : type, { ...styledProps(props), ref });
     });

package/lib/react.d.ts

@@ -18,7 +18,14 @@ type AsProps<T extends ElementType = ElementType> = {
     as?: T;
 };
 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, C["variants"]>>(type: T, config: string | {
+    base: string;
+} | Simplify<C>): <As extends ElementType = T>(props: PolymorphicComponentProps<typeof config extends string ? {} : typeof config extends {
+    base: string;
+    variants?: undefined;
+    compoundVariants?: undefined;
+    defaultVariants?: undefined;
+} ? {} : VariantOptions<C>, As>) => ReactElement | null;
 /**
  * No-op function to mark template literals as tailwind strings.
  */

package/lib/react.js

@@ -1,5 +1,5 @@
 import { createElement, forwardRef, } from "react";
-import { variants, } from "./index.js";
+import { variants, classNames, } from "./index.js";
 export function variantProps(config) {
     const variantClassName = variants(config);
     return (props) => {
@@ -11,16 +11,16 @@ export function variantProps(config) {
             }
         }
         // Add the optionally passed className prop for chaining
-        result.className = [variantClassName(props), props.className]
-            .filter(Boolean)
-            .join(" ");
+        result.className = classNames.combine(variantClassName(props), props.className);
         return result;
     };
 }
 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 Component = forwardRef(({ as, ...props }, ref) => {
         return createElement(as !== null && as !== void 0 ? as : type, { ...styledProps(props), ref });
     });

package/llms.txt

@@ -0,0 +1,163 @@
+# 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
+- `src/preact.ts` - Preact-specific bindings (similar to React but uses Preact's JSX)
+
+### 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)
+- Polymorphic components with "as" prop
+- 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
+  compoundVariants?: [...]          // Conditional class combinations
+}
+```
+
+### 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
+- Provide full autocomplete and type checking
+
+## 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");
+```
+
+### 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.4.1",
+  "version": "1.6.0",
   "description": "Variant API for plain class names",
   "author": "Felix Gnass <fgnass@gmail.com>",
   "license": "MIT",