@oxy.so/bloom 2.8.0 → 2.10.0

package/docs/music-library.mdx

@@ -0,0 +1,159 @@
+---
+title: Music Library
+description: The Your Library side panel and its rows, plus the search page parts — the search pill, result tabs, top result card, recent searches and the browse grid.
+order: 66
+---
+
+# Music Library
+
+Two screens of a music app: the library panel on the left, and the search page.
+
+```tsx
+import {
+  BrowseGrid,
+  LibraryItem,
+  LibraryPanel,
+  RecentSearches,
+  SearchField,
+  SearchResultTabs,
+  TopResultCard,
+  filterLibraryItems,
+  sortLibraryItems,
+} from '@oxy.so/bloom/music-library';
+```
+
+Colours come from the theme in light and dark: surfaces are the page background stepped toward the text colour (so a panel reads as a panel on any page), the accent is the theme's `primary`. Hover and press change colour only — nothing scales.
+
+## `LibraryPanel`
+
+```tsx
+<LibraryPanel
+  items={entries}
+  selectedId={openPageId}
+  nowPlayingId={context?.id}
+  paused={!playing}
+  onItemPress={(item) => router.push(`/library/${item.id}`)}
+  onCreatePress={openCreateMenu}
+  collapsed={railOpen}
+  onCollapsedChange={setRailOpen}
+  expanded={wide}
+  onExpandedChange={setWide}
+  renderContextMenu={(item) => (
+    <>
+      <ContextMenuItem onPress={() => pin(item)}>{item.pinned ? 'Unpin' : 'Pin'}</ContextMenuItem>
+      <ContextMenuItem variant="destructive" onPress={() => remove(item)}>Remove from Your Library</ContextMenuItem>
+    </>
+  )}
+  style={{ width: wide ? 560 : 360, height: '100%' }}
+/>
+```
+
+| prop | decides |
+| --- | --- |
+| `items` | `LibraryEntry[]` — `id`, `title`, `kind` (`playlist` · `artist` · `album` · `podcast` · `audiobook` · `folder`), `subtitle` ("Maya"), `meta` (replaces "Playlist · Maya"), `cover` (URL or ImageResolver id), `pinned`, `downloaded`, `addedAt`, `lastPlayedAt`, `creator` |
+| `filter` / `onFilterChange` | the kind chip, or `null`. Pressing the active chip turns it off; the × chip clears the kind and Downloaded |
+| `downloadedOnly` / `onDownloadedOnlyChange` | the Downloaded chip — combines with the kind filter (AND) |
+| `sort` / `onSortChange` | `recents` (default) · `recently-added` · `alphabetical` · `creator` |
+| `view` / `onViewChange` | `compact` · `list` (default) · `grid` |
+| `query` / `onQueryChange` | the in-library search, opened from the search glyph |
+| `filters`, `hideDownloadedFilter` | which chips to draw |
+| `collapsed`, `onCollapsedChange` | the rail: 72 wide, covers only, tooltips on web. The title becomes the rail toggle when `onCollapsedChange` is set |
+| `expanded`, `onExpandedChange` | draws the expand toggle; the panel's width is yours to change |
+| `onCreatePress` | draws the + button |
+| `selectedId`, `nowPlayingId`, `paused` | the open page's fill, the playing entry's accent title and bars |
+| `renderContextMenu` | `ContextMenuItem` rows per entry — right-click on web, long press on native |
+| `labels` | every string, merged over English defaults (nested `filter`, `sort`, `view`, `kind`) |
+| `emptyState` | replaces "Nothing here yet" |
+
+**Controlled or not, per value.** Filter, Downloaded, sort, view and query each follow their prop when it is set and keep their own state when it is not; the change callback fires in both cases. So `sort="alphabetical"` alone pins the sort while the chips stay interactive.
+
+**Order.** Pinned entries always lead, in the current sort among themselves. `recents` and `recently-added` put entries without the timestamp last; `alphabetical` ignores case and accents; `creator` sorts by `creator`, else `subtitle`, then title. The sort is stable.
+
+The logic is exported so a server-backed library can apply the same rules:
+
+```ts
+const shown = sortLibraryItems(filterLibraryItems(items, { filter, downloadedOnly, query }), sort);
+```
+
+The sort and view menu is one `DropdownMenu` with two radio groups; its trigger is named "Sort and view: Recents, List".
+
+## `LibraryItem`
+
+One row, used by the panel and usable on its own (a "Your playlists" list elsewhere).
+
+| `variant` | draws |
+| --- | --- |
+| `list` (default) | 48 cover (a circle for artists) · title over "Playlist · Maya", led by the pinned and downloaded glyphs · the now-playing bars |
+| `compact` | title · meta on one line, no cover |
+| `grid` | a square cover filling the tile, title, meta |
+| `rail` | the cover alone, the bars on its corner while playing; a tooltip on web hover |
+
+The row is a `button` named by everything it shows — "Night Drive, Playlist · Maya, Pinned, Downloaded, Now playing" — because the glyphs carry state no text does. `selected` sets `aria-current="page"` on web and `accessibilityState.selected` on native. `pinnedLabel`, `downloadedLabel`, `nowPlayingLabel` and `kindLabels` translate it.
+
+## `SearchField`
+
+```tsx
+<SearchField
+  value={query}
+  onChangeText={setQuery}
+  onClear={() => setQuery('')}
+  onSubmit={runSearch}
+  onBrowsePress={() => router.push('/search')}
+  browseActive={onBrowsePage}
+/>
+```
+
+A 48-tall full pill: search glyph, input, a clear × once there is text, then a divider and the browse button. The field is controlled — `onClear` reports, it does not clear. The browse button is a toggle (`aria-pressed` on web, `accessibilityState.selected` on native). A press anywhere on the pill focuses the input; focus draws a text-coloured border without changing the size.
+
+## `SearchResultTabs`
+
+```tsx
+<SearchResultTabs
+  tabs={[{ value: 'all', label: 'All' }, { value: 'songs', label: 'Songs' }, { value: 'artists', label: 'Artists' }]}
+  value={tab}
+  onValueChange={setTab}
+/>
+```
+
+Pills painted like `Chip` (neutral at rest, primary subtle when selected), 32 tall, scrolling sideways when they do not fit. A `tablist` of `tab`s with `aria-selected`; on web the row is one tab stop and the arrow keys, Home and End move focus.
+
+## `TopResultCard`
+
+```tsx
+<TopResultCard
+  title="Lumen Vale"
+  kind="artist"
+  subtitle="4.2M monthly listeners"
+  cover={artist.image}
+  onPress={openArtist}
+  onPlayPress={playArtist}
+  playing={isPlaying}
+/>
+```
+
+A 16-radius card: a 92 cover (round for `artist` and `profile`), the title in `title-1-bold`, a kind pill and the subtitle. The `PlayButton` sits in the bottom-right corner — on web it fades in on hover or keyboard focus (and stays while playing), on touch and native it is always shown. It is a sibling of the card's button, not nested in it, so both are reachable. `kindLabel` translates the pill.
+
+## `RecentSearches`
+
+```tsx
+<RecentSearches
+  items={recent}
+  onItemPress={(item) => setQuery(item.title)}
+  onRemove={(item) => forget(item.id)}
+  onClearAll={forgetAll}
+/>
+```
+
+Rows of cover, title and meta with a × button beside each (a separate control named "Remove Paper Moons"), and a "Clear recent searches" button while there is anything to clear. `round` draws an artist's cover as a circle.
+
+## `BrowseGrid`
+
+```tsx
+<BrowseGrid title="Browse all" items={genres} onItemPress={openGenre} />
+
+<BrowseGrid minTileWidth={200}>
+  {moods.map((mood) => <MoodCard key={mood.id} {...mood} />)}
+</BrowseGrid>
+```
+
+Columns are as many as fit at `minTileWidth` (default 128, which is two on a phone), measured from the grid's width. With `items` each tile is a 12-radius colour block with its title and a tilted image in the corner. **The title always clears 4.5:1**: white when white does, near-black when that does, and for a mid-grey that neither clears the tile's fill is darkened until white does — so any colour the backend sends stays readable. An unparseable colour falls back to a neutral tile. With `children`, each child is one cell and draws itself.

