@oxy.so/bloom 2.9.0 → 2.11.0

package/README.md

@@ -20,7 +20,7 @@
 
 ### What it is
 
-Components, hooks and design tokens published as `@oxy.so/bloom` across 139 subpath exports, shipped as `src` for Metro and as compiled CommonJS and ESM for everyone else. Web builds resolve platform forks automatically through export conditions, so a `.web.tsx` fork never reaches a native bundle.
+Components, hooks and design tokens published as `@oxy.so/bloom` across 167 subpath exports, shipped as `src` for Metro and as compiled CommonJS and ESM for everyone else. Web builds resolve platform forks automatically through export conditions, so a `.web.tsx` fork never reaches a native bundle.
 
 Styling is NativeWind classes throughout. There are no colour props and no wrapper components to theme a button, because a second way to set a colour is a second thing that can disagree.
 
@@ -151,7 +151,7 @@ Every palette is generated from a single seed colour by a dependency free colour
 
 ## Components
 
-Bloom publishes 139 subpath exports. Importing from the subpath rather than the root keeps a bundle to what it actually renders.
+Bloom publishes 167 subpath exports. Importing from the subpath rather than the root keeps a bundle to what it actually renders.
 
 | Group | Exports |
 |---|---|
@@ -159,12 +159,15 @@ Bloom publishes 139 subpath exports. Importing from the subpath rather than the
 | App shell and navigation | `app-shell`, `page-header`, `sidebar`, `rail`, `breadcrumb`, `pagination`, `tabs`, `tab-bar`, `layout`, `content-panel` |
 | Overlays | `dialog`, `alert-dialog`, `bottom-sheet`, `popover`, `context-menu`, `dropdown-menu`, `menubar`, `tooltip`, `overlay`, `portal`, `teleport`, `surfaces`, `settings-modal` |
 | Actions | `button`, `button-group`, `social-button`, `fab`, `frosted-icon-button`, `pressable-scale`, `subtle-hover` |
-| Forms | `text-field`, `textarea`, `phone-input`, `input-otp`, `field`, `input-group`, `label`, `select`, `command`, `checkbox`, `radio`, `switch`, `slider`, `segmented-control`, `search`, `date-picker`, `file-upload`, `auth-card`, `stepper`, `rating` |
+| Forms | `text-field`, `textarea`, `phone-input`, `input-otp`, `field`, `input-group`, `label`, `select`, `command`, `checkbox`, `radio`, `switch`, `slider`, `segmented-control`, `search`, `date-picker`, `file-upload`, `auth-card`, `stepper`, `rating`, `wizard` |
 | Layout and lists | `grid`, `list`, `scroll`, `settings-list`, `card`, `accordion`, `aspect-ratio`, `divider`, `item`, `carousel` |
 | Data and charts | `table`, `data-table`, `chart-cards`, `stat-cards`, `calendar`, `composition-bar`, `dot-grid-meter`, `stat-bar`, `activity-heatmap`, `recent-hires-card`, `patient-info-card`, `important-alerts-card`, `agent-limits-card`, `ai-profile-card` |
+| Music and media | `media-card`, `media-controls`, `media-header`, `media-player`, `media-shelf`, `track-list`, `queue-panel`, `lyrics`, `music-library`, `creator-studio`, `sortable-media` |
+| Housing | `home-search`, `listing-actions`, `listing-editor`, `offering-badge`, `place-reviews`, `property-insights`, `tenancy`, `eviction` |
 | Stays and booking | `listing-card`, `listing-details`, `stay-search`, `stay-filters`, `booking`, `category-bar`, `map-marker` |
 | AI and agents | `agent-chat`, `ai-chat`, `composer-panel`, `composer-loader`, `agent-thinking`, `agent-log`, `agent-progress`, `task-list`, `web-search`, `questionnaire` |
 | Identity and media | `avatar`, `avatar-group`, `hover-card`, `user-hover-card`, `image-resolver`, `image-aspect-ratio-cache`, `zoomable-image-gallery`, `zoomable-media-gallery`, `media-flight`, `media-inset-border`, `progressive-blur`, `fill` |
