@oxy.so/bloom 3.6.0 → 4.1.0

package/docs/pipeline.mdx

@@ -0,0 +1,126 @@
+---
+title: Pipeline
+description: Deals and the board they move on — a deal card, a stage column with its count and total, and a board that behaves on a phone. No drag and drop, on purpose.
+order: 124
+---
+
+# Pipeline
+
+Three components: `DealCard`, `PipelineColumn`, `PipelineBoard`.
+
+```tsx
+import { DealCard, PipelineBoard } from '@oxy.so/bloom';
+
+<PipelineBoard
+  stages={stages}
+  renderStage={(stage) =>
+    dealsIn(stage.id).map((deal) => (
+      <DealCard key={deal.id} {...deal} onPress={open} onMove={askWhereTo} />
+    ))
+  }
+  accessibilityLabel="Sales pipeline"
+/>
+```
+
+## There is no drag and drop, and that is the design
+
+Moving a deal between stages is the app's TRANSACTION. It owns the optimistic
+update, the rollback when the server says no, the permission check, the audit
+entry and the undo. A board that reordered its own view and left the app to
+notice is the worst version of this: it looks like it worked.
+
+A half-built drag is also worse than none in the hand. On a touch screen a
+vertical drag inside a horizontal scroller inside a vertical page has to win
+three gesture fights, and the one that loses is usually the page scroll — the
+board that "sometimes" scrolls is the one every user learns to distrust.
+
+So the board exposes the AFFORDANCE instead:
+
+- `DealCard`'s `onMove` draws a named move action ("Move Fleet telematics
+  rollout"). What it opens is the app's — a `DropdownMenu` of stages, a
+  `BottomSheet`, an `AlertDialog` confirming a downgrade.
+- `DealCard`'s `actions` slot takes anything else, typically a menu trigger.
+
+If an app wants drag, it wraps the cards itself; nothing here is in the way.
+
+## The amount is a string
+
+`DealCardProps.amount` and `PipelineStage.total` are PRE-FORMATTED. Currency,
+locale, rounding and abbreviation are four decisions Bloom cannot make — and a
+component that guessed one would be wrong in a way nobody notices until a
+customer does.
+
+Both are drawn on one line and never wrap: `€148,` above `000` is a different
+number to a reader. The amount also does not shrink when the close date beside
+it is long; the DATE gives way instead, because a truncated date is still a
+date and a truncated amount is a lie. `Pipeline.test.tsx` reads the emitted
+`white-space` and `flex-shrink` rather than the props, since the props prove
+nothing about the DOM.
+
+## One health axis, not two
+
+`health` is `on-track` / `at-risk` / `stalled`, drawn as a tinted `Badge` with
+the tone's glyph. There is deliberately no separate "priority" flag: a
+high-priority deal that is fine needs no mark, a stalled one is already the
+loudest thing on the card, and two pills that both mean "pay attention" is the
+duplication this family exists not to ship.
+
+`stalledFor` turns the stalled state into a duration — "Stalled for 23 days" —
+and is IGNORED on every other health, because a deal that is moving has not
+stalled for anything. The rule is `dealHealthLabel()`, exported and pinned in
+both directions.
+
+`stage` is for a card drawn OUTSIDE a column — a search result, a "my deals"
+list — where the column no longer says which stage it is in.
+
+## The column
+
+`PipelineColumn` paints ONE STEP off whatever is behind it (`surfaceFillOn`) and
+publishes that fill, so the deal cards inside step off the column instead of off
+the page. The same column therefore reads on a page, inside a `ContentPanel` and
+inside a dialog without being told which one it is on; the suite asserts the step
+clears 1.1:1 in both modes, which is the smallest fill difference that reads as
+a difference.
+
+- `count` is a counter `Badge` beside the name; `total` is right-aligned on one
+  line.
+- With no children it draws its `emptyLabel` in a hairline-outlined tile rather
+  than collapsing to nothing.
+- `loading` draws three `Skeleton.Box` placeholders INSTEAD of the empty state,
+  and suppresses "load more" — asking for more of what is not there yet.
+- `onLoadMore` renders a `text` button under the cards.
+
+## The board picks its own layout
+
+`layout="auto"` (the default) measures ITSELF with `useContainerWidth`, so a
+board in a side panel behaves like a phone without asking the window how wide it
+is. At or below `singleMaxWidth` (700) it draws `single`, otherwise `board`.
+
+Before the first layout the width is unknown, and `auto` chooses `board`: a
+board scrolls, so it is merely cramped at a phone width, while `single` on a
+desktop would hide four columns behind a tab row nobody asked for.
+
+- **board** — a horizontal `ScrollView` of 288-wide columns, 12 apart. The
+  scroller is the board's own, so the page behind it does not move sideways.
+  288 is wide enough for an amount and a close date on one line at the card's
+  type ramp and narrow enough that three fit a 960 pane.
+- **single** — a scrolling tab row of stage names plus the selected column at
+  full width. `SegmentedControl` was the obvious choice and is the wrong one:
+  five stage names do not fit 390, and a segmented control that clips is worse
+  than a row that admits it scrolls. So the tabs are `Chip role="tab"` inside a
+  `ChipRow role="tablist"`, which scroll and carry `aria-selected`.
+
+The selected stage is a controlled/uncontrolled pair (`stageId`,
+`defaultStageId`, `onStageChange`) reconciled by `useControllableState` — one
+mechanism, as `docs/composition.mdx` asks.
+
+`renderStage` returns the CARDS of one stage and the board never inspects what
+comes back. The stage list is data; the cards are opaque. Nothing here reads a
+child's type to decide anything.
+
+## What to reach for instead
+
+- A list of deals as a TABLE — sorting, columns, row actions — is `data-table`,
+  not a column of cards.
+- A funnel of stage-to-stage conversion is `FunnelChartCard`; stage totals over
+  time are `StageBarsCard`. A chart is not a board and neither is a meter.

