@lotics/ui 5.3.0 → 5.5.0

package/AGENTS.md

@@ -75,16 +75,18 @@ Pick by capability, not by name. (→ the source file for the API.)
 - **Files** — `FileDropzone`, `FileThumbnail` / `FileThumbnailGrid`, `FilePreview` /
   `FileGalleryModal`, `ImageGallery`; for gated CRUD compose locally with `useSelectionMode` +
   `shareOrDownloadFiles` + `rotateImageToBlob` (see §Data entry → Attachments).
-- **Specialized work surfaces** — `ScanField` (scan/verify), `StepList` (guided run),
-  `RemainderMeter` + `AllocationRow` (allocation), `Timeline`, `Calendar`, `Gantt`,
-  `comments_thread`.
+- **Specialized work surfaces** — `ScanField` (scan/verify), `Stepper` (a guided run / progress
+  sequence — done · current · upcoming, horizontal OR vertical), `RemainderMeter` + `AllocationRow`
+  (allocation), `Timeline` (a heterogeneous event LOG — icons + expandable details, not progress),
+  `Calendar`, `Gantt`, `comments_thread`.
 - **AI surfaces** — `Composer` (the adaptive command/chat composer — a compact pill when empty that
   expands for long text + attachments; the surface that triggers agent work),
   `AgentRun` (the live streaming work feed) + `AgentProgress` (its compact, floating, expandable
   form — a composer's "working" state), `ReviewCard` (THE single-proposal review card — compositional
   body via `children`: a `RecordFields` record (header-first) or a `MatchSides` pairing (body-first))
-  + `Confidence`; `ChangeReview` (the BATCH review engine — whole-set OR 1-by-1; compositional via
-  `renderItem`, with `ChangeDiff` for the before→after body),
+  + `Confidence`; `ChangeReview` (the BATCH review list — whole-set OR 1-by-1; compositional via
+  `renderItem`, with `ChangeDiff` for the before→after body) + `ChangeReviewActions` (its commit bar,
+  pinned by the host in a `DialogFooter`/`DrawerFooter` or inline),
   `Clarify` (the agent asks back — selectable `ChoiceList` options),
   `Sources` (provenance chips for AI output). For STRUCTURED AI output the review
   surfaces above don't cover: `SpecList` (the "exact breakdown" — a labeled-value spec sheet, the
@@ -263,9 +265,13 @@ 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 steps (reasoning, tool calls) on a
-  spine, the running node a pulsing ink dot (a done step settles to a hollow ring). Transparent
-  work, NEVER a bare spinner — the
+- **Show the work** — `AgentRun`: a live feed of the agent's work — its streamed narration (with a
+  blinking caret) + 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
   morphs into it while running, and reveals again when done.
@@ -281,8 +287,13 @@ Compose the surfaces as a loop, and reach for the right one by job:
     → `tpl_match`). Stack several (rank by confidence) for a shortlist or a document's records.
   - **`ChangeReview`** — THE batch engine for a SET you decide each then commit together. `renderItem`
     draws each proposal (a `ChangeDiff` before→after body, a record, an editable form), 1-by-1
-    Keep/Drop collapses each, "Accept all" + Apply commits only the kept (e.g. ingested rate lines —
-    `tpl_ratedesk`); whole-set mode applies/discards the lot.
+    Keep/Drop collapses each (e.g. ingested rate lines — `tpl_ratedesk`); whole-set mode reviews the
+    lot. It is the LIST only — the commit bar (Accept all / Apply / Discard) is the SEPARATE
+    **`ChangeReviewActions`**, which the host places where commit bars belong (a `DialogFooter` /
+    `DrawerFooter`, or inline under the list). Don't bundle a commit into a scroll body — like every
+    other footer in the kit it's the container's to pin (`tpl_ratedesk` puts it in the `DialogFooter`).
+    `ChangeReviewActions` reads the same `items`/`statusOf`, so it owns Accept-all + the kept count —
+    never re-derive them in the host.
   The body atoms (`RecordFields`, `MatchSides`, `ChangeDiff`) are pure presentation — usable inside
   either engine OR standalone (a live-edit field card). The decide / accept-all / apply mechanics are
   never re-implemented per surface.
