@lotics/ui 45.8.1 → 45.10.0

package/AGENTS.md

@@ -104,12 +104,12 @@ CURRENT major only — upgrading an app across majors is `MIGRATION.md`.
   `error={overdue ? … }` is the tell: it makes a date due tomorrow read like one due in three
   months. → [catalog.md §Dates & times](./docs/catalog.md).
 - **A third-party channel takes `BrandMark`, our own glyphs take `Icon`.** `@lotics/ui/brand_mark`
-  draws Facebook / Zalo / LinkedIn / X / Google Meet / Gmail / Outlook / Google Drive as solid
-  single-colour silhouettes — a reader scanning a feed recognises the logo before the word. The
-  names are an allowlist, so a channel with no mark (a phone call, an event, a website) fails to
-  typecheck and falls back to `Icon` instead of borrowing another company's logo. `SwitchButton`
-  takes one directly as `brand`, for a row naming an outside service.
-  → [catalog.md §Text & formatting](./docs/catalog.md).
+  draws Facebook / Zalo / LinkedIn / X / Google Meet as solid single-colour silhouettes — a reader
+  scanning a feed recognises the logo before the word. The names are an allowlist, so a channel with
+  no mark (a phone call, an event, a website) fails to typecheck and falls back to `Icon` instead of
+  borrowing another company's logo. A product's official full-colour logo is NOT one of these: the
+  kit ships no vendor artwork, so a row that names a product passes its own image into
+  `SwitchButton`'s `leading` slot. → [catalog.md §Text & formatting](./docs/catalog.md).
 - **The kit's fonts/colors/icons ARE the design system** — never a custom font, icon set, or
   hand-picked palette shade; color is `solid`/`tint`/`ramp` with ONE accent per screen.
 - **Hand-typed type is off-system — and it always lands too small.** Every run of language is

package/MIGRATION.md

@@ -4,6 +4,24 @@ 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.
 
+## 45.9.0
+
+**`BrandMark` no longer carries product logos, and `SwitchButton` takes `leading` instead of
+`brand`.** `BRAND_NAMES` drops `gmail`, `outlook` and `google-drive`; the kit's marks are the
+single-colour CC0 silhouettes that NAME a channel — `facebook`, `zalo`, `linkedin`, `x`,
+`google-meet` — and a monochrome stand-in for a product logo reads as a different thing.
+
+Replace `<BrandMark name="gmail" />` with your own image asset. A row that named a product with
+`<SwitchButton brand="gmail" …>` passes it through the new `leading` slot instead, which takes any
+node:
+
+```tsx
+<SwitchButton leading={<Image source={{ uri: logo }} style={{ width: 20, height: 20 }} />} … />
+```
+
+A retired name no longer typechecks, and a bundle compiled against an older kit renders nothing
+where the mark was rather than throwing.
+
 ## 45.5.0
 
 **`InlineSelect` and `InlineMemberSelect` are a `combobox`, not a `button`.** They rest as a

package/docs/catalog.md

@@ -285,7 +285,11 @@ its max it reads `2,100 / 2,000 (105%)`, because a meter that says "100%" when y
 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 — 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
