@oxy.so/bloom 2.9.0 → 2.11.0

package/docs/creator-studio.mdx

@@ -0,0 +1,153 @@
+---
+title: Creator Studio
+description: The artist and podcaster portal — audience KPIs, streams over time with release markers, top tracks, audience breakdown, the release catalog and its distribution timeline, uploads, track metadata and credits, artwork, payouts and editorial pitching.
+order: 114
+---
+
+# Creator Studio
+
+Everything an artist sees after signing in to their studio. Every block is built on Bloom's own families — `StatCards`, the chart cards (`CartesianPlot`, `BarListCard`, `RadialChartCard`, `PeriodChartHeader`), `DataTable`, `FileUpload`, and the form primitives — so they share geometry, colour, motion and accessibility with the rest of the library.
+
+```tsx
+import {
+  AudienceOverview,
+  StreamsChart,
+  TopTracksTable,
+  AudienceBreakdown,
+  PayoutSummaryCard,
+  ReleaseCard,
+  ReleaseTimeline,
+  TrackUploadRow,
+  TrackMetadataForm,
+  ArtworkUploader,
+  PitchCard,
+} from '@oxy.so/bloom/creator-studio';
+```
+
+Data is props. Numbers that are only displayed (`value`, `delta`, prices, dates) arrive pre-formatted — the app owns currency and locale. Charts take raw numbers and format them with `format` / `formatAxisValue`.
+
+## Dashboard
+
+### AudienceOverview
+
+```tsx
+<AudienceOverview
+  period={period}
+  onPeriodChange={setPeriod}
+  caption="Compared with the previous 28 days"
+  metrics={[
+    { kind: 'listeners', label: 'Listeners', value: '48,210', delta: '+12.4%', trend: 'up', series: last14Days },
+    { kind: 'streams', label: 'Streams', value: '312,904', delta: '+8.1%', trend: 'up', series },
+    { kind: 'followers', label: 'Followers', value: '9,846', delta: '0.0%', trend: 'flat' },
+    { kind: 'saves', label: 'Saves', value: '6,120', delta: '-3.2%', trend: 'down' },
+  ]}
+/>
+```
+
+A heading with a `SegmentedControl` (7 days · 28 days · 12 months · All time, override with `periods`) over plain `StatCards`. Each tile's `accessory` is a `Sparkline` of `series` in the trend's status colour; it is hidden from assistive tech because the value and delta chip already say the same. `trend` maps `up → lime`, `down → rose`, `flat → neutral` on the delta chip. Below 560px of its own width the switcher drops under the heading; the tiles follow `StatCards`' grid (2 columns, 4 from a 1024px window). `kind` picks the icon (headphones, play, follow, bookmark); `icon` overrides it.
+
+### StreamsChart
+
+```tsx
+<StreamsChart
+  metrics={[
+    { id: 'streams', label: 'Streams', data: streamsByDay, delta: 0.081 },
+    { id: 'listeners', label: 'Listeners', data: listenersByDay, delta: 0.124 },
+  ]}
+  events={[{ index: 14, label: 'Low Tide · Single' }]}
+/>
+```
+
+A 360-tall chart card: `PeriodChartHeader` with the metric switcher, then an area + 2.5px monotone line on `CartesianPlot` (dashed grid, Y axis 44). Each metric takes the next chart hue (the first blue, the second purple). An `event` draws a dashed rule, a ring dot on the line, and a label chip pinned to the plot top on whichever side has more room. Hovering (web) or scrubbing (native) moves the headline to the point, and a marked point's release name appears as the caption. The plot is one `role="img"` named `"Streams over time; releases: Low Tide · Single (15 Mar)"`. Controlled with `metric` / `onMetricChange`, or uncontrolled with `defaultMetric`.
+
+### TopTracksTable
+
+`DataTable` in the `inset` layout: rank, 40px cover + title/subtitle, Streams, Listeners, Saves (sortable, descending first) and a trend glyph named Rising / Falling / Steady / New entry. `tracks` is in rank order; the rank stays attached through sorting. Below 560px of its own width the Listeners and Saves columns drop and the cover shrinks to 32, so a phone keeps rank, track, streams and trend without horizontal scrolling. `artwork` is a URL or an ImageResolver id (resolved with the `thumb` variant).
+
+### AudienceBreakdown
+
+Four chart cards on the container's own width — two columns from 720px, one below:
+
+| card | family |
+|---|---|
+| Top locations | `BarListCard` with Cities / Countries tabs, share of listeners |
+| Listening sources | `RadialChartCard` `stacked` (the half-gauge donut with a legend) |
+| Age | `BarListCard`, every group shown |
+| Gender | `RadialChartCard` `stacked` |
+
+### PayoutSummaryCard
+
+The estimate this month (`title-1-medium`) with a delta chip, a 112px monthly bar chart on `CartesianPlot` (band scale, radius 6, the current — last — month in `chart-6`, the rest `chart-track`; hovering names the month and value above the bars), Last payout / Next payout rows under a divider, and a "View statements" link (`onViewStatements` or `statementsHref`).
+
+## Releases
+
+### ReleaseCard and ReleaseStatusBadge
+
+```tsx
+<ReleaseCard
+  release={{ id, title: 'Northbound', artist: 'Juno Varga', type: 'single', releaseDate: '9 Jul 2026',
+             status: 'rejected', statusReason: 'The artwork contains a web address.', trackCount: 2, artwork }}
+  onPress={openRelease}
+  actions={[{ label: 'Edit metadata', icon: RiEditLine }, { label: 'Delete', icon: RiDeleteBinLine, destructive: true }]}
+/>
+```
+
+`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 &lt;title&gt;") is its sibling, never nested. A rejected or taken-down release with a `statusReason` shows it in an error-tinted note.
+
+`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 |
+|---|---|---|
+| `draft` | Draft | default, subtle |
+| `in-review` | In review | warning, subtle |
+| `scheduled` | Scheduled | info, subtle |
+| `live` | Live | success, subtle |
+| `rejected` | Rejected | error, subtle |
+| `takedown` | Taken down | error, outlined |
+
+### ReleaseTimeline
+
+`steps` of `{ id, label, state, date?, description? }` with states `complete` (accent disc + check), `current` (accent ring + dot), `upcoming` (neutral ring) and `error` (error disc + cross). Connectors turn accent after a complete step. `orientation="horizontal"` lays the steps out in a row — it falls back to vertical when its own width gives a step less than 96px. It is a `role="list"` of `listitem`s named "Review, in progress, Usually 2–3 days."; the current step carries `aria-current="step"`.
+
+## New release
+
+### TrackUploadRow
+
+| status | draws |
+|---|---|
+| `queued` | "Queued" |
+| `uploading` | a 4px `progressbar` (named "Uploading &lt;file&gt;", flat `aria-value*`) + "42% · About 20 s left" |
+| `processing` | a decorative running segment (CSS keyframes on web, reanimated on native, still under reduced motion) + "Transcoding…" |
+| `ready` | an accent check tile, a placeholder waveform derived from the file name, "Ready · 3:42" |
+| `failed` | a warning tile, the message in the error colour, and a "Retry" button |
+
+The row is `aria-busy` while uploading or processing; the remove button is named "Remove &lt;file&gt;". `size` is bytes (formatted like `FileUpload`) or a string. Pair the rows with a `FileUpload` limited to audio extensions for the drop zone.
+
+### TrackMetadataForm, ArtistChipsInput, IsrcField, CreditsEditor
+
+`TrackMetadataForm` is controlled (`value` / `onChange` with the whole next value) and composes: title + version (side by side from 560px of its own width), an explicit `Switch` row, genre + language `Select`s, primary (required) and featured `ArtistChipsInput`s, `IsrcField`, a lyrics `Textarea` with a counter, and `CreditsEditor` (`showCredits={false}` to place your own). `errors` paints a field invalid and shows its message.
+
+- `ArtistChipsInput` — names as `Chip`s, each with a remove glyph named "Remove &lt;name&gt;"; Enter or "Add" adds the trimmed name once (case-insensitive). `max` disables the input at the cap.
+- `IsrcField` — groups the value as `CC-XXX-YY-NNNNN` while typing (`formatIsrc`); a complete but malformed code turns invalid (`isValidIsrc`).
+- `CreditsEditor` — rows of role `Select` · name `TextFieldInput` · delete button ("Remove credit 2, Teodor Brask"), and "Add credit" (the new row takes the first role). Below 480px of its own width the role takes its own line. `createId` builds new ids.
+
+### ArtworkUploader
+
+A square up to 320 wide (or `size`). Without `artwork` it is a `FileUpload` limited to JPG / PNG (drag and drop or pick on web; `onPickFiles` on native). With `artwork` it previews the image with "Replace" (swaps back to the drop zone with a Cancel) and a delete button. `error` draws a 2px error ring and the message under the square. The component never decodes an image — measure it in the app and pass `artworkDimensionsError(width, height)`, which returns the "too small" / "must be square" message or `null`.
+
+## Pitching
+
+### PitchCard
+
+A release `Select`, Mood and Genre chip groups (selectable `Chip`s with `aria-pressed`, capped at `maxTags` — the rest disable), a pitch `Textarea` with a `maxLength` counter and a "Send pitch" button that stays disabled until a release and text are in (`loading` while `status="submitting"`). Once `status` is `submitted`, `accepted` or `declined`, the form is replaced by a status panel with the release and `submittedAt`; `onEdit` offers "Edit pitch" while still `submitted`.
+
+## 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/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/eviction.mdx