package/docs/offering-badge.mdx

@@ -0,0 +1,73 @@
+---
+title: Offering Badge
+description: A small pill naming how a home is offered — for rent, for sale, vacation rental or swap — tinted on the page or light over a photo.
+order: 106
+---
+
+# Offering Badge
+
+```tsx
+import { OfferingBadge } from '@oxy.so/bloom/offering-badge';
+import type { Offering } from '@oxy.so/bloom/offering-badge';
+
+<OfferingBadge offering="long_term_rent" />
+<OfferingBadge offering="sale" size="small" />
+<OfferingBadge offering="short_term_rent" variant="onMedia" />
+<OfferingBadge offering="exchange" label="Intercambio" />
+```
+
+An **offering** is how a home is put on the market, and a listing may carry
+several at once (a flat for rent and for sale). A room, a studio or a house is
+the property's _type_, not an offering.
+
+```ts
+type Offering = 'long_term_rent' | 'short_term_rent' | 'sale' | 'exchange';
+```
+
+The type lives with the listing card (`@oxy.so/bloom/listing-card`) and is
+re-exported here.
+
+| prop       | decides                                                                                      |
+| ---------- | -------------------------------------------------------------------------------------------- |
+| `offering` | the default label, icon and tint                                                             |
+| `label`    | replaces the English label — "For rent", "For sale", "Vacation rental", "Swap"               |
+| `icon`     | `true` (default) the offering's icon, `false` none, or an icon component to draw instead     |
+| `size`     | `'medium'` (default) or `'small'`                                                            |
+| `variant`  | `'tinted'` (default) on the page, `'onMedia'` over a photo                                   |
+| `style`, `testID` | the icon is `<testID>-icon`                                                           |
+
+## Anatomy
+
+|          | height | padding-x | icon | text                 |
+| -------- | ------ | --------- | ---- | -------------------- |
+| `small`  | 20     | 8         | 12   | `caption-1-semibold` |
+| `medium` | 24     | 10        | 14   | `body-2-semibold`    |
+
+A full pill, 4 between the icon and the label, the leading padding 2 tighter
+when there is an icon. One line, truncated.
+
+| offering          | icon                   | tone      |
+| ----------------- | ---------------------- | --------- |
+| `long_term_rent`  | `RiKey2Line`           | `info`    |
+| `sale`            | `RiPriceTag3Line`      | `success` |
+| `short_term_rent` | `RiSuitcaseLine`       | `warning` |
+| `exchange`        | `RiArrowLeftRightLine` | `default` (neutral) |
+
+## Colour
+
+`tinted` paints the tone's `subtle` pair from `resolveAccentColors` — the tint and
+its foreground, gated at AA by the colour policy, so nothing is derived here.
+The tones are **fixed**, never the preset's brand colour: `info`, `success` and
+`warning` do not move with the preset, so "blue is rent" holds in every app,
+whereas a brand tint would collide with one of them (a blue brand IS `info`, a
+green one `success`). Swap takes the one neutral, which no preset can collide
+with. The four stay distinct on every preset in both modes.
+
+`onMedia` is a `neutral-50` pill with a `neutral-900` label and icon and
+`shadow-s`, the same in both modes because the photo under it does not change
+with the theme.
+
+## Accessibility
+
+It is text, not a control: no role, the icon hidden, so it reads as its label.
+Inside a pressable card, fold the label into the card's name — `ListingCard` does.

