[ios] Deprecate CarPlay delegate methods (#7872)

CHANGELOG.md

@@ -10,7 +10,11 @@
 ### API deprecations:
 
 * `MapboxCopilot.startActiveGuidanceSession(requestIdentifier:route:searchResultUsed:)`, `MapboxCopilot.startFreeDriveSession()`, and `MapboxCopilot.completeNavigationSession()` are deprecated in favor of `MapboxCopilot.startActiveGuidanceSessionAsync(requestIdentifier:route:searchResultUsed:)`, `MapboxCopilot.startFreeDriveSessionAsync()`, `MapboxCopilot.completeNavigationSessionAsync()`. Using deprecated methods may lead to losing events in the recorded history files.
-* `NavigationViewControllerDelegate.navigationMapView(_:didAdd:pointAnnotationManager:)` method is deprecated and should no longer be used, as the final destination annotation is no longer added to the map.
+* The following methods are deprecated and should no longer be used, as the final destination annotation is no longer added to the map:
+    * `NavigationViewControllerDelegate.navigationViewController(_:didAdd:pointAnnotationManager:)`
+    * `CarPlayNavigationViewControllerDelegate.carPlayNavigationViewController(_:didAdd:pointAnnotationManager:)`
+    * `CarPlayMapViewControllerDelegate.carPlayMapViewController(_:didAdd:pointAnnotationManager:)`
+    * `CarPlayManagerDelegate.carPlayManager(_:didAdd:to:pointAnnotationManager:)`
 
 ### Other changes
 

Sources/MapboxNavigationCore/Map/NavigationMapViewDelegate.swift

@@ -55,7 +55,7 @@ public protocol NavigationMapViewDelegate: AnyObject, UnimplementedLogging {
     @available(
         *,
         deprecated,
-        message: "This method is deprecated and should no longer be used, as the final destination annotation is no longer added to the map. Use corresponding delegate methods to customize waypoints appearance."
+        message: "This method is deprecated and should no longer be used, as the final destination annotation is no longer added to the map. Use the corresponding delegate methods to customize waypoints appearance."
     )
     func navigationMapView(
         _ navigationMapView: NavigationMapView,
@@ -113,7 +113,7 @@ public protocol NavigationMapViewDelegate: AnyObject, UnimplementedLogging {
     /// `FeatureCollection` for waypoints.
     /// Within this method:
     ///     1. Add an image to the map by calling `MapboxMap.addImage(_:id:stretchX:stretchY:)` method.
-    ///     2. Iterate through `waypoints` array and create `Feature` for each waypoint.
+    ///     2. Iterate through the `waypoints` array and create `Feature` for each waypoint.
     ///     3. Add a key-value pair to `Feature.properties` for specifying an icon image if the waypoint is
     ///     intermediate.
     ///

Sources/MapboxNavigationUIKit/CarPlay/CarPlayManager.swift

@@ -1196,19 +1196,6 @@ extension CarPlayManager: CarPlayNavigationViewControllerDelegate {
         return delegate?.carPlayManager(self, shouldPresentArrivalUIFor: waypoint) ?? true
     }
 
-    public func carPlayNavigationViewController(
-        _ carPlayNavigationViewController: CarPlayNavigationViewController,
-        didAdd finalDestinationAnnotation: PointAnnotation,
-        pointAnnotationManager: PointAnnotationManager
-    ) {
-        delegate?.carPlayManager(
-            self,
-            didAdd: finalDestinationAnnotation,
-            to: carPlayNavigationViewController,
-            pointAnnotationManager: pointAnnotationManager
-        )
-    }
-
     public func carPlayNavigationViewController(
         _ carPlayNavigationViewController: CarPlayNavigationViewController,
         shapeFor waypoints: [Waypoint],
@@ -1295,19 +1282,6 @@ extension CarPlayManager: CarPlayNavigationViewControllerDelegate {
 // MARK: CarPlayMapViewControllerDelegate Methods
 
 extension CarPlayManager: CarPlayMapViewControllerDelegate {
-    public func carPlayMapViewController(
-        _ carPlayMapViewController: CarPlayMapViewController,
-        didAdd finalDestinationAnnotation: PointAnnotation,
-        pointAnnotationManager: PointAnnotationManager
-    ) {
-        delegate?.carPlayManager(
-            self,
-            didAdd: finalDestinationAnnotation,
-            to: carPlayMapViewController,
-            pointAnnotationManager: pointAnnotationManager
-        )
-    }
-
     public func carPlayMapViewController(
         _ carPlayMapViewController: CarPlayMapViewController,
         routeLineLayerWithIdentifier identifier: String,

Sources/MapboxNavigationUIKit/CarPlay/CarPlayManagerDelegate.swift

@@ -233,53 +233,147 @@ public protocol CarPlayManagerDelegate: AnyObject, UnimplementedLogging {
     ///   - parentViewController: The view controller that contains the map view, which is an instance of either
     /// ``CarPlayMapViewController`` or ``CarPlayNavigationViewController``.
     ///   - pointAnnotationManager: The object that manages the point annotation in the map view.
+    @available(
+        *,
+        deprecated,
+        message: "This method is deprecated and should no longer be used, as the final destination annotation is no longer added to the map. Use the corresponding delegate methods to customize waypoints appearance."
+    )
     func carPlayManager(
         _ carPlayManager: CarPlayManager,
         didAdd finalDestinationAnnotation: PointAnnotation,
         to parentViewController: UIViewController,
         pointAnnotationManager: PointAnnotationManager
     )
 
-    /// Returns a `FeatureCollection` that represents intermediate waypoints along the route (that is, excluding the
-    /// origin).
-    /// If this method is unimplemented, the navigation view controller's map view draws the waypoints using default
-    /// `FeatureCollection`.
+    // MARK: Customizing Waypoint(s) Appearance
+
+    /// Asks the receiver to return a `CircleLayer` for waypoints, given an identifier and source.
+    /// The returned layer is added to the map below the layer returned by
+    /// ``CarPlayManagerDelegate/carPlayManager(_:waypointSymbolLayerWithIdentifier:sourceIdentifier:)``.
+    /// This method is invoked any time waypoints are added or shown.
     /// - Parameters:
     ///   - carPlayManager: The ``CarPlayManager`` object.
-    ///   - waypoints: The intermediate waypoints to be displayed on the map.
-    ///   - legIndex: The index of the current leg during navigation.
-    /// - Returns: A `FeatureCollection` that represents intermediate waypoints along the route (that is, excluding the
-    /// origin).
+    ///   - identifier: The `CircleLayer` identifier.
+    ///   - sourceIdentifier: Identifier of the source, which contains the waypoint data that this method would style.
+    /// - Returns: A `CircleLayer` that the map applies to all waypoints.
     func carPlayManager(
         _ carPlayManager: CarPlayManager,
-        shapeFor waypoints: [Waypoint],
-        legIndex: Int
-    ) -> FeatureCollection?
+        waypointCircleLayerWithIdentifier identifier: String,
+        sourceIdentifier: String
+    ) -> CircleLayer?
 
-    ///  Asks the receiver to return a `SymbolLayer` for waypoint symbols, given an identifier and source.
+    /// Asks the receiver to return a `SymbolLayer` for waypoint symbols, given an identifier and source.
+    /// The returned layer is added to the map above the layer returned by
+    /// ``CarPlayManagerDelegate/carPlayManager(_:waypointCircleLayerWithIdentifier:sourceIdentifier:)``.
+    /// This method is invoked any time waypoints are added or shown.
     /// - Parameters:
     ///   - carPlayManager: The ``CarPlayManager`` object.
     ///   - identifier: The `SymbolLayer` identifier.
     ///   - sourceIdentifier:  Identifier of the source, which contains the waypoint data that this method would style.
-    /// - Returns: A `SymbolLayer` that the map applies to all intermediate waypoint symbols.
+    /// - Returns: A `SymbolLayer` that the map applies to all waypoint symbols.
     func carPlayManager(
         _ carPlayManager: CarPlayManager,
         waypointSymbolLayerWithIdentifier identifier: String,
         sourceIdentifier: String
     ) -> SymbolLayer?
 
-    //  Asks the receiver to return a `CircleLayer` for waypoints, given an identifier and source. This method is
-    //  invoked any time waypoints are added or shown.
+    /// Asks the receiver to return a `FeatureCollection` that describes the geometry of waypoints.
+    ///
+    /// For example, to customize the appearance of intermediate waypoints by adding an image follow these steps:
+    ///
+    /// 1. Implement the ``CarPlayManagerDelegate/carPlayManager(_:shapeFor:legIndex:)``
+    /// method to provide a
+    /// `FeatureCollection` for waypoints.
+    /// Within this method:
+    ///     1. Add an image to the map by calling `MapboxMap.addImage(_:id:stretchX:stretchY:)` method.
+    ///     2. Iterate through the `waypoints` array and create `Feature` for each waypoint.
+    ///     3. Add a key-value pair to `Feature.properties` for specifying an icon image if the waypoint is
+    ///     intermediate.
+    ///
+    /// Example:
+    ///
+    /// ```swift
+    /// func carPlayManager(
+    ///     _ carPlayManager: CarPlayManager,
+    ///     shapeFor waypoints: [Waypoint],
+    ///     legIndex: Int
+    /// ) -> FeatureCollection? {
+    ///     guard let navigationMapView = carPlayManager.navigationMapView else { return nil }
+    ///
+    ///     let imageId = "intermediateWaypointImageId"
+    ///     if !navigationMapView.mapView.mapboxMap.imageExists(withId: imageId) {
+    ///         do {
+    ///             try navigationMapView.mapView.mapboxMap.addImage(
+    ///                 UIImage(named: "waypoint")!,
+    ///                 id: imageId,
+    ///                 stretchX: [],
+    ///                 stretchY: []
+    ///             )
+    ///         } catch {
+    ///             // Handle the error
+    ///             return nil
+    ///         }
+    ///     }
+    ///     return FeatureCollection(
+    ///         features: waypoints.enumerated().map { waypointIndex, waypoint in
+    ///             var feature = Feature(geometry: .point(Point(waypoint.coordinate)))
+    ///             var properties: [String: JSONValue] = [:]
+    ///             properties["waypointCompleted"] = .boolean(waypointIndex <= legIndex)
+    ///             properties["waypointIconImage"] = waypointIndex > 0 && waypointIndex < waypoints.count - 1
+    ///             ? .string(imageId)
+    ///             : nil
+    ///             feature.properties = properties
+    ///             return feature
+    ///         }
+    ///     )
+    /// }
+    /// ```
+    ///
+    /// 2. Implement the
+    /// ``CarPlayManagerDelegate/carPlayManager(_:waypointSymbolLayerWithIdentifier:sourceIdentifier:)``
+    /// method to provide a custom `SymbolLayer`.
+    ///     1. Create a `SymbolLayer`.
+    ///     2. Set `SymbolLayer.iconImage` to an expression `Exp` to retrieve the icon image name based on the
+    ///     properties defined in step 1.3.
+    ///
+    /// Example:
+    /// ```swift
+    /// func carPlayManager(
+    ///     _ carPlayManager: CarPlayManager,
+    ///     waypointSymbolLayerWithIdentifier identifier: String,
+    ///     sourceIdentifier: String
+    /// ) -> SymbolLayer? {
+    ///
+    ///     var symbolLayer = SymbolLayer(id: identifier, source: sourceIdentifier)
+    ///     let opacity = Exp(.switchCase) {
+    ///         Exp(.any) {
+    ///             Exp(.get) {
+    ///                 "waypointCompleted"
+    ///             }
+    ///         }
+    ///         0
+    ///         1
+    ///     }
+    ///     symbolLayer.iconOpacity = .expression(opacity)
+    ///     symbolLayer.iconImage = .expression(Exp(.get) { "waypointIconImage" })
+    ///     symbolLayer.iconAnchor = .constant(.bottom)
+    ///     symbolLayer.iconOffset = .constant([0, 15])
+    ///     symbolLayer.iconAllowOverlap = .constant(true)
+    ///     return symbolLayer
+    /// }
+    /// ```
+    ///
     /// - Parameters:
     ///   - carPlayManager: The ``CarPlayManager`` object.
-    ///   - identifier: The `CircleLayer` identifier.
-    ///   - sourceIdentifier: Identifier of the source, which contains the waypoint data that this method would style.
-    /// - Returns: A `CircleLayer` that the map applies to all intermediate waypoints.
+    ///   - waypoints: The waypoints to be displayed on the map.
+    ///   - legIndex: The index of the current leg during navigation.
+    /// - Returns: Optionally, a `FeatureCollection` that defines the shape of the waypoint, or `nil` to use default
+    /// behavior.
     func carPlayManager(
         _ carPlayManager: CarPlayManager,
-        waypointCircleLayerWithIdentifier identifier: String,
-        sourceIdentifier: String
-    ) -> CircleLayer?
+        shapeFor waypoints: [Waypoint],
+        legIndex: Int
+    ) -> FeatureCollection?
 
     // MARK: Transitioning Between Templates
 

Sources/MapboxNavigationUIKit/CarPlay/CarPlayMapViewController.swift

@@ -47,7 +47,8 @@ open class CarPlayMapViewController: UIViewController {
     }
 
     @MainActor
-    var navigationMapView: NavigationMapView {
+    /// The map view showing the route and the user’s location.
+    public var navigationMapView: NavigationMapView {
         return view as! NavigationMapView
     }
 
@@ -435,18 +436,6 @@ extension CarPlayMapViewController: StyleManagerDelegate {
 // MARK: NavigationMapViewDelegate Methods
 
 extension CarPlayMapViewController: NavigationMapViewDelegate {
-    public func navigationMapView(
-        _ navigationMapView: NavigationMapView,
-        didAdd finalDestinationAnnotation: PointAnnotation,
-        pointAnnotationManager: PointAnnotationManager
-    ) {
-        delegate?.carPlayMapViewController(
-            self,
-            didAdd: finalDestinationAnnotation,
-            pointAnnotationManager: pointAnnotationManager
-        )
-    }
-
     public func navigationMapView(
         _ navigationMapView: NavigationMapView,
         shapeFor waypoints: [Waypoint],