@oxy.so/bloom 2.9.0 → 2.11.0

package/docs/media-header.mdx

@@ -0,0 +1,183 @@
+---
+title: Media Headers
+description: The top of every music page — album, playlist, liked songs, artist, podcast show, episode, profile and audiobook headers, the media action bar, the sticky top bar and the artist page sections.
+order: 114
+---
+
+# Media Headers
+
+The header block of a collection or entity page, and the controls that sit under it.
+
+```tsx
+import {
+  ArtistAbout,
+  ArtistHero,
+  ArtistPick,
+  ArtistStats,
+  AudiobookHeader,
+  CollectionHeader,
+  DiscographyFilter,
+  EpisodeHeader,
+  MediaActionBar,
+  PodcastShowHeader,
+  PopularTracks,
+  ProfileHeader,
+  StickyMediaTopBar,
+  useMediaHeaderScroll,
+} from '@oxy.so/bloom/media-header';
+
+<CollectionHeader
+  typeLabel="Album"
+  title="Lanterns Over Kessel Bay"
+  cover={album.coverUrl}
+  artworkColor={album.dominantColor}
+  owners={[{ name: 'Velvet Harbour', avatar: artist.avatar, onPress: openArtist }]}
+  year="2025"
+  summary="12 songs, 48 min"
+  actions={
+    <MediaActionBar
+      playing={playing}
+      onPlayPress={togglePlay}
+      playSubject="Lanterns Over Kessel Bay"
+      shuffle={shuffle}
+      onShuffleChange={setShuffle}
+      liked={saved}
+      onLikedChange={setSaved}
+      download={downloadState}
+      downloadProgress={progress}
+      onDownloadPress={toggleDownload}
+      onMorePress={openMenu}
+    />
+  }
+/>
+```
+
+Everything is data in props: counts, durations, dates and listener figures arrive pre-formatted as strings — the app owns locale and plurals. Images are a URL or an ImageResolver id. Every header is controlled: it draws what it is given and reports what the user did.
+
+## The band
+
+Each header paints a gradient band from `artworkColor` — the artwork's dominant colour, as a hex or `rgb()` string from the backend. Components never sample images.
+
+- The colour is **tinted towards the page**: its OKLCH lightness is clamped to 0.66–0.84 in light mode and 0.30–0.44 in dark, chroma to 0.14, hue kept. A near-black or neon artwork colour still gives a band that belongs to the page.
+- The band runs from that colour to 55% of it over the page background; the `actions` area continues the fade into the page.
+- **Text on the band** is the theme's text or background colour — whichever has the better *worst* contrast over both ends of the band. Secondary text is walked towards the band only while it stays above AA. The test suite checks AA for every preset × mode × 47 artwork colours.
+- Absent or unparsable, the band is **neutral** (neutral-200 light, neutral-800 dark).
+- Over an `ArtistHero` banner photo the text is white on a bottom scrim, because it sits on a photo rather than the theme.
+
+`resolveMediaHeaderPaint(theme, artworkColor)` is exported and pure, for a page that wants to tint its own surroundings to match.
+
+## Title size
+
+Titles shrink through the display steps of the type ramp — `large-title` 64, `display-1` 56, `display-2` 48, `display-3` 40, `display-4` 32, then `title-1` 24, all bold. `selectTitleVariant(title, width)` picks the largest step whose estimated line count (a glyph-width estimate, stable on first render and identical on both platforms) fits that step's allowance: one line for 64 and 56, two for 48–32. Below 480 wide the largest step is `display-4`. An episode title starts at `display-3`.
+
+## Layout
+
+From **600 wide** (the header measures itself, not the window) the cover stands beside the text and the text sits on the cover's baseline; below it the cover is centred on top. Covers: collections 232 (narrow 240), podcast 232 radius 12, episode 160, audiobook 2:3 at 200×300, artist and profile round.
+
+## `CollectionHeader`
+
+Album, single, EP, playlist, liked songs, audiobook-as-collection.
+
+| prop | decides |
+| --- | --- |
+| `typeLabel` | "Album", "Public playlist" |
+| `title`, `description` | the heading (level `headingLevel`, default 1) and a two-line description |
+| `cover`, `artworkColor` | the image and the band colour |
+| `variant` | `'liked'`: an accent gradient cover with a heart, and an accent-tinted band |
+| `owners` | people at the start of the meta line: up to three overlapped 24 avatars, then names — links when they have `onPress` |
+| `year`, `summary`, `saves` | the rest of the meta line, joined by bullets |
+| `editable`, `onEdit`, `editLabel` | a pencil badge on the cover (web: the cover darkens with "Edit details" on hover); the cover and the title are buttons to `onEdit` |
+| `actions` | rendered on the fade under the header |
+
+## `MediaActionBar`
+
+Each control draws only when its handler is given.
+
+| control | props | accessibility |
+| --- | --- | --- |
+| Play (56, accent) | `playing`, `onPlayPress`, `playSubject`, `playDisabled` | "Play Lanterns…" / "Pause Lanterns…" |
+| Shuffle | `shuffle`, `onShuffleChange` | toggle "Shuffle", `aria-pressed`; accent with a dot when on |
+| Heart | `liked`, `onLikedChange` | `LikeButton` |
+| Outline pill | `following`, `onFollowChange`, `followLabel`, `followingLabel` | toggle named by `followLabel` in both states, `aria-pressed` |
+| Download | `download` (`'idle' \| 'downloading' \| 'downloaded'`), `downloadProgress`, `onDownloadPress` | "Download", `aria-pressed` once downloaded, `aria-busy` plus a named `progressbar` while downloading |
+| More | `onMorePress`, or `more` to replace it | "More options" |
+| Search (right) | `onSearchPress`, `searchLabel` | "Search in playlist" |
+| View (right) | `view`, `onViewChange`, `compactViewLabel` | toggle "Compact view", `aria-pressed` |
+| `trailing` | anything at the far right | |
+
+The pieces are exported too: `ShuffleButton`, `DownloadButton`, `FollowButton`, `MediaMoreButton`, `MediaIconButton`. `MediaMoreButton` forwards `aria-expanded` / `aria-haspopup`, so it works as a menu trigger:
+
+```tsx
+<MediaActionBar
+  playing={playing}
+  more={
+    <DropdownMenu>
+      <DropdownMenuTrigger asChild>
+        <MediaMoreButton />
+      </DropdownMenuTrigger>
+      <DropdownMenuContent>
+        <DropdownMenuItem onPress={addToQueue}>Add to queue</DropdownMenuItem>
+      </DropdownMenuContent>
+    </DropdownMenu>
+  }
+/>
+```
+
+## `StickyMediaTopBar`
+
+The compact bar (64 high, band colour, play button + title) that takes over when the header scrolls away. It does not position itself — put it in an absolutely positioned, `sticky` or `fixed` container over the page. Below half shown it is `aria-hidden` and takes no pointer events.
+
+Drive it one of two ways:
+
+- `visible` — fades over 200ms (instant under reduced motion).
+- `progress` 0..1 — drawn at that opacity. Feed it from `useMediaHeaderScroll`:
+
+```tsx
+// A ScrollView
+const { progress, onScroll } = useMediaHeaderScroll({ start: 260, end: 340 });
+<ScrollView onScroll={onScroll} scrollEventThrottle={16}>…</ScrollView>
+<StickyMediaTopBar title={album.title} playing={playing} progress={progress} artworkColor={album.color} />
+
+// Web, a page that scrolls the document: no handler to wire
+const { progress } = useMediaHeaderScroll({ start: 260, window: true });
+```
+
+`start` is normally the header's height minus the bar's; `end` defaults to `start + 80`. `mediaHeaderScrollProgress(offset, start, end)` is the pure mapping.
+
+## `ArtistHero`
+
+`name`, `verified` + `verifiedLabel` ("Verified artist"), `listeners` ("1,234,567 monthly listeners"). With `banner` the image fills the band (400 tall wide) under a scrim; without it the band is tinted from `artworkColor` beside a round `avatar`. Pass the Play / Follow / shuffle / more row as `actions`.
+
+## Artist page sections
+
+- **`PopularTracks`** — `tracks` (`id`, `title`, `image`, `plays`, `duration`, `explicit`); five rows, "See more" shows ten (`collapsedCount`, `expandedCount`, controlled `expanded` / `onExpandedChange`; the toggle carries `aria-expanded`). `activeTrackId` + `playing` draw the now-playing bars and an accent title (`aria-current`). Rows are buttons named by the title; plays hide under 480 wide. The rows are internal to this part.
+- **`DiscographyFilter`** — `value`, `onValueChange`, `options` (default Albums / Singles and EPs / Compilations), `title` ("Discography", `null` for none), `onShowAll`. Chips are `Chip`s, the chosen one `selected`.
+- **`ArtistPick`** — the pinned item: `image`, `title`, `subtitle`, `note` (with a round `avatar`), `label` ("Artist pick"), `onPress`.
+- **`ArtistAbout`** — `image` (16:9 on the card), `bio` clamped to `bioLines` (3) with "Show more", `stats`, `cities` (`{ city, count }`, "Where people listen").
+- **`ArtistStats`** — `stats` (`{ value, label }`), each announced as one element: "1,204,331 Followers".
+
+## `PodcastShowHeader`
+
+`title`, `cover`, `publisher` + `onPublisherPress` (a link), `rating` + `ratingCount` (drawn with `Rating`), `categories` + `onCategoryPress` (chips), `following` + `onFollowChange` (outline pill), `description` clamped to `descriptionLines` with "Show more", and `latestEpisode` (`title`, `date`, `duration`, `description`, `onPress`, `playing`, `onPlayPress`) as a callout card.
+
+## `EpisodeHeader`
+
+`showTitle` + `onShowPress` (link over the title), `title`, `cover`, `date`, `duration`, `playing` + `onPlayPress`, `progress` 0..1 + `remainingLabel` (a named `progressbar`), `saved` + `onSavedChange` (toggle "Save episode"), `onSharePress`, `download` / `downloadProgress` / `onDownloadPress`, `onMorePress`.
+
+## `ProfileHeader`
+
+`name`, `avatar` (round), `typeLabel` ("Profile"), `stats` (`{ label, onPress }` — "12 public playlists" — links when pressable), and either `following` + `onFollowChange` (another listener) or `onEditPress` ("Edit profile", your own), plus `onMorePress`.
+
+## `AudiobookHeader`
+
+`title`, 2:3 `cover`, `author` + `onAuthorPress`, `narrator`, `duration`, `chapters`, `rating` + `ratingCount`, `progress` 0..1 + `progressLabel`.
+
+## Platform notes
+
+Hover states (the edit overlay, underlined links, row washes) are web affordances; native shows the pencil badge and needs no hover. The band gradients use `background-image` on web and the native CSS-gradient style elsewhere. Keyboard focus rings hang off `data-bloom-media-header-press` in one adopted sheet.
+
+## Quiet labels
+
+`textMuted` is floored with `quietTextOver` against both the page and the card it
+paints on. As `neutral-500` it measured 4.38:1 on the light card. See
+[Styles → Quiet text](/docs/bloom/main/styles).

