Navigation state should identify destinations rather than duplicate entire mutable models. A deep link, restored route and tapped row should converge on a coherent destination model.

User action or URL → Validated route → Navigation state → Destination
  1. 1User action or URL
  2. 2Validated route
  3. 3Navigation state
  4. 4Destination

Work through the example

Describe what happens when the requested item no longer exists. Test back navigation after search and restoration.

Start with a disposable branch and synthetic data. Write the expected outcome before changing the implementation, then keep the first failing result. This prevents a later repair from quietly redefining the task. The procedure below is grounded in the repository reference; its examples must still be checked against your project and installed toolchain.

Implementation reference

The following focused section is adapted from the maintained project guide. It preserves the source’s examples and limitations.

The primary navigation container (iOS 16+). Replaces the deprecated NavigationView.

struct ContentView: View {
    var body: some View {
        NavigationStack {
            List(items) { item in
                NavigationLink(item.title) {
                    DetailView(item: item)
                }
            }
            .navigationTitle("Items")
            .navigationBarTitleDisplayMode(.large) // .inline, .large, .automatic
            .toolbar {
                ToolbarItem(placement: .primaryAction) {
                    Button("Add", systemImage: "plus") { addItem() }
                }
            }
        }
    }
}

The preferred pattern -- decouples the link from its destination.

struct ContentView: View {
    var body: some View {
        NavigationStack {
            List {
                NavigationLink("Show Profile", value: Route.profile("user-123"))
                NavigationLink("Settings", value: Route.settings)

                ForEach(items) { item in
                    NavigationLink(value: item) {
                        ItemRow(item: item)
                    }
                }
            }
            .navigationDestination(for: Item.self) { item in
                ItemDetailView(item: item)
            }
            .navigationDestination(for: Route.self) { route in
                switch route {
                case .profile(let id):
                    ProfileView(userId: id)
                case .settings:
                    SettingsView()
                }
            }
        }
    }
}

enum Route: Hashable {
    case profile(String)
    case settings
    case detail(Item)
}

A type-erased path that supports heterogeneous value types.

@Observable
class Router {
    var path = NavigationPath()

    func goToProfile(_ id: String) {
        path.append(Route.profile(id))
    }

    func goToDetail(_ item: Item) {
        path.append(item)
    }

    func popToRoot() {
        path = NavigationPath()
    }

    func pop() {
        if !path.isEmpty {
            path.removeLast()
        }
    }
}

struct AppView: View {
    @State private var router = Router()

    var body: some View {
        NavigationStack(path: $router.path) {
            HomeView()
                .navigationDestination(for: Route.self) { route in
                    routeView(for: route)
                }
                .navigationDestination(for: Item.self) { item in
                    ItemDetailView(item: item)
                }
        }
        .environment(router)
    }

    @ViewBuilder
    func routeView(for route: Route) -> some View {
        switch route {
        case .profile(let id): ProfileView(userId: id)
        case .settings: SettingsView()
        case .detail(let item): ItemDetailView(item: item)
        }
    }
}

// Deep push from anywhere
struct SomeChildView: View {
    @Environment(Router.self) private var router

    var body: some View {
        Button("Go to Profile") {
            router.goToProfile("user-456")
        }
    }
}

Typed path (homogeneous)

@State private var path: [Item] = []

NavigationStack(path: $path) {
    List(items) { item in
        NavigationLink(value: item) { Text(item.title) }
    }
    .navigationDestination(for: Item.self) { item in
        DetailView(item: item)
    }
}

Acceptance and failure review

Checkpoint What to inspect If it does not match
User action or URL Confirm the input and environment Preserve the failure and return to this step
Validated route Inspect the intermediate artifact Preserve the failure and return to this step
Navigation state Run the focused check Preserve the failure and return to this step
Destination Record the observed result Preserve the failure and return to this step

Ask the agent to explain the smallest change that resolves the observed mismatch. Keep unrelated refactors out of the repair. A change that makes a warning disappear is not enough if the behavior or ownership contract has changed. Re-run the same acceptance check so the before and after results are comparable.

Evidence and limits

The source guide supplies patterns; no blanket claim is made that a navigation review catches every routing bug.

This is an educational guide. Its presence in the series does not certify a completed client-specific lab. The series evidence record separates executed checks from exercises and blocked environments.

Inspect the source used in this lesson.

What to do next

Next: Adding widgets with App Intents: a timeline and verification plan