@tristan2828/ui-foundation 3.12.0 → 3.14.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

@@ -168,7 +168,10 @@ is a filled-in example while the Widgets demo is still here).
      `src/routes/<entity>/<entity>-schema.ts` (zod schema mirroring
      `<Entity>Create`/`<Entity>Update`, plus the form ↔ wire conversion
      functions — see `widgetToFormValues`/`formValuesToWidgetCreate` for
-     the shape)
+     the shape. A Markdown long text is checked with `refine`, never
+     trimmed, like Widget's `description`: a trim rewrites text nobody
+     touched, a leading indent that makes a code block or the text's
+     own ending)
    - `src/routes/widgets/widget-format.ts` →
      `src/routes/<entity>/<entity>-format.ts` (the lookups and formatters
      both the columns and the view render values with: badge variant maps,
@@ -189,6 +192,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 +212,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 +274,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 +285,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 +405,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 +434,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 +447,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,14 @@ 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. Pattern 19 (stage circle)
+and the multi-value variant of 4, the dependency list in 10 and the
+pressed icon in 15 were each built for a real app's screen first; the
+package's Storybook renders them (`app/StageCircle`,
+`patterns/CellPatterns`), and its checks pin their accessibility and
+contrast in both themes. 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
@@ -109,6 +114,63 @@ narrow.
   cell, absent in an isolated Storybook story.
 - Encode the value in the glyph's **shape** (solid / half / slashed /
   dashed), not its colour.
+- **Give the trigger a focus ring**
+  (`rounded-sm outline-none focus-visible:ring-3 focus-visible:ring-ring/50`):
+  it's focusable, and a span has none of its own.
+
+### Several values: the icons side by side, every name in one tooltip
+
+A multi value (several categories on one record) where each value has
+its own icon and colour slot, and the column is narrow. The package's
+Storybook renders it (`patterns/CellPatterns`, "Icons with one tooltip").
+
+```tsx
+// values: the row's categories, `undefined` for one still loading.
+const names = values.map((value) => value?.name ?? '…').join(', ')
+if (values.length === 0) return emptyCell
+
+<Tooltip>
+  <TooltipTrigger
+    render={
+      <span role="img" aria-label={names} tabIndex={0}
+        className="inline-flex items-center gap-1 rounded-sm outline-none focus-visible:ring-3 focus-visible:ring-ring/50" />
+    }
+  >
+    {values.map((value, index) => {
+      if (!value) return <span key={index} className="text-muted-foreground">…</span>
+      const Icon = CATEGORY_ICON[value.icon]
+      return <Icon key={value.id} className={`size-4 shrink-0 ${CATEGORY_COLOR[value.color]}`} />
+    })}
+  </TooltipTrigger>
+  <TooltipContent>{names}</TooltipContent>
+</Tooltip>
+```
+
+- **One tooltip on the whole group**, listing every name in the record's
+  order ("Home, Finance"), not one per icon: one tab stop per cell, and
+  the names read as one value.
+- **The trigger is the `role="img"` span**, named by that same list. The
+  icons inside are presentational (children of an `img`), so they need no
+  `aria-hidden` of their own. Read-only: never a button.
+- **Each icon tinted with its value's colour slot**
+  ([`design-language.md`](design-language.md) "Categorical colour"), the
+  icon's shape telling values apart in greyscale.
+- **A value still loading shows "…"**, in the cell and in the names,
+  never a bare id.
+- **Where there's room** (the record's view), each icon sits beside its
+  name instead (pattern 2 per value, in a `flex flex-wrap gap-x-3 gap-y-1`
+  list), with no tooltip.
+
+**Testing note.** With several tooltips on a page, one that's closing
+stays in the DOM for a moment beside the one opening. A spec that reads
+the open tooltip must select `[data-slot=tooltip-content][data-open]`;
+the bare `[data-slot=tooltip-content]` can match the closing one, and
+reads the wrong text:
+
+```ts
+await page.getByRole('img', { name: 'Home, Finance', exact: true }).focus()
+await expect(page.locator('[data-slot=tooltip-content][data-open]')).toHaveText('Home, Finance')
+```
 
 ## 5. Enum → tone-mapped badge
 
