@tristan2828/ui-foundation 3.11.0 → 3.13.0

package/README.md

@@ -18,7 +18,7 @@ than installing this by hand:
 
 | Import | What |
 |---|---|
-| `@tristan2828/ui-foundation` | `AppShell`, `DataTable`, `EntityView`, `EntityForm`, `Markdown`, `ErrorState`, `MultiChoice`, `MultiReference`, `ListEditor`, `PasswordInput`, `RouteErrorBoundary`, `FoundationProviders`, `LoginRoute`, `RegisterRoute`, `useAuth`, `useTableUrlState`, `useDebouncedValue`, `createQueryClient`, `cn`; types `Page`, `AppError`, `QuerySpec` |
+| `@tristan2828/ui-foundation` | `AppShell`, `DataTable`, `EntityView` (with `EditableValue`, `editInPlace`), `EntityForm`, `Markdown`, `RichTextEditor`, `ErrorState`, `MultiChoice`, `MultiReference`, `ListEditor`, `PasswordInput`, `RouteErrorBoundary`, `FoundationProviders`, `LoginRoute`, `RegisterRoute`, `useAuth`, `useTableUrlState`, `useRecordUpdate`, `useDebouncedValue`, `createQueryClient`, `cn`; types `Page`, `AppError`, `QuerySpec` |
 | `@tristan2828/ui-foundation/ui/<name>` | shadcn primitives: badge, button, calendar, card, checkbox, combobox, dialog, empty, field, input, input-group, label, popover, select, separator, sheet, sidebar, skeleton, sonner, spinner, switch, table, textarea, tooltip |
 | `@tristan2828/ui-foundation/gateway` | `safeFetch`, `toAppError`, `networkError` — for an app's `src/api/gateway/` only |
 | `@tristan2828/ui-foundation/mocks` | MSW: `authHandlers`, `resetMockAuth`, `getMockCurrentUser`, `MOCK_USER`, `exposeMswForE2E` |

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

@@ -154,11 +154,13 @@ is a filled-in example while the Widgets demo is still here).
 
    **A `yes/no` marked `toggle`** copies In Stock's cell
    (`in-stock-toggle.tsx`, cell pattern 15): a `Switch` in its own
-   component that PATCHes the one field through an optimistic mutation
-   (`useToggleWidgetInStockMutation`: every cached list page updates at
-   once and is restored if the save fails, with a toast naming the row),
-   then refetches the lists. Its specs cover a flip that saves, the
-   keyboard, and a failed save putting the switch back.
+   component that PATCHes the one field through `useSaveWidgetField`, the
+   entity's wrapper of the foundation's `useRecordUpdate` (the row and the
+   record's view update at once and go back if the save is refused, with
+   a toast naming the row and the server's reason; the lists refetch
+   after). Its specs cover a flip that saves, the keyboard, and a failed
+   save putting the switch back. Copy `useSaveWidgetField` whenever the
+   plan has a `toggle` or any quick action, and only then.
    - `src/routes/widgets/use-widgets.ts`, `use-widget-categories.ts` →
      `src/routes/<entity>/use-<entity>.ts` (TanStack Query hooks over the
      new gateway module)
@@ -183,6 +185,19 @@ is a filled-in example while the Widgets demo is still here).
      `src/routes/<entity>/<entity>-view.tsx` — thin consumer of the
      foundation's `<EntityView>`. Swap the title, badges and sections for
      the plan's "View screen" (below).
+   - `src/routes/widgets/widget-quick-actions.tsx` →
+     `src/routes/<entity>/<entity>-quick-actions.tsx`, **only when the
+     plan's "View screen" lists `Quick actions`**: one component per
+     control the plan names (below).
+   - `src/routes/widgets/widget-fields.tsx` →
+     `src/routes/<entity>/<entity>-fields.tsx`: **one control per field
+     the plan edits in place** (`Edit in place`), shared by the form
+     (through a `Controller`) and the view (through `editInPlace`), and
+     the Markdown long text's `RichTextEditor` (on the form whether or
+     not it edits in place). Every other field's control stays inline in
+     the form, as `widget-form.tsx`'s Category, Tags and Available From
+     do. No `Edit in place` line and no Markdown long text: no fields
+     file.
    - `src/routes/widgets/delete-widget-action.tsx` →
      `src/routes/<entity>/delete-<entity>-action.tsx` (Delete in the
      view's header: the confirm dialog, then `onDeleted` leaves for the
@@ -193,7 +208,9 @@ is a filled-in example while the Widgets demo is still here).
      delete). Swap the zod schema and fields. Every way out lands on a
      view (below).
 
