@dowel-ui/react 0.1.0

package/src/components/pagination/meta.ts

@@ -0,0 +1,17 @@
+import { defineMeta } from "@/registry/schema";
+
+export const meta = defineMeta({
+  name: "pagination",
+  title: "Pagination",
+  description: "Navigation between pages of a list.",
+  category: "navigation",
+  status: "stable",
+  dependencies: ["radix-ui"],
+  registryDependencies: ["button"],
+  files: ["pagination.tsx"],
+  a11y:
+    'A named nav landmark. The current page carries aria-current="page" — styling it ' +
+    "differently conveys nothing on its own. Links by default, since a page of results is a " +
+    "place worth sharing; use asChild for your router's link, or render buttons when paging " +
+    "only changes client state.",
+});

package/src/components/pagination/pagination.stories.tsx

@@ -0,0 +1,129 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { useState } from "react";
+
+import {
+  Pagination,
+  PaginationContent,
+  PaginationEllipsis,
+  PaginationItem,
+  PaginationLink,
+  PaginationNext,
+  PaginationPrevious,
+} from "./pagination";
+
+const meta = {
+  title: "Navigation/Pagination",
+  component: Pagination,
+  parameters: { controls: { disable: true } },
+} satisfies Meta<typeof Pagination>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  render: () => (
+    <Pagination>
+      <PaginationContent>
+        <PaginationItem>
+          <PaginationPrevious href="#1" />
+        </PaginationItem>
+        <PaginationItem>
+          <PaginationLink href="#1">1</PaginationLink>
+        </PaginationItem>
+        <PaginationItem>
+          <PaginationLink href="#2" isActive>
+            2
+          </PaginationLink>
+        </PaginationItem>
+        <PaginationItem>
+          <PaginationLink href="#3">3</PaginationLink>
+        </PaginationItem>
+        <PaginationItem>
+          <PaginationEllipsis />
+        </PaginationItem>
+        <PaginationItem>
+          <PaginationLink href="#12">12</PaginationLink>
+        </PaginationItem>
+        <PaginationItem>
+          <PaginationNext href="#3" />
+        </PaginationItem>
+      </PaginationContent>
+    </Pagination>
+  ),
+};
+
+export const Compact: Story = {
+  render: () => (
+    <Pagination>
+      <PaginationContent>
+        <PaginationItem>
+          <PaginationPrevious href="#1" />
+        </PaginationItem>
+        <PaginationItem>
+          <PaginationNext href="#3" />
+        </PaginationItem>
+      </PaginationContent>
+    </Pagination>
+  ),
+};
+
+/**
+ * When paging only changes client state there is no URL to link to, so the
+ * pages render as buttons instead — same styling, correct semantics.
+ */
+export const AsButtons: Story = {
+  render: function AsButtons() {
+    const [page, setPage] = useState(2);
+    const pages = [1, 2, 3, 4, 5];
+
+    return (
+      <Pagination>
+        <PaginationContent>
+          <PaginationItem>
+            <PaginationLink asChild size="sm" className="gap-1 px-2.5">
+              <button
+                type="button"
+                aria-label="Go to previous page"
+                disabled={page === 1}
+                onClick={() => {
+                  setPage((current) => Math.max(1, current - 1));
+                }}
+              >
+                Previous
+              </button>
+            </PaginationLink>
+          </PaginationItem>
+          {pages.map((value) => (
+            <PaginationItem key={value}>
+              <PaginationLink asChild isActive={value === page}>
+                <button
+                  type="button"
+                  aria-label={`Go to page ${String(value)}`}
+                  onClick={() => {
+                    setPage(value);
+                  }}
+                >
+                  {value}
+                </button>
+              </PaginationLink>
+            </PaginationItem>
+          ))}
+          <PaginationItem>
+            <PaginationLink asChild size="sm" className="gap-1 px-2.5">
+              <button
+                type="button"
+                aria-label="Go to next page"
+                disabled={page === pages.length}
+                onClick={() => {
+                  setPage((current) => Math.min(pages.length, current + 1));
+                }}
+              >
+                Next
+              </button>
+            </PaginationLink>
+          </PaginationItem>
+        </PaginationContent>
+      </Pagination>
+    );
+  },
+};

package/src/components/pagination/pagination.test.tsx

