swift-composable-architecture-mirror/Sources/ComposableArchitecture/Documentation.docc/Articles/TreeBasedNavigation.md

Tree-based navigation

Learn about tree-based navigation, that is navigation modeled with optionals and enums, including how to model your domains, how to integrate features, how to test your features, and more.

Overview

Tree-based navigation is the process of modeling navigation using optional and enum state. This style of navigation allows you to deep-link into any state of your application by simply constructing a deeply nested piece of state, handing it off to SwiftUI, and letting it take care of the rest.

• Basics
• Enum state
• Integration
• Dismissal
• Testing

Basics

The tools for this style of navigation include the PresentationState property wrapper, PresentationAction, the ReducerProtocol/ifLet(_:action:then:fileID:line:) operator, and a bunch of APIs that mimic SwiftUI's regular tools, such as .sheet, .popover, etc., but tuned specifically for the Composable Architecture.

The process of integrating two features together for navigation largely consists of 2 steps: integrating the features' domains together and integrating the features' views together. One typically starts by integrating the features' domains together. This consists of adding the child's state and actions to the parent, and then utilizing a reducer operator to compose the child reducer into the parent.

For example, suppose you have a list of items and you want to be able to show a sheet to display a form for adding a new item. We can integrate state and actions together by utilizing the PresentationState and PresentationAction types:

struct InventoryFeature: ReducerProtocol {
  struct State: Equatable {
    @PresentationState var addItem: ItemFormFeature.State?
    var items: IdentifiedArrayOf<Item> = []
    // ...
  }

  enum Action: Equatable {
    case addItem(PresentationAction<ItemFormFeature.Action>)
    // ...
  }

  // ...
}

Note: The addItem state is held as an optional. A non-nil value represents that feature is being presented, and nil presents the feature is dismissed.

Next you can integrate the reducers of the parent and child features by using the ReducerProtocol/ifLet(_:action:then:fileID:line:) reducer operator, as well as having an action in the parent domain for populating the child's state to drive navigation:

struct InventoryFeature: ReducerProtocol {
  struct State: Equatable { /* ... */ }
  enum Action: Equatable { /* ... */ }
  
  var body: some ReducerProtocolOf<Self> {
    Reduce<State, Action> { state, action in 
      switch action {
      case .addButtonTapped:
        // Populating this state performs the navigation
        state.addItem = ItemFormFeature.State()
        return .none

      // ...
      }
    }
    .ifLet(\.$addItem, action: /Action.addItem) {
      ItemFormFeature()
    }
  }
}

Note: The key path used with ifLet focuses on the @PresentationState projected value since it uses the $ syntax. Also note that the action uses a case path, which is analogous to key paths but tuned for enums, and uses the forward slash syntax.

That's all that it takes to integrate the domains and logic of the parent and child features. Next we need to integrate the features' views. This is done using view modifiers that look similar to SwiftUI's, but are tuned specifically to work with the Composable Architecture.

For example, to show a sheet from the addItem state in the InventoryFeature, we can use the sheet(store:) modifier that takes a Store as an argument that is focused on presentation state and actions:

struct InventoryView: View {
  let store: StoreOf<InventoryFeature>

  var body: some View {
    List {
      // ...
    }
    .sheet(
      store: self.store.scope(state: \.$addItem, action: { .addItem($0) })
    ) { store in
      ItemFormView(store: store)
    }
  }
}

Note: We again must specify a key path to the @PresentationState projected value, i.e. \.$addItem.

With those few steps completed the domains and views of the parent and child features are now integrated together, and when the addItem state flips to a non-nil value the sheet will be presented, and when it is nil'd out it will be dismissed.

In this example we are using the .sheet view modifier, but the library ships with overloads for all of SwiftUI's navigation APIs that take stores of presentation domain, including:

• alert(store:)
• confirmationDialog(store:)
• sheet(store:)
• popover(store:)
• fullScreenCover(store:)
• navigationDestination(store:)
• NavigationLinkStore

This should make it possible to use optional state to drive any kind of navigation in a SwiftUI application.

Enum state

While driving navigation with optional state can be powerful, it can also lead to less-than-ideal modeled domains. In particular, if a feature can navigate to multiple screens then you may be tempted to model that with multiple optional values:

struct State {
  @PresentationState var detailItem: DetailFeature.State?
  @PresentationState var editItem: EditFeature.State?
  @PresentationState var addItem: AddFeature.State?
  // ...
}

However, this can lead to invalid states, such as 2 or more states being non-nil at the same time, and that can cause a lot of problems. First of all, SwiftUI does not support presenting multiple views at the same time from a single view, and so by allowing this in our state we run the risk of putting our application into an inconsistent state with respect to SwiftUI.