+| Chat | `chat-list`, `chat-screen`, `chat-composer`, `chat-people`, `chat-indicators`, `message-bubble`, `message-media`, `call-ui` |
 | Feedback | `toast`, `notification`, `notification-center`, `announcement`, `admonition`, `loading`, `skeleton`, `error-boundary`, `badge`, `chip`, `kbd`, `code`, `link-preview`, `connection-status`, `connection-dots` |
 | Motion and assets | `motion`, `animated-check`, `icon-circle`, `radio-indicator`, `icons`, `typography`, `fonts` |
 

package/docs/app-shell.mdx

@@ -1,6 +1,6 @@
 ---
 title: AppShell
-description: Page frame with the sidebar, a responsive drawer, a breadcrumb + title header, a notification bell and a floating Pro offer card.
+description: Page frame with four layout variants, the sidebar and a responsive drawer, pinned top/bottom/floating slots, a breadcrumb + title header, a notification bell and a floating Pro offer card.
 order: 83
 ---
 
@@ -25,6 +25,228 @@ import { AppShell, NotificationBell, ProOfferCard } from '@oxy.so/bloom/app-shel
 </AppShell>
 ```
 
+## Variants
+
+One engine, four shapes. `variant` picks the shape; everything else — the nav,
+the drawer, the pinned regions, the slots, the sizes — works the same in all
+four.
+
+| `variant` | The page | Scroll |
+| --- | --- | --- |
+| `dashboard` (default) | nav + one fluid column capped at `contentMaxWidth`, optional `aside` | `document` / `container` / `fixed` |
+| `feed` | nav + a `contentWidth` reading column CENTRED in what the nav leaves, optional `aside` beside it, optionally in a `ContentPanel` | `document` / `container` / `fixed` |
+| `split` | a list pane, a detail pane and an optional info pane, each scrolling on its own, with a draggable divider | always one screen |
+| `focus` | one centred `contentWidth` column and NO nav | `document` / `container` / `fixed` |
+
+`dashboard` is what this component always was, unchanged to the pixel — the
+existing stories render byte-identically against the version before variants
+existed.
+
+### `feed`
+
+```tsx
+<AppShell variant="feed" sidebar={sidebar} title="Home" aside={<Trending />} contentWidth={600}>
+  {posts}
+</AppShell>
+```
+
+The nav sits in flow, and the content column plus the aside are centred as a
+PAIR in the space it leaves. The column is `flexBasis: contentWidth` with
+`flexShrink: 1` and a matching `maxWidth`, never a `width` — so on a 360px phone
+it shrinks to the screen instead of pushing the page sideways.
+
+With `scroll="document"` (the default on web) the nav and the aside pin
+themselves (`position: sticky`) and the centre column scrolls the page. Measured
+in Chrome at 1440: after scrolling 406px the nav stayed at `y = 121` and the
+aside at `y = 16` while the content moved from `16` to `-390`.
+
+`panel` wraps the centre column in a [`ContentPanel`](/docs/bloom/main/content-panel),
+so the page background reads as a gutter around a framed surface; `framedFrom`
+is forwarded. The panel's content is inset by `gutter` — without it the page sits
+ON the frame, and a radius-28 corner clips whatever is in it (the heading loses
+its first letter). So `contentWidth` is the COLUMN's width, and the reading
+measure inside a panel is that minus two gutters. Do not render your own
+`ContentPanel` inside this one; it trips the nesting guard.
+
+### `split`
+
+```tsx
+<AppShell
+  variant="split"
+  sidebar={sidebar}
+  title="Inbox"
+  list={<ThreadList />}
+  info={<ThreadDetails />}
+  pane={selected ? 'detail' : 'list'}
+>
+  <Thread id={selected} />
+</AppShell>
+```
+
+`list`, then `children` as the detail pane, then `info`. Each pane gets its own
+`ScrollView` (`paneScroll={false}` when the pane's content already scrolls — a
+`FlatList`, a virtualizer). The divider between the first two is `ai-chat`'s
+`AiChatResizeHandle`, reused rather than rewritten: pointer-capture dragging on
+web, a `PanResponder` on native, arrow keys, and the same grip. It is named
+`resizeLabel` (`"Resize panes"`) with `role="separator"`. `listWidth` (360) is
+the resting width and a drag is clamped to `listMinWidth`/`listMaxWidth`
+(280/520); `onListWidthChange` reports where it settled.
+
+Two panes from `splitFrom` (`md`, 768), three from `infoFrom` (`xl`, 1280).
+Below `splitFrom` EXACTLY ONE pane renders — the one `pane` names, falling back
+to the detail pane when that one was never given content.
+
+**`split` never scrolls the document**, whatever `scroll` says: there is one
+document, so at most one region could scroll it, and three columns that each
+keep their own position is a bounded-box layout by definition. `scroll="document"`
+resolves to `fixed` (one screen) and `scroll="container"` is honoured as-is.
+
+### `focus`
+
+A single centred column and no navigation at all — sign-in, onboarding, a
+reader. A `sidebar` passed to a `focus` shell is ignored (and `AppShellMenuButton`
+renders nothing, because there is no drawer to open). The header and all three
+bar slots still work, so a sign-up flow gets its pinned footer CTA:
+
+```tsx
+<AppShell variant="focus" contentWidth={480} title="Create your account"
+  bottomBarVisibility="always" bottomBar={<Footer />}>
+  {form}
+</AppShell>
+```
+
+## Pinned slots
+
+`topBar`, `bottomBar` and `floatingAction` exist so that **nothing in a
+consumer's code needs `position: fixed`, a negative margin, or a window-width
+hook to sit in the right place.** Every app that has drawn a phone tab bar has
+written the same four lines, and all four are wrong somewhere: a fixed bar is
+wrong inside an embedded shell, a hardcoded `bottom` is wrong on a notched
+phone, and a negative margin is wrong the moment the page's padding changes.
+
+```tsx
+<AppShell
+  variant="feed"
+  sidebar={sidebar}
+  topBar={<PhoneHeader leading={<AppShellMenuButton />} />}
+  bottomBar={<Tabs />}
+  floatingAction={<Button iconOnly leadingIcon={RiQuillPenLine} accessibilityLabel="Compose" />}
+>
+  {feed}
+</AppShell>
+```
+
+- **`topBar`** is a sibling ABOVE the shell's columns, so it spans the shell edge
+  to edge without escaping the frame's padding. Sticky to the top with document
+  scroll; simply outside the scroller otherwise. It takes the TOP safe-area inset
+  as padding. `header` is the in-column page heading and is unaffected — a shell
+  may have both — but while a `topBar` is drawn the default header does not add a
+  SECOND hamburger under it; put an `AppShellMenuButton` in the bar.
+  Not drawn under `drawer="reveal"`, which slides the whole page sideways.
+- **`bottomBar`** is pinned to the bottom of the viewport (document scroll) or of
+  the frame, with the BOTTOM safe-area inset as its own padding — so the bar's
+  background paints under the home indicator instead of leaving a stripe of page
+  showing through.
+- **`floatingAction`** sits a `gutter` above the bar (or above the safe area when
+  there is no bar), in the `floatingActionPlacement` corner (`end` by default).
+  The wrapper spans the width and ALIGNS its child, so the button never has to
+  know its own width. It has no `compact`/`always` switch: a compose button is
+  not phone chrome, so it is drawn whenever it is given — pass `null` to drop it.
+
+Both bars are MEASURED, and the content column reserves exactly their height, so
+the last row of a feed is never hidden behind them. Measured in Chrome at 390,
+scrolled to the page end: last item bottom `768`, action top `784`, bar top `844`.
+
+`topBarVisibility` / `bottomBarVisibility` are `compact` (the default — only
+while the nav is a drawer, the phone case the slots exist for) or `always`, for
+a bar that is part of the app at every width.
+
+## Breakpoints an app can name itself
+
+Every `*From` prop takes a named tier (`sm` 640 · `md` 768 · `lg` 1024 · `xl` 1280) **or a width in pixels**, because a real app's layout rarely lands on the tiers. A feed whose side column earns its place at 990 and whose rail goes in flow at 500 says so:
+
+```tsx
+<AppShell
+  variant="feed"
+  panel                     // the reading column inside a framed ContentPanel
+  navFrom={500}             // rail in flow from 500, a drawer below it
+  navExpandedFrom={1300}    // icons until 1300, labels past it
+  asideFrom={990}
+  asideWidth={350}
+  sidebar={sidebar}
+  aside={<SideColumn />}
+>
+  {feed}
+</AppShell>
+```
+
+The tiers stay the default vocabulary — `breakpointPx` resolves either — so a
+shell that says nothing still lays out on Bloom's own scale.
+
+## Sizes and breakpoints
+
+Every number is a prop, and `APP_SHELL_DEFAULTS` is the exported record of the
+defaults.
+
+| Prop | Default | Why |
+| --- | --- | --- |
+| `contentMaxWidth` | 1300 | `dashboard`'s cap. The column is fluid and stops growing here. |
+| `contentWidth` | 600 | `feed`/`focus`. The measure a single column of `body-regular` holds at ~75 characters — wider loses the line, narrower breaks too often. |
+| `asideWidth` | 320 | |
+| `asideFrom` | `xl` (1280) | 272 (panel) + 600 + 320 + three gutters is 1216: `xl` is the first tier where three columns fit without squeezing the content. |
+| `navFrom` | `lg` for the panel, `sm` for a rail | Where the nav sits in FLOW; below it the same props drive the drawer. |
+| `navExpandedFrom` | unset | Icons below, labels above: the shell swaps `sidebar.variant` between `rail` and `panel`. Setting it also makes `navFrom` default to `sm`, because below that tier the nav IS a rail. |
+| `gutter` | 12 (`dashboard`), 16 (others) | The space between the shell's edge and its regions, and between the regions. `dashboard` keeps the 12-padding/16-gap pair it shipped with, because changing either moves every existing page by four pixels. |
+| `splitFrom` | `md` (768) | 360 of list still leaves ~380 of detail (~280 once a nav rail takes its share) — a phone's worth of reading width. Below it a second pane is a sliver, not a pane. |
+| `infoFrom` | `xl` (1280) | Same headroom the aside needs. |
+| `listWidth` / `listMinWidth` / `listMaxWidth` | 360 / 280 / 520 | |
+| `infoWidth` | 320 | |
+
+## The shell measures ITSELF
+
+Every breakpoint above is read off the shell's own laid-out width, not the
+window. A shell mounted in a preview pane, in one half of a split view, or
+inside a desktop app's own chrome is narrower than the window, and a
+window-width decision puts three columns into a 480px box.
+
+The fallback before the first layout is the WINDOW rather than zero: otherwise
+frame one would be a phone layout for every shell and the correction would be a
+visible reflow on every page load. A shell that spans the page is therefore
+right on the first paint, and only an embedded one pays a single layout pass.
+
+One consequence worth knowing: where the browser draws a CLASSIC (space-taking)
+document scrollbar, the shell's box is `innerWidth` minus its width, so a
+breakpoint crossed within ~15px of the boundary lands one tier lower than the
+equivalent CSS media query would. That is the layout reading the space it
+actually has, and it is the same reason the measurement exists — but it is a
+real difference from `@media`, not an accident. (Chrome's headless shell uses
+overlay scrollbars, so every measurement below has the shell's width exactly
+equal to `innerWidth`.)
+
+(The measurement is `useContainerWidth`, the hook `listing-details` already uses
+for the same reason.)
+
+## Why there are no tricks in here
+
+The shape this replaced was a template full of them: negative margins to escape
+the preview's padding, an ad-hoc `position: fixed` for the bottom bar and the
+floating button, a per-story sticky column — and it broke at phone widths. None
+of that is in the shell, and none of it is left for a consumer:
+
+- Every region is a flex child of one row, sized by `flexBasis` + `maxWidth` and
+  allowed to SHRINK. A `width` is what overflows; a basis that shrinks cannot.
+- The only `position` values in the family are the sticky nav/aside and the bar
+  slots' own anchor, all inside the shell. No `100vw`, no negative margin, no
+  window-width hook anywhere.
+- Stories set `parameters: { bleed: true }` (see `.storybook/preview.tsx`) and
+  the shell fills what it is given — no per-story CSS.
+
+Verified in Chrome across `dashboard`, `dashboard + aside`, `feed`,
+`feed + panel`, `feed + chrome`, `split` and `focus`, at 360, 390, 414, 768,
+834, 1024, 1280, 1440 and 1920, in light and dark: 126 renders, no sideways
+scroll anywhere (`scrollWidth === innerWidth` in every one), no sibling region
+overlapping another, and no console error.
+
 ## Layout
 
 - `lg` and up: the rail sits in flow; the content column is centred, max `contentMaxWidth` (1300), header then content 16 apart.
@@ -42,7 +264,20 @@ import { AppShell, NotificationBell, ProOfferCard } from '@oxy.so/bloom/app-shel
 </AppShell>
 ```
 
