@tristan2828/ui-foundation 4.34.0 → 4.36.0

package/conventions/docs/design-language.md

@@ -3,19 +3,20 @@
 <!-- index: written by `npm run docs:index` in the package from the headings below; never edit it by hand -->
 ## Index
 
-- [Semantic tones](#semantic-tones) · lines 28–56
-- [The three badge styles](#the-three-badge-styles) · lines 58–75
-- [Mapping an enum to tones](#mapping-an-enum-to-tones) · lines 77–106
-- [Glyphs and icons: 3:1](#glyphs-and-icons-31) · lines 108–121
-- [Logos and brand marks](#logos-and-brand-marks) · lines 123–167
-- [Categorical colour](#categorical-colour) · lines 169–239
-- [Typography](#typography) · lines 241–323
-  - [Written text (notes)](#written-text-notes) · lines 272–323
-- [Density](#density) · lines 325–382
-- [Widget cards (hub pages)](#widget-cards-hub-pages) · lines 384–459
-- [Module cards (a hub's places)](#module-cards-a-hubs-places) · lines 461–519
-- [Notices](#notices) · lines 521–549
-- [A value over time](#a-value-over-time) · lines 551–584
+- [Semantic tones](#semantic-tones) · lines 29–57
+- [The three badge styles](#the-three-badge-styles) · lines 59–76
+- [Mapping an enum to tones](#mapping-an-enum-to-tones) · lines 78–107
+- [Glyphs and icons: 3:1](#glyphs-and-icons-31) · lines 109–122
+- [Logos and brand marks](#logos-and-brand-marks) · lines 124–168
+- [Categorical colour](#categorical-colour) · lines 170–240
+- [Typography](#typography) · lines 242–324
+  - [Written text (notes)](#written-text-notes) · lines 273–324
+- [Density](#density) · lines 326–383
+- [Widget cards (hub pages)](#widget-cards-hub-pages) · lines 385–460
+- [Module cards (a hub's places)](#module-cards-a-hubs-places) · lines 462–520
+- [Notices](#notices) · lines 522–550
+- [A value over time](#a-value-over-time) · lines 552–585
+- [A list as a board](#a-list-as-a-board) · lines 587–638
 
 <!-- /index -->
 
@@ -582,3 +583,56 @@ or `'last'`) with its value.
   `formatX` the page uses for those values elsewhere.
 - One series and a few dozen points. Several series, zoom or tooltips
   are a request for the foundation, not a hand-drawn chart in the app.
+
+## A list as a board
+
+`Board` (4.36) shows a list as a column per value of one choice field (a
+status, a stage), a card per record, and moves a record by moving its
+card. It is a second view of a list, on its own page beside the
+`DataTable`, never a replacement: filters, sorting and saved views stay
+the table's.
+
+```tsx
+<Board
+  aria-label="Projects by stage"
+  columns={STAGES.map((stage) => ({ value: stage, name: STAGE_NAMES[stage], label: <StageLabel value={stage} />, count: totals[stage] }))}
+  items={projects}
+  getId={(project) => project.id}
+  getColumn={(project) => project.stage}
+  getName={(project) => project.name}
+  renderCard={(project) => <ProjectCard project={project} />}
+  onMove={(project, stage) => saves.get(project.id)?.({ stage })}
+  moveTo={[...STAGE_TARGETS, { value: 'archived', label: 'Archived' }]}
+  isLoading={isLoading}
+  error={error}
+  onRetry={refetch}
+  emptyTitle="No projects yet"
+/>
+```
+
+- **A card moves two ways:** dragged to another column, and its Move
+  button, a menu of `moveTo` (the columns by default) for the keyboard
+  and a phone, where there is no drag. A value with no column (Archived,
+  Dropped) is only in the menu, and takes the card off the board. After
+  a move from the menu the focus is back on the card's Move button in
+  its new column (on the board, if the card left it), and a status line
+  tells a screen reader "Moved <name> to <column>".
+- **A column has a name in words** for the menu and that line: its
+  `label` when that is a string, else give `name` (a label with a glyph
+  in it is not plain text). The columns are headings, h2 by default;
+  `headingLevel` puts them under a section's heading.
+- **Saving is the app's**, through `useRecordUpdate`, optimistic: cards
+  are placed by `getColumn` on the record, so a move shows at once and a
+  refusal puts the card back with the toast. Without `onMove` the board
+  is read-only, for a computed field.
+- **A column is its own query** when a list can outgrow one page: give
+  it `count` (the total) and a `footer` linking the table filtered to it
+  when it holds more than it shows.
+- **The card is short:** the title (a link to the record, cell pattern
+  16) and three or four values as glyphs, the same cells the table uses.
+  An empty value is left out, not shown as a dash.
+- It owns its states: skeleton columns, `ErrorState`, and an empty
+  board; an empty column is a muted line, not an empty state. The
+  columns share the width, at least 16rem each, and scroll sideways with
+  snap points; a phone shows one column at a time, with the edge of the
+  next one showing.

package/conventions/docs/reminders.md

@@ -13,8 +13,8 @@ to the device, where the app's service worker shows it.
 | `usePushPermission()` | the package | Whether this device gets reminders, and `enable`/`disable` |
 | `AllowReminders` | the package | The control: says what reminders are, then asks, on a click |
 | `/push/public-key`, `/push/subscriptions` | `openapi.yaml`, the foundation's part (optional) | The VAPID key to subscribe with; this device's subscription saved or dropped |
-| `app/push.py` | the reference backend | `send_push(session, user_id, title, body, url)`: encrypted (RFC 8291), signed (VAPID), to every device the user allowed |
-| `app/reminders.py`, `reminders` | the reference backend | A reminder row (when, which days, the text, the path), and the `send-reminders` job that sends each one when it's due |
+| `foundation_backend.push` | `ui-foundation-backend` | `send_push(session, user_id, title, body, url)`: encrypted (RFC 8291), signed (VAPID), to every device the user allowed |
+| `foundation_backend.reminders`, `reminders` | `ui-foundation-backend` | A reminder row (when, which days, the text, the path), and the `send-reminders` job that sends each one when it's due |
 
 Off until the backend turns it on (`PUSH_ENABLED`, `docs/deploy.md`
 "Reminders (Web Push)"). An app without reminders leaves `/push/*` out of
@@ -82,4 +82,4 @@ reads `mock` and never subscribes: screens show the `mock` state, and a
 Playwright spec checks it the same way. The rest is the backend's: its
 tests decrypt every message as a browser would. To try it end to end, run
 the real backend with push on, allow reminders in the browser, then
-`backend/scripts/send_test_push.py <email>`.
+`python -m foundation_backend.scripts.send_test_push <email>` (from `backend/`).

package/dist/components/app/board.d.ts

@@ -0,0 +1,50 @@
+import { type ReactNode } from 'react';
+import type { AppError } from '../../api/contracts.js';
+export type BoardColumn<V extends string> = {
+    /** The field's value this column holds. */
+    value: V;
+    /** The column's heading: a word, or a glyph and a word. */
+    label: ReactNode;
+    /**
+     * The column's name as plain text: its entry in the default Move menu and
+     * in what a screen reader hears after a move. Omitted: `label` when it is
+     * a string, else `value`.
+     */
+    name?: string;
+    /** The column's total, beside its heading. Omitted: the cards on the board are counted. */
+    count?: number;
+    /** The line an empty column shows. Default "Nothing here". */
+    empty?: ReactNode;
+    /** Under the cards: "Showing 100 of 240", a link to the whole list. */
+    footer?: ReactNode;
+};
+/** A value a card can be moved to from its Move menu. */
+export type BoardMoveTarget<V extends string> = {
+    value: V;
+    label: string;
+};
+export type BoardProps<T, V extends string> = {
+    /** Names the board as a whole ("Tasks by status"). */
+    'aria-label': string;
+    columns: readonly BoardColumn<V>[];
+    items: readonly T[];
+    getId: (item: T) => string | number;
+    /** The record's value of the field: which column its card is in. */
+    getColumn: (item: T) => V;
+    /** What the Move button calls the record: "Move <name>". */
+    getName: (item: T) => string;
+    renderCard: (item: T) => ReactNode;
+    /** Saves the record's new value. Omitted: a read-only board. */
+    onMove?: (item: T, value: V) => void;
+    /** The Move menu's choices. Default: the columns, by their `name`. */
+    moveTo?: readonly BoardMoveTarget<V>[];
+    /** The columns' heading level: 2 under the page's h1 (the default), deeper under a section. */
+    headingLevel?: 2 | 3 | 4 | 5 | 6;
+    isLoading?: boolean;
+    error?: AppError | null;
+    onRetry?: () => void;
+    emptyTitle?: ReactNode;
+    emptyDescription?: ReactNode;
+    emptyAction?: ReactNode;
+};
+export declare function Board<T, V extends string>({ 'aria-label': ariaLabel, columns, items, getId, getColumn, getName, renderCard, onMove, moveTo, headingLevel, isLoading, error, onRetry, emptyTitle, emptyDescription, emptyAction, }: BoardProps<T, V>): import("react").JSX.Element;

package/dist/components/app/board.js

@@ -0,0 +1,131 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// A board: a column per value of one choice field (a status, a stage), a
+// card per record, and a record moved by moving its card. A second way to
+// look at a list, beside its DataTable, never instead of it: filters, sort
+// and saved views stay the table's.
+//
+// - Columns: `columns`, in order, each a `value` with its `label` (a stage
+//   circle and a word, say), an optional `count` (the column's total,
+//   which may be more than the cards loaded), an `empty` line, and a
+//   `footer` ("Showing 100 of 240", a link to the filtered list). A
+//   column whose `label` isn't plain text gives its `name` for the Move
+//   menu and what a screen reader hears after a move.
+// - Cards: every record in `items` whose `getColumn` is one of the
+//   columns' values, in `items`' order; a record whose value has no column
+//   isn't shown. `renderCard` is the card's content: the title (a link to
+//   the record's page) and a few values.
+// - Moving: with `onMove`, a card drags to another column (a pointer) and
+//   has a Move button (a menu of `moveTo`, by default the columns: the
+//   keyboard and a phone, where there is no drag). `moveTo` may add values
+//   with no column, such as Dropped, which take the card off the board.
+//   After a move from the menu the focus goes back to the card's Move
+//   button in its new column (to the board, if the card left it), and a
+//   status line says where the card went.
+//   Without `onMove` the board is read-only: a computed field.
+//   `onMove(item, value)` is the save; the app makes it optimistic
+//   (useRecordUpdate), so placing cards by `getColumn` on the record shows
+//   a move at once, and a refusal puts the card back.
+// - States: `isLoading` (skeleton columns), `error` (ErrorState with
+//   `onRetry`), and an empty board (`emptyTitle`, `emptyDescription`,
+//   `emptyAction`), each for the board as a whole; an empty column is not
+//   an empty state, only a muted line.
+//
+// Columns share the width, at least 16rem each, and scroll sideways with
+// snap points when they don't fit. A phone shows one column at a time,
+// with the edge of the next one showing.
+import { useEffect, useId, useRef, useState } from 'react';
+import { ArrowRightLeftIcon } from 'lucide-react';
+import { cn } from 'cn';
+import { ErrorState } from './error-state.js';
+import { Button } from '../ui/button.js';
+import { Card } from '../ui/card.js';
+import { DropdownMenu, DropdownMenuContent, DropdownMenuGroup, DropdownMenuLabel, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuTrigger, } from '../ui/dropdown-menu.js';
+import { Empty, EmptyContent, EmptyDescription, EmptyHeader, EmptyTitle } from '../ui/empty.js';
+import { Skeleton } from '../ui/skeleton.js';
+// The drag's data type: a card of this board, and nothing a drop from
+// elsewhere (a file, a link) carries.
+const DRAG_TYPE = 'application/x-ui-foundation-board-card';
+// At least 16rem, sharing the width; on a phone the board's width less 2rem,
+// so the next column's edge shows there is more to scroll to.
+const COLUMN_WIDTH = 'min-w-[calc(100%-2rem)] flex-1 basis-0 sm:min-w-64';
+const columnName = (column) => column.name ?? (typeof column.label === 'string' ? column.label : column.value);
+export function Board({ 'aria-label': ariaLabel, columns, items, getId, getColumn, getName, renderCard, onMove, moveTo, headingLevel = 2, isLoading = false, error = null, onRetry, emptyTitle = 'Nothing here yet', emptyDescription, emptyAction, }) {
+    const boardRef = useRef(null);
+    const [announcement, setAnnouncement] = useState('');
+    // A move from the Move menu, until its card is in its new column or off
+    // the board. The card is remounted there, so the Move button that had
+    // the focus is gone: its new one takes the focus, or the board does.
+    const moved = useRef(null);
+    useEffect(() => {
+        const pending = moved.current;
+        if (pending === null)
+            return;
+        const item = items.find((candidate) => String(getId(candidate)) === pending.id);
+        if (item !== undefined && getColumn(item) !== pending.value)
+            return;
+        moved.current = null;
+        const board = boardRef.current;
+        // Only when the focus was lost with the old button, never taken from
+        // wherever the user has gone since.
+        if (board === null || (document.activeElement !== null && document.activeElement !== document.body))
+            return;
+        const button = Array.from(board.querySelectorAll('[data-board-move]')).find((candidate) => candidate.dataset.boardMove === pending.id);
+        (button ?? board).focus();
+    }, [items, getId, getColumn]);
+    if (error) {
+        return (_jsx("div", { "data-slot": "board", "data-state": "error", children: _jsx(ErrorState, { error: error, onRetry: onRetry }) }));
+    }
+    if (isLoading) {
+        return (_jsx("div", { "data-slot": "board", "data-state": "loading", role: "group", "aria-busy": "true", "aria-label": ariaLabel, className: "flex gap-3 overflow-x-auto pb-2", children: columns.map((column) => (_jsxs("div", { className: cn('flex flex-col gap-2 rounded-lg bg-muted p-2', COLUMN_WIDTH), children: [_jsx(Skeleton, { className: "h-5 w-24" }), _jsx(Skeleton, { className: "h-20 w-full" }), _jsx(Skeleton, { className: "h-20 w-full" })] }, column.value))) }));
+    }
+    const shown = items.filter((item) => columns.some((column) => column.value === getColumn(item)));
+    if (shown.length === 0) {
+        return (_jsx("div", { "data-slot": "board", "data-state": "empty", children: _jsxs(Empty, { children: [_jsxs(EmptyHeader, { children: [_jsx(EmptyTitle, { children: emptyTitle }), emptyDescription && _jsx(EmptyDescription, { children: emptyDescription })] }), emptyAction && _jsx(EmptyContent, { children: emptyAction })] }) }));
+    }
+    const targets = moveTo ?? columns.map((column) => ({ value: column.value, label: columnName(column) }));
+    const move = (id, value, from) => {
+        const item = items.find((candidate) => String(getId(candidate)) === id);
+        if (onMove === undefined || item === undefined || getColumn(item) === value)
+            return;
+        const column = columns.find((candidate) => candidate.value === value);
+        const where = targets.find((target) => target.value === value)?.label ?? (column ? columnName(column) : value);
+        setAnnouncement(`Moved ${getName(item)} to ${where}`);
+        if (from === 'menu')
+            moved.current = { id, value };
+        onMove(item, value);
+    };
+    return (_jsxs("div", { ref: boardRef, "data-slot": "board", "data-state": "success", role: "group", "aria-label": ariaLabel, tabIndex: -1, className: "flex snap-x snap-mandatory gap-3 overflow-x-auto pb-2 outline-none", children: [columns.map((column) => {
+                const cards = shown.filter((item) => getColumn(item) === column.value);
+                return (_jsxs(BoardColumnView, { column: column, count: column.count ?? cards.length, headingLevel: headingLevel, onDrop: onMove ? (id) => move(id, column.value, 'drag') : undefined, children: [cards.map((item) => (_jsx(Card, { size: "sm", "data-slot": "board-card", draggable: onMove ? true : undefined, onDragStart: onMove
+                                ? (event) => {
+                                    event.dataTransfer.setData(DRAG_TYPE, String(getId(item)));
+                                    event.dataTransfer.effectAllowed = 'move';
+                                }
+                                : undefined, className: cn('gap-2 px-3 py-3', onMove && 'cursor-grab active:cursor-grabbing'), children: _jsxs("div", { className: "flex items-start gap-2", children: [_jsx("div", { className: "flex min-w-0 flex-1 flex-col gap-2", children: renderCard(item) }), onMove && (_jsx(MoveMenu, { id: String(getId(item)), name: getName(item), value: getColumn(item), targets: targets, onMove: (value) => move(String(getId(item)), value, 'menu') }))] }) }, getId(item)))), cards.length === 0 && (_jsx("p", { className: "px-1 py-6 text-center type-caption text-muted-foreground", children: column.empty ?? 'Nothing here' })), column.footer && _jsx("div", { className: "px-1 type-caption text-muted-foreground", children: column.footer })] }, column.value));
+            }), _jsx("span", { role: "status", className: "sr-only", children: announcement })] }));
+}
+function BoardColumnView({ column, count, headingLevel, onDrop, children, }) {
+    const [over, setOver] = useState(false);
+    const headingId = useId();
+    const Heading = `h${headingLevel}`;
+    const accepts = (event) => onDrop !== undefined && event.dataTransfer.types.includes(DRAG_TYPE);
+    return (_jsxs("section", { "aria-labelledby": headingId, "data-slot": "board-column", "data-over": over || undefined, className: cn('flex snap-start flex-col gap-2 rounded-lg bg-muted p-2 outline-2 outline-offset-2 outline-transparent data-over:outline-ring', COLUMN_WIDTH), onDragOver: (event) => {
+            if (!accepts(event))
+                return;
+            event.preventDefault();
+            event.dataTransfer.dropEffect = 'move';
+            setOver(true);
+        }, onDragLeave: (event) => {
+            if (!event.currentTarget.contains(event.relatedTarget))
+                setOver(false);
+        }, onDrop: (event) => {
+            setOver(false);
+            if (!accepts(event))
+                return;
+            event.preventDefault();
+            onDrop?.(event.dataTransfer.getData(DRAG_TYPE));
+        }, children: [_jsxs(Heading, { id: headingId, className: "flex items-center gap-2 px-1 pt-0.5 type-label", children: [column.label, _jsx("span", { className: "font-normal tabular-nums text-muted-foreground", children: count })] }), children] }));
+}
+function MoveMenu({ id, name, value, targets, onMove, }) {
+    return (_jsxs(DropdownMenu, { children: [_jsx(DropdownMenuTrigger, { render: _jsx(Button, { variant: "ghost", size: "icon-xs", "aria-label": `Move ${name}`, title: "Move to\u2026", "data-board-move": id }), children: _jsx(ArrowRightLeftIcon, { "aria-hidden": "true" }) }), _jsx(DropdownMenuContent, { align: "end", className: "w-44", children: _jsxs(DropdownMenuGroup, { children: [_jsx(DropdownMenuLabel, { children: "Move to" }), _jsx(DropdownMenuRadioGroup, { value: value, onValueChange: (next) => onMove(next), children: targets.map((target) => (_jsx(DropdownMenuRadioItem, { value: target.value, closeOnClick: true, children: target.label }, target.value))) })] }) })] }));
+}

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 export { AppShell, type AppShellProps, type AppShellVersion, type BottomBarItem, type NavEntry, type NavItem, type NavSection, } from './components/app/app-shell.js';
 export type { IconComponent } from './components/app/icon-component.js';
+export { Board, type BoardColumn, type BoardMoveTarget, type BoardProps } from './components/app/board.js';
 export { CountLink, type CountLinkProps } from './components/app/count-link.js';
 export { DataTable, type DataTableProps, type DataTableTotals, type DataTableWidth, type SortingState, } from './components/app/data-table.js';
 export { type RowGroup } from './components/app/table-groups.js';

package/dist/index.js

@@ -4,6 +4,7 @@
 // points (`/gateway`, `/mocks`, `/testing`) so each stays behind its boundary.
 // Composites
 export { AppShell, } from './components/app/app-shell.js';
+export { Board } from './components/app/board.js';
 export { CountLink } from './components/app/count-link.js';
 export { DataTable, } from './components/app/data-table.js';
 export {} from './components/app/table-groups.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tristan2828/ui-foundation",
-  "version": "4.34.0",
+  "version": "4.36.0",
   "description": "Shared UI foundation for contract-first, database-backed React apps: shadcn primitives, DataTable/EntityForm composites, auth, the gateway error seam, design tokens, lint rules and the AI playbook.",
   "license": "MIT",
   "repository": {