package/docs/place-reviews.mdx

@@ -0,0 +1,80 @@
+---
+title: Place reviews
+description: Reviews of a building by its past tenants — an anonymised review card with housing categories, a summary with deposit and recommendation stats, and an invitation to review.
+order: 122
+---
+
+# Place reviews
+
+Reviews of a BUILDING, not a listing: they outlive any one listing and stay with the
+place.
+
+```tsx
+import { PlaceReviewCard, PlaceReviewSummary, WriteReviewPrompt } from '@oxy.so/bloom/place-reviews';
+
+<PlaceReviewSummary
+  rating={3.9}
+  title="Rated by past tenants"
+  reviewCount={46}
+  categories={[
+    { label: 'Landlord responsiveness', value: 3.4, icon: RiCustomerService2Line },
+    { label: 'Maintenance', value: 3.1, icon: RiToolsLine },
+    { label: 'Noise', value: 4.2, icon: RiVolumeDownLine },
+  ]}
+  depositReturnedRate={0.82}
+  recommendRate={0.71}
+/>
+
+<WriteReviewPrompt buildingTitle="Calle del Olmo 14" onStart={openReviewForm} onDismiss={hide} />
+
+<PlaceReviewCard
+  authorLabel="Tenant, 2021–2024"
+  authorInitial="T"
+  date="Reviewed March 2026"
+  rating={4}
+  wouldRecommend
+  depositReturned
+  categories={[{ label: 'Maintenance', value: 3.5 }, { label: 'Neighbours', value: 5 }]}
+  text={review.text}
+  helpfulCount={12}
+  helpful={helpful}
+  onHelpfulChange={setHelpful}
+  onReport={report}
+/>
+```
+
+## Anonymous by construction
+
+`PlaceReviewCard` has no name field: `authorLabel` is the anonymised line ("Tenant,
+2021–2023") and `authorInitial` an optional single letter in the avatar disc. A review
+of a building can reach the landlord, so the app decides what the line reveals.
+
+## `PlaceReviewSummary` reuses `ReviewSummary`
+
+It renders `ReviewSummary` from `@oxy.so/bloom/listing-details` — the big rating, the
+title, "46 reviews" and the category `RatingBar`s in two columns from 640 wide — and adds
+the tenancy stat lines under it. It does not copy that part, so the two stay one design.
+
+The rates are fractions (0..1) and are the one thing computed here: rounded to a whole
+percent and passed to `formatDepositReturned` ("Deposit returned in 82% of tenancies")
+and `formatRecommend` ("71% would recommend living here"). Each line is one accessible
+element. `formatReviewCount` defaults to "1 review" / "46 reviews".
+
+## `PlaceReviewCard`
+
+- **Chips:** would recommend (success) or not (neutral); deposit returned (success) or
+  not (error). `undefined` draws neither — unknown is not "no".
+- **Categories:** `RatingBar`s, two columns from 520 wide (`layout="auto"`), one below.
+- **Text:** clamped to `numberOfLines` (4); "Show more" appears only when the text IS
+  clamped (measured), with `aria-expanded` / `expanded`.
+- **Helpful:** a pill toggle with `aria-pressed` (web) and `accessibilityState.selected`
+  (native), named "Helpful, 12". The count is the caller's — add the viewer's vote
+  yourself.
+- **Report:** a secondary link button, drawn with `onReport`.
+
+## `WriteReviewPrompt`
+
+A card with a building tile, "Did you live here?" (a heading), a description that names
+`buildingTitle`, and a small primary "Write a review" button that drops under the text
+when narrow. `onDismiss` adds a close button named `dismissLabel`. `media` replaces the
+tile (a photo of the building).

package/docs/property-insights.mdx

@@ -0,0 +1,177 @@
+---
+title: Property insights
+description: The data parts of a home for rent or sale — energy label and badge, price history chart, explainable price estimate, price per area comparison, neighbourhood scores, nearby places and rent history.
+order: 114
+---
+
+# Property insights
+
+```tsx
+import {
+  EnergyBadge,
+  EnergyLabel,
+  NearbyPlaces,
+  NeighbourhoodScores,
+  PriceEstimate,
+  PriceHistoryChart,
+  PricePerAreaComparison,
+  RentHistoryList,
+} from '@oxy.so/bloom/property-insights';
+
+<ListingSection title="Energy certificate">
+  <EnergyLabel
+    consumption={{ rating: 'C', value: '112 kWh/m²·year' }}
+    emissions={{ rating: 'D', value: '24 kg CO₂/m²·year' }}
+  />
+</ListingSection>
+
+<ListingSection title="Is the price right?">
+  <PriceEstimate
+    low={362000}
+    high={398000}
+    estimate={381000}
+    asking={385000}
+    confidence="high"
+    confidenceNote="Nine recent sales nearby"
+    reasons={reasons}
+    comparables={24}
+    method="Automated valuation"
+    version="Model 3.2"
+    updated="Updated 2 Sep 2026"
+    format={formatPrice}
+  />
+  <PriceHistoryChart periods={periods} format={formatPrice} formatAxisValue={formatPriceShort} />
+  <PricePerAreaComparison rows={[
+    { label: 'This home', value: 2790, display: '€2,790/m²', highlight: true },
+    { label: 'Cedofeita', value: 2940, display: '€2,940/m²' },
+  ]} />
+</ListingSection>
+
+<ListingSection title="The neighbourhood">
+  <NeighbourhoodScores items={scores} />
+  <NearbyPlaces items={places} />
+</ListingSection>
+
+<ListingSection title="Rent history">
+  <RentHistoryList items={history} />
+</ListingSection>
+```
+
+The page around them — facts, floor plans, the agent or landlord card — is in
+[`@oxy.so/bloom/listing-details`](./listing-details) (`PropertyFacts`, `FloorPlan`,
+`ContactCard`). Storybook: **Blocks/Housing/Property Insights** has a full sale page
+and a rental page at 1280 and 390, light and dark, and every part alone.
+
+## What arrives formatted, and what the parts compute
+
+Labels, dates, units, `display` values and deltas are pre-formatted strings. Three
+parts must do arithmetic, so they take NUMBERS plus a `format` function (the app owns
+currency and locale; the default is `€385,000`):
+
+| part | computes |
+| --- | --- |
+| `PriceHistoryChart` | the Y domain and ticks, the path, the headline and the chart summary |
+| `PriceEstimate` | the bar positions, the verdict and its percentage |
+| `PricePerAreaComparison` | bar lengths (`value / largest value`); the label is `display` |
+| `NeighbourhoodScores` | `value / max`; the label is `display`, default `value` to one decimal |
+
+## `EnergyLabel` and `EnergyBadge`
+
+Seven bars, A → G, 24 tall and 4 apart; A is 40% of the scale column and each class
+adds 10%. The colours are Bloom's own scale on the theme: a fixed lightness curve
+(dark green, up to a light yellow at D, down to a deep red) with the HUES taken from
+the theme's `success` (A), `warning` (E) and `error` (G), interpolated in OKLCH. The
+letter is white or neutral-950, whichever contrasts more — at least 4.5:1 in every
+preset and mode (gated).
+
+Each rating given (`consumption`, `emissions`) gets a column with an arrow tag on its
+class's row, in the class colour: "C · 112 kWh/m²·year". With both columns below 560
+wide the tags hold the letter only and the values move under the scale, so nothing
+truncates on a phone. `pending` draws the scale neutral, no tags, and "Certificate in
+progress" (`pendingLabel`).
+
+The label is one image with a composed name ("Energy rating. Consumption: C,
+112 kWh/m²·year. Emissions: D, 24 kg CO₂/m²·year.").
+
+`EnergyBadge` is the class inline — a neutral pill (20 / 24 tall, `size`) with a disc in
+the class colour and `label` ("Energy"; `""` for the class alone). Without `rating`, or
+with `pending`, it draws a clock and "Pending". Named "Energy rating C".
+
+## `PriceHistoryChart`
+
+Built on the chart-card primitives (`ChartCardSurface`, `PeriodChartHeader`,
+`CartesianPlot`): the headline is the current price and follows the hovered point;
+`periods` are the 1Y / 3Y / All segments, each with its own `data` and `events`.
+
+- `shape="step"` (default) holds each price until it changes — an asking price does not
+  glide between listings. `shape="line"` joins the points.
+- The Y axis is nice ticks AROUND the prices, not from zero, so a 5% drop is visible.
+- `events` are markers on their point, coloured by `kind`: `listed` primary,
+  `price-drop` success, `price-rise` warning, `rented` / `sold` text, `delisted`
+  tertiary — and repeated as text in a legend under the plot.
+- The last point carries a "Now · €385,000" callout (`currentLabel`), hidden while a
+  point is hovered.
+- Fewer than two points draw "No price history yet" (`emptyLabel`) instead of a plot.
+
+**Accessible summary.** The plot's `role="img"` is named by a composed summary: "Price
+history, 1Y: from €405,000 in September 2025 to €385,000 in March 2026. Listed,
+September 2025. Price drop −5%, March 2026." (`accessibilityLabel` overrides it). Give
+points a `title` so the summary reads in full months, not axis labels.
+
+## `PriceEstimate`
+
+An estimate that explains itself and never implies precision it does not have.
+
+- The range as a heading, then a bar: the band `low` → `high`, the point `estimate` as
+  a tick, the `asking` price as a taller marker with its label, and the ends labelled.
+- The verdict compares `asking` with the NEAREST edge of the range: inside is "Fair
+  price" (success); below is "Below estimate by 6%" (success); above is "Above estimate
+  by 8%" — warning up to `highAboveRatio` (10%), error beyond. `formatVerdict`
+  translates it.
+- `confidence` is a 3-segment meter (a `progressbar`, 1–3) with its label and
+  `confidenceNote`.
+- "Why this estimate" expands `reasons` and the `comparables` count; the footer joins
+  `method`, `version` and `updated`.
+
+### Confidence changes the drawing, not just the label
+
+| confidence | band drawn | core band | estimate tick | verdict |
+| --- | --- | --- | --- | --- |
+| `high` | `low` → `high` | accent | shown | shown |
+| `medium` | widened by 25% of the range each side, soft | accent | shown | shown |
+| `low` | widened by 50% of the range each side, soft | **soft, no firm edge** | **hidden** | **replaced by "Not enough data for a verdict"** |
+
+`confidence: 'low'` widens the visual band and hides the verdict. The numbers under
+the band stay the model's range — only the picture refuses to look precise.
+
+## `PricePerAreaComparison`
+
+Rows of label + `display` over an 8-tall bar from zero; the `highlight` row is primary,
+the rest neutral. A named list; each row reads "This home: €2,790/m²".
+
+## `NeighbourhoodScores` and `NearbyPlaces`
+
+`NeighbourhoodScores` draws each score as a bar (`variant="bars"`, default) or a 56px
+ring (`rings`), with an optional icon and a short `description`. The labels are yours
+("Transport", "Schools", "Quiet"…); `max` defaults to 10. Columns: 1 below 560 wide,
+2 from 560 (`columns`). Every bar or ring is a `progressbar` named by its label with
+flat `aria-valuemin/max/now` and `aria-valuetext` ("9.2 out of 10").
+
+`NearbyPlaces` rows: a 40 icon disc, name and category, and the walking time on the
+right (`modeIcon` for another mode). Each row reads "Lapa station, Metro, 4 min walk"
+(`formatTime`).
+
+## `RentHistoryList`
+
+The rents (or prices) a place has had, for a place page that outlives its listings:
+amount, period, note, and a small `Chip` for the delta. A leading "+" is warning, "−"
+success (`deltaTone` overrides). An empty list draws "No history for this home yet".
+
+## Accessibility
+
+- Charts and scales are images with composed names; the history legend repeats the
+  events as text.
+- Every meter is a `progressbar` with flat `aria-value*`.
+- "Why this estimate" carries `aria-expanded` (web) and `expanded` (native).
+- Nothing relies on colour alone: verdicts are words, events are labelled, the energy
+  class is a letter.

package/docs/queue-panel.mdx

@@ -0,0 +1,116 @@
+---
+title: Queue Panel
+description: The play queue — now playing, what the listener added, what follows from the context — with drag, keyboard and menu reordering, and a recently played tab.
+order: 64
+---
+
+# Queue Panel
+
+The play queue as a side panel on web and as bottom-sheet content on native.
+
+```tsx
+import { moveQueueItem, QueuePanel } from '@oxy.so/bloom/queue-panel';
+
+<QueuePanel
+  nowPlaying={current}
+  playing={isPlaying}
+  queue={queue}
+  context={upNext}
+  contextName="Night Drive"
+  recentlyPlayed={history}
+  onReorder={(section, from, to) => {
+    const set = section === 'queue' ? setQueue : setUpNext;
+    set((list) => moveQueueItem(list, from, to));
+  }}
+  onRemove={(section, index) => removeAt(section, index)}
+  onPlay={(section, index, track) => playFrom(section, index, track)}
+  onClearQueue={() => setQueue([])}
+  onClose={closeQueue}
+  style={{ height: '100%' }}
+/>
+```
+
+Every list is a prop and every change is a callback. The panel reorders, removes and clears nothing itself; it draws what it is given, so the player stays the one owner of the queue.
+
+## Layout
+
+| part | what it shows |
+| --- | --- |
+| header | `Tabs` — Queue / Recently played — and a close button when `onClose` is set |
+| Now playing | `nowPlaying` with an accent title and `NowPlayingIndicator` (still while `playing` is false) |
+| Next in queue | `queue`, the tracks the listener added, with "Clear queue" when `onClearQueue` is set |
+| Next from: *context* | `context`, what follows from the playing album, playlist or radio (`contextName` names it; without one the heading is "Next up") |
+| Recently played | `recentlyPlayed` through `RecentlyPlayedList`; the loaded track is marked there too |
+
+A section with no rows is not drawn. With no now-playing track and both lists empty the panel shows an empty state.
+
+`variant="panel"` (the web default) is a rounded-8 surface `width` wide (360) with a hairline, in the same surface colours as a menu. `variant="sheet"` (the native default) is flat and full width. Give either a height — the list scrolls inside it.
+
+## Rows
+
+Each row is 56 tall: a 40px cover, the title (`body-medium`) over the artists (`caption-1-regular`, with the explicit badge when `explicit`), and the track's `meta` string — a duration in the queue, a "when" in the history. The cover and text are one button named "Play *title*"; the controls sit beside it, never inside it.
+
+| control | when | web | native |
+| --- | --- | --- | --- |
+| remove (×) | `onRemove`, `panel` only | revealed on hover or keyboard focus | — (use the menu) |
+| more (⋯) | `onReorder` or `onRemove` | revealed on hover or keyboard focus | always |
+| drag handle | `onReorder` | revealed on hover or keyboard focus | always |
+
+On a device without hover (`(hover: none)`) web draws the controls all the time, like native.
+
+`QueueTrack` is `{ id, title, artists?, cover?, explicit?, meta? }`. `cover` is a URL or an id your `ImageResolver` turns into one. `id` must be stable: rows are keyed by it.
+
+## Reordering
+
+Three ways, one callback — `onReorder(section, from, to)`, with indices inside that section (`'queue'` or `'context'`). A row never moves between sections.
+
+- **Drag** the handle. The row lifts under the pointer or finger, and its neighbours slide to show where it will land. Rows are a fixed 56 tall, so the landing slot is `from + round(dy / 56)` (`queueDragTarget`) with no measuring; the row cannot be dragged past its section's first or last slot. The panel's scroll view stops scrolling while a drag is live.
+- **Keyboard**: focus a handle and press <kbd>↑</kbd> / <kbd>↓</kbd>. Focus stays on the handle as the row moves — the panel puts it back once your new list arrives. On native the handle offers "Move up" and "Move down" as accessibility actions.
+- **Menu**: "Move up", "Move down" (disabled at the ends) and "Remove from queue".
+
+Every move is announced: "Slow Tide moved to position 2 of 3" — through a polite live region on web and `AccessibilityInfo.announceForAccessibility` on native.
+
+`moveQueueItem(list, from, to)` applies a move to your array (a new array, target clamped). `queueDragTarget` and `queueDragShift` are the arithmetic the drag uses, exported for anything that wants to draw the same preview.
+
+## `RecentlyPlayedList`
+
+```tsx
+import { RecentlyPlayedList } from '@oxy.so/bloom/queue-panel';
+
+<RecentlyPlayedList items={history} currentId={current.id} onPlay={(index, track) => play(track)} />
+```
+
+The same rows, without reordering. `currentId` marks the loaded track.
+
+## `QueuePanelRow`
+
+The row on its own, for a list of your own: `track`, `onPress`, `current`, `playing`, `trailing` (your controls), `highlighted` (keep the hover paint, e.g. while your menu is open), `accessibilityLabel`.
+
+## Labels
+
+Every string is in `labels` — pass any subset to translate. The ones that name a track are functions:
+
+```tsx
+<QueuePanel
+  labels={{
+    queueTab: 'Cola',
+    recentTab: 'Escuchado',
+    nextFrom: (context) => `A continuación de: ${context}`,
+    moreOptions: (title) => `Más opciones para ${title}`,
+    reorder: (title) => `Reordenar ${title}`,
+    moved: (title, position, total) => `${title}, posición ${position} de ${total}`,
+  }}
+/>
+```
+
+`DEFAULT_QUEUE_PANEL_LABELS` holds the English defaults.
+
+## Accessibility
+
+- Section titles are `role="heading"`; each section is a `list` of `listitem`s.
+- The row's play area, the handle, remove, more and close are all buttons with names that include the track ("Reorder Slow Tide", "More options for Slow Tide").
+- Moves are announced (above). The tabs are `Tabs`, so they carry `role="tab"` and `aria-selected`.
+
+## Colours
+
+From the theme only, light and dark: the panel is the menu surface and hairline, a row under the pointer takes the menu row highlight, the glyph buttons one neutral step above it, and the playing title the accent. Hover and press change colour only; nothing scales.

package/docs/settings-list.mdx

@@ -88,6 +88,27 @@ When `rightElement` is set, the chevron is hidden automatically (you can overrid
 />
 ```
 
+## On a card-coloured surface
+
+A group paints the `card` colour, which reads as a raised card on a page painted
+in `background`. Inside something that is already `card` — a `ContentPanel`, a
+Dialog body — that same group has no edge left and its rows float on the page.
+`variant="filled"` paints the group in `backgroundSecondary` instead, the same
+surface `Card variant="filled"` uses:
+
+```tsx
+<ContentPanel>
+  <SettingsListGroup variant="filled" title="Account">
+    <SettingsListItem title="Privacy" onPress={openPrivacy} />
+  </SettingsListGroup>
+</ContentPanel>
+```
+
+| `variant` | Surface | Use on |
+| --- | --- | --- |
+| `plain` (default) | `card` | a page painted in `background` |
+| `filled` | `backgroundSecondary` | a surface painted in `card` |
+
 ## Footer / header text
 
 ```tsx
@@ -113,6 +134,7 @@ When `rightElement` is set, the chevron is hidden automatically (you can overrid
 | `footer?` | `string` | Section footer. |
 | `children` | `React.ReactNode` | `Item`, `Divider`. |
 | `style?` | `StyleProp<ViewStyle>` | Override group container style. |
+| `variant?` | `'plain' \| 'filled'` | The group's surface: `card` (default) or `backgroundSecondary`, for a group on a card-coloured surface. |
 
 ### `SettingsListItem`