@oxy.so/bloom 4.0.0 → 4.1.0

package/docs/menu-item.mdx

@@ -0,0 +1,117 @@
+---
+title: Menu Item
+description: A dish in a menu — photo, clamped description, price, dietary pills and a heat level, a basket quantity and an add control — and the grouped choice that customises it, built on Radio, Checkbox and Field.
+order: 135
+---
+
+# Menu Item
+
+`@oxy.so/bloom/menu-item`
+
+Two components: the dish as a row, and choosing it.
+
+```tsx
+import { MenuItemRow, MenuItemOptions } from '@oxy.so/bloom/menu-item';
+```
+
+## `MenuItemRow`
+
+```tsx
+<MenuItemRow
+  name="Ember flatbread"
+  description="Wood-fired base, slow-roasted tomato, torn basil."
+  price="€12.50"
+  photo="ember-flatbread"
+  diets={['vegetarian']}
+  spice={2}
+  quantity={inBasket}
+  onQuantityChange={setInBasket}
+  onAdd={add}
+  onPress={openOptions}
+/>
+```
+
+It is `Item` with a dish's slots filled in. The row, the press target, the hover wash, the density rungs and the a11y role translation are `Item`'s; the price line is `listing-card`'s `ListingPriceLines`, which already draws a struck original beside a current price. This family owns the photo's rung, the marks and the add control.
+
+### The quantity is drawn once
+
+With `onQuantityChange` it lives in the `Stepper`, which is where a reader would change it. Without, it is a count over the photo. A badge beside a stepper showing the same number is two controls that mean one thing, and a reader has to work out which is the real one.
+
+### A pressable row and its control are siblings
+
+`Item`'s pressable form is a real `<button>` on web. A button inside a button is invalid HTML, and on web — unlike native, which does not bubble a press — a click on the inner control **also opens the row**. So a row that both opens the dish and adds it splits into the row and the control side by side, which is the same answer `address/AddressRow` reaches. A row with no `onPress` keeps its control in `Item`'s trailing slot, where there is nothing to nest inside.
+
+This is a web-only failure. A native run cannot find it.
+
+### The name owns its line
+
+The flames used to sit beside the name. At 390 — where a 72 thumbnail and a stepper leave the text column about 50 wide — a one-line `Text` is `nowrap` on web, so the fixed 44px glyph run took what it needed and the name collapsed to **zero**: three flames and no dish. The marks are a row of their own now, under the description, which is also where they belong: the flames and the diet pills are the same kind of thing.
+
+That row is ONE wrapping row, not a row nested in a row. A nested wrapping row is a single flex item that will not shrink below its content, and its pills ran off the card's right edge instead of wrapping — which is why `MenuItemDiets` takes the flames through a `leading` slot rather than as a sibling.
+
+Neither failure has a jest spelling: jsdom has no layout. What the suite holds is the arrangement that made them possible.
+
+### Marks: pills for diets, flames for heat
+
+`diets` is a **closed** list (`vegetarian`, `vegan`, `gluten-free`, `dairy-free`, `halal`, `kosher`), because each member has a word Bloom draws and a spoken form a screen reader gets; an open `string[]` would be a row of untranslated, unannounced pills. Only the two that are about what the dish is *made of* carry a glyph — inventing a symbol for a certification would be Bloom asking an app's customers to learn one.
+
+**An allergen is not one of these.** "Contains nuts" is a legal statement about a recipe, it belongs in the dish's own copy where it can be read in full, and a two-word pill is the wrong instrument for it.
+
+`spice` is a **level**, 1–3, drawn as that many flames and announced as one element with one name ("Spicy 2 of 3"). A pill saying "Spicy" cannot tell a reader whether one is enough; a run of three identical glyphs announces nothing at all.
+
+### The description is clamped, and is not in the name
+
+Two lines on screen, and deliberately absent from the row's accessible name. Read in full it turns a scannable list into a recipe book; the whole text belongs on the dish's own screen.
+
+## `MenuItemOptions`
+
+```tsx
+<MenuItemOptions
+  groups={[
+    { id: 'size', title: 'Size', min: 1, max: 1, options: [...] },
+    { id: 'extras', title: 'Extras', max: 3, options: [...] },
+  ]}
+  value={chosen}
+  onValueChange={(groupId, ids) => setChosen((c) => ({ ...c, [groupId]: ids }))}
+  quantity={quantity}
+  onQuantityChange={setQuantity}
+  total="€16.40"
+  onSubmit={addToBasket}
+/>
+```
+
+### It is content, not a surface
+
+On a phone it is what a `BottomSheet` holds; on a desktop what a `Dialog` holds. It paints no backdrop, claims no edge and owns no open state, so the same tree works in either — and building a sheet in here would be a third one beside the two Bloom already ships. `ScreenScope` comes with `DialogBody` and `BottomSheetBase`, so the form inside it is already scoped (see [Composition](/docs/composition)).
+
+### The rule is derived from `min` and `max`
+
+| `min` / `max` | drawn |
+| --- | --- |
+| `1` / `1` | Choose 1 |
+| `2` / `2` | Choose 2 |
+| `0` / `3` | Up to 3 |
+| `2` / `4` | Choose 2 to 4 |
+| `0` / `1` | Optional — "Up to 1" is not a sentence anybody says |
+
+`ruleLabel` replaces it for a language that is not English. `min >= 1` also makes the group `required`, which is the asterisk on the label.
+
+`max === 1` renders a `RadioGroup`; anything above renders a column of `Checkbox`. Both go through the `Field` contract — `docs/composition.mdx` names hand-rolled `role="radiogroup"` as debt and keeps a list of the three families that carry it, and this is not a fourth.
+
+### The cap disables, it does not evict
+
+At a group's `max`, the options that are not already chosen go `disabled`. A reader who presses a fourth extra and watches the first one disappear has been told nothing about the rule. `toggleOptionSelection` is the pure function behind it and refuses the same press, so the two cannot disagree.
+
+### An option's price shares its text column
+
+`RadioOption` and `Checkbox` draw a label and a description and nothing else, so `optionSubtitle()` joins the description and the price into the one line they have. **A right-aligned price column would mean hand-rolling the grouped-choice semantics**, and that is the debt above. If `Radio`/`Checkbox` ever grow a trailing slot, this is the call site that wants it.
+
+### The running price rides on the button
+
+`total` is a string the app formatted; nothing here adds anything up. With `onSubmit` it is appended to the button's label ("Add to basket · €16.40"), because the number a reader is agreeing to belongs on the control they press. Without `onSubmit` it is drawn as a plain row instead.
+
+## Traps
+
+- **Both components are fully controlled.** `value` is a map of group id to chosen option ids, and the component keeps no copy of it.
+- **`unavailable` removes the controls.** A sold-out dish has no stepper and no add button — dimming a control that still fires is worse than not drawing it.
+- **The thumbnail's geometry is props, not a density.** `cart-panel` draws the same square at its own rung; two implementations of one square is how the wash ends up at two different opacities.

