@boxcustodia/library 2.0.0-alpha.2 → 2.0.0-alpha.20

package/src/components/button/button.stories.tsx

@@ -0,0 +1,338 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { cva, type VariantProps } from "class-variance-authority";
+import { Flame, SearchIcon } from "lucide-react";
+import { type ComponentProps } from "react";
+import { BaseButton, Button, buttonVariants } from "../../components";
+import { cn } from "../../lib";
+
+/**
+ * Primary action trigger built on the [Base UI Button](https://base-ui.com/react/components/button) primitive.
+ *
+ * **Loading** — pass an async function to `onClick` and loading state is managed automatically.
+ * Control it externally with the `loading` prop. The spinner overlays content while preserving
+ * the button's original dimensions so layout never shifts.
+ *
+ * **Custom elements** — use the `render` prop to swap the underlying element.
+ * For links, apply `buttonVariants` directly to a plain `<a>` — Base UI always sets
+ * `role="button"` which overrides the semantic link role on `<a>` elements rendered via `render`.
+ *
+ * **Extension** — use `BaseButton` to build fully custom variants without inheriting any styles.
+ */
+const meta: Meta<typeof Button> = {
+  title: "Components/Button",
+  component: Button,
+  args: {
+    children: "Click me",
+  },
+  parameters: { layout: "centered" },
+};
+
+export default meta;
+type Story = StoryObj<typeof Button>;
+
+export const Default: Story = {};
+
+export const Variants: Story = {
+  render: (args) => (
+    <div className="flex flex-wrap items-center gap-3">
+      {(
+        [
+          "default",
+          "outline",
+          "secondary",
+          "ghost",
+          "link",
+          "error",
+          "success",
+          "warning",
+        ] as const
+      ).map((variant) => (
+        <Button key={variant} {...args} variant={variant}>
+          {variant}
+        </Button>
+      ))}
+    </div>
+  ),
+};
+
+export const Sizes: Story = {
+  render: () => {
+    const textSizes = ["xs", "sm", "default", "lg"] as const;
+    const iconSizes = ["icon-xs", "icon-sm", "icon", "icon-lg"] as const;
+
+    return (
+      <div className="space-y-6">
+        <div className="flex flex-wrap items-end gap-4">
+          {textSizes.map((size) => (
+            <div key={size} className="flex flex-col items-center gap-2">
+              <p className="text-xs text-muted-foreground">{size}</p>
+              <Button size={size}>Click me</Button>
+            </div>
+          ))}
+        </div>
+        <div className="flex flex-wrap items-end gap-4">
+          {iconSizes.map((size) => (
+            <div key={size} className="flex flex-col items-center gap-2">
+              <p className="text-xs text-muted-foreground">{size}</p>
+              <Button size={size}>
+                <Flame />
+              </Button>
+            </div>
+          ))}
+        </div>
+      </div>
+    );
+  },
+};
+
+/**
+ * Compose icons directly as children. Position is determined by JSX order —
+ * place the icon before or after the label. Use an icon-only size (`icon`,
+ * `icon-sm`, etc.) for square icon buttons.
+ */
+export const WithIcon: Story = {
+  render: (args) => (
+    <div className="flex flex-wrap items-center gap-4">
+      <Button {...args}>
+        <SearchIcon />
+        Search
+      </Button>
+      <Button {...args}>
+        Search
+        <SearchIcon />
+      </Button>
+      <Button size="icon">
+        <SearchIcon />
+      </Button>
+    </div>
+  ),
+  parameters: {
+    docs: {
+      source: {
+        code: `<Button>
+  <SearchIcon />
+  Search
+</Button>
+
+<Button>
+  Search
+  <SearchIcon />
+</Button>
+
+<Button size="icon">
+  <SearchIcon />
+</Button>`,
+      },
+    },
+  },
+};
+
+/**
+ * When `onClick` returns a `Promise`, loading activates automatically and stops when
+ * the Promise settles — no external state needed. Pass `loading` directly to control it
+ * from outside (e.g., from a form submission handler or mutation hook).
+ *
+ * While loading, the button is non-interactive (`pointer-events-none`, `aria-busy`)
+ * and the spinner overlays content without changing the button's dimensions.
+ */
+export const Loading: Story = {
+  render: () => {
+    const sleep = (): Promise<void> =>
+      new Promise((resolve) => setTimeout(resolve, 2000));
+
+    return (
+      <div className="space-y-10">
+        <section className="space-y-3">
+          <h2 className="text-sm font-semibold">Auto — async onClick</h2>
+          <p className="text-sm text-muted-foreground">
+            Click any button. Loading starts when the Promise begins and stops
+            when it resolves.
+          </p>
+          <div className="flex flex-wrap items-center gap-3">
+            <Button onClick={sleep}>Save</Button>
+            <Button onClick={sleep}>
+              <SearchIcon />
+              Search
+            </Button>
+            <Button onClick={sleep} size="icon">
+              <SearchIcon />
+            </Button>
+          </div>
+        </section>
+
+        <section className="space-y-3">
+          <h2 className="text-sm font-semibold">Controlled</h2>
+          <p className="text-sm text-muted-foreground">
+            Pass the <code>loading</code> prop directly to control state
+            externally.
+          </p>
+          <div className="flex flex-wrap items-center gap-3">
+            <Button loading>Save</Button>
+            <Button loading>
+              <SearchIcon />
+              Search
+            </Button>
+            <Button loading size="icon">
+              <SearchIcon />
+            </Button>
+          </div>
+        </section>
+
+        <section className="space-y-3">
+          <h2 className="text-sm font-semibold">All sizes</h2>
+          <div className="flex flex-wrap items-end gap-4">
+            {(["xs", "sm", "default", "lg"] as const).map((size) => (
+              <div key={size} className="flex flex-col items-center gap-2">
+                <p className="text-xs text-muted-foreground">{size}</p>
+                <Button loading size={size}>
+                  Save
+                </Button>
+              </div>
+            ))}
+            {(["icon-xs", "icon-sm", "icon", "icon-lg"] as const).map(
+              (size) => (
+                <div key={size} className="flex flex-col items-center gap-2">
+                  <p className="text-xs text-muted-foreground">{size}</p>
+                  <Button loading size={size}>
+                    <SearchIcon />
+                  </Button>
+                </div>
+              ),
+            )}
+          </div>
+        </section>
+
+        <section className="space-y-3">
+          <h2 className="text-sm font-semibold">All variants</h2>
+          <div className="flex flex-wrap items-center gap-3">
+            {(
+              [
+                "default",
+                "outline",
+                "secondary",
+                "ghost",
+                "error",
+                "success",
+                "warning",
+              ] as const
+            ).map((variant) => (
+              <Button key={variant} onClick={sleep} variant={variant}>
+                {variant}
+              </Button>
+            ))}
+          </div>
+        </section>
+      </div>
+    );
+  },
+};
+
+/**
+ * Use the `render` prop to render the button as any element while keeping all styles
+ * and behavior. For navigation links, use `buttonVariants` on a plain `<a>` tag instead —
+ * Base UI always applies `role="button"` which overrides the semantic `<a>` role.
+ *
+ * ```tsx
+ * // Render as a different element
+ * <Button render={<div />}>Custom element</Button>
+ *
+ * // Link styled as a button — correct pattern for navigation
+ * <a href="/dashboard" className={buttonVariants({ variant: "outline" })}>
+ *   Go to dashboard
+ * </a>
+ * ```
+ */
+export const Render: Story = {
+  render: (args) => (
+    <div className="flex flex-wrap items-center gap-4">
+      <Button {...args} render={<div />}>
+        Rendered as div
+      </Button>
+      <a href="#" className={buttonVariants({ variant: "outline" })}>
+        Link as button
+      </a>
+    </div>
+  ),
+  parameters: {
+    docs: {
+      source: {
+        code: `<Button render={<div />}>Rendered as div</Button>
+
+<a href="/dashboard" className={buttonVariants({ variant: "outline" })}>
+  Link as button
+</a>`,
+      },
+    },
+  },
+};
+
+const customButtonVariants = cva(
+  [
+    "inline-flex items-center justify-center gap-2 rounded-lg px-4 py-2",
+    "text-sm font-medium transition-all outline-none select-none",
+    "focus-visible:ring-3 focus-visible:ring-ring/50",
+    "disabled:pointer-events-none disabled:opacity-50",
+  ],
+  {
+    variants: {
+      variant: {
+        white: "border border-border bg-white text-primary",
+        black: "bg-black text-white",
+      },
+    },
+    defaultVariants: {
+      variant: "white",
+    },
+  },
+);
+
+type BaseButtonProps = ComponentProps<typeof BaseButton>;
+interface CustomButtonProps
+  extends BaseButtonProps,
+    VariantProps<typeof customButtonVariants> {}
+
+const CustomButton = ({ variant, className, ...props }: CustomButtonProps) => (
+  <BaseButton
+    className={cn(customButtonVariants({ variant }), className)}
+    {...props}
+  />
+);
+
+/**
+ * `BaseButton` is an unstyled wrapper around the Base UI primitive. Use it to build
+ * fully custom button variants without inheriting any library styles.
+ * It supports all native button props plus `loading` and the `render` prop.
+ *
+ * ```tsx
+ * import { type ComponentProps } from 'react';
+ * import { cva, type VariantProps } from 'class-variance-authority';
+ * import { BaseButton, cn } from '@boxcustodia/library';
+ *
+ * const myVariants = cva(
+ *   'inline-flex items-center justify-center gap-2 rounded-lg px-4 py-2 text-sm font-medium transition-all outline-none disabled:pointer-events-none disabled:opacity-50',
+ *   {
+ *     variants: {
+ *       variant: {
+ *         white: 'border border-border bg-white text-primary',
+ *         black: 'bg-black text-white',
+ *       },
+ *     },
+ *     defaultVariants: { variant: 'white' },
+ *   },
+ * );
+ *
+ * type Props = ComponentProps<typeof BaseButton> & VariantProps<typeof myVariants>;
+ *
+ * export const CustomButton = ({ variant, className, ...props }: Props) => (
+ *   <BaseButton className={cn(myVariants({ variant }), className)} {...props} />
+ * );
+ * ```
+ */
+export const CustomVariants: Story = {
+  render: () => (
+    <div className="flex flex-wrap items-center gap-4">
+      <CustomButton variant="white">White button</CustomButton>
+      <CustomButton variant="black">Black button</CustomButton>
+    </div>
+  ),
+};

