portal-mojo 0.1.0

package/docs/collection-select.md

@@ -0,0 +1,132 @@
+# CollectionSelect — the single-record server picker
+
+```tsx
+import { CollectionSelect, type CollectionSelectValue } from 'portal-mojo/ui';
+```
+
+Search-as-you-type against any model or endpoint, pick ONE row, and hydrate
+a bare stored id into its display label. The value is **controlled** in both
+directions. Ported from web-mojo `CollectionSelect.js`; sibling of
+`CollectionMultiSelect` in the server-data selects family (epic #1275) —
+the two share the model-binding prop contract.
+
+```tsx
+const [ownerId, setOwnerId] = useState<string | number | null>(42);
+
+<CollectionSelect<User>
+    model={UserModel}             // or endpoint="/api/user"
+    labelField="display_name"
+    value={ownerId}               // bare id → renders "#42", then the label
+    onChange={(id, row) => setOwnerId(id)}
+    label="Owner"
+    required
+/>
+```
+
+## Props
+
+| Prop | Behavior |
+|---|---|
+| `model` / `endpoint` | One is required. `model` is a `defineModel` def (supplies endpoint + row type); `endpoint` is the bare path. |
+| `value` | Controlled: `string \| number \| null`, **or a row-like object** (a record with the relation expanded) — id and label extract via the `valueField`/`labelField` dot paths, no fetch. `0`/`'0'` (web-mojo's no-selection sentinel) and `''` normalize to "no selection" on the way IN and never leak OUT. |
+| `onChange` | `(id \| null, row?)` — fires on **commit only**: picking a row → `(id, row)`; clearing (✕, or typing away from the committed label) → `(null)`. Re-picking the already-committed row does not re-fire. Never fires per keystroke; never emits `'0'` — `null` is the empty value. |
+| `labelField` / `valueField` | Row fields for label and id, **dot notation** reaches nested fields (`'user.email'`). Defaults `'name'` / `'id'`. A missing field warns once and falls back (label → the id; missing id → row dropped / object value → no selection) — never renders nothing silently. |
+| `maxItems` | Rows fetched per search — the `size` wire param. Default 10. |
+| `placeholder` | Input placeholder. Default `'Search…'`. |
+| `debounceMs` | Keystroke → `search` wire param delay. Default 400 (source parity — deliberately not ModelTable's 300). |
+| `emptyFetch` | Default true: opening the dropdown (focus/click) fetches the initial unsearched page so options exist before typing. `false`: nothing is fetched until a term exists — the dropdown shows "Start typing to search…". |
+| `defaultParams` | Extra wire params — a dict, or a **callback re-evaluated per render** (each fetch uses the freshest result; a changed result is a new query key → refetch). Merge order: `{size: maxItems} → defaultParams → group → search` (later wins). |
+| `requiresActiveGroup` | Folds the active group id in as `group`. With NO active group the fetch is **held** (the dropdown says "Select an active group first") — never an unscoped list where a scoped one was demanded. Needs a `<GroupProvider>` above; missing one warns. |
+| `label` / `required` / `help` / `error` | Field wrapper (house `.field-label` / `.field-help` / `.field-error`; `error` replaces `help` and paints the input `.input-invalid`). |
+| `disabled` / `readOnly` | Both freeze the pipeline (no open, no typing, no ✕). `readOnly` still shows the committed label at input contrast. |
+
+## Selection semantics (the contract)
+
+- **Picking commits**: the input fills with the row's label, the dropdown
+  closes, `onChange(id, row)` fires (only when the id actually changed).
+- **Typing that diverges from the committed label clears the selection** —
+  `onChange(null)` fires ONCE and the typed text becomes the live search
+  (web-mojo re-emitted the clear on every keystroke; fixed here).
+- **Clear ✕** shows while a selection exists: resets to empty, fires
+  `onChange(null)`, refocuses the input — which reopens the dropdown on
+  the base page (the source's emergent behavior, kept on purpose).
+- **Escape** closes the dropdown and restores the committed label (the
+  in-progress search text is dropped). Inside a native-`<dialog>` modal the
+  first Escape closes only the dropdown, the second the modal (Popover's
+  capture-phase handling). **Outside click and Tab-away do the same
+  revert** — deliberate deviation from the source, which left typed text
+  visible in the input while its hidden value said "no selection" (the
+  display-diverges-from-state bug class ends here).
+- **Keyboard**: ArrowDown/ArrowUp walk the options (clamped at the ends, no
+  wrap — source parity; ArrowDown also reopens a closed dropdown), Enter
+  commits the focused option (and never submits an enclosing form while the
+  dropdown is open). Focus never leaves the input — options are
+  `tabIndex={-1}` and mousedown-prevented, and the input is never
+  remounted, so it stays focus-stable across result updates.
+
+## id → label hydration
+
+A `value` whose label is unknown renders `#<id>` immediately, then resolves
+in this order:
+
+1. **Object value** — label extracted via the dot path, no fetch.
+2. **Label learned at pick time** (kept per instance — survives list-cache
+   garbage collection).
+3. **Any cached LIST row** under `[endpoint, …]` — ModelTable pages, other
+   pickers and this picker's own fetches all share those keys.
+4. **Fetch the one record** through the generic `[endpoint, 'one', id]` key
+   — the same cache `useOne`/DetailView read, so the fetch dedupes with
+   them. Numeric-string ids fetch under the **numeric** key (django-mojo
+   pks are ints; uuid/slug ids pass through).
+
+A failed hydration keeps `#<id>` on screen and warns once per id (mojo 4xx
+errors never retry, per `mojoQueryDefaults`).
+
+## Wire contract
+
+GETs to the list endpoint through `useModelList` — cache key
+`[endpoint, params]`, `placeholderData: keepPreviousData`. Params sent:
+`size: maxItems`, merged with `defaultParams`, plus `group` (when
+`requiresActiveGroup`) and `search` (trimmed; **dropped entirely when
+empty** — an empty search is the plain first page, not `search=`).
+Fetches run only while the dropdown is open; with `emptyFetch: false`,
+only once a term exists. `model.invalidate(qc)` refreshes an open picker
+too — there is no parallel fetch path.
+
+## Invariants
+
+1. Controlled value, one pipeline: the input displays either the committed
+   label (or `#<id>` while resolving) or the live draft — never a mix, and
+   never text the state doesn't hold. Commit fires on selection/clear only.
+2. Every id comparison goes through one `String()` normalization; `'0'`/`0`
+   normalize to null at the boundary and `null` is the only empty value on
+   the way out.
+3. Rows the server returns are shown as-is — every narrowing (kind, group,
+   search…) is a wire param, never a client-side filter.
+4. Dropdown states: spinner row while the current key's rows aren't on
+   screen; "No results found" (searched) vs "Start typing to search…"
+   (no term); fetch errors show the server's message + Retry; a held
+   group-scoped fetch says "Select an active group first".
+5. The dropdown lives in the shared `<Popover>` (top layer): it stacks
+   above native-`<dialog>` modals, escapes overflow containers, and
+   matches the field's width.
+
+## Pitfalls
+
+- `maxItems` is the fetch size — there is no paging in the dropdown. If the
+  target row isn't in the first page, the user searches; search is
+  server-side, so it can find anything.
+- The picker never invents rows: a `value` id that doesn't exist
+  server-side stays `#<id>` (with one console warning). Feed it real ids
+  or a row object.
+- `labelField` must exist on the **list** graph rows for the dropdown to
+  read well; hydration can additionally use one-record-graph fields (the
+  detail graph is often wider), but options come from list rows.
+- An inline `defaultParams` object/callback re-evaluates per render; that
+  is fine (TanStack hashes keys structurally). Only a changed RESULT
+  refetches.
+- `requiresActiveGroup` holds the fetch until a group is active; pair the
+  control with `RequiresGroup` or group-scoped screens so users aren't
+  handed a picker that says to pick a group they can't pick there.
+- Don't wire `onChange` to a per-keystroke autosave expectation — it fires
+  on commit (that is the point; see the B3 autosave contract).

package/docs/combobox.md

@@ -0,0 +1,105 @@
+# ComboBox — the house autocomplete
+
+```ts
+import { ComboBox, type ComboOption, type ComboValue } from 'portal-mojo/ui';
+```
+
+One editable select: a text input over a filtered suggestion list. Ported
+from web-mojo's `ComboInput.js` (the feature spec — descriptions, meta,
+highlight, ARIA, relevance ranking) plus `ComboBox.js`'s open-on-focus.
+This is the base for TimezoneSelect (#1274) and rule-builder field pickers;
+there is exactly ONE combobox in this toolkit.
+
+## API
+
+```ts
+type ComboValue = string | number;
+
+interface ComboOption {
+    value: ComboValue;
+    label: string;          // what the input displays
+    description?: string;   // muted second line in the list
+    meta?: Record<string, unknown>;  // opaque; returned via onSelect
+}
+
+<ComboBox
+    value={v}                        // committed value (string | number | null)
+    options={opts}                   // ComboOption[] — bare strings normalize to {value:s,label:s}
+    onChange={(value, option?) => …} // COMMIT only, and only when the value changed
+    onSelect={(option) => …}         // any commit that resolves to an option — carries meta
+    allowCustom     // default true: unmatched text commits as-is
+    showDescription // default true
+    minChars={0}    // typing auto-opens the list only at ≥ N chars
+    maxSuggestions={10}  // caps the rendered list AND keyboard wraparound
+    placeholder disabled readOnly required id className
+/>
+```
+
+## The commit pipeline (the invariant)
+
+The input's text is a private **draft**; the committed value lives in the
+`value` prop. `onChange` fires ONLY on:
+
+| Gesture | Result |
+|---|---|
+| Click option / Enter on highlighted | commit that option |
+| Enter on typed text (`allowCustom`) | resolve → option, else commit text as custom |
+| Blur / outside click / Tab / chevron-close | **settle**: exact label or `String(value)` match → that option; else custom when allowed (`''` commits a clear); else **revert** — the display falls back to the committed label |
+| Escape while list is open | Popover dismisses → revert, keep focus — never commits |
+
+Never per keystroke — web-mojo's ComboBox emitted per keystroke and
+FormView's 300ms autosave saved partial text. Typed text equal to an
+option's **label** commits the option's **value** (display shows labels;
+labels must never leak into state). `onChange` is skipped when the resolved
+value equals the current `value`; `onSelect` still fires on an explicit
+option commit (rule builders may want the meta again).
+
+## Filtering
+
+Case-insensitive substring across label + value + description; ranked exact
+label match, then label starts-with, then input order (stable). `minChars`
+gates only the auto-open while typing (below it the list closes); explicit
+opens — focus, ArrowDown, chevron — always show the full (capped) list.
+The chevron reopens with the filter cleared and the input text selected, so
+the next keystroke starts a fresh query. Empty states (verbatim):
+with `allowCustom` — "No matches found. Press Enter to use custom value." /
+"Start typing to see suggestions..."; without — "No matching options found."
+
+## Keyboard + ARIA
+
+ArrowDown opens, then moves next; ArrowUp previous; both wrap over the
+*visible* (maxSuggestions-capped) list. Enter selects the highlighted
+option, else commits custom text. Escape reverts through the shared Popover
+(and reaches a parent `<dialog>` once the list is closed). Tab settles
+and passes through. The highlighted option scrolls into view
+(`block:'nearest'`). Full combobox pattern: `role=combobox`,
+`aria-expanded`, `aria-autocomplete=list`, `aria-controls`,
+`aria-activedescendant`, `role=listbox/option`, `aria-selected` + check
+icon on the selected option. Match highlighting renders as split React
+nodes around `<mark class="combo-mark">` — regex-escaped query, no HTML
+strings.
+
+## Invariants / fixed web-mojo bugs (do not reintroduce)
+
+- **Commit-only `onChange`** — the draft/value split is the fix; there is no
+  code path that emits while typing.
+- **`allowCustom:false` reverts for real** — web-mojo overwrote its
+  committed value per keystroke, so its revert restored the typed text.
+- **Numeric values survive** — selection passes option objects in closures;
+  web-mojo strict-equalled stringified `data-value` DOM attributes.
+- **One dismissal owner** — shared Popover alone listens for outside
+  mousedown/Escape; ComboBox only chooses settle-vs-revert.
+- Unknown `value` under `allowCustom:false` warns once and displays
+  verbatim — never renders nothing (rule 4).
+
+## Pitfalls
+
+- Value matching is strict `===`: `5` and `'5'` are different values. Keep
+  option values and the `value` prop the same type (URL params are strings —
+  convert before binding).
+- `description` renders only when provided (web-mojo silently defaulted it
+  to the label, duplicating every row — not carried).
+- The dropdown is mounted in the shared top-layer Popover, so overflow
+  containers and native dialogs do not clip it.
+- Styles live in `apps/portal/src/theme/combobox.css` (tokens only, both
+  themes); consuming apps must include it.

package/docs/dataview.md

@@ -0,0 +1,226 @@
+# DataView — the inferred record grid
+
+```tsx
+import { DataView, JsonBlock, inferFieldType, type DataViewField } from 'portal-mojo/ui';
+
+<DataView data={user} />                              // schemaless: infer everything
+<DataView data={user} fields={SCHEMA} />              // explicit schema
+```
+
+Point it at any record and get a sensible detail grid. Field **names** and
+**values** together pick the renderer, nested objects become nested grids,
+and anything that isn't a scalar lands in a JSON block with copy and
+collapse. Port of web-mojo `src/core/views/data/DataView.js` (1,153 lines).
+Styles: `apps/portal/src/theme/dataview.css`. Demo: **Develop → Components →
+DataView**.
+
+## DataView vs KnownFieldsCard
+
+They look similar and solve opposite problems. Both often appear on the
+same page.
+
+| | Input | Which keys | Unknown keys |
+|---|---|---|---|
+| **`DataView`** | a whole **record** (`user`, `job`, `incident`) | **all of them**, inferred | inferred too — that is the point |
+| **`KnownFieldsCard`** | one **blob** column (`metadata`, `ip_info`, `payload`) | only the **curated** `known` list you pass | left in the raw `<details>` below |
+
+Rule of thumb: `DataView` when you don't know (or don't want to enumerate)
+the shape; `KnownFieldsCard` when you know exactly which few keys matter
+and the rest is an open bag. `<DataView data={record} />` +
+`<KnownFieldsCard data={record.metadata} known={…} />` is a normal pairing.
+
+## Props
+
+| Prop | Default | Effect |
+|---|---|---|
+| `data` | — | the record. `null`/`undefined` is safe (renders `emptyText`) |
+| `fields` | inferred | explicit schema; omit for full inference over `Object.keys(data)` |
+| `exclude` | `[]` | keys to drop. Applies in **both** modes |
+| `columns` | `2` | grid columns at full width |
+| `showEmptyValues` | `true` | `false` restores the source behavior: an empty value drops its row |
+| `emptyValueText` | `'—'` | rendered for an empty value |
+| `emptyText` | `'No data.'` | shown when nothing is renderable |
+| `maxDepth` | `2` | levels of **nested** DataView below this one; deeper → JSON block |
+| `depth` | `0` | internal recursion counter — callers leave it alone |
+
+**Ordering is stable**: the schema's order, or the record's own key order
+(`Object.keys`, i.e. insertion order).
+
+### `DataViewField`
+
+```tsx
+const SCHEMA: DataViewField[] = [
+    { name: 'display_name', label: 'Name' },
+    { name: 'settings.theme', label: 'Theme' },                    // dotted path
+    { name: 'plan_amount', label: 'Plan', type: 'currency' },      // declared renderer
+    { name: 'trust_score', format: (v) => <b>{Number(v).toFixed(1)} / 10</b> },
+    { name: 'bio', span: 'full' },
+    { name: 'last_error', hideEmpty: true },
+];
+```
+
+- `name` — a **dotted path** (`settings.theme`); an own property of that
+  literal name wins over traversal (KnownFieldsCard's rule).
+- `label` — defaults to the humanized last path segment (`created_at` →
+  `Created At`, `lastLogin` → `Last Login`).
+- `type` — names a built-in renderer, skipping inference. An unknown value
+  **warns and infers** — never renders nothing (rule 4).
+- `format(value, name, data)` — replaces the renderer entirely; returns any
+  `ReactNode`. Same signature as `KnownFieldsCard`'s.
+- `span` — `'full'` spans the grid; `'auto'` (default) is full only for
+  arrays / objects / nested grids.
+- `hideEmpty` — drop the row instead of showing `—`.
+
+## Inference — the heuristics
+
+Two exported pure functions carry it, usable on their own:
+`inferFieldType(value, key)` and `shouldUseDataView(value, keyLower)`.
+
+**Order matters** — the first match wins:
+
+| # | Test | Type |
+|---|---|---|
+| 1 | `value == null` | `text` |
+| 2 | `typeof value === 'boolean'` | `boolean` |
+| 3 | key starts `is_`/`has_`/`can_`/`should_` **and** value is boolean-ish (`0`/`1`/`"true"`/`"yes"`…) | `boolean` |
+| 4 | key contains `date`, `time`, `created`, `updated`, `modified`, `last_login`, `expires`, `last_activity`, or **ends in `_at`** | `datetime` |
+| 5 | key contains `email` / `mail` | `email` |
+| 6 | key contains `url` / `website` / `homepage`, or has the word `link` | `url` |
+| 7 | key contains `phone` / `mobile`, or has the word `tel` / `cell` | `phone` |
+| 8 | key contains `price` / `amount` / `salary` / `revenue`, or has the word `cost` / `fee` | `currency` |
+| 9 | key has the word `size` / `bytes` / `filesize` | `filesize` |
+| 10 | (key contains `percent` or has the word `rate` / `ratio`) **and** value is a number | `percent` |
+| 11 | `typeof value === 'number'` | `number` |
+| 12 | array | `array` |
+| 13 | object with `renditions` | `file` |
+| 14 | object passing `shouldUseDataView` | `dataview` |
+| 15 | any other object | `object` |
+| 16 | string `"…@….…"` / `^\d{4}-\d{2}-\d{2}` / `^https?://` / phone-shaped **with ≥7 digits** | `email` / `date` / `url` / `phone` |
+| 17 | anything else | `text` |
+
+"contains" is a substring test (the source's); "has the word X" is an exact
+**token** match after splitting the key on `_`, `-` and camelCase humps —
+see *Deviations* for why.
+
+### `shouldUseDataView` — nested grid or JSON?
+
+An object gets a nested `DataView` when **either**:
+
+1. it carries an `id` — it's a related record; or
+2. its key contains one of `permissions perms access rights settings config
+   configuration options profile info details data metadata meta attributes
+   props preferences prefs user_data contact address location stats
+   statistics metrics counts`, **and** it has 2–20 keys, **and** no child of
+   it is an object with more than 3 keys.
+
+Everything else is a JSON block. That last clause is the source's: one
+deep child disqualifies the whole object, on the theory that a grid of
+grids stops being readable.
+
+### What each type renders
+
+| Type | Rendering |
+|---|---|
+| `datetime` | `fmt.relative` for `last_*`/`*ago*`/`*relative*`; `fmt.datetime` for a `time`-not-`date` key; else `fmt.date` |
+| `date` | `fmt.date` |
+| `email` | `<a href="mailto:…">` |
+| `url` / `file` | `<a target="_blank" rel="noopener noreferrer">` + external-link icon |
+| `phone` | `<a href="tel:…">` around `fmt.phone` (digits + `+` only in the href) |
+| `currency` | `fmt.currency`; `EUR`/`GBP` from the key, else `USD`. **Integer → cents, fractional → major units** |
+| `filesize` | `fmt.filesize` (decimal KB/MB/GB) |
+| `percent` | `fmt.percent`; **`\|v\| ≤ 1` is scaled ×100**, anything larger is already a percentage |
+| `number` | `count`/`total`/`followers`/`views` → `fmt.compact` at ≥1000 else `fmt.number`; `score`/`rating` → `fmt.number(v, 1)` when fractional; `version` / the word `id` → verbatim; else `fmt.number` |
+| `boolean` | `<Badge tone="success\|muted">Yes/No</Badge>` — the house treatment, via `fmt.yesNo` |
+| `text` | `description`/`content`/`body` → truncate 200/100; `summary`/`excerpt` → 150; `username`/`slug`/`handle`/`login` → verbatim monospace; `name`/`title`/`label` → `.cap` + truncate 50; `code`/`token`/`key`/`secret` → monospace, `fmt.mask` over 20 chars; else truncate 100 |
+| `array` | scalars join with `, `; objects → `Array · N items` in a collapsed `JsonBlock` |
+| `object` | `JsonBlock` |
+| `dataview` | nested `<DataView>` (tinted inset) until `maxDepth`, then `JsonBlock` |
+
+Truncated text keeps the full value on a `title` attribute.
+
+## JsonBlock
+
+```tsx
+<JsonBlock value={payload} />                                    // auto
+<JsonBlock value={payload} label="Request trace" collapsible defaultOpen />
+```
+
+| Prop | Default | Effect |
+|---|---|---|
+| `value` | — | anything JSON-serializable |
+| `label` | `Object` / `Array · N lines` | caption override |
+| `collapsible` | `>10 lines \|\| >500 chars` (source rule) | force the Show/Hide affordance |
+| `defaultOpen` | `false` | start expanded when collapsible |
+
+- **Syntax highlighting is real tokenization**, not regex-over-HTML:
+  `tokenizeJson()` walks the string emitting `key` / `string` / `number` /
+  `boolean` / `null` / `plain` tokens, rendered as React `<span>`s. **No
+  `dangerouslySetInnerHTML`.** The token stream reassembles to the exact
+  input, so a value like `"has a colon: and \"q\""` colors correctly (the
+  source's five regexes did not).
+- Copy writes with the async Clipboard API, toasts on success, flips the
+  icon to a check for 1.2s, and toasts an error if the write rejects.
+  Outside a secure context `navigator.clipboard` is absent — it says so
+  rather than silently no-op'ing through `document.execCommand`.
+- A circular payload renders a muted `[Object] — cannot display as JSON`.
+  Nothing here throws.
+
+## Invariants
+
+1. **A renderer is the last thing allowed to take a record down.** Every
+   per-field render is wrapped: a throw becomes a `console.warn` plus the
+   plain `String(value)`. `fmt.*` never throws either.
+2. **Empty is `—`, not absent** (`emptyValueText`). `null`, `''`, `[]` and
+   `{}` all read empty. `showEmptyValues={false}` or `hideEmpty` opt out.
+3. **Unknown `type` warns and infers** (rule 4) — never renders nothing.
+4. **`ReactNode` in, `ReactNode` out.** No HTML strings anywhere (rule 6).
+5. **Epoch SECONDS** are handled by `fmt.*`; don't pre-convert.
+6. **Depth is capped.** `maxDepth` (default 2) bounds nesting, so a
+   pathological payload degrades to JSON instead of recursing.
+
+## Pitfalls
+
+- **Money is CENTS when it's an integer.** django-mojo stores minor units,
+  so `plan_amount: 129900` → `$1,299.00` while `overage_price: 4.75` →
+  `$4.75`. A record that breaks that convention needs an explicit
+  `format`.
+- **Percent auto-scales below 1.** `error_rate: 0.0182` → `2%`;
+  `error_rate: 12` → `12%`. A ratio that legitimately exceeds 1 needs an
+  explicit `format`.
+- **The name wins over the value.** `contact_email: 1234` still renders a
+  `mailto:` link — that is the source's contract, and it is what makes
+  schemaless inference useful on sparse rows. Declare a `type` (or a
+  `format`) on any field whose name lies.
+- **No pipe strings.** `format: "date('MMM D')|capitalize"` does not exist
+  here (do-not-recreate); nor does the source's inline `name: 'is_tor|
+  status_text'` syntax. Use `type` or a function.
+- **`fmt.capitalize` doesn't exist**, so `name`-ish fields get the `.cap`
+  class — CSS capitalization, which leaves the stored value intact.
+- Container queries do the reflow off the grid's **own** width, so a
+  DataView inside a modal or a detail rail stacks correctly without
+  knowing the viewport.
+
+## Deviations from web-mojo
+
+Beyond the pipe engine and trusted HTML (both architecture rules), these
+are behavior changes, each a source bug:
+
+| Source | Here |
+|---|---|
+| `percent \|\| rate \|\| ratio && number` — `&&` binds tighter, so `rate` matched any type, and `includes()` matched **inside words**: `duration` contains "ratio" (8040 → `804,000%`), `generated` contains "rate" | short needles (`rate` `ratio` `size` `bytes` `tel` `cell` `cost` `fee` `id` `key` `code` `link` `label` `body`) match on **word boundaries**, and the number guard covers the whole percent branch |
+| `typeof value === 'boolean'` tested **after** the name chain, so `is_email_verified: true` → `mailto:true` | booleans are typed first, before any name pattern |
+| `/^\+?[\d\s\-()]+$/` made `"42"` and `"2024"` tel: links | a phone string needs ≥7 digits |
+| `username` contains `name`, so it hit the capitalize branch and the `slug` branch below was unreachable for it — and `slug` rewrote `ian.starnes` to `ianstarnes` | identifiers are checked first and render **verbatim** in monospace |
+| an empty value **dropped its row**, so a record's shape changed with its data | `showEmptyValues` defaults `true`; `—` is the house empty |
+| `shouldUseDataView`'s `id` rule was gated on `window.utils`, a global absent in half of web-mojo's entry points | the rule always applies |
+| no `file` renderer — `{renditions}` objects stringified to `[object Object]` | anchor to `url` with `name`/`filename`, else a JSON block |
+| unbounded nesting | `maxDepth`, then JSON |
+| JSON "highlighting" = 5 regexes over escaped HTML with hardcoded light-mode hexes (`#0969da`, `#0a3069`, …) injected as `innerHTML` | a real tokenizer → React spans over theme tokens, correct in both themes |
+
+Not ported (deliberately): `model` binding and the `change` re-render
+listener (TanStack Query owns reactivity — pass `data` from a hook),
+`updateData`/`updateFields`/`updateConfig`/`refresh` (props, not
+imperative setters), `setFieldFormat`/`addFormatPipe`/`clearFieldFormat`/
+`getFieldFormats` (the fluent pipe-string API), `{{key}}` template
+strings, and the `field:click` event (`data-field` is still on each item
+for tests and CSS).

package/docs/datepicker.md

@@ -0,0 +1,151 @@
+# DatePicker — the single-value picker shell
+
+```ts
+import { DatePicker, type DatePickerChangeEvent } from 'portal-mojo/ui';
+```
+
+The trigger-and-popover shell over the [Calendar engine](calendar.md), ported
+from web-mojo's `forms/inputs/DatePicker.js`. One component covers all three
+precisions — day, month-only, year-only — and renders either as a form
+control that opens a [Popover](popover.md), or `inline` as a bare calendar.
+
+It owns exactly three things the engine does not: the display text, the
+open/closed popover, and the clear affordance. Everything else is
+pass-through.
+
+```tsx
+const [due, setDue] = useState<string | null>(null);
+
+<DatePicker
+    value={due}
+    min="2026-01-01"
+    disabledDates={['2026-03-12']}
+    onChange={(e) => setDue(e.value)}
+/>
+```
+
+## Value shape (the contract)
+
+- `value` is the **canonical string at precision** — `YYYY-MM-DD` /
+  `YYYY-MM` / `YYYY` — or `null` for empty. Same strings the engine speaks;
+  no `Date` objects, no epochs. (django-mojo datetime *fields* are epoch
+  seconds — convert at the model/form boundary, not here.)
+- **Controlled.** A commit fires `onChange`; the trigger repaints only once
+  the owner writes the value back. The picker holds no shadow copy.
+- A loose-but-valid prop is canonicalized before anything reads it
+  (`"2026-3-4"` → `"2026-03-04"`), so `onChange().oldValue` and the calendar
+  always see the same normal form.
+
+```ts
+interface DatePickerChangeEvent {
+    value: string | null;      // canonical, or null when cleared
+    formatted: string;         // the trigger's display text ('' when null)
+    oldValue: string | null;   // canonical value being replaced
+}
+```
+
+`onChange` fires on **commit only** — a calendar pick or the clear ✕ — and
+only when the canonical value actually changes. Re-picking the selected day
+closes the popover without an event.
+
+## API
+
+| Prop | Notes |
+|---|---|
+| `value` | controlled canonical string, or `null` |
+| `precision` | `'day' \| 'month' \| 'year'` (default `day`). Unknown values warn + fall back to `day` |
+| `onChange` | `(e: DatePickerChangeEvent) => void` — commit only |
+| `displayFormat` | trigger text format (`formatForDisplay` tokens). Default per precision: `MMM DD, YYYY` / `MMM YYYY` / `YYYY` |
+| `placeholder` | empty-state text. Default `Select date/month/year...` |
+| `min` / `max` | pass-through bounds (compared at the pane precision being painted) |
+| `disabledDates` | `YYYY-MM-DD[]`, day grids only |
+| `firstDay` | 0=Sun … default 1=Mon |
+| `locale` | BCP-47 for month/weekday names, default `en-US` |
+| `autoApply` | close the popover on commit. Default `true`; `false` commits and stays open |
+| `inline` | render the calendar in place — no trigger, no popover, no ✕ |
+| `disabled` / `readOnly` | both make the picker inert (no open, no commits); both hide the ✕ |
+| `required` | hides the ✕ — a required field cannot return to empty |
+| `invalid` | paints the error border (`is-invalid`) |
+| `name` | renders a hidden input with the canonical value (native form posts only) |
+| `id` / `className` | trigger id (for a label's `htmlFor`) / extra class on the root |
+
+The popover is the shared `Popover` at `bottom-start`: outside-mousedown and
+Escape close it, it repositions on scroll/resize, and it joins the top layer
+so a picker inside a `<dialog>` modal paints above it.
+
+## Display formatting
+
+`displayFormat` is filtered to the tokens the precision can actually fill,
+then trailing separators are trimmed (ported verbatim as
+`_stripIncompatibleTokens`):
+
+| precision | behavior |
+|---|---|
+| `day` | passes through untouched |
+| `month` | `\bDD\b` / `\bD\b` removed |
+| `year` | all month + day tokens removed; empties fall back to `'YYYY'` |
+
+```
+month  "D MMMM YYYY"  → "MMMM YYYY"  → "August 2026"
+month  "YYYY-MM-DD"   → "YYYY-MM"    → "2026-08"
+year   "MMM DD"       → "YYYY"       → "2026"
+month  "MMM DD, YYYY" → "MMM , YYYY" → "Aug , 2026"   ← the wart
+year   "DD/MM/YYYY"   → "//YYYY"     → "//2026"       ← the wart
+```
+
+The strip removes the **token**, not the punctuation around it, and only
+trailing separators are cleaned. Pass a format that suits the precision, or
+lean on the per-precision default.
+
+## Invariants (keep them true)
+
+- **One value pipeline.** The prop is parsed + re-formatted once into
+  `canonical`; the trigger text, the calendar's `value`, the hidden input and
+  every emitted event read that single derivation. The control can never
+  display something the owner's state does not hold.
+- **A value that does not parse renders as empty and logs one
+  `console.warn`** naming the expected shape — once per distinct bad value,
+  from an effect (never during render), never silently blank.
+- **The clear ✕ is hidden when `required || disabled || readOnly`.** It is a
+  SIBLING of the trigger button, absolutely positioned over it — clicking it
+  can never open the popover.
+- **`disabled`/`readOnly` are inert in both modes** — the trigger opens
+  nothing and, inline, the calendar takes no commits.
+- The ✕ shows whenever clearing is allowed, even with nothing selected
+  (source parity); clicking it then is a no-op — no `onChange`.
+- The trigger is a real `<button>`: Enter/Space open it, Escape closes.
+
+## Deviations from web-mojo (deliberate)
+
+| Source | Here | Why |
+|---|---|---|
+| clear `<button>` nested inside the trigger `<button>` | sibling, absolutely positioned | button-in-button is invalid DOM; React logs a `validateDOMNesting` error |
+| `_setValue` patched `textContent` + a hidden input in place | value is a controlled prop | one pipeline; no shadow state to drift |
+| `change` emitted `value: ''` when cleared | `value: null` | matches the `string \| null` prop type end to end |
+| calendar instance persisted across opens (page position too) | popover content unmounts on close | React idiom; reopening always re-pages to the value, else today |
+| inline mode ignored `disabled` | inline honors `disabled`/`readOnly` | the props have to mean something |
+| imperative `setValue/getValue/clear/setMin/setMax/show/hide/focus` | props | nothing to call — the owner holds the value |
+
+## Pitfalls
+
+- The ✕ is `tabIndex={-1}` (source parity — a second tab stop per date field
+  was not wanted). Keyboard users clear the field through the owning form,
+  not the trigger.
+- `min`/`max` gate at the **pane's** precision: with `min="2026-03-15"` the
+  March tile and the 2026 tile stay enabled, only out-of-bounds days
+  disable. Day-level rules belong in `disabledDates`.
+- `inline` fills its container — give it a sized wrapper (~280px), same as a
+  bare `<Calendar>`.
+- Don't feed it `new Date().toISOString().slice(0,10)` if you care about the
+  local day — that's UTC. Build canonical strings with `dateFns.formatYmd`.
+- `autoApply={false}` keeps the popover open after a commit; there is no
+  Apply button (there wasn't one in the source either) — the user closes it
+  by clicking out, pressing Escape, or clicking the trigger.
+
+## Styling
+
+`apps/portal/src/theme/datepicker.css` — trigger, clear ✕, popover content
+box, inline host. The grid itself is `theme/calendar.css` and the floating
+surface is `theme/popover.css`; this file adds nothing they already cover.
+Trigger metrics follow the house control (`.input`): `--surface2` fill,
+`--line` border, 8px radius, accent focus ring. Tokens only, both themes.