-A second column on the right of the page. From `asideFrom` (`xl`, 1280; or `md` / `lg`) it sits beside the content at `asideWidth` (320), pinned like the sidebar — with document scroll it is sticky and scrolls its own overflow, so give it `flex: 1` content if it should fill the height. Below the breakpoint it is stacked after the content (`asideCollapse="stack"`, the default) or dropped (`"hidden"`). Under `drawer="reveal"` it slides with the page.
+A second column on the right of the page (`dashboard` and `feed`; `split` has
+its `info` pane instead and `focus` has no second column at all). From `asideFrom` (`xl`, 1280; or `md` / `lg`) it sits beside the content at `asideWidth` (320), pinned like the sidebar — with document scroll it is sticky and scrolls its own overflow, so give it `flex: 1` content if it should fill the height. Below the breakpoint it is stacked after the content (`asideCollapse="stack"`, the default) or dropped (`"hidden"`). Under `drawer="reveal"` it slides with the page.
+
+## The nav's identity is not the shell's layout
+
+`variant` picks the LAYOUT; `sidebar.surface` and `sidebar.size` pick what the navigation looks like. They are separate axes on purpose — the same shell carries a social reader, a workspace and a product dashboard without any of them re-implementing it:
+
+```tsx
+<AppShell variant="feed" sidebar={{ items, surface: 'plain', size: 'large' }} />     {/* a reader */}
+<AppShell sidebar={{ items, surface: 'docked', size: 'small' }} />                    {/* a workspace */}
+<AppShell sidebar={{ items }} />                                                     {/* the floating card */}
+```
+
+A `docked` nav is flush to the window: the shell drops its left and vertical padding around that column, gives up the column gap and lets the nav run the full height, because the nav's own hairline is the separator. Everything else about the shell is unchanged. The surfaces and sizes themselves are in [`Sidebar`](/docs/bloom/main/sidebar).
 
 ## Opening the drawer without a title
 