package/docs/place-card.mdx

@@ -0,0 +1,121 @@
+---
+title: Place card
+description: A place on a map — the result row in a list and the detail header of the sheet it opens, as one component, with the name, category, rating, open/closed state, hours, distance, photo and the four actions.
+order: 134
+---
+
+# Place card
+
+```tsx
+import { PlaceCard, PlaceActions } from '@oxy.so/bloom/place-card';
+
+<PlaceCard
+  name="Forner de la Plaça"
+  category="Bakery · €€"
+  photo={photo}
+  rating={4.6}
+  reviewCount={318}
+  openState="open"
+  hours="Open until 20:00"
+  address="Plaça de les Bruixes 4"
+  facts={[{ icon: RiWalkLine, label: '6 min' }, { label: '450 m' }]}
+  onPress={open}
+/>
+```
+
+## Two densities, one component
+
+`density="row"` is the result in a list over the map. `density="detail"` is the header of
+the sheet that opens when the result is picked. They are ONE component because they carry
+the same facts in the same order — a name, what the place is, how well it is thought of,
+whether it is open, how far away it is and what you can do with it. A second component
+would be a second place for "open until eight" to be spelled, and two spellings drift.
+
+Only the arrangement differs:
+
+| | row | detail |
+| --- | --- | --- |
+| photo | 112 square thumbnail, radius 12 | a 165 cover across the top |
+| name | `body-semibold` | `title-2-medium` |
+| rating | `Rating` at `small`, beside the name | `Rating` at `medium`, beside the name |
+| figure | — | a quiet label over a tabular `title-1` reading |
+| tiles | — | `stats`, one row from 640 wide, two columns below |
+| actions | under the row | under the figure block |
+
+## Nothing here is drawn twice
+
+Every part of this card already existed, and this family composes them rather than
+redrawing them:
+
+- the stars are **`Rating`**, exactly as `ListingCard` uses it — beside the title, never
+  pushing it out;
+- the open/closed pill is **`Badge`** on a tone (`success` / `warning` / `error`), which is
+  the library's one labelled status pill;
+- the distance chip on the detail header is **`Chip`**;
+- the address line and the facts row are **`listing-card`'s own parts**
+  (`ListingLocationLine`, `ListingFacts`), imported, so a pin and a clipped fact row look
+  the same in a place card and in a listing card because they are the same code;
+- the row's 112 thumbnail is `listing-card`'s `COMPACT_PHOTO_SIZE` and
+  `COMPACT_PHOTO_RADIUS`, not a second pair of numbers;
+- the heart is **`FavoriteButton`**;
+- the actions are Bloom **`Button`s** through `PlaceActions`;
+- every colour is read off the surface the card was dropped on
+  (`styles/surface-levels.ts`), so the card is right on the page, in a sheet and inside a
+  `ContentPanel` without being told which.
+
+The REVIEWS are not here either. [`place-reviews`](/docs/place-reviews) already draws the
+summary, the review cards and the write-a-review prompt; a sheet renders
+`PlaceReviewSummary` under this header rather than this header growing a second one.
+
+## The detail header is `ai-profile-card`'s register
+
+A cover band, a name at title weight, a quiet label over a figure, tiles, and labelled
+`secondary` actions. That is deliberate: a place sheet and a profile card are the same
+shape of object — a picture, a name, one number that matters and a row of things to do —
+and Bloom should not have two registers for it.
+
+The one thing it does NOT copy is the avatar. A profile has a face over the cover; a place
+has only its photograph, so the cover IS the photo and the content starts under it.
+
+## Open, closing soon, closed, opens soon
+
+Four states rather than a boolean, because "closes in fifteen minutes" is a different
+answer from "open" and an app that can only say `true` says the reassuring one. The word
+comes from `PLACE_OPEN_LABELS` (or `openLabel`), the tone from `PLACE_OPEN_TONE`.
+
+**The pill and the hours are separate lines.** The pill is a WORD ("Open") and the hours
+are a SENTENCE ("Open until 20:00"). Pushed onto one line the sentence truncates first and
+leaves the pill saying half of what the app knows.
+
+## The row is a link and the controls are its siblings
+
+The thumbnail and the text sit inside ONE pressable — a real `<a href>` on web when `href`
+is set. The heart is laid over its corner and the actions sit under it, both from OUTSIDE
+that pressable. A button inside an anchor is invalid HTML, and on web a click on the heart
+would ALSO open the place.
+
+The row is one press target, so it carries one composed name — `composePlaceName` puts the
+name, the badge, the category, the rating as a sentence, the state, the hours, the address
+and the facts in reading order. Without it a screen reader reads "Forner de la Plaça Bakery
+€€ Open Open until twenty hundred" as one run, with the rating announced as "star four
+point six paren three one eight".
+
+## Known gap: an action has no pressed state
+
+"Save" is a toggle in every maps app, and Bloom's `Button` declares no `aria-pressed` and no
+`accessibilityState` — a component with a closed prop list drops what it does not name. So a
+saved place is expressed by the action's own WORDS and glyph ("Save" → "Saved",
+`RiBookmarkLine` → `RiBookmarkFill`), which is the one spelling that reaches both platforms
+today.
+
+That is a real shortfall and it is recorded rather than worked around: `PlaceActions` does
+not hand-roll a second labelled button to get the attribute. The fix belongs on `Button`
+(`pressed?: boolean`, emitting both spellings, exactly as `GlyphButton` already does).
+
+The heart is not affected — `FavoriteButton` carries both spellings itself.
+
+## Geometry
+
+`PLACE_CARD_GEOMETRY` holds the detail side: the 165 cover, the 24 radius, 16 of padding,
+15 between blocks, 10 for a tile's corner and padding, 10 between actions. The row side has
+no geometry of its own on purpose — it is `listing-card`'s compact row, part for part.

