Use full struct NavigationProgress in Viewport state (#10608)

kried · volkdmitri · commit 893a152164f8 · 2025-10-10T12:47:11.000+02:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -4,13 +4,18 @@
 
 ### API Deprecations
 
+* `ViewportState.routeProgress` is deprecated and is always `nil` now. Use `ViewportState.navigationProgress` instead.
 * `ViewportState.heading` is deprecated and is always `nil` now. Use `ViewportState.navigationHeading` instead.
 * `ViewportState.location` is deprecated in favor of `ViewportState.navigationLocation` instead.
-* `ViewportState.init(location:routeProgress:viewportPadding:heading:)` is deprecated in favor of `ViewportState.init(navigationLocation:routeProgress:viewportPadding:navigationHeading:)`.
+* `ViewportState.init(location:routeProgress:viewportPadding:heading:)` is deprecated in favor of `ViewportState.init(navigationLocation:navigationProgress:viewportPadding:navigationHeading:)`.
+
+### Navigation Camera
+
+* When implementing a custom `ViewportDataSource` for the navigation camera, migrate to `viewportState.navigationProgress` for tracking active guidance progress.
 
 ### Other changes
 
-* Fixed a possible race condition in `NavigationCamera` state `CLHeading` updates.
+* Fixed a possible race condition in `NavigationCamera` state updates.
 * Fixed memory leaks caused by `Task.detached` usage in `NavigationController`.
 * Fixed memory leaks in `NWPathMonitor` caused by a non-stopped monitor.
 * Removed excessive `Sendable` conformance for types from Turf and Maps.
diff --git a/Examples/AdditionalExamples/Examples/NavigationCamera/CustomViewportDataSource.swift b/Examples/AdditionalExamples/Examples/NavigationCamera/CustomViewportDataSource.swift
@@ -68,7 +68,7 @@ class CustomViewportDataSource: ViewportDataSource {
             pitch: 0.0
         )
 
-        if let shape = state.routeProgress?.route.shape, let cameraOptions = try? mapView.mapboxMap.camera(
+        if let shape = state.navigationProgress?.route.shape, let cameraOptions = try? mapView.mapboxMap.camera(
             for: shape.coordinates.compactMap { $0 },
             camera: initialCameraOptions,
             coordinatesPadding: UIEdgeInsets(
diff --git a/Sources/MapboxNavigationCore/Map/Camera/NavigationCamera.swift b/Sources/MapboxNavigationCore/Map/Camera/NavigationCamera.swift
@@ -16,7 +16,7 @@ public class NavigationCamera {
         var cameraState: NavigationCameraState = .idle
         var location: NavigationLocation?
         var navigationHeading: NavigationHeading?
-        var routeProgress: RouteProgress?
+        var navigationProgress: NavigationProgress?
         var viewportPadding: UIEdgeInsets = .zero
     }
 
@@ -92,7 +92,7 @@ public class NavigationCamera {
                     self.viewportDataSource.update(
                         using: ViewportState(
                             navigationLocation: location,
-                            routeProgress: newState.routeProgress,
+                            navigationProgress: newState.navigationProgress,
                             viewportPadding: viewportPadding,
                             navigationHeading: newState.navigationHeading
                         )
@@ -143,7 +143,7 @@ public class NavigationCamera {
         routeProgress
             .receive(on: DispatchQueue.main)
             .sink { [weak self] in
-                self?.state.routeProgress = $0
+                self?.state.navigationProgress = $0.map(NavigationProgress.init)
             }.store(in: &lifetimeSubscriptions)
     }
 
diff --git a/Sources/MapboxNavigationCore/Map/Camera/NavigationProgress.swift b/Sources/MapboxNavigationCore/Map/Camera/NavigationProgress.swift
@@ -0,0 +1,78 @@
+import CoreLocation
+import MapboxDirections
+
+/// ``NavigationProgress`` stores the user’s progress along a route.
+public struct NavigationProgress: RouteProgressRepresentable, Equatable, Sendable {
+    /// Returns the current main `Route`.
+    public let route: Route
+    /// Returns the id of the current main `Route`.
+    public let routeId: RouteId
+
+    /// Returns the progress along the current ``RouteLeg``.
+    public let currentLegProgress: RouteLegProgress
+    /// Total distance traveled by user along all legs.
+    public let distanceTraveled: CLLocationDistance
+    /// Number between 0 and 1 representing how far along the `Route` the user has traveled.
+    public let fractionTraveled: Double
+    /// Total seconds remaining on all legs.
+    public let durationRemaining: TimeInterval
+    /// Total distance remaining in meters along route.
+    public let distanceRemaining: CLLocationDistance
+    /// Index representing current ``RouteLeg``.
+    public let legIndex: Int
+    /// Index relative to route shape, representing the point the user is currently located at.
+    public let shapeIndex: Int
+    /// The waypoints of the route.
+    public let waypoints: [Waypoint]
+
+    /// Initializes a new ``NavigationProgress``.
+    /// - Parameters:
+    ///   - route: The current main `Route`.
+    ///   - routeId: The id of the current main `Route`.
+    ///   - currentLegProgress: The progress along the current ``RouteLeg``.
+    ///   - distanceTraveled: Total distance traveled by user along all legs.
+    ///   - fractionTraveled: Number between 0 and 1 representing how far along the `Route` the user has traveled.
+    ///   - durationRemaining: Total seconds remaining on all legs.
+    ///   - distanceRemaining: Total distance remaining in meters along route.
+    ///   - legIndex: Index representing current ``RouteLeg``.
+    ///   - shapeIndex: Index relative to route shape, representing the point the user is currently located at.
+    ///   - waypoints: The waypoints of the route.
+    public init(
+        route: Route,
+        routeId: RouteId,
+        currentLegProgress: RouteLegProgress,
+        distanceTraveled: CLLocationDistance,
+        fractionTraveled: Double,
+        durationRemaining: TimeInterval,
+        distanceRemaining: CLLocationDistance,
+        legIndex: Int,
+        shapeIndex: Int,
+        waypoints: [Waypoint]
+    ) {
+        self.route = route
+        self.routeId = routeId
+        self.currentLegProgress = currentLegProgress
+        self.distanceTraveled = distanceTraveled
+        self.fractionTraveled = fractionTraveled
+        self.durationRemaining = durationRemaining
+        self.distanceRemaining = distanceRemaining
+        self.legIndex = legIndex
+        self.shapeIndex = shapeIndex
+        self.waypoints = waypoints
+    }
+}
+
+extension NavigationProgress {
+    init(_ routeProgress: RouteProgress) {
+        self.route = routeProgress.route
+        self.routeId = routeProgress.navigationRoutes.mainRoute.routeId
+        self.currentLegProgress = routeProgress.currentLegProgress
+        self.distanceTraveled = routeProgress.distanceTraveled
+        self.fractionTraveled = routeProgress.fractionTraveled
+        self.distanceRemaining = routeProgress.distanceRemaining
+        self.durationRemaining = routeProgress.durationRemaining
+        self.legIndex = routeProgress.legIndex
+        self.shapeIndex = routeProgress.shapeIndex
+        self.waypoints = routeProgress.waypoints
+    }
+}
diff --git a/Sources/MapboxNavigationCore/Map/Camera/ViewportDataSource/CommonViewportDataSource.swift b/Sources/MapboxNavigationCore/Map/Camera/ViewportDataSource/CommonViewportDataSource.swift
@@ -78,7 +78,7 @@ class CommonViewportDataSource {
                 let parameters = provider.parameters(
                     with: viewportState.navigationLocation,
                     navigationHeading: viewportState.navigationHeading,
-                    routeProgress: viewportState.routeProgress,
+                    navigationProgress: viewportState.navigationProgress,
                     viewportPadding: viewportState.viewportPadding,
                     options: options
                 )
diff --git a/Sources/MapboxNavigationCore/Map/Camera/ViewportDataSource/ViewportDataSource.swift b/Sources/MapboxNavigationCore/Map/Camera/ViewportDataSource/ViewportDataSource.swift
@@ -8,7 +8,7 @@ public struct ViewportState: Equatable, Sendable {
     /// The current location of the user.
     public let navigationLocation: NavigationLocation
     /// The navigation route progress.
-    public let routeProgress: RouteProgress?
+    public let navigationProgress: NavigationProgress?
     /// The padding applied to the viewport.
     public let viewportPadding: UIEdgeInsets
     /// The current user heading.
@@ -17,17 +17,17 @@ public struct ViewportState: Equatable, Sendable {
     /// Initializes a new ``ViewportState`` instance.
     /// - Parameters:
     ///   - navigationLocation: The current location of the user.
-    ///   - routeProgress: The navigation route progress. Pass `nil` in case of no active navigation at the moment.
+    ///   - navigationProgress: The navigation route progress. Pass `nil` in case of no active navigation at the moment.
     ///   - viewportPadding: The padding applied to the viewport.
     ///   - navigationHeading: The current user heading.
     public init(
         navigationLocation: NavigationLocation,
-        routeProgress: RouteProgress?,
+        navigationProgress: NavigationProgress?,
         viewportPadding: UIEdgeInsets,
         navigationHeading: NavigationHeading?
     ) {
         self.navigationLocation = navigationLocation
-        self.routeProgress = routeProgress
+        self.navigationProgress = navigationProgress
         self.viewportPadding = viewportPadding
         self.navigationHeading = navigationHeading
     }
@@ -41,7 +41,7 @@ public struct ViewportState: Equatable, Sendable {
     @available(
         *,
         deprecated,
-        message: "Use `init(navigationLocation:routeProgress:viewportPadding:navigationHeading:)` instead"
+        message: "Use `init(navigationLocation:navigationProgress:viewportPadding:navigationHeading:)` instead"
     )
     public init(
         location: CLLocation,
@@ -50,7 +50,7 @@ public struct ViewportState: Equatable, Sendable {
         heading: CLHeading?
     ) {
         self.navigationLocation = NavigationLocation(location)
-        self.routeProgress = routeProgress
+        self.navigationProgress = routeProgress.map(NavigationProgress.init)
         self.viewportPadding = viewportPadding
         self.navigationHeading = heading.map(NavigationHeading.init)
     }
@@ -66,6 +66,10 @@ extension ViewportState {
     public var location: CLLocation {
         navigationLocation.clLocation
     }
+
+    /// The navigation route progress. Use ``navigationProgress`` instead. Always returns `nil`.
+    @available(*, deprecated, message: "Use `navigationProgress` instead")
+    public var routeProgress: RouteProgress? { return nil }
 }
 
 /// The protocol, which is used to fill and store ``NavigationCameraOptions`` which will be used by ``NavigationCamera``
diff --git a/Sources/MapboxNavigationCore/Map/Camera/ViewportParametersProvider.swift b/Sources/MapboxNavigationCore/Map/Camera/ViewportParametersProvider.swift
@@ -7,18 +7,18 @@ struct ViewportParametersProvider: Sendable {
     func parameters(
         with navigationLocation: NavigationLocation?,
         navigationHeading: NavigationHeading?,
-        routeProgress: RouteProgress?,
+        navigationProgress: NavigationProgress?,
         viewportPadding: UIEdgeInsets,
         options: NavigationViewportDataSourceOptions
     ) -> ViewportDataSourceState {
-        if let routeProgress {
+        if let navigationProgress {
             let intersectionDensity = options.followingCameraOptions.intersectionDensity
-            let stepIndex = routeProgress.currentLegProgress.stepIndex
-            let nextStepIndex = min(stepIndex + 1, routeProgress.currentLeg.steps.count - 1)
+            let stepIndex = navigationProgress.currentLegProgress.stepIndex
+            let nextStepIndex = min(stepIndex + 1, navigationProgress.currentLeg.steps.count - 1)
 
-            var remainingCoordinatesOnRoute = routeProgress.currentLegProgress.currentStepProgress
+            var remainingCoordinatesOnRoute = navigationProgress.currentLegProgress.currentStepProgress
                 .remainingStepCoordinates()
-            routeProgress.currentLeg.steps[nextStepIndex...]
+            navigationProgress.currentLeg.steps[nextStepIndex...]
                 .lazy
                 .compactMap { $0.shape?.coordinates }
                 .forEach { stepCoordinates in
@@ -30,15 +30,19 @@ struct ViewportParametersProvider: Sendable {
                 navigationHeading: navigationHeading,
                 navigationState: .active(
                     .init(
-                        coordinatesToManeuver: routeProgress.currentLegProgress.currentStepProgress
+                        coordinatesToManeuver: navigationProgress.currentLegProgress.currentStepProgress
                             .remainingStepCoordinates(),
-                        lookaheadDistance: lookaheadDistance(routeProgress, intersectionDensity: intersectionDensity),
-                        currentLegStepIndex: routeProgress.currentLegProgress.stepIndex,
-                        currentLegSteps: routeProgress.currentLeg.steps,
-                        isRouteComplete: routeProgress.routeIsComplete == true,
+                        lookaheadDistance: lookaheadDistance(
+                            navigationProgress,
+                            intersectionDensity: intersectionDensity
+                        ),
+                        currentLegStepIndex: navigationProgress.currentLegProgress.stepIndex,
+                        currentLegSteps: navigationProgress.currentLeg.steps,
+                        isRouteComplete: navigationProgress.routeIsComplete == true,
                         remainingCoordinatesOnRoute: remainingCoordinatesOnRoute,
-                        transportType: routeProgress.currentLegProgress.currentStep.transportType,
-                        distanceRemainingOnStep: routeProgress.currentLegProgress.currentStepProgress.distanceRemaining
+                        transportType: navigationProgress.currentLegProgress.currentStep.transportType,
+                        distanceRemainingOnStep: navigationProgress.currentLegProgress.currentStepProgress
+                            .distanceRemaining
                     )
                 ),
                 viewportPadding: viewportPadding
@@ -60,10 +64,10 @@ struct ViewportParametersProvider: Sendable {
     ///   - intersectionDensity: Lookahead distance
     /// - Returns: The lookahead distance.
     private func lookaheadDistance(
-        _ routeProgress: RouteProgress,
+        _ navigationProgress: NavigationProgress,
         intersectionDensity: IntersectionDensity
     ) -> CLLocationDistance {
-        let averageIntersectionDistances = routeProgress.route.legs.map { leg -> [CLLocationDistance] in
+        let averageIntersectionDistances = navigationProgress.route.legs.map { leg -> [CLLocationDistance] in
             return leg.steps.map { step -> CLLocationDistance in
                 if let firstStepCoordinate = step.shape?.coordinates.first,
                    let lastStepCoordinate = step.shape?.coordinates.last
@@ -90,8 +94,8 @@ struct ViewportParametersProvider: Sendable {
 
         let averageDistanceMultiplier = intersectionDensity.enabled ? intersectionDensity
             .averageDistanceMultiplier : 1.0
-        let currentRouteLegIndex = routeProgress.legIndex
-        let currentRouteStepIndex = routeProgress.currentLegProgress.stepIndex
+        let currentRouteLegIndex = navigationProgress.legIndex
+        let currentRouteStepIndex = navigationProgress.currentLegProgress.stepIndex
         let lookaheadDistance = averageIntersectionDistances[currentRouteLegIndex][currentRouteStepIndex] *
             averageDistanceMultiplier
 
diff --git a/Sources/MapboxNavigationCore/Navigator/RouteProgress/RouteProgress.swift b/Sources/MapboxNavigationCore/Navigator/RouteProgress/RouteProgress.swift

Original file line number	Diff line number	Diff line change
`@@ -68,7 +68,7 @@ class CustomViewportDataSource: ViewportDataSource {`
`68`	`68`	`pitch: 0.0`
`69`	`69`	`)`
`70`	`70`
`71`		`- if let shape = state.routeProgress?.route.shape, let cameraOptions = try? mapView.mapboxMap.camera(`
	`71`	`+ if let shape = state.navigationProgress?.route.shape, let cameraOptions = try? mapView.mapboxMap.camera(`
`72`	`72`	`for: shape.coordinates.compactMap { $0 },`
`73`	`73`	`camera: initialCameraOptions,`
`74`	`74`	`coordinatesPadding: UIEdgeInsets(`
Original file line number	Diff line number	Diff line change
`@@ -78,7 +78,7 @@ class CommonViewportDataSource {`
`78`	`78`	`let parameters = provider.parameters(`
`79`	`79`	`with: viewportState.navigationLocation,`
`80`	`80`	`navigationHeading: viewportState.navigationHeading,`
`81`		`- routeProgress: viewportState.routeProgress,`
	`81`	`+ navigationProgress: viewportState.navigationProgress,`
`82`	`82`	`viewportPadding: viewportState.viewportPadding,`
`83`	`83`	`options: options`
`84`	`84`	`)`