+the fill and the percentage exact) / `StackedProgressBar` (ONE whole split across segments,
+filling its own track whatever the total) / `StackedBarChart` (SEVERAL wholes compared — rows
+of stacked bars on one shared scale, so length says how big and the segments say what of) /
+`StepProgress`, `WaterfallChart` (the BRIDGE — an opening level, the signed steps that move
+it, the level they close at; revenue walked down to net), `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
@@ -484,17 +488,16 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   `SubsectionHeading` instead. Pick between this and `Eyebrow` by what is LABELLED — a block or a
   value; composition.md § Eyebrow vs group lead has the table.
 - **`brand_mark`** — `BrandMark`: an OUTSIDE brand's mark, naming the channel a touchpoint
-  happened on or the service a connection reaches — `facebook`, `zalo`, `linkedin`, `x`,
-  `google-meet`, `gmail`, `outlook`, `google-drive`. Solid single-colour silhouettes in
-  each brand's own hex, not the full-colour logos: a byline draws these at 14–20px and a
-  five-colour logo turns to mud there. `size` (default 16) and `muted` (draw in the text colour).
-  The name list is an ALLOWLIST — `BRAND_NAMES` is the array and `BrandName` derives from it, so a
-  channel with no mark will not typecheck and the call site falls back to a generic `Icon` rather
-  than rendering the wrong company's logo. Not for the app's
+  happened on — `facebook`, `zalo`, `linkedin`, `x`, `google-meet`. Solid single-colour silhouettes
+  in each brand's own hex, drawn from CC0 geometry. `size` (default 16) and `muted` (draw in the
+  text colour). The name list is an ALLOWLIST — `BRAND_NAMES` is the array and `BrandName` derives
+  from it, so a channel with no mark will not typecheck and the call site falls back to a generic
+  `Icon` rather than rendering the wrong company's logo. Not for the app's
   own glyphs; that is `icon`. `x` is the one mark whose brand colour is BLACK, so it is the one
-  that needs `muted` on a dark ground; the rest carry their own hue either way. Where a brand's
-  official mark is a composite (Outlook's envelope-and-O), the entry carries the half that stays
-  legible small — the identifying monogram — because a shape nobody can read is not the mark.
+  that needs `muted` on a dark ground; the rest carry their own hue either way. **Not a product
+  logo**: a monochrome stand-in for one reads as a different thing (a red "M" is not Gmail), the kit
+  ships no vendor artwork, and official artwork is not uniformly inlinable anyway — pass your own
+  image to `SwitchButton`'s `leading` slot instead.
 - **`markdown`** — `Markdown`: the single canonical markdown renderer for chat, apps, and
   `AgentRun`; rich GFM markdown on web with copyable tables, plain-text on
   native; takes a markdown `children` string. **`variant`** decides whose type
@@ -1079,9 +1082,8 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   (optional leading mark + medium title left, `Switch` pinned right) where the whole row IS the
   switch (`accessibilityRole="switch"`, the inner Switch read-only). The settings-panel/menu
   row toggle. The leading slot takes EITHER `icon` (an `IconName`, the app's own glyph language)
-  or `brand` (a `BrandName`, an outside service's mark); `icon` wins if both are passed. A row
-  naming a third-party service takes `brand` — the two sets are deliberately separate, so a
-  connector row cannot reach for a Lotics glyph to stand in for a company's logo.
+  or `leading` (any node); `icon` wins if both are passed. A row naming an outside product passes
+  its logo through `leading`, because the kit ships no vendor artwork of its own.
 - **`use_form`** — `useForm`: THE batch draft-form state hook — `values` = `initialValues` +
   an edits overlay (a revalidation refreshes untouched fields, no sync effect), `validate`
   (sync/async, gates submit, editing clears the field's error), `onSubmit(values, helpers)`
@@ -1782,7 +1784,11 @@ component rather than showing it at zero.
   register wants — a column of them turns "12 numbers per row" into a pattern the eye reads
   without stopping. Reach for a real chart the moment someone needs to read a value off it.
 - **`bar_chart`** / **`line_chart`** / **`pie_chart`** — `BarChart` / `LineChart` /
-  `PieChart`: the canonical SVG chart set (no recharts).
+  `PieChart`: the canonical SVG chart set (no recharts). `LineChart` prints as many x labels
+  as the track fits and thins the rest, anchored on the LAST point — the newest reading is the
+  one a reader looks up, and anchoring there is what keeps the spacing uniform. The first
+  point is labelled only when it clears the same distance, so a series whose length does not
+  divide evenly drops its opening label rather than crowding the one beside it.
 - **`progress_bar`** — `ProgressBar`: the determinate meter; `compact` = ONE row, track + a
   plain sm tabular count beside it.
 - **`progress_ring`** — `ProgressRing`: the same meter in a circle, and the ONLY circular one. Same API shape as the bar — a real `value`/`max` rather than a
@@ -1794,7 +1800,35 @@ component rather than showing it at zero.
   bare ring renders no text, so it announces nothing — whatever owns it must say what it
   measures.
 - **`stacked_progress_bar`** — `StackedProgressBar`: one whole split across segments (a
-  status mix on one bar).
+  status mix on one bar). Its segments size against EACH OTHER, not against `total` — the
+  track is always full — because one whole is the whole of itself. That is the right model for
+  one bar and the wrong one for a column of them: ten unequal totals draw ten equal bars, which
+  reads as a chart and states nothing. Several wholes → `stacked_bar_chart`.
+- **`stacked_bar_chart`** — `StackedBarChart`: rows of stacked bars on ONE SHARED SCALE
+  (`max` defaults to the largest row total). Bar LENGTH answers "how big is this one", the
+  segment run answers "what is it made of", in one pass — spend against return per campaign,
+  cost make-up per product line. `series` (key/label/colour, one hue family per dimension)
+  drives a legend that is on by default; each `StackedBarRow` takes `label` + optional `meta`,
+  a pre-formatted headline `value` with its `valueTone`, and a `caption` sentence, so colour is
+  never the only channel. Between `stacked_progress_bar` (one whole, own track) and `breakdown`
+  (one whole + ranked share rows beneath it): reach here the moment there are SEVERAL wholes to
+  compare.
+- **`waterfall_chart`** — `WaterfallChart`: the BRIDGE — an opening level, the signed steps
+  that move it, and the level they close at. Revenue walked down to net, budget to actual,
+  opening balance to closing. `items` carry a `kind`: `basis` and `total` are LEVELS standing on
+  zero, `delta` (the default) is a signed STEP floating between the level before it and the
+  level after; colour derives from that — neutral basis, emerald up, red down, and a close in
+  the ink of its own sign — so a caller passes no colours. `orientation` vertical columns |
+  horizontal rows (take rows for a narrow container or long step names; a 70px column and a
+  rotated label is not an answer). The span always includes zero, so a bridge that closes at a
+  loss hangs below the baseline instead of floating on a scale that exaggerates every step.
+  `waterfallLayout` is the pure geometry, exported and tested on its own: a bridge is only worth
+  drawing if the floating bars land where the arithmetic says, and no screenshot confirms that.
+  Pick it over `ledger` when the reader is scanning for SHAPE (a dashboard), and `ledger` when
+  the figures must be read exactly and reconciled line by line (a record). Over `bar_chart`
+  whenever the bars are steps in ONE arithmetic — five columns all starting at zero state a
+  comparison nobody meant. The steps must be all of the arithmetic and must close on the total
+  drawn; derive them from one computation, never two that can drift.
 - **`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. Pass the stage

