@apliteni/apliteni-ui 0.25.3 → 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.25.3",
+  "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
 
@@ -64,3 +72,85 @@ The bare `@apliteni/apliteni-ui` specifier in this source resolves to the kit it
 once installed. In the repo there is no copy to resolve to, so `kit-alias.ts` points
 vitest and Storybook straight at `../src/` — which is why the class-name parity tests
 now compare against the working tree rather than the last published release.
+
+### Tables with another presentation of the same rows
+
+Pass `selectable={false}` to omit selection controls and their callbacks. Existing callers
+that supply selection callbacks retain the checkbox column by default.
+
+`sort` and `onSortChange` make sorting controlled. Both presentations can use the exported
+`sortTableRows` helper, so initial order, stable ties and later changes agree:
+
+```tsx
+const [sort, setSort] = useState<TableSort<Row>>({ key: 'name', dir: -1 });
+const ordered = sortTableRows(rows, sort);
+
+<DataTable columns={columns} rows={rows} selectable={false}
+  sort={sort} onSortChange={setSort} />
+```
+
+Render the sibling list from `ordered`. Omit `sort` to keep the table's own state;
+`onSortChange` can also observe that uncontrolled state. Set `key: undefined` to preserve
+input order. Import `TableSort` and `sortTableRows` from `@apliteni/apliteni-ui/react`.
+
+Changing the sort returns the table to its first page. The comparator uses JavaScript
+`<` and `>`; use consistently typed, comparable values in sortable columns. Ordering of
+mixed types, missing values and `NaN` is not guaranteed. `sortTableRows` always returns
+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

@@ -45,17 +45,81 @@ type Column<T> = {
     sortable?: boolean;
     render?: (row: T) => ReactNode;
 };
-type DataTableProps<T> = {
-    columns: Column<T>[];
-    rows: T[];
-    pageSize?: number;
+type TableSort<T> = {
+    key: (keyof T & string) | undefined;
+    dir: 1 | -1;
+};
+type SelectionProps = {
+    selectable: false;
+    selected?: Set<string>;
+    onToggle?: (name: string) => void;
+    onTogglePage?: (names: string[]) => void;
+} | {
+    selectable?: true;
     selected: Set<string>;
     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;
+    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;
+} | {
+    sort: TableSort<T>;
+    onSortChange: (sort: TableSort<T>) => void;
+});
+declare function sortTableRows<T>(rows: T[], sort: TableSort<T>): T[];
 declare function DataTable<T extends {
     name: string;
-}>({ columns, rows, pageSize, selected, onToggle, onTogglePage, }: 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. */
@@ -96,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 };
+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 };