@oxy.so/bloom 4.16.1 → 4.18.0

package/docs/adoption-matrix.mdx

@@ -37,7 +37,7 @@ The classification is an EQUALITY in `src/__tests__/adoption-matrix.test.ts`, no
 
 | contract | applies to | reads | delegated | n/a¹ | adaptation |
 | --- | --- | --- | --- | --- | --- |
-| Field membership | 46 | 21 | 0 | 20 | 5 |
+| Field membership | 47 | 21 | 0 | 20 | 5 |
 | Control presentation | 16 | 8 | 2 | 6 | 0 |
 | Trigger composition | 10 | 8 | 0 | 2 | 0 |
 | Controlled / uncontrolled state | 49 | 40 | 1 | 1 | 7 |
@@ -122,12 +122,12 @@ The classification is an EQUALITY in `src/__tests__/adoption-matrix.test.ts`, no
 | `agent-log` | `@oxy.so/bloom/agent-log` + barrel | universal | `agent-log.mdx` | yes | 1 |  |  |  |  |
 | `agent-progress` | `@oxy.so/bloom/agent-progress` + barrel | universal | `agent-progress.mdx` | yes | 1 |  |  |  | reads |
 | `agent-thinking` | `@oxy.so/bloom/agent-thinking` + barrel | universal | `agent-thinking.mdx` | yes | 1 |  |  |  |  |
-| `ai-chat` | `@oxy.so/bloom/ai-chat` + barrel | web fork | `ai-chat.mdx` | yes | 7 |  |  |  | reads |
+| `ai-chat` | `@oxy.so/bloom/ai-chat` + barrel | web fork | `ai-chat.mdx` | yes | 9 |  |  |  | reads |
 | `ai-profile-card` | `@oxy.so/bloom/ai-profile-card` + barrel | universal | `ai-profile-card.mdx` | yes | 1 |  |  |  | reads |
 | `alert-dialog` | `@oxy.so/bloom/alert-dialog` + barrel | web fork | `alert-dialog.mdx` | yes | 1 |  |  |  |  |
 | `animated-check` | `@oxy.so/bloom/animated-check` + barrel | universal | `animated-check.mdx` | yes | 2 |  |  |  |  |
 | `announcement` | `@oxy.so/bloom/announcement` + barrel | universal | `announcement.mdx` | yes | 1 |  |  |  |  |
-| `app-shell` | `@oxy.so/bloom/app-shell` + barrel | web fork | `app-shell.mdx` | yes | 3 |  |  |  | reads |
+| `app-shell` | `@oxy.so/bloom/app-shell` + barrel | web fork | `app-shell.mdx` | yes | 5 |  |  |  | reads |
 | `appearance` | `@oxy.so/bloom/appearance` + barrel | universal | `appearance.mdx` | yes | 4 |  |  |  |  |
 | `aspect-ratio` | `@oxy.so/bloom/aspect-ratio` + barrel | universal | `aspect-ratio.mdx` | yes | 1 |  |  |  |  |
 | `auth-card` | `@oxy.so/bloom/auth-card` + barrel | universal | `auth-card.mdx` | yes | 1 |  |  |  |  |
@@ -135,11 +135,11 @@ The classification is an EQUALITY in `src/__tests__/adoption-matrix.test.ts`, no
 | `avatar-group` | `@oxy.so/bloom/avatar-group` + barrel | web fork | `avatar-group.mdx` | yes | 3 |  |  |  |  |
 | `badge` | `@oxy.so/bloom/badge` + barrel | universal | `badge.mdx` | yes | 2 |  |  |  |  |
 | `booking` | `@oxy.so/bloom/booking` + barrel | universal | `booking.mdx` | yes | 3 |  |  |  | reads |
-| `bottom-bar` | `@oxy.so/bloom/bottom-bar` + barrel | web fork | `bottom-bar.mdx` | yes | 1 |  |  |  |  |
+| `bottom-bar` | `@oxy.so/bloom/bottom-bar` + barrel | web fork | `bottom-bar.mdx` | yes | 2 |  |  |  |  |
 | `bottom-sheet` | `@oxy.so/bloom/bottom-sheet` + barrel | web fork | `bottom-sheet.mdx` | yes | 6 |  |  |  |  |
 | `breadcrumb` | `@oxy.so/bloom/breadcrumb` + barrel | universal | `breadcrumb.mdx` | yes | 1 |  |  |  |  |
-| `button` | `@oxy.so/bloom/button` + barrel | web fork | `button.mdx` | yes | 30 |  |  | n/a¹ |  |
-| `button-group` | `@oxy.so/bloom/button-group` + barrel | universal | `button-group.mdx` | yes | 5 |  | reads |  |  |
+| `button` | `@oxy.so/bloom/button` + barrel | web fork | `button.mdx` | yes | 31 |  |  | n/a¹ |  |
+| `button-group` | `@oxy.so/bloom/button-group` + barrel | universal | `button-group.mdx` | yes | 7 |  | reads |  |  |
 | `calendar` | `@oxy.so/bloom/calendar` + barrel | universal | `calendar.mdx` | yes | 1 |  |  |  | reads |
 | `call-ui` | `@oxy.so/bloom/call-ui` + barrel | universal | `call-ui.mdx` | yes | 1 |  |  |  |  |
 | `card` | `@oxy.so/bloom/card` + barrel | universal | `card.mdx` | yes | 3 |  |  |  |  |
