From 7560c54556cf555b5a20c7294c7edfcef9a744a2 Mon Sep 17 00:00:00 2001
From: Aaron Reisman <aaron.reisman@plane.so>
Date: Wed, 10 Jun 2026 00:16:59 +0700
Subject: [PATCH 1/5] Add Pagination component (Figma 4762-503)

Composite pagination nav built from semantic HTML: a <nav aria-label> landmark
holding an optional per-page selector, an optional range label, and an ordered
list of page controls (prev/next arrow buttons + page numbers with first/last
anchors and ellipses around a window near the current page).

The four Figma truncation layouts (all-visible / near-start / middle / near-end)
are derived from page/pageCount, not exposed as a variant. The current page is
marked aria-current="page" and disabled; prev/next disable at the bounds and
their arrows mirror under RTL. Tokens (24px slots, radius/sm pages, radius/md
arrows, text/13, transparent-active selected fill) match the Figma frame.
---
 .../src/components/pagination/index.tsx       | 288 ++++++++++++++++++
 .../pagination/pagination.stories.tsx         | 120 ++++++++
 2 files changed, 408 insertions(+)
 create mode 100644 packages/propel/src/components/pagination/index.tsx
 create mode 100644 packages/propel/src/components/pagination/pagination.stories.tsx

diff --git a/packages/propel/src/components/pagination/index.tsx b/packages/propel/src/components/pagination/index.tsx
new file mode 100644
index 00000000..91e5bad2
--- /dev/null
+++ b/packages/propel/src/components/pagination/index.tsx
@@ -0,0 +1,288 @@
+import { cva, cx } from "class-variance-authority";
+import { ArrowLeft, ArrowRight, ChevronDown, LoaderCircle, MoreHorizontal } from "lucide-react";
+import * as React from "react";
+
+// Pagination is a single composite navigation control rather than a variant matrix:
+// the Figma "variant" axis (All pages visible / Near start / Middle / Near end) is
+// purely a function of where the current page sits within the total, so it's derived
+// at render time from `page`/`pageCount` — never a prop. What designers can toggle is
+// genuinely additive: an optional per-page selector and an optional range label.
+//
+// Tokens (Figma node 4762-503):
+// - page-number button: 24px square, radius/sm (4px), text/13, transparent bg that
+//   fills to `layer-transparent-hover` on hover and `layer-transparent-active` when
+//   it is the current page; disabled/loading dim to the placeholder/disabled colors.
+// - prev/next: 24px square icon buttons, radius/md (6px), 16px arrows. The arrows are
+//   directional, so they mirror in RTL via `rtl:-scale-x-100`.
+// - ellipsis: a non-interactive 24px slot holding a 14px more-horizontal glyph.
+// - per-page selector: a `layer-3` pill, 24px tall, radius/md, "50" + chevron-down,
+//   followed by "per page" tertiary text.
+
+// Shared 24px square slot used by page numbers, the prev/next buttons and the
+// ellipsis. `radius/sm` for page numbers, `radius/md` for the arrow buttons.
+const slotBase = cx(
+  "inline-flex size-6 shrink-0 items-center justify-center px-1",
+  "text-13 text-primary outline-none",
+);
+
+const pageButtonVariants = cva(
+  cx(
+    slotBase,
+    "rounded-sm bg-layer-transparent",
+    "hover:bg-layer-transparent-hover",
+    "focus-visible:ring-2 focus-visible:ring-accent-strong",
+    "disabled:pointer-events-none disabled:text-disabled",
+  ),
+  {
+    variants: {
+      // The current page reads as pressed: it sits on the `transparent-active` fill
+      // (Figma "Selected") and is not interactive.
+      current: {
+        true: "bg-layer-transparent-active",
+        false: "",
+      },
+    },
+  },
+);
+
+const arrowButtonVariants = cva(
+  cx(
+    slotBase,
+    "rounded-md bg-layer-transparent text-icon-secondary",
+    "hover:bg-layer-transparent-hover",
+    "focus-visible:ring-2 focus-visible:ring-accent-strong",
+    "disabled:pointer-events-none disabled:text-icon-disabled",
+    // Prev/next arrows are directional — mirror them under RTL so "previous" always
+    // points toward the start of the run.
+    "[&_svg]:size-4 [&_svg]:shrink-0 rtl:[&_svg]:-scale-x-100",
+  ),
+);
+
+/** A non-interactive gap marker between distant page numbers. */
+function PaginationEllipsis() {
+  return (
+    <li aria-hidden className={cx(slotBase, "text-icon-placeholder")}>
+      <MoreHorizontal className="size-3.5 shrink-0" />
+    </li>
+  );
+}
+
+// Builds the sequence of visible page tokens. Always shows the first and last page;
+// shows up to one neighbour either side of the current page; inserts an ellipsis
+// wherever the run skips pages. This reproduces the four Figma layouts:
+//   1 2 3 4              (all visible)
+//   1 2 3 … 100          (near start)
+//   1 … 44 45 46 … 100   (middle)
+//   1 … 98 99 100        (near end)
+type PageToken = number | "ellipsis-start" | "ellipsis-end";
+
+function buildPageTokens(page: number, pageCount: number): PageToken[] {
+  // Few enough pages to show them all.
+  if (pageCount <= 7) {
+    return Array.from({ length: pageCount }, (_, i) => i + 1);
+  }
+  // A window of three consecutive pages around the current one (current ± 1). When
+  // that window butts up against an end, it shifts inward so the end side always
+  // shows three numbers — reproducing Figma's `1 2 3 … 100` / `1 … 98 99 100`.
+  let windowStart = page - 1;
+  let windowEnd = page + 1;
+  if (windowStart < 2) {
+    // Near the start: the run abuts the `1` anchor, so show `1 2 3 … last`.
+    windowStart = 2;
+    windowEnd = 3;
+  }
+  if (windowEnd > pageCount - 1) {
+    // Near the end: the run abuts the `last` anchor, so show `1 … last-2 last-1 last`.
+    windowEnd = pageCount - 1;
+    windowStart = pageCount - 2;
+  }
+  const tokens: PageToken[] = [1];
+  // Show a leading ellipsis only when the window skips past page 2.
+  if (windowStart > 2) tokens.push("ellipsis-start");
+  for (let p = windowStart; p <= windowEnd; p++) tokens.push(p);
+  // Show a trailing ellipsis only when the window stops short of the last anchor.
+  if (windowEnd < pageCount - 1) tokens.push("ellipsis-end");
+  tokens.push(pageCount);
+  return tokens;
+}
+
+export type PaginationLabels = {
+  /** Accessible name for the `<nav>` landmark. */
+  root: string;
+  /** Accessible name for the previous-page button. */
+  previous: string;
+  /** Accessible name for the next-page button. */
+  next: string;
+  /**
+   * Accessible name for a page button, given its number. Defaults to e.g.
+   * `"Go to page 3"`; the current page is additionally marked `aria-current`.
+   */
+  page: (page: number) => string;
+  /** Visible text on the per-page selector trigger, given the size. Defaults to `"50"`. */
+  perPageValue: (pageSize: number) => React.ReactNode;
+  /** Trailing text after the per-page selector. Defaults to `"per page"`. */
+  perPage: React.ReactNode;
+};
+
+const DEFAULT_LABELS: PaginationLabels = {
+  root: "Pagination",
+  previous: "Go to previous page",
+  next: "Go to next page",
+  page: (page) => `Go to page ${page}`,
+  perPageValue: (pageSize) => String(pageSize),
+  perPage: "per page",
+};
+
+export type PaginationProps = Omit<
+  React.ComponentProps<"nav">,
+  "className" | "style" | "children" | "aria-label" | "onChange"
+> & {
+  /** The current page, 1-based. */
+  page: number;
+  /** Total number of pages. */
+  pageCount: number;
+  /** Called with the target page (1-based) when a control is activated. */
+  onPageChange: (page: number) => void;
+  /**
+   * The current page is rendered as a loading spinner instead of its number — for
+   * when navigating to that page is in flight.
+   */
+  loading?: boolean;
+  /**
+   * Optional per-page size selector (Figma `50 v  per page`). Provide `value`, the
+   * `options`, and `onChange`; omit to hide the selector entirely.
+   */
+  pageSize?: {
+    /** Currently selected page size. */
+    value: number;
+    /** Selectable page sizes. */
+    options: number[];
+    /** Called with the chosen page size. */
+    onChange: (pageSize: number) => void;
+  };
+  /**
+   * Optional range label shown before the controls (Figma `1-50 of 250`). Provide
+   * the already-formatted `current` range and `total`.
+   */
+  range?: {
+    /** The visible range, e.g. `"1-50"` (rendered in the primary text color). */
+    current: React.ReactNode;
+    /** The total count, e.g. `250` (rendered after `of` in the tertiary color). */
+    total: React.ReactNode;
+  };
+  /** Override the default English accessible names / visible selector text. */
+  labels?: Partial<PaginationLabels>;
+};
+
+/**
+ * Page navigation for a paginated list or table. Renders a `<nav>` landmark holding
+ * an optional per-page selector and range label plus an ordered list of page
+ * controls: a previous button, first/last anchors with ellipses around a window of
+ * pages near the current one, and a next button. The current page is marked
+ * `aria-current="page"`; the prev/next ends disable at the bounds and their arrows
+ * mirror under RTL.
+ */
+export function Pagination({
+  page,
+  pageCount,
+  onPageChange,
+  loading = false,
+  pageSize,
+  range,
+  labels,
+  ...props
+}: PaginationProps) {
+  const l = { ...DEFAULT_LABELS, ...labels };
+  const tokens = buildPageTokens(page, pageCount);
+  const atStart = page <= 1;
+  const atEnd = page >= pageCount;
+
+  return (
+    <nav aria-label={l.root} className="flex items-center gap-4" {...props}>
+      {pageSize ? (
+        <div className="flex min-w-0 flex-1 items-center gap-2">
+          <label className="inline-flex h-6 min-w-10 items-center justify-center gap-1 rounded-md bg-layer-3 px-2 text-13 font-medium text-secondary">
+            <span className="sr-only">{l.perPage}</span>
+            <select
+              value={pageSize.value}
+              onChange={(e) => pageSize.onChange(Number(e.target.value))}
+              className="cursor-default appearance-none bg-transparent text-center outline-none focus-visible:underline"
+            >
+              {pageSize.options.map((option) => (
+                <option key={option} value={option}>
+                  {option}
+                </option>
+              ))}
+            </select>
+            <ChevronDown aria-hidden className="size-3.5 shrink-0 text-icon-secondary" />
+          </label>
+          <span aria-hidden className="whitespace-nowrap text-13 text-tertiary">
+            {l.perPage}
+          </span>
+        </div>
+      ) : null}
+
+      {range ? (
+        <p className="whitespace-nowrap text-12 text-tertiary">
+          <span className="text-primary">{range.current}</span>
+          <span>{" of "}</span>
+          <span>{range.total}</span>
+        </p>
+      ) : null}
+
+      <ul className="flex items-center gap-1.5">
+        <li>
+          <button
+            type="button"
+            aria-label={l.previous}
+            disabled={atStart}
+            onClick={() => onPageChange(page - 1)}
+            className={arrowButtonVariants()}
+          >
+            <ArrowLeft aria-hidden />
+          </button>
+        </li>
+
+        {tokens.map((token) => {
+          if (token === "ellipsis-start" || token === "ellipsis-end") {
+            return <PaginationEllipsis key={token} />;
+          }
+          const isCurrent = token === page;
+          return (
+            <li key={token}>
+              <button
+                type="button"
+                aria-label={l.page(token)}
+                aria-current={isCurrent ? "page" : undefined}
+                disabled={isCurrent}
+                onClick={() => onPageChange(token)}
+                className={pageButtonVariants({ current: isCurrent })}
+              >
+                {isCurrent && loading ? (
+                  <LoaderCircle
+                    aria-hidden
+                    className="size-3.5 shrink-0 animate-spin text-icon-placeholder"
+                  />
+                ) : (
+                  token
+                )}
+              </button>
+            </li>
+          );
+        })}
+
+        <li>
+          <button
+            type="button"
+            aria-label={l.next}
+            disabled={atEnd}
+            onClick={() => onPageChange(page + 1)}
+            className={arrowButtonVariants()}
+          >
+            <ArrowRight aria-hidden />
+          </button>
+        </li>
+      </ul>
+    </nav>
+  );
+}
diff --git a/packages/propel/src/components/pagination/pagination.stories.tsx b/packages/propel/src/components/pagination/pagination.stories.tsx
new file mode 100644
index 00000000..91bd7c28
--- /dev/null
+++ b/packages/propel/src/components/pagination/pagination.stories.tsx
@@ -0,0 +1,120 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import * as React from "react";
+import { expect } from "storybook/test";
+import { Pagination } from "./index";
+
+const meta = {
+  title: "Components/Pagination",
+  component: Pagination,
+  tags: ["ai-generated"],
+  parameters: {
+    design: {
+      type: "figma",
+      url: "https://www.figma.com/design/ioN74zM1xMGbcPemsxs4J1/Global-components?node-id=4762-503",
+    },
+  },
+  args: {
+    page: 1,
+    pageCount: 25,
+    onPageChange: () => {},
+  },
+  // Drive `page` from local state so the controls actually navigate in the canvas.
+  render: function Render(args) {
+    const [page, setPage] = React.useState(args.page);
+    React.useEffect(() => setPage(args.page), [args.page]);
+    return <Pagination {...args} page={page} onPageChange={setPage} />;
+  },
+} satisfies Meta<typeof Pagination>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+/** A bare pager: prev/next plus the page-number window with first/last anchors. */
+export const Default: Story = {};
+
+/** With the per-page selector and the `1-50 of 250` range label (Figma frame). */
+export const WithSelectorAndRange: Story = {
+  args: {
+    page: 1,
+    pageCount: 5,
+    pageSize: { value: 50, options: [25, 50, 100], onChange: () => {} },
+    range: { current: "1-50", total: 250 },
+  },
+};
+
+/**
+ * The four truncation layouts the design derives from where the current page sits:
+ * all pages visible, near the start, in the middle, and near the end — shown here
+ * with the selector + range to match the Figma frame exactly.
+ */
+export const Variants: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="flex flex-col gap-4">
+      <Pagination
+        page={1}
+        pageCount={5}
+        onPageChange={() => {}}
+        pageSize={{ value: 50, options: [25, 50, 100], onChange: () => {} }}
+        range={{ current: "1-50", total: 250 }}
+        labels={{ root: "All pages visible" }}
+      />
+      <Pagination
+        page={1}
+        pageCount={100}
+        onPageChange={() => {}}
+        pageSize={{ value: 50, options: [25, 50, 100], onChange: () => {} }}
+        range={{ current: "1-50", total: 5000 }}
+        labels={{ root: "Near start" }}
+      />
+      <Pagination
+        page={45}
+        pageCount={100}
+        onPageChange={() => {}}
+        pageSize={{ value: 50, options: [25, 50, 100], onChange: () => {} }}
+        range={{ current: "2000-2050", total: 5000 }}
+        labels={{ root: "Middle" }}
+      />
+      <Pagination
+        page={100}
+        pageCount={100}
+        onPageChange={() => {}}
+        pageSize={{ value: 50, options: [25, 50, 100], onChange: () => {} }}
+        range={{ current: "4951-5000", total: 5000 }}
+        labels={{ root: "Near end" }}
+      />
+    </div>
+  ),
+};
+
+/** The current page can render as a spinner while navigating to it is in flight. */
+export const Loading: Story = {
+  args: { page: 3, pageCount: 25, loading: true },
+};
+
+/**
+ * Behavioral checks: the nav landmark is named, the current page is marked
+ * `aria-current` and disabled, the previous button is disabled at the first page,
+ * and activating a page number reports the new page through `onPageChange`.
+ */
+export const Behavior: Story = {
+  tags: ["!dev", "!autodocs", "!manifest"],
+  args: { page: 1, pageCount: 25 },
+  play: async ({ canvas, userEvent }) => {
+    await expect(canvas.getByRole("navigation", { name: "Pagination" })).toBeInTheDocument();
+
+    // At page 1 the previous button is disabled and page 1 is current.
+    await expect(canvas.getByRole("button", { name: "Go to previous page" })).toBeDisabled();
+    const page1 = canvas.getByRole("button", { name: "Go to page 1" });
+    await expect(page1).toHaveAttribute("aria-current", "page");
+    await expect(page1).toBeDisabled();
+
+    // Navigating to page 2 moves the current marker.
+    await userEvent.click(canvas.getByRole("button", { name: "Go to page 2" }));
+    await expect(canvas.getByRole("button", { name: "Go to page 2" })).toHaveAttribute(
+      "aria-current",
+      "page",
+    );
+    await expect(canvas.getByRole("button", { name: "Go to previous page" })).toBeEnabled();
+  },
+};