package/docs/navigation-banner.mdx

@@ -0,0 +1,184 @@
+---
+title: NavigationBanner
+description: Guidance while it is happening — the next maneuver, the lanes, the posted limit, and the strip that ends it.
+order: 138
+---
+
+# NavigationBanner
+
+`@oxy.so/bloom/navigation-banner`
+
+`directions` is the route BEFORE you set off: the alternatives, the summary, the
+step list. This is the route while you are on it — one maneuver at a time, over
+a map, at arm's length.
+
+```tsx
+import {
+  ArrivalBar,
+  LaneGuidance,
+  NavigationBanner,
+  SpeedLimitPill,
+} from '@oxy.so/bloom/navigation-banner';
+
+<NavigationBanner
+  maneuver="right"
+  distance="400 m"
+  instruction="Carrer del Roure"
+  thenManeuver="left"
+  then="onto Passatge de l'Om"
+>
+  <LaneGuidance lanes={lanes} />
+</NavigationBanner>
+```
+
+## It reuses `directions`' maneuvers, it does not restate them
+
+`maneuver` is `DirectionsManeuver` and the glyph comes from
+`DIRECTIONS_MANEUVER_ICON`. A banner with its own arrow set would be a second
+opinion about what "slight right" looks like, drawn next to a step list that
+already had one — and the two would drift at the first icon change. The
+announcement uses `DIRECTIONS_MANEUVER_LABELS` for the same reason.
+
+`LaneDirection` is a SUBSET of the same vocabulary: a lane arrow is a maneuver
+drawn small, with the members that make no sense painted on tarmac (`depart`,
+`arrive`, `board`, …) left out.
+
+## The pane is a `GlassIsland`, at a surface radius
+
+Guidance is drawn over tiles Bloom does not own, and the island is the one
+material in the library priced for that — a translucent pane that takes its fill
+from a surface Bloom DOES own, so the text on it is legible whether the map
+underneath is a night satellite tile or a white street map.
+
+It is asked for `radius: 16` rather than its default capsule. A banner is a
+surface; the pill rung belongs to button-like controls.
+
+The island also mounts the `ControlSurface` the controls inside it read, which
+is why nothing here writes `variant="glass"` on anything.
+
+## The row
+
+| part | rung |
+| --- | --- |
+| tile | 56 square, 12 radius, the state's tone as a tint, the glyph at 40 in that tone's accent |
+| headline | `title-2-semibold`, TABULAR — the distance |
+| instruction | `headline-medium`, up to two lines — the street |
+| then | `body-2-medium` behind a full-bleed rule |
+| children | behind a second rule |
+
+The distance is the figure and the street is under it, because a driver reads
+"how far" first and "onto what" second. Without a distance the street is
+promoted to the figure rung rather than sitting small under an empty line —
+which is what an arrival banner ("Arriving at Plaça de les Bruixes") looks like.
+
+Tabular numerals matter more here than anywhere else in Bloom: the distance
+counts down continuously, and proportional digits make the street name under it
+shuffle sideways several times a second.
+
+## `off-route` and `rerouting` are this component
+
+Not a second surface. They take the same strip, in the same place, at the same
+moment — a different pane appearing where this one was is a jump, and the driver
+has to re-find the thing they were already reading.
+
+What the state changes:
+
+| state | glyph | tone | headline |
+| --- | --- | --- | --- |
+| `guiding` | the maneuver | `primary` | the distance |
+| `off-route` | a warning | `error` | "Off route" |
+| `rerouting` | a loop | `warning` | "Finding a new route" |
+
+`rerouting` is deliberately NOT the error tone. Nothing is wrong yet, the app is
+working, and a red banner at that moment tells a driver to act when the only
+correct action is to keep driving.
+
+In both states the maneuver stops being announced. A reader told to turn right
+while the car is off the route has been told the one thing that is no longer
+true.
+
+## It is one utterance
+
+The glyph is the only thing on screen that says which way to turn, and a glyph
+says nothing aloud. So the maneuver row is a single `img` named by
+`describeNavigationBanner` — "400 m, Turn right, Carrer del Roure, then turn
+left onto Passatge de l'Om" — with its drawn text hidden from assistive
+technology so the distance is not read twice.
+
+`children` sit OUTSIDE that name. A lane row and a speed sign each announce
+themselves, and folding them into the banner's sentence would make one
+four-clause utterance that changes every few seconds.
+
+## LaneGuidance
+
+Lanes left to right as the driver sees them, numbered from 1 in the
+announcement, because that is how you count them through a windscreen.
+
+- A lane you may use takes the accent's tint; one you may not takes no fill at
+  all. Two levels, not three: the question is binary.
+- `preferred` picks the one arrow to take from an allowed lane and leaves its
+  siblings at the quiet rung — a lane that also goes straight on is still the
+  lane you want.
+- A quiet arrow sits at the GRAPHICAL contrast rung (3:1), not a text one. It is
+  a glyph, and flooring it at text contrast would make the lanes shout over the
+  maneuver above them.
+- A lane with several arrows grows sideways rather than stacking them. A cell
+  taller than its neighbours breaks the count.
+
+The row announces "Lane guidance, 4 lanes, use lane 3 and lane 4", and still
+announces the count when none of them is yours.
+
+## SpeedLimitPill
+
+A 48 circle with a 4 ring, on the same chrome surface every floating map piece
+paints, with `shadow-s`. It is a CIRCLE because it is a sign, not a capsule of
+text.
+
+`exceeded` FILLS the sign with its tone and takes that fill's own on-colour for
+the number. A sign that merely got brighter is a sign a driver reads as the same
+sign; the change has to survive a glance, in daylight, at an angle. Nothing
+animates: a warning that flashes in a car asks for attention the road needs.
+
+`tone` defaults to `error` and exists because not every jurisdiction posts a red
+ring.
+
+## ArrivalBar
+
+The bottom strip: when you get there, how long is left, how far is left, and the
+way out.
+
+Three readings of EQUAL weight, each `title-3-semibold` and tabular over its own
+caption. Peers because the driver is asking a different question of each one and
+none of them is the answer to the other two.
+
+The ending action is `Button` in `destructive` **at the 44 rung** — larger than
+looks right in a screenshot, because it is pressed by a thumb, in a moving car,
+at the bottom of the screen. It keeps its own chrome inside the island on
+purpose: a control painted flush with the pane would be the quietest thing on a
+strip whose only action stops the navigation.
+
+### Why this is not `OrderStatusBar`
+
+They look alike and they answer differently shaped questions, and the shape is
+the whole component.
+
+`OrderStatusBar` has ONE headline with an arrival reading beside it, a glyph
+tile, a quiet second line and a progress meter. It says "here is what is
+happening, and here is how far along it is" — it is for a journey you are
+WAITING for. `ArrivalBar` has three readings of equal weight, no state and no
+meter: the journey is happening, you are on it, and you pick whichever of the
+three you wanted.
+
+Giving `OrderStatusBar` a three-figure mode would be a second layout behind a
+prop; giving `ArrivalBar` a status line and a meter would be a tracker for a
+trip the user is driving.
+
+What they do share is written down rather than duplicated: the same surface
+rung, the same tabular figures, and the same refusal to compute anything —
+neither reads a clock, formats a duration or knows what a kilometre is.
+
+## Nothing here computes
+
+Every string is pre-formatted by the app: the distance, the ETA, the remaining
+time, the limit. There is no clock, no unit conversion and no route state
+machine in this family.

