RFC: Better Bindings Revisited

[stephencelis]

About two years ago, we introduced binding tools to help reduce the boilerplate that came with using SwiftUI bindings in a feature. Due to some edge cases in that original design, we had to make them a little less nice, but the tools have more-or-less remained the same ever since.

They aren't without their faults:

• For one, they completely fall apart when view state is involved, which quickly becomes a necessity of non-leaf features of a TCA application, and this is a regular topic of discussion.
• View actions throw another wrench in things.

The library does provide a tool for the problem of view state and view actions, but it’s difficult to wield and introduces more boilerplate than the tools intend to remove.

These shortcomings have been on our radar for a long time, and we want to provide a better solution before shipping 1.0. And even though WWDC23 has introduced new tools that largely eliminate these issues, we want to provide a solution that works for folks today, and for apps that can’t target iOS 17 and friends immediately.

Of all our many experiments to solve these problems, one stands ahead of the pack, so we’d like to present it today and gather a bit more feedback before merging a solution.

BindingViewStore and @BindingViewState

We would like to introduce two more tools to our ever-growing menagerie of binding APIs in order to better support bindings with view state. They are the missing pieces that stand alongside @BindingState, BindingAction, and BindingReducer. Bindings with non-view state will work mostly as they did before with one improvement/caveat.

But when your feature requires view state, there is now a much more straightforward path. Let’s say you have an existing feature that needs view state (perhaps it will be embedding a child feature that its view should not observe):

struct FormFeature: Reducer {
  struct State {
    @BindingState var description = ""
    var isLoading = false
    // ...
  }
  enum Action: BindableAction {
    case binding(BindingAction<State>)
    // ...
  }
  var body: some ReducerOf<Self> {
    BindingReducer()
    // ...
  }
}

Your view should introduce a ViewState struct so that it only observes the bare essentials needed for the view to render.

To do so with the new tools:

1. Introduce that ViewState struct to your view, marking all bindable properties with the @BindingViewState property wrapper:

   struct FormView: View {
     struct ViewState: Equatable {
       @BindingViewState var description: String
       let isLoading: Bool
     }
   
     let store: StoreOf<FormFeature>
     var body: some View {
       // ...
     }
   }

2. Use the new overload of WithViewStore where observe is handed a BindingViewStore, which can be used to produce @BindingViewState using .$propertyName:

   struct FormView: View {
     // ...
     var body: some View {
       WithViewStore(
         self.store,
         observe: {
           ViewState(description: $0.$description, isLoading: $0.isLoading)
         }
       ) { viewStore in
         // ...
       }
     }
   }

   Tip: We can extract this transform into helpers…

   E.g. on FormView.ViewState:

   extension FormView.ViewState {
     init(store: BindingViewStore<FormFeature.State>) {
       self._description = store.$description
       self.isLoading = store.isLoading
     }
   }
   // Simplifies `observe:`
   WithViewStore(self.store, observe: ViewState.init) { viewStore in
     // ...
   }

   Or on BindingStore<FormFeature.State> directly:

   extension BindingViewStore<FormFeature.State> {
     var view: FormView.ViewState {
       FormView.ViewState(
         description: self.$description,
         isLoading: self.isLoading
       )
     }
   }
   // Simplifies `observe:`
   WithViewStore(self.store, observe: \.view) { viewStore in
     // ...
   }

3. Access these bindings in the view using viewStore.$propertyName:

   TextField("Description", text: viewStore.$description)

Note that we have generally restored this viewStore.$propertyName syntax for deriving bindings, so you will be able to simplify your existing features:

-viewStore.binding(\.$description)
+viewStore.$description

To recap, the two new types introduced to facilitate bindings and view state, and their respective roles:

• @BindingViewState: A property wrapper for producing bindings from view state. Note that we cannot simply use @Binding because view state must generally be equatable, and Binding does not conditionally conform to the Equatable protocol (and probable should not).
• BindingViewStore: A wrapper for producing BindingViewState values from a store when building a view store.

View actions

Our binding tools are also now more compatible with view actions.

As an example, consider the following domain with a sub-set of view-only actions:

struct Login: Reducer {
  struct State {
    // 1. Annotate state with `@BindingState` as usual:
    @BindingState public var email = ""
    @BindingState public var password = ""
    // ...
  }
  public enum Action {
    // 2. Conform the `View` action enum to `BindableAction`,
    //    and point its `binding` case to `BindingAction<State>.
    public enum View: BindableAction {
      case binding(BindingAction<State>)
      case loginButtonTapped
    }

