Package.swift

@@ -2,22 +2,41 @@
 
 import PackageDescription
 
+private var excludePlatforms: [String] = [.PlatformFolder.iOS]
+
+#if os(iOS)
+excludePlatforms = []
+#endif
+
 let package = Package(
     name: "SwiftLibs",
     products: [
         .library(
             name: "SwiftLibs",
             targets: [
+                "Coordinator",
                 "Core"
             ]
         ),
     ],
     dependencies: [],
     targets: [
+        .target(
+            name: "Coordinator",
+            dependencies: [],
+            exclude: excludePlatforms
+        ),
         .target(
             name: "Core",
+            dependencies: []
+        ),
+        .testTarget(
+            name: "CoordinatorTests",
             dependencies: [
-            ]
+                "Coordinator"
+            ],
+            path: "Tests/Coordinator",
+            exclude: excludePlatforms
         ),
         .testTarget(
             name: "CoreTests",
@@ -28,3 +47,11 @@ let package = Package(
         ),
     ]
 )
+
+// MARK: - String+Constants
+
+private extension String {
+    enum PlatformFolder {
+        static let iOS = "Platform/iOS"
+    }
+}

Sources/Coordinator/Platform/iOS/Routers/BaseNavigationRouter.swift

@@ -0,0 +1,68 @@
+//
+//  BaseNavigationRouter.swift
+//  Coordinator
+//
+//  Created by Javier Cicchelli on 11/04/2023.
+//  Copyright © 2023 Röck+Cöde. All rights reserved.
+//
+
+import UIKit
+
+/// This is a base class for the `NavigationRouter` concrete router implementations.
+public class BaseNavigationRouter: NSObject {
+    
+    // MARK: Properties
+    
+    /// A navigation controller to use within this concrete router.
+    var navigationController: UINavigationController
+    
+    /// Dictionary that persist `onDismiss` closure for its respective view controllers until one of the later is dismissed.
+    var onDismissForViewController: [UIViewController: Router.OnDismissedClosure] = [:]
+    
+    // MARK: Initialisers
+    
+    /// Initialise this router.
+    /// - Parameter navigationController: A `UINavigationController` navigation controller instance to use in this router.
+    init(navigationController: UINavigationController) {
+        self.navigationController = navigationController
+        
+        super.init()
+        
+        self.navigationController.delegate = self
+    }
+    
+    // MARK: Functions
+    
+    /// Executes the `onDismiss` closure for a given view controller.
+    /// - Parameter viewController: A `UIViewController` view controller instance for which the on dismiss closure will be executed.
+    func performOnDismissed(for viewController: UIViewController) {
+        guard let onDismiss = onDismissForViewController[viewController] else {
+            return
+        }
+        
+        onDismiss()
+        
+        onDismissForViewController[viewController] = nil
+    }
+    
+}
+
+// MARK: - UINavigationControllerDelegate
+
+extension BaseNavigationRouter: UINavigationControllerDelegate {
+    
+    // MARK: Functions
+    
+    public func navigationController(
+        _ navigationController: UINavigationController,
+        didShow viewController: UIViewController,
+        animated: Bool
+    ) {
+        guard let dismissedViewController = navigationController.transitionCoordinator?.viewController(forKey: .from) else {
+            return
+        }
+        
+        performOnDismissed(for: dismissedViewController)
+    }
+
+}

Sources/Coordinator/Platform/iOS/Routers/ModalNavigationRouter.swift

