@oxy.so/bloom 4.0.0 → 4.2.0

package/docs/carrier-quote.mdx

@@ -0,0 +1,121 @@
+---
+title: Carrier quote
+description: A carrier's offer on a job, and the offers together — the identity, the price, the window and the ETA, the cheapest and fastest marks, and the empty and loading states of a list that is still filling up.
+order: 135
+---
+
+# Carrier quote
+
+```tsx
+import { CarrierQuoteCard, CarrierQuoteList } from '@oxy.so/bloom/carrier-quote';
+
+<CarrierQuoteList
+  quotes={quotes}
+  selectedId={accepted}
+  onAccept={accept}
+  onMessage={openThread}
+  onDecline={decline}
+/>
+```
+
+## The card is a record of a person
+
+An offer is a **person with a number attached**, so the card is drawn in the
+register Bloom draws a person in — the same blocks in the same order as a contact
+record, with the price where a record puts its headline figure:
+
+```
+mark      the 48 avatar
+identity  the name at title-3-semibold with the verified glyph, then ONE meta
+          line: the list's marks, the rating, the jobs done, the trade line
+headline  the price at title-1-medium in tabular figures, right-aligned
+tiles     pick-up, arrival, vehicle — value over label, on the next fill up
+message   what the carrier wrote, three lines then truncated
+price     the itemisation, collapsed, through PriceSummary
+footer    decline · message · accept, over a hairline
+```
+
+`density="compact"` is a **list row**, not a card with the padding taken out: 64
+tall, a 36 mark, the name, one meta line, the price at the end, and no tiles or
+breakdown at all — a list that draws a card per row has stopped being a list.
+
+**The marks sit on the meta line, never beside the name.** A pill states a fact
+in one word and must not shrink; the name beside it is what gives way, and at 390
+that left `Maris…` next to a full-width `Cheapest`.
+
+### The card is not one big button
+
+`onPressCarrier` is bound to the **identity block**; the three actions sit outside
+it. A control inside a control is invalid on web and ambiguous everywhere, and it
+renders perfectly well either way, which is why it needs saying.
+
+### The actions never lose their names
+
+Each action is a `Button`. Under 420 of the card's **own** width they drop to
+`iconOnly`, and each one is named `"<action> <carrier>"` whichever way it is
+drawn — losing the label must not lose the name. The same measurement stacks the
+tiles two by two, because a card too narrow for three tiles is too narrow for
+three labelled buttons beside a 48 mark.
+
+## The marks belong to the SET
+
+`cheapest` and `fastest` are statements about a group of offers. A card handed
+one out of context is claiming something it cannot know, so it does not derive
+them: `CarrierQuoteList` computes them with `markCarrierQuotes` and passes them
+down.
+
+They are derived from `priceValue` and `etaMinutes` — **numbers the app supplies
+for comparison and this family never draws.** Money arrives here as a
+pre-formatted string (`price`, `priceNote`, every `priceLines` amount) and
+nothing in this family parses, sums, converts or rounds it; the numeric fields
+exist only so the list can ask which of two is smaller.
+
+**Every offer tied at a minimum is marked.** Two offers at the same price are
+both the cheapest; picking one of them would be this component inventing a
+tie-break the app never asked for, and marking neither would hide a true
+statement.
+
+**A quote with no number cannot be marked, and sorts last.** Within that group
+the caller's own order is kept — there is nothing left to sort on, and
+re-shuffling a group of equals makes a list jump for no visible reason.
+`sortCarrierQuotes` is stable for the same reason.
+
+`rating` sorts high-first; price and ETA sort low-first. That is the only place
+the direction differs, and it is a property of what the number means.
+
+## The list's two non-list states
+
+- **loading** draws placeholder cards of the same height, inside an
+  `aria-busy` group. Not a spinner: the answer arriving is a list, and a list is
+  what should be reserved for it.
+- **empty** draws a tinted glyph disc over one line of explanation and the
+  caller's own action. An empty offers list is a **wait**, not a failure, so the
+  default copy says what happens next rather than what went wrong. Pass
+  `emptyTitle` / `emptyDescription` when it is a failure.
+
+## Traps
+
+- **There is no head until there is a list.** "0 offers" over a control that can
+  reorder nothing is chrome for a list that does not exist yet, and the empty
+  state already says the same thing in words a reader can act on.
+- **`quotes.length` is the count, not `ordered.length`.** The heading counts what
+  the caller has, which is the same number either way today — but it is the
+  caller's set that a "3 offers" line is about.
+- **The sort is uncontrolled by default.** Pass `sort` + `onSortChange` to own
+  it; `sortOptions={[]}` draws no control at all, which is right for a list of
+  two.
+- **`selected` moves a pixel of border and gives it back.** The chosen card takes
+  a 2px accent border and drops its own inset by one, so nothing inside it moves
+  when it is chosen.
+- **`vehicleIcon` has no default.** A marketplace routing five bodies has five
+  glyphs, and Bloom's icon set has no generic one that is honest about all of
+  them, so a caller that names none gets no glyph rather than the wrong vehicle.
+- **A tile the quote does not answer is not drawn.** A tile holding an em dash is
+  a slot that failed to load.
+
+## Tracking is not here
+
+Once an offer is accepted the job is tracked with
+[`order-status`](/docs/order-status) — `OrderStatusBar` for the live line and
+`OrderStatusTimeline` for what has happened. This family draws no timeline; the
+`EndToEnd` story shows the three families in one screen.