@@ -359,9 +370,11 @@ controls — while **status/severity/diffs use functional colour** the way the r
 - **Confidence** — a 3-tick meter + word, emerald / amber / zinc by level.
 - **Finding severity** — a coloured dot `Badge` + metric: red critical, amber warning, blue note,
   emerald on-track (+ stacking order, most severe first).
-- **AgentRun** — `Timeline`-style tinted-disc nodes that fade in: a running step spins **blue**, a
-  finished step is an **emerald check**, a failure a **red** alert; the header reads `Working` (blue
-  spinner) / `Done` (emerald check) / `Stopped` (red).
+- **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.
 - **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.
@@ -578,8 +591,8 @@ inline_time_picker (the Inline* family — per-field editors on `inline_edit`'s
 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 +
 columnFilterToConditions; for a register filtering on several columns) · chip_group · search_input ·
-sort_header · table · pagination · accordion · stepper ·
-step_progress · step_list · timeline · drawer (+ DrawerFooter) · dialog · popover · tooltip ·
+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 ·
 command_menu · alert · peek · empty_state · completion_state · callout (Callout · CalloutTitle ·
 CalloutText · CalloutActions) · kpi_card · kpi_strip · metric · trend_chip · sparkline ·
 bar_chart · line_chart · pie_chart · ring_gauge · progress_bar · stacked_progress_bar · breakdown ·
