@oxy.so/bloom 2.10.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 160 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 160 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 |
 |---|---|
@@ -167,7 +167,7 @@ Bloom publishes 160 subpath exports. Importing from the subpath rather than the
 | 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-indicators` |
+| 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/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. |

package/docs/button.mdx

@@ -40,6 +40,33 @@ import { Button } from '@oxy.so/bloom';
 | `text` | Borderless `primary` label on a compact 4/8 padding with a hover wash (Bloom-only). |
 | `link` | No container at all — label only, `accent-600` (`linkTone="secondary"`: secondary text), underline (offset 3) on hover, `accent-800` while held. |
 
+### Which variant for which job
+
+The variants overlap, and five families answered the overlap with their own
+component rather than with this list. So, explicitly:
+
+| You want | Use |
+|---|---|
+| The action of the screen | `primary` |
+| A second action beside it | `secondary` |
+| A THIRD, still accent-coloured, action | `ghost` |
+| A destructive action | `destructive` |
+| A neutral ⋯ / × / clear / toggle GLYPH | **`GlyphButton`** (below) |
+| A neutral icon button WITH a surface | `icon` |
+| A transparent LABELLED button | `text` |
+| An action inside running copy | `link` + `linkTone` + `underline` |
+
+**`ghost` is not the transparent one.** It paints an accent WASH at rest
+(`accent-100`, dark `accent-900`) with an accent label, and that is the whole
+point of it: it is the low-emphasis member of the ACCENT family. A neutral ⋯ or
+× in it lands tinted, and a destructive action in it draws a RED label on a BLUE
+fill — which is what `track-list`'s selection bar shipped before this was
+written down.
+
+**The neutral transparent icon button is `GlyphButton`**, not a `Button`
+variant: it takes an arbitrary diameter, where `Button iconOnly` is pinned to
+the four heights in the size table.
+
 The accent and neutral ramps are rebuilt around the theme colours in OKLCH (`button/shared.ts`), since Bloom presets carry one `primary` rather than a Tailwind ramp. There is NO press scale — a press is the active paint alone — and disabled buttons take their own paint instead of an opacity dip (`icon` excepted).
 
 On web the state colours arrive as `--bloom-btn-*` custom properties and are declared only in the adopted stylesheet — an inline `background-color` would silence the `:hover` rule. The gradient variants cross-fade their hover gradient in through `::before`, because `background-image` does not transition. On native the gradient is a `react-native-svg` layer; every gradient stop is an opaque composite, since react-native-svg drops alpha in `stopColor`.
@@ -101,7 +128,8 @@ Use Remix icons (`RiAddLine`, `RiArrowRightLine`, `RiDeleteBinLine`…). `iconOn
 
 ## IconButton, LinkButton, CloseButton
 