@@ -173,7 +173,7 @@ The classification is an EQUALITY in `src/__tests__/adoption-matrix.test.ts`, no
 | `date-picker` | `@oxy.so/bloom/date-picker` + barrel | universal | `date-picker.mdx` | yes | 4 | reads | reads |  | reads |
 | `delivery-slot` | `@oxy.so/bloom/delivery-slot` + barrel | universal | `delivery-slot.mdx` | yes | 2 | reads |  |  |  |
 | `design-tokens` | `@oxy.so/bloom/design-tokens` + barrel | universal | `design-tokens.mdx` | yes | 3 |  |  |  |  |
-| `dialog` | `@oxy.so/bloom/dialog` + barrel | web fork | `dialog.mdx` | yes | 16 |  |  |  |  |
+| `dialog` | `@oxy.so/bloom/dialog` + barrel | web fork | `dialog.mdx` | yes | 17 |  |  |  |  |
 | `directions` | `@oxy.so/bloom/directions` + barrel | universal | `directions.mdx` | yes | 2 |  |  |  |  |
 | `divider` | `@oxy.so/bloom/divider` + barrel | universal | `divider.mdx` | yes | 1 |  |  |  |  |
 | `dot-grid-meter` | `@oxy.so/bloom/dot-grid-meter` + barrel | universal | `dot-grid-meter.mdx` | yes | 2 |  |  |  |  |
@@ -192,10 +192,10 @@ The classification is an EQUALITY in `src/__tests__/adoption-matrix.test.ts`, no
 | `glass` | internal | universal | `glass.mdx` | — | 1 |  | reads |  |  |
 | `grid` | `@oxy.so/bloom/grid` + barrel | universal | `grid.mdx` | yes | 1 |  |  |  |  |
 | `home-search` | `@oxy.so/bloom/home-search` + barrel | universal | `home-search.mdx` | yes | 1 | n/a¹ |  |  |  |
-| `hooks` | `@oxy.so/bloom/hooks` + barrel | universal | `hooks.mdx` | yes | 10 |  |  |  | reads |
+| `hooks` | `@oxy.so/bloom/hooks` + barrel | universal | `hooks.mdx` | yes | 11 |  |  |  | reads |
 | `hover-card` | `@oxy.so/bloom/hover-card` + barrel | web fork | `hover-card.mdx` | yes | 2 |  |  | reads | reads |
 | `icon-circle` | `@oxy.so/bloom/icon-circle` + barrel | universal | `icon-circle.mdx` | yes | 1 |  |  |  |  |
-| `icons` | `@oxy.so/bloom/icons` + barrel | universal | `icons.mdx` | yes | 48 |  |  |  |  |
+| `icons` | `@oxy.so/bloom/icons` + barrel | universal | `icons.mdx` | yes | 51 |  |  |  |  |
 | `image-aspect-ratio-cache` | `@oxy.so/bloom/image-aspect-ratio-cache` + barrel | universal | `image-aspect-ratio-cache.mdx` | yes | 1 |  |  |  |  |
 | `image-resolver` | `@oxy.so/bloom/image-resolver` + barrel | universal | `image-resolver.mdx` | yes | 7 |  |  |  |  |
 | `important-alerts-card` | `@oxy.so/bloom/important-alerts-card` + barrel | universal | `important-alerts-card.mdx` | yes | 1 |  |  |  |  |
@@ -213,7 +213,7 @@ The classification is an EQUALITY in `src/__tests__/adoption-matrix.test.ts`, no
 | `listing-card` | `@oxy.so/bloom/listing-card` + barrel | universal | `listing-card.mdx` | yes | 4 |  |  |  |  |
 | `listing-details` | `@oxy.so/bloom/listing-details` + barrel | universal | `listing-details.mdx` | yes | 4 |  |  |  | reads |
 | `listing-editor` | `@oxy.so/bloom/listing-editor` + barrel | universal | `listing-editor.mdx` | yes | 1 | **adaptation** |  |  | reads |
-| `loading` | `@oxy.so/bloom/loading` + barrel | web fork | `loading.mdx` | yes | 2 |  |  |  |  |
+| `loading` | `@oxy.so/bloom/loading` + barrel | web fork | `loading.mdx` | yes | 3 |  |  |  |  |
 | `location-puck` | `@oxy.so/bloom/location-puck` + barrel | universal | `location-puck.mdx` | yes | 1 |  |  |  |  |
 | `lyrics` | `@oxy.so/bloom/lyrics` + barrel | universal | `lyrics.mdx` | yes | 2 |  |  |  |  |
 | `mail-compose` | `@oxy.so/bloom/mail-compose` + barrel | universal | `mail-compose.mdx` | yes | 2 | reads |  |  | reads |
@@ -257,7 +257,7 @@ The classification is an EQUALITY in `src/__tests__/adoption-matrix.test.ts`, no
 | `place-list` | `@oxy.so/bloom/place-list` + barrel | universal | `place-list.mdx` | yes | 1 |  |  |  |  |
 | `place-reviews` | `@oxy.so/bloom/place-reviews` + barrel | universal | `place-reviews.mdx` | yes | 1 |  |  |  | reads |
 | `popover` | `@oxy.so/bloom/popover` + barrel | web fork | `popover.mdx` | yes | 7 |  |  | reads | reads |
-| `portal` | `@oxy.so/bloom/portal` + barrel | web fork | `portal.mdx` | yes | 15 |  |  |  |  |
+| `portal` | `@oxy.so/bloom/portal` + barrel | web fork | `portal.mdx` | yes | 18 |  |  |  |  |
 | `pressable-scale` | `@oxy.so/bloom/pressable-scale` + barrel | universal | `pressable-scale.mdx` | yes | 1 |  |  |  |  |
 | `price-breakdown` | `@oxy.so/bloom/price-breakdown` + barrel | universal | `price-breakdown.mdx` | yes | 3 |  |  |  | reads |
 | `progressive-blur` | `@oxy.so/bloom/progressive-blur` + barrel | web fork | `progressive-blur.mdx` | yes | 1 |  |  |  |  |
