@dowel-ui/react 0.1.0

package/src/components/toast/toast.stories.tsx

@@ -0,0 +1,167 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+
+import { Button } from "@/components/button";
+
+import { Toaster, type ToastPosition } from "./toast";
+import { toast } from "./toast-store";
+
+const meta = {
+  title: "Feedback/Toast",
+  component: Toaster,
+  args: { position: "bottom-right" },
+  argTypes: {
+    position: {
+      control: "select",
+      options: [
+        "top-left",
+        "top-center",
+        "top-right",
+        "bottom-left",
+        "bottom-center",
+        "bottom-right",
+      ] satisfies ToastPosition[],
+    },
+    duration: { control: { type: "number", min: 1000, max: 20000, step: 500 } },
+  },
+} satisfies Meta<typeof Toaster>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  render: (args) => (
+    <>
+      <Button onClick={() => toast("Project created")}>Show toast</Button>
+      <Toaster {...args} />
+    </>
+  ),
+};
+
+export const Variants: Story = {
+  render: (args) => (
+    <>
+      <div className="flex flex-wrap gap-2">
+        <Button variant="outline" onClick={() => toast("Saved")}>
+          Default
+        </Button>
+        <Button variant="outline" onClick={() => toast.success("Deployment succeeded")}>
+          Success
+        </Button>
+        <Button variant="outline" onClick={() => toast.info("Build queued")}>
+          Info
+        </Button>
+        <Button variant="outline" onClick={() => toast.warning("Approaching your quota")}>
+          Warning
+        </Button>
+        <Button variant="outline" onClick={() => toast.error("Payment failed")}>
+          Error
+        </Button>
+      </div>
+      <Toaster {...args} />
+    </>
+  ),
+};
+
+export const WithDescription: Story = {
+  render: (args) => (
+    <>
+      <Button
+        onClick={() =>
+          toast.success("Project created", {
+            description: "acme-inc is ready. Deploy when you are.",
+          })
+        }
+      >
+        Show toast
+      </Button>
+      <Toaster {...args} />
+    </>
+  ),
+};
+
+/** An action needs alt text: "Undo" alone is meaningless once the toast is gone. */
+export const WithAction: Story = {
+  render: (args) => (
+    <>
+      <Button
+        onClick={() =>
+          toast("Message archived", {
+            action: {
+              label: "Undo",
+              altText: "Undo archiving the message",
+              onClick: () => toast.success("Message restored"),
+            },
+          })
+        }
+      >
+        Archive message
+      </Button>
+      <Toaster {...args} />
+    </>
+  ),
+};
+
+export const Persistent: Story = {
+  render: (args) => (
+    <>
+      <Button
+        variant="outline"
+        onClick={() =>
+          toast.custom({
+            title: "Connection lost",
+            description: "Reconnecting…",
+            variant: "destructive",
+            duration: Infinity,
+          })
+        }
+      >
+        Show until dismissed
+      </Button>
+      <Toaster {...args} />
+    </>
+  ),
+};
+
+export const Promise: Story = {
+  render: (args) => (
+    <>
+      <Button
+        variant="outline"
+        onClick={() => {
+          const work = new window.Promise<string>((resolve) => {
+            window.setTimeout(() => {
+              resolve("acme-inc");
+            }, 1500);
+          });
+
+          void toast.promise(work, {
+            loading: "Creating project…",
+            success: (name) => `Created ${name}`,
+            error: "Could not create the project",
+          });
+        }}
+      >
+        Create project
+      </Button>
+      <Toaster {...args} />
+    </>
+  ),
+};
+
+export const Stacking: Story = {
+  render: (args) => (
+    <>
+      <Button
+        variant="outline"
+        onClick={() => {
+          for (let index = 1; index <= 6; index += 1) {
+            toast(`Event ${String(index)}`);
+          }
+        }}
+      >
+        Raise six toasts
+      </Button>
+      <Toaster {...args} />
+    </>
+  ),
+};

package/src/components/toast/toast.test.tsx

