[feat]: add ViewEnvironmentUI module

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'
 
@@ -101,6 +102,12 @@ Pod::Spec.new do |s|
     }
   end
 
+  s.test_spec 'ViewEnvironmentUITests' do |test_spec|
+    test_spec.requires_app_host = true
+    test_spec.source_files = 'ViewEnvironmentUI/Tests/**/*.swift'
+    test_spec.framework = 'XCTest'
+  end
+
   s.test_spec 'WorkflowTests' do |test_spec|
     test_spec.requires_app_host = true
     test_spec.source_files = 'Workflow/Tests/**/*.swift'

Package.swift

@@ -82,6 +82,13 @@ let package = Package(
             name: "ViewEnvironment",
             targets: ["ViewEnvironment"]
         ),
+
+        // MARK: ViewEnvironmentUI
+
+        .library(
+            name: "ViewEnvironmentUI",
+            targets: ["ViewEnvironmentUI"]
+        ),
     ],
     dependencies: [
         .package(url: "https://github.com/ReactiveCocoa/ReactiveSwift.git", from: "7.1.1"),
@@ -228,6 +235,13 @@ let package = Package(
             name: "ViewEnvironment",
             path: "ViewEnvironment/Sources"
         ),
+
+        // MARK: ViewEnvironmentUI
+
+        .target(
+            name: "ViewEnvironmentUI",
+            path: "ViewEnvironmentUI/Sources"
+        ),
     ],
     swiftLanguageVersions: [.v5]
 )

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,36 @@
+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'
+
+        # 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,6 @@
+# ViewEnvironmentUI
+
+`ViewEnvironmentUI` provides a means to propagate a `ViewEnvironment` through a heirarchy of object nodes.
+
+Support for propagation of `ViewEnvironment` through `UIViewController`s and `UIView`s is provided by this framework.
+

ViewEnvironmentUI/Sources/UIView+ViewEnvironmentPropagatingObject.swift

@@ -0,0 +1,35 @@
+/*
+ * Copyright 2023 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 2023 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 2023 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
+
+/// `ViewEnvironmentObserving` 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
+/// {
+///     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 environment updates should be applied.
+    ///
+    /// This will call ``apply(environment:)`` on the receiver if the node has been flagged for needing update.
+    ///
+    /// When working with `UIViewController` and `UIView` nodes, consumers _must_ call this function in
+    /// `viewWillLayoutSubviews()` for `UIViewController`s and `layoutSubviews()` for `UIView`s.
+    ///
+    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() {}
+}