@@ -0,0 +1,86 @@
+//
+//  ModalNavigationRouter.swift
+//  Coordinator
+//
+//  Created by Javier Cicchelli on 11/04/2023.
+//  Copyright © 2023 Röck+Cöde. All rights reserved.
+//
+
+import UIKit
+
+/// This class is responsible for showing view controllers modally, as it is a concrete implementation of the `Router` protocol.
+public class ModalNavigationRouter: BaseNavigationRouter {
+    
+    // MARK: Properties
+    
+    /// The parent view controller from where this router is being called from.
+    public unowned let parentViewController: UIViewController
+
+    // MARK: Initialisers
+    
+    /// Initialise this router.
+    /// - Parameter parentViewController: A `UIViewController` view controller instance from where this router is originated.
+    public init(parentViewController: UIViewController) {
+        self.parentViewController = parentViewController
+        
+        super.init(navigationController: .init())
+    }
+    
+}
+
+extension ModalNavigationRouter: Router {
+    public func present(
+        _ viewController: UIViewController,
+        animated: Bool,
+        onDismiss: OnDismissedClosure?
+    ) {
+        onDismissForViewController[viewController] = onDismiss
+        
+        if navigationController.viewControllers.isEmpty {
+            presentModally(viewController, animated: animated)
+        } else {
+            navigationController.pushViewController(viewController, animated: animated)
+        }
+    }
+    
+    public func dismiss(animated: Bool) {
+        guard let firstViewController = navigationController.viewControllers.first else {
+            return
+        }
+        
+        performOnDismissed(for: firstViewController)
+        
+        parentViewController.dismiss(animated: animated)
+    }
+    
+}
+
+// MARK: - Helpers
+
+private extension ModalNavigationRouter {
+    
+    // MARK: Functions
+    
+    func presentModally(_ viewController: UIViewController, animated: Bool) {
+        viewController.navigationItem.leftBarButtonItem = UIBarButtonItem(
+            title: "Cancel",
+            style: .plain,
+            target: self,
+            action: #selector(onCancelPressed)
+        )
+        
+        navigationController.setViewControllers([viewController], animated: false)
+        
+        parentViewController.present(navigationController, animated: animated)
+    }
+    
+    @objc func onCancelPressed() {
+        guard let firstViewController = navigationController.viewControllers.first else {
+            return
+        }
+        
+        performOnDismissed(for: firstViewController)
+        dismiss(animated: true)
+    }
+    
+}

Sources/Coordinator/Platform/iOS/Routers/PushNavigationRouter.swift

@@ -0,0 +1,64 @@
+//
+//  PushNavigationRouter.swift
+//  Coordinator
+//
+//  Created by Javier Cicchelli on 11/04/2023.
+//  Copyright © 2023 Röck+Cöde. All rights reserved.
+//
+
+import UIKit
+
+/// This class is responsible for pushing view controllers into a navigation controller, as it is a concrete implementation of the `Router` protocol.
+public class PushNavigationRouter: BaseNavigationRouter {
+    
+    // MARK: Properties
+    
+    /// A root view controller coming in from the navigation controller, if any.
+    private let rootViewController: UIViewController?
+    
+    // MARK: Initialisers
+    
+    /// Initialise this router.
+    /// - Parameters:
+    ///   - navigationController: A `UINavigationController` navigation controller instance to use in this router.
+    ///   - rootViewController: A `UIViewController` view controller instance to define as a root view controller of the navigation controller.
+    /// - Note This initialiser added the `rootViewController` parameter although it is not really needed to differentiate itself from the `.init(navigationController:)` implemented for the `BaseNavigationRouter` base class.
+    public init(
+        navigationController: UINavigationController,
+        rootViewController: UIViewController? = nil
+    ) {
+        self.rootViewController = navigationController.viewControllers.first ?? rootViewController
+
+        super.init(navigationController: navigationController)
+    }
+
+}
+
+// MARK: - Router
+
+extension PushNavigationRouter: Router {
+    
+    // MARK: Functions
+    
+    public func present(
+        _ viewController: UIViewController,
+        animated: Bool,
+        onDismiss: OnDismissedClosure?
+    ) {
+        onDismissForViewController[viewController] = onDismiss
+        
+        navigationController.pushViewController(viewController, animated: animated)
+    }
+    
+    public func dismiss(animated: Bool) {
+        guard let rootViewController else {
+            navigationController.popViewController(animated: animated)
+            return
+        }
+        
+        performOnDismissed(for: rootViewController)
+        
+        navigationController.popToViewController(rootViewController, animated: animated)
+    }
+    
+}

Sources/Coordinator/Platform/iOS/Routers/WindowRouter.swift

