@dowel-ui/react 0.1.0

package/src/blocks/dashboard/dashboard.stories.tsx

@@ -0,0 +1,106 @@
+import type { Decorator, Meta, StoryObj } from "@storybook/react-vite";
+
+import { Button } from "@/components/button";
+
+import { DashboardBlock, type DashboardEvent, type DashboardStat } from "./dashboard";
+
+/** Named so its type is nameable in declaration output (TS2883). */
+const withPageWidth: Decorator = (Story) => (
+  <div className="w-[64rem] max-w-full">
+    <Story />
+  </div>
+);
+
+const STATS: DashboardStat[] = [
+  {
+    id: "mrr",
+    label: "Monthly revenue",
+    value: "$48,120",
+    change: 12.4,
+    comparison: "on last month",
+  },
+  {
+    id: "users",
+    label: "Active users",
+    value: "2,410",
+    change: 4.2,
+    comparison: "on last week",
+  },
+  {
+    id: "churn",
+    label: "Churn",
+    value: "1.8%",
+    change: 0.4,
+    comparison: "on last month",
+    higherIsBetter: false,
+  },
+  { id: "uptime", label: "Uptime", value: "99.98%" },
+];
+
+const EVENTS: DashboardEvent[] = [
+  {
+    id: "1",
+    title: "Deployed to production",
+    detail: "Build 1420 · main",
+    at: "2026-09-01T09:12:00Z",
+    label: "12 minutes ago",
+    tone: "success",
+  },
+  {
+    id: "2",
+    title: "Build finished with warnings",
+    detail: "3 unused exports",
+    at: "2026-09-01T09:04:00Z",
+    label: "20 minutes ago",
+    tone: "warning",
+  },
+  {
+    id: "3",
+    title: "Build failed",
+    detail: "Type error in table.tsx",
+    at: "2026-09-01T08:31:00Z",
+    label: "53 minutes ago",
+    tone: "destructive",
+  },
+  {
+    id: "4",
+    title: "Opened pull request #482",
+    at: "2026-08-31T17:20:00Z",
+    label: "Yesterday",
+  },
+];
+
+const meta = {
+  title: "Blocks/Dashboard",
+  component: DashboardBlock,
+  args: { stats: STATS, events: EVENTS },
+  parameters: { controls: { disable: true } },
+  decorators: [withPageWidth],
+} satisfies Meta<typeof DashboardBlock>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+/** Every change is stated in words — "up 12.4%", not a green triangle. */
+export const Default: Story = {};
+
+export const Loading: Story = {
+  args: { loading: true },
+};
+
+export const MetricsOnly: Story = {
+  args: { events: [] },
+};
+
+export const WithActions: Story = {
+  args: {
+    actions: (
+      <div className="flex gap-2">
+        <Button variant="outline" size="sm">
+          Last 30 days
+        </Button>
+        <Button size="sm">Export</Button>
+      </div>
+    ),
+  },
+};

package/src/blocks/dashboard/dashboard.test.tsx

