portal-mojo 0.1.0

package/docs/feedback.md

@@ -0,0 +1,85 @@
+# feedback — awaitable modals + toasts
+
+```ts
+import { modal, formModal, toast, ModalHost, ToastHost } from 'portal-mojo/ui';
+```
+
+Mount `<ModalHost />` and `<ToastHost />` once in the app shell. Modals are
+native `<dialog>` — stacking, backdrop and Escape come free; every opener
+is a Promise that resolves when its dialog closes.
+
+## modal
+
+| Call | Resolves |
+|---|---|
+| `modal.confirm({title, message, confirmText, danger?})` | `boolean` |
+| `modal.open<T>((close) => <JSX/>)` | `T \| null` — generic surface; call `close(value)` |
+| `modal.detail((close) => <DetailView …/>)` | detail-sized shell for record views |
+| `modal.drawer<T>({title, content\|render, …})` | `T \| null` — right slide-over (below) |
+| `formModal({title, fields, initial?, submitText?, intro?})` | `FormData \| null` (see forms.md) |
+
+Patterns:
+- Danger confirms: `danger: true` styles the confirm button destructively.
+- Batch prepare: open a `formModal` INSIDE a flow to collect once-per-batch
+  input; resolve null to cancel the whole thing.
+- Stacked dialogs are fine (disable-reason form over a detail modal).
+
+## modal.drawer
+
+```ts
+const picked = await modal.drawer<string>({
+    eyebrow: 'Source IP', title: '198.51.100.24',
+    meta: [{ icon: 'bi-clock', text: 'Last 30 days' }, '412 events'],
+    width: 'wide',
+    render: (close) => <button onClick={() => close('approved')}>Approve</button>,
+});
+```
+
+Right-anchored slide-over on the SAME `<dialog showModal>` substrate as the
+rest of the manager — backdrop, Escape and stacking are native, so a drawer
+opened from an open modal simply takes the top layer. Header shape (eyebrow ·
+title · meta) is web-mojo's `Modal.drawer()` carried over.
+
+| Option | Meaning |
+|---|---|
+| `title` / `eyebrow` / `meta` | Header: big line, uppercase tag above it, subtitle row (`string` or `{icon, text}`) |
+| `content` | Static body ReactNode — ignored when `render` is given |
+| `render(close)` | Body that owns the result; `close(value)` resolves the await |
+| `width` | `480px` default · `'wide'` → `720px` · a number → px (min 280). Always clamped to the viewport (`min(w, 100%)`); full-bleed under 560px |
+| `dismissable` | Default `true`. Governs Escape + backdrop + the header X together — no half-states |
+
+- **Resolution:** `close(value)` → `value`; Escape / backdrop / X → `null`.
+  The promise settles AFTER the slide-out (~200ms), so `await` then toast
+  reads in the right order. First close wins; later ones are ignored.
+- **Exit animation:** close adds `.mojo-drawer-closing`, the manager waits out
+  the keyframes, THEN drops the item (unmount calls `dialog.close()`). Under
+  `prefers-reduced-motion: reduce` the wait is 0 and the keyframes are off.
+- **`dismissable: false` requires a `render`** that can close the drawer —
+  otherwise there is no exit at all, so it falls back to dismissable with a
+  `console.warn` (house rule: degenerate input → default + warn).
+- An unknown `width` warns and falls back to 480px.
+- Styles: `apps/portal/src/theme/drawer.css` (`.mojo-drawer`, `.drawer-panel`,
+  `.drawer-head/-eyebrow/-title/-meta`, `.drawer-body`) — tokens only, both
+  themes. `DRAWER_EXIT_MS` in `modal.tsx` must match the closing keyframes.
+
+**Boundary — this drawer is TRANSIENT.** It is a modal, top-layer, awaitable
+surface for drill-downs and one-off flows: it blocks the page, it resolves,
+it is gone. The persistent shell right-panel slot (tickets / assistant) is a
+different thing — a non-modal layout region that lives alongside content and
+holds state across navigation. Do not build that with `modal.drawer`, and do
+not grow `modal.drawer` toward it.
+
+## toast
+
+`toast.success(msg)` / `.error(msg)` / `.info(msg)` / `.warning(msg)` —
+bottom-right cards, max 5, 3.5s. Conventions:
+- Server failures: toast the server's message verbatim
+  (`err instanceof Error ? err.message : 'Fallback'`).
+- Batch partial results use `warning` (`"Disable: 3 succeeded, 2 failed"`).
+- `response: 'payload'` actions toast the SERVER's payload message
+  (`outcome.body.message`), not client copy.
+
+## Pitfall
+
+An open `<dialog>` pauses ModelTable's autoRefresh by design — don't build
+alternative modal systems that bypass `<dialog>` or that interlock breaks.