@@ -280,7 +280,7 @@ The classification is an EQUALITY in `src/__tests__/adoption-matrix.test.ts`, no
 | `settings-list` | `@oxy.so/bloom/settings-list` + barrel | universal | `settings-list.mdx` | yes | 5 |  |  |  |  |
 | `settings-modal` | `@oxy.so/bloom/settings-modal` + barrel | universal | `settings-modal.mdx` | yes | 3 |  |  |  | reads |
 | `shipment-request` | `@oxy.so/bloom/shipment-request` + barrel | universal | `shipment-request.mdx` | yes | 1 | **adaptation** |  |  |  |
-| `sidebar` | `@oxy.so/bloom/sidebar` + barrel | universal | `sidebar.mdx` | yes | 6 | n/a¹ |  |  | reads |
+| `sidebar` | `@oxy.so/bloom/sidebar` + barrel | universal | `sidebar.mdx` | yes | 8 | n/a¹ |  |  | reads |
 | `skeleton` | `@oxy.so/bloom/skeleton` + barrel | universal | `skeleton.mdx` | yes | 1 |  |  |  |  |
 | `slider` | `@oxy.so/bloom/slider` + barrel | universal | `slider.mdx` | yes | 4 | reads |  |  |  |
 | `social-button` | `@oxy.so/bloom/social-button` + barrel | universal | `social-button.mdx` | yes | 1 |  |  |  |  |
@@ -290,12 +290,12 @@ The classification is an EQUALITY in `src/__tests__/adoption-matrix.test.ts`, no
 | `stay-filters` | `@oxy.so/bloom/stay-filters` + barrel | universal | `stay-filters.mdx` | yes | 4 | n/a¹ |  |  |  |
 | `stay-search` | `@oxy.so/bloom/stay-search` + barrel | universal | `stay-search.mdx` | yes | 4 |  |  |  |  |
 | `stepper` | `@oxy.so/bloom/stepper` + barrel | universal | `stepper.mdx` | yes | 3 | reads |  |  |  |
-| `styles` | `@oxy.so/bloom/styles` + barrel | universal | `styles.mdx` | yes | 65 |  |  |  |  |
+| `styles` | `@oxy.so/bloom/styles` + barrel | universal | `styles.mdx` | yes | 66 | **UNCLASSIFIED** |  |  |  |
 | `subtle-hover` | `@oxy.so/bloom/subtle-hover` + barrel | universal | `subtle-hover.mdx` | yes | 1 |  |  |  |  |
 | `surfaces` | `@oxy.so/bloom/surfaces` + barrel | web fork | `alert.mdx` | yes | 2 |  |  |  |  |
 | `swipe-row` | `@oxy.so/bloom/swipe-row` + barrel | universal | `swipe-row.mdx` | yes | 1 |  |  |  |  |
 | `switch` | `@oxy.so/bloom/switch` + barrel | universal | `switch.mdx` | yes | 6 | reads |  |  |  |
-| `tab-bar` | `@oxy.so/bloom/tab-bar` | web fork | `tab-bar.mdx` | yes | 12 |  |  | reads |  |
+| `tab-bar` | `@oxy.so/bloom/tab-bar` | web fork | `tab-bar.mdx` | yes | 13 |  |  | reads |  |
 | `table` | `@oxy.so/bloom/table` + barrel | universal | `table.mdx` | yes | 1 |  |  |  |  |
 | `tabs` | `@oxy.so/bloom/tabs` + barrel | universal | `tabs.mdx` | yes | 3 |  |  |  |  |
 | `tag-field` | `@oxy.so/bloom/tag-field` + barrel | universal | `tag-field.mdx` | yes | 2 | reads | reads |  |  |
@@ -304,7 +304,7 @@ The classification is an EQUALITY in `src/__tests__/adoption-matrix.test.ts`, no
 | `tenancy` | `@oxy.so/bloom/tenancy` + barrel | universal | `tenancy.mdx` | yes | 3 |  | n/a¹ |  |  |
 | `text-field` | `@oxy.so/bloom/text-field` + barrel | universal | `text-field.mdx` | yes | 13 | reads | reads |  |  |
 | `textarea` | `@oxy.so/bloom/textarea` + barrel | universal | `textarea.mdx` | yes | 4 | reads | reads |  | n/a¹ |
-| `theme` | `@oxy.so/bloom/theme` + barrel | web fork | `theme.mdx` | yes | 295 |  |  | n/a¹ | reads |
+| `theme` | `@oxy.so/bloom/theme` + barrel | web fork | `theme.mdx` | yes | 303 |  |  | n/a¹ | reads |
 | `theme-toggle` | `@oxy.so/bloom/theme-toggle` + barrel | universal | `theme-toggle.mdx` | yes | 1 | n/a¹ |  |  |  |
 | `toast` | `@oxy.so/bloom/toast` + barrel | universal | `toast.mdx` | yes | 17 |  |  |  |  |
 | `tooltip` | `@oxy.so/bloom/tooltip` + barrel | web fork | `tooltip.mdx` | yes | 1 |  |  |  |  |

package/docs/app-shell.mdx

@@ -628,8 +628,9 @@ panel at rest and during scroll.
 `gutter` and the aside gap. The social template uses `navigationGap={0}` to bring
 plain navigation up to the reading panel while retaining the panel frame insets.
 
