Introduce EnvironmentAccessible and allow for later intialization of @…

…modifier and @model

Sources/Spezi/Capabilities/Observable/EnvironmentAccessible.swift

@@ -0,0 +1,38 @@
+//
+// This source file is part of the Stanford Spezi open-source project
+//
+// SPDX-FileCopyrightText: 2023 Stanford University and the project authors (see CONTRIBUTORS.md)
+//
+// SPDX-License-Identifier: MIT
+//
+
+import SwiftUI
+
+
+/// Places a ``Module`` into the SwiftUI environment.
+///
+/// Below is a short code example how you would declare an environment accessible module,
+/// and how to access it within SwiftUI, if it is configured in your ``Configuration``.
+///
+/// ```swift
+/// public class ExampleModule: Module, EnvironmentAccessible {
+///     // ... implement your functionality
+/// }
+///
+///
+/// struct ExampleView: View {
+///     @Environment(ExampleModule.self) var module
+///
+///     var body: some View {
+///         // ... access module functionality
+///     }
+/// }
+/// ```
+public protocol EnvironmentAccessible: AnyObject, Observable {}
+
+
+extension EnvironmentAccessible {
+    var viewModifier: any ViewModifier {
+        ModelModifier(model: self)
+    }
+}

Sources/Spezi/Capabilities/Observable/ModelPropertyWrapper.swift

@@ -15,15 +15,18 @@ public class _ModelPropertyWrapper<Model: Observable & AnyObject> {
     // swiftlint:disable:previous type_name
     // We want the type to be hidden from autocompletion and documentation generation
 
-    private var storedValue: Model
+    private var storedValue: Model?
     private var collected = false
 
 
     /// Access the store model.
     /// - Note: You cannot access the value once it was collected.
     public var wrappedValue: Model {
         get {
-            storedValue
+            guard let storedValue else {
+                preconditionFailure("@Model was accessed before it was initialized for the first time.")
+            }
+            return storedValue
         }
         set {
             precondition(!collected, "You cannot reassign a @Model property after it was already collected.")
@@ -32,6 +35,9 @@ public class _ModelPropertyWrapper<Model: Observable & AnyObject> {
     }
 
 
+    /// Initialize a new `@Model` property wrappe
+    public init() {}
+
     /// Initialize a new `@Model` property wrapper.
     /// - Parameter wrappedValue: The initial value.
     public init(wrappedValue: Model) {
@@ -67,8 +73,14 @@ extension Module {
 
 
 extension _ModelPropertyWrapper: ViewModifierProvider {
-    var viewModifier: any ViewModifier {
+    var viewModifier: (any ViewModifier)? {
         collected = true
+
+        guard let storedValue else {
+            assertionFailure("@Model with type \(Model.self) was collected but no value was provided!")
+            return nil
+        }
+
         return ModelModifier(model: storedValue)
     }
 

Sources/Spezi/Capabilities/ViewModifier/ModifierPropertyWrapper.swift

@@ -15,15 +15,18 @@ public class _ModifierPropertyWrapper<Modifier: ViewModifier> {
     // swiftlint:disable:previous type_name
     // We want the type to be hidden from autocompletion and documentation generation
 
-    private var storedValue: Modifier
+    private var storedValue: Modifier?
     private var collected = false
 
 
     /// Access the store value.
     /// - Note: You cannot access the value once it was collected.
     public var wrappedValue: Modifier {
         get {
-            storedValue
+            guard let storedValue else {
+                preconditionFailure("@Modifier was accessed before it was initialized for the first time.")
+            }
+            return storedValue
         }
         set {
             precondition(!collected, "You cannot update a @Modifier property after it was already collected.")
@@ -32,6 +35,9 @@ public class _ModifierPropertyWrapper<Modifier: ViewModifier> {
     }
 
 
+    /// Initialize a new `@Modifier` property wrapper.
+    public init() {}
+
     /// Initialize a new `@Modifier` property wrapper.
     /// - Parameter wrappedValue: The initial value.
     public init(wrappedValue: Modifier) {
@@ -69,8 +75,14 @@ extension Module {
 
 
 extension _ModifierPropertyWrapper: ViewModifierProvider {
-    var viewModifier: any ViewModifier {
+    var viewModifier: (any ViewModifier)? {
         collected = true
+
+        guard let storedValue else {
+            assertionFailure("@Modifier with type \(Modifier.self) was collected but no value was provided!")
+            return nil
+        }
+
         return storedValue
     }
 }

Sources/Spezi/Capabilities/ViewModifier/ViewModifierProvider.swift

@@ -22,7 +22,9 @@ enum ModifierPlacement: Int, Comparable {
 /// [`ViewModifier`](https://developer.apple.com/documentation/swiftui/viewmodifier) to be injected into the global view hierarchy.
 protocol ViewModifierProvider {
     /// The view modifier instance that should be injected into the SwiftUI view hierarchy.
-    var viewModifier: any ViewModifier { get }
+    ///
+    /// Does nothing if `nil` is provided.
+    var viewModifier: (any ViewModifier)? { get }
 
     /// Defines the placement order of this view modifier.
     ///
@@ -47,7 +49,7 @@ extension Module {
             .sorted { lhs, rhs in
                 lhs.placement < rhs.placement
             }
-            .map { provider in
+            .compactMap { provider in
                 provider.viewModifier
             }
     }

Sources/Spezi/Spezi.docc/Module.md

@@ -142,13 +142,11 @@ class ExampleModule: Module {
 - ``Module/Provide``
 - ``Module/Collect``
 
-### Managing Model state
+### Interaction with SwiftUI
 
 - ``Module/Model``
-
-### Modifying the View hierarchy
-
 - ``Module/Modifier``
+- ``EnvironmentAccessible``
 
 ### Lifecycle Handling
 

Sources/Spezi/Spezi/Spezi.swift

@@ -95,6 +95,11 @@ public actor Spezi<S: Standard>: AnySpezi {
             module.storeModule(into: &storage)
 
             collectedModifiers.append(contentsOf: module.viewModifiers)
+
+            // If a module is @Observable, we automatically inject it view the `ModelModifier` into the environment.
+            if let observable = module as? EnvironmentAccessible {
+                collectedModifiers.append(observable.viewModifier)
+            }
         }
 
         self.storage = storage

Tests/UITests/TestApp/ModelTests/ModuleWithModel.swift

@@ -27,17 +27,23 @@ class MyModel2 {
 private struct MyModifier: ViewModifier {
     @Environment(MyModel2.self)
     var model
+    @Environment(ModuleWithModel.self)
+    var module
 
     func body(content: Content) -> some View {
         content
-            .environment(\.customKey, model.message == "Hello World")
+            .environment(\.customKey, model.message == "Hello World" && module.message == "MODEL")
     }
 }
 
 
-class ModuleWithModel: Module {
+class ModuleWithModel: Module, EnvironmentAccessible {
     @Model var model = MyModel2(message: "Hello World")
-    @Modifier fileprivate var modifier = MyModifier() // ensure reordering happens, ViewModifier must be able to access the model from environment
+
+    // ensure reordering happens, ViewModifier must be able to access the model from environment
+    @Modifier fileprivate var modifier = MyModifier()
+
+    let message: String = "MODEL"
 }