react-native-audio-browser 0.2.0-next.9 → 0.2.0

package/src/types/browser-native.ts

@@ -9,7 +9,7 @@
 import type {
   ArtworkRequestConfig,
   BrowserSourceCallback,
-  ResolveAlbumUrlCallback,
+  CarPlayNowPlayingButton,
   FormatNavigationErrorCallback,
   HandleTrackLoadCallback,
   MediaRequestConfig,
@@ -18,12 +18,6 @@ import type {
 } from './browser'
 import type { ResolvedTrack } from './browser-nodes'
 
-// Native resolvers are Promise-only. The public `request`/`browse` resolver may
-// return its config sync OR async; `toNativeConfig` wraps it in Promise.resolve so
-// the bridge never sees a `T | Promise<T>` variant (which would misread the async
-// case). Resolvers run once per content generation, so the wrap is free.
-type NativeRequestConfigResolver = () => Promise<TransformableRequestConfig>
-
 /**
  * Flattened route entry for native bridge.
  */
@@ -48,25 +42,18 @@ export interface NativeRouteEntry {
 export interface NativeBrowserConfiguration {
   path?: string
 
-  // Request defaults (applied to every request: browse, search, media, artwork).
-  // The union `TransformableRequestConfig | RequestConfigResolver` from the public
-  // API is lowered here into two sibling fields (mirrors browseCallback/browseConfig).
+  // Request defaults
   request?: TransformableRequestConfig
-  requestResolver?: NativeRequestConfigResolver
 
-  // Per-kind request config, layered request → <kind> → route.
-  browse?: TransformableRequestConfig
-  browseResolver?: NativeRequestConfigResolver
+  // Global media/artwork config (applied when route doesn't override)
   media?: MediaRequestConfig
   artwork?: ArtworkRequestConfig
-  nowPlayingArtwork?: ArtworkRequestConfig
 
   // Routes as array - includes:
   // - Explicit routes from config.routes
-  // - The '*' route (if any) as the __default__ entry (custom default override)
+  // - Root browse as __default__ entry
   // - Tabs as __tabs__ entry (returns ResolvedTrack with children for navigation tabs)
   // - Search as __search__ entry (has searchCallback or searchConfig)
-  // A browse path matching none of these is fetched via request + browse + path.
   routes?: NativeRouteEntry[]
 
   // Behavior
@@ -75,7 +62,7 @@ export interface NativeBrowserConfiguration {
   androidControllerOfflineError?: boolean
 
   // CarPlay options
-  carPlayLoadingTitle?: string
-  resolveAlbumUrl?: ResolveAlbumUrlCallback
+  carPlayUpNextButton?: boolean
+  carPlayNowPlayingButtons?: CarPlayNowPlayingButton[]
   formatNavigationError?: FormatNavigationErrorCallback
 }

package/src/types/browser-nodes.ts

@@ -23,113 +23,24 @@ export interface ImageSource {
   body?: string
 }
 
-/**
- * Per-track override applied as the most-specific layer of THIS track's media
- * request (after the shared `request` and `media` layers). Deliberately narrow:
- * a track may customize HOW its request is made (identity, auth, signed-URL
- * params), not WHERE it goes — `baseUrl`/`path`/`method`/`body` are intentionally
- * absent so a (often server-sourced) track can't repoint its own host or verb.
- * Carried verbatim on the Track and round-tripped like any other field.
- */
-export interface TrackRequest {
-  userAgent?: string
-  headers?: Record<string, string>
-  query?: Record<string, string>
-}
-
 // export interface BrowserSection {
 //   title: string
 //   style?: BrowserItemStyle
 //   children: Track
 // }
 
-/**
- * Artwork URLs for a track that ships a different image per appearance.
- *
- * Both are required: a pair with one side missing has no sensible fallback at
- * render time, and making that unrepresentable is the reason this is a pair
- * rather than two optional fields.
- *
- * Android Auto is dark-only and takes `dark`.
- */
-export interface ArtworkVariants {
-  /** Shown in light mode. */
-  light: string
-  /** Shown in dark mode, and on Android Auto. */
-  dark: string
-}
-
-// Aliased rather than written inline on `Track.artwork` because Nitro names
-// variant types after their members: without the alias the generated Swift and
-// Kotlin type is `Variant_String_ArtworkVariants` either way, but the alias is
-// what keeps that name readable rather than accidental. Kept out of the doc
-// comment below — it is a note for this repo, not for the API reference.
-/** A single artwork URL, or one per appearance. */
-export type TrackArtwork = string | ArtworkVariants
-
 export interface ImageRowItem {
-  /**
-   * Opaque, stable identifier for this item's track. Round-tripped like
-   * `Track.id` when the thumbnail is played (see `src`).
-   */
-  id?: string
   /** Navigation path. Tapping this thumbnail navigates to this URL. */
   url?: string
-  /**
-   * Direct audio source. When present, tapping this thumbnail plays it
-   * immediately (same selection path as a playable list row) instead of
-   * navigating. Takes precedence over `url`.
-   */
-  src?: string
   /** Artwork URL for the thumbnail image. */
   artwork?: string
   /** Output only — populated by the artwork transform pipeline. */
   readonly artworkSource?: ImageSource
-  /** Title of this item. Shown as the thumbnail caption; used for identification and accessibility. */
+  /** Title of this item. Used for identification and accessibility. */
   title: string
-  /** Now-playing secondary line when played via `src` (mirrors `Track.artist`). */
-  artist?: string
-  /** Now-playing album line when played via `src` (mirrors `Track.album`). */
-  album?: string
-  /** Navigation target of the album line when played via `src` (mirrors `Track.albumUrl`). */
-  albumUrl?: string
-  /** Live stream indicator when played via `src` (mirrors `Track.live`). */
-  live?: boolean
-  /** Per-item media-request override when played via `src` (mirrors `Track.request`). */
-  request?: TrackRequest
 }
 
 export interface Track {
-  /**
-   * Opaque, stable identifier for this track.
-   *
-   * The library never parses or derives anything from this value — it is
-   * round-tripped verbatim through `setQueue`, `getActiveTrack`, the queue, and
-   * `onActiveTrackChanged`, so consumers can recognise which item became active
-   * after an external transport change (lock screen / CarPlay / Android Auto /
-   * Bluetooth next-previous) without parsing the playable `src`.
-   *
-   * When present on a playable track it is also the track's *identity* on car
-   * browse surfaces: CarPlay's and Android Auto's "now playing" row indicator
-   * match the active track to browse rows by `id` (falling back to exact `src`
-   * equality for tracks without one). Assign ids when your playable `src`
-   * strings for the same item can differ between browse rows and loaded tracks
-   * (absolute vs relative URLs, volatile query params) — otherwise the
-   * indicator never matches.
-   *
-   * It is also handed to the per-track `MediaRequestConfig.resolve` and
-   * `ArtworkRequestConfig.resolve` hooks, so requests can be built from a stable
-   * id (e.g. supply tracks with only an `id` and synthesise `src` in `resolve`).
-   *
-   * Optional: consumers whose `url`/`src` strings are already stable across
-   * surfaces can ignore it.
-   *
-   * Note: an Android Auto item selected directly from the browse tree that the
-   * consumer never queued is identified only by `url`/`src`, so `id` may be
-   * undefined on that specific path.
-   */
-  id?: string
-
   /**
    * Navigation path. When present, this track is a container (tab, album, playlist, folder)
    * that can be navigated into to view its contents.
@@ -150,17 +61,12 @@ export interface Track {
   src?: string
 
   /**
-   * Artwork URL for the item, or a URL per appearance.
+   * Artwork URL for the item.
    *
    * The artwork URL is also returned by native in the `artworkSource` property
    * for use in an `<Image>` component, which will contain the transformed version
    * if `artwork` configuration is set in `BrowserConfiguration` or a route.
    *
-   * Pass an {@link ArtworkVariants} pair to supply genuinely different images
-   * per appearance — a logo that changes colour, say. For a monochrome glyph
-   * that only needs recolouring, prefer a single URL plus
-   * {@link Track.artworkCarPlayTinted}, which is one fetch instead of two.
-   *
    * **iOS:** supports {@link https://developer.apple.com/sf-symbols/ | SF Symbols}
    * with the `sf:` prefix and optional color params:
    * `sf:heart.fill?bg=#FF0090&fg=#fff`. `bg` sets the background color
@@ -168,7 +74,7 @@ export interface Track {
    * On CarPlay, SF Symbols without explicit colors automatically adapt to
    * light/dark mode.
    */
-  artwork?: TrackArtwork
+  artwork?: string
 
   /**
    * Ready-to-use image source for React Native's `<Image>` component.
@@ -186,9 +92,6 @@ export interface Track {
    */
   readonly artworkSource?: ImageSource
 
-  /** Per-track media-request override; merged last (request → media → track.request). */
-  request?: TrackRequest
-
   /**
    * Whether this artwork should be tinted based on CarPlay's current appearance (light/dark mode).
    *
@@ -207,51 +110,12 @@ export interface Track {
   artworkCarPlayTinted?: boolean
 
   // type?: TrackType
-  /** Primary line shown for this item, in both browse lists and now-playing. */
   title: string
-
-  /**
-   * Secondary line shown for this item in **browse lists** (CarPlay list detail
-   * text, Android Auto list subtitle). Free-form, per-context display text — set
-   * it to whatever the row should show, or leave it unset for a blank line. It is
-   * *not* shown on the now-playing screen; use {@link artist} for that.
-   */
   subtitle?: string
-
-  /**
-   * Secondary line shown on the **now-playing / lock-screen** UI, and the value
-   * sent to Bluetooth / car head units — it maps to the platform's "artist"
-   * metadata slot.
-   *
-   * Distinct from {@link subtitle}: `artist` drives the now-playing line,
-   * `subtitle` drives browse-list rows. Neither falls back to the other — set
-   * each for the surface you want it on.
-   */
   artist?: string
-
-  /**
-   * Browse path the {@link album} line navigates to (same path namespace as
-   * {@link url}). On CarPlay, when the active track has an `albumUrl`, its
-   * album line on the Now Playing screen becomes tappable and navigates the
-   * browse stack there. See also `resolveAlbumUrl` in the browser
-   * configuration for a dynamic fallback.
-   *
-   * Requires {@link album} to be set: CarPlay renders the tappable line from
-   * the album metadata — without an album there is no line to tap.
-   *
-   * @platform ios
-   */
-  albumUrl?: string
-
   album?: string
   description?: string
   genre?: string
-
-  /**
-   * Duration in seconds, as catalog metadata for app UI (e.g. an episode
-   * list). Does not drive the now-playing scrubber — every platform surface
-   * derives elapsed/duration from the player itself.
-   */
   duration?: number
 
   /**
@@ -281,7 +145,7 @@ export interface Track {
   childrenStyle?: TrackStyle
 
   /**
-   * Whether this track is favorited. When the `favorite` capability is enabled,
+   * Whether this track is favorited. When the `set-rating` capability is enabled,
    * displays a filled/empty heart icon in media controllers (notification, Android Auto).
    */
   favorited?: boolean
@@ -305,18 +169,13 @@ export interface Track {
    *
    * - Track.title → row header text
    * - Track.url → navigated when header is tapped (optional)
-   * - Each ImageRowItem → one thumbnail in the horizontal row; a thumbnail
-   *   with `src` plays immediately on tap, otherwise its `url` is navigated
+   * - Each ImageRowItem → one thumbnail in the horizontal row
    *
    * On CarPlay: maps to CPListImageRowItem. Limits visible images by display
-   * width (~4-5). Excess silently truncated. A row whose track has no `url`
-   * is a pure preview: its header is not tappable.
+   * width (~4-5). Excess silently truncated.
    *
-   * On Android Auto: there is no image-row rendering, so the row expands into
-   * its items as grid-styled rows (artwork tiles where the host honors the
-   * per-item content-style hint, list rows otherwise) grouped under the
-   * track's title, followed by the track itself as a browsable "view all"
-   * link when it has a `url`.
+   * On Android Auto: ignored; the parent Track renders as a regular
+   * browsable item using its own artwork/title/url.
    *
    * On app side: consumable by React Native UI for horizontal thumbnail layouts.
    */
@@ -331,13 +190,10 @@ export interface Track {
  *
  * @example
  * ```ts
- * // navigate() is fire-and-forget (returns void); read the resolved page
- * // from getContent() / useContent() / onContentChanged.
- * navigate('albums/abbey-road');
- * const resolved = getContent();
- * console.log(resolved?.url); // "albums/abbey-road"
- * console.log(resolved?.title); // "Abbey Road"
- * console.log(resolved?.children); // Array of tracks in this album
+ * const resolved = await audioBrowser.navigate('albums/abbey-road');
+ * console.log(resolved.url); // "albums/abbey-road"
+ * console.log(resolved.title); // "Abbey Road"
+ * console.log(resolved.children); // Array of tracks in this album
  * ```
  */
 export interface ResolvedTrack extends Track {
@@ -354,10 +210,7 @@ export interface ResolvedTrack extends Track {
 
   /**
    * Shows the "Ask Siri to Play Audio" assistant cell on the CarPlay list template
-   * for this content. Requires the Siri entitlement, the `INPlayMediaIntent` keys in
-   * Info.plist, and an in-app intent handler in your `AppDelegate`
-   * (`application(_:handlerFor:)`) — no separate Intents Extension is needed. See the
-   * setup guide for the full wiring.
+   * for this content. Requires an Intents Extension to be configured in the app.
    *
    * - `'top'`: Shows at the top of the list
    * - `'bottom'`: Shows at the bottom of the list