@@ -0,0 +1,43 @@
+//
+//  WindowRouter.swift
+//  Coordinator
+//
+//  Created by Javier Cicchelli on 11/04/2023.
+//  Copyright © 2023 Röck+Cöde. All rights reserved.
+//
+
+import UIKit
+
+/// This class is responsible for populating the window of an application.
+public class WindowRouter: Router {
+    
+    // MARK: Properties
+    
+    /// The window to set manually with a `UIViewController` view controller instance.
+    private let window: UIWindow?
+    
+    // MARK: Initialisers
+    
+    /// Initialise this router.
+    /// - Parameter window: A `UIWindow` window instance to be set manually.
+    public init(window: UIWindow?) {
+        self.window = window
+    }
+    
+    // MARK: Functions
+
+    public func present(
+        _ viewController: UIViewController,
+        animated: Bool,
+        onDismiss: OnDismissedClosure?
+    ) {
+        window?.rootViewController = viewController
+
+        window?.makeKeyAndVisible()
+    }
+    
+    public func dismiss(animated: Bool) {
+        // Nothing to do here...
+    }
+    
+}

Sources/Coordinator/Protocols/Coordinator.swift

@@ -0,0 +1,76 @@
+//
+//  Coordinator.swift
+//  Coordinator
+//
+//  Created by Javier Cicchelli on 11/04/2023.
+//  Copyright © 2023 Röck+Cöde. All rights reserved.
+//
+
+/// This protocol organize the flow logic between view controllers in the app.
+public protocol Coordinator: AnyObject {
+
+    // MARK: Properties
+    
+    /// The child coordinators that are being currently presented.
+    var children: [Coordinator] { get set }
+    
+    /// The router that handles how the view controllers in the coordinators will be shown or dismissed.
+    var router: Router { get }
+
+    // MARK: Functions
+    
+    /// Present the coordinator animatedly or not, depending on the given `animated` parameter, and also pass a closure that should be called on dismissal.
+    /// - Parameters:
+    ///   - animated: A boolean that represents whether the coordinator should be dismissed animatedly or not.
+    ///   - onDismiss: A closure to be called or executed when the presented coordinator is dismissed.
+    func present(animated: Bool, onDismiss: Router.OnDismissedClosure?)
+
+}
+
+// MARK: - Coordinator+Implementations
+
+public extension Coordinator {
+    
+    /// Present a child coordinator animatedly or not, depending on the given `animated` parameter, and also pass a closure that should be called on dismissal.
+    /// - Parameters:
+    ///   - child: A child coordinator to be presented.
+    ///   - animated: A boolean that represents whether the coordinator should be dismissed animatedly or not.
+    ///   - onDismiss: A closure to be called or executed when the presented coordinator is dismissed.
+    func present(
+        child: Coordinator,
+        animated: Bool,
+        onDismiss: Router.OnDismissedClosure? = nil
+    ) {
+        store(child)
+        child.present(animated: animated) { [weak self, weak child] in
+            guard let self, let child else {
+                return
+            }
+            
+            self.free(child)
+            onDismiss?()
+        }
+    }
+    
+    /// Dismiss the coordinator animatedly or not, depending on the given `animated` parameter.
+    /// - Parameter animated: A boolean that represents whether the coordinator should be dismissed animatedly or not.
+    func dismiss(animated: Bool) {
+        router.dismiss(animated: animated)
+    }
+
+}
+
+// MARK: - Helpers
+
+private extension Coordinator {
+    
+    // MARK: Functions
+    
+    func store(_ coordinator: Coordinator) {
+        children.append(coordinator)
+    }
+    
+    func free(_ coordinator: Coordinator) {
+        children = children.filter { $0 !== coordinator }
+    }
+}

Sources/Coordinator/Protocols/Router.swift