Second, it becomes more difficult for us to determine what feature is actually being presented. We must check multiple optionals to figure out which one is non-nil, and then we must figure out how to interpret when multiple pieces of state are non-nil at the same time.

And the number of invalid states increases exponentially with respect to the number of features that can be navigated to. For example, 3 optionals leads to 4 invalid states, 4 optionals leads to 11 invalid states, and 5 optionals leads to 26 invalid states.

For these reasons, and more, it can be better to model multiple destinations in a feature as a single enum rather than multiple optionals. So the example of above, with 3 optionals, can be refactored as an enum:

enum State {
  case addItem(AddFeature.State)
  case detailItem(DetailFeature.State)
  case editItem(EditFeature.State)
  // ...
}

This gives us compile-time proof that only one single destination can be active at a time.

In order to utilize this style of domain modeling you must take a few extra steps. First you model a "destination" reducer that encapsulates the domains and behavior of all of the features that you can navigate to. And typically it's best to nest this reducer inside the feature that can perform the navigation:

struct InventoryFeature: ReducerProtocol {
  // ...

  struct Destination: ReducerProtocol {
    enum State {
      case addItem(AddFeature.State)
      case detailItem(DetailFeature.State)
      case editItem(EditFeature.State)
    }
    enum Action {
      case addItem(AddFeature.Action)
      case detailItem(DetailFeature.Action)
      case editItem(EditFeature.Action)
    }
    var body: some ReducerProtocolOf<Self> {
      Scope(state: /State.addItem, action: /Action.addItem) { 
        AddFeature()
      }
      Scope(state: /State.editItem, action: /Action.editItem) { 
        EditFeature()
      }
      Scope(state: /State.detailItem, action: /Action.detailItem) { 
        DetailFeature()
      }
    }
  }
}

Note: Both the State and Action types nested in the reducer are enums, with a case for each screen that can be navigated to. Further, the body computed property has a Scope reducer for each feature, and uses case paths for focusing in on the specific case of the state and action enums.

With that done we can now hold onto a single piece of optional state in our feature, using the PresentationState property wrapper, and we hold onto the destination actions using the PresentationAction type:

struct InventoryFeature: ReducerProtocol {
  struct State { 
    @PresentationState var destination: Destination.State?
    // ...
  }
  enum Action {
    case destination(PresentationAction<Destination.Action>)
    // ...
  }

  // ...
}

Now when we want to present a particular feature we can simply populate the destination state with a case of the enum:

case addButtonTapped:
  state.destination = .addItem(AddFeature.State())
  return .none

And at any time we can figure out exactly what feature is being presented by switching or otherwise destructuring the single piece of destination state rather than checking multiple optional values.

The final step is to make use of the special view modifiers that come with this library that mimic SwiftUI's APIs, but are tuned specifically for enum state. In particular, you provide a store that is focused in on the Destination domain, and then provide transformations for isolating a particular case of the state and action enums.

For example, suppose the "add" screen is presented as a sheet, the "edit" screen is presented by a popover, and the "detail" screen is presented in a drill-down. Then we can use the .sheet(store:state:action:), .popover(store:state:action:), and .navigationDestination(store:state:action:) view modifiers to have each of those styles of presentation powered by the respective case of the destination enum:

struct InventoryView: View {
  let store: StoreOf<InventoryFeature>

  var body: some View {
    List {
      // ...
    }
    .sheet(
      store: self.store.scope(state: \.destination, action: { .destination($0) }),
      state: /InventoryFeature.State.addItem,
      action: /InventoryFeature.Action.addItem
    ) { store in 
      AddFeatureView(store: store)
    }
    .popover(
      store: self.store.scope(state: \.destination, action: { .destination($0) }),
      state: /InventoryFeature.State.editItem,
      action: /InventoryFeature.Action.editItem
    ) { store in 
      EditFeatureView(store: store)
    }
    .navigationDestination(
      store: self.store.scope(state: \.destination, action: { .destination($0) }),
      state: /InventoryFeature.State.detailItem,
      action: /InventoryFeature.Action.detailItem
    ) { store in 
      DetailFeatureView(store: store)
    }
  }
}

With those steps completed you can be sure that your domains are modeled as concisely as possible. If the "add" item sheet was presented, and you decided to mutate the destination state to point to the .detailItem case, then you can be certain that the sheet will be dismissed and the drill-down will occur immediately.

API Unification

One of the best features of tree-based navigation is that it unifies all forms of navigation with a single style of API. First of all, regardless of the type of navigation you plan on performing, integrating the parent and child features together can be done with the single ReducerProtocol/ifLet(_:action:destination:fileID:line:) operator. This one single API services all forms of optional-driven navigation.