-Three companions to `Button`, exported from the same family:
+Three more companions to `Button` (a fourth, `GlyphButton`, has its own section
+below), exported from the same family:
 
 ```tsx
 <IconButton icon={RiMore2Line} accessibilityLabel="More" />          // 36, glyph 20
@@ -118,6 +146,99 @@ Three companions to `Button`, exported from the same family:
 - `href` (any `Button`) renders a real `<a href>` on web and drops the `href` while disabled; on native a press opens the URL unless `onPress` is set.
 - `CloseButton` is a round `background/tertiary` disc (16 / 20 / 24 / 32) with a two-stroke X drawn per size in its own viewBox, so the stroke is a literal pixel value (1.6 / 2 / 2 / 2.5); the glyph turns `text/primary` on hover (held press on native). The control draws no text, so `accessibilityLabel` is required.
 
+## Inline text actions
+
+```tsx
+// The underline IS the affordance, at the reading colour: a "Clear all",
+// a "Show more", a price row's label, a listing's "128 reviews".
+<Button variant="link" linkTone="text" underline="rest" textVariant="body-semibold">
+  Clear all
+</Button>
+
+// The underline as the pointer cue, in the accent (the `link` default).
+<Button variant="link">Learn more</Button>
+```
+
+| Prop | Values | Default |
+|---|---|---|
+| `underline` | `rest` · `hover` · `none` | `hover` for `link`, `none` otherwise |
+| `linkTone` | `primary` (accent-600) · `secondary` (neutral-500) · `text` (the reading colour) | `primary` |
+| `textVariant` | any `TYPE_SCALE` step | the size's own step |
+
+`linkTone="text"` is `colors.text` at rest, `colors.textSecondary` under a
+pointer or a press, `colors.textTertiary` disabled — the tone for an action that
+sits inside a sentence and must not read as the accent. It is the only tone
+whose HOVER changes the label colour; on web that arrives as
+`--bloom-btn-fg-hover` and the hover rule falls back to the rest colour for
+every other variant.
+
+`underline="hover"` is web-only by nature: native dispatches no hover, so the
+underline never appears there. Reach for `rest` when the underline has to be
+visible on a phone.
+
+`textVariant` replaces the four TYPE fields the size picked (size, line height,
+weight, tracking) and nothing else — the height, padding, gap and icon size stay
+the size's. Use it rather than `textStyle`: a `lineHeight` NUMBER in a style
+object is CSS's unitless multiplier on web, so a ramp step passed that way
+renders at twenty times its size.
+
+`numberOfLines={1}` truncates a label with an ellipsis instead of clipping it
+(`.bloom-btn` is `white-space: nowrap; overflow: hidden`, so a long label was
+cut with nothing to say so). Native honours any count; web honours `1`.
+
+`accessibilityRole` overrides the announced role — `link` with no `href`, for a
+control that navigates through the app's own router. Prefer `href`, which
+renders a real anchor and is the only spelling middle-click and copy-link
+understand.
+
+## GlyphButton
+
+The round glyph-only control at an ARBITRARY size — the neutral, transparent
+⋯ / × / shuffle / clear affordance.
+
+```tsx
+import { GlyphButton } from '@oxy.so/bloom/button';
+
+<GlyphButton icon={RiMoreFill} accessibilityLabel="More options" onPress={open} />
+<GlyphButton size={40} icon={RiShuffleLine} accessibilityLabel="Shuffle"
+             pressed={shuffle} onPress={() => setShuffle(!shuffle)} />
+```
+
+|  | off | on (`pressed`) |
+|---|---|---|
+| rest | `color` — `textSecondary` | `activeColor` — the accent |
+| hover / press | `hoverColor` — `text` | `activeHoverColor` — `activeColor` |
+| fill | `fill` — none | the same |
+| fill, hover / press | `hoverFill` — the neutral wash (neutral-100, dark 800) | the same |
+
+All four corners are spellable because the on-state and the hover state are
+independent: a player's lit shuffle still brightens under the cursor.
+
+- **`size`** is the diameter (default 36); the glyph is **0.6 × the box**
+  (`GLYPH_BUTTON_GLYPH_RATIO`), and **`glyphSize`** overrides it. Across the five
+  family-local copies this replaced the ratio ran 0.50 to 0.75; 0.6 is the middle
+  of that range, and every call site that measured differently passes its own.
+- **`pressed`** makes it a TOGGLE and emits `aria-pressed` AND
+  `accessibilityState.selected` — react-native-web drops `accessibilityState`,
+  React Native has no `aria-pressed`. Leave it undefined for a plain button:
+  `aria-pressed="false"` on one announces a state nobody set.
+- **`accessibilityLabel` is required** — the control draws no text, so nothing
+  else can name it.
+- **`ring`** is the focus ring's colour (default the accent). Pass a light one on
+  a surface Bloom does not own — artwork, a player bar — or the ring disappears
+  exactly where a keyboard user needs it.
+- **`disabled`** blocks the press, sets `aria-disabled` and
+  `accessibilityState.disabled`, and dims the control to `disabledOpacity`
+  (0.5).
+- **`children`** replaces `icon` with a node you paint yourself; as a FUNCTION it
+  is handed the resolved foreground, so a text glyph still follows hover and the
+  toggle. **`grow`** turns the box into a minimum width for exactly that case.
+- **`decoration`** is an extra absolutely-positioned layer over the box — the
+  media player's 4px active dot. The family owns its geometry.
+
+Colour change only, 150ms, no scale. Focus is a 2px ring at a 2px offset, on
+`:focus-visible` so a mouse press leaves none behind.
+
 ## Disabled
 
 ```tsx
@@ -135,11 +256,15 @@ Three companions to `Button`, exported from the same family:
 | `disabled?` | `boolean` | `false` | Blocks presses, disabled paint. |
 | `variant?` | `'primary' \| 'secondary' \| 'ghost' \| 'destructive' \| 'outline' \| 'inverse' \| 'icon' \| 'text' \| 'link'` | `'primary'` | Visual style. |
 | `size?` | `'xs' \| 'small' \| 'medium' \| 'large'` (+ `sm \| md \| lg \| icon`) | `'medium'` | Height, radius, padding, type and icon size. |
-| `leadingIcon?` | `ComponentType<{ width, height, fill }>` | — | Icon component before the label, sized by the button. |
-| `trailingIcon?` | `ComponentType<{ width, height, fill }>` | — | Icon component after the label. |
+| `leadingIcon?` | `BloomIconComponent` | — | Icon component before the label, sized by the button. |
+| `trailingIcon?` | `BloomIconComponent` | — | Icon component after the label. |
 | `iconOnly?` | `boolean` | `false` | Square icon-only button. |
 | `icon?` | `React.ReactNode \| ComponentType` | — | Icon component (sized) or pre-rendered node next to the label. |
-| `linkTone?` | `'primary' \| 'secondary'` | `'primary'` | Colour of the `link` variant. |
+| `linkTone?` | `'primary' \| 'secondary' \| 'text'` | `'primary'` | Colour of the `link` variant; `text` is the reading colour. |
+| `underline?` | `'rest' \| 'hover' \| 'none'` | `hover` for `link`, else `none` | When the label carries its underline. |
+| `textVariant?` | `TypeScaleVariant` | the size's step | Override the label's type-ramp step. |
+| `numberOfLines?` | `number` | — | Truncate the label. Web honours `1`. |
+| `accessibilityRole?` | `'button' \| 'link'` | derived from `href` | Override the announced role. |
 | `href?` | `string` | — | Renders an anchor on web; opens the URL on native. `target` / `rel` pass through on web. |
 | `iconPosition?` | `'left' \| 'right'` | `'left'` | Which side of the label `icon` goes. |
 | `loading?` | `boolean` | `false` | Show centered spinner, block presses. |