classname-variants 1.3.3 → 1.4.1

package/README.md

@@ -1,20 +1,67 @@
-# classname-variants
+# classname-variants 🌈
 
-Stitches-like [variant API](https://stitches.dev/docs/variants) for plain class names.
+Library to create type-safe components that render their class name based on a set of variants.
 
-The library is framework-agnostic and can be used with any kind of CSS flavor.
+## Features
 
-It is especially useful though if used with [Tailwind](https://tailwindcss.com/) or [CSS Modules](https://github.com/css-modules/css-modules) in combination with React, as it provides some [dedicated helpers](#React) and even allows for a _styled-components_ like API, but with [class names instead of styles](#bonus-styled-components-but-with-class-names-)!
+- ⚛️ 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
 
-[![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)
+![npm bundle size](https://img.shields.io/bundlephobia/minzip/classname-variants)
+
+# Examples
+
+Here is an example that uses React and Tailwind CSS:
+
+```tsx
+import { styled } from "classname-variants/react";
+
+const Button = styled("button", {
+  variants: {
+    size: {
+      small: "text-xs",
+      large: "text-lg",
+    },
+    primary: {
+      true: "bg-teal-500 text-white",
+    },
+  },
+});
+
+function UsageExample() {
+  return <Button primary size="large" />;
+}
+```
 
-# Basics
+[![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)
 
-Let's assume we want to build a button component with Tailwind CSS that comes in different sizes and colors.
+While the library has been designed with tools like Tailwind in mind, it can be also used with custom classes or CSS modules:
 
-It consists of some _base classes_ that are always present as well as some optional classes that need to be added depending on the desired _variants_.
+## Preact + CSS modules
 
 ```tsx
+import { styled } from "classname-variants/preact";
+import styles from "./styles.module.css";
+
+const Button = styled("button", {
+  variants: {
+    size: {
+      small: styles.small,
+      large: styles.large,
+    },
+  },
+});
+```
+
+## Vanilla DOM
+
+The core of the library is completely framework-agnostic:
+
+```ts
+import { variants } from "classname-variants";
+
 const button = variants({
   base: "rounded text-white",
   variants: {
@@ -22,50 +69,61 @@ const button = variants({
       brand: "bg-sky-500",
       accent: "bg-teal-500",
     },
-    size: {
-      small: "px-5 py-3 text-xs",
-      large: "px-6 py-4 text-base",
-    },
   },
 });
-```
-
-The result is a function that expects an object which specifies what variants should be selected. When called, it returns a string containing the respective class names:
 
-```ts
 document.write(`
-  <button class="${button({
-    color: "accent",
-    size: "large",
-  })}">
+  <button class="${button({ color: "accent" })}">
     Click Me!
   </button>
 `);
 ```
 
-# Advanced Usage
+# API
 
-## Boolean variants
+### Defining variants
 
-Variants can be of type `boolean` by using `"true"` as the key:
+You can add any number of variants by using the `variants` key.
 
-```tsx
-const button = variants({
-  base: "text-white",
+```ts
+{
+  variants: {
+    color: {
+      primary: "bg-teal",
+      secondary: "bg-indigo",
+      danger: "bg-red"
+    },
+    size: {
+      small: "text-sm",
+      medium: "text-md",
+      large: "text-lg",
+    }
+  }
+}
+```
+
+### Boolean variants
+
+Variants can be typed as `boolean` by using `true` / `false` as key:
+
+```ts
+{
   variants: {
-    rounded: {
-      true: "rounded-full",
+    primary: {
+      true: "bg-teal-500",
     },
   },
-});
+}
 ```
 
-## Compound variants
+```ts
+<Button primary>Click Me!</Button>
+```
 
-The `compoundVariants` option can be used to apply class names based on a combination of other variants.
+The `compoundVariants` option can be used to apply class names based on a combination of other variants:
 
-```tsx
-const button = variants({
+```ts
+{
   variants: {
     color: {
       neutral: "bg-gray-200",
@@ -84,128 +142,71 @@ const button = variants({
       className: "border-teal-500",
     },
   ],
-});
+}
 ```
 
-## Default variants
+### Default variants
 
-The `defaultVariants` option can be used to select a variant by default:
+If you define a variant it becomes a required prop unless you specify a default (or the variant is boolean). You can use the `defaultVariants` property to specify defaults:
 
 ```ts
-const button = variants({
+{
   variants: {
     color: {
-      neutral: "bg-gray-200",
-      accent: "bg-teal-400",
+      primary: "bg-teal-300",
+      secondary: "bg-teal-100"
     },
   },
   defaultVariants: {
-    color: "neutral",
-  },
-});
+    color: "secondary",
+  }
+}
 ```
 
-# React
-
-The library contains utility functions that are useful for writing React components.
+### Base class
 
-It works much like `variants()` but instead of a class name string, the resulting function returns an object with props.
+Use the `base` property to specify class names that should always be applied:
 
 ```ts
-import { variantProps } from "classname-variants/react";
-
-const buttonProps = variantProps({
-  base: "rounded-md text-white",
+{
+  base: "text-black rounded-full px-2",
   variants: {
-    color: {
-      brand: "bg-sky-500",
-      accent: "bg-teal-500",
-    },
-    size: {
-      small: "px-5 py-3 text-xs",
-      large: "px-6 py-4 text-base",
-    },
-    rounded: {
-      true: "rounded-full",
-    },
-  },
-  defaultVariants: {
-    color: "brand",
-  },
-});
-```
-
-This way a component's props (or part of them) can be directly spread into the target element. All variant-related props are used to construct the `className` property while all other props are passed through verbatim:
-
-```tsx
-type Props = JSX.IntrinsicElements["button"] &
-  VariantPropsOf<typeof buttonProps>;
-
-function Button(props: Props) {
-  return <button {...buttonProps(props)} />;
-}
-
-function App() {
-  return (
-    <Button size="small" color="accent" onClick={console.log}>
-      Click Me!
-    </Button>
-  );
+    // ...
+  }
 }
 ```
 
-# Bonus: styled-components, but for static CSS 💅
+### Components without variants
 
-Things can be taken even a step further, resulting in a _styled-components_ like way of defining reusable components. Under the hood, this does basically the same as the example above, but also handles _refs_ correctly:
+Sometimes it can be useful to define styled components that
+don't have any variants, which can be done like this:
 
-```ts
-import { styled, tw } from "classname-variants/react";
+```tsx
+import { styled } from "classname-variants/react";
 
-const Button = styled("button", {
-  variants: {
-    size: {
-      small: tw`text-xs`,
-      large: tw`text-base`,
-    },
-  },
-});
+const Button = styled("button", "bg-transparent border p-2");
 ```
 
-Again, this is not limited to tailwind, so you could do the same with CSS modules:
+### Styling custom components
 
-```ts
-import { styled } from "classname-variants/react";
-import styles from "./styles.module.css";
+You can style any custom React/Preact component as long as they accept a `className` prop (or `class` in case of Preact).
 
-const Button = styled("button", {
+```tsx
+function MyComponent(props) {
+  return <div {...props}>I'm a stylable custom component.</div>;
+}
+
+const MyStyledComponent = styled(MyComponent, {
+  base: "some-class",
   variants: {
-    size: {
-      small: styles.small,
-      large: styles.large,
-    },
+    // ...
   },
 });
 ```
 
-> [!TIP]
-> You can also style other custom React components as long as they accept a `className` prop.
-
-## Styled components without variants
-
-You can also use the `styled` function to create styled components without any variants at all:
-
-```ts
-import { styled } from "classname-variants/react";
-
-const Button = styled(
-  "button",
-  "border-none rounded px-3 font-sans bg-green-600 text-white hover:bg-green-500"
-);
-```
-
-## Polymorphic components with "as"
+### Polymorphic components with "as"
 
-If you want to keep all the variants you have defined for a component but want to render a different HTML tag or a different custom component, you can use the "as" prop to do so:
+If you want to keep all the variants you have defined for a component but want to render a different HTML tag or a different custom component, you can use the `as` prop to do so:
 
 ```tsx
 import { styled } from "classname-variants/react";
@@ -215,17 +216,20 @@ const Button = styled("button", {
     //...
   },
 });
+```
 
-function App() {
-  return (
-    <div>
-      <Button>I'm a button</Button>
-      <Button as="a" href="/">
-        I'm a link!
-      </Button>
-    </div>
-  );
-}
+The component can then be rendered as button or as anchor or even as custom component exposed by some router:
+
+```tsx
+<>
+  <Button>I'm a button</Button>
+  <Button as="a" href="/">
+    I'm a link!
+  </Button>
+  <Button as={Link} to="/">
+    I'm a styled Link component
+  </Button>
+</>
 ```
 
 # Tailwind IntelliSense

package/index.html

@@ -10,7 +10,10 @@
     <script src="https://cdn.tailwindcss.com"></script>
   </head>
   <body>
-    <div id="root"></div>
-    <script type="module" src="./src/example.tsx"></script>
+    <h1>React</h1>
+    <div id="react-root"></div>
+    <h1>Preact</h1>
+    <div id="preact-root"></div>
+    <script type="module" src="./src/example/index.ts"></script>
   </body>
 </html>

package/lib/example/index.d.ts

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

package/lib/example/index.js

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

package/lib/example/preact.d.ts

@@ -0,0 +1,9 @@
+/** @jsx h */
+import { h } from "preact";
+export declare const ExpectErrors: <As extends keyof h.JSX.IntrinsicElements | import("preact").ComponentType<any> = "div">(props: {
+    as?: As | undefined;
+} & Omit<import("preact").ComponentProps<As>, "as" | "color"> & {
+    color: "neutral" | "accent";
+} & {}) => import("preact").VNode<{}> | null;
+export declare function WithErrors(): h.JSX.Element;
+export declare function PreactApp(): h.JSX.Element;

package/lib/example/preact.js

@@ -0,0 +1,76 @@
+/** @jsx h */
+import { styled } from "../preact";
+import { h } 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 Button = styled("button", {
+    base: "px-5 py-2 text-white disabled:bg-gray-400 disabled:text-gray-300",
+    variants: {
+        color: {
+            neutral: "bg-slate-500 hover:bg-slate-400",
+            accent: "bg-teal-500 hover:bg-teal-400",
+        },
+        size: {
+            small: "text-sm",
+            medium: "text-md",
+        },
+        outlined: {
+            true: "border-2",
+        },
+        rounded: {
+            true: "rounded-full",
+            false: "rounded-sm",
+        },
+    },
+    compoundVariants: [
+        {
+            variants: { color: "accent", outlined: true },
+            className: "border-teal-600",
+        },
+    ],
+    defaultVariants: {
+        color: "neutral",
+    },
+});
+export const ExpectErrors = styled("div", {
+    variants: {
+        color: {
+            neutral: "grey",
+            accent: "hotpink",
+        },
+    },
+    compoundVariants: [
+        {
+            //@ts-expect-error
+            variants: { outlined: true },
+            className: "",
+        },
+    ],
+    defaultVariants: {
+        //@ts-expect-error
+        outlined: true,
+    },
+});
+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, 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(TitleCard, { title: "Hello" }),
+        h(Card, null,
+            h("h1", null, "Hello"),
+            h("p", null, "world")),
+        h(Card, { as: "a", href: "https://example.com" }, "Link"),
+        h(Card, { as: CustomComponent, title: "Test" })));
+}

package/lib/example/react.d.ts

@@ -0,0 +1,8 @@
+import React from "react";
+export declare const ExpectErrors: <As extends React.ElementType<any> = "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;

package/lib/example/react.js

@@ -0,0 +1,76 @@
+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 Button = styled("button", {
+    base: "px-5 py-2 text-white disabled:bg-gray-400 disabled:text-gray-300",
+    variants: {
+        color: {
+            neutral: "bg-slate-500 hover:bg-slate-400",
+            accent: "bg-teal-500 hover:bg-teal-400",
+        },
+        size: {
+            small: "text-sm",
+            medium: "text-md",
+        },
+        outlined: {
+            true: "border-2",
+        },
+        rounded: {
+            true: "rounded-full",
+            false: "rounded-sm",
+        },
+    },
+    compoundVariants: [
+        {
+            variants: { color: "accent", outlined: true },
+            className: "border-teal-600",
+        },
+    ],
+    defaultVariants: {
+        color: "neutral",
+    },
+});
+export const ExpectErrors = styled("div", {
+    variants: {
+        color: {
+            neutral: "grey",
+            accent: "hotpink",
+        },
+    },
+    compoundVariants: [
+        {
+            //@ts-expect-error
+            variants: { outlined: true },
+            className: "",
+        },
+    ],
+    defaultVariants: {
+        //@ts-expect-error
+        outlined: true,
+    },
+});
+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, 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(TitleCard, { title: "Hello" }),
+        React.createElement(Card, null,
+            React.createElement("h1", null, "Hello"),
+            React.createElement("p", null, "world")),
+        React.createElement(Card, { as: "a", href: "https://example.com" }, "Link"),
+        React.createElement(Card, { as: CustomComponent, title: "Test" })));
+}