package/docs/cart-panel.mdx

@@ -0,0 +1,76 @@
+---
+title: Cart Panel
+description: The basket — the vendor it belongs to, lines with their options and a stepper, a minimum-order warning, a tip picker, a promo code field, and the totals drawn by price-breakdown.
+order: 136
+---
+
+# Cart Panel
+
+`@oxy.so/bloom/cart-panel`
+
+What is in the basket, and what it costs.
+
+```tsx
+import { CartPanel } from '@oxy.so/bloom/cart-panel';
+
+<CartPanel
+  vendorName="Fig & Ember"
+  vendorPhoto="fig-ember-cover"
+  vendorMeta="25–35 min · €1.90 delivery"
+  lines={lines}
+  onLineQuantityChange={setQuantity}
+  onLineRemove={remove}
+  tip={{ options: TIPS, value: tip, onValueChange: setTip }}
+  promo={{ value: code, onChangeText: setCode, onApply: apply, applied }}
+  summary={{ lines: priceLines, total: { label: 'Total', amount: '€52.00' } }}
+  onCheckout={checkout}
+/>
+```
+
+The family also publishes its parts — `CartLine`, `CartTipPicker`, `CartPromoField` — for a screen that arranges them itself.
+
+## It is content, not a surface
+
+Inline in a desktop sidebar it is dropped in a `Card`; on a phone it is what a `BottomSheet` holds. It paints no background of its own and claims no edge, so the same tree works in both. Every colour it *does* paint is read **relative to whatever it was dropped on** (`styles/surface-levels.ts`): a hairline picked for a card disappears on a sheet, and a panel that hardcoded one would be right in exactly one of the two places it ships.
+
+## There is one breakdown, and it is `PriceSummary`
+
+`summary` is handed straight to `price-breakdown`'s `PriceSummary`: subtotal, delivery, service, discount, tip and total are `PriceLine`s the app formatted. Nothing in this family adds anything up — the minimum-order `message` is a sentence the app wrote, not a subtraction performed here.
+
+**A note on the duplicate that exists.** `booking/PriceBreakdown` and `price-breakdown/PriceSummary` are the same idea in two spellings: rows with a label and a right-aligned tabular amount, a discount tone, a hairline, a bold total, and no arithmetic in either. `PriceSummary` is the later and larger one — it has the estimated/pending states, the per-line info popover, the collapsible disclosure and the surface-relative paint — so it is the one this family composes, and `booking`'s is the one to fold in. A third was never an option.
+
+## A basket belongs to one vendor
+
+Which is why the vendor is a header and not a field on every line. Switching vendor is a different action — it empties the basket — and this component does not offer it.
+
+## The stepper does not remove
+
+`CartLine`'s stepper has a floor of **1**, and removing is its own control with its own accessible name. A stepper that deletes the line when you press `−` once too often is a destructive action hiding behind an arithmetic one, and it has no label saying so.
+
+The line is never pressable, which is what lets its controls live inside it: a pressable `Item` is a real `<button>` on web, and a control inside one is invalid HTML whose click also fires the row. Editing a line's options is `MenuItemOptions` in a sheet, opened from the dish rather than from a row that is mostly controls.
+
+## The promo field has two states, not one
+
+While `applied` is set the input is **replaced** by a removable pill. A field still holding a code that has already been accepted invites a reader to press Apply again and wonder why nothing happened. Apply is disabled while the field is blank — an action that can only fail teaches a reader to distrust it — and whether a code is *valid* is the app's to say, which it says by handing back `error` or `applied`.
+
+Both states are a `Field`, so the rejection message is wired to the input through `aria-describedby` and the group paints invalid, rather than a red line sitting nearby with no association.
+
+## The tip is a `SegmentedControl`
+
+`type="radio"`, at the `large` rung — which is 44 tall, the floor a touch target has. It is already a `radiogroup` of `radio`s that reads a `Field`, slides its thumb and carries one focus ring; a row of pills would be a second grouped-choice control with the same meaning, and the one thing it could not do is announce "2 of 4".
+
+Every amount is a label the app formatted. A percentage and a fixed amount are the same thing here, and "No tip" is an option like any other rather than a state this component invents.
+
+## The shortfall sits above the totals
+
+Not at the top. Read before there is a total to compare it to, "€4.50 more to reach the €14 minimum" is a sentence about nothing; beside the number it is about, it is the reason checkout is blocked. It is an `Admonition` in the warning tone, with an optional `Meter` under it — never a bar drawn by hand.
+
+## Order tracking is not here
+
+Once the order is placed it belongs to `order-status`: `OrderStatusTimeline` for the steps and `OrderStatusBar` for the live line with its ETA. This family draws no second timeline, and the courier's own card is not one of its components — the `AfterCheckout` story composes one from `Avatar` and `Card` to show the seam.
+
+## Traps
+
+- **Every amount is a string.** `price` on a line is the line's own total, already multiplied by `quantity` **by the app**. Nothing here multiplies, converts or rounds.
+- **The empty basket hides everything after the lines.** No tip picker, no promo field, no totals and no checkout button — each of them would be a control acting on nothing.
+- **`CartLine` takes the line's fields, not the entry.** `CartLineEntry` carries the `id` the panel keys and reports by; the standalone component takes the rest, so a caller cannot pass an id that reaches nothing.

