@lotics/ui 14.1.0 → 14.3.0

package/AGENTS.md

@@ -56,6 +56,11 @@ doc before building any screen, **never from memory**. Exact props are the shipp
   hand-picked palette shade; color is `solid`/`tint`/`ramp` with ONE accent per screen.
 - **Pure primitives only** — no i18n, analytics, or domain types in `src/` (pass `labels`,
   callbacks); Lotics-coupled UI belongs in `@lotics/ui-internal`.
+- **A button never contains a control** — a row that presses open AND carries its own controls
+  (a CTA, ⋯, a checkbox, a `Link`) is a role-less `PressableRow` + a **`PressDoor`** sibling
+  (the tab stop, name, focus ring), never `PressableHighlight`, which wraps its children in the
+  button. `Table`/`TableRow` and `LinkedRecordBox` already do this. →
+  [composition.md](./docs/composition.md).
 - **Every state designed** — skeleton (mirroring layout), empty, error; no layout shift.
 - **Copy states content, not mechanics** — a `description` names the section's content or one
   domain rule; widget behavior ("edits in place, saves on its own") and selling points never

package/docs/ai_patterns.md

@@ -39,7 +39,7 @@ Three shapes:
 
 The Document desk's Use-AI fork IS this table as UI: Extract data (1) · Cross-check (2) ·
 Edit with AI (3) — one entry point, three outcome shapes
-([`tpl_documents`](../examples/tpl_documents.tsx)).
+([`tpl_record`](../examples/tpl_record.tsx)'s Documents section).
 
 ## Command / compose — `Composer`
 
@@ -138,16 +138,20 @@ pass it as the `error` prop and it renders as a terminal danger row under the tr
 
 **In a bounded container, wrap it in `FollowScroll`.** An `AgentRun` streaming inside a dialog,
 drawer, or fixed-height panel grows BELOW the fold — a plain scroll container doesn't follow. Wrap
-the feed: `<FollowScroll style={{ maxHeight: … }}><AgentRun … /></FollowScroll>` — pinned to the
-newest content while streaming, unpinned when the human scrolls up to read (`AgentProgress`'s
-expanded panel already does this). A full-page inverted list (chat) follows by construction and
-doesn't need it.
+the feed: `<FollowScroll style={{ maxHeight: … }}><AgentRun … /></FollowScroll>` — the same
+inverted-list mechanism as a chat message list, packaged as a wrapper: the follow happens at
+LAYOUT level (each growth paints already pinned — no scroll-after-paint flash), scrolling up
+releases it, and the feed stays at the newest content when the run settles (`AgentProgress`'s
+expanded panel does this). When settling REPLACES the feed with different content (a results
+pane), swap `FollowScroll` for a plain scroller on the phase flip — the remount opens the new
+content at the top; a transcript that persists just stays in `FollowScroll`. A full-page chat
+list is already inverted and doesn't need the wrapper.
 
 Fed natively by `@lotics/app-sdk`'s `useAgentRun().parts` (reasoning + per-tool I/O + state come
 for free — no hand-assembly): `<AgentRun parts={run.parts} state={…} error={run.error} />` — see
 [the SDK doc](../../app-sdk/docs/ai.md) for the hook. Requires `ai` as an optional (type-only) peer.
 **Reasoning only shows when the model produces it** — the declared model must support thinking
-(Sonnet 4.6 / Opus 4.8, not Haiku); the renderer shows every reasoning part it's handed.
+(Sonnet / Opus, not Haiku); the renderer shows every reasoning part it's handed.
 
 **Limitation:** the collapsed reasoning row's "Thinking" label and the expanded detail's
 "Input"/"Output"/"Error" panel titles are currently English-only (not on the locale provider and
@@ -171,7 +175,7 @@ when done.
 
 Every "the agent proposes → the human accepts / edits / dismisses → nothing auto-applies" surface
 composes from twelve pieces in three groups (all in `@lotics/ui/change_review`; worked example:
-[`tpl_documents`](../examples/tpl_documents.tsx)).
+[`tpl_record`](../examples/tpl_record.tsx)'s Use-AI extract flow).
 
 **Frame**
 
@@ -278,7 +282,9 @@ Back / Next / Cancel / Submit (Next/Submit primary), the step position an eyebro
 question — no progress bar, and no eyebrow at all for a single question. Each step is a `Clarify`; advance only once the
 current question is answered; `onSubmit` gives one `{ value, custom }` per question (aligned by index,
 `custom` true when the answer came from "Other…"), `onCancel` dismisses. All navigation chrome is
-locale-wired (the `clarify` slice). The multi-question form of the ask-back.
+locale-wired (the `clarify` slice). The multi-question form of the ask-back. Worked example:
+[`tpl_item_list`](../examples/tpl_item_list.tsx)'s intake fork (the wizard between the analyze
+and import runs).
 
 ## Provenance — `Sources`
 
