@apliteni/apliteni-ui 0.26.0 → 0.30.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.30.0",
   "workspaces": [
     "react"
   ],

package/react/README.md

@@ -25,11 +25,36 @@ 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`, `Drawer`, `CommandPalette`, `Button`, `Badge`, `Card`, `Icon`.
+
+`CommandPalette` renders the kit's `commandPalette()` markup, class for class, and imports the
+kit's ranking rather than repeating it — so a palette a server rendered and the same palette
+after a keystroke put the same row first. Three differences from the vanilla one. Two are
+because a React host already owns the state the wiring would: it has no Cmd+K binding, since
+`open` is the host's prop to set from whatever key it wants; and a destructive row names an
+`onConfirm` callback rather than the id of a confirm dialog, which is refused the same way — a
+`danger` row with neither renders disabled. `rank={false}` hands the query back through
+`onQueryChange` for a palette a server feeds.
+
+The third is not a design decision and is going: **one Escape closes a `Modal` and the palette
+under it.** The React palette and the React `Modal` each register their own listener on the
+document, and `inert` does not stop a document listener, so the question and the surface it was
+asked about close together. The vanilla pair does not do this — every kit overlay is on one
+stack there, and Escape closes the top one only. The React half joins that shared dialog stack
+when this branch is rebased onto the drawer branch, which is where `dialog.ts` lands; until then,
+open a `Modal` from a palette row knowing both will close.
+
+`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
 
@@ -39,6 +64,37 @@ controls, disabled controls, controls inside a closed disclosure and elements wi
 negative tabindex are skipped. Tab and Shift+Tab wrap at the ends of the same list.
 Escape and a click on the scrim dismiss the dialog and return focus to its opener.
 
+The Modal fades in and out: the scrim fades and the panel rises a few pixels. After `open`
+turns false it stays mounted until that transition ends, then unmounts. While it leaves,
+focus is already back on the opener and the dialog takes no clicks.
+
+## Drawer
+
+A panel that slides in from an edge of the screen over a scrim. It renders the vanilla
+`drawer()` markup, class for class, so it looks and moves like the kit's drawer, and like
+`Pagination` its styles come from `@apliteni/apliteni-ui/css` rather than from this bundle.
+Group what goes inside it the way `drawerSection()` does — a heading over a `<dl>` of label
+and value rows — rather than in cards; the rules are on Guidelines / Drawers.
+
+```tsx
+<Drawer open={open} title="Transaction" onClose={() => setOpen(false)}
+  side="right" size="md" footer={<Button onClick={save}>Save</Button>}>
+  …
+</Drawer>
+```
+
+`side` is `right` (default), `left`, `top` or `bottom`. `size` is `sm`, `md` (default) or
+`lg`, measured along the slide. `closeLabel` names the close button (default "Close").
+Focus, Escape, the scrim, Tab and the return of focus behave as the Modal's do. Like the
+Modal, it stays mounted until its exit slide ends. It is portalled to `document.body`.
+
+React Modals, Drawers and CommandPalettes share one stack. When one is open over another,
+only the top one takes Escape and Tab, and closing it hands focus back to the one below —
+so a destructive palette row that opens a Modal takes one Escape to answer, not one that
+closes both. The vanilla `drawer()`, `confirm()` and `commandPalette()` keep a separate
+stack that this one cannot see, so do not open a React dialog and a vanilla overlay over
+each other on the same page.
+
 ## Work on them
 
 From the repo root — one `npm install` covers the workspace:
@@ -93,3 +149,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

@@ -25,7 +25,12 @@
   backdrop-filter: blur(2px);
   display: grid;
   place-items: center;
-  z-index: 50;
+  z-index: calc(var(--z-overlay) + 1);
+  opacity: 0;
+  transition: opacity var(--dur-med) var(--ease);
+}
+.rx-scrim.is-open {
+  opacity: 1;
 }
 .rx-modal {
   width: min(480px, 92vw);
@@ -34,6 +39,11 @@
   border-radius: var(--radius-xl);
   box-shadow: var(--shadow-lg);
   overflow: hidden;
+  transform: translateY(8px);
+  transition: transform var(--dur-med) var(--ease);
+}
+.rx-scrim.is-open .rx-modal {
+  transform: none;
 }
 .rx-modal__head {
   display: flex;
@@ -80,15 +90,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

@@ -23,9 +23,11 @@ declare function Badge({ variant, children }: {
     children: ReactNode;
 }): react.JSX.Element;
 
-declare function Card({ title, sub, children }: {
+type Level = 2 | 3 | 4 | 5 | 6;
+declare function Card({ title, sub, level, children }: {
     title?: ReactNode;
     sub?: ReactNode;
+    level?: Level;
     children?: ReactNode;
 }): react.JSX.Element;
 
@@ -38,6 +40,63 @@ type ModalProps = {
 };
 declare function Modal({ open, title, onClose, footer, children }: ModalProps): react.ReactPortal | null;
 
+type DrawerProps = {
+    open: boolean;
+    title: string;
+    onClose: () => void;
+    side?: 'right' | 'left' | 'top' | 'bottom';
+    size?: 'sm' | 'md' | 'lg';
+    footer?: ReactNode;
+    children?: ReactNode;
+    closeLabel?: string;
+};
+declare function Drawer({ open, title, onClose, side, size, footer, children, closeLabel, }: DrawerProps): react.ReactPortal | null;
+
+type CommandItem = {
+    id: string;
+    label: string;
+    description?: string;
+    icon?: string;
+    /** Aliases a reader might type instead of the label. */
+    keywords?: string[];
+    /** Drawn as <kbd>, never read out: the row already says what it does. */
+    shortcut?: string | string[];
+    badge?: string;
+    /** A row that goes somewhere. Cmd or Ctrl held on Enter opens it in a tab. */
+    href?: string;
+    /** A row that destroys something. It must carry `onConfirm`, or it is disabled. */
+    danger?: boolean;
+    /** What a destructive row opens instead of running. */
+    onConfirm?: () => void;
+    disabled?: boolean;
+};
+type CommandGroup = {
+    label?: string;
+    items: CommandItem[];
+};
+type CommandPaletteProps = {
+    open: boolean;
+    onClose: () => void;
+    groups: CommandGroup[];
+    /** What the reader chose. `newTab` is Cmd or Ctrl held, for a row with an href. */
+    onSelect?: (item: CommandItem, meta: {
+        newTab: boolean;
+    }) => void;
+    label?: string;
+    placeholder?: string;
+    empty?: string;
+    density?: 'compact' | 'roomy';
+    hint?: boolean;
+    /**
+     * false → the caller ranks. `groups` is rendered in the order it is given and
+     * `onQueryChange` is where the query goes — the shape a palette fed by a
+     * server takes, where the rest of the results are not on this page to rank.
+     */
+    rank?: boolean;
+    onQueryChange?: (query: string) => void;
+};
+declare function CommandPalette({ open, onClose, groups, onSelect, label, placeholder, empty, density, hint, rank, onQueryChange, }: CommandPaletteProps): react.ReactPortal | null;
+
 type Column<T> = {
     key: keyof T & string;
     label: string;
@@ -60,11 +119,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 +161,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 +219,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, type CommandGroup, type CommandItem, CommandPalette, type CommandPaletteProps, DEFAULT_PAGE_SIZE, DataTable, type DataTableProps, Denied, type DeniedProps, Drawer, type DrawerProps, Icon, Modal, type ModalProps, PAGE_SIZES, Pagination, type PaginationProps, Skeleton, type SkeletonProps, SkeletonTable, type SkeletonTableProps, type TableSort, sortTableRows };