@oxy.so/bloom 2.8.0 → 2.10.0

package/README.md

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

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

package/docs/chat-indicators.mdx

@@ -0,0 +1,178 @@
+---
+title: Chat Indicators
+description: Presence dots, delivery ticks, unread counts, typing dots and the story ring — the small pieces every messaging surface repeats.
+order: 63
+---
+
+# Chat Indicators
+
+```tsx
+import {
+  AvatarPresence,
+  MessageStatus,
+  PresenceDot,
+  StoryRing,
+  TypingDots,
+  UnreadBadge,
+  formatUnreadCount,
+} from '@oxy.so/bloom/chat-indicators';
+```
+
+Six pieces, none of them a layout: they sit inside a row, a header or a bubble
+that someone else owns. Everything is a PROP — no component here reads the
+clock, formats a name or decides what "recently" means.
+
+## `PresenceDot`
+
+```tsx
+<PresenceDot status="online" />
+<PresenceDot status="busy" size="large" ringColor={theme.colors.backgroundSecondary} />
+<PresenceDot status="offline" accessibilityLabel="" />   // the row already says it
+```
+
+| prop                 | decides                                                                      |
+| -------------------- | ---------------------------------------------------------------------------- |
+| `status`             | `'online'` success · `'idle'` warning · `'busy'` negative · `'offline'` hollow neutral |
+| `size`               | `'small'` 8, `'medium'` 10 (default), `'large'` 12 — the DOT, not the footprint |
+| `ringColor`          | the colour separating the dot from what is behind it; default the page background |
+| `ringWidth`          | default `2`; `0` draws no ring                                               |
+| `accessibilityLabel` | default "Online" / "Away" / "Offline" / "Busy"; `""` hides it from assistive tech |
+
+`offline` is a HOLLOW dot, not a grey one. Four states told apart by hue alone
+are four states one reader in twelve cannot tell apart at all, so the quiet one
+differs in shape too.
+
+The ring is drawn OUTSIDE the dot, so the component measures
+`size + 2 * ringWidth` (14 at the default medium). On a card, pass the card's
+own colour as `ringColor` — the default is the page background, which reads as
+a halo on a raised surface.
+
+## `AvatarPresence`
+
+```tsx
+<AvatarPresence name="Ana Restrepo" source={avatarUrl} size={44} status="online" />
+```
+
+Every `Avatar` prop passes through (`source`, `uri`, `name`, `initials`,
+`shape`, `size`, `onPress`, …) plus:
+
+| prop                | decides                                                       |
+| ------------------- | ------------------------------------------------------------- |
+| `status`            | the dot; omit it to draw the avatar alone                     |
+| `presenceSize`      | overrides the rung picked from the avatar size                |
+| `presenceRingColor` | forwarded to the dot                                          |
+| `presenceLabel`     | forwarded to the dot's `accessibilityLabel`                   |
+| `containerStyle`    | the positioning wrapper, not the avatar                       |
+
+The rung follows the avatar: `small` to 28px, `medium` to 44px, `large` above.
+The dot sits at the bottom-right corner of the avatar's own box, where the 45°
+edge of a circle passes through it — so the footprint never changes when
+someone comes online, and a list does not re-lay-out as presence arrives.
+
+## `MessageStatus`
+
+The delivery ticks on an OUTGOING message. Never draw it on an incoming one.
+
+```tsx
+<MessageStatus status="read" />
+<MessageStatus status="sent" size={12} color={onBubbleColor} />
+```
+
+| status      | glyph                  | colour        | default name |
+| ----------- | ---------------------- | ------------- | ------------ |
+| `sending`   | clock outline          | muted         | "Sending…"   |
+| `sent`      | one tick               | muted         | "Sent"       |
+| `delivered` | two ticks              | muted         | "Delivered"  |
+| `read`      | two ticks              | ACCENT        | "Read"       |
+| `failed`    | filled error circle    | negative      | "Not sent"   |
+
+`size` is `12 | 14 | 16` (default 14). `color` repaints the glyph for ticks on a
+coloured bubble — except `failed`, which stays negative: an error recoloured to
+match the bubble stops reading as an error. `label=""` hides the glyph from
+assistive tech for a bubble whose own text reports delivery.
+
+`read` and `delivered` differ by COLOUR alone, which is why the name is not
+optional — that distinction does not survive a screen reader or a red-green
+confusion, and the tick count is the same.
+
+## `UnreadBadge`
+
+```tsx
+<UnreadBadge count={3} />
+<UnreadBadge count={128} />            // "99+", named "128 unread messages"
+<UnreadBadge count={6} muted />        // notifications off
+<UnreadBadge count={2} dot />          // no number
+<UnreadBadge count={0} />              // renders nothing
+```
+
+| prop                 | decides                                                             |
+| -------------------- | ------------------------------------------------------------------- |
+| `count`              | `0` or less renders `null` (unless `dot`)                           |
+| `max`                | default `99`; above it the pill reads `"99+"`                       |
+| `dot`                | a plain dot, no number — 8 (small) or 10 (medium)                   |
+| `muted`              | neutral fill instead of the accent                                  |
+| `size`               | `'small'` 16 tall, `'medium'` 20 (default); one digit is a circle   |
+| `formatLabel`        | `(count) => string` for the accessible name — it gets the REAL count |
+| `accessibilityLabel` | replaces the composed name outright                                 |
+| `textStyle`          | the digits                                                          |
+
+The clamp is a layout constraint, not information: the drawn text says "99+"
+while the name still says "128 unread messages". The default name is English
+("1 unread message" / "3 unread messages", "Unread" for a bare dot) — translate
+it with `formatLabel`.
+
+`formatUnreadCount(count, max = 99)` is exported for the places that need the
+same string outside a badge (a tab title, a document title).
+
+## `TypingDots`
+
+```tsx
+<TypingDots />                              // decorative, inside a bubble
+<TypingDots label="Ana is typing…" />       // named, in a row
+```
+
+| prop         | decides                                              |
+| ------------ | ---------------------------------------------------- |
+| `size`       | dot diameter, default `6`                            |
+| `color`      | default the secondary text colour                    |
+| `label`      | drawn beside the dots AND used as the accessible name |
+| `labelStyle` | the label text                                       |
+
+Each dot lifts 55% of its diameter and fades from 0.45 to 1 over 900ms,
+staggered 150ms. Under reduced motion they stand still and fully opaque — the
+row still says "typing", it just stops moving. Without a `label` the component is decorative
+and hidden from assistive tech: three bouncing dots have nothing to announce.
+
+## `StoryRing`
+
+```tsx
+<StoryRing state="unseen" size={56} onPress={open} accessibilityLabel="Ana's story">
+  <Avatar name="Ana Restrepo" size={56} />
+</StoryRing>
+```
+
+| prop                 | decides                                                                 |
+| -------------------- | ----------------------------------------------------------------------- |
+| `state`              | `'unseen'` a three-stop accent gradient · `'seen'` neutral hairline · `'none'` no ring, same footprint |
+| `size`               | the AVATAR's diameter                                                   |
+| `thickness`          | ring stroke, default `2`                                                |
+| `gap`                | avatar edge to ring, default `2`                                        |
+| `colors`             | one string for a solid ring, 2+ for a gradient — overrides the state's own |
+| `badge`              | a node pinned bottom-right: an "Add" affordance, a `+ N` pill           |
+| `onPress`            | wraps it in a `button` — `accessibilityLabel` is then required          |
+
+The component measures `size + 2 * (thickness + gap)` — 68 for a 56px avatar at
+the defaults. `'none'` keeps that footprint: a row where one person has no
+story must not shift by 8px, and a list that re-lays-out as stories are read is
+worse than a ring nobody needed.
+
+A solid ring is a bordered view; only the gradient goes through
+`react-native-svg` (which `Avatar` already needs). Both platforms draw the same
+ring.
+
+## What these do not do
+
+- **No clock.** "12:41", "Yesterday", "last seen recently" arrive as strings.
+- **No press animation.** Nothing here scales under a finger.
+- **No layout.** Rows, bubbles and headers own their own geometry; these are
+  marks that sit inside one.

package/docs/creator-studio.mdx

@@ -0,0 +1,146 @@
+---
+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 `Chip` whose recipe is `RELEASE_STATUS_TONES`:
+
+| 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`.

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} />)}
+```