package/docs/file-upload-ux.md

@@ -0,0 +1,146 @@
+# File upload UX
+
+```tsx
+import {
+    AttachmentQueue, FileDropZone, FilePicker, UploadQueue, useUploadQueue,
+    validateFileSelection,
+} from 'portal-mojo/ui';
+```
+
+The UI layer composes the imperative transport documented in
+[`client.md`](client.md). It does not replace the server contract: browser
+validation is convenience only, and every accepted file still passes through
+django-mojo's initiate → byte transfer → authoritative reconciliation flow.
+
+Live examples: portal → Develop → Components → **File upload**. The Showcase
+transport and progress fixture live only in its demo module; package consumers
+use the real client by default.
+
+## Selection controls
+
+```tsx
+const selected = ({ accepted, rejected }: FileSelectionResult) => {
+    queue.add(accepted);
+    rejected.forEach((item) => toast.warning(item.message));
+};
+
+<FileDropZone
+    accept={['image/*', '.pdf']}
+    maxFileSize={10_000_000}
+    maxFiles={4}
+    onSelection={selected}
+/>
+
+<FilePicker accept=".csv,text/csv" multiple onSelection={selected}>
+    Import CSV
+</FilePicker>
+```
+
+`validateFileSelection(files, rules)` is pure. It returns ordered `accepted`
+and `rejected` arrays and never uploads. `accept` supports exact MIME types,
+MIME wildcards, and extensions. `maxFileSize` is bytes; `maxFiles` applies to
+one picker/drop gesture.
+
+Both controls are native buttons. The hidden input is a sibling, so the DOM
+does not nest interactive controls. The picker clears its input after every
+change, allowing the same file to be chosen twice in separate gestures.
+`FileDropZone` also installs a reference-counted window guard while mounted:
+file drags cannot navigate the tab when dropped outside the zone, while text,
+links, and other non-file drags retain normal browser behavior.
+
+`useFileDrop(options)` exposes the same behavior for a custom native control:
+
+```tsx
+const { isDragActive, dropProps } = useFileDrop({ onSelection: selected });
+return <button type="button" {...dropProps}>{isDragActive ? 'Drop' : 'Attach'}</button>;
+```
+
+## Queue
+
+```tsx
+const queue = useUploadQueue({
+    consumerKey: 'ticket-attachments',
+    destination: { use: 'support', groupId },
+    async onComplete(file, { signal }) {
+        await attachFileToTicket(file.id, { signal });
+    },
+});
+
+<FileDropZone onSelection={({ accepted }) => queue.add(accepted)} />
+<UploadQueue queue={queue} />
+```
+
+Defaults are concurrency **3** and capacity **6**. Files enter a FIFO and the
+transport task is not created until a slot opens; selecting six files never
+starts six initiate requests. The queue belongs to the mounted component—no
+local/session persistence and no TanStack Query cache. StrictMode's probe
+unmount is tolerated, but a real unmount aborts tasks and callbacks, removes
+progress cards, unsubscribes observers, and drops retained `File` references.
+An authenticated queue also disposes immediately if its auth UID changes or
+the session signs out.
+
+The queue deduplicates on consumer + normalized destination + file metadata.
+Use a stable `consumerKey` for the owning form/view. `destination` accepts
+`fileManagerId`, `groupId`, and the django-mojo `use` selector. Two consumers
+or two destinations may intentionally queue the same local file.
+
+The public snapshot is stable between transitions and deliberately inert. It
+contains safe filename/type/size, byte counts, status, sanitized failures, and
+safe completed File references. It never contains browser `File` objects,
+transport tasks, callbacks, capabilities, abort controllers, toast handles,
+raw errors, or auth data.
+
+`AttachmentQueue` is the shared reference-only composition used by record
+notes and Assistant chat. It adds picker/drop UI to the same queue and emits
+only completed `{id,filename,content_type,category}` references after checking
+the authoritative lifecycle result has a positive manager id and the exact
+expected group. It never emits browser Files, deletes a File, or turns a failed
+or uncertain upload into an attachable reference.
+
+Admin Files composes this primitive in `FileUploadSurface`: Add File and a
+drag-only whole-page overlay share an explicit policy-backed destination modal,
+while the queue remains mounted outside it. The surface fabricates neither
+progress nor reconciliation timers.
+
+## Outcome truth and actions
+
+- **Cancel** is a request. An active item becomes `cancelling`; it becomes
+  `uncertain` if django-mojo cannot prove the remote state. The UI never calls
+  an initiated transfer “cancelled” merely because `AbortController` fired.
+- **Retry** explicitly replays a retryable failed/id-less-uncertain task.
+- **Recover** appears only when the task has a known File id and invokes the
+  transport's reconciliation-only recovery—no duplicate byte transfer.
+- **Finalizing** begins after upload truth is `completed` and while
+  `onComplete` runs. It is non-cancellable and releases the transfer slot.
+- A rejected `onComplete` is `completed-warning`, not upload failure. “Retry
+  follow-up” reruns only the callback using the already-completed safe File
+  reference; it never replays the bytes.
+- Remove is immediate for queued/settled items. Removing an active item first
+  requests cancellation and only forgets it after transport truth settles.
+
+Every active attempt owns exactly one `toast.progress` card. Its displayed
+percentage changes only when real byte events cross an integer percentage.
+Reconciliation/callback work uses the additive non-cancellable `finalizing`
+state, then settles to success, failure, or completed-with-warning.
+
+## Headless use and verification
+
+`createUploadQueue()` exposes the same external-store controller for code that
+does not need the hook. `UploadQueue` is presentational and accepts any
+controller with the documented snapshot/actions, which also keeps Showcase
+fixtures out of production transport code.
+
+Run the focused executable contract:
+
+```bash
+npm run verify:upload-ux
+npm run verify:form-uploads
+npm run verify:record-attachments
+```
+
+It covers pure validation, lazy concurrency, capacity, stable/safe snapshots,
+consumer/destination dedupe, real progress updates, callback-only retry,
+truthful cancellation, known-id recovery, and byte-identical Portal/Showcase
+token CSS. The form contract adds strict relation normalization, explicit
+attach states, owner-response reconciliation, orphan retention, safe previews,
+avatar #1488 semantics, and cache-boundary sanitization.