And then in the view, whether you are wanting to perform a drill-down, show a sheet, display an alert, or even show a custom navigation component, all you need to do is invoke an API that is provided a store focused on some PresentationState and PresentationAction. If you do that, then the API can handle the rest, making sure to present the child view when the state becomes non-nil and dismissing when it goes back to nil.

This means that theoretically you could have a single view that needs to be able to show a sheet, popover, drill-down, alert and confirmation dialog, and all of the work to display the various forms of navigation could be as simple as this:

.sheet(
  store: self.store.scope(state: \.addItem, action: { .addItem($0) })
) { store in 
  AddFeatureView(store: store)
}
.popover(
  store: self.store.scope(state: \.editItem, action: { .editItem($0) })
) { store in 
  EditFeatureView(store: store)
}
.navigationDestination(
  store: self.store.scope(state: \.detailItem, action: { .detailItem($0) })
) { store in 
  DetailFeatureView(store: store)
}
.alert(
  store: self.store.scope(state: \.alert, action: { .alert($0) })
)
.confirmationDialog(
  store: self.store.scope(state: \.confirmationDialog, action: { .confirmationDialog($0) })
)

In each case we provide a store scoped to the presentation domain, and a view that will be presented when its corresponding state flips to non-nil. It is incredibly powerful to see that so many seemingly disparate forms of navigation can be unified under a single style of API.

Integration

Once your features are integrated together using the steps above, your parent feature gets instant access to everything happening inside the child feature. You can use this as a means to integrate the logic of child and parent features. For example, if you want to detect when the "Save" button inside the edit feature is tapped, you can simply destructure on that action. This consists of pattern matching on the PresentationAction, then the PresentationAction/presented(_:) case, then the feature you are interested in, and finally the action you are interested in:

case .destination(.presented(.editItem(.saveButtonTapped))):
  // ...

Once inside that case you can then try extracting out the feature state so that you can perform additional logic, such as closing the "edit" feature and saving the edited item to the database:

case .destination(.presented(.editItem(.saveButtonTapped))):
  guard case let .editItem(editItemState) = self.destination
  else { return .none }

  state.destination = nil
  return .fireAndForget {
    self.database.save(editItemState.item)
  }

Dismissal

Dismissing a presented feature is as simple as nil-ing out the state that represents the presented feature:

case .closeButtonTapped:
  state.destination = nil
  return .none

In order to nil out the presenting state you must have access to that state, and usually only the parent has access, but often we would like to encapsulate the logic of dismissing a feature to be inside the child feature without needing explicit communication with the parent.

SwiftUI provides a wonderful tool for allowing child views to dismiss themselves from the parent, all without any explicit communication with the parent. It's an environment value called dismiss, and it can be used like so:

struct ChildView: View {
  @Environment(\.dismiss) var dismiss
  var body: some View {
    Button("Close") { self.dismiss() }
  }
}

When self.dismiss() is invoked, SwiftUI finds the closet parent view with a presentation, and causes it to dismiss by writing false or nil to the binding that drives the presentation. This can be incredibly useful, but it is also relegated to the view layer. It is not possible to use dismiss elsewhere, like in an observable object, which would allow you to have nuanced logic for dismissal such as validation or async work.

The Composable Architecture has a similar tool, except it is appropriate to use from a reducer, where the rest of your feature's logic and behavior resides. It is accessed via the library's dependency management system (see doc:DependencyManagement) using DismissEffect:

struct Feature: ReducerProtocol {
  struct State { /* ... */ }
  enum Action { 
    case closeButtonTapped
    // ...
  }
  @Dependency(\.dismiss) var dismiss
  func reduce(into state: inout State, action: Action) -> EffectTask<Action> {
    switch action {
    case .closeButtonTapped:
      return .fireAndForget { await self.dismiss() }
    } 
  }
}

Note: The DismissEffect function is async which means it cannot be invoked directly inside a reducer. Instead it must be called from either EffectPublisher/run(priority:operation:catch:fileID:line:) or EffectPublisher/fireAndForget(priority:_:).

When self.dismiss() is invoked it will nil out the state responsible for presenting the feature by sending a PresentationAction/dismiss action back into the system, causing the feature to be dismissed. This allows you to encapsulate the logic for dismissing a child feature entirely inside the child domain without explicitly communicating with the parent.

Note: Because dismissal is handled by sending an action, it is not valid to ever send an action after invoking dismiss():

return .run { send in 
  await self.dismiss()
  await send(.tick)  // ⚠️
}

To do so would be to send an action for a feature while its state is nil, and that will cause a runtime warning in Xcode and a test failure when running tests.

Warning: SwiftUI's environment value @Environment(\.dismiss) and the Composable Architecture's dependency value @Dependency(\.dismiss) serve similar purposes, but are completely different types. SwiftUI's environment value can only be used in SwiftUI views, and this library's dependency value can only be used inside reducers.

Testing