From b2b96fe60114316e67331fe4991b3bfa94e7d5b0 Mon Sep 17 00:00:00 2001
From: Aaron Reisman <aaron.reisman@plane.so>
Date: Wed, 10 Jun 2026 00:50:14 +0700
Subject: [PATCH 2/5] Pagination: grow page slots for multi-digit numbers; drop
 single-page ellipses
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- slotBase: replace fixed size-6 with h-6 min-w-6 w-auto so single digits stay
  square (24px) but the slot grows for wider content — 100 no longer clips.
- buildPageTokens: only ellipsize gaps of 2+ pages; a lone skipped page is
  rendered as its own number, so pageCount=8/page=4 reads 1 2 3 4 5 … 8 (page 2
  no longer hidden) instead of 1 … 3 4 5 … 8.
- stories: add ThreeDigit (pageCount=100/page=100) and SingleGap play test
  (pageCount=8/page=4) covering both cases.
---
 .../src/components/pagination/index.tsx       | 26 +++++++++++-----
 .../pagination/pagination.stories.tsx         | 30 +++++++++++++++++++
 2 files changed, 48 insertions(+), 8 deletions(-)

diff --git a/packages/propel/src/components/pagination/index.tsx b/packages/propel/src/components/pagination/index.tsx
index 91e5bad2..b966043c 100644
--- a/packages/propel/src/components/pagination/index.tsx
+++ b/packages/propel/src/components/pagination/index.tsx
@@ -18,10 +18,13 @@ import * as React from "react";
 // - per-page selector: a `layer-3` pill, 24px tall, radius/md, "50" + chevron-down,
 //   followed by "per page" tertiary text.
 