package/docs/chat-people.mdx

@@ -47,6 +47,7 @@ with `onSelectedChange`, an action button with `onAction`, nothing otherwise.
 | `subtitle`              | the quiet second line — a handle, a last-seen string      |
 | `actionDone`            | swaps the button for a quiet "Added" mark                 |
 | `size`                  | `'medium'` 44px avatar (default), `'small'` 36 for a picker |
+| `horizontalInset`       | Avatar/text inset, default `10`. Use `0` when the surrounding widget already provides its inset. |
 
 ### Selection is ONE target
 
@@ -275,3 +276,21 @@ and its refusal to jump to an absent letter, the role badges, and both pure
 functions. It cannot see whether the sticky headings actually stick, whether the
 rail is reachable with a thumb, or whether the story chrome stays legible over a
 bright photo. Those are browser and device checks.
+
+
+### Application identity in ContactRow
+
+`avatarSlot` replaces `AvatarPresence`; `identitySlot` replaces the visible name/subtitle block. Both accept React nodes, including `null` to intentionally omit that content. The row retains its flexible identity column, trailing action and selection behavior. Provide an appropriately sized avatar; the defaults are36px for `small` and44px for `medium`.
+
+```tsx
+<ContactRow
+  id={user.id}
+  name={user.displayName}
+  subtitle={user.handle}
+  avatarSlot={<VerifiedAvatar user={user} />}
+  identitySlot={<UserName user={user} showFederation />}
+  onPress={openProfile}
+/>
+```
+
+`VerifiedAvatar` and `UserName` are application components. Keep `name` as plain text: it still supplies the accessible name for selection and action buttons; pressable rows also include `subtitle`. Slots preserve application verification, federation and placeholder logic without duplicating those policies inside Bloom. Keep slot content non-interactive when the row itself is an interactive target.

package/docs/checkout-summary.mdx