@@ -362,7 +368,7 @@ ranked set, don't cram it into chat prose:
   so the alternatives are first-class and picking a different one changes the outcome; refining
   the description re-ranks. For look-up-and-explain: tariff/classification codes, fee lookup,
   policy Q&A, a spec/compliance desk. (NOT a chat with the answer in a bubble.)
-- **Document desk** ([`tpl_documents`](../examples/tpl_documents.tsx) — THE go-to for
+- **Document desk** (in [`tpl_record`](../examples/tpl_record.tsx) — THE go-to for
   document-driven records) — the record's files block feeds ONE "Use AI" entry that FORKS into
   the two document tasks, each a specialized run with a task-pure result: **Extract** (files
   read → fields already matching fold into one quiet line → every add / update / conflict a
@@ -376,6 +382,15 @@ ranked set, don't cram it into chat prose:
   full-page `FileGalleryModal`. Plus **Create documents**: a readiness checklist (unchecked by
   default, missing inputs called out) → generate → the files land back on the record. Never merge
   the two AI tasks into one mixed output — the fork is the design.
+- **Intake desk** (in [`tpl_item_list`](../examples/tpl_item_list.tsx)'s "Enter data" fork) — the
+  register's New CTA leads with AI: a `FileDropzone` hero → a short ANALYZE run reads the files →
+  `ClarifyWizard` asks the ambiguities the analysis surfaced → the IMPORT run drafts records →
+  `ChangeRecord` cards + one Apply land the rows; the manual VARIANTS sit below the dropzone as
+  `CardSelectItem`s, each opening the classic create-then-refine form. The template mocks the
+  clarify step as TWO app-orchestrated phases (analyze-run → wizard → import-run); a real app
+  can do it in ONE run — every app agent carries `ask_user_choice`, so the run PARKS on the
+  agent's own question and `useAgentRun().pendingChoice`/`answerChoice` drive the same
+  `ClarifyWizard` (see the SDK's [ai doc](../../app-sdk/docs/ai.md)).
 - **Triage** — an inbox the agent classified + routed is a `ChangeReview` of `Change`s (body: the
   item + the agent's call; the standard Keep/Drop verbs; Keep-all covers the high-confidence
   sweep). Leads, tickets, documents, emails.

package/docs/catalog.md

@@ -179,10 +179,19 @@ of a record/settings surface).
 
 `PressableRow` (THE register row; forwards its `ref`, so wrapping it in a `PopoverTrigger`
 anchors a row-triggered peek Popover — without the ref the trigger is unmeasurable and the
-popover renders off-screen), `ListItem`, `MenuButton`, `MenuListItem`, `DetailRow`
+popover renders off-screen), `PressDoor` (the keyboard door that pairs with it — see
+below), `ListItem`, `MenuButton`, `MenuListItem`, `DetailRow`
 (label+value for drawers/peeks; optional `trailing` slot for a right-side
 action/badge/unit), `ActionMenu` (⋯), `FloatingActionBar` (bulk-select bar).
 
+A DESIGNED row (your own pile, card, or panel) that presses open AND carries its own
+controls is `PressableRow` + **`PressDoor`** — never `PressableHighlight`, which IS a
+button and wraps its children (a button must not contain interactive descendants). The
+door is an empty absolutely-positioned SIBLING of the content carrying the tab stop,
+accessible name, and focus ring; lift the content above it with `zIndex: 1`. `Table`/
+`TableRow` and `LinkedRecordBox` do exactly this internally, so a columnar register needs
+no assembly — reach for `PressDoor` only outside them.
+
 ### Filters & view controls
 
 `SearchInput`, `ChipGroup`, `FilterChip` (+ `RangeSlider`, `Counter`), `Chip`,
@@ -212,8 +221,9 @@ trailing ⋯ menu = Download · Open-external · Remove; the default "here are s
 surface), `FileGrid` (the upload-aware grid: completed files + a live upload queue in one
 surface — `FilesEditor` is this + the toolbar; reach for `FileGrid` bare when you own the
 chrome), `FileThumbnail` / `FileThumbnailGrid` (square tiles; `onPress`/`onFilePress` makes each
-tile a pressable door — e.g. tap-to-preview — carrying an accessible button role + filename
-label; `selectedIds` for a selection overlay),
+tile a pressable door — e.g. tap-to-preview — carrying an accessible button role + the
+filename as its name, overridable per tile with `accessibilityLabel` when what the press
+DOES reads better than a raw filename; `selectedIds` for a selection overlay),
 `UploadingThumbnail` (the single in-flight tile FileGrid renders — reach for it only when
 hand-rolling a non-grid upload layout), `FileRow` (a horizontal file/document LINE —
 badge-or-placeholder + name + meta + a composable `trailing` slot for a status badge /
@@ -443,6 +453,14 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
 - **`pressable_row`** — `PressableRow`: THE register row — full-width hover/open wash,
   `selected` (the open record) vs `marked` (ticked in bulk-select), forwards `ref` for
   popover anchoring.
+- **`press_door`** — `PressDoor`: THE keyboard door — an EMPTY absolutely-positioned
+  `Pressable` sibling that carries the `role="button"` tab stop, the (REQUIRED)
+  `accessibilityLabel`, and the focus ring for a pressable surface whose content holds its
+  own controls. Pair it with `PressableRow` (surface takes the mouse + the wash, door takes
+  the keyboard, nested controls keep their own presses); the parent owns the positioning
+  context and the content lifts above the door with `zIndex: 1`. `radius` (default 10)
+  matches the surface it spans. `TableRow` / `LinkedRecordBox` are the in-kit consumers —
+  reach for it when designing a row those don't cover.
 - **`linked_record_box`** — `LinkedRecordBox`: a bordered box scoping ANOTHER record's data
   (`icon` · `name` · `subtitle` · vertical `facts`), the WHOLE box a keyboard door into its
   detail (`onOpen`/`doorLabel`); verbs ride an `actions` slot in a hairline-fenced footer at the
@@ -906,7 +924,11 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
 - **`file_thumbnail`** — `FileThumbnail` + `DisplayFile` + `THUMBNAIL_SIZE` /
   `COMPACT_THUMBNAIL_SIZE` + `getMediaIcon`: the completed tile — the right surface per
   MIME: image thumbnail · a doc tile with the `FileBadge` centered + a single-line filename
-  · media card; `isTemplate` overlays a TMPL marker.
+  · media card; `isTemplate` overlays a TMPL marker. The tile's accessible name is the
+  filename; pass `accessibilityLabel` to say what pressing it DOES instead. The per-surface
+  pieces are exported for a hand-rolled layout: `DocumentBadge` (a bare pressable badge —
+  its `size` is the square SLOT side, like every other tile here, and the badge is fitted to
+  it), `DocumentCard`, `MediaCard`, `RemoveButton`.
 - **`file_thumbnail_grid`** — `FileThumbnailGrid` (+ the generic `ThumbnailGrid`):
   display-only square-tile grid; `selectedIds` + `onFilePress` pair with
   `useSelectionMode()` for gated select-mode CRUD.
@@ -919,7 +941,9 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   + a ⋯ Download/Open-external/Remove menu; composes `FileRow` + `ActionMenu` +
   `FileGalleryModal`; localized via the `gallery` locale slice.
 - **`file_badge`** — `FileBadge`: the two-tone file-type mark (PDF / XLSX / DOCX / video /
-  audio …) driven by MIME.
+  audio …) driven by MIME. Its `size` is the badge's WIDTH and everything scales off it —
+  the mark is TALLER than it is wide (26 × 32 by default), so a square slot takes the
+  fitted width, not the slot side (that conversion is what `DocumentBadge` does).
 - **`file_preview`** — `FilePreview`: the universal inline preview — image/PDF/video/audio +
   Word via `@lotics/docx` + Excel/CSV via `@lotics/xlsx`; the heavy engines (pdf.js ·
   `@lotics/docx` · `@lotics/xlsx`) are LAZY (dynamic-imported, ~free until a doc of that
@@ -977,10 +1001,13 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
 - **`agent_progress`** — `AgentProgress`: `AgentRun`'s compact, floating, expandable form (same
   `parts` prop) — a composer's working state.
 - **`follow_scroll`** — `FollowScroll`: a scroll container that FOLLOWS its growing content —