-// Shared 24px square slot used by page numbers, the prev/next buttons and the
-// ellipsis. `radius/sm` for page numbers, `radius/md` for the arrow buttons.
+// Shared 24px slot used by page numbers, the prev/next buttons and the ellipsis.
+// 24px tall with a 24px minimum width so single digits stay square (per Figma),
+// but the slot grows for wider content — multi-digit page numbers like `100` get
+// their own width plus horizontal padding rather than clipping a fixed square.
+// `radius/sm` for page numbers, `radius/md` for the arrow buttons.
 const slotBase = cx(
-  "inline-flex size-6 shrink-0 items-center justify-center px-1",
+  "inline-flex h-6 w-auto min-w-6 shrink-0 items-center justify-center px-1",
   "text-13 text-primary outline-none",
 );
 
@@ -69,7 +72,9 @@ function PaginationEllipsis() {
 
 // Builds the sequence of visible page tokens. Always shows the first and last page;
 // shows up to one neighbour either side of the current page; inserts an ellipsis
-// wherever the run skips pages. This reproduces the four Figma layouts:
+// only where the run skips 2+ pages. A gap of exactly one page renders that page
+// number instead, since a `…` standing in for a single page just hides a reachable
+// page. This reproduces the four Figma layouts:
 //   1 2 3 4              (all visible)
 //   1 2 3 … 100          (near start)
 //   1 … 44 45 46 … 100   (middle)
@@ -97,11 +102,16 @@ function buildPageTokens(page: number, pageCount: number): PageToken[] {
     windowStart = pageCount - 2;
   }
   const tokens: PageToken[] = [1];
-  // Show a leading ellipsis only when the window skips past page 2.
-  if (windowStart > 2) tokens.push("ellipsis-start");
+  // Bridge the gap between the `1` anchor and the window. An ellipsis is only worth
+  // it when 2+ pages are hidden; a lone skipped page (here, page 2) is rendered as
+  // its own number so it isn't buried under `…` — `1 2 3 4 5 …` instead of `1 … 3 …`.
+  if (windowStart === 3) tokens.push(2);
+  else if (windowStart > 3) tokens.push("ellipsis-start");
   for (let p = windowStart; p <= windowEnd; p++) tokens.push(p);
-  // Show a trailing ellipsis only when the window stops short of the last anchor.
-  if (windowEnd < pageCount - 1) tokens.push("ellipsis-end");
+  // Likewise on the trailing side: a single skipped page (pageCount - 1) is shown
+  // rather than hidden behind a trailing ellipsis.
+  if (windowEnd === pageCount - 2) tokens.push(pageCount - 1);
+  else if (windowEnd < pageCount - 2) tokens.push("ellipsis-end");
   tokens.push(pageCount);
   return tokens;
 }
