@lotics/ui 21.1.0 → 21.3.0

package/AGENTS.md

@@ -27,6 +27,13 @@ CURRENT major only — upgrading an app across majors is `MIGRATION.md`.
   license to hand-roll.
 - **One canonical component per data role** (member → `MemberChip`, select → `OptionBadge`,
   files → `FilePreview` family, …) — the catalog's Reach-by-role outranks neighboring code.
+- **Progress: rows of WORK vs positions of ONE thing.** N items ticked in any order, every row
+  the same shape → `task` (`TaskList`). ONE record walking ordered stages where the stage decides
+  which fields, conditions and act are even offered → **`pipeline`** (`Pipeline` +
+  `PipelineStage`, over `stepper`) — worked in `examples/tpl_record.tsx` § Progress, which it took
+  over FROM a per-desk checklist. Rendering positions as a checklist forces every row to carry
+  every control and never says where the record sits; rendering work items as a pipeline implies
+  an order that is not there.
 - **`Badge` = STATUS only; supporting detail is the muted second line.** A type / category /
   attribute / count is not a status — it belongs under its identity as `size="xs" color="muted"`,
   never a second chip. A chip beside a name reads as its PEER (a colored one reads louder),

package/MIGRATION.md

@@ -4,6 +4,22 @@ Breaking changes, newest first — normally per major, plus the rare minor that
 anyway (recorded under its exact version). The current contract lives in `AGENTS.md` + `docs/`;
 this file exists only to move an app from one release to the next.
 
+## 21.2.0 — `Stepper` is a list, not a progressbar
+
+No API changed, but the RENDERED role did, so a test that queried it breaks:
+
+```ts
+page.getByRole("progressbar", { name: "Pick path" })   // BEFORE
+page.getByRole("list", { name: "Pick path" })          // AFTER — <ul> of <li>, one per Step
+```
+
+`progressbar` is a range widget: without `aria-valuenow`/`min`/`max` it announces as an
+indeterminate "busy", and its children are PRESENTATIONAL — which hid every step's label, and
+in a `Pipeline` the date pickers, selects and buttons a stage carries. A sequence of named
+positions is a `list` whose live entry has `aria-current="step"`. `StepProgress` keeps
+`progressbar` — its segments really are decoration over one quantity — and now carries the
+values it was missing.
+
 ## v21 from 20.x
 
 **`FilesEditor` is a COMPOUND.** It rendered a fixed toolbar — Upload · Select · Download all,

package/docs/catalog.md

@@ -112,9 +112,10 @@ its NAME beside it), never a `DetailTable` in a `TaskDetail`, which declares a g
 The SAME composition serves a record's 5–8-task drawer checklist and a grouped desk board,
 because a sub-row reflows instead of being authored per surface; add `SuggestionChip` commons +
 `CaptureRow` for the checklist case. **A list you scan DOWN columns — the same four values
-compared across twenty rows — is a `Table`, not a `TaskList`.** See
-[`tpl_record`](../examples/tpl_record.tsx) / [`tpl_item_list`](../examples/tpl_item_list.tsx),
-and [`tpl_task_board`](../examples/tpl_task_board.tsx) for columns.
+compared across twenty rows — is a `Table`, not a `TaskList`.** And a record's own PROGRESS is
+not a checklist at all — that's `Pipeline` ([`tpl_record`](../examples/tpl_record.tsx) § Progress).
+See [`tpl_item_list`](../examples/tpl_item_list.tsx) for the checklist grammar, and
+[`tpl_task_board`](../examples/tpl_task_board.tsx) for columns.
 
 ### Tabular data — pick by SCALE + intent
 
@@ -158,7 +159,9 @@ plain sm tabular count beside it — the cell/heading/peek-trigger meter; a capt
 above a tiny bar reads misaligned. **The track clamps at 100%, the caption does not** — over
 its max it reads `2,100 / 2,000 · 105%`, because a meter that says "100%" when you are over
 tells the reader they are exactly at the limit. Numbers format in the reader's locale, so