@@ -0,0 +1,95 @@
+---
+title: Eviction reports
+description: Community reports of upcoming evictions — a report card with status, a coarse area, support counters and an "I'll be there" toggle, and the case history timeline.
+order: 121
+---
+
+# Eviction reports
+
+People publish upcoming evictions so neighbours and support groups can turn up and help.
+These parts draw a report and its history; the moderation, verification and location
+policy live in the app.
+
+```tsx
+import { EvictionReportCard, EvictionTimeline } from '@oxy.so/bloom/eviction';
+
+<EvictionReportCard
+  date="Tuesday, 23 September"
+  time="09:00"
+  relativeLabel="in 3 days"
+  status="scheduled"
+  area="Carabanchel, Madrid"
+  household={['Family with minors', 'Elderly person']}
+  description={report.summary}
+  attendeesLabel="12 people will attend"
+  organisationsLabel="3 organisations supporting"
+  verified
+  attending={attending}
+  onAttendingChange={setAttending}
+  onShare={share}
+  onContactSupport={openSupportChat}
+/>
+
+<EvictionTimeline
+  events={[
+    { kind: 'published', title: 'Report published', date: '2 Sep 2026', source: 'Neighbourhood assembly' },
+    { kind: 'postponed', title: 'Postponed to 23 September', date: '15 Sep 2026', source: 'Family’s lawyer' },
+    { kind: 'date-set', title: 'Eviction scheduled', date: '23 Sep 2026, 09:00', upcoming: true },
+  ]}
+/>
+```
+
+## Privacy: the card takes an AREA, never an address
+
+`area` is a coarse string — a neighbourhood and city ("Carabanchel, Madrid") or a street
+without a number. There is deliberately no field for a door, floor or exact position,
+and no map. **How precise the area is gets decided upstream**, where the report is
+moderated: the component draws whatever it is given, so an app that passes a full
+address has published one. Household details are short free strings ("Family with
+minors") — never names.
+
+`verified` means checked by the community (neighbours, a housing group), NOT by an
+authority, and the default label says so ("Community verified"). Keep that meaning
+when translating.
+
+## Status
+
+| status | badge | meaning |
+| --- | --- | --- |
+| `scheduled` | subtle warning | a date is set |
+| `postponed` | subtle info | the date moved |
+| `suspended` | subtle success | stopped, for now |
+| `executed` | solid neutral (dark on light) | it happened |
+| `cancelled` | subtle neutral | withdrawn |
+
+`relativeLabel` is drawn in the status's text colour. The app computes it ("in 3 days",
+"10 days ago"); the card never reads the clock. `EVICTION_STATUS` is exported.
+
+## Actions
+
+- **I'll be there** is a pill toggle: `aria-pressed` on web and
+  `accessibilityState.selected` on native. Its name stays `attendLabel` in both states —
+  the pressed state carries the change, and the check icon replaces the heart.
+- **Share** and **Contact support group** are small secondary `Button`s, drawn only when
+  their handlers are set. The row wraps on narrow screens.
+
+## `EvictionTimeline`
+
+`TenancyTimeline` (from `@oxy.so/bloom/tenancy`) at comfortable density with a marker
+per `kind`: `published` file, `date-set` calendar (warning), `postponed` clock (info),
+`suspended` shield (success), `executed` house and `cancelled` x (neutral),
+`mobilisation` group, `update` info. `source` is drawn beside the date through
+`formatSource` ("Source: Court notice") so readers can weigh each claim. `upcoming`
+draws a hollow marker. The list is named "Case history" (`accessibilityLabel`).
+
+## A list with a filter
+
+There is no list component — compose the cards with a `SegmentedControl`:
+
+```tsx
+<SegmentedControl label="Show evictions" type="tabs" size="large" value={tab} onChange={setTab}>
+  <SegmentedControlItem value="upcoming"><SegmentedControlItemText>Upcoming</SegmentedControlItemText></SegmentedControlItem>
+  <SegmentedControlItem value="past"><SegmentedControlItemText>Past</SegmentedControlItemText></SegmentedControlItem>
+</SegmentedControl>
+{reports.filter(byTab).map((r) => <EvictionReportCard key={r.id} {...r} />)}
+```