diff --git a/packages/propel/src/components/pagination/pagination.stories.tsx b/packages/propel/src/components/pagination/pagination.stories.tsx
index 91bd7c28..a6d65634 100644
--- a/packages/propel/src/components/pagination/pagination.stories.tsx
+++ b/packages/propel/src/components/pagination/pagination.stories.tsx
@@ -87,11 +87,41 @@ export const Variants: Story = {
   ),
 };
 
+/**
+ * Three-digit page numbers must render in full. The slot keeps its 24px minimum so
+ * single digits stay square, but grows to fit wider content — `100` is not clipped.
+ */
+export const ThreeDigit: Story = {
+  args: { page: 100, pageCount: 100 },
+};
+
 /** The current page can render as a spinner while navigating to it is in flight. */
 export const Loading: Story = {
   args: { page: 3, pageCount: 25, loading: true },
 };
 
+/**
+ * A single skipped page is rendered as its own number rather than hidden behind an
+ * ellipsis: with `pageCount=8, page=4` the gap on the leading side is exactly one
+ * page (page 2), so the run reads `1 2 3 4 5 … 8` — page 2 stays reachable and only
+ * the 2+-page trailing gap (pages 6, 7) collapses to a `…`.
+ */
+export const SingleGap: Story = {
+  tags: ["!dev", "!autodocs", "!manifest"],
+  args: { page: 4, pageCount: 8 },
+  play: async ({ canvas }) => {
+    // The lone skipped page on the leading side is shown, not ellided.
+    await expect(canvas.getByRole("button", { name: "Go to page 2" })).toBeInTheDocument();
+    // The 2+-page trailing gap (pages 6 and 7) collapses to a single ellipsis.
+    await expect(canvas.queryByRole("button", { name: "Go to page 6" })).not.toBeInTheDocument();
+    await expect(canvas.queryByRole("button", { name: "Go to page 7" })).not.toBeInTheDocument();
+    // Anchors and window are present: 1 2 3 4 5 … 8.
+    for (const n of [1, 3, 4, 5, 8]) {
+      await expect(canvas.getByRole("button", { name: `Go to page ${n}` })).toBeInTheDocument();
+    }
+  },
+};
+
 /**
  * Behavioral checks: the nav landmark is named, the current page is marked
  * `aria-current` and disabled, the previous button is disabled at the first page,

From 4788635cd49d3a0c1c966f29df04f8a35d00b012 Mon Sep 17 00:00:00 2001
From: Aaron Reisman <aaron.reisman@plane.so>
Date: Wed, 10 Jun 2026 11:55:43 +0700
Subject: [PATCH 3/5] Pagination: selected page keeps text-primary (Figma
 4762-503)

The current/selected page is marked `disabled` to block re-navigation,
which triggered the base `disabled:text-disabled` dim. Figma's
"Selected" state (node 4762:550) keeps `text/primary`, so the current
variant now applies `disabled:text-primary` to override the dim while
staying on the `transparent-active` fill. Default/hover/disabled states
are unchanged and still match Figma.
---
 packages/propel/src/components/pagination/index.tsx | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/packages/propel/src/components/pagination/index.tsx b/packages/propel/src/components/pagination/index.tsx
index b966043c..eb87ed71 100644
--- a/packages/propel/src/components/pagination/index.tsx
+++ b/packages/propel/src/components/pagination/index.tsx
@@ -39,9 +39,11 @@ const pageButtonVariants = cva(
   {
     variants: {
       // The current page reads as pressed: it sits on the `transparent-active` fill
-      // (Figma "Selected") and is not interactive.
+      // (Figma "Selected") and is not interactive. It's marked `disabled` to block
+      // re-navigation, but the Figma "Selected" state keeps `text/primary` — so it
+      // must override the `disabled:text-disabled` dim that the base applies.
       current: {
-        true: "bg-layer-transparent-active",
+        true: "bg-layer-transparent-active disabled:text-primary",
         false: "",
       },
     },

From 86f3c7b2e0d76c415bb70dff2cd20bdbb3fe300d Mon Sep 17 00:00:00 2001
From: Aaron Reisman <aaron.reisman@plane.so>
Date: Wed, 10 Jun 2026 12:18:05 +0700
Subject: [PATCH 4/5] Pagination: add keyboard play test (Enter/Space
 activation, disabled ends, aria-current)

---
 .../pagination/pagination.stories.tsx         | 111 +++++++++++++++++-
 1 file changed, 110 insertions(+), 1 deletion(-)

diff --git a/packages/propel/src/components/pagination/pagination.stories.tsx b/packages/propel/src/components/pagination/pagination.stories.tsx
index a6d65634..dd0f48af 100644
--- a/packages/propel/src/components/pagination/pagination.stories.tsx
+++ b/packages/propel/src/components/pagination/pagination.stories.tsx
@@ -1,6 +1,6 @@
 import type { Meta, StoryObj } from "@storybook/react-vite";
 import * as React from "react";
-import { expect } from "storybook/test";
+import { expect, fn, userEvent } from "storybook/test";
 import { Pagination } from "./index";
 
 const meta = {
@@ -148,3 +148,112 @@ export const Behavior: Story = {
     await expect(canvas.getByRole("button", { name: "Go to previous page" })).toBeEnabled();
   },
 };
+
+/**
+ * Keyboard operation: Tab reaches the prev button and the page-number buttons, and
+ * Enter / Space activate a focused page button — each reporting the target page
+ * through `onPageChange`. The disabled current page and the disabled prev/next ends
+ * are skipped by Tab (not focusable) and never fire `onPageChange`.
+ */
+export const KeyboardNavigation: Story = {
+  tags: ["!dev", "!autodocs", "!manifest"],
+  args: { page: 3, pageCount: 25, onPageChange: fn() },
+  // Spy on `onPageChange` while still driving `page` from state so the current
+  // marker / disabled-end behaviour stays live as we navigate.
+  render: function Render(args) {
+    const [page, setPage] = React.useState(args.page);
+    React.useEffect(() => setPage(args.page), [args.page]);
+    const spy = args.onPageChange as (next: number) => void;
+    const onPageChange = (next: number) => {
+      spy(next);
+      setPage(next);
+    };
+    return <Pagination {...args} page={page} onPageChange={onPageChange} />;
+  },
+  play: async ({ args, canvas, step }) => {
+    const onPageChange = args.onPageChange as ReturnType<typeof fn>;
+
+    // Landmark + list semantics: the controls live in a named <nav> wrapping a list.
+    const nav = canvas.getByRole("navigation", { name: "Pagination" });
+    await expect(nav).toBeInTheDocument();
+    await expect(canvas.getByRole("list")).toBeInTheDocument();
+    await expect(canvas.getAllByRole("listitem").length).toBeGreaterThan(0);
+
+    // The current page is marked aria-current and is disabled (not re-activatable).
+    const currentPage = canvas.getByRole("button", { name: "Go to page 3" });
+    await expect(currentPage).toHaveAttribute("aria-current", "page");
+    await expect(currentPage).toBeDisabled();
+
+    await step("Tab reaches prev then the focusable page buttons", async () => {
+      const prev = canvas.getByRole("button", { name: "Go to previous page" });
+      // Start from the document body so the first Tab lands on the first control.
+      (document.activeElement as HTMLElement | null)?.blur();
+      await userEvent.tab();
+      await expect(prev).toHaveFocus();
+      // The disabled current page (3) is not in the tab order; tabbing forward from
+      // prev reaches the first focusable page button (1).
+      await userEvent.tab();
+      await expect(canvas.getByRole("button", { name: "Go to page 1" })).toHaveFocus();
+    });
+
+    await step("Enter on a focused page button fires onPageChange with that page", async () => {
+      // page 1 is always shown (the first anchor) and is enabled while we sit on 3.
+      const page1 = canvas.getByRole("button", { name: "Go to page 1" });
+      page1.focus();
+      await expect(page1).toHaveFocus();
+      await userEvent.keyboard("{Enter}");
+      await expect(onPageChange).toHaveBeenLastCalledWith(1);
+      // page is now 1 → page 1 becomes the current/disabled marker.
+      await expect(canvas.getByRole("button", { name: "Go to page 1" })).toHaveAttribute(
+        "aria-current",
+        "page",
+      );
+    });
+
+    await step("Space on a focused page button fires onPageChange with that page", async () => {
+      // We're on page 1; the last anchor (25) is always shown and enabled. Space
+      // activates it the same as Enter / a click.
+      const last = canvas.getByRole("button", { name: "Go to page 25" });
+      last.focus();
+      await expect(last).toHaveFocus();
+      await userEvent.keyboard("[Space]");
+      await expect(onPageChange).toHaveBeenLastCalledWith(25);
+    });
+
+    await step("Next is disabled at the last page and never fires", async () => {
+      // Space took us to the last page (25), so Next is now at its bound.
+      const next = canvas.getByRole("button", { name: "Go to next page" });
+      await expect(next).toBeDisabled();
+      onPageChange.mockClear();
+      // A disabled button is not focusable and ignores keyboard activation.
+      next.focus();
+      await expect(next).not.toHaveFocus();
+      await userEvent.keyboard("{Enter}");
+      await expect(onPageChange).not.toHaveBeenCalled();
+    });
+
+    await step("Prev is disabled at the first page and never fires", async () => {
+      // Jump back to the first page via its anchor, then assert Prev is dead.
+      await userEvent.click(canvas.getByRole("button", { name: "Go to page 1" }));
+      const prev = canvas.getByRole("button", { name: "Go to previous page" });
+      await expect(prev).toBeDisabled();
+      onPageChange.mockClear();
+      prev.focus();
+      await expect(prev).not.toHaveFocus();
+      await userEvent.keyboard("{Enter}");
+      await expect(onPageChange).not.toHaveBeenCalled();
+    });
+
+    await step("The current page is disabled and not re-activatable", async () => {
+      // page is now 1 → page 1 is the aria-current, disabled marker.
+      const page1 = canvas.getByRole("button", { name: "Go to page 1" });
+      await expect(page1).toHaveAttribute("aria-current", "page");
+      await expect(page1).toBeDisabled();
+      onPageChange.mockClear();
+      page1.focus();
+      await expect(page1).not.toHaveFocus();
+      await userEvent.keyboard("{Enter}");
+      await expect(onPageChange).not.toHaveBeenCalled();
+    });
+  },
+};