package/lib/preact.d.ts

@@ -0,0 +1,30 @@
+import type { JSX, ComponentType, ComponentProps, VNode } from "preact";
+type ElementType<P = any> = keyof JSX.IntrinsicElements | ComponentType<P>;
+import { Variants, VariantsConfig, VariantOptions, Simplify } from "./index.js";
+/**
+ * Utility type to infer the first argument of a variantProps function.
+ */
+export type VariantPropsOf<T> = T extends (props: infer P) => any ? P : never;
+/**
+ * Type for the variantProps() argument – consists of the VariantOptions and an optional className for chaining.
+ */
+type VariantProps<C extends VariantsConfig<V>, V extends Variants = C["variants"]> = VariantOptions<C> & {
+    class?: string;
+    className?: string;
+};
+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 : {};
+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;
+/**
+ * No-op function to mark template literals as tailwind strings.
+ */
+export declare const tw: (template: {
+    raw: readonly string[] | ArrayLike<string>;
+}, ...substitutions: any[]) => string;
+export {};

package/lib/preact.js

@@ -0,0 +1,33 @@
+import { h } from "preact";
+import { forwardRef } from "preact/compat";
+import { 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) {
+            if (config.variants && !(prop in config.variants)) {
+                result[prop] = props[prop];
+            }
+        }
+        // Add the optionally passed class/className prop for chaining
+        result.class = [variantClassName(props), props.class, props.className]
+            .filter(Boolean)
+            .join(" ");
+        return result;
+    };
+}
+export function styled(type, config) {
+    const styledProps = typeof config === "string"
+        ? variantProps({ base: config, variants: {} })
+        : variantProps(config);
+    const Component = forwardRef(({ as, ...props }, ref) => {
+        return h(as !== null && as !== void 0 ? as : type, { ...styledProps(props), ref });
+    });
+    return Component;
+}
+/**
+ * No-op function to mark template literals as tailwind strings.
+ */
+export const tw = String.raw;