A huge benefit of properly modeling your domains for navigation is that testing because quite easy. Further, using "non-exhaustive testing" (see doc:Testing#Non-exhaustive-testing) can be very useful for testing navigation since you often only want to assert on a few high level details and not all state mutations and effects.

As an example, consider the following simple counter feature that wants to dismiss itself if its count is greater than or equal to 5:

struct CounterFeature: ReducerProtocol {
  struct State: Equatable {
    var count = 0
  }
  enum Action: Equatable {
    case decrementButtonTapped
    case incrementButtonTapped
  }

  @Dependency(\.dismiss) var dismiss

  func reduce(into state: inout State, action: Action) -> EffectTask<Action> {
    switch action {
    case .decrementButtonTapped:
      state.count += 1
      return .none

    case .incrementButtonTapped:
      state.count += 1
      return state.count >= 5
        ? .fireAndForget { await self.dismiss() }
        : .none
    }
  }
}

And then let's embed that feature into a parent feature using PresentationState, PresentationAction and ReducerProtocol/ifLet(_:action:destination:fileID:line:):

struct Feature: ReducerProtocol {
  struct State: Equatable {
    @PresentationState var counter: CounterFeature.State?
  }
  enum Action: Equatable {
    case counter(CounterFeature.Action)
  }
  var body: some ReducerProtocolOf<Self> {
    Reduce { state, action in 
      // Logic and behavior for core feature.
    }
    .ifLet(\.$counter, action: /Action.counter) {
      CounterFeature()
    }
  }
}

Now let's try to write a test on the Feature reducer that proves that when the child counter feature's count is incremented above 5 it will dismiss itself. To do this we will construct a TestStore for Feature that starts in a state with the count already set to 3:

func testDismissal() {
  let store = TestStore(
    initialState: Feature.State(
      counter: CounterFeature.State(count: 3)
    )
  ) {
    CounterFeature()
  }
}

Then we can send the .incrementButtonTapped action in the counter child feature to confirm that the count goes up by one:

await store.send(.counter(.presented(.incrementButtonTapped))) {
  $0.counter?.count = 4
}

And then we can send it one more time to see that the count goes up to 5:

await store.send(.counter(.presented(.incrementButtonTapped))) {
  $0.counter?.count = 5
}

And then we finally expect that the child dismisses itself, which manifests itself as the PresentationAction/dismiss action being sent to nil out the counter state, which we can assert using the TestStore/receive(_:timeout:assert:file:line:)-1rwdd method on TestStore:

await store.receive(.counter(.dismiss)) {
  $0.counter = nil
}

This shows how we can write very nuanced tests on how parent and child features interact with each other.

However, the more complex the features become, the more cumbersome testing their integration can be. By default, TestStore requires us to be exhaustive in our assertions. We must assert on how every piece of state changes, how every effect feeds data back into the system, and we must make sure that all effects finish by the end of the test (see docs:Testing for more info).

But TestStore also supports a form of testing known as "non-exhaustive testing" that allows you to assert on only the parts of the features that you actually care about (see doc:Testing#Non-exhaustive-testing for more info).

For example, if we turn off exhaustivity on the test store (see TestStore/exhaustivity) then we can assert at a high level that when the increment button is tapped twice that eventually we receive a dismiss action:

func testDismissal() {
  let store = TestStore(
    initialState: Feature.State(
      counter: CounterFeature.State(count: 3)
    )
  ) {
    CounterFeature()
  }
  store.exhaustivity = .off

  await store.send(.counter(.presented(.incrementButtonTapped)))
  await store.send(.counter(.presented(.incrementButtonTapped)))
  await store.receive(.counter(.dismiss)) 
}

This essentially proves the same thing that the previous test proves, but it does so in much fewer lines and is more resilient to future changes in the features that we don't necessarily care about.

That is the basics of testing, but things get a little more complicated when you leverage the concepts outlined in doc:TreeBasedNavigation#Enum-state in which you model multiple destinations as an enum instead of multiple optionals. In order to assert on state changes when using enum state you must be able to extract the associated state from the enum, make a mutation, and then embed the new state back into the enum.

The library provides a tool to perform these steps in a single step, and it is called XCTModify:

await store.send(.destination(.presented(.counter(.incrementButtonTapped)))) {
  XCTModify(&$0.destination, case: /Feature.Destination.State.counter) { 
    $0.count = 4
  }
}

The XCTModify function takes an inout piece of enum state as its first argument and a case path for its second argument, and then uses the case path to extract the payload in that case, allow you to perform a mutation to it, and embed the data back into the enum. So, in the code above, we are wanting to mutate the $0.destination enum by isolating the .counter case, and mutating the count to be 4 since it incremented by one. Further, if the case of $0.destination didn't match the case path, then a test failure would be emitted.