@oxy.so/bloom 2.10.0 → 2.12.0

package/docs/chip.mdx

@@ -64,6 +64,58 @@ The hues sit BESIDE the accent recipe, not inside it: `resolveAccentColors` is u
 
 `selected` promotes the chip to the brand tone rather than to a colour system of its own, and announces as `aria-pressed`. On web a keyboard user gets a `:focus-visible` ring — keyboard-only, so a mouse click does not leave one behind.
 
+### Role
+
+A pressable chip's ROLE decides which state attribute it carries, and the three are not interchangeable:
+
+| `role` | web | native |
+|---|---|---|
+| `button` (default) | `aria-pressed` | `accessibilityState.selected` |
+| `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.
+
+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`
+
+`variant="inverted"` is a fourth fill and a different idea rather than a fourth loudness. At rest it is a hairline on the page (transparent fill, neutral-200 border, dark neutral-700); selected, it turns the page's own reading pair OVER — fill `text`, label `background`.
+
+That pair is legible by construction in both modes and under every preset, which is what a filters sheet needs and what promoting to the brand tone cannot promise. It answers hover with its BORDER rather than the shared opacity step, because a pill with no fill has nothing to fade.
+
+```tsx
+<Chip size="2xl" variant="inverted" role="radio" selected={value === n} onPress={() => onChange(n)}>
+  {String(n)}
+</Chip>
+```
+
+## `ChipRow`
+
+The pill row that scrolls sideways, with a fade at whichever edge has more behind it. Without the fade a clipped pill stops mid-glyph and reads as a rendering fault rather than as "there is more".
+
+```tsx
+import { Chip, ChipRow } from '@oxy.so/bloom/chip';
+
+<ChipRow role="tablist" accessibilityLabel="Result types" fadeColor={card}>
+  {tabs.map((tab) => (
+    <Chip key={tab.value} size="xl" role="tab" selected={tab.value === value} onPress={() => onChange(tab.value)}>
+      {tab.label}
+    </Chip>
+  ))}
+</ChipRow>
+```
+
+| prop | |
+|---|---|
+| `gap` | between pills, default 8 |
+| `contentInset` | side padding inside the scroller |
+| `fadeColor` | the surface BEHIND the row — the row cannot know it. Default the page background; pass the card colour when the row sits on a card, or the fade blends into the wrong thing |
+| `ringInset` | room kept for a pill's focus ring inside the scroller, taken back out with negative margins so the row still lines up. Default 4 |
+| `role` / `accessibilityLabel` | the row's semantics, which belong to the caller |
+
+The fade is web only (it is a CSS gradient); the row scrolls on both platforms.
+
 ## Removable
 
 ```tsx
@@ -74,7 +126,23 @@ The close affordance is its own control inside the pill, with its own label and
 
 ## Sizes and icons
 
-`size` is `small` (`caption-1-medium`, 24 tall), `medium` (default, `body-medium`, 24 tall) or `large` (`body-medium`, 28 tall), all with 6px side padding and set in Inter through the typography `Text`. The close glyph is Remix `close-line` at 16. `startIcon` and `endIcon` take any node, and both are sized to the pill rather than to whatever was passed — an icon in a `small` chip and the same icon in a `large` one come out proportional.
+| `size` | height | padding-x | gap | icon | text |
+|---|---|---|---|---|---|
+| `small` | 24 | 6 | 4 | 14 | `caption-1-medium` |
+| `medium` (default) | 24 | 6 | 4 | 16 | `body-medium` |
+| `large` | 28 | 6 | 4 | 16 | `body-medium` |
+| `xl` | 32 | 12 | 8 | 16 | `body-medium` |
+| `2xl` | 40 | 16 | 8 | 18 | `body-medium` |
+
+The scale used to stop at `large`, which is why five families grew a pill of their own rather than use this one: 28 tall with 6px sides is a TAG, and a filter you tap needs a target. `xl` is the filter/segment pill; `2xl` is the filters-sheet pill, and it pins a `minWidth` of 48 so a one-character label ("1", "8+") stays a pill rather than collapsing to a dot — a rung with a `minWidth` also centres its contents.
+
+**Override the side padding with `paddingHorizontal`, never `paddingLeft`/`paddingRight`.** react-native-web maps the shorthand this component uses to `padding-inline`, which its atomic sheet ranks above `padding-left` whatever the array order — so a longhand override drops on WEB and lands on native. Two families were overriding it that way and had been drawing 6px on the web since they shipped. Better still: pick the rung that already carries the padding you want.
+
+The close glyph is Remix `close-line` at 16. `startIcon` and `endIcon` take any node, and both are sized to the RUNG rather than to whatever was passed — an icon in a `small` chip and the same icon in a `2xl` one come out proportional.
+
+## The focus ring
+
+The `:focus-visible` ring is the accent ramp's 500, the colour every other ring in the library uses. It used to be the chip's own LABEL colour, which is the one colour guaranteed to be invisible: on a solid chip the label is white and so was the ring — measured 1.09:1 in light mode, black on black in dark. The ring is drawn with `outline-offset: 2px`, i.e. on the PAGE, so what it has to contrast with is the page; `accent[500]` clears 4.2:1 against it on all 64 presets in both modes.
 
 ## A pill does not shrink
 

package/docs/content-panel.mdx

@@ -18,6 +18,28 @@ import { ContentPanel } from '@oxy.so/bloom/content-panel';
 </ContentPanel>
 ```
 
