@iternio/react-native-auto-play 0.5.14-beta.1 → 0.6.0

package/ios/templates/AutoPlayMapPanelDelegate.swift

@@ -0,0 +1,190 @@
+//
+//  AutoPlayMapPanelDelegate.swift
+//  Pods
+//
+
+import CarPlay
+
+/// Shared `CPMapPanel.Delegate` for any `AutoPlayTemplate` that renders as a map panel
+/// (`ListTemplate`, and future panel-backed templates like a grid). `CPMapPanel.delegate` is
+/// `weak`, so the owning template must keep a strong reference to this instance for as long as
+/// the panel exists.
+@available(iOS 27.0, *)
+class AutoPlayMapPanelDelegate: NSObject, CPMapPanel.Delegate {
+    private weak var template: AutoPlayTemplate?
+    private let templateId: String
+    // As of iOS 27 beta 4, CarPlay invokes panelDidShow twice for a single push. Guard against
+    // firing the JS appear callbacks more than once per panel.
+    private var hasFiredPanelDidShow = false
+
+    init(template: AutoPlayTemplate, templateId: String) {
+        self.template = template
+        self.templateId = templateId
+    }
+
+    /// There's no "will appear" delegate method, so `onWillAppear` and `onDidAppear` fire
+    /// together here. Also fires `onWillDisappear` and `onDidDisappear` on whichever panel was on top
+    /// before this one, since CPMapPanelDelegate never notifies a covered panel itself —
+    /// `panelDidShow` only tells us about the panel that just appeared.
+    func panelDidShow(_ panel: CPMapPanel) {
+        if hasFiredPanelDidShow {
+            return
+        }
+        hasFiredPanelDidShow = true
+
+        template?.onWillAppear(animated: true)
+        template?.onDidAppear(animated: true)
+
+        let templateId = self.templateId
+
+        Task { @MainActor in
+            var previousPanelId: String?
+            var mapTemplate: CPMapTemplate?
+
+            try? await RootModule.withInterfaceController { interfaceController in
+                mapTemplate = interfaceController.rootTemplate as? CPMapTemplate
+                previousPanelId =
+                    interfaceController.panelTemplateIds
+                    .filter { $0 != templateId }
+                    .last
+            }
+
+            // This panel owns the map template's bar buttons and map buttons while it's on top.
+            if let mapTemplate {
+                // Auto-hiding the bar shifts the panel and interrupts taps on it.
+                mapTemplate.automaticallyHidesNavigationBar = false
+                mapTemplate.hidesButtonsWithNavigationBar = false
+
+                applyPanelHeaderActions(self.template?.getPanelHeaderActions(), to: mapTemplate)
+                applyPanelMapButtons(self.template?.getPanelMapButtons(), to: mapTemplate)
+            }
+
+            guard let previousPanelId else { return }
+
+            try? RootModule.withAutoPlayTemplate(templateId: previousPanelId) {
+                (template: AutoPlayTemplate) in
+                // let the now covered panel know it disappeared
+                template.onWillDisappear(animated: true)
+                template.onDidDisappear(animated: true)
+            }
+        }
+    }
+
+    /// There's no "will disappear" delegate method, so `onWillDisappear` and `onDidDisappear`
+    /// fire together here. Also fires `onWillAppear` and `onDidAppear` on whichever panel is now on
+    /// top after this one is removed, since CPMapPanelDelegate never notifies a revealed panel
+    /// itself — `panelDidHide` only tells us about the panel that just disappeared.
+    /// https://developer.apple.com/documentation/ios-ipados-release-notes/ios-ipados-27-release-notes#CarPlay
+    func panelDidHide(_ panel: CPMapPanel) {
+        let templateId = self.templateId
+
+        Task { @MainActor in
+            var stillTracked = false
+
+            try? await RootModule.withInterfaceController { interfaceController in
+                stillTracked = interfaceController.panelTemplateIds.contains(templateId)
+            }
+
+            // Already torn down elsewhere, e.g. by popToRootTemplate for a covered panel.
+            guard stillTracked else { return }
+
+            await handlePanelPopped(templateId: templateId, animated: true)
+        }
+    }
+}
+
+/// Tears down `templateId`'s panel and reveals whatever's now on top (or lets the map template
+/// reclaim its own bar/map buttons if nothing remains). Shared by `panelDidHide` — which only
+/// fires for a `hidePanel()`-triggered close — and `popTopEntry`'s `.panel` case, since
+/// `popPanel()` never triggers `panelDidHide` and so has to run this itself.
+@available(iOS 27.0, *)
+@MainActor
+func handlePanelPopped(templateId: String, animated: Bool) async {
+    var revealedPanelId: String?
+    var mapTemplate: CPMapTemplate?
+
+    try? await RootModule.withInterfaceController { interfaceController in
+        interfaceController.removeNavigationEntryIfPresent(templateId: templateId)
+        revealedPanelId = interfaceController.panelTemplateIds.last
+        mapTemplate = interfaceController.rootTemplate as? CPMapTemplate
+    }
+
+    try? RootModule.withAutoPlayTemplate(templateId: templateId) {
+        (template: AutoPlayTemplate) in
+        template.onWillDisappear(animated: animated)
+        template.onDidDisappear(animated: animated)
+    }
+
+    try? RootModule.withTemplateStore { templateStore in
+        templateStore.removeTemplate(templateId: templateId)
+    }
+
+    HybridAutoPlay.removeListeners(templateId: templateId)
+
+    if let revealedPanelId {
+        // Another panel is now on top: it reclaims the bar/map buttons and its own appear pair, same as a fresh push.
+        try? RootModule.withAutoPlayTemplate(templateId: revealedPanelId) {
+            (revealed: AutoPlayTemplate) in
+            if let mapTemplate {
+                applyPanelHeaderActions(revealed.getPanelHeaderActions(), to: mapTemplate)
+                applyPanelMapButtons(revealed.getPanelMapButtons(), to: mapTemplate)
+            }
+            // let the now uncovered panel know it appeared again
+            revealed.onWillAppear(animated: animated)
+            revealed.onDidAppear(animated: animated)
+        }
+    }
+    else if let mapTemplate {
+        // No panel remains: let the map template reclaim its own bar/map buttons.
+        try? RootModule.withAutoPlayTemplate(templateId: mapTemplate.id) {
+            (root: AutoPlayTemplate) in
+            root.invalidate()
+        }
+    }
+}
+
+/// Re-applies `templateId`'s header/map buttons to the root map template's nav bar, but only if
+/// it's currently the topmost (visible) panel. `_invalidate()` (e.g. from `setHeaderActions()`)
+/// runs for covered panels too, and only the topmost panel owns the nav bar — applying
+/// unconditionally would clobber whichever panel is actually on top. A covered panel's own
+/// buttons get reapplied later, when it's revealed again (see `handlePanelPopped`).
+@available(iOS 27.0, *)
+@MainActor
+func reapplyPanelBarIfVisible(_ template: AutoPlayTemplate, templateId: String) {
+    guard
+        let scene = SceneStore.getRootScene(),
+        let interfaceController = scene.interfaceController,
+        interfaceController.panelTemplateIds.last == templateId,
+        let mapTemplate = interfaceController.rootTemplate as? CPMapTemplate
+    else { return }
+
+    applyPanelHeaderActions(template.getPanelHeaderActions(), to: mapTemplate)
+    applyPanelMapButtons(template.getPanelMapButtons(), to: mapTemplate)
+}
+
+/// apply header buttons according to mapConfig.headerActions or remove the map provided buttons in case none are specified for the panel
+@available(iOS 27.0, *)
+@MainActor
+private func applyPanelHeaderActions(_ headerActions: [NitroAction]?, to mapTemplate: CPMapTemplate) {
+    guard let headerActions else {
+        mapTemplate.backButton = nil
+        mapTemplate.leadingNavigationBarButtons = []
+        mapTemplate.trailingNavigationBarButtons = []
+        return
+    }
+
+    setBarButtons(template: mapTemplate, barButtons: headerActions)
+}
+
+/// Applies mapConfig.mapButtons to the map template, or clears them if the panel specifies none.
+@available(iOS 27.0, *)
+@MainActor
+private func applyPanelMapButtons(_ mapButtons: [NitroMapButton]?, to mapTemplate: CPMapTemplate) {
+    // Only need the root MapTemplate for its onPanButtonPress callback, since a .pan button still controls the same underlying map.
+    try? RootModule.withAutoPlayTemplate(templateId: mapTemplate.id) { (root: MapTemplate) in
+        mapTemplate.mapButtons = Parser.parseMapButtons(
+            mapButtons: mapButtons ?? [],
+            onPanButtonPress: root.onPanButtonPress
+        )
+    }
+}