@@ -0,0 +1,119 @@
+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 {
+  Pagination,
+  PaginationContent,
+  PaginationEllipsis,
+  PaginationItem,
+  PaginationLink,
+  PaginationNext,
+  PaginationPrevious,
+} from "./pagination";
+
+function Example({ current = 2 }: { current?: number } = {}) {
+  return (
+    <Pagination>
+      <PaginationContent>
+        <PaginationItem>
+          <PaginationPrevious href="#1" />
+        </PaginationItem>
+        {[1, 2, 3].map((page) => (
+          <PaginationItem key={page}>
+            <PaginationLink href={`#${String(page)}`} isActive={page === current}>
+              {page}
+            </PaginationLink>
+          </PaginationItem>
+        ))}
+        <PaginationItem>
+          <PaginationEllipsis />
+        </PaginationItem>
+        <PaginationItem>
+          <PaginationLink href="#12">12</PaginationLink>
+        </PaginationItem>
+        <PaginationItem>
+          <PaginationNext href="#3" />
+        </PaginationItem>
+      </PaginationContent>
+    </Pagination>
+  );
+}
+
+describe("Pagination", () => {
+  it("is a named navigation landmark", () => {
+    render(<Example />);
+    expect(screen.getByRole("navigation", { name: "Pagination" })).toBeInTheDocument();
+  });
+
+  it("marks the current page with aria-current", () => {
+    render(<Example current={2} />);
+
+    const current = screen.getByRole("link", { name: "2" });
+    expect(current).toHaveAttribute("aria-current", "page");
+    expect(screen.getByRole("link", { name: "1" })).not.toHaveAttribute("aria-current");
+  });
+
+  it("names the previous and next controls", () => {
+    render(<Example />);
+    expect(screen.getByRole("link", { name: "Go to previous page" })).toBeInTheDocument();
+    expect(screen.getByRole("link", { name: "Go to next page" })).toBeInTheDocument();
+  });
+
+  it("renders pages as links, so they can be shared and opened in a tab", () => {
+    render(<Example />);
+    expect(screen.getByRole("link", { name: "2" })).toHaveAttribute("href", "#2");
+  });
+
+  it("hides the ellipsis but keeps a readable equivalent", () => {
+    const { container } = render(<Example />);
+    const ellipsis = container.querySelector("[data-slot='pagination-ellipsis']");
+
+    expect(ellipsis).toHaveAttribute("aria-hidden", "true");
+    expect(ellipsis).toHaveTextContent("More pages");
+  });
+
+  it("renders as buttons via asChild when paging is client state", async () => {
+    const onClick = vi.fn();
+    const user = userEvent.setup();
+
+    render(
+      <Pagination>
+        <PaginationContent>
+          <PaginationItem>
+            <PaginationLink asChild isActive>
+              <button type="button" onClick={onClick}>
+                1
+              </button>
+            </PaginationLink>
+          </PaginationItem>
+        </PaginationContent>
+      </Pagination>,
+    );
+
+    const button = screen.getByRole("button", { name: "1" });
+    expect(button).toHaveAttribute("aria-current", "page");
+
+    await user.click(button);
+    expect(onClick).toHaveBeenCalledTimes(1);
+  });
+
+  it("is reachable by keyboard", async () => {
+    const user = userEvent.setup();
+    render(<Example />);
+
+    await user.tab();
+    expect(screen.getByRole("link", { name: "Go to previous page" })).toHaveFocus();
+  });
+
+  it("styles the active page differently", () => {
+    render(<Example current={3} />);
+    expect(screen.getByRole("link", { name: "3" })).toHaveAttribute("data-active", "true");
+  });
+
+  it("has no accessibility violations", async () => {
+    const { container } = render(<Example />);
+    await expectNoA11yViolations(container);
+  });
+});

package/src/components/pagination/pagination.tsx