package/docs/composition.md

@@ -10,6 +10,40 @@ them produces off-system UI.
 
 ## The form comes before the treatment
 
+**If the domain already has a standard shape, that is the answer — build it.** A parcel's journey
+has looked the same in every carrier's app for twenty years: an ordered set of stages, where it is
+now, when each was stamped, and where it is stuck. A ledger has looked like a ledger since before
+software. A calendar, a seating chart, a pipeline, a boarding pass — each is a form the reader has
+already learned somewhere else, and matching it means they arrive knowing how to read the screen.
+Go and look at how the industry does it before designing something new; a shape that is unfamiliar
+in a domain that has a familiar one is a cost paid by every user, forever, to no end.
+
+That is a licence, not a leash. **The rules in this document constrain treatment, not invention.**
+Where the job needs a component the kit does not have, build it — the catalog is where solved
+problems live, not a ceiling on what a screen may be, and a screen assembled only from the parts
+nearest to hand is how everything ends up a register with a header. The bar for a new composition
+is that it is the RIGHT shape for the subject and that it obeys the language below: the kit's type
+ramp, colours, spacing and states. Reach for the shape the work deserves, then dress it in the
+kit's clothes.
+
+**Which rules bind, and which advise.** Read every rule here for what it ENCODES, because the two
+kinds are answered differently:
+
+- **A rule that prevents a known HARM binds.** A page that scrolls sideways on a phone, an act that
+  cannot be undone, a figure that is typed where it should be computed, a machine's guess rendered
+  like a person's decision, a control a keyboard cannot reach — these are settled, they were paid
+  for once, and re-opening them just re-buys the defect.
+- **A rule that picks among valid FORMS advises.** Which shape fits this subject, how a set is cut,
+  what the reader sees first — the space of jobs is unbounded and the best answer is regularly one
+  no document here has named. Treat these as the accumulated experience they are, then decide.
+
+The distinction is not hard-versus-soft, it is harm-versus-choice — and the second kind is where
+the good work happens. **Most of what reads as inventive is this document's FIRST rule being
+followed well, not escaped**: a set whose tabs are the stages its records pass through is not a
+departure from "name what the subject IS", it is that rule landing. Naming the subject honestly is
+what produces a shape nobody has seen; reaching for the nearest template is what produces the
+fiftieth register with a header.
+
 **Name what the subject IS, then reach for parts.** A set of records is a register; a thing moving
 through ordered places is a rail; work assigned to finite resources over time is a board; a
 sequence of events is a timeline; a population whose point is its deviant minority is a queue
@@ -563,6 +597,14 @@ read-only drill-downs expand via `Accordion` or glance via `Peek`; every other r
 surface is the door: register rows are `PressableRow` (full-bleed wash including nested controls),
 Divider-separated.
 
+**How MUCH the row reveals decides expand-vs-drawer.** An expanding row is for a few facts the
+reader takes in without losing their place — the rows around it stay visible, which is the whole
+point. Once the reveal is a screenful, it pushes the rest of the register off the fold and the
+reader is now reading a record through a slot cut in a list: they cannot see the set they came for,
+and they have to remember to collapse it. That is a `Drawer`. The threshold is not a row count, it
+is whether the neighbouring rows survive the expansion; if opening one row means the list is gone,
+open it properly.
+
 | `PressableRow` variant | Shape | Use |
 |---|---|---|
 | `register` (default) | rounded (radius 10) full-width hover/open/`marked` wash | THE record list |
