@oxy.so/bloom 3.6.0 → 4.0.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/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/provider.mdx

@@ -1,64 +1,38 @@
 ---
 title: BloomProvider
-description: The one root a consuming app mounts — and why the outlets are deliberately not in it.
-order: 56
+description: Universal application state with an explicit router adapter.
 ---
 
 # BloomProvider
 
-The single root that composes Bloom's app-wide **state** providers, so none of
-them lands at the wrong depth.
+Mount one `BloomProvider` above every render branch, including loading UI. It
+composes theme, image resolution, haptics and scroll storage without importing a
+router. It is exported from both `@oxy.so/bloom` and `@oxy.so/bloom/provider`.
+Without `scrollAdapter`, automatic route restoration is inactive.
 
 ```tsx
 import { BloomProvider } from '@oxy.so/bloom/provider';
+import { expoRouterScrollAdapter } from '@oxy.so/bloom/scroll/expo-router';
 
-export default function RootLayout() {
-  return (
-    <BloomProvider>
-      <Stack />
-    </BloomProvider>
-  );
-}
+<BloomProvider scrollAdapter={expoRouterScrollAdapter}>
+  <App />
+</BloomProvider>
 ```
 
-## Why one root rather than several
+Keep the adapter reference stable. Vite and other router integrations supply their
+own `ScrollRouterAdapter`; Expo consumers now pass the adapter explicitly instead
+of receiving an implicit router dependency.
 
-Depth is not a detail for these. Mounted too low:
+Visual hosts (`ToastOutlet`, `SurfaceHost`, portal/dialog outlets) stay outside the
+provider: their position determines stacking, and mounting duplicate outlets draws
+duplicate surfaces. `Screen` scopes coordinated geometry and motion locally.
 
-- `useScrollRestoration()` **throws** for anything rendered beside it;
-- `useMinimizeState()` silently hands out a private fallback, so two parts of
-  the app disagree about the same state and neither errors.
+The original depth hazards remain: `useScrollRestoration()` throws outside its
+provider, and legacy `useMinimizeState()` creates a private fallback without its
+provider. Mounting providers beneath a sibling scroll region recreates those
+failures. New screen chrome uses the local `Screen` shared values, rather than
+sharing one global motion state across retained routes. `useTheme()` also throws
+outside its provider, including an early-return splash branch on cold start.
 
-One root removes the chance to get that wrong.
-
-## Expo/expo-router apps only
-
-`BloomProvider` binds the scroll store to `expoRouterScrollAdapter`, so it is
-expo-router-only **by construction** — which is also why the family is not on
-the root barrel: importing it would drag `expo-router` into every consumer's
-graph, and Metro does not tree-shake, so an unmet peer is a build failure
-rather than a degradation.
-
-A Vite/SPA consumer mounts the pieces instead: `BloomThemeProvider` plus
-`<ScrollRestorationProvider adapter={…}>` with its own router adapter.
-
-## The OUTLETS are deliberately not in it
-
-`ToastOutlet`, `PortalProvider`/`PortalOutlet`, `SurfaceHost` and the dialog
-hosts stay out. Where an outlet sits in the tree is an app decision — it has to
-paint over the app's own chrome — and **a second mount duplicates every
-surface**. Adding one here would silently double the toasts of any app that
-already mounts its own.
-
-That failure is quiet: two identical toasts read as a double-fire in your own
-code, not as two outlets.
-
-## Where the theme provider goes
-
-Above **every** render branch, including the splash/loading one.
-
-`useTheme()` throws outside `BloomThemeProvider`, and the classic way to hit
-that is an `appIsReady` early-return in `app/_layout.tsx` that renders a splash
-screen *before* the providers mount. It fails at runtime only — `tsc` and the
-build stay green — and only on a cold start. Verify in a real browser after any
-theming migration.
+`PortalProvider`/`PortalOutlet` are native infrastructure; the web portal uses its
+own DOM implementation. Choose outlet placement deliberately and mount each once.