@@ -0,0 +1,142 @@
+import { Slot } from "radix-ui";
+import type { ComponentPropsWithRef } from "react";
+
+import { buttonVariants } from "@/components/button";
+import { cn } from "@/lib/utils";
+
+/**
+ * Navigation between pages of a list.
+ *
+ * Rendered as links by default, not buttons: a page of results is a place, so
+ * it should be shareable, openable in a new tab and part of history. Use
+ * `asChild` to hand off to your router's link. For pagination that only changes
+ * client state, render buttons instead — `PaginationLink` accepts either.
+ */
+export function Pagination({ className, ...props }: ComponentPropsWithRef<"nav">) {
+  return (
+    <nav
+      // A named landmark, so it can be jumped to and is distinguishable from
+      // the page's main navigation.
+      aria-label="Pagination"
+      data-slot="pagination"
+      className={cn("mx-auto flex w-full justify-center", className)}
+      {...props}
+    />
+  );
+}
+
+export function PaginationContent({ className, ...props }: ComponentPropsWithRef<"ul">) {
+  return (
+    <ul
+      data-slot="pagination-content"
+      className={cn("flex flex-row items-center gap-1", className)}
+      {...props}
+    />
+  );
+}
+
+export function PaginationItem({ className, ...props }: ComponentPropsWithRef<"li">) {
+  return <li data-slot="pagination-item" className={cn(className)} {...props} />;
+}
+
+export interface PaginationLinkProps extends ComponentPropsWithRef<"a"> {
+  /** Marks the page the user is on. Sets aria-current="page". */
+  isActive?: boolean;
+  size?: "sm" | "md" | "icon" | "icon-sm";
+  asChild?: boolean;
+}
+
+export function PaginationLink({
+  className,
+  isActive,
+  size = "icon",
+  asChild,
+  ...props
+}: PaginationLinkProps) {
+  const Comp = asChild ? Slot.Root : "a";
+
+  return (
+    <Comp
+      data-slot="pagination-link"
+      // aria-current is what tells a screen reader user where they are; styling
+      // the active page differently does nothing on its own.
+      aria-current={isActive ? "page" : undefined}
+      data-active={isActive || undefined}
+      className={cn(
+        buttonVariants({ variant: isActive ? "outline" : "ghost", size }),
+        isActive && "border-border-strong font-medium",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+export function PaginationPrevious({ className, ...props }: PaginationLinkProps) {
+  return (
+    <PaginationLink
+      aria-label="Go to previous page"
+      size="sm"
+      className={cn("gap-1 px-2.5", className)}
+      {...props}
+    >
+      <svg viewBox="0 0 24 24" fill="none" aria-hidden="true" className="size-4">
+        <path
+          d="m15 18-6-6 6-6"
+          stroke="currentColor"
+          strokeWidth="2"
+          strokeLinecap="round"
+          strokeLinejoin="round"
+        />
+      </svg>
+      <span className="hidden sm:inline">Previous</span>
+    </PaginationLink>
+  );
+}
+
+export function PaginationNext({ className, ...props }: PaginationLinkProps) {
+  return (
+    <PaginationLink
+      aria-label="Go to next page"
+      size="sm"
+      className={cn("gap-1 px-2.5", className)}
+      {...props}
+    >
+      <span className="hidden sm:inline">Next</span>
+      <svg viewBox="0 0 24 24" fill="none" aria-hidden="true" className="size-4">
+        <path
+          d="m9 18 6-6-6-6"
+          stroke="currentColor"
+          strokeWidth="2"
+          strokeLinecap="round"
+          strokeLinejoin="round"
+        />
+      </svg>
+    </PaginationLink>
+  );
+}
+
+/**
+ * Stands in for a run of skipped pages.
+ *
+ * Hidden from assistive technology and given screen-reader text, because "…"
+ * is announced as nothing useful and the gap is already implied by the page
+ * numbers either side.
+ */
+export function PaginationEllipsis({ className, ...props }: ComponentPropsWithRef<"span">) {
+  return (
+    <span
+      data-slot="pagination-ellipsis"
+      aria-hidden="true"
+      className={cn("grid size-9 place-items-center text-muted-foreground", className)}
+      {...props}
+    >
+      <svg viewBox="0 0 24 24" fill="none" className="size-4">
+        <circle cx="5" cy="12" r="1.5" fill="currentColor" />
+        <circle cx="12" cy="12" r="1.5" fill="currentColor" />
+        <circle cx="19" cy="12" r="1.5" fill="currentColor" />
+      </svg>
+      <span className="sr-only">More pages</span>
+    </span>
+  );
+}

package/src/components/popover/index.ts

@@ -0,0 +1,9 @@
+export {
+  Popover,
+  PopoverAnchor,
+  PopoverArrow,
+  PopoverClose,
+  PopoverContent,
+  PopoverTrigger,
+  type PopoverContentProps,
+} from "./popover";

package/src/components/popover/meta.ts

@@ -0,0 +1,18 @@
+import { defineMeta } from "@/registry/schema";
+
+export const meta = defineMeta({
+  name: "popover",
+  title: "Popover",
+  description: "Rich floating content anchored to a trigger.",
+  category: "overlay",
+  status: "stable",
+  dependencies: ["radix-ui"],
+  registryDependencies: [],
+  files: ["popover.tsx"],
+  a11y:
+    'The content has role="dialog" and therefore REQUIRES an accessible name — pass aria-label, ' +
+    "or aria-labelledby pointing at a heading inside it. A development-only warning fires if " +
+    "neither is present. The trigger exposes aria-expanded and aria-controls; Escape closes and " +
+    "returns focus to it. Non-modal by default, so the rest of the page stays reachable; pass " +
+    "`modal` only when the content is a task the user must finish or abandon.",
+});

package/src/components/popover/popover.stories.tsx

@@ -0,0 +1,84 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+
+import { Button } from "@/components/button";
+import { Input } from "@/components/input";
+import { Label } from "@/components/label";
+
+import { Popover, PopoverArrow, PopoverContent, PopoverTrigger } from "./popover";
+
+const meta = {
+  title: "Overlays/Popover",
+  component: PopoverContent,
+  args: { side: "bottom", align: "center" },
+  argTypes: {
+    side: { control: "inline-radio", options: ["top", "right", "bottom", "left"] },
+    align: { control: "inline-radio", options: ["start", "center", "end"] },
+  },
+} satisfies Meta<typeof PopoverContent>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  render: (args) => (
+    <Popover>
+      <PopoverTrigger asChild>
+        <Button variant="outline">Dimensions</Button>
+      </PopoverTrigger>
+      <PopoverContent {...args} aria-labelledby="dimensions-heading">
+        <div className="grid gap-3">
+          <div className="space-y-1">
+            <h4 id="dimensions-heading" className="text-sm font-medium">
+              Dimensions
+            </h4>
+            <p className="text-xs text-muted-foreground">Set the layout for the layer.</p>
+          </div>
+          <div className="grid gap-2">
+            <div className="grid grid-cols-3 items-center gap-2">
+              <Label htmlFor="width">Width</Label>
+              <Input id="width" inputSize="sm" defaultValue="100%" className="col-span-2" />
+            </div>
+            <div className="grid grid-cols-3 items-center gap-2">
+              <Label htmlFor="height">Height</Label>
+              <Input id="height" inputSize="sm" defaultValue="24px" className="col-span-2" />
+            </div>
+          </div>
+        </div>
+      </PopoverContent>
+    </Popover>
+  ),
+};
+
+/** Growth direction follows the anchor, so every side reads as one motion. */
+export const Sides: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="flex flex-wrap gap-3">
+      {(["top", "right", "bottom", "left"] as const).map((side) => (
+        <Popover key={side}>
+          <PopoverTrigger asChild>
+            <Button variant="outline">{side}</Button>
+          </PopoverTrigger>
+          <PopoverContent side={side} className="w-48" aria-label={`Opened from the ${side}`}>
+            <p className="text-sm">Opened from the {side}.</p>
+          </PopoverContent>
+        </Popover>
+      ))}
+    </div>
+  ),
+};
+
+export const WithArrow: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <Popover>
+      <PopoverTrigger asChild>
+        <Button variant="outline">Show details</Button>
+      </PopoverTrigger>
+      <PopoverContent className="w-56" aria-label="Deployment details">
+        <p className="text-sm">Deployed 4 minutes ago from main.</p>
+        <PopoverArrow />
+      </PopoverContent>
+    </Popover>
+  ),
+};

