Supporting to distinguish multiple consent forms during onboarding via an identifier (#50)

.github/workflows/build-and-test.yml

@@ -107,7 +107,7 @@ jobs:
       runsonlabels: '["macOS", "self-hosted"]'
       path: 'Tests/UITests'
       scheme: TestApp
-      destination: 'platform=iOS Simulator,name=iPad Air (5th generation)'
+      destination: 'platform=iOS Simulator,name=iPad Pro 11-inch (M4)'
       buildConfig: ${{ matrix.buildConfig }}
       resultBundle: ${{ matrix.resultBundle }}
       artifactname: ${{ matrix.artifactname }}

Sources/SpeziOnboarding/ConsentConstraint.swift

@@ -0,0 +1,21 @@
+//
+// This source file is part of the Stanford Spezi open-source project
+//
+// SPDX-FileCopyrightText: 2024 Stanford University and the project authors (see CONTRIBUTORS.md)
+//
+// SPDX-License-Identifier: MIT
+//
+
+import Foundation
+import PDFKit
+import Spezi
+
+
+/// A Constraint which all `Standard` instances must conform to when using the `OnboardingConsentView`.
+public protocol ConsentConstraint: Standard {
+    /// Adds a new exported consent form represented as `PDFDocument` to the `Standard` conforming to ``ConsentConstraint``.
+    /// 
+    /// - Parameters:
+    ///     - consent: The exported consent form represented as `ConsentDocumentExport` that should be added.            
+    func store(consent: ConsentDocumentExport) async throws
+}

Sources/SpeziOnboarding/ConsentView/ConsentDocument.swift

@@ -178,7 +178,7 @@ public struct ConsentDocument: View {
     }
 
     private var inputFieldsDisabled: Bool {
-        viewState == .base(.processing) || viewState == .export
+        viewState == .base(.processing) || viewState == .export || viewState == .storing
     }
 
 

Sources/SpeziOnboarding/ConsentView/ConsentDocumentExport.swift

@@ -0,0 +1,47 @@
+//
+// This source file is part of the Stanford Spezi open-source project
+//
+// SPDX-FileCopyrightText: 2022 Stanford University and the project authors (see CONTRIBUTORS.md)
+//
+// SPDX-License-Identifier: MIT
+//
+
+import PDFKit
+
+/// A type representing an exported `ConsentDocument`. It holds the exported `PDFDocument` and the corresponding document identifier String.
+public actor ConsentDocumentExport {
+    /// Provides default values for fields related to the `ConsentDocumentExport`.
+    public enum Defaults {
+        /// Default value for a document identifier.
+        /// This identifier will be used as default value if no identifier is provided.
+        public static let documentIdentifier = "ConsentDocument"
+    }
+
+    private var cachedPDF: PDFDocument
+
+    /// An unique identifier for the exported `ConsentDocument`.
+    /// Corresponds to the identifier which was passed  when creating the `ConsentDocument` using an `OnboardingConsentView`.
+    public let documentIdentifier: String
+    /// The `PDFDocument` exported from a `ConsentDocument`.
+    /// This property is asynchronous and accesing it potentially triggers the export of the PDF from the underlying `ConsentDocument`,
+    /// if the `ConsentDocument` has not been previously exported or the `PDFDocument` was not cached.
+    /// For now, we always require a PDF to be cached to create a ConsentDocumentExport. In the future, we might change this to lazy-PDF loading.
+    public var pdf: PDFDocument {
+        get async {
+            cachedPDF
+        }
+    }
+
+
+    /// Creates a `ConsentDocumentExport`, which holds an exported PDF and the corresponding document identifier string.
+    /// - Parameters:
+    ///   - documentIdentfier: A unique String identifying the exported `ConsentDocument`.
+    ///   - cachedPDF: A `PDFDocument` exported from a `ConsentDocument`.
+    init(
+        documentIdentifier: String,
+        cachedPDF: PDFDocument
+    ) {
+        self.documentIdentifier = documentIdentifier
+        self.cachedPDF = cachedPDF
+    }
+}

Sources/SpeziOnboarding/ConsentView/ConsentViewState.swift

@@ -35,4 +35,6 @@ public enum ConsentViewState: Equatable {
     ///
     /// The export procedure (resulting in the ``ConsentViewState/exported(document:)`` state) can be triggered via setting the ``ConsentViewState/export`` state of the ``ConsentDocument``    .
     case exported(document: PDFDocument)
+    /// The `storing` state indicates that the ``ConsentDocument`` is currently being stored to the Standard.
+    case storing
 }

Sources/SpeziOnboarding/OnboardingConsentView.swift

@@ -6,10 +6,14 @@
 // SPDX-License-Identifier: MIT
 //
 
+#if os(macOS)
+import AppKit
+#endif
+
 import Foundation
+import SpeziViews
 import SwiftUI
 
-
 /// Onboarding view to display markdown-based consent documents that can be signed and exported.
 ///
 /// The `OnboardingConsentView` provides a convenient onboarding view for the display of markdown-based documents that can be
@@ -21,6 +25,16 @@ import SwiftUI
 /// The `OnboardingConsentView` builds on top of the SpeziOnboarding ``ConsentDocument`` 
 /// by providing a more developer-friendly, convenient API with additional functionalities like the share consent option.
 ///
+/// If you want to use multiple `OnboardingConsentView`, you can provide each with an identifier (see below).
+/// The identifier allows to distinguish the consent forms in the `Standard`.
+/// Any identifier is a string. We recommend storing and grouping consent document identifiers in an enum:
+/// ```swift
+/// enum DocumentIdentifiers {
+///     static let first = "firstConsentDocument"
+///     static let second = "secondConsentDocument"
+/// }
+/// ```
+///
 /// ```swift
 /// OnboardingConsentView(
 ///     markdown: {
@@ -30,6 +44,8 @@ import SwiftUI
 ///         // The action that should be performed once the user has provided their consent.
 ///     },
 ///     title: "Consent",   // Configure the title of the consent view
+///     identifier: DocumentIdentifiers.first, // Specify a unique identifier String, preferably bundled
+///                                            // in an enum (see above). Only relevant if more than one OnboardingConsentView is needed.
 ///     exportConfiguration: .init(paperSize: .usLetter)   // Configure the properties of the exported consent form
 /// )
 /// ```
@@ -41,18 +57,21 @@ public struct OnboardingConsentView: View {
             LocalizedStringResource("CONSENT_VIEW_TITLE", bundle: .atURL(from: .module))
         }
     }
