Make it easier to directly manage screen-backed UIViewControllers directly to remove DescribedViewController layering from VC hierarchies.

Author: kyleve

Workflow.podspec

@@ -13,7 +13,7 @@ Pod::Spec.new do |s|
   s.cocoapods_version = '>= 1.7.0'
 
   s.swift_versions = ['5.0']
-  s.ios.deployment_target = '11.0'
+  s.ios.deployment_target = '12.0'
   s.osx.deployment_target = '10.13'
 
   s.source_files = 'Workflow/Sources/*.swift'

WorkflowReactiveSwift.podspec

@@ -13,7 +13,7 @@ Pod::Spec.new do |s|
   s.cocoapods_version = '>= 1.7.0'
 
   s.swift_versions = ['5.0']
-  s.ios.deployment_target = '11.0'
+  s.ios.deployment_target = '12.0'
   s.osx.deployment_target = '10.13'
 
   s.source_files = 'WorkflowReactiveSwift/Sources/**/*.swift'

WorkflowReactiveSwiftTesting.podspec

@@ -13,7 +13,7 @@ Pod::Spec.new do |s|
   s.cocoapods_version = '>= 1.7.0'
 
   s.swift_versions = ['5.0']
-  s.ios.deployment_target = '11.0'
+  s.ios.deployment_target = '12.0'
   s.osx.deployment_target = '10.13'
 
   s.source_files = 'WorkflowReactiveSwift/Testing/**/*.swift'

WorkflowRxSwift.podspec

@@ -13,7 +13,7 @@ Pod::Spec.new do |s|
   s.cocoapods_version = '>= 1.7.0'
 
   s.swift_versions = ['5.0']
-  s.ios.deployment_target = '11.0'
+  s.ios.deployment_target = '12.0'
   s.osx.deployment_target = '10.13'
 
   s.source_files = 'WorkflowRxSwift/Sources/**/*.swift'

WorkflowRxSwiftTesting.podspec

@@ -13,7 +13,7 @@ Pod::Spec.new do |s|
   s.cocoapods_version = '>= 1.7.0'
 
   s.swift_versions = ['5.0']
-  s.ios.deployment_target = '11.0'
+  s.ios.deployment_target = '12.0'
   s.osx.deployment_target = '10.13'
 
   s.source_files = 'WorkflowRxSwift/Testing/**/*.swift'

WorkflowTesting.podspec

@@ -13,7 +13,7 @@ Pod::Spec.new do |s|
   s.cocoapods_version = '>= 1.7.0'
 
   s.swift_versions = ['5.0']
-  s.ios.deployment_target = '11.0'
+  s.ios.deployment_target = '12.0'
   s.osx.deployment_target = '10.13'
 
   s.source_files = 'WorkflowTesting/Sources/**/*.swift'

WorkflowUI.podspec

@@ -13,7 +13,7 @@ Pod::Spec.new do |s|
   s.cocoapods_version = '>= 1.7.0'
 
   s.swift_versions = ['5.0']
-  s.ios.deployment_target = '11.0'
+  s.ios.deployment_target = '12.0'
   s.osx.deployment_target = '10.13'
 
   s.source_files = 'WorkflowUI/Sources/**/*.swift'

WorkflowUI/Sources/Container/ContainerViewController.swift

@@ -27,22 +27,27 @@
             return workflowHost.output
         }
 
-        internal let rootViewController: DescribedViewController
+        private(set) var rootViewController: UIViewController
 
         private let workflowHost: WorkflowHost<RootWorkflow<ScreenType, Output>>
 
         private let (lifetime, token) = Lifetime.make()
 
         public var rootViewEnvironment: ViewEnvironment {
             didSet {
-                // Re-render the current rendering with the new environment
-                render(screen: workflowHost.rendering.value, environment: rootViewEnvironment)
+                update(screen: workflowHost.rendering.value, environment: rootViewEnvironment)
             }
         }
 
         public init<W: AnyWorkflowConvertible>(workflow: W, rootViewEnvironment: ViewEnvironment = .empty) where W.Rendering == ScreenType, W.Output == Output {
             self.workflowHost = WorkflowHost(workflow: RootWorkflow(workflow))
-            self.rootViewController = DescribedViewController(screen: workflowHost.rendering.value, environment: rootViewEnvironment)
+
+            self.rootViewController = workflowHost
+                .rendering
+                .value
+                .viewControllerDescription(environment: rootViewEnvironment)
+                .buildViewController()
+
             self.rootViewEnvironment = rootViewEnvironment
 
             super.init(nibName: nil, bundle: nil)
@@ -56,7 +61,8 @@
                 .take(during: lifetime)
                 .observeValues { [weak self] screen in
                     guard let self = self else { return }
-                    self.render(screen: screen, environment: self.rootViewEnvironment)
+
+                    self.update(screen: screen, environment: self.rootViewEnvironment)
                 }
         }
 