package/docs/home-search.mdx

@@ -0,0 +1,246 @@
+---
+title: Home Search
+description: Search for every housing mode — rent, buy, vacation rentals and swap — with the mode tabs, a segmented search bar per mode, budget, move-in and property-type panels, and saved searches.
+order: 114
+---
+
+# Home Search
+
+One search surface for every way to find a home. `SearchModeTabs` switches
+between Rent, Buy, Vacation rentals and Swap; `HomeSearchBar` draws that mode's
+segments; the panel parts fill the dropdown under the open segment; and
+`SavedSearchCard` / `SaveSearchButton` keep a search for later.
+
+```tsx
+import {
+  BudgetPicker,
+  HomeSearchBar,
+  MoveInPicker,
+  PropertyTypePicker,
+  SavedSearchCard,
+  SaveSearchButton,
+  SearchModeTabs,
+  homeSearchSegments,
+  type HomeSearchMode,
+} from '@oxy.so/bloom/home-search';
+import { DestinationSuggestions, StaySearchPanel } from '@oxy.so/bloom/stay-search';
+
+const [mode, setMode] = useState<HomeSearchMode>('rent');
+const [segment, setSegment] = useState<string | null>(null);
+
+<SearchModeTabs value={mode} onValueChange={(m) => { setMode(m); setSegment(null); }} />
+<HomeSearchBar
+  segments={homeSearchSegments('rent', {
+    location: area,
+    moveIn: moveInText,
+    budget: budgetText, // "€800 – €1,200", formatted by the app
+  })}
+  activeSegment={segment}
+  onActiveSegmentChange={setSegment}
+  query={query}
+  onQueryChange={setQuery}
+  onSearch={search}
+  panel={
+    segment === 'budget' ? (
+      <StaySearchPanel width={420} padding={24} accessibilityLabel="Budget">
+        <BudgetPicker value={budget} onValueChange={setBudget} formatAmount={formatEuro} />
+      </StaySearchPanel>
+    ) : segment === 'moveIn' ? (
+      <StaySearchPanel width={380} padding={24} accessibilityLabel="Move-in">
+        <MoveInPicker value={moveIn} onValueChange={setMoveIn} />
+      </StaySearchPanel>
+    ) : segment === 'location' ? (
+      <StaySearchPanel width={420} accessibilityLabel="Areas">
+        <DestinationSuggestions heading="Suggested areas" items={areas} onSelect={chooseArea} />
+      </StaySearchPanel>
+    ) : null
+  }
+/>
+```
+
+Everything is controlled. Segment values arrive as text the app formatted; the
+panel parts that compute (budgets, property types) take numbers or keys and
+hand them back.
+
+## SearchModeTabs
+
+| prop | decides |
+| --- | --- |
+| `value` / `onValueChange` | the selected mode key |
+| `modes` | which modes and in what order. Default `rent`, `buy`, `stays`, `swap`; any subset works |
+| `labels` | override by key. Defaults Rent, Buy, Vacation rentals, Swap |
+| `variant` | `tabs` (default) or `segmented` |
+| `accessibilityLabel` | the tablist's name, default "Search mode" |
+| `testID` | derives `-<key>` per tab (and `-<key>-bar` for the underline) |
+
+- **`tabs`** — text tabs with the same selected underline as `CategoryBar`:
+  a `body-medium` label, text-secondary at rest and text-primary on hover or
+  when selected, with a 2px text-primary bar the width of the label under the
+  selected one. 24 between labels. The label weight never changes, so
+  switching does not reflow the row.
+- **`segmented`** — Bloom's `SegmentedControl` at `large`, a full pill
+  stretched to the width. Use it on a phone above `StaySearchCompact`.
+
+Both are a `tablist` of `tab`s with `aria-selected`. The `tabs` variant is one
+tab stop on web (the selected tab); ArrowLeft/ArrowRight, Home and End move
+focus, Enter and Space select.
+
+## HomeSearchBar
+
+The segmented search pill for any mode — the shared implementation behind
+`StaySearchBar`, which is its vacation-rental preset (see
+[Stay Search](/docs/bloom/main/stay-search)). Its look is the same: 66 tall, a hairline and a
+soft shadow, segments that fill on hover, a raised pill for the open segment,
+and a round search button that widens to its label while a segment is open.
+
+| prop | decides |
+| --- | --- |
+| `segments` | `{ key, label, value?, placeholder, flex?, panelAlign? }[]`, left to right |
+| `activeSegment` / `onActiveSegmentChange` | the open segment's key, or `null` |
+| `query` / `onQueryChange` | with the handler set, the open **first** segment is a focused text field (a typed location) |
+| `panel` | drops 12 below the bar while a segment is open |
+| `onSearch` / `searchLabel` | the search button in the **last** segment (default "Search") |
+| `dismissible` | Escape and a press outside close it on web. Default `true` |
+| `testID` | derives `-<key>`, `-separator-<i>`, `-search`, `-panel`, `-<firstKey>-input` |
+
+`flex` sets a segment's relative width (default 1). The panel aligns under the
+open segment: `start` for the first, `end` for the last, `center` between —
+`panelAlign` overrides it per segment.
+
+### Presets per mode
+
+`HOME_SEARCH_SEGMENTS` holds each mode's segments with labels, placeholders and
+widths; `homeSearchSegments(mode, values, overrides)` fills the values in and
+applies per-key overrides.
+
+| mode | keys | labels |
+| --- | --- | --- |
+| `rent` | `location`, `moveIn`, `budget` | Location · Move-in · Budget |
+| `buy` | `location`, `price`, `propertyType` | Location · Price · Property type |
+| `stays` | `destination`, `checkIn`, `checkOut`, `guests` | Where · Check in · Check out · Who |
+| `swap` | `destination`, `dates`, `homeSize` | Where · Dates · Home size |
+
+```tsx
+homeSearchSegments('buy', { location: 'Marrowfield', price: '€150K – €300K' }, { propertyType: { label: 'Type' } });
+```
+
+For locations, reuse `DestinationSuggestions` from `@oxy.so/bloom/stay-search`
+with a heading such as "Suggested areas" — there is no separate location list.
+For stay dates and guests, reuse `RangeCalendar`, `DateFlexibilityChips` and
+`GuestPicker`; for a swap's home size, `StepperRow` from
+`@oxy.so/bloom/stepper`.
+
+## BudgetPicker
+
+A title, a Minimum / Maximum pair of fields and preset chips.
+
+| prop | decides |
+| --- | --- |
+| `value` / `onValueChange` | `[min, max]`; `null` is open-ended |
+| `period` | `month` (rent, default) or `total` (sale) — picks the defaults below |
+| `presets` | `{ min, max, label? }[]`; `[]` hides the row |
+| `formatAmount` | how amounts show in the fields and preset labels (the app's currency and locale). Default `String(n)` |
+| `title` / `description` | defaults "Monthly budget" / "Rent per month, before bills", or "Price" / "Total price"; `description={null}` hides it |
+| `minLabel` / `maxLabel` | default "Minimum" / "Maximum" |
+| `step` | typed amounts snap to it. Default 50 per month, 5,000 total |
+| `presetsLabel` | names the chip group, default "Budget presets" |
+
+Default presets: `month` — up to 800, 800–1,200, 1,200–1,800, 1,800+; `total`
+— up to 150,000, 150,000–300,000, 300,000–600,000, 600,000+. A preset's label
+is built from `formatAmount` ("Up to €800", "€800 – €1,200", "€1,800+") unless
+it has its own.
+
+This part **computes**: typed text is a draft until blur or submit, then
+parsed ("€1,200" reads as 1200), snapped to `step` and kept on its own side of
+the range. An emptied field commits `null`. A preset sets both ends; pressing
+the chosen preset again clears the budget. Chips are Bloom `Chip`s (`large`,
+`outlined`, brand tone when chosen) with `aria-pressed`.
+
+## MoveInPicker
+
+A single-day `Calendar`, "Flexible" / "As soon as possible" chips, and the
+contract length.
+
+| prop | decides |
+| --- | --- |
+| `value` / `onValueChange` | `{ timing: 'date' \| 'flexible' \| 'asap', date, contractLength }` |
+| `contractLengths` | `{ value, label }[]`. Default `any` Any, `short` 1–6 months, `medium` 6–12 months, `long` 1+ year |
+| `labels` | `date`, `flexible`, `asap`, `contractLength` headings and chip labels |
+| `defaultMonth`, `minDate`, `maxDate`, `isDateUnavailable`, `weekStartsOn`, `locale` | passed to `Calendar` |
+
+There is one answer to "when": picking a day sets `timing: 'date'`; a timing
+chip sets its timing and clears the day, and pressing it again goes back to
+`date`. While a chip is chosen the calendar shows no day. The contract length
+is independent and single-select.
+
+## PropertyTypePicker
+
+A multi-select grid of icon tiles: Apartment, House, Room, Studio,
+Duplex / Penthouse, Coliving, Hostel, Land / Other. An empty selection means
+any type.
+
+| prop | decides |
+| --- | --- |
+| `value` / `onValueChange` | the selected keys, reported in option order |
+| `options` | `{ value, label, icon }[]`. Default `PROPERTY_TYPE_OPTIONS` from `@oxy.so/bloom/stay-filters` |
+| `labels` | override built-in labels by key |
+| `columns` | tiles per row. Default: as many as fit (2 to 4) |
+| `accessibilityLabel` | default "Property type" |
+
+Tiles have radius 12, a 24px icon over a `body-2-medium` label, 12 inset, at
+least 92 tall so a two-line label fits. At rest they have a 1px neutral-200
+(dark neutral-700) border; hover turns the border text-primary. **Selected** is
+a 2px text-primary border on a neutral-100 (dark neutral-800) tint — the inset
+gives back the extra pixel, so the content does not move. Each tile is a toggle
+`button` with `aria-pressed`. The same tiles, larger, are
+`PropertyTypeFilter` in [Stay Filters](/docs/bloom/main/stay-filters).
+
+## SavedSearchCard
+
+| prop | decides |
+| --- | --- |
+| `title` | the search's name, two lines at most |
+| `criteria` | short pre-formatted strings drawn as outlined chips |
+| `newCount` / `formatNewCount` | a primary `Badge` ("12 new") while above 0 |
+| `alertFrequency` / `alertsOffLabel` | the footer line with a bell; without a frequency a struck bell and "Alerts off" |
+| `icon` | the 44px tile's glyph. Default a search glyph |
+| `onPress` | opens the results; makes the header a button |
+| `onEdit` / `onDelete` | an "Edit" button and a delete icon button (`editLabel`, `deleteLabel`) |
+
+The card has radius 16, the card surface with a hairline, 16 inset. The header
+button is named "title, 12 new" and fills neutral on hover. The Edit and Delete
+buttons sit beside it, not inside it, and are named "Edit <title>" and
+"Delete <title>".
+
+## SaveSearchButton
+
+`saved`, `onSavedChange`, `label` (default "Save search"), `savedLabel`
+(default "Saved"), `disabled`. It is the 40-tall filter pill with a bell: an
+outline bell at rest, and inverted with a filled bell once saved. It is a
+toggle `button` with `aria-pressed`, named by the label it shows.
+
+## Mobile
+
+On a phone, put `SearchModeTabs variant="segmented"` above a
+`StaySearchCompact` whose `title` and `summary` describe the mode ("Find a home
+to rent", "Anywhere · Any time · Any budget"). It opens a sheet of
+`StaySearchStep` cards, one per segment, with the same panel parts inside. The
+stories show the flow for each mode at 375.
+
+## Accessibility
+
+- Mode tabs are a `tablist` with `aria-selected` on web and
+  `accessibilityState.selected` on native.
+- Bar segments are `button`s with `aria-expanded`; the typed location field is
+  named by its segment label.
+- Chips carry `aria-pressed`; property tiles and the save toggle carry
+  `aria-pressed` plus `accessibilityState.selected` for native.
+- Keyboard focus draws an accent ring on tabs, segments, tiles and the saved
+  card's header (`:focus-visible` only). Hover and selection are colour changes
+  only, and nothing scales.
+
+## Platform notes
+
+The panel drops below the bar with absolute positioning. On Android a panel
+that reaches past its parent's bounds does not receive touches, so use the
+compact trigger and a sheet on phones.

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