@@ -0,0 +1,306 @@
+import { act, render, screen, waitFor } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { expectNoA11yViolations } from "../../../test/a11y";
+import { Toaster } from "./toast";
+import { TOAST_LIMIT, resetToasts, toast } from "./toast-store";
+
+afterEach(() => {
+  act(() => {
+    resetToasts();
+  });
+});
+
+function raise(fn: () => void) {
+  act(() => {
+    fn();
+  });
+}
+
+describe("toast store", () => {
+  it("returns the id it created", () => {
+    let id = "";
+    raise(() => {
+      id = toast("Saved");
+    });
+    expect(id).toMatch(/^toast-\d+$/);
+  });
+
+  it("honours an explicit id, replacing rather than duplicating", async () => {
+    render(<Toaster />);
+
+    raise(() => toast.custom({ id: "sync", title: "Syncing" }));
+    expect(await screen.findByText("Syncing")).toBeInTheDocument();
+
+    raise(() => toast.custom({ id: "sync", title: "Synced" }));
+    await waitFor(() => {
+      expect(screen.getByText("Synced")).toBeInTheDocument();
+    });
+    expect(screen.queryByText("Syncing")).not.toBeInTheDocument();
+  });
+
+  it("keeps only the most recent toasts", async () => {
+    render(<Toaster />);
+
+    raise(() => {
+      for (let index = 0; index < TOAST_LIMIT + 3; index += 1) {
+        toast(`Message ${String(index)}`);
+      }
+    });
+
+    await waitFor(() => {
+      expect(document.querySelectorAll("[data-slot='toast']")).toHaveLength(TOAST_LIMIT);
+    });
+    expect(screen.queryByText("Message 0")).not.toBeInTheDocument();
+    expect(screen.getByText(`Message ${String(TOAST_LIMIT + 2)}`)).toBeInTheDocument();
+  });
+
+  it("calls onDismiss when a toast is removed", () => {
+    const onDismiss = vi.fn();
+    let id = "";
+    raise(() => {
+      id = toast.custom({ title: "Saved", onDismiss });
+    });
+
+    raise(() => {
+      toast.dismiss(id);
+    });
+    expect(onDismiss).toHaveBeenCalledWith(id);
+  });
+
+  it("updates a toast in place", async () => {
+    render(<Toaster />);
+
+    let id = "";
+    raise(() => {
+      id = toast("Uploading");
+    });
+    await screen.findByText("Uploading");
+
+    raise(() => {
+      toast.update(id, { title: "Uploaded", variant: "success" });
+    });
+
+    await waitFor(() => {
+      expect(screen.getByText("Uploaded")).toBeInTheDocument();
+    });
+    expect(document.querySelector("[data-slot='toast']")).toHaveClass("border-success/30");
+  });
+
+  it("exposes a helper per variant", async () => {
+    render(<Toaster />);
+
+    raise(() => {
+      toast.default("Plain");
+      toast.info("Informational");
+    });
+
+    expect(await screen.findByText("Plain")).toBeInTheDocument();
+    expect(screen.getByText("Informational")).toBeInTheDocument();
+  });
+
+  it("dismisses everything at once", async () => {
+    render(<Toaster />);
+
+    raise(() => {
+      toast("One");
+      toast("Two");
+    });
+    await screen.findByText("One");
+
+    raise(() => {
+      toast.dismissAll();
+    });
+    await waitFor(() => {
+      expect(screen.queryByText("One")).not.toBeInTheDocument();
+    });
+  });
+
+  describe("promise", () => {
+    it("resolves the pending toast into a success toast", async () => {
+      render(<Toaster />);
+
+      let resolve!: (value: string) => void;
+      const pending = new Promise<string>((r) => {
+        resolve = r;
+      });
+
+      raise(() => {
+        void toast.promise(pending, {
+          loading: "Saving…",
+          success: (value) => `Saved ${value}`,
+          error: "Failed",
+        });
+      });
+
+      expect(await screen.findByText("Saving…")).toBeInTheDocument();
+
+      await act(async () => {
+        resolve("project");
+        await pending;
+      });
+
+      await waitFor(() => {
+        expect(screen.getByText("Saved project")).toBeInTheDocument();
+      });
+    });
+
+    it("turns a rejection into an error toast and still rejects", async () => {
+      render(<Toaster />);
+
+      const failure = new Error("network");
+      const pending = Promise.reject(failure);
+
+      let returned!: Promise<never>;
+      raise(() => {
+        returned = toast.promise(pending, {
+          loading: "Saving…",
+          success: "Saved",
+          error: (error) => `Failed: ${(error as Error).message}`,
+        });
+      });
+
+      // The original promise is returned untouched, so callers still handle it.
+      await expect(returned).rejects.toThrow("network");
+      await waitFor(() => {
+        expect(screen.getByText("Failed: network")).toBeInTheDocument();
+      });
+    });
+  });
+});
+
+describe("Toaster", () => {
+  it("renders nothing until a toast is raised", () => {
+    render(<Toaster />);
+    expect(document.querySelector("[data-slot='toast']")).not.toBeInTheDocument();
+  });
+
+  it("renders a title and description", async () => {
+    render(<Toaster />);
+    raise(() => toast("Project created", { description: "It is ready to use." }));
+
+    expect(await screen.findByText("Project created")).toBeInTheDocument();
+    expect(screen.getByText("It is ready to use.")).toBeInTheDocument();
+  });
+
+  it.each([
+    ["success", "border-success/30"],
+    ["warning", "border-warning/35"],
+    ["destructive", "border-destructive/30"],
+    ["info", "border-info/30"],
+  ] as const)("applies the %s variant", async (variant, expectedClass) => {
+    render(<Toaster />);
+    raise(() => toast.custom({ title: "Message", variant }));
+    await screen.findByText("Message");
+
+    expect(document.querySelector("[data-slot='toast']")).toHaveClass(expectedClass);
+  });
+
+  it("interrupts for problems and waits for a pause otherwise", async () => {
+    render(<Toaster />);
+
+    raise(() => toast.error("Payment failed"));
+    const problem = await screen.findByText("Payment failed");
+    expect(problem.closest("[data-slot='toast']")).toHaveAttribute("data-type", "foreground");
+
+    raise(() => toast.success("Saved"));
+    const routine = await screen.findByText("Saved");
+    expect(routine.closest("[data-slot='toast']")).toHaveAttribute("data-type", "background");
+  });
+
+  it("announces a problem assertively through a live region", async () => {
+    render(<Toaster />);
+    raise(() => toast.error("Payment failed"));
+
+    const announcement = await screen.findByRole("status");
+    expect(announcement).toHaveAttribute("aria-live", "assertive");
+    // The primitive mounts the region first and fills it on a later tick.
+    await waitFor(() => {
+      expect(announcement).toHaveTextContent("Payment failed");
+    });
+  });
+
+  it("dismisses from the close button", async () => {
+    const user = userEvent.setup();
+    render(<Toaster />);
+    raise(() => toast("Saved"));
+    await screen.findByText("Saved");
+
+    await user.click(screen.getByRole("button", { name: "Dismiss" }));
+    await waitFor(() => {
+      expect(screen.queryByText("Saved")).not.toBeInTheDocument();
+    });
+  });
+
+  it("runs an action and exposes alt text for screen readers", async () => {
+    const onClick = vi.fn();
+    const user = userEvent.setup();
+    render(<Toaster />);
+
+    raise(() =>
+      toast.custom({
+        title: "Message archived",
+        action: { label: "Undo", altText: "Undo archiving the message", onClick },
+      }),
+    );
+
+    const action = await screen.findByRole("button", { name: "Undo" });
+    // The primitive announces the alt text in place of the visible label, since
+    // "Undo" alone is meaningless once the toast is gone.
+    expect(action).toHaveAttribute(
+      "data-radix-toast-announce-alt",
+      "Undo archiving the message",
+    );
+    const announcement = await screen.findByRole("status");
+    await waitFor(() => {
+      expect(announcement).toHaveTextContent("Undo archiving the message");
+    });
+
+    await user.click(action);
+    expect(onClick).toHaveBeenCalledTimes(1);
+  });
+
+  it("falls back to the action label for alt text", async () => {
+    render(<Toaster />);
+    raise(() =>
+      toast.custom({
+        title: "Message archived",
+        action: { label: "Undo", onClick: () => undefined },
+      }),
+    );
+
+    expect(await screen.findByRole("button", { name: "Undo" })).toHaveAttribute(
+      "data-radix-toast-announce-alt",
+      "Undo",
+    );
+  });
+
+  it.each([
+    ["top-left", "top-0"],
+    ["bottom-right", "bottom-0"],
+    ["bottom-center", "left-1/2"],
+  ] as const)("positions the viewport for %s", async (position, expectedClass) => {
+    const { baseElement } = render(<Toaster position={position} />);
+    raise(() => toast("Message"));
+    await screen.findByText("Message");
+
+    expect(baseElement.querySelector("[data-slot='toast-viewport']")).toHaveClass(
+      expectedClass,
+    );
+  });
+
+  it("has no accessibility violations", async () => {
+    const { baseElement } = render(<Toaster />);
+    raise(() =>
+      toast.custom({
+        title: "Project created",
+        description: "It is ready to use.",
+        action: { label: "View", onClick: () => undefined },
+      }),
+    );
+    await screen.findByText("Project created");
+
+    await expectNoA11yViolations(baseElement);
+  });
+});