@@ -0,0 +1,61 @@
+//
+//  Router.swift
+//  Coordinator
+//
+//  Created by Javier Cicchelli on 11/04/2023.
+//  Copyright © 2023 Röck+Cöde. All rights reserved.
+//
+
+#if canImport(UIKit)
+import UIKit
+#endif
+
+/// This protocol defines how view controllers will be shown and dismissed.
+public protocol Router: AnyObject {
+    
+    // MARK: Typealiases
+    
+    typealias OnDismissedClosure = () -> Void
+    
+    // MARK: Functions
+    
+    #if canImport(UIKit)
+    /// Present a view controller animatedly or not, depending on the given `animated` parameter, and also pass a closure that should be called on dismissal.
+    /// - Parameters:
+    ///   - viewController: A `UIViewController` view controller instance to present.
+    ///   - animated: A boolean that represents whether the view controller should be dismissed animatedly or not.
+    ///   - onDismiss: A closure to be called or executed when the presented view controller is dismissed.
+    func present(
+        _ viewController: UIViewController,
+        animated: Bool,
+        onDismiss: OnDismissedClosure?
+    )
+    #endif
+    
+    /// Dismiss a view controller animatedly or not, depending on the given `animated` parameter.
+    /// - Parameter animated: A boolean that represents whether the view controller should be dismissed animatedly or not.
+    func dismiss(animated: Bool)
+    
+}
+
+#if canImport(UIKit)
+// MARK: - Router+Implementations
+
+public extension Router {
+    
+    // MARK: Functions
+    
+    /// Present a view controller animatedly or not, depending on the given `animated` parameter.
+    /// - Parameters:
+    ///   - viewController: A `UIViewController` view controller instance to present.
+    ///   - animated: A boolean that represents whether the view controller should be dismissed animatedly or not.
+    func present(_ viewController: UIViewController, animated: Bool) {
+        present(
+            viewController,
+            animated: animated,
+            onDismiss: nil
+        )
+    }
+
+}
+#endif

Tests/Coordinator/Platform/iOS/Helpers/TestCoordinators.swift

@@ -0,0 +1,106 @@
+//
+//  TestCoordinators.swift
+//  CoordinatorTests
+//
+//  Created by Javier Cicchelli on 11/04/2023.
+//  Copyright © 2023 Röck+Cöde. All rights reserved.
+//
+
+import Coordinator
+import UIKit
+
+// MARK: - Test coordinators
+
+class SomeCoordinator: Coordinator {
+    
+    // MARK: Properties
+    
+    var children: [Coordinator] = []
+    var router: Router
+    
+    // MARK: Initialisers
+    
+    init(router: Router) {
+        self.router = router
+    }
+    
+    // MARK: Functions
+    
+    func present(animated: Bool, onDismiss: (() -> Void)?) {
+        router.present(
+            SomeViewController(),
+            animated: animated,
+            onDismiss: onDismiss
+        )
+    }
+
+}
+
+class SomeOtherCoordinator: Coordinator {
+
+    // MARK: Properties
+    
+    var children: [Coordinator] = []
+    var router: Router
+    
+    // MARK: Initialisers
+    
+    init(router: Router) {
+        self.router = router
+    }
+    
+    // MARK: Functions
+    
+    func present(animated: Bool, onDismiss: (() -> Void)?) {
+        router.present(
+            SomeOtherViewController(),
+            animated: animated,
+            onDismiss: onDismiss
+        )
+    }
+
+}
+
+// MARK: - SpyRouter
+
+class SpyRouter: Router {
+    
+    // MARK: Enumerations
+    
+    enum State {
+        case initialised
+        case presented
+        case dismissed
+    }
+    
+    // MARK: Properties
+    
+    var state: State = .initialised
+    var viewController: UIViewController?
+    var animated: Bool?
+    var onDismiss: OnDismissedClosure?
+    
+    // MARK: Functions
+    
+    func present(
+        _ viewController: UIViewController,
+        animated: Bool,
+        onDismiss: OnDismissedClosure?
+    ) {
+        self.viewController = viewController
+        self.animated = animated
+        self.onDismiss = onDismiss
+        self.state = .presented
+    }
+    
+    func dismiss(animated: Bool) {
+        self.animated = animated
+        self.state = .dismissed
+    }
+    
+}
+
+// MARK: - Test view controllers
+
+class SomeViewController: UIViewController {}
+class SomeOtherViewController: UIViewController {}

Tests/Coordinator/Platform/iOS/Protocols/CoordinatorTests.swift