package/docs/place-details.mdx

@@ -0,0 +1,202 @@
+---
+title: Place details
+description: The body of a place's screen — the rows you act on, the hours by day, what the place has, how busy it is by the hour, and the transit around it, under PlaceCard's detail header.
+order: 137
+---
+
+# Place details
+
+```tsx
+import {
+  PlaceAmenities,
+  PlaceHours,
+  PlaceInfoList,
+  PlacePopularTimes,
+  PlaceTransit,
+} from '@oxy.so/bloom/place-details';
+```
+
+[`PlaceCard`](/docs/place-card) at `density="detail"` draws the HEADER of a place — the
+photo, the name, the rating, the figure and the four actions. This family is everything
+under it. Together they are the screen a maps app opens when a result is picked; neither
+half is a screen on its own.
+
+## What composes the screen
+
+| the part | what draws it |
+| --- | --- |
+| the header | `PlaceCard density="detail"` |
+| the hours | `PlaceHours` |
+| the photos | [`ListingPhotoGrid`](/docs/listing-details) + [`ZoomableMediaGallery`](/docs/zoomable-media-gallery) |
+| the address, phone, website | `PlaceInfoList` |
+| how busy it is | `PlacePopularTimes` |
+| what it has | `PlaceAmenities` |
+| the stops around it | `PlaceTransit` |
+| the reviews | [`place-reviews`](/docs/place-reviews) |
+| the section frames | [`ListingSection`](/docs/listing-details) |
+
+The sections are `ListingSection` and not a `PlaceSection`: a home's detail page and a
+place's detail screen stack sections the same way — a hairline, 32 above and below, a
+title at `title-3-semibold` — and a second component for that is a second set of numbers
+to keep equal.
+
+```tsx
+<ScrollView>
+  <PlaceCard density="detail" {...place} actions={actions} />
+  <PlaceHours state="open" summary="Open until 20:00" days={week} />
+
+  <ListingSection title="About">
+    <PlaceInfoList items={info} />
+  </ListingSection>
+
+  <ListingSection title="Popular times">
+    <PlacePopularTimes days={popular} />
+  </ListingSection>
+</ScrollView>
+```
+
+On a phone that goes inside a `BottomSheet` over the map; on a desktop inside a
+`ContentPanel` beside it. Nothing in this family knows which — every block reads the
+surface it was dropped on (`styles/surface-levels.ts`), so a sheet that publishes its own
+fill gets a settings card, a chart track and hairlines resolved against the sheet rather
+than against the page:
+
+```tsx
+<SurfaceLevelProvider level={1} fill={colors.card}>
+  <View style={[{ backgroundColor: colors.card }, surfaceFillVars(colors.card)]}>
+    …
+  </View>
+</SurfaceLevelProvider>
+```
+
+## `PlaceInfoList` is `settings-list`, row for row
+
+A place's contact block and a settings screen are the same object: a short card of rows,
+each carrying one value and one thing that happens when you press it. So this is
+`SettingsListGroup` and `SettingsListItem` — the glyph well, the 44 minimum height, the
+hairline between rows, and the surface the group resolves from whatever is behind it.
+
+Two decisions of its own:
+
+- **The VALUE is the first line and the kind is the second.** A reader scanning a place
+  sheet is looking for the address, not for the word "Address". The announcement inverts
+  that — "Address: Plaça de les Bruixes 4" — because a list of five rows is *listened* to
+  by kind, and five values with no labels cannot be told apart.
+- **The trailing glyph is not a button.** `action` picks it (a copy sheet, a handset, an
+  arrow out of the box) so the press is legible before it is made, and the row stays ONE
+  press target with ONE announcement. A second control inside a pressable row is a second
+  tab stop saying the same word, and on web it is a button inside a button.
+- **The action's WORD is in the name, not in a hint.** The first version put it on
+  `accessibilityHint`, and react-native-web drops that prop entirely — no `title`, no
+  `aria-description`, no `aria-describedby` — so on web the row announced a fact and never
+  said it could be pressed, while native read it correctly. Same class as
+  `accessibilityState`, same fix: the name is the one spelling that reaches both. It goes
+  last ("Address: Plaça de les Bruixes 4, Copy"), because the fact is what the reader came
+  for. `PLACE_INFO_ACTION_LABELS` holds the English words; `actionLabels` replaces them.
+
+`action` is a closed list rather than a slot for the same reason: one row, one action.
+Nothing here touches the clipboard, the dialler or the browser — `onPress` is handed the
+row's id and the app does the rest.
+
+`numberOfLines` defaults to **2**, because a postal address does not fit on one across a
+phone and the tail that would be cut is the part that identifies it. A settings row's
+title is a noun and fits on one; this one's title is the row's content.
+
+## `PlaceHours` says what the app tells it
+
+**Nothing here reads a clock.** `summary` is the app's whole sentence ("Open until 20:00",
+"Closes soon", "Closed — opens 07:30 tomorrow") and `today` is the app's flag. A place's
+hours are in the place's timezone, the reader is in another, and whether a Tuesday is open
+also depends on a holiday calendar Bloom has never heard of. A component that guessed would
+be wrong twice a year, quietly.
+
+The state pill and the state word are `PlaceCard`'s own — `PLACE_OPEN_TONE` and
+`openLabelFor` — so a place cannot be "Open" on the header of a sheet and "Closing soon" in
+the body of it.
+
+The disclosure is Bloom's `Accordion`: it owns the chevron, the `aria-expanded` and the
+reveal. One trap comes with it — `AccordionContent` keeps its children mounted while shut
+(it animates `maxHeight` to 0), so the week would still be read out under a trigger that
+says it is collapsed. `PlaceHours` hides its week from assistive tech while shut; nothing
+in there takes focus, so it costs nothing.
+
+**A split day stays on one line** (`07:30 – 14:00, 17:00 – 20:00`). The week is read as a
+column of days, and a day that takes two rows breaks the alignment that makes the column
+scannable. Both stretches are short, and the pair fits where one does.
+
+A day with no `intervals` is CLOSED — that is the whole encoding, so an app cannot say
+"closed" and list hours at the same time. `exception` puts a `warning` badge on the row
+("Public holiday", "Market day") and adds it to the row's announcement, because a badge is
+silent.
+
+## `PlaceAmenities` is the listing amenity block, called
+
+`layout="list"` **is** [`AmenityList`](/docs/listing-details), handed the same items — not
+a copy of it and not a port. Icon, label, an optional second line, a struck-through label
+for what the place does not have, the two-column split from 560 wide and the "Show all"
+button are all that component's. The only difference between a home's amenities and a
+place's was the noun, and a noun is not a component.
+
+`layout="chips"` is the one thing a listing page does not have: a wrapping strip of `Chip`s
+for the top of a sheet, where four attributes have to read at a glance. Same items, same
+unavailable treatment, different density.
+
+The name sits on the strip's `listitem` and not on the chip, because a non-pressable `Chip`
+is a plain `View` — and on web a `div` carrying an `aria-label` and no role is not
+announced at all.
+
+## `PlacePopularTimes` is a chart
+
+A meter answers "how full is this one thing". Every reading here only means something
+against the twenty-three beside it, so it is a chart, drawn the way Bloom draws charts:
+`react-native-svg` bars on `chart-cards`' own bar geometry (`singleBarSlot`,
+`roundedBarPath`) in one of its nine series hues, over its chart track colour.
+
+**Which chart card this is not.** `StepsCard` draws exactly these bars — inside the medical
+card's fixed height, under its own headline, its week pill and its count-up, with seven
+labelled bands. A place sheet already has a section header and needs twenty-four bands with
+a day switch, so reusing that card would have meant suppressing four of its five parts. The
+bar maths is what was worth sharing, and that is what is imported.
+
+Three decisions:
+
+- **The domain is a fixed 0–100.** A per-day maximum would make Tuesday's quiet peak as
+  tall as Saturday's queue, which is the one comparison the chart exists to allow.
+- **The track is drawn behind every hour**, so a quiet hour is still a shape and a CLOSED
+  hour reads as a gap rather than as a missing one.
+- **`currentHourIndex` belongs to a DAY.** Switching to Tuesday drops the "now" marker and
+  the live line with it, because Tuesday has no now.
+
+The chart is ONE image with one name ("Wednesday, busiest at 9, now 18, busier than usual").
+Twenty-four bars two pixels wide would be twenty-four tab stops saying a number each, which
+is not a reading of anything. The axis labels every hour that fits and every second or third
+below that — twenty-four labels across a phone is sixteen pixels each — and the current
+hour keeps its label whatever the step.
+
+`PLACE_BUSY_LABELS` holds the three English trend sentences; `trendLabel` replaces one.
+
+## `PlaceTransit` reuses the line badge
+
+The line pills are `directions`' own [`TransitLineBadge`](/docs/directions), imported. An
+operator's line colour is data the app owns, and that badge already knows how to *measure* a
+readable label against an arbitrary fill in both modes. A second badge here would be a second
+answer to that question, and they would drift.
+
+A departure is ONE utterance — "Line L4 to Pla del Bosc, 4 min, live" — because read part by
+part, a column of three badges and three times is six announcements the listener has to pair
+up themselves.
+
+**`realtime` is a colour AND a word.** The dot and the green time are what a sighted reader
+sees; `live` is in the row's name for everyone else. Green alone says nothing to a reader who
+cannot see it, and it is the first thing a high-contrast mode takes away.
+
+The stop header is pressable only when `onPressStop` is given (an app pans its map to the
+stop). It takes the library's one hover wash and one focus ring, built by
+`interactiveWebCss` rather than hand-written.
+
+## Geometry
+
+`PLACE_DETAILS_GEOMETRY` holds the numbers: 16 between blocks, 12 between rows, a 20 glyph,
+a 120 plot with a 22 axis under it, a 4 bar radius. The gaps are `listing-details`' own
+rungs, so a place's section and a home's section stack identically; only the chart has
+measurements of its own, because nothing else in Bloom draws a day of hours.

