classname-variants 1.0.0

package/README.md

@@ -0,0 +1,173 @@
+# classname-variants
+
+Stitches-like [variant API](https://stitches.dev/docs/variants) for plain class names.
+
+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-)!
+
+# Basics
+
+Let's aussume we want to build a button component with Tailwind CSS that comes in different sizes and colors.
+
+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_.
+
+```tsx
+const button = variants({
+  base: "rounded text-white",
+  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",
+    },
+  },
+});
+```
+
+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",
+  })}">
+    Click Me!
+  </button>
+`);
+```
+
+# Advanced Usage
+
+## Boolean variants
+
+Variants can be of type `boolean` by using `"true"` as the key:
+
+```tsx
+const button = variants({
+  base: "text-white",
+  variants: {
+    rounded: {
+      true: "rounded-full",
+    },
+  },
+});
+```
+
+## Compound variants
+
+The `compoundVariants` option can be used to apply class names based on a combination of other variants.
+
+```tsx
+const button = variants({
+  variants: {
+    color: {
+      neutral: "bg-gray-200",
+      accent: "bg-teal-400",
+    },
+    outlined: {
+      true: "border-2",
+    },
+  },
+  compoundVariants: [
+    {
+      variants: {
+        color: "accent",
+        outlined: true,
+      },
+      className: "border-teal-500",
+    },
+  ],
+});
+```
+
+## Default variants
+
+The `defaultVariants` option can be used to select a variant by default:
+
+```ts
+const button = variants({
+  variants: {
+    color: {
+      neutral: "bg-gray-200",
+      accent: "bg-teal-400",
+    },
+  },
+  defaultVariants: {
+    color: "neutral",
+  },
+});
+```
+
+# React
+
+The library contains utility functions that are useful for writing React components.
+
+It works much like `variants()` but instead of a class name string, the resulting function returns an object with props.
+
+```ts
+import { variantProps } from "classname-variants/react";
+
+const buttonProps = variantProps({
+  base: "rounded-md text-white",
+  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 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>;
+
+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 with class names 💅
+
+Things can be taken even a step further, resulting in a _styled-components_ like way of defining reusable components:
+
+```tsx
+import { styled } from "classname-variants/react";
+
+const Button = styled("button", {
+  variants: {
+    size: {
+      small: "text-xs",
+      large: "text-base",
+    },
+  },
+});
+```
+
+# License
+
+MIT

package/example.tsx

@@ -0,0 +1,40 @@
+import React from "react";
+import ReactDOM from "react-dom";
+import { styled } from "./src/react";
+
+const Button = styled("button", {
+  base: "rounded-md px-5 py-2 text-white",
+  variants: {
+    color: {
+      neutral: "bg-gray-500",
+      accent: "bg-teal-500",
+    },
+    outlined: {
+      true: "border-2",
+    },
+  },
+  compoundVariants: [
+    {
+      variants: {
+        color: "accent",
+        outlined: true,
+      },
+      className: "border-teal-800",
+    },
+  ],
+});
+
+function App() {
+  return (
+    <>
+      <Button color="neutral" onClick={console.log}>
+        Neutral
+      </Button>
+      <Button color="accent" outlined onClick={console.log}>
+        Accent + Outlined
+      </Button>
+    </>
+  );
+}
+
+ReactDOM.render(<App />, document.getElementById("root"));

package/index.html

@@ -0,0 +1,16 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta
+      name="viewport"
+      content="width=device-width, initial-scale=1.0, user-scalable=no"
+    />
+    <title>classname-variants</title>
+    <script src="https://cdn.tailwindcss.com"></script>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="./example.tsx"></script>
+  </body>
+</html>

package/lib/index.d.ts

@@ -0,0 +1,18 @@
+export declare type VariantDefinitions = Record<string, string>;
+export declare type Variants = Record<string, VariantDefinitions>;
+export declare type VariantsConfig<V extends Variants> = {
+    base?: string;
+    variants?: V;
+    compoundVariants?: CompoundVariant<V>[];
+    defaultVariants?: VariantSelection<V>;
+};
+export declare type CompoundVariant<V extends Variants> = {
+    variants: VariantSelection<V>;
+    className: string;
+};
+export declare type VariantSelection<V extends Variants> = {
+    [VariantName in keyof V]?: StringToBool<keyof V[VariantName]>;
+};
+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 {};

package/lib/index.js

@@ -0,0 +1,19 @@
+export function variants({ base, variants, compoundVariants, defaultVariants, }) {
+    return (props) => {
+        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]; };
+        for (let name in variants) {
+            const selected = getSelected(name);
+            const options = variants[name];
+            if (selected)
+                res.push(options[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)
+                res.push(className);
+        }
+        return res.filter(Boolean).join(" ");
+    };
+}

package/lib/react.d.ts

@@ -0,0 +1,9 @@
+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) => {
+    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>;
+export {};

package/lib/react.js

@@ -0,0 +1,19 @@
+import { createElement, forwardRef, } from "react";
+import { variants } from ".";
+export function variantProps(config) {
+    const mkClass = variants(config);
+    return (props) => {
+        const className = mkClass(props);
+        const result = { className };
+        for (let prop in props) {
+            if (config.variants && !(prop in config.variants)) {
+                result[prop] = props[prop];
+            }
+        }
+        return result;
+    };
+}
+export function styled(type, config) {
+    const styledProps = variantProps(config);
+    return forwardRef((props, ref) => createElement(type, { ...styledProps(props), ref }));
+}

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "classname-variants",
+  "version": "1.0.0",
+  "description": "Variant API for plain class names",
+  "author": "Felix Gnass <fgnass@gmail.com>",
+  "license": "MIT",
+  "repository": "fgnass/classname-variants",
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "start": "npx vite"
+  },
+  "keywords": [
+    "tailwind",
+    "css",
+    "classname",
+    "variants",
+    "react"
+  ],
+  "devDependencies": {
+    "@types/react": "^17.0.39",
+    "react": "^17.0.2",
+    "react-dom": "^17.0.2",
+    "typescript": "^4.5.5"
+  }
+}

package/react/package.json

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

package/src/index.ts

@@ -0,0 +1,47 @@
+export type VariantDefinitions = Record<string, string>;
+
+export type Variants = Record<string, VariantDefinitions>;
+
+export type VariantsConfig<V extends Variants> = {
+  base?: string;
+  variants?: V;
+  compoundVariants?: CompoundVariant<V>[];
+  defaultVariants?: VariantSelection<V>;
+};
+
+export type CompoundVariant<V extends Variants> = {
+  variants: VariantSelection<V>;
+  className: string;
+};
+
+export type VariantSelection<V extends Variants> = {
+  [VariantName in keyof V]?: StringToBool<keyof V[VariantName]>;
+};
+
+type StringToBool<T> = T extends "true" | "false" ? boolean : T;
+
+export function variants<V extends Variants>({
+  base,
+  variants,
+  compoundVariants,
+  defaultVariants,
+}: VariantsConfig<V>) {
+  return (props: VariantSelection<V>) => {
+    const res = [base];
+
+    const getSelected = (name: string) =>
+      props[name] ?? defaultVariants?.[name];
+
+    for (let name in variants) {
+      const selected = getSelected(name);
+      const options: any = variants[name];
+      if (selected) res.push(options[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);
+    }
+    return res.filter(Boolean).join(" ");
+  };
+}

package/src/react.ts

@@ -0,0 +1,46 @@
+import {
+  ComponentProps,
+  createElement,
+  ElementType,
+  forwardRef,
+  ForwardRefExoticComponent,
+  PropsWithoutRef,
+} from "react";
+
+import { Variants, variants, VariantsConfig, VariantSelection } 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) => {
+    const className = mkClass(props);
+    const result: any = { className };
+    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>;
+  };
+}
+
+type StyledComponent<
+  P extends ElementType,
+  V extends Variants
+> = ForwardRefExoticComponent<
+  PropsWithoutRef<ComponentProps<P> & VariantSelection<V>> &
+    React.RefAttributes<P>
+>;
+
+export function styled<P extends ElementType, V extends Variants>(
+  type: P,
+  config: VariantsConfig<V>
+): StyledComponent<P, V> {
+  const styledProps = variantProps(config);
+  return forwardRef<P, ComponentProps<P> & VariantSelection<V>>((props, ref) =>
+    createElement(type, { ...styledProps(props), ref })
+  );
+}

package/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2019",
+    "lib": ["ESNext", "dom"],
+    "jsx": "react",
+    "module": "ESNext",
+    "moduleResolution": "node",
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "strict": true,
+    "forceConsistentCasingInFileNames": true,
+    "isolatedModules": true,
+    "outDir": "lib",
+    "declaration": true
+  },
+  "include": ["./src"]
+}