@@ -0,0 +1,94 @@
+import { render, screen, within } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+
+import { expectNoA11yViolations } from "../../../test/a11y";
+import { DashboardBlock, type DashboardEvent, type DashboardStat } from "./dashboard";
+
+const STATS: DashboardStat[] = [
+  {
+    id: "mrr",
+    label: "Monthly revenue",
+    value: "$48,120",
+    change: 12.4,
+    comparison: "on last month",
+  },
+  { id: "churn", label: "Churn", value: "1.8%", change: 0.4, higherIsBetter: false },
+  { id: "users", label: "Active users", value: "2,410", change: -3.1 },
+  { id: "uptime", label: "Uptime", value: "99.98%" },
+];
+
+const EVENTS: DashboardEvent[] = [
+  {
+    id: "1",
+    title: "Deployed to production",
+    at: "2026-09-01T09:12:00Z",
+    label: "12 minutes ago",
+    tone: "success",
+  },
+  {
+    id: "2",
+    title: "Build failed",
+    detail: "Type error in table.tsx",
+    at: "2026-09-01T08:40:00Z",
+    label: "44 minutes ago",
+    tone: "destructive",
+  },
+];
+
+describe("DashboardBlock", () => {
+  it("renders each metric", () => {
+    render(<DashboardBlock stats={STATS} />);
+    expect(screen.getByText("$48,120")).toBeInTheDocument();
+    expect(screen.getByText("Active users")).toBeInTheDocument();
+  });
+
+  it("puts the metrics in a named region", () => {
+    render(<DashboardBlock stats={STATS} />);
+    expect(screen.getByRole("region", { name: "Key metrics" })).toBeInTheDocument();
+  });
+
+  it("states each change in words, not by a coloured arrow", () => {
+    render(<DashboardBlock stats={STATS} />);
+    expect(screen.getByText(/up 12\.4%/)).toBeInTheDocument();
+    expect(screen.getByText(/down 3\.1%/)).toBeInTheDocument();
+  });
+
+  it("knows a rise is not always good", () => {
+    render(<DashboardBlock stats={STATS} />);
+
+    // Churn rising is bad; revenue rising is good. Same sign, opposite meaning.
+    const churn = screen.getByText(/up 0\.4%/);
+    const revenue = screen.getByText(/up 12\.4%/);
+    expect(churn).toHaveClass("text-destructive");
+    expect(revenue).toHaveClass("text-success");
+  });
+
+  it("omits the change when there is nothing to compare to", () => {
+    render(<DashboardBlock stats={[STATS[3]!]} />);
+    expect(screen.queryByText(/up |down /)).not.toBeInTheDocument();
+  });
+
+  it("renders the activity feed as an ordered list", () => {
+    render(<DashboardBlock stats={STATS} events={EVENTS} />);
+
+    const list = screen.getByRole("list");
+    expect(list.tagName).toBe("OL");
+    expect(within(list).getAllByRole("listitem")).toHaveLength(2);
+  });
+
+  it("shows placeholders while loading, with no numbers to misread", () => {
+    render(<DashboardBlock stats={STATS} events={EVENTS} loading />);
+    expect(screen.queryByText("$48,120")).not.toBeInTheDocument();
+    expect(screen.queryByText(/up 12\.4%/)).not.toBeInTheDocument();
+  });
+
+  it("renders actions beside the heading", () => {
+    render(<DashboardBlock stats={STATS} actions={<button type="button">Export</button>} />);
+    expect(screen.getByRole("button", { name: "Export" })).toBeInTheDocument();
+  });
+
+  it("has no accessibility violations", async () => {
+    const { container } = render(<DashboardBlock stats={STATS} events={EVENTS} />);
+    await expectNoA11yViolations(container);
+  });
+});

package/src/blocks/dashboard/dashboard.tsx