From 6b685069ee650fa7e0ed25ec4ea4345dfa974791 Mon Sep 17 00:00:00 2001
From: Aaron Reisman <aaron.reisman@plane.so>
Date: Wed, 10 Jun 2026 14:32:22 +0700
Subject: [PATCH 5/5] Pagination: compose propel Dropdown for the page-size
 selector (#41)

Replace the interim native <select> with the propel Dropdown: the layer-3
pill becomes a DropdownTrigger labeled "N per page" and the menu lists the
page-size options as single-select DropdownItems (current one checked), with
selection reporting through the existing pageSize.onChange. Same pageSize API
({ value, options, onChange }); keyboard (ArrowDown/Enter opens, arrows +
Enter select) and the labeled trigger keep it accessible. Adds a play-tested
PageSizeSelector story covering open/select/keyboard.
---
 .../src/components/pagination/index.tsx       | 55 +++++++++---
 .../pagination/pagination.stories.tsx         | 86 ++++++++++++++++++-
 2 files changed, 126 insertions(+), 15 deletions(-)

diff --git a/packages/propel/src/components/pagination/index.tsx b/packages/propel/src/components/pagination/index.tsx
index eb87ed71..c2982d82 100644
--- a/packages/propel/src/components/pagination/index.tsx
+++ b/packages/propel/src/components/pagination/index.tsx
@@ -1,6 +1,7 @@
 import { cva, cx } from "class-variance-authority";
 import { ArrowLeft, ArrowRight, ChevronDown, LoaderCircle, MoreHorizontal } from "lucide-react";
 import * as React from "react";
+import { Dropdown, DropdownContent, DropdownItem, DropdownTrigger } from "../dropdown/index";
 
 // Pagination is a single composite navigation control rather than a variant matrix:
 // the Figma "variant" axis (All pages visible / Near start / Middle / Near end) is
@@ -16,7 +17,9 @@ import * as React from "react";
 //   directional, so they mirror in RTL via `rtl:-scale-x-100`.
 // - ellipsis: a non-interactive 24px slot holding a 14px more-horizontal glyph.
 // - per-page selector: a `layer-3` pill, 24px tall, radius/md, "50" + chevron-down,
-//   followed by "per page" tertiary text.
+//   followed by "per page" tertiary text. The pill is the trigger for a propel
+//   Dropdown (single-select) whose menu lists the page-size options; picking one
+//   reports it through `pageSize.onChange`.
 
 // Shared 24px slot used by page numbers, the prev/next buttons and the ellipsis.
 // 24px tall with a 24px minimum width so single digits stay square (per Figma),
@@ -63,6 +66,19 @@ const arrowButtonVariants = cva(
   ),
 );
 
