Scoped Override (#112)

* Implement scoped override feature

* Add comment for future optimization

Author: ra1028

README.md

@@ -1307,33 +1307,52 @@ Note that other atoms that depend on scoped atoms will be in a shared state and
 
 #### Override Atoms
 
-Overriding an atom in [AtomRoot](#atomroot) or [AtomScope](#atomscope) overwrites its state when used in the descendant views, which is useful for dependency injection or swapping state in a particular view.  
+You can override atoms in [AtomRoot](#atomroot) or [AtomScope](#atomscope) to overwirete the atom states for dependency injection or faking state in particular view, which is useful especially for testing.  
+
+Overriding in `AtomRoot` return the given value instead of the actual atom value no matter where the overridden atom is used in its descendant views.  
 
 ```swift
+// Overrides the CounterAtom value to be `456` in anywhere in the ancestor.
+AtomRoot {
+    RootView()
+}
+.override(CounterAtom()) { _ in
+    456
+}
+```
+
+On the other hand, overriding with `AtomScope` behaves similar to overriding in `AtomRoot`, but the atoms used in other scopes nested in the descendants are not overridden.  
+
+```swift
+// Overrides the CounterAtom value to be `456` only for this scope.
 AtomScope {
     CountDisplay()
+
+    // CounterAtom is not overridden in this scope.
+    AtomScope {
+        CountDisplay()
+    }
 }
-.override(CounterAtom()) { _ in
-    456  // Overrides the count to be `456` only for this scope.
+.scopedOverride(CounterAtom()) { _ in
+    456
 }
 ```
 
-Note that when multiple `AtomScope`s are nested, it doesn't inherit the overrides of its ancestor scopes.  
-In this case, you can explicitly inherit overrides from the parent scope by passing a `@ViewContext` context that has gotten in the parent scope.  
+If you want to inherit the overridden atom from the parent scope, you can explicitly pass `@ViewContext` context that has gotten in the parent scope. Then, the new scope completely inherits the parent scope's context.  
 
 ```swift
 @ViewContext
 var context
 
 var body: some {
-    // Inherites the nearest ancester scope's overrides.
+    // Inherites the parent scope's overrides.
     AtomScope(inheriting: context) {
         CountDisplay()
     }
 }
 ```
 
-Note also that overridden atoms will automatically be scoped to the `AtomScope`, but other atoms that depend on them will be in a shared state and must be given `Scoped` attribute (See also: [Scoped Atoms](#scoped-atoms)) in order to scope them as well.  
+Note that overridden atoms in `AtomScope` automatically be scoped, but other atoms that depend on them will be in a shared state and must be given `Scoped` attribute (See also: [Scoped Atoms](#scoped-atoms)) in order to avoid it from being shared across out of scope.  
 
 See [Testing](#testing) section for details on dependency injection on unit tests.  
 
@@ -1501,7 +1520,8 @@ digraph {
 
 #### Preview
 
-Even in SwiftUI previews, the view must have an `AtomRoot` somewhere in the ancestor. However, since This library offers the new solution for dependency injection, you don't need to do painful DI each time you create previews anymore. You can to override the atoms that you really want to inject substitutions.
+Even in SwiftUI previews, the view must have an `AtomRoot` somewhere in the ancestor.  
+To inject dependencies so that display a static preview, define the dependencies as atoms and override them.  
 
 ```swift
 struct NewsList_Preview: PreviewProvider {
@@ -1516,6 +1536,8 @@ struct NewsList_Preview: PreviewProvider {
 }
 ```
 
+ See [Override Atoms](#override-atoms) section for more details of dependency injection.  
+
 ---
 
 ### Advanced Usage

Sources/Atoms/AtomRoot.swift

@@ -17,15 +17,15 @@ import SwiftUI
 /// }
 /// ```
 ///
-/// Optionally, this component allows you to override a value of arbitrary atoms, that's useful
+/// This view allows you to override a value of arbitrary atoms, which is useful
 /// for dependency injection in testing.
 ///
 /// ```swift
 /// AtomRoot {
-///     MyView()
+///     RootView()
 /// }
-/// .override(RepositoryAtom()) {
-///     FakeRepository()
+/// .override(APIClientAtom()) {
+///     StubAPIClient()
 /// }
 /// ```
 ///
@@ -118,34 +118,34 @@ public struct AtomRoot<Content: View>: View {
         mutating(self) { $0.observers.append(Observer(onUpdate: onUpdate)) }
     }
 
-    /// Overrides the atom value with the given value.
+    /// Overrides the atoms with the given value.
     ///
-    /// When accessing the overridden atom, this context will create and return the given value
-    /// instead of the atom value.
+    /// It will create and return the given value instead of the actual atom value when accessing
+    /// the overridden atom in any scopes.
     ///
     /// - Parameters:
     ///   - atom: An atom to be overridden.
     ///   - value: A value to be used instead of the atom's value.
     ///
     /// - Returns: The self instance.
     public func override<Node: Atom>(_ atom: Node, with value: @escaping (Node) -> Node.Loader.Value) -> Self {
-        mutating(self) { $0.overrides[OverrideKey(atom)] = AtomOverride(value: value) }
+        mutating(self) { $0.overrides[OverrideKey(atom)] = AtomOverride(isScoped: false, value: value) }
     }
 
-    /// Overrides the atom value with the given value.
+    /// Overrides the atoms with the given value.
     ///
-    /// Instead of overriding the particular instance of atom, this method overrides any atom that
-    /// has the same metatype.
-    /// When accessing the overridden atom, this context will create and return the given value
-    /// instead of the atom value.
+    /// It will create and return the given value instead of the actual atom value when accessing
+    /// the overridden atom in any scopes.
+    /// This method overrides any atoms that has the same metatype, instead of overriding
+    /// the particular instance of atom.
     ///
     /// - Parameters:
     ///   - atomType: An atom type to be overridden.
     ///   - value: A value to be used instead of the atom's value.
     ///
     /// - Returns: The self instance.
     public func override<Node: Atom>(_ atomType: Node.Type, with value: @escaping (Node) -> Node.Loader.Value) -> Self {
-        mutating(self) { $0.overrides[OverrideKey(atomType)] = AtomOverride(value: value) }
+        mutating(self) { $0.overrides[OverrideKey(atomType)] = AtomOverride(isScoped: false, value: value) }
     }
 }
 
@@ -178,7 +178,8 @@ private extension AtomRoot {
                     inheritedScopeKeys: [:],
                     observers: observers,
                     scopedObservers: [],
-                    overrides: overrides
+                    overrides: overrides,
+                    scopedOverrides: [:]
                 )
             )
         }
@@ -207,7 +208,8 @@ private extension AtomRoot {
                     inheritedScopeKeys: [:],
                     observers: observers,
                     scopedObservers: [],
-                    overrides: overrides
+                    overrides: overrides,
+                    scopedOverrides: [:]
                 )
             )
         }

Sources/Atoms/AtomScope.swift

@@ -2,7 +2,19 @@ import SwiftUI
 
 /// A view to override or monitor atoms in scope.
 ///
-/// This view allows you to monitor changes of atoms used in descendant views by``AtomScope/scopedObserve(_:)``.
+/// This view allows you to override a value of arbitrary atoms used in this scope, which is useful
+/// for dependency injection in testing.
+///
+/// ```swift
+/// AtomScope {
+///     MyView()
+/// }
+/// .scopedOverride(APIClientAtom()) {
+///     StubAPIClient()
+/// }
+/// ```
+///
+/// You can also observe updates with a snapshot that captures a specific set of values of atoms.
 ///
 /// ```swift
 /// AtomScope {
@@ -100,38 +112,38 @@ public struct AtomScope<Content: View>: View {
         mutating(self) { $0.observers.append(Observer(onUpdate: onUpdate)) }
     }
 
-    /// Override the atom value used in this scope with the given value.
+    /// Override the atoms used in this scope with the given value.
     ///
-    /// When accessing the overridden atom, this context will create and return the given value
-    /// instead of the atom value.
+    /// It will create and return the given value instead of the actual atom value when accessing
+    /// the overridden atom in this scope.
     ///
-    /// This only overrides atoms used in this scope and never be inherited to a nested scope.
+    /// This only overrides atoms used in this scope and never be inherited to a nested scopes.
     ///
     /// - Parameters:
     ///   - atom: An atom to be overridden.
     ///   - value: A value to be used instead of the atom's value.
     ///
     /// - Returns: The self instance.
-    public func override<Node: Atom>(_ atom: Node, with value: @escaping (Node) -> Node.Loader.Value) -> Self {
-        mutating(self) { $0.overrides[OverrideKey(atom)] = AtomOverride(value: value) }
+    public func scopedOverride<Node: Atom>(_ atom: Node, with value: @escaping (Node) -> Node.Loader.Value) -> Self {
+        mutating(self) { $0.overrides[OverrideKey(atom)] = AtomOverride(isScoped: true, value: value) }
     }
 
-    /// Override the atom value used in this scope with the given value.
+    /// Override the atoms used in this scope with the given value.
     ///
-    /// Instead of overriding the particular instance of atom, this method overrides any atom that
-    /// has the same metatype.
-    /// When accessing the overridden atom, this context will create and return the given value
-    /// instead of the atom value.
+    /// It will create and return the given value instead of the actual atom value when accessing
+    /// the overridden atom in this scope.
+    /// This method overrides any atoms that has the same metatype, instead of overriding
+    /// the particular instance of atom.
     ///
-    /// This only overrides atoms used in this scope and never be inherited to a nested scope.
+    /// This only overrides atoms used in this scope and never be inherited to a nested scopes.
     ///
     /// - Parameters:
     ///   - atomType: An atom type to be overridden.
     ///   - value: A value to be used instead of the atom's value.
     ///
     /// - Returns: The self instance.
-    public func override<Node: Atom>(_ atomType: Node.Type, with value: @escaping (Node) -> Node.Loader.Value) -> Self {
-        mutating(self) { $0.overrides[OverrideKey(atomType)] = AtomOverride(value: value) }
+    public func scopedOverride<Node: Atom>(_ atomType: Node.Type, with value: @escaping (Node) -> Node.Loader.Value) -> Self {
+        mutating(self) { $0.overrides[OverrideKey(atomType)] = AtomOverride(isScoped: true, value: value) }
     }
 }
 
@@ -181,7 +193,7 @@ private extension AtomScope {
                 \.store,
                 context._store.inherited(
                     scopedObservers: observers,
-                    overrides: overrides
+                    scopedOverrides: overrides
                 )
             )
         }

Sources/Atoms/Context/AtomTestContext.swift

@@ -366,7 +366,7 @@ public struct AtomTestContext: AtomWatchableContext {
     ///   - value: A value to be used instead of the atom's value.
     @inlinable
     public func override<Node: Atom>(_ atom: Node, with value: @escaping (Node) -> Node.Loader.Value) {
-        _state.overrides[OverrideKey(atom)] = AtomOverride(value: value)
+        _state.overrides[OverrideKey(atom)] = AtomOverride(isScoped: false, value: value)
     }
 
     /// Overrides the atom value with the given value.
@@ -381,7 +381,7 @@ public struct AtomTestContext: AtomWatchableContext {
     ///   - value: A value to be used instead of the atom's value.
     @inlinable
     public func override<Node: Atom>(_ atomType: Node.Type, with value: @escaping (Node) -> Node.Loader.Value) {
-        _state.overrides[OverrideKey(atomType)] = AtomOverride(value: value)
+        _state.overrides[OverrideKey(atomType)] = AtomOverride(isScoped: false, value: value)
     }
 }
 
@@ -444,7 +444,8 @@ internal extension AtomTestContext {
             inheritedScopeKeys: [:],
             observers: [],
             scopedObservers: [],
-            overrides: _state.overrides
+            overrides: _state.overrides,
+            scopedOverrides: [:]
         )
     }
 

Sources/Atoms/Core/AtomOverride.swift

@@ -2,16 +2,20 @@
 internal protocol AtomOverrideProtocol {
     associatedtype Node: Atom
 
+    var isScoped: Bool { get }
     var value: (Node) -> Node.Loader.Value { get }
 }
 
 @usableFromInline
 internal struct AtomOverride<Node: Atom>: AtomOverrideProtocol {
+    @usableFromInline
+    let isScoped: Bool
     @usableFromInline
     let value: (Node) -> Node.Loader.Value
 
     @usableFromInline
-    init(value: @escaping (Node) -> Node.Loader.Value) {
+    init(isScoped: Bool, value: @escaping (Node) -> Node.Loader.Value) {
+        self.isScoped = isScoped
         self.value = value
     }
 }

Sources/Atoms/Core/Environment.swift

@@ -16,6 +16,7 @@ private struct StoreEnvironmentKey: EnvironmentKey {
             observers: [],
             scopedObservers: [],
             overrides: [:],
+            scopedOverrides: [:],
             enablesAssertion: true
         )
     }