@@ -590,7 +603,7 @@ spacer · stack · section_card · page_header · page_content · calendar (cale
 comments_thread · agent_run (live streaming work feed) · agent_progress (its compact floating
 expandable form — a composer's working state) · composer (Composer — the adaptive command/chat
 composer: a compact pill that expands for long text + attachments) · review_card (ReviewCard — THE single-proposal review card; compositional body via children + a generic actions footer; header-first with a title/eyebrow, body-first without) · confidence (calibrated high/med/low) ·
-record_fields (RecordFields — the editable extracted-record BODY for a ReviewCard, or a standalone live-edit field card) · change_review (ChangeReview — the BATCH review engine, whole-set OR 1-by-1; compositional `renderItem` body + the `ChangeDiff` before→after helper) ·
+record_fields (RecordFields — the editable extracted-record BODY for a ReviewCard, or a standalone live-edit field card) · change_review (ChangeReview — the BATCH review LIST, whole-set OR 1-by-1; compositional `renderItem` body + the `ChangeDiff` before→after helper, `labels` localizes Undo/Applied/Discarded/counter — PLUS `ChangeReviewActions`, the separate commit bar the host pins in a `DialogFooter`/`DrawerFooter` or inline so it never scrolls away) ·
 clarify (the agent asks back, via ChoiceList) · choice_list (ChoiceList — selectable answer options,
 the agent's quick-reply surface) · sources (provenance chips, per-kind glyphs) · spec_list (SpecList — the exact
 labeled-value breakdown, the panel of an answer) · match_sides (MatchSides — the two-sided pairing BODY for a body-first ReviewCard reconciliation; composable side slots + the MatchSideText default) ·

package/examples/tpl_assistant.tsx

@@ -4,7 +4,7 @@ import { colors } from "@lotics/ui/colors";
 import { Text } from "@lotics/ui/text";
 import { DotsIndicator } from "@lotics/ui/dots_indicator";
 import { Composer } from "@lotics/ui/composer";
-import { ChangeReview, ChangeDiff, type ChangeReviewItemStatus } from "@lotics/ui/change_review";
+import { ChangeReview, ChangeReviewActions, ChangeDiff, type ChangeReviewItemStatus } from "@lotics/ui/change_review";
 
 // ─────────────────────────────────────────────────────────────────────────────
 // Template · AI assistant — a CHAT workflow, a different shape from the design
@@ -115,30 +115,42 @@ export function TplAssistant() {
                 ) : null}
                 {m.text ? <Text size="sm">{m.text}</Text> : null}
                 {m.changes ? (
-                  <ChangeReview
-                    items={m.changes}
-                    getKey={(c, i) => `${m.id}:${i}`}
-                    statusOf={(_, i) => decisions[`${m.id}:${i}`] ?? "pending"}
-                    renderItem={(c) => (
-                      <>
-                        <Text size="xs" color="muted" weight="medium">{c.label}</Text>
-                        <ChangeDiff before={c.before} after={c.after} />
-                      </>
-                    )}
-                    renderSummary={(c, kept) => (
-                      <View style={{ flexDirection: "row", alignItems: "center", gap: 10 }}>
-                        <Text size="sm" weight="medium" numberOfLines={1}>{c.label}</Text>
-                        <Text size="sm" numberOfLines={1} color={kept ? "default" : "muted"} style={[{ flex: 1 }, kept ? undefined : { textDecorationLine: "line-through" }]}>{kept ? c.after : (c.before ?? c.after)}</Text>
+                  <View style={{ gap: 14 }}>
+                    <ChangeReview
+                      items={m.changes}
+                      getKey={(c, i) => `${m.id}:${i}`}
+                      statusOf={(_, i) => decisions[`${m.id}:${i}`] ?? "pending"}
+                      renderItem={(c) => (
+                        <>
+                          <Text size="xs" color="muted" weight="medium">{c.label}</Text>
+                          <ChangeDiff before={c.before} after={c.after} />
+                        </>
+                      )}
+                      renderSummary={(c, kept) => (
+                        <View style={{ flexDirection: "row", alignItems: "center", gap: 10 }}>
+                          <Text size="sm" weight="medium" numberOfLines={1}>{c.label}</Text>
+                          <Text size="sm" numberOfLines={1} color={kept ? "default" : "muted"} style={[{ flex: 1 }, kept ? undefined : { textDecorationLine: "line-through" }]}>{kept ? c.after : (c.before ?? c.after)}</Text>
+                        </View>
+                      )}
+                      status={m.applied ? "applied" : "open"}
+                      onAcceptItem={active ? (i) => decide(m.id, i, "accepted") : undefined}
+                      onRejectItem={active ? (i) => decide(m.id, i, "rejected") : undefined}
+                      onUndoItem={active ? (i) => setDecisions((d) => { const n = { ...d }; delete n[`${m.id}:${i}`]; return n; }) : undefined}
+                    />
+                    {/* Inline (no dialog) — the commit bar sits under the list behind a divider. */}
+                    {active && !m.applied ? (
+                      <View style={{ borderTopWidth: 1, borderTopColor: colors.zinc[200], paddingTop: 14, flexDirection: "row" }}>
+                        <ChangeReviewActions
+                          items={m.changes}
+                          statusOf={(_, i) => decisions[`${m.id}:${i}`] ?? "pending"}
+                          applyLabel="Apply accepted"
+                          onAcceptItem={(i) => decide(m.id, i, "accepted")}
+                          onApply={() => applyMsg(m.id)}
+                          onDiscard={() => setMessages((ms) => ms.map((x) => (x.id === m.id ? { ...x, applied: true } : x)))}
+                        />
                       </View>
-                    )}
-                    status={m.applied ? "applied" : "open"}
-                    applyLabel="Apply accepted"
-                    onAcceptItem={active ? (i) => decide(m.id, i, "accepted") : undefined}
-                    onRejectItem={active ? (i) => decide(m.id, i, "rejected") : undefined}
-                    onUndoItem={active ? (i) => setDecisions((d) => { const n = { ...d }; delete n[`${m.id}:${i}`]; return n; }) : undefined}
-                    onApply={active ? () => applyMsg(m.id) : undefined}
-                    onDiscard={active ? () => setMessages((ms) => ms.map((x) => (x.id === m.id ? { ...x, applied: true } : x))) : undefined}
-                  />
+                    ) : null}
+                  </View>
                 ) : null}
               </View>
             </View>

