Let hosts embed TripPlannerView in their own navigation

CLAUDE.md

@@ -45,7 +45,7 @@ Optional pre-push hooks via pre-commit (`pre-commit install --hook-type pre-push
 2. An `APIService` implementation.
 3. An `OTPMapProvider` implementation.
 
-`TripPlanner` internally wires up `MapCoordinator` and `TripPlannerViewModel`, and `createTripPlannerView(origin:destination:viaPoint:transportMode:onClose:)` returns the SwiftUI UI (`TripPlannerView`), which the demo hosts in a `PanelHostingController` bottom sheet. Cross-object events flow through `NotificationCenter` (injectable; see `Core/Notifications.swift`).
+`TripPlanner` internally wires up `MapCoordinator` and `TripPlannerViewModel`, and `createTripPlannerView(origin:destination:viaPoint:transportMode:chrome:onClose:)` returns the SwiftUI UI (`TripPlannerView`), which the demo hosts in a `PanelHostingController` bottom sheet. `chrome` (`TripPlannerChrome`) decides whether the planner supplies its own `NavigationStack`, title and close button (`.standalone`, the default) or renders the body alone inside navigation the host owns (`.embedded`); an embedded host owns dismissal, leaves `onClose` nil, and calls `TripPlanner.reset()` when it dismisses. Cross-object events flow through `NotificationCenter` (injectable; see `Core/Notifications.swift`).
 
 ### The map is inversion-of-control
 

OTPKit/Sources/OTPKit/Presentation/TripPlanner.swift

@@ -26,11 +26,15 @@ public class TripPlanner {
     /// Map provider for operations
     private let mapProvider: OTPMapProvider
 
-    private let mapCoordinator: MapCoordinator
+    /// Internal rather than private so tests can observe the state `reset()` clears.
+    /// Not part of the public API.
+    let mapCoordinator: MapCoordinator
 
     private let notificationCenter: NotificationCenter
 
-    private let viewModel: TripPlannerViewModel
+    /// Internal rather than private so tests can observe the state `reset()` clears.
+    /// Not part of the public API.
+    let viewModel: TripPlannerViewModel
 
     // MARK: - Initialization
 
@@ -67,26 +71,34 @@ public class TripPlanner {
     /// Creates the trip planner UI, optionally prefilled.
     ///
     /// - Parameters:
-    ///   - origin: Prefilled origin location.
-    ///   - destination: Prefilled destination location.
+    ///   - origin: Prefilled origin location. Nil leaves any existing selection alone.
+    ///   - destination: Prefilled destination location. Nil leaves any existing
+    ///     selection alone.
     ///   - viaPoint: An intermediate coordinate every planned trip must pass through —
     ///     the "plan a trip using this bike" entry point passes the vehicle's location.
     ///     Note: OTP servers may require a transit mode in the request to route through
     ///     a via point, so pair this with `.transitBikeRental` rather than `.bikeRental`.
     ///   - transportMode: Preselected transport mode. Ignored when the injected API
     ///     service cannot support it (e.g. rental modes on an OTP 1.x REST backend).
-    ///   - onClose: Called when the rider dismisses the planner.
+    ///   - chrome: Whether the planner supplies its own navigation container, title
+    ///     and close button. Pass `.embedded` when presenting inside navigation the
+    ///     host already owns, and call `reset()` when dismissing.
+    ///   - onClose: Called when the rider dismisses the planner. Leave it nil when
+    ///     `chrome` is `.embedded`, which renders no close button and so can never
+    ///     call it.
     public func createTripPlannerView(
         origin: Location? = nil,
         destination: Location? = nil,
         viaPoint: CLLocationCoordinate2D? = nil,
         transportMode: TransportMode? = nil,
-        onClose: @escaping VoidBlock
+        chrome: TripPlannerChrome = .standalone,
+        onClose: VoidBlock? = nil
     ) -> some View {
         // The prefill is all-or-nothing: a via point paired with an unsupported mode
         // must not be applied alone, or the planner would route the rider through a
         // rental vehicle's location in a mode that can't use it. Nil parameters
-        // leave existing state untouched, so re-invoking the factory is harmless.
+        // leave existing state untouched — here and in `TripPlannerView.init` — so
+        // re-invoking the factory is harmless.
         let modeIsAvailable = transportMode.map { viewModel.availableTransportModes.contains($0) } ?? true
         if modeIsAvailable {
             if let transportMode {
@@ -102,12 +114,29 @@ public class TripPlanner {
             viewModel: viewModel,
             mapCoordinator: mapCoordinator,
             origin: origin,
-            destination: destination, onClose: onClose)
+            destination: destination,
+            chrome: chrome,
+            onClose: onClose)
 
         return view
             .environment(\.otpTheme, viewModel.config.themeConfiguration)
             .environment(\.otpSearchRegion, viewModel.config.searchRegion)
             .environmentObject(mapCoordinator)
             .environmentObject(viewModel)
     }
+
+    /// Clears planned trip state and anything drawn for it on the map: the selected
+    /// origin, destination and via point, the plan response and selected itinerary,
+    /// any error, and the route and location annotations on the map. Trip options and
+    /// the transport mode return to their defaults.
+    ///
+    /// The `.standalone` close button does this on the rider's behalf. A host using
+    /// `.embedded` chrome owns the close control instead, so it has to call this as
+    /// it dismisses — otherwise the next presentation reopens on the previous trip.
+    ///
+    /// Call it at the point of dismissal, not from `onDisappear`, which also fires
+    /// when the host pushes another screen or the app is backgrounded.
+    public func reset() {
+        viewModel.resetTripPlanner()
+    }
 }

OTPKit/Sources/OTPKit/Presentation/TripPlanner/TripPlannerChrome.swift

@@ -0,0 +1,37 @@
+//
+//  TripPlannerChrome.swift
+//  OTPKit
+//
+
+import Foundation
+
+/// How `TripPlannerView` frames its own content.
+public enum TripPlannerChrome: Sendable, Equatable {
+    /// Wrap the planner in its own `NavigationStack`, navigation title and close
+    /// button. Suits a full-screen or modally presented planner, and is the default
+    /// so existing integrations are unaffected.
+    case standalone
+
+    /// Render the planner body alone, leaving the navigation container, title and
+    /// close affordance to the host.
+    ///
+    /// For hosts that present the planner inside navigation they already own — a
+    /// sheet in their own stack, say — where `standalone` would produce two headers
+    /// and two close buttons. The host owns dismissal in this mode, so `onClose` is
+    /// never invoked: the control that would call it belongs to the host. Leave
+    /// `onClose` nil rather than passing a closure that cannot fire.
+    ///
+    /// The host also inherits the cleanup the close button used to perform, so call
+    /// `TripPlanner.reset()` at the point of dismissal — not on view disappearance,
+    /// which also fires when the host pushes another screen or backgrounds the app:
+    ///
+    /// ```swift
+    /// .sheet(isPresented: $showingPlanner, onDismiss: { planner.reset() }) {
+    ///     NavigationStack {
+    ///         planner.createTripPlannerView(chrome: .embedded)
+    ///             .navigationTitle("Plan a trip")
+    ///     }
+    /// }
+    /// ```
+    case embedded
+}

