classname-variants 1.0.0 → 1.1.1

package/README.md

@@ -6,6 +6,8 @@ The library is framework agnostic and can be used with any kind of CSS flavor.
 
 It is especially useful though if used with [Tailwind](https://tailwindcss.com/) and 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-)!
 
+[![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)
+
 # Basics
 
 Let's aussume we want to build a button component with Tailwind CSS that comes in different sizes and colors.
@@ -136,7 +138,8 @@ const buttonProps = variantProps({
 This way a compontents' 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 = SX.IntrinsicElements["button"] & VariantProps<typeof buttonProps>;
+type Props = SX.IntrinsicElements["button"] &
+  VariantPropsOf<typeof buttonProps>;
 
 function Button(props: Props) {
   return <button {...buttonProps(props)} />;
@@ -168,6 +171,50 @@ const Button = styled("button", {
 });
 ```
 
+You can also style other custom React components as long as the accept a `className` prop.
+
+# 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.
+
+One way of doing so is by using tagged template literals:
+
+```ts
+const tw = String.raw;
+
+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`,
+    },
+  },
+});
+```
+
+```ts
+const tw = String.raw;
+
+const button = variants({
+  base: tw.px(5).py(2).text.white,
+  variants: {
+    color: {
+      neutral: tw.bg.slate(500).hover(tw.bg.slate.400),
+      accent: tw.bg.teal(500).hover(tw.bg.teal(400)),
+    },
+  },
+});
+```
+
+You can then add the following line to your `settings.json`:
+
+```
+"tailwindCSS.experimental.classRegex": ["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).
+
 # License
 
 MIT

package/example.tsx

@@ -2,38 +2,60 @@ import React from "react";
 import ReactDOM from "react-dom";
 import { styled } from "./src/react";
 
+function CustomComponent({
+  title,
+  ...props
+}: {
+  className?: string;
+  title: string;
+}) {
+  return <div {...props}>{title}</div>;
+}
+
+const Card = styled(CustomComponent, {
+  base: "bg-white p-4 border-2 rounded-lg",
+  variants: {},
+});
+
 const Button = styled("button", {
-  base: "rounded-md px-5 py-2 text-white",
+  base: "px-5 py-2 text-white disabled:bg-gray-400 disabled:text-gray-300",
   variants: {
     color: {
-      neutral: "bg-gray-500",
-      accent: "bg-teal-500",
+      neutral: "bg-slate-500 hover:bg-slate-400",
+      accent: "bg-teal-500 hover:bg-teal-400",
     },
     outlined: {
       true: "border-2",
     },
+    rounded: {
+      true: "rounded-full",
+      false: "rounded-sm",
+    },
   },
   compoundVariants: [
     {
-      variants: {
-        color: "accent",
-        outlined: true,
-      },
-      className: "border-teal-800",
+      variants: { color: "accent", outlined: true },
+      className: "border-teal-600",
     },
   ],
+  defaultVariants: {
+    color: "neutral",
+  },
 });
 
 function App() {
   return (
-    <>
-      <Button color="neutral" onClick={console.log}>
-        Neutral
-      </Button>
-      <Button color="accent" outlined onClick={console.log}>
+    <div className="flex justify-center items-center pt-8 gap-4 flex-wrap">
+      <Button onClick={console.log}>Accent</Button>
+      <Button rounded>Neutral + Rounded</Button>
+      <Button color="accent" outlined>
         Accent + Outlined
       </Button>
-    </>
+      <Button color="accent" disabled>
+        Disabled
+      </Button>
+      <Card title="Hello" />
+    </div>
   );
 }
 

package/lib/index.d.ts

@@ -1,18 +1,105 @@
-export declare type VariantDefinitions = Record<string, string>;
-export declare type Variants = Record<string, VariantDefinitions>;
-export declare type VariantsConfig<V extends Variants> = {
+/**
+ * Definition of the available variants and their options.
+ * @example
+ * {
+ *   color: {
+ *     white: "bg-white"
+ *     green: "bg-green-500",
+ *   },
+ *   size: {
+ *     small: "text-xs",
+ *     large: "text-lg"
+ *   }
+ * }
+ */
+export declare type Variants = Record<string, Record<string, string>>;
+/**
+ * Configuration including defaults and compound variants.
+ */
+export interface VariantsConfig<V extends Variants> {
     base?: string;
-    variants?: V;
+    variants: V;
     compoundVariants?: CompoundVariant<V>[];
-    defaultVariants?: VariantSelection<V>;
-};
-export declare type CompoundVariant<V extends Variants> = {
-    variants: VariantSelection<V>;
+    defaultVariants?: Partial<OptionsOf<V>>;
+}
+/**
+ * Rules for class names that are applied for certain variant combinations.
+ */
+export interface CompoundVariant<V extends Variants> {
+    variants: Partial<OptionsOf<V>>;
     className: string;
+}
+/**
+ * Only the boolean variants, i.e. ones that have "true" or "false" as options.
+ */
+declare type BooleanVariants<V extends Variants> = {
+    [K in keyof V as V[K] extends {
+        true: any;
+    } | {
+        false: any;
+    } ? K : never]: V[K];
+};
+/**
+ * Only the variants for which a default options is set.
+ */
+declare type DefaultVariants<C extends VariantsConfig<V>, V extends Variants = C["variants"]> = {
+    [K in keyof V as K extends keyof C["defaultVariants"] ? K : never]: C["variants"][K];
+};
+/**
+ * Names of all optional variants, i.e. booleans or ones with default options.
+ */
+declare type OptionalVariantNames<C extends VariantsConfig<V>, V extends Variants = C["variants"]> = keyof BooleanVariants<V> | keyof DefaultVariants<C>;
+/**
+ * Possible options for all the optional variants.
+ *
+ * @example
+ * {
+ *   color?: "white" | "green",
+ *   rounded?: boolean | undefined
+ * }
+ */
+declare type OptionalOptions<C extends VariantsConfig<V>, V extends Variants = C["variants"]> = {
+    [K in keyof V as K extends OptionalVariantNames<C> ? K : never]?: OptionsOf<V>[K];
+};
+/**
+ * Possible options for all required variants.
+ *
+ * @example {
+ *   size: "small" | "large"
+ * }
+ */
+declare type RequiredOptions<C extends VariantsConfig<V>, V extends Variants = C["variants"]> = {
+    [K in keyof V as K extends OptionalVariantNames<C> ? never : K]: OptionsOf<V>[K];
+};
+/**
+ * Utility type to extract the possible options.
+ * Converts "true" | "false" options into booleans.
+ *
+ * @example
+ * OptionsOf<{
+ *   size: { small: "text-xs"; large: "text-lg" };
+ *   rounded: { true: "rounded-full" }
+ * }>
+ * ==>
+ * {
+ *   size: "text-xs" | "text-lg";
+ *   rounded: boolean;
+ * }
+ */
+declare type OptionsOf<V extends Variants> = {
+    [K in keyof V]: keyof V[K] extends "true" | "false" ? boolean : keyof V[K];
 };
-export declare type VariantSelection<V extends Variants> = {
-    [VariantName in keyof V]?: StringToBool<keyof V[VariantName]>;
+/**
+ * Extracts the possible options.
+ */
+export declare type VariantOptions<C extends VariantsConfig<V>, V extends Variants = C["variants"]> = RequiredOptions<C> & OptionalOptions<C>;
+/**
+ * Without this conversion step, defaultVariants and compoundVariants will
+ * allow extra keys, i.e. non-existent variants.
+ * See https://github.com/sindresorhus/type-fest/blob/main/source/simplify.d.ts
+ */
+export declare type Simplify<T> = {
+    [K in keyof T]: T[K];
 };
-declare type StringToBool<T> = T extends "true" | "false" ? boolean : T;
-export declare function variants<V extends Variants>({ base, variants, compoundVariants, defaultVariants, }: VariantsConfig<V>): (props: VariantSelection<V>) => string;
+export declare function variants<C extends VariantsConfig<V>, V extends Variants = C["variants"]>(config: Simplify<C>): (props: VariantOptions<C>) => string;
 export {};

package/lib/index.js

@@ -1,18 +1,26 @@
-export function variants({ base, variants, compoundVariants, defaultVariants, }) {
+export function variants(config) {
+    const { base, variants, compoundVariants, defaultVariants } = config;
+    const isBooleanVariant = (name) => {
+        const v = variants === null || variants === void 0 ? void 0 : variants[name];
+        return v && ("false" in v || "true" in v);
+    };
     return (props) => {
+        var _a;
         const res = [base];
-        const getSelected = (name) => { var _a; return (_a = props[name]) !== null && _a !== void 0 ? _a : defaultVariants === null || defaultVariants === void 0 ? void 0 : defaultVariants[name]; };
+        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);
+        };
         for (let name in variants) {
             const selected = getSelected(name);
-            const options = variants[name];
-            if (selected)
-                res.push(options[selected]);
+            if (selected !== undefined)
+                res.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];
-            const allSelected = Object.keys(variants).every(isSelected);
-            if (allSelected)
+            const isSelected = (name) => getSelected(name) === variants[name];
+            if (Object.keys(variants).every(isSelected)) {
                 res.push(className);
+            }
         }
         return res.filter(Boolean).join(" ");
     };

package/lib/react.d.ts

@@ -1,9 +1,18 @@
 import { ComponentProps, ElementType, ForwardRefExoticComponent, PropsWithoutRef } from "react";
-import { Variants, VariantsConfig, VariantSelection } from ".";
-export declare type VariantProps<T> = T extends (props: infer VariantSelection) => any ? VariantSelection : never;
-export declare function variantProps<V extends Variants>(config: VariantsConfig<V>): <T extends VariantSelection<V>>(props: T) => {
+import { Variants, VariantsConfig, VariantOptions, Simplify } from ".";
+/**
+ * Utility type to infer the first argument of a variantProps function.
+ */
+export declare 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.
+ */
+declare type VariantProps<C extends VariantsConfig<V>, V extends Variants = C["variants"]> = VariantOptions<C> & {
+    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) => {
     className: string;
-} & Omit<T, keyof V>;
-declare type StyledComponent<P extends ElementType, V extends Variants> = ForwardRefExoticComponent<PropsWithoutRef<ComponentProps<P> & VariantSelection<V>> & React.RefAttributes<P>>;
-export declare function styled<P extends ElementType, V extends Variants>(type: P, config: VariantsConfig<V>): StyledComponent<P, V>;
+} & Omit<P, keyof C["variants"]>;
+declare type StyledComponent<T extends ElementType, C extends VariantsConfig<V>, V extends Variants = C["variants"]> = ForwardRefExoticComponent<PropsWithoutRef<ComponentProps<T> & VariantOptions<C>> & React.RefAttributes<T>>;
+export declare function styled<T extends ElementType, C extends VariantsConfig<V>, V extends Variants = C["variants"]>(type: T, config: Simplify<C>): StyledComponent<T, C>;
 export {};

package/lib/react.js

@@ -1,15 +1,19 @@
 import { createElement, forwardRef, } from "react";
-import { variants } from ".";
+import { variants, } from ".";
 export function variantProps(config) {
-    const mkClass = variants(config);
+    const variantClassName = variants(config);
     return (props) => {
-        const className = mkClass(props);
-        const result = { className };
+        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 className prop for chaining
+        result.className = [props.className, variantClassName(props)]
+            .filter(Boolean)
+            .join(" ");
         return result;
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "classname-variants",
-  "version": "1.0.0",
+  "version": "1.1.1",
   "description": "Variant API for plain class names",
   "author": "Felix Gnass <fgnass@gmail.com>",
   "license": "MIT",
@@ -8,9 +8,30 @@
   "type": "module",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./lib/index.js",
+      "type": "./lib/index.d.ts"
+    },
+    "./react": {
+      "import": "./lib/react.js",
+      "type": "./lib/react.d.ts"
+    }
+  },
+  "typesVersions": {
+    "*": {
+      "*": [
+        "./lib/index.d.ts"
+      ],
+      "react": [
+        "./lib/react.d.ts"
+      ]
+    }
+  },
   "scripts": {
     "build": "tsc",
-    "start": "npx vite"
+    "start": "npx vite",
+    "prepublishOnly": "npm run build"
   },
   "keywords": [
     "tailwind",

package/src/index.ts

@@ -1,46 +1,165 @@
-export type VariantDefinitions = Record<string, string>;
+/**
+ * Definition of the available variants and their options.
+ * @example
+ * {
+ *   color: {
+ *     white: "bg-white"
+ *     green: "bg-green-500",
+ *   },
+ *   size: {
+ *     small: "text-xs",
+ *     large: "text-lg"
+ *   }
+ * }
+ */
+export type Variants = Record<string, Record<string, string>>;
 
-export type Variants = Record<string, VariantDefinitions>;
-
-export type VariantsConfig<V extends Variants> = {
+/**
+ * Configuration including defaults and compound variants.
+ */
+export interface VariantsConfig<V extends Variants> {
   base?: string;
-  variants?: V;
+  variants: V;
   compoundVariants?: CompoundVariant<V>[];
-  defaultVariants?: VariantSelection<V>;
-};
+  defaultVariants?: Partial<OptionsOf<V>>;
+}
 
-export type CompoundVariant<V extends Variants> = {
-  variants: VariantSelection<V>;
+/**
+ * Rules for class names that are applied for certain variant combinations.
+ */
+export interface CompoundVariant<V extends Variants> {
+  variants: Partial<OptionsOf<V>>;
   className: string;
+}
+
+/**
+ * Only the boolean variants, i.e. ones that have "true" or "false" as options.
+ */
+type BooleanVariants<V extends Variants> = {
+  [K in keyof V as V[K] extends { true: any } | { false: any }
+    ? K
+    : never]: V[K];
+};
+
+/**
+ * Only the variants for which a default options is set.
+ */
+type DefaultVariants<
+  C extends VariantsConfig<V>,
+  V extends Variants = C["variants"]
+> = {
+  [K in keyof V as K extends keyof C["defaultVariants"]
+    ? K
+    : never]: C["variants"][K];
+};
+
+/**
+ * Names of all optional variants, i.e. booleans or ones with default options.
+ */
+type OptionalVariantNames<
+  C extends VariantsConfig<V>,
+  V extends Variants = C["variants"]
+> = keyof BooleanVariants<V> | keyof DefaultVariants<C>;
+
+/**
+ * Possible options for all the optional variants.
+ *
+ * @example
+ * {
+ *   color?: "white" | "green",
+ *   rounded?: boolean | undefined
+ * }
+ */
+type OptionalOptions<
+  C extends VariantsConfig<V>,
+  V extends Variants = C["variants"]
+> = {
+  [K in keyof V as K extends OptionalVariantNames<C>
+    ? K
+    : never]?: OptionsOf<V>[K];
+};
+
+/**
+ * Possible options for all required variants.
+ *
+ * @example {
+ *   size: "small" | "large"
+ * }
+ */
+type RequiredOptions<
+  C extends VariantsConfig<V>,
+  V extends Variants = C["variants"]
+> = {
+  [K in keyof V as K extends OptionalVariantNames<C>
+    ? never
+    : K]: OptionsOf<V>[K];
 };
 
-export type VariantSelection<V extends Variants> = {
-  [VariantName in keyof V]?: StringToBool<keyof V[VariantName]>;
+/**
+ * Utility type to extract the possible options.
+ * Converts "true" | "false" options into booleans.
+ *
+ * @example
+ * OptionsOf<{
+ *   size: { small: "text-xs"; large: "text-lg" };
+ *   rounded: { true: "rounded-full" }
+ * }>
+ * ==>
+ * {
+ *   size: "text-xs" | "text-lg";
+ *   rounded: boolean;
+ * }
+ */
+type OptionsOf<V extends Variants> = {
+  [K in keyof V]: keyof V[K] extends "true" | "false" ? boolean : keyof V[K];
 };
 
-type StringToBool<T> = T extends "true" | "false" ? boolean : T;
+/**
+ * Extracts the possible options.
+ */
+export type VariantOptions<
+  C extends VariantsConfig<V>,
+  V extends Variants = C["variants"]
+> = RequiredOptions<C> & OptionalOptions<C>;
+
+/**
+ * Without this conversion step, defaultVariants and compoundVariants will
+ * allow extra keys, i.e. non-existent variants.
+ * See https://github.com/sindresorhus/type-fest/blob/main/source/simplify.d.ts
+ */
+export type Simplify<T> = {
+  [K in keyof T]: T[K];
+};
 
-export function variants<V extends Variants>({
-  base,
-  variants,
-  compoundVariants,
-  defaultVariants,
-}: VariantsConfig<V>) {
-  return (props: VariantSelection<V>) => {
+export function variants<
+  C extends VariantsConfig<V>,
+  V extends Variants = C["variants"]
+>(config: Simplify<C>) {
+  const { base, variants, compoundVariants, defaultVariants } = config;
+
+  const isBooleanVariant = (name: keyof V) => {
+    const v = variants?.[name];
+    return v && ("false" in v || "true" in v);
+  };
+
+  return (props: VariantOptions<C>) => {
     const res = [base];
 
-    const getSelected = (name: string) =>
-      props[name] ?? defaultVariants?.[name];
+    const getSelected = (name: keyof V) =>
+      (props as any)[name] ??
+      defaultVariants?.[name] ??
+      (isBooleanVariant(name) ? false : undefined);
 
     for (let name in variants) {
       const selected = getSelected(name);
-      const options: any = variants[name];
-      if (selected) res.push(options[selected]);
+      if (selected !== undefined) res.push(variants[name]?.[selected]);
     }
+
     for (let { variants, className } of compoundVariants ?? []) {
-      const isSelected = (name: string) => getSelected(name) == variants[name];
-      const allSelected = Object.keys(variants).every(isSelected);
-      if (allSelected) res.push(className);
+      const isSelected = (name: string) => getSelected(name) === variants[name];
+      if (Object.keys(variants).every(isSelected)) {
+        res.push(className);
+      }
     }
     return res.filter(Boolean).join(" ");
   };

package/src/react.ts

@@ -7,40 +7,67 @@ import {
   PropsWithoutRef,
 } from "react";
 
-import { Variants, variants, VariantsConfig, VariantSelection } from ".";
+import {
+  Variants,
+  variants,
+  VariantsConfig,
+  VariantOptions,
+  Simplify,
+} from ".";
+
+/**
+ * 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> & { className?: string };
 
-export type VariantProps<T> = T extends (props: infer VariantSelection) => any
-  ? VariantSelection
-  : never;
+export function variantProps<
+  C extends VariantsConfig<V>,
+  V extends Variants = C["variants"]
+>(config: Simplify<C>) {
+  const variantClassName = variants<C>(config);
+  return <P extends VariantProps<C>>(props: P) => {
+    const result: any = {};
 
-export function variantProps<V extends Variants>(config: VariantsConfig<V>) {
-  const mkClass = variants(config);
-  return <T extends VariantSelection<V>>(props: T) => {
-    const className = mkClass(props);
-    const result: any = { className };
+    // Pass-through all unrelated props
     for (let prop in props) {
       if (config.variants && !(prop in config.variants)) {
         result[prop] = props[prop];
       }
     }
-    return result as { className: string } & Omit<T, keyof V>;
+
+    // Add the optionally passed className prop for chaining
+    result.className = [props.className, variantClassName(props)]
+      .filter(Boolean)
+      .join(" ");
+
+    return result as { className: string } & Omit<P, keyof C["variants"]>;
   };
 }
 
 type StyledComponent<
-  P extends ElementType,
-  V extends Variants
+  T extends ElementType,
+  C extends VariantsConfig<V>,
+  V extends Variants = C["variants"]
 > = ForwardRefExoticComponent<
-  PropsWithoutRef<ComponentProps<P> & VariantSelection<V>> &
-    React.RefAttributes<P>
+  PropsWithoutRef<ComponentProps<T> & VariantOptions<C>> &
+    React.RefAttributes<T>
 >;
 
-export function styled<P extends ElementType, V extends Variants>(
-  type: P,
-  config: VariantsConfig<V>
-): StyledComponent<P, V> {
+export function styled<
+  T extends ElementType,
+  C extends VariantsConfig<V>,
+  V extends Variants = C["variants"]
+>(type: T, config: Simplify<C>): StyledComponent<T, C> {
   const styledProps = variantProps(config);
-  return forwardRef<P, ComponentProps<P> & VariantSelection<V>>((props, ref) =>
+  return forwardRef<T, ComponentProps<T> & VariantOptions<C>>((props, ref) =>
     createElement(type, { ...styledProps(props), ref })
   );
 }

package/react/package.json

@@ -1,5 +0,0 @@
-{
-  "internal": true,
-  "module": "../lib/react.js",
-  "types": "../lib/react.d.ts"
-}