@@ -687,6 +729,15 @@ The tokens are one step darker for exactly that reason, and they are what `IconB
 hover language. Bleed the wash outward (`marginHorizontal: -8` against its own padding) so the
 cell's content stays on the column's edge — see `ROW_WASH_BLEED`.
 
+**A pressable cell's target is the whole CELL, not the text inside it.** Bind the press and the
+hover to the cell box, so the reader aims at a column rather than at a word. Wrapping only the name
+leaves a target whose shape nobody can predict — it changes with the length of the value, it is a
+sliver on a short one, and the wash it lights stops short of the cell's edges so the highlight
+appears to bleed into the neighbouring thumbnail or supporting line rather than belonging to
+anything. If a cell holds an image and a name and pressing it opens the same thing, the image is
+part of the target too; a cell where only some of the content responds is telling the reader there
+are two things there when there is one.
+
 **Size a flexible column by what it CARRIES, measured.** A `flex` share is a claim about content;
 when the content shrinks — a value moves to the record, a stacked pair becomes a count — the
 share left behind is white space, and the columns beside it pay for it. Measure the widest row's
@@ -1330,6 +1381,27 @@ A flat register sorted by a column hands the reader every row at equal weight an
 deciding to them: "which of these needs me today" is answered by reading all of them. `TableGroup`
 moves that decision into the screen — a titled band of rows with a count.
 
+**Flat is the default; grouping is something the reader turns ON.** A register opens as one
+continuous list, and the control that splits it into bands lives in the filter band beside the
+other view controls — an explicit "group by" the reader operates, defaulting to none. Authored
+bands fail three ways at once: the value they group on is unsortable, it is unfilterable, and it
+vanishes the moment the reader wants a different cut — so the screen holds an opinion the reader
+cannot inspect, disagree with, or put down. Worse, it decides on their behalf every time they open
+the screen, including the many times the triage it encodes is not the question they came with.
+
+**The status COLUMN is the floor.** Whatever the register can group on also exists as a column the
+reader can see, sort and filter — the column is the fact, the grouping is one way of looking at it.
+Ship the column first, offer grouping as a control, and let `TableGroup` render whatever the reader
+picked. Everything below still governs how the bands look and behave once they are on; it just no
+longer describes the state the screen starts in.
+
+**A value's filter renders the value the same way its cell does.** If the status cell is a
+`Badge variant="dot"`, the status filter's options are dot badges too — same vocabulary, same
+colours, same shapes. The reader is matching what they just saw in the rows against what the
+control offers; re-rendering it as plain text makes them translate between two presentations of
+one field, and the two drift the first time either side gains a value. This holds for every
+custom-rendered value, not just status.
+
 **Group by what implies a different ACTION, never by a category the reader can already see.**
 Bands like *Waiting on you* / *Gone quiet* / *Open* / *Closed* each name a different response, so
 the grouping tells the reader something no column does. Grouping by a value that is already a
@@ -1596,6 +1668,37 @@ Type SCALE is the fourth, and it belongs with the others: range = largest ÷ sma
 screen, and under about 2× reads flat *at any amount of colour*. Scale is the one hierarchy device
 colour cannot substitute for. A register with no page band tops out near 1.33×.
 
+**The test every visual has to pass: does it make the screen CLEARER *and* better-looking?** Both,
+not either. A visual that only decorates is clutter and goes; a visual that only informs but fights
+the composition is a chart nobody reads. The ones that pay are the ones where the two are the same
+act — a status colour that is also the scan path, a product thumbnail that is also the identifier, a
+trend line that is also the answer. That framing is what keeps "make it less bland" from becoming
+"add more things", which is the failure this section is most often misread into.
+
+**And the same test cuts the other way, which the rest of this document does not say often enough.**
+Nearly every rule here removes something — SUBTRACT is a gate, the trim test hunts restatement, the
+absence pass looks for what should not be there. Follow only that gradient and you converge on a
+screen that is clean, defensible, and *does not tell the reader enough to act*. **Minimal is not the
+same as clear.** A number with no comparison, a status with no age, a total with no composition, a
+row that forces a click to answer the question it exists to answer — each is a screen that passed
+every subtraction and failed the reader. Withholding is a defect exactly as much as clutter is; it
+is simply the one that survives review, because nothing on the screen looks wrong. Ask what the
+reader must DECIDE, then check that the screen holds every fact that decision needs.
+
+**Where the data has a history, show the trajectory, not just the latest value.** A figure states
+where things stand; a line, a bar series or a `Sparkline` states where they are GOING, and the
+direction is usually the decision — a balance that is falling, a return rate that is climbing, a
+week that broke the pattern. This is the most common honest source of visual interest in work
+software, because the shape *is* information. It is also the one most often left out, since the
+current value is what the query returns first.
+
+**A register whose entity has ordered stages should render the stage, not just name it.** A word in
+a cell makes the reader know the vocabulary and its order; a small coloured progress indicator makes
+position legible at a glance and lets rows be compared down the column — which is the question a
+register is asked. Colour it by what the stage MEANS (moving / stalled / done / failed), so the
+column reads as a state of play rather than a palette. Do not spend this on a two-state field: a
+progress rendering of "open / closed" is a badge wearing a costume.
+
 ## Where the accent goes — "where you are", and nothing else
 
 `colors.accent` paints an active FILTER — the one place a brand hue answers "where the reader is"
@@ -1856,6 +1959,17 @@ Anything pressable is ≥ 40px tall (8px minimum gap between pressables). 16px b
 canvas padding, 16–20 inside bands, 10–12 between content lines. Density comes from alignment +
 hierarchy, not cramming.
 
+**Space states what belongs together, so the gap INSIDE a unit is always smaller than the gap
+BETWEEN units.** A line item's name, its code and its quantity are one thing and sit tight; the
+next line item starts after a clearly larger gap. Get the ratio backwards — or make both gaps
+equal — and the reader has to reconstruct the grouping from the content, because the layout is
+telling them the parts are peers of the wholes. The tell is a stack that reads as an undifferentiated
+list when you unfocus your eyes, or a supporting line drifting so far from the value it supports
+that it looks like the next unit's first line. This is the same law the gap-ratio probe in
+[reviewing.md](./reviewing.md) measures (~2:1 between over inside); it is stated here because it is
+a composition decision, not a treatment one — no amount of type or colour work fixes a stack whose
+spacing groups the wrong things.
+
 **A control's height comes from `CONTROL_HEIGHT`, never from padding tuned against a leading.**
 Padding that happens to sum to the band height is a second owner of that number, and it drifts the
 moment the type ramp moves — which the ramp is allowed to do. The signature is one control

package/docs/reviewing.md

@@ -269,6 +269,14 @@ spacing distinguishes them.
   do not rescue it. → [composition.md](./composition.md) §"Numbers, money, dates".
 - **A slot holding another component's part must be sized by that component's constant** — a
   24px mark in an 18px column sits 3px outside the surface.
+- **Labels placed along a track: collect each one's HEIGHT and compare across the set.** Anything
+  positioned by a fraction of its container — an axis tick, a marker on a timeline, a legend on a
+  meter — is sized by the space left to the container's EDGE, so the one at 100% shrink-wraps to a
+  few pixels and breaks its own text across two lines while every sibling measures fine. Height,
+  not width, is the signature: a wrapped label is *taller* than its neighbours, which no
+  alignment check and no screenshot at the width where it happens to fit will show. The same
+  collection catches a fixed pixel nudge standing in for centring — spacing between label CENTRES
+  that drifts across the track means each one was offset by a guess at its own width.
 - **A row beat belongs to the PAGE** — collect every row primitive's height on one screen before
   calling any of them right.
 

package/docs/templates.md

@@ -146,6 +146,36 @@ name `Peek`s the dossier). Also exercises the wider chart family (`LineChart`, `
 filter actually filters the KPI datasets. Start here for any "state of the operation"
 landing screen.
 