+## The panel's edge
+
+```tsx
+<ContentPanel framed chrome="elevated" />   {/* default: hairline + panel shadow */}
+<ContentPanel framed chrome="border" />     {/* hairline only */}
+<ContentPanel framed chrome="none" />       {/* flat rounded surface */}
+<ContentPanel framed shadow="0 8px 24px rgba(0,0,0,.12)" />  {/* your own lift */}
+```
+
+A framed panel wears the same edge the [`Sidebar`](/docs/bloom/main/sidebar)
+does — a hairline **and** the floating-panel shadow, from one recipe in
+`styles/panel-chrome.ts` (`resolvePanelChrome`, `PANEL_SHADOW`) so the two
+surfaces cannot drift apart. The border alone read as a box drawn on the page;
+the shadow is what makes it a panel lifted off it.
+
+- On **web** the shadow rides the same sticky overlay as the hairline, so the
+  lift and the edge always describe the same rectangle, and it paints outward
+  into the gutter the page background shows.
+- On **native** the surface carries both.
+- `chrome` is ignored while the panel is full-bleed (below `framedFrom`, or
+  `framed={false}`) — there is no edge to draw.
+
 ## Which prop decides what
 
 | prop               | decides                                                  |
@@ -26,25 +48,51 @@ import { ContentPanel } from '@oxy.so/bloom/content-panel';
 | `framedFrom`       | the breakpoint it starts framing at — `500` `640` `768` `1024` |
 | `showStickyFrame`  | whether the frame persists behind sticky content           |
 | `surfaceStyle` / `surfaceClassName` | the surface itself                        |
+| `surfaceColor`     | what the panel tells its content it is painted in — only when `surfaceClassName`/`surfaceStyle` repainted it |
 | `contentStyle` / `contentClassName` | the column inside it                      |
 | `maskColor`        | the colour the gutter mask fades to                        |
-| `overlaySizing`     | (web) how the mask/border overlays size themselves — see below |
+| `overlaySizing`     | (web) the screen's frame (default) or the panel's own box — see below |
+| `overlayInset`      | (web) where that sticky frame pins — match your layout's gutter |
+| `fill`              | the panel is the height it is given; its content scrolls inside |
+
+## `overlaySizing`: the screen's frame, or the panel's own box
+
+The web overlays (the border frame and the gutter bleed-mask) default to
+**`overlaySizing="viewport"`**: a screen-tall sticky rectangle, `100dvh` minus
+the insets. The panel's own box grows with its content and the document scrolls
+it, while the edge stays where the screen is — so the panel occupies the window
+from top to bottom and the content moves inside it. That is what makes a
+document-scrolled column read as a surface rather than as an open-ended strip
+whose bottom edge is somewhere past the fold.
+
+**`overlayInset` has to match where the panel really starts.** Sticky
+positioning leaves an element at its static position until scrolling would push
+it past the inset, so a panel that begins 16px down the page with the default
+8px inset draws its frame at 16 and then SNAPS it to 8 on the first scroll. That
+8px jump is what "the panel moves when I scroll" is. Pass the gutter your
+layout uses:
 