package/docs/order-confirmation.mdx

@@ -0,0 +1,66 @@
+---
+title: Order confirmation
+description: It is placed — the mark, the reference, the tracking strip from order-status, where it goes, what was charged, what was ordered, and the two things you do next.
+order: 139
+---
+
+# Order confirmation
+
+```tsx
+import { OrderConfirmation } from '@oxy.so/bloom/order-confirmation';
+
+<OrderConfirmation
+  description="We have sent the receipt to your inbox."
+  reference="A-4821"
+  status={{ status: 'Being prepared', eta: 'Arrives 17:35', icon: RiBikeLine, progress }}
+  address={{ title: 'Home', subtitle: 'Carrer de l’Om 14, 2nd floor', kind: 'saved' }}
+  facts={[
+    { label: 'Arrives', value: 'Friday 24, 17:00 – 19:00' },
+    { label: 'Paid with', value: 'Card ending 4417' },
+    { label: 'Total', value: '€49.62' },
+  ]}
+  items={<OrderLines lines={lines} />}
+  action={{ label: 'Track order', onPress: track }}
+  secondaryAction={{ label: 'Get help', onPress: help }}
+/>;
+```
+
+## It IS an `EmptyState`
+
+Not "looks like one". A mark, a heading, a line of explanation, a block of content and up
+to two actions is exactly that family's shape, and a "done" screen is the same object as a
+"nothing here" screen with a different reason for existing. Building it a second time is
+how two centred columns with different paddings ship inside one library.
+
+That also means `variant="compact"` works here for the same reason it works there: the
+panel rung, for a confirmation inside a card rather than as the whole screen.
+
+## The mark is static, and that is a decision
+
+`AnimatedCheck` draws its ring and its check on only when a caller kicks it through its
+ref — at rest it is invisible. A mark nobody can see until a method runs is not a mark,
+and a user with reduce-motion would never see it at all. So the default is a check on a
+success-tinted disc: `IconCircle` with its own primary pair overridden TOGETHER (the one
+way its docs allow), from `resolveAccentColors(colors, 'success', 'subtle')` — a resolved
+pair, never a token with alpha appended.
+
+An app that wants the draw-on passes `<AnimatedCheck>` as `mark` and plays it itself.
+`mark={null}` draws none, for a surface that already carries a brand header.
+
+## The tracking strip is `order-status`'s
+
+`status` is `OrderStatusBarProps`, passed straight through. "Where it is right now" has
+one component in this library; this is a place that shows it, not a second one. The
+address row is `address`'s `AddressRow` and the fact box is the label/value box Bloom's
+action cards already draw.
+
+## `items` is a slot
+
+A line of an order is a dish, a parcel or a seat depending on the app, and each already
+has a row family of its own. The family draws the caption above whatever comes and stays
+out of the way.
+
+## It computes nothing
+
+Every amount, every time and every reading is a string the app formatted — including the
+reference, prefix and all.