-   **The view** is the read-only page for one record, at `/<entity>/:id`.
+   **The view** is the read-only page for one record, at `/<entity>/:id`
+   (apart from the plan's quick actions and fields edited in place, if it
+   lists any).
    `<EntityView>` owns its loading skeleton, its not-found state (another
    user's record is the same plain 404, with a way back to the list and
    no retry) and its error state with retry. The screen supplies what the
@@ -219,9 +236,31 @@ is a filled-in example while the Widgets demo is still here).
      entity has one: the name, from the same lookup by id the table uses,
      inside `<Link to={`/<other>/${id}`}>`. Without a view, the plain name
      (Widget's categories have none).
-   - **Sub-records are read-only**: the done-count, then each item in
-     order with its state as a glyph and words, never a checkbox
-     (`ChecklistItems` in `widget-view.tsx`). A list of links: each an
+   - **Sub-records are read-only** unless the plan's `Quick actions`
+     names the list: the done-count, then each item in order with its
+     state as a glyph and words, never a checkbox. Widget's checklist is
+     a quick action, so this is the markup to use (the shape Widget's
+     view had before it was):
+
+     ```tsx
+     <div className="flex flex-col gap-2">
+       <p className="type-caption tabular-nums text-muted-foreground">{checklistDoneCount(items)}</p>
+       <ul aria-label="Checklist items" className="flex flex-col gap-1.5">
+         {items.map((item, index) => (
+           <li key={index} className="flex items-start gap-2">
+             {item.done ? (
+               <CircleCheckIcon role="img" aria-label="Done" className="mt-0.5 size-4 shrink-0 text-success-text" />
+             ) : (
+               <CircleIcon role="img" aria-label="Not done" className="mt-0.5 size-4 shrink-0 text-muted-foreground" />
+             )}
+             <span className={item.done ? 'text-muted-foreground' : undefined}>{item.text}</span>
+           </li>
+         ))}
+       </ul>
+     </div>
+     ```
+
+     A list of links: each an
      `<a target="_blank" rel="noreferrer">` with an `ExternalLinkIcon`
      and a visually hidden "(opens in a new tab)".
    - **Long text the plan marks Markdown** renders through the
@@ -230,11 +269,42 @@ is a filled-in example while the Widgets demo is still here).
      as markup. The app needs no Markdown dependency of its own. Plain
      long text renders as text (`whitespace-pre-line` keeps its line
      breaks).
-   - **Quick actions and editing in place aren't in the playbook yet**
-     (flipping a yes/no, changing a status or ticking an item from the
-     view). Don't build them on your own: a row's value can hold a control
-     and `actions` takes any buttons, so they'll slot in once a release
-     adds them.
+   - **Quick actions: only the fields the plan's `Quick actions` line
+     names**, each a control that saves on its own (cell pattern 17,
+     `widget-quick-actions.tsx`). A `yes/no` is a
+     `Switch` with its words (`WidgetInStockSwitch`); a sub-record list's
+     yes/no item field is a checkbox per item in a named group
+     (`ChecklistItems`), whose change is a function of the record
+     (`(current) => ({ checklist: ... })`) so quick ticks build on each
+     other. Each control calls `useSave<Entity>Field(id)` itself and shows
+     its own "Saving" spinner; nothing is disabled. A control goes where
+     the field already shows (`badges`, a field's `value`, a section's
+     `content`): `EntityView` needs nothing new. **With no `Quick actions`
+     line, every value is read-only** and there is no quick-actions file:
+     the view is exactly the read-only one above.
+   - **Edit in place: only the fields the plan's `Edit in place` line
+     names** (cell pattern 18). Each becomes `editInPlace({ kind, value,
+     control, schema, save })` (`widgetEdits` in `widget-view.tsx`):
+     `value` is what the form's control starts from, `control` is the
+     shared control from `<entity>-fields.tsx` given the props it's
+     handed (`readOnly={props.disabled}`, `aria-label={props.label}`,
+     `aria-describedby={props.describedBy}`), `schema` is the form's own
+     rule (`<entity>FormSchema.shape.<field>`), and `save` is
+     `useEdit<Entity>Field(id).mutateAsync({ <field>: value })` (copy
+     `useEditWidgetField`: the single-field save with `optimistic: false,
+     toastOnError: false`). `kind` follows the control: `text` (one line;
+     a number or integer too), `long-text` (Markdown, `RichTextEditor`
+     with `autoFocus` and `onProblem={props.onProblem}`), `choice` (a
+     select or a single reference: its list opens with the field,
+     `defaultOpen`, non-modal, `onChange={(v) => props.commit(v)}`,
+     `onOpenChange={(open) => !open && props.cancel()}`; a yes/no switch
+     commits on change), `multi` (a multi reference; `isEqual` comparing
+     ids as a set). A field gets `edit`, a `content` section gets `edit`,
+     the title gets `titleEdit={{ label, ...edit }}`, and a header badge
+     wraps itself in `<EditableValue label edit layout="inline">`. The
+     shown value stays exactly as before. **With no `Edit in place` line,
+     nothing is editable in place** and none of this is copied. Never a
+     computed field or a sub-record list.
 
    **The table opens the view, and the form returns to it.** The title
    column's link is the way in (a `yes/no` marked `toggle` stays in its