package/docs/place-list.mdx

@@ -0,0 +1,101 @@
+---
+title: Place list
+description: A saved list of places — the list as a card with its cover strip, count, collaborators and visibility, and the places inside it as PlaceCard rows with a note each, reorderable and removable.
+order: 138
+---
+
+# Place list
+
+```tsx
+import { PlaceList, PlaceListCard } from '@oxy.so/bloom/place-list';
+```
+
+"Want to go", "Favourites", "Coffee, ranked". `PlaceListCard` is the list seen from
+outside; `PlaceList` is what is inside it.
+
+## `PlaceListCard`
+
+```tsx
+<PlaceListCard
+  name="Want to go"
+  count={12}
+  photos={[a, b, c, d]}
+  icon={RiFlagLine}
+  visibility="shared"
+  collaborators={people}
+  onPress={open}
+/>
+```
+
+- **The cover is a STRIP, not a square.** 112 tall — `listing-card`'s compact thumbnail
+  height, which is the height of the place rows the list is made of, so a list's cover and
+  the first place under it agree. The first tile takes two shares of the row and the rest
+  one each, with 2px seams.
+- **The count and the sharing are ONE line.** A saved list is scanned in a grid of them,
+  and the only questions asked of a card in that grid are "which list is this" and "how
+  much is in it".
+- **`color` is the person's, not a token.** A list's colour is a choice, and Bloom has no
+  ramp for it. It paints the glyph and tints the empty strip; nothing derives anything from
+  it.
+- **The card is one press target, so it announces one sentence** — "Want to go, 12 places,
+  Shared with 3, Shared". Left to ARIA's contents algorithm it is four runs with no commas.
+- **`AvatarGroup` takes no `onPressItem` here.** A button inside the card's own press target
+  is the nested control this library refuses everywhere else; a collaborator's profile
+  belongs on the list's own screen.
+
+It is deliberately NOT `listing-card`'s `WishlistCard`. That card is a square 2×2 mosaic
+with its text underneath, built for a grid of wishlists; this one is a wide card with a body
+that has to carry a count, three faces and a visibility badge. They share the idea and none
+of the geometry, so sharing the component would have meant a second layout inside it.
+
+## `PlaceList`
+
+The places inside are `PlaceCard` at `density="row"`, untouched — a saved place and a search
+result are the same object, so this list draws no row of its own and inherits the thumbnail,
+the rating, the open state and the composed announcement with it.
+
+**The note is a sibling of the place, not part of it.** The place is the place; the note is
+what someone said about it. It is announced as "Note: get the sourdough before noon", after
+the row.
+
+### Reordering is buttons, and the buttons are the accessible path
+
+`moveItem` (`hooks/list-reorder`) is the same list maths the track list, the queue and the
+photo grid use, so "move" means one thing in this package.
+
+There is no pointer drag. `SortablePhotoGrid`'s drag is GRID geometry — a point resolved to
+a cell in a fixed row of columns — and a column of rows of different heights is a different
+problem, not a smaller one. Buttons are also what a keyboard and a screen reader get out of
+a drag surface anyway, so the list is fully operable with the half that exists. If you want
+a swipe to delete on touch, wrap a row in [`SwipeRow`](/docs/swipe-row) — that is the app's
+call, not this component's.
+
+Two properties that are easy to lose:
+
+- **Every row is keyed by its id**, so on web the button that was just pressed keeps focus
+  and travels with its row. A reader can press "move later" three times without hunting for
+  the control again.
+- **The ends are DISABLED, not absent.** The first row's "move earlier" and the last row's
+  "move later" stay in place; a control that disappears at the end of its travel moves the
+  two beside it under the pointer.
+
+Every move is announced politely through a visually hidden live region, because a reorder
+draws nothing new — the rows just swap, and a screen reader would otherwise hear nothing at
+all.
+
+### Controls are 44
+
+The move and remove controls are `GlyphButton`s at 44 with a 20 glyph, right-aligned under
+the row rather than stacked beside it: three 44 boxes do not fit in the 112 a place row is
+tall, and a column of controls narrower than that is not a thumb target.
+
+## Geometry
+
+`PLACE_LIST_GEOMETRY`: a 112 cover at radius 12 with 2px seams and at most four photos, 12
+between blocks, 44 controls with a 20 glyph.
+
+## Labels
+
+Every word `PlaceList` speaks that is not in the data is in `PlaceListLabels`, with
+`DEFAULT_PLACE_LIST_LABELS` as the English set. `PLACE_LIST_VISIBILITY_LABELS` and
+`PLACE_LIST_VISIBILITY_ICON` carry the three visibility words and their glyphs.

