classname-variants 1.0.1 → 1.0.2

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.
@@ -168,6 +170,48 @@ const Button = styled("button", {
 });
 ```
 
+# 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

@@ -3,37 +3,43 @@ import ReactDOM from "react-dom";
 import { styled } from "./src/react";
 
 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>
+    </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,9 @@
 import { ComponentProps, ElementType, ForwardRefExoticComponent, PropsWithoutRef } from "react";
-import { Variants, VariantsConfig, VariantSelection } from ".";
+import { Variants, VariantsConfig, VariantOptions, Simplify } 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) => {
+export declare function variantProps<C extends VariantsConfig<V>, V extends Variants = C["variants"]>(config: Simplify<C>): <T extends VariantOptions<C, C["variants"]>>(props: T) => {
     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<T, keyof C["variants"]>;
+declare type StyledComponent<P extends ElementType, C extends VariantsConfig<V>, V extends Variants = C["variants"]> = ForwardRefExoticComponent<PropsWithoutRef<ComponentProps<P> & VariantOptions<C>> & React.RefAttributes<P>>;
+export declare function styled<P extends ElementType, C extends VariantsConfig<V>, V extends Variants = C["variants"]>(type: P, config: Simplify<C>): StyledComponent<P, C>;
 export {};

package/lib/react.js

@@ -1,5 +1,5 @@
 import { createElement, forwardRef, } from "react";
-import { variants } from ".";
+import { variants, } from ".";
 export function variantProps(config) {
     const mkClass = variants(config);
     return (props) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "classname-variants",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "Variant API for plain class names",
   "author": "Felix Gnass <fgnass@gmail.com>",
   "license": "MIT",

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,15 +7,24 @@ import {
   PropsWithoutRef,
 } from "react";
 
-import { Variants, variants, VariantsConfig, VariantSelection } from ".";
+import {
+  Variants,
+  variants,
+  VariantsConfig,
+  VariantOptions,
+  Simplify,
+} from ".";
 
 export type VariantProps<T> = T extends (props: infer VariantSelection) => any
   ? VariantSelection
   : never;
 
-export function variantProps<V extends Variants>(config: VariantsConfig<V>) {
-  const mkClass = variants(config);
-  return <T extends VariantSelection<V>>(props: T) => {
+export function variantProps<
+  C extends VariantsConfig<V>,
+  V extends Variants = C["variants"]
+>(config: Simplify<C>) {
+  const mkClass = variants<C>(config);
+  return <T extends VariantOptions<C>>(props: T) => {
     const className = mkClass(props);
     const result: any = { className };
     for (let prop in props) {
@@ -23,24 +32,26 @@ export function variantProps<V extends Variants>(config: VariantsConfig<V>) {
         result[prop] = props[prop];
       }
     }
-    return result as { className: string } & Omit<T, keyof V>;
+    return result as { className: string } & Omit<T, keyof C["variants"]>;
   };
 }
 
 type StyledComponent<
   P extends ElementType,
-  V extends Variants
+  C extends VariantsConfig<V>,
+  V extends Variants = C["variants"]
 > = ForwardRefExoticComponent<
-  PropsWithoutRef<ComponentProps<P> & VariantSelection<V>> &
+  PropsWithoutRef<ComponentProps<P> & VariantOptions<C>> &
     React.RefAttributes<P>
 >;
 
-export function styled<P extends ElementType, V extends Variants>(
-  type: P,
-  config: VariantsConfig<V>
-): StyledComponent<P, V> {
+export function styled<
+  P extends ElementType,
+  C extends VariantsConfig<V>,
+  V extends Variants = C["variants"]
+>(type: P, config: Simplify<C>): StyledComponent<P, C> {
   const styledProps = variantProps(config);
-  return forwardRef<P, ComponentProps<P> & VariantSelection<V>>((props, ref) =>
+  return forwardRef<P, ComponentProps<P> & VariantOptions<C>>((props, ref) =>
     createElement(type, { ...styledProps(props), ref })
   );
 }