react-native-audio-browser 0.2.0-next.2 → 0.2.0-next.21

package/ios/Browser/JsonModels.swift

@@ -62,41 +62,193 @@ extension JsonArtwork {
   }
 }
 
-/// JSON model for image row items (horizontal thumbnail row).
-struct JsonImageRowItem: Codable {
-  let id: String?
-  let url: String?
-  let src: String?
-  let artwork: String?
-  let title: String
-  let artist: String?
-  let album: String?
-  let albumUrl: String?
-  let live: Bool?
-  let request: JsonTrackRequest?
+/// A style declaration block on the wire (ADR 0011):
+/// `{ display?, gridWrap?, artworkRendering? }`.
+///
+/// One JSON model serves both the `TrackStyle` and `SectionStyle` positions —
+/// keys that don't exist at the narrower position simply don't map.
+///
+/// Decoding is tolerant by design: a stale payload — the retired string
+/// styles, a wrong-typed field, an unknown enum value — must degrade to "no
+/// declaration", never fail the page or the persisted playback state (the
+/// decoders above this are strict, so a throw here would kill the whole
+/// payload). `init(from:)` therefore never throws, and unknown enum values
+/// map to nil at `toNitro` time.
+struct JsonStyle: Codable, Equatable {
+  let display: String?
+  let gridWrap: Bool?
+  let gridTile: String?
+  let artworkRendering: String?
+  let imageShape: String?
+  let accessorySymbol: String?
+  let cardTint: String?
+  let cardImage: String?
 
   init(
-    id: String? = nil,
-    url: String? = nil,
-    src: String? = nil,
-    artwork: String? = nil,
-    title: String,
-    artist: String? = nil,
-    album: String? = nil,
-    albumUrl: String? = nil,
-    live: Bool? = nil,
-    request: JsonTrackRequest? = nil,
+    display: String? = nil,
+    gridWrap: Bool? = nil,
+    gridTile: String? = nil,
+    artworkRendering: String? = nil,
+    imageShape: String? = nil,
+    accessorySymbol: String? = nil,
+    cardTint: String? = nil,
+    cardImage: String? = nil,
+  ) {
+    self.display = display
+    self.gridWrap = gridWrap
+    self.gridTile = gridTile
+    self.artworkRendering = artworkRendering
+    self.imageShape = imageShape
+    self.accessorySymbol = accessorySymbol
+    self.cardTint = cardTint
+    self.cardImage = cardImage
+  }
+
+  init(from decoder: Decoder) throws {
+    // A non-object value (the retired `style: 'grid'` string) decodes as an
+    // empty block rather than failing the parent.
+    guard let container = try? decoder.container(keyedBy: CodingKeys.self) else {
+      self.init()
+      return
+    }
+    self.init(
+      display: (try? container.decodeIfPresent(String.self, forKey: .display)) ?? nil,
+      gridWrap: (try? container.decodeIfPresent(Bool.self, forKey: .gridWrap)) ?? nil,
+      gridTile: (try? container.decodeIfPresent(String.self, forKey: .gridTile)) ?? nil,
+      artworkRendering: (try? container.decodeIfPresent(String.self, forKey: .artworkRendering)) ?? nil,
+      imageShape: (try? container.decodeIfPresent(String.self, forKey: .imageShape)) ?? nil,
+      accessorySymbol: (try? container.decodeIfPresent(String.self, forKey: .accessorySymbol)) ?? nil,
+      cardTint: (try? container.decodeIfPresent(String.self, forKey: .cardTint)) ?? nil,
+      cardImage: (try? container.decodeIfPresent(String.self, forKey: .cardImage)) ?? nil,
+    )
+  }
+}
+
+extension JsonStyle {
+  /// The wire strings map to Nitro enums here, tolerantly: an unknown value
+  /// (a future `display` mode, say) is no declaration, not an error. A block
+  /// that resolves to no declarations at all — `{}`, the tolerant decoder's
+  /// empty result for the retired string vocabulary, or all-unknown values —
+  /// maps to nil, so "no declaration" has one shape on every platform
+  /// (Android's lenient mapper makes the same collapse).
+  func toTrackStyle() -> TrackStyle? {
+    let display = display.flatMap { StyleDisplay(fromString: $0.lowercased()) }
+    let artworkRendering = artworkRendering.flatMap { ArtworkRendering(fromString: $0.lowercased()) }
+    let imageShape = imageShape.flatMap { ImageShape(fromString: $0.lowercased()) }
+    // The 'none' sentinel is a legitimate value; only emptiness collapses.
+    let accessorySymbol = accessorySymbol?.isEmpty == false ? accessorySymbol : nil
+    let cardTint = cardTint?.isEmpty == false ? cardTint : nil
+    let cardImage = cardImage.flatMap { CardImage(fromString: $0.lowercased()) }
+    guard display != nil || artworkRendering != nil || imageShape != nil
+      || accessorySymbol != nil || cardTint != nil || cardImage != nil
+    else { return nil }
+    return TrackStyle(
+      display: display,
+      artworkRendering: artworkRendering,
+      imageShape: imageShape,
+      accessorySymbol: accessorySymbol,
+      cardTint: cardTint,
+      cardImage: cardImage,
+    )
+  }
+
+  func toSectionStyle() -> SectionStyle? {
+    let display = display.flatMap { StyleDisplay(fromString: $0.lowercased()) }
+    let gridTile = gridTile.flatMap { GridTile(fromString: $0.lowercased()) }
+    let artworkRendering = artworkRendering.flatMap { ArtworkRendering(fromString: $0.lowercased()) }
+    let imageShape = imageShape.flatMap { ImageShape(fromString: $0.lowercased()) }
+    let accessorySymbol = accessorySymbol?.isEmpty == false ? accessorySymbol : nil
+    let cardTint = cardTint?.isEmpty == false ? cardTint : nil
+    let cardImage = cardImage.flatMap { CardImage(fromString: $0.lowercased()) }
+    guard display != nil || artworkRendering != nil || gridWrap != nil
+      || gridTile != nil || imageShape != nil || accessorySymbol != nil
+      || cardTint != nil || cardImage != nil
+    else { return nil }
+    // Argument order is the generated init's (own properties before
+    // inherited ones — Nitro flattens `extends` own-props-first).
+    return SectionStyle(
+      gridWrap: gridWrap,
+      gridTile: gridTile,
+      display: display,
+      artworkRendering: artworkRendering,
+      imageShape: imageShape,
+      accessorySymbol: accessorySymbol,
+      cardTint: cardTint,
+      cardImage: cardImage,
+    )
+  }
+
+  /// Snapshot a live track block back to its JSON model (for persistence).
+  /// An all-nil block snapshots as no block — the decoders collapse it to
+  /// "no declaration" anyway, so never persist the distinction.
+  init?(_ style: TrackStyle?) {
+    guard let style,
+          style.display != nil || style.artworkRendering != nil
+          || style.imageShape != nil || style.accessorySymbol != nil
+          || style.cardTint != nil || style.cardImage != nil
+    else { return nil }
+    self.init(
+      display: Self.string(style.display),
+      artworkRendering: Self.string(style.artworkRendering),
+      imageShape: Self.string(style.imageShape),
+      accessorySymbol: style.accessorySymbol,
+      cardTint: style.cardTint,
+      cardImage: Self.string(style.cardImage),
+    )
+  }
+
+  private static func string(_ display: StyleDisplay?) -> String? {
+    switch display {
+    case .list: "list"
+    case .grid: "grid"
+    case nil: nil
+    }
+  }
+
+  private static func string(_ rendering: ArtworkRendering?) -> String? {
+    switch rendering {
+    case .original: "original"
+    case .stencil: "stencil"
+    case nil: nil
+    }
+  }
+
+  private static func string(_ shape: ImageShape?) -> String? {
+    switch shape {
+    case .circular: "circular"
+    case .roundedRectangle: "rounded-rectangle"
+    case nil: nil
+    }
+  }
+
+  private static func string(_ mode: CardImage?) -> String? {
+    switch mode {
+    case .normal: "normal"
+    case .background: "background"
+    case nil: nil
+    }
+  }
+}
+
+/// JSON model for a page section (ADR 0010). Legacy `groupTitle`/`imageRow`
+/// keys in payloads are simply unknown to these models and decode as
+/// ignored dead weight.
+struct JsonSection: Codable {
+  let title: String?
+  let style: JsonStyle?
+  let path: String?
+  let children: [JsonTrack]
+
+  init(
+    title: String? = nil,
+    style: JsonStyle? = nil,
+    path: String? = nil,
+    children: [JsonTrack],
   ) {
-    self.id = id
-    self.url = url
-    self.src = src
-    self.artwork = artwork
     self.title = title
-    self.artist = artist
-    self.album = album
-    self.albumUrl = albumUrl
-    self.live = live
-    self.request = request
+    self.style = style
+    self.path = path
+    self.children = children
   }
 }
 
@@ -116,60 +268,63 @@ struct JsonTrackRequest: Codable {
 /// JSON model for resolved track (container with children).
 struct JsonResolvedTrack: Codable {
   let id: String?
-  let url: String
+  let path: String
   let title: String
   let subtitle: String?
   let artwork: JsonArtwork?
   let artist: String?
-  let albumUrl: String?
+  let albumPath: String?
   let album: String?
   let description: String?
   let genre: String?
   let duration: Double?
+  let sections: [JsonSection]?
   let children: [JsonTrack]?
   let src: String?
-  let style: String?
-  let childrenStyle: String?
-  let groupTitle: String?
+  let style: JsonStyle?
+  let disabled: Bool?
   let live: Bool?
+  let icyCharset: String?
   let carPlaySiriListButton: String?
 
   init(
     id: String? = nil,
-    url: String,
+    path: String,
     title: String,
     subtitle: String? = nil,
     artwork: JsonArtwork? = nil,
     artist: String? = nil,
-    albumUrl: String? = nil,
+    albumPath: String? = nil,
     album: String? = nil,
     description: String? = nil,
     genre: String? = nil,
     duration: Double? = nil,
+    sections: [JsonSection]? = nil,
     children: [JsonTrack]? = nil,
     src: String? = nil,
-    style: String? = nil,
-    childrenStyle: String? = nil,
-    groupTitle: String? = nil,
+    style: JsonStyle? = nil,
+    disabled: Bool? = nil,
     live: Bool? = nil,
+    icyCharset: String? = nil,
     carPlaySiriListButton: String? = nil,
   ) {
-    self.url = url
+    self.path = path
     self.title = title
     self.subtitle = subtitle
     self.artwork = artwork
     self.artist = artist
-    self.albumUrl = albumUrl
+    self.albumPath = albumPath
     self.album = album
     self.description = description
     self.genre = genre
     self.duration = duration
+    self.sections = sections
     self.children = children
     self.src = src
     self.style = style
-    self.childrenStyle = childrenStyle
-    self.groupTitle = groupTitle
+    self.disabled = disabled
     self.live = live
+    self.icyCharset = icyCharset
     self.carPlaySiriListButton = carPlaySiriListButton
     self.id = id
   }
@@ -178,50 +333,48 @@ struct JsonResolvedTrack: Codable {
 /// JSON model for individual tracks.
 struct JsonTrack: Codable {
   let id: String?
-  let url: String?
+  let path: String?
   let title: String
   let subtitle: String?
   let artwork: JsonArtwork?
   let artist: String?
-  let albumUrl: String?
+  let albumPath: String?
   let album: String?
   let description: String?
   let genre: String?
   let duration: Double?
   let src: String?
   let request: JsonTrackRequest?
-  let style: String?
-  let childrenStyle: String?
-  let groupTitle: String?
+  let style: JsonStyle?
+  let disabled: Bool?
   let live: Bool?
-  let imageRow: [JsonImageRowItem]?
+  let icyCharset: String?
 
   init(
     id: String? = nil,
-    url: String? = nil,
+    path: String? = nil,
     title: String,
     subtitle: String? = nil,
     artwork: JsonArtwork? = nil,
     artist: String? = nil,
-    albumUrl: String? = nil,
+    albumPath: String? = nil,
     album: String? = nil,
     description: String? = nil,
     genre: String? = nil,
     duration: Double? = nil,
     src: String? = nil,
     request: JsonTrackRequest? = nil,
-    style: String? = nil,
-    childrenStyle: String? = nil,
-    groupTitle: String? = nil,
+    style: JsonStyle? = nil,
+    disabled: Bool? = nil,
     live: Bool? = nil,
-    imageRow: [JsonImageRowItem]? = nil,
+    icyCharset: String? = nil,
   ) {
-    self.url = url
+    self.path = path
     self.title = title
     self.subtitle = subtitle
     self.artwork = artwork
     self.artist = artist
-    self.albumUrl = albumUrl
+    self.albumPath = albumPath
     self.album = album
     self.description = description
     self.genre = genre
@@ -229,10 +382,9 @@ struct JsonTrack: Codable {
     self.src = src
     self.request = request
     self.style = style
-    self.childrenStyle = childrenStyle
-    self.groupTitle = groupTitle
+    self.disabled = disabled
     self.live = live
-    self.imageRow = imageRow
+    self.icyCharset = icyCharset
     self.id = id
   }
 }
@@ -250,26 +402,28 @@ struct JsonTrack: Codable {
 
   extension JsonTrack {
     /// Snapshot the persistable subset of a live Track (inverse of `toNitro()`).
+    /// The track's own declared style block and `disabled` persist (ADR 0011);
+    /// section/page-inherited values are never stamped onto tracks and
+    /// re-resolve at render, exactly as they do live.
     init(from track: Track) {
       self.init(
         id: track.id,
-        url: track.url,
+        path: track.path,
         title: track.title,
         subtitle: track.subtitle,
         artwork: JsonArtwork(track.artwork),
         artist: track.artist,
-        albumUrl: track.albumUrl,
+        albumPath: track.albumPath,
         album: track.album,
         description: track.description,
         genre: track.genre,
         duration: track.duration,
         src: track.src,
         request: track.request.map(JsonTrackRequest.init(from:)),
-        style: nil,
-        childrenStyle: nil,
-        groupTitle: track.groupTitle,
+        style: JsonStyle(track.style),
+        disabled: track.disabled,
         live: track.live,
-        imageRow: nil,
+        icyCharset: track.icyCharset,
       )
     }
   }
@@ -289,15 +443,18 @@ struct JsonTrack: Codable {
     init(from track: Track) {
       self.init(
         id: track.id,
-        url: track.url,
+        path: track.path,
         title: track.title,
         artwork: JsonArtwork(track.artwork),
         artist: track.artist,
-        albumUrl: track.albumUrl,
+        albumPath: track.albumPath,
         album: track.album,
         src: track.src,
         request: track.request.map(JsonTrackRequest.init(from:)),
+        style: JsonStyle(track.style),
+        disabled: track.disabled,
         live: track.live,
+        icyCharset: track.icyCharset,
       )
     }
   }
@@ -308,26 +465,13 @@ struct JsonTrack: Codable {
 
 #if canImport(NitroModules)
 
-  private extension String {
-    func toTrackStyle() -> TrackStyle? {
-      TrackStyle(fromString: lowercased())
-    }
-  }
-
-  extension JsonImageRowItem {
-    func toNitro() -> ImageRowItem {
-      ImageRowItem(
-        id: id,
-        url: url,
-        src: src,
-        artwork: artwork,
-        artworkSource: nil,
+  extension JsonSection {
+    func toNitro() -> Section {
+      Section(
         title: title,
-        artist: artist,
-        album: album,
-        albumUrl: albumUrl,
-        live: live,
-        request: request?.toNitro(),
+        style: style?.toSectionStyle(),
+        path: path,
+        children: children.map { $0.toNitro() },
       )
     }
   }
@@ -335,28 +479,27 @@ struct JsonTrack: Codable {
   extension JsonResolvedTrack {
     func toNitro() -> ResolvedTrack {
       ResolvedTrack(
-        url: url,
+        path: path,
+        style: style?.toSectionStyle(),
+        sections: sections?.map { $0.toNitro() },
         children: children?.map { $0.toNitro() },
         carPlaySiriListButton: carPlaySiriListButton.flatMap { CarPlaySiriListButtonPosition(fromString: $0) },
         id: id,
         src: src,
         artwork: artwork?.toNitro(),
         artworkSource: nil, request: nil,
-        artworkCarPlayTinted: nil,
         title: title,
         subtitle: subtitle,
         artist: artist,
-        albumUrl: albumUrl,
+        albumPath: albumPath,
         album: album,
         description: description,
         genre: genre,
         duration: duration,
-        style: style?.toTrackStyle(),
-        childrenStyle: childrenStyle?.toTrackStyle(),
+        disabled: disabled,
         favorited: nil,
-        groupTitle: groupTitle,
         live: live,
-        imageRow: nil,
+        icyCharset: icyCharset,
       )
     }
   }
@@ -365,26 +508,24 @@ struct JsonTrack: Codable {
     func toNitro() -> Track {
       Track(
         id: id,
-        url: url,
+        path: path,
         src: src,
         artwork: artwork?.toNitro(),
         artworkSource: nil,
         request: request?.toNitro(),
-        artworkCarPlayTinted: nil,
         title: title,
         subtitle: subtitle,
         artist: artist,
-        albumUrl: albumUrl,
+        albumPath: albumPath,
         album: album,
         description: description,
         genre: genre,
         duration: duration,
         style: style?.toTrackStyle(),
-        childrenStyle: childrenStyle?.toTrackStyle(),
+        disabled: disabled,
         favorited: nil,
-        groupTitle: groupTitle,
         live: live,
-        imageRow: imageRow?.map { $0.toNitro() },
+        icyCharset: icyCharset,
       )
     }
   }
@@ -396,15 +537,29 @@ struct JsonTrack: Codable {
     func toNitro() -> Track {
       Track(
         id: id ?? "",
-        url: url,
+        path: path,
         src: src,
+        artwork: artwork?.toNitro(),
         request: request.map { TrackRequest(userAgent: $0.userAgent, headers: $0.headers, query: $0.query) },
         title: title,
         artist: artist,
-        albumUrl: albumUrl,
+        albumPath: albumPath,
         album: album,
+        style: style?.toTrackStyle(),
+        disabled: disabled,
         live: live,
-        artwork: artwork?.toNitro(),
+        icyCharset: icyCharset,
+      )
+    }
+  }
+
+  extension JsonSection {
+    func toNitro() -> Section {
+      Section(
+        title: title,
+        style: style?.toSectionStyle(),
+        path: path,
+        children: children.map { $0.toNitro() },
       )
     }
   }
@@ -412,10 +567,13 @@ struct JsonTrack: Codable {
   extension JsonResolvedTrack {
     func toNitro() -> ResolvedTrack {
       ResolvedTrack(
-        url: url,
+        path: path,
+        style: style?.toSectionStyle(),
+        sections: sections?.map { $0.toNitro() },
         children: children?.map { $0.toNitro() },
         artwork: artwork?.toNitro(),
         title: title,
+        disabled: disabled,
       )
     }
   }

package/ios/Browser/SearchDrillIn.swift

@@ -1,18 +1,18 @@
 import Foundation
 
 /// A search result that may or may not be directly playable. `src` is the
-/// playable stream; `url` is a browsable container path. Abstracting these two
+/// playable stream; `path` is a browsable container path. Abstracting these two
 /// fields keeps the drill-in decision free of the Nitro `Track` type so it can
 /// be unit-tested.
 protocol PlayableSearchItem {
   var src: String? { get }
-  var url: String? { get }
+  var path: String? { get }
 }
 
 enum SearchDrillIn {
   /// Picks the playable items for a "play «X»" voice search.
   ///
-  /// If the first result is browsable-only (a `url` container with no `src` — a
+  /// If the first result is browsable-only (a `path` container with no `src` — a
   /// place/genre page), drills into it via `resolveChildren` and uses its
   /// playable children, so we play the first station *inside* the page rather
   /// than skipping the page for a later inline station. Falls back to the flat
@@ -20,13 +20,13 @@ enum SearchDrillIn {
   /// yields nothing. Returns nil when nothing is playable.
   static func playable<Item: PlayableSearchItem>(
     from children: [Item],
-    resolveChildren: sending (String) async throws -> [Item]
+    resolveChildren: sending (String) async throws -> [Item],
   ) async throws -> [Item]? {
     guard !children.isEmpty else { return nil }
 
     let candidates: [Item]
-    if let first = children.first, first.src == nil, let url = first.url {
-      let drilled = try await resolveChildren(url).filter { $0.src != nil }
+    if let first = children.first, first.src == nil, let path = first.path {
+      let drilled = try await resolveChildren(path).filter { $0.src != nil }
       candidates = drilled.isEmpty ? children : drilled
     } else {
       candidates = children
@@ -37,7 +37,7 @@ enum SearchDrillIn {
   }
 }
 
-// The real Nitro `Track` already carries `src`/`url`; conform it for the app
+// The real Nitro `Track` already carries `src`/`path`; conform it for the app
 // build. (The testable target builds without NitroModules and uses a stub item.)
 #if canImport(NitroModules)
   extension Track: PlayableSearchItem {}

package/ios/Browser/SectionPresentation.swift

@@ -0,0 +1,64 @@
+#if canImport(NitroModules)
+  import NitroModules
+#endif
+
+/// The rendered form of a section — the single place where (resolved style,
+/// platform capability) maps to what CarPlay draws. Degradation drops
+/// decorations before layout (ADR 0011): a *wrapping* grid can only reach the
+/// tile path where the platform has a wrapping tile container (CarPlay:
+/// iOS 26+'s element API); without one it becomes a list, where every item
+/// stays reachable instead of truncating at an unknowable width. A
+/// single-line grid (`gridWrap: false`) renders everywhere — the legacy image
+/// row IS the single-line presentation.
+enum SectionPresentation: Equatable {
+  case list
+  case singleLineRow
+  case wrappingGrid
+
+  /// - Parameter supportsWrappingGrid: whether the platform has a wrapping
+  ///   tile container. Injected (rather than read via `#available` here) so
+  ///   the mapping is testable off-device.
+  init(for style: SectionStyle?, supportsWrappingGrid: Bool) {
+    guard style?.display == .grid else {
+      self = .list
+      return
+    }
+    if style?.gridWrap == false {
+      self = .singleLineRow
+    } else if supportsWrappingGrid {
+      self = .wrappingGrid
+    } else {
+      self = .list
+    }
+  }
+
+  /// The accessory symbol a resolved block actually draws: nil when
+  /// undeclared, and nil for the `'none'` sentinel — the inheritance escape
+  /// that restores the derived accessory (a browsable row's chevron). Here,
+  /// not in the CarPlay factory, so the sentinel rule is testable off-device.
+  static func effectiveAccessorySymbol(_ style: TrackStyle?) -> String? {
+    guard let symbol = style?.accessorySymbol, symbol != "none" else { return nil }
+    return symbol
+  }
+
+  /// The element family a tile presentation renders on iOS 26+ — here, not
+  /// in the CarPlay factory, so the style→family mapping is testable
+  /// off-device. `gridTile` picks the family (plain by default); the plain
+  /// single-line shelf keeps row elements, the one plain element with a
+  /// subtitle slot. Pre-26 has no element API at all: the treatment drops
+  /// with the legacy image row (decorations drop before layout).
+  enum TileElementFamily: Equatable {
+    case rowElements
+    case imageGridElements
+    case cardElements
+    case condensedElements
+  }
+
+  static func tileFamily(for style: SectionStyle?, singleLine: Bool) -> TileElementFamily {
+    switch style?.gridTile {
+    case .card: .cardElements
+    case .condensed: .condensedElements
+    case .plain, nil: singleLine ? .rowElements : .imageGridElements
+    }
+  }
+}