Introduce SpeziPersonalInfo target

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

@@ -20,9 +20,9 @@ jobs:
     name: Build and Test Swift Package
     uses: StanfordSpezi/.github/.github/workflows/xcodebuild-or-fastlane.yml@v2
     with:
-      artifactname: SpeziViews.xcresult
+      artifactname: SpeziViews-Package.xcresult
       runsonlabels: '["macOS", "self-hosted"]'
-      scheme: SpeziViews
+      scheme: SpeziViews-Package
   buildandtestuitests:
     name: Build and Test UI Tests
     uses: StanfordSpezi/.github/.github/workflows/xcodebuild-or-fastlane.yml@v2
@@ -36,4 +36,4 @@ jobs:
     needs: [buildandtest, buildandtestuitests]
     uses: StanfordSpezi/.github/.github/workflows/create-and-upload-coverage-report.yml@v2
     with:
-      coveragereports: SpeziViews.xcresult TestApp.xcresult
+      coveragereports: SpeziViews-Package.xcresult TestApp.xcresult

Package.swift

@@ -1,4 +1,4 @@
-// swift-tools-version:5.7
+// swift-tools-version:5.9
 
 //
 // This source file is part of the Stanford Spezi open-source project
@@ -15,19 +15,27 @@ let package = Package(
     name: "SpeziViews",
     defaultLocalization: "en",
     platforms: [
-        .iOS(.v16)
+        .iOS(.v17)
     ],
     products: [
-        .library(name: "SpeziViews", targets: ["SpeziViews"])
+        .library(name: "SpeziViews", targets: ["SpeziViews"]),
+        .library(name: "SpeziPersonalInfo", targets: ["SpeziPersonalInfo"])
     ],
     targets: [
         .target(
             name: "SpeziViews"
         ),
+        .target(
+            name: "SpeziPersonalInfo",
+            dependencies: [
+                .target(name: "SpeziViews")
+            ]
+        ),
         .testTarget(
             name: "SpeziViewsTests",
             dependencies: [
-                .target(name: "SpeziViews")
+                .target(name: "SpeziViews"),
+                .target(name: "SpeziPersonalInfo")
             ]
         )
     ]

Sources/SpeziPersonalInfo/Fields/NameFieldRow.swift

@@ -0,0 +1,139 @@
+//
+// 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 SpeziViews
+import SwiftUI
+
+
+/// A `NameTextField` that always shows a description in front of the text field.
+///
+/// The `NameFieldRow` uses the `DescriptionGridRow` and is to be placed into a [Grid](https://developer.apple.com/documentation/swiftui/grid)
+/// view to provide a description text in front of the ``NameTextField``.
+///
+/// Below is a short code example on how to collect both the given name and family name of a person within a SwiftUI `Form`.
+/// ```swift
+/// @State private var name = PersonNameComponents()
+///
+/// var body: some View {
+///     Form {
+///         Grid(horizontalSpacing: 15) { // optional horizontal spacing
+///             NameFieldRow(name: $name, for: \.givenName) {
+///                 Text(verbatim: "First")
+///             } label: {
+///                 Text(verbatim: "enter first name")
+///             }
+///
+///             Divider()
+///                 .gridCellUnsizedAxes(.horizontal)
+///
+///             NameFieldRow(name: $name, for: \.familyName) {
+///                 Text(verbatim: "Last")
+///             } label: {
+///                 Text(verbatim: "enter last name")
+///             }
+///         }
+///     }
+/// }
+/// ```
+public struct NameFieldRow<Description: View, Label: View>: View {
+    private let description: Description
+    private let label: Label
+    private let component: WritableKeyPath<PersonNameComponents, String?>
+
+    @Binding private var name: PersonNameComponents
+
+
+    public var body: some View {
+        DescriptionGridRow {
+            description
+        } content: {
+            NameTextField(name: $name, for: component) {
+                label
+            }
+        }
+    }
+
+
+    /// Creates a name text field with a description label.
+    /// - Parameters:
+    ///   - description: The localized description label displayed before the text field.
+    ///   - name: The name to display and edit.
+    ///   - component: The `KeyPath` to the property of the provided `PersonNameComponents` to display and edit.
+    ///   - label: A view that describes the purpose of the text field.
+    public init(
+        _ description: LocalizedStringResource,
+        name: Binding<PersonNameComponents>,
+        for component: WritableKeyPath<PersonNameComponents, String?>,
+        @ViewBuilder label: () -> Label
+    ) where Description == Text {
+        self.init(name: name, for: component, description: { Text(description) }, label: label)
+    }
+
+    /// Creates a name text field with a description label.
+    /// - Parameters:
+    ///   - name: The name to display and edit.
+    ///   - component: The `KeyPath` to the property of the provided `PersonNameComponents` to display and edit.
+    ///   - prompt: An optional `Text` prompt. Refer to the documentation of `TextField` for more information.
+    ///   - description: The description label displayed before the text field.
+    ///   - label: A view that describes the purpose of the text field.
+    public init(
+        name: Binding<PersonNameComponents>,
+        for component: WritableKeyPath<PersonNameComponents, String?>,
+        @ViewBuilder description: () -> Description,
+        @ViewBuilder label: () -> Label
+    ) {
+        self._name = name
+        self.component = component
+        self.description = description()
+        self.label = label()
+    }
+}
+
+
+#if DEBUG
+#Preview {
+    @State var name = PersonNameComponents()
+    return Grid(horizontalSpacing: 15) {
+        NameFieldRow(name: $name, for: \.familyName) {
+            Text(verbatim: "First")
+        } label: {
+            Text(verbatim: "enter first name")
+        }
+
+        Divider()
+            .gridCellUnsizedAxes(.horizontal)
+
+        NameFieldRow(name: $name, for: \.familyName) {
+            Text(verbatim: "Last")
+        } label: {
+            Text(verbatim: "enter last name")
+        }
+    }
+}
+#Preview {
+    @State var name = PersonNameComponents()
+    return Form {
+        Grid(horizontalSpacing: 15) {
+            NameFieldRow(name: $name, for: \.givenName) {
+                Text(verbatim: "First")
+            } label: {
+                Text(verbatim: "enter first name")
+            }
+
+            Divider()
+                .gridCellUnsizedAxes(.horizontal)
+
+            NameFieldRow(name: $name, for: \.familyName) {
+                Text(verbatim: "Last")
+            } label: {
+                Text(verbatim: "enter last name")
+            }
+        }
+    }
+}
+#endif

