@apliteni/apliteni-ui 0.26.0 → 0.27.0

package/README.md

@@ -107,7 +107,7 @@ import { tokensCss, topbarCss, cssText } from '@apliteni/apliteni-ui/inline';
 
 ## React components (stateful surfaces)
 
-`DataTable`, `Modal`, `Button`, `Badge`, `Card` and `Icon` — same `.ui-*` classes,
+`DataTable`, `Pagination`, `Modal`, `Button`, `Badge`, `Card` and `Icon` — same `.ui-*` classes,
 same tokens, TypeScript types included. They ship as a **subpath of this package**,
 not as a package of their own: one install, one version, one pin.
 
@@ -126,7 +126,7 @@ its tree.
 
 ```tsx
 import '@apliteni/apliteni-ui/css';        // kit tokens + .ui-* classes
-import '@apliteni/apliteni-ui/react/css';  // React components' shell styles (modal, pager)
+import '@apliteni/apliteni-ui/react/css';  // React components' shell styles (modal, sort control)
 import { DataTable, Modal } from '@apliteni/apliteni-ui/react';
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@apliteni/apliteni-ui",
-  "version": "0.26.0",
+  "version": "0.27.0",
   "workspaces": [
     "react"
   ],

package/react/README.md

@@ -25,11 +25,19 @@ The kit declares no dependency on `react` or `react-dom`, so install them yourse
 
 ```tsx
 import '@apliteni/apliteni-ui/css';        // kit tokens + .ui-* classes
