@oxy.so/bloom 2.8.0 → 2.10.0

package/docs/sortable-media.mdx

@@ -0,0 +1,68 @@
+---
+title: Sortable Media
+description: SortablePhotoGrid — an editable grid of uploaded photos with a cover, drag to reorder on web, move buttons everywhere, per-photo upload progress, errors with retry and an add tile.
+order: 115
+---
+
+# Sortable Media
+
+`SortablePhotoGrid` is the photo step of an editor: the photos the user has
+added, in order, the first one marked as the cover.
+
+```tsx
+import { SortablePhotoGrid, type SortablePhoto } from '@oxy.so/bloom/sortable-media';
+
+const [photos, setPhotos] = useState<SortablePhoto[]>([
+  { id: 'living', uri: 'https://…/living.jpg', alt: 'Living room' },
+  { id: 'kitchen', uri: localPreviewUri, status: 'uploading', progress: 42 },
+  { id: 'bath', uri: localPreviewUri2, status: 'error', error: 'File too large' },
+]);
+
+<SortablePhotoGrid
+  photos={photos}
+  onReorder={setPhotos}
+  onRemove={(id) => setPhotos((list) => list.filter((p) => p.id !== id))}
+  onRetry={(id) => restartUpload(id)}
+  onAdd={openPicker}
+  maxPhotos={20}
+  addHint="JPG or PNG"
+/>
+```
+
+## Data
+
+The list is controlled. Each photo is `{ id, uri, status?, progress?, error?, alt? }`:
+
+- `uri` is an absolute URL (a local `file:` or `blob:` preview works while the
+  upload runs) or an `ImageResolver` id, resolved with `photoVariant`.
+- `status` is `uploading`, `uploaded` (the default) or `error`. While uploading,
+  `progress` (0..100) draws a percentage and a bar over a scrim; without it, a
+  spinner.
+- `onReorder` receives the WHOLE list in its new order — after a drag, and after
+  every move-button press — so the app stores it as is.
+
+## Reordering
+
+- **Web, mouse or pen:** press a tile and drag. After 5px of travel the tile
+  lifts and follows the pointer, the other tiles make room live, and releasing
+  commits. Escape cancels. Buttons inside a tile never start a drag.
+- **Everywhere else — touch, native, keyboard and screen readers:** each tile
+  has "Move photo 2 earlier" / "Move photo 2 later" buttons. After a move the
+  focus stays on the moved photo's button (or its other one, if it reached an
+  end) and the new position is announced politely.
+
+On a web pointer that can hover, the tile's buttons appear while the tile is
+hovered or holds focus; on touch screens and native they are always shown.
+
+## Layout
+
+Square tiles, 3 columns below 640 wide and 4 from there (`columns` fixes it),
+12 apart (8 below 480). The add tile follows the photos until `maxPhotos` is
+reached.
+
+## Accessibility
+
+The grid is a `list` named by `accessibilityLabel` (default "Photos"); each tile
+is a `listitem` named "Photo 1 of 6, Cover, Living room" (the error is added
+to a failed photo). The upload overlay is a `progressbar` named "Uploading photo
+3". Every string is in `labels` for localisation.

package/docs/stat-cards.mdx

@@ -67,6 +67,17 @@ Surfaces are built on Bloom's ramps (`button/shared`): the card is `neutral-100`
 - **Deltas.** `lime` / `rose` / `neutral`. The plain card's `Chip` reads `success` / `error` / `default`. The footer pill uses a status recipe on the theme's `success` and `negative` ramps: light `200` fill with `800` text, dark `950` at 60% over the band with `500` text.
 - **Tile tones.** `blue` is the accent ramp, `orange` the `warning` ramp, `sky` the `info` ramp and `emerald` the `success` ramp — so a preset that moves a status colour moves the tile with it. `purple` and `pink` have no theme role: they keep Tailwind's offset from `blue-500` (lightness step, chroma ratio, hue distance), measured from the theme's `primary`. Stops are fixed (`500 → 600`, `orange`/`sky` `400 → 500`), always opaque (react-native-svg drops alpha in `stopColor`).
 