@@ -0,0 +1,90 @@
+---
+title: Checkout summary
+description: Review and confirm — the rows a buyer checks before paying, each showing its chosen value and opening the thing that changes it, the totals from price-breakdown, and one confirm control that cannot place two orders.
+order: 137
+---
+
+# Checkout summary
+
+Between "I want this" and "it is ordered" there is one screen: where it goes, when, how
+it is paid, what it costs, and the note to the seller. This family is that screen's body.
+
+```tsx
+import { CheckoutSummary } from '@oxy.so/bloom/checkout-summary';
+
+<CheckoutSummary
+  address={{ title: 'Home', subtitle: 'Carrer de l’Om 14, 2nd floor', kind: 'saved', onPress: pickAddress }}
+  delivery={{ label: 'Delivery window', value: 'Friday 24, 17:00 – 19:00', onPress: pickWindow }}
+  payment={<PaymentMethodRow onPress={pickCard} />}
+  note={{ label: 'Note for the shop', placeholder: 'Add a note', onPress: editNote }}
+  price={{ lines, total: { label: 'Total', amount: '€49.62' } }}
+  confirm={{ amount: '€49.62', terms: 'By placing this order you agree to the shop’s terms.', busy, onConfirm: place }}
+/>;
+```
+
+## The row is the summary AND the trigger
+
+A label with a "Change" button beside it is two targets for one decision, and two screen
+reader stops that do not mention each other. Here the whole row is the button: its name is
+`"<label>: <value>"`, its hint is what pressing it opens, and the chevron is decoration.
+A row with no `onPress` draws no chevron and is a static receipt line — which is what the
+same component is after the order is placed.
+
+**Known gap: the hint is NATIVE ONLY.** react-native-web has no `accessibilityHint` — not
+a wrong mapping, no mapping at all — so on web the affordance is the `button` role and the
+chevron, and the row says nothing about what pressing it opens. It is pinned in the suite
+rather than hidden, and it is not swapped for an `aria-describedby` because native would
+then announce the same sentence twice.
+
+The row reads label-first and value-below (`caption-2-bold` uppercase over `body-medium`),
+which is the other way round from `SettingsListItem`'s title-with-a-value-on-the-right.
+The difference is length: a settings value is a word, and a checkout value is an address,
+a two-hour window and a masked card number — none of which fits in the right half of a
+390 row without truncating the thing the reader came to check.
+
+## What this family does not own
+
+- **The totals are `price-breakdown`'s `PriceSummary`**, passed straight through as
+  `price`. There is no second breakdown here and no arithmetic anywhere: every amount is
+  a string the app formatted, including the one on the confirm button.
+- **The address row is `address`'s `AddressRow`.** It goes inside the summary row's value
+  column with `leading={null}` — the row already drew the gutter, which is the case
+  `AddressRow` documents — and with `Item`'s padding reset in the LONGHANDS `Item` itself
+  writes, so there is one row's chrome rather than two. (Overriding `paddingVertical`
+  with `paddingTop`/`paddingBottom` would have worked on native and been silently
+  dropped on web, where the atomic sheet ranks the shorthand higher whatever the array's
+  order.)
+- **`payment` is a SLOT**, not data. The payment-method row is its own family; a
+  placeholder drawn here would be a second spelling of it. An app that has no such family
+  yet renders a `CheckoutSummaryRow` in the same register, which is what the stories do.
+- **Tracking, afterwards, is `order-status`**, and the screen that says it worked is
+  `order-confirmation`.
+
+## The group publishes its surface
+
+The rows sit in a group one rung above whatever the summary was dropped on, and that rung
+is PUBLISHED with `SurfaceLevelProvider`. Without it every row's glyph tile resolves one
+step off the PAGE rather than one step off the group, and the tiles disappear into the
+group on exactly the surfaces where a summary is most often put — a sheet, a panel, a
+card.
+
+## Two guards against a double order
+
+`busy` is the app's: while the order is in flight the button spins, is renamed to
+`busyLabel`, and drops every press. That is not enough on its own. A press calls
+`onConfirm`, the app sets its state, and `busy` only arrives on the NEXT commit — the
+second tap of a double-tap lands inside that window and places a second order. So
+`CheckoutConfirm` also latches on its own press, synchronously, in a ref: React state
+would not do, because two presses in one tick read the same render's value.
+
+The latch clears on the first commit where `busy` is false again. An app that never sets
+`busy` — a confirm that navigates away, a story — therefore gets exactly one press per
+tick and is never wedged; an app that does sets the button inert for the whole flight.
+
+## The amount is on the button
+
+The number a press commits to and the press are one decision. A total elsewhere on the
+screen and a button reading "Place order" are two, and the gap between them is where a
+reader confirms a figure they last saw before a tip picker changed it. The separator is a
+middle dot: "Place order - €49.62" reads as a subtraction at a glance in a row that is
+otherwise full of money.

package/docs/content-panel.mdx

