react-native-audio-browser 0.2.0-next.3 → 0.2.0-next.31

package/ios/CarPlay/CarPlayListItemFactory.swift

@@ -7,8 +7,9 @@ import os.log
 
 /// Typed metadata stored on CPListItems, replacing stringly-typed userInfo dictionaries.
 struct CarPlayItemInfo {
-  let id: String?
-  let src: String?
+  /// The track's identity (`id` when non-blank, else `src`) — the comparison
+  /// key for the now-playing indicator repaint sweep.
+  let identity: String?
 }
 
 extension CPListItem {
@@ -29,68 +30,89 @@ final class CarPlayListItemFactory {
   private let logger = Logger(subsystem: "com.audiobrowser", category: "CarPlayListItemFactory")
 
   var imageLoader: CarPlayImageLoader?
-  private let isActiveTrack: (_ id: String?, _ src: String?) -> Bool
-  private let onItemSelected: (Track, @escaping () -> Void) -> Void
-
-  init(
-    isActiveTrack: @escaping (_ id: String?, _ src: String?) -> Bool,
-    onItemSelected: @escaping (Track, @escaping () -> Void) -> Void,
-  ) {
+  /// Pushed by the controller (at creation and when options change), like
+  /// `imageLoader` — the factory never reads options itself.
+  var playingIndicatorLocation: CPListItemPlayingIndicatorLocation = .leading
+  private let isActiveTrack: (_ identity: String?) -> Bool
+  /// A row or tile was tapped; call `completion` once CarPlay may take the next tap.
+  var onItemSelected: (Track, @escaping () -> Void) -> Void = { _, completion in completion() }
+  /// A section header's "view all" was tapped.
+  var onNavigate: (_ path: String, _ title: String) -> Void = { _, _ in }
+
+  init(isActiveTrack: @escaping (_ identity: String?) -> Bool) {
     self.isActiveTrack = isActiveTrack
-    self.onItemSelected = onItemSelected
   }
 
   // MARK: - Sections
 
+  /// Whether this OS has CarPlay's iOS 26 element API — the wrapping tile
+  /// container and the text-less image row `SectionPresentation` degrades
+  /// against.
+  private static var supportsElements: Bool {
+    if #available(iOS 26.0, *) { return true }
+    return false
+  }
+
+  private static func listSection(_ items: [CPListTemplateItem], header: String?) -> CPListSection {
+    if let header {
+      return CPListSection(items: items, header: header, sectionIndexTitle: nil)
+    }
+    return CPListSection(items: items)
+  }
+
+  /// Maps the page's sections 1:1 to CPListSections (ADR 0010), respecting
+  /// CarPlay's section and total-item budgets. Style blocks declare the
+  /// requested presentation (resolved `section ?? page` here — ADR 0011);
+  /// this renders CarPlay's nearest supported form (`SectionPresentation`):
+  /// - list (default): a titled/headerless section of list rows.
+  /// - single-line grid (`gridWrap: false`): a section holding one
+  ///   single-line image-row item — the tiles that fit render, the rest
+  ///   truncate (the platform doesn't report the fit).
+  /// - wrapping grid: a wrapping, titled tile grid on iOS 26+; a plain list
+  ///   before that.
   func createSections(from resolvedTrack: ResolvedTrack) -> [CPListSection] {
-    guard let children = resolvedTrack.children else {
+    guard let sections = resolvedTrack.normalizedSections else {
       return []
     }
 
     let maxSections = CPListTemplate.maximumSectionCount
     let maxTotalItems = CPListTemplate.maximumItemCount
 
-    // Contiguous runs sharing a groupTitle form a section (the same semantics
-    // Android Auto's GROUP_TITLE hint has), so sections — titled or not —
-    // render in exact source (server) order. Ungrouped runs become headerless
-    // sections in place rather than being hoisted to the top.
-    var runs: [(title: String?, tracks: [Track])] = []
-    for track in children {
-      if let last = runs.indices.last, runs[last].title == track.groupTitle {
-        runs[last].tracks.append(track)
-      } else {
-        runs.append((track.groupTitle, [track]))
-      }
-    }
-
-    // Create sections (respecting both section and total item limits)
-    var sections: [CPListSection] = []
+    var listSections: [CPListSection] = []
     var totalItemCount = 0
 
-    for run in runs {
-      guard sections.count < maxSections else { break }
+    for section in sections {
+      guard listSections.count < maxSections else { break }
       guard totalItemCount < maxTotalItems else { break }
-
-      let availableSlots = maxTotalItems - totalItemCount
-      let items: [CPListTemplateItem] = run.tracks.prefix(availableSlots).map { track in
-        // Empty image rows fall through to a plain list item: zero-image
-        // CPListImageRowItem init is undocumented territory, and a header-only
-        // row is a dead end regardless (a "popular" row with no entries yet).
-        if let imageRow = track.imageRow, !imageRow.isEmpty {
-          return createImageRowItem(for: track)
+      // An empty section is a dead end regardless of style (a "popular"
+      // section with no entries yet) — skip it rather than render a header
+      // with nothing under it.
+      guard !section.children.isEmpty else { continue }
+
+      let style = StyleResolver.sectionStyle(section: section.style, page: resolvedTrack.style)
+      let presentation = SectionPresentation(for: style, supportsWrappingGrid: Self.supportsElements)
+      switch presentation {
+      case .list:
+        let availableSlots = maxTotalItems - totalItemCount
+        let items: [CPListTemplateItem] = section.children.prefix(availableSlots).map {
+          createListItem(for: $0, style: StyleResolver.trackStyle(track: $0.style, section: style))
         }
-        return createListItem(for: track)
+        listSections.append(Self.listSection(items, header: section.title))
+        totalItemCount += items.count
+      case .singleLineRow, .wrappingGrid:
+        // Tile presentations render as one image-row item in its own
+        // CPListSection. The title is drawn once: as the section's header
+        // (`SectionPresentation.tileSectionHeader`), or as the item's text.
+        let header = SectionPresentation.tileSectionHeader(section, supportsElements: Self.supportsElements)
+        guard let item = createImageRowItem(
+          for: section, text: header == nil ? section.title : nil, style: style, presentation: presentation,
+        ) else { continue }
+        listSections.append(Self.listSection([item], header: header))
+        totalItemCount += 1
       }
-      guard !items.isEmpty else { continue }
-      if let title = run.title {
-        sections.append(CPListSection(items: items, header: title, sectionIndexTitle: nil))
-      } else {
-        sections.append(CPListSection(items: items))
-      }
-      totalItemCount += items.count
     }
 
-    return sections
+    return listSections
   }
 
   // MARK: - List Item
@@ -98,9 +120,14 @@ final class CarPlayListItemFactory {
   /// Creates a CPListItem for a track with common setup (typed userInfo, artwork, isPlaying).
   /// - Parameters:
   ///   - track: The track to create the item for
+  ///   - style: The track's resolved style block (`track ?? section ?? page`,
+  ///     via `StyleResolver`). nil = the track's own declaration — the one
+  ///     genuinely section-less caller (the Up Next queue list) has no
+  ///     inheritance to resolve.
   ///   - handler: Optional custom handler. If nil, uses default browse/play handling.
   func createListItem(
     for track: Track,
+    style: TrackStyle? = nil,
     handler: ((CPSelectableListItem, @escaping () -> Void) -> Void)? = nil,
   ) -> CPListItem {
     let item = CPListItem(
@@ -109,46 +136,70 @@ final class CarPlayListItemFactory {
     )
 
     // Store typed info for updatePlayingIndicators()
-    item.setCarPlayItemInfo(CarPlayItemInfo(id: track.id, src: track.src))
+    item.setCarPlayItemInfo(CarPlayItemInfo(identity: track.identity))
 
     // Set accessory type based on whether track is browsable or playable
     if let src = track.src {
       // Playable track - check if it's currently playing
       item.accessoryType = .none
-      // Leading (the system default, set explicitly to make the choice
-      // deliberate): the indicator draws in the artwork slot. Note the
+      // Consumer-configurable via `ios.carPlayPlayingIndicatorLocation`
+      // (default leading: the indicator draws in the artwork slot). Note the
       // indicator's rendering is owned by the phone's CarPlay service, and on
       // some iOS/CarPlay-Simulator combinations it isn't drawn at all — for
       // ANY third-party app. Verify on a real head unit before assuming a
       // logic bug here.
-      item.playingIndicatorLocation = .leading
-      item.isPlaying = isActiveTrack(track.id, src)
+      item.playingIndicatorLocation = playingIndicatorLocation
+      item.isPlaying = isActiveTrack(track.identity)
       if item.isPlaying {
         logger.debug("Setting isPlaying=true for: \(track.title) (src: \(src))")
       }
-    } else if track.url != nil {
+    } else if track.path != nil {
       // Browsable only - show disclosure indicator
       item.accessoryType = .disclosureIndicator
     }
 
+    // A resolved accessorySymbol replaces the derived accessory above
+    // (accessoryImage outranks accessoryType in the SDK). 'none' — the
+    // inheritance escape — keeps the derived behavior instead.
+    if let symbol = SectionPresentation.effectiveAccessorySymbol(style ?? track.style),
+       let accessory = UIImage(systemName: symbol)
+    {
+      // `accessoryImage` is readonly on CPListItem; post-init updates go
+      // through the setter (which also clears `accessoryType`, per the SDK).
+      item.setAccessoryImage(accessory)
+    }
+
+    // An unavailable track grays out and goes inert — list rows are the
+    // surface that CAN draw the fact, so it shows rather than hides
+    // (Track.disabled's rendering ladder).
+    if track.disabled == true {
+      item.isEnabled = false
+    }
+
     // Load artwork with size context for proper CDN optimization
     if track.artwork != nil || track.artworkSource != nil {
       // Set empty placeholder to reserve space while loading
-      item.setImage(imageLoader?.placeholderImage)
-      imageLoader?.loadArtwork(for: track, size: CPListItem.maximumImageSize) { [weak item] image in
+      item.setImage(imageLoader?.placeholderImage(size: CPListItem.maximumImageSize))
+      imageLoader?.loadArtwork(for: track, style: style, size: CPListItem.maximumImageSize) { [weak item] image in
         Task { @MainActor in
           item?.setImage(image)
         }
       }
     }
 
-    // Set selection handler
-    if let handler {
-      item.handler = handler
-    } else {
-      item.handler = { [onItemSelected] _, completion in
-        onItemSelected(track, completion)
+    // Set selection handler. The disabled guard wraps BOTH handler paths —
+    // custom handlers (Up Next rows skipping the queue, say) included: belt
+    // over the isEnabled braces, so an unavailable track stays inert even if
+    // a surface delivers the tap.
+    let selection = handler ?? { [onItemSelected] _, completion in
+      onItemSelected(track, completion)
+    }
+    item.handler = { item, completion in
+      guard track.disabled != true else {
+        completion()
+        return
       }
+      selection(item, completion)
     }
 
     return item
@@ -156,58 +207,218 @@ final class CarPlayListItemFactory {
 
   // MARK: - Image Row Item
 
-  /// Creates a CPListImageRowItem for a track that has an imageRow.
-  /// Renders as a horizontal row of tappable artwork thumbnails with a header title.
-  func createImageRowItem(for track: Track) -> CPListImageRowItem {
-    guard let imageRowItems = track.imageRow else {
-      fatalError("createImageRowItem called without imageRow")
+  /// Target size for images inside an image row. The iOS 26 SDK deprecates
+  /// `CPListImageRowItem.maximumImageSize` in favor of the element-based API,
+  /// so read whichever the running OS considers canonical.
+  private static var rowImageSize: CGSize {
+    if #available(iOS 26.0, *) {
+      return CPListImageRowItemElement.maximumImageSize
     }
+    return CPListImageRowItem.maximumImageSize
+  }
 
-    // CPListImageRowItem requires images at init — start with placeholders
-    let maxImages = CPMaximumNumberOfGridImages
-    let visibleItems = Array(imageRowItems.prefix(maxImages))
-    let placeholders = visibleItems.map { _ in imageLoader?.placeholderImage ?? UIImage() }
-    let titles = visibleItems.map(\.title)
+  /// Target artwork size for one tile. Cards, image tiles and plain row
+  /// elements read their own class maximums ('background' selects the larger
+  /// full-height card target); condensed tiles use the shared element size.
+  private static func tileImageSize(
+    family: SectionPresentation.TileElementFamily, cardImage: CardImage?,
+  ) -> CGSize {
+    guard #available(iOS 26.0, *) else { return CPListImageRowItem.maximumImageSize }
+    switch family {
+    case .cardElements:
+      return cardImage == .background
+        ? CPListImageRowItemCardElement.maximumFullHeightImageSize
+        : CPListImageRowItemCardElement.maximumImageSize
+    case .rowElements:
+      return CPListImageRowItemRowElement.maximumImageSize
+    case .imageGridElements:
+      return CPListImageRowItemImageGridElement.maximumImageSize
+    case .condensedElements:
+      return CPListImageRowItemElement.maximumImageSize
+    }
+  }
 
-    // Use imageTitles variant on iOS 17.4+ to show titles below each thumbnail
-    let item = if #available(iOS 17.4, *) {
-      CPListImageRowItem(text: track.title, images: placeholders, imageTitles: titles)
+  /// Creates the image-row item rendering a tile-presented section: a single
+  /// truncating line (`.singleLineRow`) or a wrapping multi-line grid
+  /// (`.wrappingGrid` — constructed on iOS 26+ only, by `SectionPresentation`).
+  ///
+  /// Returns nil when nothing is drawable — every child hidden by the
+  /// disabled ladder (pre-26 only; the element APIs gray instead).
+  ///
+  /// - Parameter text: the row's own title; nil when the list section's
+  ///   header carries it.
+  private func createImageRowItem(
+    for section: Section, text rowText: String?, style: SectionStyle, presentation: SectionPresentation,
+  ) -> CPListImageRowItem? {
+    let singleLine = presentation == .singleLineRow
+    let family = SectionPresentation.tileFamily(for: style)
+    // Disabled ladder: iOS 26 elements can draw unavailability (grayed +
+    // inert, below); the legacy image row can't, so there a disabled track
+    // hides — never a normal-looking dead tile.
+    let visibleChildren: [Track] = if #available(iOS 26.0, *) {
+      section.children
     } else {
-      CPListImageRowItem(text: track.title, images: placeholders)
+      section.children.filter { $0.disabled != true }
+    }
+    guard !visibleChildren.isEmpty else { return nil }
+    // A single line shows at most CPMaximumNumberOfGridImages; the wrapping
+    // grid takes every child (queue scope is declared, never rendered — the
+    // cap here only limits what's drawn, and only where the platform does).
+    let tracks = singleLine
+      ? Array(visibleChildren.prefix(CPMaximumNumberOfGridImages))
+      : visibleChildren
+    let placeholder = { [imageLoader] in
+      imageLoader?.placeholderImage(size: Self.rowImageSize) ?? UIImage()
     }
 
-    // Handler for row header tap → navigate to track.url if present. A row
-    // without a url (pure preview) has nothing to open, so its header tap is
-    // a no-op rather than a selection that can't resolve.
-    item.handler = { [onItemSelected] _, completion in
-      guard track.url != nil else {
+    let item: CPListImageRowItem
+    // Applies an async-loaded artwork image to a tile on the element-based
+    // API (the elements are captured per availability branch — their type
+    // doesn't exist before iOS 26). nil = the legacy gridImages path.
+    // @MainActor makes the closure Sendable for the artwork completion hop.
+    var applyImage: (@MainActor @Sendable (Int, UIImage) -> Void)?
+    // Resolved once per track, shared by element construction and the
+    // artwork loads below.
+    let resolvedStyles = tracks.map { StyleResolver.trackStyle(track: $0.style, section: style) }
+    if #available(iOS 26.0, *) {
+      // Builds a family's elements with the shared per-element tail: the
+      // disabled fact (isEnabled lives on the element base class) applied
+      // once, not per family.
+      func makeElements<Element: CPListImageRowItemElement>(
+        _ make: (Track, TrackStyle) -> Element,
+      ) -> [Element] {
+        zip(tracks, resolvedStyles).map { track, resolved in
+          let element = make(track, resolved)
+          if track.disabled == true {
+            element.isEnabled = false
+          }
+          return element
+        }
+      }
+      // The image setter every element family shares (`image` is on the base
+      // class); bounds-checked against the elements the row was built with.
+      func imageApplier(_ elements: [some CPListImageRowItemElement]) -> @MainActor @Sendable (Int, UIImage) -> Void {
+        { index, image in
+          guard index < elements.count else { return }
+          elements[index].image = image
+        }
+      }
+      // The family is style-driven (`SectionPresentation.tileFamily`); every
+      // family takes either wrap mode. Pre-26 the treatment drops and the
+      // layout survives (the legacy branch below).
+      switch family {
+      case .cardElements:
+        // Cards have no shape and no accessory slot; their knobs are the
+        // tint and the image mode ('background' fills the card full-height
+        // and fades the tint in behind the labels).
+        let elements = makeElements { track, resolved in
+          CPListImageRowItemCardElement(
+            image: placeholder(),
+            showsImageFullHeight: resolved.cardImage == .background,
+            title: track.title,
+            subtitle: track.subtitle,
+            tintColor: resolved.cardTint.flatMap { UIColor(declaredHex: $0) },
+          )
+        }
+        item = CPListImageRowItem(
+          text: rowText, cardElements: elements, allowsMultipleLines: !singleLine,
+        )
+        applyImage = imageApplier(elements)
+      case .condensedElements:
+        let elements = makeElements { track, resolved in
+          CPListImageRowItemCondensedElement(
+            image: placeholder(),
+            imageShape: resolved.imageShape == .circular ? .circular : .roundedRectangle,
+            title: track.title,
+            subtitle: track.subtitle,
+            accessorySymbolName: SectionPresentation.effectiveAccessorySymbol(resolved),
+          )
+        }
+        item = CPListImageRowItem(
+          text: rowText, condensedElements: elements, allowsMultipleLines: !singleLine,
+        )
+        applyImage = imageApplier(elements)
+      case .imageGridElements:
+        // imageGridElements, never the title-less gridElements: an
+        // artwork-less track must keep its name on screen (ADR 0010).
+        let elements = makeElements { track, resolved in
+          CPListImageRowItemImageGridElement(
+            image: placeholder(),
+            imageShape: resolved.imageShape == .circular ? .circular : .roundedRectangle,
+            title: track.title,
+            accessorySymbolName: SectionPresentation.effectiveAccessorySymbol(resolved),
+          )
+        }
+        item = CPListImageRowItem(
+          text: rowText, imageGridElements: elements, allowsMultipleLines: !singleLine,
+        )
+        applyImage = imageApplier(elements)
+      case .rowElements:
+        // Titled, so an artwork-less track keeps its name on screen
+        // (ADR 0010); no shape and no accessory slot.
+        let elements = makeElements { track, _ in
+          CPListImageRowItemRowElement(
+            image: placeholder(), title: track.title, subtitle: track.subtitle,
+          )
+        }
+        item = CPListImageRowItem(
+          text: rowText, elements: elements, allowsMultipleLines: !singleLine,
+        )
+        applyImage = imageApplier(elements)
+      }
+    } else {
+      let placeholders = tracks.map { _ in placeholder() }
+      // Use imageTitles variant on iOS 17.4+ to show titles below each thumbnail
+      if #available(iOS 17.4, *) {
+        item = CPListImageRowItem(text: rowText ?? "", images: placeholders, imageTitles: tracks.map(\.title))
+      } else {
+        item = CPListImageRowItem(text: rowText ?? "", images: placeholders)
+      }
+    }
+
+    // Header tap → navigate to section.path ("view all"). A path-less
+    // section is a pure preview and gets no handler.
+    if let path = section.path {
+      let title = section.title ?? ""
+      item.handler = { [onNavigate] _, completion in
+        onNavigate(path, title)
         completion()
-        return
       }
-      onItemSelected(track, completion)
     }
 
-    // Handler for individual image taps
+    // Per-tile taps select the child track directly. A disabled tile is
+    // grayed and inert (26+ elements) — the guard keeps it inert even if
+    // the surface delivers the tap anyway.
     item.listImageRowHandler = { [onItemSelected] _, index, completion in
-      guard index < visibleItems.count else {
+      guard index < tracks.count, tracks[index].disabled != true else {
         completion()
         return
       }
-      let tappedItem = visibleItems[index]
-      onItemSelected(tappedItem.toTrack(), completion)
+      onItemSelected(tracks[index], completion)
     }
 
-    // Load artwork for each visible image row item asynchronously
-    for (index, imageRowItem) in visibleItems.enumerated() {
-      guard imageRowItem.artwork != nil || imageRowItem.artworkSource != nil else { continue }
+    // Load artwork for each rendered tile asynchronously
+    for (index, track) in tracks.enumerated() {
+      guard track.artwork != nil || track.artworkSource != nil else { continue }
 
-      imageLoader?.loadArtwork(for: imageRowItem.toTrack(), size: CPListImageRowItem.maximumImageSize) { [weak item] image in
+      let resolved = resolvedStyles[index]
+      imageLoader?.loadArtwork(
+        for: track,
+        style: resolved,
+        size: Self.tileImageSize(family: family, cardImage: resolved.cardImage),
+      ) { [weak item, applyImage] image in
         Task { @MainActor in
           guard let item, let image else { return }
-          var images = item.gridImages
-          if index < images.count {
-            images[index] = image
-            item.update(images)
+          if let applyImage {
+            // The element-based API exposes a settable `image`; assigning it
+            // updates the element the row observes.
+            applyImage(index, image)
+          } else {
+            var images = item.gridImages
+            if index < images.count {
+              images[index] = image
+              item.update(images)
+            }
           }
         }
       }