+// The per-page selector trigger (Figma `4762-503`): a `layer-3` pill, 24px tall,
+// `radius/md`, holding the current size + a chevron-down. It's the trigger for the
+// page-size Dropdown, so it gets a focus ring and rotates its chevron while the menu
+// is open.
+const perPageTriggerClass = cx(
+  "inline-flex h-6 min-w-10 cursor-default items-center justify-center gap-1 rounded-md px-2",
+  "bg-layer-3 text-13 font-medium text-secondary outline-none",
+  "hover:bg-layer-3-hover",
+  "focus-visible:ring-2 focus-visible:ring-accent-strong",
+  "[&_svg]:size-3.5 [&_svg]:shrink-0 [&_svg]:text-icon-secondary",
+  "[&[data-popup-open]_svg]:rotate-180",
+);
+
 /** A non-interactive gap marker between distant page numbers. */
 function PaginationEllipsis() {
   return (
@@ -213,21 +229,32 @@ export function Pagination({
     <nav aria-label={l.root} className="flex items-center gap-4" {...props}>
       {pageSize ? (
         <div className="flex min-w-0 flex-1 items-center gap-2">
-          <label className="inline-flex h-6 min-w-10 items-center justify-center gap-1 rounded-md bg-layer-3 px-2 text-13 font-medium text-secondary">
-            <span className="sr-only">{l.perPage}</span>
-            <select
-              value={pageSize.value}
-              onChange={(e) => pageSize.onChange(Number(e.target.value))}
-              className="cursor-default appearance-none bg-transparent text-center outline-none focus-visible:underline"
-            >
+          {/*
+            The selector is the propel Dropdown (single-select): the `layer-3` pill is
+            its trigger and the menu lists the page sizes, the current one marked with a
+            trailing check. The trigger carries the accessible name (the visible size +
+            the visually-hidden "per page"), and picking a size reports it through
+            `pageSize.onChange`. Keyboard works via the Dropdown (Enter/ArrowDown opens,
+            arrows move, Enter selects).
+          */}
+          <Dropdown>
+            <DropdownTrigger render={<button type="button" className={perPageTriggerClass} />}>
+              <span>{l.perPageValue(pageSize.value)}</span>
+              <span className="sr-only">{l.perPage}</span>
+              <ChevronDown aria-hidden className="transition-transform" />
+            </DropdownTrigger>
+            <DropdownContent width="anchor" align="center">
               {pageSize.options.map((option) => (
-                <option key={option} value={option}>
-                  {option}
-                </option>
+                <DropdownItem
+                  key={option}
+                  variant="default"
+                  label={l.perPageValue(option)}
+                  selected={option === pageSize.value}
+                  onClick={() => pageSize.onChange(option)}
+                />
               ))}
-            </select>
-            <ChevronDown aria-hidden className="size-3.5 shrink-0 text-icon-secondary" />
-          </label>
+            </DropdownContent>
+          </Dropdown>
           <span aria-hidden className="whitespace-nowrap text-13 text-tertiary">
             {l.perPage}
           </span>
diff --git a/packages/propel/src/components/pagination/pagination.stories.tsx b/packages/propel/src/components/pagination/pagination.stories.tsx
index dd0f48af..09f0bedb 100644
--- a/packages/propel/src/components/pagination/pagination.stories.tsx
+++ b/packages/propel/src/components/pagination/pagination.stories.tsx
@@ -1,6 +1,6 @@
 import type { Meta, StoryObj } from "@storybook/react-vite";
 import * as React from "react";
-import { expect, fn, userEvent } from "storybook/test";
+import { expect, fn, userEvent, waitFor, within } from "storybook/test";
 import { Pagination } from "./index";
 
 const meta = {
@@ -42,6 +42,90 @@ export const WithSelectorAndRange: Story = {
   },
 };
 
+/**
+ * The page-size selector is a propel Dropdown: its `layer-3` pill trigger is labeled
+ * "50 per page"; clicking it opens the portaled menu of sizes (the current one marked
+ * with a check), and picking one reports it through `pageSize.onChange` and updates the
+ * trigger. Keyboard works too — ArrowDown opens the menu and arrow+Enter selects.
+ */
+export const PageSizeSelector: Story = {
+  tags: ["!dev", "!autodocs", "!manifest"],
+  args: {
+    page: 1,
+    pageCount: 5,
+    pageSize: { value: 50, options: [25, 50, 100], onChange: fn() },
+    range: { current: "1-50", total: 250 },
+  },
+  // Drive `pageSize.value` from state so selecting an option visibly updates the
+  // trigger, while still spying on the provided `onChange`.
+  render: function Render(args) {
+    const [value, setValue] = React.useState(args.pageSize?.value ?? 50);
+    const spy = args.pageSize?.onChange;
+    return (
+      <Pagination
+        {...args}
+        pageSize={{
+          value,
+          options: args.pageSize?.options ?? [25, 50, 100],
+          onChange: (next) => {
+            spy?.(next);
+            setValue(next);
+          },
+        }}
+      />
+    );
+  },
+  play: async ({ args, canvas, step }) => {
+    // The portaled menu renders outside the story canvas, so query the document body.
+    const body = within(document.body);
+    const onChange = args.pageSize?.onChange as ReturnType<typeof fn>;
+
+    await step("the trigger is a labeled button showing the current size", async () => {
+      const trigger = canvas.getByRole("button", { name: /50 per page/i });
+      await expect(trigger).toBeInTheDocument();
+    });
+
+    await step("clicking the trigger opens the page-size menu", async () => {
+      await userEvent.click(canvas.getByRole("button", { name: /50 per page/i }));
+      await waitFor(() => expect(body.getByRole("menu")).toBeInTheDocument());
+      // All sizes are listed as menu items.
+      for (const n of [25, 50, 100]) {
+        await expect(body.getByRole("menuitem", { name: String(n) })).toBeInTheDocument();
+      }
+    });
+
+    await step("selecting a size reports it and updates the trigger", async () => {
+      await userEvent.click(body.getByRole("menuitem", { name: "100" }));
+      await expect(onChange).toHaveBeenLastCalledWith(100);
+      await waitFor(() =>
+        expect(canvas.getByRole("button", { name: /100 per page/i })).toBeInTheDocument(),
+      );
+    });
+
+    await step("keyboard: ArrowDown opens the menu, then arrows + Enter select", async () => {
+      const trigger = canvas.getByRole("button", { name: /100 per page/i });
+      trigger.focus();
+      await expect(trigger).toHaveFocus();
+      // ArrowDown opens the menu and highlights the first item (25).
+      await userEvent.keyboard("{ArrowDown}");
+      await waitFor(() => expect(body.getByRole("menu")).toBeInTheDocument());
+      await waitFor(() =>
+        expect(body.getByRole("menuitem", { name: "25" })).toHaveAttribute("data-highlighted"),
+      );
+      // ArrowDown moves the highlight to the second item (50); Enter selects it.
+      await userEvent.keyboard("{ArrowDown}");
+      await waitFor(() =>
+        expect(body.getByRole("menuitem", { name: "50" })).toHaveAttribute("data-highlighted"),
+      );
+      await userEvent.keyboard("{Enter}");
+      await expect(onChange).toHaveBeenLastCalledWith(50);
+      await waitFor(() =>
+        expect(canvas.getByRole("button", { name: /50 per page/i })).toBeInTheDocument(),
+      );
+    });
+  },
+};
+
 /**
  * The four truncation layouts the design derives from where the current page sits:
  * all pages visible, near the start, in the middle, and near the end — shown here