@@ -0,0 +1,192 @@
+"use client";
+
+import type { ReactNode } from "react";
+
+import {
+  ActivityContent,
+  ActivityDescription,
+  ActivityFeed,
+  ActivityIndicator,
+  ActivityItem,
+  ActivityTime,
+  ActivityTitle,
+} from "@/components/activity-feed";
+import { Badge } from "@/components/badge";
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@/components/card";
+import { Skeleton } from "@/components/skeleton";
+import { cn } from "@/lib/utils";
+
+/**
+ * An overview page: headline numbers and what happened recently.
+ *
+ * The trend on a stat is stated in words as well as by direction and colour —
+ * "up 12.4%" rather than a green triangle — because a triangle is unreadable to
+ * a screen reader and ambiguous to anyone who cannot tell the colours apart.
+ */
+
+export interface DashboardStat {
+  id: string;
+  label: string;
+  value: string;
+  /** Signed change, e.g. 12.4 or -3.1. Omit when there is nothing to compare to. */
+  change?: number;
+  /** What the change is measured against. */
+  comparison?: string;
+  /** Whether a rise is good. Churn going up is not. */
+  higherIsBetter?: boolean;
+}
+
+export interface DashboardEvent {
+  id: string;
+  title: string;
+  detail?: string;
+  /** Machine-readable timestamp. */
+  at: string;
+  /** Human label, e.g. "12 minutes ago". */
+  label: string;
+  tone?: "default" | "success" | "warning" | "destructive";
+}
+
+export interface DashboardBlockProps {
+  title?: string;
+  description?: string;
+  stats: DashboardStat[];
+  events?: DashboardEvent[];
+  /** Renders placeholders instead of content. */
+  loading?: boolean;
+  /** Anything to put beside the heading — a date range picker, an action. */
+  actions?: ReactNode;
+  className?: string;
+}
+
+function formatChange(change: number): string {
+  const rounded = Math.abs(change).toFixed(1);
+  return `${change >= 0 ? "up" : "down"} ${rounded}%`;
+}
+
+export function DashboardBlock({
+  title = "Overview",
+  description = "How things are going.",
+  stats,
+  events = [],
+  loading = false,
+  actions,
+  className,
+}: DashboardBlockProps) {
+  return (
+    <div className={cn("flex flex-col gap-6", className)}>
+      <div className="flex flex-wrap items-end justify-between gap-3">
+        <div>
+          <h1 className="text-xl font-semibold tracking-tight">{title}</h1>
+          <p className="mt-1 text-sm text-muted-foreground">{description}</p>
+        </div>
+        {actions}
+      </div>
+
+      <section aria-label="Key metrics" className="grid gap-4 sm:grid-cols-2 lg:grid-cols-4">
+        {stats.map((stat) => {
+          const good =
+            stat.change === undefined
+              ? undefined
+              : (stat.higherIsBetter ?? true)
+                ? stat.change >= 0
+                : stat.change < 0;
+
+          return (
+            <Card key={stat.id}>
+              <CardHeader className="pb-2">
+                <CardDescription>{stat.label}</CardDescription>
+                {/* Not a heading: a number is data, and making it one both
+                    breaks the heading order and litters the outline. */}
+                <p className="text-2xl leading-tight font-semibold tracking-tight tabular-nums">
+                  {loading ? <Skeleton className="h-7 w-24" /> : stat.value}
+                </p>
+              </CardHeader>
+              <CardContent>
+                {loading ? (
+                  <Skeleton className="h-4 w-32" />
+                ) : stat.change === undefined ? null : (
+                  <p className={cn("text-xs", good ? "text-success" : "text-destructive")}>
+                    {/* In words: direction and magnitude, not a coloured arrow. */}
+                    {formatChange(stat.change)}
+                    {stat.comparison ? (
+                      <span className="text-muted-foreground"> {stat.comparison}</span>
+                    ) : null}
+                  </p>
+                )}
+              </CardContent>
+            </Card>
+          );
+        })}
+      </section>
+
+      {events.length > 0 || loading ? (
+        <Card>
+          <CardHeader>
+            <CardTitle asChild>
+              <h2>Recent activity</h2>
+            </CardTitle>
+            <CardDescription>The last few things that happened.</CardDescription>
+          </CardHeader>
+          <CardContent>
+            {loading ? (
+              <div className="flex flex-col gap-4">
+                {[0, 1, 2].map((index) => (
+                  <div key={index} className="flex gap-3">
+                    <Skeleton className="size-6 rounded-full" />
+                    <div className="flex-1 space-y-2">
+                      <Skeleton className="h-4 w-48" />
+                      <Skeleton className="h-3 w-24" />
+                    </div>
+                  </div>
+                ))}
+              </div>
+            ) : (
+              <ActivityFeed>
+                {events.map((event, index) => (
+                  <ActivityItem key={event.id} last={index === events.length - 1}>
+                    <ActivityIndicator
+                      className={cn(
+                        event.tone === "success" && "border-success/40 text-success",
+                        event.tone === "warning" && "border-warning/40 text-warning",
+                        event.tone === "destructive" &&
+                          "border-destructive/40 text-destructive",
+                      )}
+                    />
+                    <ActivityContent>
+                      <ActivityTitle className="flex flex-wrap items-center gap-2">
+                        {event.title}
+                        {event.tone && event.tone !== "default" ? (
+                          <Badge
+                            size="sm"
+                            variant={
+                              event.tone === "success"
+                                ? "success"
+                                : event.tone === "warning"
+                                  ? "warning"
+                                  : "destructive"
+                            }
+                          >
+                            {event.tone === "success"
+                              ? "Succeeded"
+                              : event.tone === "warning"
+                                ? "Warning"
+                                : "Failed"}
+                          </Badge>
+                        ) : null}
+                      </ActivityTitle>
+                      {event.detail ? (
+                        <ActivityDescription>{event.detail}</ActivityDescription>
+                      ) : null}
+                      <ActivityTime dateTime={event.at}>{event.label}</ActivityTime>
+                    </ActivityContent>
+                  </ActivityItem>
+                ))}
+              </ActivityFeed>
+            )}
+          </CardContent>
+        </Card>
+      ) : null}
+    </div>
+  );
+}

package/src/blocks/dashboard/index.ts

@@ -0,0 +1,6 @@
+export {
+  DashboardBlock,
+  type DashboardBlockProps,
+  type DashboardEvent,
+  type DashboardStat,
+} from "./dashboard";

package/src/blocks/dashboard/meta.ts