@@ -223,3 +223,29 @@ They are both surfaces. A card filling a framed panel is two borders with a few
 pixels between them. Use the panel's frame, and reach for
 [`Card`](/docs/bloom/main/card) for things *within* the column that are
 genuinely separate objects.
+
+
+## Shared document insets
+
+The viewport mask covers the complete `overlayInset`, including asymmetric top
+and bottom values. A 1 CSS pixel horizontal overlap covers device-pixel rounding:
+at 125% display scaling, a flush clip left a bright physical-pixel seam at the
+right edge. `scripts/verify-content-panel-pixel-seam.mjs` probes both edges in
+light/dark at 100%, 125%, 150% and 200% scaling and even/odd viewport widths. The former
+12px horizontal halo painted over 5px of the adjacent 50px sidebar Fab when
+`navigationGap={0}`: the Fab’s measured bounds were correct, but its right edge
+was hidden under the mask. `scripts/verify-sidebar-fab-visibility.mjs` checks
+both painted edges in light/dark mode before and after document scroll. The previous fixed 12px vertical clip exposed a 4px strip of scrolling
+content with a 16px gutter; increasing only the shadow could not repair that clip.
+
+`ContentPanel` also publishes its framed top edge through
+`--bloom-panel-sticky-top`. `PageHeader` inherits that sticky position rather than
+pinning behind the mask at viewport zero. Below `framedFrom`, for `framed={false}`,
+and in panel-sized overlays, this inset is zero. The responsive decision stays
+in CSS, matching the panel’s existing breakpoints.
+
+Run `scripts/verify-content-panel-mask.mjs` against Storybook to measure painted
+top/bottom gutter pixels and header bounds in both modes, at 8/16/40/72px insets
+and multiple scroll positions. `scripts/verify-storybook-document-scroll.mjs`
+checks real wheel gestures over each column, sticky navigation and reachable
+last content without nested vertical scroll containers.

package/docs/delivery-slot.mdx

@@ -0,0 +1,91 @@
+---
+title: Delivery slot
+description: When — the days across the top, the windows of the chosen day with their surcharge, capacity and tier, the sold-out ones, and the ASAP option that belongs to no day. A radio group through Field, not pressables that look selected.
+order: 138
+---
+
+# Delivery slot
+
+```tsx
+import { DeliverySlotPicker } from '@oxy.so/bloom/delivery-slot';
+
+<DeliverySlotPicker
+  days={days}
+  day={day}
+  onDayChange={(id) => { setDay(id); loadWindows(id); }}
+  windows={windows}
+  value={slot}
+  onValueChange={setSlot}
+  asap={{ id: 'asap', eta: '25 – 40 min', price: '+€4.90' }}
+  error={touched && !slot ? 'Pick a delivery window to continue.' : null}
+/>;
+```
+
+## It is a selection, so it is a radio group
+
+Not a set of pressables that happen to look selected. The difference is what a screen
+reader says: a `radiogroup` announces the name of the choice and "3 of 7", and each row
+announces whether it is the chosen one. Seven pressables announce seven unrelated buttons,
+one of which is drawn differently — which is exactly as usable as it sounds, and looks
+identical.
+
+There are TWO groups, because there are two choices: the DAYS (which day's windows are
+listed) and the WINDOWS. One group a reader has to infer the halves of would be worse than
+either.
+
+Each option is `Item` with `role="radio"` — the press target, the hover and press paint,
+the disabled opacity and the `aria-checked` that ARIA scopes to that role are all `Item`'s.
+A sold-out window is `disabled`, so it announces as unavailable rather than merely being
+drawn pale.
+
+## The field, and the one clever bit
+
+Standalone, the picker IS a `Field` (`multiple`): one `label` names the choice, one
+`error` puts it in its invalid state, one `description` explains it, and one `disabled`
+reaches the strip and every option and cannot be opted out of from inside.
+
+Dropped inside somebody else's `Field`, it renders no second one — two fields means two
+labels above one control and an error the outer field describes and the inner one does
+not. It reads the enclosing field's context instead, through `useFieldMembership()`, which
+is why `label` is deliberately UNDEFAULTED: a default here would outrank the one string
+the user can actually read.
+
+## The parts are the library's
+
+- The day tile is `SelectChip shape="day"` — the same 56-wide, radius-12, weekday-over-date
+  tile Bloom already draws for scheduling a viewing. A day picked out of a strip is one
+  thing, not one per app.
+- The strip is `ChipRow`, which supplies the sideways scroll, the fade at whichever edge
+  has more behind it, and the room a focus ring needs so the outline is not clipped by its
+  own scroller. **The fade resolves into the surface BEHIND the row**, which the row
+  cannot know: on a card, pass `fadeColor`.
+- The dot is `RadioIndicator` at 20 — `Radio`'s `lg` rung, because the row it marks is two
+  lines tall and the 16 `md` dot read as a bullet beside it rather than as the control.
+- The empty day is `EmptyState` at the panel rung.
+
+## Capacity is a string, and sold out says only that
+
+`capacity` is `"2 left"` or `"Almost full"` or `"Last one"` — a string, because those are
+the same fact said three ways and only the app knows which one its couriers mean.
+
+A SOLD-OUT window's detail line says "Sold out" and nothing else. The tier and the
+capacity of a window nobody can take are facts about a thing that is not on offer, and
+reading them out after "Sold out" is how a reader ends up tapping it.
+
+## ASAP is at the head of the options, not beside them
+
+It belongs to no day, so it stays where it is while the days change — but it is in the
+SAME radio group as the windows, because it is the same choice. A button labelled "ASAP"
+next to a group of windows is how a reader ends up with both chosen, or neither.
+
+## Loading is not empty
+
+The windows are RELOADED when the day changes. Pass `loading` during that reload: an empty
+list drawn in the gap reads as "nothing left on this day", which is a different and wrong
+answer. The placeholder rows are announced `aria-busy`, so a reader is told to wait rather
+than told nothing.
+
+## It computes nothing
+
+Every window, every price, every reading is a string the app formatted. The only ordering
+this family does is the order it was handed.