OTPKit/Sources/OTPKit/Presentation/TripPlanner/TripPlannerView.swift

@@ -9,7 +9,9 @@ import SwiftUI
 import MapKit
 
 /// Main view for planning trips, showing controls and results.
-/// Full-screen interface with navigation bar, top controls, and inline results.
+///
+/// Supplies its own navigation chrome by default; pass `chrome: .embedded` to render
+/// the body alone inside a host's own navigation.
 public struct TripPlannerView: View {
     /// ViewModel managing trip planning state and logic
     @StateObject private var tripPlannerVM: TripPlannerViewModel
@@ -22,71 +24,52 @@ public struct TripPlannerView: View {
 
     @State private var directionSheetDetent: PresentationDetent = DirectionsSheetView.tipDetent
 
-    private let onClose: VoidBlock
+    /// Whether this view supplies its own navigation container and close button.
+    private let chrome: TripPlannerChrome
+
+    private let onClose: VoidBlock?
 
     /// Initializes the TripPlannerView with a map provider, configuration, and optional locations
     /// This is the main entry point for using OTPKit
     /// - Parameters:
     ///   - viewModel: The TripPlannerViewModel
     ///   - mapCoordinator: The MapCoordinator object
-    ///   - origin: Optional starting location (if nil, current location will be used)
-    ///   - destination: Optional destination location
-    ///   - onClose: A callback invoked when the close button is tapped.
+    ///   - origin: Prefilled starting location. Nil leaves any existing selection
+    ///     alone; the view falls back to the current location only when nothing is
+    ///     selected yet.
+    ///   - destination: Prefilled destination location. Nil leaves any existing
+    ///     selection alone.
+    ///   - chrome: Whether the view supplies its own navigation container, title and
+    ///     close button. Defaults to `.standalone`.
+    ///   - onClose: A callback invoked when the close button is tapped. Leave it nil
+    ///     when `chrome` is `.embedded`, which renders no close button and so can
+    ///     never call it.
     public init(
         viewModel: TripPlannerViewModel,
         mapCoordinator: MapCoordinator,
         origin: Location? = nil,
         destination: Location? = nil,
-        onClose: @escaping VoidBlock
+        chrome: TripPlannerChrome = .standalone,
+        onClose: VoidBlock? = nil
     ) {
-        viewModel.selectedOrigin = origin
-        viewModel.selectedDestination = destination
+        // Only a supplied value is applied. Assigning nil here would clear the
+        // rider's selection every time the host rebuilt the view, which SwiftUI
+        // hosts do freely; `TripPlanner.reset()` is the way to clear on purpose.
+        if let origin {
+            viewModel.selectedOrigin = origin
+        }
+        if let destination {
+            viewModel.selectedDestination = destination
+        }
 
         self._tripPlannerVM = StateObject(wrappedValue: viewModel)
         self._mapCoordinator = StateObject(wrappedValue: mapCoordinator)
+        self.chrome = chrome
         self.onClose = onClose
     }
 
     public var body: some View {
-        NavigationStack {
-            ScrollView(.vertical, showsIndicators: false) {
-                LazyVStack(spacing: 0, pinnedViews: []) {
-                    // Top controls for location selection and trip planning
-                    TopControlsOverlay(selectedMode: $selectedMode)
-                        .padding(.bottom, 24)
-
-                    // Trip results (shown inline when available)
-                    if !tripPlannerVM.itineraries.isEmpty {
-                        tripResultsSection
-                            .transition(.asymmetric(
-                                insertion: .move(edge: .top).combined(with: .opacity),
-                                removal: .opacity
-                            ))
-                    }
-
-                    // Bottom spacer for proper scrolling and safe area
-                    Spacer(minLength: 120)
-                }
-                .padding(.top, 8)
-            }
-            .scrollDismissesKeyboard(.interactively)
-            .navigationTitle(OTPLoc("trip_planner.title", comment: "Title of the trip planning screen"))
-            .toolbarTitleDisplayMode(.inlineLarge)
-            .toolbar {
-                ToolbarItem(placement: .topBarTrailing) {
-                    Button(OTPLoc("common.close", comment: "Close button"), systemImage: "xmark") {
-                        tripPlannerVM.resetTripPlanner()
-                        self.onClose()
-                    }
-                }
-            }
-            .overlay {
-                // Loading overlay
-                if tripPlannerVM.isLoading {
-                    LoadingOverlay()
-                }
-            }
-        }
+        framedContent
         .task {
             // Auto-set current location as origin if no origin is provided
             if tripPlannerVM.selectedOrigin == nil {
@@ -105,6 +88,70 @@ public struct TripPlannerView: View {
         .environmentObject(tripPlannerVM)
     }
 
+    // MARK: - Layout
+
+    /// The planner body, identical in both chrome modes. Navigation-scoped modifiers
+    /// stay out of here: an `.embedded` planner sits inside the host's own
+    /// `NavigationStack`, where `navigationTitle` and `toolbar` would take effect and
+    /// overwrite the host's title and bar items. They belong to `.standalone`, which
+    /// supplies the container they are meant to configure.
+    private var plannerContent: some View {
+        ScrollView(.vertical, showsIndicators: false) {
+            LazyVStack(spacing: 0, pinnedViews: []) {
+                // Top controls for location selection and trip planning
+                TopControlsOverlay(selectedMode: $selectedMode)
+                    .padding(.bottom, 24)
+
+                // Trip results (shown inline when available)
+                if !tripPlannerVM.itineraries.isEmpty {
+                    tripResultsSection
+                        .transition(.asymmetric(
+                            insertion: .move(edge: .top).combined(with: .opacity),
+                            removal: .opacity
+                        ))
+                }
+
+                // Bottom spacer for proper scrolling and safe area
+                Spacer(minLength: 120)
+            }
+            .padding(.top, 8)
+        }
+        .scrollDismissesKeyboard(.interactively)
+        .overlay {
+            // Loading overlay
+            if tripPlannerVM.isLoading {
+                LoadingOverlay()
+            }
+        }
+    }
+
+    @ViewBuilder
+    private var framedContent: some View {
+        switch chrome {
+        case .standalone:
+            NavigationStack {
+                plannerContent
+                    .navigationTitle(OTPLoc("trip_planner.title", comment: "Title of the trip planning screen"))
+                    .toolbarTitleDisplayMode(.inlineLarge)
+                    .toolbar {
+                        // Only when there is somewhere to go. `onClose` is optional for
+                        // `.embedded`, and a close button that resets the trip and then
+                        // does nothing would leave the rider staring at a blank planner.
+                        if let onClose {
+                            ToolbarItem(placement: .topBarTrailing) {
+                                Button(OTPLoc("common.close", comment: "Close button"), systemImage: "xmark") {
+                                    tripPlannerVM.resetTripPlanner()
+                                    onClose()
+                                }
+                            }
+                        }
+                    }
+            }
+        case .embedded:
+            plannerContent
+        }
+    }
+
     // MARK: - Trip Results Section
 
     private var tripResultsSection: some View {