@@ -0,0 +1,18 @@
+import { defineMeta } from "@/registry/schema";
+
+export const meta = defineMeta({
+  name: "dashboard",
+  kind: "block",
+  title: "Dashboard",
+  description: "An overview page with headline metrics and a recent activity feed.",
+  category: "data",
+  status: "stable",
+  dependencies: [],
+  registryDependencies: ["activity-feed", "badge", "card", "skeleton"],
+  files: ["dashboard.tsx"],
+  a11y:
+    'Each metric states its change in words — "up 12.4%" — rather than by a coloured arrow, ' +
+    "which is unreadable to a screen reader and ambiguous to anyone who cannot distinguish the " +
+    "colours. Whether a rise is good is configurable, since churn going up is not. The metrics " +
+    "sit in a named region so they can be jumped to.",
+});

package/src/blocks/forgot-password/forgot-password.stories.tsx

@@ -0,0 +1,41 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { useState } from "react";
+
+import { ForgotPasswordBlock } from "./forgot-password";
+
+const meta = {
+  title: "Blocks/Forgot password",
+  component: ForgotPasswordBlock,
+  parameters: { layout: "centered", controls: { disable: true } },
+} satisfies Meta<typeof ForgotPasswordBlock>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {};
+
+/** Neutral about whether the address exists — otherwise this form enumerates accounts. */
+export const Sent: Story = {
+  args: { sent: true },
+};
+
+export const Interactive: Story = {
+  render: function Interactive() {
+    const [pending, setPending] = useState(false);
+    const [sent, setSent] = useState(false);
+
+    return (
+      <ForgotPasswordBlock
+        pending={pending}
+        sent={sent}
+        onSubmit={() => {
+          setPending(true);
+          window.setTimeout(() => {
+            setPending(false);
+            setSent(true);
+          }, 900);
+        }}
+      />
+    );
+  },
+};

package/src/blocks/forgot-password/forgot-password.test.tsx

@@ -0,0 +1,62 @@
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { describe, expect, it, vi } from "vitest";
+
+import { expectNoA11yViolations } from "../../../test/a11y";
+import { ForgotPasswordBlock } from "./forgot-password";
+
+describe("ForgotPasswordBlock", () => {
+  it("asks for an email", () => {
+    render(<ForgotPasswordBlock />);
+    expect(screen.getByLabelText("Email")).toHaveAttribute("type", "email");
+  });
+
+  it("submits a valid address", async () => {
+    const onSubmit = vi.fn();
+    const user = userEvent.setup();
+    render(<ForgotPasswordBlock onSubmit={onSubmit} />);
+
+    await user.type(screen.getByLabelText("Email"), "ada@example.com");
+    await user.click(screen.getByRole("button", { name: "Send reset link" }));
+
+    expect(onSubmit).toHaveBeenCalledWith({ email: "ada@example.com" });
+  });
+
+  it("refuses an invalid address", async () => {
+    const onSubmit = vi.fn();
+    const user = userEvent.setup();
+    render(<ForgotPasswordBlock onSubmit={onSubmit} />);
+
+    await user.type(screen.getByLabelText("Email"), "nope");
+    await user.click(screen.getByRole("button", { name: "Send reset link" }));
+
+    expect(onSubmit).not.toHaveBeenCalled();
+  });
+
+  describe("the confirmation", () => {
+    it("announces itself, because it replaces the form", () => {
+      render(<ForgotPasswordBlock sent />);
+      expect(screen.getByRole("status")).toHaveTextContent("Check your inbox");
+    });
+
+    it("does not reveal whether the account exists", () => {
+      render(<ForgotPasswordBlock sent />);
+      // Confirming it would turn this form into an account enumeration oracle.
+      expect(screen.getByText(/If an account exists/)).toBeInTheDocument();
+    });
+
+    it("replaces the form entirely", () => {
+      render(<ForgotPasswordBlock sent />);
+      expect(screen.queryByLabelText("Email")).not.toBeInTheDocument();
+    });
+  });
+
+  it("has no accessibility violations in either state", async () => {
+    const form = render(<ForgotPasswordBlock />);
+    await expectNoA11yViolations(form.container);
+    form.unmount();
+
+    const sent = render(<ForgotPasswordBlock sent />);
+    await expectNoA11yViolations(sent.container);
+  });
+});

package/src/blocks/forgot-password/forgot-password.tsx