@@ -69,8 +75,10 @@
             fatalError("init(coder:) has not been implemented")
         }
 
-        private func render(screen: ScreenType, environment: ViewEnvironment) {
-            rootViewController.update(screen: screen, environment: environment)
+        private func update(screen: ScreenType, environment: ViewEnvironment) {
+            update(child: \.rootViewController, with: screen, in: environment)
+
+            updatePreferredContentSizeIfNeeded()
         }
 
         override public func viewDidLoad() {

WorkflowUI/Sources/Screen/Screen.swift

@@ -26,4 +26,10 @@
         func viewControllerDescription(environment: ViewEnvironment) -> ViewControllerDescription
     }
 
+    extension Screen {
+        public func update(viewController: UIViewController, with environment: ViewEnvironment) {
+            viewControllerDescription(environment: environment).update(viewController: viewController)
+        }
+    }
+
 #endif

WorkflowUI/Sources/ViewControllerDescription/DescribedViewController.swift

@@ -124,5 +124,4 @@
             preferredContentSize = newPreferredContentSize
         }
     }
-
 #endif

WorkflowUI/Sources/ViewControllerDescription/UIViewController+Extensions.swift

@@ -0,0 +1,129 @@
+/*
+ * Copyright 2020 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
+
+    extension UpdateChildScreenViewController where Self: UIViewController {
+        /// Updates the view controller at the given `child` key path with the
+        /// `ViewControllerDescription`from `screen`. If the type of the underlying view
+        /// controller changes between update passes, this method will remove
+        /// the old view controller, create a new one, update it, and insert it into the view controller hierarchy.
+        ///
+        /// The view controller at `child` must be a child of `self`.
+        ///
+        /// - Parameters:
+        /// - parameter child: The `KeyPath` which describes what view controller to update. This view controller must be a direct child of `self`.
+        /// - parameter screen: The `Screen` instance to apply to the view controller.
+        /// - parameter environment: The `environment` to used when updating the view controller.
+        /// - parameter onChange: A callback called if the view controller instance changed.
+        ///
+        public func update<VC: UIViewController, ScreenType: Screen>(
+            child: ReferenceWritableKeyPath<Self, VC>,
+            with screen: ScreenType,
+            in environment: ViewEnvironment,
+            onChange: (VC) -> Void = { _ in }
+        ) {
+            let description = screen.viewControllerDescription(environment: environment)
+
+            let existing = self[keyPath: child]
+
+            if description.canUpdate(viewController: existing) {
+                // Easy path: Just update the existing view controller if we can do that.
+                description.update(viewController: existing)
+            } else {
+                // If we can't update the view controller, that means it's type changed.
+                // We'll need to make a new view controller and swap over to it.
+
+                let old = existing
+
+                // Make the new view controller.
+
+                let new = description.buildViewController() as! VC
+
+                // We already have a reference to the old vc above, update the keypath to the new one.
+
+                self[keyPath: child] = new
+
+                // We should only add the view controller if the old one was already within the parent.
+
+                if let parent = old.parent {
+                    precondition(
+                        parent == self,
+                        """
+                        The parent of the child view controller must be \(self). Instead, it was \(parent). \
+                        Please call `update(child:)` on the correct parent view controller.
+                        """
+                    )
+
+                    // Begin the transition: Signal the new vc will begin moving in, and the old one, out.
+
+                    parent.addChild(new)
+                    old.willMove(toParent: nil)
+
+                    if
+                        parent.isViewLoaded,
+                        old.isViewLoaded,
+                        let container = old.view.superview {
+                        // We will only add the view to the hierarchy if
+                        // the parent's view is loaded, and the existing view
+                        // is loaded, and the old view was in a superview.
+
+                        // We will only perform appearance transitions if we're visible.
+
+                        let isVisible = parent.view.window != nil
+
+                        // We only send appearance transitions if the parent won't do it
+                        // for us on insert of the added subview.
+
+                        let sendsAppearanceTransitions = isVisible && parent.shouldAutomaticallyForwardAppearanceMethods == false
+
+                        // The view should end up with the same frame.
+
+                        new.view.frame = old.view.frame
+
+                        container.insertSubview(new.view, aboveSubview: old.view)
+
+                        if sendsAppearanceTransitions {
+                            new.beginAppearanceTransition(true, animated: false)
+                            old.beginAppearanceTransition(false, animated: false)
+                        }
+
+                        old.view.removeFromSuperview()
+
+                        if sendsAppearanceTransitions {
+                            new.endAppearanceTransition()
+                            old.endAppearanceTransition()
+                        }
+                    }
+
+                    // Finish the transition by signaling the vc they've fully moved in / out.
+
+                    new.didMove(toParent: parent)
+                    old.removeFromParent()
+                }
+
+                onChange(new)
+            }
+        }
+    }
+
+    public protocol UpdateChildScreenViewController {}
+
+    extension UIViewController: UpdateChildScreenViewController {}
+
+#endif

WorkflowUI/Sources/ViewControllerDescription/ViewControllerDescription.swift

@@ -41,11 +41,15 @@
         /// When creating container view controllers that contain other view controllers
         /// (eg, a navigation stack), you usually want to set this value to `false` to avoid
         /// duplicate updates to your children if they are created in `init`.
-        public var performInitialUpdate: Bool = true
+        public var performInitialUpdate: Bool
+
+        /// Describes the `UIViewController` type that backs the `ViewControllerDescription`
+        /// in a way that is `Equatable` and `Hashable`. When implementing view controller
+        /// updating and diffing, you can use this type to identify if the backing view controller
+        /// type changed.
+        public let kind: KindIdentifier
 
-        private let viewControllerType: UIViewController.Type
         private let build: () -> UIViewController
-        private let checkViewControllerType: (UIViewController) -> Bool
         private let update: (UIViewController) -> Void
 
         /// Constructs a view controller description by providing closures used to
@@ -70,13 +74,16 @@
             update: @escaping (VC) -> Void
         ) {
             self.performInitialUpdate = performInitialUpdate
-            self.viewControllerType = type
+
+            self.kind = .init(VC.self)
+
             self.build = build
-            self.checkViewControllerType = { $0 is VC }
+
             self.update = { untypedViewController in
                 guard let viewController = untypedViewController as? VC else {
                     fatalError("Unable to update \(untypedViewController), expecting a \(VC.self)")
                 }
+
                 update(viewController)
             }
         }
@@ -101,7 +108,7 @@
         /// ### Note
         /// Failure to confirm the view controller is updatable will result in a fatal `precondition`.
         public func canUpdate(viewController: UIViewController) -> Bool {
-            return checkViewControllerType(viewController)
+            kind.canUpdate(viewController: viewController)
         }
 
         /// Update the given view controller with the content from the view controller description.
@@ -118,12 +125,50 @@
                 """
                 `ViewControllerDescription` was provided a view controller it cannot update: (\(viewController).
 
-                The view controller type (\(type(of: viewController)) is a compatible type to the expected type \(viewControllerType)).
+                The view controller type (\(type(of: viewController)) is a compatible type to the expected type \(kind.viewControllerType)).
                 """
             )
 
             update(viewController)
         }
     }
 
+    extension ViewControllerDescription {
+        /// Describes the `UIViewController` type that backs the `ViewControllerDescription`
+        /// in a way that is `Equatable` and `Hashable`. When implementing view controller
+        /// updating and diffing, you can use this type to identify if the backing view controller
+        /// type changed.
+        public struct KindIdentifier: Hashable {
+            fileprivate let viewControllerType: UIViewController.Type
+
+            private let checkViewControllerType: (UIViewController) -> Bool
+
+            /// Creates a new kind for the given view controller type.
+            public init<VC: UIViewController>(_ kind: VC.Type) {
+                self.viewControllerType = VC.self
+
+                self.checkViewControllerType = { $0 is VC }
+            }
+
+            /// If the given view controller is of the correct type to be updated by this view controller description.
+            ///
+            /// If your view controller type can change between updates, call this method before invoking `update(viewController:)`.
+            public func canUpdate(viewController: UIViewController) -> Bool {
+                return checkViewControllerType(viewController)
+            }
+
+            // MARK: Hashable
+
+            public func hash(into hasher: inout Hasher) {
+                hasher.combine(ObjectIdentifier(viewControllerType))
+            }
+
+            // MARK: Equatable
+
+            public static func == (lhs: Self, rhs: Self) -> Bool {
+                lhs.viewControllerType == rhs.viewControllerType
+            }
+        }
+    }
+
 #endif

WorkflowUI/Tests/ContainerViewControllerTests.swift

@@ -47,7 +47,7 @@
             let container = ContainerViewController(workflow: workflow)
 
             withExtendedLifetime(container) {
-                let vc = container.rootViewController.currentViewController as! TestScreenViewController
+                let vc = container.rootViewController as! TestScreenViewController
                 XCTAssertEqual("0", vc.screen.string)
             }
         }
@@ -60,7 +60,7 @@
             withExtendedLifetime(container) {
                 let expectation = XCTestExpectation(description: "View Controller updated")
 
-                let vc = container.rootViewController.currentViewController as! TestScreenViewController
+                let vc = container.rootViewController as! TestScreenViewController
                 vc.onScreenChange = {
                     expectation.fulfill()
                 }
@@ -118,7 +118,7 @@
             withExtendedLifetime(container) {
                 let expectation = XCTestExpectation(description: "View Controller updated")
 
-                let vc = container.rootViewController.currentViewController as! TestScreenViewController
+                let vc = container.rootViewController as! TestScreenViewController
 
                 XCTAssertEqual("first", vc.screen.string)