classname-variants 1.5.0 → 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

@@ -281,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/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

@@ -19,7 +19,9 @@ 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 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

@@ -18,7 +18,9 @@ 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 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.5.0",
+  "version": "1.6.0",
   "description": "Variant API for plain class names",
   "author": "Felix Gnass <fgnass@gmail.com>",
   "license": "MIT",