-  pinned to the bottom as children stream in; scrolling up unpins (read history), scrolling back
-  re-pins. Wrap a streaming `AgentRun` with it in any bounded container (a dialog, a drawer,
-  a panel — put the height bound on `style`); `AgentProgress`'s expanded panel uses it. Chat
-  doesn't need it (an inverted message list follows by construction).
+  the chat message list's inverted mechanism packaged as a wrapper (single-cell inverted list),
+  so the follow happens at LAYOUT level: each growth paints already pinned (no flash), scrolling
+  up releases it, and short content still reads top-down. Wrap a streaming `AgentRun` with it in
+  any bounded container (a dialog, a drawer, a panel — put the height bound on `style`);
+  `AgentProgress`'s expanded panel uses it. Inherits the inverted pattern's quirks (scrollbar
+  thumb runs opposite; keyboard paging inverted) — same as chat. A full-page chat list is
+  already inverted and doesn't need it.
 - **`confidence`** — `Confidence` + `ConfidenceLevel` + `levelFromScore`: calibrated
   high/med/low; localized via the provider.
 - **`change_review`** — the COMPOUND review family — frame: `ChangeReview` provider/stack ·

package/docs/composition.md

@@ -287,6 +287,14 @@ body is arbitrary app content — `TableRow`'s cells, which legitimately carry a
 trigger — the door is an EMPTY absolutely-positioned sibling under the cells (tab stop + name +
 focus ring; the mouse rides the surface), so a control in a cell never nests inside it.
 