package/docs/media-player.mdx

@@ -0,0 +1,244 @@
+---
+title: Media Player
+description: The transport row, the desktop now-playing bar, the phone's mini player, the full-screen player, speed and sleep-timer menus, the device picker and the connect banner.
+order: 63
+---
+
+# Media Player
+
+The player surfaces of a music or podcast app. They are **presentational only**: there is no audio engine inside. Every state (playing, position, repeat, volume, device…) is a prop and every user action is a callback — the app's player owns the truth and re-renders these.
+
+```tsx
+import {
+  ConnectBanner,
+  DevicePicker,
+  FullScreenPlayer,
+  MiniPlayer,
+  NowPlayingBar,
+  PlaybackSpeedMenu,
+  SleepTimerMenu,
+  TransportControls,
+} from '@oxy.so/bloom/media-player';
+```
+
+They are built from [Media Controls](/docs/bloom/main/media-controls) (`PlayButton`, `LikeButton`, `PlaybackProgress`, `VolumeControl`, `ExplicitBadge`) and share their colours: the theme accent, the neutral ramps, light and dark. No control scales or bounces; hover and press change colour only.
+
+## The track
+
+`NowPlayingBar`, `MiniPlayer` and `FullScreenPlayer` take a `track`:
+
+```ts
+interface MediaPlayerTrack {
+  title: string;
+  artists: string | { id?: string; name: string }[];
+  artwork?: string; // a URL, or an ImageResolver id
+  explicit?: boolean;
+}
+```
+
+A list of artists makes each credit a link when `onArtistPress(artist, index)` is given; a string is one plain credit. Artwork resolves the way `Avatar` does: a URL passes through, anything else goes to the app's `ImageResolver`.
+
+## `TransportControls`
+
+```tsx
+<TransportControls
+  playing={playing}
+  onPlayPause={toggle}
+  onPrevious={previous}
+  onNext={next}
+  shuffle={shuffle}
+  onShuffleChange={setShuffle}
+  repeat={repeat}
+  onRepeatChange={setRepeat}
+/>
+
+<TransportControls
+  variant="podcast"
+  playing={playing}
+  onPlayPause={toggle}
+  onSkipBack={() => seekBy(-15)}
+  onSkipForward={() => seekBy(30)}
+  playbackRate={rate}
+  onPlaybackRateChange={setRate}
+  trailing={<SleepTimerMenu value={sleep} onValueChange={setSleep} />}
+/>
+```
+
+| | play | glyphs | previous / next | hit box | gap |
+| --- | --- | --- | --- | --- | --- |
+| `compact` | 32 | 16 | 20 | 32 | 8 |
+| `regular` (default) | 48 | 20 | 24 | 32 | 16 |
+| `large` | 56 | 24 | 32 | 40 | 24 |
+
+- **music** — shuffle · previous · play · next · repeat. **podcast** — speed · back N · play · forward N · `trailing`.
+- The play button is `PlayButton` `inverse`, named "Play &lt;subject&gt;" / "Pause &lt;subject&gt;".
+- Shuffle and repeat show when their `on…Change` is given; their slot is kept either way, so play stays centred. Previous / next are disabled without a handler or with `previousDisabled` / `nextDisabled`.
+- **Repeat cycles `off` → `all` → `one` → `off`.** `onRepeatChange` receives the NEXT mode (`nextRepeatMode(mode)`). `one` draws `RiRepeatOneLine`.
+- **Skip glyphs** are the numbered ones for 5, 10, 15 and 30 seconds; any other `skipBackSeconds` / `skipForwardSeconds` draws a plain curved arrow, and the name still says the count ("Forward 45 seconds").
+- **Active state**: accent glyph plus a 4px accent dot underneath — shuffle on, repeat `all`/`one`, a speed other than 1×, a running sleep timer.
+- `labels` translates every name: `shuffle`, `previous`, `next`, `play`, `pause`, `repeat`, `repeatOne`, `skipBack(s)`, `skipForward(s)`.
+
+**Accessibility.** Shuffle and repeat are toggles: `aria-pressed` on web and `accessibilityState.selected` on native, with a fixed name. Repeat is "Repeat" while off or `all` and "Repeat one" while `one` — the pressed state says whether it is on, the name which repeat. Previous, next, skip and play are plain buttons (no pressed state).
+
+## `NowPlayingBar`
+
+The desktop bar, full width at the bottom of the window.
+
+```tsx
+<NowPlayingBar
+  track={track}
+  onTitlePress={openAlbum}
+  onArtistPress={(artist) => openArtist(artist.id)}
+  liked={liked}
+  onLikedChange={setLiked}
+  transport={{ playing, onPlayPause: toggle, onPrevious, onNext, shuffle, onShuffleChange, repeat, onRepeatChange }}
+  position={position}
+  duration={duration}
+  buffered={buffered}
+  onSeekPreview={setPreview}
+  onSeek={seekTo}
+  lyricsActive={lyricsOpen}
+  onLyricsChange={setLyricsOpen}
+  queueActive={queueOpen}
+  onQueueChange={setQueueOpen}
+  deviceName={remoteDevice?.name}
+  devicePicker={<DevicePicker current={device} devices={devices} onSelect={connect} />}
+  volume={volume}
+  onVolumeChange={setVolume}
+  muted={muted}
+  onMutedChange={setMuted}
+  onFullscreenPress={openFullScreen}
+/>
+```
+
+- **80 tall**, 16 side inset, the page background and a 1px neutral-200 (dark neutral-800) top rule.
+- **Left** — 56 cover (8 corner), title (a link with `onTitlePress`) with the explicit badge, artists, and the like button (with `onLikedChange`).
+- **Centre** (≤ 722) — `compact` transport over `PlaybackProgress` with times beside it.
+- **Right** — lyrics (`RiMicLine`) and queue (`RiPlayListLine`) toggles, the device button, `VolumeControl`, fullscreen. Each shows when its handler is given.
+- **Device button** — with `devicePicker` it opens a `Popover` above itself holding that content (`devicePickerOpen` / `onDevicePickerOpenChange` to control it); otherwise it calls `onDevicePress`. It is lit (accent + dot) while `deviceName` is set, and its name adds the device.
+- **Collapse** — the bar measures its OWN width (seeded from the window): under **1024** the fullscreen button goes and the volume slider shortens to 64; under **768** lyrics, volume and the scrubber times go, the device button stays only while casting, and the actions column shrinks to what it draws.
+
+Put a `ConnectBanner` under it while casting.
+
+## `MiniPlayer`
+
+The phone's floating bar above the tab bar. Press it to open the full player.
+
+```tsx
+<MiniPlayer
+  track={track}
+  artworkColor={track.color}
+  playing={playing}
+  onPlayPause={toggle}
+  position={position}
+  duration={duration}
+  liked={liked}
+  onLikedChange={setLiked}
+  deviceName={remoteDevice?.name}
+  onPress={openPlayer}
+  onNext={next}
+  onPrevious={previous}
+/>
+```
+
+- **56 tall, 12 corner** (a panel, not a pill), 8 side margins. 40 cover, title (`body-2-semibold`) and artist (`caption-1-regular`), like, and a plain play button. Text truncates — nothing scrolls.
+- **A 2px progress line** along the bottom, 8 in from each side: the text colour over the text colour composited at 24% on the bar's fill. It is decorative (`aria-hidden`) — the full player has the scrubber.
+- **Casting** — the artist line becomes the device name with a speaker glyph (accent on the neutral surface, the text colour on a tint).
+- **Swipe** — on native, a horizontal swipe past 48 calls `onNext` (left) or `onPrevious` (right). Web does not swipe.
+- **Accessibility** — the cover and text are ONE button, "Open player: Title, Artists" (`openLabel` translates the prefix). Like and play are its siblings, not nested inside it.
+
+### The artwork tint and its contrast fallback
+
+`artworkColor` is a hex from the backend — never sampled from the image. `resolveArtworkTint(color, text, textMuted)` darkens it in 5% steps until BOTH the dark theme's text and muted text clear **4.5:1**, stopping at the first step that holds (a dark colour is used as given; `#F4E3A1` comes out as a deep olive). The walk itself is `darkenUntilContrast` from [`@oxy.so/bloom/styles`](/docs/bloom/main/styles), shared with the lyrics pane, the generated covers and the browse tiles. The bar's content then renders under the dark theme, so it reads light-on-colour in a light app too.
+
+No colour, or one that does not parse, falls back to the floating-surface recipe under the app's own theme: the card with a neutral-200 hairline (dark: neutral-800 with neutral-700).
+
+`contrastRatio(a, b)` (from `@oxy.so/bloom/styles`) is the WCAG ratio the check uses, exported for an app that wants the same guarantee elsewhere.
+
+## `FullScreenPlayer`
+
+The phone's expanded player and the desktop's immersive view. It **fills its parent** and presents nothing itself:
+
+- **Phone** — render it as a route (a modal stack screen sliding up), or inside a full-height `BottomSheet` with `showHandle={false}`; wire `onCollapse` to going back / dismissing.
+- **Desktop** — render it as a page, or in a `Dialog` sized to the window; wire `onCollapse` to closing it.
+
+```tsx
+<FullScreenPlayer
+  track={track}
+  artworkColor={track.color}
+  contextLabel="Playing from playlist"
+  contextName="Night Drive"
+  onCollapse={close}
+  onMore={openTrackMenu}
+  liked={liked}
+  onLikedChange={setLiked}
+  transport={{ playing, onPlayPause: toggle, onPrevious, onNext, shuffle, onShuffleChange, repeat, onRepeatChange }}
+  position={position}
+  duration={duration}
+  onSeek={seekTo}
+  deviceName={remoteDevice?.name}
+  onDevicePress={openDevices}
+  onShare={share}
+  queueActive={queueOpen}
+  onQueuePress={openQueue}
+  lyrics={{ lines, activeIndex, onPress: openLyrics }}
+  aboutArtist={<ArtistCard artist={artist} />}
+/>
+```
+
+- **Top bar** — collapse chevron, "PLAYING FROM PLAYLIST" over "Night Drive", more.
+- **Narrow** — square artwork (16 corner, ≤ 480) over title + artists + like, the scrubber with times below it, the `large` transport spread to the column's width, and a row of device (with the device name while casting), share and queue.
+- **Wide (≥ 900, measured)** — artwork and details side by side, 64 apart.
+- **The first screen is exactly the parent's height**, painted with a vertical gradient from the contrast-safe artwork tint to neutral-950. **Below the fold**, in the same scroll, a lyrics preview card (earlier lines dimmed up to `activeIndex`; a button when `onPress` is given) and the `aboutArtist` slot — side by side when wide.
+- **It is always dark.** Its content renders under the dark theme whatever the app's mode. A light app on a named preset gets that preset's dark accent; an app whose accent is a seed or scope keeps its accent as given.
+- `labels` translates `collapse`, `more`, `devices`, `share`, `queue`.
+
+## `PlaybackSpeedMenu` and `SleepTimerMenu`
+
+```tsx
+<PlaybackSpeedMenu rate={rate} onRateChange={setRate} />
+
+<SleepTimerMenu
+  value={sleep}                 // 'off' | 'end' | minutes
+  onValueChange={setSleep}
+  remaining={sleep === 'off' ? undefined : '12:04'}
+  endLabel="End of episode"
+/>
+```
+
+Both are a `DropdownMenu`: an anchored dropdown on web, a bottom sheet on native — so on a phone they already ARE sheet content.
+
+- **Speed** — a text trigger showing the rate ("1.25×", lit when not 1×), a "Playback speed" heading, and radio rows for `rates` (default `PLAYBACK_RATES`: 0.5× to 3×) with a trailing check. `onRateChange` receives a number. `formatRate` and `label` translate it.
+- **Sleep timer** — a timer glyph (lit while a timer runs), a "Sleep timer" heading that adds "Stops in 12:04" from `remaining`, then Off, the `minutes` (default `SLEEP_TIMER_MINUTES`: 5, 10, 15, 30, 45, 60) and "End of episode" (`endLabel` — pass "End of track" for music). `onValueChange` receives `'off'`, `'end'` or the minutes. `remaining` arrives pre-formatted; the app owns the countdown.
+- Pass `children` to replace the trigger (it goes through `asChild`), and `open` / `onOpenChange` to control the menu.
+- The rows announce `aria-checked`, as every Bloom radio row does.
+
+## `DevicePicker`
+
+Content only — host it in a `Popover` on web (as `NowPlayingBar`'s `devicePicker` does) or a sheet on native; a `Popover` on native already presents as a sheet.
+
+```tsx
+<DevicePicker
+  current={{ id: 'this', name: 'This computer', kind: 'computer' }}
+  devices={devices}
+  onSelect={connect}
+  onHelpPress={openHelp}
+/>
+```
+
+- `kind` picks the glyph: `computer`, `phone`, `tablet`, `speaker`, `tv`, `car`, `headphones`, `group`.
+- "Current device" heading, then the current device: accent icon well, accent name and "Listening on". It is not a button.
+- "Select a device", then one 52-tall row per other device (36 icon well, name, optional `description` such as "Wi-Fi" or "3 speakers"). Each is a button named "Name, description"; `disabled` devices dim and do not press. The current device is left out of the list even if `devices` includes it.
+- `emptyLabel` when there is nothing else; a help link with `onHelpPress`. `title`, `currentLabel`, `devicesTitle` and `helpLabel` translate it.
+
+## `ConnectBanner`
+
+```tsx
+<ConnectBanner deviceName="Living Room Speaker" kind="speaker" onPress={openDevices} />
+```
+
+A 28-tall full-width strip in the accent with the device glyph and "Listening on Living Room Speaker" in the accent's foreground. With `onPress` it is a button named by that sentence; without, a plain strip. `label` translates "Listening on".
+
+## Native
+
+Everything renders on native. The web-only parts degrade: hover washes and link underlines do not exist there, the menus and the device popover present as sheets, the mini player gains its swipe, and focus rings are the platform's. The gradient uses the native CSS-gradient style.

package/docs/media-shelf.mdx

@@ -0,0 +1,88 @@
+---
+title: Media Shelf
+description: Home and search sections — a titled row or grid of tiles, its loading placeholder, and the filter pills above a feed.
+order: 63
+---
+
+# Media Shelf
+
+The building blocks of a music home feed: a `Shelf` is one section (a heading, an optional "Show all", and a run of tiles), `ShelfSkeleton` stands in while it loads, and `FilterChips` is the single-select pill row above the feed.
+
+```tsx
+import { FilterChips, Shelf, ShelfSkeleton } from '@oxy.so/bloom/media-shelf';
+
+<FilterChips
+  options={[
+    { value: 'all', label: 'All' },
+    { value: 'music', label: 'Music' },
+    { value: 'podcasts', label: 'Podcasts' },
+    { value: 'audiobooks', label: 'Audiobooks' },
+  ]}
+  value={filter}
+  onValueChange={setFilter}
+/>
+
+<Shelf
+  title="Maya"
+  eyebrow="Made for"
+  eyebrowAvatar={user.avatar}
+  onTitlePress={openMixes}
+  onShowAll={openMixes}
+>
+  {mixes.map((mix) => <MixTile key={mix.id} mix={mix} />)}
+</Shelf>
+
+<Shelf title="Recently played" layout="grid" minItemWidth={240} rows={2} gap={8}>
+  {recent.map((item) => <CompactTile key={item.id} item={item} />)}
+</Shelf>
+
+{loading ? <ShelfSkeleton count={8} /> : null}
+```
+
+The tiles are yours — any card works. The shelf only lays them out.
+
+## `Shelf`
+
+| prop | decides |
+| --- | --- |
+| `title` | the heading (`title-2-bold`); also names the group and the arrow buttons |
+| `subtitle` | a `body-2-regular` secondary line under the title |
+| `eyebrow` / `eyebrowAvatar` | a small line above the title ("Made for") with a 24px avatar (URL, ImageResolver id or image source) |
+| `onTitlePress` | makes the title a link; it underlines on hover |
+| `onShowAll` / `showAllLabel` | the "Show all" button on the right of the header (default text "Show all") |
+| `layout` | `'row'` (default) scrolls horizontally; `'grid'` wraps |
+| `itemWidth` | row: the width each item is laid out at (items keep their own width when omitted) |
+| `minItemWidth` | grid: the narrowest a column may get, default `160` |
+| `rows` | grid: rows shown, default `1`; extra items are dropped. `Infinity` shows all |
+| `gap` | between items, default `16` on web and `12` on native |
+| `contentInset` | row: padding inside the track so it can scroll edge to edge while the first item lines up with the page gutter |
+| `headingLevel` | the heading's `aria-level`, default `2` |
+| `previousLabel` / `nextLabel` | the arrow buttons' names, default "Previous" / "Next", suffixed with the title |
+| `style`, `testID` | |
+
+**Row on web.** The scrollbar is hidden, items snap to their start (`scroll-snap-type`), and two round secondary buttons in the header page through the row by 90% of its width. Each disables at its end; both are hidden while nothing overflows, and on touch screens (`hover: none`), where a swipe already scrolls. Paging is not animated under reduced motion.
+
+**Row on native.** A plain horizontal `ScrollView`. With `itemWidth` it snaps one item at a time.
+
+**Grid.** The column count is computed from the container's measured width: as many columns of at least `minItemWidth` as fit, at least one, stretched to fill. Nothing renders until the first layout, so a grid never flashes at the wrong column count. The rule is exported as `shelfGridColumns(width, minItemWidth, gap)`.
+
+**Semantics.** The shelf is a `role="group"` named by `title`, the title is a `role="heading"`, and "Show all" is a button named "Show all: *title*" — the visible text leads the name, so a voice command of "Show all" still matches.
+
+## `ShelfSkeleton`
+
+The same header rhythm and gaps as `Shelf`, with square (or `round`) covers over two text lines. Props: `layout`, `count` (6), `itemWidth` (160), `minItemWidth`, `round`, `eyebrow`, `gap`, `accessibilityLabel` ("Loading"). It renders a `role="group"` with `aria-busy`, so a screen reader hears one "Loading" rather than a dozen blank shapes.
+
+## `FilterChips`
+
+| prop | decides |
+| --- | --- |
+| `options` | `{ value, label }[]` |
+| `value` | the selected option |
+| `onValueChange` | called with the pressed value — or `undefined` when `allowDeselect` and the selected chip is pressed |
+| `allowDeselect` | default `false`: pressing the selected chip does nothing |
+| `accessibilityLabel` | the group's name, default "Filters" |
+| `contentInset` | horizontal padding inside the scroll track |
+
+Each option is an `xl` `Chip` (32 tall, 12px sides): neutral subtle at rest, the brand subtle tint when selected. The row is a `ChipRow`, so it scrolls sideways with an edge fade. Each chip is a toggle button with `aria-pressed` (and `accessibilityState.selected` on native — the `Chip` contract).
+
+Two things changed here and are worth knowing if you were matching them. It asked for `variant="solid"` when selected, the one filter row in the library that shouted its selection where every other one tints it. And it overrode the side padding with `paddingLeft`/`paddingRight` against a base that spells it `paddingHorizontal`, so on WEB the override dropped and the pills drew at 6 — native got 12, web got 6, and nothing failed. The rung carries 12 for both.