portal-mojo 0.1.0

package/docs/grouping-and-fmt.md

@@ -0,0 +1,98 @@
+# grouping helpers + formatters
+
+## groupBy* helpers
+
+```ts
+import { groupByDay, groupByField, groupByRecency, groupByBoolean } from 'portal-mojo/ui';
+```
+
+Each returns `{groupBy, groupHeaderLabel}` — spread straight into
+ModelTable props: `{...groupByRecency<User>('last_activity')}`. Keys are
+STABLE bucket ids (sort-ordered where it matters); labels format
+separately. A null key = ungrouped tail (no header; the prior section
+continues). All date helpers parse through `date/fns detectTemporal`, so
+they accept **every** shape django-mojo emits: epoch seconds, epoch
+milliseconds, either as a numeric string (JSONField metadata routinely
+carries these), `'YYYY-MM-DD'`, `'YYYY-MM'`, `'YYYY'`, full ISO with `Z` or
+an offset, IANA-tailed wall times, and `Date`. A 4-digit numeric string is
+read as a **year**, never an epoch. Anything unrecognizable degrades to the
+fallback — a formatter never throws.
+
+| Helper | Buckets |
+|---|---|
+| `groupByDay(field \| accessor)` | local `YYYY-MM-DD`; labels Today / Yesterday / Apr 25 / Dec 19, 2025 |
+| `groupByRecency(field)` | Today / Yesterday / This week / This month / Earlier this year / Older — keys sort so `-date` order reads top-down |
+| `groupByField(field, {labels?, format?, fallback?})` | categorical on `String(raw)`; `labels` wins over `format`; `fallback` names the empty bucket (default: tail). `0`/`false` DO bucket |
+| `groupByBoolean(field, {trueLabel?, falseLabel?})` | binary; string-false forms (`'false','0','no','off'`) coerce false; missing → tail |
+
+Align the grouped field with the table's sort — grouping runs in render
+order, so a mismatched sort repeats headers per key change (defined
+behavior).
+
+## fmt
+
+```ts
+import { fmt } from 'portal-mojo/ui';
+```
+
+The complete `DataFormatter.js` FUNCTION set, typed. Deliberately absent:
+the **pipe-string parser** (`"filesize|muted"` — do-not-recreate: it defeats
+the type checker and was the source's silent-failure vector) and the
+**HTML-emitting** formatters (badge/avatar/linkify/clipboard/tooltip/status)
+— those are components, not formatters.
+
+### Dates
+
+| Fn | Notes |
+|---|---|
+| `fmt.date(v, fallback='—')` / `fmt.datetime(v, fallback='—')` | `MM/DD/YYYY` / `Mon D, YYYY h:mm` — accepts **epoch seconds** (the django-mojo wire shape), ms, ISO, Date |
+| `fmt.relative(v, fallback='Never')` | "3 weeks ago" style |
+| `fmt.relativeShort(v, fallback='—')` | compact age for chips: `now` / `5h` / `3d` / `3w` / `2mo` / `1y`. **Magnitude only** — a future date reads the same as a past one (use `relative` when direction matters). Source boundaries kept (`>`, not `>=`): 7d is `7d`, 8d is `1w` |
+
+### Numbers
+
+| Fn | Notes |
+|---|---|
+| `fmt.number(v, decimals=0, fallback='—')` | thousands separators: `1234567` → `1,234,567`. *Deviation:* source defaulted to 2 decimals; portal columns are counts |
+| `fmt.currency(v, code='USD', {unit, decimals, fallback})` | `129900` → `$1,299.00`. **Input is CENTS by default** — django-mojo stores money as integer minor units (`cents_to_currency`) so it never touches a float; pass `{unit:'major'}` for a dollars value or a zero-decimal currency (JPY). *Deviation:* arg 2 is an ISO **code**, not a symbol — the source's own callers passed `currency("EUR")` and got `EUR1,299.00`. An unknown code warns once and falls back to USD |
+| `fmt.percent(v, decimals=0, multiply=true, fallback='—')` | `0.856` → `86%`; `multiply=false` when the value is already a percentage |
+| `fmt.compact(v, decimals=1, fallback='—')` | `1234` → `1.2K`, `3400000` → `3.4M`. Uppercase K/M/B (source casing); caps at B, so `1e12` reads `1000.0B`. Below 1,000 the raw number passes through unseparated |
+| `fmt.filesize(v, binary=false, decimals=1, fallback='—')` | `1536` → `1.5 KB`; `binary` switches to 1024/`KiB`. Whole bytes stay integral (`999 B`); caps at TB. Negatives degrade readably (`-500 B`) |
+| `fmt.ordinal(v, suffixOnly=false, fallback='—')` | `3` → `3rd`, `11` → `11th`. *Deviation:* the suffix is computed on the absolute value, so `-1` → `-1st` (source made every negative `th`) |
+
+### Strings
+
+| Fn | Notes |
+|---|---|
+| `fmt.truncate(v, length=50, suffix='...', fallback='—')` | cuts to `length` **then** appends the suffix, so the result runs longer than `length` (source behavior) |
+| `fmt.truncateMiddle(v, size=8, replace='***', fallback='—')` | keeps both ends: `d41d***427e` — ids stay recognizable. `size` is the TOTAL kept, split in half |
+| `fmt.truncateFront(v, length=8, prefix='...', fallback='—')` | keeps only the TAIL: `...2eZvKY` |
+| `fmt.mask(v, char='*', showLast=4, fallback='—')` | all-but-last-4: `************1111`. Values no longer than `showLast` return intact. *Fixes a source bug:* `showLast:0` masked the string and re-appended it whole (`slice(-0)` is `slice(0)`) |
+| `fmt.slug(v, separator='-')` | **fallback is `''`**, not `—` (a slug of nothing is nothing). *Deviations:* accents fold to ASCII (`Café` → `cafe`, matching django-mojo's `strip_accents`) instead of being dropped (`caf`); the separator is regex-escaped — the source interpolated it raw, so `slug(v,'.')` misbehaved and `slug(v,'')` threw on an empty quantifier |
+| `fmt.phone(v, fallback='—')` | **DISPLAY ONLY.** E.164 (`+15555550142`) stays the wire shape — django-mojo REJECTS pretty formats on save, so never round-trip this into a field. US 10/11-digit → `(555) 555-0142` / `+1 (555) 555-0142`; anything else (a real international number) is returned trimmed and unchanged. *Deviation:* the source stripped the leading `+`, turning valid E.164 into digit soup. No `<a href="tel:">` — links are components |
+
+### Duration + booleans
+
+| Fn | Notes |
+|---|---|
+| `fmt.duration(v, unit='ms', {short, precision, fallback})` | `8040000` → `2h 14m`; `duration(8040,'s')` is the same. `unit` ∈ `ms\|s\|m\|h\|d` (unknown → `ms` + one `console.warn`). `precision` (default 2) caps the unit count; sub-second values report `500ms`. *Deviations:* short form is the DEFAULT (source: long — get it with `{short:false}` → `2 hours 14 minutes`) and its parts are space-separated (source: `2h14m`) |
+| `fmt.yesNo(v, {yes, no, fallback})` | `Yes`/`No`; string-false forms (`'false','0','no','off'`) and empty arrays/objects read false — the same coercion table as `groupByBoolean`. **null/undefined/`''` → `—`**: unset is not the same answer as "No" |
+
+### Tone
+
+| Fn | Notes |
+|---|---|
+| `fmt.initials(name)` | 1–2 letters; null-safe (`'?'` for empty — live rows carry `display_name: null`) |
+| `fmt.inferTone(value)` | status text → Badge tone ('active'→success, 'banned'→danger, booleans, …) |
+
+Formatters NEVER throw on bad input — they degrade (rule: a formatter is
+the last thing allowed to take down a row). Every one is null/undefined-safe,
+parses strictly (`"12 items"` is NOT 12 — it degrades, unlike the source's
+`parseFloat`), and formats at a fixed `en-US` locale rather than the
+browser's. The trailing `fallback` param (or `opts.fallback`) overrides the
+`—`; pass `''` when composing strings rather than filling a cell.
+
+Live gallery: **Develop → Components → Formatters**.
+
+`Badge`: `<Badge tone="success|warning|danger|info|muted|primary">` from
+`portal-mojo/ui` — the standard status chip.

package/docs/idioms.md

@@ -0,0 +1,112 @@
+# UX idioms — armed button · undo toast · progress toast
+
+```ts
+import { ArmedButton } from 'portal-mojo/ui';          // component
+import { toast, undoToast, progressToast } from 'portal-mojo/ui';
+// toast.undo === undoToast · toast.progress === progressToast
+```
+
+Ported from maestro's workspaces portal (`workspaces/js/dom.js`), these three
+are the house grammar for **action feedback by reversibility**:
+
+| The action is… | Use | Never |
+|---|---|---|
+| Irreversible, no input needed | `<ArmedButton>` two-step | a confirm dialog |
+| Irreversible, needs input (a reason) | `formModal` flow | armed button (it can't collect input) |
+| Reversible | act IMMEDIATELY + `toast.undo` | a confirm dialog |
+| Long-running | `toast.progress` handle | fire-and-forget with a success toast at the end |
+
+Live demo: portal → Develop → Components → **UX idioms**. First real
+consumers: ApiKeysPage (revoke = armed, disable = undo), UserDetail
+(revoke-all-sessions = armed).
+
+## ArmedButton
+
+```tsx
+<ArmedButton
+    label="Revoke key"
+    armedLabel="Click again — token dies now"
+    onConfirm={() => revoke.mutateAsync({ id })}   // may be async
+    icon="bi-trash"          // optional, resting state only
+    className="btn-compact"  // appended to `btn armed-btn`
+    disarmMs={6000}          // auto-disarm window (source parity: 6s)
+    title="…"                // defaults to string labels
+    disabled={false}
+/>
+```
+
+Behavior contract (dom.js `armedButton` parity):
+
+- First click **arms**: danger fill, warning icon, `armedLabel` shown. The
+  armed label MUST name the blast radius ("Click again — signs out every
+  device"), not repeat the verb.
+- Second click disarms first, then awaits `onConfirm`. Re-clicks while the
+  promise is pending are ignored (button disables).
+- **Auto-disarm** after `disarmMs`; `Escape` disarms; unmount disarms (state
+  dies with the node — a re-render that drops the button can never leave a
+  live trigger). Fail-safe cost is one extra click, never an unintended fire.
+- Clicks `stopPropagation()` — safe inside clickable rows / expand rows.
+
+Styling: `apps/portal/src/theme/idioms.css` — `.armed-btn` (rest) /
+`.armed-btn.is-armed` (armed, pulsing; static under
+`prefers-reduced-motion`). Tokens only, both themes; the dark theme swaps
+the armed text color for contrast against the light --bad.
+
+## toast.undo / undoToast
+
+```ts
+const handle = toast.undo('Key disabled', () => reenable(), { timeout: 6000 });
+handle.dismiss(); // optional early resolution
+```
+
+- **The action has already happened** when the toast shows — do the mutation
+  first, then offer Undo. This replaces `confirm()` for reversible actions.
+- Clicking **Undo** dismisses at once and calls `onUndo`. Otherwise the card
+  auto-dismisses after `timeout` (default 6000ms) and the action stands.
+- `onUndo` typically fires the inverse mutation; surface ITS failure with a
+  normal `toast.error` — the undo toast itself is done by then.
+
+## toast.progress / progressToast
+
+```ts
+const p = toast.progress('Uploading export.csv…', { onCancel: () => abort() });
+p.update(42);          // clamped + rounded to 0–100
+p.finalizing('Finishing upload'); // → 100% + spinner, cancel hidden; still unsettled
+p.done('Uploaded');    // → 100% + ✓, auto-removes after 1.4s
+p.fail('Cancelled');   // → red + ✕, auto-removes after 5s
+p.remove();            // immediate removal
+```
+
+- **Persistent**: never auto-dismisses while active — the caller drives it to
+  `done` / `fail` / `remove`. After the first of those, the handle is settled
+  and later calls no-op.
+- `onCancel` renders a ✕ **only while active**. Clicking it calls `onCancel`
+  and nothing else — the CALLER aborts its operation and then settles the
+  toast (usually `fail('Cancelled')`). Cancel is a request, not a dismissal.
+- `finalizing()` is additive and non-settling: it shows a spinner at 100% and
+  removes cancellation while an authoritative server read or consumer
+  callback completes. The caller must still finish with `done` or `fail`.
+- Basic toasts stay capped at 5; undo/progress cards are exempt from the cap
+  (evicting a live progress bar would orphan the operation's only indicator).
+
+## Invariants
+
+- All three render through the one `<ToastHost />` / store — mount nothing
+  new. Every existing `toast.success/error/info/warning` behavior (3.5s life,
+  newest-last, cap of 5) is byte-for-byte unchanged.
+- Handles are safe to call after settlement/dismissal — every method no-ops
+  rather than throwing or resurrecting a card.
+- `ArmedButton` is a plain `<button>` — no portal, no dialog; it composes
+  with rows, expand panels and modals without z-index ceremony.
+
+## Pitfalls
+
+- Don't pair `ArmedButton` with a follow-up `modal.confirm` — the arming IS
+  the confirmation; stacking both is the friction the idiom removes.
+- Don't `toast.undo` an action you haven't performed yet ("undo" that
+  actually means "cancel a pending thing" is a lie — use the progress
+  toast's cancel for that).
+- Don't reuse a settled progress handle for a second operation — mint a new
+  one per run.
+- The undo window is UX grace, not a transaction: if the inverse mutation
+  can fail, handle its rejection (the demo and ApiKeysPage show the shape).

package/docs/image-editor.md

@@ -0,0 +1,101 @@
+# Image editor
+
+Import from `portal-mojo/ui`:
+
+```tsx
+import { ImageEditor, imageEditorModal, type ImageEditorResult } from 'portal-mojo/ui';
+```
+
+`ImageEditor` is the dependency-free crop/transform/filter editor. It accepts a
+controlled `source` (`Blob`, `File`, or URL), reports only through `onSave`, and
+never triggers a browser file download. A URL source is fetched before decode:
+same-origin requests include same-origin credentials, while cross-origin URLs
+remain subject to CORS and receive no credentials. Source/capability URLs are
+never echoed in editor errors. `imageEditorModal(source, options)` is the
+awaitable native dialog form: it resolves an `ImageEditorResult` on save and
+`null` on Cancel, Escape, backdrop dismissal, or owner-signal abort.
+
+```ts
+interface ImageEditorResult {
+  blob: Blob;                 // image/png, alpha preserved
+  filename: string;
+  width: number;
+  height: number;
+  cropData: CropData | null;  // logical pixels at the crop's input stage
+  operations: readonly ImageEditorOperation[];
+}
+```
+
+```tsx
+const result = await imageEditorModal(file, {
+  startMode: 'crop',
+  filename: file.name,
+  crop: { aspectRatio: 1, cropAndScale: { width: 200, height: 200 } },
+});
+if (result) upload(new File([result.blob], result.filename, { type: 'image/png' }));
+```
+
+Options are `filename`, `startMode`, `modes`, `crop`, `initialOperations`,
+`maxHistory` (1–20), and `saveText`. Modal use additionally accepts `title`,
+`size` (`sm`, `md`, or `lg`), and an `AbortSignal` as `signal`; abort resolves
+the modal with `null`. Embedded use additionally supplies `onSave`, optional
+`onCancel`, `disabled`, and `onBusyChange`.
+
+## Low-level exports
+
+The framework-free math and raster contracts are intentionally public from the
+same `portal-mojo/ui` subpath for non-React composition and deterministic
+verification:
+
+- Geometry/state types include `ImageSize`, `ImagePoint`, `ImageRect`,
+  `CropData`, `CropOptions`, `TransformState`, `FilterState`,
+  `ImageEditorOperation`, and `ImageEditorSnapshot`. The corresponding defaults,
+  limits, crop handles, presets, and filter order are exported constants.
+- Geometry helpers cover canvas/image mapping, crop initialize/constrain/move/
+  resize, transform clamp/rotate/zoom/output sizing, filter composition,
+  operation output/crop inspection, and immutable history commits.
+- Raster helpers expose `PixelSurface`, `filterPixels`,
+  `applyOperationsToPixels`, `decodeImageSource`, `drawPixelSurface`,
+  `pixelSurfaceToBlob`, and `renderImageOperations`. `decodeImageSource`, canvas
+  drawing, and Blob encoding require browser APIs; callers that retain a
+  returned `DecodedImage` must call its `dispose()`.
+
+These helpers operate on logical pixels and do not mount UI, upload Files,
+persist state, or initiate a browser download. `decodeImageSource` is the one
+exception that performs the URL fetch described above.
+
+## Composition and history
+
+Operations are immutable and chronological. Transform creates a logical
+full-resolution output canvas; pan is measured in logical image pixels and is
+unchanged by a preview resize. Crop consumes the current working bitmap in
+source-pixel coordinates and either retains its natural crop dimensions or
+emits exact `cropAndScale` dimensions. Filters consume the current full working
+bitmap after every prior operation. The preview's CSS size and device-pixel
+ratio never participate in export.
+
+Apply commits one snapshot. Switching modes commits only a dirty mode. Pointer
+drags and slider movement update one draft, so they coalesce into one history
+entry. Undo/redo crosses committed operations, a divergent commit truncates
+redo, Reset returns to the decoded source, and at most 20 snapshots are kept.
+
+## Source-derived invariants
+
+- Crop defaults to the centered 80% box; the minimum is 50 source pixels.
+- Transform scale is clamped to 0.1–5 with the legacy 0.02 step; rotations
+  normalize to 0–359 degrees.
+- Filter defaults, preset values, and application order are carried from
+  web-mojo: brightness → contrast → saturation → hue → blur → grayscale →
+  sepia. Unknown modes/presets warn and fall back.
+- Invalid/non-finite ratios, dimensions, histories, and operations reject at
+  the React boundary. Decode/CORS/encoding failures use generic errors that do
+  not echo source or capability URLs and retain the prior decoded source and
+  history.
+- Owned object URLs and image bitmaps are released on replacement/unmount;
+  async decode/save work is generation guarded. PNG encoding is explicit and
+  preserves alpha. Crop overlays never enter the output bitmap.
+
+For image relations, `ImageField` can opt into `edit={{ crop: ... }}`. Editing
+runs before the existing upload queue: Cancel or editor failure keeps the
+selected original available, and no File id or owner attachment exists until
+the edited PNG File enters that queue.

package/docs/loading.md

@@ -0,0 +1,242 @@
+# Loaders — spinner · busy overlay · view loader · inline · Busy
+
+```ts
+import {
+    Spinner, ViewLoader, LoadingState, InlineLoader, Busy, LoadingOverlay,
+    busy, busyWhile, closeAllBusy, useDelayedFlag,
+    LOADING_DELAY_MS, BUSY_MIN_VISIBLE_MS, BUSY_TIMEOUT_MS,
+} from 'portal-mojo/ui';
+// LoadingState === ViewLoader (alias — reads better in a route's early return)
+```
+
+The "we're fetching / working" family. It **complements the skeleton
+silhouette**, which stays the default for anything whose shape is already
+known (see the decision table below). Live demo: portal → Develop →
+Components → **Loaders**. Styling: `apps/portal/src/theme/loading.css` —
+tokens only, both themes.
+
+Ported from web-mojo `src/core/views/feedback/BusyIndicator.js` (its only
+loading UI: a singleton frosted overlay behind `Modal.loading()` /
+`app.showLoading()`, used by ~30 admin call sites). Reference counting, the
+newest-message-wins label and the 30s watchdog are kept; the z-index
+arithmetic, the hardcoded light-theme palette and the show-on-the-same-tick
+behavior are not.
+
+## The anti-flash rule (the design idea)
+
+> **An indicator that appears for 80ms is worse than none.** It reads as a
+> glitch, and it makes fast software look broken.
+
+Every loader here is gated by `useDelayedFlag`:
+
+- nothing renders until the work has run **`LOADING_DELAY_MS` (200ms)** —
+  work that finishes inside that window produces no indicator at all;
+- the overlay, once up, stays at least **`BUSY_MIN_VISIBLE_MS` (400ms)**, so
+  it can't blink out either.
+
+Both are per-call overridable (`delay`, `minVisible`). `delay: 0` opts out —
+correct for demos and for a route that is *known* to be slow.
+
+```ts
+const show = useDelayedFlag(query.isFetching);              // 200ms default
+const show = useDelayedFlag(save.isPending, 400);           // number = delay
+const show = useDelayedFlag(active, { delay: 150, minVisible: 500 });
+```
+
+## Skeleton vs loader — which one
+
+| Situation | Use |
+|---|---|
+| Table rows, detail grids, card lists — **shape known** | **Skeleton** (`.skel` silhouette: `skel-avatar`, `skel-stack`, `skel-w-60`, `skel-pill`) |
+| A panel or route with nothing to show yet, shape unknown | `<ViewLoader label="Loading members…" />` |
+| One row / cell / field resolving on its own | `<InlineLoader />` |
+| A form or card whose own mutation is in flight | `<Busy active={save.isPending}>` |
+| Work the user must wait out (export, long save, batch) | `busy()` / `<LoadingOverlay>` |
+| Long work with a real percentage | `toast.progress` — see [idioms.md](./idioms.md) |
+| Background refresh of data already on screen | **Nothing** (or the toolbar refresh spin) |
+
+Rules of thumb: a skeleton **promises a shape**, so never render one for
+data whose shape you can't predict (a report, an export, a search that may
+return nothing). A loader **says work is happening**, so never render one
+over content that is already on screen and still valid — dim it (`<Busy>`)
+or leave it alone.
+
+ModelTable, CollectionMultiSelect and DetailView already use skeletons and
+should keep doing so. Nothing in this family replaces them.
+
+## Spinner
+
+```tsx
+<Spinner />                       {/* md, decorative */}
+<Spinner size="xs" />             {/* xs | sm | md | lg, or a pixel number */}
+<Spinner size={44} />
+<Spinner size="sm" label="Refreshing" />   {/* the ONLY indication → named */}
+```
+
+| Prop | Type | Notes |
+|---|---|---|
+| `size?` | `'xs' \| 'sm' \| 'md' \| 'lg' \| number` | 12 / 15 / 20 / 30px, or an explicit diameter. Unknown value → `'md'` **with a `console.warn`** (once per bad value). |
+| `label?` | `string` | Omit when visible text sits beside it (then it renders `aria-hidden`). Pass it only for an icon-only affordance. |
+| `className?` | `string` | Appended after `mojo-spinner …`. |
+
+The ring is drawn in `currentColor`, so it inherits its context: white inside
+`.btn-primary`, `--accent` inside a loader card, `--mute` in a table cell. No
+color prop, and none needed.
+
+## busy() — the blocking full-screen overlay
+
+```ts
+const b = busy('Rebuilding index…');
+try { await rebuild(); } finally { b.close(); }
+
+// Preferred — a throw can never strand the overlay:
+await busyWhile('Preparing export…', () => mojoDownload(endpoint, params, 'csv'));
+```
+
+| API | Signature |
+|---|---|
+| `busy` | `(label?: string, opts?: BusyOptions) => BusyHandle` |
+| `busyWhile` | `<T>(label: string, run: () => Promise<T> \| T, opts?: BusyOptions) => Promise<T>` |
+| `closeAllBusy` | `() => void` — escape hatch for an error boundary / hard reset |
+| `BusyOptions` | `{ delay?: number; minVisible?: number; timeout?: number }` |
+| `BusyHandle` | `{ close(): void; setLabel(label: string): void; isActive(): boolean }` |
+
+- **Imperative on purpose**, matching `modal.*` / `toast.*`: call it from any
+  handler, or from non-component code (client interceptors, route guards).
+  There is **no host component to mount** — nothing to wire into `App.tsx`.
+- **Reference-counted by ticket.** Nested calls compose; the newest live
+  ticket's label is displayed, and closing it falls back to the previous
+  label rather than leaving stale text. `close()` is idempotent.
+- **Watchdog:** a ticket left open longer than `timeout` (default 30s)
+  force-closes with a `console.error` naming the label. A caller that throws
+  outside a `finally` can never wedge the app behind an overlay nobody can
+  dismiss. `timeout: 0` disables it for a legitimately unbounded operation.
+- `<LoadingOverlay active label />` is the declarative binding to the same
+  overlay (renders nothing into the React tree). Changing `label` swaps the
+  text **without restarting the delay**.
+
+### Why a `<dialog>`, and what "blocking" means
+
+The overlay is a native `<dialog>` opened with `showModal()` — a member of
+the browser **top layer**, exactly the reasoning behind
+[Popover](./popover.md):
+
+- it paints **above open modals and drawers** with no z-index arithmetic
+  (web-mojo needed `ModalView.getFullscreenAwareZIndex().modal + 1000`);
+- the rest of the document goes **inert** — pointer *and* keyboard. A
+  `pointer-events: none` scrim leaves <kbd>Tab</kbd> working, which is not
+  blocking, it just looks like it;
+- **Escape is swallowed** (`cancel` → `preventDefault`): dismissible only by
+  the caller, because the operation keeps running either way;
+- focus returns to the pre-open element on close (native `<dialog>`
+  behavior), so a save started from a toolbar button lands you back on it.
+
+A modal opened *after* the overlay stacks above it (top-layer promotion
+order) — that is deliberate: an error modal raised mid-operation must be
+readable.
+
+## ViewLoader / LoadingState
+
+```tsx
+if (query.isPending) return <ViewLoader label="Loading members…" />;
+
+<ViewLoader size="lg" label="Loading dashboard…" hint="First load builds the cache." />
+```
+
+| Prop | Type | Notes |
+|---|---|---|
+| `label?` | `string` | Default `'Loading…'`. Say **what** — "Loading members…" beats "Loading…". |
+| `hint?` | `ReactNode` | Second line for the honestly slow. |
+| `size?` | `'sm' \| 'md' \| 'lg'` | Reserved height 88 / 168 / 280px + spinner size. Unknown → `'md'` with a `console.warn`. |
+| `delay?` | `number` | Default 200ms. |
+| `className?` | `string` | |
+
+Before the delay elapses it renders an **empty box of the same height**
+(`aria-hidden`), not `null`: a fast panel pops in with no layout jump, and a
+slow one doesn't shove content down when the spinner appears.
+
+## InlineLoader
+
+```tsx
+<InlineLoader />                          {/* "Loading…" */}
+<InlineLoader label="checking sessions…" />
+<InlineLoader label="" />                 {/* bare spinner, still announced */}
+```
+
+Small inline row: `label?`, `delay?`, `className?`. Renders `null` before the
+delay (inline text needs no reserved height).
+
+## Busy — dim + disable a region
+
+```tsx
+<Busy active={save.isPending} label="Saving…">
+    <SchemaForm … />
+</Busy>
+```
+
+| Prop | Type | Notes |
+|---|---|---|
+| `active` | `boolean` | A mutation's `isPending`. |
+| `label?` | `string` | Caption under the veil spinner. |
+| `delay?` | `number` | Anti-flash for the **dim only**. |
+| `spinner?` | `boolean` | Default true; false = bare dim. |
+| `className?` | `string` | Appended after `mojo-dim`. |
+
+**Blocking is immediate, dimming is delayed.** The content wrapper gets the
+native `inert` attribute the instant `active` goes true — no double-submits,
+no tabbing into a form mid-save — while the visual dim waits out the
+anti-flash window so a 60ms save doesn't strobe the panel. That split is the
+whole reason this wrapper exists; `pointer-events: none` alone would leave
+the keyboard path open.
+
+**Focus survives it.** Going inert blurs whatever was focused inside (the
+field the user was in when they hit save), so `Busy` remembers that element
+and restores focus when `active` goes false — but only if focus is still
+parked on `<body>`, i.e. nothing else claimed it. If the user deliberately
+clicked away mid-save, they keep where they went.
+
+## Accessibility contract
+
+- `Spinner` is `role="img"` + `aria-label` when named, `aria-hidden`
+  otherwise — **never** a live region. Nesting live regions double-announces.
+- The overlay dialog carries `aria-busy="true"` and an `aria-label` mirroring
+  the label; the label element inside is `role="status"`, so a mid-flight
+  `setLabel('Finalizing…')` is announced politely.
+- `ViewLoader` and `InlineLoader` are `role="status"`; `ViewLoader` adds
+  `aria-busy="true"`. Its pre-delay placeholder is `aria-hidden` (nothing to
+  announce yet).
+- `Busy` sets `aria-busy` on the wrapper and `inert` on the content, which
+  also removes it from the accessibility tree while the mutation runs — and
+  restores focus to the element the inert switch blurred (see above). Its
+  veil is `pointer-events: none`: `inert` already stopped the clicks, and a
+  veil that swallowed them would break text selection after release.
+- **Reduced motion:** the spinner does not spin. `theme.css` kills every
+  animation with a universal `!important` rule — right for a skeleton
+  (shimmer stops), wrong for a spinner (the ring would freeze mid-rotation
+  with one colored quarter and read as a stuck control). `loading.css`
+  therefore **substitutes** a uniform ring on a slow opacity pulse, with
+  `!important` so it out-ranks that universal rule (among important
+  declarations the more specific selector wins).
+
+## Pitfalls
+
+- **Don't overlay a background refresh.** The blocking overlay is for work
+  the user must wait out. Data already on screen stays interactive; use
+  `<Busy>`, a skeleton, or the toolbar refresh spin.
+- **Don't hand-roll `busy()` without a `finally`.** Use `busyWhile` — the
+  watchdog exists because that mistake was made in web-mojo, not
+  hypothetically.
+- **Don't nest a `<LoadingOverlay>` per component.** One overlay serves the
+  app; several tickets are fine, several *hosts* are not a thing (there is no
+  host).
+- **Don't use a loader where a progress toast belongs.** If you have real
+  percentages (uploads, multi-file exports), `toast.progress` keeps the app
+  usable; a blocking overlay for 40 seconds is hostile.
+- **Don't add `delay={0}` to make it "feel responsive."** It does the
+  opposite — you get the flash the delay exists to remove. `delay: 0` is for
+  demos and known-slow routes.
+- **The overlay is `dialog[open]`.** ModelTable's `autoRefresh` skips ticks
+  while any `dialog[open]` exists, so auto-refresh politely pauses during a
+  busy operation. That is intended; don't "fix" it.
+- **Toasts render under the overlay** (`.toast-host` is z-index 60, the
+  overlay is in the top layer). Toast *after* closing the handle, not during.

package/docs/location-address.md

@@ -0,0 +1,76 @@
+# LocationClient + AddressField
+
+```ts
+import { LocationClient } from 'portal-mojo/client';
+import { AddressField } from 'portal-mojo/ui';
+```
+
+`LocationClient` is the typed adapter for django-mojo's six public location
+endpoints. It calls `mojoCall` directly—there is no Query cache—and parses the
+backend's intentionally mixed response shapes without performing a second
+envelope unwrap.
+
+| Method | Wire contract |
+|---|---|
+| `validateAddress(address)` | `POST /api/location/address/validate`; reads nested `data` |
+| `autocomplete(input, options?)` | `GET /api/location/address/suggestions`; reads top-level `success/data/size/count` |
+| `placeDetails(placeId)` | `GET /api/location/address/place-details`; reads top-level `address` |
+| `geocode(address)` | `POST /api/location/address/geocode`; reads top-level coordinates/components |
+| `reverseGeocode({lat,lng})` | `GET /api/location/address/reverse-geocode` |
+| `timezone({lat,lng,timestamp?})` | `GET /api/location/timezone` |
+
+## Provider session and races
+
+The first suggestions request deliberately omits `session_token`; django-mojo
+creates it. The client accepts that response token into a JavaScript private
+field, reuses it on later suggestions and place-details GETs, then destroys it
+when selection ends the session. There is no token getter or input prop.
+
+Every request captures a monotonically increasing generation. A later request,
+`cancelPending()`, `reset()`, `replaceTransport()`, `dispose()`, unmount, or
+upstream-client change makes older completions reject with
+`StaleLocationRequestError`. Use `isStaleLocationRequest(error)` when a UI
+should silently discard that expected outcome.
+
+Never put the session token in TanStack Query, router/search params, form
+values, storage, application logs, or mock history. The mock exposes only
+derived booleans/counts such as `has_session_token` and `input_length`.
+
+## AddressField
+
+`AddressField` is controlled and commit-only. Keystrokes stay in a private
+draft. Raw text commits on Enter/Tab/blur/outside; Escape restores the
+controlled value. Selecting a suggestion privately fetches place details and
+only then commits. A details failure drops the provider description and
+restores the prior value.
+
+```tsx
+<AddressField
+  fieldName="address1"
+  value={values.address1}
+  fields={{ city: 'city', state_code: 'state', postal_code: 'postal_code' }}
+  onCommit={(address1) => setValues(v => ({ ...v, address1 }))}
+  onPatch={(patch) => setValues(v => ({ ...v, ...patch }))}
+/>
+```
+
+For schema-driven forms, use `type: 'address'`:
+
+```ts
+const fields: Field[] = [{
+  name: 'address1', type: 'address', label: 'Street address',
+  addressFields: {
+    city: 'city', state_code: 'state', postal_code: 'postal_code',
+    latitude: 'latitude', longitude: 'longitude',
+  },
+} /* plus every destination as a declared Field */];
+```
+
+`address1` defaults to the address field's own name. Other destinations are
+opt-in. SchemaForm and FormView discard undeclared destinations. FormView
+queues the accepted patch as one autosave batch; a server failure rolls every
+field in that batch back to its shared server snapshot.
+
+The suggestion list uses the shared `Popover`, which is the sole owner of
+outside-mousedown and Escape dismissal. Styles live in
+`theme/location-address.css` and use design tokens in both themes.