-A document-scrolling, content-aligned shell with a plain sidebar and no top bar
-has no root padding. The sidebar spans the viewport; the reading/context group
+A content-aligned shell with a plain sidebar and no top bar has no root padding,
+whichever way it scrolls: native resolves every shell to container scroll, and
+the same layout draws the same frame there as on the web. The sidebar spans the viewport; the reading/context group
 owns the vertical gutter, which still supplies the panel mask and header inset.
 The social template uses an 8px gutter, matching the compact framed layout.
 

package/docs/breadcrumb.mdx

@@ -35,6 +35,16 @@ An item is a **link** with `href`, a **button** with `onPress`, and a plain labe
 
 The list scrolls horizontally, with no scrollbar, when it outgrows its container. Bloom uses a full pill, like every other pressable, rather than a 6px corner.
 
+### Right-to-left and custom separators
+
+The chevron points the READING direction. In a right-to-left layout (`<html dir="rtl">` on web, `I18nManager.isRTL` natively) the row mirrors, and the chevron flips with it (`scaleX(-1)`, read from `useIsRtl()`) so it still points from each crumb to the next. The landmark also carries `dir` on web, so react-native-web resolves logical keys against it.
+
+`separator` replaces the chevron with any node — a `"/"`, a dot, an icon. It is hidden from assistive tech like the chevron, and rendered as given: a custom glyph that has a direction is the caller's to mirror.
+
+```tsx
+<Breadcrumb separator={<Text variant="caption-1-medium">/</Text>}>…</Breadcrumb>
+```
+
 ### `href` and routers
 
 On web an `href` item is a real `<a href>`, so middle-click and "open in new tab" work. Pass `onPress` too and the browser's navigation is prevented so the router can navigate instead. On native, an `href` item without `onPress` opens the URL with `Linking`.
@@ -48,6 +58,7 @@ On web an `href` item is a real `<a href>`, so middle-click and "open in new tab
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
 | `Breadcrumb.accessibilityLabel?` | `string` | `'Breadcrumb'` | Names the landmark. |
+| `Breadcrumb.separator?` | `ReactNode` | direction-aware chevron | Replaces the chevron between items; hidden from assistive tech. |
 | `BreadcrumbItem.href?` | `string` | — | Makes the item a link. |
 | `BreadcrumbItem.onPress?` | `() => void` | — | Makes the item a button (or routes an `href`). |
 | `BreadcrumbItem.current?` | `boolean` | `false` | The active page. |

package/docs/button-group.mdx

@@ -79,7 +79,7 @@ Use `checked` with `onCheckedChange` for a controlled boolean toggle. `onPress`
 | padding-x | 12 | 10 |
 | icon | 20 | 18 |
 
-Text is `body-medium` (Inter 14/20 500) through Bloom's typography `Text` — a bare React Native `Text` falls back to the system font. Pass icon components to `leadingIcon` / `trailingIcon`; `iconOnly` makes a square item that needs `accessibilityLabel`.
+Text is `body-medium` (Inter 14/20 500) through Bloom's typography `Text` — a bare React Native `Text` falls back to the system font. Pass icon components to `leadingIcon` / `trailingIcon`; `iconOnly` makes a square item that needs `accessibilityLabel`. An app whose own icons take `size`/`color` rather than `width`/`height`/`fill` uses `renderLeadingIcon={({ size, color }) => …}` instead — see [Icons](/docs/icons).
 
 ## Props
 
@@ -94,6 +94,7 @@ Text is `body-medium` (Inter 14/20 500) through Bloom's typography `Text` — a
 | `ButtonGroupItem.disabled?` | `boolean` | `false` | Disabled paint, blocks presses. |
 | `ButtonGroupItem.iconOnly?` | `boolean` | `false` | Square icon-only item. |
 | `ButtonGroupItem.leadingIcon?` / `trailingIcon?` | `BloomIconComponent` | — | Icon components. |
+| `ButtonGroupItem.renderLeadingIcon?` / `renderTrailingIcon?` | `BloomIconRenderer` | — | Draw the glyph yourself, handed `{ size, color }` for the current state — for an app's own icon set. Wins over the icon component. [Icons](/docs/icons). |
 | `ButtonGroupItem.size?` | `'md' \| 'sm'` | group size | Per-item override. |
 | `ButtonGroupItem.material?` | `'solid' \| 'glass'` | group material | Per-item override. Rarely needed — the group owns it. |
 | `ButtonGroupItem.hitSlop?` | `number \| {top,bottom,left,right}` | — | Extra touch area. NOT defaulted: items in a group are adjacent, so slop on one overlaps its neighbour. Use it for an item that stands alone in its own island. |

package/docs/button.mdx

@@ -32,6 +32,30 @@ The pressable is the parent's layout child: `className` and `style` are applied
 
 See [Component contract](./appearance.mdx) for inheritance and [Migration](./coherent-system-migration.mdx) for the clean API cut.
 
+## An app's own icon set
+
+`leadingIcon` and `trailingIcon` take a `BloomIconComponent` — `width`, `height`,
+`fill` — and an app icon set usually spells that `size` and `color`. The two have
+no property in common, so the icon does not typecheck against the slot, and
+casting only moves the failure: Bloom tints by passing `fill`, so a glyph that
+paints from `color` renders at its default colour with nothing thrown.
+
+`renderLeadingIcon` / `renderTrailingIcon` hand the drawing back, with the box
+and the foreground for the current state. They win over the icon component, and
+supply the glyph for `iconOnly`.
+
+```tsx
+<Button
+  iconOnly
+  accessibilityLabel="Search"
+  renderLeadingIcon={({ size, color }) => <AppSearchGlyph size={size} color={color} />}
+/>
+```
+
+On web `color` is `currentColor`, so the glyph follows the stylesheet's state
+colours without a re-render; native gets the resolved value. Full rationale, and
+why this is a separate prop rather than a wider `leadingIcon`: [Icons](/docs/icons).
+
 ## 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.