-import '@apliteni/apliteni-ui/react/css';  // React components' shell styles (modal, pager)
+import '@apliteni/apliteni-ui/react/css';  // React components' shell styles (modal, sort control)
 import { DataTable, Modal, Button } from '@apliteni/apliteni-ui/react';
 ```
 
-Components: `DataTable`, `Modal`, `Button`, `Badge`, `Card`, `Icon`.
+Components: `DataTable`, `Pagination`, `Modal`, `Button`, `Badge`, `Card`, `Icon`.
+
+`Pagination` renders the kit's `pagination()` markup, class for class, so its styles come from
+`@apliteni/apliteni-ui/css` rather than from this bundle. One deliberate difference: it takes no
+`href`, because a React pager reports through `onPageChange` rather than navigating. Use the
+vanilla factory where the steps have to be real links. `PAGE_SIZES` and
+`DEFAULT_PAGE_SIZE` are exported here too — the scale is the kit's, so no call site writes
+either number. They are declared in this package's own types, and `PAGE_SIZES` is a
+`readonly number[]`: pass it to `pageSizes`, but do not add sizes to it.
 
 ## What the Modal does with focus
 
@@ -93,3 +101,56 @@ a new array, including when `key` is `undefined`.
 Choose controlled or uncontrolled once per table. Passing `sort` for a while and then
 dropping it is not supported: the table falls back to the sort state it started with, not to
 the one it was last given.
+
+### Tables paged by a server
+
+`page` and `onPageChange` make pagination controlled, the same way `sort` does — and the same
+rule applies: choose one mode per table and keep it. Given a `page`, the table renders `rows`
+exactly as handed to it and never slices or re-orders them; the range comes from `page`,
+`pageSize` and `total`:
+
+```tsx
+<DataTable columns={columns} rows={pageOfRows} selectable={false}
+  page={page} total={total} pageSize={size} onPageChange={fetchPage}
+  pageSizes={PAGE_SIZES} onPageSizeChange={setSize} loading={loading} />
+```
+
+`total` is required with `page`: it is the row count of the whole result, not of `rows`. Pass
+`total={null}` for a result whose size is not known, and then `hasMore` is required too — the
+pager offers Prev and Next alone, because no other control can be computed without a last
+page. Leave both out and the call does not type-check: a pager told nothing can only draw two
+dead buttons.
+
+Without `pageSize`, a controlled table takes the page size from `rows.length`, the page it was
+handed. Pass `pageSize` whenever the last page can be shorter than the rest.
+
+A controlled table never sorts the rows it is handed. Changing the sort asks its owner for page
+1 through `onPageChange`, which is the most a controlled table can do about it. Keep `sort`
+controlled too, so the headers can say which column the server ordered by. Without it the
+headers still report a press through `onSortChange`, but no column announces `aria-sort` or
+draws a direction, because the table does not know the server's order.
+
+Omit `page` to keep the table's own paging: it slices `rows` in memory and the total is
+`rows.length`. `pageSizes` offers a size control in either mode — without a `pageSize` prop the
+table remembers the size the reader picked, with one it reports the choice through
+`onPageSizeChange` and shows what it is given. A table that owns its page returns the reader to
+page 1 when the size changes. A controlled table only calls `onPageSizeChange`, once, and
+leaves the page to its owner: a new size means page 1, so fetch page 1 at that size. It does
+not also call `onPageChange(1)`, because that second call would carry the old size.
+
+`pageSize` is read the way the pager reads it, so the rows and the range always agree: a
+fraction is truncated, and `NaN`, zero or a negative number falls back to the default. A value
+taken from a URL, such as `Number(params.get('size'))`, is safe to pass as it is.
+
+`pager={false}` renders no pager at all, for a surface that supplies its own. One page of
+content renders none either: the pager keeps GOV.UK's rule that pagination for a single page is
+not shown, and with a size control on offer it keeps the row count and that control alone.
+
+Focus stays on the step the reader pressed, so they can press it again. At an end that step is
+disabled, and a browser drops focus from a disabled control to the page body. So once the new
+page has arrived, the pager moves focus to the nearest step that can still move, never into
+the rows. It moves focus only after a press in the pager, and never while `loading`.
+Clearing the page-jump box, or typing into it and then pressing a step, does not change the
+page.
+
+`pageSize` defaults to `DEFAULT_PAGE_SIZE` (100). **Breaking:** it used to default to 4.

package/react/dist/index.css

@@ -80,15 +80,3 @@
 .rx-caret {
   margin-left: 2px;
 }
-.rx-pager {
-  display: flex;
-  align-items: center;
-  gap: 8px;
-  justify-content: flex-end;
-  margin-top: 16px;
-}
-.rx-pager__info {
-  color: var(--muted);
-  font-size: var(--text-sm);
-  margin-right: auto;
-}

package/react/dist/index.d.ts

@@ -60,11 +60,39 @@ type SelectionProps = {
     onToggle: (name: string) => void;
     onTogglePage: (names: string[]) => void;
 };
+type PagerProps = {
+    page?: never;
+    onPageChange?: (page: number) => void;
+    total?: never;
+    hasMore?: never;
+} | {
+    page: number;
+    onPageChange: (page: number) => void;
+    total: number;
+    hasMore?: boolean;
+} | {
+    page: number;
+    onPageChange: (page: number) => void;
+    total: null;
+    hasMore: boolean;
+};
 type DataTableProps<T> = {
     columns: Column<T>[];
     rows: T[];
     pageSize?: number;
-} & SelectionProps & ({
+    pageSizes?: readonly number[] | null;
+    onPageSizeChange?: (size: number) => void;
+    /** `false` renders no pager at all — for a surface that supplies its own. */
+    pager?: boolean;
+    /**
+     * The pager's accessible name. Two tables on one page otherwise publish two
+     * landmarks called "Pagination", and a reader listing the landmarks cannot tell
+     * which one moves which table. Axe will not catch it: `landmark-unique` is a
+     * best-practice rule and the kit's gate runs only the WCAG A/AA tags.
+     */
+    pagerLabel?: string;
+    loading?: boolean;
+} & SelectionProps & PagerProps & ({
     sort?: never;
     onSortChange?: (sort: TableSort<T>) => void;
 } | {
@@ -74,7 +102,24 @@ type DataTableProps<T> = {
 declare function sortTableRows<T>(rows: T[], sort: TableSort<T>): T[];
 declare function DataTable<T extends {
     name: string;
-}>({ columns, rows, pageSize, selectable, selected, onToggle, onTogglePage, sort: controlledSort, onSortChange, }: DataTableProps<T>): react.JSX.Element;
+}>({ columns, rows, pageSize, pageSizes, onPageSizeChange, pager, pagerLabel, loading, selectable, selected, onToggle, onTogglePage, sort: controlledSort, onSortChange, page: controlledPage, onPageChange, total, hasMore, }: DataTableProps<T>): react.JSX.Element;
+
+type PaginationProps = {
+    page?: number;
+    pageSize?: number;
+    /** Rows in the whole result. `null` — the honest answer for a caller who cannot count. */
+    total?: number | null;
+    /** Read only when `total` is null: whether a page exists after this one. */
+    hasMore?: boolean;
+    pageSizes?: readonly number[] | null;
+    variant?: 'steps' | 'numbered' | 'jump';
+    label?: string;
+    loading?: boolean;
+    id?: string;
+    onPageChange?: (page: number) => void;
+    onPageSizeChange?: (size: number) => void;
+};
+declare function Pagination({ page, pageSize, total, hasMore, pageSizes, variant, label, loading, id, onPageChange, onPageSizeChange, }: PaginationProps): react.JSX.Element | null;
 
 type SkeletonProps = {
     /** A count of bars, or explicit widths when a ragged prose edge matters. */
@@ -115,4 +160,7 @@ type DeniedProps = {
 };
 declare function Denied({ title, sub, need, icon, className, children, }: DeniedProps): react.JSX.Element;
 
-export { Badge, BusyRegion, type BusyRegionProps, Button, type ButtonProps, Card, type Column, DataTable, type DataTableProps, Denied, type DeniedProps, Icon, Modal, type ModalProps, Skeleton, type SkeletonProps, SkeletonTable, type SkeletonTableProps, type TableSort, sortTableRows };
+declare const PAGE_SIZES: readonly number[];
+declare const DEFAULT_PAGE_SIZE: number;
+
+export { Badge, BusyRegion, type BusyRegionProps, Button, type ButtonProps, Card, type Column, DEFAULT_PAGE_SIZE, DataTable, type DataTableProps, Denied, type DeniedProps, Icon, Modal, type ModalProps, PAGE_SIZES, Pagination, type PaginationProps, Skeleton, type SkeletonProps, SkeletonTable, type SkeletonTableProps, type TableSort, sortTableRows };

package/react/dist/index.js

@@ -170,8 +170,236 @@ function Modal({ open, title, onClose, footer, children }) {
 }
 
 // src/DataTable.tsx
-import { useMemo, useState } from "react";
-import { Fragment, jsx as jsx6, jsxs as jsxs4 } from "react/jsx-runtime";
+import { useMemo, useState as useState2 } from "react";
+import { DEFAULT_PAGE_SIZE as DEFAULT_PAGE_SIZE2 } from "@apliteni/apliteni-ui";
+
+// src/Pagination.tsx
+import { useEffect as useEffect2, useId, useRef as useRef2, useState } from "react";
+import { DEFAULT_PAGE_SIZE } from "@apliteni/apliteni-ui";
+import { jsx as jsx6, jsxs as jsxs4 } from "react/jsx-runtime";
+var GHOST_SM = "ui-btn ui-btn--ghost ui-btn--sm";
+var VARIANTS = ["steps", "numbered", "jump"];
+var cx2 = (...a) => a.filter(Boolean).join(" ");
+var CAP = Number.MAX_SAFE_INTEGER;
+var int = (v, fallback) => {
+  const raw = typeof v === "number" ? v : typeof v === "string" && v.trim() !== "" ? Number(v) : NaN;
+  if (!Number.isFinite(raw)) return fallback;
+  return Math.min(Math.max(Math.trunc(raw), -CAP), CAP);
+};
+var sizeOf = (v, fallback) => {
+  const asked = int(v, fallback);
+  return asked > 0 ? asked : fallback;
+};
+var fmt = (n) => n.toLocaleString("en-US");
+function slotsFor(page, pageCount) {
+  const wanted = [1, pageCount, page - 1, page, page + 1].filter((n) => n >= 1 && n <= pageCount);
+  const shown = [...new Set(wanted)].sort((a, b) => a - b);
+  const out = [];
+  for (const n of shown) {
+    const prev = out.length ? out[out.length - 1] : null;
+    if (prev != null) {
+      if (n - prev === 2) out.push(prev + 1);
+      else if (n - prev > 2) out.push(null);
+    }
+    out.push(n);
+  }
+  return out;
+}
+function Pagination({
+  page = 1,
+  pageSize,
+  total = null,
+  hasMore = false,
+  pageSizes = null,
+  variant = "steps",
+  label = "Pagination",
+  loading = false,
+  id,
+  onPageChange,
+  onPageSizeChange
+}) {
+  const auto = useId();
+  const [draft, setDraft] = useState("");
+  const [drafting, setDrafting] = useState(false);
+  const nav = useRef2(null);
+  const pressed = useRef2(null);
+  const uid = id ?? auto;
+  const kind = VARIANTS.includes(variant) ? variant : "steps";
+  const size = sizeOf(pageSize, DEFAULT_PAGE_SIZE);
+  const asRows = int(total, null);
+  const counted = total != null && asRows !== null;
+  const rows = counted ? Math.max(0, asRows) : null;
+  const last = counted ? Math.max(1, Math.ceil(rows / size)) : null;
+  const at = counted ? Math.min(Math.max(1, int(page, 1)), last) : Math.min(Math.max(1, int(page, 1)), CAP - 1);
+  const [draftFor, setDraftFor] = useState(at);
+  if (draftFor !== at) {
+    setDraftFor(at);
+    setDraft("");
+    setDrafting(false);
+  }
+  const offered = (Array.isArray(pageSizes) ? pageSizes : []).slice(0, 12).map((s) => int(s, 0)).filter((s) => s > 0);
+  const sizes = offered.length ? [.../* @__PURE__ */ new Set([...offered, size])].sort((a, b) => a - b) : [];
+  useEffect2(() => {
+    const was = pressed.current;
+    if (!was || loading) return;
+    pressed.current = null;
+    const lost = document.activeElement === document.body || document.activeElement === was;
+    if (!lost || !nav.current?.contains(was)) return;
+    if (!was.disabled) {
+      was.focus();
+      return;
+    }
+    const strip = [...nav.current.querySelectorAll(".ui-pager__step")];
+    const from2 = strip.indexOf(was);
+    for (let d = 1; d < strip.length; d += 1) {
+      const near = [strip[from2 - d], strip[from2 + d]].find((el) => el && !el.disabled);
+      if (near) {
+        near.focus();
+        return;
+      }
+    }
+  }, [at, loading]);
+  const single = counted && last === 1;
+  if (single && !sizes.length) return null;
+  const from = (at - 1) * size + 1;
+  const to = counted ? Math.min(at * size, rows) : null;
+  const status = !counted ? `Page ${fmt(at)}` : rows === 0 ? "0 of 0" : from === to ? `${fmt(from)} of ${fmt(rows)}` : `${fmt(from)}\u2013${fmt(to)} of ${fmt(rows)}`;
+  const go = (n) => onPageChange?.(n);
+  const step = (label_, target, disabled) => (
+    // A control at an end is disabled and stays where it is: removing it slides
+    // the next control under a pointer already travelling toward it.
+    /* @__PURE__ */ jsx6(
+      "button",
+      {
+        type: "button",
+        className: `${GHOST_SM} ui-pager__step`,
+        "data-page": target,
+        disabled: loading || disabled,
+        "aria-disabled": loading || disabled ? true : void 0,
+        onClick: (e) => {
+          pressed.current = e.currentTarget;
+          go(target);
+        },
+        children: label_
+      },
+      label_
+    )
+  );
+  const atStart = at === 1;
+  const atEnd = counted && at === last;
+  const ends = kind !== "numbered";
+  const commitJump = () => {
+    setDrafting(false);
+    const typed = draft.trim();
+    if (typed === "") return;
+    const n = Math.min(Math.max(1, int(typed, at)), last);
+    if (n !== at) go(n);
+  };
+  const leaveJump = (to2) => {
+    if (to2 && nav.current?.contains(to2)) {
+      setDrafting(false);
+      setDraft("");
+      return;
+    }
+    commitJump();
+  };
+  let steps = null;
+  if (single) {
+    steps = null;
+  } else if (!counted) {
+    steps = /* @__PURE__ */ jsxs4("div", { className: "ui-pager__steps", children: [
+      step("Prev", Math.max(1, at - 1), atStart),
+      step("Next", at + 1, !hasMore)
+    ] });
+  } else {
+    let middle = null;
+    if (kind === "numbered") {
+      middle = slotsFor(at, last).map((n, i) => n == null ? /* @__PURE__ */ jsx6("span", { className: "ui-pager__gap", "aria-hidden": "true", children: "\u2026" }, `gap${i}`) : /* @__PURE__ */ jsx6(
+        "button",
+        {
+          type: "button",
+          "data-page": n,
+          className: cx2(`${GHOST_SM} ui-pager__page`, n === at && "is-current"),
+          "aria-current": n === at ? "page" : void 0,
+          disabled: loading,
+          "aria-disabled": loading ? true : void 0,
+          onClick: () => go(n),
+          children: fmt(n)
+        },
+        n
+      ));
+    } else if (kind === "jump") {
+      middle = /* @__PURE__ */ jsxs4("span", { className: "ui-pager__jump", children: [
+        /* @__PURE__ */ jsx6("label", { htmlFor: `${uid}-jump`, children: "Page" }),
+        /* @__PURE__ */ jsx6(
+          "input",
+          {
+            className: "ui-input ui-pager__jump-input",
+            id: `${uid}-jump`,
+            type: "number",
+            min: 1,
+            max: last,
+            disabled: loading,
+            value: drafting ? draft : String(at),
+            onChange: (e) => {
+              setDrafting(true);
+              setDraft(e.target.value);
+            },
+            onBlur: (e) => leaveJump(e.relatedTarget),
+            onKeyDown: (e) => {
+              if (e.key === "Enter") {
+                e.preventDefault();
+                commitJump();
+              }
+            }
+          }
+        ),
+        /* @__PURE__ */ jsxs4("span", { className: "ui-pager__jump-of", children: [
+          "of ",
+          fmt(last)
+        ] })
+      ] });
+    }
+    steps = /* @__PURE__ */ jsxs4("div", { className: "ui-pager__steps", children: [
+      ends ? step("First", 1, atStart) : null,
+      step("Prev", Math.max(1, at - 1), atStart),
+      middle,
+      step("Next", Math.min(last, at + 1), atEnd),
+      ends ? step("Last", last, atEnd) : null
+    ] });
+  }
+  return /* @__PURE__ */ jsxs4(
+    "nav",
+    {
+      ref: nav,
+      className: cx2("ui-pager", `ui-pager--${kind}`, !counted && "ui-pager--open", single && "ui-pager--single"),
+      "aria-label": label,
+      "aria-busy": loading ? true : void 0,
+      children: [
+        /* @__PURE__ */ jsx6("p", { className: "ui-pager__status", "aria-live": "polite", "aria-atomic": "true", children: status }),
+        sizes.length ? /* @__PURE__ */ jsxs4("div", { className: "ui-pager__size", children: [
+          /* @__PURE__ */ jsx6("label", { className: "ui-pager__size-label", htmlFor: `${uid}-size`, children: "Rows" }),
+          /* @__PURE__ */ jsx6(
+            "select",
+            {
+              className: "ui-select ui-pager__size-select",
+              id: `${uid}-size`,
+              disabled: loading,
+              value: size,
+              onChange: (e) => onPageSizeChange?.(Number(e.target.value)),
+              children: sizes.map((s) => /* @__PURE__ */ jsx6("option", { value: s, children: fmt(s) }, s))
+            }
+          )
+        ] }) : null,
+        steps
+      ]
+    }
+  );
+}
+
+// src/DataTable.tsx
+import { Fragment, jsx as jsx7, jsxs as jsxs5 } from "react/jsx-runtime";
+var NO_SORT = { key: void 0, dir: -1 };
 function sortTableRows(rows, sort) {
   if (sort.key === void 0) return [...rows];
   const key = sort.key;
@@ -180,7 +408,12 @@ function sortTableRows(rows, sort) {
 function DataTable({
   columns,
   rows,
-  pageSize = 4,
+  pageSize,
+  pageSizes = null,
+  onPageSizeChange,
+  pager = true,
+  pagerLabel,
+  loading = false,
   selectable = true,
   selected = /* @__PURE__ */ new Set(),
   onToggle = () => {
@@ -188,113 +421,124 @@ function DataTable({
   onTogglePage = () => {
   },
   sort: controlledSort,
-  onSortChange
+  onSortChange,
+  page: controlledPage,
+  onPageChange,
+  total,
+  hasMore = false
 }) {
-  const [localSort, setLocalSort] = useState(
+  const [localSort, setLocalSort] = useState2(
     { key: columns.find((c) => c.sortable)?.key, dir: -1 }
   );
-  const sort = controlledSort ?? localSort;
-  const [page, setPage] = useState(0);
-  const [pagedSort, setPagedSort] = useState(sort);
+  const owned = controlledPage === void 0;
+  const sort = controlledSort ?? (owned ? localSort : NO_SORT);
+  const sortIsKnown = owned || controlledSort !== void 0;
+  const [localPage, setLocalPage] = useState2(1);
+  const [localSize, setLocalSize] = useState2(DEFAULT_PAGE_SIZE2);
+  const size = sizeOf(pageSize, owned ? localSize : rows.length || DEFAULT_PAGE_SIZE2);
+  const [pagedSort, setPagedSort] = useState2(sort);
   if (pagedSort.key !== sort.key || pagedSort.dir !== sort.dir) {
     setPagedSort(sort);
-    setPage(0);
+    setLocalPage(1);
   }
-  const sorted = useMemo(() => sortTableRows(rows, sort), [rows, sort.key, sort.dir]);
-  const pages = Math.max(1, Math.ceil(sorted.length / pageSize));
-  const safePage = Math.min(page, pages - 1);
-  const slice = sorted.slice(safePage * pageSize, safePage * pageSize + pageSize);
+  const ordered = useMemo(
+    () => owned ? sortTableRows(rows, sort) : rows,
+    [owned, rows, sort.key, sort.dir]
+  );
+  const pages = Math.max(1, Math.ceil(ordered.length / size));
+  const page = owned ? Math.min(Math.max(1, localPage), pages) : controlledPage;
+  const slice = owned ? ordered.slice((page - 1) * size, page * size) : ordered;
+  const goTo = (n) => owned ? setLocalPage(n) : onPageChange?.(n);
+  const toFirstPage = () => {
+    if (owned) setLocalPage(1);
+    else if (page !== 1) onPageChange?.(1);
+  };
   const onSort = (key) => {
     const next = sort.key === key ? { key, dir: sort.dir === 1 ? -1 : 1 } : { key, dir: -1 };
     if (controlledSort === void 0) setLocalSort(next);
     onSortChange?.(next);
-    setPage(0);
+    toFirstPage();
   };
   const caret = (k) => sort.key === k ? sort.dir === 1 ? " \u25B2" : " \u25BC" : " \u2195";
   const pageAllOn = selectable && slice.length > 0 && slice.every((r) => selected.has(r.name));
-  return /* @__PURE__ */ jsxs4(Fragment, { children: [
-    /* @__PURE__ */ jsxs4("table", { className: "ui-table ui-table--hover ui-table--zebra", children: [
-      /* @__PURE__ */ jsx6("thead", { children: /* @__PURE__ */ jsxs4("tr", { children: [
-        selectable ? /* @__PURE__ */ jsx6("th", { scope: "col", children: /* @__PURE__ */ jsx6(
-          "input",
-          {
-            type: "checkbox",
-            checked: pageAllOn,
-            "aria-label": "Select all rows on this page",
-            onChange: () => onTogglePage(slice.map((r) => r.name))
-          }
-        ) }) : null,
-        columns.map((c) => (
-          // The sort control is a real <button> inside the header cell. It used to be
-          // role="button" ON the <th>, which threw away the columnheader role and put
-          // aria-sort on a role that forbids it.
-          /* @__PURE__ */ jsx6(
-            "th",
-            {
-              scope: "col",
-              className: [c.num && "ui-table__num", c.sortable && "rx-sortable"].filter(Boolean).join(" "),
-              "aria-sort": sort.key === c.key ? sort.dir === 1 ? "ascending" : "descending" : c.sortable ? "none" : void 0,
-              children: c.sortable ? /* @__PURE__ */ jsxs4("button", { type: "button", className: "rx-sort", onClick: () => onSort(c.key), children: [
-                c.label,
-                /* @__PURE__ */ jsx6("span", { className: "rx-caret", "aria-hidden": "true", children: caret(c.key) })
-              ] }) : c.label
-            },
-            c.key
-          )
-        ))
-      ] }) }),
-      /* @__PURE__ */ jsx6("tbody", { children: slice.map((r) => /* @__PURE__ */ jsxs4("tr", { children: [
-        selectable ? /* @__PURE__ */ jsx6("td", { children: /* @__PURE__ */ jsx6(
-          "input",
-          {
-            type: "checkbox",
-            checked: selected.has(r.name),
-            "aria-label": `Select ${r.name}`,
-            onChange: () => onToggle(r.name)
-          }
-        ) }) : null,
-        columns.map((c) => /* @__PURE__ */ jsx6("td", { className: c.num ? "ui-table__num" : void 0, children: c.render ? c.render(r) : String(r[c.key]) }, c.key))
-      ] }, r.name)) })
-    ] }),
-    /* @__PURE__ */ jsxs4("div", { className: "rx-pager", children: [
-      /* @__PURE__ */ jsxs4("span", { className: "rx-pager__info", children: [
-        "Page ",
-        safePage + 1,
-        " of ",
-        pages,
-        " \xB7 ",
-        sorted.length,
-        " rows"
-      ] }),
-      /* @__PURE__ */ jsx6(
-        Button,
-        {
-          variant: "ghost",
-          size: "sm",
-          icon: "chevronLeft",
-          disabled: safePage === 0,
-          onClick: () => setPage(safePage - 1),
-          children: "Prev"
-        }
-      ),
-      /* @__PURE__ */ jsx6(
-        Button,
-        {
-          variant: "ghost",
-          size: "sm",
-          iconRight: "chevronRight",
-          disabled: safePage >= pages - 1,
-          onClick: () => setPage(safePage + 1),
-          children: "Next"
+  return /* @__PURE__ */ jsxs5(Fragment, { children: [
+    /* @__PURE__ */ jsxs5(
+      "table",
+      {
+        className: "ui-table ui-table--hover ui-table--zebra",
+        "aria-busy": loading || void 0,
+        children: [
+          /* @__PURE__ */ jsx7("thead", { children: /* @__PURE__ */ jsxs5("tr", { children: [
+            selectable ? /* @__PURE__ */ jsx7("th", { scope: "col", children: /* @__PURE__ */ jsx7(
+              "input",
+              {
+                type: "checkbox",
+                checked: pageAllOn,
+                "aria-label": "Select all rows on this page",
+                onChange: () => onTogglePage(slice.map((r) => r.name))
+              }
+            ) }) : null,
+            columns.map((c) => (
+              // The sort control is a real <button> inside the header cell. It used to be
+              // role="button" ON the <th>, which threw away the columnheader role and put
+              // aria-sort on a role that forbids it.
+              /* @__PURE__ */ jsx7(
+                "th",
+                {
+                  scope: "col",
+                  className: [c.num && "ui-table__num", c.sortable && "rx-sortable"].filter(Boolean).join(" "),
+                  "aria-sort": sort.key === c.key ? sort.dir === 1 ? "ascending" : "descending" : c.sortable && sortIsKnown ? "none" : void 0,
+                  children: c.sortable ? /* @__PURE__ */ jsxs5("button", { type: "button", className: "rx-sort", onClick: () => onSort(c.key), children: [
+                    c.label,
+                    /* @__PURE__ */ jsx7("span", { className: "rx-caret", "aria-hidden": "true", children: caret(c.key) })
+                  ] }) : c.label
+                },
+                c.key
+              )
+            ))
+          ] }) }),
+          /* @__PURE__ */ jsx7("tbody", { children: slice.map((r) => /* @__PURE__ */ jsxs5("tr", { children: [
+            selectable ? /* @__PURE__ */ jsx7("td", { children: /* @__PURE__ */ jsx7(
+              "input",
+              {
+                type: "checkbox",
+                checked: selected.has(r.name),
+                "aria-label": `Select ${r.name}`,
+                onChange: () => onToggle(r.name)
+              }
+            ) }) : null,
+            columns.map((c) => /* @__PURE__ */ jsx7("td", { className: c.num ? "ui-table__num" : void 0, children: c.render ? c.render(r) : String(r[c.key]) }, c.key))
+          ] }, r.name)) })
+        ]
+      }
+    ),
+    pager ? /* @__PURE__ */ jsx7(
+      Pagination,
+      {
+        page,
+        pageSize: size,
+        total: owned ? ordered.length : total ?? null,
+        hasMore,
+        pageSizes,
+        loading,
+        ...pagerLabel === void 0 ? {} : { label: pagerLabel },
+        onPageChange: goTo,
+        onPageSizeChange: (s) => {
+          if (pageSize === void 0) setLocalSize(s);
+          onPageSizeChange?.(s);
+          if (owned) setLocalPage(1);
         }
-      )
-    ] })
+      }
+    ) : null
   ] });
 }
 
+// src/index.ts
+import { PAGE_SIZES as KIT_PAGE_SIZES, DEFAULT_PAGE_SIZE as KIT_DEFAULT_PAGE_SIZE } from "@apliteni/apliteni-ui";
+
 // src/Loading.tsx
-import { jsx as jsx7, jsxs as jsxs5 } from "react/jsx-runtime";
-var cx2 = (...a) => a.filter(Boolean).join(" ");
+import { jsx as jsx8, jsxs as jsxs6 } from "react/jsx-runtime";
+var cx3 = (...a) => a.filter(Boolean).join(" ");
 function Skeleton({ lines = 3, width, height, radius, className }) {
   const widths = Array.isArray(lines) ? lines : null;
   const n = widths ? widths.length : Math.max(1, lines);
@@ -303,19 +547,19 @@ function Skeleton({ lines = 3, width, height, radius, className }) {
     if (!w && !height && !radius) return void 0;
     return { ...w && { width: w }, ...height && { height }, ...radius && { borderRadius: radius } };
   };
-  return /* @__PURE__ */ jsx7("div", { className: cx2("ui-skel", className), "aria-hidden": "true", children: Array.from({ length: n }, (_, i) => /* @__PURE__ */ jsx7("span", { className: "ui-skel__bar m-skeleton", style: styleFor(i) }, i)) });
+  return /* @__PURE__ */ jsx8("div", { className: cx3("ui-skel", className), "aria-hidden": "true", children: Array.from({ length: n }, (_, i) => /* @__PURE__ */ jsx8("span", { className: "ui-skel__bar m-skeleton", style: styleFor(i) }, i)) });
 }
 function SkeletonTable({ rows = 5, cols = 4, head = true }) {
-  const cells = Array.from({ length: Math.max(1, cols) }, (_, i) => /* @__PURE__ */ jsx7("span", { className: "ui-skel__bar m-skeleton" }, i));
-  return /* @__PURE__ */ jsxs5(
+  const cells = Array.from({ length: Math.max(1, cols) }, (_, i) => /* @__PURE__ */ jsx8("span", { className: "ui-skel__bar m-skeleton" }, i));
+  return /* @__PURE__ */ jsxs6(
     "div",
     {
       className: "ui-skel ui-skel--table",
       style: { "--skel-cols": Math.max(1, cols) },
       "aria-hidden": "true",
       children: [
-        head && /* @__PURE__ */ jsx7("div", { className: "ui-skel__row ui-skel__row--head", children: cells }),
-        Array.from({ length: Math.max(1, rows) }, (_, i) => /* @__PURE__ */ jsx7("div", { className: "ui-skel__row", children: cells }, i))
+        head && /* @__PURE__ */ jsx8("div", { className: "ui-skel__row ui-skel__row--head", children: cells }),
+        Array.from({ length: Math.max(1, rows) }, (_, i) => /* @__PURE__ */ jsx8("div", { className: "ui-skel__row", children: cells }, i))
       ]
     }
   );
@@ -328,16 +572,16 @@ function BusyRegion({
   className,
   children
 }) {
-  return /* @__PURE__ */ jsxs5(
+  return /* @__PURE__ */ jsxs6(
     "div",
     {
-      className: cx2("ui-busy", className),
+      className: cx3("ui-busy", className),
       role: "status",
       "aria-live": "polite",
       "aria-busy": busy,
       children: [
-        /* @__PURE__ */ jsx7("span", { className: "ui-sr", children: busy ? label : message }),
-        /* @__PURE__ */ jsx7("div", { className: "ui-busy__body", children: busy ? placeholder ?? /* @__PURE__ */ jsx7(Skeleton, { lines: 3 }) : children })
+        /* @__PURE__ */ jsx8("span", { className: "ui-sr", children: busy ? label : message }),
+        /* @__PURE__ */ jsx8("div", { className: "ui-busy__body", children: busy ? placeholder ?? /* @__PURE__ */ jsx8(Skeleton, { lines: 3 }) : children })
       ]
     }
   );
@@ -350,26 +594,33 @@ function Denied({
   className,
   children
 }) {
-  return /* @__PURE__ */ jsxs5("div", { className: cx2("ui-denied", className), children: [
-    /* @__PURE__ */ jsx7("div", { className: "ui-denied__seal", children: /* @__PURE__ */ jsx7(Icon, { name: icon2 }) }),
-    /* @__PURE__ */ jsx7("div", { className: "ui-denied__title", children: title }),
-    sub && /* @__PURE__ */ jsx7("div", { className: "ui-denied__sub", children: sub }),
-    need && /* @__PURE__ */ jsxs5("div", { className: "ui-denied__need", children: [
+  return /* @__PURE__ */ jsxs6("div", { className: cx3("ui-denied", className), children: [
+    /* @__PURE__ */ jsx8("div", { className: "ui-denied__seal", children: /* @__PURE__ */ jsx8(Icon, { name: icon2 }) }),
+    /* @__PURE__ */ jsx8("div", { className: "ui-denied__title", children: title }),
+    sub && /* @__PURE__ */ jsx8("div", { className: "ui-denied__sub", children: sub }),
+    need && /* @__PURE__ */ jsxs6("div", { className: "ui-denied__need", children: [
       "Needs ",
-      /* @__PURE__ */ jsx7("code", { className: "ui-code", children: need })
+      /* @__PURE__ */ jsx8("code", { className: "ui-code", children: need })
     ] }),
-    children && /* @__PURE__ */ jsx7("div", { className: "ui-denied__actions", children })
+    children && /* @__PURE__ */ jsx8("div", { className: "ui-denied__actions", children })
   ] });
 }
+
+// src/index.ts
+var PAGE_SIZES = KIT_PAGE_SIZES;
+var DEFAULT_PAGE_SIZE3 = KIT_DEFAULT_PAGE_SIZE;
 export {
   Badge,
   BusyRegion,
   Button,
   Card,
+  DEFAULT_PAGE_SIZE3 as DEFAULT_PAGE_SIZE,
   DataTable,
   Denied,
   Icon,
   Modal,
+  PAGE_SIZES,
+  Pagination,
   Skeleton,
   SkeletonTable,
   sortTableRows

package/src/components/pagination.js

@@ -0,0 +1,344 @@
+// Pagination — the strip under a table or a list, as an HTML string.
+//
+// It renders a page the CALLER computed. Rows never come in here: `page`,
+// `pageSize` and `total` are numbers, so a page counted by a server and a page
+// sliced out of an array in memory produce the same markup.
+//
+// `total: null` is the honest shape for an API that cannot count what it has not
+// fetched. The component then knows no last page, so it draws Prev and Next and
+// nothing else — see `ui-pager--open` below.
+import { esc } from './index.js';
+
+// The sizes a table offers, and the one it starts on. Named here so no call site
+// writes either number: both moved once already and would have moved in thirteen
+// files. MUI's DataGrid ships exactly this pair (default 100, options 25/50/100),
+// AG Grid defaults to 100, and the finance portal's two data-heavy surfaces
+// already page at 100. A 250 step was in the first draft of this component and
+// no surveyed kit offers one, so it went rather than being invented.
+export const PAGE_SIZES = [25, 50, 100];
+export const DEFAULT_PAGE_SIZE = 100;
+
+// The classes button({ variant: 'ghost', size: 'sm' }) emits, written out because
+// button() takes no extra class and every control here needs one of its own for
+// the React component to key on. src/components/pagination.test.js asserts the
+// two agree, so a change to button()'s class list fails there instead of drifting.
+const GHOST_SM = 'ui-btn ui-btn--ghost ui-btn--sm';
+
+const VARIANTS = ['steps', 'numbered', 'jump'];
+
+// The id seeds a <label for> and the control it names, so two pagers that share
+// one are two labels pointing at one control: the second table's "Rows" label
+// focuses the FIRST table's select, and the second select has no accessible name
+// at all. `tabs()` states the same requirement in words and leaves it there; a
+// pager is dropped under a table by a caller who is not thinking about ids, and
+// two tables on a page is the ordinary case rather than the exotic one. So an
+// omitted id is unique by construction instead. A caller who needs a stable id —
+// a server rendering the same page twice, a test — passes one.
+let seq = 0;
+const cx = (...a) => a.filter(Boolean).join(' ');
+
+// Every number here arrives from a URL in real use — `?page=-2`, `?page=abc`,
+// `?page=` — so each is coerced before it is clamped, and nothing that is not a
+// finite integer reaches the markup.
+//
+// `Number()` alone is not that check, and the first draft of this used it. It
+// reads '', '  ', null, [] and false as 0, all of which are finite: `?total=` then
+// meant "this result holds zero rows" and erased the whole component, and
+// `?pageSize=` meant one row per page. Only a number, or a string with something
+// in it, is a number here. A Symbol is refused rather than thrown on — a string
+// factory that raises a TypeError is a worse answer than a pager.
+//
+// The cap is Number.MAX_SAFE_INTEGER because above it arithmetic stops moving:
+// `at - 1 === at === at + 1`, so Prev and Next would carry the same target while
+// both rendered live, and a page past 1e21 prints as `1e+21`, which parseInt reads
+// back as 1.
+const CAP = Number.MAX_SAFE_INTEGER;
+const int = (v, fallback) => {
+  const raw = typeof v === 'number' ? v
+    : (typeof v === 'string' && v.trim() !== '') ? Number(v)
+      : NaN;
+  if (!Number.isFinite(raw)) return fallback;
+  return Math.min(Math.max(Math.trunc(raw), -CAP), CAP);
+};
+const fmt = (n) => n.toLocaleString('en-US');
+
+// A control at an end is DISABLED, never removed. Polaris states the rule as
+// "Hint when merchants are at the first or the last page by disabling the
+// corresponding button": removing it slides the next control sideways under a
+// pointer already travelling toward it, and takes away the only evidence a
+// screen-reader user has that they are at the start.
+//
+// An <a> has no disabled state, so an end that is off renders as
+// <button disabled> even when `href` was given — a link that goes nowhere reads
+// as available right up until it is followed.
+function control({ cls, page, label, href, disabled = false, current = false }) {
+  const attrs = `class="${cls}" data-page="${page}"${current ? ' aria-current="page"' : ''}`;
+  return href && !disabled
+    ? `<a href="${esc(href(page))}" ${attrs}>${esc(label)}</a>`
+    : `<button type="button" ${attrs}${disabled ? ' disabled aria-disabled="true"' : ''}>${esc(label)}</button>`;
+}
+
+/**
+ * The page numbers a `numbered` pager shows, with `null` where a run was cut.
+ *
+ * Seven slots at most: page 1, the last page, the current page with one
+ * neighbour each side, and a gap for each run removed between them. Two rules
+ * keep the strip honest — no two gaps side by side, and no gap standing in for a
+ * single page, because an ellipsis hiding one number is wider than the number
+ * and costs a click to find out what it was.
+ */
+function slotsFor(page, pageCount) {
+  const wanted = [1, pageCount, page - 1, page, page + 1]
+    .filter((n) => n >= 1 && n <= pageCount);
+  const shown = [...new Set(wanted)].sort((a, b) => a - b);
+  const out = [];
+  for (const n of shown) {
+    const prev = out.length ? out[out.length - 1] : null;
+    if (prev != null) {
+      if (n - prev === 2) out.push(prev + 1); // one page hidden — draw it, not a gap
+      else if (n - prev > 2) out.push(null);
+    }
+    out.push(n);
+  }
+  return out;
+}
+
+/**
+ * pagination({ … }) → the <nav> a caller drops under a table.
+ *
+ * A pager for a single page draws no steps: GOV.UK's guidance is "Do not show
+ * pagination if there's only one page of content", and the kit was rendering
+ * two permanently dead buttons under every short table. With no size control to
+ * offer, such a pager has no job at all and returns the empty string; with one,
+ * the <nav> stays for the size control alone — somebody looking at 25 of 25 rows
+ * may still want 100 per page — and carries `ui-pager--single`.
+ */
+export function pagination({
+  page = 1,
+  pageSize = DEFAULT_PAGE_SIZE,
+  total = null,
+  hasMore = false,
+  pageSizes = null,
+  variant = 'steps',
+  label = 'Pagination',
+  loading = false,
+  href = null,
+  id,
+} = {}) {
+  const uid = esc(String(id ?? `pager-${++seq}`));
+  const kind = VARIANTS.includes(variant) ? variant : 'steps';
+  // A size of zero or less is not a size, so it is read as absent rather than
+  // clamped to 1 — clamping turns `?pageSize=0` into 4,812 pages of one row.
+  const asked = int(pageSize, DEFAULT_PAGE_SIZE);
+  const size = asked > 0 ? asked : DEFAULT_PAGE_SIZE;
+  // A total that is not a number is a total nobody knows — the open shape is the
+  // truthful answer to it, and it is the same answer `total: null` asks for.
+  const asRows = int(total, null);
+  const counted = total != null && asRows !== null;
+  const rows = counted ? Math.max(0, asRows) : null;
+  const last = counted ? Math.max(1, Math.ceil(rows / size)) : null;
+  // One below the cap when nothing is counted, because the open shape emits
+  // `at + 1` as Next's target and MAX_SAFE_INTEGER + 1 is not representable — it
+  // rounds back onto its neighbour, so Prev and Next would carry one page again.
+  const at = counted
+    ? Math.min(Math.max(1, int(page, 1)), last)
+    : Math.min(Math.max(1, int(page, 1)), CAP - 1);
+
+  // The current size is offered even when the caller's list forgot it: a select
+  // whose value is not among its options renders as the first one, which reports
+  // a page size the table is not using.
+  // Capped: this is a string factory, and a caller who hands it a hundred thousand
+  // sizes gets a hundred thousand <option>s and megabytes of HTML rather than an
+  // error. Twelve is past any real size menu — MUI ships four.
+  const offered = (Array.isArray(pageSizes) ? pageSizes : [])
+    .slice(0, 12)
+    .map((s) => int(s, 0))
+    .filter((s) => s > 0);
+  const sizes = offered.length
+    ? [...new Set([...offered, size])].sort((a, b) => a - b)
+    : [];
+
+  const single = counted && last === 1;
+  if (single && !sizes.length) return '';
+
+  const from = (at - 1) * size + 1;
+  const to = counted ? Math.min(at * size, rows) : null;
+  // Not "1–0 of 0" for an empty result, and not "7–7 of 7" for a single row:
+  // both are arithmetic a reader has to undo.
+  const status = !counted ? `Page ${fmt(at)}`
+    : rows === 0 ? '0 of 0'
+      : from === to ? `${fmt(from)} of ${fmt(rows)}`
+        : `${fmt(from)}–${fmt(to)} of ${fmt(rows)}`;
+
+  const sizeBlock = sizes.length
+    ? `<div class="ui-pager__size">`
+      + `<label class="ui-pager__size-label" for="${uid}-size">Rows</label>`
+      + `<select class="ui-select ui-pager__size-select" id="${uid}-size"${loading ? ' disabled' : ''}>`
+      + sizes.map((s) => `<option value="${s}"${s === size ? ' selected' : ''}>${fmt(s)}</option>`).join('')
+      + `</select></div>`
+    : '';
+
+  const step = (spec) => control({ cls: `${GHOST_SM} ui-pager__step`, href, ...spec, disabled: loading || spec.disabled });
+  const atStart = at === 1;
+  const atEnd = counted && at === last;
+
+  let steps = '';
+  if (single) {
+    steps = ''; // GOV.UK: no pagination for one page of content.
+  } else if (!counted) {
+    // The open shape: no last page exists, so no control may claim to reach one.
+    // Next is off when the caller says there is nothing after this page.
+    steps = `<div class="ui-pager__steps">`
+      + step({ page: Math.max(1, at - 1), label: 'Prev', disabled: atStart })
+      + step({ page: at + 1, label: 'Next', disabled: !hasMore })
+      + `</div>`;
+  } else {
+    let middle = '';
+    if (kind === 'numbered') {
+      middle = slotsFor(at, last).map((n) => (n == null
+        ? '<span class="ui-pager__gap" aria-hidden="true">…</span>'
+        : control({
+          cls: cx(`${GHOST_SM} ui-pager__page`, n === at && 'is-current'),
+          href,
+          page: n,
+          label: fmt(n),
+          current: n === at,
+          disabled: loading,
+        }))).join('');
+    } else if (kind === 'jump') {
+      middle = `<span class="ui-pager__jump"><label for="${uid}-jump">Page</label>`
+        + `<input class="ui-input ui-pager__jump-input" id="${uid}-jump" type="number"`
+        + ` min="1" max="${last}" value="${at}"${loading ? ' disabled' : ''}>`
+        + `<span class="ui-pager__jump-of">of ${fmt(last)}</span></span>`;
+    }
+    // First and Last are the numbered variant's own job — its first and last
+    // slots are always those two pages, so a second pair of controls for them
+    // would be the same jump written twice.
+    const ends = kind !== 'numbered';
+    steps = `<div class="ui-pager__steps">`
+      + (ends ? step({ page: 1, label: 'First', disabled: atStart }) : '')
+      + step({ page: Math.max(1, at - 1), label: 'Prev', disabled: atStart })
+      + middle
+      + step({ page: Math.min(last, at + 1), label: 'Next', disabled: atEnd })
+      + (ends ? step({ page: last, label: 'Last', disabled: atEnd }) : '')
+      + `</div>`;
+  }
+
+  // The status line is the only live region in the component: a strip where the
+  // numbers, the size control and four buttons all announced would read the same
+  // change out four times.
+  return `<nav class="${cx('ui-pager', `ui-pager--${kind}`, !counted && 'ui-pager--open', single && 'ui-pager--single')}"`
+    + ` aria-label="${esc(label)}"${loading ? ' aria-busy="true"' : ''}>`
+    + `<p class="ui-pager__status" aria-live="polite" aria-atomic="true">${esc(status)}</p>`
+    + sizeBlock
+    + steps
+    + `</nav>`;
+}
+
+/**
+ * Make a rendered pager work.
+ *
+ * Every control the factory draws is inert markup until this runs: the steps
+ * carry `data-page` and nothing reads it, the size control is a `<select>` with
+ * no handler, and the jump input is an `<input>` with no handler. Shipping the
+ * `jump` variant without this meant shipping the one control that reaches an
+ * arbitrary page and having it do nothing.
+ *
+ * It reads the class contract rather than hooks of its own — `.ui-pager__step`,
+ * `.ui-pager__page`, `.ui-pager__size-select`, `.ui-pager__jump-input` — so the
+ * markup is exactly what `pagination()` already returns and the React component
+ * is still class-for-class identical to it.
+ *
+ *   const pager = wirePagination(root, {
+ *     onPage: (page) => load({ page }),
+ *     onPageSize: (size) => load({ page: 1, size }),
+ *   });
+ *
+ * Listeners are delegated from `root`, so a pager re-rendered underneath stays
+ * wired. Returns a function that removes them.
+ *
+ * A step rendered as an `<a href>` is left alone: it is a link, the browser owns
+ * it, and calling it back as well would navigate twice.
+ */
+export function wirePagination(root = document, { onPage, onPageSize } = {}) {
+  const scope = typeof root === 'string' ? document.querySelector(root) : root;
+  if (!scope || typeof scope.addEventListener !== 'function') return () => {};
+
+  const pageOf = (el) => int(el.getAttribute('data-page'), null);
+  const inPager = (el) => el && el.closest && el.closest('.ui-pager');
+
+  const onClick = (e) => {
+    const step = e.target.closest?.('.ui-pager__step, .ui-pager__page');
+    if (!step || !inPager(step) || step.tagName === 'A' || step.disabled) return;
+    const page = pageOf(step);
+    if (page !== null) onPage?.(page);
+  };
+
+  const onChange = (e) => {
+    const select = e.target.closest?.('.ui-pager__size-select');
+    if (!select || !inPager(select)) return;
+    const size = int(select.value, null);
+    if (size !== null && size > 0) onPageSize?.(size);
+  };
+
+  // Enter commits; so does leaving the box. A value the input cannot parse — it
+  // is type="number", so a rejected keystroke leaves it empty — is not a page,
+  // and the box goes back to the one it was showing rather than to page 1.
+  const commit = (box) => {
+    const asked = int(box.value, null);
+    const max = int(box.getAttribute('max'), null);
+    if (asked === null || asked < 1) {
+      box.value = box.defaultValue;
+      return;
+    }
+    const page = max === null ? asked : Math.min(asked, max);
+    box.value = String(page);
+    if (String(page) !== box.defaultValue) onPage?.(page);
+  };
+  const onKeydown = (e) => {
+    const box = e.target.closest?.('.ui-pager__jump-input');
+    if (!box || !inPager(box) || e.key !== 'Enter') return;
+    // A lone number input inside a <form> submits it on Enter, which reloads the
+    // page the reader was trying to move within.
+    e.preventDefault();
+    commit(box);
+  };
+  const onBlur = (e) => {
+    const box = e.target.closest?.('.ui-pager__jump-input');
+    if (box && inPager(box)) commit(box);
+  };
+
+  scope.addEventListener('click', onClick);
+  scope.addEventListener('change', onChange);
+  scope.addEventListener('keydown', onKeydown);
+  scope.addEventListener('focusout', onBlur);
+  return () => {
+    scope.removeEventListener('click', onClick);
+    scope.removeEventListener('change', onChange);
+    scope.removeEventListener('keydown', onKeydown);
+    scope.removeEventListener('focusout', onBlur);
+  };
+}
+
+/**
+ * Rewrite a pager's row range, in place. THIS is the announcement.
+ *
+ * The factory returns a whole `<nav>`, so the obvious way to show a new page is
+ * to replace it — which inserts a brand-new live region that already contains its
+ * text, and several screen readers say nothing at all about a region that arrived
+ * with its content. The kit has met this before and answered it the same way:
+ * `setBusy()` rewrites the line its region already holds rather than inserting a
+ * new one. why: docs/specification.md#pending-and-denied-states
+ *
+ * So a consumer re-rendering a pager should hand the new range here instead of
+ * relying on the replacement to speak. Returns the status element, or null when
+ * there is nothing to update — safe against a torn-down view.
+ */
+export function setPagerStatus(root, text) {
+  const el = typeof root === 'string' ? document.querySelector(root) : root;
+  if (!el || typeof el.querySelector !== 'function') return null;
+  const status = el.matches?.('.ui-pager__status') ? el : el.querySelector('.ui-pager__status');
+  if (!status) return null;
+  if (status.textContent !== String(text)) status.textContent = String(text);
+  return status;
+}

package/src/index.css

@@ -28,6 +28,7 @@
 @import "./styles/drawer.css";
 @import "./styles/confirm.css";
 @import "./styles/table.css";
+@import "./styles/pagination.css";
 @import "./styles/empty.css";
 @import "./styles/callout.css";
 @import "./styles/code.css";

package/src/index.js

@@ -13,6 +13,7 @@ export * from './components/feedback.js';
 export * from './components/toasts.js';
 export * from './components/success.js';
 export * from './components/loading.js';
+export * from './components/pagination.js';
 export * from './assets/icons.js';
 export * from './assets/brand.js';
 export * from './motion.js';

package/src/inline.js

@@ -41,6 +41,7 @@ export const styles = {
   drawer: read('styles/drawer.css'),
   confirm: read('styles/confirm.css'),
   table: read('styles/table.css'),
+  pagination: read('styles/pagination.css'),
   empty: read('styles/empty.css'),
   callout: read('styles/callout.css'),
   code: read('styles/code.css'),
@@ -69,6 +70,7 @@ export const cssText = [
   styles.drawer,
   styles.confirm,
   styles.table,
+  styles.pagination,
   styles.empty,
   styles.callout,
   styles.code,

package/src/styles/button.css

@@ -100,7 +100,21 @@
 .ui-btn--ghost[aria-disabled="true"] {
   background: transparent;
   border-color: transparent;
+  color: var(--disabled-ink-bare);
 }
+/* With no box, the ink is read on whatever is behind it. --disabled-ink read
+   5.18:1 on a card and 4.66:1 on --surface-3 in dark, under #220's 5.56, so the
+   ghost takes an ink set for the dullest ground: in dark 7.00 / 6.24 / 6.69 /
+   5.62 on --bg / --surface / --surface-2 / --surface-3, in light 6.50 / 6.50 /
+   6.01 / 5.60. The enabled ghost's --dim reads 1.5 times that in dark, 1.6 in light.
+
+   #273 got here the long way. It first gave the ghost the flat disabled box
+   instead, on the claim that nothing would get less readable. That was false:
+   --bg and --surface lost up to 0.46. Then the box was rendered in a pager at
+   page 1, and the boxed First and Prev read heavier than the boxless Next and
+   Last beside them: the controls that were off looked like the live ones. No
+   contrast table shows that. The box was reverted and this ink shipped.
+   Held by src/styles/button-disabled.test.js. */
 
 /* Busy: keep the label, run an indeterminate accent shimmer along the base, and
    the button is disabled (not clickable). Pass busy + the .ui-btn__bars markup.

package/src/styles/input.css

@@ -49,7 +49,13 @@
 
 /* The value a reader typed is still the value; it goes quiet, it does not fade
    into the field under it the way an opacity would take both down together. #220 */
+/* `.ui-select` joins these two in #273. It had no disabled rule at all, and it
+   sets `background: var(--surface-2)` as an author declaration — which outranks
+   the UA's own grey-out — so a disabled select rendered pixel-identical to a live
+   one. A pager marked busy showed every button and the jump input visibly off
+   beside a size control that still looked available. */
 .ui-input:disabled,
+.ui-select:disabled,
 .ui-textarea:disabled {
   background: var(--disabled-surface);
   border-color: var(--disabled-border);

package/src/styles/pagination.css

@@ -0,0 +1,124 @@
+/* ============================================================================
+ * Pagination — .ui-pager  (variants: --steps / --numbered / --jump)
+ *   --open    total unknown: Prev and Next only, no last page to reach
+ *   --single  one page of content: the size control alone, no steps
+ * The controls are .ui-btn ghost/sm and the size control is a .ui-select, so
+ * everything here is layout and the two states those sheets do not own.
+ * ========================================================================== */
+
+.ui-pager {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: var(--space-3) var(--space-4);
+  font-size: var(--text-sm);
+}
+
+/* The status is the only thing anchored to the start of the strip: it is read,
+   not aimed at, and pushing the controls to the far end keeps the pointer's
+   target group in one place as the row count changes width. */
+.ui-pager__status {
+  margin: 0 auto 0 0;
+  color: var(--muted);
+  font-variant-numeric: tabular-nums;
+}
+
+.ui-pager__size {
+  display: flex;
+  align-items: center;
+  gap: var(--space-2);
+}
+.ui-pager__size-label { color: var(--muted); }
+
+/* .ui-select is a form field sized for a form — full width, 12px/15px padding.
+   In a pager it sits in a row of sm buttons, so it takes their scale. Two things
+   travel with that: the chevron .ui-select paints is positioned from the right
+   edge, so the padding on that side has to stay clear of it, and the height is
+   declared so this control and the jump input beside it agree on one box. */
+.ui-pager__size-select {
+  width: auto;
+  min-height: var(--space-8);
+  padding: var(--space-1) var(--space-6) var(--space-1) var(--space-2);
+  font-size: var(--text-sm);
+  border-radius: var(--radius-sm);
+  background-position: right var(--space-2) center;
+}
+
+.ui-pager__steps {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: var(--space-1);
+}
+
+/* Page numbers are read as a row of equal cells, and .ui-btn--sm's padding makes
+   "1" narrower than "49" — so a strip re-flows under the pointer as the reader
+   walks into three-digit pages. The number is WCAG 2.5.8's 24px: an equalised
+   cell should not be narrower than a target is allowed to be. */
+.ui-pager__page {
+  min-width: var(--space-6);
+  font-variant-numeric: tabular-nums;
+}
+
+/* The page you are on. Guarded, because this weighs the same as `.ui-btn:disabled`
+   and is imported after it: written plainly it would repaint the current page of
+   a `loading` pager as though it were live, which is the one thing the busy state
+   must not leave behind. Spelled `[disabled]` rather than `:disabled` — the same
+   selector for the markup this component emits, and the spelling that keeps a
+   rule about an ENABLED control out of the disabled-rule sweep in
+   stories/guidelines/accessibility-floor.test.js, which reads selector text. */
+.ui-pager__page.is-current:not([disabled]) {
+  background: var(--surface-3);
+  border-color: var(--border);
+  color: var(--strong);
+  font-weight: var(--weight-semibold);
+}
+
+.ui-pager__gap {
+  padding: 0 var(--space-1);
+  color: var(--muted);
+}
+
+.ui-pager__jump {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--space-2);
+  color: var(--muted);
+  padding: 0 var(--space-1);
+}
+/* Wide enough for four digits and the spinner a number input draws beside them;
+   in ch so it follows the type rather than a measured pixel. The height is
+   declared rather than left to the line box, because an <input> holds its value
+   in a property: it is the one control in the strip with no text of its own, and
+   nothing else gives it the 24px WCAG 2.5.8 asks of a pointer target. */
+.ui-pager__jump-input {
+  width: 8ch;
+  min-height: var(--space-8);
+  padding: var(--space-1) var(--space-2);
+  font-size: var(--text-sm);
+  border-radius: var(--radius-sm);
+  text-align: center;
+}
+
+/* A pager directly after a table stands off it. The strip owns no margin of its
+   own — it is dropped under lists and cards too, and a component that carries
+   spacing everywhere is one every caller has to cancel somewhere — so the gap is
+   declared on the one adjacency the kit can see. `.rx-pager` carried a bare
+   `margin-top: 16px` for this, which is --space-4; the number moves to the scale
+   with it rather than travelling as a literal.
+   why: docs/specification.md#spacing-and-rhythm */
+.ui-table + .ui-pager { margin-top: var(--space-4); }
+
+/* A step given an `href` is an anchor, and a host stylesheet's `a:link` is
+   (0,1,1) — which outranks `.ui-btn--ghost` at (0,1,0) and paints the enabled
+   steps in the host's link colour while the disabled ends keep --disabled-ink-bare.
+   One strip, reading as two different controls. The kit has paid for this twice
+   already and both fixes are the same shape: see the (0,2,0) note on
+   `.ui-nav .ui-nav__item` in nav.css. Storybook ships no `a:link`, so the "Pages
+   as links" story cannot show it — which is why the rule is stated rather than
+   discovered.
+   why: docs/specification.md#pagination */
+a.ui-pager__step,
+a.ui-pager__page { color: var(--dim); }
+a.ui-pager__step:hover,
+a.ui-pager__page:hover { color: var(--strong); }

package/src/tokens/tokens.css

@@ -158,6 +158,11 @@
   --disabled-ink: var(--muted);
   --disabled-surface: var(--surface-2);
   --disabled-border: var(--border);
+  /* The ink of a disabled control that paints no box of its own — a ghost button. With
+     no surface beside it, it is read on whatever is behind it, so it is set to clear the
+     floor on the dullest ground there is (--surface-3). #273
+     why: docs/specification.md#colour-and-contrast */
+  --disabled-ink-bare: #a39eb7;
 
   /* Lifted from #9b5dff, which cleared the flat surfaces and failed on its own wash over
      a card; the value was already in the ramp. --ring is var(--accent) and follows by
@@ -271,6 +276,7 @@
   --disabled-ink: var(--muted);
   --disabled-surface: var(--surface-2);
   --disabled-border: var(--border);
+  --disabled-ink-bare: #585e6c;
 
   --accent: #6a2dcc;
   --accent-strong: #6a2dcc; /* already dark enough for white text */