-
-
+
     private let markdown: () async -> Data
     private let action: () async -> Void
     private let title: LocalizedStringResource?
+    private let identifier: String
     private let exportConfiguration: ConsentDocument.ExportConfiguration
-
+    private var backButtonHidden: Bool {
+        viewState == .storing || (viewState == .export && !willShowShareSheet)
+    }
+
     @Environment(OnboardingDataSource.self) private var onboardingDataSource
     @State private var viewState: ConsentViewState = .base(.idle)
     @State private var willShowShareSheet = false
     @State private var showShareSheet = false
-    
+
 
     public var body: some View {
         ScrollViewReader { proxy in // swiftlint:disable:this closure_body_length
@@ -73,25 +92,39 @@ public struct OnboardingConsentView: View {
                     .padding(.bottom)
                 },
                 actionView: {
-                    OnboardingActionsView(
-                        LocalizedStringResource("CONSENT_ACTION", bundle: .atURL(from: .module)),
+                    Button(
                         action: {
                             viewState = .export
+                        },
+                        label: {
+                            Text("CONSENT_ACTION", bundle: .module)
+                                .frame(maxWidth: .infinity, minHeight: 38)
+                                .processingOverlay(isProcessing: viewState == .storing || (viewState == .export && !willShowShareSheet))
                         }
                     )
+                        .buttonStyle(.borderedProminent)
                         .disabled(!actionButtonsEnabled)
                         .animation(.easeInOut, value: actionButtonsEnabled)
                         .id("ActionButton")
                 }
             )
             .scrollDisabled($viewState.signing.wrappedValue)
+            .navigationBarBackButtonHidden(backButtonHidden)
             .onChange(of: viewState) {
                 if case .exported(let exportedConsentDocumented) = viewState {
                     if !willShowShareSheet {
-                        Task { @MainActor in
-                            /// Stores the finished PDF in the Spezi `Standard`.
-                            await onboardingDataSource.store(exportedConsentDocumented)
-                            await action()
+                        viewState = .storing
+                        Task {
+                            do {
+                                /// Stores the finished PDF in the Spezi `Standard`.
+                                try await onboardingDataSource.store(exportedConsentDocumented, identifier: identifier)
+
+                                await action()
+                                viewState = .base(.idle)
+                            } catch {
+                                // In case of error, go back to previous state.
+                                viewState = .base(.error(AnyLocalizedError(error: error)))
+                            }
                         }
                     } else {
                         showShareSheet = true
@@ -103,18 +136,29 @@ public struct OnboardingConsentView: View {
         }
             .toolbar {
                 ToolbarItem(placement: .primaryAction) {
-                    Button(action: {
-                        viewState = .export
-                        willShowShareSheet = true
-                    }) {
-                        Label {
-                            Text("CONSENT_SHARE", bundle: .module)
-                        } icon: {
-                            Image(systemName: "square.and.arrow.up")
-                                .accessibilityHidden(true)
+                    Button(
+                        action: {
+                            viewState = .export
+                            willShowShareSheet = true
+                        },
+                        label: {
+                            if willShowShareSheet {
+                                HStack {
+                                    Spacer()
+                                    ProgressView()
+                                    Spacer()
+                                }
+                            } else {
+                                Label {
+                                    Text("CONSENT_SHARE", bundle: .module)
+                                } icon: {
+                                    Image(systemName: "square.and.arrow.up")
+                                        .accessibilityHidden(true)
+                                }
+                            }
                         }
-                    }
-                        .disabled(!actionButtonsEnabled)
+                    )
+                        .disabled(!actionButtonsEnabled || willShowShareSheet)
                 }
             }
             .sheet(isPresented: $showShareSheet) {
@@ -141,6 +185,7 @@ public struct OnboardingConsentView: View {
                     showShareSheet = false
                 }
             }
+
             // `NSSharingServicePicker` doesn't provide a completion handler as `UIActivityViewController` does,
             // therefore necessitating the deletion of the temporary file on disappearing.
             .onDisappear {
@@ -155,7 +200,7 @@ public struct OnboardingConsentView: View {
 
     private var actionButtonsEnabled: Bool {
         switch viewState {
-        case .signing, .signed, .export, .exported: true
+        case .signing, .signed, .exported: true
         default: false
         }
     }
@@ -166,17 +211,20 @@ public struct OnboardingConsentView: View {
     ///   - markdown: The markdown content provided as an UTF8 encoded `Data` instance that can be provided asynchronously.
     ///   - action: The action that should be performed once the consent is given.
     ///   - title: The title of the view displayed at the top. Can be `nil`, meaning no title is displayed.
+    ///   - identifier: A unique identifier or "name" for the consent form, helpful for distinguishing consent forms when storing in the `Standard`.
     ///   - exportConfiguration: Defines the properties of the exported consent form via ``ConsentDocument/ExportConfiguration``.
     public init(
         markdown: @escaping () async -> Data,
         action: @escaping () async -> Void,
         title: LocalizedStringResource? = LocalizationDefaults.consentFormTitle,
+        identifier: String = ConsentDocumentExport.Defaults.documentIdentifier,
         exportConfiguration: ConsentDocument.ExportConfiguration = .init()
     ) {
         self.markdown = markdown
         self.exportConfiguration = exportConfiguration
         self.title = title
         self.action = action
+        self.identifier = identifier
     }
 }
 

Sources/SpeziOnboarding/OnboardingConstraint.swift

@@ -12,9 +12,26 @@ import Spezi
 
 
 /// A Constraint which all `Standard` instances must conform to when using the Spezi Onboarding module.
+@available(
+    *,
+    deprecated,
+    message: """
+    Storing consent documents without an identifier is deprecated.
+    Please use `ConsentConstraint` instead.
+    """
+)
 public protocol OnboardingConstraint: Standard {
     /// Adds a new exported consent form represented as `PDFDocument` to the `Standard` conforming to ``OnboardingConstraint``.
     /// 
-    /// - Parameter consent: The exported consent form represented as `PDFDocument` that should be added.
+    /// - Parameters:
+    ///     - consent: The exported consent form represented as `PDFDocument` that should be added.
+    @available(
+        *,
+        deprecated,
+        message: """
+        Storing consent documents without an identifier is deprecated.
+        Please use `ConsentConstraint.store(consent: PDFDocument, identifier: String)` instead.
+        """
+    )
     func store(consent: PDFDocument) async
 }

Sources/SpeziOnboarding/OnboardingDataSource.swift

@@ -34,18 +34,29 @@
 /// }
 /// ```
 public class OnboardingDataSource: Module, EnvironmentAccessible {
-    @StandardActor var standard: any OnboardingConstraint
+    @StandardActor var standard: any Standard
 
 
     public init() { }
-
+
+
+    public func configure() {
+        guard standard is any OnboardingConstraint || standard is any ConsentConstraint else {
+            fatalError("A \(type(of: standard).self) must conform to `ConsentConstraint` to process signed consent documents.")
+        }
+    }
 
     /// Adds a new exported consent form represented as `PDFDocument` to the ``OnboardingDataSource``.
     ///
-    /// - Parameter consent: The exported consent form represented as `PDFDocument` that should be added.
-    public func store(_ consent: PDFDocument) async {
-        Task { @MainActor in
-            await standard.store(consent: consent)
+    /// - Parameter consent: The exported consent form represented as `ConsentDocumentExport` that should be added.
+    public func store(_ consent: PDFDocument, identifier: String = ConsentDocumentExport.Defaults.documentIdentifier) async throws {
+        if let consentConstraint = standard as? any ConsentConstraint {
+            let consentDocumentExport = ConsentDocumentExport(documentIdentifier: identifier, cachedPDF: consent)
+            try await consentConstraint.store(consent: consentDocumentExport)
+        } else if let onboardingConstraint = standard as? any OnboardingConstraint {
+            await onboardingConstraint.store(consent: consent)
+        } else {
+            fatalError("A \(type(of: standard).self) must conform to `ConsentConstraint` to process signed consent documents.")
         }
     }
 }