[DNR WIP] Prototype: UIKit bridging with simplified ViewEnvironmentUI

Development.podspec

@@ -18,6 +18,7 @@ Pod::Spec.new do |s|
   s.dependency 'WorkflowCombine'
   s.dependency 'WorkflowConcurrency'
   s.dependency 'ViewEnvironment'
+  s.dependency 'ViewEnvironmentUI'
 
   s.source_files = 'Samples/Dummy.swift'
 

RELEASING.md

@@ -17,7 +17,7 @@ For Squares, membership is managed through the `Workflow Swift Owners` registry
 
 > ⚠️ [Optional] To avoid possible headaches when publishing podspecs, validation can be performed before updating the Workflow version number(s). To do this, run the following in the root directory of this repo:
 > ```bash
-> bundle exec pod lib lint Workflow.podspec ViewEnvironment.podspec WorkflowTesting.podspec WorkflowReactiveSwift.podspec WorkflowUI.podspec WorkflowRxSwift.podspec WorkflowReactiveSwiftTesting.podspec WorkflowRxSwiftTesting.podspec WorkflowSwiftUI.podspec WorkflowCombine.podspec WorkflowCombineTesting.podspec WorkflowConcurrency.podspec WorkflowConcurrencyTesting.podspec
+> bundle exec pod lib lint Workflow.podspec ViewEnvironment.podspec ViewEnvironmentUI.podspec WorkflowTesting.podspec WorkflowReactiveSwift.podspec WorkflowUI.podspec WorkflowRxSwift.podspec WorkflowReactiveSwiftTesting.podspec WorkflowRxSwiftTesting.podspec WorkflowSwiftUI.podspec WorkflowCombine.podspec WorkflowCombineTesting.podspec WorkflowConcurrency.podspec WorkflowConcurrencyTesting.podspec
 > ```
 
 1. Update `VERSION` file based on [`semver`](https://semver.org/).
@@ -37,6 +37,7 @@ For Squares, membership is managed through the `Workflow Swift Owners` registry
     bundle exec pod trunk push WorkflowTesting.podspec  --synchronous
     bundle exec pod trunk push WorkflowReactiveSwift.podspec --synchronous
     bundle exec pod trunk push ViewEnvironment.podspec --synchronous
+    bundle exec pod trunk push ViewEnvironmentUI.podspec --synchronous
     bundle exec pod trunk push WorkflowUI.podspec --synchronous
     bundle exec pod trunk push WorkflowRxSwift.podspec --synchronous
     bundle exec pod trunk push WorkflowReactiveSwiftTesting.podspec --synchronous

ViewEnvironmentUI.podspec

@@ -0,0 +1,37 @@
+require_relative('version')
+
+Pod::Spec.new do |s|
+    s.name = 'ViewEnvironmentUI'
+    s.version = WORKFLOW_VERSION
+    s.summary = 'Provides a way to propagate a ViewEnvironment through an imperative hierarchy'
+    s.homepage     = 'https://www.github.com/square/workflow-swift'
+    s.license      = 'Apache License, Version 2.0'
+    s.author       = 'Square'
+    s.source       = { :git => 'https://github.com/square/workflow-swift.git', :tag => "v#{s.version}" }
+
+    # 1.7 is needed for `swift_versions` support
+    s.cocoapods_version = '>= 1.7.0'
+
+    s.swift_versions = [WORKFLOW_SWIFT_VERSION]
+    s.ios.deployment_target = WORKFLOW_IOS_DEPLOYMENT_TARGET
+    s.osx.deployment_target = WORKFLOW_MACOS_DEPLOYMENT_TARGET
+
+    s.source_files = 'ViewEnvironmentUI/Sources/**/*.swift'
+
+    s.dependency 'ViewEnvironment', "#{s.version}"
+
+    s.pod_target_xcconfig = { 'APPLICATION_EXTENSION_API_ONLY' => 'YES' }
+
+    s.test_spec 'Tests' do |test_spec|
+        test_spec.source_files = 'ViewEnvironmentUI/Tests/**/*.swift'
+        test_spec.framework = 'XCTest'
+        test_spec.library = 'swiftos'
+        test_spec.dependency 'WorkflowReactiveSwift', "#{s.version}"
+
+        # Create an app host so that we can host
+        # view or view controller based tests in a real environment.
+        test_spec.requires_app_host = true
+
+        test_spec.pod_target_xcconfig = { 'APPLICATION_EXTENSION_API_ONLY' => 'NO' }
+    end
+end

ViewEnvironmentUI/README.md

@@ -0,0 +1,5 @@
+# ViewEnvironmentUI
+
+`ViewEnvironmentUI` provides a means to propagate a `ViewEnvironment` through the view controller hierarchy.
+
+> **_Note:_** This is currently considered an implementation detail of `MarketUI` and is intended to bridge `MarketContext` propagation between `MarketUI` and the Modals framework. Use the wrapper types declared in `MarketUI` to access the propagation of Market features.

ViewEnvironmentUI/Sources/UIView+ViewEnvironmentPropagatingObject.swift

@@ -0,0 +1,35 @@
+/*
+ * Copyright 2022 Square Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#if canImport(UIKit)
+
+import UIKit
+import ViewEnvironment
+
+extension UIView: ViewEnvironmentPropagatingObject {
+    @_spi(ViewEnvironmentWiring)
+    public var defaultEnvironmentAncestor: ViewEnvironmentPropagating? { superview }
+
+    @_spi(ViewEnvironmentWiring)
+    public var defaultEnvironmentDescendants: [ViewEnvironmentPropagating] { subviews }
+
+    @_spi(ViewEnvironmentWiring)
+    public func setNeedsApplyEnvironment() {
+        setNeedsLayout()
+    }
+}
+
+#endif

ViewEnvironmentUI/Sources/UIViewController+ViewEnvironmentPropagatingObject.swift

@@ -0,0 +1,43 @@
+/*
+ * Copyright 2022 Square Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#if canImport(UIKit)
+
+import UIKit
+import ViewEnvironment
+
+extension UIViewController: ViewEnvironmentPropagatingObject {
+    @_spi(ViewEnvironmentWiring)
+    public var defaultEnvironmentAncestor: ViewEnvironmentPropagating? { parent ?? presentingViewController }
+
+    @_spi(ViewEnvironmentWiring)
+    public var defaultEnvironmentDescendants: [ViewEnvironmentPropagating] {
+        var descendants = children
+
+        if let presentedViewController = presentedViewController {
+            descendants.append(presentedViewController)
+        }
+
+        return descendants
+    }
+
+    @_spi(ViewEnvironmentWiring)
+    public func setNeedsApplyEnvironment() {
+        viewIfLoaded?.setNeedsLayout()
+    }
+}
+
+#endif

ViewEnvironmentUI/Sources/ViewEnvironmentObserving.swift

@@ -0,0 +1,92 @@
+/*
+ * Copyright 2022 Square Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+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 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``
+    ///   in `viewWillLayoutSubviews()` and `layoutSubviews()` respectively.
+    ///
+    func apply(environment: ViewEnvironment)
+
+    /// Consumers _must_ call this function when the environment should be re-applied, e.g. in
+    /// `viewWillLayoutSubviews()` for `UIViewController`s and `layoutSubviews()` for `UIView`s.
+    ///
+    /// This will call ``apply(environment:)`` on the receiver if the node has been flagged for needing update.
+    ///
+    /// - 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/ViewEnvironmentPropagating.swift

@@ -0,0 +1,146 @@
+/*
+ * Copyright 2022 Square Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+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).
+    ///
+    /// Any `UIViewController`/`UIView` that conforms to `ViewEnvironmentObserving` _must_ call
+    /// ``ViewEnvironmentObserving/applyEnvironmentIfNeeded()-8gr5k`` in the subclass' `viewWillLayoutSubviews()` /
+    /// `layoutSubviews()` respectively.
+    ///
+    /// - Important: Nodes providing manual conformance to this protocol should call ``setNeedsEnvironmentUpdate()`` on
+    ///   all `environmentDescendants` (which is behind the `ViewEnvironmentWiring` SPI namespace).
+    ///
+    /// - Tag: ViewEnvironmentObserving.setNeedsEnvironmentUpdate
+    ///
+    func setNeedsEnvironmentUpdate()
+
+    /// The `ViewEnvironment` propagation ancestor.
+    ///
+    /// This describes the ancestor that the `ViewEnvironment` is inherited from.
+    ///
+    /// To override the return value of this property for `UIViewController`/`UIView` subclasses, set the
+    /// ``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 }
+
+    /// The [`ViewEnvironment` propagation](x-source-tag://ViewEnvironmentObserving)
+    /// descendants.
+    ///
+    /// This describes the descendants that will be notified when the `ViewEnvironment` changes.
+    ///
+    /// To override the return value of this property for `UIViewController`/`UIView` subclasses, set the
+    /// ``ViewEnvironmentPropagatingObject/environmentDescendantsOverride`` property.  If no override is present, the
+    /// return value will be a collection of all `children` in  addition to the `presentedViewController` for
+    /// `UIViewController`s and `subviews` for `UIView`s.
+    ///
+    @_spi(ViewEnvironmentWiring)
+    var environmentDescendants: [ViewEnvironmentPropagating] { get }
+}
+
+extension ViewEnvironmentPropagating {
+    /// 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. The invalidation path may be
+    /// interrupted if a node has set it's `environmentAncestor` to `nil`, even if there is a node
+    /// which specifies this node as an `environmentDescendant`.
+    ///
+    /// 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.
+    ///
+    public var environment: ViewEnvironment {
+        var environment = environmentAncestor?.environment ?? .empty
+
+        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 {
+            // If the descendant's ancestor is nil it has opted out of environment updates and is likely acting as
+            // a root for propagation bridging purposes (e.g. from a Workflow ViewEnvironment update).
+            // Avoid updating the descendant if this is the case.
+            guard descendant.environmentAncestor != nil else {
+                continue
+            }
+
+            descendant.setNeedsEnvironmentUpdate()
+        }
+    }
+}