@elabs-ai/components-ui 4.0.0 → 4.1.0

package/src/components/page-shell/page-shell.stories.tsx

@@ -103,3 +103,166 @@ export const ToolbarSticky: Story = {
     await expect(Math.abs(headerTopAfterScroll - headerTopStuck)).toBeLessThanOrEqual(1);
   },
 };
+
+/**
+ * `scroll="content"` makes `PageShell` itself the scroll port, for embedding
+ * inside a `SidebarInset` whose height is already bounded — the app chrome
+ * outside it (the top bar here) never moves.
+ */
+export const ScrollContent: Story = {
+  render: function ScrollContentStory() {
+    return (
+      <div className="flex h-[420px] flex-col border border-border">
+        <div
+          data-testid="app-topbar"
+          className="shrink-0 border-b border-border bg-sidebar px-4 py-2 text-body"
+        >
+          App chrome outside PageShell
+        </div>
+        <PageShell scroll="content" data-testid="scroll-content-shell">
+          <div className="flex flex-col gap-3">
+            {Array.from({ length: 40 }, (_, i) => (
+              <div
+                key={i}
+                data-testid={i === 20 ? "marker-row" : undefined}
+                className="rounded-lg border bg-card p-4 text-body"
+              >
+                Row {i + 1}
+              </div>
+            ))}
+          </div>
+        </PageShell>
+      </div>
+    );
+  },
+  play: async ({ canvasElement }) => {
+    const shell = canvasElement.querySelector<HTMLElement>('[data-testid="scroll-content-shell"]');
+    const marker = canvasElement.querySelector<HTMLElement>('[data-testid="marker-row"]');
+    const topbar = canvasElement.querySelector<HTMLElement>('[data-testid="app-topbar"]');
+
+    await expect(shell).not.toBeNull();
+    await expect(marker).not.toBeNull();
+    await expect(topbar).not.toBeNull();
+
+    await expect(getComputedStyle(shell!).overflowY).toBe("auto");
+
+    // scroll="content" makes this element the scroll port, so it defaults to
+    // keyboard-operable (WCAG 2.1.1, axe `scrollable-region-focusable`). Read
+    // the ATTRIBUTE, not the `tabIndex` IDL getter — the getter reports a
+    // default for an element that carries no attribute at all.
+    await expect(shell!.getAttribute("tabindex")).toBe("0");
+    // And the rung is the inset one: `scroll="content"` is documented for use
+    // inside a `SidebarInset`, whose `overflow-hidden` clips both layers of the
+    // plain rung. `classList` is an exact token match, so this cannot be
+    // satisfied by `focus-ring-inset` being a superstring of `focus-ring`.
+    await expect(shell!.classList.contains("focus-ring-inset")).toBe(true);
+    await expect(shell!.classList.contains("focus-ring")).toBe(false);
+
+    const topbarTopBefore = topbar!.getBoundingClientRect().top;
+    const markerTopBefore = marker!.getBoundingClientRect().top;
+
+    shell!.scrollTop = 300;
+
+    await waitFor(() => {
+      expect(marker!.getBoundingClientRect().top).toBeLessThan(markerTopBefore);
+    });
+
+    // The chrome outside PageShell never moved — PageShell owns its own scroll.
+    await expect(topbar!.getBoundingClientRect().top).toBe(topbarTopBefore);
+  },
+};
+
+/**
+ * `scroll="fill"` fills its parent and scrolls nothing itself — a child (here
+ * an inner list) owns the overflow instead.
+ */
+export const ScrollFill: Story = {
+  render: function ScrollFillStory() {
+    return (
+      <div className="h-[320px] border border-border">
+        <PageShell
+          scroll="fill"
+          data-testid="scroll-fill-shell"
+          contentClassName="flex h-full min-h-0 flex-col"
+        >
+          <div
+            data-testid="inner-scroll"
+            // The inner list is the scroll port here (`scroll="fill"` means
+            // PageShell itself owns none of it), so THIS element needs the
+            // keyboard-operable fix (WCAG 2.1.1, axe
+            // `scrollable-region-focusable`) — same precedent as `DialogBody`.
+            tabIndex={0}
+            className="min-h-0 flex-1 space-y-2 overflow-y-auto rounded-lg border bg-card p-2 focus-ring"
+          >
+            {Array.from({ length: 40 }, (_, i) => (
+              <div
+                key={i}
+                data-testid={i === 20 ? "marker-row" : undefined}
+                className="rounded-md bg-surface-muted p-2 text-body"
+              >
+                Row {i + 1}
+              </div>
+            ))}
+          </div>
+        </PageShell>
+      </div>
+    );
+  },
+  play: async ({ canvasElement }) => {
+    const shell = canvasElement.querySelector<HTMLElement>('[data-testid="scroll-fill-shell"]');
+    const inner = canvasElement.querySelector<HTMLElement>('[data-testid="inner-scroll"]');
+    const marker = canvasElement.querySelector<HTMLElement>('[data-testid="marker-row"]');
+
+    await expect(shell).not.toBeNull();
+    await expect(inner).not.toBeNull();
+    await expect(marker).not.toBeNull();
+
+    // PageShell itself does not scroll — the inner list owns the overflow.
+    await expect(getComputedStyle(shell!).overflow).toBe("hidden");
+    await expect(getComputedStyle(inner!).overflowY).toBe("auto");
+
+    const markerTopBefore = marker!.getBoundingClientRect().top;
+    inner!.scrollTop = 300;
+    await waitFor(() => {
+      expect(marker!.getBoundingClientRect().top).toBeLessThan(markerTopBefore);
+    });
+  },
+};
+
+/**
+ * `headerGutter` reserves a fixed-height header row so a page title lands at
+ * the same vertical coordinate on every route that turns it on.
+ */
+export const WithHeaderGutter: Story = {
+  render: () => (
+    <PageShell headerGutter header={<h1 className="text-title font-medium">Pipeline runs</h1>}>
+      <div className="rounded-xl border bg-card p-6 text-body text-muted-foreground">Content</div>
+    </PageShell>
+  ),
+  play: async ({ canvasElement }) => {
+    const gutter = canvasElement.querySelector<HTMLElement>('[data-slot="page-shell-header"]');
+    await expect(gutter).not.toBeNull();
+    await expect(getComputedStyle(gutter!).minHeight).toBe("48px");
+  },
+};
+
+/**
+ * The reserved row renders even on a route with no header at all — an empty
+ * band, not a missing one — which is what keeps titles aligned across routes
+ * that do and don't have one (ADR 0035).
+ */
+export const WithHeaderGutterNoHeader: Story = {
+  render: () => (
+    <PageShell headerGutter>
+      <div className="rounded-xl border bg-card p-6 text-body text-muted-foreground">
+        This route has no header, but the reserved row above still holds its space.
+      </div>
+    </PageShell>
+  ),
+  play: async ({ canvasElement }) => {
+    const gutter = canvasElement.querySelector<HTMLElement>('[data-slot="page-shell-header"]');
+    await expect(gutter).not.toBeNull();
+    await expect(gutter!.textContent).toBe("");
+    await expect(getComputedStyle(gutter!).minHeight).toBe("48px");
+  },
+};

