feat: nested observable state stores #333

watt · 2025-04-04T00:34:56Z

This PR adds new scoping methods to Store that allow you to create child stores from nested observable state.

These same scoping methods already exist for child models, typically created by rendering child workflows and composing their renderings, but not for nested state within a single workflow.

I've added a new ObservableCounter sample to demonstrate. The existing ObservableScreen sample has been renamed to ObservableComposition.

Example

Consider a state like this:

@ObservableState
struct State {
  var children: [ChildState]

  @ObservableState
  struct ChildState: Identifiable {
    let id = UUID()
    var foo: Int
  }
}

If one was trying to iterate over children and form bindings to the foo property, you might attempt this construction, which creates a Binding<[ChildState]> and then uses ForEach to map over individual Binding<ChildState>s.

struct ExampleView: View {
  @Perception.Bindable
  var store: Store<StateAccessor<State>>

  var body: some View {
    ForEach($store.children) { child in
      FooView(foo: child.foo)
    }
  }
}

Unfortunately this will compile and run, but writes to child.foo will not cause FooView to be invalidated. The exact mechanics behind this are opaque, but the bindings captured by the ForEach don't register observation at the right scope.

Using the new scoping methods, you can iterate over child stores, and create a binding from each store instead.

struct ExampleView: View {
  var store: Store<StateAccessor<State>>

  var body: some View {
    ForEach(store.scope(collection: \.children)) { child in
      // you can also inline this incantation to the capture list if you prefer
      @Perception.Bindable var child = child
      FooView(foo: $child.foo)
    }
  }
}

Checklist

Unit Tests
UI Tests
Snapshot Tests (iOS only)
I have made corresponding changes to the documentation

Samples/ObservableCounter/Sources/CounterListView.swift

watt · 2025-04-04T00:49:46Z

WorkflowSwiftUI/Sources/Derived/ObservableState.swift

@@ -113,6 +113,20 @@ public func _$isIdentityEqual<T: ObservableState>(
    lhs._$id == rhs._$id
 }