    // ...
    case view(View)
  }
  var body: some ReducerOf<Self> {
    // 3. Point `BindingReducer` to the view action case:
    BindingReducer(action: /Action.view)
  }
}

With that defined, we can now point WithViewStore's send: to the view case and access the bindings accordingly:

WithViewStore(self.store, observe: { $0 }, send: { .view($0) }) { viewStore in
  TextField("blob@pointfree.co", text: viewStore.$email)
  SecureTextField("••••••••", text: viewStore.$password)
}

A deprecation

The one deprecation and breaking change introduced by this PR is that you should no longer chain the @BindingState property wrapper to produce child BindingState. This means you should not longer do:

// In the reducer:
case .binding(\.$sectionA.text):
  // ...

// In the view:
viewStore.binding(\.$sectionA.text)

Instead a reducer can only listen to the firehose of changes:

// In the reducer:
case .binding(\.$sectionA):
  // ...

If you must listen for more granular changes, move your @BindingState annotation to the child properties, instead.

Edit: The above was ill-advised, and the issue here is a bit more subtle. See this reply and thread for more info.

As a result of this change, though, we can recover a simplified view syntax we eliminated long ago:

// In the view:
viewStore.$sectionA.text

More examples

The examples have all been updated. Here are a few:

• The Todo feature of the Todos app: https://github.com/pointfreeco/swift-composable-architecture/blob/c73f5daed5dec36f7da5170ade74a5c2e838557d/Examples/Todos/Todos/Todo.swift
• The parent Todos feature, which contains view state: https://github.com/pointfreeco/swift-composable-architecture/blob/c73f5daed5dec36f7da5170ade74a5c2e838557d/Examples/Todos/Todos/Todos.swift
• The Login feature of the Tic-Tac-Toe app uses both view state and view actions:
  • Its domain/reducer: https://github.com/pointfreeco/swift-composable-architecture/blob/c73f5daed5dec36f7da5170ade74a5c2e838557d/Examples/TicTacToe/tic-tac-toe/Sources/LoginCore/LoginCore.swift
  • Its view: https://github.com/pointfreeco/swift-composable-architecture/blob/c73f5daed5dec36f7da5170ade74a5c2e838557d/Examples/TicTacToe/tic-tac-toe/Sources/LoginSwiftUI/LoginView.swift

Take it for a spin today!

We want your feedback, and we want to make sure this solution works in your existing code bases, please take it for a spin today:

• binding-store: If you’re on a recent, released version of TCA, point to the binding-store branch.
• prerelease/binding-store: If you’re on prerelease/1.0, point to prerelease/binding-store.

[jefflewis]

Is the idea of this to be the "legacy" support until apps could required iOS 17 and get macro support for @observable like you demonstrated? https://hachyderm.io/@pointfreeco/110555023243470033

That said, the updated API looks great and solves an issue I faced with binding actions in a recent app. To make it work, I just removed the bindings entirely and made my own viewStore.binding(get: send:) with custom actions for each property. This would have reduced the amount of code I would need to write/maintain to have the same effect.

[stephencelis]

Generally yes, we think this solution is going to be mostly applicable to apps targeting < iOS 17, but that's going to be a lot of apps for the time being. We're still exploring the iOS 17 backwards compatibility story, but going forward TCA is looking a lot simpler given the explorations you reference 😄

[jefflewis]

Awesome! Ya'll do a great job on making things backwards compatible, so glad to hear timings will still be possible with a clear path to cleaner code with newer APIs!

[GreatApe]

How do we create a BindingViewStore?

[GreatApe]

I mean, how do we make WithViewStore give us a BindingViewStore instead of a State, in the observe closure?

[oliverfoggin]