package/examples/tpl_extract.tsx

@@ -133,7 +133,7 @@ export function TplExtract() {
 
         {phase === "extracting" ? (
           <Card>
-            <AgentRun title="Extracting line items" steps={steps} state={streaming ? "streaming" : "done"} />
+            <AgentRun steps={steps} state={streaming ? "streaming" : "done"} />
           </Card>
         ) : null}
 

package/examples/tpl_lookup.tsx

@@ -201,7 +201,7 @@ export function TplLookup() {
 
         <ScrollView style={{ flex: 1 }} contentContainerStyle={{ padding: 16, gap: 16 }}>
           {/* current run */}
-          <AgentRun title="Classifying the goods" steps={steps} state={streaming ? "streaming" : "done"} />
+          <AgentRun steps={steps} state={streaming ? "streaming" : "done"} />
 
           <View style={{ gap: 8 }}>
             <Text size="xs" color="muted" weight="medium">Nearest matches</Text>

package/examples/tpl_pick.tsx

@@ -11,7 +11,7 @@ import { Divider } from "@lotics/ui/divider";
 import { Popover, PopoverContent, PopoverFooter, PopoverTrigger } from "@lotics/ui/popover";
 import { ProgressBar } from "@lotics/ui/progress_bar";
 import { ScanField } from "@lotics/ui/scan_field";
-import { StepList, type StepListItem } from "@lotics/ui/step_list";
+import { Stepper, Step, type StepStatus } from "@lotics/ui/stepper";
 import { CompletionState } from "@lotics/ui/completion_state";
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -155,18 +155,6 @@ function Complete({ lines, onReset }: { lines: PickLine[]; onReset: () => void }
 // The right rail — the whole run at a glance: done · now · up next. Read-only;
 // the run is sequential, so position is shown, not chosen.
 function RunPath({ lines, currentIndex }: { lines: PickLine[]; currentIndex: number }) {
-  const steps: StepListItem[] = lines.map((l, i) => ({
-    id: l.id,
-    status: l.status === "short" ? "warning" : l.status === "picked" ? "done" : i === currentIndex ? "current" : "pending",
-    title: l.bin,
-    subtitle: l.item,
-    trailing:
-      l.status === "short" ? (
-        <Badge variant="dot" label={`${l.picked ?? 0} of ${l.qty}`} color="amber" />
-      ) : (
-        <Text size="sm" color="muted" tabular>{`×${l.qty}`}</Text>
-      ),
-  }));
   return (
     <Card style={{ padding: 0 }}>
       <View style={{ paddingHorizontal: 16, paddingVertical: 12 }}>
@@ -174,7 +162,27 @@ function RunPath({ lines, currentIndex }: { lines: PickLine[]; currentIndex: num
       </View>
       <Divider />
       <View style={{ paddingHorizontal: 16, paddingVertical: 14 }}>
-        <StepList steps={steps} accessibilityLabel="Pick path" />
+        <Stepper orientation="vertical" accessibilityLabel="Pick path">
+          {lines.map((l, i) => {
+            const status: StepStatus =
+              l.status === "short" ? "warning" : l.status === "picked" ? "done" : i === currentIndex ? "current" : "upcoming";
+            return (
+              <Step key={l.id} status={status}>
+                <View style={{ flexDirection: "row", alignItems: "flex-start", gap: 12, flex: 1 }}>
+                  <View style={{ flex: 1, gap: 1 }}>
+                    <Text size="sm">{l.bin}</Text>
+                    <Text size="xs" color="muted" numberOfLines={1}>{l.item}</Text>
+                  </View>
+                  {l.status === "short" ? (
+                    <Badge variant="dot" label={`${l.picked ?? 0} of ${l.qty}`} color="amber" />
+                  ) : (
+                    <Text size="sm" color="muted" tabular>{`×${l.qty}`}</Text>
+                  )}
+                </View>
+              </Step>
+            );
+          })}
+        </Stepper>
       </View>
     </Card>
   );

package/examples/tpl_ratedesk.tsx

@@ -17,7 +17,7 @@ import { AgentRun, type AgentRunStep } from "@lotics/ui/agent_run";
 import { Table, TableRow, TableCell, type TableColumn } from "@lotics/ui/table";
 import { InlineNumberInput } from "@lotics/ui/inline_number_input";
 import { CompletionState } from "@lotics/ui/completion_state";
-import { ChangeReview, type ChangeReviewItemStatus } from "@lotics/ui/change_review";
+import { ChangeReview, ChangeReviewActions, type ChangeReviewItemStatus } from "@lotics/ui/change_review";
 import { Dialog, DialogHeader, DialogHeaderTitle, DialogScrollArea, DialogFooter } from "@lotics/ui/dialog";
 import { formatDate } from "@lotics/ui/format_date";
 import { colors, solid, type ColorName } from "@lotics/ui/colors";
@@ -238,7 +238,7 @@ export function TplRatedesk() {
           </View>
         ) : null}
 
-        {phase === "reading" ? <AgentRun title="Reading carrier sheets" steps={runSteps} state="streaming" /> : null}
+        {phase === "reading" ? <AgentRun steps={runSteps} state="streaming" /> : null}
 
         {phase === "review" ? (
           <ChangeReview
@@ -254,12 +254,9 @@ export function TplRatedesk() {
                 <Text size="xs" color="muted" numberOfLines={1} tabular style={[{ flex: 1 }, kept ? undefined : { textDecorationLine: "line-through" }]}>{l.carrier} · {l.unit} · sell {usd(l.sell)}</Text>
               </View>
             )}
-            applyLabel={`Apply ${lines.filter((l) => decisions[l.id] === "accepted").length} kept`}
             onAcceptItem={(i) => decide(lines[i].id, "accepted")}
             onRejectItem={(i) => decide(lines[i].id, "rejected")}
             onUndoItem={(i) => decide(lines[i].id, null)}
-            onApply={applyAccepted}
-            onDiscard={reset}
           />
         ) : null}
 
@@ -268,21 +265,29 @@ export function TplRatedesk() {
         ) : null}
       </DialogScrollArea>
 
-      {/* idle + done carry footer actions; reading streams and review owns its
-          own Accept-all / Apply footer inside ChangeReview */}
-      {phase === "idle" || phase === "done" ? (
+      {/* idle / review / done carry footer actions; reading just streams. The
+          review commit bar pins HERE via ChangeReviewActions — it never scrolls
+          away inside the list. */}
+      {phase === "idle" ? (
         <DialogFooter>
-          {phase === "idle" ? (
-            <>
-              {files.length > 0 ? <Button title="Clear" color="muted" shape="rounded" onPress={() => setFiles([])} /> : null}
-              <Button title={files.length ? `Read ${files.length} sheets` : "Read sheets"} color="primary" shape="rounded" disabled={!files.length} onPress={() => { setRevealed(0); setPhase("reading"); }} />
-            </>
-          ) : (
-            <>
-              <Button title="Import more" color="secondary" shape="rounded" onPress={reset} />
-              <Button title="Done" color="primary" shape="rounded" onPress={closeImport} />
-            </>
-          )}
+          {files.length > 0 ? <Button title="Clear" color="muted" shape="rounded" onPress={() => setFiles([])} /> : null}
+          <Button title={files.length ? `Read ${files.length} sheets` : "Read sheets"} color="primary" shape="rounded" disabled={!files.length} onPress={() => { setRevealed(0); setPhase("reading"); }} />
+        </DialogFooter>
+      ) : phase === "review" ? (
+        <DialogFooter>
+          <ChangeReviewActions
+            items={lines}
+            statusOf={(l) => decisions[l.id] ?? "pending"}
+            onAcceptItem={(i) => decide(lines[i].id, "accepted")}
+            onApply={applyAccepted}
+            onDiscard={reset}
+            applyLabel={`Apply ${lines.filter((l) => decisions[l.id] === "accepted").length} kept`}
+          />
+        </DialogFooter>
+      ) : phase === "done" ? (
+        <DialogFooter>
+          <Button title="Import more" color="secondary" shape="rounded" onPress={reset} />
+          <Button title="Done" color="primary" shape="rounded" onPress={closeImport} />
         </DialogFooter>
       ) : null}
     </Dialog>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/ui",
-  "version": "5.3.0",
+  "version": "5.5.0",
   "type": "module",
   "exports": {
     "./tokens": "./src/tokens.ts",
@@ -139,7 +139,6 @@
     "./table": "./src/table.tsx",
     "./detail_row": "./src/detail_row.tsx",
     "./scan_field": "./src/scan_field.tsx",
-    "./step_list": "./src/step_list.tsx",
     "./completion_state": "./src/completion_state.tsx",
     "./remainder_meter": "./src/remainder_meter.tsx",
     "./allocation_row": "./src/allocation_row.tsx",

package/src/agent_progress.tsx

@@ -4,7 +4,7 @@ import { colors } from "./colors";
 import { Text } from "./text";
 import { WaveAvatar } from "./wave_avatar";
 import { PressableHighlight } from "./pressable_highlight";
-import { AgentRun, type AgentRunStep } from "./agent_run";
+import { AgentRun, resolveToolMeta, type AgentRunStep } from "./agent_run";
 
 export interface AgentProgressProps {
   steps: AgentRunStep[];
@@ -12,6 +12,11 @@ export interface AgentProgressProps {
   /** The collapsed-pill label. Defaults to the running step's label (or
    *  "Working…" / "Done"). */
   label?: string;
+  /** The agent's streamed text — forwarded to the expanded `AgentRun`. */
+  text?: string;
+  /** Localize / override a tool step's label by raw tool name — applied to both
+   *  the collapsed pill and the expanded feed. */
+  labelForTool?: (toolName: string) => string | undefined;
   defaultExpanded?: boolean;
 }
 
@@ -24,11 +29,16 @@ export interface AgentProgressProps {
  * label, so the surface stays calm until you ask to see the steps.
  */
 export function AgentProgress(props: AgentProgressProps) {
-  const { steps, state = "streaming", label, defaultExpanded } = props;
+  const { steps, state = "streaming", label, text, labelForTool, defaultExpanded } = props;
   const [expanded, setExpanded] = useState(defaultExpanded ?? false);
 
   const running = steps.filter((s) => s.status === "running").at(-1);
-  const compact = label ?? running?.label ?? (state === "done" ? "Done" : state === "error" ? "Stopped" : "Working…");
+  const runningLabel = running
+    ? running.kind === "tool"
+      ? resolveToolMeta(running.label, labelForTool).label
+      : running.label
+    : undefined;
+  const compact = label ?? runningLabel ?? (state === "done" ? "Done" : state === "error" ? "Stopped" : "Working…");
   const streaming = state === "streaming";
 
   return (
@@ -36,7 +46,7 @@ export function AgentProgress(props: AgentProgressProps) {
       {expanded ? (
         <View style={styles.panel}>
           <ScrollView style={{ maxHeight: 260 }} contentContainerStyle={{ padding: 16 }}>
-            <AgentRun steps={steps} state={state} />
+            <AgentRun steps={steps} state={state} text={text} labelForTool={labelForTool} />
           </ScrollView>
         </View>
       ) : null}