package/src/components/button/button.test.tsx

@@ -0,0 +1,242 @@
+import { act, render, screen, waitFor } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { createRef, useState } from "react";
+import { describe, expect, it, vi } from "vitest";
+import { BaseButton, Button } from "../../components";
+
+describe("Button component", () => {
+  it("should render correctly", () => {
+    render(<Button />);
+    const button = screen.getByRole("button");
+
+    expect(button).toBeInTheDocument();
+    expect(button).toHaveAttribute("data-slot", "button");
+  });
+
+  it("should render children correctly", () => {
+    render(<Button>Click me</Button>);
+    const button = screen.getByRole("button");
+
+    expect(button).toHaveTextContent("Click me");
+  });
+
+  it("should render as custom element via render prop", () => {
+    render(
+      <Button nativeButton={false} render={<a href="#">Click me</a>}>
+        Click me
+      </Button>,
+    );
+
+    const button = screen.getByRole("button");
+    expect(button).toBeInTheDocument();
+    expect(button).toHaveTextContent("Click me");
+    expect(button.tagName.toLowerCase()).toBe("a");
+  });
+
+  it("should accept className prop alongside variant classes", () => {
+    const TEST_CLASS = "lorem";
+    render(<Button className={TEST_CLASS} />);
+    const button = screen.getByRole("button");
+
+    expect(button).toHaveClass(TEST_CLASS);
+    expect(button).toHaveClass("inline-flex");
+  });
+
+  it("should accept ref prop", () => {
+    const ref = createRef<HTMLButtonElement>();
+    render(<Button ref={ref} />);
+
+    expect(ref.current).not.toBeNull();
+    expect(ref.current).toBeInstanceOf(HTMLButtonElement);
+  });
+
+  it("defaults variant to 'default' on data-variant when omitted", () => {
+    render(<Button />);
+    const button = screen.getByRole("button");
+
+    expect(button).toHaveAttribute("data-variant", "default");
+    expect(button).toHaveClass("bg-primary");
+  });
+
+  it.each([
+    ["default", "bg-primary"],
+    ["outline", "border-border"],
+    ["secondary", "bg-secondary"],
+    ["ghost", "hover:bg-muted"],
+    ["error", "bg-error"],
+    ["success", "bg-success"],
+    ["warning", "bg-warning"],
+    ["link", "text-primary"],
+  ] as const)("applies variant '%s' classes and data-variant attribute", (variant, expectedClass) => {
+    render(<Button variant={variant} />);
+    const button = screen.getByRole("button");
+
+    expect(button).toHaveAttribute("data-variant", variant);
+    expect(button).toHaveClass(expectedClass);
+  });
+
+  it.each([
+    ["default", "h-8"],
+    ["xs", "h-6"],
+    ["sm", "h-7"],
+    ["lg", "h-9"],
+    ["icon", "size-8"],
+    ["icon-xs", "size-6"],
+    ["icon-sm", "size-7"],
+    ["icon-lg", "size-9"],
+  ] as const)("applies size '%s' classes", (size, expectedClass) => {
+    render(<Button size={size} />);
+    const button = screen.getByRole("button");
+
+    expect(button).toHaveClass(expectedClass);
+  });
+});
+
+describe("BaseButton loading behavior", () => {
+  it("should set data-loading and aria-busy when loading is true", () => {
+    render(<BaseButton loading>Click me</BaseButton>);
+    const button = screen.getByRole("button");
+
+    expect(button).toHaveAttribute("data-loading");
+    expect(button).toHaveAttribute("aria-busy", "true");
+    expect(screen.getByTestId("btn-loader")).toBeInTheDocument();
+  });
+
+  it("should omit data-loading and aria-busy when loading is false", () => {
+    render(<BaseButton loading={false}>Click me</BaseButton>);
+    const button = screen.getByRole("button");
+
+    expect(button).not.toHaveAttribute("data-loading");
+    expect(button).not.toHaveAttribute("aria-busy");
+    expect(screen.queryByTestId("btn-loader")).not.toBeInTheDocument();
+  });
+
+  it("invokes a synchronous onClick handler on click", async () => {
+    const onClick = vi.fn();
+    render(<BaseButton onClick={onClick}>Click me</BaseButton>);
+
+    await userEvent.click(screen.getByRole("button"));
+
+    expect(onClick).toHaveBeenCalledTimes(1);
+  });
+
+  it("does not blow up on click when onClick is not provided", async () => {
+    render(<BaseButton>Click me</BaseButton>);
+
+    await userEvent.click(screen.getByRole("button"));
+
+    expect(screen.getByRole("button")).toBeInTheDocument();
+  });
+
+  it("toggles internal loading state across an async onClick lifecycle", async () => {
+    let resolve!: () => void;
+    const onClick = vi.fn(
+      () =>
+        new Promise<void>((res) => {
+          resolve = res;
+        }),
+    );
+
+    render(<BaseButton onClick={onClick}>Click me</BaseButton>);
+    const button = screen.getByRole("button");
+
+    await userEvent.click(button);
+
+    await waitFor(() => {
+      expect(button).toHaveAttribute("data-loading");
+    });
+    expect(button).toHaveAttribute("aria-busy", "true");
+    expect(screen.getByTestId("btn-loader")).toBeInTheDocument();
+
+    await act(async () => {
+      resolve();
+    });
+
+    await waitFor(() => {
+      expect(button).not.toHaveAttribute("data-loading");
+    });
+    expect(screen.queryByTestId("btn-loader")).not.toBeInTheDocument();
+  });
+
+  it("clears loading state even when the onClick promise rejects", async () => {
+    // The component re-throws via `await promise.finally(...)`, so the
+    // rejection escapes as an unhandled rejection on the Node process. Swallow
+    // the expected one for the duration of this test only.
+    const onUnhandled = (err: unknown) => {
+      if (err instanceof Error && err.message === "boom") return;
+      throw err;
+    };
+    process.on("unhandledRejection", onUnhandled);
+
+    const onClick = vi.fn(() => Promise.reject(new Error("boom")));
+    render(<BaseButton onClick={onClick}>Click me</BaseButton>);
+    const button = screen.getByRole("button");
+
+    try {
+      await userEvent.click(button);
+
+      await waitFor(() => {
+        expect(button).not.toHaveAttribute("data-loading");
+      });
+      expect(onClick).toHaveBeenCalledTimes(1);
+    } finally {
+      process.off("unhandledRejection", onUnhandled);
+    }
+  });
+
+  it("ignores clicks while already loading", async () => {
+    const onClick = vi.fn();
+    render(
+      <BaseButton loading onClick={onClick}>
+        Click me
+      </BaseButton>,
+    );
+
+    await userEvent.click(screen.getByRole("button"));
+
+    expect(onClick).not.toHaveBeenCalled();
+  });
+
+  it("respects controlled loading state from parent", async () => {
+    function Wrapper() {
+      const [loading, setLoading] = useState(false);
+      return (
+        <>
+          <BaseButton loading={loading}>Action</BaseButton>
+          <button type="button" onClick={() => setLoading(true)}>
+            toggle
+          </button>
+        </>
+      );
+    }
+
+    render(<Wrapper />);
+    const action = screen.getByRole("button", { name: "Action" });
+
+    expect(action).not.toHaveAttribute("data-loading");
+
+    await userEvent.click(screen.getByRole("button", { name: "toggle" }));
+
+    expect(action).toHaveAttribute("data-loading");
+    expect(screen.getByTestId("btn-loader")).toBeInTheDocument();
+  });
+
+  it("renders children alongside the loader while loading", () => {
+    render(<BaseButton loading>Visible label</BaseButton>);
+
+    const button = screen.getByRole("button");
+    expect(button).toHaveTextContent("Visible label");
+    expect(screen.getByTestId("btn-loader")).toBeInTheDocument();
+  });
+
+  it("forwards style and arbitrary props to the underlying button", () => {
+    render(
+      <BaseButton style={{ color: "rgb(0, 128, 0)" }} data-testid="bb">
+        Styled
+      </BaseButton>,
+    );
+
+    const button = screen.getByTestId("bb");
+    expect(button).toHaveStyle({ color: "rgb(0, 128, 0)" });
+  });
+});