@@ -116,6 +178,11 @@ A many-valued enum that collapses to good / neutral / bad. **The grouping
 is the decision, not the style** — see
 [`design-language.md`](design-language.md#mapping-an-enum-to-tones).
 
+An **ordered** status (a lifecycle every record moves through toward
+*done*) reads better as a stage circle beside the word (pattern 19);
+the tone badge stays right for a status with no order, or one whose end
+isn't *done*.
+
 Keep a separate short-label map when the API strings are full sentences
 (`"Yes – Full Crossplay"` → `Full`): read once in a dropdown they're right,
 read down 25 rows under a column header they're noise.
@@ -232,6 +299,40 @@ A one-to-many value (`★ 4.7 (3)` opening a per-person breakdown).
   can't be sorted server-side without a backend change
   (`enableSorting: false`).
 
+### A second example: what a row depends on
+
+The records a row waits on (parts it needs, a date that has to pass,
+other records that have to finish), summarised in the cell, listed in
+the popover. The package's Storybook renders it
+(`patterns/CellPatterns`, "Dependency list").
+
+- **The cell: a computed summary.** "Ready" when nothing holds the row,
+  else the count of what does ("1 hold", "2 holds"). Compute it where the
+  data is: the backend, when the column sorts or filters on it.
+- **The popover: every related record, grouped by kind**, each kind
+  under a small heading (`type-caption text-muted-foreground`) in its own
+  labelled group, in a fixed order. Each record keeps its kind's glyph
+  (`aria-hidden`, beside the name), so the kinds stay apart in
+  greyscale.
+- **Held reads dark, with its reason; clear reads muted.** A held record
+  is `text-foreground` with why after its name ("Bulb: unavailable",
+  "Delivery day: hasn't happened", or the blocking record's status);
+  a clear one is `text-muted-foreground` with a visually hidden ": clear",
+  so a screen reader hears the state the colour shows. No tone: a hold
+  is the normal state of waiting, not an error, and the count already
+  says how many.
+- **Name the popup**: `<PopoverContent aria-label={`What ${name} depends on`}>`.
+  It's a `dialog`, and axe fails one with no name.
+- **A row that links nothing has nothing to open**: render the summary as
+  plain text (`<span>Ready</span>`), not a button. A button that opens an
+  empty popover is a dead end.
+- **The trigger reads as the value**, with a dotted underline
+  (`underline decoration-dotted underline-offset-4`) and a focus ring,
+  so it looks openable without becoming a column of buttons.
+- The trigger's name starts with the summary it shows
+  (`aria-label={`${summary}: what ${name} depends on`}`), so it's still
+  found by its visible text, and says which row.
+
 ## 11. Number or currency — *Unproven*
 
 A count, a quantity, a price.
@@ -358,6 +459,91 @@ now", "happened"). Widget's In Stock column is the reference
 - **Cost:** one click changes data, with no confirmation. Only for values
   that are cheap to flip back; never for anything destructive.
 
+### A variant: a pressed icon inside another value's cell
+
+A yes/no that belongs to another value rather than having a column of
+its own: a "focus" flag that only exists while the status is "doing", a
+"pinned" mark on an open item. It's a small icon button inside the owning
+value's cell, beside its word. The package's Storybook renders it
+(`patterns/CellPatterns`, "Pressed icon in a cell").
+
+**Pick it over the Switch** when the yes/no only means something while
+another value allows it, or when a Switch and its words would crowd that
+value's cell. A yes/no that stands on its own keeps its own column and
+the Switch.
+
+```tsx
+// Off: faint. On: the destructive text tone, filled. The primitive's
+// pressed background is dropped: the icon carries the value.
+const FLAG_TOGGLE_CLASS =
+  'text-muted-foreground/80 hover:text-muted-foreground aria-pressed:bg-transparent ' +
+  'aria-pressed:text-destructive-text'
+
+// <entity>-focus-toggle.tsx, rendered inside the status cell
+export function FocusToggle({ item }: { item: Item }) {
+  const save = useSaveItemField(item.id) // useRecordUpdate, like Widget's useSaveWidgetField
+  return (
+    <>
+      <Toggle size="icon-xs" pressed={item.focus} aria-label={`Focus: ${item.name}`}
+        className={FLAG_TOGGLE_CLASS} onPressedChange={(focus) => save.mutate({ focus })}>
+        <FlagIcon className="group-aria-pressed/toggle:fill-current" />
+      </Toggle>
+      <span className="inline-flex size-3.5 shrink-0">
+        {save.isPending && <Spinner aria-label="Saving" className="size-3.5 text-muted-foreground" />}
+      </span>
+    </>
+  )
+}
+
+// The status cell: the word stays, the toggle only while the status allows it.
+<span className="inline-flex items-center gap-1.5">
+  <StageCircle {...STATUS_STAGE[item.status]} />
+  {STATUS_LABEL[item.status]}
+  {item.status === 'doing' && <FocusToggle item={item} />}
+</span>
+```
+
+- **`Toggle` from the package** (`/ui/toggle`, shadcn's, on Base UI), at
+  `size="icon-xs"`: a 24px target, the smallest WCAG 2.2 allows, which
+  keeps the row's height. It's `aria-pressed` by itself.
+- **Named for the row, not the state**: `Focus: <record name>`. The
+  pressed state is announced on its own; a name that changes with it
+  ("Unfocus") reads twice.
+- **The icon carries the value.** Filled when on
+  (`group-aria-pressed/toggle:fill-current`), outline when off, so it
+  reads in greyscale. Pick a glyph with an area to fill (`FlagIcon`,
+  `StarIcon`, `PinIcon`), not a line.
+- **Faint, but never below 3:1.** Off is `text-muted-foreground/80`, the
+  faintest step that still clears WCAG's 3:1 non-text minimum in light
+  mode (3.2:1; dark is 5.2:1). `/70` measures 2.7:1, and a control a
+  reader can't see fails them. Hover lifts it to full
+  `muted-foreground`. axe doesn't measure icons, so the package's
+  Storybook glyph check does.
+- **Tone: `destructive-text`, read as "flagged", not "error".** A flag
+  claims attention ahead of the rest of the row, and the destructive
+  tone is the one with that pull. The other tones are taken where it
+  sits: `info` is the in-progress status it belongs to (an info flag
+  beside an info stage disappears), `success` reads as done, and
+  `warning` says something may be wrong. It stays honest because it's
+  rare (a flag nearly every row carries is the "about a third" limit
+  broken) and because no word beside it says error. If a flag is common,
+  or does mean "something's wrong", it's an enum with a verdict
+  (pattern 5) instead.
+- **It saves on its own, through `useRecordUpdate`**, like the Switch: the
+  new value shows at once, and a refusal (a cap the server enforces)
+  puts it back with the toast giving the server's reason. The hook does
+  both; add nothing.
+- **The "Saving" slot is always there**, after the toggle, so nothing
+  moves while it saves, and nothing is disabled.
+- **Only rendered while the owning value allows it.** When the status
+  moves on, the toggle goes; what the server does with the flag then (it
+  clears it, or keeps it for next time) is the plan's rule, and shows
+  through the record it returns.
+- **On the record's view** it's the same component beside the owning
+  value in the header, as a quick action (pattern 17): the plan names it
+  under `Quick actions`. There its name is the field's label alone
+  (`Focus`), like the view's other controls.
+
 ## 16. Title linking to the record's view
 
 The column that names a record (its name or title), when the entity has a
@@ -397,23 +583,25 @@ 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 `yes/no` that belongs to another value (pattern 15's variant), beside that value in the header | The same pressed icon `Toggle` as in the table's cell | The field's label: `Focus` |
 | 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
@@ -452,12 +640,176 @@ 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.
+
+## 19. Stage circle for an ordered status
+
+A status that's an ordered lifecycle (each record moves through the same
+stages, in the same order, toward one that means *done*), with one or
+more exit states off the side. A small circle beside the word fills as
+the record moves on. The package ships it: `StageCircle`, rendered with
+every stage and tone in its Storybook (`app/StageCircle`).
+
+| Stage (`stage`) | Drawn as | Say it for |
+|---|---|---|
+| `0` | a dashed outline | the first stage: not started |
+| `1`, `2`, `3` | the outline with a quarter, a half, three quarters filled | a stage under way, in order |
+| `'complete'` | a solid circle with a tick | the final stage: done |
+| `'exit'` | the outline, struck through | off the lifecycle: dropped, cancelled |
+
+```tsx
+import { StageCircle, type StageCircleStage, type StageCircleTone } from '@tristan2828/ui-foundation'
+
+// <entity>-format.ts: typed by the enum, so a new value can't go unmapped.
+const STATUS_STAGE: Record<ItemStatus, { stage: StageCircleStage; tone?: StageCircleTone }> = {
+  idea: { stage: 0 },
+  considering: { stage: 1 },
+  doing: { stage: 2, tone: 'info' },
+  done: { stage: 'complete', tone: 'success' },
+  dropped: { stage: 'exit' },
+}
+
+cell: ({ getValue }) => {
+  const status = getValue() as ItemStatus
+  return (
+    <span className="inline-flex items-center gap-1.5">
+      <StageCircle {...STATUS_STAGE[status]} />
+      {STATUS_LABEL[status]}
+    </span>
+  )
+}
+```
+
+- **The word stays**, in plain `text-foreground`. The circle is
+  `aria-hidden`; the word is what's read, and what a reader who doesn't
+  know the shapes yet goes by.
+- **The shape carries the stage, in greyscale.** Dashed, filling, solid,
+  struck through: the stage reads from the shape alone, and the tone only
+  reinforces it.
+- **Tone it like pattern 5:** the stage in progress is `info` ("notice
+  this"), complete is `success`, and the rest stay `muted` (the default).
+  The tones are the `*-text` shades, so the circle clears 3:1 on the page
+  in both themes, measured by the package's glyph check. An exit is
+  muted: dropped is an end, not a failure. Give it `destructive` only if
+  the exit really is bad news (failed, rejected).
+- **Map the stages in order**, the first `0`, the final `'complete'`, the
+  ones between `1`–`3` in order. Two middle stages fill a quarter and a
+  half; three, up to three quarters. More than three stages between
+  first and done is more than a fill can tell apart: use the tone badge.
+- **Stage circle or tone badge (pattern 5)?** The circle is for an
+  *ordered* status: every record goes the same way, and "how far along
+  toward done" is the question. A status with no order (`active` /
+  `paused` / `blocked`), or one whose end isn't *done*, keeps pattern 5.
+  Widget's Status is the second kind: `draft` → `active` → `archived` is
+  an order in time, but `archived` is retirement, not completion, and its
+  good state is the middle one. A tick on `archived` would say "done"
+  where nothing was finished, so it stays a tone badge.
+- **On the record's view** it's the same markup in the header, beside the
+  title; editing the status in place (pattern 18) wraps it in
+  `<EditableValue>` like a badge.
+- **Cost:** a reader learns the shapes once. Until then the word does the
+  work, which is why it stays.

package/conventions/docs/design-language.md

@@ -82,6 +82,24 @@ Two rules that keep this honest:
   greyscale screenshot and a printed page all lose it. The label text
   usually carries the meaning already; where a cell is a glyph rather than
   a word, vary the *shape* (filled / half / slashed) too, not just the hue.
+  The package's `StageCircle` does this for an ordered status: dashed,
+  filling, solid with a tick, struck through
+  ([`cell-patterns.md`](cell-patterns.md) pattern 19).
+
+## Glyphs and icons: 3:1
+
+An icon that carries meaning on its own (a stage circle, a category's
+icon, a pressed flag) must clear WCAG's **3:1 non-text minimum** against
+the background behind it, in both themes. axe measures text only, so the
+package's Storybook has a glyph check of its own: every `<svg>` in its
+design-language stories, its ink (with any opacity modifier painted over
+its background) against what's behind it. Every `*-text` tone, every
+category slot and `muted-foreground` clear it as they are. An opacity
+modifier is where it goes wrong: `text-muted-foreground/80` is the
+faintest step that still clears it in light mode (3.2:1), and `/70`
+doesn't (2.7:1). A deliberately faint icon that carries nothing on its
+own (an "empty" star beside a rating's filled ones, pattern 9) may go
+lower; say so in a comment.
 
 ## Categorical colour
 
@@ -119,10 +137,11 @@ Four things about them:
   `text-foreground`, so readability never depends on the hue. A slot used
   as a background needs its own contrast check, which nothing here does
   for you.
-- **Nothing re-measures them automatically.** All eight clear the 3:1
-  non-text minimum in both themes (measured, recorded in `theme.css`), but
-  axe checks text contrast, not icon contrast — so a change to these
-  values is not caught by any gate.
+- **The glyph check re-measures them.** All eight clear the 3:1
+  non-text minimum in both themes (recorded in `theme.css`). axe checks
+  text contrast, not icon contrast, so the package's Storybook glyph check
+  draws an icon in each slot (`patterns/CellPatterns`, "Icons with one
+  tooltip") and fails a change that takes one below 3:1.
 
 If you find yourself wanting a ninth, that is usually a sign the column
 should be showing a shape or a label rather than more colours.