Sources/SpeziPersonalInfo/Fields/NameTextField.swift

@@ -0,0 +1,122 @@
+//
+// 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
+
+
+/// A TextField for properties of `PersonNameComponents`.
+///
+/// The `NameTextField` view allows to create a SwiftUI [TextField](https://developer.apple.com/documentation/swiftui/textfield) for properties
+/// of [PersonNameComponents](https://developer.apple.com/documentation/foundation/personnamecomponents).
+/// To do so you supply a Binding to your `PersonNameComponents` value and a `KeyPath` to the property of `PersonNameComponents` you are trying to input.
+///
+/// `NameTextField` modifies the underlying `TextField` to optimize for name entry and automatically sets modifiers like
+/// [textContentType(_:)](https://developer.apple.com/documentation/swiftui/view/textcontenttype(_:)-ufdv).
+///
+/// Below is a short code example on how to create an editable text interface for the given name of a person.
+/// ```swift
+/// @State private var name = PersonNameComponents()
+///
+/// var body: some View {
+///     NameTextField("enter first name", name: $name, for: \.givenName)
+/// }
+/// ```
+///
+/// - Note: A empty string will be automatically mapped to a `nil` value for the respective property of `PersonNameComponents`.
+public struct NameTextField<Label: View>: View {
+    private let prompt: Text?
+    private let label: Label
+    private let nameComponent: WritableKeyPath<PersonNameComponents, String?>
+
+    @Binding private var name: PersonNameComponents
+
+    private var componentBinding: Binding<String> {
+        Binding {
+            name[keyPath: nameComponent] ?? ""
+        } set: { newValue in
+            name[keyPath: nameComponent] = newValue.isEmpty ? nil : newValue
+        }
+    }
+
+    private var contentType: UITextContentType? {
+        switch nameComponent {
+        case \.namePrefix:
+            return .namePrefix
+        case \.nameSuffix:
+            return .nameSuffix
+        case \.givenName:
+            return .givenName
+        case \.middleName:
+            return .middleName
+        case \.familyName:
+            return .familyName
+        case \.nickname:
+            return .nickname
+        default:
+            return .name // general, catch all content type
+        }
+    }
+
+
+    public var body: some View {
+        TextField(text: componentBinding, prompt: prompt) {
+            label
+        }
+            .autocorrectionDisabled()
+            .textInputAutocapitalization(.words)
+            .textContentType(contentType)
+    }
+
+
+    /// Creates a name text field with an optional prompt.
+    /// - Parameters:
+    ///   - label: A localized title of the text field, describing its purpose.
+    ///   - name: The name to display and edit.
+    ///   - component: The `KeyPath` to the property of the provided `PersonNameComponents` to display and edit.
+    ///   - prompt: An optional `Text` prompt. Refer to the documentation of `TextField` for more information.
+    public init(
+        _ label: LocalizedStringResource,
+        name: Binding<PersonNameComponents>,
+        for component: WritableKeyPath<PersonNameComponents, String?>,
+        prompt: Text? = nil
+    ) where Label == Text {
+        self.init(name: name, for: component, prompt: prompt) {
+            Text(label)
+        }
+    }
+
+    /// Creates a name text field with an optional prompt.
+    /// - Parameters:
+    ///   - name: The name to display and edit.
+    ///   - component: The `KeyPath` to the property of the provided `PersonNameComponents` to display and edit.
+    ///   - prompt: An optional `Text` prompt. Refer to the documentation of `TextField` for more information.
+    ///   - label: A view that describes the purpose of the text field.
+    public init(
+        name: Binding<PersonNameComponents>,
+        for component: WritableKeyPath<PersonNameComponents, String?>,
+        prompt: Text? = nil,
+        @ViewBuilder label: () -> Label
+    ) {
+        self._name = name
+        self.nameComponent = component
+        self.prompt = prompt
+        self.label = label()
+    }
+}
+
+
+#if DEBUG
+#Preview {
+    @State var name = PersonNameComponents()
+    return List {
+        NameTextField(name: $name, for: \.givenName) {
+            Text(verbatim: "enter first name")
+        }
+    }
+}
+#endif

Sources/SpeziPersonalInfo/Resources/Localizable.xcstrings

@@ -0,0 +1,7 @@
+{
+  "sourceLanguage" : "en",
+  "strings" : {
+
+  },
+  "version" : "1.0"
+}

Sources/SpeziPersonalInfo/Resources/Localizable.xcstrings.license

@@ -0,0 +1,6 @@
+
+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

Sources/SpeziPersonalInfo/SpeziPersonalInfo.docc/SpeziPersonalInfo.md

@@ -0,0 +1,24 @@
+# ``SpeziPersonalInfo``
+
+A SpeziViews target that provides a common set of SwiftUI views and related functionality for managing personal information.
+
+<!--
+
+This source file is part of the Spezi open-source project
+
+SPDX-FileCopyrightText: 2023 Stanford University and the project authors (see CONTRIBUTORS.md)
+
+SPDX-License-Identifier: MIT
+
+-->
+
+## Topics
+
+### Person Name
+
+- ``NameTextField``
+- ``NameFieldRow``
+
+### User Profile
+
+- ``UserProfileView``