package/docs/forms.md

@@ -0,0 +1,435 @@
+# forms — the Field language, SchemaForm, formModal, FormView (autosave)
+
+```ts
+import {
+    SchemaForm, SchemaSelect, formModal,
+    FormView, FileField, ImageField, registerFormTabs, getFormTabs,
+    type Field, type FormData, type FormTab,
+} from 'portal-mojo/ui';
+import { useFormAutosave, resolveShowWhen } from 'portal-mojo/ui'; // the machine, standalone
+// Field/FormData/ModelForm/FieldValues/ShowWhen TYPES also export from
+// 'portal-mojo/client' — model definitions carry form configs as plain data.
+```
+
+Two surfaces over ONE field language:
+
+- **SchemaForm / formModal** — submit-style (create dialogs, action forms).
+- **FormView** — the inline-autosave surface bound to a server row via
+  `defineModel`. **No save buttons**; edits save themselves.
+
+## The `Field` language (data, not JSX)
+
+```ts
+interface Field {
+    name: string;              // wire key; DOTTED names read/write nested dicts
+    type: FieldType;           // 6 builtins + every registry type (below) + (string & {})
+    label: string;
+    placeholder?: string;
+    required?: boolean;        // SchemaForm submit validation
+    help?: string;
+    columns?: 6 | 12;          // grid halves / full row
+    options?: FieldOption[];   // select/multiselect/combo: {value, label, description?, disabled?}
+    showWhen?: ShowWhen;       // conditional visibility (both surfaces)
+    schema?: ZodType;          // per-field zod validation (FormView commits)
+    disabled?: boolean;        // registry types
+    accept?: string | string[]; maxFileSize?: number; // file/image selection UX
+    uploadDestination?: { fileManagerId?; groupId?; use? };
+    onUploadOrphan?: (fileId: number) => void;
+    // …plus the registry-type props (precision, outputFormat, presets,
+    // model/endpoint, timezone, maxTags, …) — see "Field-type registry".
+}
+type FormData    = Record<string, FieldValue>;               // SchemaForm values
+type FieldValue  = string | number | boolean | null | Array<string | number>;
+type FieldValues = Record<string, FieldValue>;               // FormView values
+type ShowWhen    = { field; value; negate? } | ((values: FieldValues) => boolean);
+```
+
+**Builtins** — rendered inline by both surfaces, byte-for-byte the pre-B4
+behavior: `text` `email` `tel` `select` `switch` `textarea`. Every other
+type resolves through the **field-type registry** (below).
+
+`ModelForm = { title, fields, submitText? }` — the shape `defineModel`
+carries (`UserModel.forms.create`) and `formModal` renders.
+
+### showWhen (both surfaces, one pipeline: `resolveShowWhen`)
+
+Declarative rule = web-mojo FormBuilder semantics: the controlling field's
+current value is `String()`-coerced and matched against `value`
+(scalar or list); `negate` flips. Or pass a predicate over the live values.
+**Hidden fields don't submit/save, and their pending edits + errors clear.**
+
+### Per-field zod (`schema`)
+
+Validated at COMMIT against the display value (string for text-ish types,
+boolean for switch). A failing parse **blocks the save of that field only** —
+the first issue's message shows in the field's error slot; other fields keep
+saving. The server stays authoritative: values zod allows can still be
+rejected server-side (and then revert — below).
+
+## SchemaForm
+
+`<SchemaForm fields initial? submitText? onSubmit onCancel? />` — fully
+controlled; validates required + email format on visible fields; async
+`onSubmit` gets a busy state and surfaces thrown errors as the form alert.
+showWhen-hidden fields don't render, don't validate, and are stripped from
+the submitted payload.
+
+When file/image fields are present, submit, cancel, wizard steps/tabs, and
+modal dismissal lock while bytes are active. `onSubmit`/`onFinish` must return
+the authoritative saved owner row so the field can compare its returned
+relation to the requested id/null. A rejection or mismatch keeps the completed
+candidate available for attachment-only retry; it never replays bytes.
+
+**Select semantics (the rule-4 fix):** display always equals state. While
+the value is `''` (unset) the select shows a real disabled placeholder; an
+initial value not among the options warns once and shows the placeholder.
+`SchemaSelect` is exported — FormView renders selects through the same
+component. One select implementation, one value pipeline.
+
+## formModal
+
+```ts
+const data = await formModal({ ...UserModel.forms.create!, initial?, intro? });
+if (!data) return;   // cancelled → null
+```
+
+## FormView — inline autosave
+
+```tsx
+<FormView
+    model={UserModel}          // Pick<ModelDef, 'useSave'> — the batch POST
+    row={user}                 // current server row (snapshot + revert target)
+    fields={PROFILE_FIELDS}    // flat fields, and/or:
+    tabs="user.permissions"    // registry name — or inline FormTab[]
+    debounceMs={300}           // batch window (default 300)
+    savedFlashMs={1500}        // saved-check duration (default 1500)
+    onSaved={({ changes, fields, row }) => …}
+    onSaveError={({ changes, fields, error }) => …}
+    onPendingChange={(uploading) => setDetailDismissLocked(uploading)}
+/>
+```
+
+### The autosave lifecycle (the machine: `useFormAutosave`)
+
+1. **Commit, never keystroke.** Text/textarea update the draft per keystroke
+   (dirty dot) but COMMIT on blur — text also on Enter. Selects and switches
+   commit on change. This is by construction: web-mojo's per-keystroke
+   `input` autosave saved partial text (the ComboBox "Amer" leak).
+2. **300ms batch.** Each accepted commit (re)arms one window; commits inside
+   it coalesce. The batch POSTs **one save with only the changed fields**
+   (change-detection against the server snapshot: trimmed-string compare,
+   strict boolean for switches — `42` vs `'42'` and `null` vs `''` are not
+   changes).
+3. **Serialized.** While a POST is in flight, further commits queue the next
+   batch; completion re-arms the window. Never two saves interleaved for one
+   form. (web-mojo's `isSaving` guard silently dropped the queue — fixed.)
+4. **Indicators** ride the label row: dirty dot → spinner (queued + in
+   flight) → saved check (~1.5s) → idle. An **error pins** on the field with
+   the zod/server message until that field's next successful save.
+5. **Revert on fail.** A rejected batch restores every batch field to the
+   **server snapshot** and toasts the server's message verbatim — a failed
+   value never sticks (`Model.save` resolve-on-failure heritage ends here;
+   `useSave` REJECTS).
+6. **Reconcile.** The success row (and any `row` prop change — refetch,
+   another form's save) becomes the new snapshot; untouched fields follow it.
+   Server normalization is visible: save `555 010 0142`, the field comes back
+   `+15550100142`.
+
+### `file` / `image` relations
+
+Both registry bindings use the exported controlled `FileField`/`ImageField`
+over the one shared `UploadQueue` + client transport. Their public value is
+only a positive numeric File id or `null`; expanded relation objects normalize
+to their positive numeric id before generic string coercion, while booleans,
+numeric strings, non-positive numbers, and ambiguous objects normalize to
+null and are never posted as File ids.
+
+The explicit UI states are keep, clear, replacement-in-progress,
+replacement-failed, completed-awaiting-attach, and attach-failed. The stored
+relation remains the visible/revert baseline until upload completion and an
+authoritative owner save both succeed. FormView receives the exact sent File
+value plus saved row from its autosave mutation and reconciles only that File
+field: a result for an older candidate is ignored, while an exact returned
+id/null means attached; reject or mismatch restores the prior server value but
+retains the completed candidate for “Retry attachment.” Remove reports the
+candidate once through `onUploadOrphan`; Clear posts null. Neither action
+deletes File.
+
+ImageField previews a newly selected image with a component-local object URL
+and revokes it on replace/settle/unmount. Stored preview URLs are resolved by
+an imperative mounted File detail read, scheme-checked, rendered with
+`referrerPolicy="no-referrer"`, and never cached, persisted, logged, or copied
+into errors. Queue work is generation-guarded, cancelled on unmount/auth loss,
+and an active task is cancelled before removal.
+
+Image editing is opt-in. Direct use passes `edit` to `ImageField`; schema data
+passes `imageEdit` on an `image` field. The value is `true` for defaults or the
+`imageEditorModal` options (`startMode`, `modes`, `crop`, `maxHistory`, and
+labels). `requireEdit` (schema: `imageEditRequired`) removes the Use original
+escape hatch while still retaining the selection for retry/discard. The editor opens before upload initiation. Cancel and decode/encode
+failure retain the selected original locally with Edit/Use original/Discard
+choices; no File row, relation id, or owner save exists yet. Save converts the
+explicit PNG Blob into the exact File fed to the existing queue. Editing joins
+transfer in `onPendingChange`, so owning forms and dialogs keep their existing
+dismiss/submit lock.
+
+```ts
+{
+  name: 'avatar', type: 'image', label: 'Avatar',
+  imageEdit: {
+    startMode: 'crop',
+    crop: { aspectRatio: 1, cropAndScale: { width: 200, height: 200 } },
+  },
+  imageEditRequired: true,
+}
+```
+
+All machine state lives in one reducer (draft, server snapshot, per-field
+status, pending batch, in-flight flag); the two timers only dispatch.
+
+### Dotted names — the nested-value wire contract
+
+`name: 'permissions.manage_users'` reads `row.permissions.manage_users`
+(loose truthy: `true` or `1`) and saves as a **partial dict**:
+`{permissions: {manage_users: true}}`. django-mojo **merges** dict bodies
+into JSONFields (`rest.py on_rest_update_jsonfield` → `objict.merge_dicts`)
+— never send the whole dict, never fear clobbering sibling keys. The mock
+mirrors the merge exactly.
+
+### Permission tabsets — a registry, not mutated arrays
+
+```ts
+registerFormTabs('user.permissions', [
+    { key: 'standard', label: 'Standard', fields: [...] },
+    { key: 'users', label: 'Users', permissions: ['users', 'manage_users'], fields: [...] },
+]);
+```
+
+- Registering the same name again **appends new keys / replaces same keys**
+  (an app adds its tab beside the framework's — web-mojo
+  `registerPermissions` semantics without `arr.length = 0; arr.push(…)`).
+- `getFormTabs(name)` returns a snapshot copy; mounted FormViews re-render
+  on registration (subscription).
+- Tab `permissions` resolve **fail-closed like `<Guarded>`** against `me` +
+  the active-group member (`hasPermission`): hidden while loading, while
+  anonymous, and on failure. The active tab self-heals to the first visible.
+- A tab whose field holds a pinned error shows a red dot.
+
+The machine spans ALL tabs' fields — a batch may carry fields from several
+tabs; switching tabs loses nothing.
+
+## Field-type registry (board #1278)
+
+```ts
+import {
+    registerFieldType, resolveFieldRenderer, registeredFieldTypes,
+    warnUnknownFieldType,                       // the shared unknown-type warn
+    fieldToWire, wireToField,                   // the epoch boundary (field-wire)
+    emptyFieldValue, fieldPrecision,
+    type RegistryFieldProps, type FieldTypeRenderer,
+} from 'portal-mojo/ui';
+```
+
+`ui/field-registry` maps every non-builtin `Field.type` string to a renderer
+that binds the Field def + the form's controlled value/commit pipeline to
+the real component — web-mojo's `INPUT_TYPES`/`createInput` +
+FormBuilder's field-type switch, carried as a registry (also the FormPlugins
+replacement: apps extend with `registerFieldType`). **Both surfaces consult
+it**: SchemaForm and FormView render any registered type from the same
+schema, with the same commit semantics (every registry component fires on
+COMMIT, so each change is one autosave gesture).
+
+### The registry API
+
+```ts
+// Renderers are function components — they may hold hooks/state.
+type FieldTypeRenderer = ComponentType<RegistryFieldProps>;
+interface RegistryFieldProps {
+    field: Field;
+    value: FieldValue;              // form-state value (WIRE-shaped — below)
+    invalid?: boolean;              // paint the error border (text is the surface's)
+    disabled?: boolean;
+    commit: (value: FieldValue) => void;   // THE change pipeline, once per commit
+    commitPatch: (patch: FieldValues) => void; // one declared-field transaction
+}
+registerFieldType('rating', RatingField);       // add / replace (HMR-safe)
+registerFieldType(['a', 'b'], SharedField);     // aliases share one renderer
+resolveFieldRenderer('rating');                 // renderer | null
+registeredFieldTypes();                         // names, registration order
+```
+
+Names match **exactly** (no case folding): a typo'd type must fall through
+to the loud fallback, not silently half-match.
+
+**Unknown-type rule** (house rule 4): a type with no renderer renders a
+**text input** and `console.warn`s ONCE per (field, type) — never "render
+nothing". Both surfaces enforce it (`warnUnknownFieldType` carries the
+shared warn-once set).
+
+### The value-shape table
+
+**State holds the WIRE shape.** The registry renderer converts at its own
+edge — render through `wireToField(field, value)`, commit through
+`fieldToWire(field, value)` — so SchemaForm's submit payload and FormView's
+autosave batches carry wire-ready values without either surface knowing
+dates exist. This is the ONE conversion point.
+
+| `Field.type` (aliases) | Component | Control (what the picker holds) | State = wire (what the save body carries) | Empty |
+|---|---|---|---|---|
+| `tag`, `tags` | TagInput | chip list | **CSV string** `'a,b'` (django-mojo models split it) | `''` |
+| `multiselect` | MultiSelectDropdown | checked options | **array** of option values | `[]` |
+| `collection` | CollectionSelect | one picked row | the row's **id** (`string \| number`); `null` clears | `null` |
+| `collectionmultiselect`, `collection-multiselect` | CollectionMultiSelect | checked rows | **array of ids** | `[]` |
+| `combo`, `combobox`, `autocomplete` | ComboBox | committed option/text | the committed value (`string \| number`; free text iff `allowCustom`) | `''` |
+| `address` | AddressField | private draft + provider suggestions | raw committed address, or one atomic mapped details patch | `''` |
+| `datepicker`, `monthpicker`, `yearpicker` | DatePicker | canonical `YYYY-MM-DD` / `YYYY-MM` / `YYYY` | the shape it read (see below); **epoch seconds** at UTC midnight by default; `outputFormat` overrides | `null` |
+| `daterange`, `monthrange`, `yearrange` | DateRangePicker | canonical `[start, end]` pair | as above, per element — **`[startEpoch, endEpoch]`** by default | `null` |
+| `timepicker` | TimePicker (+ the REAL TimezoneSelect in its slot) | HH:MM (+ zone) | serialized **string** — `'iso'` (default) `'14:30-07:00'`, `'iana'` `'14:30 America/…'`; times are never epochs | `''` |
+| `datetimepicker` | DateTimePicker | `'YYYY-MM-DD HH:MM'` local | the shape it read; **epoch seconds** (exact instant) by default, ISO when the column spoke ISO | `null` |
+| `timezone` | TimezoneSelect | IANA zone | the IANA **string** | `''` (picker displays the local zone; `resolveTimezone` computes that effective default when a form must post it) |
+
+Alias precision mapping (web-mojo `PRECISION_ALIASES`): `monthpicker`/
+`monthrange` → `'month'`, `yearpicker`/`yearrange` → `'year'`; an
+**explicit `Field.precision` wins** over the alias (`createInput` parity).
+
+Registry-type Field props (all optional, additive): `precision`,
+`outputFormat`, `displayFormat`, `min`/`max`, `presets`, `months`,
+`separator` (tag CSV joiner / daterange display), `timeFormat`, `step`,
+`timezone`/`timezones`, `model`/`endpoint`, `labelField`/`valueField`,
+`maxItems`, `emptyFetch`, `debounceMs`, `requiresActiveGroup`,
+`defaultParams`, `enableSearch`, `maxTags`, `allowDuplicates`,
+`allowCustom`, `showDescription`, `maxSuggestions`, `addressFields`,
+`country`, `minChars`, `disabled`. Component
+knobs a Field doesn't carry (locale, firstDay, disabledDates, …) are
+reachable only by using the component directly.
+
+### The epoch-seconds save boundary (`ui/field-wire`)
+
+The measured django-mojo contract (serializer.py:380-389 +
+rest.py:1888-1892 / `dates.parse_datetime`): **DateTimeField serializes OUT
+as epoch seconds** and the save path parses epochs back in; DateField
+serializes OUT as `'YYYY-MM-DD'` but its save path ALSO accepts epochs
+(naive/UTC-parsed — a UTC-midnight epoch lands on the same day). Hence:
+
+- `wireToField(field, raw)` — accepts **every** shape django-mojo emits
+  (epoch seconds, epoch **milliseconds**, either of those as numeric
+  strings, `'YYYY-MM-DD'`, full ISO, `Date`), so rows mixing `last_login`
+  epochs and `dob` strings flow through one path. Detection is
+  `date/fns detectTemporal`; unparseable stored values warn once and read
+  as empty.
+- `fieldToWire(field, control)` — **answers in the shape the field last
+  read**. A column that arrived as `'YYYY-MM-DD'` saves back as
+  `'YYYY-MM-DD'`; one that arrived as ISO saves ISO; one that arrived as
+  epoch milliseconds saves milliseconds; everything else (and any field
+  never read — a fresh record) saves **epoch seconds**, the DateTimeField
+  contract. Canonical strings become UTC midnight for date-only
+  precisions; datetimes honor an explicit offset/IANA zone, else the
+  browser's local wall time.
+
+  This auto-detection exists because the wire shape is per-COLUMN, not
+  global: emitting epochs for everything silently rewrote a DateField's
+  type on every save and turned ISO metadata values into numbers.
+  `Field.outputFormat` (`'epoch' | 'date' | 'iso'`) remains the explicit
+  override and always wins — set it when a column's shape must not be
+  inferred. The remembered shape is keyed by the Field **object**, so
+  module-level schema constants (the normal case) carry it correctly and
+  two forms sharing a field name never collide.
+- **`dr_field/dr_start/dr_end` filter params are NOT this boundary** — they
+  stay `YYYY-MM-DD` strings and belong to FilterBar/params (rest.py parses
+  dr_* itself). Untouched.
+
+Every other type passes through both functions unchanged — its control
+shape IS its wire shape, per the table.
+
+### Kitchen sink
+
+The playground's **Field registry kitchen sink** section renders EVERY
+registered type (all aliases) from one schema on both surfaces — FormView
+autosave against the mock user (saves land in `metadata.*`, live
+control-vs-wire panel per field) and SchemaForm submit (exact payload
+shown) — plus the explicit-precision override, `outputFormat:'date'`, the
+#1273 seam, and the deliberate unknown type.
+(`apps/portal/src/pages/components/demos-kitchen-sink.tsx`)
+
+## Pitfalls
+
+`SchemaForm` and `FormWizard` share one controlled submit-state/rendering core. SchemaForm intentionally keeps its original lazy initialization and required/email-only submit contract; FormWizard adds cross-section validation, focus, reset, and roster reconciliation. `FormView` does **not** use that submit store: it retains the one autosave reducer across flat fields and all tabs. See [tabs-and-form-wizard.md](tabs-and-form-wizard.md).
+
+- Never uncontrolled inputs, never a second value pipeline — the
+  buttongroup/checklistdropdown bug class stays impossible only while this
+  holds.
+- Phone fields: django-mojo runs `set_phone_number` on save and wants E.164
+  (`+15555550142`); pretty/short formats REJECT with
+  `Invalid phone number: <value>` — surface it verbatim (FormView does).
+  The mock enforces the same rule.
+- Keep the client `schema` **looser or equal** to the server: client zod is
+  UX, the reject/revert path is the safety net — don't try to out-validate
+  the backend.
+- FormView needs a LOADED row — gate on `useOne`'s `isPending` first.
+- The rich field set (collection pickers, tags, dates, …) lives in the
+  field-type registry above — extend THIS language via `registerFieldType`;
+  don't fork it. New renderers must fire on COMMIT only and keep state
+  wire-shaped (convert in the renderer, like the date bindings do).
+- `commitPatch` is for one provider-driven gesture, such as address details.
+  Both form surfaces filter it to declared field names. FormView validates
+  and queues the whole accepted patch as one batch, so server failure rolls
+  every member back together.
+- `daterange` here is ONE field name whose value is a `[start, end]` pair —
+  NOT web-mojo's `startName`/`endName` twin wire keys. A model with two
+  separate date COLUMNS should use two `datepicker` fields.
+- `timepicker`'s `outputFormat:'object'` (component-level) is not a form
+  shape — form state is JSON-scalar/array; the registry always serializes
+  to the string forms.
+
+## Simple-types parity audit
+
+Every `case` in web-mojo `FormBuilder.js`'s field-type switch (the ~45-type
+FieldTypes list), vs this package. **Gaps are recorded, not built** — the
+orchestrator files follow-ups.
+
+| FormBuilder case | SchemaForm/FormView | Registry | Status / note |
+|---|---|---|---|
+| `text` | builtin | — | OK |
+| `email` | builtin (+ format validation) | — | OK |
+| `password` | — | — | **GAP** — C3 auth pages own password UX (strength/generator, board #1259) |
+| `number` | — | — | **GAP** — obvious next builtin (min/max/step props already exist on Field) |
+| `tel` | builtin | — | OK |
+| `url` | — | — | **GAP** — trivial builtin (text + `type="url"`) |
+| `search` | — | — | **GAP** as a FORM field; the live-search UX exists as the params-store search (ModelTable) |
+| `hex` | — | — | **GAP** — pattern-validated text; zod `schema` covers it today |
+| `textarea` | builtin | — | OK |
+| `htmlpreview` | — | — | **GAP** — sweep verdict: PATTERN (iframe preview), rebuild small when needed |
+| `json` | — | — | **GAP** — textarea + zod covers today; DataView/JSON viewer (#1303) is the read side |
+| `select` | builtin (SchemaSelect) | — | OK (placeholder + unknown-value warn beat source) |
+| `multiselect` | — | MultiSelectDropdown | OK |
+| `checkbox` | — | — | **GAP** — portal has `switch` only; plain-checkbox look absent (use `switch`) |
+| `toggle` / `switch` | builtin `switch` | — | OK |
+| `radio` | — | — | **GAP** — use `select`; radio-group component unfiled |
+| `date` (native input) | — | — | superseded by `datepicker` (registry) — native input not carried |
+| `datetime` (native) | — | — | superseded by `datetimepicker` |
+| `time` (native) | — | — | superseded by `timepicker` |
+| `file` | — | FileField | OK — positive File id/null; shared 3-stage queue; authoritative owner attach |
+| `image` | — | ImageField | OK — FileField foundation + safe local/stored image preview |
+| `color` | — | — | **GAP** — native `<input type=color>` wrapper unfiled |
+| `range` | — | — | **GAP** — native `<input type=range>` wrapper unfiled |
+| `hidden` | — | — | N/A by design — controlled forms post state, not hidden DOM inputs |
+| `button` | — | — | N/A by design — SchemaForm owns submit/cancel; FormView has no buttons |
+| `divider` | — | — | **GAP** — layout-only field (FormWizard/Tabs #1305 is the structure story) |
+| `html` | — | — | N/A by design — trusted-HTML slots became ReactNode (architecture rule 6) |
+| `heading` / `header` | — | — | **GAP** — layout-only field, same #1305 story |
+| `tag` / `tags` | — | TagInput | OK (CSV wire shape) |
+| `collection` | — | CollectionSelect | OK |
+| `collectionmultiselect` / `collection-multiselect` | — | CollectionMultiSelect | OK |
+| `datepicker` | — | DatePicker | OK (epoch wire; `outputFormat:'date'` opt-out) |
+| `monthpicker` | — | DatePicker | OK (alias → precision `month`; explicit `precision` wins) |
+| `yearpicker` | — | DatePicker | OK (alias → precision `year`) |
+| `daterange` | — | DateRangePicker | OK — deviation: ONE name, `[start, end]` value; no `startName`/`endName` twin keys (use two datepickers for split columns) |
+| `monthrange` | — | DateRangePicker | OK (alias → precision `month`) |
+| `yearrange` | — | DateRangePicker | OK (alias → precision `year`) |
+| `timepicker` | — | TimePicker | OK (real TimezoneSelect in the slot; string wire) |
+| `datetimepicker` | — | seam → DateTimePicker | OK once #1273 merges (alias + epoch boundary live now; interim text input) |
+| `checklistdropdown` | — | — | folded into `multiselect` (sweep: ONE implementation) — alias deliberately NOT registered |
+| `buttongroup` | — | — | **GAP** — segmented control; source was the split-pipeline bug family (do-not-recreate), needs a fresh build |
+| `combo` / `combobox` / `autocomplete` | — | ComboBox | OK (ComboInput feature spec, commit-only) |
+| `address` | — | AddressField | OK (private session token, details → atomic declared-field patch) |
+| `tabset` | FormView `tabs` prop | — | OK — tabsets are FORM STRUCTURE here (registry-of-tabs + permissions), not a field type |