package/docs/radio-indicator.mdx

@@ -27,6 +27,7 @@ import { RadioIndicator } from '@oxy.so/bloom/radio-indicator';
 | `selected`      | filled or hollow                                |
 | `size`          | the diameter (16); the dot and hairline scale   |
 | `selectedColor` | the accent the selected gradient is built from  |
+| `selectedForeground` | foreground paired with a supplied selected fill |
 | `borderColor`   | the ring when not                               |
 
 `pressed` is still accepted and ignored: there is no pressed paint.
@@ -56,12 +57,12 @@ a table row, a settings row with its own affordances.
 
 ## The dot colour is derived, not white
 
-When `selectedColor` is the theme primary, the dot uses the preset's readable
+When `selectedColor` is omitted, the dot uses the preset's readable
 foreground — dark on a yellow primary, light on a blue one. A hardcoded white
 dot disappears on a light accent, which is the same class of failure as
 appending alpha to a token: correct markup, invisible control.
 
-A caller-supplied `selectedColor` falls back to white, because Bloom cannot
+Shared radio controls pass `selectedForeground` with their semantic fill. A caller-supplied `selectedColor` without that foreground falls back to white, because Bloom cannot
 know the right contrast for an arbitrary colour. If you pass one, check it.
 
 ## Selected drops the border

package/docs/radio.mdx

@@ -33,19 +33,19 @@ import { RadioGroup } from '@oxy.so/bloom/radio';
 | `label` (group)           | the accessible name of the whole group — required    |
 | `value` / `onValueChange` | the selection; the group is fully controlled         |
 | `options`                 | the choices, each with its own `label`/`description` |
-| `size`                    | `small` · `medium` · `large`                         |
+| `size`                    | `sm` · `md` · `lg`                         |
 | `disabled`                | the whole group, or one option via its `disabled`    |
 
 ## What it looks like
 
 The dot is [`RadioIndicator`](/docs/bloom/main/radio-indicator); the row puts an 8px gap between it and the label.
 
-|       | `small` | `medium` | `large` |
+|       | `sm` | `md` | `lg` |
 | ----- | ------- | -------- | ------- |
 | dot   | 14      | 16       | 20      |
 | label | `body-2-medium` 13/18 | `body-medium` 14/20 | `headline-medium` 16/22 |
 