package/docs/price-breakdown.mdx

@@ -0,0 +1,102 @@
+---
+title: Price breakdown
+description: What a price is made of — line items, discounts, an "estimated" or "pending" number, a total that is visually the answer, and a collapsed summary that expands.
+order: 131
+---
+
+# Price breakdown
+
+A shipping quote, a restaurant bill and a service invoice are the same object: some
+charges, some credits, and the number they come to.
+
+```tsx
+import { PriceSummary } from '@oxy.so/bloom/price-breakdown';
+
+<PriceSummary
+  lines={[
+    { label: 'Collection and delivery', sublabel: '18 km, one helper', amount: '€34.00' },
+    { label: 'Stairs', amount: '€8.00', info: 'Charged per floor above the second when there is no lift.' },
+    { label: 'First trip discount', amount: '−€5.00', tone: 'discount' },
+    { label: 'VAT', amount: '€8.72', tone: 'muted' },
+  ]}
+  total={{ label: 'Total', amount: '€45.72' }}
+/>
+```
+
+## Amounts are strings, and that is the whole contract
+
+**Nothing in this family parses, adds, negates, rounds or formats a number.** Every
+`amount` — each line's and the total's — is drawn exactly as it arrives.
+
+That is not laziness, it is the only correct division. Currency, locale, the position of
+the symbol, the decimal separator, the grouping, how a credit is signed and how a total
+is rounded are all decisions an app makes with information this component does not have.
+A component that formatted them would be right for one app and quietly wrong for the next
+two — and "quietly" is the problem: a mis-formatted price still renders.
+
+In particular, **`tone="discount"` colours a credit; it does not create one.** Pass
+`"−€5.00"`, not `"5.00"`.
+
+## The three tones
+
+| tone | what it is for |
+| --- | --- |
+| `default` | everything, **including a fee** |
+| `discount` | money coming back — the success rung, which is the tone's SUBTLE foreground rather than its fill |
+| `muted` | the lines a reader scans past: a tax line, a rounding line |
+
+A fee is deliberately not a tone of its own. A fee is a line with a label and an amount,
+and giving it a colour would be this component deciding what an app's fees mean.
+
+## Not final yet
+
+`state` says whether the number is the answer.
+
+- `estimated` — a real number that can still move (a distance-based charge before the
+  route is fixed). Drawn, with "Estimated" under it.
+- `pending` — no number yet. The amount cell draws `pendingPlaceholder` (`—`) and
+  "Pending" under it.
+
+The caveat sits **under the amount**, not after the label, because it is a fact about the
+NUMBER. `stateLabels` replaces the two words.
+
+## The disclosure folds the lines, never the total
+
+With `collapsible`, the itemisation is what hides and the total stays on screen. That is
+the right way round: the number a reader came for should not be the thing they have to
+open a disclosure to see, and a summary that collapsed to nothing would be a row that
+says "prices" and nothing else.
+
+The trigger is a `text` `Button` carrying `aria-expanded`, so it announces the state of
+the thing it controls on both platforms. It is controllable (`expanded` /
+`onExpandedChange`) and uncontrolled (`defaultExpanded`) through the usual pair.
+
+## Geometry
+
+- a line is **32 tall minimum**, whether or not it carries the info affordance — the info
+  glyph is a 32 round target, and a column that grew only on the lines that happened to
+  have an explanation read as ragged
+- amounts are **tabular figures**, right-aligned; a price column of proportional digits
+  does not line up, and a column that does not line up cannot be scanned
+- the total is **`title-3-semibold` on both sides** — a type step above the charges rather
+  than the same size in bold, so a reader scanning for the number finds it without
+  reading a single line
+- the rule above the total is the surface's own hairline, read off whatever the summary
+  was dropped on
+
+## The info affordance
+
+`info` takes any node and shows it in a `Popover` anchored to a 32 glyph after the label.
+A string is wrapped in `Text` for you. Name it with `infoAccessibilityLabel` when
+"About <label>" is not the right sentence — the control draws no text of its own.
+
+The 32 target is smaller than the 44 a primary control gets. That is a deliberate
+exception for an optional secondary affordance inside a text row: a 44 target would set
+the height of every line in the breakdown, and a price column with 44-tall rows reads as
+a settings list rather than a bill.
+
+## PriceSummaryLine on its own
+
+`PriceSummaryLine` is exported so a screen that arranges its own charges — a checkout with
+a rule in the middle, a bill split across two cards — draws the same row without
+reimplementing the tone, the state caption or the tabular alignment.

package/docs/progressive-blur.mdx

@@ -10,6 +10,10 @@ A blur that is strongest at one edge and fades to nothing. Put it behind a
 floating tab bar or a transparent header so scrolling content dissolves rather
 than hitting a hard blur boundary halfway up a word.
 
+The tint follows the nearest published surface fill (`SurfaceLevelProvider`),
+falling back to the theme background outside a surface. A blur inside a tonal
+panel therefore fades into that panel's color.
+
 ```tsx
 import { ProgressiveBlur } from '@oxy.so/bloom/progressive-blur';