-never hand-format the value you pass in) / `StackedProgressBar` / `StepProgress`, `Breakdown` (a
+never hand-format the value you pass in — when display precision differs from the true value
+(whole credits off a fractional balance), `formatValue` reshapes the caption text and leaves
+the fill and the percentage exact) / `StackedProgressBar` / `StepProgress`, `Breakdown` (a
 stacked bar + ranked share rows, pressable to drill; `maxRows` folds the long tail behind a
 "Show N more" toggle — `labels` to localize — so several facet cards align to one height in
 a row), `Funnel` (a CONVERSION funnel — ordered stages as bars that NARROW; the step
@@ -687,7 +690,7 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
     VALUE-FIRST: the date drops its resting calendar glyph, a select drops its chevron (the column
     header + the uniformly-editable grid are the affordance; the saving spinner still shows). For a
     DENSE, uniformly-editable surface — a register/`DataGrid` column, a task row (worked example:
-    `tpl_task_board`'s columns, `tpl_record`'s Tasks section).
+    `tpl_task_board`'s columns, `tpl_item_list`'s rows).
 
   There is NO separate `*Cell` component family — a data-grid cell is `<InlineSelect variant="cell" …/>`,
   not a `SelectCell`. (Naming a component for a USE, and duplicating the picker stack to flip two
@@ -983,7 +986,9 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   plain sm tabular count beside it.
 - **`stacked_progress_bar`** — `StackedProgressBar`: one whole split across segments (a
   status mix on one bar).
-- **`step_progress`** — `StepProgress`: N-of-M dots/segments progress.
+- **`step_progress`** — `StepProgress`: N-of-M dots/segments progress. A real `progressbar`
+  (valuenow/min/max) because its segments are decoration over ONE quantity — the opposite
+  case from `stepper`, whose steps carry content a `progressbar` would hide.
 - **`breakdown`** — `Breakdown`: a stacked bar + ranked share rows, pressable to drill;
   `maxRows` folds the long tail behind a localized "Show N more" toggle
   (`BreakdownLabels`).
@@ -1020,11 +1025,23 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   provider-wired — pass `labels` (`DEFAULT_GANTT_LABELS` is English).
 - **`timeline`** — `Timeline`: a heterogeneous event LOG — per-row icon + expandable
   details; models the past, NOT progress.
+- **`pipeline`** — `Pipeline` + `PipelineStage` + `PipelineField` / `PipelineNote` /
+  `PipelineActions` — the handoff COMPOUND: one record walking ordered STAGES where each stage
+  owns its own fields, conditions and act. Composes over `stepper` (which renders position
+  only). Reach for it over `task` when the rows are POSITIONS rather than work items — one thing
+  moving, one stage live, different controls per stage; `task` is N identical rows ticked in any
+  order. `PipelineNote` is a condition ON a stage (never a `Callout` above the run);
+  `PipelineField` stays editable on a PASSED stage, which is what makes a mis-entry fixable.
+  Worked screen: `examples/tpl_record.tsx` § Progress — the desks (Sales → Operations →
+  Accounting) ARE the stages, each owning the facts it stamps and, on the live one, the act
+  that leaves it. A `PipelineStage` is deliberately NOT pressable: its body holds the controls.
 - **`stepper`** — `Stepper` + `Step` — done/current/upcoming/warning/complete progress on a
   track (horizontal) or spine (vertical); compound `<Step status>children` OR data
   `steps[]`+`current`; **navigable** via `Step.onPress` (both orientations — the whole step
   is the tap target) + `active` to wash the selected one, so it doubles as a section/phase
-  switcher; the guided-run / agent-feed primitive.
+  switcher; the guided-run / agent-feed primitive. It is a **`list` of `listitem`s** with
+  `aria-current="step"` on the live one — a sequence of NAMED positions whose steps carry
+  their own content is a list, never a `progressbar`.
 
 ### Files
 

package/docs/templates.md

@@ -41,8 +41,10 @@ the package index is [../AGENTS.md](../AGENTS.md).
 | A register / consolidated work-list (browse, per-row action, bulk action) | `tpl_item_list` |
 | A guided sequence of physical tasks (scan, confirm, next) | `tpl_pick` |
 | Splitting one source amount across many targets | `tpl_allocate` |
-| A record's create/edit surface — also the settings shape (its Tasks section IS the canonical task pattern) | `tpl_record` |
+| A record's create/edit surface — also the settings shape | `tpl_record` |
+| A checklist ON a record (the canonical task-list grammar) | `tpl_item_list` (its Tasks section) |
 | A team task board (inline-managed grouped table) | `tpl_task_board` |
+| One record HANDED between desks — stages that each own their controls | `tpl_record` (its Progress section) |
 | Financial statements | `tpl_statements` |
 | A scoped lookup report with export | `tpl_report` |
 | A week calendar + agenda | `tpl_calendar` |
@@ -258,10 +260,10 @@ left panel as the bare circular `BackButton`). First paint is a `Skeleton` MIRRO
 layout, never a spinner. It absorbed the old order-form, inline-record, intake, settings,
 billing, and quick-capture templates. Top → bottom:
 
