@tristan2828/ui-foundation 3.11.0 → 3.12.0

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,10 @@ 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/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 +199,8 @@ 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, 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 +226,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 +259,23 @@ 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 `single choice` in the header is a
+     `Select` showing its badge (`WidgetStatusSelect`); 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.
+   - **Editing in place isn't in the playbook yet** (a text or date field
+     turning into its form control on the view). Don't build it: every
+     other change goes through Edit.
 
    **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 +366,14 @@ 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. 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
@@ -353,6 +401,13 @@ is a filled-in example while the Widgets demo is still here).
 
 ## 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 status gets the
+  status picker, and the In Stock switch and the checklist's checkboxes
+  are left out.
+
 - 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,8 +7,9 @@ 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
+Patterns 12 (boolean), 15 (yes/no flipped in the row), 16 (title linking
+to its view) and 17 (quick action on the view) 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
@@ -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,70 @@ 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, saved on
+its own the moment it changes, without the form: a status picked from the
+header, a yes/no flipped, a sub-record item ticked. Widget's view is the
+reference (`src/routes/widgets/widget-quick-actions.tsx`): Status and 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`; 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, never text (that's editing in place, not built
+yet).
+
+| The plan's field | The control | Accessible name |
+|---|---|---|
+| `single choice`, in the header | A `Select` (`size="sm"`) whose value and options render as the field's tone-mapped `Badge` (pattern 5), in place of the badge | The field's label: `Status` |
+| `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 status keeps its tone-mapped badge
+  inside the picker; 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.

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

@@ -75,8 +75,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 +113,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 +133,18 @@ 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 fields the view changes
+  right where they show, each saved on its own the moment it changes,
+  without the form. Every other value stays read-only. Each one is a
+  `single choice` (picked from a list, usually a badge field), 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: status (the server refuses Finished while the checklist
+  has open items), checklist
 
 ## 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/entity-view.d.ts

