Update docs for next release (#2238)

* Update docs for next release

* wip

* fix deprecations

---------

Co-authored-by: Brandon Williams <[email protected]>

Author: stephencelis

Sources/ComposableArchitecture/Documentation.docc/Articles/Bindings.md

@@ -231,11 +231,10 @@ struct Settings: ReducerProtocol {
 }
 ```
 
-Binding actions are constructed and sent to the store by calling
-``ViewStore/binding(_:fileID:line:)`` with a key path to the binding state:
+Binding actions are constructed and sent to the store by invoking dynamic member lookup on the view:
 
 ```swift
-TextField("Display name", text: viewStore.binding(\.$displayName))
+TextField("Display name", text: viewStore.$displayName)
 ```
 
 Should you need to layer additional functionality over these bindings, your reducer can pattern
@@ -274,3 +273,103 @@ store.send(.set(\.$protectMyPosts, true)) {
   $0.protectMyPosts = true
 )
 ```
+
+> Tip: If you use `@BindingState` on a larger struct and would like to observe changes to smaller
+> fields, apply the ``ReducerProtocol/onChange(of:_:)`` modifier to the ``BindingReducer``:
+>
+> ```swift
+> struct Settings: ReducerProtocol {
+>   struct State {
+>     @BindingState var developerSettings: DeveloperSettings
+>     // ...
+>   }
+>   // ...
+>   var body: some ReducerProtocol<State, Action> {
+>     BindingReducer()
+>       .onChange(of: \.developerSettings.showDiagnostics) { oldValue, newValue in
+>         // Logic for when `showDiagnostics` changes...
+>       }
+> 
+>     // ...
+>   }
+> }
+> ```
+
+### Binding view state and binding view stores
+
+When a view store observes state bundled up in a "view state" struct (as described in
+<doc:Performance#View-stores>), a couple additional tools are required. First, the `ViewState`
+struct must annotate the fields it will hold onto with the ``BindingViewState`` property wrapper:
+
+```swift
+struct NotificationSettingsView: View {
+  let store: StoreOf<Settings>
+
+  struct ViewState: Equatable {
+    @BindingViewState var enableNotifications: Bool
+    @BindingViewState var sendEmailNotifications: Bool
+    @BindingViewState var sendMobileNotifications: Bool
+  }
+
+  // ...
+}
+```
+
+And then, when the view store is constructed, we can invoke the
+``WithViewStore/init(_:observe:content:file:line:)-4gpoj`` initializer, which is handed a
+``BindingViewStore`` that can produce ``BindingViewState`` values from a store:
+
+```swift
+struct NotificationSettingsView: View {
+  // ...
+
+  var body: some View {
+    WithViewStore(
+      self.store,
+      observe: { bindingViewStore in
+        ViewState(
+          enableNotifications: bindingViewStore.$enableNotifications,
+          sendEmailNotifications: bindingViewStore.$sendEmailNotifications,
+          sendMobileNotifications: bindingViewStore.$sendMobileNotifications
+        )
+      }
+    ) {
+      // ...
+    }
+  }
+}
+```
+
+We recommend extracting this work to simplify the call site, _e.g._ with an initializer on your
+`ViewState` struct:
+
+```swift
+struct NotificationSettingsView: View {
+  // ...
+  struct ViewState: Equatable {
+    // ...
+
+    init(bindingViewStore: BindingViewStore<Settings.State>) {
+      self._enableNotifications = bindingViewStore.$enableNotifications
+      self._sendEmailNotifications = bindingViewStore.$sendEmailNotifications
+      self._sendMobileNotifications = bindingViewStore.$sendMobileNotifications
+    }
+  }
+
+  var body: some View {
+    WithViewStore(self.store, ViewStore.init) { viewStore in
+      // ...
+    }
+  }
+}
+```
+
+Finally, you can use dynamic member lookup on the view store to pluck out any view state bindings:
+
+```swift
+Form {
+  Toggle("Enable notifications", isOn: viewStore.$enableNotifications)
+
+  // ...
+}
+```

Sources/ComposableArchitecture/Documentation.docc/ComposableArchitecture.md

@@ -63,7 +63,7 @@ day-to-day when building applications, such as:
 
 ### Integrations
 
-- <doc:SwiftUI>
+- <doc:SwiftUIIntegration>
 - <doc:UIKit>
 
 ### Testing

Sources/ComposableArchitecture/Documentation.docc/Extensions/Deprecations/SwiftUIDeprecations.md

@@ -12,9 +12,10 @@ Avoid using deprecated APIs in your app. Select a method to see the replacement
 
 - ``ActionSheetState``
 
-### BindableState
+### Bindings
 
 - ``BindableState``
+- ``ViewStore/binding(_:fileID:line:)``
 
 ### ForEachStore
 

Sources/ComposableArchitecture/Documentation.docc/Extensions/ReducerProtocol.md

@@ -33,6 +33,7 @@
 
 - ``dependency(_:_:)``
 - ``transformDependency(_:transform:)``
+- ``onChange(of:_:)``
 - ``signpost(_:log:)``
 - ``_printChanges(_:)``
 

Sources/ComposableArchitecture/Documentation.docc/Extensions/Store.md

@@ -11,6 +11,14 @@
 
 - ``scope(state:action:)-9iai9``
 
+### Accessing state
+
+- ``withState(_:)``
+
+### Sending actions
+
+- ``send(_:)``
+
 ### Combine integration
 
 - ``StorePublisher``

Sources/ComposableArchitecture/Documentation.docc/Extensions/SwiftUI.md renamed to Sources/ComposableArchitecture/Documentation.docc/Extensions/SwiftUIIntegration.md

@@ -4,7 +4,8 @@ Integrating the Composable Architecture into a SwiftUI application.
 
 ## Overview
 
-The Composable Architecture can be used to power applications built in many frameworks, but it was designed with SwiftUI in mind, and comes with many powerful tools to integrate into your SwiftUI applications.
+The Composable Architecture can be used to power applications built in many frameworks, but it was
+designed with SwiftUI in mind, and comes with many powerful tools to integrate into your SwiftUI applications.
 
 ## Topics
 
@@ -24,7 +25,8 @@ The Composable Architecture can be used to power applications built in many fram
 - ``BindableAction``
 - ``BindingAction``
 - ``BindingReducer``
-- ``ViewStore/binding(_:fileID:line:)``
+- ``BindingViewState``
+- ``BindingViewStore``
 
 <!--DocC: Can't currently document `View` extensions-->
 <!--### View Modifiers-->

Sources/ComposableArchitecture/SwiftUI/Alert.swift

@@ -42,11 +42,11 @@ extension View {
               switch button.action.type {
               case let .send(action):
                 if let action = action {
-                  _ = store.send(.presented(fromDestinationAction(action)))
+                  store.send(.presented(fromDestinationAction(action)))
                 }
               case let .animatedSend(action, animation):
                 if let action = action {
-                  _ = withAnimation(animation) {
+                  withAnimation(animation) {
                     store.send(.presented(fromDestinationAction(action)))
                   }
                 }

Sources/ComposableArchitecture/SwiftUI/Binding.swift

@@ -151,6 +151,10 @@ extension BindableAction {
   }
 }
 
+/// A property wrapper type that can designate properties of view state that can be directly
+/// bindable in SwiftUI views.
+///
+/// Read <doc:Bindings> for more information.
 @propertyWrapper
 public struct BindingViewState<Value> {
   let binding: Binding<Value>
@@ -196,6 +200,9 @@ where Value: CustomDebugStringConvertible {
   }
 }
 
+/// A property wrapper type that can derive ``BindingViewState`` values for a ``ViewStore``.
+///
+/// Read <doc:Bindings> for more information.
 @dynamicMemberLookup
 @propertyWrapper
 public struct BindingViewStore<State> {
@@ -271,6 +278,19 @@ public struct BindingViewStore<State> {
 }
 
 extension WithViewStore where Content: View {
+  /// Initializes a structure that transforms a ``Store`` into an observable ``ViewStore`` in order
+  /// to compute bindings and views from state.
+  ///
+  /// Read <doc:Bindings> for more information.
+  /// 
+  /// - Parameters:
+  ///   - store: A store.
+  ///   - toViewState: A function that transforms binding store state into observable view state.
+  ///     All changes to the view state will cause the `WithViewStore` to re-compute its view.
+  ///   - fromViewAction: A function that transforms view actions into store action.
+  ///   - isDuplicate: A function to determine when two `ViewState` values are equal. When values
+  ///     are equal, repeat view computations are removed,
+  ///   - content: A function that can generate content from a view store.
   public init<State, Action>(
     _ store: Store<State, Action>,
     observe toViewState: @escaping (BindingViewStore<State>) -> ViewState,
@@ -298,6 +318,18 @@ extension WithViewStore where Content: View {
     )
   }
 
+  /// Initializes a structure that transforms a ``Store`` into an observable ``ViewStore`` in order
+  /// to compute bindings and views from state.
+  ///
+  /// Read <doc:Bindings> for more information.
+  ///
+  /// - Parameters:
+  ///   - store: A store.
+  ///   - toViewState: A function that transforms binding store state into observable view state.
+  ///     All changes to the view state will cause the `WithViewStore` to re-compute its view.
+  ///   - isDuplicate: A function to determine when two `ViewState` values are equal. When values
+  ///     are equal, repeat view computations are removed,
+  ///   - content: A function that can generate content from a view store.
   public init<State>(
     _ store: Store<State, ViewAction>,
     observe toViewState: @escaping (BindingViewStore<State>) -> ViewState,
@@ -319,6 +351,17 @@ extension WithViewStore where Content: View {
 }
 
 extension WithViewStore where ViewState: Equatable, Content: View {
+  /// Initializes a structure that transforms a ``Store`` into an observable ``ViewStore`` in order
+  /// to compute bindings and views from state.
+  ///
+  /// Read <doc:Bindings> for more information.
+  ///
+  /// - Parameters:
+  ///   - store: A store.
+  ///   - toViewState: A function that transforms binding store state into observable view state.
+  ///     All changes to the view state will cause the `WithViewStore` to re-compute its view.
+  ///   - fromViewAction: A function that transforms view actions into store action.
+  ///   - content: A function that can generate content from a view store.
   public init<State, Action>(
     _ store: Store<State, Action>,
     observe toViewState: @escaping (BindingViewStore<State>) -> ViewState,
@@ -338,6 +381,16 @@ extension WithViewStore where ViewState: Equatable, Content: View {
     )
   }
 
+  /// Initializes a structure that transforms a ``Store`` into an observable ``ViewStore`` in order
+  /// to compute bindings and views from state.
+  ///
+  /// Read <doc:Bindings> for more information.
+  ///
+  /// - Parameters:
+  ///   - store: A store.
+  ///   - toViewState: A function that transforms binding store state into observable view state.
+  ///     All changes to the view state will cause the `WithViewStore` to re-compute its view.
+  ///   - content: A function that can generate content from a view store.
   public init<State>(
     _ store: Store<State, ViewAction>,
     observe toViewState: @escaping (BindingViewStore<State>) -> ViewState,
@@ -388,11 +441,26 @@ extension ViewStore where ViewAction: BindableAction, ViewAction.State == ViewSt
     )
   }
 
-  // TODO: Deprecate?
-  /// Returns a binding to the resulting binding state of a given key path.
-  ///
-  /// - Parameter keyPath: A key path to a specific binding state.
-  /// - Returns: A new binding.
+  @available(
+    iOS,
+    deprecated: 9999,
+    message: "Use 'viewStore.$value' instead."
+  )
+  @available(
+    macOS,
+    deprecated: 9999,
+    message: "Use 'viewStore.$value' instead."
+  )
+  @available(
+    tvOS,
+    deprecated: 9999,
+    message: "Use 'viewStore.$value' instead."
+  )
+  @available(
+    watchOS,
+    deprecated: 9999,
+    message: "Use 'viewStore.$value' instead."
+  )
   public func binding<Value: Equatable>(
     _ keyPath: WritableKeyPath<ViewState, BindingState<Value>>,
     fileID: StaticString = #fileID,