Add environmentDidChange observation option

Author: n8chur

ViewEnvironmentUI/Sources/ViewEnvironmentObserving.swift

@@ -74,10 +74,19 @@ public protocol ViewEnvironmentObserving: ViewEnvironmentPropagating {
     /// - Tag: ViewEnvironmentObserving.applyEnvironmentIfNeeded
     ///
     func applyEnvironmentIfNeeded()
+
+    /// Called when the environment has been set for needing update, but before it has been applied.
+    ///
+    /// This may be called frequently when compared to ``apply(environment:)`` which should only be called
+    /// when it's appropriate to apply the environment to the backing object (e.g. `viewWillLayoutSubviews`).
+    ///
+    func environmentDidChange()
 }
 
 extension ViewEnvironmentObserving {
     public func customize(environment: inout ViewEnvironment) {}
 
     public func apply(environment: ViewEnvironment) {}
+
+    public func environmentDidChange() {}
 }

ViewEnvironmentUI/Sources/ViewEnvironmentPropagatingObject.swift

@@ -225,7 +225,11 @@ extension ViewEnvironmentPropagatingObject {
             }
         }
 
-        setNeedsApplyEnvironment()
+        if let observer = self as? ViewEnvironmentObserving {
+            observer.environmentDidChange()
+
+            setNeedsApplyEnvironment()
+        }
 
         setNeedsEnvironmentUpdateOnAppropriateDescendants()
     }

ViewEnvironmentUI/Sources/ViewEnvironmentPropagationNode.swift

@@ -39,6 +39,10 @@ public class ViewEnvironmentPropagationNode: ViewEnvironmentPropagatingObject, V
         didSet { setNeedsEnvironmentUpdate() }
     }
 
+    public var environmentDidChangeObserver: ((ViewEnvironment) -> Void)? {
+        didSet { setNeedsEnvironmentUpdate() }
+    }
+
     public var applyEnvironment: (ViewEnvironment) -> Void {
         didSet { setNeedsEnvironmentUpdate() }
     }
@@ -47,11 +51,13 @@ public class ViewEnvironmentPropagationNode: ViewEnvironmentPropagatingObject, V
         environmentAncestor: @escaping EnvironmentAncestorProvider = { nil },
         environmentDescendants: @escaping EnvironmentDescendantsProvider = { [] },
         customizeEnvironment: @escaping (inout ViewEnvironment) -> Void = { _ in },
+        environmentDidChange: ((ViewEnvironment) -> Void)? = nil,
         applyEnvironment: @escaping (ViewEnvironment) -> Void = { _ in }
     ) {
         self.environmentAncestorProvider = environmentAncestor
         self.environmentDescendantsProvider = environmentDescendants
         self.customizeEnvironment = customizeEnvironment
+        self.environmentDidChangeObserver = environmentDidChange
         self.applyEnvironment = applyEnvironment
     }
 
@@ -71,6 +77,12 @@ public class ViewEnvironmentPropagationNode: ViewEnvironmentPropagatingObject, V
         customizeEnvironment(&environment)
     }
 
+    public func environmentDidChange() {
+        guard let didChange = environmentDidChangeObserver else { return }
+
+        didChange(environment)
+    }
+
     public func apply(environment: ViewEnvironment) {
         applyEnvironment(environment)
     }

ViewEnvironmentUI/Tests/ViewEnvironmentObservingTests.swift

@@ -164,6 +164,48 @@ final class ViewEnvironmentObservingTests: XCTestCase {
         window.resignKey()
     }
 
+    // MARK: - environmentDidChange
+
+    func test_environmentDidChange() {
+        var rootEnvironmentDidChangeCallCount = 0
+        let rootNode = ViewEnvironmentPropagationNode(
+            environmentDidChange: { _ in
+                rootEnvironmentDidChangeCallCount += 1
+            }
+        )
+        XCTAssertEqual(rootEnvironmentDidChangeCallCount, 0)
+
+        let viewController = UIViewController()
+        rootNode.environmentDescendantsProvider = { [viewController] }
+
+        // Setting an environmentDescendantsProvider on ViewEnvironmentPropagationNode triggers a
+        // setNeedsEnvironmentUpdate()
+        XCTAssertEqual(rootEnvironmentDidChangeCallCount, 1)
+
+        viewController.environmentAncestorOverride = { [weak rootNode] in
+            rootNode
+        }
+
+        var leafEnvironmentDidChangeCallCount = 0
+        let leafNode = ViewEnvironmentPropagationNode(
+            environmentAncestor:  { [weak viewController] in
+                viewController
+            },
+            environmentDidChange: { _ in
+                leafEnvironmentDidChangeCallCount += 1
+            }
+        )
+        viewController.environmentDescendantsOverride = { [leafNode] }
+
+        XCTAssertEqual(rootEnvironmentDidChangeCallCount, 1)
+        XCTAssertEqual(leafEnvironmentDidChangeCallCount, 0)
+
+        rootNode.setNeedsEnvironmentUpdate()
+
+        XCTAssertEqual(rootEnvironmentDidChangeCallCount, 2)
+        XCTAssertEqual(leafEnvironmentDidChangeCallCount, 1)
+    }
+
     // MARK: - Overridden Flow
 
     func test_ancestor_customFlow() {