@tristan2828/ui-foundation 4.41.0 → 4.43.0

package/README.md

@@ -22,7 +22,7 @@ than installing this by hand:
 | `@tristan2828/ui-foundation/ui/<name>` | shadcn primitives: badge, button, calendar, card, checkbox, combobox, dialog, empty, field, input, input-group, label, popover, select, separator, sheet, sidebar, skeleton, sonner, spinner, switch, table, textarea, tooltip |
 | `@tristan2828/ui-foundation/gateway` | `safeFetch`, `toAppError`, `networkError` — for an app's `src/api/gateway/` only |
 | `@tristan2828/ui-foundation/mocks` | MSW: `authHandlers`, `environmentHandlers`, `resetMockAuth`, `getMockCurrentUser`, `MOCK_USER`, `exposeMswForE2E` |
-| `@tristan2828/ui-foundation/testing` | Playwright: `defineA11ySuite`, `defineMockModeBannerSuite`, `defineDataEnvironmentBannerSuite`, `forceMswOverride`, `forceLoggedOut`, `waitForMswReady`, `expectDataViewsLoaded` |
+| `@tristan2828/ui-foundation/testing` | Playwright: `test` and `expect` (a page whose `goto()`/`reload()` wait for the app's boot; `withBootWait` for a page of your own), `defineA11ySuite`, `defineMockModeBannerSuite`, `defineDataEnvironmentBannerSuite`, `forceMswOverride`, `forceLoggedOut`, `waitForMswReady`, `expectDataViewsLoaded` |
 | `@tristan2828/ui-foundation/eslint` | the lint rules, as a flat config: `export default [...uiFoundation()]` |
 | `@tristan2828/ui-foundation/styles.css` | tokens and base styles, after `@import "tailwindcss";` |
 | `@tristan2828/ui-foundation/openapi.yaml` | the part of an app's API contract the package calls: `/auth/*`, `/environment` (optional) and the error bodies |

package/conventions/docs/add-an-entity.md

@@ -4,7 +4,7 @@
 ## Index
 
 - [The reference files](#the-reference-files) · lines 37–59
-- [Before anything: the entity plan](#before-anything-the-entity-plan) · lines 61–702
+- [Before anything: the entity plan](#before-anything-the-entity-plan) · lines 61–706
   - Step 1: Add `<Entity>` to `openapi.yaml` · lines 99–106
   - Step 2: `npm run gen:api` · lines 107–108
   - Step 3: Add gateway tests in `tests/gateway/<entity>.test.ts`, derived from the spec · lines 109–120
@@ -12,13 +12,13 @@
   - Step 5: Add a gateway module in `src/api/gateway/<entity>.ts` · lines 131–135
   - Step 6: Copy the reference files, one for one, not just the two screens · lines 136–598
   - Step 7: Register routes · lines 599–609
-  - Step 8: Add Playwright specs for all three screens · lines 610–684
-  - Step 9: Register the nav entry and route names · lines 685–699
-  - Step 10: `npm run verify`. · lines 700–702
-- [What not to copy](#what-not-to-copy) · lines 704–730
-- [After a commit, in the backend](#after-a-commit-in-the-backend) · lines 732–749
-- [Deleting](#deleting) · lines 751–780
-- [Fields only a script writes](#fields-only-a-script-writes) · lines 782–803
+  - Step 8: Add Playwright specs for all three screens · lines 610–688
+  - Step 9: Register the nav entry and route names · lines 689–703
+  - Step 10: `npm run verify`. · lines 704–706
+- [What not to copy](#what-not-to-copy) · lines 708–734
+- [After a commit, in the backend](#after-a-commit-in-the-backend) · lines 736–753
+- [Deleting](#deleting) · lines 755–784
+- [Fields only a script writes](#fields-only-a-script-writes) · lines 786–807
 
 <!-- /index -->
 
@@ -612,7 +612,11 @@ is a filled-in example while the Widgets demo is still here).
    MSW overrides — `forceMswOverride`, `waitForMswReady` and the
    `window.__msw` handle from `@tristan2828/ui-foundation/testing`, and
    `e2e/widgets-table.spec.ts`/`e2e/widget-form.spec.ts`/
-   `e2e/widget-view.spec.ts` for the pattern. The view's states are
+   `e2e/widget-view.spec.ts` for the pattern. Import `test` and
+   `expect` from there too, not from `@playwright/test`: its page's
+   `goto()` and `reload()` return once the app has rendered (after MSW's
+   start), and load once more if the server refused one of its files,
+   so a spec's first expect never meets an empty page. The view's states are
    loading, not found (a 404: "Not found", the way back, no retry), error
    (a failed load, then Try again recovering) and success (every section,
    each value as its cell shows it), plus the sparse record showing its

package/conventions/docs/design-language.md

@@ -3,21 +3,23 @@
 <!-- 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 30–58
-- [The three badge styles](#the-three-badge-styles) · lines 60–77
-- [Mapping an enum to tones](#mapping-an-enum-to-tones) · lines 79–108
-- [Glyphs and icons: 3:1](#glyphs-and-icons-31) · lines 110–123
-- [Logos and brand marks](#logos-and-brand-marks) · lines 125–169
-- [Categorical colour](#categorical-colour) · lines 171–241
-- [Typography](#typography) · lines 243–325
-  - [Written text (notes)](#written-text-notes) · lines 274–325
-- [Density](#density) · lines 327–384
-- [Widget cards (hub pages)](#widget-cards-hub-pages) · lines 386–464
-- [Module cards (a hub's places)](#module-cards-a-hubs-places) · lines 466–524
-- [Notices](#notices) · lines 526–554
-- [A value over time](#a-value-over-time) · lines 556–589
-- [A list as a board](#a-list-as-a-board) · lines 591–642
-- [A list as cards](#a-list-as-cards) · lines 644–690
+- [Semantic tones](#semantic-tones) · lines 32–60
+- [The three badge styles](#the-three-badge-styles) · lines 62–79
+- [Mapping an enum to tones](#mapping-an-enum-to-tones) · lines 81–110
+- [Glyphs and icons: 3:1](#glyphs-and-icons-31) · lines 112–125
+- [Logos and brand marks](#logos-and-brand-marks) · lines 127–171
+- [Categorical colour](#categorical-colour) · lines 173–243
+- [Typography](#typography) · lines 245–327
+  - [Written text (notes)](#written-text-notes) · lines 276–327
+- [Density](#density) · lines 329–386
+- [Widget cards (hub pages)](#widget-cards-hub-pages) · lines 388–466
+- [Module cards (a hub's places)](#module-cards-a-hubs-places) · lines 468–526
+- [Notices](#notices) · lines 528–556
+- [A value over time](#a-value-over-time) · lines 558–591
+- [A list as a board](#a-list-as-a-board) · lines 593–644
+- [A list as cards](#a-list-as-cards) · lines 646–692
+- [Picking at random](#picking-at-random) · lines 694–725
+- [Filling in what's missing](#filling-in-whats-missing) · lines 727–777
 
 <!-- /index -->
 
@@ -688,3 +690,88 @@ const { layout, setLayout } = useTableLayout({
   dash. Never an action only one layout has.
 - `totals` and `highlightRow` are the table's alone. Sorting is the
   toolbar's in a card layout (there is no header to click).
+
+## Picking at random
+
+`SpinWheel` (4.42) picks one of a few candidates by chance, for "what do
+I do next?" when every one would do: a wheel of slices, a pointer at the
+top and a Spin button.
+
+```tsx
+const [picked, setPicked] = useState<SpinWheelItem | null>(null)
+
+<SpinWheel
+  aria-label="Ready tasks"
+  items={tasks.map((task) => ({ id: task.id, label: task.title, weight: task.priority, emphasis: task.flagged }))}
+  result={picked?.id ?? null}
+  onResult={setPicked}
+  emptyMessage="Nothing ready to pick from"
+/>
+```
+
+- **The candidates and their chances are the app's.** `weight` (> 0,
+  default 1) is both a slice's size and its chance, so a bigger slice
+  is visibly likelier. Keep it to what fits: a dozen or so; past that,
+  slices thin out and lose their labels (the full label is still each
+  slice's tooltip).
+- **The result is the app's too:** `onResult` when the wheel stops, and
+  `result` is the slice drawn picked at rest (a solid fill). Show what
+  was picked next to the wheel, with what to do about it (a link to the
+  record, Start); the wheel only points.
+- `emphasis` tints a slice (a flagged record). It doesn't change the
+  chance; give it a weight for that.
+- It spins a few turns with an ease-out and says "Picked <label>" to a
+  screen reader; with reduced motion it doesn't turn, the result is at
+  once. Square, the width of its container up to 28rem.
+
+## Filling in what's missing
+
+`FillInQueue` (4.42) walks a list of records that are each missing a
+value, one record at a time: a size for every project without one, a
+category for each unsorted purchase. It is a screen of its own for
+clearing a backlog of blanks, linked from the list ("12 without a
+size"); the list stays where a record is edited one field at a time.
+
+```tsx
+<FillInQueue
+  items={missing}
+  getKey={(project) => project.id}
+  progress={{ done: total - missing.length, total }}
+  canSave={(project) => drafts[project.id]?.size != null}
+  onSave={(project) => saveSize.mutateAsync({ id: project.id, size: drafts[project.id].size })}
+  renderItem={(project) => (
+    <>
+      <RecordHeading project={project} />
+      <FillInChoice
+        label="Size"
+        choices={SIZES}
+        value={drafts[project.id]?.size}
+        onChange={(size) => setDraft(project.id, { size })}
+        suggestion={project.guess ? { value: project.guess, note: 'from similar projects' } : undefined}
+        shortcut
+      />
+    </>
+  )}
+  loading={isLoading}
+  error={error}
+  onRetry={refetch}
+  empty="Every project has a size"
+/>
+```
+
+- **The app owns the list, the draft and the save.** `items` is the
+  query for records still missing the value, so a saved one leaves it
+  and the next takes its place; one still missing something after a
+  save is moved past. `progress` is the app's count. The draft is kept
+  per record, so Skip and back finds it as it was.
+- **A record is its heading, the few values to decide by, then its
+  fields:** a `FillInChoice` (a row of toggle buttons, one picked,
+  clicked again to clear) for a short choice, any input for the rest.
+  A guess is a `suggestion`: drawn dashed in the info tone and said
+  under the row, never picked for the person.
+- **Quick from the keyboard:** Enter is Save and next (not in a
+  textarea), and the one row marked `shortcut` takes the number keys.
+  After a move the focus is on the new record.
+- A refused save keeps the record and says why under the buttons, not
+  in a toast. It owns its states: skeletons, `ErrorState`, and the
+  empty queue, which is the good news ("Every project has a size").

package/dist/components/app/fill-in-queue-index.d.ts

@@ -0,0 +1,13 @@
+export type FillInKey = string | number;
+/**
+ * The index to show: the held key's, while it's in the list; else the
+ * place it was at (`lastIndex`), kept inside the list, which now holds the
+ * record after it. -1 for an empty list.
+ */
+export declare function resolveFillInIndex(keys: readonly FillInKey[], key: FillInKey | null, lastIndex: number): number;
+/**
+ * The key after `key`, wrapping to the first; `key` itself when it is the
+ * only one. When `key` isn't in the list, the one now at `lastIndex`.
+ * Null for an empty list.
+ */
+export declare function nextFillInKey(keys: readonly FillInKey[], key: FillInKey | null, lastIndex: number): FillInKey | null;

package/dist/components/app/fill-in-queue-index.js

@@ -0,0 +1,33 @@
+// Which record FillInQueue shows, as its `items` change under it. The
+// record is held by its key, not its place: saving one usually takes it out
+// of `items` (it isn't missing anything now), and the list may arrive after
+// the save resolves or before. Holding the key of the record to show next
+// makes both orders land on the same one.
+/**
+ * The index to show: the held key's, while it's in the list; else the
+ * place it was at (`lastIndex`), kept inside the list, which now holds the
+ * record after it. -1 for an empty list.
+ */
+export function resolveFillInIndex(keys, key, lastIndex) {
+    if (keys.length === 0)
+        return -1;
+    if (key !== null) {
+        const found = keys.indexOf(key);
+        if (found !== -1)
+            return found;
+    }
+    return Math.min(Math.max(lastIndex, 0), keys.length - 1);
+}
+/**
+ * The key after `key`, wrapping to the first; `key` itself when it is the
+ * only one. When `key` isn't in the list, the one now at `lastIndex`.
+ * Null for an empty list.
+ */
+export function nextFillInKey(keys, key, lastIndex) {
+    if (keys.length === 0)
+        return null;
+    const at = key === null ? -1 : keys.indexOf(key);
+    if (at === -1)
+        return keys[resolveFillInIndex(keys, null, lastIndex)];
+    return keys[(at + 1) % keys.length];
+}

package/dist/components/app/fill-in-queue.d.ts

@@ -0,0 +1,62 @@
+import { type ReactNode } from 'react';
+import type { AppError } from '../../api/contracts.js';
+export interface FillInQueueProgress {
+    /** Records filled so far. */
+    done: number;
+    /** Records in all, filled or not. */
+    total: number;
+    /** The word after the count: "12 of 160 <label>". Default "filled". */
+    label?: string;
+}
+export interface FillInQueueProps<T> {
+    /** The records still missing something, in order. */
+    items: readonly T[];
+    getKey: (item: T) => string | number;
+    /** One record: its heading and values, then its fields. */
+    renderItem: (item: T) => ReactNode;
+    /** Saves the app's draft for the record; the queue moves on when it resolves. A rejection keeps the record and shows its message. */
+    onSave: (item: T) => Promise<void> | void;
+    /** False disables Save and next (nothing picked yet); a function is asked about the record on screen. Default true. */
+    canSave?: boolean | ((item: T) => boolean);
+    /** Told when Skip moves past a record without saving. */
+    onSkip?: (item: T) => void;
+    /** A bar and "12 of 160 filled" at the top. The app counts. */
+    progress?: FillInQueueProgress;
+    /** Default "Save and next". */
+    saveLabel?: string;
+    /** Default "Skip". */
+    skipLabel?: string;
+    loading?: boolean;
+    /** An AppError (ErrorState, with `onRetry`), or the app's own message. */
+    error?: AppError | ReactNode;
+    onRetry?: () => void;
+    /** The empty queue's title. Default "Nothing left to fill in". */
+    empty?: ReactNode;
+    /** Shows the record at this index; the queue still moves on its own after a save or a skip and reports it. */
+    index?: number;
+    /** Told whenever another record is on screen, or the one on screen moves to another index. */
+    onIndexChange?: (index: number, item: T) => void;
+    className?: string;
+}
+export declare function FillInQueue<T>({ items, getKey, renderItem, onSave, canSave, onSkip, progress, saveLabel, skipLabel, loading, error, onRetry, empty, index: indexProp, onIndexChange, className, }: FillInQueueProps<T>): import("react").JSX.Element;
+export interface FillInChoiceProps<V extends string | number> {
+    /** Names the row of choices. */
+    label: string;
+    choices: readonly {
+        value: V;
+        label: ReactNode;
+    }[];
+    value: V | null | undefined;
+    /** The choice picked, or null when the picked one is clicked again. */
+    onChange: (value: V | null) => void;
+    /** A guess drawn dashed in the info tone, with "Suggested: <label> (<note>)" under the row. */
+    suggestion?: {
+        value: V;
+        note?: ReactNode;
+    };
+    /** The number keys pick in this row while the focus is in the queue (not in a text field). One row per queue. */
+    shortcut?: boolean;
+    className?: string;
+}
+/** One field of a FillInQueue record as a row of toggle buttons: one picked, or none. */
+export declare function FillInChoice<V extends string | number>({ label, choices, value, onChange, suggestion, shortcut, className, }: FillInChoiceProps<V>): import("react").JSX.Element;

package/dist/components/app/fill-in-queue.js

@@ -0,0 +1,229 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+// Fill in what a list of records is missing, one record at a time: a size
+// for every project without one, a category for each unsorted purchase.
+// A screen for clearing a backlog of blanks quickly, beside the list
+// (where the same fields stay editable one by one), never instead of it.
+//
+// - Records: `items` are the ones still missing something, in order, and
+//   `renderItem` draws one: its heading and a few values to decide by,
+//   then its fields (FillInChoice, or any input). The draft is the app's:
+//   it keeps what's picked for each record, and `canSave` says whether
+//   there's enough to save.
+// - Moving: "Save and next" calls `onSave(item)` (the app saves its draft)
+//   and, when it resolves, shows the next record. A saved record usually
+//   leaves `items`, so the one after it takes its place; if it stays (still
+//   missing something), the queue moves past it. Skip moves on without
+//   saving, wrapping from the last record to the first. After either, the
+//   focus is on the new record, for a screen reader and the keys below.
+// - Keys, while the focus is inside the queue: Enter (not in a textarea,
+//   not on a button) is Save and next; with one FillInChoice marked
+//   `shortcut`, the number keys pick its choices (not in a text field).
+// - Saving: the button shows it's pending; a refusal keeps the record and
+//   says why under the buttons, not in a toast.
+// - Progress: the app counts (`progress`): a bar and "12 of 160 filled".
+// - States: `loading` (skeletons), `error` (ErrorState, with `onRetry`),
+//   and an empty queue (`empty`, default "Nothing left to fill in").
+//
+// The record is a centred column, 40rem at most; the buttons sit under it,
+// Skip at the start and Save and next at the end.
+import { createContext, isValidElement, useCallback, useContext, useEffect, useId, useRef, useState, } from 'react';
+import { cn } from 'cn';
+import { ErrorState } from './error-state.js';
+import { nextFillInKey, resolveFillInIndex } from './fill-in-queue-index.js';
+import { Button } from '../ui/button.js';
+import { Empty, EmptyDescription, EmptyHeader, EmptyTitle } from '../ui/empty.js';
+import { Skeleton } from '../ui/skeleton.js';
+import { Spinner } from '../ui/spinner.js';
+import { Toggle } from '../ui/toggle.js';
+const ShortcutContext = createContext(null);
+const isAppError = (value) => typeof value === 'object' &&
+    value !== null &&
+    !isValidElement(value) &&
+    typeof value.kind === 'string' &&
+    typeof value.message === 'string';
+const messageOf = (reason) => {
+    if (typeof reason === 'string' && reason !== '')
+        return reason;
+    if (typeof reason === 'object' && reason !== null && typeof reason.message === 'string') {
+        const message = reason.message;
+        if (message !== '')
+            return message;
+    }
+    return "Couldn't save this record.";
+};
+const TEXT_INPUT_TYPES = new Set(['', 'text', 'search', 'email', 'url', 'tel', 'password', 'number', 'date', 'time', 'datetime-local', 'month', 'week']);
+// Where a key types into a field, so it's the field's, not the queue's.
+function isTextField(element) {
+    if (element.isContentEditable)
+        return true;
+    if (element instanceof HTMLTextAreaElement || element instanceof HTMLSelectElement)
+        return true;
+    if (element instanceof HTMLInputElement)
+        return TEXT_INPUT_TYPES.has(element.type);
+    return element.getAttribute('role') === 'combobox' || element.getAttribute('role') === 'textbox';
+}
+// Where Enter already does something of its own.
+function ownsEnter(element) {
+    if (element.isContentEditable || element instanceof HTMLTextAreaElement || element instanceof HTMLSelectElement)
+        return true;
+    return (element.closest('button, a[href], summary, [role=button], [role=link], [role=combobox], [role=listbox], [role=option], [role=menu], [role=menuitem], [role=menuitemradio], [role=menuitemcheckbox], [role=switch], [role=checkbox], [role=radio], [role=tab]') !== null);
+}
+export function FillInQueue({ items, getKey, renderItem, onSave, canSave = true, onSkip, progress, saveLabel = 'Save and next', skipLabel = 'Skip', loading = false, error, onRetry, empty = 'Nothing left to fill in', index: indexProp, onIndexChange, className, }) {
+    const keys = items.map(getKey);
+    const [held, setHeld] = useState(() => ({
+        key: indexProp !== undefined ? (keys[indexProp] ?? null) : null,
+        index: indexProp ?? 0,
+    }));
+    const index = resolveFillInIndex(keys, held.key, held.index);
+    const current = index === -1 ? undefined : items[index];
+    const currentKey = index === -1 ? null : keys[index];
+    const savable = current !== undefined && (typeof canSave === 'function' ? canSave(current) : canSave);
+    const [saving, setSaving] = useState(false);
+    const [saveError, setSaveError] = useState(null);
+    const [moves, setMoves] = useState(0);
+    const rootRef = useRef(null);
+    const recordRef = useRef(null);
+    const latest = useRef({ keys, index, items });
+    useEffect(() => {
+        latest.current = { keys, index, items };
+    });
+    // Re-pin the hold to the record on screen once the one held has left
+    // (adjusting state while rendering, so nothing draws the old one).
+    if (index !== -1 && (held.key !== currentKey || held.index !== index))
+        setHeld({ key: currentKey, index });
+    // The app moving the queue to an index.
+    const appliedIndex = useRef(indexProp);
+    useEffect(() => {
+        if (indexProp === undefined || indexProp === appliedIndex.current)
+            return;
+        appliedIndex.current = indexProp;
+        const { keys: now } = latest.current;
+        if (indexProp >= 0 && indexProp < now.length)
+            setHeld({ key: now[indexProp], index: indexProp });
+    }, [indexProp]);
+    const reported = useRef({ index, key: currentKey });
+    const onIndexChangeRef = useRef(onIndexChange);
+    useEffect(() => {
+        onIndexChangeRef.current = onIndexChange;
+    });
+    useEffect(() => {
+        if (index === reported.current.index && currentKey === reported.current.key)
+            return;
+        reported.current = { index, key: currentKey };
+        appliedIndex.current = index;
+        const item = latest.current.items[index];
+        if (index !== -1 && item !== undefined)
+            onIndexChangeRef.current?.(index, item);
+    }, [index, currentKey]);
+    // After a move, the focus goes to the record now on screen (to the queue
+    // when none is left).
+    const focusPending = useRef(false);
+    useEffect(() => {
+        if (!focusPending.current)
+            return;
+        focusPending.current = false;
+        (recordRef.current ?? rootRef.current)?.focus();
+    }, [moves]);
+    const moveOn = useCallback((from) => {
+        const { keys: now, index: at } = latest.current;
+        const next = nextFillInKey(now, from, at);
+        setHeld({ key: next, index: next === null ? at : now.indexOf(next) });
+        setSaveError(null);
+        focusPending.current = true;
+        setMoves((count) => count + 1);
+    }, []);
+    const save = async () => {
+        if (saving || !savable || current === undefined || currentKey === null)
+            return;
+        setSaving(true);
+        setSaveError(null);
+        try {
+            await onSave(current);
+        }
+        catch (reason) {
+            setSaving(false);
+            setSaveError(messageOf(reason));
+            return;
+        }
+        setSaving(false);
+        moveOn(currentKey);
+    };
+    const skip = () => {
+        if (saving || current === undefined || currentKey === null)
+            return;
+        onSkip?.(current);
+        moveOn(currentKey);
+    };
+    const shortcuts = useRef(new Set());
+    const register = useCallback((handler) => {
+        shortcuts.current.add(handler);
+        return () => {
+            shortcuts.current.delete(handler);
+        };
+    }, []);
+    const onKeyDown = (event) => {
+        if (event.defaultPrevented || event.altKey || event.ctrlKey || event.metaKey || event.nativeEvent.isComposing)
+            return;
+        const target = event.target;
+        if (event.key === 'Enter' && !event.shiftKey) {
+            if (ownsEnter(target))
+                return;
+            event.preventDefault();
+            void save();
+            return;
+        }
+        if (/^[1-9]$/.test(event.key) && !event.shiftKey && !isTextField(target)) {
+            for (const handler of shortcuts.current) {
+                if (handler(Number(event.key))) {
+                    event.preventDefault();
+                    return;
+                }
+            }
+        }
+    };
+    const progressBar = progress && _jsx(ProgressLine, { progress: progress });
+    if (error !== undefined && error !== null && error !== false) {
+        return (_jsx("div", { "data-slot": "fill-in-queue", "data-state": "error", className: className, children: isAppError(error) ? (_jsx(ErrorState, { error: error, onRetry: onRetry })) : (_jsxs(Empty, { "data-state": "error", children: [_jsxs(EmptyHeader, { children: [_jsx(EmptyTitle, { children: "Something went wrong" }), _jsx(EmptyDescription, { children: error })] }), onRetry && (_jsx(Button, { size: "sm", variant: "outline", onClick: onRetry, children: "Try again" }))] })) }));
+    }
+    if (loading) {
+        return (_jsxs("div", { "data-slot": "fill-in-queue", "data-state": "loading", "aria-busy": "true", className: cn('flex flex-col gap-6', className), children: [_jsxs("div", { className: "flex flex-col gap-2", children: [_jsx(Skeleton, { className: "h-2 w-full" }), _jsx(Skeleton, { className: "h-4 w-40" })] }), _jsxs("div", { className: "mx-auto flex w-full max-w-[40rem] flex-col gap-4", children: [_jsx(Skeleton, { className: "h-6 w-2/3" }), _jsx(Skeleton, { className: "h-4 w-1/2" }), _jsx(Skeleton, { className: "h-9 w-full" }), _jsx(Skeleton, { className: "h-9 w-full" })] })] }));
+    }
+    if (current === undefined) {
+        return (_jsxs("div", { ref: rootRef, tabIndex: -1, "data-slot": "fill-in-queue", "data-state": "empty", className: cn('flex flex-col gap-6 outline-none', className), children: [progressBar, _jsx(Empty, { children: _jsx(EmptyHeader, { children: _jsx(EmptyTitle, { children: empty }) }) })] }));
+    }
+    const position = `Record ${index + 1} of ${items.length}`;
+    return (_jsx(ShortcutContext.Provider, { value: register, children: _jsxs("div", { ref: rootRef, tabIndex: -1, "data-slot": "fill-in-queue", "data-state": "success", onKeyDown: onKeyDown, className: cn('flex flex-col gap-6 outline-none', className), children: [_jsxs("div", { className: "flex flex-col gap-2", children: [progressBar, _jsx("p", { className: "type-caption text-muted-foreground tabular-nums", "data-slot": "fill-in-queue-position", children: position })] }), _jsxs("div", { className: "mx-auto flex w-full max-w-[40rem] flex-col gap-6", children: [_jsx("div", { ref: recordRef, role: "group", "aria-label": position, tabIndex: -1, "data-slot": "fill-in-queue-record", className: "flex flex-col gap-6 rounded-lg outline-none focus-visible:ring-[3px] focus-visible:ring-ring/50", children: renderItem(current) }, currentKey ?? undefined), _jsxs("div", { className: "flex flex-col gap-2 border-t border-border pt-4", children: [_jsxs("div", { className: "flex items-center justify-between gap-3", children: [_jsx(Button, { variant: "ghost", onClick: skip, disabled: saving, children: skipLabel }), _jsxs(Button, { onClick: () => void save(), disabled: !savable || saving, "aria-busy": saving || undefined, children: [saving && _jsx(Spinner, { "aria-hidden": "true", role: "presentation", "aria-label": undefined, "data-icon": "inline-start" }), saveLabel] })] }), saveError !== null && (_jsx("p", { role: "alert", className: "text-end type-caption text-destructive-text", children: saveError }))] })] })] }) }));
+}
+function ProgressLine({ progress }) {
+    const { done, total, label = 'filled' } = progress;
+    const share = total > 0 ? Math.min(Math.max(done / total, 0), 1) : 0;
+    const text = `${done} of ${total} ${label}`;
+    return (_jsxs("div", { className: "flex flex-col gap-1.5", "data-slot": "fill-in-queue-progress", children: [_jsx("div", { role: "progressbar", "aria-label": "Progress", "aria-valuemin": 0, "aria-valuemax": total, "aria-valuenow": done, "aria-valuetext": text, className: "h-2 w-full overflow-hidden rounded-full bg-muted", children: _jsx("div", { className: "h-full rounded-full bg-primary transition-[width]", style: { width: `${share * 100}%` } }) }), _jsx("p", { className: "type-caption text-muted-foreground tabular-nums", children: text })] }));
+}
+/** One field of a FillInQueue record as a row of toggle buttons: one picked, or none. */
+export function FillInChoice({ label, choices, value, onChange, suggestion, shortcut = false, className, }) {
+    const labelId = useId();
+    const register = useContext(ShortcutContext);
+    const latest = useRef({ choices, onChange });
+    useEffect(() => {
+        latest.current = { choices, onChange };
+    });
+    useEffect(() => {
+        if (!shortcut || register === null)
+            return;
+        return register((digit) => {
+            const choice = latest.current.choices[digit - 1];
+            if (choice === undefined)
+                return false;
+            latest.current.onChange(choice.value);
+            return true;
+        });
+    }, [shortcut, register]);
+    const suggested = suggestion ? choices.find((choice) => choice.value === suggestion.value) : undefined;
+    const keys = shortcut && register !== null;
+    return (_jsxs("div", { "data-slot": "fill-in-choice", className: cn('flex flex-col gap-2', className), children: [_jsx("div", { id: labelId, className: "type-label", children: label }), _jsx("div", { role: "group", "aria-labelledby": labelId, className: "flex flex-wrap gap-2", children: choices.map((choice, index) => {
+                    const pressed = value !== null && value !== undefined && choice.value === value;
+                    const isSuggested = suggested !== undefined && choice.value === suggested.value;
+                    return (_jsxs(Toggle, { variant: "outline", pressed: pressed, onPressedChange: () => onChange(pressed ? null : choice.value), "aria-keyshortcuts": keys && index < 9 ? String(index + 1) : undefined, "data-suggested": isSuggested || undefined, className: cn('h-auto min-h-9 px-3 py-1.5', isSuggested && 'border-dashed border-info-text', 'aria-pressed:border-primary aria-pressed:bg-primary aria-pressed:text-primary-foreground aria-pressed:hover:bg-primary/90 aria-pressed:hover:text-primary-foreground'), children: [keys && index < 9 && (_jsx("span", { "aria-hidden": "true", className: "type-caption tabular-nums text-muted-foreground group-aria-pressed/toggle:text-primary-foreground", children: index + 1 })), choice.label] }, String(choice.value)));
+                }) }), suggested !== undefined && (_jsxs("p", { className: "type-caption text-muted-foreground", children: ["Suggested: ", suggested.label, suggestion?.note !== undefined && suggestion.note !== null && _jsxs(_Fragment, { children: [" (", suggestion.note, ")"] })] }))] }));
+}

package/dist/components/app/spin-wheel-pick.d.ts

@@ -0,0 +1,15 @@
+export interface SpinWheelItem {
+    id: string | number;
+    label: string;
+    /** > 0, default 1: the slice's size and its chance (weight over the sum). */
+    weight?: number;
+    /** A tinted slice: a flagged record, a favourite. */
+    emphasis?: boolean;
+}
+/** An item's weight: its own when > 0 and finite, else 1. */
+export declare const spinWheelWeight: (item: SpinWheelItem) => number;
+/**
+ * The index of the item a value in [0, 1) lands on: each item's share of
+ * [0, 1) is its weight over the sum, in order. -1 for no items.
+ */
+export declare function pickSpinWheelIndex(items: readonly SpinWheelItem[], value: number): number;

package/dist/components/app/spin-wheel-pick.js

@@ -0,0 +1,21 @@
+// SpinWheel's chance: which item a value in [0, 1) lands on, each item's
+// share being its weight over the sum of weights.
+/** An item's weight: its own when > 0 and finite, else 1. */
+export const spinWheelWeight = (item) => item.weight !== undefined && Number.isFinite(item.weight) && item.weight > 0 ? item.weight : 1;
+/**
+ * The index of the item a value in [0, 1) lands on: each item's share of
+ * [0, 1) is its weight over the sum, in order. -1 for no items.
+ */
+export function pickSpinWheelIndex(items, value) {
+    if (items.length === 0)
+        return -1;
+    const total = items.reduce((sum, item) => sum + spinWheelWeight(item), 0);
+    const target = Math.min(Math.max(value, 0), 1) * total;
+    let reached = 0;
+    for (let index = 0; index < items.length; index++) {
+        reached += spinWheelWeight(items[index]);
+        if (target < reached)
+            return index;
+    }
+    return items.length - 1;
+}

package/dist/components/app/spin-wheel.d.ts

@@ -0,0 +1,22 @@
+import { type ReactNode } from 'react';
+import { type SpinWheelItem } from './spin-wheel-pick.js';
+export type { SpinWheelItem };
+export interface SpinWheelProps {
+    items: readonly SpinWheelItem[];
+    /** Called when the wheel stops, with the item under the pointer. */
+    onResult: (item: SpinWheelItem) => void;
+    /** The slice drawn as picked while the wheel is at rest. The app owns it. */
+    result?: SpinWheelItem['id'] | null;
+    /** The button's label. Default "Spin". */
+    spinLabel?: string;
+    /** How long a spin turns. Default 4000. */
+    durationMs?: number;
+    /** Shown in the wheel's place, with the button disabled, when `items` is empty. */
+    emptyMessage?: ReactNode;
+    /** The source of chance, [0, 1). Default Math.random; a test passes a fixed one. */
+    random?: () => number;
+    /** Names the wheel. Default "Wheel". */
+    'aria-label'?: string;
+    className?: string;
+}
+export declare function SpinWheel({ items, onResult, result, spinLabel, durationMs, emptyMessage, random, 'aria-label': ariaLabel, className, }: SpinWheelProps): import("react").JSX.Element;

package/dist/components/app/spin-wheel.js

@@ -0,0 +1,128 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// A wheel that picks one item at random, weighted: "what do I do next?"
+// answered by chance among the app's own candidates.
+//
+// - Items: `items`, each a slice in order clockwise from the pointer. Its
+//   `weight` (> 0, default 1; anything else counts as 1) is both the
+//   slice's size and its chance: weight over the sum of weights. An
+//   `emphasis` item is a tinted slice (a flagged record, a favourite).
+// - Spinning: the Spin button turns the wheel several full turns with an
+//   ease-out and stops with the pointer inside the picked slice, a little
+//   off its centre. Spinning again starts from where it stopped. While it
+//   turns the button is disabled; when it stops, `onResult(item)` and a
+//   polite live region says "Picked <label>". With reduced motion asked
+//   for, it doesn't turn: the result is at once.
+// - The result at rest is the app's: `result` is the id of the slice drawn
+//   picked (a solid fill), so the app can keep it, clear it, or show one
+//   it chose itself.
+// - Empty: `emptyMessage` in the wheel's place, the button disabled.
+//
+// Drawn in SVG so every fill is a theme token. Labels read from the hub
+// out, cut to fit their slice, and left off a slice too thin to read; the
+// full label is the slice's <title>. Square, the container's width up to
+// 28rem.
+import { useEffect, useId, useRef, useState } from 'react';
+import { cn } from 'cn';
+import { Button } from '../ui/button.js';
+import { usePrefersReducedMotion } from '../../hooks/use-prefers-reduced-motion.js';
+import { pickSpinWheelIndex, spinWheelWeight as weightOf } from './spin-wheel-pick.js';
+// Degrees clockwise from the top, where the pointer is.
+function slicesOf(items) {
+    const total = items.reduce((sum, item) => sum + weightOf(item), 0);
+    let at = 0;
+    return items.map((item) => {
+        const start = at;
+        at += (weightOf(item) / total) * 360;
+        return { item, start, end: at };
+    });
+}
+// The wheel in viewBox units: centred on 0, 208 across so the pointer fits.
+const RADIUS = 96;
+const HUB = 18;
+const FONT = 7.5;
+// Roughly a character's width at FONT, for cutting a label to its slice.
+const CHAR = FONT * 0.52;
+const RIM_GAP = 7;
+const point = (degrees, radius) => {
+    const radians = (degrees * Math.PI) / 180;
+    return `${(radius * Math.sin(radians)).toFixed(3)} ${(-radius * Math.cos(radians)).toFixed(3)}`;
+};
+const slicePath = ({ start, end }) => `M 0 0 L ${point(start, RADIUS)} A ${RADIUS} ${RADIUS} 0 ${end - start > 180 ? 1 : 0} 1 ${point(end, RADIUS)} Z`;
+// The label cut to the room its slice has: from where the slice is wide
+// enough for a line of text out to the rim. Null when that's under three
+// characters.
+function fitLabel(label, degrees) {
+    const radians = (Math.min(degrees, 180) * Math.PI) / 180;
+    // The radius at which the slice is a line of text and a little wide.
+    const wideEnough = degrees >= 180 ? 0 : (FONT * 1.3) / radians;
+    const from = Math.max(HUB + 5, wideEnough);
+    const room = RADIUS - RIM_GAP - from;
+    const chars = Math.floor(room / CHAR);
+    if (chars < 3)
+        return null;
+    return label.length <= chars ? label : `${label.slice(0, chars - 1).trimEnd()}…`;
+}
+// How far to turn so the pointer lands at `angle` on the wheel, from
+// `rotation`, clockwise: never backwards.
+const turnTo = (rotation, angle) => (((-angle - rotation) % 360) + 360) % 360;
+export function SpinWheel({ items, onResult, result = null, spinLabel = 'Spin', durationMs = 4000, emptyMessage = 'Nothing to pick from', random = Math.random, 'aria-label': ariaLabel = 'Wheel', className, }) {
+    const reducedMotion = usePrefersReducedMotion();
+    const [rotation, setRotation] = useState(0);
+    const [spinning, setSpinning] = useState(false);
+    const [announcement, setAnnouncement] = useState('');
+    const timer = useRef(null);
+    const onResultRef = useRef(onResult);
+    useEffect(() => {
+        onResultRef.current = onResult;
+    });
+    useEffect(() => () => {
+        if (timer.current !== null)
+            clearTimeout(timer.current);
+    }, []);
+    const titleId = useId();
+    const slices = slicesOf(items);
+    const empty = items.length === 0;
+    const spin = () => {
+        if (spinning || empty)
+            return;
+        const index = pickSpinWheelIndex(items, random());
+        const slice = slices[index];
+        // Somewhere inside the slice, not on its edge.
+        const angle = slice.start + (slice.end - slice.start) * (0.15 + 0.7 * random());
+        const turns = reducedMotion ? 0 : Math.max(3, Math.round(durationMs / 800));
+        const next = rotation + turns * 360 + turnTo(rotation, angle);
+        const finish = () => {
+            timer.current = null;
+            setSpinning(false);
+            setAnnouncement(`Picked ${slice.item.label}`);
+            onResultRef.current(slice.item);
+        };
+        setRotation(next);
+        if (reducedMotion) {
+            finish();
+            return;
+        }
+        setAnnouncement('');
+        setSpinning(true);
+        timer.current = setTimeout(finish, durationMs);
+    };
+    return (_jsxs("div", { "data-slot": "spin-wheel", className: cn('flex w-full max-w-md flex-col items-center gap-4', className), children: [_jsx("div", { className: "relative aspect-square w-full", children: empty ? (_jsx("div", { "data-state": "empty", className: "flex size-full items-center justify-center rounded-full border-2 border-dashed border-border p-8 text-center type-body text-muted-foreground", children: emptyMessage })) : (_jsxs("svg", { viewBox: "-104 -104 208 208", role: "img", "aria-labelledby": titleId, className: "size-full select-none", "data-state": spinning ? 'spinning' : 'idle', children: [_jsx("title", { id: titleId, children: `${ariaLabel}, ${items.length} ${items.length === 1 ? 'item' : 'items'}` }), _jsxs("g", { "data-slot": "spin-wheel-rotor", style: {
+                                transform: `rotate(${rotation}deg)`,
+                                transformBox: 'fill-box',
+                                transformOrigin: 'center',
+                                transition: spinning && !reducedMotion ? `transform ${durationMs}ms cubic-bezier(0.15, 0.75, 0.2, 1)` : 'none',
+                            }, children: [slices.map((slice, index) => {
+                                    const picked = !spinning && result !== null && slice.item.id === result;
+                                    const degrees = slice.end - slice.start;
+                                    const text = fitLabel(slice.item.label, degrees);
+                                    const mid = (slice.start + slice.end) / 2;
+                                    return (_jsxs("g", { "data-slot": "spin-wheel-slice", "data-picked": picked || undefined, "data-emphasis": slice.item.emphasis || undefined, children: [_jsx("title", { children: slice.item.label }), degrees >= 359.999 ? (_jsx("circle", { r: RADIUS, className: sliceFill(picked, slice.item.emphasis, index) })) : (_jsx("path", { d: slicePath(slice), className: cn(sliceFill(picked, slice.item.emphasis, index), 'stroke-border'), strokeWidth: 0.75 })), text !== null && (_jsx("text", { transform: `rotate(${mid - 90})`, x: RADIUS - RIM_GAP, y: 0, textAnchor: "end", dominantBaseline: "central", fontSize: FONT, className: cn(picked ? 'fill-primary-foreground font-semibold' : 'fill-foreground'), children: text }))] }, slice.item.id));
+                                }), _jsx("circle", { r: RADIUS, className: "fill-none stroke-border", strokeWidth: 1.5 })] }), _jsx("circle", { r: HUB, className: "fill-background stroke-border", strokeWidth: 1.5 }), _jsx("text", { textAnchor: "middle", dominantBaseline: "central", fontSize: 11, className: "fill-foreground font-semibold tabular-nums", "aria-hidden": "true", children: items.length }), _jsx("path", { d: "M -7 -104 L 7 -104 L 0 -88 Z", className: "fill-foreground stroke-background", strokeWidth: 1.5, strokeLinejoin: "round" })] })) }), _jsx(Button, { onClick: spin, disabled: spinning || empty, size: "lg", className: "min-w-32", children: spinLabel }), _jsx("p", { role: "status", "aria-live": "polite", className: "sr-only", children: announcement })] }));
+}
+function sliceFill(picked, emphasis, index) {
+    if (picked)
+        return 'fill-primary';
+    if (emphasis)
+        return 'fill-info/20';
+    return index % 2 === 0 ? 'fill-muted' : 'fill-card';
+}

package/dist/index.d.ts

@@ -1,6 +1,9 @@
 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 { SpinWheel, type SpinWheelProps } from './components/app/spin-wheel.js';
+export { pickSpinWheelIndex, type SpinWheelItem } from './components/app/spin-wheel-pick.js';
+export { FillInChoice, FillInQueue, type FillInChoiceProps, type FillInQueueProgress, type FillInQueueProps, } from './components/app/fill-in-queue.js';
 export { Artwork, ArtworkTag, ArtworkToggle, type ArtworkAspect, type ArtworkProps, type ArtworkToggleProps, } from './components/app/artwork.js';
 export { CountLink, type CountLinkProps } from './components/app/count-link.js';
 export { DataTable, type DataTableCardLayout, type DataTableProps, type DataTableTotals, type DataTableWidth, type SortingState, } from './components/app/data-table.js';

package/dist/index.js

@@ -5,6 +5,9 @@
 // Composites
 export { AppShell, } from './components/app/app-shell.js';
 export { Board } from './components/app/board.js';
+export { SpinWheel } from './components/app/spin-wheel.js';
+export { pickSpinWheelIndex } from './components/app/spin-wheel-pick.js';
+export { FillInChoice, FillInQueue, } from './components/app/fill-in-queue.js';
 export { Artwork, ArtworkTag, ArtworkToggle, } from './components/app/artwork.js';
 export { CountLink } from './components/app/count-link.js';
 export { DataTable, } from './components/app/data-table.js';

package/dist/testing/index.d.ts

@@ -1,7 +1,24 @@
-import { type Page } from '@playwright/test';
+import { expect, type Page } from '@playwright/test';
 import { type NavEntry } from '../components/app/app-shell-nav.js';
 import type { MswOverride } from '../mocks/override.js';
 export type { MswHandle, MswOverride } from '../mocks/override.js';
+export { expect };
+/**
+ * Makes the page's `goto()` and `reload()` return once the app has
+ * booted (its first render into `#root`), not at the load event, and load
+ * the page once more when one of the app's own files is refused before
+ * then; a second refusal fails naming the file. The wait is bounded by
+ * the test's timeout like any navigation, and the page's own expects keep
+ * their time from there. The `test` exported here applies it to every
+ * test's `page`; this is for a page an app's own fixture opens.
+ */
+export declare function withBootWait(page: Page): Page;
+/**
+ * Playwright's `test`, with a `page` whose `goto()` and `reload()` wait
+ * for the app's boot (`withBootWait`). Import `test` and `expect` from
+ * here instead of '@playwright/test'; the suites below use it too.
+ */
+export declare const test: import("playwright/test").TestType<import("playwright/test").PlaywrightTestArgs & import("playwright/test").PlaywrightTestOptions, import("playwright/test").PlaywrightWorkerArgs & import("playwright/test").PlaywrightWorkerOptions>;
 /**
  * Forces a response for the page's *first* load: set before navigation, so
  * it wins the race against the app's own first fetch. For states forced

package/dist/testing/index.js

@@ -12,8 +12,75 @@
 // Runs in Node, inside Playwright: @playwright/test and @axe-core/playwright
 // are optional peer dependencies, needed only by apps that import this.
 import AxeBuilder from '@axe-core/playwright';
-import { expect, test } from '@playwright/test';
+import { expect, test as base } from '@playwright/test';
 import { navPathname, navTargets } from '../components/app/app-shell-nav.js';
+export { expect };
+// A page load returns at the load event, but the app isn't up yet: React
+// renders only after MSW's worker.start(), which took up to 2.4 s past
+// load in a busy run, and a test's first 5 s expect then failed on an
+// empty page. Under the same load `vite preview` sometimes refuses a
+// connection (about 1 page in 1500): one of the entry's chunks fails, the
+// browser never retries a module script, and the page stays empty until
+// the test's timeout. Both were seen as "never rendered" in every suite.
+const REFUSED = /ERR_CONNECTION_(REFUSED|RESET)/;
+// The app's first render into the template's `<div id="root">`, which is
+// the boot in a mock build (after MSW's start) and a real one alike. A
+// page without one (another site, about:blank) has nothing to wait for.
+const rendered = (page) => page.waitForFunction(() => {
+    const root = document.getElementById('root');
+    return !root || root.hasChildNodes();
+});
+async function boot(page, load, again) {
+    for (let attempt = 1;; attempt++) {
+        let onFailed = () => { };
+        const refused = new Promise((resolve) => {
+            onFailed = (request) => {
+                const url = new URL(request.url());
+                const own = url.origin === new URL(page.url()).origin;
+                if (own && REFUSED.test(request.failure()?.errorText ?? ''))
+                    resolve(url.pathname);
+            };
+            page.on('requestfailed', onFailed);
+        });
+        try {
+            const response = await (attempt === 1 ? load() : again());
+            const file = await Promise.race([rendered(page).then(() => null), refused]);
+            if (file === null)
+                return response;
+            if (attempt === 2)
+                throw new Error(`The server refused ${file} twice: the app never booted`);
+        }
+        finally {
+            page.off('requestfailed', onFailed);
+        }
+    }
+}
+/**
+ * Makes the page's `goto()` and `reload()` return once the app has
+ * booted (its first render into `#root`), not at the load event, and load
+ * the page once more when one of the app's own files is refused before
+ * then; a second refusal fails naming the file. The wait is bounded by
+ * the test's timeout like any navigation, and the page's own expects keep
+ * their time from there. The `test` exported here applies it to every
+ * test's `page`; this is for a page an app's own fixture opens.
+ */
+export function withBootWait(page) {
+    const goto = page.goto.bind(page);
+    const reload = page.reload.bind(page);
+    page.goto = (url, options) => boot(page, () => goto(url, options), () => reload(options));
+    page.reload = (options) => boot(page, () => reload(options), () => reload(options));
+    return page;
+}
+/**
+ * Playwright's `test`, with a `page` whose `goto()` and `reload()` wait
+ * for the app's boot (`withBootWait`). Import `test` and `expect` from
+ * here instead of '@playwright/test'; the suites below use it too.
+ */
+export const test = base.extend({
+    page: async ({ page }, provide) => {
+        await provide(withBootWait(page));
+    },
+});
 /**
  * Forces a response for the page's *first* load: set before navigation, so
  * it wins the race against the app's own first fetch. For states forced

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tristan2828/ui-foundation",
-  "version": "4.41.0",
+  "version": "4.43.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": {