package/src/components/page-shell/page-shell.test.tsx

@@ -1,7 +1,18 @@
+import { createRef } from "react";
 import { describe, expect, it } from "vitest";
 import { render, screen } from "@testing-library/react";
 import { PageShell } from "./page-shell";
 
+/** True if any element in the tree carries a `min-h-*` utility class. */
+function hasAnyMinHeightClass(root: HTMLElement): boolean {
+  const all = [root, ...Array.from(root.querySelectorAll<HTMLElement>("*"))];
+  return all.some((el) => /(^|\s)min-h-\S/.test(el.className));
+}
+
+const HEADER_VARIANTS = [undefined, "default", "toolbar"] as const;
+const WIDTHS = [undefined, "md", "lg", "xl", "full"] as const;
+const HEADERS = [false, true] as const;
+
 describe("PageShell", () => {
   it("headerVariant omitted: renders the header inline with no sticky wrapper (AC2 — byte-identical default)", () => {
     render(<PageShell header={<div data-testid="hdr">H</div>}>body</PageShell>);
@@ -54,4 +65,222 @@ describe("PageShell", () => {
 
     expect(document.querySelector('[data-slot="page-shell-toolbar-header"]')).toBeNull();
   });
+
+  describe("component-API baseline (forwardRef, spread, data-slot)", () => {
+    it("forwards a ref to the root element", () => {
+      const ref = createRef<HTMLDivElement>();
+      const { container } = render(<PageShell ref={ref}>body</PageShell>);
+
+      expect(ref.current).not.toBeNull();
+      expect(ref.current).toBe(container.firstElementChild);
+    });
+
+    it("spreads extra DOM props (id, data-testid, aria-label) onto the root", () => {
+      render(
+        <PageShell id="my-page" data-testid="ps-root" aria-label="Runs">
+          body
+        </PageShell>,
+      );
+
+      const root = screen.getByTestId("ps-root");
+      expect(root.id).toBe("my-page");
+      expect(root.getAttribute("aria-label")).toBe("Runs");
+    });
+
+    it('carries data-slot="page-shell" on the root and "page-shell-content" on the inner column', () => {
+      const { container } = render(<PageShell>body</PageShell>);
+      const root = container.firstElementChild as HTMLElement;
+
+      expect(root.getAttribute("data-slot")).toBe("page-shell");
+      expect(root.querySelector('[data-slot="page-shell-content"]')).not.toBeNull();
+    });
+  });
+
+  describe('scroll="body" (default) — byte-identical to pre-R6, across every header/headerVariant/width combination', () => {
+    for (const headerVariant of HEADER_VARIANTS) {
+      for (const width of WIDTHS) {
+        for (const withHeader of HEADERS) {
+          const label = `header=${withHeader} headerVariant=${headerVariant ?? "(unset)"} width=${width ?? "(unset)"}`;
+
+          it(`root class is exactly the pre-R6 literal, no min-h-* anywhere, no gutter row — ${label}`, () => {
+            const { container } = render(
+              <PageShell
+                header={withHeader ? <div data-testid="hdr">H</div> : undefined}
+                headerVariant={headerVariant}
+                width={width}
+              >
+                body
+              </PageShell>,
+            );
+            const root = container.firstElementChild as HTMLElement;
+
+            // (1) The additive default: root's own class string is unchanged, whatever
+            // the header/headerVariant/width combination — those axes never touch it.
+            expect(root.className).toBe("w-full px-4 py-6 sm:px-6 lg:px-8");
+
+            // (2) No min-h-* class anywhere in the tree — the gutter mechanism is
+            // entirely absent, not merely invisible.
+            expect(hasAnyMinHeightClass(root)).toBe(false);
+
+            // (3) No gutter row — `headerGutter: false` must not produce the empty
+            // reserved row ADR 0035 calls "the whole mechanism".
+            expect(root.querySelector('[data-slot="page-shell-header"]')).toBeNull();
+
+            // (4) The header itself renders exactly where it always did.
+            if (withHeader) {
+              const hdr = screen.getByTestId("hdr");
+              if (headerVariant === "toolbar") {
+                const toolbarWrapper = root.querySelector(
+                  '[data-slot="page-shell-toolbar-header"]',
+                );
+                expect(toolbarWrapper).not.toBeNull();
+                expect(toolbarWrapper).toContainElement(hdr);
+              } else {
+                expect(root.querySelector('[data-slot="page-shell-toolbar-header"]')).toBeNull();
+              }
+            }
+          });
+        }
+      }
+    }
+
+    it('passing scroll="body" explicitly is identical to omitting it', () => {
+      const { container: withProp } = render(<PageShell scroll="body">body</PageShell>);
+      const { container: omitted } = render(<PageShell>body</PageShell>);
+
+      expect((withProp.firstElementChild as HTMLElement).className).toBe(
+        (omitted.firstElementChild as HTMLElement).className,
+      );
+    });
+  });
+
+  describe("scroll modes", () => {
+    it('scroll="content" makes the inner column the scroll container', () => {
+      const { container } = render(<PageShell scroll="content">body</PageShell>);
+      const root = container.firstElementChild as HTMLElement;
+      expect(root.className).toContain("min-h-0");
+      expect(root.className).toContain("flex-1");
+      expect(root.className).toContain("overflow-y-auto");
+      // The base padding/width classes are still present — additive, not a replacement.
+      expect(root.className).toContain("w-full");
+    });
+
+    it('scroll="fill" fills its parent and does not scroll itself', () => {
+      const { container } = render(<PageShell scroll="fill">body</PageShell>);
+      const root = container.firstElementChild as HTMLElement;
+      expect(root.className).toContain("h-full");
+      expect(root.className).toContain("overflow-hidden");
+    });
+
+    it("a caller className can still override a scroll-mode utility (className merges last)", () => {
+      const { container } = render(
+        <PageShell scroll="fill" className="overflow-visible">
+          body
+        </PageShell>,
+      );
+      const root = container.firstElementChild as HTMLElement;
+      expect(root.className).toContain("overflow-visible");
+      expect(root.className).not.toContain("overflow-hidden");
+    });
+
+    it('scroll="content" defaults to keyboard-operable (WCAG 2.1.1 / axe scrollable-region-focusable)', () => {
+      const { container } = render(<PageShell scroll="content">body</PageShell>);
+      const root = container.firstElementChild as HTMLElement;
+      // `getAttribute`, never the `tabIndex` IDL getter: that getter answers a
+      // DEFAULT (-1 here, 0 for natively focusable elements) whether or not the
+      // attribute was ever written, so `expect(root.tabIndex).toBe(-1)` and the
+      // "gains no tab stop" cases below would pass on a component that emits
+      // nothing at all.
+      expect(root.getAttribute("tabindex")).toBe("0");
+      // `classList.contains` is an EXACT token match. `toContain("focus-ring")`
+      // is a substring test that `focus-ring-inset` satisfies, so it could not
+      // tell the two rungs apart — it passed before this fix and would pass
+      // after it, proving nothing either way.
+      expect(root.classList.contains("focus-ring-inset")).toBe(true);
+      // The plain rung must be ABSENT, not merely accompanied: both of its
+      // layers are drawn outside the element's box, and `scroll="content"`'s
+      // own doc sends callers to put this inside a `SidebarInset`, whose
+      // `overflow-hidden` clips exactly that.
+      expect(root.classList.contains("focus-ring")).toBe(false);
+    });
+
+    it('scroll="content" lets a caller opt out of the default tab stop', () => {
+      const { container } = render(
+        <PageShell scroll="content" tabIndex={-1}>
+          body
+        </PageShell>,
+      );
+      const root = container.firstElementChild as HTMLElement;
+      expect(root.getAttribute("tabindex")).toBe("-1");
+    });
+
+    it('scroll="fill" does not gain a default tab stop — the child scroll region owns it', () => {
+      const { container } = render(<PageShell scroll="fill">body</PageShell>);
+      const root = container.firstElementChild as HTMLElement;
+      expect(root.getAttribute("tabindex")).toBeNull();
+      expect(root.classList.contains("focus-ring")).toBe(false);
+      expect(root.classList.contains("focus-ring-inset")).toBe(false);
+    });
+
+    it('scroll="body" (default) gains no tabIndex attribute — byte-identical', () => {
+      const { container } = render(<PageShell>body</PageShell>);
+      const root = container.firstElementChild as HTMLElement;
+      expect(root.getAttribute("tabindex")).toBeNull();
+    });
+  });
+
+  describe("headerGutter", () => {
+    it("reserves a fixed header row so titles land at one coordinate, when a header is present", () => {
+      render(
+        <PageShell headerGutter header={<h1>Runs</h1>}>
+          body
+        </PageShell>,
+      );
+      const gutter = screen.getByText("Runs").closest('[data-slot="page-shell-header"]');
+      expect(gutter).not.toBeNull();
+      expect((gutter as HTMLElement).className).toContain("min-h-(--page-shell-header-gutter)");
+    });
+
+    it("renders the reserved row even when NO header is supplied — the empty row IS the mechanism (ADR 0035)", () => {
+      const { container } = render(<PageShell headerGutter>body</PageShell>);
+      const root = container.firstElementChild as HTMLElement;
+
+      const gutter = root.querySelector('[data-slot="page-shell-header"]');
+      expect(gutter).not.toBeNull();
+      expect((gutter as HTMLElement).className).toContain("min-h-(--page-shell-header-gutter)");
+      // It really is empty — no header content leaked in.
+      expect((gutter as HTMLElement).textContent).toBe("");
+    });
+
+    it("declares the --page-shell-header-gutter default (--spacing(12)) on the root when on", () => {
+      const { container } = render(<PageShell headerGutter>body</PageShell>);
+      const root = container.firstElementChild as HTMLElement;
+      expect(root.className).toContain("[--page-shell-header-gutter:--spacing(12)]");
+    });
+
+    it("is retunable per surface: a caller className overrides the default gutter height", () => {
+      const { container } = render(
+        <PageShell headerGutter className="[--page-shell-header-gutter:--spacing(16)]">
+          body
+        </PageShell>,
+      );
+      const root = container.firstElementChild as HTMLElement;
+      expect(root.className).toContain("[--page-shell-header-gutter:--spacing(16)]");
+      expect(root.className).not.toContain("--spacing(12)");
+    });
+
+    it('composes with headerVariant="toolbar": the sticky bar nests inside the reserved row', () => {
+      render(
+        <PageShell headerGutter headerVariant="toolbar" header={<div data-testid="hdr">H</div>}>
+          body
+        </PageShell>,
+      );
+      const gutter = document.querySelector('[data-slot="page-shell-header"]');
+      const toolbar = document.querySelector('[data-slot="page-shell-toolbar-header"]');
+      expect(gutter).not.toBeNull();
+      expect(toolbar).not.toBeNull();
+      expect(gutter).toContainElement(toolbar as HTMLElement);
+      expect(toolbar).toContainElement(screen.getByTestId("hdr"));
+    });
+  });
 });

package/src/components/page-shell/page-shell.tsx

@@ -1,7 +1,7 @@
-import { type ReactNode } from "react";
+import { forwardRef, type ComponentProps, type ReactNode } from "react";
 import { cn } from "../../lib/cn";
 
-export interface PageShellProps {
+export interface PageShellProps extends ComponentProps<"div"> {
   children: ReactNode;
   /** Optional header row (often a <SectionHeader />, or a <ViewToolbar> — see headerVariant). */
   header?: ReactNode;
@@ -20,6 +20,37 @@ export interface PageShellProps {
   headerVariant?: "default" | "toolbar";
   /** Constrain content width. Defaults to "xl". */
   width?: "md" | "lg" | "xl" | "full";
+  /**
+   * "body" (default) — the page scrolls with the document. Byte-identical to
+   * the pre-#R6 behaviour; existing callers are unaffected.
+   * "content" — this container is the scroll port. Use inside a `SidebarInset`
+   * whose height is already bounded, so the top bar stays put. Defaults its own
+   * `tabIndex` to `0` (a scroll container must be keyboard-operable — WCAG
+   * 2.1.1, axe `scrollable-region-focusable`), following the `DialogBody`
+   * precedent; pass `tabIndex={-1}` to opt out when the content already
+   * supplies its own focusable child.
+   * "fill" — fills its parent and scrolls nothing itself; a child (a table, a
+   * canvas) owns the scrolling — and owns that child's keyboard reachability
+   * too, the same way.
+   */
+  scroll?: "body" | "content" | "fill";
+  /**
+   * Reserve a fixed header row so a page title lands at identical coordinates
+   * on every route, whether or not that route has a header. Default `false`.
+   *
+   * The row's height is a component-local CSS variable —
+   * `--page-shell-header-gutter`, declared on the root, default `--spacing(12)`
+   * (3rem / 48px at a 16px root — the height a one-line title already occupies
+   * inside the `headerVariant="toolbar"` bar's own `py-3`). It is NOT a theme
+   * token (`pnpm theme-parity:check` does not see it); retune it per surface the
+   * same way `--focus-ring-color` is retargeted elsewhere in this package:
+   * `<PageShell headerGutter className="[--page-shell-header-gutter:--spacing(16)]" />`.
+   *
+   * When `true` the header row renders **even if `header` is omitted** — that
+   * empty row is the whole mechanism, and it is what `headerGutter={false}`
+   * must never produce.
+   */
+  headerGutter?: boolean;
   className?: string;
   contentClassName?: string;
 }
@@ -31,32 +62,84 @@ const widthMap = {
   full: "max-w-none",
 } as const;
 
+const scrollMap = {
+  body: "",
+  content: "min-h-0 flex-1 overflow-y-auto",
+  fill: "h-full min-h-0 overflow-hidden",
+} as const;
+
 /** Page-level content container with consistent padding and max width. */
-export function PageShell({
-  children,
-  header,
-  headerVariant = "default",
-  width = "xl",
-  className,
-  contentClassName,
-}: PageShellProps) {
+export const PageShell = forwardRef<HTMLDivElement, PageShellProps>(function PageShell(
+  {
+    children,
+    header,
+    headerVariant = "default",
+    width = "xl",
+    scroll = "body",
+    headerGutter = false,
+    className,
+    contentClassName,
+    tabIndex,
+    ...props
+  },
+  ref,
+) {
+  // scroll="content" makes this element the scroll port, so it needs the same
+  // keyboard-operable fix `DialogBody`/`ExpandDialogPanes` ship: default the
+  // tab stop to 0, let a caller opt out with an explicit `tabIndex` (typically
+  // `-1`). "body"/"fill" never set a default, so their DOM gains no attribute.
+  const resolvedTabIndex = tabIndex ?? (scroll === "content" ? 0 : undefined);
+
+  const headerNode = header ? (
+    headerVariant === "toolbar" ? (
+      <div
+        data-slot="page-shell-toolbar-header"
+        className="sticky top-0 z-10 border-b border-border bg-background/95 py-3 backdrop-blur"
+      >
+        {header}
+      </div>
+    ) : (
+      header
+    )
+  ) : null;
+
   return (
-    <div className={cn("w-full px-4 py-6 sm:px-6 lg:px-8", className)}>
-      <div className={cn("mx-auto w-full space-y-6", widthMap[width], contentClassName)}>
-        {header ? (
-          headerVariant === "toolbar" ? (
-            <div
-              data-slot="page-shell-toolbar-header"
-              className="sticky top-0 z-10 border-b border-border bg-background/95 py-3 backdrop-blur"
-            >
-              {header}
-            </div>
-          ) : (
-            header
-          )
-        ) : null}
+    <div
+      ref={ref}
+      data-slot="page-shell"
+      tabIndex={resolvedTabIndex}
+      className={cn(
+        "w-full px-4 py-6 sm:px-6 lg:px-8",
+        scrollMap[scroll],
+        // `focus-ring-inset`, NOT `focus-ring`: `scroll="content"`'s own doc
+        // above tells the caller to use it inside a `SidebarInset`, whose
+        // `overflow-hidden` clips both layers of the plain rung — they are
+        // drawn OUTSIDE the element's box. A consumer following that
+        // instruction would get a focusable scroll port with no visible focus
+        // indicator at all. Same reasoning, verbatim, as the app-shell blocks'
+        // own scroll ports.
+        scroll === "content" && "focus-ring-inset",
+        headerGutter && "[--page-shell-header-gutter:--spacing(12)]",
+        className,
+      )}
+      {...props}
+    >
+      <div
+        data-slot="page-shell-content"
+        className={cn("mx-auto w-full space-y-6", widthMap[width], contentClassName)}
+      >
+        {headerGutter ? (
+          <div
+            data-slot="page-shell-header"
+            className="flex min-h-(--page-shell-header-gutter) items-center"
+          >
+            {headerNode}
+          </div>
+        ) : (
+          headerNode
+        )}
         {children}
       </div>
     </div>
   );
-}
+});

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

@@ -0,0 +1,90 @@
+import { describe, expect, it } from "vitest";
+import { render, screen } from "@testing-library/react";
+import { LocaleProvider } from "../locale-provider";
+import { PaginationEllipsis, PaginationNext, PaginationPrevious } from "./pagination";
+
+/**
+ * Pagination had no test file before #18 — its three microcopy sites
+ * (Previous/Next reuse the generic keys, the ellipsis's sr-only "More pages"
+ * is a new namespaced key) are locked here.
+ */
+describe("Pagination — microcopy (#18)", () => {
+  it("PaginationPrevious/PaginationNext keep their shipped English labels", () => {
+    render(
+      <>
+        <PaginationPrevious />
+        <PaginationNext />
+      </>,
+    );
+    expect(screen.getByText("Previous")).toBeInTheDocument();
+    expect(screen.getByText("Next")).toBeInTheDocument();
+  });
+
+  it("PaginationEllipsis keeps its shipped sr-only 'More pages' text", () => {
+    render(<PaginationEllipsis />);
+    expect(screen.getByText("More pages")).toHaveClass("sr-only");
+  });
+
+  it("translates all three via a LocaleProvider (generic + namespaced keys)", () => {
+    render(
+      <LocaleProvider
+        locale="de-DE"
+        messages={{
+          previous: "Zurück",
+          next: "Weiter",
+          "ui.pagination.morePages": "Weitere Seiten",
+        }}
+      >
+        <PaginationPrevious />
+        <PaginationNext />
+        <PaginationEllipsis />
+      </LocaleProvider>,
+    );
+    expect(screen.getByText("Zurück")).toBeInTheDocument();
+    expect(screen.getByText("Weiter")).toBeInTheDocument();
+    expect(screen.getByText("Weitere Seiten")).toHaveClass("sr-only");
+  });
+
+  // #12/#53 review (P2): the `aria-label` overrides visible text content as
+  // the ACCESSIBLE NAME, so a non-English `LocaleProvider` that only
+  // translated the visible `previous`/`next` span left screen-reader users
+  // hearing hardcoded English regardless of locale.
+  describe("accessible name (aria-label) is localized, not just the visible text", () => {
+    it("defaults to the shipped English accessible names", () => {
+      render(
+        <>
+          <PaginationPrevious />
+          <PaginationNext />
+        </>,
+      );
+      expect(screen.getByLabelText("Go to previous page")).toBeInTheDocument();
+      expect(screen.getByLabelText("Go to next page")).toBeInTheDocument();
+    });
+
+    it("routes the aria-label through t() under a non-English LocaleProvider", () => {
+      render(
+        <LocaleProvider
+          locale="de-DE"
+          messages={{
+            previous: "Zurück",
+            next: "Weiter",
+            "ui.pagination.previous": "Zur vorherigen Seite",
+            "ui.pagination.next": "Zur nächsten Seite",
+          }}
+        >
+          <PaginationPrevious />
+          <PaginationNext />
+        </LocaleProvider>,
+      );
+      const prev = screen.getByLabelText("Zur vorherigen Seite");
+      const next = screen.getByLabelText("Zur nächsten Seite");
+      // The visible text is translated too — the accessible name isn't just
+      // masking untranslated visible content.
+      expect(prev).toHaveTextContent("Zurück");
+      expect(next).toHaveTextContent("Weiter");
+      // Neither link's accessible name is the stale hardcoded English string.
+      expect(screen.queryByLabelText("Go to previous page")).not.toBeInTheDocument();
+      expect(screen.queryByLabelText("Go to next page")).not.toBeInTheDocument();
+    });
+  });
+});