@@ -63,6 +298,8 @@ function MyHeader() {
 
 `AppShellMenuButton` is the same button the header uses and renders nothing while the sidebar is in flow. `useAppShell()` works anywhere inside the shell (the header, the page, the aside); `drawerAvailable` says whether there is a drawer to open right now.
 
+`header={null}` means **no header**: not the default one, and not the menu button either — the page has said it owns that corner, so it also owns getting the drawer open (`useAppShell()`, an `AppShellMenuButton` of its own). Leave `header` off to get the default.
+
 ## A fixed screen
 
 `scroll="fixed"` makes the shell exactly one screen tall (`100dvh` on web, its parent on native) and scrolls nothing: the header stays, and the content column fills the height left under it (`flex: 1`). The page owns its scrolling — a chat with a pinned composer, a map, a board:
@@ -88,6 +325,34 @@ The page scrolls the **document**, like a [`ContentPanel`](/docs/bloom/main/cont
 
 Native has no document: `document` behaves as `container` there, and `fixed` works the same as on web.
 
+## On native
+
+Every variant and every slot works on native; what changes is the mechanism,
+never the arrangement:
+
+- The nav and the aside are not sticky — on native the shell is always a bounded
+  box (`container` / `fixed`), so they are ordinary full-height flex columns and
+  stay put by construction.
+- `bottomBar` and `floatingAction` anchor `position: absolute` inside the
+  shell's own frame rather than `fixed` to a viewport. Yoga has no `fixed`, and
+  it ignores it SILENTLY — a bar written that way would scroll away with no
+  error to explain it.
+- `topBar` is simply the first child above the columns and outside the scroller,
+  which pins it without any positioning at all.
+- Safe-area insets come from `SafeAreaInsetsContext` — read with `useContext`,
+  not `useSafeAreaInsets`, which throws outside a provider. `AppShell` is
+  mounted at an app's root, and making a previously optional provider mandatory
+  would break every consumer that never had a bar to inset. Outside one the
+  insets are zero.
+- `split`'s divider drags through a `PanResponder` (`ai-chat`'s handle owns both
+  paths).
+- `panel` resolves to `ContentPanel`'s native variant — a plain rounded,
+  bordered surface, with none of the web sticky-overlay machinery, which is what
+  it should be where there is no document to bleed into.
+
+None of this is exercised by the web gate: jest resolves no platform extensions
+here, and Storybook is react-native-web. It is reasoned, not measured.
+
 ## NotificationBell
 
 A medium secondary icon button with the unread count (16px red disc, 1.5px ring in the button's surface that drops on hover) and a `NotificationCenter` in a bottom-end popover, 440 wide. `unreadCount` overrides the computed count.

package/docs/avatar.mdx

@@ -205,3 +205,17 @@ This is the recommended fallback when you don't have an avatar URL — never sho
   }} />
 </View>
 ```
+
+## Fallback tints keep their hue and clear AA
+
+The four initials tints paint a disc from a theme role (`primary`, `success`,
+`negative`, the neutral ramp) and the letter from a stop on the same ramp. The
+stop is a PREFERENCE: `legibleStop` walks outward from it along that ramp until
+the letter clears 4.5:1 on its own disc, so the hue survives and the letter is
+always readable.
+
+It has to walk, because the ramp is rebuilt around a theme role whose lightness
+moves with the mode. Measured in dark on `blue`: `pink` **1.24:1**
+(`#ffb4ab` on `#ecd8d6`), `lime` 4.29:1, `neutral` 3.19:1 — and
+`avatarTintForName` sends a quarter of all fallback avatars to each tint. After:
+5.42, 6.09 and 5.85. The discs are unchanged. Gate: `surface-levels.test.ts`.

