@tristan2828/ui-foundation 4.40.0 → 4.42.0

package/conventions/docs/cell-patterns.md

@@ -26,14 +26,14 @@
   - [A variant: a pressed icon inside another value's cell](#a-variant-a-pressed-icon-inside-another-values-cell) · lines 564–647
 - [16. Title linking to the record's view](#16-title-linking-to-the-records-view) · lines 649–684
 - [17. Quick action on the view](#17-quick-action-on-the-view) · lines 686–759
-- [18. Editable value](#18-editable-value) · lines 761–1176
-  - [A list of sub-items](#a-list-of-sub-items) · lines 1020–1077
-  - [In a table's rows](#in-a-tables-rows) · lines 1079–1164
-  - [A table of a few short columns: `width="content"`](#a-table-of-a-few-short-columns-widthcontent) · lines 1166–1176
-- [19. Stage circle for an ordered status](#19-stage-circle-for-an-ordered-status) · lines 1178–1244
-- [20. Count linking to the related records](#20-count-linking-to-the-related-records) · lines 1246–1310
-- [21. Rows grouped under headings, and a pill filter](#21-rows-grouped-under-headings-and-a-pill-filter) · lines 1312–1377
-- [22. A highlighted row, and rows that are done](#22-a-highlighted-row-and-rows-that-are-done) · lines 1379–1407
+- [18. Editable value](#18-editable-value) · lines 761–1207
+  - [A list of sub-items](#a-list-of-sub-items) · lines 1023–1108
+  - [In a table's rows](#in-a-tables-rows) · lines 1110–1195
+  - [A table of a few short columns: `width="content"`](#a-table-of-a-few-short-columns-widthcontent) · lines 1197–1207
+- [19. Stage circle for an ordered status](#19-stage-circle-for-an-ordered-status) · lines 1209–1275
+- [20. Count linking to the related records](#20-count-linking-to-the-related-records) · lines 1277–1341
+- [21. Rows grouped under headings, and a pill filter](#21-rows-grouped-under-headings-and-a-pill-filter) · lines 1343–1408
+- [22. A highlighted row, and rows that are done](#22-a-highlighted-row-and-rows-that-are-done) · lines 1410–1438
 
 <!-- /index -->
 
@@ -781,8 +781,11 @@ the form stay.
 **At rest: says it's editable without shouting.** The value reads as it
 always did. Hover tints it (`bg-muted`) and shows a pencil; the pencil is
 a real button ("Edit <label>"), so Tab reaches it and Enter opens the
-field, and its focus ring tints the value too. On a touch screen the
-pencil always shows. A click anywhere on the value opens it, except on a
+field, and its focus ring tints the value too. Muted text inside it (the
+view's "Not set", a "No caption", a done item) turns `text-foreground`
+on that tint, since muted on `bg-muted` is under 4.5:1; the package does
+it, so an app just uses `text-muted-foreground` as anywhere else. On a
+touch screen the pencil always shows. A click anywhere on the value opens it, except on a
 link inside it (a reference to a record with a view, a link in the
 notes), which still navigates.
 
@@ -1056,6 +1059,14 @@ Checklist is the reference (`checklist` in `widgetEdits`). It's built on
   option is still inside the row, and Enter in the row's text box or
   leaving the row saves the item, ids only on the wire. A new item starts
   with no pick, which the list's schema refuses on that row.
+- **Items that come from elsewhere** (a record's files, added by upload):
+  `add` in place of `newItem` and `addLabel`. It renders the app's own
+  control (an "Add files" button over a hidden file input) and is given
+  `add(items)`, which saves them at the end through `save`, as a move is
+  ("Saving…", a refusal under the list, the caret back on the control),
+  plus `items` (to stop at a limit), `disabled` (a change is saving) and
+  `onProblem(message)` (an upload refused, under the list). Each item
+  then reads, edits, moves and removes like a checklist's.
 
 ```tsx
 const checklist = editInPlace<ChecklistItem>({
@@ -1076,6 +1087,26 @@ The row's fields are one component shared with the form
 (`WidgetChecklistItemFields` in `widget-fields.tsx`), each field named by
 position ("Item 2 text") as the row buttons name the item.
 
+A list added by upload:
+
+```tsx
+const files = editInPlace<Attachment>({
+  kind: 'list',
+  value: record.attachments,
+  save: (change) => editField.mutateAsync((current) => ({ attachments: change(current.attachments) })),
+  itemName: (index) => record.attachments[index]?.name ?? `file ${index + 1}`,
+  add: ({ add, items, disabled, onProblem }) => (
+    <UploadButton                                           // the app's: a button over <input type="file" hidden>
+      disabled={disabled || items.length >= MAX}
+      onUploaded={(stored) => add(stored.map(toAttachment))}
+      onRefused={(error) => onProblem(error.message)}
+    />
+  ),
+  renderShown: (file) => <FileRow file={file} />,           // its thumbnail, name and caption
+  renderItem: (props) => <CaptionInput {...props} />,       // what edits on a click: the caption
+})
+```
+
 ### In a table's rows
 
 For a **small entity edited in its table** (a name and a few fields,

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/edit-in-place.d.ts

@@ -123,14 +123,31 @@ export type EditListItemProps<TItem> = EditControlProps<TItem> & {
     /** The item being added at the end, not one already in the list. */
     isNew: boolean;
 };
+/** What a list's own `add` is given: how to put new items at the end, saved as the list's other changes are. */
+export type EditListAddProps<TItem> = {
+    /**
+     * Saves these items at the end of the list, through the list's `save`
+     * (built on its latest list, after whatever is open and whatever is
+     * still saving). "Saving…" and a refusal show under the list, as for a
+     * move. Resolves once it's done: `true` saved, `false` refused.
+     */
+    add: (items: TItem[]) => Promise<boolean>;
+    /** The list as saved: to stop adding at a limit (`items.length >= max`). */
+    items: readonly TItem[];
+    /** A change is saving: the list's buttons wait, and so should this one. */
+    disabled: boolean;
+    /** Why the add can't happen (an upload refused), under the list where a refused save shows; `null` clears it. */
+    onProblem: (message: string | null) => void;
+};
 /**
- * A list of sub-items edited in place (a checklist, a list of links), on
- * a `content` section of EntityView. Make one with `editInPlace({ kind:
- * 'list', ... })`. Every item reads as `renderShown` (a quick action, such
- * as its done box, still works there); clicking it or its pencil turns it
- * into `renderItem`, the form's own row. "Add" at the end opens a new item;
- * move up, move down and remove are ListEditor's buttons. Each change is one
- * save of the whole list.
+ * A list of sub-items edited in place (a checklist, a list of links, a
+ * record's files), on a `content` section of EntityView. Make one with
+ * `editInPlace({ kind: 'list', ... })`. Every item reads as `renderShown`
+ * (a quick action, such as its done box, still works there); clicking it
+ * or its pencil turns it into `renderItem`, the form's own row. "Add" at
+ * the end opens a new item (`newItem`), or the app's own `add` puts items
+ * there (an upload); move up, move down and remove are ListEditor's
+ * buttons. Each change is one save of the whole list.
  */
 export type EditInPlaceListOptions<TItem> = {
     kind: 'list';
@@ -145,12 +162,19 @@ export type EditInPlaceListOptions<TItem> = {
     renderItem: (props: EditListItemProps<TItem>) => ReactNode;
     /** How the item reads when it isn't being edited. Its own controls (a done box) keep working. */
     renderShown: (item: TItem, index: number) => ReactNode;
-    /** A blank item, what "Add" starts from. */
-    newItem: () => TItem;
+    /** A blank item, what "Add" starts from. Not needed with `add`; one or the other is. */
+    newItem?: () => TItem;
+    /**
+     * In place of "Add" and its blank item: what adds items, such as a file
+     * upload or a picker, e.g. a button that uploads, then calls
+     * `props.add(stored.map(toItem))`. The items save at the end of the list
+     * through `save`, so they read, move and save like any other.
+     */
+    add?: (props: EditListAddProps<TItem>) => ReactNode;
     /** How the buttons name an item, as on the form: (i) => `item ${i + 1}` gives "Move item 2 up". */
     itemName: (index: number) => string;
-    /** The Add button's text, e.g. "Add item". */
-    addLabel: string;
+    /** The Add button's text, e.g. "Add item". Not needed with `add`, whose control has its own. */
+    addLabel?: string;
     /**
      * The form's schema for the whole list (`widgetFormSchema.shape.checklist`).
      * Each change is checked as the list it would make; a message about an
@@ -169,7 +193,8 @@ export type EditInPlaceListOptions<TItem> = {
     save: (change: (current: TItem[]) => TItem[]) => Promise<unknown>;
 };
 /** A list marked editable in place. Make one with `editInPlace({ kind: 'list', ... })`. */
-export type EditInPlaceList = Omit<EditInPlaceListOptions<unknown>, 'renderItem' | 'renderShown' | 'schema' | 'save'> & {
+export type EditInPlaceList = Omit<EditInPlaceListOptions<unknown>, 'renderItem' | 'renderShown' | 'schema' | 'save' | 'add'> & {
+    add?: (props: EditListAddProps<unknown>) => ReactNode;
     renderItem: (props: EditListItemProps<unknown>) => ReactNode;
     renderShown: (item: unknown, index: number) => ReactNode;
     schema?: {

package/dist/components/app/editable-list.js

@@ -9,7 +9,8 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 //   form's row (`renderItem`), an EditableValue like any field: leaving or
 //   Enter saves, Esc gives up, one field open at a time.
 // - "Add" at the end opens a new item the same way. Enter saves it and
-//   opens the next, so a run of items goes in from the keyboard.
+//   opens the next, so a run of items goes in from the keyboard. Or the
+//   app's own `add` (an upload) puts items at the end, saved as a move is.
 // - Move and remove save at once. Whatever is open is saved first; while
 //   the change saves, the buttons wait, "Saving…" shows under the list,
 //   and a refusal leaves the list as it was with the reason under it.
@@ -56,16 +57,22 @@ function checkItem(edit, items, index, draft) {
     const issue = issues.find(({ path }) => path?.[0] === index) ?? issues.find(({ path }) => !path?.length) ?? issues[0];
     return { success: false, error: { issues: issue ? [issue] : [] } };
 }
+// The app's own add, as a component of its own: it renders the app's
+// control with what it's given, and holds nothing.
+function ListAdd({ render, ...props }) {
+    return _jsx("div", { "data-list-add-slot": "", children: render(props) });
+}
 export function EditableList({ label, edit, emptyLabel }) {
     const store = useContext(EditInPlaceContext);
     if (!store)
         throw new Error('A list edited in place works inside an <EntityView>, which runs editing in place.');
     const items = edit.value;
     const statusId = useId();
-    const [status, setStatus] = useState({ saving: false, error: null });
+    const [status, setStatus] = useState({ saving: false, inFlight: 0, error: null });
     // The buttons are disabled while a change saves, which drops the caret.
     // Once the list shows the outcome it goes to the first of these buttons
-    // (by name) that's there and enabled, else to Add.
+    // (by name) that's there and enabled, else to Add (or the app's add's
+    // first button).
     const root = useRef(null);
     const focusNext = useRef(null);
     useEffect(() => {
@@ -75,26 +82,30 @@ export function EditableList({ label, edit, emptyLabel }) {
         focusNext.current = null;
         const buttons = [...(root.current?.querySelectorAll('button:not(:disabled)') ?? [])];
         const target = names.map((name) => buttons.find((button) => button.getAttribute('aria-label') === name)).find(Boolean);
-        (target ?? root.current?.querySelector('[data-list-add]:not(:disabled)'))?.focus();
+        (target ?? root.current?.querySelector('[data-list-add]:not(:disabled), [data-list-add-slot] button:not(:disabled)'))?.focus();
     }, [items, status.saving]);
-    // Move and remove: save the open field first (if it can't save, it stays
-    // and nothing else happens), then the change.
-    const act = async (change, focusAfter, focusIfRefused) => {
-        if (status.saving)
-            return;
+    // Move, remove and the app's own add: save the open field first (if it
+    // can't save, it stays and nothing else happens), then the change. An
+    // add that lands while a change saves (an upload finishing) still goes:
+    // `save` builds on the latest list, and "Saving…" stays until both are done.
+    const act = async (change, focusAfter, focusIfRefused, waits = true) => {
+        if (waits && status.saving)
+            return false;
         const open = store.open;
         if (open !== null && !(await store.commit(open)))
-            return;
-        setStatus({ saving: true, error: null });
+            return false;
+        setStatus((now) => ({ saving: true, inFlight: now.inFlight + 1, error: null }));
+        let error = null;
         try {
             await edit.save(change);
             focusNext.current = focusAfter;
-            setStatus({ saving: false, error: null });
         }
-        catch (error) {
+        catch (refused) {
             focusNext.current = focusIfRefused;
-            setStatus({ saving: false, error: messageOf(error) });
+            error = messageOf(refused);
         }
+        setStatus((now) => ({ saving: now.inFlight > 1, inFlight: now.inFlight - 1, error: error ?? now.error }));
+        return error === null;
     };
     const move = (from, to) => {
         const direction = to < from ? 'up' : 'down';
@@ -124,13 +135,19 @@ export function EditableList({ label, edit, emptyLabel }) {
             return current.map((other, i) => (i === at ? item : other));
         }),
     });
+    // The app's own add: its items saved at the end, the caret back on it.
+    const addItems = (added) => added.length === 0 ? Promise.resolve(true) : act((current) => [...current, ...added], [], [], false);
+    const onProblem = (message) => setStatus((now) => ({ ...now, error: message }));
     // The item being added, at the end.
+    const newItem = edit.newItem;
+    if (!newItem && !edit.add)
+        throw new Error('A list edited in place needs `newItem` (a blank item to add) or `add` (its own control).');
     const addEdit = {
         kind: 'text',
-        value: edit.newItem(),
+        value: newItem?.(),
         control: (props) => _jsx(ItemRow, { children: edit.renderItem({ ...props, index: items.length, isNew: true }) }),
         schema: { safeParse: (draft) => checkItem(edit, items, items.length, draft) },
         save: (item) => edit.save((current) => [...current, item]),
     };
-    return (_jsxs("div", { ref: root, className: "flex flex-col gap-2", "data-slot": "editable-list", children: [_jsx(ListEditor, { "aria-label": label, items: items.map((_, index) => ({ id: String(index) })), itemName: edit.itemName, addLabel: edit.addLabel, emptyText: emptyLabel, disabled: status.saving, onRemove: remove, onMove: move, renderItem: (index) => (_jsx(EditableField, { label: edit.itemName(index), edit: itemEdit(index), children: edit.renderShown(items[index], index) })), add: _jsx(EditableField, { label: edit.itemName(items.length), edit: addEdit, reopenAfterKeyboardSave: true, children: null, trigger: (start) => (_jsx("div", { children: _jsxs(Button, { "data-list-add": "", type: "button", variant: "outline", size: "sm", disabled: status.saving, onClick: start, children: [_jsx(PlusIcon, {}), edit.addLabel] }) })) }) }), _jsx("span", { id: statusId, className: "type-body", children: status.saving ? (_jsxs("span", { role: "status", className: "inline-flex items-center gap-1.5 type-caption text-muted-foreground", children: [_jsx(Spinner, { "aria-hidden": "true", className: "size-3.5" }), "Saving\u2026"] })) : (status.error && _jsx(FieldError, { className: "type-caption", children: status.error })) })] }));
+    return (_jsxs("div", { ref: root, className: "flex flex-col gap-2", "data-slot": "editable-list", children: [_jsx(ListEditor, { "aria-label": label, items: items.map((_, index) => ({ id: String(index) })), itemName: edit.itemName, addLabel: edit.addLabel ?? '', emptyText: emptyLabel, disabled: status.saving, onRemove: remove, onMove: move, renderItem: (index) => (_jsx(EditableField, { label: edit.itemName(index), edit: itemEdit(index), children: edit.renderShown(items[index], index) })), add: edit.add ? (_jsx(ListAdd, { render: edit.add, add: addItems, items: items, disabled: status.saving, onProblem: onProblem })) : (_jsx(EditableField, { label: edit.itemName(items.length), edit: addEdit, reopenAfterKeyboardSave: true, children: null, trigger: (start) => (_jsx("div", { children: _jsxs(Button, { "data-list-add": "", type: "button", variant: "outline", size: "sm", disabled: status.saving, onClick: start, children: [_jsx(PlusIcon, {}), edit.addLabel] }) })) })) }), _jsx("span", { id: statusId, className: "type-body", children: status.saving ? (_jsxs("span", { role: "status", className: "inline-flex items-center gap-1.5 type-caption text-muted-foreground", children: [_jsx(Spinner, { "aria-hidden": "true", className: "size-3.5" }), "Saving\u2026"] })) : (status.error && _jsx(FieldError, { className: "type-caption", children: status.error })) })] }));
 }

package/dist/components/app/editable-value.js

@@ -206,7 +206,7 @@ export function EditableField({ label, edit, children, layout = 'block', classNa
     if (state.status === 'closed' && !always) {
         if (trigger)
             return (_jsx("span", { ref: triggerBox, className: "contents", children: trigger(start) }));
-        return (_jsxs("span", { "data-slot": "editable-value", onClick: onShownClick, className: cn('group/editable relative -mx-1.5 cursor-text items-start gap-1 rounded-md px-1.5 transition-colors hover:bg-muted has-[[data-edit]:focus-visible]:bg-muted', layout === 'block' ? 'flex w-full' : 'inline-flex max-w-full align-top', className), children: [_jsx("span", { className: "min-w-0 flex-1", children: children }), _jsx(Button, { ref: editButton, "data-edit": "", type: "button", variant: "ghost", size: "icon-xs", "aria-label": `Edit ${label}`, onClick: start, className: "shrink-0 text-muted-foreground opacity-0 group-hover/editable:opacity-100 focus-visible:opacity-100 pointer-coarse:opacity-100", children: _jsx(PencilIcon, {}) })] }));
+        return (_jsxs("span", { "data-slot": "editable-value", onClick: onShownClick, className: cn('group/editable relative -mx-1.5 cursor-text items-start gap-1 rounded-md px-1.5 transition-colors hover:bg-muted has-[[data-edit]:focus-visible]:bg-muted', layout === 'block' ? 'flex w-full' : 'inline-flex max-w-full align-top', className), children: [_jsx("span", { className: "min-w-0 flex-1 group-hover/editable:[&_.text-muted-foreground]:text-foreground group-has-[[data-edit]:focus-visible]/editable:[&_.text-muted-foreground]:text-foreground", children: children }), _jsx(Button, { ref: editButton, "data-edit": "", type: "button", variant: "ghost", size: "icon-xs", "aria-label": `Edit ${label}`, onClick: start, className: "shrink-0 text-muted-foreground opacity-0 group-hover/editable:opacity-100 focus-visible:opacity-100 pointer-coarse:opacity-100", children: _jsx(PencilIcon, {}) })] }));
     }
     // Always editable, before the store has it (the first render): the saved value.
     const open = state.status === 'closed' ? { status: 'open', draft: edit.value, error: null, autosave: undefined, revision: 0 } : state;

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';
@@ -8,7 +11,7 @@ export { type RowGroup } from './components/app/table-groups.js';
 export { byDay, type ByDayOptions } from './lib/group-by-day.js';
 export { EntityForm, type EntityFormProps } from './components/app/entity-form.js';
 export { EntityView, type EntityViewField, type EntityViewLayout, type EntityViewPlacement, type EntityViewProps, type EntityViewSection, } from './components/app/entity-view.js';
-export { editInPlace, type EditControlProps, type EditInPlace, type EditInPlaceList, type EditInPlaceListOptions, type EditInPlaceOptions, type EditKind, type EditListItemProps, } from './components/app/edit-in-place.js';
+export { editInPlace, type EditControlProps, type EditInPlace, type EditInPlaceList, type EditInPlaceListOptions, type EditInPlaceOptions, type EditKind, type EditListAddProps, type EditListItemProps, } from './components/app/edit-in-place.js';
 export { DataEnvironmentBanner } from './components/app/data-environment-banner.js';
 export { EditableValue, type EditableValueProps } from './components/app/editable-value.js';
 export { ErrorState } from './components/app/error-state.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.40.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": {