[feat]: add experimental WorkflowUI telemetry hooks

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