package/src/components/toast/toast.tsx

@@ -0,0 +1,241 @@
+"use client";
+
+import { cva, type VariantProps } from "class-variance-authority";
+import { Toast as ToastPrimitive } from "radix-ui";
+import type { ComponentPropsWithRef } from "react";
+
+import { focusRing } from "@/lib/styles";
+import { cn } from "@/lib/utils";
+
+import {
+  DEFAULT_TOAST_DURATION,
+  toast,
+  useToasts,
+  type ToastRecord,
+  type ToastVariant,
+} from "./toast-store";
+
+/**
+ * Brief, non-blocking messages about something that just happened.
+ *
+ * Render one `<Toaster />` near the root of the app; raise messages from
+ * anywhere with `toast()`. The primitive underneath supplies the parts that are
+ * easy to get wrong: a screen-reader announcement region, timers that pause on
+ * hover, focus and window blur, swipe-to-dismiss, and F8 to jump focus into the
+ * toast list from anywhere on the page.
+ */
+
+const toastVariants = cva(
+  cn(
+    "group pointer-events-auto relative flex w-full items-start gap-3 overflow-hidden",
+    "rounded-lg border p-4 pr-10 shadow-lg",
+    "[--slide-x:calc(100%+1rem)]",
+    "data-[state=closed]:animate-float-out data-[state=open]:animate-slide-in",
+    "data-[swipe=move]:translate-x-[var(--radix-toast-swipe-move-x)] data-[swipe=move]:transition-none",
+    "data-[swipe=cancel]:translate-x-0 data-[swipe=cancel]:transition-transform",
+    "data-[swipe=end]:animate-toast-swipe-out",
+  ),
+  {
+    variants: {
+      variant: {
+        default: "border-border bg-popover text-popover-foreground",
+        success: "border-success/30 bg-popover text-popover-foreground [&_svg]:text-success",
+        warning: "border-warning/35 bg-popover text-popover-foreground [&_svg]:text-warning",
+        destructive:
+          "border-destructive/30 bg-popover text-popover-foreground [&_svg]:text-destructive",
+        info: "border-info/30 bg-popover text-popover-foreground [&_svg]:text-info",
+      },
+    },
+    defaultVariants: {
+      variant: "default",
+    },
+  },
+);
+
+export const ToastProvider = ToastPrimitive.Provider;
+
+export interface ToastProps
+  extends
+    ComponentPropsWithRef<typeof ToastPrimitive.Root>,
+    VariantProps<typeof toastVariants> {}
+
+export function Toast({ className, variant, ...props }: ToastProps) {
+  return (
+    <ToastPrimitive.Root
+      data-slot="toast"
+      className={cn(toastVariants({ variant }), className)}
+      {...props}
+    />
+  );
+}
+
+export function ToastTitle({
+  className,
+  ...props
+}: ComponentPropsWithRef<typeof ToastPrimitive.Title>) {
+  return (
+    <ToastPrimitive.Title
+      data-slot="toast-title"
+      className={cn("text-sm leading-snug font-medium", className)}
+      {...props}
+    />
+  );
+}
+
+export function ToastDescription({
+  className,
+  ...props
+}: ComponentPropsWithRef<typeof ToastPrimitive.Description>) {
+  return (
+    <ToastPrimitive.Description
+      data-slot="toast-description"
+      className={cn("text-sm text-muted-foreground", className)}
+      {...props}
+    />
+  );
+}
+
+export function ToastAction({
+  className,
+  ...props
+}: ComponentPropsWithRef<typeof ToastPrimitive.Action>) {
+  return (
+    <ToastPrimitive.Action
+      data-slot="toast-action"
+      className={cn(
+        "inline-flex h-8 shrink-0 items-center rounded-md border border-input bg-transparent px-3 text-xs font-medium",
+        "transition-colors duration-[var(--duration-fast)] hover:bg-accent hover:text-accent-foreground",
+        focusRing,
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+export function ToastClose({
+  className,
+  ...props
+}: ComponentPropsWithRef<typeof ToastPrimitive.Close>) {
+  return (
+    <ToastPrimitive.Close
+      data-slot="toast-close"
+      aria-label="Dismiss"
+      className={cn(
+        "absolute top-3 right-3 grid size-6 place-items-center rounded-md text-muted-foreground",
+        "transition-colors duration-[var(--duration-fast)] hover:bg-accent hover:text-foreground",
+        focusRing,
+        className,
+      )}
+      {...props}
+    >
+      <svg viewBox="0 0 24 24" fill="none" aria-hidden="true" className="size-3.5">
+        <path
+          d="m6 6 12 12M18 6 6 18"
+          stroke="currentColor"
+          strokeWidth="2"
+          strokeLinecap="round"
+        />
+      </svg>
+    </ToastPrimitive.Close>
+  );
+}
+
+export type ToastPosition =
+  "top-left" | "top-center" | "top-right" | "bottom-left" | "bottom-center" | "bottom-right";
+
+const viewportPositions: Record<ToastPosition, string> = {
+  "top-left": "top-0 left-0 sm:flex-col-reverse",
+  "top-center": "top-0 left-1/2 -translate-x-1/2 sm:flex-col-reverse",
+  "top-right": "top-0 right-0 sm:flex-col-reverse",
+  "bottom-left": "bottom-0 left-0",
+  "bottom-center": "bottom-0 left-1/2 -translate-x-1/2",
+  "bottom-right": "bottom-0 right-0",
+};
+
+export interface ToasterProps {
+  position?: ToastPosition;
+  /** Default auto-dismiss in ms. Individual toasts may override it. */
+  duration?: number;
+  className?: string;
+  /** Names the toast region for assistive technology. */
+  label?: string;
+}
+
+/**
+ * Renders the toast queue. Mount once, near the root of the application.
+ */
+export function Toaster({
+  position = "bottom-right",
+  duration = DEFAULT_TOAST_DURATION,
+  className,
+  label = "Notifications",
+}: ToasterProps) {
+  const toasts = useToasts();
+  // Swiping should follow the edge the toasts are docked against.
+  const swipeDirection = position.endsWith("left") ? "left" : "right";
+
+  return (
+    <ToastPrimitive.Provider swipeDirection={swipeDirection} duration={duration} label={label}>
+      {toasts.map((record) => (
+        <ToastItem key={record.id} record={record} />
+      ))}
+      <ToastPrimitive.Viewport
+        data-slot="toast-viewport"
+        className={cn(
+          "pointer-events-none fixed z-[var(--z-toast)] flex max-h-screen w-full flex-col gap-2 p-4 sm:max-w-sm",
+          viewportPositions[position],
+          className,
+        )}
+      />
+    </ToastPrimitive.Provider>
+  );
+}
+
+/** Variants that report a problem should interrupt rather than wait for a pause. */
+const FOREGROUND_VARIANTS = new Set<ToastVariant>(["destructive", "warning"]);
+
+/**
+ * Largest delay setTimeout accepts (2^31 - 1 ms, about 24 days).
+ *
+ * Anything above this silently overflows to a 32-bit integer and fires almost
+ * immediately, so mapping `Infinity` to MAX_SAFE_INTEGER would dismiss a
+ * persistent toast after roughly one millisecond — the exact opposite of what
+ * was asked for.
+ */
+const MAX_TIMEOUT_MS = 2_147_483_647;
+
+function ToastItem({ record }: { record: ToastRecord }) {
+  const { id, title, description, variant, action, duration } = record;
+
+  const type = FOREGROUND_VARIANTS.has(variant) ? "foreground" : "background";
+
+  return (
+    <Toast
+      variant={variant}
+      type={type}
+      // Mirrored onto the element because the primitive expresses `type` only
+      // through the transient live region it renders elsewhere. Having it here
+      // gives styling and tests something stable to read.
+      data-type={type}
+      duration={duration === Infinity ? MAX_TIMEOUT_MS : duration}
+      onOpenChange={(open) => {
+        // Covers every route out: the timer, the close button and a swipe.
+        if (!open) toast.dismiss(id);
+      }}
+    >
+      <div className="flex min-w-0 flex-1 flex-col gap-1">
+        {title === undefined ? null : <ToastTitle>{title}</ToastTitle>}
+        {description === undefined ? null : <ToastDescription>{description}</ToastDescription>}
+      </div>
+      {action ? (
+        <ToastAction altText={action.altText ?? action.label} onClick={action.onClick}>
+          {action.label}
+        </ToastAction>
+      ) : null}
+      <ToastClose />
+    </Toast>
+  );
+}
+
+export { toastVariants };