portal-mojo 0.1.0

package/docs/daterange.md

@@ -0,0 +1,170 @@
+# DateRangePicker + PresetRail
+
+```ts
+import { DateRangePicker, PresetRail } from 'portal-mojo/ui';
+import type { DateRangeChangeEvent, PresetEntry, PresetsOption } from 'portal-mojo/ui';
+```
+
+The range picker built on the [Calendar engine](calendar.md) and the shared
+[Popover](popover.md), with the "Quick range" preset rail. Ported from
+web-mojo's `DateRangePicker.js` + `calendar/PresetSidebar.js`. One
+component, three precisions: `'day'` (default, two side-by-side panes),
+`'month'`, `'year'` — each with its own default preset list, display
+format, and placeholder.
+
+```tsx
+const [start, setStart] = useState('');
+const [end, setEnd] = useState('');
+
+<DateRangePicker
+    start={start}
+    end={end}
+    onChange={(e) => { setStart(e.start); setEnd(e.end); }}
+/>
+```
+
+## Value contract
+
+**Controlled, canonical strings.** `start`/`end` are the engine's canonical
+strings at precision — `YYYY-MM-DD` / `YYYY-MM` / `YYYY` — with `''`/null
+as empty. Every commit (completed calendar range, preset pick, clear ✕)
+emits `onChange` and paints only once the owner writes the props back:
+
+```ts
+interface DateRangeChangeEvent {
+    start: string;      // canonical at precision ('' when cleared)
+    end: string;
+    formatted: string;  // display text of the NEW range (what the trigger shows)
+    oldStart: string;   // the props at emit time
+    oldEnd: string;
+}
+```
+
+`onChange` fires only when the pair actually changes (re-picking the current
+range emits nothing). There is no per-keystroke path — commits only.
+
+## `<DateRangePicker>` API
+
+| Prop | Notes |
+|---|---|
+| `start` / `end` | Controlled canonical strings (or `''`/null). |
+| `onChange` | `(DateRangeChangeEvent) => void` — see above. |
+| `precision` | `'day' \| 'month' \| 'year'` (default `day`). Unknown values warn + fall back to `day`. |
+| `months` | Day-view panes `1 \| 2`. Default **2 for day precision, 1 for month/year** (source rule). Clamped like the engine. |
+| `presets` | `'default' \| true` → the precision's built-in list; `PresetEntry[]` → custom; absent/`false`/`[]` → no rail. |
+| `displayFormat` | Display tokens (`YYYY YY MMMM MMM MM M DD D`). Defaults: day `MMM DD, YYYY`, month `MMM YYYY`, year `YYYY`. Tokens the precision can't honor are stripped (the source's `_stripIncompatibleTokens`, ported verbatim — trailing separator debris swept). |
+| `separator` | Between the formatted ends. Default `' – '` (spaced en dash). |
+| `placeholder` | Default per precision: `Select date range...` / `Select month range...` / `Select year range...`. |
+| `min` / `max` | Canonical strings, passed straight to the Calendar (compared at the pane precision being painted). |
+| `disabled` | Trigger disabled; popover can't open. |
+| `readOnly` | Trigger shows the value but won't open; no clear ✕. |
+| `required` | Hides the clear ✕ (the field can't be emptied from the trigger). |
+| `inline` | Render rail + calendar in place — no trigger, no popover. |
+| `autoApply` | Default `true`. See semantics below. |
+| `className` / `id` | Root class / trigger button id. |
+
+**`autoApply` means auto-CLOSE, not staged apply** (source semantics carried
+exactly): values apply on every commit either way; `autoApply` only decides
+whether completing a range or picking a preset also closes the popover.
+For an explicit Apply step, mount `inline` inside a dialog and stage the
+values in the dialog's own state — that is precisely what FilterBar does.
+
+## Trigger anatomy
+
+`bi-calendar3-range` icon + formatted text (`start – end`, tabular-nums,
+ellipsized) or muted placeholder + clear ✕. The ✕ renders whenever the
+picker is not `required`/`disabled`/`readOnly` and clears both ends in one
+commit. It is an absolutely-positioned **sibling** button of the trigger —
+web-mojo nested `<button>` inside `<button>`, invalid HTML; do not
+reintroduce. A half-set range displays just the one formatted end
+(deep-linked one-sided `dr_*` filters still render).
+
+## Presets
+
+```ts
+type PresetsOption = 'default' | true | PresetEntry[];
+type PresetEntry =
+    | { label: string; range: () => { start: ParsedDate | string; end: ParsedDate | string } }
+    | { divider: true };
+```
+
+`range()` is resolved at click time (so "Today" is always today) and may
+return parsed shapes (`{y,m,d}` / `{y,m}` / `{y}`) or canonical strings.
+Default lists (verbatim from source; builders exported as
+`dayPresets()` / `monthPresets()` / `yearPresets()` / `defaultPresets(p)`):
+
+| Precision | List |
+|---|---|
+| day | Today · Yesterday · Last 7 days · Last 30 days · Last 90 days · ─ · This month · Last month · This year |
+| month | This month · Last month · Last 3 months · Last 6 months · YTD · Last 12 months |
+| year | This year · Last year · Last 3 years · Last 5 years · Last 10 years |
+
+Rail behavior: "Quick range" eyebrow (`eyebrow` prop on `PresetRail`; `''`
+hides it); the picked preset highlights and stays highlighted until a
+**manual calendar anchor starts** (`onRangeStart` → highlight cleared —
+source parity). Dividers consume an index, so `activeIndex` lines up with
+the flat entry list. `<PresetRail>` is exported standalone (controlled
+`activeIndex`, `onSelect` emits `{index, label, start, end, range}` with
+canonical strings); the C2 custom-range dialog can reuse it.
+
+## FilterBar integration (the dr_* wire triple)
+
+FilterBar's daterange dialog mounts `<DateRangePicker inline months={1}
+presets="default">` and stages `e.start`/`e.end` in dialog state; its
+**Apply** button writes `params.setDateRange(field, start, end)` — the
+`dr_field`/`dr_start`/`dr_end` triple — exactly as the old native date
+inputs did. Same canonical `YYYY-MM-DD` values on the wire, same pills,
+same deep links; only the dialog body changed. The params store remains the
+single source of truth; the picker never touches it directly.
+
+## Form-registry aliases (for the #1278 field registry)
+
+Source `inputs/index.js` registers three aliases over this one component —
+carry them when the registry lands:
+
+| Field type | Component | `precision` |
+|---|---|---|
+| `daterange` | DateRangePicker | `day` |
+| `monthrange` | DateRangePicker | `month` |
+| `yearrange` | DateRangePicker | `year` |
+
+(Explicit `precision` in the field options beats the alias, per source's
+`createInput`.)
+
+## Deviations from source (deliberate)
+
+- **Controlled props replace the form-DOM bridge**: no hidden `<input>`s,
+  no `name`/`startName`/`endName`/`fieldName`, no `outputFormat`
+  (`combined` was `start + separator + end` — derive it if needed), no
+  `getFormValue`/`setFormValue`. The #1278 registry adapter owns form
+  wiring.
+- **A half-picked anchor does not survive popover close/reopen.** The
+  anchor is Calendar-internal state and the popover unmounts its content on
+  close; web-mojo kept one live calendar element across opens. The
+  load-bearing behavior — the anchor surviving paging/zooming
+  mid-selection — is engine-owned and fully preserved; reopening shows the
+  committed range. Revisit only if the engine grows a controlled `anchor`
+  prop.
+- **Escape closes the popover first** (Popover owns Escape in the capture
+  phase — one press, popover only; a second reaches an enclosing modal).
+  The engine's Escape-cancels-anchor applies in `inline` mode.
+- `is-invalid` styling was not carried — source's `hasError()` was a stub
+  that always returned false.
+
+## Pitfalls
+
+- **Do not write `start`/`end` back from anything but `onChange`.** A range
+  prop write is `setRange` semantics to the engine — it cancels an
+  in-progress anchor (that is also why preset picks repaint correctly:
+  owner writes back, engine syncs).
+- Presets are **not min/max-clamped** (source parity): a custom preset can
+  commit out-of-bounds values even though the grid cells paint disabled.
+  Clamp inside your `range()` if bounds matter.
+- The popover body sizes itself (`180px` rail + fixed calendar width);
+  `inline` is fluid to its host. Two panes + rail ≈ 850px — don't mount
+  two-pane popovers inside narrow scroll containers, and keep dialogs on
+  `months={1}`.
+- Styling lives in `apps/portal/src/theme/daterange.css` (trigger
+  `.mojo-daterange-*`, rail `.mojo-calendar-preset*`), tokens only, both
+  themes; the calendar grid ships in `calendar.css`, the popover shell in
+  `popover.css`.

package/docs/datetimepicker.md

@@ -0,0 +1,249 @@
+# DateTimePicker
+
+The combined date **and** time field, ported from web-mojo
+`forms/inputs/DateTimePicker.js` (523 lines) — the source's locked **variant
+A**: one popover with the day [`Calendar`](calendar.md) on the left, the
+embedded [`TimePicker`](timepicker.md) steppers on the right under a "Time"
+heading, a full-width [`TimezoneSelect`](timezone-select.md) row below the
+pair, and a Now/Done footer. **One field, one value** — the timezone belongs
+to this picker, it is never a second field.
+
+```ts
+import { DateTimePicker } from 'portal-mojo/ui';
+import type {
+    DateTimeValue, DateTimeInput, DateTimeChangeEvent,
+    DateTimeObjectValue, DateTimeOutputFormat,
+} from 'portal-mojo/ui';
+```
+
+## Value shapes (the contract)
+
+Storage is **always canonical**: `YYYY-MM-DD` + 24h `HH:MM` + an optional IANA
+zone. `displayFormat`/`timeFormat` only decide what the trigger renders;
+`outputFormat` decides what leaves:
+
+| `outputFormat` | with a zone | without a zone | empty |
+|---|---|---|---|
+| `'iso'` (default) | `'2026-07-04T14:30:00-07:00'` | `'2026-07-04T14:30:00'` | `''` |
+| `'iana'` (legacy) | `'2026-07-04 14:30 America/Los_Angeles'` | `'2026-07-04 14:30'` | `''` |
+| `'object'` | `{date:'2026-07-04', time:'14:30', timezone:'America/Los_Angeles'}` | `{date, time}` (no `timezone` key) | `null` |
+
+`'object'` always yields an object when a date is set — unlike TimePicker, it
+never degrades to a string. The `timezone` key exists (possibly `null`) exactly
+when the zone row is enabled.
+
+**The ISO offset is DST-correct at the value's own date.** It is computed with
+`dateFns.ianaOffset(zone, <the selected instant>)`, so `America/Los_Angeles`
+serializes `-07:00` on July 4 and `-08:00` on January 4. (`TimePicker` cannot
+do this — a wall-clock time has no date, so it must resolve against
+`new Date()`.)
+
+**Everything above parses back in**, plus the looser shapes the source
+accepted:
+
+- date only — `'2026-05-04'` (time reads as `00:00`)
+- 12h text — `'2026-05-04 2:30 PM'`, with or without an IANA tail
+- ISO offsets in every spelling — `Z` → `+00:00`, `+0530` → `+05:30`
+- `T` or a space between date and time
+- loose numbers — `'2026-5-4 14:30'`
+
+Two coverage **extensions over `dateFns.parseDateTime`**, both implemented in
+`DateTimePicker.tsx` because the shared parser would otherwise drop data the
+caller supplied:
+
+1. an object with **no date keeps its `timezone`** (`parseDateTime` returns
+   `null` for the whole thing);
+2. an offset separated from the time by a **space** —
+   `'2026-05-04 14:30 -07:00'` (`parseDateTime` reads an offset only when it is
+   glued to the time, and a zone *name* only after a space).
+
+Anything else parses to empty **with one `console.warn` per distinct value**
+(house rule 4) — never a silent blank.
+
+## API
+
+| Prop | Notes |
+|---|---|
+| `value` | `string \| {date?, time?, timezone?} \| null` — see above. Omit entirely for an uncontrolled picker |
+| `onChange` | `({value, formatted, oldValue})` — fires on **commit only**, and only when the serialized string actually changed |
+| `displayFormat` | date half of the trigger text (`formatForDisplay` tokens). Default `'MMM DD, YYYY'` |
+| `timeFormat` | `'24h'` (default) \| `'12h'`. Unknown values warn + fall back |
+| `timeStep` | minute stepping increment for the time column, ≥1 (default 1) |
+| `min` / `max` | a date (`'2026-05-04'`) **or** a datetime (`'2026-05-04 09:00'`) — see bounds below |
+| `placeholder` | default `'Pick date & time...'` |
+| `disabled` / `readOnly` / `required` / `invalid` | trigger states; `required`, `disabled` and `readOnly` each suppress the clear ✕ |
+| `inline` | render the panel in place — no trigger, no popover, no Done |
+| `disabledDates` | individually blocked days, `"YYYY-MM-DD"` |
+| `firstDay` / `locale` | passed to the Calendar. Default `1` (Mon) / `'en-US'` |
+| `timezone` | `true` enables the zone row; a `string[]` enables it **and is the zone list** |
+| `timezones` | zone list when `timezone` is `true` (default: the engine's own list) |
+| `outputFormat` | `'iso'` \| `'iana'` \| `'object'`. Unknown values warn + fall back |
+| `renderTimezoneSelect` | the zone-picker slot — see below |
+| `name` | renders a hidden input carrying the serialized string (native-form use) |
+| `id` | trigger id, for a label's `htmlFor` |
+| `className` | appended to the root |
+
+`DateTimeChangeEvent.oldValue` is always the **previous canonical serialized
+string** (`''` when empty), in every `outputFormat` — it is the diffing key,
+not a mirror of `value`.
+
+Types split in/out on purpose: `value` takes `DateTimeInput` (every part
+optional), `onChange` hands back `DateTimeValue` (parts guaranteed). Writing
+`event.value` straight back into `value` type-checks.
+
+## Layout (the locked variant)
+
+```
+┌──────────────────────────────┬──────────────────┐
+│  Calendar precision="day"    │  TIME            │
+│  mode="single" months={1}    │  ▲   ▲   [AM]    │
+│                              │  09 : 30  [PM]   │
+│                              │  ▼   ▼           │
+├──────────────────────────────┴──────────────────┤
+│  TIMEZONE                                       │
+│  [ America/Los_Angeles (UTC−07:00)          ▾ ] │
+├─────────────────────────────────────────────────┤
+│  Now                                     [Done] │
+└─────────────────────────────────────────────────┘
+```
+
+The time column embeds `TimePicker inline showFooter={false} timezone={false}`
+— the footerless variant that exists for exactly this. The zone row sits below
+the pair, full width, so the IANA combobox has room for its labels. **Done only
+closes the popover**; every edit committed the moment it was made.
+
+## Behavior invariants (from source, keep them true)
+
+- **Commit-only pipeline.** `onChange` fires on: a calendar pick, any
+  TimePicker commit (stepper, typed + Enter/blur, AM/PM), a zone pick, **Now**,
+  and the clear ✕. Typing in a time column changes nothing until it commits.
+  Re-committing the same value is silent.
+- **Defaults that make one field out of two.** Picking a date with no time yet
+  → time `00:00`. Committing a time with no date → date **today**, and the
+  calendar follows (it reads the same state). **Now** sets both.
+- **min/max**: the DATE part bounds the calendar (out-of-range days are
+  disabled). Where the bound also spelled a TIME, that time clamps **on the
+  boundary day only** — `min="2026-05-04 09:00"` forbids 08:00 on May 4 and
+  nothing at all on May 5. `Now` is clamped through the same rule, so it can
+  never escape the window.
+- **The clamp lives in two places on purpose.** The picker clamps every commit,
+  *and* hands the embedded TimePicker a day-scoped `min`/`max` so it clamps
+  itself. Without the second, the steppers would keep showing the pre-clamp
+  value the parent just rejected.
+- **A cleared field keeps its zone** — the zone is a picker setting, not data
+  (source `clear()`).
+- The trigger is `bi-calendar3` + `MMM DD, YYYY HH:MM [Zone]` + a clear ✕ that
+  appears on hover/focus (suppressed by `required`/`disabled`/`readOnly`).
+
+## The timezone seam
+
+The picker owns every bit of the zone's value and serialization logic but
+renders the picker itself through a slot. Its **default tenant is the real
+`<TimezoneSelect>`**, so `timezone` alone gives you the full searchable,
+offset-labelled zone list:
+
+```tsx
+<DateTimePicker timezone value={value} onChange={(e) => setValue(e.value)} />
+```
+
+Override only to change the rendering (a shorter list, a different control):
+
+```tsx
+<DateTimePicker
+  timezone
+  renderTimezoneSelect={({ value, onChange, timezones, disabled }) => (
+    <TimezoneSelect value={value} timezones={timezones ?? null} disabled={disabled}
+                    onChange={(e) => onChange(e.value)} />
+  )}
+/>
+```
+
+The slot contract is `TimezoneSelectSlotProps` — the same one `TimePicker`
+uses, so a slot written for one drops into the other. Enabling `timezone`
+seeds the browser's local zone **without emitting** (source parity); the owner
+learns it on the first real commit.
+
+## State ownership (read this before wiring a form)
+
+The picker holds its **own committed state**, seeded from `value` and re-seeded
+whenever `value` changes to something that is not an echo of its own last emit
+— the same shape [`Calendar`](calendar.md) and [`TimePicker`](timepicker.md)
+use. Write `event.value` straight back into `value` and the two stay in
+lockstep; omit `value` entirely and it behaves as an uncontrolled picker.
+
+Why not derive purely from props: `'iso'` output carries only the **offset**,
+so re-parsing our own echo would silently degrade `'America/Los_Angeles'` →
+`'-07:00'`. The zone therefore lives in component state, and the echo guard is
+what protects it. Corollary: **writing back the same value is a no-op, and
+writing a different one re-seeds the panel** — to refuse a value, write the
+value you *do* want.
+
+## The wire reality (epoch seconds)
+
+django-mojo model datetimes are **epoch SECONDS** on the wire — this component
+never speaks them. Its contract is the string/object shapes above; the
+**field-type registry (#1278) owns the save-boundary conversion** in both
+directions:
+
+```
+wire (int seconds) ──▶ registry: seconds → 'YYYY-MM-DDTHH:MM:00±HH:MM' ──▶ value
+value ──▶ registry: parse + Date.getTime()/1000 ──▶ wire (int seconds)
+```
+
+Passing an epoch number (or its digits as a string) as `value` parses to empty
+with the usual warn — that is the registry's bug to catch, not a shape this
+picker guesses at. When the zone matters to the *server*, prefer `'iana'` or
+`'object'` output: an offset is a fact about one instant, an IANA name is a
+fact about a place. And remember `fmt.*` accepts epoch seconds directly — do
+not `new Date(epochSeconds)` without `× 1000`.
+
+## Deviations from source (deliberate)
+
+1. **No-op commits are silent, and `oldValue` is real.** web-mojo called
+   `_syncOutputs()` with no argument on nearly every path, which emitted
+   `change` *every time* with `oldValue: null` — even when nothing changed.
+   Here `onChange` fires only on a real change and always carries the previous
+   serialized string.
+2. **Time clamping on the boundary day** (the source only date-bounded the
+   calendar, so a `09:00`–`17:30` window was unenforceable on the first and
+   last day). A date-only bound still clamps nothing but the date.
+3. **`Now` is clamped** like every other commit path.
+4. **An already-offset zone passes through** `'iso'` serialization
+   (`'…-07:00'` re-saves as `'…-07:00'`). `ianaOffset('-07:00')` returns
+   `null`, so the source dropped it on re-save.
+5. **The clear ✕ is a sibling of the trigger**, not nested inside it (the
+   source produced a `<button>` inside a `<button>`).
+6. **`inline` omits Done** — it exists to dismiss the popover and there is
+   none. The source rendered a dead button.
+7. `disabled`/`readOnly` are enforced at the commit boundary, so a locked
+   `inline` panel is inert (the source only guarded the popover).
+8. The dead `format` and `autoApply` options (stored, never read in source)
+   are not carried, and there is no `hasError()` stub — pass `invalid`.
+
+## Styling
+
+`apps/portal/src/theme/datetimepicker.css` — layout glue only
+(`mojo-datetime-*`: `trigger` / `trigger-text` / `trigger-clear` /
+`popover-inner` / `row` / `cal-col` / `time-col` / `time-head` / `tz-row` /
+`tz-label` / `tz-host` / `foot`), tokens only, both themes. The grid, the
+steppers, the combobox and the floating shell are already styled by
+`calendar.css`, `timepicker.css`, `combobox.css` and `popover.css`; this file
+adds the two-column popover (520px floor, stacked under 620px), strips the
+embedded TimePicker's card chrome, and gives the trigger the house `.input`
+look so it lines up with DatePicker/TimePicker in a form grid.
+
+## Pitfalls
+
+- Don't read the time columns to get the value — they may hold an uncommitted
+  draft. `onChange`/`value` is the only value channel.
+- `'object'` output is `null` when empty, `''` for every other `outputFormat`.
+  Check both if you switch formats at runtime.
+- `min`/`max` are **not** a general datetime window: the time half only applies
+  on the boundary day (that is what the calendar can express). A window like
+  "May 4 09:00 → May 8 17:30" is honored at both ends and unrestricted between
+  them.
+- With the zone row open, **Escape closes the whole picker**, not just the
+  combobox dropdown — the shared Popover claims Escape in the capture phase.
+- The zone row's dropdown is locally positioned and can extend past the
+  popover's edge; that is intentional (`.mojo-popover` is `overflow: visible`)
+  and matches web-mojo.

package/docs/defineModel.md

@@ -0,0 +1,72 @@
+# defineModel — typed model definitions + hooks
+
+```ts
+import { defineModel, type ModelDef, type ActionOutcome } from 'portal-mojo/client';
+```
+
+A model is a **stateless definition** — endpoint + permissions + forms +
+actions — plus hooks bound to it. TanStack Query owns all data; there are
+no model instances (web-mojo's `Model`/`Collection` classes end here).
+
+```ts
+export const UserModel = defineModel<User>({
+    name: 'user',
+    endpoint: '/api/user',
+    permissions: { view: ['users', 'view_users'], manage: ['users', 'manage_users'] },
+    forms: { create: { title: 'Add user', submitText: 'Create', fields: [/* Field[] */] } },
+    actions: {
+        disable: { permissions: ['users', 'manage_users'] },   // response: 'row' (default)
+        revoke_sessions: { response: 'payload' },              // action-specific body
+    },
+});
+```
+
+`T` must extend `{ id: number | string }`.
+
+## Hooks & helpers on the returned def
+
+| Member | Behavior |
+|---|---|
+| `useList(params?, {enabled?})` | `useQuery` list under key `[endpoint, params]` with `keepPreviousData`; `enabled:false` suppresses permission-hidden background reads |
+| `useOne(id \| null)` | one record, key `[endpoint, 'one', id]`; disabled while `id` is null |
+| `useSave()` | mutation `{id, changes}`; `id: null` creates. Handles one fresh-auth 440/retry, then writes the returned row into the one-record cache and invalidates `[endpoint]`. REJECTS on failure |
+| `useDelete()` | mutation `{id}`; removes the one-record cache entry + invalidates |
+| `useAction(name)` | mutation for ONE declared POST_SAVE_ACTION (below), with one fresh-auth 440/retry. THROWS at render time for an undeclared name |
+| `fetchOne(queryClient, id)` | imperative fetch through the same cache key — dedupes with mounted `useOne`s (prefetch pattern) |
+| `invalidate(queryClient)` | invalidate everything under `[endpoint]` |
+| `keys.root / keys.list(params) / keys.one(id)` | key builders for targeted cache surgery |
+
+Cache keys are shared with the generic hooks (`useModelList`, `useModel`),
+so `ModelTable` and model hooks read/invalidate one cache.
+
+Save/action mutation functions use `withFreshAuth` globally. Their original
+variables and declared response mode survive the retry, and cache updates run
+only on final success. Delete remains unwrapped, as do direct `mojoCall`
+mutations; callers opt those in only when the endpoint is both sensitive and
+safe to retry once.
+
+## POST_SAVE_ACTIONS
+
+Backend contract (`mojo/models/rest.py on_rest_save`): an action is a key
+in the save body — `POST endpoint/<id>` `{disable: {reason, note}}`. Plain
+fields in the same body save first, then `on_action_<key>(value)` runs.
+The response is either the refreshed row (handler returned nothing) or an
+action-specific payload. **Which one is DECLARED, never sniffed:**
+
+- `response: 'row'` (default) → `ActionOutcome.row` is the refreshed record
+  (written through to the cache).
+- `response: 'payload'` → `row` is null; read `outcome.body` (e.g.
+  `body.message` for `revoke_sessions` — toast the server's text).
+
+Invoke: `await disableAction.mutateAsync({ id, payload: { reason: 'abuse' } })`.
+`payload` defaults to `{}`; handlers treat the value as a dict. Errors
+(e.g. `"reason must be one of: abuse, admin"`) REJECT with the server's
+message.
+
+## Pitfalls
+
+- Don't build a second store around these hooks — pages read query state.
+- The action-name union isn't typed; an undeclared name throws in dev the
+  first time the hook renders (fail loud, not a 404 later).
+- UI `permissions` on the def are affordance gates for `useCan`; the server
+  re-checks every request.

package/docs/detail-primitives.md

@@ -0,0 +1,174 @@
+# Detail primitives — the record-page building blocks
+
+```ts
+import {
+    StatusPanel, FlowStrip, Timeline, KnownFieldsCard, MetadataSection, StackTraceView,
+} from 'portal-mojo/ui';
+```
+
+Six small pieces admin record pages are composed from, ported from
+web-mojo's `src/core/views/data/*` primitives plus its admin metadata
+section. They are presentational and stateless (except `MetadataSection`,
+which writes) — drop them inside a `DetailView` section, a `panel`, or a
+`modal.detail`. Styles: `apps/portal/src/theme/detail-primitives.css`.
+
+**All three trusted-HTML slots are gone.** web-mojo rendered
+`StatusPanel.meta`, `FlowStrip.value/hint` and `Timeline.detail` as
+trusted HTML with a "the caller must escape interpolations" contract.
+Here they are `ReactNode` props — compose `<code>`/`<strong>`/`<a>`
+directly and the escaping question never arises (architecture rule 6).
+
+## StatusPanel — "what state is this in, what do I do next"
+
+```tsx
+<StatusPanel
+    tone="danger" state="Firing" icon="bi-fire"        // icon replaces the tone dot
+    headline="Auth brute-force from 203.0.113.0/24"
+    meta={<>Triggered <code>4m ago</code> · 218 events</>}
+    actions={<><button className="btn btn-primary btn-compact">Acknowledge</button></>}
+/>
+```
+
+The hero banner that opens an Overview section. Tone tints the surface and
+colors the state eyebrow + dot. `actions` is a slot — the caller owns the
+handlers (web-mojo dispatched `data-action` through a global pipeline).
+Container queries stack the actions under the headline below 480px of the
+panel's OWN width, so it behaves inside an `lg` modal.
+
+## FlowStrip — STEP 1 → N
+
+```tsx
+<FlowStrip
+    steps={[
+        { title: 'Match', tone: 'primary', value: <code>category=auth</code>, hint: 'Every condition must match.' },
+        { title: 'Re-trigger', empty: true, value: 'Not configured' },
+    ]}
+    onEditStep={(step, i) => openTab(step, i)}
+/>
+```
+
+| Step field | Effect |
+|---|---|
+| `num` | eyebrow; defaults to `STEP <n>` |
+| `tone` | 2px cap over the column + colored eyebrow (which stage failed) |
+| `empty` | renders `value` muted-italic ("not configured") |
+| `editable: false` | opts one step out of the pencil |
+| `editTitle` | pencil tooltip; defaults to `Edit <title>` |
+
+Column count rides the inline `--flow-strip-cols` custom property; the CSS
+container queries reflow 4 → 2 → 1 off the strip's own width. Empty
+`steps` renders nothing.
+
+## Timeline — the vertical event feed
+
+```tsx
+<Timeline items={[{ tone: 'danger', title: 'Incident opened', meta: fmt.relative(ev.at), body: <>…</> }]} limit={5} />
+```
+
+`{tone, title, meta, body}` — source names were `headline/when/detail`.
+`meta` is the right-aligned monospace timestamp column: format it yourself
+(`fmt.relative` / `fmt.datetime`, both epoch-SECONDS aware). `limit` slices
+to the first N ("recent activity" mode). The empty state renders inside the
+`<ol>` so the rail stays visually intact.
+
+## KnownFieldsCard — promoted keys + raw blob
+
+```tsx
+<KnownFieldsCard
+    data={record.metadata ?? {}}
+    known={[
+        { key: 'created_by', label: 'Created by' },
+        { key: 'last_resolved', label: 'Resolved', format: 'datetime' },   // an fmt.* name
+        { key: 'os.family', label: 'OS', format: (v, key, data) => <code>{String(v)}</code> },
+        { key: 'agent_prompt', hideEmpty: true },
+    ]}
+    rawLabel="Raw metadata"
+/>
+```
+
+- `key` is a **dotted path** (`os.family`); an own property of that literal
+  name wins over traversal.
+- `format` is an `fmt.*` name (`date` | `datetime` | `relative`) or a
+  function returning any node. An unknown name **warns and renders the raw
+  value** — never nothing (rule 4).
+- Missing values render a muted `—`; `hideEmpty` drops the row instead.
+- Objects with no formatter render as compact JSON in a `<code>`.
+- The raw blob goes in a collapsed `<details>` below (`showRaw={false}` to
+  drop it, `rawCollapsed={false}` to start open). Skipped for an empty blob.
+
+**Not to be confused with `DataView`** ([dataview.md](dataview.md)):
+KnownFieldsCard takes one **blob** column and promotes a **curated** list of
+known keys, leaving the rest in the raw `<details>`; DataView takes a
+**whole record** and **infers** a renderer for every key from its name and
+value. They coexist happily — `<DataView data={record} />` for the record,
+`<KnownFieldsCard data={record.metadata} known={…} />` for its blob.
+
+## MetadataSection — editable key/value CRUD (writes)
+
+```tsx
+<MetadataSection
+    endpoint="/api/user" id={user.id} metadata={user.metadata}
+    onSaved={(next) => qc.setQueryData<User>(['/api/user', 'one', user.id], (p) => p && { ...p, metadata: next })}
+/>
+```
+
+**Wire contract:** every mutation is one `POST <endpoint>/<id>` with body
+`{metadata: {…the whole blob…}}` through `mojoCall` — the same single
+envelope-unwrap boundary as everything else. Add, edit and delete all take
+this one path; there is no per-key endpoint.
+
+Invariants:
+
+1. **Controlled on `metadata`; `onSaved` is REQUIRED.** The component never
+   mirrors server state (rule 5) — wire `onSaved` into the TanStack cache or
+   parent state or the UI will not move after a save.
+2. **A rejected save is unmissable** (rule 3). `mojoCall` REJECTS; the
+   server's own message lands in a persistent inline banner AND the editor
+   stays open holding what you typed. web-mojo read `resp.status === 200`
+   off a never-rejecting `model.save()` and fired a generic toast — that is
+   exactly the trap this port retires. Editing is therefore inline, not a
+   modal: a closed modal has no editor state to keep.
+3. **Values are JSON-parsed when they can be** (source semantics): `42`,
+   `true` and `{"a":1}` land as real types, everything else stays a string.
+   Object values then display **read-only** — a string editor round-trips
+   them lossily; remove and re-add to change one.
+
+Deletion confirms through `modal.confirm`; success toasts.
+
+## StackTraceView — JS **and** Python tracebacks
+
+```tsx
+<StackTraceView trace={job.stack_trace} collapseAfter={24} />
+```
+
+One parser, both dialects, in this match order (ported verbatim):
+`at fn (file:line:col)` → `at file:line:col` → `File "…", line N, in fn` →
+any `at …` line → context. Non-string traces are JSON-pretty-printed first.
+
+- **Re-themed.** The source shipped a hardcoded light-only `<style>` block
+  (`#f8f9fa` surface, `#dc3545`/`#0d6efd`/`#6610f2` text) that was
+  unreadable in dark mode. This renders semantic classes over tokens.
+- **The exception line is found anywhere.** The source only colored line 0,
+  so every Python traceback — which opens with `Traceback (most recent call
+  last):` and puts the exception LAST — rendered its most important line as
+  plain context. An anchored `^[A-Za-z_][\w.]*(Error|Exception|…)` pattern
+  now catches it, including dotted ones (`django.db.utils.IntegrityError`).
+- Frame indentation is preserved so Python frames stay aligned with their
+  source lines, terminal-style.
+- Traces longer than `collapseAfter` (default 24) collapse behind a "Show
+  all N lines" toggle; `0` disables collapsing. The body scroll-caps at
+  600px either way.
+
+## Pitfalls
+
+- `tone` is portal-mojo's 6-value `Tone` (`success | warning | danger |
+  info | muted | primary`), not web-mojo's 7 — `default`/`secondary` both
+  map to `muted`. Tones arriving as wire data go through a runtime guard:
+  unknown values fall back to `muted` **with a `console.warn`**.
+- Timestamps are never formatted for you. django-mojo sends epoch SECONDS;
+  pass them through `fmt.*` before handing them to `Timeline.meta`.
+- `KnownFieldsCard` and `MetadataSection` both render a `metadata` blob and
+  are easy to confuse: the card is read-only with promoted known keys; the
+  section is the editor. A detail page often wants both. `DataView` is the
+  third member of that family — whole-record inference rather than a
+  curated key list over one blob.