package/docs/badge.mdx

@@ -25,17 +25,23 @@ import { Badge } from '@oxy.so/bloom/badge';
 
 Geometry is a standard counter badge; colours stay on Bloom's accent recipe.
 
-| size | height | text | padding-x |
-| ---- | ------ | ---- | --------- |
-| `small` | 17 | `caption-2-semibold` (11/15), tracking 0 | 4 |
-| `medium` | 18 | `caption-1-semibold` (12/16), tracking 0 | 4 |
-| `large` | 24 | `body-semibold` (14/20) | 6 |
+There are five rungs in TWO families, and the difference between them is not just height.
 
-Every label is Bloom's typography `Text` on a `TYPE_SCALE` step, so it is set in Inter on both platforms.
+| size | height | text | padding-x | icon |
+| ---- | ------ | ---- | --------- | ---- |
+| `small` | 17 | `caption-2-semibold` (11/15), tracking 0 | 4 | 10 |
+| `medium` | 18 | `caption-1-semibold` (12/16), tracking 0 | 4 | 11 |
+| `large` | 24 | `body-semibold` (14/20) | 6 | 14 |
+| `label-small` | 20 | `caption-1-semibold` (12/16) | 8 | 12 |
+| `label-medium` | 24 | `body-2-semibold` (13/18) | 10 | 14 |
 
