@tristan2828/ui-foundation 4.41.0 → 4.42.0

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/package.json

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