@@ -325,7 +395,22 @@ is a filled-in example while the Widgets demo is still here).
    each value as its cell shows it), plus the sparse record showing its
    "not set" labels and no blank value. Its flows: the table's title link
    opens it, saving and cancelling the form return to it, creating opens
-   the new record's view, and Delete confirms then lands on the list. If
+   the new record's view, and Delete confirms then lands on the list.
+   Each quick action gets its own tests (copy `quick action: …` in
+   `e2e/widget-view.spec.ts`): the change shows and the PATCH carries it
+   (a list item sends the whole list), a server-side effect shows once the
+   save answers if the plan has one, a refused save (an MSW override
+   answering 422 with the reason on the field) goes back with the toast,
+   the "Saving" spinner shows while nothing is disabled, and, for a
+   list, two quick changes both land. Fields edited in place get their
+   own spec (copy `e2e/widget-edit-in-place.spec.ts`): only the plan's
+   fields offer it; each kind saves (Enter, a pick, Ctrl/Cmd+Enter,
+   leaving) with the PATCH it should send and "Saving…" while it waits;
+   unchanged sends nothing; Esc restores; the schema's refusal is never
+   sent; a 422 (an MSW override, the reason on the field) and a 500 stay
+   open with the draft and the reason; opening a second field saves the
+   first, or doesn't open if that fails; and leaving the page with
+   unsaved text asks first. Add it to `mobile-chrome`'s `testMatch`. If
    the plan has Markdown long text, a test forces a record whose text has
    a heading, a list, a table, a link and raw HTML, and asserts the HTML
    shows as text. Add the view's spec to `playwright.config.ts`'s