-Every badge is a full pill with a `minWidth` equal to
-its height, so a single digit is a circle rather than a pill narrower than it is
-tall.
+`small` / `medium` / `large` are the COUNTER rungs, sized to a digit: `minWidth` equals the height so "3" is a circle rather than a pill narrower than it is tall, and the pill never shrinks — it is a fixed token in the row it sits in.
+
+`label-small` and `label-medium` are sized to a WORD: the side padding a word needs, a leading icon slot, and they SHRINK and truncate, because a two-word status in a narrow card has to yield before the card's title does. They are the rung the housing badges live on — `OfferingBadge` and the listing card's status pill are presets over them.
+
+Every label is Bloom's typography `Text` on a `TYPE_SCALE` step, so it is set in Inter on both platforms. Every badge is a full pill.
+
+**Override the side padding with `paddingLeft`/`paddingRight`, the longhands the component uses** — react-native-web ranks `padding-inline` above `padding-left` whatever the array order, so mixing the spellings drops the override on web while it lands on native.
 
 A **standalone** `dot` is a status dot: a solid centre on a tinted halo —
 12 / 6 at `medium` (8 / 4 `small`, 16 / 8 `large`). The halo is the tone's
@@ -49,7 +55,8 @@ marker: a halo over the child's corner reads as a second ring on the icon.
 | ----------- | ----------------------------------------------------------- |
 | `content`   | the label; absent, the badge draws nothing                   |
 | `color`     | the semantic tone                                            |