package/docs/page-header.mdx

@@ -256,3 +256,17 @@ Mention, Allo and Homiio each hand-roll a `Header` with an `options` object. The
 | Homiio `scrollY` | `scrollY`, or a `ScrollOffsetProvider` around the screen |
 | Homiio `useSafeAreaInsets().top` | `safeArea` (default on native) |
 | Mention `options.headerTitleStyle` | pass a node `title` |
+
+
+The default scrim and bar background inherit the containing surface’s published
+fill (`SurfaceLevelProvider` / `ContentPanel`), falling back to the page
+background outside a surface. An explicit `scrimColor` still overrides the fade.
+The header’s outer box should span that surface; its own title/action padding
+provides the interior spacing.
+
+
+### Reveal after an in-content heading
+
+`titleReveal="onScroll" titleRevealOffset={headingHeight}` holds both title and subtitle until that scroll distance, then fades them in across `scrollThreshold` (default20px). The scrim remains independent. Hidden header titles leave the accessibility tree until they start appearing; back and action islands remain available.
+
+Measure the in-content heading block with its `onLayout` and pass its height as `titleRevealOffset` when it is the first block below the header. For later headings include the preceding content height. `Screen` and `ScreenScrollView` supply the shared offset; no consumer scroll listener is needed. See **Blocks / Page Header / Reveal After Content Heading** for the complete live composition. The default offset0 preserves existing reveal timing.