package/src/components/button/button.tsx

@@ -0,0 +1,73 @@
+"use client";
+
+import { cva, type VariantProps } from "class-variance-authority";
+import { type ComponentProps } from "react";
+import { cn } from "../../lib";
+import { BaseButton } from "./components/base-button";
+
+const buttonVariants = cva(
+  [
+    "group/button relative inline-flex shrink-0 items-center justify-center gap-1 rounded-lg border border-transparent bg-clip-padding",
+    "text-sm font-medium whitespace-nowrap transition-all outline-none select-none",
+    "focus-visible:border-ring focus-visible:ring-3 focus-visible:ring-ring/50",
+    "active:not-aria-[haspopup]:translate-y-px",
+    "disabled:pointer-events-none disabled:opacity-50",
+    "aria-invalid:border-destructive aria-invalid:ring-3 aria-invalid:ring-destructive/20 dark:aria-invalid:border-destructive/50 dark:aria-invalid:ring-destructive/40",
+    "[&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
+    "[&[data-loading]]:text-transparent",
+    "[&[data-loading]>*:not([data-loader])]:invisible",
+    "[&[data-loading]]:pointer-events-none",
+  ],
+  {
+    variants: {
+      variant: {
+        default:
+          "bg-primary text-primary-foreground hover:bg-primary/90 [--btn-loader-color:var(--color-primary-foreground)]",
+        outline:
+          "border-border hover:bg-muted hover:text-foreground aria-expanded:bg-muted aria-expanded:text-foreground dark:border-input dark:hover:bg-input/50 [--btn-loader-color:var(--color-foreground)]",
+        secondary:
+          "bg-secondary text-secondary-foreground hover:bg-secondary/80 aria-expanded:bg-secondary aria-expanded:text-secondary-foreground [--btn-loader-color:var(--color-secondary-foreground)]",
+        ghost:
+          "hover:bg-muted hover:text-foreground aria-expanded:bg-muted aria-expanded:text-foreground dark:hover:bg-muted/50 [--btn-loader-color:var(--color-foreground)]",
+        error:
+          "bg-error text-error-foreground hover:bg-error/90 [--btn-loader-color:var(--color-error-foreground)]",
+        success:
+          "bg-success text-success-foreground hover:bg-success/90 [--btn-loader-color:var(--color-success-foreground)]",
+        warning:
+          "bg-warning text-warning-foreground hover:bg-warning/90 [--btn-loader-color:var(--color-warning-foreground)]",
+        link: "text-primary underline-offset-4 hover:underline [--btn-loader-color:var(--color-primary)]",
+      },
+      size: {
+        default: "h-8 px-2.5",
+        xs: "h-6 rounded-[min(var(--radius-md),10px)] px-2 text-xs in-data-[slot=button-group]:rounded-lg [&_svg:not([class*='size-'])]:size-3",
+        sm: "h-7 rounded-[min(var(--radius-md),12px)] px-2.5 text-[0.8rem] in-data-[slot=button-group]:rounded-lg [&_svg:not([class*='size-'])]:size-3.5",
+        lg: "h-9 px-2.5",
+        icon: "size-8",
+        "icon-xs":
+          "size-6 rounded-[min(var(--radius-md),10px)] in-data-[slot=button-group]:rounded-lg [&_svg:not([class*='size-'])]:size-3",
+        "icon-sm":
+          "size-7 rounded-[min(var(--radius-md),12px)] in-data-[slot=button-group]:rounded-lg",
+        "icon-lg": "size-9",
+      },
+    },
+    defaultVariants: {
+      variant: "default",
+      size: "default",
+    },
+  },
+);
+
+type BaseButtonProps = ComponentProps<typeof BaseButton>;
+type Props = BaseButtonProps & VariantProps<typeof buttonVariants>;
+
+const Button = ({ variant, size, className, ...rest }: Props) => {
+  return (
+    <BaseButton
+      {...rest}
+      className={cn(buttonVariants({ variant, size }), className)}
+      data-variant={variant || "default"}
+    />
+  );
+};
+
+export { Button, buttonVariants };