[feat]: add experimental WorkflowUI telemetry hooks (#221)

### Motivation

we'd like to be able to build out some observation tooling that is aware of certain events that occur within WorkflowUI. specifically, view lifecycle data is of particular interest. currently the options for tying into UIViewController lifecycle events are either:

1. introduce new subclasses in client code that override the methods of interest and provide observation hooks there.
2. swizzle the methods of interest to allow client observation

option `1.` may place a large burden on consumers that have many existing subclasses (of, say, ScreenViewController), and only works for the `open` types defined in `WorkflowUI`, which excludes `WorkflowHostingController` & `DescribedViewController`. option `2.` may require less code to implement, but adds indirection (swizzling is often not particularly discoverable), runtime overhead, and may not work for Swift-only methods.

note: this is all currently implemented behind 'experimental' SPI declarations. the intent would be to treat this as sort of an 'alpha' version of this functionality, and to set expectations that it may have breaking changes going forward, without a major version increment in the library.

### Implementation

to achieve this goal, we've implemented an approach that does the following:

- unifies all `UIViewController` subtypes defined in `WorkflowUI` under a new parent class `WorkflowUIViewController`
- instruments some view controller lifecycle events (viewDidAppear, etc) within the shared base class
- exposes a static value that can be used to register a 'global' observer of these events
- adds some new protocols and event data types to enable observation of WorkflowUI lifecycle events

Author: jamieQ

WorkflowUI/Sources/Hosting/WorkflowHostingController.swift

@@ -22,7 +22,7 @@ import UIKit
 import Workflow
 
 /// Drives view controllers from a root Workflow.
-public final class WorkflowHostingController<ScreenType, Output>: UIViewController where ScreenType: Screen {
+public final class WorkflowHostingController<ScreenType, Output>: WorkflowUIViewController where ScreenType: Screen {
     public typealias CustomizeEnvironment = (inout ViewEnvironment) -> Void
 
     /// Emits output events from the bound workflow.
@@ -118,13 +118,13 @@ public final class WorkflowHostingController<ScreenType, Output>: UIViewControll
         updatePreferredContentSizeIfNeeded()
     }
 
-    public override func viewWillLayoutSubviews() {
+    override public func viewWillLayoutSubviews() {
         super.viewWillLayoutSubviews()
         applyEnvironmentIfNeeded()
     }
 
     override public func viewDidLayoutSubviews() {
-        super.viewDidLayoutSubviews()
+        defer { super.viewDidLayoutSubviews() }
         rootViewController.view.frame = view.bounds
     }
 

WorkflowUI/Sources/Observation/WorkflowUIEvents.swift

@@ -0,0 +1,56 @@
+/*
+ * 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 Foundation
+import UIKit
+
+/// Protocol that describes an observable 'event' that may be emitted from `WorkflowUI`.
+@_spi(ExperimentalObservation)
+public protocol WorkflowUIEvent {
+    var viewController: UIViewController { get }
+}
+
+// MARK: ViewController Lifecycle Events
+
+/// Event emitted from a `WorkflowUIViewController`'s `viewWillLayoutSubviews` method.
+@_spi(ExperimentalObservation)
+public struct ViewWillLayoutSubviewsEvent: WorkflowUIEvent, Equatable {
+    public let viewController: UIViewController
+}
+
+/// Event emitted from a `WorkflowUIViewController`'s `viewDidLayoutSubviews` method.
+@_spi(ExperimentalObservation)
+public struct ViewDidLayoutSubviewsEvent: WorkflowUIEvent, Equatable {
+    public let viewController: UIViewController
+}
+
+/// Event emitted from a `WorkflowUIViewController`'s `viewWillAppear` method.
+@_spi(ExperimentalObservation)
+public struct ViewWillAppearEvent: WorkflowUIEvent, Equatable {
+    public let viewController: UIViewController
+    public let animated: Bool
+    public let isFirstAppearance: Bool
+}
+
+/// Event emitted from a `WorkflowUIViewController`'s `viewDidAppear` method.
+@_spi(ExperimentalObservation)
+public struct ViewDidAppearEvent: WorkflowUIEvent, Equatable {
+    public let viewController: UIViewController
+    public let animated: Bool
+    public let isFirstAppearance: Bool
+}
+#endif

WorkflowUI/Sources/Observation/WorkflowUIObserver.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 Foundation
+
+/// Protocol to observe events emitted from WorkflowUI.
+/// **N.B. This is currently part of an experimental interface, and may have breaking changes in the future.**
+@_spi(ExperimentalObservation)
+public protocol WorkflowUIObserver {
+    func observeEvent<E: WorkflowUIEvent>(_ event: E)
+}
+
+// MARK: - Global Observation
+
+@_spi(ExperimentalObservation)
+public enum WorkflowUIObservation {
+    /// The shared `WorkflowUIObserver` instance to which all `WorkflowUIEvent`s will be forwarded.
+    public static var sharedUIObserver: WorkflowUIObserver?
+}
+
+#endif

WorkflowUI/Sources/Observation/WorkflowUIViewController.swift

@@ -0,0 +1,77 @@
+/*
+ * 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 Foundation
+import UIKit
+
+/// Ancestor type from which all ViewControllers in WorkflowUI inherit.
+open class WorkflowUIViewController: UIViewController {
+    /// Set to `true` once `viewDidAppear` has been called
+    public private(set) final var hasViewAppeared: Bool = false
+
+    // MARK: Event Emission
+
+    /// Observation event emission point.
+    /// - Parameter event: The event forwarded to any observers.
+    @_spi(ExperimentalObservation)
+    public final func sendObservationEvent<E: WorkflowUIEvent>(
+        _ event: @autoclosure () -> E
+    ) {
+        WorkflowUIObservation
+            .sharedUIObserver?
+            .observeEvent(event())
+    }
+
+    // MARK: Lifecycle Methods
+
+    override open func viewWillAppear(_ animated: Bool) {
+        sendObservationEvent(ViewWillAppearEvent(
+            viewController: self,
+            animated: animated,
+            isFirstAppearance: !hasViewAppeared
+        ))
+        super.viewWillAppear(animated)
+    }
+
+    override open func viewDidAppear(_ animated: Bool) {
+        let isFirstAppearance = !hasViewAppeared
+        if isFirstAppearance { hasViewAppeared = true }
+
+        super.viewDidAppear(animated)
+
+        sendObservationEvent(ViewDidAppearEvent(
+            viewController: self,
+            animated: animated,
+            isFirstAppearance: isFirstAppearance
+        ))
+    }
+
+    override open func viewWillLayoutSubviews() {
+        sendObservationEvent(
+            ViewWillLayoutSubviewsEvent(viewController: self)
+        )
+        super.viewWillLayoutSubviews()
+    }
+
+    override open func viewDidLayoutSubviews() {
+        super.viewDidLayoutSubviews()
+        sendObservationEvent(
+            ViewDidLayoutSubviewsEvent(viewController: self)
+        )
+    }
+}
+#endif

WorkflowUI/Sources/Screen/ScreenViewController.swift

@@ -37,7 +37,7 @@ import ViewEnvironment
 ///     }
 /// }
 /// ```
-open class ScreenViewController<ScreenType: Screen>: UIViewController {
+open class ScreenViewController<ScreenType: Screen>: WorkflowUIViewController {
     public private(set) final var screen: ScreenType
 
     public final var screenType: Screen.Type {

WorkflowUI/Sources/ViewControllerDescription/DescribedViewController.swift

@@ -18,7 +18,7 @@
 
 import UIKit
 
-public final class DescribedViewController: UIViewController {
+public final class DescribedViewController: WorkflowUIViewController {
     var currentViewController: UIViewController
 
     public init(description: ViewControllerDescription) {

WorkflowUI/Tests/WorkflowUIObservationTestCase.swift

@@ -0,0 +1,106 @@
+/*
+ * 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 Combine
+import Workflow
+import XCTest
+
+@_spi(ExperimentalObservation) import WorkflowUI
+
+open class WorkflowUIObservationTestCase: XCTestCase {
+    var publishingObserver: PublishingObserver!
+
+    var observedEvents: [WorkflowUIEvent] = []
+
+    private var cancellables: [AnyCancellable] = []
+
+    override open func invokeTest() {
+        publishingObserver = PublishingObserver()
+        defer { publishingObserver = nil }
+
+        // collect all events emitted during test invocation
+        publishingObserver.subject
+            .sink { [weak self] event in
+                self?.observedEvents.append(event)
+            }
+            .store(in: &cancellables)
+
+        withGlobalObserver(publishingObserver) {
+            super.invokeTest()
+        }
+    }
+
+    private func withGlobalObserver(_ globalObserver: WorkflowUIObserver, perform: () -> Void) {
+        let oldObserver = WorkflowUIObservation.sharedUIObserver
+        defer {
+            WorkflowUIObservation.sharedUIObserver = oldObserver
+        }
+
+        WorkflowUIObservation.sharedUIObserver = globalObserver
+        perform()
+    }
+
+    func observationEvents(
+        from viewController: WorkflowUIViewController,
+        perform: () -> Void
+    ) -> [WorkflowUIEvent] {
+        var events: [WorkflowUIEvent] = []
+
+        let scopedObserver = publishingObserver
+            .publisher
+            .filter { $0.viewController === viewController }
+            .sink { events.append($0) }
+        defer { scopedObserver.cancel() }
+
+        perform()
+
+        return events
+    }
+}
+
+final class PublishingObserver: WorkflowUIObserver {
+    let subject: PassthroughSubject<WorkflowUIEvent, Never>
+    private(set) lazy var publisher = { subject.eraseToAnyPublisher() }()
+
+    init() {
+        self.subject = .init()
+    }
+
+    func observeEvent<E: WorkflowUIEvent>(_ event: E) {
+        subject.send(event)
+    }
+}
+
+// MARK: Event Introspection Utilities
+
+typealias EventDescriptor = String
+extension EventDescriptor {
+    static var viewWillAppear: EventDescriptor = "\(ViewWillAppearEvent.self)"
+
+    static var viewDidAppear: EventDescriptor = "\(ViewDidAppearEvent.self)"
+
+    static var viewWillLayoutSubviews: EventDescriptor = "\(ViewWillLayoutSubviewsEvent.self)"
+
+    static var viewDidLayoutSubviews: EventDescriptor = "\(ViewDidLayoutSubviewsEvent.self)"
+}
+
+extension WorkflowUIEvent {
+    var descriptor: EventDescriptor {
+        "\(type(of: self))"
+    }
+}
+#endif