+@inlinable
+public func _$isIdentityEqual<T: ObservableState>(


This addition is not strictly needed for scoping, but makes the optional case much more efficient when going from nil to nil.

Is it worth moving this to a file outside of the Derived folder? It'd probably make diffs between this and the TCA ObservableState easier.

🤷 previously I was asked to put it in this folder for the same reason.

I just mean this function specifically (if it's not from the upstream repo)

watt · 2025-04-04T00:51:32Z

WorkflowSwiftUI/Tests/Derived/ObservableStateTests.swift


            withPerceptionTracking {
                _ = state.optional
            } onChange: {
-                optionalDidChange.fulfill()
+                XCTFail("Optional should not change")


result of the new _$isIdentityEqual overload

watt · 2025-04-04T00:54:31Z

Package.resolved

The Tuist setup means this file at best redundant and at worst completely out of sync. (I can pull this into a separate PR if it's controversial.)

nsillik

Nice addition, surprisingly easy.

I was wondering if it would be possible to create a purple warning when folks try to do this the wrong way. Since we've already had people try to reach for ForeEach(store.children) substates, we'll definitely want to encourage them to use scoped stores (and aren't likely to catch 100% of people who don't!). A runtime warning (like you get when you forget WithPerceptionTracking) seems like the easiest way to go (or an assert if you're feeling especially punitive, I suppose)

watt · 2025-04-04T22:46:20Z

I was wondering if it would be possible to create a purple warning when folks try to do this the wrong way. Since we've already had people try to reach for ForeEach(store.children) substates, we'll definitely want to encourage them to use scoped stores (and aren't likely to catch 100% of people who don't!). A runtime warning (like you get when you forget WithPerceptionTracking) seems like the easiest way to go (or an assert if you're feeling especially punitive, I suppose)

It might be, but it's a little tricky. I'm not sure we can do it reliably, and there are cases where it's still OK to access nested state without a store. I think I want to wait and see how usage develops first.

maxg-square · 2025-04-05T22:35:07Z

Samples/ObservableCounter/Sources/CounterListView.swift

+        WithPerceptionTracking {
+            VStack {
+                ForEach(store.scope(collection: \.counters)) { counter in
+                    @Perception.Bindable var counter = counter


I'm a little surprised this works – maybe just stable because counters isn't changing?

Is it possible to have the scope collection method vend a bindable variable, or does that not work?

I'm a little surprised this works – maybe just stable because counters isn't changing?

You mean the shadowing, or the fact that we can wrap it at all? The pattern for a local @Bindable actually comes straight from Apple.

Is it possible to have the scope collection method vend a bindable variable, or does that not work?

That won't work, or more accurately, it's uglier, because you'd lose the property wrapper magic and have to call into counter.wrappedValue or counter.projectedValue manually.

maxg-square · 2025-04-05T22:35:22Z

Samples/ObservableCounter/Sources/CounterListView.swift

+                ForEach(store.scope(collection: \.counters)) { counter in
+                    @Perception.Bindable var counter = counter
+
+                    WithPerceptionTracking {


Does the nested WithPerceptionTracking here do something?

Trying this out locally, removing WithPerceptionTracking triggers those Perception runtime warnings. I think this is because of the binding to the child store being used inside the ForEach escaping closure.

Yep, ForEach is a case that requires nested WithPerceptionTracking.

johnnewman-square

It’s great to have a working solution to this one. The sample app provides good context, too.

jamieQ · 2025-04-07T22:11:10Z

Samples/ObservableCounter/Sources/CounterListView.swift

@@ -0,0 +1,23 @@
+import SwiftUI


commenting here primarily for threading purposes, but wondering if this issue is specific to our setup, or can something analogous be replicated with 'vanilla' SwiftUI?

Specific to our setup. There may be some assumptions built around the state being a reference type that we're running into.

WorkflowSwiftUI/Tests/NestedStoreTests.swift

robmaceachern · 2025-04-08T15:28:54Z

WorkflowSwiftUI/Sources/Store.swift

+    public func scope<Substate: ObservableState>(
+        keyPath: WritableKeyPath<Model.State, Substate>
+    ) -> Store<StateAccessor<Substate>> {


Do you think there's any way to influence autocomplete to exclude collection keypaths?

Not that I'm aware of, unfortunately. I'm pleasantly surprised that the error message is decent.

robmaceachern · 2025-04-08T15:35:39Z

WorkflowSwiftUI/Sources/Store.swift

+    /// Derives a collection of stores from an `IdentifiedArray` of child models.
+    ///
+    /// Stores in the returned collection are lazy created on first access, and invalidated when
+    /// the ID is no longer present in the collection. Reorders do not invalidate.


Reorders do not invalidate.

Is it worth expanding on this a bit? I'm not sure I understand the ramifications.

Hmm, honestly maybe I shouldn't mention store invalidation in the API docs, as that's sort of an implementation detail. What's more important to consumers is knowing how mutations to individual elements will affect access to other elements.

The tl;dr is that on every render we invalidate child stores that are no longer connected to state in case SwiftUI decides to send a value to a stale binding.

robmaceachern · 2025-04-08T15:44:26Z

WorkflowSwiftUI/Tests/NestedStoreTests.swift

+        // mutate element
+        do {
+            var state = State(array: [.init()])
+            let model = StateAccessor(state: state) { update in
+                update(&state)
+            }
+            let (store, _) = Store.make(model: model)
+
+            withPerceptionTracking {
+                _ = store.scope(collection: \.array)
+            } onChange: {
+                XCTFail("Array should not change")
+            }
+
+            withPerceptionTracking {
+                _ = store.scope(collection: \.array)[0]
+            } onChange: {
+                XCTFail("Array element 0 should not change")
+            }
+
+            let array0NameDidChange = expectation(description: "array[0].didChange")
+            withPerceptionTracking {
+                _ = store.scope(collection: \.array)[0].name
+            } onChange: {
+                array0NameDidChange.fulfill()
+            }
+
+            state.array[0].name = "test"
+
+            await fulfillment(of: [array0NameDidChange], timeout: 0)
+        }


🥳 Awesome. Thanks for the great test coverage.

robmaceachern · 2025-04-08T16:07:33Z

WorkflowSwiftUI/Sources/Derived/ObservableState.swift

@@ -113,6 +113,20 @@ public func _$isIdentityEqual<T: ObservableState>(
    lhs._$id == rhs._$id
 }

+@inlinable
+public func _$isIdentityEqual<T: ObservableState>(


Is it worth moving this to a file outside of the Derived folder? It'd probably make diffs between this and the TCA ObservableState easier.

Documentation/WorkflowSwiftUI Adoption Guide.md

even when not needed

watt added 5 commits April 3, 2025 16:16

feat: bump perception dependency

66a3fba

feat: treat nil optionals identical

79b8e62

feat: nested observable state child stores

adc836f

feat: update samples

a65b0bb

docs: improve scoping docs

e0aee35

watt marked this pull request as ready for review April 4, 2025 00:41

watt requested review from a team as code owners April 4, 2025 00:41

watt commented Apr 4, 2025

View reviewed changes

Samples/ObservableCounter/Sources/CounterListView.swift Show resolved Hide resolved

watt commented Apr 4, 2025

View reviewed changes

nsillik reviewed Apr 4, 2025

View reviewed changes

maxg-square reviewed Apr 5, 2025

View reviewed changes

johnnewman-square approved these changes Apr 7, 2025

View reviewed changes

jamieQ reviewed Apr 7, 2025

View reviewed changes

square-tomb approved these changes Apr 7, 2025

View reviewed changes

WorkflowSwiftUI/Tests/NestedStoreTests.swift Outdated Show resolved Hide resolved

watt added 3 commits April 7, 2025 17:25

docs: nested observable state in adoption guide

7a637dd

test: remove a redundant state set

49bc0e0

docs: comment about body evaluation prints

67fc256

robmaceachern approved these changes Apr 8, 2025

View reviewed changes

watt added 2 commits April 9, 2025 13:05

docs: tune documentation around collection stores

28918fd

test: tune tests to use setModel consistently

2a81f39

even when not needed

watt enabled auto-merge (squash) April 9, 2025 20:12

watt merged commit c50ec9b into main Apr 9, 2025
7 checks passed

watt deleted the awatt/observing-array-experiments branch April 9, 2025 20:16

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: nested observable state stores #333

feat: nested observable state stores #333

watt commented Apr 4, 2025 •

edited

Loading

watt Apr 4, 2025

robmaceachern Apr 8, 2025

watt Apr 9, 2025

robmaceachern Apr 9, 2025

watt Apr 4, 2025

watt Apr 4, 2025

nsillik left a comment

watt commented Apr 4, 2025

maxg-square Apr 5, 2025

watt Apr 7, 2025

maxg-square Apr 5, 2025

johnnewman-square Apr 7, 2025 •

edited

Loading

watt Apr 7, 2025

johnnewman-square left a comment

jamieQ Apr 7, 2025 •

edited

Loading

watt Apr 8, 2025

robmaceachern Apr 8, 2025

watt Apr 9, 2025

robmaceachern Apr 8, 2025

watt Apr 9, 2025

robmaceachern Apr 8, 2025

robmaceachern Apr 8, 2025

feat: nested observable state stores #333

feat: nested observable state stores #333

Conversation

watt commented Apr 4, 2025 • edited Loading

Example

Checklist

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

nsillik left a comment

Choose a reason for hiding this comment

watt commented Apr 4, 2025

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

johnnewman-square Apr 7, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

johnnewman-square left a comment

Choose a reason for hiding this comment

jamieQ Apr 7, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

watt commented Apr 4, 2025 •

edited

Loading

johnnewman-square Apr 7, 2025 •

edited

Loading

jamieQ Apr 7, 2025 •

edited

Loading