-`small` is the `sm` size and `medium` the `md` size; `large` extends the ramp — the same rungs as `Checkbox`, so a form mixing the two lines up. A disabled option dims the whole row to 50%. On web, keyboard focus draws a `ring-2 ring-offset-2` around the dot: a 2px accent ring outside a 2px white offset (white in dark mode too — Tailwind's default offset colour). Text is Inter from Bloom's type ramp. There is no hover or press paint and no press scale — selection is the only thing that animates.
+`sm` is the `sm` size and `md` the `md` size; `lg` extends the ramp — the same rungs as `Checkbox`, so a form mixing the two lines up. A disabled option dims the whole row to 50%. On web, keyboard focus draws a `ring-2 ring-offset-2` around the dot: a 2px accent ring outside a 2px offset matching the scoped page background. Text is Inter from Bloom's type ramp. There is no hover or press paint and no press scale — selection is the only thing that animates.
 
 ## Cards
 
@@ -74,7 +74,7 @@ tapping the words does nothing — which reads as an unresponsive control.
 
 If you need the dot alone — inside a custom row, a card selector, a table cell —
 that is [`RadioIndicator`](/docs/bloom/main/radio-indicator), which is
-presentational and takes `selected`. Using the indicator where you meant the
+presentational and takes `checked`. Using the indicator where you meant the
 control is how a "radio group" ends up announcing as decoration.
 
 ## In a `Field`

package/docs/recent-hires-card.mdx

@@ -33,7 +33,7 @@ import { RecentHiresCard } from '@oxy.so/bloom/recent-hires-card';
 | header | padding 8 8 0; label `body-medium` text-secondary, 2, count `title-1-medium`; team switcher `body-medium` + 16px chevron (text-secondary), gap 6, px 2 |
 | grid | 11 under the header, 2 × 2, gap 8; the two rows share the height left over |
 | person | radius 10, padding 10, `background-inner`, `shadow-card`, space-between: `Avatar` lg (36) + name `body-medium` / joined `body-2-medium` text-secondary (both truncate), gap 8; then the role `Chip` (small, full width, centred, full pill per Bloom's radius rule) |
-| pager | 8 under the grid: two small secondary `Button`s, gap 8, half the width each, arrow-left leading / arrow-right trailing |
+| pager | 8 under the grid: two small subtle neutral `Button`s, gap 8, half the width each, arrow-left leading / arrow-right trailing |
 
 | token | light | dark |
 |---|---|---|

package/docs/route-stops.mdx

@@ -0,0 +1,104 @@
+---
+title: Route stops
+description: An origin, a destination and what is between them — the connector line, a swap for the two-stop case, add and remove, and a "stop reached" state so the same component works while a journey is in progress.
+order: 133
+---
+
+# Route stops
+
+```tsx
+import { RouteStops } from '@oxy.so/bloom/route-stops';
+
+<RouteStops
+  stops={stops}
+  onPressStop={openPlacePicker}
+  onSwap={swap}
+  onAddStop={addStop}
+  onRemoveStop={removeStop}
+/>
+```
+
+## One component for planning and for travelling
+
+`state` (`pending | current | reached`) is what makes a route being PLANNED and a route
+being TRAVELLED the same component. A planner leaves every stop `pending`; a journey in
+progress marks the ones behind it `reached` and the one it is heading for `current`. The
+markers and the rail change, the layout does not, and an app does not swap components
+half way through a trip.
+
+## The marker column is two half-lines
+
+Each stop's marker sits between two `flex: 1` rails inside a 24 column. That is the whole
+alignment mechanism, and it is worth stating because it is what this family does INSTEAD
+of measuring anything:
+
+- the marker centres itself in whatever height the row turns out to be — with a subtitle,
+  with a badge, with a wrapped line, with none of those;
+- the half-rail below one row meets the half-rail above the next exactly, because both
+  are the same computed colour and both end at the row boundary;
+- nothing is nudged, offset or measured, so a row that changes height cannot break the
+  line.
+
+The first row's upper rail and the last row's lower rail are transparent rather than
+absent, so every marker sits at the same place in its row.
+
+## Shape says which stop, colour says how far
+
+| stop | shape |
+| --- | --- |
+| origin | a 12 ring, 3px |
+| between | an 8 dot |
+| destination | a 12 square, 3 radius — an end, not another dot |
+
+`reached` and `current` paint the accent; `pending` paints the graphical rung (the one the
+surface ladder sizes for a line or a glyph, so it clears 3:1 on whatever is behind it).
+
+**The current stop also GROWS**, by 6 (compact 4), and wears its 3px tint ring outside its
+own diameter. A halo drawn inside an 8px dot is two pixels of fill, and it shipped that
+way for one screenshot: the current stop and the one before it were the same dot, so the
+only thing saying which was which was a colour they shared.
+
+The rail fills behind the journey on the same rule the order-status rail uses: travelled
+when the stop BELOW it is reached or current.
+
+## Swap is offered for exactly two stops
+
+With three or more there is no single swap to make, so the control is not drawn. A control
+that silently meant something different at three stops would be worse than no control —
+and "reverse the whole route" is a different action with a different name, which an app
+can put in its own menu.
+
+The swap button lives in a column beside the list, centred against the whole of it, so
+with two stops it lands between them without a magic offset.
+
+## Every word is in one prop
+
+`labels` carries all of it — `origin`, `destination`, `stop(position)`, `swap`,
+`addStop`, `remove(stop)` and the three `state` words. It is one prop rather than nine
+because all of it is copy an app localises and none of it is layout.
+
+`remove` is a FUNCTION of the stop, because "Remove" on five buttons in one list names
+nothing: the default is `Remove ${stop.title}`.
+
+## Accessibility
+
+The stops are a `list` of `listitem`s named as one. Each row's announced name carries its
+POSITION and its STATE before its text — "Destination, not reached, Home, Carrer de l’Om
+14" — because the shape and the colour that say both of those things on screen say
+nothing at all to a screen reader.
+
+**Where that name lands depends on whether the row is a control, and it is one place or
+the other, never both.** A row with `onPressStop` is a button and carries the name itself.
+A read-only row is not a control: `Item`'s non-pressable branch renders `role="none"`,
+which is the one element assistive technology is told to ignore, so the name goes on the
+`listitem` instead. Naming both would announce every stop twice.
+
+Swap and add sit OUTSIDE the list, which is right: they act on the list rather than being
+members of it, so a reader moving through the stops is not interrupted by them.
+
+## Rows are `AddressRow`
+
+Each stop is an `AddressRow` with `leading={null}` — same press target, same density
+rungs, same disabled opacity, same trailing `meta`/`action` pairing. A stop's `action` is
+drawn before the remove affordance, so an app can add its own control per stop without
+losing removal.

package/docs/sankey-chart-card.mdx

@@ -47,10 +47,31 @@ import { SankeyChartCard } from '@oxy.so/bloom/chart-cards';
 
 - recharts' props: `nodeWidth` 12, `nodePadding` 14, `linkCurvature` 0.55, 32 iterations, `sort={false}`, margin top/bottom 2, left 88 and right 150 for the labels. Justified: every sink sits in the last column.
 - Nodes: rounded 5 only on their outward side (sources left, sinks right, pass-through square), so ribbons meet a flat edge (`sankeyNodePath`).
-- Ribbons: one cubic per link stroked at its thickness, stroke-opacity 0.32 at rest; neutral ink ×1.6 (capped 0.85).
+- Ribbons: closed cubic bands with value-proportional vertical thickness, fill-opacity 0.32 at rest; neutral ink ×1.6 (capped 0.85).
 - Labels (Bloom `Text` over the SVG, placed on recharts' baselines — `svg-text.ts`): sources right-aligned 8px left of the node, name `body-2-medium` text-primary over its value `caption-1` text-tertiary (a node under 26px keeps the name only); sinks 8px right, `"Name · 22%"`, the share in text-tertiary. Pass-through nodes are unlabelled.
 - Neutral: light neutral-400 (hover 500), dark neutral-300 (hover 100).
 
 ## Hover
 
-Web hover, native press-and-scrub (letting go clears). The pointer is hit-tested in `hitTestSankey`: nodes first (they paint on top), then the topmost ribbon whose stroke contains the point. A node lifts its ribbons to 0.7, fades the rest to 0.08 and every unconnected node to 35%; a link isolates itself and its two ends. The node fill steps to its `-active` colour. Opacities ease over 200ms and the fill over 150ms (`use-eased-values.ts` — react-native-svg can't CSS-transition presentation attributes); snaps under reduced motion.
+Web hover, native press-and-scrub (letting go clears). The pointer is hit-tested in `hitTestSankey`: nodes first (they paint on top), then the topmost ribbon whose filled band contains the point. A node lifts its ribbons to 0.7, fades the rest to 0.08 and every unconnected node to 35%; a link isolates itself and its two ends. The node fill steps to its `-active` colour. Opacities ease over 200ms and the fill over 150ms (`use-eased-values.ts` — react-native-svg can't CSS-transition presentation attributes); snaps under reduced motion.
+
+
+## Narrow cards
+
+Below 440px of measured plot width, labels stay beside their nodes in proportional
+left and right gutters (starting at 24% and 32%, widening for measured whole words while preserving ribbon space). Full names wrap at their regular 13px text
+size; values and sink percentages sit on a separate line. The flow retains the
+remaining width and its quantitative proportions.
+
+The plot grows when the labels need more vertical room. Their actual rendered
+heights refine the initial estimate, and labels are arranged around node centres
+without overlapping. Subtle leaders connect any displaced label to its node.
+No categories are removed or replaced by a separate legend. Wider cards retain
+the original side labels and fixed height. Layout follows the card's available
+width rather than the window.
+
+
+Ribbons use closed filled bands between each node's top and bottom link edges.
+Their vertical thickness represents value; a narrow, steep curve cannot create
+the side protrusions of an oversized SVG stroke. Pointer hit testing follows the
+same filled boundaries.

package/docs/screen.mdx

@@ -0,0 +1,61 @@
+---
+title: Screen
+description: Continuous content with coordinated header, scrolling and bottom chrome.
+---
+
+# Screen
+
+`Screen` owns a continuous page canvas. `header` and `bottomBar` overlay the content;
+`ScreenScrollView` reserves their measured footprints, adding its own content padding.
+Safe-area padding belongs to the chrome, so it is included exactly once in those measurements.
+
+```tsx
+import { Screen, ScreenScrollView } from '@oxy.so/bloom/screen';
+
+<Screen header={<PageHeader title="Inbox" />} bottomBar={<Navigation />}>
+  <ScreenScrollView><Messages /></ScreenScrollView>
+</Screen>
+```
+
+`PageHeader` automatically reads its enclosing screen's offset. `useScreen()` exposes
+`scrollY` and `collapseProgress` to coordinated chrome. Pass `collapseProgress` as
+`BottomBar`'s `minimizeProgress`; navigation and the lateral action then move together.
+
+For a virtualized list, call `useScreenScroll({ active, handler })`, bind `onScroll`,
+and apply `contentInsets.top`/`bottom` to its content container. `handler` accepts a
+processed Reanimated handler, preserving drag and momentum subscriptions. Only the
+active binding drives chrome. Set `active={false}` on retained background lists.
+Nested `Screen`s keep scroll offsets local. Under AppShell they inherit navigation motion and bottom clearance; `navigationScope="isolated"` creates an independent modal scope. Do not place several active scrollers
+in one screen; designate the primary list explicitly.
+
+`ScreenScrollView` forwards its ref. Scroll restoration remains the independent
+`useScrollRestoration` binding: pass it as `restoration={binding}` and pass the same ref. Pending restored content
+stays laid out with opacity zero; native offset recording is forwarded automatically. Web restoration observes the actual DOM scroller itself.
+
+The shell does not choose a router or create overlay outlets. Measurements settle
+on layout; content footprint stays expanded while visual chrome contracts, avoiding
+scroll-range changes during animation.
+
+For a standalone action, `primaryAction={<Fab ... />}` anchors a static action
+inside the screen. With navigation, pass the action to `BottomBar.action` instead.
+`headerHeight` and `bottomBarHeight` declare initial footprints for custom chrome;
+defaults match Bloom's 56-point header and 58-point bottom bar plus safe area.
+Measured heights replace those estimates. Custom chrome should declare its height
+to prevent the first layout changing the content's padding.
+
+`documentScroll` enables web sticky chrome for a document virtualizer.
+`VirtualList screen={{ active, restoration }}` connects both platforms to the
+screen without a surrounding ScrollView. Use `useScreenWindowScroll` for another
+window virtualizer; `useScreenScroll` remains the animated native/container binding.
+
+When navigation retains whole screens, set `Screen active={focused}` (or
+`AppShell active={focused}`). That boundary disables every descendant scroll
+writer; an explicitly isolated modal keeps its own navigation scope. During restoration,
+offsets update the header but do not trigger a new collapse. On native, showing
+the keyboard hides bottom chrome and releases its reserved content footprint;
+hiding it restores the previous footprint.
+
+AppShell establishes `navigationScope="shared"`. Route Screens use the default
+`inherit`: their local header offset is independent, while the focused list owns
+the shared navigation progress. Set every retained route's `active` explicitly;
+use `navigationScope="isolated"` for modal screens that cover the shell navigation.

package/docs/search.mdx

@@ -14,7 +14,7 @@ import { Search } from '@oxy.so/bloom/search';
 
 <Search
   value={query}
-  onChangeText={setQuery}
+  onValueChange={setQuery}
   onClearText={() => setQuery('')}
   label="Search people"
 />

package/docs/segmented-control.mdx

@@ -16,7 +16,7 @@ import {
   SegmentedControlItemText,
 } from '@oxy.so/bloom/segmented-control';
 
-<SegmentedControl label="Appearance" type="radio" value={mode} onChange={setMode}>
+<SegmentedControl label="Appearance" type="radio" value={mode} onValueChange={setMode}>
   <SegmentedControlItem value="light">
     <SegmentedControlItemText>Light</SegmentedControlItemText>
   </SegmentedControlItem>
@@ -75,13 +75,13 @@ a field the group announces nothing.
 | `label`    | the accessible name of the whole group          |
 | `type`     | radio group vs tab list (see above)             |
 | `value`    | the selected segment — fully controlled         |
-| `onChange` | receives the pressed segment's `value`          |
-| `size`     | `small` (32) · `medium` (36, default) · `large` (44) |
+| `onValueChange` | receives the pressed segment's `value`          |
+| `size`     | `sm` (32) · `md` (36, default) · `lg` (44) |
 | `variant`  | `solid` (track + sliding thumb) or `plain`      |
 
 ## What it looks like
 
-A segmented control, in Bloom's colours. `medium` is the default control:
+A segmented control, in Bloom's colours. `md` is the default control:
 28-tall segments with 10px side padding on a 4px-padded track, 2px apart.
 
 - **Track** neutral-100 (dark: neutral-925); **thumb** the card surface (dark:
@@ -91,7 +91,7 @@ A segmented control, in Bloom's colours. `medium` is the default control:
   is regular weight in neutral-500 and turns primary on hover.
 - Track and thumb are full pills, like `Button`.
 - `variant="plain"` draws no track, padding or thumb.
-- Text is Inter from the type ramp: `body` (`body-2` at `small`), `-medium` when selected and `-regular` when not.
+- Text is Inter from the type ramp: `body` (`body-2` at `sm`), `-medium` when selected and `-regular` when not.
 - Disabled segments sit at 50%; keyboard focus rings the segment (2px).
 
 The control hugs its segments. To fill a row, stretch it (`style={{ alignSelf:
@@ -105,3 +105,16 @@ active from context. Passing one is a type error.
 - More than about four options, or long labels: a [`Select`](/docs/bloom/main/select).
 - A view of the same subject with real panels underneath: [`Tabs`](/docs/bloom/main/tabs).
 - A single on/off: [`Switch`](/docs/bloom/main/switch).
+
+## Drag selection
+
+Drag horizontally to move the thumb continuously across measured segment widths.
+Selection commits once on release; disabled items are skipped and cancellation
+returns to the controlled value. Vertical movement remains available to scrolling.
+Taps and keyboard activation preserve radio/tab semantics. Settling respects the
+system reduced-motion preference. Native apps mount `GestureHandlerRootView` at
+the application root, as for BottomBar. The plain variant also accepts dragging.
+
+## Compatibility
+
+The shared `size`, `tone` and `appearance` vocabulary coexists with the previously published family props. Explicit shared props take precedence over legacy spellings; existing size and state callbacks remain supported. New code should prefer the shared vocabulary.