package/docs/directions.mdx

@@ -0,0 +1,109 @@
+---
+title: Directions
+description: Getting there — the chosen route as a figure with its alternates, the turn list grouped by leg with a maneuver glyph and a current step, and a transit line's own badge.
+order: 135
+---
+
+# Directions
+
+```tsx
+import { DirectionsSummary, DirectionsSteps } from '@oxy.so/bloom/directions';
+
+<DirectionsSummary
+  routes={routes}
+  selectedRouteId={chosen}
+  onSelectRoute={setChosen}
+  stops={stops}
+  onSwapStops={swap}
+  modes={['drive', 'transit', 'walk', 'cycle']}
+  mode={mode}
+  onModeChange={setMode}
+  onStart={navigate}
+/>
+<DirectionsSteps legs={legs} currentStepId={current} />
+```
+
+## What this family does NOT draw
+
+- **The origin and the destination.** They are [`RouteStops`](/docs/route-stops), which
+  already owns the marker column, the connector, the swap and the reached/current/pending
+  states. `DirectionsSummary` renders it from `stops` and draws no second header. Without
+  `stops` it draws no header at all, for an app whose screen already shows them.
+- **The mode switcher.** A switcher of views is `SegmentedControl`. The four modes are
+  data (`DIRECTIONS_MODE_LABELS`, `DIRECTIONS_MODE_ICON`), not four components.
+- **A row.** Every route alternate and every turn step is an
+  [`AddressRow`](/docs/address) — the row, the glyph tile, the press target, the density
+  rungs, the trailing `meta` and the disabled opacity are `Item`'s, through it. This
+  family adds a glyph table and the words.
+- **A map.** There is no engine, no projection and no tile here.
+
+## The duration is the figure
+
+Nobody leaves the house because a place is 8.2 km away. `DirectionsSummary` leads with the
+DURATION at `title-1`, tabular, under a quiet label — the figure block
+[`ai-profile-card`](/docs/ai-profile-card) uses — with the distance as a `Chip` and the
+traffic as a `Badge` on its tone beside it. The arrival time and the via line follow as two
+quiet readings, each a 16 glyph and a line of secondary text.
+
+`traffic: 'light'` is `success`, not `default`. A clear road is good news and the reader is
+scanning for it; a neutral pill beside a red one reads as "no information" rather than as
+"clear".
+
+## The chosen route is not in the alternates
+
+It is drawn in full above them, and a route shown twice is a reader wondering whether they
+are two. That is also why the alternates are a `list` of pressable rows and not a
+`radiogroup`: a radio group whose checked member is missing announces a choice with nothing
+chosen. A press on a row CHOOSES it, which swaps it into the figure.
+
+## The maneuver glyphs, and the two that are mirrored
+
+A maneuver set is symmetric — a right turn IS a left turn seen from the other side — and
+Bloom's icon set carries one side of each pair. `right` is `RiCornerUpLeftLine` mirrored
+about its own centre (`scaleX: -1`), and `slight-left` is `RiArrowRightUpLine` mirrored.
+
+**Mirroring is the correct answer here, not a shortcut.** The alternative is picking a
+different glyph that happens to point the right way, and it does not share the partner's
+stroke weight, arrowhead or corner radius — the pair then reads as coming from two icon
+sets. A mirror moves nothing and needs no offset.
+
+Each mirrored component is built ONCE at module scope. Built inside a render it would be a
+new component type on every frame, and React would unmount and remount the SVG each time.
+
+The table is `DIRECTIONS_MANEUVER_ICON`; the words are `DIRECTIONS_MANEUVER_LABELS`, and
+they are announced BEFORE the instruction because a glyph says nothing aloud. That is the
+same hole `RouteStops` fills for its marker shapes.
+
+## The current step
+
+It wears the accent's own `subtle` wash, painted through the row's `style` — **not through
+`selected`**. `Item` maps `selected` on a row with no role to `aria-pressed`, and a turn
+instruction is not a toggle: a screen reader would announce every step as "not pressed".
+
+The state a step carries is "this is where you are", which ARIA has no attribute for on a
+list row, so it travels in the NAME instead (`currentLabel`, default "Current step"),
+where it is certain to be heard.
+
+## Where a step's name goes
+
+Exactly as in `RouteStops`, and for the same reason: a pressable step is a button and
+carries its own name; a read-only one renders `role="none"`, which assistive technology is
+told to ignore, so the name goes on the `listitem` around it. Naming both would read every
+step twice.
+
+## Transit
+
+A leg header carries its mode glyph, its title at the section rung, its line badge and its
+reading. `TransitLineBadge` is Bloom's `Badge` with two colours overridden and nothing
+else — the same construction `listing-card`'s status pill uses, because an operator's line
+colour is DATA the app owns and only the fill and the label may come from outside the
+palette.
+
+**The label is measured, not derived.** `readableOn` picks whichever end of the theme's own
+reading pair clears more contrast against the operator's fill, in both modes — a derived
+label (lighten the fill until it clears AA) invents a colour that is in no palette, and on
+a saturated operator red it lands on pink. A line with no colour is the plain neutral
+badge, which is the right answer for an operator that publishes none.
+
+The badge shows two characters and says a sentence: `describeTransitLine` gives it
+"Line L4, towards Pla del Bosc".