-## `overlaySizing`: viewport chrome vs. a bounded shell
+```tsx
+<View style={{ padding: 16 }}>
+  <ContentPanel framed overlayInset={16}>{page}</ContentPanel>
+</View>
+```
 
-The web overlays default to `overlaySizing="viewport"`: sized to `100dvh` and
-`position: sticky`-pinned, so they read as a constant frame around the visible
-slice of a panel whose own DOM height can exceed one screen — the right choice
-in a document that actually scrolls (a feed page that grows with content).
+`AppShell` passes its own `gutter` for you. Measured in Chrome at 1280 × 900,
+`variant="feed" panel`: the frame reports `top: 16, height: 868` at scrollY 0,
+1, 200, 600 and 846 — the same rectangle at every one — while the surface
+behind it moves from 16 to −830.
 
-A consumer whose OWN shell already bounds the panel's height — a fixed app
-shell with its own internal scroll containers, no document scroll — doesn't
-have that problem, and viewport-sizing there is actively wrong: the overlay
-still reads `100dvh` regardless of how much of the viewport is actually the
-panel's, so anything placed OUTSIDE the panel (a header above it, say) gets
-painted over. `overlaySizing="panel"` fixes that: the overlays size to the
-panel's own real box via CSS Grid layer-stacking instead of viewport math, so
-they never extend past whatever height the panel actually has.
+An inset PAIR (`{ top, bottom }`) is for persistent chrome the consumer keeps
+outside the panel: a sticky header above it shifts where the panel visually
+starts without moving its DOM position, so the frame starts lower without also
+ending higher.
+
+`overlaySizing="panel"` is the other mode: the overlays are the panel's own box,
+through CSS Grid layer-stacking. Use it when the panel's box already IS the
+visible area (`fill`, below) or when something placed outside the panel must
+never be painted over by an overlay sized to the whole viewport — a bounded app
+shell with its own internal scrollers.
 
 ```tsx
 <View style={{ flex: 1 }}>
@@ -55,6 +103,32 @@ they never extend past whatever height the panel actually has.
 </View>
 ```
 
+## `fill`: a panel that reaches the bottom
+
+```tsx
+<AppShell scroll="fixed">        {/* something has to bound it */}
+  <ContentPanel framed fill>
+    <FlatList … />                {/* scrolls INSIDE the panel */}
+  </ContentPanel>
+</AppShell>
+```
+
+By default the panel grows with its content and the page scrolls: on a feed
+taller than the window you see the panel's top edge and its bottom edge is
+somewhere past the fold — an open-ended column, not a surface.
+
+`fill` makes the panel the height of the space it is given, with its content
+scrolling inside it. It closes at the bottom of the screen, the way the
+[`Sidebar`](/docs/bloom/main/sidebar) beside it does, and the frame never moves
+because the frame IS that box.
+
+It needs a parent that bounds it — an `AppShell` with `scroll="fixed"` or
+`scroll="container"` (which passes `fill` for you when you ask for `panel`), or
+any screen that is `flex: 1`. In a document-scrolled page there is no height to
+fill and the panel keeps growing; that page wants `scroll="document"`, not this
+prop. On web the content wrapper becomes the scroller; on native the panel is
+already `flex: 1`, so a `FlatList` inside fills it and scrolls within it.
+
 ## `framedFrom` is why the branch is not in your screen
 
 A phone wants a plain column: a frame a few pixels from the screen edge reads
@@ -80,6 +154,69 @@ Two columns side by side are two panels as **siblings**:
 
 A screen picks one panel per column; the sections inside it are plain views.
 