@@ -346,13 +431,25 @@ is a filled-in example while the Widgets demo is still here).
    `/<entity>/new` to `e2e/a11y.spec.ts`'s `formRoutes`, and add the view
    of a full record and of the sparse one to its `viewRoutes` (the table
    page is picked up from the sidebar automatically; the form and the view
-   aren't in it).
+   aren't in it). With fields edited in place, copy `e2e/a11y.spec.ts`'s
+   "editing in place" block for them: a field open, saving and refused,
+   the rich-text editor, an open list, and the leave prompt, in both
+   themes.
 10. **`npm run verify`.** Fix until it passes. Then stop — do not add
     anything beyond what this list covers; note ideas in the app's
     backlog instead.
 
 ## What not to copy
 
+- `widget-quick-actions.tsx`, its `quick action: …` specs and
+  `useSaveWidgetField` unless the plan has a `Quick actions` line (or,
+  for the hook, a `yes/no` marked `toggle`). Copy only the controls for
+  the fields the line names: a plan naming only its yes/no gets the
+  switch, and the checklist's checkboxes are left out.
+- `widgetEdits`, `useEditWidgetField`, `widget-edit-in-place.spec.ts` and
+  the in-place a11y block unless the plan has an `Edit in place` line,
+  and then only for the fields it names.
+
 - The saved-views row in `widgets-table.tsx` (`VIEWS`, the "Saved views"
   button group and `visibleColumns`) unless the plan's List screen lists
   saved views. When it does, copy it: `useTableUrlState`'s third argument

package/conventions/docs/cell-patterns.md

@@ -7,9 +7,10 @@ per-entity, and only the shape is reusable. Copy the markup into your
 
 Patterns 1–10 were each chosen for a real column, from a page of
 alternatives ([`column-options.md`](column-options.md)), not designed in the abstract.
-Patterns 12 (boolean) and 16 (title linking to its view) are the
-template's own references: Widget's In Stock and Name columns render them
-and their specs pin them. The other patterns from 11 on are
+Patterns 12 (boolean), 15 (yes/no flipped in the row), 16 (title linking
+to its view), 17 (quick action on the view) and 18 (editable value) are
+the template's own references: Widget's In Stock and Name columns and its
+view render them, and their specs pin them. The other patterns from 11 on are
 marked **Unproven**: written ahead of a real
 column, so no app has tested them on real data yet. Prefer a proven
 pattern when one fits. When you use an unproven one, say so in the
@@ -339,9 +340,14 @@ now", "happened"). Widget's In Stock column is the reference
 
 - **A `Switch`, never a checkbox.** It acts at once; a checkbox in a row
   reads as "select this row".
-- **It saves on its own:** a PATCH of that one field, not the form. Show
-  the new value at once (optimistic) and put it back, with a toast naming
-  the row, if the save fails (`useToggleWidgetInStockMutation`).
+- **It saves on its own:** a PATCH of that one field, not the form,
+  through the foundation's `useRecordUpdate` (Widget's
+  `useSaveWidgetField`). The new value shows at once, in the table and on
+  the record's view, and goes back, with a toast naming the row and the
+  server's reason, if the save is refused.
+- **Saving blocks nothing.** The switch stays usable (a second flip waits
+  for the first and builds on it), and a "Saving" spinner shows beside it
+  in a slot that's always there, so the cell never changes width.
 - **Keep the word beside it** (pattern 12), `aria-hidden` since the switch
   announces its own state. Give the switch a row-specific name
   (`In stock: ${row.original.name}`).