-| `variant`   | how loudly it is painted — `solid` · `subtle` · `outlined`   |
+| `variant`   | how loudly it is painted — `solid` · `subtle` · `outlined` · `onMedia` |
+| `icon`      | a leading glyph, drawn at the rung's size in the LABEL's colour |
 | `dot`       | drops the label entirely for a presence marker               |
 | `max`       | caps a number and appends a plus                             |
 | `invisible` | hides the badge **without unmounting the child**             |
@@ -63,6 +70,37 @@ resolves to `rgb(...)`, so hand-appending a hex alpha suffix parses back
 OPAQUE (contrast 1.00, a label on its own colour) rather than translucent —
 `resolveAccentColors` is what makes the pairing legible instead of that.
 
+## `icon`
+
+A leading glyph, given as a component (`RiKey2Line`), drawn at the rung's icon size in the LABEL's own colour and hidden from assistive technology — the badge announces its text, never "image, key" beside it. Its testID is `<testID>-icon`. An icon tucks the leading padding in by 2, optically.
+
+```tsx
+<Badge size="label-medium" variant="subtle" color="info" icon={RiKey2Line} content="For rent" />
+```
+
+## `onMedia`
+
+A fourth fill: a `neutral-50` pill with a `neutral-900` label and `shadow-s`, for over a photograph. It IGNORES `color`, and it is the same in both modes — because the photograph under it does not change with them. A badge that followed the mode would go dark-on-dark over half the images in a library.
+
+```tsx
+<Badge variant="onMedia" size="label-medium" icon={RiKey2Line} content="For rent" />
+```
+
+## Status labels are a `Badge`, not a `Chip`
+
+One pattern across the fleet. A status that is READ — a lease payment, an eviction stage, a trip, a release, a maintenance priority — is a `Badge`, driven by a `Record<Status, { tone, fill, label }>` in the family's own `constants.ts` (or `shared.ts`), wrapped in a named preset when more than one card draws it:
+
+```tsx
+export const TRIP_STATUS: Record<TripStatus, { tone: AccentTone; label: string }> = {
+  confirmed: { tone: 'success', label: 'Confirmed' },
+  cancelled: { tone: 'error', label: 'Cancelled' },
+};
+
+<Badge content={label ?? TRIP_STATUS[status].label} color={TRIP_STATUS[status].tone} variant="subtle" />
+```
+
+A [`Chip`](/docs/bloom/main/chip) is for a pill the user PRESSES — a filter, a toggle, a removable tag. A `Chip` with no `onPress` is a pill that merely looks like a control, and `tenancy`, `eviction`, `booking`, `creator-studio` and `listing-card` had drifted into three different answers to one question.
+
 ## Three props that each prevent a specific bug
 
 **`max`** — an unread count is unbounded, and `1204` inside a 20px pill either

package/docs/booking.mdx

@@ -12,7 +12,7 @@ Five pieces for booking a stay, all under one subpath:
 | ---------------- | ----------------------------------------------------------------------------------- |
 | `BookingCard`    | the reservation card beside a listing: price, dates, guests, Reserve, breakdown     |
 | `PriceBreakdown` | itemised charges and a bold total — inside the card, or alone on a checkout page    |