@@ -30,7 +30,11 @@ export type EntityViewSection = {
 export type EntityViewProps = {
     /** The record's name or title, the page's <h1>. */
     title?: string;
-    /** A few status-like values beside the title, as `<Badge>`s. */
+    /**
+     * A few status-like values beside the title, as `<Badge>`s, or as the
+     * control that changes one when the plan makes it a quick action (a
+     * status `Select`, a yes/no `Switch`).
+     */
     badges?: ReactNode;
     /** The header's actions: an Edit button, a Delete with its confirm dialog. */
     actions?: ReactNode;

package/dist/components/app/entity-view.js

@@ -12,9 +12,12 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 // is that an empty value reads as the plan's "not set" label, never a
 // blank.
 //
-// A value can be any markup, a control included, and `actions` takes any
-// buttons: that's the room left for quick actions on this page (a toggle,
-// a status change, ticking a checklist item) without the form.
+// A value can be any markup, a control included, and so can `badges`:
+// that's where quick actions go (cell pattern 17), a value the plan marks
+// as changed straight from this page and saved on its own through
+// `useRecordUpdate`: a status picked in the header, a yes/no switch,
+// checklist items ticked in place. Everything else stays read-only, and
+// every change of more than that goes through Edit, in `actions`.
 import { useId } from 'react';
 import { Link } from 'react-router';
 import { ArrowLeftIcon, SearchXIcon } from 'lucide-react';

package/dist/hooks/use-record-update.d.ts

@@ -0,0 +1,58 @@
+import { type MutationOptions, type QueryClient, type QueryKey } from '@tanstack/react-query';
+import type { AppError } from '../api/contracts.js';
+type RecordId = string | number;
+/**
+ * What one save changes: the fields to send (`{ status: 'done' }`), or a
+ * function building them from the record (`(task) => ({ checklist: ... })`).
+ * Use the function when the new value depends on the current one, like a
+ * whole list with one item changed: it is applied to the record on screen
+ * at once, and again to the server's latest record when the request is
+ * sent, so a change made while another is saving builds on it.
+ */
+export type RecordChange<TRecord, TUpdate> = TUpdate | ((record: TRecord) => TUpdate);
+export type RecordUpdateOptions<TRecord extends {
+    id: RecordId;
+}, TUpdate extends Partial<TRecord>> = {
+    /** The record's id: list items with this id are the ones updated. */
+    id: TRecord['id'];
+    /** The record's detail query key, the one its view reads. */
+    detailKey: QueryKey;
+    /** The prefix every list query of the entity starts with; each holds a `Page<TRecord>`. */
+    listsKey: QueryKey;
+    /** The gateway's PATCH: sends `update`, resolves with the saved record, rejects with an `AppError`. */
+    update: (id: TRecord['id'], update: TUpdate) => Promise<TRecord>;
+    /** What a refusal's toast calls the record: "Couldn't update <name>: <reason>". */
+    name: (record: TRecord) => string;
+};
+type Entry<TRecord, TUpdate> = {
+    change: RecordChange<TRecord, TUpdate>;
+};
+/**
+ * Why a save was refused, in the server's words: for a 422, the message
+ * on a field the save sent (the first field error otherwise), else the
+ * `AppError`'s message.
+ */
+export declare function refusalReason(error: AppError, sent?: object): string;
+/**
+ * The mutation options behind `useRecordUpdate`, for a given QueryClient.
+ * Exported for tests and for code outside React; screens use the hook.
+ */
+export declare function recordUpdateMutationOptions<TRecord extends {
+    id: RecordId;
+}, TUpdate extends Partial<TRecord>>(queryClient: QueryClient, { id, detailKey, listsKey, update, name }: RecordUpdateOptions<TRecord, TUpdate>): MutationOptions<TRecord, AppError, RecordChange<TRecord, TUpdate>, {
+    entry: Entry<TRecord, TUpdate>;
+}>;
+/**
+ * Saves a record's fields on their own, optimistically, wherever the
+ * record is cached (see the top of this file). Call it once per control,
+ * with the entity's query keys and its gateway PATCH, then
+ * `mutate({ field: value })` or `mutate((record) => ({ field: ... }))`.
+ * `isPending` is that control's own save in flight. A refusal rolls back
+ * and shows a toast by itself.
+ */
+export declare function useRecordUpdate<TRecord extends {
+    id: RecordId;
+}, TUpdate extends Partial<TRecord>>(options: RecordUpdateOptions<TRecord, TUpdate>): import("@tanstack/react-query").UseMutationResult<TRecord, AppError, RecordChange<TRecord, TUpdate>, {
+    entry: Entry<TRecord, TUpdate>;
+}>;
+export {};

package/dist/hooks/use-record-update.js

@@ -0,0 +1,142 @@
+// One record's fields saved on their own, straight from the screen showing
+// them (a quick action on the view, a switch in a table row), instead of
+// through the form. A PATCH of what changed, optimistic everywhere the
+// record is cached: its detail query (what the view shows) and every list
+// page holding it. The piece any save-without-the-form reuses.
+//
+// - **Shown at once.** The change is applied to the cached record before
+//   the request goes out, so the screen moves when the user does.
+// - **The server's record wins.** When the save answers, the cache takes
+//   the record the server returned, not the one sent, so a server-side
+//   effect (a computed field, a flag one change clears) shows at once.
+// - **Rapid changes don't lose each other.** Saves of one record run one
+//   at a time (a TanStack mutation scope per record), and each request is
+//   built when it is sent, from the server's latest record. Ticking two
+//   checklist items quickly sends the whole list twice, and the second
+//   request already holds the first tick. A change can be a function of
+//   the record for exactly this: `(record) => ({ checklist: ... })`.
+// - **A refusal rolls back only itself.** The cache goes back to the
+//   server's latest record with every change still waiting re-applied on
+//   top, and a toast gives the server's reason (the field's 422 message,
+//   or the AppError's).
+// - **The lists refetch once the last save settles**, so a filter on the
+//   field drops the row once the server agrees.
+import { hashKey, useMutation, useQueryClient, } from '@tanstack/react-query';
+import { toast } from 'sonner';
+const states = new WeakMap();
+function recordStates(queryClient) {
+    let map = states.get(queryClient);
+    if (!map)
+        states.set(queryClient, (map = new Map()));
+    return map;
+}
+function resolve(change, record) {
+    return typeof change === 'function' ? change(record) : change;
+}
+/**
+ * Why a save was refused, in the server's words: for a 422, the message
+ * on a field the save sent (the first field error otherwise), else the
+ * `AppError`'s message.
+ */
+export function refusalReason(error, sent) {
+    const fieldErrors = Object.entries(error.fieldErrors ?? {});
+    const fields = Object.keys(sent ?? {});
+    const onSentField = fieldErrors.find(([key]) => fields.some((field) => key === field || key.startsWith(`${field}.`)));
+    return (onSentField ?? fieldErrors[0])?.[1][0] ?? error.message;
+}
+/**
+ * The mutation options behind `useRecordUpdate`, for a given QueryClient.
+ * Exported for tests and for code outside React; screens use the hook.
+ */
+export function recordUpdateMutationOptions(queryClient, { id, detailKey, listsKey, update, name }) {
+    const key = hashKey(detailKey);
+    const lists = { queryKey: listsKey };
+    const map = recordStates(queryClient);
+    // The record as the caches hold it now: the detail, else a list's copy.
+    function cached() {
+        const detail = queryClient.getQueryData(detailKey);
+        if (detail)
+            return detail;
+        for (const [, page] of queryClient.getQueriesData(lists)) {
+            const item = page?.items.find((record) => record.id === id);
+            if (item)
+                return item;
+        }
+        return undefined;
+    }
+    // Writes confirmed + pending changes to the detail (when it's cached)
+    // and to every list page holding the record.
+    function render(state) {
+        if (!state.confirmed)
+            return;
+        const shown = state.pending.reduce((record, entry) => ({ ...record, ...resolve(entry.change, record) }), state.confirmed);
+        queryClient.setQueryData(detailKey, (detail) => detail && shown);
+        queryClient.setQueriesData(lists, (page) => page && { ...page, items: page.items.map((record) => (record.id === id ? shown : record)) });
+    }
+    // A save has settled: drop its change and show what's left on top of
+    // the server's latest record. After the last one, refetch the lists.
+    function settle(state, entry) {
+        state.pending = state.pending.filter((pending) => pending !== entry);
+        render(state);
+        if (state.pending.length === 0) {
+            map.delete(key);
+            void queryClient.invalidateQueries(lists);
+        }
+    }
+    return {
+        // One save of this record at a time: the next waits for the last
+        // one's answer, so its request is built on the server's latest record.
+        scope: { id: `record-update:${key}` },
+        mutationFn: (change) => {
+            const confirmed = map.get(key)?.confirmed ?? cached();
+            if (!confirmed)
+                return Promise.reject(new Error('The record to update is not loaded'));
+            return update(id, resolve(change, confirmed));
+        },
+        onMutate: async (change) => {
+            let state = map.get(key);
+            if (!state)
+                map.set(key, (state = { confirmed: undefined, pending: [] }));
+            const entry = { change };
+            state.pending.push(entry);
+            // A refetch landing now would overwrite the change on screen.
+            await Promise.all([
+                queryClient.cancelQueries({ queryKey: detailKey }),
+                queryClient.cancelQueries(lists),
+            ]);
+            // The first change of a burst: the caches still hold the server's record.
+            state.confirmed ??= cached();
+            render(state);
+            return { entry };
+        },
+        onError: (error, _change, context) => {
+            const state = map.get(key);
+            if (!state || !context)
+                return;
+            // What was sent: the change built on the record it was sent against.
+            const record = state.confirmed;
+            const sent = record && resolve(context.entry.change, record);
+            settle(state, context.entry);
+            toast.error(`Couldn't update ${record ? name(record) : 'this record'}: ${refusalReason(error, sent)}`);
+        },
+        onSuccess: (saved, _change, context) => {
+            const state = map.get(key);
+            if (!state || !context)
+                return;
+            state.confirmed = saved;
+            settle(state, context.entry);
+        },
+    };
+}
+/**
+ * Saves a record's fields on their own, optimistically, wherever the
+ * record is cached (see the top of this file). Call it once per control,
+ * with the entity's query keys and its gateway PATCH, then
+ * `mutate({ field: value })` or `mutate((record) => ({ field: ... }))`.
+ * `isPending` is that control's own save in flight. A refusal rolls back
+ * and shows a toast by itself.
+ */
+export function useRecordUpdate(options) {
+    const queryClient = useQueryClient();
+    return useMutation(recordUpdateMutationOptions(queryClient, options));
+}

package/dist/index.d.ts

@@ -22,5 +22,6 @@ export { createQueryClient } from './api/query-client.js';
 export { useTableUrlState } from './hooks/use-table-url-state.js';
 export type { TableView, UrlChanges } from './hooks/table-url-changes.js';
 export { useDebouncedValue } from './hooks/use-debounced-value.js';
+export { useRecordUpdate, type RecordChange, type RecordUpdateOptions, } from './hooks/use-record-update.js';
 export { useIsMobile } from './hooks/use-mobile.js';
 export { cn } from './lib/utils.js';

package/dist/index.js

@@ -27,6 +27,7 @@ export { createQueryClient } from './api/query-client.js';
 // Hooks
 export { useTableUrlState } from './hooks/use-table-url-state.js';
 export { useDebouncedValue } from './hooks/use-debounced-value.js';
+export { useRecordUpdate, } from './hooks/use-record-update.js';
 export { useIsMobile } from './hooks/use-mobile.js';
 // Utilities
 export { cn } from './lib/utils.js';

package/package.json

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