@tristan2828/ui-foundation 3.12.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

@@ -189,6 +189,15 @@ is a filled-in example while the Widgets demo is still here).
      `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
@@ -200,7 +209,8 @@ is a filled-in example while the Widgets demo is still here).
      view (below).
 
    **The view** is the read-only page for one record, at `/<entity>/:id`
-   (apart from the plan's quick actions, if it lists any).
+   (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
@@ -261,8 +271,7 @@ is a filled-in example while the Widgets demo is still here).
      breaks).
    - **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
+     `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
@@ -273,9 +282,29 @@ is a filled-in example while the Widgets demo is still here).
      `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.
+   - **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
@@ -373,7 +402,15 @@ is a filled-in example while the Widgets demo is still here).
    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
+   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
@@ -394,7 +431,10 @@ 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.
@@ -404,9 +444,11 @@ is a filled-in example while the Widgets demo is still here).
 - `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 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

package/conventions/docs/cell-patterns.md

@@ -8,9 +8,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), 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
+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
@@ -397,22 +397,23 @@ cell: ({ row }) => (
 
 ## 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.
+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`; 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 "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 |
 |---|---|---|
-| `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) |
 
@@ -452,12 +453,108 @@ const save = useSaveWidgetField(widget.id) // one per control
 - **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.
+- **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
@@ -133,18 +134,29 @@ except the quick actions, if any.
 - "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.
+- 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: status (the server refuses Finished while the checklist
-  has open items), checklist
+  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/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 {};

package/dist/components/app/edit-in-place-store.js

@@ -0,0 +1,159 @@
+import { refusalReason } from '../../hooks/use-record-update.js';
+const CLOSED = { status: 'closed' };
+const sameAsJson = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+function messageOf(error) {
+    if (error && typeof error === 'object' && 'kind' in error)
+        return refusalReason(error);
+    if (error instanceof Error)
+        return error.message;
+    return 'The save failed. Try again.';
+}
+export class EditInPlaceStore {
+    configs = new Map();
+    states = new Map();
+    saving = new Map();
+    openKey = null;
+    listeners = new Set();
+    subscribe = (listener) => {
+        this.listeners.add(listener);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    };
+    emit() {
+        for (const listener of this.listeners)
+            listener();
+    }
+    set(key, state) {
+        this.states.set(key, state);
+        if (state.status === 'closed' && this.openKey === key)
+            this.openKey = null;
+        this.emit();
+    }
+    /** A field joins the view. `config` is read fresh each time it's needed. */
+    register(key, config) {
+        this.configs.set(key, config);
+        return () => {
+            this.configs.delete(key);
+            this.states.delete(key);
+            if (this.openKey === key)
+                this.openKey = null;
+        };
+    }
+    state(key) {
+        return this.states.get(key) ?? CLOSED;
+    }
+    /** The field that's open, if any. */
+    get open() {
+        return this.openKey;
+    }
+    /** Whether leaving the page now would lose something: a draft that isn't saved. */
+    get dirty() {
+        if (this.openKey === null)
+            return false;
+        const state = this.state(this.openKey);
+        if (state.status === 'closed')
+            return false;
+        if (state.status === 'saving' || state.error !== null)
+            return true;
+        const isEqual = this.configs.get(this.openKey)?.().isEqual ?? sameAsJson;
+        return !isEqual(state.draft, state.initial);
+    }
+    /**
+     * 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.
+     */
+    async start(key) {
+        if (this.openKey === key)
+            return true;
+        if (this.openKey !== null) {
+            const closed = await this.commit(this.openKey);
+            if (!closed)
+                return false;
+            // Another field may have opened while that save was in flight.
+            if (this.openKey !== null && this.openKey !== key)
+                return false;
+        }
+        const config = this.configs.get(key)?.();
+        if (!config)
+            return false;
+        this.openKey = key;
+        this.set(key, { status: 'open', draft: config.value, initial: config.value, error: null, problem: null });
+        return true;
+    }
+    /** The control's value changed. Ignored while saving: the field is read-only then. */
+    change(key, draft) {
+        const state = this.state(key);
+        if (state.status !== 'open')
+            return;
+        this.set(key, { ...state, draft });
+    }
+    /** The control can't produce a value to save as it stands (`null` once it can). */
+    report(key, problem) {
+        const state = this.state(key);
+        if (state.status === 'closed' || state.problem === problem)
+            return;
+        this.set(key, { ...state, problem });
+    }
+    /**
+     * 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, draft) {
+        const inFlight = this.saving.get(key);
+        if (inFlight)
+            return inFlight;
+        let state = this.state(key);
+        if (state.status === 'closed')
+            return Promise.resolve(true);
+        if (draft !== undefined && state.status === 'open') {
+            state = { ...state, draft };
+            this.set(key, state);
+        }
+        const open = state;
+        const config = this.configs.get(key)?.();
+        if (!config)
+            return Promise.resolve(false);
+        if (open.problem) {
+            this.set(key, { ...open, error: open.problem });
+            return Promise.resolve(false);
+        }
+        const isEqual = config.isEqual ?? sameAsJson;
+        if (isEqual(open.draft, open.initial)) {
+            this.set(key, CLOSED);
+            return Promise.resolve(true);
+        }
+        const parsed = config.schema ? config.schema.safeParse(open.draft) : { success: true, data: open.draft };
+        if (!parsed.success) {
+            this.set(key, { ...open, error: parsed.error.issues[0]?.message ?? 'Check this value.' });
+            return Promise.resolve(false);
+        }
+        this.set(key, { ...open, status: 'saving', error: null });
+        const save = config
+            .save(parsed.data)
+            .then(() => {
+            this.set(key, CLOSED);
+            return true;
+        }, (error) => {
+            this.set(key, { ...open, status: 'open', error: messageOf(error) });
+            return false;
+        })
+            .finally(() => this.saving.delete(key));
+        this.saving.set(key, save);
+        return save;
+    }
+    /** Esc: closes and shows the saved value again. Not while a save is in flight. */
+    cancel(key) {
+        const state = this.state(key);
+        if (state.status !== 'open')
+            return;
+        this.set(key, CLOSED);
+    }
+    /** Leaving the page anyway: whatever is open is dropped. */
+    discard() {
+        if (this.openKey !== null)
+            this.cancel(this.openKey);
+    }
+}

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