package/lib/react.d.ts

@@ -17,16 +17,8 @@ type VariantsOf<T, V> = T extends VariantsConfig ? V : {};
 type AsProps<T extends ElementType = ElementType> = {
     as?: T;
 };
-type PolymorphicComponentProps<T extends ElementType> = AsProps<T> & Omit<ComponentProps<T>, "as">;
-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: AsProps<As> & Omit<ComponentProps<As>, "as"> & (C["variants"] extends infer T_1 extends Variants ? { [K in keyof T_1 as K extends keyof (C["variants"] extends infer T_2 extends Variants ? { [K_1 in keyof T_2 as C["variants"][K_1] extends {
-    true: any;
-} | {
-    false: any;
-} ? K_1 : never]: C["variants"][K_1]; } : never) | keyof (C["variants"] extends infer T_3 extends Variants ? { [K_2 in keyof T_3 as K_2 extends keyof C["defaultVariants"] ? K_2 : never]: C["variants"][K_2]; } : never) ? never : K]: (C["variants"] extends infer T_4 extends Variants ? { [K_3 in keyof T_4]: keyof C["variants"][K_3] extends "true" | "false" ? boolean : keyof C["variants"][K_3]; } : never)[K]; } : never) & (C["variants"] extends infer T_5 extends Variants ? { [K_4 in keyof T_5 as K_4 extends keyof (C["variants"] extends infer T_2 extends Variants ? { [K_1 in keyof T_2 as C["variants"][K_1] extends {
-    true: any;
-} | {
-    false: any;
-} ? K_1 : never]: C["variants"][K_1]; } : never) | keyof (C["variants"] extends infer T_3 extends Variants ? { [K_2 in keyof T_3 as K_2 extends keyof C["defaultVariants"] ? K_2 : never]: C["variants"][K_2]; } : never) ? K_4 : never]?: (C["variants"] extends infer T_4 extends Variants ? { [K_3 in keyof T_4]: keyof C["variants"][K_3] extends "true" | "false" ? boolean : keyof C["variants"][K_3]; } : never)[K_4] | undefined; } : never)) => ReactElement | null;
+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;
 /**
  * No-op function to mark template literals as tailwind strings.
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "classname-variants",
-  "version": "1.3.3",
+  "version": "1.4.1",
   "description": "Variant API for plain class names",
   "author": "Felix Gnass <fgnass@gmail.com>",
   "license": "MIT",
@@ -16,6 +16,10 @@
     "./react": {
       "import": "./lib/react.js",
       "type": "./lib/react.d.ts"
+    },
+    "./preact": {
+      "import": "./lib/preact.js",
+      "type": "./lib/preact.d.ts"
     }
   },
   "typesVersions": {
@@ -25,6 +29,9 @@
       ],
       "react": [
         "./lib/react.d.ts"
+      ],
+      "preact": [
+        "./lib/preact.d.ts"
       ]
     }
   },
@@ -38,11 +45,13 @@
     "css",
     "classname",
     "variants",
-    "react"
+    "react",
+    "preact"
   ],
   "devDependencies": {
     "@types/react": "^18.0.26",
     "@types/react-dom": "^18.0.9",
+    "preact": "^10.20.2",
     "react": "^18.2.0",
     "react-dom": "^18.2.0",
     "typescript": "^4.9.4"