package/docs/payment-method.mdx

@@ -0,0 +1,169 @@
+---
+title: Payment method
+description: A way to pay, as a row and as a choice — the neutral mark, the masked identifier, the default, the expired and declined states, and the list they live in.
+order: 137
+---
+
+# Payment method
+
+Bloom had a basket, a quote and a total, and nothing that takes money. This is the
+first half of that: the methods a person has already saved, as a row you can read and
+as a choice you can make.
+
+```tsx
+import { PaymentMethodList } from '@oxy.so/bloom/payment-method';
+
+<PaymentMethodList
+  variant="picker"
+  accessibilityLabel="Pay with"
+  selectedId={selected}
+  onSelect={setSelected}
+  onAdd={openAddSheet}
+  methods={[
+    { id: 'a', scheme: 'Aurora', masked: '•••• 4417', expiry: 'Expires 09/29', isDefault: true },
+    { id: 'b', kind: 'account', scheme: 'Direct debit', masked: '•••• •••• 8842' },
+  ]}
+/>
+```
+
+## Bloom never draws a brand's logo
+
+The mark is a plate the shape of a card, a **neutral glyph** on it, and the scheme's
+**name as text**. That is the whole mark, and it is deliberate rather than unfinished:
+
+- the names are trademarks, and the artwork is licensed per scheme, per territory and
+  per acquirer. A library shipping twelve logos would be answering a question that
+  belongs to the app and its processor.
+- the set changes. A scheme launches, an acquirer drops one, a region gets a local
+  network, and a hardcoded list is wrong the day after it ships.
+
+An app that **has** the rights passes `image`, and it is drawn inside the plate at the
+plate's geometry. Everything else — the shape, the size, the state tint, the layout of
+the row — stays Bloom's. The escape hatch belongs to the app because the rights do.
+
+Bloom also ships **no scheme table**: no names, no prefixes, no ranges. `scheme` on a row
+is a string the app wrote. `card-form` takes the same position, at more length.
+
+## Nothing here is sensitive
+
+`masked` is a string the app already masked — `'•••• 4417'`, `'ES•• •••• 8842'`,
+`'€18.40 left'`. There is no prop that takes a full number, nothing in this family
+unmasks, parses, stores, logs or transmits anything, and `expiry` is words the app
+formatted.
+
+Whether a date is in the past is the app's finding, not this component's: nothing here
+reads a clock. Report it through `state`.
+
+## The kind is data
+
+`kind` is `card | account | wallet | cash`, and it chooses the default glyph and nothing
+else. There is no `SavedCardRow`, `BankAccountRow` and `WalletRow`, because a checkout
+picker, a settings list and a receipt all draw the same row and differ only in what they
+put in it. An app whose kinds are not those four passes `icon`.
+
+## The state is three, and the third is the point
+
+`ok | expired | declined`. `expired` paints the warning tone, `declined` the error tone,
+and both draw a line under the row — the state's own word, or the app's sentence through
+`stateMessage`, which is where a bank's reason belongs.
+
+They are STATES rather than tones because a picker and a settings screen must not
+disagree about what colour a declined card is. The mapping is `PAYMENT_METHOD_STATE_TONE`,
+in one place.
+
+## The variant is the announced tree
+
+- `list` — a `list` of `listitem`s, each wrapping a button. A reader is MANAGING these.
+- `picker` — a `radiogroup` of `radio`s carrying `aria-checked`. A reader is CHOOSING one.
+
+Both roles exist on both platforms, which is why the picker is a radio group rather than
+the listbox ARIA would suggest: React Native has no `listbox`, and a role that reaches
+one platform is the silent half of an accessibility bug.
+
+### The picker is a `Field` member, not a hand-rolled radiogroup
+
+`PaymentMethodList` resolves `useFieldMembership()` the way `RadioGroup` does, so a
+`Field` around it names the group, describes it with its error, marks it invalid and
+freezes every row — and a row inside a disabled field cannot re-enable itself, because
+`disabled` combines with `||` rather than deferring.
+
+```tsx
+<Field label="Pay with" description="Charged when the order is dispatched." multiple>
+  <PaymentMethodList variant="picker" methods={methods} selectedId={id} onSelect={setId} />
+</Field>
+```
+
+`multiple`, because the field holds several controls: a single-control field publishes
+one control id, and one id on four radios is invalid HTML.
+
+`accessibilityLabel` is the caller's and wins; the field's label is next; `"Payment
+methods"` is a LAST resort rather than a default, because a default would outrank the one
+string on screen the user can read.
+
+The composition page names three families that write `role="radiogroup"` over their own
+cards and stop there — a group nothing can name or disable. Writing the role is the easy
+half.
+
+### A disabled row keeps its handler
+
+It is handed `disabled` instead, so `Item` renders a real disabled control that still
+announces itself as a radio and as unavailable. Withholding the press handler would have
+made the row a plain `View`: present, silent, and gone from the choice.
+
+## The add row is not one of the choices
+
+"Add a payment method" is an action, so `onAdd` draws it OUTSIDE the `radiogroup`. A
+button among the radios would be announced as part of the choice and counted in "3 of 4".
+It is drawn under the empty state too, which is exactly when a reader needs it.
+
+## It is `Item`, filled in
+
+`PaymentMethodRow` is Bloom's `Item` with a payment method's slots filled: the row, the
+press target, the density rungs, the selected wash, the disabled opacity and the ARIA role
+translation are all `Item`'s, and this family owns no second copy of any of them. What it
+adds is the plate, the scheme/masked pairing on the title line, the default `Badge`, the
+state line and the `RadioIndicator`.
+
+It is `address`'s `AddressRow` one family over, and knowingly so — same base, same
+trailing-action rule, same geometry column so a checkout stacking an address row and a
+payment row does not step sideways between them. The two differ in three things worth the
+separate component:
+
+- the leading media is a **card-shaped plate**, not a round tile, and it carries a state
+  tint.
+- the title line is a **pair** — a name and a masked identifier in tabular figures — not
+  one string.
+- the selection control sits **inside** the press target, where `AddressRow`'s `action` is
+  deliberately split OUT of it.
+
+If a row needs something `Item` does not do, that is a report about `Item`, not a fork
+here.
+
+## Geometry
+
+```
+plate       40 × 28, radius 6 · compact 32 × 22, radius 5
+glyph       18 · compact 14
+title       Item's title rung; the masked identifier in body-2 TABULAR figures
+line 2      the expiry, secondary
+line 3      the state's words, in the state's own colour
+dot         16 · compact 14 — RadioIndicator, never a hand-drawn circle
+rows        4 apart
+```
+
+40 wide is the leading column the rest of the library already uses. 28 tall against it is
+the ratio that reads as a card rather than an app tile, and it is the one measurement here
+that is about shape rather than size.
+
+## The trailing action splits out of a pressable row
+
+A pressable row is a real `<button>` on web, so a control cannot live inside it: a button
+in a button is invalid HTML and a web click on the inner control also fires the row. A row
+with both `onPress` and `action` draws them side by side. The selection dot is not a
+control — it draws no press target — so it stays inside.
+
+## Reuse
+
+`PaymentMethodMark` is the whole mark, and `card-form` uses it for the scheme it detects.
+Use it anywhere a method has to be identified without a row: a receipt line, a
+confirmation screen, a settings header.

