Merge pull request #16 from gregberge/additional-props

feat: add additional props support

.eslintrc.json

@@ -5,5 +5,8 @@
   },
   "parser": "@typescript-eslint/parser",
   "extends": ["eslint:recommended", "plugin:@typescript-eslint/recommended"],
-  "plugins": ["@typescript-eslint"]
+  "plugins": ["@typescript-eslint"],
+  "rules": {
+    "@typescript-eslint/ban-types": "off"
+  }
 }

.npmignore

@@ -1,2 +1,3 @@
 /*
-!/dist/**/*.{ts,js}
+!/dist/index.d.ts
+!/dist/index.mjs

README.md

@@ -8,7 +8,7 @@
 
 ## Features
 
-- ⚡️ Lightweight — only 0.42kb
+- ⚡️ Lightweight — only 0.44kb
 - ✨ Autocompletion in all editors
 - 🎨 Adapt the style based on props
 - ♻️ Reuse classes with `asChild` prop

rollup.config.js

@@ -1,15 +1,17 @@
 import { swc } from "rollup-plugin-swc3";
 import ts from "rollup-plugin-ts";
 
-const swcPlugin = swc({
-  tsconfig: false,
-  jsc: {
-    parser: {
-      syntax: "typescript",
+const swcPlugin = (minify) =>
+  swc({
+    tsconfig: false,
+    minify,
+    jsc: {
+      parser: {
+        syntax: "typescript",
+      },
+      target: "es2018",
     },
-    target: "es2018",
-  },
-});
+  });
 
 const tsPlugin = ts({ transpiler: "swc" });
 
@@ -26,7 +28,21 @@ const buildEs = ({
     file: output,
     format: "es",
   },
-  plugins: [swcPlugin],
+  plugins: [swcPlugin(false)],
+});
+
+const buildMin = ({
+  input = "src/index.tsx",
+  output = "dist/index.min.mjs",
+  external = ignoreRelative,
+} = {}) => ({
+  input,
+  external,
+  output: {
+    file: output,
+    format: "es",
+  },
+  plugins: [swcPlugin(true)],
 });
 
 const buildTypes = ({
@@ -43,4 +59,4 @@ const buildTypes = ({
   plugins: [tsPlugin],
 });
 
-export default [buildEs(), buildTypes()];
+export default [buildEs(), buildMin(), buildTypes()];

src/index.test.tsx

@@ -1,7 +1,7 @@
 import { describe, expect, test, beforeEach } from "vitest";
 import { render, screen, cleanup } from "@testing-library/react";
 import { cva, VariantProps } from "class-variance-authority";
-import { twc, createTwc } from "./index";
+import { twc, createTwc, TwcComponentProps } from "./index";
 import * as React from "react";
 import { twMerge } from "tailwind-merge";
 
@@ -25,6 +25,51 @@ describe("twc", () => {
     expect(title.dataset.foo).toBe("bar");
   });
 
+  test("supports attrs", () => {
+    const Checkbox = twc.input.attrs({ type: "checkbox" })`text-xl`;
+    render(<Checkbox data-testid="checkbox" />);
+    const checkbox = screen.getByTestId("checkbox");
+    expect(checkbox).toBeDefined();
+    expect(checkbox.getAttribute("type")).toBe("checkbox");
+  });
+
+  test("supports attrs from props", () => {
+    const Checkbox = twc.input.attrs<{ $type?: string }>((props) => ({
+      type: props.$type || "checkbox",
+      "data-testid": "checkbox",
+    }))`text-xl`;
+    render(<Checkbox />);
+    const checkbox = screen.getByTestId("checkbox");
+    expect(checkbox).toBeDefined();
+    expect(checkbox.getAttribute("type")).toBe("checkbox");
+
+    cleanup();
+
+    render(<Checkbox $type="radio" />);
+    const radio = screen.getByTestId("checkbox");
+    expect(radio).toBeDefined();
+    expect(radio.getAttribute("type")).toBe("radio");
+  });
+
+  test("complex attrs support", () => {
+    type LinkProps = TwcComponentProps<"a"> & { $external?: boolean };
+
+    // Accept an $external prop that adds `target` and `rel` attributes if present
+    const Link = twc.a.attrs<LinkProps>((props) =>
+      props.$external ? { target: "_blank", rel: "noopener noreferrer" } : {},
+    )`appearance-none size-4 border-2 border-blue-500 rounded-sm bg-white`;
+
+    render(
+      <Link $external href="https://example.com">
+        My link
+      </Link>,
+    );
+    const link = screen.getByText("My link");
+    expect(link).toBeDefined();
+    expect(link.getAttribute("target")).toBe("_blank");
+    expect(link.getAttribute("rel")).toBe("noopener noreferrer");
+  });
+
   test("merges classes", () => {
     const Title = twc.h1`text-xl`;
     render(<Title className="font-medium">Title</Title>);

src/index.tsx

@@ -26,7 +26,8 @@ type Template<
   TComponent extends React.ElementType,
   TCompose extends AbstractCompose,
   TExtraProps,
-> = <TProps = undefined>(
+  TParentProps = undefined,
+> = <TProps = TParentProps>(
   strings:
     | TemplateStringsArray
     | ((
@@ -37,10 +38,24 @@ type Template<
   ResultProps<TComponent, TProps, TExtraProps, TCompose>
 >;
 
+type FirstLevelTemplate<
+  TComponent extends React.ElementType,
+  TCompose extends AbstractCompose,
+  TExtraProps,
+> = Template<TComponent, TCompose, TExtraProps> & {
+  attrs: <TProps = undefined>(
+    attrs:
+      | Record<string, any>
+      | ((
+          props: ResultProps<TComponent, TProps, TExtraProps, TCompose>,
+        ) => Record<string, any>),
+  ) => Template<TComponent, TCompose, TExtraProps, TProps>;
+};
+
 type Twc<TCompose extends AbstractCompose> = (<T extends React.ElementType>(
   component: T,
-) => Template<T, TCompose, undefined>) & {
-  [Key in keyof HTMLElementTagNameMap]: Template<
+) => FirstLevelTemplate<T, TCompose, undefined>) & {
+  [Key in keyof HTMLElementTagNameMap]: FirstLevelTemplate<
     Key,
     TCompose,
     { asChild?: boolean }
@@ -81,44 +96,62 @@ function filterProps(
   return filteredProps;
 }
 
+type Attributes = Record<string, any> | ((props: any) => Record<string, any>);
+
 export const createTwc = <TCompose extends AbstractCompose = typeof clsx>(
   config: Config<TCompose> = {},
 ) => {
-  const compose = config.compose ?? clsx;
+  const compose = config.compose || clsx;
   const shouldForwardProp =
-    config.shouldForwardProp ?? ((prop) => prop[0] !== "$");
-  const template =
-    (Component: React.ElementType) =>
-    // eslint-disable-next-line @typescript-eslint/ban-types
-    (stringsOrFn: TemplateStringsArray | Function, ...values: any[]) => {
-      const isFn = typeof stringsOrFn === "function";
-      const twClassName = isFn
-        ? ""
-        : String.raw({ raw: stringsOrFn }, ...values);
-      return React.forwardRef((props: any, ref) => {
-        const { className, asChild, ...rest } = props;
-        const filteredProps = filterProps(rest, shouldForwardProp);
-        const Comp = asChild ? Slot : Component;
-        return (
-          <Comp
-            ref={ref}
-            className={compose(
-              isFn ? stringsOrFn(props) : twClassName,
-              className,
-            )}
-            {...filteredProps}
-          />
-        );
-      });
+    config.shouldForwardProp || ((prop) => prop[0] !== "$");
+  const wrap = (Component: React.ElementType) => {
+    const createTemplate = (attrs?: Attributes) => {
+      const template = (
+        stringsOrFn: TemplateStringsArray | Function,
+        ...values: any[]
+      ) => {
+        const isFn = typeof stringsOrFn === "function";
+        const twClassName = isFn
+          ? ""
+          : String.raw({ raw: stringsOrFn }, ...values);
+        return React.forwardRef((p: any, ref) => {
+          const { className, asChild, ...rest } = p;
+          const rp =
+            typeof attrs === "function" ? attrs(p) : attrs ? attrs : {};
+          const fp = filterProps({ ...rp, ...rest }, shouldForwardProp);
+          const Comp = asChild ? Slot : Component;
+          return (
+            <Comp
+              ref={ref}
+              className={compose(
+                isFn ? stringsOrFn(p) : twClassName,
+                className,
+              )}
+              {...fp}
+            />
+          );
+        });
+      };
+
+      if (attrs === undefined) {
+        template.attrs = (attrs: Attributes) => {
+          return createTemplate(attrs);
+        };
+      }
+
+      return template;
     };
 
+    return createTemplate();
+  };
+
   return new Proxy(
     (component: React.ComponentType) => {
-      return template(component);
+      return wrap(component);
     },
     {
       get(_, name) {
-        return template(name as keyof JSX.IntrinsicElements);
+        return wrap(name as keyof JSX.IntrinsicElements);
       },
     },
   ) as any as Twc<TCompose>;

website/pages/docs/api-reference.mdx

@@ -2,7 +2,7 @@
 
 List of exports available from `react-twc` package.
 
-## `twc`
+### `twc`
 
 Builds a `twc` component.
 
@@ -12,7 +12,7 @@ import { twc } from "react-twc";
 const Title = twc.h2`font-bold`;
 ```
 
-## `createTwc`
+### `createTwc`
 
 Create a custom instance of `twc`.
 
@@ -26,12 +26,12 @@ const twx = createTwc({
 });
 ```
 
-### Options
+#### Options
 
 - `compose`: The compose function to use. Defaults to `clsx`.
 - `shouldForwardProp`: The function to use to determine if a prop should be forwarded to the underlying component. Defaults to `prop => prop[0] !== "$"`.
 
-## `cx`
+### `cx`
 
 Concatenates class names (an alias of [`clsx`](https://github.com/lukeed/clsx)).
 
@@ -40,3 +40,13 @@ import { cx } from "react-twc";
 
 const className = cx(classes);
 ```
+
+### `TwcComponentProps<Component, Compose = typeof clsx>`
+
+Returns props accepted by a `twc` component. Similar to `React.ComponentProps<"button">` with `asChild` prop and `className` type from `clsx`.
+
+```tsx
+import type { TwcComponentProps } from "react-twc";
+
+type ButtonProps = TwcComponentProps<"button">;
+```

website/pages/docs/guides/_meta.json

@@ -1,4 +1,8 @@
 {
   "as-child-prop": "asChild prop",
-  "class-name-prop": "className prop"
+  "class-name-prop": "className prop",
+  "refs": "Refs",
+  "styling-any-component": "Styling any component",
+  "additional-props": "Additional props",
+  "adapting-based-on-props": "Adapting based on props"
 }

website/pages/docs/guides/additional-props.mdx

@@ -0,0 +1,34 @@
+# Additional props
+
+To avoid unnecessary wrappers that just pass on some props to the rendered component or element, you can use the `.attrs` constructor. It allows you to attach additional props (or "attributes") to a component.
+
+## Usage
+
+Create an `input` of type "checkbox" with `twc`:
+
+```ts
+const Checkbox = twc.input.attrs({
+  type: "checkbox",
+})`appearance-none size-4 border-2 border-blue-500 rounded-sm bg-white`;
+```
+
+## Adapting attributes based on props
+
+`attrs` accepts a function to generate attributes based on input props.
+
+In this example, we create an anchor that accepts an `$external` prop and adds `target` and `rel` attributes based on its value.
+
+```ts
+import { twc, TwcComponentProps } from "react-twc";
+
+type AnchorProps = TwcComponentProps<"a"> & { $external?: boolean };
+
+// Accept an $external prop that adds `target` and `rel` attributes if present
+const Anchor = twc.a.attrs<AnchorProps>((props) =>
+  props.$external ? { target: "_blank", rel: "noopener noreferrer" } : {},
+)`appearance-none size-4 border-2 border-blue-500 rounded-sm bg-white`;
+
+render(
+  <Anchor $external href="https://cva.style">Class Variance Authority</Link>
+);
+```

website/pages/docs/guides/styling-any-component.mdx

@@ -25,3 +25,11 @@ export default () => (
   </HoverCard.Root>
 );
 ```
+
+If you need to specify some default props, you can use [additional props](/guides/additional-props). For example you can define the `sideOffset` by default using `attrs` constructor:
+
+```tsx
+const HoverCardContent = twc(HoverCard.Content).attrs({
+  sideOffset: 5,
+})`data-[side=bottom]:animate-slideUpAndFade data-[side=right]:animate-slideLeftAndFade data-[side=left]:animate-slideRightAndFade data-[side=top]:animate-slideDownAndFade w-[300px] rounded-md bg-white p-5 shadow-[hsl(206_22%_7%_/_35%)_0px_10px_38px_-10px,hsl(206_22%_7%_/_20%)_0px_10px_20px_-15px] data-[state=open]:transition-all`;
+```

website/pages/index.mdx

@@ -47,7 +47,7 @@ const Card = twc.div`rounded-lg border bg-slate-100 text-white shadow-sm`;
 
 With just one single line of code, you can create a reusable component with all these amazing features out-of-the-box:
 
-- ⚡️ Lightweight — only 0.42kb
+- ⚡️ Lightweight — only 0.44kb
 - ✨ Autocompletion in all editors
 - 🎨 Adapt the style based on props
 - ♻️ Reuse classes with `asChild` prop