+That empty door is the **`PressDoor`** primitive (`@lotics/ui/press_door`) — don't hand-roll it
+when you design a row `Table` doesn't cover (a mobile pile with a per-row control, a bespoke
+card): `<PressableRow onPress>` + `<PressDoor onPress accessibilityLabel="Open …" />` + your
+content on `zIndex: 1` (the door hit-tests above in-flow siblings, so the content must lift back
+over it). `PressableHighlight` is the wrong base for such a row — it IS a button and wraps its
+children, so any nested control lands inside it; it stays for surfaces whose content is
+non-interactive by construction. `TableRow` and `LinkedRecordBox` already compose `PressDoor`.
+
 Actions stay **visible** — a hover-only action is invisible to keyboard and touch users. The ONLY
 exception is a DENSE tree/register where a persistent per-row action would clutter: reveal on
 hover **OR focus-within**, keeping the action in the DOM + tab order and gating only its opacity,

package/docs/templates.md

@@ -50,7 +50,7 @@ the package index is [../AGENTS.md](../AGENTS.md).
 | Shift signup + staffing | `tpl_shifts` |
 | AI produces a visual artifact on a canvas | `tpl_dieline` |
 | AI ranks answers — look-up-and-explain | `tpl_lookup` |
-| AI over a record's documents (extract / cross-check / generate) | `tpl_documents` |
+| AI over a record's documents (extract / cross-check / generate) | `tpl_record` — its Documents + Document set sections |
 
 ## Composition rules — how a record surface is assembled
 
@@ -204,6 +204,17 @@ screens — register, per-row action, gated selection, and act-on-many in one. T
     newest first — an entry's attachments ride its expandable details as a thumbnail grid
     whose press opens the shared `FileGalleryModal`.
   - A closing `DangerZone`.