-- A MINIMAL header: `RecordSummary` (title · subtitle ONLY — no stage chip, no metric; Tasks
-  carries progress, Handoff carries the desk, money lives in Billing), then the record's
+- A MINIMAL header: `RecordSummary` (title · subtitle ONLY — no stage chip, no metric; Progress
+  carries the desk, Handoff carries what it created, money lives in Billing), then the record's
   ATTENTION state as a co-located `Callout` (e.g. overdue — record-scoped state reads here;
-  field-scoped state stays on its field), then a quiet `SummaryLine` (tasks done · documents
+  field-scoped state stays on its field), then a quiet `SummaryLine` (desk · documents
   · to collect).
 - **GENERAL — the MAIN details, FIRST in the rail**; every later section is supplementary.
   A `SubsectionStack` (space-only beat) of a headingless LEAD group (the key facts) plus
@@ -283,20 +285,15 @@ billing, and quick-capture templates. Top → bottom:
   (author-only edit/delete; attachments as a pressable `FileGrid` → gallery preview; a
   file-capable edit form injected via `renderEditForm`) + THE kit `Composer` (attach via
   `actionsButton`, staged files in its `files` slot) — never a bespoke comment box.
-- **Tasks** — the full task-list grammar: clearable Group-by `FilterChip` (+ assignee/status
-  chips), the `CaptureRow` on top, `TaskList`/`TaskItem` rows and per-row `TaskActions` menus,
-  suggestions as `SuggestionChip`s; groups divide via the `SubsectionStack` beat with plain
-  text heads (no dot badges). Each row's **due + assignee are `TaskSubRow`s UNDER the title** —
-  the SAME `InlineDatePicker` / `InlineMemberSelect` used in the General section, in the default
-  form variant, each with its NAME beside it one indent step in: the due an urgency-coloured date
-  (`tone` = `dueTone` — red past due, amber ≤3d, else muted), the assignee the full member chip.
-  A task row is not a table row — a value column reserved on the list put each name a quarter of
-  the record from its own control. ONE row ("Book the carrier") carries **SUBTASKS** — a nested
-  `TaskList` of four child ticks, each a `TaskItem` with a STRING `TaskTitle`; every other row
-  holds an empty array and renders no list at all. There is no built-in expander: collapsing is
-  the app's call, and this template always shows them. It is the line to copy — a booking's steps
-  carry only a tick, so they stay child rows; anything needing its own due date or assignee is a
-  task instead.
+- **Progress** — the desk handoff as the ordered positions it is: a bare `Pipeline` over
+  Sales → Operations → Accounting. Each REACHED stage owns the facts it stamps as
+  `PipelineField`s (taken-on `InlineDatePicker`, owner `InlineMemberSelect`) and keeps them
+  editable once the record has moved on; the LIVE one adds its condition (`PipelineNote`, e.g.
+  past the due date) and the single act that leaves it (`PipelineActions` → the handoff dialog).
+  An unreached stage is its title alone. `meta` carries how long the desk has held it — prose
+  the reader can't set, never the date that the stage's own field already shows. See § The
+  handoff shape for the rules; for a record that genuinely needs a CHECKLIST, the task-list
+  grammar is worked in `tpl_item_list`.
 - **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).
@@ -385,9 +382,16 @@ billing, and quick-capture templates. Top → bottom:
   here: the dialog collects the receiver (`MemberSelect`, confirm disabled until chosen) +
   an optional note; confirm writes the trail mark and the SIBLING record, shown as the same
   linked-record box (its drawer holds the reference info + Open record + **Recall**). After
