Simplify ViewEnvironmentUI protocols

Author: n8chur

ViewEnvironmentUI/Sources/ViewEnvironmentCustomizing.swift

@@ -16,14 +16,14 @@
 
 import ViewEnvironment
 
-/// `ViewEnvironmentObserving` allows an environment propagation node to observe updates to the
+/// `ViewEnvironmentPropagating` allows an environment propagation node to observe updates to the
 /// `ViewEnvironment` as it flows through the node hierarchy and have
 /// the environment applied to the node.
 ///
 /// For example, for a `UIViewController` hierarchy observing `ViewEnvironment`:
 /// ```swift
 /// final class MyViewController:
-///     UIViewController, ViewEnvironmentObserving
+///     UIViewController, ViewEnvironmentPropagating
 /// {
 ///     override func viewWillLayoutSubviews() {
 ///         super.viewWillLayoutSubviews()
@@ -47,9 +47,18 @@ import ViewEnvironment
 /// - Important: `UIViewController` and `UIView` conformers _must_ call ``applyEnvironmentIfNeeded()-3bamq``
 ///   in `viewWillLayoutSubviews()` and `layoutSubviews()` respectively.
 ///
-/// - Tag: ViewEnvironmentObserving
-///
-public protocol ViewEnvironmentObserving: ViewEnvironmentCustomizing {
+public protocol ViewEnvironmentObserving: ViewEnvironmentPropagating {
+    /// Customizes the `ViewEnvironment` as it flows through this propagation node to provide overrides to environment
+    /// values. These changes will be propagated to all descendant nodes.
+    ///
+    /// If you'd like to just inherit the environment from above, leave this function body empty.
+    ///
+    /// - Important: `UIViewController` and `UIView` conformers _must_ call
+    ///   ``ViewEnvironmentObserving/applyEnvironmentIfNeeded()-8gr5k``in `viewWillLayoutSubviews()` and
+    ///   `layoutSubviews()` respectively.
+    ///
+    func customize(environment: inout ViewEnvironment)
+
     /// Consumers should apply the `ViewEnvironment` to their node when this function is called.
     ///
     /// - Important: `UIViewController` and `UIView` conformers _must_ call ``applyEnvironmentIfNeeded()-3bamq``
@@ -66,11 +75,25 @@ public protocol ViewEnvironmentObserving: ViewEnvironmentCustomizing {
     ///
     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()
+
+    @_spi(ViewEnvironmentWiring)
+    var _environmentOverride: ViewEnvironment { get }
 }
 
 extension ViewEnvironmentObserving {
+    public func customize(environment: inout ViewEnvironment) {}
+
     public func apply(environment: ViewEnvironment) {}
 
     public func environmentDidChange() {}
+
+    // Using SPI for this property will cause consumers to be unable to synthesize the default implementation if they do
+    // not @_spi(ViewEnvironmentWiring) import ViewEnvironmentUI.
+    public var _environmentOverride: ViewEnvironment { _defaultEnvironment }
 }

ViewEnvironmentUI/Sources/ViewEnvironmentObserving.swift

@@ -16,6 +16,37 @@
 
 import ViewEnvironment
 
+/// `ViewEnvironmentPropagating` allows an environment propagation node to observe updates to the
+/// `ViewEnvironment` as it flows through the node hierarchy and have
+/// the environment applied to the node.
+///
+/// For example, for a `UIViewController` hierarchy observing `ViewEnvironment`:
+/// ```swift
+/// final class MyViewController:
+///     UIViewController, ViewEnvironmentPropagating
+/// {
+///     override func viewWillLayoutSubviews() {
+///         super.viewWillLayoutSubviews()
+///
+///         // You _must_ call this function in viewWillLayoutSubviews()
+///         applyEnvironmentIfNeeded()
+///     }
+///
+///     func apply(environment: ViewEnvironment) {
+///         // Apply values from the environment to your view controller (e.g. a theme)
+///     }
+///
+///     // If you'd like to override values in the environment you can provide them here. If you'd
+///     // like to just inherit the context from above there is no need to implement this function.
+///     func customize(environment: inout ViewEnvironment) {
+///         environment.traits.mode = .dark
+///     }
+/// }
+/// ```
+///
+/// - Important: `UIViewController` and `UIView` conformers _must_ call ``applyEnvironmentIfNeeded()-3bamq``
+///   in `viewWillLayoutSubviews()` and `layoutSubviews()` respectively.
+///
 public protocol ViewEnvironmentPropagating {
     /// Calling this will flag this node for needing to update the `ViewEnvironment`. For `UIView`/`UIViewController`,
     /// this will occur on the next layout pass (`setNeedsLayout` will be called on the caller's behalf).
@@ -39,6 +70,10 @@ public protocol ViewEnvironmentPropagating {
     /// ``ViewEnvironmentPropagatingObject/environmentAncestorOverride`` property.  If no override is present, the
     /// return value will be `parent ?? presentingViewController`/`superview`.
     ///
+    /// If the value of the ancestor is `nil`, by default, ancestors will not call notify this node of needing an
+    /// environment update as it changes. This allows a node to effectively act as a root node when needed (e.g.
+    /// bridging from other propagation systems like WorkflowUI).
+    ///
     @_spi(ViewEnvironmentWiring)
     var environmentAncestor: ViewEnvironmentPropagating? { get }
 
@@ -54,34 +89,6 @@ public protocol ViewEnvironmentPropagating {
     ///
     @_spi(ViewEnvironmentWiring)
     var environmentDescendants: [ViewEnvironmentPropagating] { get }
-
-    /// The `ViewEnvironment` that is flowing through the propagation hierarchy.
-    ///
-    /// If you'd like to provide overrides for the environment as it flows through a node, you should conform to
-    /// `ViewEnvironmentObserving` and provide those overrides in `customize(environment:)`. E.g.:
-    /// ```swift
-    /// func customize(environment: inout ViewEnvironment) {
-    ///     environment.traits.mode = .dark
-    /// }
-    /// ```
-    ///
-    /// By default, this property gets the environment by recursively walking to the root of the
-    /// propagation path, and applying customizations on the way back down. You may override this
-    /// property instead if you want to completely interrupt the propagation flow and replace the
-    /// environment. You can get the default value that would normally be propagated by calling
-    /// `_defaultViewEnvironment`.
-    ///
-    /// If you'd like to update the return value of this variable and have those changes propagated through the
-    /// propagation hierarchy, conform to `ViewEnvironmentObserving` and call ``setNeedsEnvironmentUpdate()`` and wait
-    /// for the system to call `apply(context:)` when appropriate (e.g. on the next layout pass for
-    /// `UIViewController`/`UIView` subclasses).
-    ///
-    /// - Important: `UIViewController` and `UIView` conformers _must_ call
-    /// ``ViewEnvironmentObserving/applyEnvironmentIfNeeded()-8gr5k`` in `viewWillLayoutSubviews()` and
-    /// `layoutSubviews()` respectively.
-    ///
-    @_spi(ViewEnvironmentWiring)
-    var environment: ViewEnvironment { get }
 }
 
 extension ViewEnvironmentPropagating {
@@ -99,7 +106,7 @@ extension ViewEnvironmentPropagating {
     /// propagation path, and applying customizations on the way back down. You may override this
     /// property instead if you want to completely interrupt the propagation flow and replace the
     /// environment. You can get the default value that would normally be propagated by calling
-    /// `_defaultViewEnvironment`.
+    /// `_defaultEnvironment`.
     ///
     /// If you'd like to update the return value of this variable and have those changes propagated through the
     /// propagation hierarchy, conform to `ViewEnvironmentObserving` and call ``setNeedsEnvironmentUpdate()`` and wait
@@ -111,7 +118,7 @@ extension ViewEnvironmentPropagating {
     /// `layoutSubviews()` respectively.
     ///
     public var environment: ViewEnvironment {
-        _defaultViewEnvironment
+        (self as? ViewEnvironmentObserving)?._environmentOverride ?? _defaultEnvironment
     }
 
     /// The default `ViewEnvironment` returned by ``environment``.
@@ -122,15 +129,30 @@ extension ViewEnvironmentPropagating {
     ///  You should only need to access this value if you are overriding ``environment``
     /// and want to conditionally return the default.
     @_spi(ViewEnvironmentWiring)
-    public var _defaultViewEnvironment: ViewEnvironment {
-        var environment = environmentAncestor?.environment
-            ?? .empty
+    public var _defaultEnvironment: ViewEnvironment {
+        var environment: ViewEnvironment = {
+            guard let ancestor = environmentAncestor else {
+                return .empty
+            }
+
+            if let observing = ancestor as? ViewEnvironmentObserving {
+                return observing.environment
+            }
 
-        (self as? ViewEnvironmentCustomizing)?.customize(environment: &environment)
+            return ancestor._defaultEnvironment
+        }()
+
+        if let observing = self as? ViewEnvironmentObserving {
+            observing.customize(environment: &environment)
+        }
 
         return environment
     }
 
+    /// Notifies all appropriate descendants that the environment needs update.
+    ///
+    /// If a descendant's ancestor is `nil` it will not be notified of needing update.
+    ///
     @_spi(ViewEnvironmentWiring)
     public func setNeedsEnvironmentUpdateOnAppropriateDescendants() {
         for descendant in environmentDescendants {

ViewEnvironmentUI/Sources/ViewEnvironmentPropagating.swift

@@ -45,13 +45,16 @@ public protocol ViewEnvironmentPropagatingObject: AnyObject, ViewEnvironmentProp
     func setNeedsApplyEnvironment()
 }
 
-extension ViewEnvironmentObserving where Self: ViewEnvironmentPropagatingObject {
+extension ViewEnvironmentPropagating where Self: ViewEnvironmentPropagatingObject {
     public func applyEnvironmentIfNeeded() {
         guard needsEnvironmentUpdate else { return }
 
         needsEnvironmentUpdate = false
 
-        apply(environment: environment)
+        if let observing = self as? ViewEnvironmentObserving {
+            let environment = observing.environment
+            observing.apply(environment: environment)
+        }
     }
 }
 
@@ -216,17 +219,15 @@ extension ViewEnvironmentPropagatingObject {
 
         if let observing = self as? ViewEnvironmentObserving {
             observing.environmentDidChange()
-        }
 
-        if !needsUpdateObservers.isEmpty {
-            let environment = self.environment
+            if !needsUpdateObservers.isEmpty {
+                let environment = observing.environment
 
-            for observer in needsUpdateObservers.values {
-                observer(environment)
+                for observer in needsUpdateObservers.values {
+                    observer(environment)
+                }
             }
-        }
 
-        if self is ViewEnvironmentObserving {
             setNeedsApplyEnvironment()
         }
 

ViewEnvironmentUI/Sources/ViewEnvironmentPropagatingObject.swift

@@ -22,7 +22,7 @@ import ViewEnvironment
 /// environment as it flows between two nodes.
 ///
 @_spi(ViewEnvironmentWiring)
-public class ViewEnvironmentPropagationNode: ViewEnvironmentCustomizing, ViewEnvironmentObserving {
+public class ViewEnvironmentPropagationNode: ViewEnvironmentPropagatingObject, ViewEnvironmentObserving {
     public typealias EnvironmentAncestorProvider = () -> ViewEnvironmentPropagating?
 
     public typealias EnvironmentDescendantsProvider = () -> [ViewEnvironmentPropagating]
@@ -47,8 +47,6 @@ public class ViewEnvironmentPropagationNode: ViewEnvironmentCustomizing, ViewEnv
         didSet { setNeedsEnvironmentUpdate() }
     }
 
-    private var needsEnvironmentUpdate: Bool = true
-
     public init(
         environmentAncestor: @escaping EnvironmentAncestorProvider = { nil },
         environmentDescendants: @escaping EnvironmentDescendantsProvider = { [] },
@@ -63,20 +61,20 @@ public class ViewEnvironmentPropagationNode: ViewEnvironmentCustomizing, ViewEnv
         self.applyEnvironment = applyEnvironment
     }
 
-    public var environmentAncestor: ViewEnvironmentPropagating? { environmentAncestorProvider() }
-
-    public var environmentDescendants: [ViewEnvironmentPropagating] { environmentDescendantsProvider() }
-
-    public func customize(environment: inout ViewEnvironment) {
-        customizeEnvironment(&environment)
+    public var defaultEnvironmentAncestor: ViewEnvironmentPropagating? {
+        environmentAncestorProvider()
     }
 
-    public func setNeedsEnvironmentUpdate() {
-        needsEnvironmentUpdate = true
+    public var defaultEnvironmentDescendants: [ViewEnvironmentPropagating] {
+        environmentDescendantsProvider()
+    }
 
-        environmentDidChange()
+    public func setNeedsApplyEnvironment() {
+        applyEnvironmentIfNeeded()
+    }
 
-        setNeedsEnvironmentUpdateOnAppropriateDescendants()
+    public func customize(environment: inout ViewEnvironment) {
+        customizeEnvironment(&environment)
     }
 
     public func environmentDidChange() {
@@ -85,14 +83,6 @@ public class ViewEnvironmentPropagationNode: ViewEnvironmentCustomizing, ViewEnv
         didChange(environment)
     }
 
-    public func applyEnvironmentIfNeeded() {
-        guard needsEnvironmentUpdate else { return }
-
-        needsEnvironmentUpdate = false
-
-        apply(environment: environment)
-    }
-
     public func apply(environment: ViewEnvironment) {
         applyEnvironment(environment)
     }

ViewEnvironmentUI/Sources/ViewEnvironmentPropagationNode.swift

@@ -76,6 +76,8 @@ public final class WorkflowHostingController<ScreenType, Output>: UIViewControll
             .observeValues { [weak self] screen in
                 self?.update(screen: screen)
             }
+
+        setNeedsEnvironmentUpdate()
     }
 
     /// Updates the root Workflow in this container.
@@ -180,7 +182,7 @@ public final class WorkflowHostingController<ScreenType, Output>: UIViewControll
     }
 }
 
-extension WorkflowHostingController: ViewEnvironmentCustomizing, ViewEnvironmentObserving {
+extension WorkflowHostingController: ViewEnvironmentObserving {
     public func customize(environment: inout ViewEnvironment) {
         customizeEnvironment(&environment)
     }

WorkflowUI/Sources/Hosting/WorkflowHostingController.swift

@@ -213,7 +213,7 @@ extension ViewControllerDescription {
 }
 
 extension ViewControllerDescription {
-    fileprivate struct PropagationNode: ViewEnvironmentCustomizing {
+    fileprivate struct PropagationNode: ViewEnvironmentObserving {
         typealias EnvironmentAncestorProvider = () -> ViewEnvironmentPropagating?
 
         typealias EnvironmentDescendantsProvider = () -> [ViewEnvironmentPropagating]
@@ -253,6 +253,10 @@ extension ViewControllerDescription {
         func setNeedsEnvironmentUpdate() {
             setNeedsEnvironmentUpdateOnAppropriateDescendants()
         }
+
+        func applyEnvironmentIfNeeded() {
+            /// `apply(environment:)` is not implemented so do nothing.
+        }
     }
 }