+- **The "Enter data" INTAKE FORK** (the New CTA) — AI FIRST, the form as fallback, one phased
+  dialog: a `FileDropzone` hero (drop the customer's files) → a short ANALYZE stream
+  (`AgentRun` in a `FollowScroll`) reads them → `ClarifyWizard` asks the ambiguities the
+  analysis surfaced (described options, one custom-answer slot) → the IMPORT stream drafts the
+  records → `ChangeRecord` cards to Keep/Drop (fee editable in place) + one outcome-named
+  Apply that really lands the rows in the register (no drawer on a bulk landing). BELOW the
+  dropzone, "or enter manually" → the record VARIANTS as `CardSelectItem`s, each opening the
+  same THREE-field create-then-refine form (a single manual create still opens its drawer).
+  The template mocks the clarify step as two app-orchestrated phases; a real app can do it in
+  ONE run — every app agent carries `ask_user_choice`, so the run parks on the agent's own
+  question and `useAgentRun().pendingChoice`/`answerChoice` drive the same `ClarifyWizard`.
 
 ### `tpl_pick` — the guided queue
 
@@ -266,15 +277,13 @@ billing, and quick-capture templates. Top → bottom:
   (dashed add-ghost when unset), sized to the list's `trailingWidth` so the title never overlaps.
   (Contrast the General section's dates/assignee, the same editors in the default `variant="form"`
   — a zinc-50 chip + hover-border + the full member chip.)
-- **Documents** — the Agents "Document desk" pattern (shared with `tpl_documents` — change
-  it in BOTH): the register `Table` (search · Add files) whose selection feeds the
-  `FloatingActionBar` → ONE "Use AI" fork (extract / cross-check / edit-with-AI). Every
-  row's leading visual is a `FileThumbnail` in ONE square 32px slot — an image file fills
-  it as a real thumbnail, a document centers its badge in it — never a bare `FileBadge`
-  (mixed footprints misalign the identity column). ONE
-  sanctioned divergence: GENERATION — on the record page this desk holds what ARRIVES and
-  Create moves to the Document set OUTPUT section below; `tpl_documents` (no output
-  pipeline on its page) keeps the toolbar "Create documents" dialog.
+- **Documents** — the Agents "Document desk" pattern (this template is its worked example —
+  see the Agents chapter below): the register `Table` (search · Add files) whose selection
+  feeds the `FloatingActionBar` → ONE "Use AI" fork (extract / cross-check / edit-with-AI).
+  Every row's leading visual is a `FileThumbnail` in ONE square 32px slot — an image file
+  fills it as a real thumbnail, a document centers its badge in it — never a bare `FileBadge`
+  (mixed footprints misalign the identity column). The desk holds what ARRIVES; generation
+  lives in the Document set OUTPUT section below.
 - **Customer — the LINKED-RECORD reference** via **`LinkedRecordBox`**: another record's data
   NEVER renders as field rows on this one — a BORDERED, fully pressable box (glyph anchor ·
   identity · facts stacked VERTICALLY) whose press opens the detail drawer; the verbs ride the
@@ -460,8 +469,9 @@ double-shift days flagged). Accepting and assigning move the board live.
 ## Agents
 
 Screens where AI does the work and the human reviews. `tpl_dieline` *produces* an artifact;
-`tpl_lookup` and `tpl_documents` *structure* information for a decision. The AI component
-contracts and the propose→review→apply loop live in [ai_patterns.md](./ai_patterns.md).
+`tpl_lookup` *structures* information for a decision; the document desk (in `tpl_record`)
+does both over a record's files. The AI component contracts and the propose→review→apply
+loop live in [ai_patterns.md](./ai_patterns.md).
 
 ### `tpl_dieline` — the design canvas
 
@@ -484,12 +494,15 @@ rows, policy `Callout`s, `Confidence`, and `Sources`. The flow is input → matc
 a single confident verdict: classification is ambiguous, so the alternatives are first-class.
 Refine the description in a follow-up and the ranking updates.
 
-### `tpl_documents` — the document desk
+### The document desk — in `tpl_record`
 
-THE worked example for everything document-driven on a record. A record's files block feeds
-ONE **"Use AI"** entry — the one AI entry point, never per-row AI buttons (the per-row `⋯`
+THE worked example for everything document-driven on a record lives on the record template
+(its Documents section — no standalone template). A record's files block feeds ONE
+**"Use AI"** entry — the one AI entry point, never per-row AI buttons (the per-row `⋯`
 menu holds only Rename/Download). Inside its dialog the run FORKS into three tasks as
-`CardSelectItem`s (select → a confirming footer CTA, never one-click):
+`CardSelectItem`s (select → a confirming footer CTA, never one-click), and the streaming
+phase runs inside a `FollowScroll` (swapped back to `DialogScrollArea` on the phase flip,
+so review opens at the top):
 
 - **Extract** (read the documents, fill the record) — the open `ChangeFields` review: ONE
   `Change` section per record whose body stacks a `ChangeField` per proposed value (label ·
@@ -502,10 +515,9 @@ menu holds only Rename/Download). Inside its dialog the run FORKS into three tas
 - **Edit with AI** — the `askAi` handoff: dialogue-shaped file iteration happens in the
   platform chat (the documents attached to a fresh thread), not in the app.
 
-Separately, a **Create documents** action opens its own dialog: a readiness checklist
-(hand-composed rows — per-document missing inputs open a fill screen, saved values recompute
-readiness) → generation runs as a visible `AgentRun`, never a teleport → generated files stay
-PENDING (previewable) until the user commits them onto the record.
+GENERATION is separate and deterministic — the record's Document set OUTPUT section
+(readiness checklist → template fill with a `loading` trigger, never `AgentRun` theater;
+the set appears at once).
 
 All mock — `useState` plus a timer streams the `AgentRun`; a real app drives the same
 components from its live agent run.