package/docs/cart-panel.mdx

@@ -43,10 +43,12 @@ Inline in a desktop sidebar it is dropped in a `Card`; on a phone it is what a `
 
 Which is why the vendor is a header and not a field on every line. Switching vendor is a different action — it empties the basket — and this component does not offer it.
 
-## The stepper does not remove
+## The stepper does not remove — unless you ask
 
 `CartLine`'s stepper has a floor of **1**, and removing is its own control with its own accessible name. A stepper that deletes the line when you press `−` once too often is a destructive action hiding behind an arithmetic one, and it has no label saying so.
 
+`removeInStepper` (on `CartLine`, and on `CartPanel` for every line) opts into the storefront pattern instead: at quantity 1 the `−` becomes a trash button NAMED as removal — `removeLabel`, default `"Remove <name>"` — through `Stepper`'s `onRemove`, and the separate remove control is not drawn. It needs both `onQuantityChange` and `onRemove`. A sold-out line keeps the separate control, because its stepper is disabled and could not remove anything.
+
 The line is never pressable, which is what lets its controls live inside it: a pressable `Item` is a real `<button>` on web, and a control inside one is invalid HTML whose click also fires the row. Editing a line's options is `MenuItemOptions` in a sheet, opened from the dish rather than from a row that is mostly controls.
 
 ## The promo field has two states, not one
@@ -71,6 +73,6 @@ Once the order is placed it belongs to `order-status`: `OrderStatusTimeline` for
 
 ## Traps
 
-- **Every amount is a string.** `price` on a line is the line's own total, already multiplied by `quantity` **by the app**. Nothing here multiplies, converts or rounds.
+- **Every amount is a string.** `price` on a line is the line's own total, already multiplied by `quantity` **by the app**. Nothing here multiplies, converts or rounds. A second currency is `secondaryPrice` (`"≈ 12,00 €"`), drawn de-emphasised under the price and added to the line's accessible name after it — `listing-card`'s `ListingPriceLine.secondary`, spelled after this family's `price`. The totals take `secondaryAmount` on their `PriceLine`s.
 - **The empty basket hides everything after the lines.** No tip picker, no promo field, no totals and no checkout button — each of them would be a control acting on nothing.
 - **`CartLine` takes the line's fields, not the entry.** `CartLineEntry` carries the `id` the panel keys and reports by; the standalone component takes the rest, so a caller cannot pass an id that reaches nothing.

package/docs/checkout-summary.mdx

@@ -88,3 +88,7 @@ screen and a button reading "Place order" are two, and the gap between them is w
 reader confirms a figure they last saw before a tip picker changed it. The separator is a
 middle dot: "Place order - €49.62" reads as a subtraction at a glance in a row that is
 otherwise full of money.
+
+The button carries ONE amount — the one the charge is made in. A second currency is
+`secondaryAmount` (`"≈ 49,62 €"`), pre-formatted like `amount` and drawn de-emphasised,
+centred 8 under the button, above the terms.

package/docs/chip.mdx

@@ -66,16 +66,29 @@ The hues sit BESIDE the accent recipe, not inside it: `resolveAccentColors` is u
 
 ### Role
 
-A pressable chip's ROLE decides which state attribute it carries, and the three are not interchangeable:
+A pressable chip's ROLE decides which state attribute it carries, and the four are not interchangeable:
 
 | `role` | web | native |
 |---|---|---|
 | `button` (default) | `aria-pressed` | `accessibilityState.selected` |
+| `checkbox` | `aria-checked` | `accessibilityState.checked` |
 | `radio` | `aria-checked` | `accessibilityState.checked` |
 | `tab` | `aria-selected` | `accessibilityState.selected` |
 
 `aria-pressed` is invalid on a radio and on a tab, which is what this component used to emit for every one of them. Put a `radio` inside a `role="radiogroup"` and a `tab` inside a `role="tablist"` — `ChipRow` takes that role for you.
 
+A multi-select filter row (brands, sizes, amenities — any number on at once) is a `group` of `checkbox` chips: a screen reader then says "checked"/"not checked" rather than "pressed", which is what a filter is. `onCheckedChange` receives the next state.
+
+```tsx
+<ChipRow accessibilityLabel="Brand">
+  {brands.map((brand) => (
+    <Chip key={brand} role="checkbox" checked={picked.has(brand)} onCheckedChange={(on) => toggle(brand, on)}>
+      {brand}
+    </Chip>
+  ))}
+</ChipRow>
+```
+
 On web, `tabIndex` and `onKeyDown` are passed through for a roving-tabindex row (one tab stop, arrows move focus). Both are inert on native. A chip also forwards a ref to its pressable, so a row can focus one.
 
 ### `inverted`

package/docs/dialog.mdx

@@ -6,7 +6,7 @@ order: 3
 
 # Dialog
 
-A single `<Dialog>` component for every overlay surface — centered modal, side-sheet (left/right drawer), or bottom-sheet — controlled by the `placement` prop. Same component, same props on every platform.
+A single `<Dialog>` component for every overlay surface — centered modal, side-sheet (left/right or logical start/end drawer), or bottom-sheet — controlled by the `placement` prop. Same component, same props on every platform.
 
 <Callout variant="warning" title="Required providers (native)">
 Your app root **must** be wrapped with `GestureHandlerRootView` from `react-native-gesture-handler` for the bottom-sheet pan gestures to work. See [Getting started](/docs/bloom/main/getting-started).
@@ -105,7 +105,7 @@ Drop the declarative props entirely — `children` owns every pixel.
 | `children?` | `React.ReactNode` | — | Custom content rendered after the description. |
 | `onClose?` | `() => void` | — | Fires after the dialog finishes closing. In controlled mode, the host flips `open` to `false`. |
 | `contentPadding?` | `number` | `20` | Inner padding of the dialog body (px). Set `0` for custom children that own their insets. |
-| `width?` | `number` | `460` | Side-sheet width (px) on `left`/`right` placements. |
+| `width?` | `number` | `460` | Side-sheet width (px) on `left`/`right`/`start`/`end` placements. |
 | `maxWidth?` | `number` | `480` | Centered-card max width (px). |
 | `maxHeightRatio?` | `number` | `0.9` | Bottom-sheet max height as a fraction of the viewport height. |
 | `inset?` | `{ top?; bottom?; left?; right? }` | — | Side-sheet inset (px) from the overlay container edges. |
@@ -123,7 +123,7 @@ Drop the declarative props entirely — `children` owns every pixel.
 `placement` accepts a single value or a **responsive map** resolved by `useWindowDimensions()`:
 
 ```ts