@@ -0,0 +1,158 @@
+"use client";
+
+import { useState, type FormEvent } from "react";
+
+import { Button } from "@/components/button";
+import {
+  Card,
+  CardContent,
+  CardDescription,
+  CardFooter,
+  CardHeader,
+  CardTitle,
+} from "@/components/card";
+import {
+  EmptyState,
+  EmptyStateDescription,
+  EmptyStateIcon,
+  EmptyStateTitle,
+} from "@/components/empty-state";
+import { Form, FormControl, FormField, FormLabel, FormMessage } from "@/components/form";
+import { Input } from "@/components/input";
+import { cn } from "@/lib/utils";
+
+/**
+ * A password reset request.
+ *
+ * The confirmation deliberately does not say whether the address was found.
+ * Telling an anonymous visitor which emails have accounts turns this form into
+ * an account enumeration oracle, and the same neutral message covers both cases
+ * without being a lie.
+ */
+
+export interface ForgotPasswordBlockProps {
+  onSubmit?: (values: { email: string }) => void;
+  /** Switches to the confirmation view. */
+  sent?: boolean;
+  error?: string;
+  pending?: boolean;
+  loginHref?: string;
+  className?: string;
+}
+
+export function ForgotPasswordBlock({
+  onSubmit,
+  sent = false,
+  error,
+  pending = false,
+  loginHref = "/login",
+  className,
+}: ForgotPasswordBlockProps) {
+  const [email, setEmail] = useState("");
+  const [touched, setTouched] = useState(false);
+
+  const emailError =
+    touched && !email.includes("@") ? "Enter a valid email address." : undefined;
+
+  function handleSubmit(event: FormEvent<HTMLFormElement>) {
+    event.preventDefault();
+    setTouched(true);
+    if (!email.includes("@")) return;
+    onSubmit?.({ email });
+  }
+
+  if (sent) {
+    return (
+      <Card className={cn("w-full max-w-sm", className)}>
+        <CardContent className="pt-6">
+          {/* Announced, because it replaces the form the user just submitted. */}
+          <EmptyState role="status" aria-live="polite">
+            <EmptyStateIcon>
+              <svg viewBox="0 0 24 24" fill="none" aria-hidden="true">
+                <rect
+                  x="3"
+                  y="5"
+                  width="18"
+                  height="14"
+                  rx="2"
+                  stroke="currentColor"
+                  strokeWidth="2"
+                />
+                <path
+                  d="m3 7 9 6 9-6"
+                  stroke="currentColor"
+                  strokeWidth="2"
+                  strokeLinecap="round"
+                />
+              </svg>
+            </EmptyStateIcon>
+            <EmptyStateTitle>Check your inbox</EmptyStateTitle>
+            <EmptyStateDescription>
+              If an account exists for {email}, a reset link is on its way. It expires in an
+              hour.
+            </EmptyStateDescription>
+          </EmptyState>
+        </CardContent>
+        <CardFooter className="justify-center">
+          <a
+            href={loginHref}
+            className="text-sm font-medium text-primary underline underline-offset-4"
+          >
+            Back to sign in
+          </a>
+        </CardFooter>
+      </Card>
+    );
+  }
+
+  return (
+    <Card className={cn("w-full max-w-sm", className)}>
+      <CardHeader>
+        <CardTitle>Reset your password</CardTitle>
+        <CardDescription>
+          Enter the address you signed up with and we will send you a link.
+        </CardDescription>
+      </CardHeader>
+
+      <CardContent>
+        <Form onSubmit={handleSubmit} className="gap-4">
+          {error ? (
+            <p role="alert" className="text-sm font-medium text-destructive">
+              {error}
+            </p>
+          ) : null}
+
+          <FormField name="email" error={emailError}>
+            <FormLabel>Email</FormLabel>
+            <FormControl>
+              <Input
+                type="email"
+                autoComplete="email"
+                placeholder="you@example.com"
+                value={email}
+                disabled={pending}
+                onChange={(event) => {
+                  setEmail(event.target.value);
+                }}
+              />
+            </FormControl>
+            <FormMessage />
+          </FormField>
+
+          <Button type="submit" loading={pending} className="w-full">
+            Send reset link
+          </Button>
+        </Form>
+      </CardContent>
+
+      <CardFooter className="justify-center">
+        <a
+          href={loginHref}
+          className="text-sm text-muted-foreground underline underline-offset-4"
+        >
+          Back to sign in
+        </a>
+      </CardFooter>
+    </Card>
+  );
+}

package/src/blocks/forgot-password/index.ts

@@ -0,0 +1 @@
+export { ForgotPasswordBlock, type ForgotPasswordBlockProps } from "./forgot-password";