@@ -388,3 +394,167 @@ cell: ({ row }) => (
 - **Cost:** none to speak of. Specs that match the title as a cell still
   work (`getByRole('cell', { name })` reads the link's text); ones that
   opened the form from a row button go through the view's Edit instead.
+
+## 17. Quick action on the view
+
+A value on the record's view that changes right where it's shown, with one
+click, saved on its own the moment it changes, without the form: a yes/no
+flipped, a sub-record item ticked. Widget's view is the reference
+(`src/routes/widgets/widget-quick-actions.tsx`): In Stock in the header,
+Checklist items ticked in place.
+
+**Read-only is the default.** A value on the view is a control only when
+the plan's "View screen" names it under `Quick actions` (or `Edit in
+place`, pattern 18); everything else renders as its table cell does, and
+changes through Edit. A quick action is for a value people change often
+and can change back as easily: never anything destructive. Anything you
+type or pick from a list (text, a status) edits in place instead
+(pattern 18); a status was a quick action in 3.12, and moved there in
+3.13.
+
+| The plan's field | The control | Accessible name |
+|---|---|---|
+| `yes/no`, in the header or a field row | A `Switch` (`size="sm"`) with the value in words beside it, `aria-hidden` (pattern 15) | The field's label: `In stock` |
+| A sub-record list's `yes/no` item field | Each item a `Checkbox` inside a `<label>` with the item's text, so the text ticks it too; the list in one `role="group"` named for the list, described by the done-count | `Done: <item text>` (a visually hidden `Done: ` inside the label) |
+
+```tsx
+const save = useSaveWidgetField(widget.id) // one per control
+
+// A value: send the field.
+<Switch size="sm" checked={widget.inStock} aria-label="In stock"
+  onCheckedChange={(inStock) => save.mutate({ inStock })} />
+
+// A list item: send the whole list, built from the latest record.
+<Checkbox checked={item.done} onCheckedChange={(done) =>
+  save.mutate((current) => ({
+    checklist: current.checklist.map((other, i) => (i === index ? { ...other, done } : other)),
+  }))} />
+
+// Beside every control: the "Saving" slot, always there.
+<span className="inline-flex size-3.5 shrink-0">
+  {save.isPending && <Spinner aria-label="Saving" className="size-3.5 text-muted-foreground" />}
+</span>
+```
+
+- **Every save goes through `useRecordUpdate`** (the entity's
+  `useSave<Entity>Field(id)` in `use-<entity>.ts`), called once per
+  control. The change shows at once on the view and in every cached list
+  page. When the save answers, the view takes the record the server
+  returned, so a server-side effect shows (a computed field, a flag the
+  change cleared). Never write a quick action's mutation by hand.
+- **A list is sent whole, built from the latest record**: pass a function
+  of the record (`(current) => ({ checklist: ... })`), not a list read from
+  props. Saves of one record run one at a time and each request is built
+  when it's sent, so two quick ticks both land.
+- **A refusal puts the value back** and toasts "Couldn't update <name>:
+  <reason>", the reason being the server's: the 422's message on the
+  field, or the error's message. That's built into the hook; don't add a
+  second toast.
+- **Saving shows, and blocks nothing.** Each control keeps its own
+  "Saving" spinner in a slot that's always there (nothing moves), and
+  nothing is disabled: not the other controls, not this one, not Edit.
+- **Keep the value's look.** The yes/no keeps its words; a ticked item
+  keeps the muted text a done item had. The control only adds the
+  affordance.
+- **One component per control, in its own file** (`<entity>-quick-actions.tsx`),
+  so each hook lives in a component and the view's sections stay plain
+  data.
+- **Cost:** one click changes data, with no confirmation, and the server
+  may still say no. Keep the list short: a view where every value is a
+  control reads as a form.
+
+## 18. Editable value
+
+A value on the record's view that turns into **the form's own control**
+where it's shown, and saves when you leave it: a title, a status, a
+price, notes, a list of linked records. Widget's view is the reference
+(`src/routes/widgets/widget-view.tsx`): Name (the title), Status (its
+header badge), Price, Description (rich text) and Extra Categories, with
+the controls in `widget-fields.tsx`, the same ones the form uses.
+
+The rule behind every part of it: **nothing typed is ever lost.**
+
+**Which values.** Only those the plan's "View screen" names under `Edit
+in place`; read-only is the default, and a value not named renders
+exactly as it did. Single values only: text, long text, a single choice
+(optional ones with their "not set" option), an integer or a rating, a
+yes/no, a single or multi reference. Never a computed field, and never a
+sub-record list (adding, removing and reordering items stays on the
+form). The view's Edit button and 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
+link inside it (a reference to a record with a view, a link in the
+notes), which still navigates.
+
+**Open: the form's control, nothing else.** The same labels, choices and
+pickers as `EntityForm`; the field's label is its accessible name. No
+Save button, no Undo:
+
+| Kind (`editInPlace({ kind })`) | Saves on | Esc |
+|---|---|---|
+| `text`: one line | Enter, or leaving it | puts the saved value back |
+| `long-text`: notes, rich text for Markdown | Ctrl/Cmd+Enter, or leaving it (Enter is a new line) | the same |
+| `choice`: a select, a switch, a single reference | the pick (its list opens with the field, non-modal) | closes the list with nothing picked: gives up |
+| `multi`: a multi reference | leaving it, or Ctrl/Cmd+Enter (Enter picks) | closes the list first; Esc again gives up |
+
+Leaving means clicking or tabbing anywhere else. Unchanged closes with no
+request; a value the form's schema refuses never leaves the browser and
+shows the schema's message. Opening another value saves the open one
+first; if that save fails, the open one stays and the other doesn't
+open.
+
+**Saving: still open, read-only, and says so.** Under the control,
+"Saving…" with a spinner (`role="status"`) until the server agrees, then
+it closes on the saved value. **Not optimistic**: the value only shows as
+saved once it is, and the view shows the record the server returned (a
+side effect included). The rest of the page stays usable.
+
+**Refused: still open, with exactly what was typed and why.** The reason
+under the control in the destructive text tone (`FieldError`), word for
+word: a 422's field error as `EntityForm` shows it, or the error's
+message (a 500, no answer). The control is `aria-invalid` and described
+by the reason. Nothing reverts on its own, and there's no toast. Leaving
+again retries; Esc gives up.
+
+**Leaving the page** (a link, Back) while a value holds unsaved text asks
+"Discard your changes?" first (Keep editing / Discard); closing the tab
+asks through the browser. A link press doesn't save the field on its
+way out: the prompt decides.
+
+```tsx
+const editField = useEditWidgetField(widget.id) // optimistic: false, toastOnError: false
+const price = editInPlace({
+  kind: 'text',
+  value: widget.price,                         // as the form's control holds it
+  schema: widgetFormSchema.shape.price,        // the form's own rule
+  save: (price) => editField.mutateAsync({ price }),
+  control: (props) => (
+    <WidgetPriceInput id={props.id} value={props.value} onChange={props.onChange}
+      invalid={props.invalid} readOnly={props.disabled}
+      aria-label={props.label} aria-describedby={props.describedBy} />
+  ),
+})
+// A field: { label: 'Price', value: <…as the table shows it…>, edit: price }
+// The title: <EntityView titleEdit={{ label: 'Name', ...name }} />
+// A badge: <EditableValue label="Status" edit={status} layout="inline"><Badge>…</Badge></EditableValue>
+```
+
+- **One control per field, shared with the form** (`<entity>-fields.tsx`):
+  each takes `value`/`onChange` and `readOnly`, and the form wraps it in a
+  `Controller`. Never a second, in-place-only control.
+- **Long text written as Markdown edits as rich text** (`RichTextEditor`):
+  formatted where it's read, saved as Markdown with every block the person
+  didn't touch kept exactly as written. On the form too, so it's one
+  control.
+- **The save is the single-field save** (`useRecordUpdate` with
+  `optimistic: false, toastOnError: false`, the entity's
+  `useEdit<Entity>Field`), `mutateAsync` of one field's PATCH.
+- **Keep the value's look at rest**: the badge stays a badge, the price
+  stays formatted. Only the open state looks like a form.
+- **Cost:** a value that looks like text but edits on click can surprise.
+  Keep it to the fields the plan names, and leave the form for everything
+  else.

package/conventions/docs/entity-plan-template.md

@@ -25,7 +25,8 @@ One or two sentences: what one record is, and who uses the screens.
   - *Demonstrated by the Widget reference* (copied directly): `text` (one
     line), `long text` (say `Markdown` when it's written in Markdown, like
     notes or a write-up: the view renders its headings, lists, tables and
-    links, and it's never a table column), `decimal` (fixed places — say how many),
+    links, the form and editing in place edit it as formatted text, and
+    it's never a table column), `decimal` (fixed places — say how many),
     `date-time`, `email`, `yes/no` (a boolean that is always yes or no:
     say its default and the filter's three labels, e.g. Any stock /
     In stock / Out of stock), `single choice` (list the options, in display
@@ -75,8 +76,10 @@ per list; delete the section if there are none.
 - Most items: 50.
 - In the table: a done-count (`2/6 done`), or blank if the list isn't
   shown.
-- On the view: always shown, read-only: the done-count, then each item in
-  order (a `url` item field opens in a new tab).
+- On the view: always shown: the done-count, then each item in order (a
+  `url` item field opens in a new tab). Read-only, unless the View
+  screen's `Quick actions` names the list: then its yes/no item field is a
+  checkbox on each item, ticked in place.
 
 | Field | Label | Type | Required | Options / rules |
 |---|---|---|---|---|
@@ -111,7 +114,8 @@ per list; delete the section if there are none.
 
 The read-only page for one record (`/<entity>/:id`), opened by clicking
 its title in the table. Edit and Delete live in its header, so the table
-has no row actions. Every field it shows renders as its table cell does.
+has no row actions. Every field it shows renders as its table cell does,
+except the quick actions, if any.
 
 - Title: the field that names a record, shown as the page heading and
   linked from the table: `title`.
@@ -130,6 +134,29 @@ has no row actions. Every field it shows renders as its table cell does.
 - "Not set" labels: what an empty optional field reads as on the view
   (`dueDate`: No due date; `checklist`: No items). A field not listed here
   reads "Not set". A `yes/no` is never empty: it reads Yes or No.
+- Quick actions (optional; delete if none): the values the view changes
+  with one click, each saved on its own the moment it changes, without
+  the form: a `yes/no` (a switch), or a sub-records list (its yes/no item
+  field ticked on each item). Only values people change often and can
+  change back as easily.
+  Say any rule the server enforces on one (it can refuse the change) and
+  any side effect (another field the server changes with it), so each
+  gets a test; the view always shows the record the server returns.
+
+  Quick actions: checklist
+
+- Edit in place (optional; delete if none): the fields that turn into
+  their form control where the view shows them and save when you leave
+  them (cell pattern 18): the title, a badge field, a field row, a long
+  text. Single values only: text, long text, a single choice, an integer
+  or a rating, a yes/no, a single or multi reference. Never a computed
+  field or a sub-records list (those stay on the form). Every value not
+  named here, or under Quick actions, stays read-only. Say any rule the
+  server enforces on one (its refusal shows under the field) and any
+  side effect:
+
+  Edit in place: title, status (the server refuses Finished while the
+  checklist has open items), dueDate, notes
 
 ## Screens and access
 

package/dist/api/gateway/errors.js

@@ -13,7 +13,13 @@ export async function safeFetch(path, init) {
 }
 export function toAppError(status, body) {
     if (status === 422) {
-        const detail = body?.detail ?? [];
+        // A rule the server enforces (a cap, a status the change needs) is
+        // often refused with FastAPI's HTTPException shape: a sentence, not a
+        // list of field issues. That sentence is the message to show.
+        const raw = body?.detail;
+        if (typeof raw === "string")
+            return { kind: "validation", message: raw, fieldErrors: {} };
+        const detail = raw ?? [];
         const fieldErrors = {};
         for (const issue of detail) {
             const field = fieldKey(issue.loc);

package/dist/components/app/edit-in-place-store.d.ts

@@ -0,0 +1,76 @@
+type SafeParse = (value: unknown) => {
+    success: true;
+    data: unknown;
+} | {
+    success: false;
+    error: {
+        issues: readonly {
+            message: string;
+        }[];
+    };
+};
+/** What a field needs to edit in place, read fresh on every use. */
+export type EditFieldConfig = {
+    /** The saved value, as the control holds it (the form's value for the field). */
+    value: unknown;
+    /** The form's zod schema for the field: a value it rejects never leaves the browser. */
+    schema?: {
+        safeParse: SafeParse;
+    };
+    /** Sends the value (the schema's output). Resolves once saved; rejects with an AppError. */
+    save: (value: unknown) => Promise<unknown>;
+    /** Whether the draft is still the saved value. Defaults to comparing as JSON. */
+    isEqual?: (a: unknown, b: unknown) => boolean;
+};
+export type EditFieldState = {
+    status: 'closed';
+} | OpenFieldState;
+export type OpenFieldState = {
+    status: 'open' | 'saving';
+    /** What the control shows: exactly what was typed. */
+    draft: unknown;
+    /** The saved value when the field opened. */
+    initial: unknown;
+    /** Why it can't save (the schema's or the server's words), shown under it. */
+    error: string | null;
+    /** A problem the control reports itself (rich text that can't save as it stands). */
+    problem: string | null;
+};
+export declare class EditInPlaceStore {
+    private configs;
+    private states;
+    private saving;
+    private openKey;
+    private listeners;
+    subscribe: (listener: () => void) => () => void;
+    private emit;
+    private set;
+    /** A field joins the view. `config` is read fresh each time it's needed. */
+    register(key: string, config: () => EditFieldConfig): () => void;
+    state(key: string): EditFieldState;
+    /** The field that's open, if any. */
+    get open(): string | null;
+    /** Whether leaving the page now would lose something: a draft that isn't saved. */
+    get dirty(): boolean;
+    /**
+     * Opens a field. The open one, if another, is saved first: if that
+     * fails it stays open and this one doesn't, and this returns false.
+     */
+    start(key: string): Promise<boolean>;
+    /** The control's value changed. Ignored while saving: the field is read-only then. */
+    change(key: string, draft: unknown): void;
+    /** The control can't produce a value to save as it stands (`null` once it can). */
+    report(key: string, problem: string | null): void;
+    /**
+     * Saves the field (leaving it, Enter, a choice picked). Resolves true
+     * once it's closed (saved, or unchanged), false if it stays open (the
+     * schema refused it, or the save failed). `draft`, when given, is the
+     * value to save (a choice saves the moment it's picked).
+     */
+    commit(key: string, draft?: unknown): Promise<boolean>;
+    /** Esc: closes and shows the saved value again. Not while a save is in flight. */
+    cancel(key: string): void;
+    /** Leaving the page anyway: whatever is open is dropped. */
+    discard(): void;
+}
+export {};