Continuous Alternatives CarPlay selection and callouts (#3956)

* vk-3927-alternatives-selection: added CarPlay list view for picking an alternative route; localizable string added; added alternative routes duration delta callouts; refactored duration callouts a bit; CHANGELOG updated; factored out DateComponentsFormatter.travelDurationStyle

Author: Udumft

CHANGELOG.md

@@ -35,13 +35,15 @@
 * Added the `layerPosition` parameter to the `NavigationMapView.show(_:layerPosition:legIndex:)` method for controlling the position of the main route layer while presenting routes. ([#3897](https://github.com/mapbox/mapbox-navigation-ios/pull/3897))
 * Fixed an issue where camera kept receiving updates even after stopping `MapboxNavigationService`. ([#3928](https://github.com/mapbox/mapbox-navigation-ios/pull/3928))
 * Added `NavigationViewController.showsContinuousAlternatives` and `CarPlayNavigationViewController.showsContinuousAlternatives` flags to toggle displaying alternative route's lines during navigation session. Use `NavigationMapView.show(continuousAlternatives:)` and `NavigationMapView.removeContinuousAlternativesRoutes()` methods for fine control over displayed routes. ([#3850](https://github.com/mapbox/mapbox-navigation-ios/pull/3850))
+* Each alternative route shown during turn-by-turn navigation is now annotated with the amount of time it saves or adds to the trip. To hide these annotations, set the `NavigationMapView.showsRelativeDurationOnContinuousAlternativeRoutes` property to `false`. ([#3956](https://github.com/mapbox/mapbox-navigation-ios/pull/3956))
 
 ### CarPlay
 
 * Fixed an issue where route shields disappeared when the user enters a tunnel. ([#3882](https://github.com/mapbox/mapbox-navigation-ios/pull/3882))
 * The map automatically chooses the night style when "Always Show Dark Maps" is enabled in the Appearance section of Settings. ([#3882](https://github.com/mapbox/mapbox-navigation-ios/pull/3882))
 * Renamed the `VisualInstruction.carPlayManeuverLabelAttributedText(bounds:shieldHeight:window:)` to the `VisualInstruction.carPlayManeuverLabelAttributedText(bounds:shieldHeight:window:traitCollection:instructionLabelType:)` to have the ability to change color of the shield icons depending on provided trait collection. ([#3882](https://github.com/mapbox/mapbox-navigation-ios/pull/3882))
 * Fixed an issue where a `StyleManager` for CarPlay would update the appearance on both CarPlay and the iOS device simultaneously. ([#3914](https://github.com/mapbox/mapbox-navigation-ios/pull/3914))
+* During the navigating activity, the user can tap the "Alternatives" button in the navigation bar to switch to an alternative route. ([#3956](https://github.com/mapbox/mapbox-navigation-ios/pull/3956))
 
 ### Other changes
 

Sources/MapboxCoreNavigation/AlternativeRoute.swift

@@ -38,7 +38,11 @@ public struct AlternativeRoute: Identifiable {
     public let infoFromDeviationPoint: RouteInfo
     /// Alternative route statistics, counting from it's origin.
     public let infoFromOrigin: RouteInfo
-
+    /// The difference of distances between alternative and the main routes
+    public let distanceDelta: LocationDistance
+    /// The difference of expected travel time between alternative and the main routes
+    public let expectedTravelTimeDelta: TimeInterval
+    
     init?(mainRoute: Route, alternativeRoute nativeRouteAlternative: RouteAlternative) {
         self.id = nativeRouteAlternative.id
         guard let decoded = RerouteController.decode(routeRequest: nativeRouteAlternative.route.getRequestUri(),
@@ -70,6 +74,9 @@ public struct AlternativeRoute: Identifiable {
                                             duration: nativeRouteAlternative.infoFromFork.duration)
         self.infoFromOrigin = .init(distance: nativeRouteAlternative.infoFromStart.distance,
                                     duration: nativeRouteAlternative.infoFromStart.duration)
+        
+        self.distanceDelta = infoFromOrigin.distance - mainRoute.distance
+        self.expectedTravelTimeDelta = infoFromOrigin.duration - mainRoute.expectedTravelTime
     }
 
     /**
@@ -83,13 +90,17 @@ public struct AlternativeRoute: Identifiable {
                 mainRouteIntersection: Intersection,
                 alternativeRouteIntersection: Intersection,
                 infoFromDeviationPoint: RouteInfo,
-                infoFromOrigin: RouteInfo) {
+                infoFromOrigin: RouteInfo,
+                distanceDelta: LocationDistance,
+                expectedTravelTimeDelta: TimeInterval) {
         self.id = id
         self.indexedRouteResponse = indexedRouteResponse
         self.mainRouteIntersection = mainRouteIntersection
         self.alternativeRouteIntersection = alternativeRouteIntersection
         self.infoFromDeviationPoint = infoFromDeviationPoint
         self.infoFromOrigin = infoFromOrigin
+        self.distanceDelta = distanceDelta
+        self.expectedTravelTimeDelta = expectedTravelTimeDelta
     }
 }
 

Sources/MapboxNavigation/BottomBannerViewController.swift

@@ -206,7 +206,7 @@ open class BottomBannerViewController: UIViewController, NavigationComponent {
             distanceRemainingLabel.text = distanceFormatter.string(from: routeProgress.distanceRemaining)
         }
 
-        dateComponentsFormatter.unitsStyle = routeProgress.durationRemaining < 3600 ? .short : .abbreviated
+        dateComponentsFormatter.unitsStyle = DateComponentsFormatter.travelDurationUnitStyle(interval: routeProgress.durationRemaining)
 
         if let hardcodedTime = dateComponentsFormatter.string(from: 61), routeProgress.durationRemaining < 60 {
             timeRemainingLabel.text = String.localizedStringWithFormat(NSLocalizedString("LESS_THAN", bundle: .mapboxNavigation, value: "<%@", comment: "Format string for a short distance or time less than a minimum threshold; 1 = duration remaining"), hardcodedTime)

Sources/MapboxNavigation/CarPlayManager.swift

@@ -300,6 +300,26 @@ public class CarPlayManager: NSObject {
         return muteButton
     }()
 
+    /**
+     The bar button that brings alternative routes selection during navigation.
+     */
+    public lazy var alternativeRoutesButton: CPBarButton = {
+        let altsButton = CPBarButton(type: .text) { [weak self] (button: CPBarButton) in
+            guard let template = self?.carPlayNavigationViewController?.alternativesListTemplate() else {
+                return
+            }
+            self?.interfaceController?.pushTemplate(template,
+                                                    animated: true)
+        }
+        
+        altsButton.title = NSLocalizedString("CARPLAY_ALTERNATIVES",
+                                             bundle: .mapboxNavigation,
+                                             value: "Alternatives",
+                                             comment: "Title for alternatives selection list button")
+        
+        return altsButton
+    }()
+    
     /**
      The bar button that prompts the presented navigation view controller to display the feedback screen.
      */
@@ -989,7 +1009,7 @@ extension CarPlayManager: CPMapTemplateDelegate {
                                                          for: currentActivity) {
             mapTemplate.leadingNavigationBarButtons = leadingButtons
         } else {
-            mapTemplate.leadingNavigationBarButtons = [muteButton]
+            mapTemplate.leadingNavigationBarButtons = [muteButton, alternativeRoutesButton]
         }
 
         if let trailingButtons = delegate?.carPlayManager(self,

Sources/MapboxNavigation/CarPlayNavigationViewController.swift

@@ -6,6 +6,8 @@ import MapboxCoreNavigation
 #if canImport(CarPlay)
 import CarPlay
 
+let CarPlayAlternativeIDKey: String = "MBCarPlayAlternativeID"
+
 /**
  `CarPlayNavigationViewController` is a fully-featured turn-by-turn navigation UI for CarPlay.
 
@@ -88,6 +90,86 @@ open class CarPlayNavigationViewController: UIViewController, BuildingHighlighti
         navigationService.router.continuousAlternatives
     }
 
+    private func format(value: LocationDistance,
+                        labels: (decreasing: String, increasing: String, equal: String)) -> String {
+        switch value {
+        case ..<0:
+            return labels.decreasing
+        case 0:
+            return labels.equal
+        default:
+            return labels.increasing
+        }
+    }
+    
+    func alternativesListTemplate() -> CPListTemplate {
+        var variants: [CPListSection] = []
+        let distanceFormatter = DistanceFormatter()
+        self.continuousAlternatives.forEach { alternative in
+            guard let title = alternative.indexedRouteResponse.currentRoute?.description else {
+                return
+            }
+            distanceFormatter.measurementFormatter.numberFormatter.negativePrefix = ""
+            let distanceDeltaText = distanceFormatter.string(from: alternative.distanceDelta)
+            let distanceDelta = format(value: alternative.distanceDelta,
+                                       labels: (decreasing: String.localizedStringWithFormat(NSLocalizedString("SHORTER_ALTERNATIVE",
+                                                                                                               bundle: .mapboxNavigation,
+                                                                                                               value: "%@ shorter",
+                                                                                                               comment: "Alternatives selection note about a shorter route distance in any unit."),
+                                                                                             distanceDeltaText),
+                                                increasing: String.localizedStringWithFormat(NSLocalizedString("LONGER_ALTERNATIVE",
+                                                                                                               bundle: .mapboxNavigation,
+                                                                                                               value: "%@ longer",
+                                                                                                               comment: "Alternatives selection note about a longer route distance in any unit."),
+                                                                                             distanceDeltaText),
+                                                equal: NSLocalizedString("SAME_DISTANCE",
+                                                                         bundle: .mapboxNavigation,
+                                                                         value: "Same distance",
+                                                                         comment: "Alternatives selection note about equal travel distance.")))
+            let timeDeltaText = DateComponentsFormatter.travelTimeString(alternative.expectedTravelTimeDelta, signed: false, unitStyle: .full)
+            let timeDelta = format(value: alternative.expectedTravelTimeDelta,
+                                   labels: (decreasing: String.localizedStringWithFormat(NSLocalizedString("FASTER_ALTERNATIVE",
+                                                                                                           bundle: .mapboxNavigation,
+                                                                                                           value: "%@ faster",
+                                                                                                           comment: "Alternatives selection note about a faster route time interval in any unit."),
+                                                                                         timeDeltaText),
+                                            increasing: String.localizedStringWithFormat(NSLocalizedString("SLOWER_ALTERNATIVE",
+                                                                                                           bundle: .mapboxNavigation,
+                                                                                                           value: "%@ slower",
+                                                                                                           comment: "Alternatives selection note about a slower route time interval in any unit."),
+                                                                                         timeDeltaText),
+                                            equal: NSLocalizedString("SAME_TIME",
+                                                                     bundle: .mapboxNavigation,
+                                                                     value: "Same time",
+                                                                     comment: "Alternatives selection note about equal travel time.")))
+            
+            let items: [CPListItem] = [CPListItem(text: String.localizedStringWithFormat(NSLocalizedString("ALTERNATIVE_NOTES",
+                                                                                                           bundle: .mapboxNavigation,
+                                                                                                           value: "%1$@ / %2$@",
+                                                                                                           comment: "Combined alternatives selection notes about duration (first slot position) and distance (second slot position) delta."),
+                                                                                         timeDelta,
+                                                                                         distanceDelta),
+                                                  detailText: nil)]
+            items.forEach { (item: CPListItem) -> Void in
+                item.userInfo = [CarPlayAlternativeIDKey: alternative.id]
+            }
+            let section = CPListSection(items: items,
+                                        header: title,
+                                        sectionIndexTitle: nil)
+            variants.append(section)
+        }
+        
+        let alternativesTitle = NSLocalizedString("CARPLAY_ALTERNATIVES",
+                                                  bundle: .mapboxNavigation,
+                                                  value: "Alternatives",
+                                                  comment: "Title for alternatives selection list button")
+        
+        let template = CPListTemplate(title: alternativesTitle,
+                                      sections: variants)
+        template.delegate = self
+        return template
+    }
+    
     /**
      Controls whether night style will be used whenever traversing through a tunnel. Defaults to `true`.
      */
@@ -1019,4 +1101,28 @@ extension CarPlayNavigationViewController: CPSessionConfigurationDelegate {
         applyStyleIfNeeded(contentStyle)
     }
 }
+
+@available(iOS 12.0, *)
+extension CarPlayNavigationViewController: CPListTemplateDelegate {
+    
+    public func listTemplate(_ listTemplate: CPListTemplate,
+                      didSelect item: CPListItem,
+                      completionHandler: @escaping () -> Void) {
+        // Selected a list item for switching to alternative route.
+        guard let userInfo = item.userInfo as? CarPlayUserInfo,
+              let alternativeId = userInfo[CarPlayAlternativeIDKey] as? AlternativeRoute.ID,
+              let alternativeRoute = continuousAlternatives.first(where: { $0.id == alternativeId})?.indexedRouteResponse else {
+                  completionHandler()
+                  return
+              }
+        
+        navigationService.router.updateRoute(with: alternativeRoute,
+                                             routeOptions: nil,
+                                             completion: { _ in
+            self.carInterfaceController.popTemplate(animated: true)
+            completionHandler()
+        })
+    }
+}
+
 #endif

Sources/MapboxNavigation/DateComponentsFormatter+NavigationAdditions.swift

@@ -21,4 +21,26 @@ extension DateComponentsFormatter {
         formatter.allowedUnits = [.day, .hour, .minute]
         return formatter
     }()
+    
+    public static func travelDurationUnitStyle(interval: TimeInterval) -> DateComponentsFormatter.UnitsStyle {
+        return interval < 3600 ? .short : .abbreviated
+    }
+    
+    public static func travelTimeString(_ interval: TimeInterval,
+                                        signed: Bool,
+                                        unitStyle: DateComponentsFormatter.UnitsStyle?) -> String {
+        let formatter = DateComponentsFormatter()
+        formatter.unitsStyle = unitStyle ?? travelDurationUnitStyle(interval: interval)
+        let timeString = formatter.string(from: signed ? interval : abs(interval)) ?? ""
+        
+        if signed && interval >= 0 {
+                return String.localizedStringWithFormat(NSLocalizedString("EXPLICITLY_POSITIVE_NUMBER",
+                                                                          bundle: .mapboxNavigation,
+                                                                          value: "+%@",
+                                                                          comment: "Number string with an explicit '+' sign."),
+                                                        timeString)
+        } else {
+            return timeString
+        }
+    }
 }

Sources/MapboxNavigation/NavigationMapView+ContinuousAlternatives.swift

@@ -20,6 +20,8 @@ extension NavigationMapView {
 
         self.continuousAlternatives = continuousAlternatives
 
+        showContinuousAlternativeRoutesDurations()
+        
         guard let routes = self.routes,
               !routes.isEmpty else { return }
 
@@ -52,6 +54,8 @@ extension NavigationMapView {
         removeContinuousAlternativesRoutesLayers()
 
         continuousAlternatives = nil
+        
+        showContinuousAlternativeRoutesDurations()
     }
 
     /**