+**A dashboard is VISUAL first.** Its reader is scanning for shape — is this up or down, where is
+the outlier, which slice dominates — and shape is what a chart states and a number does not. A
+dashboard built as rows of figures is a report wearing a dashboard's name: correct, and it makes
+the reader do the comparing that the screen was supposed to do for them. Lead with the charts, let
+the figures support them. `KPIStrip` earns its place as the headline row above the charts, never as
+the whole screen.
+
+The chart family is `BarChart`, `LineChart`, `PieChart`, `Funnel`, `Heatmap`, `Sparkline`,
+`ProgressRing`, `ProgressBar`, `StackedProgressBar`, `StackedBarChart`, `WaterfallChart`,
+`StepProgress` — and **that list is a starting inventory, not the boundary.** When the truth needs
+a shape the kit has no component for — a dual-axis pairing spend against return, a bullet against
+target — **build it into `@lotics/ui`** rather than hand-rolling it inside one app. A chart
+assembled from `View`s in an app screen is invisible to every other app, carries its own spacing
+and colour decisions, and is the exact duplication `src/` exists to prevent; the same component in
+the kit is measured, themed and reusable the day after. Graduating it is the intended path, not an
+imposition on the kit (→ AGENTS.md, "components graduate into `src/` + an `examples/tpl_*` + a
+catalog entry").
+
+Read the `dataviz` guidance before choosing a chart type or a palette — picking the form is a
+separate decision from drawing it well.
+
+**No AI run belongs on a dashboard.** A dashboard's entire contract is that the answer is already
+there — the reader opens it and knows. A panel that has to be asked, that streams, that costs
+credits and can fail, breaks exactly the property the surface exists for, and it lands the reader
+on a spinner in the one place they came for an instant read. If a figure is worth showing, compute
+it and show it; if the question is open-ended enough to need a model, it belongs in chat, where
+interrogating the data is the point and waiting is understood. The same test disqualifies anything
+else that makes a dashboard *ask before it answers*: a required mode chooser, an empty state
+awaiting a selection, a panel that loads only on click.
+
 ### `tpl_stock` — the drill-down overview (large populations)
 
 Monitoring a population too large to browse (10,000+ units). The funnel: `KPIStrip`
@@ -194,7 +224,31 @@ master-detail panel.
 ### `tpl_item_list` — THE canonical register
 
 The one work-execution list shape; it subsumes approvals, dispatch, batch-building, and run
-screens — register, per-row action, gated selection, and act-on-many in one. The page:
+screens — register, per-row action, gated selection, and act-on-many in one.
+
+**A register is a WORK surface, and that fixes its altitude.** The reader came to narrow a set
+down and act on what is left — filter, scan, check, do. Everything on the screen serves that or it
+is in the way. So the aggregate belongs elsewhere: **no `KPIStrip`, no chart panel, no report band
+above the rows.** The register's whole summary is the one `SummaryLine`, and what it states is
+*this filtered view* — money at stake, how many need a decision, the worst case in view — never a
+count of rows the reader can already see. Aggregates are a DASHBOARD's job, and the two surfaces
+answer different questions: a dashboard says how the operation is doing, a register is where the
+work gets done. Putting a KPI band on a register pushes the rows below the fold to say something
+the reader did not come for. (A per-row micro-visual — a `Sparkline`, a bar in a cell — is row
+DATA, not a panel, and is fine.)
+
+The corollaries, each of which a register is routinely missing:
+
+- **Filter on the axis its reader actually thinks in**, and make anything transactional filterable
+  by DATE. A register you can only scroll is a report.
+- **Sortable columns wherever the reader ranks** — dates and amounts above all. "Which is biggest,
+  which is oldest" is the most common question a register is asked.
+- **Put intake ON the register.** The set is added to from the surface that lists it, and one CTA
+  per tab covers the tab's own shape. Where a file is the real-world input, the CTA pair is manual
+  entry beside a file-drop that proposes rows for review.
+- **If a row can carry a document, the register states whether it has one.** Absence is the
+  information — a badge that shows nothing for a row missing its invoice is exactly the column
+  that earns its width.
 
 - **One toolbar row** — search + a status `Select` + facet `FilterChip`s LEFT, the New CTA
   RIGHT; then a light `SummaryLine` of the filtered view BELOW it, above the rows — the counts are what the toolbar just produced, so they read after it, not before.
@@ -697,6 +751,25 @@ 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"`.
 
+### Anything that ADVANCES a record must be able to walk it back
+
+This holds wherever the progression is rendered — a stage CTA on a register row, a tick in a
+drawer's checklist, a bulk action over a selection, the handoff compound below. **Every control
+that moves a record forward ships its inverse, in reach of the person who pressed it.**
+
+A one-way control makes a misclick permanent, and stage CTAs invite the misclick: they sit on the
+row, they are the fastest thing on the screen, and the row leaves the tab the moment it is pressed
+— so the feedback for "that was wrong" is the record vanishing, with no obvious way back and often
+no obvious place it went. The reader is then hunting through tabs for a record they did not mean
+to move, which is a worse outcome than the one the CTA saved them.
+
+The undo belongs **beside the forward act, as its secondary** — the pair reads as one decision with
+two directions, the same pairing the kit already uses for a commit and the control that undoes it.
+Do not bury it in an `ActionMenu`: the person who needs it needs it in the second after the press,
+which is exactly when they will not go looking. Where a stage is genuinely irreversible (money has
+moved, a document has been filed, something left the building), the honest answer is not a missing
+undo — it is a confirmation *before* the act, and copy that says why it cannot be taken back.
+
 ### The handoff shape — a CONNECTED checklist, and where it lives
 
 One record walking N ordered positions, where **the position decides what you can see and do**:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/ui",
-  "version": "45.8.1",
+  "version": "45.10.0",
   "type": "module",
   "exports": {
     "./vite": {
@@ -83,6 +83,8 @@
     "./gantt": "./src/gantt/index.ts",
     "./progress_ring": "./src/progress_ring.tsx",
     "./stacked_progress_bar": "./src/stacked_progress_bar.tsx",
+    "./stacked_bar_chart": "./src/stacked_bar_chart.tsx",
+    "./waterfall_chart": "./src/waterfall_chart.tsx",
     "./legend_item": "./src/legend_item.tsx",
     "./breakdown": "./src/breakdown.tsx",
     "./funnel": "./src/funnel.tsx",

package/src/bar_chart.tsx

@@ -1,4 +1,4 @@
-import { View, StyleSheet } from "react-native";
+import { View, StyleSheet, type ViewStyle } from "react-native";
 import { useMemo } from "react";
 import { Text } from "./text";
 import { colors } from "./colors";
@@ -293,7 +293,25 @@ const styles = StyleSheet.create({
   horizontalAxisTick: {
     position: "absolute",
     alignItems: "center",
-    transform: [{ translateX: -12 }],
+    /**
+     * `max-content` + a half-width shift, so the label sizes to its own text and
+     * then centres on its tick at ANY label length.
+     *
+     * Both halves are load-bearing. An absolutely-positioned box with only
+     * `left` set is sized by the space remaining to the container's RIGHT EDGE,
+     * so the tick at 100% shrink-wraps to a few pixels and breaks its text
+     * across two lines — visible only at the widths where that label happens
+     * not to fit, which is why it survives a desktop-only pass. And a fixed
+     * pixel nudge cannot centre anything: it assumes one label width, so every
+     * tick is off by however far its own label differs from the guess.
+     */
+    transform: "translateX(-50%)",
+    // The one style here RN cannot type: `DimensionValue` covers numbers and
+    // percentages, and `max-content` is a real CSS width that react-native-web
+    // passes straight through. Nothing typed does this job — a number floor
+    // only moves the breaking point to the next longer label, and dropping to
+    // the track's own width is what breaks it in the first place.
+    ...({ width: "max-content" } as unknown as ViewStyle),
   },
   tickMark: {
     width: 1,

package/src/brand_mark.tsx

@@ -7,16 +7,7 @@ import { Svg, Path } from "react-native-svg";
  * email that is not tied to one provider. Inventing a mark for those is how a
  * byline ends up claiming a channel the record does not carry.
  */
-export const BRAND_NAMES = [
-  "facebook",
-  "zalo",
-  "linkedin",
-  "x",
-  "google-meet",
-  "gmail",
-  "outlook",
-  "google-drive",
-] as const;
+export const BRAND_NAMES = ["facebook", "zalo", "linkedin", "x", "google-meet"] as const;
 
 export type BrandName = (typeof BRAND_NAMES)[number];
 
@@ -37,6 +28,15 @@ interface Mark {
  * Path data is Simple Icons (CC0), so the geometry carries no licence of its
  * own; the marks themselves stay the trademarks of their owners and are used
  * here only to NAME the channel a touchpoint happened on.
+ *
+ * A product's OFFICIAL full-colour logo does not belong here, and the reason is
+ * not size — at 20px the real Gmail and Drive artwork reads perfectly well. It
+ * is provenance and shape: official artwork is the vendor's asset rather than
+ * CC0 geometry, and it is not uniformly inlinable — Gmail and Drive are flat
+ * multi-path files, Outlook is fourteen gradients across fifteen paths. A kit
+ * that carried two of them and gave up on the third would be the worst of both.
+ * Those live in the app's own image assets, and a row that wants one passes it
+ * in (`SwitchButton`'s `leading` slot).
  */
 const MARKS: Record<BrandName, Mark> = {
   facebook: {
@@ -63,29 +63,6 @@ const MARKS: Record<BrandName, Mark> = {
     color: "#00897B",
     path: "M5.53 2.13 0 7.75h5.53zm.398 0v5.62h7.608v3.65l5.47-4.45c-.014-1.22.031-2.25-.025-3.46-.148-1.09-1.287-1.47-2.236-1.36zM23.1 4.32c-.802.295-1.358.995-2.047 1.49-2.506 2.05-4.982 4.12-7.468 6.19 3.025 2.59 6.04 5.18 9.065 7.76 1.218.671 1.428-.814 1.328-1.64v-13a.828.828 0 0 0-.877-.825zM.038 8.15v7.7h5.53v-7.7zm13.577 8.1H6.008v5.62c3.864-.006 7.737.011 11.58-.009 1.02-.07 1.618-1.12 1.468-2.07v-2.51l-5.47-4.68v3.65zm-13.577 0c.02 1.44-.041 2.88.033 4.31.162.948 1.158 1.43 2.047 1.31h3.464v-5.62z",
   },
-  // The envelope silhouette, in Gmail's red. The full mark is five colours
-  // meeting along the flap's diagonals — at 16px those seams alias into a
-  // brown smear, which is precisely the case the note above is about.
-  gmail: {
-    color: "#EA4335",
-    path: "M24 5.457v13.909c0 .904-.732 1.636-1.636 1.636h-3.819V11.73L12 16.64l-6.545-4.91v9.273H1.636A1.636 1.636 0 0 1 0 19.366V5.457c0-2.023 2.309-3.178 3.927-1.964L5.455 4.64 12 9.548l6.545-4.909 1.528-1.146C21.69 2.28 24 3.434 24 5.457z",
-  },
-  // The bare "O" monogram — an oval ring, drawn as two subpaths of OPPOSITE
-  // winding so the nonzero fill leaves the counter open. Simple Icons' Outlook
-  // path is the envelope-and-O composite, and it was tried here first: at 20px
-  // it collapses into a blue rectangle with no readable feature, and it is not
-  // much better at 64. The O alone is what identifies the brand at a glance and
-  // it is the half that survives the size.
-  outlook: {
-    color: "#0078D4",
-    path: "M12 1.2a8.7 10.8 0 1 0 0 21.6 8.7 10.8 0 1 0 0-21.6ZM12 6.6a4.1 5.4 0 1 1 0 10.8 4.1 5.4 0 1 1 0-10.8Z",
-  },
-  // Drive's triangle, drawn as one silhouette. The three-colour original is the
-  // same aliasing problem as Gmail's, and worse — its colours meet at a point.
-  "google-drive": {
-    color: "#1FA463",
-    path: "M12.01 1.485c-2.082 0-3.754.02-3.743.047.011.024 1.708 3.001 3.774 6.62l3.76 6.574h7.46c.001-.02-1.696-2.998-3.762-6.618l-3.76-6.623zm-4.28.939a5.482 5.482 0 0 0-.309.443L3.71 9.17 0 15.647l1.863 3.209a338.99 338.99 0 0 0 1.914 3.28c.04.045 7.55-13.116 7.55-13.234 0-.045-1.487-2.652-3.305-5.793zM9.97 15.463c-.639 1.099-1.943 3.361-2.9 5.03l-1.737 3.021h15.09c0-.019.848-1.484 1.884-3.259l1.882-3.222H9.97z",
-  },
 };
 
 export interface BrandMarkProps {
@@ -112,7 +89,13 @@ export interface BrandMarkProps {
  */
 export function BrandMark(props: BrandMarkProps) {
   const { name, size = 16, muted, testID } = props;
-  const mark = MARKS[name];
+  // A name outside the allowlist does not typecheck, so reaching here means a
+  // deployed app compiled against an older kit that still had the name. Render
+  // nothing rather than dereferencing undefined: a mark is decoration beside a
+  // label that already names the channel, and throwing takes the whole render
+  // tree of an app that is otherwise fine.
+  const mark = MARKS[name] as Mark | undefined;
+  if (!mark) return null;
   return (
     <Svg width={size} height={size} viewBox="0 0 24 24" testID={testID}>
       <Path d={mark.path} fill={muted ? "currentColor" : mark.color} />

package/src/chip_group.tsx

@@ -4,9 +4,11 @@ import { PressableHighlight } from "./pressable_highlight";
 import { chipSurfaceStyle } from "./control_surface";
 
 // One-of-N chips: every option visible, one tap to switch, the row wraps on
-// narrow widths. Quiet zinc styling — bordered white at rest, dark fill when
-// active (color stays reserved for status + primary actions). Two jobs, one
-// control:
+// narrow widths. Quiet zinc styling — bordered white at rest, and the active one
+// keeps that same ground and takes a doubled zinc-900 EDGE instead, so a
+// selection never spends the brand and never speaks the row's language (the
+// reasoning is on `chipSurfaceStyle`). Colour stays reserved for status +
+// primary actions. Two jobs, one control:
 //   - a SMALL, HOT FILTER the user flips between constantly ("narrow this
 //     view") — model the unfiltered state as an explicit option (e.g. "All").
 //   - a small REQUIRED single-select in a form / composer (a call outcome, a

package/src/finding.tsx

@@ -142,7 +142,7 @@ export function Finding(props: FindingProps) {
             {readings.map((reading, index) => (
               <View key={`${reading.source}-${index}`} style={styles.reading}>
                 <SourceName label={reading.source} onOpen={props.onOpenSource} />
-                <Text size="sm" weight="medium" tabular numberOfLines={1}>
+                <Text size="sm" weight="medium" tabular numberOfLines={1} style={styles.readingValue}>
                   {reading.value}
                 </Text>
               </View>
@@ -181,13 +181,18 @@ export function Finding(props: FindingProps) {
 function SourceName({ label, onOpen }: { label: string; onOpen?: (source: string) => void }) {
   if (!onOpen) {
     return (
-      <Text size="sm" color="muted" numberOfLines={1}>
+      <Text size="sm" color="muted" numberOfLines={1} style={styles.sourceName}>
         {label}
       </Text>
     );
   }
   return (
-    <PressableHighlight onPress={() => onOpen(label)} accessibilityRole="link" accessibilityLabel={label}>
+    <PressableHighlight
+      onPress={() => onOpen(label)}
+      accessibilityRole="link"
+      accessibilityLabel={label}
+      style={styles.sourceName}
+    >
       <Text size="sm" weight="medium" decoration="underline" numberOfLines={1}>
         {label}
       </Text>
@@ -217,4 +222,14 @@ const styles = StyleSheet.create({
   // each source with its own value at every width and needs no separator at all.
   readings: { flexDirection: "column", alignItems: "flex-start", gap: 4 },
   reading: { flexDirection: "row", alignItems: "baseline", gap: 5, minWidth: 0 },
+  // The same split as `title`/`delta` one row up, for the same reason: the SOURCE
+  // is a label and gives way, the VALUE is the figure and never does. Both halves
+  // are required on the label — a React Native `Text` is `flexShrink: 0` unlike
+  // the web, and `flexShrink` alone then floors it at its longest word. Without
+  // this pair the row laid both children out at intrinsic width and simply ran
+  // off the card: measured at x=790 in a 390px frame, clipped, with no page
+  // scroll to reach it — so on a phone the evidence a Finding exists to show was
+  // the part you could not read.
+  sourceName: { flexShrink: 1, minWidth: 0 },
+  readingValue: { flexShrink: 0 },
 });