-| `BookingBar`     | the phone-width bar pinned under a listing: price, dates, Reserve                   |
+| `BookingBar`     | the phone-width bar pinned under a listing: price, dates, Reserve — the stay preset of [`ActionBar`](/docs/bloom/main/listing-actions) |
 | `TripCard`       | an upcoming or past reservation: photo, place, host, dates, status, actions         |
 
 ```tsx
@@ -66,6 +66,7 @@ const [guests, setGuests] = useState({ adults: 2, children: 0, infants: 0, pets:
 | prop                                          | decides                                                                                  |
 | --------------------------------------------- | ---------------------------------------------------------------------------------------- |
 | `price`, `originalPrice`, `priceUnit`         | the header; `originalPrice` is struck through before the price                            |
+| `priceUnitPrefix`                             | drawn before the unit, not spoken: `"/"` draws "$180 / night"                             |
 | `priceAccessibilityLabel`                     | the spoken price, default `"$162 per night, originally $180"`                            |
 | `rating`, `reviewCount`                       | a small `Rating` on the right; `null` draws "New", omitted draws nothing                 |
 | `checkIn`, `checkOut`, `guests`               | the values in the box; an empty date shows `datePlaceholder` ("Add date")                |
@@ -79,7 +80,9 @@ const [guests, setGuests] = useState({ adults: 2, children: 0, infants: 0, pets:
 | `breakdown`                                   | `PriceBreakdown` props, drawn 24 below                                                    |
 | `footer`                                      | anything centred at the bottom                                                            |
 
-**What it looks like.** Up to 372 wide (`width: 100%`), radius 16, a 1px hairline
+**What it looks like.** The chrome every listing action card shares (the rental,
+sale and swap cards in [Listing actions](/docs/bloom/main/listing-actions) draw
+the same shell). Up to 372 wide (`width: 100%`), radius 16, a 1px hairline
 (neutral-200, dark neutral-700), `shadow-m`, padding 24 on the card surface. The
 box is radius 12 with a 1px neutral-300 (dark neutral-600) border and dividers;
 each cell is a `caption-2-bold` uppercase label over a `body-regular` value. A
@@ -154,7 +157,9 @@ are documented with it, in [StaySearch](/docs/bloom/main/stay-search).
 />
 ```
 
-A 1px top hairline, the page background, padding 12 above and 24 at the sides,
+`BookingBar` is [`ActionBar`](/docs/bloom/main/listing-actions) with the stay
+wording (`dates` as its subtitle, "Reserve" as its button); use `ActionBar` for a
+rental, a sale or a swap. A 1px top hairline, the page background, padding 12 above and 24 at the sides,
 and **12 plus the bottom safe-area inset** below — read from
 `react-native-safe-area-context`'s context when a provider is mounted, 0 when
 not; `bottomInset` overrides it. The dates are underlined `body-2-medium`, a

package/docs/breadcrumb.mdx

@@ -51,7 +51,7 @@ On web an `href` item is a real `<a href>`, so middle-click and "open in new tab
 | `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. |
-| `BreadcrumbItem.icon?` | `ComponentType<{ width, height, fill }>` | — | Leading 16px icon. |
+| `BreadcrumbItem.icon?` | `BloomIconComponent` | — | Leading 16px icon. |
 | `BreadcrumbItem.leading?` | `ReactNode` | — | A node before the icon and label, gap 6 — the dashboard trail's 20px `Avatar` (`<BreadcrumbItem leading={<Avatar size="xs" color="blue" initials="B" />} href="#">Design team</BreadcrumbItem>`). Not recoloured on hover. |
 | `BreadcrumbItem.accessibilityLabel?` | `string` | string `children` | Accessible name. |
 | `BreadcrumbItem.style?` / `textStyle?` | style | — | Overrides. |

package/docs/button-group.mdx

@@ -52,5 +52,5 @@ Text is `body-medium` (Inter 14/20 500) through Bloom's typography `Text` — a
 | `ButtonGroupItem.selected?` | `boolean` | `false` | Hover fill + pressed state. |
 | `ButtonGroupItem.disabled?` | `boolean` | `false` | Disabled paint, blocks presses. |
 | `ButtonGroupItem.iconOnly?` | `boolean` | `false` | Square icon-only item. |
-| `ButtonGroupItem.leadingIcon?` / `trailingIcon?` | `ComponentType<{ width, height, fill }>` | — | Icon components. |
+| `ButtonGroupItem.leadingIcon?` / `trailingIcon?` | `BloomIconComponent` | — | Icon components. |
 | `ButtonGroupItem.size?` | `'medium' \| 'small'` | group size | Per-item override. |