@@ -0,0 +1,137 @@
+//
+//  CoordinatorTests.swift
+//  CoordinatorTests
+//
+//  Created by Javier Cicchelli on 11/04/2023.
+//  Copyright © 2023 Röck+Cöde. All rights reserved.
+//
+
+import Coordinator
+import UIKit
+import XCTest
+
+final class CoordinatorTests: XCTestCase {
+
+    // MARK: Properties
+    
+    private var router: SpyRouter!
+    private var coordinator: Coordinator!
+    
+    // MARK: Tests
+    
+    func test_present_withoutOnDismissClosure() {
+        // Executing this test on the main thread is required as a `UIViewController` instance in being initialised here.
+        DispatchQueue.main.async {
+            // GIVEN
+            self.router = SpyRouter()
+            self.coordinator = SomeCoordinator(router: self.router)
+            
+            
+            // WHEN
+            self.coordinator.present(animated: false, onDismiss: nil)
+            
+            // THEN
+            XCTAssertTrue(self.coordinator.children.isEmpty)
+            XCTAssertEqual(self.router.state, .presented)
+            XCTAssertTrue(self.router.viewController is SomeViewController)
+            XCTAssertFalse(self.router.animated ?? true)
+            XCTAssertNil(self.router.onDismiss)
+        }
+    }
+    
+    func test_present_withOnDismissClosure() {
+        // Executing this test on the main thread is required as a `UIViewController` instance in being initialised here.
+        DispatchQueue.main.async {
+            // GIVEN
+            self.router = SpyRouter()
+            self.coordinator = SomeOtherCoordinator(router: self.router)
+            
+            // WHEN
+            self.coordinator.present(animated: true) {}
+            
+            // THEN
+            XCTAssertTrue(self.coordinator.children.isEmpty)
+            XCTAssertEqual(self.router.state, .presented)
+            XCTAssertTrue(self.router.viewController is SomeOtherViewController)
+            XCTAssertTrue(self.router.animated ?? false)
+            XCTAssertNotNil(self.router.onDismiss)
+        }
+    }
+    
+    func test_presentChild_withoutOnDismissClosure() {
+        // Executing this test on the main thread is required as a `UIViewController` instance in being initialised here.
+        DispatchQueue.main.async {
+            // GIVEN
+            self.router = SpyRouter()
+            self.coordinator = SomeCoordinator(router: self.router)
+            
+            let child = SomeOtherCoordinator(router: self.router)
+            
+            // WHEN
+            self.coordinator.present(child: child, animated: false)
+            
+            // THEN
+            XCTAssertFalse(self.coordinator.children.isEmpty)
+            XCTAssertEqual(self.coordinator.children.count, 1)
+            XCTAssertEqual(self.router.state, .presented)
+            XCTAssertTrue(self.router.viewController is SomeOtherViewController)
+            XCTAssertFalse(self.router.animated ?? true)
+            XCTAssertNil(self.router.onDismiss)
+        }
+    }
+    
+    func test_presentChild_withOnDismissClosure() {
+        // Executing this test on the main thread is required as a `UIViewController` instance in being initialised here.
+        DispatchQueue.main.async {
+            // GIVEN
+            self.router = SpyRouter()
+            self.coordinator = SomeOtherCoordinator(router: self.router)
+            
+            let child = SomeCoordinator(router: self.router)
+            
+            // WHEN
+            self.coordinator.present(child: child, animated: true) {}
+            
+            // THEN
+            XCTAssertFalse(self.coordinator.children.isEmpty)
+            XCTAssertEqual(self.coordinator.children.count, 1)
+            XCTAssertEqual(self.router.state, .presented)
+            XCTAssertTrue(self.router.viewController is SomeViewController)
+            XCTAssertTrue(self.router.animated ?? false)
+            XCTAssertNotNil(self.router.onDismiss)
+        }
+    }
+    
+    func test_dismiss_notAnimated() {
+        // GIVEN
+        router = SpyRouter()
+        coordinator = SomeOtherCoordinator(router: router)
+        
+        // WHEN
+        coordinator.dismiss(animated: false)
+        
+        // THEN
+        XCTAssertTrue(coordinator.children.isEmpty)
+        XCTAssertEqual(router.state, .dismissed)
+        XCTAssertNil(router.viewController)
+        XCTAssertFalse(router.animated ?? true)
+        XCTAssertNil(router.onDismiss)
+    }
+    
+    func test_dismiss_animated() {
+        // GIVEN
+        router = SpyRouter()
+        coordinator = SomeOtherCoordinator(router: router)
+        
+        // WHEN
+        coordinator.dismiss(animated: true)
+        
+        // THEN
+        XCTAssertTrue(coordinator.children.isEmpty)
+        XCTAssertEqual(router.state, .dismissed)
+        XCTAssertNil(router.viewController)
+        XCTAssertTrue(router.animated ?? false)
+        XCTAssertNil(router.onDismiss)
+    }
+
+}