Merge branch 'main' into experiment/data-cache-as-macro

Author: jmarek41

README.md

@@ -14,6 +14,8 @@ This target contains types and protocols supporting the architecture. See
 
 The repository uses [DocC](https://www.swift.org/documentation/docc/) for developer-friendly access to documentation.
 
+More high-level documentation can be found in the Futured Engineering Handbook [here](https://futuredapp.github.io/Engineering-Handbook/teams/ios/ios_architecture/).
+
 ### FuturedHelpers
 
 This target contains non-mandatory extension to the Architecture and additional types and Views which

Sources/FuturedArchitecture/Architecture/Alert/AlertModel.swift

@@ -4,7 +4,7 @@ import SwiftUI
 ///
 /// ## Overview
 ///
-/// It wrappes the native `alert(_:isPresented:presenting:actions:message:)`, but you show an alert in different way by using the `defaultAlert(model:)` view modifier,
+/// It wraps the native `alert(_:isPresented:presenting:actions:message:)`, but you show an alert in different way by using the `defaultAlert(model:)` view modifier,
 /// which then appears whenever the bound `model` value is not `nil` value.
 /// Alert model contains two actions: `primaryAction` and `secondaryAction`, which are then represented as SwiftUI Button
 /// If both values are nil, system presents alert with standard "OK" button and given `title` and `message`
@@ -62,12 +62,23 @@ public struct AlertModel: Identifiable {
         }
     }
 
+    public struct TextField {
+        let title: String
+        let text: Binding<String>
+
+        public init(title: String, text: Binding<String>) {
+            self.title = title
+            self.text = text
+        }
+    }
+
     public var id: String? {
         title + (message ?? "")
     }
 
     let title: String
     let message: String?
+    let textField: TextField?
     let primaryAction: ButtonAction?
     let secondaryAction: ButtonAction?
 
@@ -78,9 +89,16 @@ public struct AlertModel: Identifiable {
     ///   - primaryAction: The specification of the alert primary action.
     ///   - secondaryAction: The specification of the alert secondary action.
 
-    public init(title: String, message: String?, primaryAction: ButtonAction? = nil, secondaryAction: ButtonAction? = nil) {
+    public init(
+        title: String,
+        message: String?,
+        textField: TextField? = nil,
+        primaryAction: ButtonAction? = nil,
+        secondaryAction: ButtonAction? = nil
+    ) {
         self.title = title
         self.message = message
+        self.textField = textField
         self.primaryAction = primaryAction
         self.secondaryAction = secondaryAction
     }

Sources/FuturedArchitecture/Architecture/Alert/AlertModifier.swift

@@ -20,20 +20,22 @@ private struct AlertModifier: ViewModifier {
             ),
             presenting: model,
             actions: { model in
+                if let textField = model.textField {
+                    TextField(textField.title, text: textField.text)
+                }
                 if let primaryAction = model.primaryAction {
                     Button(
                         primaryAction.title,
                         role: primaryAction.buttonRole,
                         action: primaryAction.action
                     )
-
-                    if let secondaryAction = model.secondaryAction {
-                        Button(
-                            secondaryAction.title,
-                            role: secondaryAction.buttonRole,
-                            action: secondaryAction.action
-                        )
-                    }
+                }
+                if let secondaryAction = model.secondaryAction {
+                    Button(
+                        secondaryAction.title,
+                        role: secondaryAction.buttonRole,
+                        action: secondaryAction.action
+                    )
                 }
             },
             message: { model in

Sources/FuturedArchitecture/Architecture/Coordinator.swift

@@ -1,12 +1,12 @@
 import SwiftUI
 
-/// This architecture is modelled around the concept of *Flow Coordinators*. You might think about
+/// This architecture is modeled around the concept of *Flow Coordinators*. You might think about
 /// *flow coordinator* as a "view model for container view." For example, whereas data model of
 /// a Table View is stored in a *component model*, data model of ``SwiftUI.TabView`` and ``SwiftUI.NavigationStack``
 /// is stored in an instance conforming to `Coordinator`.
 ///
 /// This base `protocol` contains set of common requirements for all coordinators. Other protocols
-/// tailored to specific Containers are provided aswell.
+/// tailored to specific Containers are provided as well.
 public protocol Coordinator: ObservableObject {
     /// Type used to represent the state of the container, i.e. which child-components should be presented.
     associatedtype Destination: Hashable & Identifiable
@@ -17,7 +17,7 @@ public protocol Coordinator: ObservableObject {
 
     /// `rootView` returns the coordinator's main view.
     /// - Note: It is common pattern to provide a default "destination" view as the body of the *container* instead of
-    /// ``SwiftUI.EmptyView``. If you do so, remeber to always capture the `instance` of the *coordinator* weakly!
+    /// ``SwiftUI.EmptyView``. If you do so, remember to always capture the `instance` of the *coordinator* weakly!
     /// - Warning: Maintain its purity by defining only the view, without added logic or modifiers.
     /// If logic or modifiers are needed, encapsulate them in a separate view that can accommodate necessary dependencies.
     /// Skipping this recommendation may prevent UI updates when changing `@Published` properties, as `rootView` is static.
@@ -72,8 +72,8 @@ public extension Coordinator {
 
 /// `TabCoordinator` provides additional requirements for the use with ``SwiftUI.TabView``.
 /// This *coordinator* is ment to have ``TabViewFlow`` as the Root view.
-/// - Experiment: This API is in preview and subjet to change.
-/// - Todo: ``SwiftUI.TabView`` requires internal state, which is forbiddden as per
+/// - Experiment: This API is in preview and subject to change.
+/// - Todo: ``SwiftUI.TabView`` requires internal state, which is forbidden as per
 /// documentation of ``Coordinator.rootView(with:)``. Also, the API introduces `Tab` type
 /// which is essentially duplication of `Destination`. Consider, how the API limits the use of tabs.
 public protocol TabCoordinator: Coordinator {
@@ -95,7 +95,7 @@ public protocol VariantCoordinator: TabCoordinator {}
 ///
 /// - ToDo: Create a template for this coordinator.
 public protocol NavigationStackCoordinator: Coordinator {
-    /// Property modelling the Views currently placed on stack.
+    /// Property modeling the Views currently placed on stack.
     @MainActor
     var path: [Destination] { get set }
 }
@@ -114,7 +114,7 @@ public extension NavigationStackCoordinator {
     }
 
     /// Convenience function used to remove all views from the stack, until the provided destination.
-    /// - Parameter destination: Destination to be reached. If nil is passed, or such destionation
+    /// - Parameter destination: Destination to be reached. If nil is passed, or such destination
     /// is not currently on the stack, all views are removed.
     /// - Experiment: This API is in preview and subject to change.
     @MainActor

Sources/FuturedArchitecture/Architecture/DataCache.swift

@@ -10,8 +10,8 @@ import Foundation
 /// only via provided `update` methods. As a general rule, value types should
 /// be used as a `Model`.
 ///
-/// - Experiment: This API is in preview and subjet to change.
-/// - ToDo: How the `DataCache` may interact with persistance such as
+/// - Experiment: This API is in preview and subject to change.
+/// - ToDo: How the `DataCache` may interact with persistence such as
 /// `CoreData` or `SwiftData` is an open question and subject of further
 /// research.
 public actor ActorDataCache<Model: Equatable> {
@@ -34,10 +34,38 @@ public actor ActorDataCache<Model: Equatable> {
     /// Atomically update one variable.
     ///
     /// - ToDo: Investigate whether we can use variadic generics to improve the API.
-    /// No change is emmited when the value is the same.
+    /// No change is emitted when the value is the same.
     @inlinable
     public func update<T: Equatable>(_ keyPath: WritableKeyPath<Model, T>, with value: T) {
         guard value != self.value[keyPath: keyPath] else { return }
         self.value[keyPath: keyPath] = value
     }
+
+    /// Populate one variable of Collection type.
+    ///  - Description: The method will append new elements to the existing collection. The elements which are already in the collection as well as in the new collection will be updated. No change is emmited when the new collection is empty.
+    @inlinable
+    public func populate<T: Collection>(_ keyPath: WritableKeyPath<Model, T>, with collection: T) where T.Element: Equatable {
+        guard !collection.isEmpty else { return }
+        var values = self.value[keyPath: keyPath].filter { !collection.contains($0) }
+        values.append(contentsOf: collection)
+        guard let values = values as? T else {
+            assertionFailure("Cannot convert back to generic")
+            return
+        }
+        self.value[keyPath: keyPath] = values
+    }
+
+    /// Populate one optional variable of Collection type.
+    /// - Description: The method will append new elements to the existing collection. The elements which are already in the collection as well as in the new collection will be updated. No change is emmited when the new collection is empty.
+    @inlinable
+    public func populate<T: Collection>(_ keyPath: WritableKeyPath<Model, T?>, with collection: T) where T.Element: Equatable {
+        guard !collection.isEmpty else { return }
+        var values = self.value[keyPath: keyPath]?.filter { !collection.contains($0) } ?? []
+        values.append(contentsOf: collection)
+        guard let values = values as? T else {
+            assertionFailure("Cannot convert back to generic")
+            return
+        }
+        self.value[keyPath: keyPath] = values
+    }
 }

Sources/FuturedArchitecture/Architecture/ModalCoverModel.swift

@@ -1,13 +1,32 @@
 //
 //  ModalCoverModel.swift
-//  
+//
 //
 //  Created by Simon Sestak on 01/08/2024.
 //
 
+import SwiftUI
 import Foundation
 
-/// Style of the modally presented view. 
+
+public enum SheetDetent: Hashable {
+    case medium
+    case large
+    case fraction(CGFloat)
+
+    func detent() -> PresentationDetent {
+        switch self {
+        case .medium:
+            return .medium
+        case .large:
+            return .large
+        case let .fraction(fraction):
+            return .fraction(fraction)
+        }
+    }
+}
+
+/// Style of the modally presented view.
 ///
 /// It is intended to be used with ``ModalCoverModel``. Style has been placed to
 /// the global scope, since the Model is generic.

Sources/FuturedArchitecture/Architecture/NavigationStackFlow.swift

@@ -6,31 +6,34 @@ public struct NavigationStackFlow<Coordinator: NavigationStackCoordinator, Conte
     @StateObject private var coordinator: Coordinator
     @ViewBuilder private let content: () -> Content
 
+    /// Use in case when whole navigation stack should have detents.
+    @State private var navigationDetents: Set<PresentationDetent>?
+
     /// - Parameters:
+    ///   - detents: The set of detents which should be applied to the whole navigation stack.
     ///   - coordinator: The instance of the coordinator used as the model and retained as the ``SwiftUI.StateObject``
     ///   - content: The root view of this navigation stack. The ``navigationDestination(for:destination:)`` modifier
     ///   is applied to this content.
-    public init(coordinator: @autoclosure @escaping () -> Coordinator, content: @MainActor @escaping () -> Content) {
+    public init(
+        detents: Set<SheetDetent>? = nil,
+        coordinator: @autoclosure @escaping () -> Coordinator,
+        content: @MainActor @escaping () -> Content
+    ) {
+        self.navigationDetents = detents == nil ? nil : Set(detents!.map { $0.detent() })
         self._coordinator = StateObject(wrappedValue: coordinator())
         self.content = content
     }
 
-    #if os(macOS)
-    public var body: some View {
-        NavigationStack(path: $coordinator.path) {
-            content().navigationDestination(for: Coordinator.Destination.self, destination: coordinator.scene(for:))
-        }
-        .sheet(item: sheetBinding, onDismiss: coordinator.onModalDismiss, content: coordinator.scene(for:))
-    }
-    #else
     public var body: some View {
         NavigationStack(path: $coordinator.path) {
             content().navigationDestination(for: Coordinator.Destination.self, destination: coordinator.scene(for:))
         }
+        .presentationDetents(navigationDetents ?? [])
         .sheet(item: sheetBinding, onDismiss: coordinator.onModalDismiss, content: coordinator.scene(for:))
+        #if !os(macOS)
         .fullScreenCover(item: fullscreenCoverBinding, onDismiss: coordinator.onModalDismiss, content: coordinator.scene(for:))
+        #endif
     }
-    #endif
 
     private var sheetBinding: Binding<Coordinator.Destination?> {
         .init {

Sources/FuturedArchitecture/Architecture/TabViewFlow.swift

@@ -2,7 +2,7 @@ import SwiftUI
 
 /// The `TabViewFlow` encapsulates the ``SwiftUI.TabView`` and binds it to the
 /// variables and callbacks of the ``TabCoordinator`` which is retains as a ``SwiftUI.StateObject``.
-/// - Experiment: This API is in preview and subjet to change.
+/// - Experiment: This API is in preview and subject to change.
 public struct TabViewFlow<Coordinator: TabCoordinator, Content: View>: View {
     @StateObject private var coordinator: Coordinator
     @ViewBuilder private let content: () -> Content

Sources/FuturedArchitecture/Documentation.docc/Documentation.md

@@ -6,7 +6,7 @@ The FuturedKit Architecture is a flow-coordinator, component, component model ba
 
 This architecture uses some concepts which may be familiar, but we decided to modify the usual naming (mainly due to naming conflits with existing APIs).
 
-![overview](archoverview)
+![overview](Images/archoverview.svg)
 
 ### Scene
 

Sources/FuturedHelpers/Helpers/SceneDelegate.swift

@@ -36,7 +36,7 @@ extension View {
     /// - Parameter sceneDelegate: The SceneDelegate to set.
     /// - Description:
     /// In the main app root view call this modifier and pass the SceneDelegate. You need to specify the AppSceneDelegate which conforms to the UIWindowSceneDelegate.
-    /// This is necessary because the SceneDelegate is accessible in SwiftUI only via EnviromentObject.
+    /// This is necessary because the SceneDelegate is accessible in SwiftUI only via EnvironmentObject.
     public func set<T: AppSceneDelegate>(appSceneDelegateClass: T.Type, sceneDelegate: SceneDelegate) -> some View {
         modifier(SceneDelegateWrapperViewModifier<T>(delegate: sceneDelegate))
     }