-type DialogPlacement = 'center' | 'left' | 'right' | 'bottom';
+type DialogPlacement = 'center' | 'left' | 'right' | 'start' | 'end' | 'bottom';
 
 type ResponsiveDialogPlacement =
   | DialogPlacement
@@ -134,7 +134,8 @@ Breakpoints (px): `sm` 640 / `md` 768 / `lg` 1024 / `xl` 1280. The largest break
 
 Per-placement behavior:
 - `center` — DOM-portal modal (web) / detached floating card (native).
-- `left` / `right` — animated side-sheet anchored to the viewport edge.
+- `left` / `right` — animated side-sheet anchored to that PHYSICAL viewport edge.
+- `start` / `end` — the same side-sheet on the LOGICAL edge: `start` is the left in a left-to-right layout and the right in a right-to-left one (`end` the reverse), read from `useIsRtl()`, and the panel slides in from that edge. The matching `inset` side applies (`inset.right` for `start` in RTL). On native the panel is positioned with `insetInlineStart`/`insetInlineEnd`, which Yoga resolves against `I18nManager` — a physical `left`/`right` would be swapped by React Native's default `swapLeftAndRightInRTL`. On web the drawer is portaled outside any `dir` context, so it takes the physical edge `useIsRtl()` names. An app that ships Arabic or Hebrew wants `start`/`end`: `{ base: 'bottom', md: 'start' }` is the mirrored store drawer.
 - `bottom` — reuses the cross-platform `BottomSheet` on BOTH web and native (drag-to-dismiss + internal scroll work everywhere). Custom `children` on bottom placement are rendered in a NON-scrollable body — children own scrolling.
 
 ### `DialogAction`

package/docs/icons.mdx

@@ -131,6 +131,59 @@ the chat parts label their glyphs for tests.
 Those are deliberate and stay. Reaching for `Props` when you only set
 width/height/fill is not: it refuses a caller's own glyph for no benefit.
 
+### Your OWN icon set: `renderLeadingIcon`
+
+`BloomIconComponent` is the widest *component* a slot can take, but it is still
+a shape: `width`, `height`, `fill`. An app icon set usually spells the same idea
+`size` and `color`, and those two prop sets have **nothing in common** — so the
+icon does not typecheck against the slot, and casting it does not help either.
+Bloom tints by passing `fill`; an icon that paints from `color` renders fine and
+never takes the tint, with nothing thrown. `frosted-icon-button/shared.ts` and
+`tab-bar/types.ts` both record that hazard.
+
+Passing `color` alongside `fill` is not the answer, for the reason
+`applyIconColor` gives: the prop is not Bloom's to claim, because components use
+it for semantic variants (`color="danger"`).
+
+So the slot families expose a second prop that hands the drawing back to you,
+with the box and the foreground for the CURRENT state:
+
+```tsx
+import { RiSearchLine } from '@oxy.so/bloom/icons/RiSearchLine';
+
+// Bloom's own glyph: the component, sized and tinted for you.
+<ButtonGroupItem iconOnly leadingIcon={RiSearchLine} accessibilityLabel="Search" />
+
+// Your app's glyph, whose props are `size` and `color`.
+<ButtonGroupItem
+  iconOnly
+  renderLeadingIcon={({ size, color }) => <AppSearchGlyph size={size} color={color} />}
+  accessibilityLabel="Search"
+/>
+```
+
+```ts
+type BloomIconPaint = { size: number; color: string };
+type BloomIconRenderer = (paint: BloomIconPaint) => ReactNode;
+```
+
+Where a family offers both, the renderer WINS, which is the rule `GlyphButton`
+already uses for a caller-painted `children` over `icon`.
+
+**On web `color` is `currentColor`.** Bloom paints web glyphs that way so they
+follow the state colours the stylesheet sets without a re-render; native has no
+cascade and gets the resolved value. Either way, passing it straight to your
+icon's `color` is correct.
+
+**Why a separate prop and not a wider `leadingIcon`.** The adapter a caller
+writes today — `({ width, fill }) => <Glyph size={width} color={fill} />` — is a
+function, and so is a paint callback. One prop taking both could not tell them
+apart, and would silently re-interpret every existing adapter. Both forms are
+pinned in `src/__tests__/icon-render-slot.test.tsx`.
+
+Today this is on `Button` and `ButtonGroupItem`. The other icon slots still take
+the component only.
+
 ### The per-family names still work
 
 Twenty-five families had declared this same type under their own name

