Swift Navigation

Swift Navigation is a foundational library providing tools for building state-driven navigation and state management APIs across Apple platforms (SwiftUI, UIKit, AppKit) and non-Apple platforms (Windows, Linux, Wasm).

It provides core primitives that serve as the building blocks for more specialized libraries like SwiftUINavigation and UIKitNavigation.

Key core components include:

• observe: Minimally observes changes in a model to trigger updates.
• UIBinding: Provides two-way binding to connect navigation and UI components to an observable model.
• UITransaction: Associates animations and metadata with state changes.
• UINavigationPath: A type-erased stack of data used to describe stack-based navigation.

SwiftNavigation is a foundational library providing tools for state management and navigation across all Swift platforms (SwiftUI, UIKit, AppKit, Windows, Linux, Wasm, etc.). It provides the primitives necessary to build advanced navigation systems.

Core components include:

• Observation: Tools like observe(isolation:_:)-9xf99 for minimally observing model changes.
• Binding: UIBinding for two-way binding between navigation/UI components and observable models.
• Navigation Primitives: UINavigationPath for type-erased stack-based navigation and UITransaction for associating animations or metadata with state changes.

To associate animations, metadata, or other transient data with state changes, use UITransaction. This allows mutations to carry extra context that the UI can react to (e.g., triggering a specific animation during a state transition).

Key types:

• UITransaction: The container for associated data.
• UITransactionKey: Used to identify specific pieces of data within a transaction.
• withUITransaction(_:_:) and withUITransaction(_:_:_:): Functions to wrap state mutations within a transaction.

When a feature can navigate to multiple, mutually exclusive screens, use an enum to represent the destination state. By using the @CasePathable macro (from the CasePaths library), you can create bindings to specific enum cases to drive navigation.

Setup

1. Define an enum with @CasePathable.
2. Hold an optional instance of that enum in your state.
3. Use the specialized NavigationLink or navigationDestination overloads that accept a binding to a specific case.

Example with NavigationLink

@CasePathable
enum Destination {
  case counter(Int)
  case text(String)
}

@State var destination: Destination?

// ...

NavigationLink(item: $destination.counter) { isActive in
  destination = isActive ? .counter(42) : nil
} destination: { $number in
  CounterView(number: $number)
} label: {
  Text("Go to counter")
}

You can drive UI elements (like alerts or dialogs) from your application state on cross-platform targets. For example, you can use the alert(isPresented:_:)-9xf99 pattern to present an alert based on a boolean property in your model, which can then be implemented via platform-specific APIs (like the browser's alert or a custom DOM element).

alert(isPresented: $model.isShowingErrorAlert) { 
  "Something went wrong"
}

The library provides specialized state types to represent common UI elements, making it easier to manage the presentation of transient UI components:

• TextState: For managing text-based UI state.
• AlertState: For managing the presentation of alerts.
• ConfirmationDialogState: For managing confirmation dialogs.
• ButtonState: For managing button-related states.

Because AlertState, TextState, ButtonState, and the associated action enums are all Equatable, you can write unit tests to verify that the correct alert is presented with the correct content.

Example test pattern:

1. Trigger the method that sets the alert state.
2. Assert that model.alert is not nil.
3. Assert that model.alert?.title matches the expected TextState.
4. Simulate a button tap by calling the action handler with the expected action.
5. Assert that the resulting side effect (e.g., deletion) occurred.

func testDelete() {
  let model = FeatureModel(/* ... */)

  model.deleteButtonTapped()
  XCTAssertEqual(model.alert?.title, TextState("Are you sure?"))

  model.alertButtonTapped(.confirmDelete)
  // Assert that deletion actually occurred.
}

SwiftNavigation provides mechanisms for two-way binding to connect UI components to an observable model:

• UIBindable: Used for creating and sharing state.
• UIBinding: Provides the two-way binding mechanism between navigation/UI and the model.
• CaseBindable / CaseBindable(): Specialized tools for handling state related to enums/cases.