+## The panel says what colour it is, so chrome does not have to guess
+
+A panel is the surface a screen sits on, which makes it the thing in-panel
+chrome keeps asking about: a sticky header that has to be **opaque** over the
+scrolling column, a tab rail, a search field's backing, a reply bar pinned to
+the bottom. Each one only ever wanted "be the colour of the surface I am on",
+and the only way to say that used to be to repeat the panel's own `bg-card` at
+the call site — which turns one decision about the panel's surface into a sweep
+through every screen the next time it changes. Mention carries ~65 of those.
+
+So the panel publishes it. Anything inside reads it:
+
+```tsx
+import { useSurfaceFill } from '@oxy.so/bloom/styles';
+
+function StickyReplyBar() {
+  const surface = useSurfaceFill();          // the panel's fill — `colors.card`
+  return <View style={{ backgroundColor: surface }}>…</View>;
+}
+```
+
+`useSurfaceFill()` is the cross-platform answer and the one to reach for.
+[`styles`](/docs/bloom/main/styles#surface-levels) has the rest of the model:
+the rung the panel publishes with it (`1`), the derived hairline and text rungs,
+and `--bloom-surface`, the web variable the panel writes on the element it
+paints so a stylesheet can follow the surface too.
+
+Two things are worth knowing here:
+
+- **It is the panel's REAL fill, not a rung.** `theme.colors.card` is not rung 1
+  in dark mode — the rung is a computed step off the page — and chrome that took
+  the rung would sit a visible shade off the column it is supposed to vanish
+  into. The panel publishes the fact.
+- **Repainting the surface makes the panel stop claiming to know.**
+  `surfaceClassName` is a utility Bloom cannot resolve to a colour, and a
+  `surfaceStyle` with a `backgroundColor` is the same repaint by the other door
+  — the colour is legible there, but which of the two actually paints differs by
+  platform, so the panel refuses to guess. Either way it falls back to publishing
+  the rung alone rather than a confident wrong answer. `surfaceColor` is how that
+  caller gets the exact answer back:
+
+```tsx
+<ContentPanel surfaceClassName="bg-background" surfaceColor={colors.background} />
+```
+
+`surfaceColor` changes nothing about how the panel looks — the class still
+paints it. It only decides what the panel tells its content.
+
+### What reads it
+
+`SettingsListGroup` is the first component to stop taking a prop for this: with
+no `variant` it paints one step off the panel's published fill, so a settings
+screen reads the same on a page and inside a panel without repeating the answer
+at every group ([Settings list](/docs/bloom/main/settings-list)).
+
+A surface opened *from* the panel does not inherit it. React context reaches
+through a portal and through an RN `<Modal>` even though neither paints
+anything, so a dialog, sheet or menu would otherwise take its colours from where
+its trigger happened to live. `Dialog` and the bottom-sheet shell publish their
+own fill, `floating/FloatingPanel` publishes the menu rung, and `OverlayRoot`
+resets the ambient surface for anything portaled that does neither — so the same
+dialog paints the same way from a bare screen and from inside a panel.
+
 ## Do not put a Card immediately inside a framed panel
 
 They are both surfaces. A card filling a framed panel is two borders with a few

package/docs/creator-studio.mdx

@@ -94,7 +94,7 @@ The estimate this month (`title-1-medium`) with a delta chip, a 112px monthly ba
 
 `layout="grid"` (square cover on top) or `"row"` (64px cover leading, badge and menu trailing). The card is radius 16 with a 12 cover radius; hovering the pressable part deepens the surface (colour only). `onPress` makes the cover and text ONE pressable named by the title; the "⋯" `DropdownMenu` button (named "More actions for <title>") is its sibling, never nested. A rejected or taken-down release with a `statusReason` shows it in an error-tinted note.
 
-`ReleaseStatusBadge` is a `Chip` whose recipe is `RELEASE_STATUS_TONES`:
+`ReleaseStatusBadge` is a `Badge` on a label rung (`small` → `label-small`, 20 tall; `medium` → `label-medium`, 24) whose recipe is `RELEASE_STATUS_TONES`. A `Badge` rather than a `Chip`, which is what it used to be: a status that is READ is a `Badge` across the whole fleet, and a `Chip` with no `onPress` is a pill that merely looks like a control.
 
 | status | label | tone |
 |---|---|---|
@@ -144,3 +144,10 @@ A release `Select`, Mood and Genre chip groups (selectable `Chip`s with `aria-pr
 ## Native
 
 Everything renders on native with the same props. Web-only: hover states (colour changes), the focus ring, drag and drop in the upload zones, and the CSS keyframes of the processing bar (native runs the same sweep with reanimated). On native the upload zones need `onPickFiles`.
+
+## Quiet text is floored on the card
+
+`textSecondary` and `textTertiary` come from `surfaceTextOn(theme, surface)`, not
+from `neutral-400`/`neutral-500` — the same copy of the ramp stops that put
+chart-card captions at 2.42:1. See
+[Styles → Quiet text](/docs/bloom/main/styles).

package/docs/date-picker.mdx

@@ -6,16 +6,19 @@ order: 13
 
 # DatePicker
 
-`DatePicker`, `DateRangePicker` and `MeetingScheduler`. Bloom takes no dependency on react-aria or `@internationalized/date`, so the month layout, selection, constraints and keyboard navigation are plain TypeScript over local-midnight `Date`s. Colours come from the Bloom-derived ramps in `src/button/shared.ts`.
+`DatePicker`, `DateRangePicker`, `MeetingScheduler` and `TimeField`. Bloom takes no dependency on react-aria or `@internationalized/date`, so the month layout, selection, constraints and keyboard navigation are plain TypeScript over local-midnight `Date`s. Colours come from the Bloom-derived ramps in `src/button/shared.ts`.
 
 ```tsx
-import { DatePicker, DateRangePicker, MeetingScheduler, Calendar, RangeCalendar } from '@oxy.so/bloom/date-picker';
+import { DatePicker, DateRangePicker, MeetingScheduler, TimeField, Calendar, RangeCalendar } from '@oxy.so/bloom/date-picker';
 
 const [day, setDay] = useState<Date | null>(null);
 <DatePicker value={day} onChange={setDay} minDate={new Date()} />
 
 const [range, setRange] = useState<DateRange | null>(null);
 <DateRangePicker value={range} onChange={setRange} />
+
+const [time, setTime] = useState<string | null>('18:30');
+<TimeField value={time} onChange={setTime} step={15} accessibilityLabel="Viewing time" />
 ```
 
 ## Pickers
@@ -81,3 +84,78 @@ A range takes two presses in either order; between them the band follows the poi
 | `disabled?` | `boolean` | `false` | Blocks opening (pickers). |
 | `RangeCalendar.visibleMonths?` | `1 \| 2` | `1` | Months side by side. |
 | `defaultMonth?` | `Date` | value's month, else today's | First month shown (calendars). |
+
+## TimeField
+
+`DatePicker` is the day; `TimeField` is the hour and minute. It is a **field,
+not a fourth popover** — a viewing at 18:30 is four keystrokes, and a popover is
+the wrong instrument for four keystrokes. (`MeetingScheduler` still has the
+other shape: a fixed list of bookable slots, which is a different question —
+"which of these?" rather than "when?".)
+
+```tsx
+const [time, setTime] = useState<string | null>(null);
+<TimeField
+  value={time}
+  onChange={setTime}
+  min="09:00"
+  max="20:00"
+  step={15}
+  accessibilityLabel="Viewing time"
+/>
+```
+
+| prop | |
+| --- | --- |
+| `value` | 24h `"HH:mm"`, or `null` while empty — fully controlled |
+| `onChange` | the committed time, or `null` once emptied; never fires while typing |
+| `min`, `max` | 24h `"HH:mm"` bounds; a time outside is pulled to the bound |
+| `step` | minutes per arrow press, and the grid a typed time snaps to. Default `1` |
+| `hourFormat` | `'24h'` (default) or `'12h'` — how it is DRAWN; the value stays 24h |
+| `size` | `'small'` (96 × 32) or `'medium'` (default, 104 × 38) |
+| `disabled` | not editable, `aria-disabled`, `DISABLED_OPACITY` |
+| `accessibilityLabel` | **required** — the field draws no label, and `"--:--"` names nothing |
+| `placeholder` | default `"--:--"`, or `"--:-- --"` in 12h |
+| `width`, `style`, `testID` | |
+
+**The value is always 24h.** `hourFormat` decides what the reader sees, never
+what the caller receives, so a `TimeField` value drops straight into one of
+`MeetingScheduler`'s `timeSlots` and the app needs no locale to read it back.
+
+**It looks like the date chip because it is the same control.** Geometry,
+palette and focus behaviour are `DateChipInput`'s — the `DD/MM/YYYY` chip inside
+the pickers — so a date and a time typed beside each other line up: 1px
+`chipBorder` darkening to `chipBorderFocused` on focus (the border IS the focus
+indicator, `outline-none`), radius 10, shadow-xs, the panel fill.
+
+### Typing
+
+The field keeps its own **draft** while you type, so the text is not reformatted
+under the cursor, and commits on blur or submit. Escape reverts to the committed
+value, and so does a draft that does not parse — rather than an error the field
+has no room to draw.
+
+Parsing is deliberately forgiving, because a field that only accepts what it
+printed is a field people fight. All of these commit to `09:30`:
+
+`9:30` · `930` · `9.30` · `9 30` · `0930` · `9:3` · `9:30 am` · `9:30 a.m.`
+
+and `9` alone is `09:00`, `21:30` is `21:30`, `9pm` is `21:00`. An `am`/`pm`
+marker decides the half of the day whatever `hourFormat` says — somebody who
+typed `pm` means pm.
+
+`step` snaps a committed time to a grid counted **from midnight**, so `step={15}`
+always means :00 :15 :30 :45. Counting from `min` instead would knock the round
+times off the grid the moment a shop opened at 09:10.
+
+### Keyboard
+
+ArrowUp and ArrowDown move by `step` and commit immediately, clamped at `min`
+and `max` rather than wrapping — a wrap from `max` back to `min` reads as the
+field refusing the key. With no value yet, ArrowUp starts at `min` (or 00:00)
+and ArrowDown at `max` (or 23:59).
+
+They are a convenience **on a text box**, not a `spinbutton`: the control
+announces itself as the text field it is, named by `accessibilityLabel`, and
+every value the arrows can reach can also be typed. A `spinbutton` role would
+promise `aria-valuenow` over a value that is a string and may be empty.

package/docs/design-tokens.mdx

@@ -204,6 +204,40 @@ memory rather than from the file, `bloomDesignTokens()` from
 | `border-border-input` | input border | `--input` |
 | `border-border-input-active` | focused input | `--ring` |
 
+### One quiet-text role, one colour
+
+`text-text-tertiary` and `theme.colors.textTertiary` are the **same colour**:
+`--muted-foreground`, the theme's one quiet-text token.
+
+They were not. The utility has always aliased `--muted-foreground` (8.42:1 light
+/ 11.33:1 dark) while `theme.colors.textTertiary` read the engine's `outline`
+(4.04:1 / 6.12:1) — one named role, two colours, and the JS one was **below AA
+for body text in light**. The tie is broken toward the token, because a fixed
+third grey cannot be a third rung: it is measured against one surface and used on
+all of them. `neutral-400` is the same mistake one ramp over — it clears AA on
+the page and measures 2.42:1 on a chart card.
+
+**A genuinely quieter rung is asked for against the fill it lands on**, with
+`surfaceTextOn(theme, fill).textTertiary` — see
+[Styles](/docs/bloom/main/styles). That is what `chart-cards`, `creator-studio`,
+`property-insights`, `media-header` and `text-field` now do.
+
+Gates: `surface-levels.test.ts` (both spellings agree, and clear AA, over all 64
+presets x 2 modes) and `surface-level-adoption.test.ts` (the families).
+
+## Surfaces above the page
+
+The ramp below answers where the PAGE's own rungs sit. It does not answer "the
+surface one level above the current one", which is what a card, a popover tile
+or a field inside either of them needs — and thirty families each answered that
+by hand, leaving four different dark card fills in one tree.
+
+That question belongs to `styles/surface-levels.ts`
+([Styles](/docs/bloom/main/styles)): `resolveSurfaceLevel`, `surfaceFillOn`,
+`hairlineOn`, `surfaceTextOn` and the `SurfaceLevelProvider` that lets a
+container publish the rung its children sit on. It is built BESIDE the policy,
+reading `theme.colors`, and changes no preset and no token.
+
 ## The neutral surface ramp
 
 `--background`, `--surface`, `--popover`, `--muted`/`--accent` and `--card` are a

package/docs/dropdown-menu.mdx

@@ -150,6 +150,8 @@ Verified in a real browser by `scripts/verify-submenu-flyout.mjs` — jest can s
 
 On native these are ignored. The menu is a bottom sheet, which is anchored to the screen rather than to the trigger.
 
+An open menu follows its trigger as the page scrolls, at one measurement per animation frame and no re-render when nothing moved — the same panel behaviour every anchored surface gets, described under [Popover → Following the anchor](/docs/bloom/main/popover).
+
 ## Naming a row that is not a plain string
 
 A row whose child is a string names itself. A row composed of elements does not:

package/docs/hooks.mdx

@@ -58,6 +58,49 @@ The shared press transform, so a press dip is the same everywhere.
 The screen's horizontal insets, from one place, so a header and the content
 below it agree about where the margin is.
 
+## `useContainerWidth`
+
+The width the component was laid out at, or `null` before the first layout.
+
+```tsx
+const { width, onLayout } = useContainerWidth();
+
+<View onLayout={onLayout}>
+  {width !== null && width >= 600 ? <Wide /> : <Narrow />}
+</View>
+```
+
+A component measures ITSELF rather than the window, so a page split into a
+content column and a side column picks its layout from the space it has rather
+than from the size of the screen. The width is rounded and only stored when it
+changes, so a resize that lands on the same pixel does not re-render.
+
+Nine families across housing and music reached into `listing-details` for this
+before it lived here.
+
+## `moveItem` / `dragTarget` / `dragShift`
+
+The list maths behind every drag-to-reorder surface — a track list, a queue, a
+photo grid. Pure, so the drag, the keyboard path and the move buttons share one
+definition of "move".
+
+```tsx
+const target = dragTarget(drag.from, drag.dy, ROW_HEIGHT, rows.length);
+const shift  = dragShift(index, drag.from, target, ROW_HEIGHT);   // px, per row
+onReorder(moveItem(rows, drag.from, target));
+```
+
+Degenerate input, where the three copies of this used to disagree:
+
+- `moveItem` clamps and rounds the TARGET into range, but refuses an
+  out-of-range SOURCE — clamping that would silently move the wrong item.
+- `dragTarget` answers `from` when there are no rows or the row has not been
+  measured (`rowHeight <= 0`). Answering `0` sends the row to the top of a list
+  nobody has measured yet.
+
+`@oxy.so/bloom/queue-panel` publishes the same three as `moveQueueItem`,
+`queueDragTarget` and `queueDragShift`; they are re-exports.
+
 ## `useHaptics`
 
 Haptic feedback through Bloom's optional-peer boundary — a no-op when

package/docs/icons.mdx

@@ -36,6 +36,67 @@ Colour travels on `fill` and size on `size` (the `xs`…`xl` rung, or `width` /
 label has to be told both — an icon that "looks black in dark mode" is almost
 always one that was never given a `fill`.
 
+## `BloomIconComponent` — the type of an icon you hand to a component
+
+Most Bloom components that take an icon take the COMPONENT, not an element, so
+they can size and colour it themselves.
+
+```tsx
+import type { BloomIconComponent } from '@oxy.so/bloom/icons';
+import { RiHotelBedLine } from '@oxy.so/bloom/icons';
+
+interface FactProps {
+  icon: BloomIconComponent;
+  label: string;
+}
+
+<ListingFact icon={RiHotelBedLine} label="2 beds" />   // ✅ the component
+<ListingFact icon={<RiHotelBedLine />} label="2 beds" />  // ✗ an element
+```
+
+```ts
+type BloomIconComponent = ComponentType<{
+  width?: number; height?: number; fill?: string;
+}>;
+```
+
+All three props are optional, which makes this the WIDEST icon a component can
+be handed: a component whose props are stricter is not assignable, on purpose.
+It is also the LEAST a part may ask for, so it is the right type wherever a part
+only sets width, height and fill — which is nearly everywhere.
+
+### What this type is NOT for
+
+A part that hands its icon more than those three props takes `Props` from
+`@oxy.so/bloom/icons` instead — the full Bloom icon surface, with `style`,
+the `size` rung, `gradient` and everything `react-native-svg` accepts.
+`IconCircle` is the clear case: it sets `size` and a `color` style, so only a
+real `Ri*` icon will do and `ComponentType<Props>` says so. `ChatIconComponent`
+(`chat-indicators`) is narrower for its own reason — it adds `testID`, because
+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.
+
+### The per-family names still work
+
+Twenty-five families had declared this same type under their own name
+(`SidebarIcon`, `TrackIconComponent`, `ListingFactIcon`, `PlayerGlyph`,
+`BadgeIcon`, `CallGlyph`, …). Those names still work — they are `@deprecated`
+aliases of this one — so nothing needs changing; new code should reach for
+`BloomIconComponent`.
+
+That sentence is checked rather than promised. Writing the shape out again is
+never a compile error (the literal IS the type), so a family can quietly mint a
+twenty-sixth spelling and nothing goes red — which is exactly what happened to
+`PlayerGlyph`, `BadgeIcon` and `CallGlyph`: named in this page as converted
+while their own files still declared the literal.
+`src/__tests__/icon-component-type.test.ts` now parses `src/` and holds four
+properties: the shape is declared exactly once, that one declaration is
+`icons/icon-component.ts`, the alias list is an EQUALITY (dropping one breaks a
+consumer; adding one is a new name for a type that has one), and every alias
+carries `@deprecated`.
+
 ## Migrating from the retired Bloom icon set
 
 The old `<Subject>_<Stroke2|Filled>_Corner0_Rounded` exports (and the unsuffixed

package/docs/image-resolver.mdx

@@ -34,6 +34,35 @@ That is also why there is no `avatarUrl` field on any DTO and no per-app URL
 helper: **one chokepoint**, `getFileDownloadUrl(id, variant)`, plus this
 resolver.
 
+## `isImageUrl` — the one answer to "URL or id"
+
+Every component that takes a `source` has to decide the same thing: render the
+string, or hand it to the resolver. That decision is one exported function.
+
+```tsx
+import { isImageUrl } from '@oxy.so/bloom/image-resolver';
+
+const uri = isImageUrl(source) ? source : resolver?.(source, 'thumb');
+```
+
+It is true for `http://`, `https://`, `data:`, `blob:`, `file:` and **a leading
+slash** — `/img/cover.jpg` is a root-relative path to an asset the app already
+serves. It is deliberately not a URL parser: it routes, and anything that is
+not one of those shapes is an id.
+
+**This used to differ per family.** Twelve copies of this predicate had grown across the
+package under three spellings (`isUrl`, `isImageUrl`, and an inline check in
+`Avatar`), and they disagreed. Only `listing-card`'s accepted a leading slash;
+`Avatar`'s accepted neither `blob:` nor `file:`. All of them now behave like the
+one above, which is strictly more permissive — a path or a `blob:` URL used to
+be sent to the resolver, and a resolver has nothing to answer for one, so the
+image rendered as its placeholder. If an app really does mint ids that start
+with `/`, `blob:` or `file:`, they are no longer routed to the resolver.
+
+It also tightened in one place: `media-player` and `music-library` matched on
+the bare scheme (`http:a.jpg` with no `//`), which `<Image>` cannot load anyway.
+Those strings are now treated as ids.
+
 ## `source` versus `uri` — the failure that is total and silent
 
 `Avatar` invokes the resolver only for a **non-URL string** passed as `source`.

package/docs/listing-actions.mdx

@@ -131,7 +131,7 @@ const [mode, setMode] = useState<ExchangeMode>('swap');
   `'horizontal'` or `'vertical'`.
 - **Box.** DATES | GUESTS are `BookingCard`'s cells; empty ones show
   `datesPlaceholder` / `guestsPlaceholder`.
-- **Mode.** `Chip`s — `swap` "Reciprocal swap", `host` "Guest points", `both`
+- **Mode.** `Chip`s on the `xl` rung (32 tall — a target rather than a tag) — `swap` "Reciprocal swap", `host` "Guest points", `both`
   "Either" (`EXCHANGE_MODE_LABELS`, override with `modeLabels`, restrict with
   `modes`). The chosen one is `selected` (`aria-pressed`).
 
@@ -277,8 +277,9 @@ large icon-only secondary button sits before the primary one.
 - **Calculator** fields are named by their labels; the slider is named
   "Down payment percent" with `aria-value*`; the donut is `role="img"` named by
   its two amounts; the monthly payment is a polite live region.
-- **Checklist** progress is a `progressbar` with `aria-valuenow` / `-max` /
-  `-text`; each action is named with its item ("Upload Employment contract").
+- **Checklist** progress is a [`Meter`](/docs/stat-bar) — a `progressbar` with
+  `aria-valuenow` / `-max` / `-text`; each action is named with its item
+  ("Upload Employment contract").
 - Every custom pressable shows a 2px accent ring under keyboard focus on web.
 
 **Dark mode note.** `TextField` and `Textarea` fill with neutral-800 in dark