Oh, for me it just worked. I did { state in and then state was a BindingViewStore.

Have you set up your Bindings and stuff in the Reducer side of things?

[davdroman]

@GreatApe there's a new WithViewStore overload in the branch that hands in a BindingViewStore for you to use, so it's a pretty seamless transition.

[GreatApe]

Sure, I was just wondering what controls which overload is being used, since we don't seem to have to e.g. conform State to something.

But I do find it a bit strange that we get a BindingViewStore there, rather than say a BindingViewState.

[davdroman]

@GreatApe I think the BindingViewStore overload is considered "more specific" because it constraints the action type to BindableAction, hence it will always be preferred by the compiler vs raw state and action, without ambiguities.

swift-composable-architecture/Sources/ComposableArchitecture/SwiftUI/Binding.swift

Line 281 in 4a5d2ec

) where ViewAction: BindableAction, ViewAction.State == State {

[oliverfoggin]

RE this...

WithViewStore(self.store, observe: { $0 }, send: { .view($0) }) { viewStore in
  TextField("blob@pointfree.co", text: viewStore.$email)
  SecureTextField("••••••••", text: viewStore.$password)
}

I've added an extension onto Store to scope just by an action which I think I prefer...

extension Store {
  public func scope<ChildAction>(
    action fromChildAction: @escaping (ChildAction) -> Action
  ) -> Store<State, ChildAction> {
    scope(state: { $0 }, action: fromChildAction)
  }
}

Personal preference I guess. But something worth mentioning.

Means I can do like...

WithViewStore(self.store.scope(action: Login.Action.view), observe: { $0 }) { viewStore in
  TextField("blob@pointfree.co", text: viewStore.$email)
  SecureTextField("••••••••", text: viewStore.$password)
}

[stephencelis]

Just a note that we generally try to avoid overloads like this in the library since they can slow down compilation, especially in view bodies. Looking forward to the day when view store goes away 😄

WithViewStore is getting a few new overloads with this PR, which we'd love feedback on if it slows down or breaks compilation for anyone. We should also explore if @_disfavoredOverload alleviates any pain.

[roanutil]

Losing the ability to "chain the @BindingState property wrapper to produce child BindingState" is disappointing. However, it's a good tradeoff for ViewState and ViewAction.

This seems like a good way forward.

[stephencelis]

@roanutil First a quick note: you can still use @BindingState on a struct and chain onto it to pluck bindings off multiple fields:

// Before:
text: viewStore.binding(\.$userSettings.isHapticFeedbackEnabled)

// After:
text: viewStore.$userSettings.isHapticFeedbackEnabled

The only ability we're taking away is the ability for a reducer to pattern match deeply into those fields:

case .binding(\.$userSettings.isHapticFeedbackEnabled):

While this seems unfortunate at first glance, we came to the conclusion that it was a brittle feature: chainable binding state can be quite fraught and can break in unexpected ways, mainly because key paths aren't really decomposable, so we can't compare two key paths is very many ways.

For example, there's no hasPrefix on key path:

(\Settings.$userSettings.isHapticFeedbackEnabled).hasPrefix(\Settings.$userSettings)

These key paths are completely different, and there's no way for us to make it so that when you pattern match on .binding(\.$userSettings) you can intercept actions that had chained into something deeper.

// ✅ Only intercepts this specific binding from the view
case .binding(\.$userSettings.isHapticFeedbackEnabled):
// ❌ Fails to intercept more specific binding actions
case .binding(\.$userSettings):

And seemingly innocuous changes in the view can break reducer logic:

-text: viewStore.binding(\.$userSettings.isHapticFeedbackEnabled)
+text: viewStore.binding(\.$userSettings).isHapticFeedbackEnabled

Both compile just fine, and apply the mutation to state just fine, but any additional logic you may have layered on in the reducer will be broken. And while this seems like a silly refactor, a less-silly refactor would be to take a TCA-specific view and refactor it to a simpler binding-driven view:

struct UserSettingsView: View {
  @Binding var userSettings: UserSettings
  // ...
}

UserSettingsView(userSettings: viewStore.binding(\.$userSettings))

You may assume no changes need to happen in the reducer, but its logic has been subtly broken in the process.

[rhysm94]

This is really great - very happy with the simple viewStore.$binding syntax! A great reduction in boilerplate.

I've got a couple of questions about how to use it in other use cases.

I have a question about using the new shorter syntax when using child BindingState.
In my feature, I might have something like this:

struct Feature: Reducer {
  struct State: Equatable {
    @BindingState var someData: SomeDataType
  }

  struct SomeOtherData: Equatable {
    var someInt: Int?
    var someString: String?
  }
}

If I want to specifically listen out for \.someData.someInt right now, that's fine, I can do:
case .binding(\.$someData.someInt) or case .binding(let action) and switch on the action.
However, I can see that you're recommending we apply @BindingState to the child state properties if we need to still access them in the reducer. So, adding that, we have:

struct SomeOtherData: Equatable {
  @BindingState var someInt: Int?
  @BindingState var someString: String?
}

How do I reference these properties in a view, using the shortened syntax? Is that possible with these tools?
If I try viewStore.someData.$someInt, I get a compiler error "Cannot convert value of type BindingState<Int?> to expected argument type Binding<Int?>". If I leave them as viewStore.binding(\.someData.$someInt), everything works as before, I can use case .binding(\.someData.$someInt) to match against it - I just lose the nicer syntax.

I've tested leaving the parent someData property as being wrapped with @BindingState but switching to viewStore.$someData.someInt stops me being able to specifically catch them in the reducer, and I can't do viewStore.$someData.$someInt, nor viewStore.$someData.someInt as they cause compiler errors about converting Binding<BindingState<Int?>>.

I'm also wondering how to use the Binding ViewActions where the ViewAction type is defined separately from the context of the Reducer? For example, the couple of places I use ViewActions, they're defined local to the view (as is the ViewState).
We have:

extension FeatureView {
  struct ViewState: Equatable {}

  enum ViewAction {
    case initialise
  }
}

but the tooling for ViewActions with Bindings seems to be for where ViewAction is defined as a case of the Feature.Action - is that correct? Do I just have to use BindingAction.pullback to transform a separately-defined ViewAction to the Feature.Action type as before?

Any guidance much appreciated! Thanks 😃

[stephencelis]

Yes, maybe viewStore.binding should stick around for this edge case.

It might still be worth deprecating and removing for 1.0, since we probably shouldn't support the additional edge case when there are alternatives, though maybe we need to revisit onChange(of:) now.

I guess the question is whether onChange(of:) should be part of TCA itself (probably not, right?) or a separate library?

There were a few considerations holding us back, but maybe we can figure them out:

1. API bike shedding: There are a ton of different ways we can (and have) defined this operator over time in isowords, especially pre-dependencies/protocol/builders. But now that those APIs have settled, I think we might be ready to propose:

   onChange(of _: (State) -> ChildState, _: (ChildState, ChildState) -> some ReducerOf<Self>)

2. Performance: It's far too easy to sprinkle onChange on places that can negatively impact performance. At a leaf node on some BindingReducer it's harmless, but if you tack it onto a complex piece of state in your app reducer, actions are going to be processed very slowly. We can probably document this shortcoming, but if the tool ships with the library people are more likely to use it, and so it'll be more of a topic of discussion.

We should also keep in mind that we'd probably define a different signature/overload for Observability.

I'll PR this reducer shortly, though, I think its time has come!

[stephencelis]

#2226

[rhysm94]

Another thing I was wondering about is the story around ViewActions.
In the app I'm working on, we have one or two places with ViewActions, but they are defined at the View level, alongside the ViewState. Is that pattern now discouraged, and instead we should make ViewActions a case on the original feature Action enum?
To be completely honest, the way the entire feature in question using ViewActions is written is... suboptimal. It does too much, and we use ViewState and ViewActions to bring it down to something usable on two different views (which share a fair bit of state). But the idea of keeping ViewActions next to ViewState still appeals to me.
If that's just how it is, and that's the way to make ViewActions also work with the new Binding syntax, then fair enough!

[stephencelis]

While not set in stone, view actions will hopefully be something that a macro can simplify and lint: https://twitter.com/pointfreeco/status/1669069075862155264

View actions at the view level are certainly not discouraged, it's just a lot more work to isolate in this fashion. Nesting case view(View); enum View in the enum Action is just much less work. So you should still be able to to what you're doing today if that's your preference.

[rhysm94]

That’s reasonable. One of the other things we’ve done with ViewState and ViewActions is again due to that over-complex parent feature, which can potentially present four different sheets. Each of the two views we derive ViewState/Actions from can only present two of those sheets, so we transform that in the ViewState and ViewAction into a separate enum with an init? which returns nil if it’s in either of the two cases that view doesn’t display.

Is there any specific way to handle that transform when using the new BindingViewState (e.g. parent feature has an @BindingState property of type Feature.State.Sheet, ViewState has a property of ViewState.Sheet. Is there a way to transform between the two? I couldn’t spot anything to transform the ViewAction in the same way we currently do. But, one more, I recognise that this particular feature is overly complex and would benefit from splitting into just the two constituent components (which we’ve done in one of the cases), so I’m not hugely concerned if there isn’t a way to do this with the new tooling!

(Maybe there are potentially some edge cases where you might really want your well-designed ViewState binding property to be of a different type to your Feature.State… Probably not though!)

[stephencelis]

Thanks all for weighing in! It seems like a positive change for most folks with only minor caveats, so we're going to move forward and merge.

[tunchamroeun]

struct FormView: View {
  // ...
  var body: some View {
    WithViewStore(
      self.store,
      observe: {
        ViewState(description: $0.$description, isLoading: $0.isLoading)
      }
    ) { viewStore in
      // ...
    }
  }
}

Is it support ViewStore?

Example....

@ObservedObject var viewStore: ViewStore<ViewState, FormFeature.Action>
init() {
  viewStore = .init(self.store, observe: ViewState.init)
}

[stephencelis]

@tunchamroeun Support has been added with this PR:

#2255

When it is merged we will cut another release. Please subscribe to the PR to keep up to date!