@lotics/ui 5.7.0 → 5.9.0

package/AGENTS.md

@@ -22,9 +22,12 @@ typeahead, async search, virtualization, and a11y the primitive already ships.
 
 Pick by capability, not by name. (→ the source file for the API.)
 
-- **Actions** — `Button` (labelled; `color` = emphasis/risk, `shape` pill|rounded),
-  `IconButton` (icon-only, needs `accessibilityLabel`/`tooltip`), `LinkButton` (quiet ghost
-  action — Clear / Select all), `PillButton` (dismissible facet chip). A button is never a raw
+- **Actions** — `Button` (labelled; `title` is MANDATORY; `color` = emphasis/risk),
+  `IconButton` (icon-ONLY — the circular affordance; an icon-only Button is a type error, so reach
+  here. `size` `lg` 40px / `md` 28px / `sm` 24px, the SAME `color` palette as Button, plus `loading`
+  and `elevated` (white fill + border + shadow, for a button sitting ON imagery — a tile's remove ✕,
+  an overlay's retry); needs `accessibilityLabel`/`tooltip`), `LinkButton` (quiet ghost
+  action — Clear / Select all), `Chip` (dismissible facet chip). A button is never a raw
   `Pressable`. For a link OUT (a URL / record / document) use `Link` — underline+blue, the
   destination signal; the opposite of `LinkButton` (a quiet in-app action, never underlined).
 - **Pick from a list** — `Picker` (known options, native typeahead, single/multi/custom-render,
@@ -66,13 +69,21 @@ Pick by capability, not by name. (→ the source file for the API.)
 - **Rows & registers** — `PressableRow` (THE register row), `ListItem`, `MenuButton`,
   `MenuListItem`, `DetailRow` (label+value for drawers/peeks), `ActionMenu` (⋯), `FloatingActionBar`
   (bulk-select bar).
-- **Filters & view controls** — `SearchInput`, `ChipGroup`, `FilterPill` (+ `RangeSlider`,
-  `Counter`), `PillButton`.
+- **Filters & view controls** — `SearchInput`, `ChipGroup`, `FilterChip` (+ `RangeSlider`,
+  `Counter`), `Chip`.
 - **Overlays** — `Dialog`, `Drawer` (+ `DrawerFooter`), `Popover`, `Tooltip`, `CommandMenu`,
   `Alert` (the blocking confirm).
 - **Status / feedback** — `Badge` / `StatusBadge`, `Callout` (inline status), `EmptyState`,
   `CompletionState`, `ActivityIndicator` / `Loading`, `Skeleton`.
-- **Files** — `FileDropzone`, `FileThumbnail` / `FileThumbnailGrid`, `FilePreview` /
+- **Files** — `FileDropzone`, `FileRows` (batteries-included file LIST: tap a row → built-in
+  full-screen gallery, ⋯ menu = Download · Open-external · Remove; the default "here are some files"
+  surface), `FileGrid` (the upload-aware grid: completed files + a live upload
+  queue in one surface — use this for any add-files screen), `FileThumbnail` / `FileThumbnailGrid`
+  (square tiles, display-only), `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 / action
+  / remove; `onPress` makes the whole row a pressable door, `trailing` stays an independently-pressable
+  sibling; for checklists & readable lists), `FileBadge` (the two-tone type mark), `FilePreview` /
   `FileGalleryModal`, `ImageGallery`; for gated CRUD compose locally with `useSelectionMode` +
   `shareOrDownloadFiles` + `rotateImageToBlob` (see §Data entry → Attachments).
 - **Specialized work surfaces** — `ScanField` (scan/verify), `Stepper` (a guided run / progress
@@ -197,23 +208,49 @@ marked + disabled), not a generic text menu. A composition (Badge + Button + Pop
 
 ### Attachments — a full add / preview / DELETE field
 Capture with `<FileDropzone onFiles accept label hint dropLabel height>` (drag-over lights the
-accent; click falls back to a picker); display what landed with `<FileThumbnailGrid files>` ABOVE
+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). Make it CRUDable by wiring the grid's two
-callbacks: `onFilePress` → set a `number|null` index that drives `<FileGalleryModal files
-activeIndex onIndexChange>` (built-in prev/next/ESC/rotate); `onRemove` → drop the file from state
-(the grid renders a ✕ on each thumbnail automatically). Keep label+grid+dropzone on a `gap` (a bare
-`CardBody` has none). `FileThumbnail` shows the right surface per MIME (image thumbnail · doc card ·
-media card), and takes `uploading` to dim it with a spinner while the bytes are still going up.
-Never hand-build a drop well, a file row grid, 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
-`DisplayFile` (snake → camel: `preview_url`→`url`, `mime_type`→`mimeType`) for
-`<FileThumbnail file={…} uploading={f.status === "uploading"} />`.
+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`; the Lotics `@lotics/ui-internal` adapter already injects vi/en). 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; `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 toolbar'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) — no native `<iframe>` viewer, so they work inside the 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 / Finder); 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 is a PATTERN, composed locally — not a sealed kit component.** When a file field must
-GUARD deletion (operator-facing, accidental delete is a real risk), compose it in the app from the kit
-pieces; don't reach for a one-size widget (the action set + layout vary per app — the host frontend's
+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 — the host frontend's
 `files_editor` and each app compose their 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
@@ -270,15 +307,20 @@ Compose the surfaces as a loop, and reach for the right one by job:
   attaching HOLDS the file for review; the human presses Send. The canvas (`tpl_dieline`) uses it this
   way; while running the host swaps `Composer` for `AgentProgress` (same pill geometry, so it reads as
   a morph).
-- **Show the work** — `AgentRun`: a live feed of the agent's work — its streamed narration (rendered
-  as `Markdown`, with a trailing ▍ while live) + tool calls as a vertical `Stepper` of neutral dots (the
-  latest pulsing while live, a white-check dot once done). No title, no avatar — just the work. A terminal "Done" step (the
-  `complete` node) appears ONLY once the run finishes. A step can carry `peek` content to glance into
-  via a popover. Tool labels resolve from the raw tool name via a built-in default map + an optional
-  `labelForTool` override (localize THERE — the kit stays English). `doneLabel` localizes the terminal.
-  Transparent work, NEVER a bare spinner — the
-  intelligence is legible. On a canvas/composer app reach for `AgentProgress` — `AgentRun`
-  collapsed into a floating pill (avatar + current step) that EXPANDS on press; the composer
+- **Show the work** — `AgentRun`: a live feed of the agent's work as a TIMELINE. The prop is an
+  ORDERED `items` array — `{type:"text"}` prose (rendered as `Markdown`, a trailing ▍ while live) interleaved with `{type:"step"}` tool/step calls, in
+  the order they happened (a real run is text → a burst of calls → more text → more calls, NOT all
+  text on top of a flat step list). Consecutive `step` items fold into ONE activity group: while the
+  agent is mid-tools the tail group is a SINGLE pulsing row whose label swaps in place as each call
+  fires (no growing stack of dots); once prose resumes the group settles into a persistent "{final
+  action} · {n} steps" HEADER (a `complete` terminal dot — distinct from the filled `done` step dots)
+  that STAYS PUT and rolls the calls out BELOW it on press (a `step` can carry `peek` content;
+  `detail` is OPTIONAL — real tool I/O, never invented prose). The run ALWAYS ends on the agent's
+  text (no global terminal node). A `step` with
+  `kind:"tool"` carries the RAW tool name, resolved via a built-in map + an optional `labelForTool`
+  override (localize THERE — the kit stays English); `stepsLabel` localizes the "{n} steps" suffix.
+  Transparent work, NEVER a bare spinner. On a canvas/composer app reach for `AgentProgress` —
+  `AgentRun` collapsed into a floating pill (avatar + current step) that EXPANDS on press; the composer
   morphs into it while running, and reveals again when done.
 - **Review before apply — ONE card + the batch engine, the BODY is compositional.** Every "the agent
   proposes → the human accepts / edits / dismisses → nothing auto-applies" surface wears the same
@@ -378,8 +420,8 @@ controls — while **status/severity/diffs use functional colour** the way the r
 - **Stepper / AgentRun nodes** — progress dots on a spine: `current` a **pulsing accent ring** (white
   centre), `done` a filled accent dot + **white check**, `upcoming` a faint **grey** ring, the terminal
   `complete` a **blackish ring + black check**, `warning` **amber**. Default accent is neutral ink
-  (`color` themes it); `AgentRun` keeps the neutral default + appends the `complete` "Done" node only
-  when the run finishes.
+  (`color` themes it); `AgentRun` keeps the neutral default — an active group's tail pulses (`current`),
+  a settled group is a `done`/`warning` row, and there is no global terminal node (the run ends on text).
 - **ChangeReview diffs** — the old value struck in **red**, the new value in **green**.
 - **Discrepancy** — the agent's pick gets a **blue** highlight; `Mismatch` reads amber, `Resolved`
   emerald.
@@ -472,31 +514,49 @@ was only ever about the review surfaces' sparkles/severity glyphs, not functiona
     padded container, NO `Divider`s (the gap + rounded hover separate them).
   Right-hand columns align only if every trailing element is FIXED-width (give each trailing action
   a fixed `width`, so amount/status columns don't jitter).
+- **Row actions are ALWAYS-VISIBLE siblings, never hover-revealed, never nested.** A pressable row =
+  a role-less surface (the hover/press wash, via DOM `mouseenter` so it covers the whole row) + an
+  accessible "Open …" door (the body, a button) + trailing actions (⋯, remove ✕, edit) as SIBLINGS of
+  the door — a button must not contain another button, so the action is independently pressable and
+  the ✕ isn't swallowed by the row press (`FileRow` and `PressableRow` are the references). 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 (e.g. the DB sidebar):
+  reveal on hover **OR focus-within**, keeping the action in the DOM + tab order and gating only its
+  opacity, so it's still keyboard-reachable. Do that locally — there is no shared hover-reveal
+  primitive (the old `HoverAction` made the keyboard-inaccessible anti-pattern easy and was removed).
 - **Master-detail = list + workspace `Drawer` with sequencing.** Pressing a PRIMARY entity row
   opens the record workspace in a `Drawer` with `onPrev`/`onNext`/`position` ("3/24") over the
   visible ordering (←/→ built in). Key the drawer body by record id so per-record state resets on
   step. Facts are `DetailRow`s; the commit bar is a `DrawerFooter`. The open row shows a selected
   highlight (and `marked` — a resting blue tint — for a bulk-ticked row). `Peek` is ONLY for
   secondary references, never the primary row press.
+- **One control radius** — every interactive control (`Button`, the inputs/selects/pickers,
+  `SearchInput`, `MenuButton`, `Tabs`, the `SegmentedControl` track, `ChipGroup`/`FilterChip`/
+  `Chip`) wears `CONTROL_RADIUS` (10, from `control_surface.ts`) — never a literal. Containers
+  are deliberately larger (`Card` 16, the review card 12). An element NESTED inside a padded control
+  (a segmented thumb, a combobox chip, an ✕ on a chip) takes `CONTROL_RADIUS − padding` so its corner
+  stays CONCENTRIC with the parent — set it equal and the inner corner bulges past the outer curve.
+  Round-by-function controls (avatars, status dots, switches, sliders, progress bars, `IconButton`)
+  stay full (999); a small square toggle (`Checkbox`, 24px) keeps a proportional small radius (6 —
+  the same fraction of its box that 10 is of a 40px control), not the band radius. No capsules —
+  `Button` has no pill `shape`.
 - **One view-control vocabulary** (all 40px, `sm` labels, in one wrapping band):
-  · `SearchInput` is THE search box — a white `TextInputField` preset (rounded-8 like every other
-    input, a thin zinc-300 border, the leading search glyph + a clear ✕). It reads as search by its
+  · `SearchInput` is THE search box — a white `TextInputField` preset (the shared `CONTROL_RADIUS`
+    like every other input, a thin zinc-300 border, the leading search glyph + a clear ✕). It reads as search by its
     ICON + white fill, not a distinct shape, so a toolbar of controls stays one consistent band.
     Never a bare `TextInputField` + search icon.
   · `ChipGroup` is THE one-of-N lens (≤ ~10 options the user flips between; include "All"; counts in
     the label). Filters ONE list to a SUBSET — including by process stage / lifecycle state.
-  · `FilterPill` is THE secondary-dimension filter — a compact pill that opens a composed popover
+  · `FilterChip` is THE secondary-dimension filter — a compact chip that opens a composed popover
     editor (`PickerMenu multi` / `RangeSlider` / `Counter` / date range). Single-select closes on
     pick via the `{({close}) => …}` render prop.
   · `ColumnFilter` is the TYPED column filter — give it a `FilterableColumn` (`text` / `number` /
     `select`) + a controlled `ColumnFilterValue` and it renders the right editor (contains / range /
-    multi-select) inside a `FilterPill`, with `columnFilterToConditions` mapping the value to query
-    predicates. Reach for it — ONE compact pill per dimension — when a register filters on SEVERAL
+    multi-select) inside a `FilterChip`, with `columnFilterToConditions` mapping the value to query
+    predicates. Reach for it — ONE compact chip per dimension — when a register filters on SEVERAL
     columns (origin, destination, carrier, type…). Never hand-roll a row of bespoke chips/filters,
     and never use a permanently-expanded `ChipGroup` for a secondary dimension.
-  · `Combobox pill` is the SEARCHABLE filter in the band — `<Combobox pill>` wears the same white
-    toolbar-pill surface as `SearchInput`/`FilterPill` (don't put a bare form-look Combobox in a
-    toolbar — its transparent input reads grey on the zinc-50 canvas beside the white pills). Reach
+  · `Combobox` is the SEARCHABLE picker — reach
     for it over `ColumnFilter` when the value is ONE of a large/growing set you type to narrow (a
     port, a customer) rather than a short fixed list. Pass `recentOptions` (the same option list) so
     a click opens the full list, then typing filters. The **From → To route picker** is two of them
@@ -588,7 +648,7 @@ section_heading (SectionHeading · SectionHeadingTitle — compound, owns no mar
 option_badge (OptionBadge — a select value as its configured colored badge) ·
 member_chip (MemberChip — avatar + name; the universal person render) ·
 member_select (MemberSelect — a Picker of MemberChip options; the member picker) ·
-status_badge · button · icon_button · link · link_button · pill_button · tabs · segmented_control ·
+status_badge · button · icon_button · link · link_button · chip · tabs · segmented_control ·
 picker · combobox · tag_input (TagInput — chip box + Add-popover; for tags, not Combobox multi) ·
 text_input_field · number_input · search_input · form_field · checkbox · checkbox_input · switch ·
 radio_picker · counter · range_slider · date_picker · date_range_filter_field · time_picker ·
@@ -596,7 +656,7 @@ inline_text_input · inline_number_input · inline_select · inline_member_selec
 inline_time_picker (the Inline* family — per-field editors on `inline_edit`'s `useInlineEdit` +
 `InlineEditView`; `InlineSelect`/`InlineMemberSelect` take `renderValue` for a chip/badge at rest) ·
 list · list_item · menu_button · menu_list_item · detail_row · pressable_row · action_menu ·
-floating_action_bar · filter_pill · column_filter (ColumnFilter — the typed per-column filter pill +
+floating_action_bar · filter_chip · column_filter (ColumnFilter — the typed per-column filter pill +
 columnFilterToConditions; for a register filtering on several columns) · chip_group · search_input ·
 sort_header · table · pagination · accordion · stepper (Stepper + Step — done/current/upcoming/warning/complete progress on a track (horizontal) or spine (vertical); compound `<Step status>children` OR data `steps[]`+`current`; the guided-run / agent-feed primitive — subsumes the old StepList) ·
 step_progress · timeline (heterogeneous event LOG — per-row icon + expandable details, models the past; NOT progress) · drawer (+ DrawerFooter) · dialog · popover · tooltip ·
@@ -604,7 +664,7 @@ command_menu · alert · peek · empty_state · completion_state · callout (Cal
 CalloutText · CalloutActions) · kpi_card · kpi_strip · metric · trend_chip · sparkline ·
 bar_chart · line_chart · pie_chart · ring_gauge · progress_bar · stacked_progress_bar · breakdown ·
 status_grid (StatusGrid + StatusLegend) · heatmap · legend_item · remainder_meter · allocation_row ·
-scan_field · file_dropzone · file_thumbnail · file_thumbnail_grid · file_preview ·
+scan_field · file_dropzone · file_grid (FileGrid — the upload-aware grid: completed files + a live upload queue in one surface; FileUpload/PendingUpload types; the add-files default) · uploading_thumbnail (UploadingThumbnail — the single in-flight upload tile FileGrid renders; reach for it only when hand-rolling a non-grid upload layout) · file_thumbnail · file_thumbnail_grid · file_row · file_rows (FileRows — batteries-included file list: row press → built-in gallery + a ⋯ Download/Open-external/Remove menu; composes FileRow + ActionMenu + FileGalleryModal) · file_preview ·
 file_gallery_modal · image_gallery · use_selection_mode · share_or_download · rotate_image · avatar · skeleton · activity_indicator · loading · divider ·
 spacer · stack · section_card · page_header · page_content · calendar (calendar/index.ts) · gantt ·
 comments_thread · agent_run (live streaming work feed) · agent_progress (its compact floating

package/examples/tpl_approvals.tsx

@@ -13,7 +13,7 @@ import { Divider } from "@lotics/ui/divider";
 import { Drawer, DrawerFooter } from "@lotics/ui/drawer";
 import { EmptyState } from "@lotics/ui/empty_state";
 import { Counter } from "@lotics/ui/counter";
-import { FilterPill, selectSummary } from "@lotics/ui/filter_pill";
+import { FilterChip, selectSummary } from "@lotics/ui/filter_chip";
 import { FloatingActionBar } from "@lotics/ui/floating_action_bar";
 import { FormField } from "@lotics/ui/form_field";
 import { KPIStrip } from "@lotics/ui/kpi_strip";
@@ -240,7 +240,7 @@ export function TplApprovals() {
           />
 
           {/* layered filter band — the hot dimension (type) inline as chips,
-              secondary dimensions collapsed into FilterPills so the band stays
+              secondary dimensions collapsed into FilterChips so the band stays
               scannable as more facets are added */}
           <View style={{ flexDirection: "row", flexWrap: "wrap", gap: 8, alignItems: "center" }}>
             <ChipGroup
@@ -254,13 +254,13 @@ export function TplApprovals() {
               value={tab}
               onValueChange={(t) => { setTab(t); setOpenId(null); }}
             />
-            <FilterPill label="Requester" summary={reqSummary} onClear={() => setReqSel([])} clearLabel="Clear requester filter">
+            <FilterChip label="Requester" summary={reqSummary} onClear={() => setReqSel([])} clearLabel="Clear requester filter">
               <PickerMenu multi enableSelectAll options={REQUESTERS} value={reqSel} onValueChange={setReqSel} />
-            </FilterPill>
-            <FilterPill label="Role" summary={roleSummary} onClear={() => setRoleSel([])} clearLabel="Clear role filter">
+            </FilterChip>
+            <FilterChip label="Role" summary={roleSummary} onClear={() => setRoleSel([])} clearLabel="Clear role filter">
               <PickerMenu multi options={ROLES} value={roleSel} onValueChange={setRoleSel} />
-            </FilterPill>
-            <FilterPill label="Amount" summary={amtSummary} onClear={() => setAmt([AMT_MIN, AMT_MAX])} clearLabel="Clear amount filter">
+            </FilterChip>
+            <FilterChip label="Amount" summary={amtSummary} onClear={() => setAmt([AMT_MIN, AMT_MAX])} clearLabel="Clear amount filter">
               <RangeSlider
                 min={AMT_MIN}
                 max={AMT_MAX}
@@ -270,8 +270,8 @@ export function TplApprovals() {
                 format={fmtAmt}
                 accessibilityLabel="Amount"
               />
-            </FilterPill>
-            <FilterPill label="Waiting" summary={daysSummary} onClear={() => setMinDays(0)} clearLabel="Clear waiting filter">
+            </FilterChip>
+            <FilterChip label="Waiting" summary={daysSummary} onClear={() => setMinDays(0)} clearLabel="Clear waiting filter">
               <View style={{ gap: 10 }}>
                 <Text size="sm" color="muted">Waiting at least</Text>
                 <Counter
@@ -283,7 +283,7 @@ export function TplApprovals() {
                   format={(n) => `${n} ${n === 1 ? "day" : "days"}`}
                 />
               </View>
-            </FilterPill>
+            </FilterChip>
           </View>
 
           <Card style={{ padding: 0 }}>

package/examples/tpl_convert.tsx

@@ -8,7 +8,7 @@ import { Card } from "@lotics/ui/card";
 import { DetailRow } from "@lotics/ui/detail_row";
 import { Divider } from "@lotics/ui/divider";
 import { Drawer, DrawerFooter } from "@lotics/ui/drawer";
-import { FileBadge } from "@lotics/ui/file_badge";
+import { FileRow } from "@lotics/ui/file_row";
 import { FileDropzone } from "@lotics/ui/file_dropzone";
 import { FileThumbnailGrid } from "@lotics/ui/file_thumbnail_grid";
 import { FileGalleryModal } from "@lotics/ui/file_gallery_modal";
@@ -37,8 +37,8 @@ import { Timeline, type TimelineItem } from "@lotics/ui/timeline";
 // required-document checklist with a free FILE DUMP for anything extra. The
 // drawer's ◀▶ keys walk the manager down the queue without closing it.
 //
-// Reference composition — Drawer (list nav) + Stepper + FileBadge (+ placeholder)
-// + Pagination + DetailRow.
+// Reference composition — Drawer (list nav) + Stepper + FileRow (badge + name +
+// meta + a trailing status/action slot) + Pagination + DetailRow.
 // ─────────────────────────────────────────────────────────────────────────────
 
 const CODES: Record<string, string> = {
@@ -141,21 +141,9 @@ function QueueRow({ app, active, onPress }: { app: Applicant; active: boolean; o
   );
 }
 
-// A document line — a FileBadge (or a same-footprint placeholder) + name + meta.
-function FileRow({ name, meta, mimeType, placeholder, tone, action }: {
-  name: string; meta?: string; mimeType?: string; placeholder?: boolean; tone?: "received" | "ready"; action?: ReactNode;
-}) {
-  return (
-    <View style={{ flexDirection: "row", alignItems: "center", gap: 12 }}>
-      <FileBadge size={30} mimeType={mimeType} placeholder={placeholder} />
-      <View style={{ flex: 1 }}>
-        <Text size="sm" weight="medium">{name}</Text>
-        {meta ? <Text size="xs" color="muted">{meta}</Text> : null}
-      </View>
-      {action ?? (tone === "received" ? <Badge variant="dot" label="Received" color="emerald" /> : tone === "ready" ? <Badge variant="dot" label="Generated" color="blue" /> : null)}
-    </View>
-  );
-}
+// Document status chips — the `trailing` slot content for the kit's `FileRow`.
+const receivedBadge = <Badge variant="dot" label="Received" color="emerald" />;
+const generatedBadge = <Badge variant="dot" label="Generated" color="blue" />;
 
 // The extra-documents zone — the data-capture attachment field: a thumbnail grid
 // (click to preview in the gallery, ✕ to delete) above a dropzone. Read-only once
@@ -189,7 +177,7 @@ function UploadsField({ uploads, editable, onAdd, onRemove }: {
       ) : uploads.length === 0 ? (
         <Text size="sm" color="muted">No extra files.</Text>
       ) : null}
-      <FileGalleryModal files={uploads} activeIndex={active} onIndexChange={setActive} captionHint="ESC to close · ←/→ to move" />
+      <FileGalleryModal files={uploads} activeIndex={active} onIndexChange={setActive} />
     </View>
   );
 }
@@ -217,7 +205,7 @@ function StageSection({ app, index, onMarkDoc, onAddUploads, onRemoveUpload }: {
   if (status === "pending") {
     body = <Text size="sm" color="muted">{`Unlocks after ${STAGES[index - 1].label.toLowerCase()}.`}</Text>;
   } else if (index === 0) {
-    body = <FileRow name="Application fee receipt" meta={status === "done" ? `${formatMoney(app.fee)} · issued` : formatMoney(app.fee)} mimeType="application/pdf" tone={status === "done" ? "ready" : undefined} />;
+    body = <FileRow name="Application fee receipt" meta={status === "done" ? `${formatMoney(app.fee)} · issued` : formatMoney(app.fee)} mimeType="application/pdf" trailing={status === "done" ? generatedBadge : undefined} />;
   } else if (index === 1) {
     body = (
       <View style={{ flexDirection: "row", alignItems: "center", gap: 10 }}>
@@ -229,7 +217,7 @@ function StageSection({ app, index, onMarkDoc, onAddUploads, onRemoveUpload }: {
     body = (
       <View style={{ gap: 10 }}>
         {GENERATED_DOCS.map((d) => (
-          <FileRow key={d} name={d} mimeType="application/pdf" meta={status === "done" ? "generated" : "template"} tone={status === "done" ? "ready" : undefined} />
+          <FileRow key={d} name={d} mimeType="application/pdf" meta={status === "done" ? "generated" : "template"} trailing={status === "done" ? generatedBadge : undefined} />
         ))}
       </View>
     );
@@ -245,9 +233,9 @@ function StageSection({ app, index, onMarkDoc, onAddUploads, onRemoveUpload }: {
               meta={d.received ? `${d.file} · received` : "Awaiting upload"}
               mimeType={d.received ? "application/pdf" : undefined}
               placeholder={!d.received}
-              action={status === "current"
+              trailing={status === "current"
                 ? (d.received ? <Button title="Remove" color="muted" onPress={() => onMarkDoc(d.name, false)} /> : <Button title="Upload" color="secondary" onPress={() => onMarkDoc(d.name, true)} />)
-                : (d.received ? <Badge variant="dot" label="Received" color="emerald" /> : undefined)}
+                : (d.received ? receivedBadge : undefined)}
             />
           ))}
         </View>

package/examples/tpl_crm_desk.tsx

@@ -20,7 +20,7 @@ import { NumberInput } from "@lotics/ui/number_input";
 import { Peek } from "@lotics/ui/peek";
 import { ChipGroup } from "@lotics/ui/chip_group";
 import { DatePicker } from "@lotics/ui/date_picker";
-import { FilterPill } from "@lotics/ui/filter_pill";
+import { FilterChip } from "@lotics/ui/filter_chip";
 import { Popover, PopoverContent, PopoverTrigger } from "@lotics/ui/popover";
 import { PressableRow } from "@lotics/ui/pressable_row";
 import { SearchInput } from "@lotics/ui/search_input";
@@ -158,7 +158,7 @@ function ChiTieuGate({ chiTieu, onSave }: { chiTieu: number; onSave: (n: number)
     onSave(draft); setApDung("In effect from today · set by you"); setOpen(false);
   };
   return (
-    <FilterPill
+    <FilterChip
       label="Target"
       summary={String(chiTieu)}
       align="end"
@@ -181,7 +181,7 @@ function ChiTieuGate({ chiTieu, onSave }: { chiTieu: number; onSave: (n: number)
         </FormField>
         <Text size="xs" color="muted">{apDung}</Text>
       </View>
-    </FilterPill>
+    </FilterChip>
   );
 }
 

package/examples/tpl_dieline.tsx

@@ -10,7 +10,7 @@ import { InlineTextInput } from "@lotics/ui/inline_text_input";
 import { AgentProgress } from "@lotics/ui/agent_progress";
 import { Composer } from "@lotics/ui/composer";
 import { FileThumbnail, type DisplayFile } from "@lotics/ui/file_thumbnail";
-import { type AgentRunStep } from "@lotics/ui/agent_run";
+import { type AgentRunStep, type AgentRunItem } from "@lotics/ui/agent_run";
 
 // A real app fills the attachment from `useFileUpload` (the uploaded file's URL);
 // this mock uses an inline placeholder so the example needs no network image.
@@ -105,8 +105,9 @@ export function TplDieline() {
     return () => clearTimeout(t);
   }, [run, revealed]);
 
-  const liveSteps: AgentRunStep[] = run
+  const liveItems: AgentRunItem[] = run
     ? run.script.slice(0, revealed).map((s, i) => ({
+        type: "step",
         ...s,
         status: revealed < run.script.length && i === revealed - 1 ? "running" : "done",
       }))
@@ -167,7 +168,7 @@ export function TplDieline() {
       {/* slim top bar */}
       <View style={{ flexDirection: "row", alignItems: "center", gap: 12, paddingHorizontal: 20, paddingVertical: 12, borderBottomWidth: 1, borderBottomColor: colors.zinc[200], backgroundColor: colors.background }}>
         <Text size="sm" weight="semibold" style={{ flex: 1 }}>Carton design</Text>
-        {phase !== "empty" ? <Button title="New" color="secondary" shape="rounded" icon="plus" onPress={newSession} /> : null}
+        {phase !== "empty" ? <Button title="New" color="secondary" icon="plus" onPress={newSession} /> : null}
       </View>
 
       {/* canvas region — a pannable + zoomable surface (DRAG to pan, the zoom pill
@@ -208,7 +209,7 @@ export function TplDieline() {
       <View style={{ position: "absolute", left: 0, right: 0, bottom: 24, alignItems: "center", paddingHorizontal: 16, pointerEvents: "none" }}>
         <View style={{ width: "100%", maxWidth: 620, pointerEvents: "auto" }}>
           {phase === "working" ? (
-            <AgentProgress steps={liveSteps} state="streaming" />
+            <AgentProgress items={liveItems} state="streaming" />
           ) : (
             <Composer
               value={prompt}
@@ -217,7 +218,7 @@ export function TplDieline() {
               sendDisabled={prompt.trim().length === 0 && !attachment}
               placeholder={designReady ? "Describe a change — “make it 5 mm taller”" : "Attach a photo, add a note, then send…"}
               actionsButton={
-                <Button icon="paperclip" color="secondary" accessibilityLabel="Attach a photo" onPress={() => setAttachment(MOCK_PHOTO)} />
+                <IconButton icon="paperclip" size="lg" color="secondary" accessibilityLabel="Attach a photo" onPress={() => setAttachment(MOCK_PHOTO)} />
               }
               files={attachment ? <FileThumbnail file={attachment} size={56} onRemove={() => setAttachment(null)} /> : null}
             />
@@ -272,7 +273,7 @@ function ParamsPanel({ dims, onEditParam, onDownload }: { dims: Dims; onEditPara
             ))}
           </View>
 
-          <Button title="Download" color="primary" shape="rounded" icon="file-down" alignSelf="stretch" onPress={onDownload} />
+          <Button title="Download" color="primary" icon="file-down" alignSelf="stretch" onPress={onDownload} />
         </>
       ) : null}
     </View>

package/examples/tpl_directory.tsx

@@ -7,7 +7,7 @@ import { Avatar } from "@lotics/ui/avatar";
 import { Badge } from "@lotics/ui/badge";
 import { Button } from "@lotics/ui/button";
 import { ChipGroup } from "@lotics/ui/chip_group";
-import { FilterPill } from "@lotics/ui/filter_pill";
+import { FilterChip } from "@lotics/ui/filter_chip";
 import { Counter } from "@lotics/ui/counter";
 import { Card } from "@lotics/ui/card";
 import { Divider } from "@lotics/ui/divider";
@@ -204,7 +204,7 @@ export function TplDirectory() {
               value={tab}
               onValueChange={setTab}
             />
-            <FilterPill
+            <FilterChip
               label="Min orders"
               summary={minOrders > 0 ? `≥ ${minOrders}` : undefined}
               onClear={() => setMinOrders(0)}
@@ -222,7 +222,7 @@ export function TplDirectory() {
                   format={(n) => `${n} orders`}
                 />
               </View>
-            </FilterPill>
+            </FilterChip>
           </View>
 
           {/* the register: one card, hairline-separated rows */}

package/examples/tpl_dossier.tsx

@@ -20,7 +20,7 @@ import { Popover, PopoverContent, PopoverFooter, PopoverTrigger } from "@lotics/
 import { Table, TableRow, TableCell, type TableColumn } from "@lotics/ui/table";
 import { SearchInput } from "@lotics/ui/search_input";
 import { ChipGroup } from "@lotics/ui/chip_group";
-import { FilterPill, selectSummary } from "@lotics/ui/filter_pill";
+import { FilterChip, selectSummary } from "@lotics/ui/filter_chip";
 import { PickerMenu } from "@lotics/ui/picker_menu";
 import { cycleSort, sortBy, type SortState } from "@lotics/ui/sort_header";
 import { Combobox } from "@lotics/ui/combobox";
@@ -101,7 +101,7 @@ const TABS: { value: Tab; label: string }[] = [
 
 const PAGE_SIZE = 8;
 
-// Distinct case handlers — the secondary filter dimension (a multi-select FilterPill).
+// Distinct case handlers — the secondary filter dimension (a multi-select FilterChip).
 const ASSIGNEES = [...new Set(HO_SO.map((r) => r.phuTrach))].map((n) => ({ label: n, value: n }));
 
 // Columns defined ONCE — Table renders the header from these and each
@@ -331,7 +331,7 @@ export function TplDossier() {
         />
 
         {/* status chips (the hot dimension, inline) + a secondary Assignee
-            multi-select FilterPill — the same faceted band as Approvals */}
+            multi-select FilterChip — the same faceted band as Approvals */}
         <View style={{ flexDirection: "row", flexWrap: "wrap", gap: 8, alignItems: "center" }}>
           <View style={{ flexGrow: 1, flexBasis: 240, minWidth: 200, maxWidth: 360 }}>
             <SearchInput
@@ -350,7 +350,7 @@ export function TplDossier() {
             value={tab}
             onValueChange={chonTab}
           />
-          <FilterPill
+          <FilterChip
             label="Assignee"
             summary={assigneeSummary}
             onClear={() => { setAssignee([]); setPage(0); }}
@@ -363,10 +363,10 @@ export function TplDossier() {
               value={assignee}
               onValueChange={(v) => { setAssignee(v); setPage(0); }}
             />
-          </FilterPill>
+          </FilterChip>
           {/* Single-select sibling — the render-prop `close` shuts the popover on
               pick (the multi above stays open to collect several values). */}
-          <FilterPill
+          <FilterChip
             label="Fee"
             summary={feeStatus === "paid" ? "Paid" : feeStatus === "unpaid" ? "Unpaid" : undefined}
             onClear={() => { setFeeStatus(null); setPage(0); }}
@@ -380,7 +380,7 @@ export function TplDossier() {
                 onRequestClose={close}
               />
             )}
-          </FilterPill>
+          </FilterChip>
         </View>
 
         {/* the register — eyebrow band (Table header) → list rows → totals + paging */}

package/examples/tpl_draft.tsx

@@ -95,7 +95,7 @@ export function TplDraft() {
         {phase === "sent" ? (
           <Card>
             <CompletionState title="Reply sent" summary="Your edited draft was sent to Maya Tran.">
-              <Button title="Draft another" color="secondary" shape="rounded" onPress={() => { setPhase("idle"); setDraft(""); }} />
+              <Button title="Draft another" color="secondary" onPress={() => { setPhase("idle"); setDraft(""); }} />
             </CompletionState>
           </Card>
         ) : (
@@ -129,7 +129,7 @@ export function TplDraft() {
 
               {phase === "idle" ? (
                 <View style={{ alignItems: "flex-start", paddingTop: 4 }}>
-                  <Button title="Draft a reply" color="primary" shape="rounded" onPress={startDraft} />
+                  <Button title="Draft a reply" color="primary" onPress={startDraft} />
                 </View>
               ) : null}
 
@@ -151,8 +151,8 @@ export function TplDraft() {
             {phase === "ready" ? (
               <CardFooter>
                 <View style={{ flex: 1 }} />
-                <Button title="Regenerate" color="secondary" shape="rounded" icon="rotate-ccw" onPress={startDraft} />
-                <Button title="Send reply" color="primary" shape="rounded" onPress={() => setPhase("sent")} />
+                <Button title="Regenerate" color="secondary" icon="rotate-ccw" onPress={startDraft} />
+                <Button title="Send reply" color="primary" onPress={() => setPhase("sent")} />
               </CardFooter>
             ) : null}
           </Card>