package/docs/loading.mdx

@@ -52,6 +52,16 @@ For native-tailwind users, `className` overrides `color`:
 <Loading variant="spinner" className="text-primary" />
 ```
 
+## Accessibility
+
+A spinner draws no words, so nothing but a name can tell a screen reader what is loading. Pass `accessibilityLabel` and the indicator becomes an indeterminate `progressbar`: `role="progressbar"`, `aria-label` and `aria-busy="true"` on web (flat `aria-*`, because react-native-web drops `accessibilityState`), the same role, label and busy state natively, and deliberately **no** `aria-valuenow` — that omission is how ARIA says "indeterminate". The `top` bar carries it only while `showLoading`.
+
+```tsx
+<Loading accessibilityLabel="Loading results" />
+```
+
+It is opt-in, so an unlabelled `Loading` renders exactly as before, with no role. That is right when the spinner sits INSIDE something already announcing the wait — an upload tile's own named progressbar — where a second one would say it twice.
+
 ## Props
 
 ### Shared
@@ -64,6 +74,7 @@ For native-tailwind users, `className` overrides `color`:
 | `className?` | `string` | NativeWind class. Overrides `color`. |
 | `style?` | `ViewStyle` | Container style. |
 | `showLoading?` | `boolean` | For animated variants — pause when false. |
+| `accessibilityLabel?` | `string` | Names the indicator and makes it an indeterminate `progressbar`. See [Accessibility](#accessibility). |
 | `testID?` | `string` | |
 
 ### `spinner`

package/docs/page-header.mdx

@@ -286,3 +286,10 @@ The provider accepts the existing `scrollY` shared value or inherits `Screen`'s.
 Native lists retain sticky ownership and consume `useHeaderDockInset()` as their
 supported sticky-header offset; see [layout](./layout.mdx). Storybook's
 **Profile Docking** demonstrates the document-scroll composition.
+
+For a native list behind the header, use `placement="overlay"` and let the list
+consume `useHeaderDockInset()` for sticky clearance. This absolute header has
+both a local stacking index and native elevation: Android scroll surfaces can
+otherwise paint over its controls. `placement="overlap"` is the document-scroll
+composition for web. Keep the header and list in the same unclipped parent;
+no descendant elevation can escape an ancestor's clipping bounds.

package/docs/price-breakdown.mdx

@@ -37,6 +37,23 @@ 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"`.
 
+### A second currency
+
+`secondaryAmount` — on a `PriceLine` and on the `total` — is a second, pre-formatted
+rendering of the same amount, drawn under it in `body-2-regular` at the secondary rung,
+tabular and right-aligned: the buyer's currency beside the shop's.
+
+```tsx
+<PriceSummary
+  lines={[{ label: 'Subtotal', amount: '$13.20', secondaryAmount: '≈ 12,00 €' }]}
+  total={{ label: 'Total', amount: '$15.20', secondaryAmount: '≈ 13,82 €' }}
+/>
+```
+
+It is the same contract as `amount`: drawn as given, never converted. The name follows
+the family's own `amount`; `listing-card`'s `ListingPriceLine.secondary` and
+`cart-panel`'s `secondaryPrice` are the same idea on those families' `price`.
+
 ## The three tones
 
 | tone | what it is for |

package/docs/rating.mdx

@@ -32,6 +32,11 @@ const [stars, setStars] = useState<number | null>(null);
 | `reviewsLabel`       | the word after the count, default `"reviews"` — translate it                            |
 | `newLabel`           | drawn instead of the value when there is no rating yet, default `"New"`                 |
 | `size`               | `'small'` (14px star, body-2 text) or `'medium'` (default, 16px star, body text)        |
+| `variant`            | `'compact'` (default, one star) or `'stars'` (five stars, filled fractionally, before the value) |
+| `color`              | paints the star(s), the value and the count — e.g. white over a brand-coloured hero      |
+| `starColor`          | the filled star(s) only (a gold star beside neutral text); default `color`               |
+| `countColor`         | the count only; default `color` when given, else text-secondary                          |
+| `emptyStarColor`     | `stars` only: the unfilled part of each star; default the border colour                   |
 | `accessibilityLabel` | replaces the composed name — pass a translated sentence                                 |
 | `style`, `testID`    |                                                                                          |
 
@@ -41,6 +46,23 @@ named "Rated 4.92 out of 5, 128 reviews", so a screen reader does not read the
 star, the number and the brackets as separate items. That sentence is English;
 apps in other languages pass `accessibilityLabel`.
 
+### Five stars, and colour
+
+`variant="stars"` draws a row of five stars 2px apart instead of the single
+star. Each is the unfilled star (`emptyStarColor`) with the filled star clipped
+over it to its share of the value — 4.3 fills four stars and 30% of the fifth. A
+string `value` is parsed for the fill and drawn as given. The clip is anchored
+with a logical inset, so in a right-to-left layout the row fills from the right
+(the root carries `dir` on web for react-native-web to resolve it). The row
+stays ONE named image, like the compact rating.
+
+```tsx
+<Rating variant="stars" value={4.3} count={128} color="#fff" emptyStarColor="rgba(255,255,255,0.35)" />
+```
+
+Over a surface the theme's text pair cannot sit on — a brand-coloured hero — pass
+`color`; the default text-primary/text-secondary are measured against the PAGE.
+
 ## `RatingBar`
 
 | prop         | decides                                                                     |

package/docs/stepper.mdx