package/docs/payment-status.mdx

@@ -0,0 +1,108 @@
+---
+title: Payment status
+description: What happened to the money — five states, a compact strip that IS OrderStatusBar, and a block for the screen a reader arrives at.
+order: 139
+---
+
+# Payment status
+
+```tsx
+import { PaymentStatusBar, PaymentStatusBlock } from '@oxy.so/bloom/payment-status';
+
+<PaymentStatusBar state="failed" amount="€48.00" detail="Your bank turned this one down."
+  action={<Button size="sm" variant="outline" onPress={retry}>Retry</Button>} />
+
+<PaymentStatusBlock state="paid" amount="€48.00" detail="Aurora •••• 4417"
+  reference="8F2K-41QD-7T" actions={<Button variant="outline" onPress={open}>View receipt</Button>} />
+```
+
+## Five states, and they are the five you DRAW
+
+`authorising | paid | failed | refunded | pending`.
+
+Not the five a processor reports — a processor has twenty, and which of them counts as
+"done" is a fact about that processor's contract. An app maps its own onto these five, and
+this family does no mapping, because a component that guessed would be wrong for the next
+acquirer.
+
+`pending` is the state that is easy to leave out and the one apps need most: waiting on a
+bank window, a queued retry, a device with no connection.
+
+## The strip IS `OrderStatusBar`
+
+`PaymentStatusBar` renders `order-status`'s `OrderStatusBar`. It is not a second strip that
+looks like it.
+
+`order-status` already owns this library's answer to "where is this right now": the 40 tile
+in the tone's tint, the one-line status with a short trailing reading in tabular figures, a
+quiet second line, a `Meter` for progress, surface-relative chrome, and a `plain` variant
+for a strip already inside a card that paints. A payment is the same question with
+different data, and shipping a second strip would mean two components drifting apart on
+every one of those decisions — the tile size first, the truncation rule second.
+
+What `PaymentStatusBar` adds is the mapping a payment needs and an order does not: five
+states to five sets of words, five tones and five glyphs, in one place so a status row and
+a confirmation screen cannot disagree about what "pending" is called or what colour it is.
+
+**The amount rides the trailing reading.** That slot is a short reading in tabular figures,
+capped so it cannot crush the status beside it, which is exactly what an amount is. Its
+prop is spelled `eta` because an order was the first thing that needed it; the slot is
+general and this is the second use of it. The name is worth fixing in `order-status`, and
+it is that family's to fix.
+
+## The block is not a bigger strip
+
+`PaymentStatusBar` is what a list, a header or a sticky footer carries while something is in
+flight. `PaymentStatusBlock` is what a reader ARRIVES at — so the glyph is the page's
+subject rather than a row's ornament, the amount is the largest thing on it, and the
+failure's words get an `Admonition` of their own instead of a second line.
+
+```
+tile     56 round in the state's tint, 28 glyph in the tone's own accent
+status   title-2-semibold, centred
+amount   title-1-semibold, TABULAR — the number a reader checks
+detail   body-regular, secondary
+ref      a caption label over a body-medium tabular value, so a reference can be
+         read out one character at a time
+reason   Admonition — error for a failure, warning for a pending one
+surface  one rung above whatever it was dropped on, 16 radius, a hairline;
+         `plain` draws the content and no chrome
+```
+
+56 is the size at which a glyph reads as the page's subject rather than a row's ornament,
+and it is the tile an empty state uses two families over.
+
+## `refunded` is neutral, on purpose
+
+`PAYMENT_STATUS_TONE` maps `refunded` to the `default` tone rather than to success. Money
+coming back is neither good news nor bad: painting it green congratulates a reader on a
+cancelled order, and painting it red alarms one who asked for the refund.
+
+## The reason is only for the states that have one
+
+`reason` is drawn for `failed` and `pending` and ignored for the other three, whatever the
+caller passes. A reason under a success is a reader hunting for a problem that is not
+there. Which admonition a state uses is `PAYMENT_STATUS_ADMONITION`.
+
+## Nothing here computes anything
+
+`amount` is a string the app formatted, sign and currency included. `progress` is a value it
+measured. The component never parses a number, never formats one, never adds two, and never
+reads a clock.
+
+## The retry is the caller's
+
+There is no `onRetry`. A retry is a `Button` in `action` (strip) or `actions` (block),
+because only the app knows whether retrying means the same method, another one, or a
+different screen entirely — and because a component that owned the button would also own
+its label, its variant and whether it is disabled while a second attempt is in flight.
+
+## Names and words
+
+`status` replaces one call's words outright. `labels` replaces a state's default everywhere
+the app translates once — `PAYMENT_STATUS_LABELS` holds those defaults, and `"Payment
+failed"` rather than `"Failed"` is deliberate: the strip is read in a row of other rows,
+where "Failed" is a word with no subject.
+
+The block names itself from its words, amount and detail joined, so a reader landing on it
+hears the answer before the glyph.