+## Accessory
+
+`accessory` (plain only) puts a node at the top right of the card, level with the icon tile — a `Sparkline` from `@oxy.so/bloom/chart-cards` is the usual one. It shrinks before the tile does and is right-aligned; without it the card renders exactly as before.
+
+```tsx
+import { Sparkline } from '@oxy.so/bloom/chart-cards';
+
+{ icon: RiHeadphoneLine, label: 'Listeners', value: '48,210', delta: '+12%', deltaColor: 'lime',
+  accessory: <Sparkline data={[3, 4, 4, 6, 5, 7, 9]} tone="positive" /> }
+```
+
 ## Info tooltip
 
 `hint` adds a 20px info glyph (named `` `About ${label}` ``, or `hintLabel`). The tooltip opens on hover after 200ms, on keyboard focus, and on press — a glyph this small reads as a button and gets tapped.

package/docs/stay-filters.mdx

@@ -7,7 +7,9 @@ order: 111
 # Stay Filters
 
 The filters surface of a search results page, as parts the app composes inside
-Bloom's `Dialog`. Data is props: the app owns the filter state, the result
+Bloom's `Dialog`. They cover stays and every other housing mode: the housing
+parts (property type, area, features, energy rating, availability, floor, and a
+log-scale sale price) sit alongside the stay ones. Data is props: the app owns the filter state, the result
 count and every label.
 
 ```tsx
@@ -133,6 +135,7 @@ last row.
 | --- | --- |
 | `buckets` | listing counts per price bucket, lowest first; they split `min`..`max` evenly. Omit for no histogram |
 | `min` / `max` / `step` | the slider's bounds and granularity |
+| `scale` | `linear` (default) or `log`, for sale prices — see below |
 | `value` / `onValueChange` | the controlled `[low, high]` |
 | `onValueCommit` | once per drag end, or per committed field |
 | `formatPrice` | how a field shows a price at rest, e.g. `(n) => (n >= max ? '$620+' : '$' + n)` |
@@ -143,14 +146,28 @@ last row.
 This one **computes** prices — bucket bounds, clamping, snapping — so they are
 numbers, and `formatPrice` is where the app's currency and locale come in.
 
-- **The histogram** draws equal-width bars 2 apart with 2px top corners. A
-  bucket whose midpoint is inside the range is text-primary; the rest are
+- **The histogram** draws equal-width bars 2 apart with 3px top corners, in the
+  chart cards' visual language: a bucket whose midpoint is inside the range
+  takes the chart series tone (`chart-6`, the blue hue re-anchored on the
+  theme's primary, so it also matches the range slider); the rest are
   neutral-300 (dark neutral-700). It is hidden from assistive technology: the
   slider announces the same range as numbers. `PriceHistogram` is exported on
   its own for a custom layout.
 - **The slider** is Bloom's `RangeSlider` without value bubbles, pulled up so
   its rail sits on the bars' baseline. Both map `min`..`max` across the full
   width, so each bar sits over the prices it counts.
+- **`scale="log"` for sale prices.** A linear slider over €50K – €2M spends
+  nearly all of its width above what most people search. With `scale="log"`,
+  the same slider distance is the same **ratio**: the midpoint of 50,000 –
+  2,000,000 is about 316,000, not 1,025,000. The slider then runs over 200
+  positions (`PRICE_SCALE_POSITIONS`), and every price it reports is snapped to
+  `step` in price space, so pass a round step (5,000). `buckets` then split the
+  **position** span evenly, so bucket your counts in log space. With `min > 0`
+  the scale is geometric; with `min` of 0 it is offset by one (`log(1 + p)`) so
+  0 stays reachable. The fields are unchanged. Known gap: on a log scale the
+  thumbs' `aria-valuenow` is the position (0–200), not the price —
+  `RangeSlider` has no value text yet — so screen-reader users should rely on
+  the Minimum and Maximum fields.
 - **The fields** are floating-label `TextField`s. Focused, a field shows the
   bare number; the typed text is a draft until blur or submit, when it is
   parsed ("$1,200" reads as 1200), snapped, clamped to its own side of the
@@ -195,6 +212,78 @@ component. The selection is reported in `options` order. It needs an
 (`showMoreLabel`, `showLessLabel`, `defaultExpanded`). A selected option past
 the fold stays visible while collapsed.
 
+### `PropertyTypeFilter`
+
+Multi-select icon tiles for the property type: Apartment, House, Room, Studio,
+Duplex / Penthouse, Coliving, Hostel, Land / Other (`PROPERTY_TYPE_OPTIONS`).
+`value` / `onValueChange` (in option order; empty means any type), `options`,
+`labels` (override by key), `columns` (default: as many as fit, 2 to 4, at 120
+wide), `accessibilityLabel` (default "Property type"). Tiles have radius 12,
+are at least 100 tall with 16 inset, and have a hairline at rest. Selected is a
+2px text-primary border on a neutral tint. Each tile is a toggle `button` with
+`aria-pressed`. The search panel's `PropertyTypePicker`
+(`@oxy.so/bloom/home-search`) is the same grid, compact.
+
+### `AreaRangeFilter`
+
+Floor area in m²: a Minimum / Maximum pair of fields, and with `slider` a
+`RangeSlider` above them. `value: [min | null, max | null]` — `null` is
+open-ended. An emptied field commits `null`, and a thumb resting on `min` or
+`max` reports `null`, so dragging back to an end removes that bound. `min`
+(0), `max` (500), `step` (5), `formatArea` (default `` `${n} m²` ``),
+`minLabel`, `maxLabel`, `onValueCommit`, and `accessibilityLabel` (default
+"Area", naming the group and the slider).
+
+### `FeatureFilter`
+
+What the home must have: Elevator, Parking, Terrace, Garden, Pool, Furnished,
+Pets allowed, Air conditioning, Heating, Accessible, Storage room
+(`HOUSING_FEATURE_OPTIONS`, each with an icon). `variant="chips"` (default)
+draws the filter pills, a `group` of `aria-pressed` toggles. `variant="checkboxes"`
+draws two columns of Bloom `Checkbox`es, which read better as a long list.
+`value`, `onValueChange` (in option order), `options`, `labels`,
+`accessibilityLabel` (default "Features").
+
+### `EnergyRatingFilter`
+
+Seven small coloured letter pills, A (best) to G (worst), 32 tall.
+
+**"And better" semantics:** `value` is the **worst** rating accepted. `'C'`
+matches A, B and C. The pills from A to the chosen letter keep their colour,
+the rest turn neutral, the chosen one has a 2px text-primary ring, and the line
+underneath reads "C and better". `null` means any rating, and every pill is
+coloured. Pressing the chosen letter again clears it.
+
+Colours come from the theme's `success` → `warning` → `error`: A, D and G are
+those colours, and the letters between each pair are mixed at thirds. The letter
+is white or near-black, whichever has more contrast with its fill. It is a
+`radiogroup` (default name "Energy rating"); each pill is a `radio` with
+`aria-checked`, named by the summary it would set ("C and better", "A only").
+`formatSummary` changes both.
+
+### `AvailabilityFilter`
+
+An "Available now" `SwitchFilterRow`, then "Available from" with Bloom's
+`DatePicker`. While `availableNow` is on, the picker is disabled and its day is
+ignored. The app keeps `date`, so switching off brings it back. Props:
+`availableNow`, `onAvailableNowChange`, `date`, `onDateChange`, the four labels,
+`minDate`, `locale`.
+
+### `FloorFilter`
+
+Multi-select pills: Ground, Middle, Top, With elevator (`FLOOR_OPTIONS`).
+Nothing selected means any floor. "With elevator" combines with the floor
+choices rather than replacing them. `value`, `onValueChange`, `options`,
+`labels`, `accessibilityLabel` (default "Floor").
+
+### Housing dialogs
+
+The stories compose a **Buy** dialog (property type, a log-scale price, rooms,
+area with a slider, feature chips, energy rating, floor, new builds only) and a
+**Rent** dialog (property type, monthly rent, rooms, area fields, availability,
+feature checkboxes, energy rating, floor). Both use the same `Dialog`,
+`FilterSection` and `FilterFooter` setup shown above.
+
 ### `SwitchFilterRow`
 
 `title`, `description`, `value`, `onValueChange`, `disabled`. The switch is

package/docs/stay-search.mdx

@@ -62,6 +62,11 @@ is the guest rule below.
 
 ## StaySearchBar
 
+`StaySearchBar` is the vacation-rental preset of `HomeSearchBar` from
+[`@oxy.so/bloom/home-search`](/docs/bloom/main/home-search), which draws the bar for every
+housing mode (rent, buy, swap). The API below is unchanged; use `HomeSearchBar`
+directly for other segments.
+
 | prop                                               | decides                                                                                          |
 | -------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
 | `activeSegment` / `onActiveSegmentChange`          | the open segment — `destination`, `checkIn`, `checkOut`, `dates` or `guests` — or `null`   |

package/docs/tenancy.mdx

@@ -0,0 +1,143 @@
+---
+title: Tenancy
+description: Managing a rental as a tenant or a landlord — the lease summary, rent payments, maintenance requests, documents and a tenancy timeline.
+order: 120
+---
+
+# Tenancy
+
+```tsx
+import {
+  DocumentList,
+  LeaseSummaryCard,
+  MaintenanceRequestCard,
+  RentPaymentList,
+  TenancyTimeline,
+} from '@oxy.so/bloom/tenancy';
+
+<LeaseSummaryCard
+  title="Calle de los Tilos 27, 3º B"
+  subtitle="Two-bedroom flat · Arganzuela, Madrid"
+  parties={[
+    { name: 'Tomás Aranda', role: 'Landlord', avatar: landlordPhoto },
+    { name: 'Lucía Ferrer', role: 'Tenant (you)' },
+  ]}
+  startDate="1 Sep 2025"
+  endDate="31 Aug 2027"
+  progress={0.5}
+  remainingLabel="11 months left"
+  rent="€1,150"
+  deposit="€2,300"
+  nextPayment={{ date: '1 Oct', status: 'due', statusLabel: 'Due in 5 days' }}
+  actions={<Button size="small" onPress={pay}>Pay rent</Button>}
+/>
+
+<RentPaymentList
+  paidThisYear="€9,800"
+  outstanding="€550"
+  outstandingTone="error"
+  payments={[
+    { id: 'aug', month: 'August 2026', dueDate: '1 Aug 2026', amount: '€1,150', method: 'Bank transfer', status: 'paid', onDownloadReceipt: () => download('aug') },
+  ]}
+/>
+
+<MaintenanceRequestCard
+  title="Kitchen sink is leaking"
+  category="plumbing"
+  reference="#1042"
+  priority="high"
+  photos={photos}
+  onPressPhoto={openPhoto}
+  stage="scheduled"
+  stages={{
+    reported: { date: '12 Sep, 18:40', actor: 'You' },
+    acknowledged: { date: '13 Sep', actor: 'Tomás (landlord)' },
+    scheduled: { date: 'Thu 18 Sep, 9:00–11:00', actor: 'Plumber' },
+  }}
+  commentCount={4}
+  onPressComments={openThread}
+/>
+
+<DocumentList
+  documents={[
+    { id: 'lease', name: 'Tenancy agreement.pdf', type: 'pdf', size: '412 KB', status: 'signed', onView, onDownload },
+    { id: 'addendum', name: 'Rent review.pdf', type: 'pdf', status: 'pending', onSign },
+  ]}
+/>
+```
+
+## Nothing reads the clock
+
+Every date, amount and relative phrase is a pre-formatted string the app computes
+("11 months left", "Due in 5 days", "Overdue 12 days"). The one number a part takes is
+`LeaseSummaryCard`'s `progress` — the ELAPSED share of the lease, 0..1 — which draws the
+bar. That keeps the parts deterministic (stories, tests, server rendering) and leaves
+locale and currency with the app. Every default English string is a prop.
+
+## Status colours
+
+Statuses are subtle `Badge`s painted through `resolveAccentColors`, so they follow
+the theme in both modes. The maps are exported (`LEASE_PAYMENT_STATUS`,
+`RENT_PAYMENT_STATUS`, `MAINTENANCE_STAGE`, `MAINTENANCE_PRIORITY`,
+`TENANCY_DOCUMENT_STATUS`) for anything that needs to match them.
+
+| part | status → tone |
+| --- | --- |
+| `LeaseSummaryCard` next payment | `upcoming` info · `due` warning · `overdue` error · `paid` success |
+| `RentPaymentList` row | `paid` success · `pending` warning · `overdue` error · `partial` info |
+| `MaintenanceRequestCard` stage | `reported` warning · `acknowledged` info · `scheduled` primary · `resolved` success |
+| `MaintenanceRequestCard` priority chip | `low` neutral · `medium` info · `high` warning · `urgent` error |
+| `DocumentList` row | `signed` success · `pending` warning · `expired` error |
+
+## Layout from the part's own width
+
+`LeaseSummaryCard`, `RentPaymentList` and `DocumentList` measure themselves
+(`layout="auto"`), not the window, so they fit a dashboard column as well as a phone.
+Pass `layout="wide" | "narrow"` to skip measuring.
+
+| part | narrow | wide (from) |
+| --- | --- | --- |
+| `LeaseSummaryCard` | rent, deposit, next payment stacked | one row with hairlines (520) |
+| `RentPaymentList` | month over "Due … · method", amount over badge | columns with hidden headings (640) |
+| `DocumentList` | badge under the meta line | badge in its own column (560) |
+
+## `TenancyTimeline`
+
+A generic vertical timeline — the lease's history, a repair's progress
+(`MaintenanceRequestCard` draws one at `density="compact"`), an eviction case
+(`EvictionTimeline` in `@oxy.so/bloom/eviction`).
+
+```tsx
+<TenancyTimeline
+  accessibilityLabel="Tenancy history"
+  events={[
+    { title: 'Lease signed', date: '28 Aug 2025', actor: 'Lucía and Tomás', icon: RiFileTextLine },
+    { title: 'Rent review', date: '1 Sep 2026', state: 'current', tone: 'warning' },
+    { title: 'Lease ends', date: '31 Aug 2027', state: 'upcoming' },
+  ]}
+/>
+```
+
+`complete` (default) fills the marker with `tone` (default `primary`), `current` adds a
+tint halo and a semibold title, `upcoming` draws a hollow marker and secondary text.
+`icon` draws a 24 disc at comfortable density; compact always draws 8px dots.
+
+## Accessibility
+
+- The timeline is a `list` of `listitem`s; each marker is an `img` named by its state
+  ("Done", "In progress", "Not yet" — `stateLabels`), so the state is announced before
+  the title.
+- The lease bar is a `progressbar` named by `periodLabel`, with flat `aria-value*`
+  (0–100) and `aria-valuetext` from `remainingLabel`.
+- Icon-only buttons are named after what they act on: "Download receipt for August
+  2026" (`receiptLabel`), "View Tenancy agreement.pdf" (`viewLabel`,
+  `downloadLabel`). A photo is "Pipe under the sink, photo 1 of 3" (`photoLabel`).
+- The payment table's column headings are `aria-hidden`; each row reads as its own
+  `listitem`.
+- Titles are `heading`s (level 3).
+
+## Native
+
+Everything is React Native views; the only web-only addition is the keyboard focus ring,
+adopted once as a constructed stylesheet. Hover washes are colour changes that simply do
+not fire on touch.

package/docs/track-list.mdx

@@ -0,0 +1,236 @@
+---
+title: Track List
+description: The table of tracks for albums, playlists, liked songs and search results, podcast episode rows, loading and empty states, and the bar for bulk actions on a selection.
+order: 63
+---
+
+# Track List
+
+```tsx
+import {
+  EpisodeList,
+  EpisodeRow,
+  SelectionBar,
+  TrackList,
+  TrackListEmpty,
+  TrackListHeader,
+  TrackRow,
+  TrackRowSkeleton,
+  resolveVisibleColumns,
+} from '@oxy.so/bloom/track-list';
+```
+
+Everything is data in, callbacks out. Durations are seconds (drawn with `formatDuration` from `@oxy.so/bloom/media-controls`); dates and play counts arrive pre-formatted, because the app owns the locale. The list never mutates anything: it reports a press, a selection, a like or a reorder, and the app hands back new props.
+
+## TrackList
+
+```tsx
+<TrackList
+  tracks={tracks}
+  currentTrackId={player.trackId}
+  isPlaying={player.playing}
+  onPlay={(track, index) => player.play(queueFrom(index))}
+  onPause={() => player.pause()}
+  selectedIds={selected}
+  onSelectionChange={setSelected}
+  onLikedChange={(track, liked) => library.setLiked(track.id, liked)}
+  onArtistPress={(artist) => router.push(`/artist/${artist.id}`)}
+  onAlbumPress={(track) => router.push(`/album/${track.id}`)}
+  menuItems={(track) => [
+    { key: 'queue', label: 'Add to queue', icon: RiPlayListAddLine, onPress: () => queue.add(track) },
+  ]}
+  accessibilityLabel="Late Night Drive"
+/>
+```
+
+A `Track` is `{ id, title, artists: [{ id?, name }], album?, cover?, number?, duration, dateAdded?, plays?, explicit?, liked?, unavailable?, downloaded? }`. `cover` is a URL or an id your `ImageResolver` turns into one (asked for the `thumb` variant).
+
+### Columns
+
+`columns` picks from `index`, `title` (cover, title and artists), `album`, `dateAdded`, `plays`, `duration` and `actions` (the like button when `onLikedChange` is set, and the more button when the row has a menu). The default is all of them. Whatever you offer still collapses by the list's own width:
+
+| Width | Shown |
+| --- | --- |
+| 1024 and up | everything offered |
+| 768 – 1023 | date added hidden |
+| 640 – 767 | album and plays hidden too |
+| under 640 | the narrow list: cover, title/artists and the more button, no header |
+
+The width is measured with `onLayout` (the window width until the first layout); pass `width` to lay out for a known size. `resolveVisibleColumns(columns, width)` is the same rule as a function, for a header you render yourself.
+
+An album usually drops the date: `columns={['index', 'title', 'plays', 'duration', 'actions']}`.
+
+### Rows
+
+| | comfortable | compact | narrow |
+| --- | --- | --- | --- |
+| height | 56 | 40 | 64 (48 compact) |
+| radius | 6 | 4 | 6 (4 compact) |
+| cover | 40 | 28 | 48 (40 compact) |
+
+Hover paints the row neutral-100 (dark 800), swaps the number for a plain small `PlayButton` and brings in the like, more and drag-handle controls; a liked track keeps its heart. Selected rows are neutral-200 (dark 700). The current track has an accent title and shows `NowPlayingIndicator` while playing, or an accent number while paused. An explicit track draws `ExplicitBadge` before the artists; `showDownloaded` draws the downloaded mark for `downloaded` tracks. An `unavailable` track is drawn at half strength, has no play button and does not play; it can still be selected and opened.
+
+Controls that appear on hover are **mounted** on hover or when focus is inside the row, not hidden with opacity, so a row you are not on is never a Tab stop.
+
+### Disc groups
+
+```tsx
+<TrackList
+  tracks={album.tracks}
+  groups={[
+    { key: 'disc-1', title: 'Disc 1', startIndex: 0 },
+    { key: 'disc-2', title: 'Disc 2', startIndex: 12 },
+  ]}
+/>
+```
+
+A group header row is drawn before the track at `startIndex`. Give tracks their own `number` so each disc counts from 1. Groups are ignored while `reorderable` is on.
+
+### Selection and playing
+
+| | Web | Native |
+| --- | --- | --- |
+| Press / click | selects that row | plays |
+| Cmd/Ctrl-click | toggles the row | — |
+| Shift-click | selects from the last clicked row to this one | — |
+| Double-click | plays | — |
+| Long press | — | opens the row menu (toggles selection when there is no menu) |
+
+Selection is controlled with `selectedIds` + `onSelectionChange`, or uncontrolled with `defaultSelectedIds`. Ids come back in list order. `selectable={false}` turns it off. `onPause` is called instead of `onPlay` for the current, playing track (it defaults to `onPlay`).
+
+### Keyboard (web)
+
+The list is **one** Tab stop: the focused row carries `tabIndex={0}` and every other row `-1`.
+
+| Key | Does |
+| --- | --- |
+| ↑ / ↓ | focus the previous / next row |
+| Home / End | focus the first / last row |
+| Shift + ↑ / ↓ (Home / End) | move focus and extend the selection |
+| Enter / Space | play the focused row |
+| Menu key / Shift+F10 | open the row menu |
+| Alt + ↑ / ↓ | move the row (with `reorderable`) |
+| Tab | into the focused row's own buttons, then out of the list |
+
+### Reordering
+
+```tsx
+<TrackList
+  tracks={tracks}
+  reorderable
+  onReorder={(from, to) => setTracks((list) => move(list, from, to))}
+/>
+```
+
+`reorderable` (with `onReorder`) draws a drag handle at the start of the row on hover. While a row is dragged it lifts onto the menu surface with a shadow and the rows between part to show where it will land (a 150 ms slide, none with reduced motion). The same move is available without a pointer: **Move up** / **Move down** rows at the end of the row menu, and Alt+↑/↓. Those are the path for screen reader and keyboard users, and for native, where the handle also drags. The handle itself is hidden from assistive technology.
+
+`from` and `to` are indexes into `tracks`; the app moves the item and passes the new array back.
+
+### Accessibility
+
+- The list is `role="grid"` named by `accessibilityLabel` (default "Tracks"), with `aria-multiselectable` (when selectable) and `aria-rowcount`.
+- The header is a `row` of `columnheader`s; the clock is named "Duration".
+- Each track is a `row` with `aria-selected` and `aria-rowindex`, named "title, artists" (plus "Unavailable"); its cells are `gridcell`s. Native gets the same name and `accessibilityState.selected`.
+- `grid`, not `listbox`: an `option`'s contents are presentational, and these rows contain buttons (play, like, more) and links (artists, album).
+- Artist and album names are `link`s when their handlers are set. Like is a toggle (`aria-pressed`); the more button carries `aria-haspopup` and `aria-expanded`.
+- Every word is in `labels` for translation.
+
+### Long lists
+
+`TrackList` maps every track, which is fine up to a few hundred rows. Past that, render the header and rows inside a virtualised list yourself. `TrackRow` is the same row `TrackList` draws, and works on its own:
+
+```tsx
+const columns = resolveVisibleColumns(undefined, width);
+
+<FlatList
+  data={tracks}
+  keyExtractor={(track) => track.id}
+  getItemLayout={(_, index) => ({ length: 56, offset: 56 * index, index })}
+  ListHeaderComponent={<TrackListHeader columns={columns} likeable hasMenu />}
+  stickyHeaderIndices={[0]}
+  renderItem={({ item, index }) => (
+    <TrackRow
+      track={item}
+      index={index}
+      columns={columns}
+      width={width}
+      current={item.id === currentId}
+      playing={item.id === currentId && playing}
+      selected={selected.has(item.id)}
+      onPlay={play}
+      onPress={(track, i, { shiftKey, toggleKey }) => select(track, i, shiftKey, toggleKey)}
+      onLikedChange={setLiked}
+      menuItems={menuFor}
+    />
+  )}
+/>
+```
+
+A standalone row plays on press on native and does nothing on a single web click until you pass `onPress` (a double-click plays). Keyboard focus movement is the list's job: wire `onNavigate` and `tabIndex` if you need it in a virtualised list.
+
+## TrackListHeader
+
+`columns` (already collapsed), `density`, and `reorderable` / `likeable` / `hasMenu` to reserve the gutters a row will draw so the labels line up. On web it is `position: sticky` (`sticky`, `stickyOffset` under an app bar) over `background`, which defaults to the page background. `TrackList` exposes these as `stickyHeader`, `stickyHeaderOffset` and `headerBackground`.
+
+## TrackRowSkeleton
+
+```tsx
+{loading ? <TrackRowSkeleton count={8} /> : <TrackList tracks={tracks} />}
+```
+
+Same geometry and column collapsing as the rows (`columns`, `width`, `density`), so nothing jumps when the tracks arrive. Hidden from assistive technology: announce loading on the region around it.
+
+## TrackListEmpty
+
+```tsx
+<TrackListEmpty
+  icon={RiPlayList2Line}
+  title="Songs you add will appear here"
+  description="Use the menu on any song to add it to this playlist."
+  actionLabel="Find songs"
+  onAction={openSearch}
+/>
+```
+
+A round neutral well with the icon, a heading, a muted description and a primary button, centred and at most 360 wide.
+
+## SelectionBar
+
+```tsx
+<View style={{ flex: 1 }}>
+  <TrackList tracks={tracks} selectedIds={selected} onSelectionChange={setSelected} />
+  <SelectionBar
+    count={selected.length}
+    onClear={() => setSelected([])}
+    actions={[
+      { key: 'playlist', label: 'Add to playlist', icon: RiAddLine, onPress: addToPlaylist },
+      { key: 'queue', label: 'Add to queue', icon: RiPlayListAddLine, onPress: addToQueue },
+      { key: 'remove', label: 'Remove', icon: RiDeleteBinLine, destructive: true, onPress: remove },
+    ]}
+  />
+</View>
+```
+
+Renders nothing at `count` 0. The default `placement="floating"` sits absolutely 16 above the bottom of the nearest positioned parent, centred; `inline` leaves placement to you. A panel on the menu surface, radius 16, with ghost buttons that drop to icon-only under 640 (`width`). It is a `toolbar` named by its count text ("3 selected", `formatCount`), and the count is a polite live region.
+
+## EpisodeRow and EpisodeList
+
+```tsx
+<EpisodeList
+  episodes={episodes}
+  currentEpisodeId={player.episodeId}
+  isPlaying={player.playing}
+  onPlay={(episode) => player.play(episode)}
+  onPause={() => player.pause()}
+  onPress={(episode) => router.push(`/episode/${episode.id}`)}
+  onSavedChange={(episode, saved) => library.setSaved(episode.id, saved)}
+  onDownloadedChange={(episode, downloaded) => downloads.set(episode.id, downloaded)}
+  menuItems={(episode) => [{ key: 'share', label: 'Share episode', onPress: () => share(episode) }]}
+/>
+```
+
+An `Episode` is `{ id, title, show?, description?, cover?, date?, duration, progress?, played?, saved?, downloaded?, explicit? }` (`duration` and `progress` in seconds).
+
+Each row draws a 112 cover (radius 12), the title (accent while current), the show, a two-line description, "date · length" (or an accent "Played" check), and a row of actions: an inverse play button, a progress bar with the time left while `progress` is between 0 and `duration`, and save, download and more at the end. Under 560 wide (`width`) the cover shrinks to 64 beside the title and the description is dropped.
+
+Accessibility: the title is a `link` that opens the episode (so does a press anywhere on the row); play is named "Play <title>"; save and download are toggle buttons with `aria-pressed`; the progress bar is a `progressbar` named "Listened" with the time left as its value text. `EpisodeList` is a `list` of `listitem`s with hairlines between rows. Translate with `labels` (`played`, `save`, `download`, `moreOptions`, `progress`, `formatLength`, `formatRemaining`).