classname-variants 1.7.0 → 1.7.1

package/LICENSE

@@ -0,0 +1,7 @@
+Copyright 2022 Felix Gnass
+
+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

@@ -12,7 +12,28 @@ Library to create type-safe components that render their class name based on a s
 
 ![npm bundle size](https://img.shields.io/bundlephobia/minzip/classname-variants)
 
-# Examples
+## Installation
+
+```bash
+npm install classname-variants
+```
+
+## Import Paths
+
+```ts
+// Core — vanilla DOM, no framework dependency
+import { variants, classNames, tw } from "classname-variants";
+
+// React — styled components, variantProps, type utilities
+import { styled, variantProps, tw } from "classname-variants/react";
+import type { VariantPropsOf } from "classname-variants/react";
+
+// Preact — same API, accepts both `class` and `className`
+import { styled, variantProps, tw } from "classname-variants/preact";
+import type { VariantPropsOf } from "classname-variants/preact";
+```
+
+## Examples
 
 Here is an example that uses React and Tailwind CSS:
 
@@ -36,11 +57,9 @@ function UsageExample() {
 }
 ```
 
-[![Edit classname-variants/react](https://codesandbox.io/static/img/play-codesandbox.svg)](https://codesandbox.io/s/classname-variants-react-3bzjl?fontsize=14&hidenavigation=1&theme=dark)
-
 While the library has been designed with tools like Tailwind in mind, it can be also used with custom classes or CSS modules:
 
-## Preact + CSS modules
+### Preact + CSS modules
 
 ```tsx
 import { styled } from "classname-variants/preact";
@@ -56,7 +75,7 @@ const Button = styled("button", {
 });
 ```
 
-## Vanilla DOM
+### Vanilla DOM
 
 The core of the library is completely framework-agnostic:
 
@@ -80,7 +99,7 @@ document.write(`
 `);
 ```
 
-# API
+## API
 
 ### Defining variants
 
@@ -121,6 +140,8 @@ Variants can be typed as `boolean` by using `true` / `false` as key:
 <Button primary>Click Me!</Button>
 ```
 
+### Compound variants
+
 The `compoundVariants` option can be used to apply class names based on a combination of other variants:
 
 ```ts
@@ -231,6 +252,71 @@ const Button = styled("button", {
 <Button disabled />;
 ```
 
+### Chaining additional class names
+
+Styled components accept a `className` prop that gets merged with the variant output. This is useful for one-off overrides:
+
+```tsx
+<Button className="mt-4" size="large">Submit</Button>
+```
+
+The Preact adapter accepts both `class` and `className` — use whichever you prefer:
+
+```tsx
+<Button class="mt-4" size="large">Submit</Button>
+```
+
+### Ref forwarding
+
+All `styled()` components support refs via `React.forwardRef`:
+
+```tsx
+const Input = styled("input", {
+  base: "border rounded px-2",
+  variants: { ... },
+});
+
+const ref = useRef<HTMLInputElement>(null);
+<Input ref={ref} />;
+```
+
+### `variantProps()`
+
+The lower-level `variantProps()` function lets you separate variant logic from rendering. This is useful for headless components or when you need more control:
+
+```tsx
+import { variantProps } from "classname-variants/react";
+
+const buttonProps = variantProps({
+  base: "rounded px-4 py-2",
+  variants: {
+    intent: {
+      primary: "bg-teal-500 text-white",
+      secondary: "bg-slate-200",
+    },
+  },
+});
+
+function Button(props) {
+  // Extracts variant props, returns { className, ...rest }
+  const { className, ...rest } = buttonProps(props);
+  return <button className={className} {...rest} />;
+}
+```
+
+### `VariantPropsOf<T>`
+
+Use this utility type to extract the variant props accepted by a `variantProps` function — helpful when building wrapper components:
+
+```tsx
+import { variantProps, type VariantPropsOf } from "classname-variants/react";
+
+const buttonProps = variantProps({ ... });
+
+type ButtonProps = VariantPropsOf<typeof buttonProps>;
+// { intent: "primary" | "secondary"; className?: string }
+```
+
 ### 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).
@@ -293,7 +379,24 @@ import { twMerge } from "tailwind-merge";
 classNames.combine = twMerge;
 ```
 
-# Tailwind IntelliSense
+## Why classname-variants?
+
+### vs clsx / classnames
+
+- **Type safety** — full TypeScript inference for variant props instead of manual conditional logic
+- **Variant system** — built-in support for default values, compound variants, and boolean variants
+- **Framework bindings** — `styled()` creates ready-to-use React/Preact components
+
+### vs class-variance-authority (cva)
+
+- **Zero dependencies** — no external runtime dependencies
+- **Framework integration** — built-in `styled()` API with polymorphic `as` prop, ref forwarding, and `defaultProps`
+- **Prop forwarding** — `forwardProps` maps variant values to DOM attributes (e.g. `disabled`)
+- **TypeScript-first** — designed around type inference rather than requiring manual `VariantProps` extraction
+
+If you're coming from cva: `cva()` maps to `variants()`, and `VariantProps<typeof x>` maps to `VariantPropsOf<typeof x>`.
+
+## 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.
 
@@ -320,10 +423,10 @@ You can then set the _Tailwind CSS: Class Functions_ option to `tw`.
 
 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 AI Assistants
 
 For comprehensive technical documentation optimized for LLMs, see [`llms.txt`](./llms.txt).
 
-# License
+## License
 
 MIT

package/llms.txt

@@ -16,18 +16,27 @@ This library provides a variant API for generating class names based on componen
 
 ### 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
+- `src/preact.ts` - Preact-specific bindings (similar to React but uses Preact's JSX with `class` prop) with equivalent `defaultProps` support
+
+### Class Application Order
+When generating class names, the library combines them in this order:
+1. `base` classes (always applied)
+2. Variant classes (based on selected or default variant values)
+3. Compound variant classes (when all conditions match)
+4. User-supplied `className` prop (React/Preact only, via chaining)
 
 ### Key Features
 - Type-safe variant definitions with full TypeScript inference
 - Support for required and optional variants
 - Boolean variants (true/false)
-- Default variants
+- Default variants via `defaultVariants` (note: NOT "defaults")
 - 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
+- `className` prop chaining on styled components (user classes merged with variant output)
+- Ref forwarding — all `styled()` components use `forwardRef` internally
+- Works with any CSS framework (Tailwind, CSS modules, etc.) without additional dependencies
 
 ## File Structure
 
@@ -59,8 +68,8 @@ src/
       [optionName]: "class-names"
     }
   },
-  defaultVariants?: {...},          // Default values
-  defaultProps?: {...},             // Defaulted non-variant props (e.g. { type: "button" })
+  defaultVariants?: {...},          // IMPORTANT: Use "defaultVariants" for default variant values
+  defaultProps?: {...},             // DIFFERENT: Use "defaultProps" for non-variant props (e.g. { type: "button" })
   compoundVariants?: [...]          // Conditional class combinations
   forwardProps?: ["disabled", ...]  // Variant keys to pass through as real props
 }
@@ -92,9 +101,9 @@ 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"
+// Low-level API and type utilities
+import { variantProps, type VariantPropsOf } from "classname-variants/react"
+import { variantProps, type VariantPropsOf } from "classname-variants/preact"
 ```
 
 ### Styled Components Without Variants
@@ -139,6 +148,44 @@ const Button = styled("button", {
 <Button disabled />;
 ```
 
+### className Prop Chaining
+Styled components accept an additional `className` prop that gets merged with the variant output:
+
+```tsx
+<Button className="mt-4" size="large">Submit</Button>
+```
+
+The Preact adapter accepts both `class` and `className` — they are merged together, so either works:
+
+```tsx
+<Button class="mt-4" size="large">Submit</Button>
+```
+
+### variantProps() for Headless Components
+The lower-level `variantProps()` function separates variant logic from rendering, useful for headless components or custom wrappers:
+
+```tsx
+import { variantProps, type VariantPropsOf } from "classname-variants/react";
+
+const buttonProps = variantProps({
+  base: "rounded px-4 py-2",
+  variants: {
+    intent: {
+      primary: "bg-teal-500 text-white",
+      secondary: "bg-slate-200",
+    },
+  },
+});
+
+// Extract the variant prop types for the wrapper component
+type ButtonProps = VariantPropsOf<typeof buttonProps>;
+
+function Button(props: ButtonProps) {
+  const { className, ...rest } = buttonProps(props);
+  return <button className={className} {...rest} />;
+}
+```
+
 ### Polymorphic Components with "as" Prop
 Change the underlying element/component while keeping the same styles:
 
@@ -153,8 +200,13 @@ const Button = styled("button", { variants: {...} });
 
 ### Tailwind CSS Integration
 
-#### Using tailwind-merge for Conflict Resolution
+The library works with Tailwind CSS out of the box without any additional dependencies.
+
+#### OPTIONAL: Using tailwind-merge for Class Conflict Resolution
+**This is completely optional.** Only consider using tailwind-merge if you need to resolve conflicting Tailwind classes (e.g., when allowing className overrides). Most use cases don't need this - design your variants to avoid conflicts instead to reduce complexity and overhead.
+
 ```ts
+// Only if you really need class merging:
 import { classNames } from "classname-variants";
 import { twMerge } from "tailwind-merge";
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "classname-variants",
-  "version": "1.7.0",
+  "version": "1.7.1",
   "description": "Variant API for plain class names",
   "author": "Felix Gnass <fgnass@gmail.com>",
   "license": "MIT",
@@ -41,7 +41,7 @@
     "lint:fix": "biome check --write --unsafe .",
     "start": "npx vite",
     "test": "vitest",
-    "prepublishOnly": "npm run build && npm test"
+    "prepublishOnly": "npm run build && vitest --run"
   },
   "keywords": [
     "tailwind",