@@ -36,6 +36,7 @@ import { Stepper, StepperRow } from '@oxy.so/bloom/stepper';
 | `formatValue`                       | the drawn and announced text, e.g. `(n) => (n === 8 ? '8+' : String(n))` |
 | `accessibilityLabel`                | **required** — what is being counted                                     |
 | `decrementLabel` / `incrementLabel` | the buttons' names, default `"Decrease"` / `"Increase"` — translate them  |
+| `onRemove` / `removeLabel`          | opt-in: at `min` the `−` becomes a trash button named `removeLabel` (default `"Remove"`) that calls `onRemove`; without it the button disables at `min` |
 | `style`, `testID`                   | the row; `testID` also derives `-decrement`, `-value`, `-increment`      |
 
 `StepperRow` takes every `Stepper` prop plus `title`, `description`, `divider`
@@ -53,6 +54,30 @@ import { Stepper, StepperRow } from '@oxy.so/bloom/stepper';
 - **Row** title `headline-medium` text-primary over a `body-regular`
   text-secondary description, the stepper on the right, 16 above and below.
 
+## Remove at the floor
+
+By default the stepper floors at `min` and the `−` disables there. A basket line
+that should go from 1 to gone opts in with `onRemove`:
+
+```tsx
+<Stepper
+  value={quantity}
+  min={1}
+  onValueChange={setQuantity}
+  onRemove={removeLine}
+  removeLabel={`Remove ${name}`}
+  accessibilityLabel={name}
+/>
+```
+
+At `min` the `−` draws `RiDeleteBinLine`, is named `removeLabel`, stays enabled
+and calls `onRemove` rather than `onValueChange`. Above `min` it is the ordinary
+decrement. Only the BUTTON removes: ArrowDown, Home and the native `decrement`
+action on the value still stop at `min`, because a key or a swipe that deletes is
+a destructive action behind an arithmetic one. So that a keyboard user can
+reach it, the remove button joins the tab order (the decrement never does). A
+`disabled` stepper offers no removal.
+
 ## Accessibility
 
 The stepper is a `group` named by `accessibilityLabel` — or, inside a

package/docs/tabs.mdx

@@ -142,3 +142,9 @@ hover row and the `filled` thumb are steps off that surface.
 The rail used to be `neutral-800` in dark — the exact fill `QueuePanel` (and
 every other menu-surface family) paints its panel with, **ΔE 0**. A tab strip
 inside one had no rail. On the page the rail lands within 0.04 of its old colour.
+
+The scrolling tab viewport keeps its intrinsic height (`flexGrow: 0`,
+`flexShrink: 0`). This matters in native columns above virtualized lists:
+React Native's default ScrollView growth otherwise takes space from the feed,
+even when the caller gives the tab strip a fixed height. Caller `style` still
+styles the strip content, including its height, padding, and separator.

package/lib/commonjs/app-shell/AppShellEngine.js

@@ -578,7 +578,11 @@ function createAppShellEngine(ContentPanel, BloomColorScope) {
     // Plain navigation belongs to the viewport; only the reading surfaces are inset.
     const documentPanelInset = feedRevealed ? 12 : compactPanel ? 0 : gutter;
     const externalTopHeight = showTopBar ? topBarHeight : 0;
-    const plainDocumentFrame = doc && contentAligned && flowSidebar?.surface === 'plain' && !topBarNode;
+    // A property of the NAVIGATION, not of who scrolls: native resolves every
+    // shell to container scroll, and gating this on `document` left native
+    // phones with an 8px frame around the reading panel that the same layout on
+    // the web does not draw.
+    const plainFrame = contentAligned && flowSidebar?.surface === 'plain' && !topBarNode;
     const readingGap = Math.max(0, asideGap ?? columnGap);
     const readingGroupWidth = contentWidth + (asideBeside ? asideWidth + readingGap : 0);
     const centredBody = /*#__PURE__*/(0, _jsxRuntime.jsxs)(_reactNative.View, {
@@ -598,7 +602,7 @@ function createAppShellEngine(ContentPanel, BloomColorScope) {
           flexBasis: compactPanel ? 'auto' : readingGroupWidth,
           maxWidth: compactPanel ? undefined : readingGroupWidth
         } : {}),
-        ...(plainDocumentFrame ? {
+        ...(plainFrame ? {
           paddingTop: compactPanel ? 0 : gutter,
           paddingBottom: compactPanel ? 0 : gutter
         } : {})
@@ -840,7 +844,7 @@ function createAppShellEngine(ContentPanel, BloomColorScope) {
     const dockedNav = navInFlow && flowSidebar?.surface === 'docked';
     const navRegion = navInFlow && flowSidebar ? doc ? /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.View, {
       testID: testID ? `${testID}-navigation` : undefined,
-      style: (0, _layout.stickyRail)(dockedNav || plainDocumentFrame ? 0 : gutter),
+      style: (0, _layout.stickyRail)(dockedNav || plainFrame ? 0 : gutter),
       children: /*#__PURE__*/(0, _jsxRuntime.jsx)(_index2.Sidebar, {
         ...flowSidebar
       })
@@ -908,9 +912,9 @@ function createAppShellEngine(ContentPanel, BloomColorScope) {
         paddingTop: 0,
         paddingBottom: 0,
         paddingInlineStart: 0,
-        paddingInlineEnd: canvas || plainDocumentFrame ? 0 : gutter
+        paddingInlineEnd: canvas || plainFrame ? 0 : gutter
       } : {
-        padding: canvas || plainDocumentFrame ? 0 : gutter
+        padding: canvas || plainFrame ? 0 : gutter
       }),
       backgroundColor: background
     };