@@ -0,0 +1,88 @@
+import { type ReactNode } from 'react';
+import type { EditInPlaceStore } from './edit-in-place-store.js';
+/** What an editable value's control is given. Spread what applies onto the form's own control. */
+export type EditControlProps<TDraft> = {
+    /** The control's id. */
+    id: string;
+    /** The draft: exactly what's been typed or picked. */
+    value: TDraft;
+    onChange: (value: TDraft) => void;
+    /**
+     * Save now. A choice calls it with the value picked (`commit(value)`):
+     * a choice saves the moment it's picked.
+     */
+    commit: (value?: TDraft) => void;
+    /** Close without saving: a list closed with nothing picked. */
+    cancel: () => void;
+    /** The save is in flight: show the draft, don't let it change. */
+    disabled: boolean;
+    /** The draft was refused; its reason is under it (`aria-describedby`). */
+    invalid: boolean;
+    /** The field's label: the control's accessible name. */
+    label: string;
+    /** The id of the line under the control (Saving…, or why it can't save). */
+    describedBy: string;
+    /** For a control that can't always produce a value to save (RichTextEditor's `onProblem`). */
+    onProblem: (message: string | null) => void;
+};
+/**
+ * How the value saves, which follows from its control:
+ * - `text`: one line. Enter saves (as does leaving it).
+ * - `long-text`: Ctrl/Cmd+Enter saves; Enter is a new line.
+ * - `choice`: one pick (a select, a switch, a single reference). Saves the
+ *   moment it's picked; its list opens with the field.
+ * - `multi`: several picks (a multi reference). Saves on leaving it, or
+ *   Ctrl/Cmd+Enter; Enter picks.
+ * Leaving the field saves every kind; Esc gives up.
+ */
+export type EditKind = 'text' | 'long-text' | 'choice' | 'multi';
+type SafeParseResult<TValue> = {
+    success: true;
+    data: TValue;
+} | {
+    success: false;
+    error: {
+        issues: readonly {
+            message: string;
+        }[];
+    };
+};
+/** A field marked editable. Make one with `editInPlace({...})`. */
+export type EditInPlace = {
+    kind: EditKind;
+    value: unknown;
+    control: (props: EditControlProps<unknown>) => ReactNode;
+    schema?: {
+        safeParse: (value: unknown) => SafeParseResult<unknown>;
+    };
+    save: (value: unknown) => Promise<unknown>;
+    isEqual?: (a: unknown, b: unknown) => boolean;
+};
+export type EditInPlaceOptions<TDraft, TValue> = {
+    kind: EditKind;
+    /** The saved value as the control holds it: what the form's control would start from. */
+    value: TDraft;
+    /** The form's own control for this field (one control per field, shared with the form). */
+    control: (props: EditControlProps<TDraft>) => ReactNode;
+    /**
+     * The form's schema for this field (`widgetFormSchema.shape.name`): a
+     * value it refuses never leaves the browser, and its message shows
+     * under the field. Its output is what `save` gets.
+     */
+    schema?: {
+        safeParse: (value: unknown) => SafeParseResult<TValue>;
+    };
+    /**
+     * Saves the value: the entity's single-field save (`useRecordUpdate`
+     * with `optimistic: false, toastOnError: false`), `mutateAsync` of the
+     * field's update. Rejects with the AppError; a 422's field error shows
+     * under the field word for word.
+     */
+    save: (value: TValue) => Promise<unknown>;
+    /** Whether a draft is still the saved value. Defaults to comparing as JSON. */
+    isEqual?: (a: TDraft, b: TDraft) => boolean;
+};
+/** Marks a field editable in place, typed end to end: draft → schema → save. */
+export declare function editInPlace<TDraft, TValue = TDraft>(options: EditInPlaceOptions<TDraft, TValue>): EditInPlace;
+export declare const EditInPlaceContext: import("react").Context<EditInPlaceStore | null>;
+export {};