package/ios/templates/AutoPlayTemplate.swift

@@ -10,10 +10,30 @@ import CarPlay
 class AutoPlayTemplate: NSObject {
     public private(set) var autoDismissMs: Double?
 
-    func getTemplate() -> CPTemplate {
+    func getTemplate() throws -> CPTemplate {
         fatalError("getTemplate not implemented")
     }
 
+    /// Templates that render as an overlay panel on an existing root `CPMapTemplate`
+    /// (iOS 27+, e.g. `ListTemplate` with `mapConfig` set) override this to return their
+    /// `CPMapPanel` instead of providing a `CPTemplate` via `getTemplate()`. Returned as `Any`
+    /// since `CPMapPanel` is only available on iOS 27+ while this class supports iOS 15.1+.
+    func getPanel() -> Any? {
+        return nil
+    }
+
+    /// Header actions to apply to the root map template's bar while this template renders as
+    /// a map panel (see `getPanel()`) — distinct from any `barButtons` used for a plain
+    /// `CPTemplate`, since the panel itself has no nav bar of its own.
+    func getPanelHeaderActions() -> [NitroAction]? {
+        return nil
+    }
+
+    /// Map buttons to apply to the root map template while this renders as a map panel (see `getPanel()`).
+    func getPanelMapButtons() -> [NitroMapButton]? {
+        return nil
+    }
+
     @MainActor final func invalidate() {
         if SceneStore.getRootScene() == nil {
             return
@@ -25,7 +45,9 @@ class AutoPlayTemplate: NSObject {
     /// Override in subclasses to perform template invalidation.
     /// Do not call this method directly. Call `invalidate()` instead.
     @MainActor func _invalidate() {}
-    @MainActor func traitCollectionDidChange() {}
+    @MainActor func traitCollectionDidChange() {
+        invalidate()
+    }
 
     func onWillAppear(animated: Bool) {}
     func onDidAppear(animated: Bool) {}

package/ios/templates/GridTemplate.swift

@@ -8,92 +8,92 @@
 import CarPlay
 
 class GridTemplate: AutoPlayHeaderProviding {
-    let template: CPGridTemplate
+    /// `nil` when this template renders as a map panel instead (see `mapPanel`).
+    private(set) var template: CPGridTemplate?
     var config: GridTemplateConfig
 
     var buttons: [NitroGridButton]
 
+    /// Boxed as `Any` since `CPMapPanel` itself is only available on iOS 27+ while this class supports a much lower deployment target.
+    private var mapPanel: Any?
+
+    /// `CPMapPanel.delegate` is `weak`, so this keeps the shared delegate alive for as long as the panel exists. Boxed as `Any` for the same reason as `mapPanel`.
+    private var mapPanelDelegate: Any?
+
     override var autoDismissMs: Double? {
         return config.autoDismissMs
     }
 
-    override func getTemplate() -> CPTemplate {
+    override func getTemplate() throws -> CPTemplate {
+        guard let template else {
+            throw AutoPlayError.templateIsMapPanel(config.id)
+        }
         return template
     }
 
+    override func getPanel() -> Any? {
+        return mapPanel
+    }
+
+    override func getPanelHeaderActions() -> [NitroAction]? {
+        return barButtons
+    }
+
+    override func getPanelMapButtons() -> [NitroMapButton]? {
+        return config.mapConfig?.mapButtons
+    }
+
     init(config: GridTemplateConfig) {
         self.config = config
         buttons = config.buttons
 
-        template = CPGridTemplate(
-            title: Parser.parseText(text: config.title),
-            gridButtons: GridTemplate.parseButtons(buttons: buttons),
-            id: config.id
-        )
+        let title = Parser.parseText(text: config.title)
+
+        if #available(iOS 27.0, *), config.mapConfig != nil {
+            mapPanel = CPMapPanel(
+                title: title,
+                sections: [CPMapPanelSection(title: nil, items: [])],
+                buttonConfiguration: nil
+            )
+        }
+        else {
+            template = CPGridTemplate(
+                title: title,
+                gridButtons: GridTemplate.parseButtons(buttons: buttons),
+                id: config.id
+            )
+        }
 
         super.init()
 
         barButtons = config.headerActions
 
+        if #available(iOS 27.0, *), let mapPanel = mapPanel as? CPMapPanel {
+            let delegate = AutoPlayMapPanelDelegate(template: self, templateId: config.id)
+            mapPanelDelegate = delegate
+            mapPanel.delegate = delegate
+        }
     }
 
     static func parseButtons(buttons: [NitroGridButton]) -> [CPGridButton] {
-        let gridButtonHeight: CGFloat
-
-        if #available(iOS 26.0, *) {
-            gridButtonHeight = CPGridTemplate.maximumGridButtonImageSize.height
-        }
-        else {
-            gridButtonHeight = 44
-        }
-
-        guard let traitCollection = SceneStore.getRootTraitCollection() else {
-            return []
-        }
-
-        return buttons.compactMap { button in
-            var image: UIImage?
-
-            if let glyphImage = button.image.glyphImage {
-                image = SymbolFont.imageFromNitroImage(
-                    image: glyphImage,
-                    size: gridButtonHeight,
-                    traitCollection: traitCollection
-                )
-            }
-
-            if let assetImage = button.image.assetImage {
-                image = Parser.parseAssetImage(
-                    assetImage: assetImage,
-                    traitCollection: traitCollection
-                )
-            }
-
-            if let remoteImage = button.image.remoteImage {
-                image = Parser.parseRemoteImage(
-                    remoteImage: remoteImage,
-                    traitCollection: traitCollection
-                )
-            }
-
-            guard let image = image else { return nil }
-            guard let title = Parser.parseText(text: button.title) else { return nil }
-
-            return CPGridButton(
-                titleVariants: [title],
-                image: image
-            ) { _ in
-                button.onPress()
-            }
-        }
+        guard let traitCollection = SceneStore.getRootTraitCollection() else { return [] }
+        return Parser.parseGridButtons(buttons: buttons, traitCollection: traitCollection)
     }
 
     @MainActor
     override func _invalidate() {
+        if #available(iOS 27.0, *), let mapPanel = mapPanel as? CPMapPanel {
+            let parsedButtons = GridTemplate.parseButtons(buttons: buttons)
+            mapPanel.sections.first?.items = [CPMapPanelItem(gridButtons: parsedButtons)]
+            reapplyPanelBarIfVisible(self, templateId: config.id)
+            return
+        }
+
+        guard let template else { return }
+
         setBarButtons(template: template, barButtons: barButtons)
 
-        let buttons = GridTemplate.parseButtons(buttons: buttons)
-        template.updateGridButtons(buttons)
+        template.updateGridButtons(GridTemplate.parseButtons(buttons: buttons))
     }
 
     override func onWillAppear(animated: Bool) {

package/ios/templates/InformationTemplate.swift

@@ -8,31 +8,69 @@
 import CarPlay
 
 class InformationTemplate: AutoPlayHeaderProviding {
-    let template: CPInformationTemplate
+    /// `nil` when this template renders as a map panel instead (see `mapPanel`).
+    private(set) var template: CPInformationTemplate?
     var config: InformationTemplateConfig
 
     var section: NitroSection
 
+    /// Whether this template renders as a `CPMapPanel` instead of a plain `CPInformationTemplate`.
+    private let usesMapPanel: Bool
+
+    /// Built lazily on the first `_invalidate()` call rather than in `init()`: `CPMapPanel.buttonConfiguration`
+    /// is readonly, so unlike sections it can't be patched in later, and building it needs
+    /// `traitCollection` for the optional symbol button image — only safe to fetch on the
+    /// main thread, which `init()` isn't guaranteed to run on. Boxed as `Any` since `CPMapPanel`
+    /// itself is only available on iOS 27+ while this class supports a much lower deployment target.
+    private var mapPanel: Any?
+
+    /// `CPMapPanel.delegate` is `weak`, so this keeps the shared delegate alive for as long as the panel exists. Boxed as `Any` for the same reason as `mapPanel`.
+    private var mapPanelDelegate: Any?
+
     override var autoDismissMs: Double? {
         return config.autoDismissMs
     }
 
-    override func getTemplate() -> CPTemplate {
+    override func getTemplate() throws -> CPTemplate {
+        guard let template else {
+            throw AutoPlayError.templateIsMapPanel(config.id)
+        }
         return template
     }
 
+    override func getPanel() -> Any? {
+        return mapPanel
+    }
+
+    override func getPanelHeaderActions() -> [NitroAction]? {
+        return barButtons
+    }
+
+    override func getPanelMapButtons() -> [NitroMapButton]? {
+        return config.mapConfig?.mapButtons
+    }
+
     init(config: InformationTemplateConfig) {
         self.config = config
 
         section = config.section
 
-        template = CPInformationTemplate(
-            title: Parser.parseText(text: config.title)!,
-            layout: .leading,
-            items: Parser.parseInformationItems(section: section),
-            actions: Parser.parseInformationActions(actions: config.actions),
-            id: config.id
-        )
+        if #available(iOS 27.0, *) {
+            usesMapPanel = config.mapConfig != nil
+        }
+        else {
+            usesMapPanel = false
+        }
+
+        if !usesMapPanel {
+            template = CPInformationTemplate(
+                title: Parser.parseText(text: config.title)!,
+                layout: .leading,
+                items: Parser.parseInformationItems(section: section),
+                actions: Parser.parseInformationActions(actions: config.actions),
+                id: config.id
+            )
+        }
 
         super.init()
 
@@ -41,6 +79,43 @@ class InformationTemplate: AutoPlayHeaderProviding {
 
     @MainActor
     override func _invalidate() {
+        if usesMapPanel, #available(iOS 27.0, *) {
+            guard let mapPanel = mapPanel as? CPMapPanel else {
+                guard let traitCollection = SceneStore.getRootTraitCollection() else { return }
+
+                // InformationTemplate's actions are only ever set once and never updated
+                // afterwards, so there's nothing to keep in sync with buttonConfiguration later.
+                let panel = CPMapPanel(
+                    title: Parser.parseText(text: config.title),
+                    sections: [
+                        CPMapPanelSection(
+                            title: nil,
+                            items: Parser.parseInformationPanelItems(section: section)
+                        )
+                    ],
+                    buttonConfiguration: Parser.parsePanelButtonConfiguration(
+                        actions: config.actions,
+                        traitCollection: traitCollection
+                    )
+                )
+
+                mapPanel = panel
+
+                let delegate = AutoPlayMapPanelDelegate(template: self, templateId: config.id)
+                mapPanelDelegate = delegate
+                panel.delegate = delegate
+
+                reapplyPanelBarIfVisible(self, templateId: config.id)
+                return
+            }
+
+            mapPanel.sections.first?.items = Parser.parseInformationPanelItems(section: section)
+            reapplyPanelBarIfVisible(self, templateId: config.id)
+            return
+        }
+
+        guard let template else { return }
+
         setBarButtons(template: template, barButtons: barButtons)
         template.items = Parser.parseInformationItems(section: section)
     }

package/ios/templates/ListTemplate.swift

@@ -8,44 +8,99 @@
 import CarPlay
 
 class ListTemplate: AutoPlayHeaderProviding {
-    let template: CPListTemplate
+    /// `nil` when this template renders as a map panel instead (see `mapPanel`).
+    private(set) var template: CPListTemplate?
     var config: ListTemplateConfig
 
     var sections: [NitroSection]?
 
+    /// Boxed as `Any` since `CPMapPanel` itself is only available on
+    /// iOS 27+ while this class supports a much lower deployment target.
+    private var mapPanel: Any?
+
+    /// `CPMapPanel.delegate` is `weak`, so this keeps the shared delegate alive for as long as
+    /// the panel exists. Boxed as `Any` for the same reason as `mapPanel`.
+    private var mapPanelDelegate: Any?
+
     override var autoDismissMs: Double? {
         return config.autoDismissMs
     }
 
-    override func getTemplate() -> CPTemplate {
+    override func getTemplate() throws -> CPTemplate {
+        guard let template else {
+            throw AutoPlayError.templateIsMapPanel(config.id)
+        }
         return template
     }
 
+    override func getPanel() -> Any? {
+        return mapPanel
+    }
+
+    override func getPanelHeaderActions() -> [NitroAction]? {
+        return barButtons
+    }
+
+    override func getPanelMapButtons() -> [NitroMapButton]? {
+        return config.mapConfig?.mapButtons
+    }
+
     init(config: ListTemplateConfig) {
         self.config = config
 
         sections = config.sections
-
-        template = CPListTemplate(
-            title: Parser.parseText(text: config.title),
-            sections: [],
-            assistantCellConfiguration: nil,
-            id: config.id
-        )
+        let title = Parser.parseText(text: config.title)
+
+        if #available(iOS 27.0, *), config.mapConfig != nil {
+            mapPanel = CPMapPanel(
+                title: title,
+                sections: (config.sections ?? []).map { section in
+                    CPMapPanelSection(title: section.title, items: [])
+                },
+                buttonConfiguration: nil
+            )
+        }
+        else {
+            template = CPListTemplate(
+                title: title,
+                sections: [],
+                assistantCellConfiguration: nil,
+                id: config.id
+            )
+        }
 
         super.init()
 
         barButtons = config.headerActions
+
+        if #available(iOS 27.0, *), let mapPanel = mapPanel as? CPMapPanel {
+            let delegate = AutoPlayMapPanelDelegate(template: self, templateId: config.id)
+            mapPanelDelegate = delegate
+            mapPanel.delegate = delegate
+        }
     }
 
     @MainActor
     override func _invalidate() {
-        setBarButtons(template: template, barButtons: barButtons)
-
         guard let traitCollection = SceneStore.getRootTraitCollection() else {
             return
         }
 
+        if #available(iOS 27.0, *), let mapPanel = mapPanel as? CPMapPanel {
+            mapPanel.sections = Parser.parseMapPanelSections(
+                sections: sections,
+                updateSection: self.updateSection(section:sectionIndex:),
+                traitCollection: traitCollection
+            )
+
+            reapplyPanelBarIfVisible(self, templateId: config.id)
+            return
+        }
+
+        guard let template else { return }
+
+        setBarButtons(template: template, barButtons: barButtons)
+
         template.updateSections(
             Parser.parseSections(
                 sections: sections,