sRouting Development

Defines route enums, configures coordinators, and wires NavigationStack-based navigation for SwiftUI apps using the sRouting framework.

Architecture Overview

graph TD
    subgraph View_Layer
        V["SwiftUI View"]
        VM["ViewModifier (.onRouting, .routeObserver)"]
    end

    subgraph Logic_Layer
        SRR["SRRouter<Route>"]
        SRC["SRContext (Global)"]
    end

    subgraph State_Layer
        COORD["@sRouteCoordinator"]
        EMIT["SRCoordinatorEmitter"]
        PATH["SRNavigationPath"]
    end

    V -- "commands" --> SRR
    SRR -- "triggers" --> TR["SRTransition"]
    VM -- "observes" --> SRR
    VM -- "updates" --> SRC
    COORD -- "owns" --> EMIT
    COORD -- "owns" --> PATH
    PATH -- "wraps" --> SWPATH["NavigationPath"]
    VM -- "executes" --> SWNAV["Presentation (Sheet, Cover, Alert etc.)"]
    VM -- "updates" --> COORD
    EMIT --"wraps" --> TBS["Tabbar Selection"]
    SRC --"updates all" --> VM     

AI Context Guidance

To understand an existing sRouting implementation, follow this research path:

1. Entry Point: Find @main and SRRootView — reveals the SRContext and root AppCoordinator.
2. Coordinator: Inspect the @sRouteCoordinator class — shows tabs, navigation stacks, and mapping.
3. Routes: Find @sRoute or @sRoutePath enums — these are the source of truth for screens.
4. Navigation Logic: Locate SRRouter instances in Views and check @sRouteObserver for destination handling.

For implementation details, see Sources/sRouting/Models/ (SRRouter, SRContext, SRNavigationPath) and Sources/sRoutingMacros/ (macro definitions).

1. Core Concepts & Macros

2. Setting Up sRouting

Step 1: Define the Coordinator

import sRouting
import Observation

@sRouteCoordinator(tabs: ["home", "settings"], stacks: "home", "settings")
@Observable
final class AppCoordinator { }

Step 2: Configure App Entry Point

@main
struct MyApp: App {
    @State private var appCoordinator = AppCoordinator()
    @State private var context = SRContext()

    var body: some Scene {
        WindowGroup {
            SRRootView(context: context, coordinator: appCoordinator) {
                SRSwitchView(startingWith: AppRoute.startScreen)
            }
        }
    }
}

[!IMPORTANT]
SRRootView must be the root of your navigation hierarchy to enable deep linking and global navigation actions.

Checkpoint: Build and run — the app should launch without errors and display the initial screen from SRSwitchView.

3. Implementing TabBar & Navigation

Define a Route Observer

@sRouteObserver(HomeRoute.self, SettingsRoute.self)
struct RouteObserver { }

Create the TabBar View

Use coordinator.emitter.tabSelection for tab binding and apply .routeObserver to each NavigationStack.

struct MainTabbarView: View {
    @Environment(AppCoordinator.self) var coordinator

    var body: some View {
        @Bindable var emitter = coordinator.emitter
        TabView(selection: $emitter.tabSelection) {
            NavigationStack(path: coordinator.homePath) {
                HomeView()
                    .routeObserver(RouteObserver.self)
            }
            .tag(AppCoordinator.SRTabItem.homeItem)
            .tabItem { Label("Home", systemImage: "house") }

            NavigationStack(path: coordinator.settingsPath) {
                SettingsView()
                    .routeObserver(RouteObserver.self)
            }
            .tag(AppCoordinator.SRTabItem.settingsItem)
            .tabItem { Label("Settings", systemImage: "gear") }
        }
    }
}

Checkpoint: Build and run — tabs should appear and switching between them should work. Each tab's content view should render.

4. Navigation Actions (SRRouter)

Basic Navigation

• router.trigger(to: .detail, with: .push): Push a new screen.
• router.trigger(to: .profile, with: .sheet): Present a sheet.
• router.trigger(to: .login, with: .present): Present a full-screen cover.
• router.dismiss(): Dismiss the current modal or pop the top view.
• router.pop(): Pop one level in the current stack.
• router.popToRoot(): Pop all the way to the root of the current stack.

Advanced Actions

• router.show(alert: .error("Msg")): Show an alert (requires AlertRoute typealias in your Route enum).
• router.show(dialog: .confirm): Show a confirmation dialog.
• router.show(popover: .info): Show a popover.
• router.selectTabbar(at: .home): Programmatically switch tabs.
• router.switchTo(route: AppRoute.mainTabbar): Reset the root view (e.g., after login).
• router.dismissAll(): Dismiss all modals and reset path.

5. Advanced Features

Nested Sub-routes

Organize complex navigation by nesting routes.

@sRoute
enum HomeRoute {
    case main
    @sSubRoute case detail(DetailRoute)

    var screen: some View {
        switch self {
        case .main: HomeView()
        case .detail(let route): route.screen
        }
    }
}

Deep Linking & Global Routing

Use SRContext to perform navigation from anywhere (e.g., in response to a push notification).

await context.routing(
    .select(tabItem: .home),
    .push(route: HomeRoute.detail(.info))
)

Multiple Coordinators

Present a new flow with its own coordinator (e.g., a multi-step onboarding).

// In your view
router.openCoordinator(route: OnboardingRoute.start, with: .present)

// In your root view
SRRootView(...) { ... }
.onRoutingCoordinator(OnboardingRoute.self, context: context)

6. Troubleshooting