Navigator Navigation Framework

For scenarios where you want to avoid the 'magic' of automatic lookup and prefer explicit dependency injection, you can use the NavigationViewProviding protocol.

1. Define a protocol that requires a property conforming to NavigationViewProviding<D> where D is your destination type.
2. The application implements this protocol, returning a NavigationViewProvider that maps destinations to views.
3. The consuming module accesses the view via the injected provider.

// 1. Define the requirement in the module
public protocol HomeDependencies {
    @MainActor var homeExternalViewProvider: any NavigationViewProviding<HomeExternalViews> { get }
}

// 2. The destination type
nonisolated public enum HomeExternalViews: NavigationViews {
    case external
}

// 3. The Application provides the implementation
public class AppResolver: HomeDependencies {
    @MainActor public var homeExternalViewProvider: any NavigationViewProviding<HomeExternalViews> {
        NavigationViewProvider { destination in
            switch destination {
            case .external: SettingsDestinations.external
            }
        }
    }
}

// 4. The module consumes it
@Environment(\.homeDependencies) var resolver
// ...
resolver.homeExternalViewProvider.view(for: .external)

You can use NavigationDestination to bridge dependencies between modules. A feature module can define a requirement for an external view via its dependency resolver, while the main application (which has access to all modules) provides the actual implementation.

1. Feature Module: Defines a dependency protocol and a NavigationDestination that calls a method on that protocol.
2. App Layer: Implements the protocol by reaching into other modules and returning their views (often using .asAnyView()).

// 1. Feature module defines the requirement
private struct HomeDestinationsView: View {
    let destination: HomeDestinations
    @Environment(\.homeDependencies) var resolver
    var body: some View {
        switch self {
        case .external:
            resolver.externalView() // Calls the protocol method
        ... 
        }
    }
}

// 2. App layer implements the cross-module bridge
class AppResolver: AppDependencies {
    @MainActor func externalView() -> AnyView {
        // Reach out to the settings module to provide the view
        SettingsDestinations.external.asAnyView()
    }
}

To maintain strict modularity, you can expose a module's feature views through a NavigationDestination enum. This allows other modules to use the feature's views without having a direct dependency on the views themselves or knowing how they are constructed.

Other modules only interact with the NavigationDestination enum. This pattern, combined with Navigator's ability to avoid explicit navigationDestination registrations, allows for seamless cross-module navigation.

// In the Order Module
public enum OrderDestinations: NavigationDestination {
    case orderSummaryCard(Order)
    case order(Item)
    case listPastOrders

    public var body: some View {
        OrderDestinationsView(destination: self)
    }
}

// In a consuming module
struct CustomView: View {
    @State var order: Order
    var body: some View {
        VStack {
            // The consumer uses the enum case as a view without knowing the underlying View type
            OrderDestinations.orderSummaryCard(order)
        }
    }
}

Use the NavigationFlow protocol to manage complex, multi-step sequences like onboarding wizards or multi-step forms. A flow is a struct that acts as both the state container (holding data collected during the sequence) and the state machine (deciding the next step).

To implement a flow, you must define:

1. An associated Destination: NavigationDestination enum where each case carries the current flow state.
2. A checkpoint property of type NavigationFlowCheckpoint<Value>? to manage return points.
3. A start() method to define the first step.
4. A next() method (async throws) that inspects the current state and returns a FlowResult.

Because flows are structs, they use value semantics. Each step receives a copy of the flow, mutates it, and passes the updated copy back to the navigator.

@MainActor
public protocol NavigationFlow: Hashable {
    associatedtype Destination: NavigationDestination
    associatedtype Value

    var checkpoint: NavigationFlowCheckpoint<Value>? { get set }

    func start() -> FlowResult<Self>
    func next() async throws -> FlowResult<Self>

    func onComplete()
    func onComplete(_ value: Value)
    func onCancel()
    func onError(_ error: Error)
}

Navigator organizes navigation through a hierarchical tree of Navigator instances.

• ManagedNavigationStack: Each instance creates its own Navigator and installs it into the SwiftUI environment. This allows views contained within that stack to access the specific navigator responsible for that stack.
• Roots: The application typically starts with a 'root' Navigator configured at the app level. This root passes configuration to its children and enables communication across different branches (e.g., between tabs).
• Hierarchy: When a new ManagedNavigationStack or ManagedPresentationView is created, it retrieves the current Navigator from the environment and sets it as its 'parent', effectively growing the tree.

This tree structure allows independent navigation contexts. For example, in a TabView, each tab has its own ManagedNavigationStack and its own Navigator. A view in Tab 2 will only affect Tab 2's stack because it communicates with Tab 2's specific navigator, not the root or Tab 3's navigator.

// Example of a root Navigator configuration
func applicationNavigator() -> Navigator {
    let configuration: NavigationConfiguration = .init(
        restorationKey: nil,
        executionDelay: 0.4,
        verbosity: .info
    )
    return Navigator(configuration: configuration)
}