package/src/components/popover/popover.test.tsx

@@ -0,0 +1,163 @@
+import { render, screen, waitFor } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { describe, expect, it, vi } from "vitest";
+
+import { expectNoA11yViolations } from "../../../test/a11y";
+import { Button } from "../button";
+import { Popover, PopoverArrow, PopoverClose, PopoverContent, PopoverTrigger } from "./popover";
+
+function Example() {
+  return (
+    <Popover>
+      <PopoverTrigger asChild>
+        <Button>Open settings</Button>
+      </PopoverTrigger>
+      <PopoverContent aria-labelledby="dimensions-heading">
+        <p id="dimensions-heading">Dimensions</p>
+        <PopoverClose>Done</PopoverClose>
+      </PopoverContent>
+    </Popover>
+  );
+}
+
+describe("Popover", () => {
+  it("is closed until the trigger is activated", async () => {
+    const user = userEvent.setup();
+    render(<Example />);
+
+    expect(screen.queryByText("Dimensions")).not.toBeInTheDocument();
+    await user.click(screen.getByRole("button", { name: "Open settings" }));
+    expect(await screen.findByText("Dimensions")).toBeInTheDocument();
+  });
+
+  it("reports its state on the trigger", async () => {
+    const user = userEvent.setup();
+    render(<Example />);
+
+    const trigger = screen.getByRole("button", { name: "Open settings" });
+    expect(trigger).toHaveAttribute("aria-expanded", "false");
+
+    await user.click(trigger);
+    await waitFor(() => {
+      expect(trigger).toHaveAttribute("aria-expanded", "true");
+    });
+  });
+
+  it("opens from the keyboard", async () => {
+    const user = userEvent.setup();
+    render(<Example />);
+
+    await user.tab();
+    await user.keyboard("{Enter}");
+    expect(await screen.findByText("Dimensions")).toBeInTheDocument();
+  });
+
+  it("closes on Escape and restores focus to the trigger", async () => {
+    const user = userEvent.setup();
+    render(<Example />);
+
+    const trigger = screen.getByRole("button", { name: "Open settings" });
+    await user.click(trigger);
+    await screen.findByText("Dimensions");
+
+    await user.keyboard("{Escape}");
+    await waitFor(() => {
+      expect(screen.queryByText("Dimensions")).not.toBeInTheDocument();
+    });
+    await waitFor(() => {
+      expect(trigger).toHaveFocus();
+    });
+  });
+
+  it("closes from PopoverClose", async () => {
+    const user = userEvent.setup();
+    render(<Example />);
+    await user.click(screen.getByRole("button", { name: "Open settings" }));
+    await screen.findByText("Dimensions");
+
+    await user.click(screen.getByText("Done"));
+    await waitFor(() => {
+      expect(screen.queryByText("Dimensions")).not.toBeInTheDocument();
+    });
+  });
+
+  it("merges a consumer className", async () => {
+    const user = userEvent.setup();
+    render(
+      <Popover>
+        <PopoverTrigger>Open</PopoverTrigger>
+        <PopoverContent className="w-96" aria-label="Details" data-testid="content">
+          Content
+        </PopoverContent>
+      </Popover>,
+    );
+
+    await user.click(screen.getByText("Open"));
+    const content = await screen.findByTestId("content");
+    expect(content).toHaveClass("w-96");
+    expect(content).not.toHaveClass("w-72");
+  });
+
+  it("warns in development when the content has no accessible name", async () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => undefined);
+    const user = userEvent.setup();
+    render(
+      <Popover>
+        <PopoverTrigger>Open</PopoverTrigger>
+        <PopoverContent>Unnamed</PopoverContent>
+      </Popover>,
+    );
+
+    await user.click(screen.getByText("Open"));
+    await screen.findByText("Unnamed");
+
+    expect(warn).toHaveBeenCalledWith(expect.stringContaining("Missing accessible name"));
+    warn.mockRestore();
+  });
+
+  it("does not warn when a name is supplied", async () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => undefined);
+    const user = userEvent.setup();
+    render(
+      <Popover>
+        <PopoverTrigger>Open</PopoverTrigger>
+        <PopoverContent aria-label="Details">Named</PopoverContent>
+      </Popover>,
+    );
+
+    await user.click(screen.getByText("Open"));
+    await screen.findByText("Named");
+
+    expect(warn).not.toHaveBeenCalled();
+    warn.mockRestore();
+  });
+
+  it("renders an arrow that is hidden from assistive technology", async () => {
+    const user = userEvent.setup();
+    const { baseElement } = render(
+      <Popover>
+        <PopoverTrigger>Open</PopoverTrigger>
+        <PopoverContent aria-label="Details">
+          Details
+          <PopoverArrow />
+        </PopoverContent>
+      </Popover>,
+    );
+
+    await user.click(screen.getByText("Open"));
+    await screen.findByText("Details");
+
+    const arrow = baseElement.querySelector("[data-slot='popover-arrow']");
+    expect(arrow).toBeInTheDocument();
+    expect(arrow).toHaveClass("fill-popover");
+  });
+
+  it("has no accessibility violations while open", async () => {
+    const user = userEvent.setup();
+    const { baseElement } = render(<Example />);
+    await user.click(screen.getByRole("button", { name: "Open settings" }));
+    await screen.findByText("Dimensions");
+
+    await expectNoA11yViolations(baseElement);
+  });
+});