package/docs/earnings.mdx

@@ -0,0 +1,87 @@
+---
+title: Earnings
+description: What the work paid — the period's figure and its bars through the earnings chart card, the readings under it, the breakdown by kind, and the next payout with its date and state.
+order: 138
+---
+
+# Earnings
+
+```tsx
+import { EarningsSummary } from '@oxy.so/bloom/earnings';
+
+<EarningsSummary periods={[day, week, month]} defaultPeriod="week" formatAxisValue={euros} />
+```
+
+`EarningsSummary` is the whole panel. `EarningsBreakdown` and `EarningsPayoutRow` are two of its four parts, published because a screen often wants one of them alone.
+
+## It is built AROUND the chart card, not beside it
+
+`chart-cards`' `EarningsChartCard` is already four of the five things a courier's earnings screen needs: the period's figure, the change on the period before, the Day / Week / Month switch and the bars of the last weeks. Drawing a second figure and a second switch above it would have put two of everything on one panel and left the reader to work out which one was authoritative.
+
+So this family draws none of that. It hands the chart card the selected period's data and adds the three things the chart card has no opinion about:
+
+```
+EarningsChartCard    the switch, the figure, the delta chip, the bars
+tiles                the period's other readings
+EarningsBreakdown    where the money came from
+EarningsPayoutRow    when it reaches the bank
+```
+
+The tiles are `ai-profile-card`'s stat tile exactly — radius 10, padding 10, the reading over its label, one row from 640 and two columns below. A courier's "68 jobs done" and a profile's "9B lifetime tokens" are the same object, and a second tile geometry would be a second answer to one question.
+
+The breakdown is `price-breakdown`'s `PriceSummary` under a heading, for the same reason. A courier's earnings are an ITEMISATION — jobs, tips, bonuses, adjustments, each a label and an amount the app formatted — which is a fare's itemisation seen from the other side. Writing a second list of label-and-amount rows here would give Bloom two of those, and only one of them would know about `estimated`, `pending`, the discount tone and the info popover.
+
+## No total under the breakdown
+
+Inside `EarningsSummary` the figure above the chart already IS the total, so `EarningsBreakdown` is given no `total` and draws the kinds with no rule. Pass `total` when you use the breakdown on its own.
+
+## The money is never computed, and the headline is the proof
+
+A bar carries BOTH a number and an amount, and they are not the same fact:
+
+```tsx
+{ label: 'Fri', value: 132.4, amount: '€132.40' }
+```
+
+`value` is GEOMETRY — how tall the bar is — and is never drawn. `amount` is what the reader sees.
+
+`EarningsChartCard` formats its headline from a number, which is exactly what this family must not do. So the headline is CHOSEN rather than produced: the panel owns the chart's active bar, and `format` returns the period's own `total` at rest and the hovered bar's own `amount` over a bar. `earningsHeadline` is that choice, and it is a pure function so its boundaries — no bars, an index past the end, an index that outlived its data — are reachable by a test.
+
+Two consequences, both deliberate:
+
+- **The headline does not roll.** `ChartHeadline` counts a number up over 320ms; a pre-formatted amount has nothing to count. The 220ms fade still plays, so the change is still visible.
+- **The Y axis prints a number.** A tick is a position on a scale the chart chose, not a sum the app made, so no string exists for it to have formatted. The default prints the rounded number with nobody's currency on it; **`formatAxisValue` is where an app puts its own**, and an app that forgets it gets a bare axis rather than a wrong currency.
+
+## What jest cannot see, and where it is checked instead
+
+`earningsHeadline` is pure, so the CHOICE is pinned in `src/__tests__/Earnings.test.tsx` at every boundary. The other half — that the panel actually owns the chart's active bar and re-reads the headline from it — is driven by pointer events on a plot surface that only exists after `onLayout`, and jsdom fires no layout. Measured: gutting `setActiveIndex` to a no-op left that whole suite green.
+
+So it is `scripts/verify-earnings-headline.mjs`: a real Chrome, `page.mouse.move` over three bars of different value, reading the emitted headline. It also runs the case the pure test cannot reach — that no reading is ever the raw number the bar was SIZED by, which is what a `format` falling back to its argument would produce and what would still look plausible on screen. The axis words are checked the same way, and for the same reason.
+
+## The period is controlled here, and the chart is remounted to follow it
+
+`useChartRange` inside `chart-cards` is uncontrolled: it takes a `defaultRange` and there is no `range`. A period changed from outside the panel therefore cannot reach the chart card's own segmented control, and the switch and the panel would disagree with nothing to say so.
+
+The chart is keyed on the period id, which remounts it with the new default. The cost is that the bars grow in again instead of morphing across the switch. **This is a gap in `chart-cards`, recorded rather than worked around silently** — the fix is a controlled `range` prop on `useChartRange`, and it is not made here.
+
+## Payout states
+
+Five, because "not in the account yet" is four different situations and a courier acts differently on each.
+
+| state | tone | means |
+| --- | --- | --- |
+| `scheduled` | default | waiting; nothing to do |
+| `processing` | info | already moving; nothing to do |
+| `paid` | success | done |
+| `held` | warning | the reader has to do something, and the money is still coming |
+| `failed` | error | the reader has to fix something |
+
+**The state is said in words, not only in colour.** The badge carries the word and the tone is a second channel on top of it. `note` is drawn only for `held` and `failed` — a sentence on a scheduled payout is one nobody has to read.
+
+The row is an `item`, not a card: `item` already owns the press target, the density, the slots and the disabled wash, and what this component decides is what goes in them.
+
+## Traps
+
+- **A period carries everything it says.** `total`, `bars`, `lines`, `stats` and `payout` are all the period's own, so switching the segment replaces the whole panel. A payout that does not change with the period is written once, at the panel level.
+- **`deltaRatio` is a RATIO, not money.** `0.148` is up 14.8%. A percentage is not somebody's currency, so it is the one number here that is allowed to be formatted downstream.
+- **A period id that names nothing falls back to the FIRST period**, never to nothing. An empty figure reads as "you earned nothing" rather than as "this app asked for a period that is not on the list".