-  the handoff there is NO further CTA. Recall is the undo: confirmed, it withdraws the
-  sibling and returns the desk — history is NEVER erased (the trail keeps both marks) and
-  the CTA returns, so redo is possible.
+  the handoff there is NO further CTA — the act to leave the NEW desk rides that desk's stage
+  in Progress, and this section shows only what the handoff produced (with an empty state when
+  it has produced nothing yet).
+
+  Recall is the undo: confirmed, it withdraws the sibling, clears the custody stamp that
+  handoff wrote, and returns the record to the desk BEFORE it — one step, never a jump to the
+  first desk, which would silently drop the desks between. History is NEVER erased (the trail
+  keeps both marks) and the CTA returns, so redo is possible. **Only the LATEST handoff offers
+  Recall.** Undoing a superseded one would leave the record behind a sibling that still exists
+  — the stage and the linked records would disagree — so a walk-back is one handoff at a time.
 - **Danger zone** — with the full section anatomy (heading + description) like every other
   section; the fenced red `DangerZone` card is the section's BODY.
 - A LEFT OUTLINE RAIL (`MenuButton` + `useSectionNav`) — **the rail is the page's COMPLETE
@@ -415,6 +419,51 @@ billing, and quick-capture templates. Top → bottom:
   below that it collapses to the pinned bar. Sizing the column is the SHELL's job — inner
   blocks are plain `width: "100%"`, never a second `maxWidth` + `alignSelf: "center"`.
 
+### The handoff shape — `Pipeline`, and where it lives
+
+One record walking N ordered stages, where **the stage decides what you can see and do**: work
+passed between desks — an application through intake → review → production → filing, a claim
+through submitted → assessed → paid.
+
+It is NOT its own template. A handoff is something a RECORD does, so it renders as one section
+OF that record — see `tpl_record` § Progress, where the desks (Sales → Operations → Accounting)
+become the stages, each owning the facts it stamps (taken-on, owner) and the live one carrying
+the act that leaves it.
+
+**It replaced a per-desk CHECKLIST, and that swap is the lesson.** Ticking boxes described the
+WORK; it never said where the record SAT, so the reader had to infer position from which group
+still had unticked rows — and the handoff CTA sat in a different section entirely, the act
+divorced from the state that gated it. A stage says the position outright, and the act rides the
+stage it belongs to. Reach for a checklist only when the rows are genuinely N independent
+tickable items (`TaskList`); a record's own progress is a pipeline.
+
+Built on the `Pipeline` compound (`Pipeline` · `PipelineStage` · `PipelineField` ·
+`PipelineNote` · `PipelineActions`), which composes over `Stepper` — `Stepper` renders POSITION,
+this adds the anatomy that turns a position into a workspace.
+
+Three rules the anatomy holds, each learned from getting it wrong:
+
+- **Only the CURRENT stage carries an act.** A control on an unreached stage invites acting out
+  of order — and where the stage is derived from the highest stamp, one stray press jumps the
+  record past the desk that owns it. On a passed stage it re-offers something already done.
+- **A condition belongs to its stage.** "Sent back", "rejected", "waiting on the customer" are
+  facts about ONE stage, so they render inside it (`PipelineNote`) rather than as a `Callout`
+  above the run, which reads as "something is wrong with this record" and sits nowhere near the
+  control that answers it.
+- **A passed stage stays correctable** — its date (clearable, which is how you walk a record
+  BACK) and any field it owns. Otherwise a value typed wrong becomes unreachable the moment the
+  record moves on, and the only fix is direct table access.
+- **The stage that OPENS gets stamped by the act that opened it**, and the TERMINAL act is not
+  a handoff. Handing off asks whom (a dialog) and writes that answer into the receiving stage's
+  own fields — coming up blank re-asks a question just answered. Finishing has no receiving
+  desk, so it asks for confirmation and nothing else; routing it through the same dialog is how
+  a template ends up asking "Assignee at Closed" and then confirming nothing.
+
+**Altitude rule**: the pipeline is ONE record's progress. N records each at their own stage is
+a REGISTER (`tpl_item_list`) with a derived stage column — the same ladder module feeding both,
+so a row's badge and its filter bucket can never disagree. Rows that are structurally identical
+and tickable in any order are a `tpl_task_board`, not a pipeline.
+
 ### `tpl_task_board` — the columns shape
 
 The manager's board: a search · group-by · filter toolbar over a grouped, sortable grid of