@lotics/ui 11.4.0 → 11.6.0

package/docs/data_entry.md

@@ -0,0 +1,398 @@
+# Data entry — which pattern for which job
+
+How data gets captured and edited in a `@lotics/ui` screen: inline edit, forms, find-or-create,
+line items, handoffs, phased records, billing, tags, dispositions, attachments, and stage gates.
+This is the most common thing to get right — read it before building any editing surface, and
+match the JOB to the pattern below. Exact prop APIs are the shipped sources — `../src/<name>.tsx`
+(never guess a prop; open the file). The component inventory lives in [the catalog](./catalog.md),
+layout/color laws in [the composition grammar](./composition.md), and full worked-example screens
+in [the templates](./templates.md) (`examples/tpl_*.tsx`).
+
+## The decision table
+
+| You're capturing… | Reach for | Why |
+|---|---|---|
+| an EXISTING record's fields | [**Inline edit**](#inline-edit--the-preferred-way-to-edit-an-existing-record) (`Inline*`) | edit in place, no form mode |
+| a brand-NEW record | **create-then-refine** (`tpl_record`: "New" is ONE CLICK → a fresh Draft; everything refines in place on the record surface) | nobody fills 5 sections in one sitting; the surface is the editor |
+| a RELATED record (pick or make) | [**find-or-create**](#find-or-create--the-combobox-family-is-the-control) (`Combobox allowCustom`) | one control covers both |
+| REPEATING rows you build & revise | [**line items**](#line-items--create--preview--edit-a-composition-not-a-primitive) (create→preview→edit) | add / edit / remove, live totals |
+| CHARGES that bill onto documents | [**billing**](#billing--the-invoice-document-is-the-unit) (`tpl_record` Billing section) | the invoice document is the unit |
+| a record's FEE/charge SUMMARY | [**`Ledger`**](#fee-summary--ledger) (worked example: `tpl_item_list` drawer) | grouped money lines, one emphasized total — no bars/charts |
+| a multi-value TAG field | [**`Select multi`**](#tag--multi-value-field--select-multi) (`renderSelected` → `Chip`) | chips composed, not a separate control |
+| ONE choice from a small visible set | **`ChipGroup` pills** (or `RadioPicker`) | required single-select, one tap, every option visible |
+| a STATUS with terminal outcomes | [**disposition**](#disposition--lifecycle-status-is-asymmetric-by-phase) (open → resolve → revise) | guides the decision |
+| FILES | [**attachment field**](#attachments--a-full-add--preview--delete-field) (dropzone + grid + gallery) | add / preview / delete |
+| a state TRANSITION mid-flow | [**stage gate**](#stage-gates--tiered-by-weight) (popover / dialog by weight) | right-sized friction |
+
+## Inline edit — the preferred way to edit an existing record
+
+When the whole record is editable (a detail/record screen, dense settings), don't wrap it in a
+form mode or a preview↔edit card — make each VALUE inline-editable: it reads as a value on a quiet
+chip, hover reveals the input-family border (no extra grey wash, no pencil icon that shifts
+layout), click swaps the input in **at the same height** (zero reflow, the whole point), and it
+commits on blur (Enter saves, Escape reverts) or via `controls="buttons"` (✓ primary / ✕).
+
+One per type:
+
+- **`InlineTextInput`** — plain text; `struck` renders the value struck-through (a done task title).
+- **`InlineNumberInput`** — `format` formats the RESTING value (currency, units); edit mode is a
+  bare number input with `min`/`max`.
+- **`InlineSelect`** — plain options OR `renderOptionContent`; floats an `OptionList` in a popover
+  so the row never grows; the RESTING value renders like its option (`renderOptionContent` by
+  default; `renderSelected` overrides) — a colored `OptionBadge`, not just a label.
+- **`InlineMemberSelect`** — a `MemberChip` at rest → member picker; the inline twin of
+  `MemberSelect`; worked example: `tpl_record`'s "Sales owner" fact.
+- **`InlineDatePicker`** — `format="datetime"` for always-on time; `optionalTime` to let the user
+  ADD/REMOVE a time — the value's own shape, date vs datetime, is the source of truth
+  (`optionalTime` is ignored when `format="datetime"`).
+- **`InlineTimePicker`** — a time-only value.
+- **`InlineTagSelect`** — the MULTI member — a tag SET in the inline vocabulary: selected tags
+  render as badges inside the standard chip, clicking floats a multi `OptionList` (checkbox rows),
+  CLOSING commits the new set in one `onSave` — never a borderless `Select` posing as an inline
+  field.
+
+All are built on **`useInlineEdit`** + **`InlineEditView`** (custom inputs join the family via
+those). `onSave` is async: the saving spinner sits INSIDE the control at its right edge (never a
+sibling — that reflows); an error shows inline without losing the edit.
+
+To let a value be UNSET (a diff-write CLEAR — unassign, remove a due date, drop a select), pass
+**`onClear`** to `InlineSelect` / `InlineMemberSelect` / `InlineDatePicker`. It surfaces through
+each popover's OWN clear affordance — `InlineSelect` renders a compact left-aligned "Clear"
+`Button` below the `OptionList` (only while a value is set); `InlineDatePicker` reuses the
+calendar's own footer "Clear" button. Never a bolted-on sibling row (it can't reach the option
+list's active-highlight and doubles the footer hairline), and never a persistent ✕ on the resting
+cell (noise on a dense board, and a pressable nested in the trigger is invalid DOM). `onSave`'s
+`next` stays non-null — a caller opts in per field; the clear fires `onClear`, which writes `null`
+(the app workflow must ACCEPT null on that input — a `select`/`date`/`member` field clears on
+null). `InlineTagSelect` (multi) needs no `onClear` — an empty set is already a valid `onSave`.
+
+### The row stack — `DetailTable` + `DetailRow`
+
+A STACK of rows lives in a `DetailTable` (label · value · trailing laid out like a TABLE:
+`labelWidth` / `trailingWidth` / `minHeight` set ONCE on the parent, plus the 6px row gap the
+zinc-50 chips need) holding `DetailRow`s — set `trailingWidth` when ANY row carries a trailing
+action/badge, so EVERY row reserves the column and one row's `Copy` button never makes its editor
+narrower than its neighbours'.
+
+### The editability affordance
+
+An editor AT REST sits on a zinc-50 chip — THE editability affordance: users see what's editable
+without hovering. `background="transparent"` opts a field out of the chip — for DENSE,
+uniformly-editable surfaces (a task list/board where EVERY cell edits: the chip repeated
+everywhere is noise and distinguishes nothing; hover/focus still reveal the input). Keep the chip
+wherever editable and static values MIX. A `disabled` editor rests FLAT automatically — the chip
+is the editability promise, and an inert field must not make it.
+
+A READ-ONLY value in the same column — a computed total, a system ID, a synced/locked field — is
+**`InlineStatic`**: it copies the editor box metrics exactly (height, padding, 1px transparent
+border) but stays FLAT and non-interactive, so editable (chip) vs read-only (flat) is legible at a
+glance and the static value never reads as a disabled input.
+
+To hang a right-side action/badge off a row, use `DetailRow`'s `trailing` slot (NOT for units —
+"kg"/"$" belong IN the value via `InlineNumberInput format`) — see the "Details" `DetailTable` of
+`tpl_record`, which also reads top→bottom as a full record surface (header → fields →
+`DangerZone`). Not every field is a same-height swap — a tag field, a status, or an attachment
+grid edit in place too (below).
+
+## Fieldset form — fields lay out on a RESPONSIVE two-column grid
+
+Never hard-code columns, never 3-up. A fieldset is `flexDirection:row, flexWrap:wrap,
+columnGap:16`; each `FormField` declares an intrinsic width via `style` — `half` (`flexGrow:1,
+flexBasis:240`) or `full` (`flexGrow:1, flexBasis:"100%"`) — so two halves sit side-by-side on a
+wide card and stack on a narrow one with zero media queries. Pair short, related fields as halves
+(phone/email, qty/price); give long or singular values the full row (legal name, address, notes).
+Past two columns the label→field link breaks — MANY inputs means GROUPING into labeled fieldsets
+(each its own 2-up grid, `Divider` between), never a third column. `FormDatePicker`/`FormPicker`
+wrap their OWN `FormField` (and don't put a `style` on it) — for a grid cell use a bare
+`FormField style={half}` wrapping `DatePicker`/`Picker`.
+
+## Find-or-create — the `Combobox` family IS the control
+
+`Combobox` is COMPOUND: a root holds the DATA + behaviour (the shared `useOptionList` engine —
+`options`, `value`, `onValueChange`, `onSearchChange`, `allowCustom`, the per-row
+`getOptionDescription`/`renderOptionContent` so they're typed against the option `data`), and the
+parts render the CHROME, composed as children — never a render-prop pile:
+
+```tsx
+<Combobox options={hits} value={sel} onSearchChange={setQ} onValueChange={pick} allowCustom
+          customOptionLabel={(q) => `Create "${q}"`} getOptionDescription={(o) => o.data?.code}>
+  <ComboboxInput icon="search" clearable onClear={deselect} placeholder="Find or create…" />
+  <ComboboxContent recentsLabel="Recent">
+    <ComboboxEmpty>No match — type a name to create one</ComboboxEmpty>
+    <ComboboxFooter>{validity}</ComboboxFooter>
+  </ComboboxContent>
+</Combobox>
+```
+
+It's a SELECT by default (`ComboboxInput` with NO `icon` → a trailing chevron); opt INTO the
+search-box look with `ComboboxInput icon="search"` only when typing-to-search is primary (a
+large/remote set). For a select that the user can RESET, pass `clearable` + `onClear` (deselect):
+the chevron shows while the field is empty and a clear ✕ replaces it once there's a value/query;
+pressing ✕ clears the text and reopens the full-browse list, so `onClear` lands back on the whole
+set (on focus an empty field already browses everything — `recentOptions ?? all`).
+
+`allowCustom` appends a "Create …" row (`customOptionLabel`) when the query matches no option,
+emitting the typed text as the value — so a value not in the known set means CREATE. Wire that
+branch to a create overlay (an anchored popover for a 1–2 field gate, a modal `Dialog` for 3+)
+that builds the new record and attaches it; existing matches attach directly. A record-CREATION
+dialog stays a MINIMAL gate and really creates — the row lands and its own workspace opens for
+refinement (an EMPTY checklist, commons as ghosts). NEVER a creation wizard: create-then-refine
+puts complexity on the record surface, not in front of it.
+
+The create row sits BELOW matches by default (the keyboard highlight lands on the first MATCH, so
+Enter on a partial picks it, never a duplicate); pass `customOptionPlacement="top"` to pin it
+above. Use `reflectSelection={false}` and render the attached record below as a card with a
+Change action.
+
+For input-level status that must stay visible while results scroll (validity feedback on the typed
+value, a result count, a secondary "create" affordance), drop a `ComboboxFooter` into the content —
+a pinned row below the listbox, OUTSIDE keyboard option-nav; call `useCombobox().close()` from a
+footer action that hands off elsewhere (so the popover dismisses cleanly instead of floating over
+what you navigated to). A `ComboboxEmpty` child gives the no-match state richer content than the
+`ComboboxContent emptyText` string.
+
+## Line items — create → preview → edit (a composition, not a primitive)
+
+For a list of records you build then revise (invoice rows, repair lines, config entries), each
+item is a `Card` toggling between a read-only PREVIEW (a stack of `DetailRow`s) and an EDIT form
+(the inputs), via a local `editing` flag + Edit/Save/Cancel in the `CardFooter`. A freshly-added
+item opens in edit; Save collapses it to the preview; Edit reopens it. **Edit is cancelable** —
+snapshot the item on Edit so Cancel reverts, or DISCARDS a freshly-added one. Duplicate sits left;
+the destructive **Delete is `danger-secondary`**; Cancel + the Save/Edit toggle sit right. Every
+screen composes its own (~15 lines) so the preview rows + form fit the data.
+
+## Handoff — a stage transition, never a message
+
+When work crosses departments (sales → operations → accounting), the HANDOFF is the RECORD
+changing desks — never an inbox, a notification, or a copied task. Two types:
+
+**(A) Same entity** → a STAGE field on the shared record: sections carry OWNER dot tags, and the
+handoff is MANAGED AS TASKS — each desk's checklist on the record (the task-row vocabulary:
+sibling `CheckCircle` + struck transparent `InlineTextInput` + per-task `InlineMemberSelect`
+assignees + the `CaptureRow` add-affordance — never a decorative progress strip). A NEW record
+starts with an EMPTY checklist — tasks truly vary. The commons split in two: MANDATORY tasks are
+seeded by the app (a workflow on create, per record type) — no human types them; common-but-
+OPTIONAL tasks appear as `SuggestionChip`s under the list — a PILL, never a row, so a suggestion
+can't be mistaken for a task (tap = materialize, ✕ = dismiss for this record; already-present
+labels filter out; suggestions never count in done/total and pause while a filter narrows the
+view) — the same suggestion grammar as the billing Standard pill. Real rows carry a ⋯ `menu` (an
+`ActionMenu`; Delete lives BEHIND it, danger-styled and last — never a bare ✕ a stray tap can
+hit), completing the checklist's CRUD.
+
+Open tasks INFORM the handoff, they NEVER block it: the CTA stays enabled, the count warns, and
+open tasks carry over. The handoff CTA opens a DIALOG for the receiving desk (assignee
+`MemberSelect` + an optional note; the open-task warning inside); confirming closes the drawer —
+the record left this register.
+
+Tasks PEEK from the register: the done/total column is a pressable compact-`ProgressBar` trigger
+whose popover holds the checklist on FIXED columns — every row ring · struck `InlineTextInput`
+title (flex) · quick-reassign `InlineMemberSelect` (140) — no expandable rows (tags/files depth is
+the Task list template's lesson, not the peek's); the popover body is `PopoverContent`'s own
+ScrollView (`disableBodyScroll` is ONLY for children that manage their own scroll, like
+`OptionList`). The DRAWER carries a real Tasks SECTION in the Record template's shape (heading +
+the compact meter + the same checklist) — one shared task state per record feeds the column, the
+peek, the section, and the handoff dialog; a section owned by a later desk sits visible but GATED
+("Billing opens when the record reaches Accounting"). Registers scope by stage — the receiving
+department's register IS its inbox. The sender's sections stay editable after handoff (the gate
+transfers RESPONSIBILITY, not access — locking is app IAM, not template grammar). Worked example:
+`tpl_record`.
+
+**(B) Different entity** (a deal → a shipment) → SPAWN-AND-LINK: the upstream record's terminal
+gate CREATES the downstream record on the shared spine, linked both ways (a linked-record row
+each side); usually TWO apps — the upstream closes its own lifecycle, the downstream starts fresh
+in its department's app. Never merge the two lifecycles into one record.
+
+## Sequential phases on one record + the outline rail
+
+When a record's work happens in ORDERED PHASES (check-in → check-out; receive → dispatch), the
+phases are NOT tabs or a segmented control — hiding the other phase loses the context the current
+one needs and buries why its gate is blocked. Both phase sections sit on ONE page in
+chronological order; each phase owns ITS OWN fee rows + phase total (the invoice-band idea one
+level up — money never reads as one pot); each closes with a SEQUENTIAL confirm gate that names
+its blockers ("Confirm check-in first."). The header status chip carries the phase.
+
+A LONG record surface pairs with a LEFT OUTLINE RAIL — `MenuButton` items + `useSectionNav`
+(scroll-spy: jump to a section, the highlight follows the scroll); on narrow containers the rail
+becomes a PINNED bar naming the current section that opens a full-page section-picker `Modal`. A
+per-phase dot on a rail item carries its confirmed state. A direction that is a TYPE (one record
+per event) is instead a discriminator chosen ONCE at creation — a `SegmentedControl` in the
+create step, never a toggle on the record.
+
+## Billing — the invoice DOCUMENT is the unit
+
+When charges get grouped into issuable documents (an e-invoice, a bill) and then collected, don't
+split the screen into "enter fees here, issue there" — that smears one job across two places.
+Make **each invoice a FLAT hairline-set band that holds its own editable charge lines** (amount
+input + payment method), its **live total**, its **status badge** (nothing-to-bill · draft ·
+issued + ref), and its **issue action** in its closing row — no card chrome; data-capture
+templates are flat (see [the composition grammar](./composition.md)). A charge never lives apart
+from the document it bills on. Issuing is gated **inline, never a dead end**: when a prerequisite
+is missing (a bill-to tax ID, a method on a charged line) the issue button disables with one muted
+line saying what's needed; the payment-method picker turns required the instant a line carries an
+amount. Issuing a real e-invoice is irreversible → confirm in a `Dialog` (stage gate). A
+grand-total **receipt** validates first — surface the EXACT missing methods (`Alert.alert` listing
+each) rather than a vague "incomplete." A refundable **deposit** is its own card and its own
+receipt — never folded into the total due. Composition over `Card` + `NumberInput` + `Picker` +
+`Badge`; no new primitive. Worked example: `tpl_record`'s Billing section.
+
+## Fee summary — `Ledger`
+
+For a record's fee/charge SUMMARY (read-heavy, one payment action), reach for the `Ledger`
+compound: **`LedgerGroup`** (label + group sum) → **`LedgerRow`** (label · `meta` · ONE right
+tabular money column; `peek` makes the row a door to its PARTICULARS in an anchored popover —
+references live INSIDE the peek, since a row is never a button holding another button (`reference`
+is ignored while `peek` is set); `reference` = a trailing link on a non-peek row — an issued
+invoice, a receipt no.) → **`LedgerTotal`** (divider-set emphasized close, `zeroLabel` for the
+settled state, `tone` for a danger balance). The root `Ledger` takes `formatValue` so every row
+formats money one way. Pair it with a Record-payment POPOVER that appends a receipt. No
+bars/charts. Worked example: the `tpl_item_list` drawer.
+
+## Tag / multi-value field — `Select multi`
+
+A tag field's resting state should be a tidy CHIP BOX — and that's just a multi `Select` whose
+`renderSelected` returns a removable `<Chip onDismiss={remove}>`. There's NO separate component
+and no `display` mode: `renderSelected(item, { remove })` composes the anchor — render a `Chip`
+with `remove` for the ✕, or a plain `OptionBadge`/`MemberChip`/custom pill that ignores it;
+`renderOptionContent` renders the menu rows. `searchable` adds the filter field, `allowCustom` the
+create row. Borderless for a grid cell? Pass a `style`, never a `variant`. `Combobox` is the
+SINGLE-value sibling — for a search that emits one pick at a time and renders the selection
+elsewhere, use `reflectSelection={false}` (see the [templates](./templates.md)).
+
+## Disposition — lifecycle status is ASYMMETRIC by phase
+
+When a status is an OPEN default plus terminal OUTCOMES the user decides (Lead → Closed/Lost,
+Draft → Confirmed/Cancelled, Open → Approved/Rejected), a 3-way segmented/dropdown is wrong — it
+treats a lifecycle as flat peers and guides neither the decision nor the revision. Split by
+phase: while OPEN, surface the outcomes as ACTIONS with valence (`Mark closed` = `primary`,
+`Mark lost` = `danger-secondary`; the open state a quiet dot `Badge`). Coloring the buttons is
+right here — a SINGLE record-level decision is not the approvals-queue "wall of loud buttons."
+Once RESOLVED, show the colored STATE (`Badge variant="dot"` — emerald positive / red negative /
+blue open) with a quiet, REVERSIBLE **Change**: a popover STATE SWITCHER (each state a colored
+dot + label, current marked + disabled), not a generic text menu. A composition (Badge + Button +
+Popover/MenuButton).
+
+## Attachments — a full add / preview / DELETE field
+
+### Default: `FilesEditor`
+
+**`<FilesEditor files onAdd onRemove>`** bundles the upload-aware grid + a toolbar below it
+(Upload · Select · Download all) + a batch SELECT mode + the full-screen gallery +
+Alert-confirmed remove; the host only owns `files` and wires `onAdd` (picked → its upload) /
+`onRemove`. The destructive per-tile ✕ shows only in SELECT mode (the default view is a clean
+preview — no stray-tap deletes); pass `selectTileRemove={false}` to drop that ✕ entirely so
+select mode deletes ONLY via Select → Menu → Delete (the batch gating flow — right for a
+height-bounded cell editor). The built-in gallery is Download + inline preview (no "open in new
+tab" — it's redundant once everything previews inline). In a height-bounded container (a
+popover/drawer) pass `gridMaxHeight` so the grid SCROLLS and the toolbar pins below it; omit it
+in free-flow layouts (a form field) where the grid grows.
+
+The rest of the surface: `uploads` passes the live add-queue through to the grid (with
+`onUploadRemove`/`onRetry`/`onRetryAll`); `onUpload` overrides the Upload action's built-in web
+picker (e.g. a native document picker); `readOnly` (or omitting `onRemove`) makes it a view-only
+download+preview surface; omitting `onAdd` hides Upload. Select mode gains a Share action via
+`onShareSelected(files)` and a "Download as ZIP" item via `onDownloadZipSelected(files)` (shown at
+2+ selected) — both host-provided, hidden when omitted. `onDownload` overrides the default
+per-file `downloadFileFromUrl`; `accept` filters the picker; `itemSize`/`minItemWidth`/`columns`
+pass through to the grid; `credentials` covers auth-gated preview URLs; `labels` /
+`galleryLabels` localize the toolbar and the gallery chrome.
+
+Reach for the lower-level pieces below only when you need custom chrome.
+
+### The pieces — `FileDropzone`, `FileGrid`, `FileGalleryModal`, `FileRow`
+
+Capture with `<FileDropzone onFiles accept label hint dropLabel height>` (drag-over lights the
+accent; click falls back to a picker); display what landed with **`<FileGrid files uploads>`**
+ABOVE the dropzone (existing files are the content; the dropzone sinks to the bottom as the "add
+more" affordance — only the empty state leads with it).
+
+`FileGrid` is the upload-aware grid: `files` are the saved/completed `DisplayFile`s, `uploads` is
+the LIVE add-queue (`FileUpload[]`) — it interleaves both and renders each in-flight tile itself —
+a LABELED status overlay (uploading spinner · "Retrying" · "Paused" · "Upload failed" + a retry
+button · "Can't upload" for a dead/empty file) — so you never hand-map an upload to a
+`FileThumbnail`. Localize the labels with `labels.upload` (an `UploadStatusLabels`) and
+`labels.retryAll`. **Limitation:** the upload-status labels are NOT wired to
+`LoticsLocaleProvider` — they default to English; pass `labels` per instance to localize.
+
+Make it CRUDable by wiring its callbacks: `onFilePress` → set a `number|null` index that drives
+`<FileGalleryModal files activeIndex onIndexChange>` — a FULL-SCREEN viewer with a toolbar
+(filename · counter · actions — download, optional `onOpenExternal`/`onRemove` · close-✕),
+prev/next, ESC, and rotate. The toolbar is RESPONSIVE: on a phone (`useScreenSize().small`) the
+actions collapse into a `⋯` `ActionMenu` so the close-✕ never overflows off-screen (its popover
+portals inside the modal's own `PortalHost` — a raw `<Modal>` lacks one, which is why an inline
+popover would render behind the overlay). The 90° rotate controls for images are NOT in the
+toolbar — they FLOAT as a pill overlaid on the image (every screen size).
+`onDisplayRemove`/`onUploadRemove` → drop the file / cancel the upload (the grid renders a ✕ on
+each tile automatically); `onRetry` / `onRetryAll` for failed uploads.
+
+In a sandboxed custom-code app the gallery's "open in new tab" can't pop a window — pass
+`onOpenExternal` wired to the SDK's `openExternal` (omit it elsewhere and the action hides).
+PDF/Word/Excel/CSV all render INLINE here (pdf.js / `@lotics/docx` / `@lotics/xlsx`, lazy-loaded) —
+no native `<iframe>` viewer, so they work inside a cross-origin app iframe. Keep
+label+grid+dropzone on a `gap` (a bare `CardBody` has none).
+
+By default `FileGrid` tiles FILL the container width — a uniform size (≥ `minItemWidth`, default
+96) so full rows span the width and reflow as it changes; a short last row keeps that size and
+left-aligns (no stretched tiles, no empty cells). Pass `columns` for a fixed column count, or
+`itemSize` for exact fixed-size tiles. For a dense strip in a FIXED-width container that must NOT
+wrap, pass `singleRow` — it fits as many tiles as the width allows and collapses the rest into a
+clickable "+N" overflow tile (`onOverflowPress(hiddenCount)`, which the host wires — e.g. open the
+gallery at the first hidden file). This is the responsive overflow pattern (avatar stack /
+file-manager); prefer it over a hardcoded `maxVisible`, which can't adapt to width.
+
+Under the hood it composes `FileThumbnail` (the completed tile — right surface per MIME: image
+thumbnail · a doc tile with the `FileBadge` centered + a single-line filename · media card; also
+takes `isTemplate` to overlay a TMPL marker) and `UploadingThumbnail` (the in-flight tile); reach
+for either directly only when hand-rolling a NON-grid layout. **When the filename must be
+readable, use `FileRow`** — a horizontal LINE (`FileBadge` or a `placeholder` + the FULL name + a
+meta line + a composable `trailing` slot). `onPress` makes the whole row a pressable door (open
+the file); `trailing` (a status `Badge`, an action, a remove ✕) stays an independently-pressable
+sibling. For attachment lists / message files / document checklists where a square tile truncates
+the name.
+
+Never hand-build a drop well, a file grid, the upload tiles, or a preview modal. In a custom-code
+APP, don't hand-roll the upload+preview state either — `@lotics/app-sdk` `useAttachments()` gives
+the chat's instant-preview lifecycle (local object-URL now, `file_id` on complete); map each
+`AttachedFile` to a `FileUpload` (ready → `{ status: "complete", id, file: {…} }`, else
+`{ status, id, filename, mimeType: mime_type, previewUrl: preview_url }`) and feed `FileGrid`'s
+`uploads` — `onUploadRemove={remove}`.
+
+### Gated file CRUD — a PATTERN, composed locally, not a sealed kit component
+
+When a file field must GUARD deletion (operator-facing, accidental delete is a real risk), DON'T
+use `FileGrid` (its per-tile ✕ is exactly the stray-tap risk you're guarding against) — compose it
+in the app from the kit pieces; don't reach for a one-size widget (the action set + layout vary
+per app — each host composes its own). The recipe: `FileDropzone` (add) + `FileThumbnailGrid
+files selectedIds onFilePress` (pass `selectedIds` ONLY in select mode) + `FileGalleryModal`
+(view + rotate + persist) + a `Dialog` confirm, all driven by **`useSelectionMode()`** — the
+reusable LOGIC. The gating rule: **NO per-thumbnail ✕** — delete is **Select → ⋯ menu → Delete →
+confirm**, so a stray tap never removes a file. Three reusable primitives back it (the logic is
+shared; the action bar + layout + copy stay local):
+
+- **`useSelectionMode()`** (`@lotics/ui/use_selection_mode`) — `{ active, selected, enter, exit,
+  toggle, toggleAll }`, an agnostic multi-select state machine (string ids; pairs with the grid's
+  `selectedIds`).
+- **`shareOrDownloadFiles(files, { title, credentials })`** (`@lotics/ui/share_or_download`) —
+  `navigator.share({ files })` (mobile → save to gallery / send to an app), else individual
+  `downloadFileFromUrl` — **never a ZIP**. It shares the BYTES (fetches each URL → `File`), so URL
+  expiry afterward is moot; the share path needs the host iframe to grant `allow="web-share"`
+  (else it falls back to download). Best for FAST urls (presigned storage). **For SLOW urls (an
+  auth-gated proxy with a server round-trip), split it:** `prepareShareFiles(files,
+  {credentials})` fetches the `File[]` BEFORE the gesture (on menu-open), then `shareFiles(File[])`
+  runs `navigator.share` synchronously on the tap — **iOS Safari rejects `share()` if a slow fetch
+  burns the tap's transient activation**, which silently lands in the download fallback.
+  `prepareShareFiles` throws on a fetch failure (log it, don't swallow) and returns `null` when
+  Web Share is unavailable (download instead); `shareFiles` returns
+  `"shared" | "cancelled" | "unsupported"`.
+- **`rotateImageToBlob(url, degrees)`** (`@lotics/ui/rotate_image`) — canvas-bake a 90° rotation
+  into a NEW blob for re-upload (`useImageRotation` is view-only; this is how a rotation is
+  persisted). Pair with `FileGalleryModal`'s `onPersistRotation`/`persisting` (the ✓ shown on a
+  rotated image).
+
+## Stage gates — tiered by weight
+
+A transition that needs NO input is one click. 1–3 quick fields → a POPOVER FORM anchored to its
+action button (title + one-line stake + `FormField`s; confirm in `PopoverFooter`). A
+destructive/exception path (anything touching money or locks) → a `Dialog` (consequence in prose,
+danger confirm + cancel in `DialogFooter`) or an `Alert.alert(title, message, [{cancel},
+{destructive}])` confirm. Never an inline expanding panel for a gate — it shifts layout and loses
+the "this is a gate" framing.