Skill: foscomputerservices/fosmvvm-swiftui-view-generator (version 2.0.6)

--- name: fosmvvm-swiftui-view-generator description: Generate SwiftUI views that render FOSMVVM ViewModels. Scaffolds ViewModelView pattern with binding, loading states, and previews. homepage: https://github.com/foscomputerservices/FOSUtilities metadata: {"clawdbot": {"emoji": "📱", "os": ["darwin"]}} --- # FOSMVVM SwiftUI View Generator Generate SwiftUI views that render FOSMVVM ViewModels. ## Conceptual Foundation > For full architecture context, see [FOSMVVMArchitecture.md](../../docs/FOSMVVMArchitecture.md) | [OpenClaw reference]({baseDir}/references/FOSMVVMArchitecture.md) In FOSMVVM, **Views are thin rendering layers** that display ViewModels: ``` ┌─────────────────────────────────────────────────────────────┐ │ ViewModelView Pattern │ ├─────────────────────────────────────────────────────────────┤ │ │ │ ViewModel (Data) ViewModelView (SwiftUI) │ │ ┌──────────────────┐ ┌──────────────────┐ │ │ │ title: String │────►│ Text(vm.title) │ │ │ │ items: [Item] │────►│ ForEach(vm.items)│ │ │ │ isEnabled: Bool │────►│ .disabled(!...) │ │ │ └──────────────────┘ └──────────────────┘ │ │ │ │ Operations (Actions) │ │ ┌──────────────────┐ ┌──────────────────┐ │ │ │ submit() │◄────│ Button(action:) │ │ │ │ cancel() │◄────│ .onAppear { } │ │ │ └──────────────────┘ └──────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────┘ ``` **Key principle:** Views don't transform or compute data. They render what the ViewModel provides. --- ## View-ViewModel Alignment **The View filename should match the ViewModel it renders.** ``` Sources/ {ViewModelsTarget}/ {Feature}/ {Feature}ViewModel.swift ←──┐ {Entity}CardViewModel.swift ←──┼── Same names │ {ViewsTarget}/ │ {Feature}/ │ {Feature}View.swift ────┤ (renders {Feature}ViewModel) {Entity}CardView.swift ────┘ (renders {Entity}CardViewModel) ``` This alignment provides: - **Discoverability** - Find the view for any ViewModel instantly - **Consistency** - Same naming discipline across the codebase - **Maintainability** - Changes to ViewModel are reflected in view location --- ## Core Components ### 1. ViewModelView Protocol Every view conforms to `ViewModelView`: ```swift public struct MyView: ViewModelView { private let viewModel: MyViewModel public var body: some View { Text(viewModel.title) } public init(viewModel: MyViewModel) { self.viewModel = viewModel } } ``` **Required:** - `private let viewModel: {ViewModel}` - `public init(viewModel:)` - Conforms to `ViewModelView` protocol ### 2. Operations (Optional) Interactive views have operations: ```swift public struct MyView: ViewModelView { private let viewModel: MyViewModel private let operations: MyViewModelOperations #if DEBUG @State private var repaintToggle = false #endif public var body: some View { Button(action: performAction) { Text(viewModel.buttonLabel) } #if DEBUG .testDataTransporter(viewModelOps: operations, repaintToggle: $repaintToggle) #endif } public init(viewModel: MyViewModel) { self.viewModel = viewModel self.operations = viewModel.operations } private func performAction() { operations.performAction() toggleRepaint() } private func toggleRepaint() { #if DEBUG repaintToggle.toggle() #endif } } ``` **When views have operations:** - Store `operations` from `viewModel.operations` in init - Add `@State private var repaintToggle = false` (DEBUG only) - Add `.testDataTransporter(viewModelOps:repaintToggle:)` modifier (DEBUG only) - Call `toggleRepaint()` after every operation invocation ### 3. Child View Binding Parent views bind child views using `.bind(appState:)`: ```swift public struct ParentView: ViewModelView { @Environment(AppState.self) private var appState private let viewModel: ParentViewModel public var body: some View { VStack { Text(viewModel.title) // Bind child view with subset of parent's data ChildView.bind( appState: .init( itemId: viewModel.selectedId, isConnected: viewModel.isConnected ) ) } } } ``` **The `.bind()` pattern:** - Child views use `.bind(appState:)` to receive data from parent - Parent creates child's `AppState` from its own ViewModel data - Enables composition without tight coupling ### 4. Form Views with Validation Forms use `FormFieldView` and `Validations` environment: ```swift public struct MyFormView: ViewModelView { @Environment(Validations.self) private var validations @Environment(\.focusState) private var focusField @State private var error: Error? private let viewModel: MyFormViewModel private let operations: MyFormViewModelOperations public var body: some View { Form { FormFieldView( fieldModel: viewModel.$email, focusField: focusField, fieldValidator: viewModel.validateEmail, validations: validations ) Button(errorBinding: $error, asyncAction: submit) { Text(viewModel.submitButtonLabel) } .disabled(validations.hasError) } .onAsyncSubmit { await submit() } .alert( errorBinding: $error, title: viewModel.errorTitle, message: viewModel.errorMessage, dismissButtonLabel: viewModel.dismissButtonLabel ) } } ``` **Form patterns:** - `@Environment(Validations.self)` for validation state - `FormFieldView` for each input field - `Button(errorBinding:asyncAction:)` for async actions - `.disabled(validations.hasError)` on submit button - Separate handling for validation errors vs general errors ### 5. Previews Use `.previewHost()` for SwiftUI previews: ```swift #if DEBUG #Preview { MyView.previewHost( bundle: MyAppResourceAccess.localizationBundle ) .environment(AppState()) } #Preview("With Data") { MyView.previewHost( bundle: MyAppResourceAccess.localizationBundle, viewModel: .stub(title: "Preview Title") ) .environment(AppState()) } #endif ``` ## View Categories ### Display-Only Views Views that just render data (no user interactions): ```swift public struct InfoView: ViewModelView { private let viewModel: InfoViewModel public var body: some View { VStack { Text(viewModel.title) Text(viewModel.description) if viewModel.isActive { Text(viewModel.activeStatusLabel) } } } public init(viewModel: InfoViewModel) { self.viewModel = viewModel } } ``` **Characteristics:** - No `operations` property - No `repaintToggle` or `testDataTransporter` - Just renders ViewModel properties - May have conditional rendering based on ViewModel state ### Interactive Views Views with user actions: ```swift public struct ActionView: ViewModelView { @State private var error: Error? private let viewModel: ActionViewModel private let operations: ActionViewModelOperations #if DEBUG @State private var repaintToggle = false #endif public var body: some View { VStack { Button(action: performAction) { Text(viewModel.actionLabel) } Button(role: .cancel, action: cancel) { Text(viewModel.cancelLabel) } } .alert( errorBinding: $error, title: viewModel.errorTitle, message: viewModel.errorMessage, dismissButtonLabel: viewModel.dismissButtonLabel ) #if DEBUG .testDataTransporter(viewModelOps: operations, repaintToggle: $repaintToggle) #endif } public init(viewModel: ActionViewModel) { self.viewModel = viewModel self.operations = viewModel.operations } private func performAction() { operations.performAction() toggleRepaint() } private func cancel() { operations.cancel() toggleRepaint() } private func toggleRepaint() { #if DEBUG repaintToggle.toggle() #endif } } ``` ### Form Views Views with validated input fields: - Use `FormFieldView` for each input - `@Environment(Validations.self)` for validation state - Button disabled when `validations.hasError` - Separate error handling for validation vs operation errors ### Container Views Views that compose child views: ```swift public struct ContainerView: ViewModelView { @Environment(AppState.self) private var appState private let viewModel: ContainerViewModel private let operations: ContainerViewModelOperations public var body: some View { VStack { switch viewModel.state { case .loading: ProgressView() case .ready: ChildAView.bind( appState: .init(id: viewModel.selectedId) ) ChildBView.bind( appState: .init( isActive: viewModel.isActive, level: viewModel.level ) ) } } } } ``` ## When to Use This Skill - Creating a new SwiftUI view for a FOSMVVM app - Building UI to render a ViewModel - Following an implementation plan that requires new views - Creating forms with validation - Building container views that compose child views ## What This Skill Generates | File | Location | Purpose | |------|----------|---------| | `{ViewName}View.swift` | `Sources/{ViewsTarget}/{Feature}/` | The SwiftUI view | **Note:** The corresponding ViewModel and ViewModelOperations should already exist (use `fosmvvm-viewmodel-generator` skill). ## Project Structure Configuration | Placeholder | Description | Example | |-------------|-------------|---------| | `{ViewName}` | View name (without "View" suffix) | `TaskList`, `SignIn` | | `{ViewsTarget}` | SwiftUI views SPM target | `MyAppViews` | | `{Feature}` | Feature/module grouping | `Tasks`, `Auth` | ## Pattern Implementation This skill references conversation context to determine view structure: ### View Type Detection From conversation context, the skill identifies: - **ViewModel structure** (from prior discussion or specifications read by Claude) - **View category**: Display-only, interactive, form, or container - **Operations needed**: Whether view has user-initiated actions - **Child composition**: Whether view binds child views ### Component Selection Based on view type: - **Display-only**: ViewModelView protocol, viewModel property only - **Interactive**: Add operations, repaintToggle, testDataTransporter, toggleRepaint() - **Form**: Add Validations environment, FormFieldView, validation error handling - **Container**: Add child view `.bind()` calls ### Code Generation Generates view file with: 1. `ViewModelView` protocol conformance 2. Properties (viewModel, operations if needed, repaintToggle if interactive) 3. Body with rendering logic 4. Init storing viewModel and operations 5. Action methods (if interactive) 6. Test infrastructure (if interactive) 7. Previews for different states ### Context Sources Skill references information from: - **Prior conversation**: Requirements discussed with user - **Specification files**: If Claude has read specifications into context - **ViewModel definitions**: From codebase or discussion ## Key Patterns ### Error Handling Pattern ```swift @State private var error: Error? var body: some View { VStack { Button(errorBinding: $error, asyncAction: submit) { Text(viewModel.submitLabel) } } .alert( errorBinding: $error, title: viewModel.errorTitle, message: viewModel.errorMessage, dismissButtonLabel: viewModel.dismissButtonLabel ) } private func submit() async { do { try await operations.submit() } catch { self.error = error } toggleRepaint() } ``` ### Validation Error Pattern For forms, handle validation errors separately: ```swift private func submit() async { let validations = validations do { try await operations.submit(data: viewModel.data) } catch let error as MyRequest.ResponseError { if !error.validationResults.isEmpty { validations.replace(with: error.validationResults) } else { self.error = error } } catch { self.error = error } toggleRepaint() } ``` ### Async Task Pattern ```swift var body: some View { VStack { if isLoading { ProgressView() } else { contentView } } .task(errorBinding: $error) { try await loadData() } } private func loadData() async throws { isLoading = true try await operations.loadData() isLoading = false toggleRepaint() } ``` ### Conditional Rendering Pattern Use ViewModel state for conditionals: ```swift var body: some View { VStack { if viewModel.isEmpty { Text(viewModel.emptyStateMessage) } else { ForEach(viewModel.items) { item in ItemRow(item: item) } } } } ``` ### Computed View Components Pattern Extract reusable view fragments as computed properties: ```swift private var headerView: some View { HStack { Text(viewModel.title) Spacer() Image(systemName: viewModel.iconName) } } var body: some View { VStack { headerView contentView } } ``` ### Result/Error Handling Pattern When a view needs to render multiple possible ViewModels (success, various error types), use an enum wrapper: **The Wrapper ViewModel:** ```swift @ViewModel public struct TaskResultViewModel { public enum Result { case success(TaskViewModel) case notFound(NotFoundViewModel) case validationError(ValidationErrorViewModel) case permissionDenied(PermissionDeniedViewModel) } public let result: Result public var vmId: ViewModelId = .init(type: Self.self) public init(result: Result) { self.result = result } } ``` **The View:** ```swift public struct TaskResultView: ViewModelView { private let viewModel: TaskResultViewModel public var body: some View { switch viewModel.result { case .success(let vm): TaskView(viewModel: vm) case .notFound(let vm): NotFoundView(viewModel: vm) case .validationError(let vm): ValidationErrorView(viewModel: vm) case .permissionDenied(let vm): PermissionDeniedView(viewModel: vm) } } public init(viewModel: TaskResultViewModel) { self.viewModel = viewModel } } ``` **Key principles:** - Each error scenario has its own ViewModel type - The wrapper enum associates specific ViewModels with each case - The view switches on the enum and renders the appropriate child view - Maintains type safety (no `any ViewModel` existentials) - No generic error handling - each error type is specific and meaningful ### ViewModelId Initialization - CRITICAL **IMPORTANT:** `ViewModelId` controls SwiftUI's view identity system via the `.id(vmId)` modifier. Incorrect initialization causes SwiftUI to treat different data as the same view, breaking updates. **❌ WRONG - Never use this:** ```swift public var vmId: ViewModelId = .init() // NO! Generic identity ``` **✅ MINIMUM - Use type-based identity:** ```swift public var vmId: ViewModelId = .init(type: Self.self) ``` This ensures views of the same type get unique identities. **✅ IDEAL - Use data-based identity when available:** ```swift public struct TaskViewModel { public let id: ModelIdType public var vmId: ViewModelId public init(id: ModelIdType, /* other params */) { self.id = id self.vmId = .init(id: id) // Ties view identity to data identity // ... } } ``` **Why this matters:** - SwiftUI uses `.id()` modifier to determine when to recreate vs update views - `vmId` provides this identity for ViewModelViews - Wrong identity = views don't update when data changes - Data-based identity (`.init(id:)`) is best because it ties view lifecycle to data lifecycle ## File Organization ``` Sources/{ViewsTarget}/ ├── {Feature}/ │ ├── {Feature}View.swift # Full page → {Feature}ViewModel │ ├── {Entity}CardView.swift # Child component → {Entity}CardViewModel │ ├── {Entity}RowView.swift # Child component → {Entity}RowViewModel │ └── {Modal}View.swift # Modal → {Modal}ViewModel ├── Shared/ │ ├── HeaderView.swift # Shared components │ └── FooterView.swift └── Styles/ └── ButtonStyles.swift # Reusable button styles ``` --- ## Common Mistakes ### Computing Data in Views ```swift // ❌ BAD - View is transforming data var body: some View { Text("\(viewModel.firstName) \(viewModel.lastName)") } // ✅ GOOD - ViewModel provides shaped result var body: some View { Text(viewModel.fullName) // via @LocalizedCompoundString } ``` ### Forgetting to Call toggleRepaint() ```swift // ❌ BAD - Test infrastructure won't work private func submit() { operations.submit() // Missing toggleRepaint()! } // ✅ GOOD - Always call after operations private func submit() { operations.submit() toggleRepaint() } ``` ### Using Computed Properties for Display ```swift // ❌ BAD - View is computing var body: some View { if !viewModel.items.isEmpty { Text("You have \(viewModel.items.count) items") } } // ✅ GOOD - ViewModel provides the state var body: some View { if viewModel.hasItems { Text(viewModel.itemCountMessage) } } ``` ### Hardcoding Text ```swift // ❌ BAD - Not localizable Button(action: submit) { Text("Submit") } // ✅ GOOD - ViewModel provides localized text Button(action: submit) { Text(viewModel.submitButtonLabel) } ``` ### Missing Error Binding ```swift // ❌ BAD - Errors not handled Button(action: submit) { Text(viewModel.submitLabel) } // ✅ GOOD - Error binding for async actions Button(errorBinding: $error, asyncAction: submit) { Text(viewModel.submitLabel) } ``` ### Storing Operations in Body Instead of Init ```swift // ❌ BAD - Recomputed on every render public var body: some View { let operations = viewModel.operations Button(action: { operations.submit() }) { Text(viewModel.submitLabel) } } // ✅ GOOD - Store in init private let operations: MyOperations public init(viewModel: MyViewModel) { self.viewModel = viewModel self.operations = viewModel.operations } ``` ### Mismatched Filenames ``` // ❌ BAD - Filename doesn't match ViewModel ViewModel: TaskListViewModel View: TasksView.swift // ✅ GOOD - Aligned names ViewModel: TaskListViewModel View: TaskListView.swift ``` ### Incorrect ViewModelId Initialization ```swift // ❌ BAD - Generic identity, views won't update correctly public var vmId: ViewModelId = .init() // ✅ MINIMUM - Type-based identity public var vmId: ViewModelId = .init(type: Self.self) // ✅ IDEAL - Data-based identity (when id available) public init(id: ModelIdType) { self.id = id self.vmId = .init(id: id) } ``` ### Force-Unwrapping Localizable Strings ```swift // ❌ BAD - Force-unwrapping to work around missing overload import SwiftUI Text(try! viewModel.title.localizedString) // Anti-pattern - don't do this! Label(try! viewModel.label.localizedString, systemImage: "star") // ✅ GOOD - Request the proper SwiftUI overload instead // The correct solution is to add an init extension like this: extension Text { public init(_ localizable: Localizable) { self.init(localizable.localized) } } extension Label where Title == Text, Icon == Image { public init(_ title: Localizable, systemImage: String) { self.init(title.localized, systemImage: systemImage) } } // Then views use it cleanly without force-unwraps: Text(viewModel.title) Label(viewModel.label, systemImage: "star") ``` **Why this matters:** FOSMVVM provides the `Localizable` protocol for all localized strings and includes SwiftUI init overloads for common elements like `Text`. However, not every SwiftUI element has a `Localizable` overload yet. **When you encounter a SwiftUI element that doesn't accept `Localizable` directly:** 1. **DON'T** work around it with `try! localizable.localizedString` - this bypasses the type system and spreads force-unwrap calls throughout the view code 2. **DO** request that we add the proper init overload to FOSUtilities for that SwiftUI element 3. **The pattern is simple:** Extensions that accept `Localizable` and pass `.localized` to the standard initializer This approach keeps the codebase clean, type-safe, and eliminates force-unwraps from view code entirely. --- ## File Templates See [reference.md](reference.md) for complete file templates. ## Naming Conventions | Concept | Convention | Example | |---------|------------|---------| | View struct | `{Name}View` | `TaskListView`, `SignInView` | | ViewModel property | `viewModel` | Always `viewModel` | | Operations property | `operations` | Always `operations` | | Error state | `error` | Always `error` | | Repaint toggle | `repaintToggle` | Always `repaintToggle` | ## Common Modifiers ### FOSMVVM-Specific Modifiers ```swift // Error alert with ViewModel strings .alert( errorBinding: $error, title: viewModel.errorTitle, message: viewModel.errorMessage, dismissButtonLabel: viewModel.dismissButtonLabel ) // Async task with error handling .task(errorBinding: $error) { try await loadData() } // Async submit handler .onAsyncSubmit { await submit() } // Test data transporter (DEBUG only) .testDataTransporter(viewModelOps: operations, repaintToggle: $repaintToggle) // UI testing identifier .uiTestingIdentifier("submitButton") ``` ### Standard SwiftUI Modifiers Apply standard modifiers as needed for layout, styling, etc. ## How to Use This Skill **Invocation:** ```bash /fosmvvm-swiftui-view-generator ``` **Prerequisites:** - ViewModel and its structure are understood from conversation - Optionally, specification files have been read into context - View requirements (display-only, interactive, form, container) are clear from discussion **Output:** - `{ViewName}View.swift` - SwiftUI view conforming to ViewModelView protocol **Workflow integration:** This skill is typically used after discussing requirements or reading specification files. The skill references that context automatically—no file paths or Q&A needed. ## See Also - [Architecture Patterns](../shared/architecture-patterns.md) - Mental models and patterns - [FOSMVVMArchitecture.md](../../docs/FOSMVVMArchitecture.md) - Full FOSMVVM architecture - [fosmvvm-viewmodel-generator](../fosmvvm-viewmodel-generator/SKILL.md) - For creating ViewModels - [fosmvvm-ui-tests-generator](../fosmvvm-ui-tests-generator/SKILL.md) - For creating UI tests - [reference.md](reference.md) - Complete file templates ## Version History | Version | Date | Changes | |---------|------|---------| | 1.0 | 2026-01-23 | Initial skill for SwiftUI view generation |

path: reference.md
content: # FOSMVVM SwiftUI View Generator - Reference Templates

Complete file templates for generating SwiftUI ViewModelViews.

> **Conceptual context:** See [SKILL.md](SKILL.md) for when and why to use this skill.
> **Architecture context:** See [FOSMVVMArchitecture.md](../../docs/FOSMVVMArchitecture.md) for full FOSMVVM understanding.

## Placeholders

| Placeholder | Replace With | Example |
|-------------|--------------|---------|
| `{ViewName}` | View name (without "View" suffix) | `TaskList`, `SignIn` |
| `{ViewModel}` | Full ViewModel type name | `TaskListViewModel` |
| `{Operations}` | Full ViewModelOperations type name | `TaskListViewModelOperations` |
| `{ViewsTarget}` | SwiftUI views SPM target | `MyAppViews` |
| `{ViewModelsTarget}` | ViewModels SPM target | `MyAppViewModels` |
| `{Feature}` | Feature/module grouping | `Tasks`, `Auth` |

---

# Template 1: Display-Only View (No Operations)

**For views that just render data** - No user interactions, no business logic.

**Location:** `Sources/{ViewsTarget}/{Feature}/{ViewName}View.swift`

```swift
// {ViewName}View.swift
//
// Copyright (c) 2026 Your Organization. All rights reserved.
// License: Your License

import FOSMVVM
import Foundation
import SwiftUI
import {ViewModelsTarget}

/// Displays {description}
public struct {ViewName}View: ViewModelView {
    private let viewModel: {ViewModel}

    public var body: some View {
        HStack(alignment: .top) {
            Image(systemName: viewModel.iconName)
                .resizable()
                .frame(width: 50, height: 50)

            Spacer()

            VStack(alignment: .leading) {
                Text(viewModel.title)
                    .font(.headline)

                LabeledContent {
                    Text(viewModel.statusText)
                        .bold()
                } label: {
                    Text(viewModel.statusLabel)
                }

                if let subtitle = viewModel.subtitle {
                    Text(subtitle)
                        .font(.caption)
                }
            }
        }
        .padding()
        .background(Color.secondary.opacity(0.1))
        .cornerRadius(8)
    }

    public init(viewModel: {ViewModel}) {
        self.viewModel = viewModel
    }
}

#if DEBUG
#Preview {
    {ViewName}View.previewHost(
        bundle: MyAppResourceAccess.localizationBundle
    )
}

#Preview("With Data") {
    {ViewName}View.previewHost(
        bundle: MyAppResourceAccess.localizationBundle,
        viewModel: .stub(
            title: "Sample Title",
            statusText: "Active"
        )
    )
}
#endif
```

---

# Template 2: Simple Interactive View

**For views with basic user interactions** - Buttons that trigger operations.

**Location:** `Sources/{ViewsTarget}/{Feature}/{ViewName}View.swift`

```swift
// {ViewName}View.swift
//
// Copyright (c) 2026 Your Organization. All rights reserved.
// License: Your License

import FOSMVVM
import Foundation
import SwiftUI
import {ViewModelsTarget}

/// Interactive view for {description}
public struct {ViewName}View: ViewModelView {
    @State private var error: Error?

    #if DEBUG
    @State private var repaintToggle = false
    #endif

    private let viewModel: {ViewModel}
    private let operations: {Operations}

    public var body: some View {
        VStack {
            Text(viewModel.title)
                .font(.title)

            Text(viewModel.description)
                .font(.body)

            Spacer()

            HStack {
                Button(role: .cancel, action: cancel) {
                    Text(viewModel.cancelButtonLabel)
                        .foregroundStyle(.red)
                }

                Spacer()

                Button(action: performAction) {
                    Text(viewModel.actionButtonLabel)
                        .fontWeight(.semibold)
                }
                .buttonStyle(.borderedProminent)
            }
        }
        .padding()
        .alert(
            errorBinding: $error,
            title: viewModel.errorTitle,
            message: viewModel.errorMessage,
            dismissButtonLabel: viewModel.dismissButtonLabel
        )
        #if DEBUG
        .testDataTransporter(viewModelOps: operations, repaintToggle: $repaintToggle)
        #endif
    }

    public init(viewModel: {ViewModel}) {
        self.viewModel = viewModel
        self.operations = viewModel.operations
    }
}

private extension {ViewName}View {
    func performAction() {
        operations.performAction()
        toggleRepaint()
    }

    func cancel() {
        operations.cancel()
        toggleRepaint()
    }

    func toggleRepaint() {
        #if DEBUG
        repaintToggle.toggle()
        #endif
    }
}

#if DEBUG
#Preview {
    {ViewName}View.previewHost(
        bundle: MyAppResourceAccess.localizationBundle
    )
}
#endif
```

---

# Template 3: Form View with Validation

**For views with validated form inputs** - Uses FormFieldView and Validations.

**Location:** `Sources/{ViewsTarget}/{Feature}/{ViewName}View.swift`

```swift
// {ViewName}View.swift
//
// Copyright (c) 2026 Your Organization. All rights reserved.
// License: Your License

import FOSMVVM
import Foundation
import SwiftUI
import {ViewModelsTarget}

/// Form for {description}
public struct {ViewName}View: ViewModelView {
    @Environment(Validations.self) private var validations
    @Environment(MVVMEnvironment.self) private var mvvmEnv
    @Environment(\.focusState) private var focusField

    @State private var error: Error?
    @State private var submitSuccess: Bool = false

    #if DEBUG
    @State private var repaintToggle = false
    #endif

    private let viewModel: {ViewModel}
    private let operations: {Operations}

    public var body: some View {
        Form {
            FormFieldView(
                fieldModel: viewModel.$email,
                focusField: focusField,
                fieldValidator: viewModel.validateEmail,
                validations: validations
            )

            FormFieldView(
                fieldModel: viewModel.$password,
                focusField: focusField,
                fieldValidator: viewModel.validatePassword,
                validations: validations
            )

            FormFieldView(
                fieldModel: viewModel.$name,
                focusField: focusField,
                fieldValidator: viewModel.validateName,
                validations: validations
            )

            Button(errorBinding: $error, asyncAction: submit) {
                Text(viewModel.submitButtonLabel)
            }
            .disabled(validations.hasError)
        }
        .onAsyncSubmit {
            await submit()
        }
        .alert(
            errorBinding: $error,
            title: viewModel.errorTitle,
            message: viewModel.errorMessage,
            dismissButtonLabel: viewModel.dismissButtonLabel
        )
        .sheet(isPresented: $submitSuccess) {
            VStack {
                Text(viewModel.successMessage)
                Button(viewModel.closeButtonLabel) {
                    submitSuccess = false
                }
            }
            .padding()
        }
        #if os(macOS)
        .padding([.leading, .trailing])
        #endif
        #if DEBUG
        .testDataTransporter(viewModelOps: operations, repaintToggle: $repaintToggle)
        #endif
    }

    public init(viewModel: {ViewModel}) {
        self.viewModel = viewModel
        self.operations = viewModel.operations
    }
}

private extension {ViewName}View {
    func submit() async {
        guard validations.status?.hasError != true else {
            return
        }

        let validations = validations
        do {
            let response = try await operations.submit(
                email: viewModel.email,
                [REDACTED_SECRET],
                name: viewModel.name,
                mvvmEnv: mvvmEnv
            )

            submitSuccess = response?.success == true
        } catch let error as SubmitRequest.ResponseError {
            if !error.validationResults.isEmpty {
                validations.replace(with: error.validationResults)
            } else {
                self.error = error
            }
        } catch {
            self.error = error
        }

        toggleRepaint()
    }

    func toggleRepaint() {
        #if DEBUG
        repaintToggle.toggle()
        #endif
    }
}

#if DEBUG
#Preview {
    {ViewName}View.previewHost(
        bundle: MyAppResourceAccess.localizationBundle
    )
    .environment(Validations())
    .frame(minWidth: 300, minHeight: 200)
}
#endif
```

---

# Template 4: View with Async Loading

**For views that load data asynchronously** - With loading states and error handling.

**Location:** `Sources/{ViewsTarget}/{Feature}/{ViewName}View.swift`

```swift
// {ViewName}View.swift
//
// Copyright (c) 2026 Your Organization. All rights reserved.
// License: Your License

import FOSMVVM
import Foundation
import SwiftUI
import {ViewModelsTarget}

/// View that loads and displays {description}
public struct {ViewName}View: ViewModelView {
    @Environment(AppState.self) private var appState
    @State private var items: [ItemViewModel] = []
    @State private var error: Error?
    @State private var isLoading = false

    #if DEBUG
    @State private var repaintToggle = false
    #endif

    private let viewModel: {ViewModel}
    private let operations: {Operations}

    public var body: some View {
        VStack {
            Text(viewModel.title)
                .font(.headline)
                .padding()

            if isLoading {
                ProgressView()
            } else if items.isEmpty {
                Text(viewModel.emptyStateMessage)
                    .foregroundStyle(.secondary)
            } else {
                contentView
            }

            Spacer()

            Button(errorBinding: $error, asyncAction: refresh) {
                HStack {
                    Image(systemName: "arrow.clockwise")
                    Text(viewModel.refreshButtonLabel)
                }
            }
            .padding()
        }
        .task(errorBinding: $error) {
            try await loadItems()
        }
        .alert(
            errorBinding: $error,
            title: viewModel.errorTitle,
            message: viewModel.errorMessage,
            dismissButtonLabel: viewModel.dismissButtonLabel
        )
        #if DEBUG
        .testDataTransporter(viewModelOps: operations, repaintToggle: $repaintToggle)
        #endif
    }

    private var contentView: some View {
        ScrollView {
            VStack(alignment: .leading, spacing: 8) {
                ForEach(items) { item in
                    ItemRowView(item: item)
                }
            }
        }
    }

    public init(viewModel: {ViewModel}) {
        self.viewModel = viewModel
        self.operations = viewModel.operations
    }
}

private extension {ViewName}View {
    func loadItems() async throws {
        isLoading = true
        let stream = operations.loadItems()
        toggleRepaint()

        for try await item in stream {
            items.append(item)
        }

        isLoading = false
        toggleRepaint()
    }

    @Sendable func refresh() async throws {
        items.removeAll()
        try await loadItems()
    }

    func toggleRepaint() {
        #if DEBUG
        repaintToggle.toggle()
        #endif
    }
}

#if DEBUG
#Preview {
    {ViewName}View.previewHost(
        bundle: MyAppResourceAccess.localizationBundle
    )
    .environment(AppState())
}
#endif
```

---

# Template 5: Container View with Child Bindings

**For views that compose child views** - Uses .bind() to pass data to children.

**Location:** `Sources/{ViewsTarget}/{Feature}/{ViewName}View.swift`

```swift
// {ViewName}View.swift
//
// Copyright (c) 2026 Your Organization. All rights reserved.
// License: Your License

import FOSMVVM
import Foundation
import SwiftUI
import {ViewModelsTarget}

/// Container view that manages {description}
public struct {ViewName}View: ViewModelView {
    @Environment(AppState.self) private var appState

    #if DEBUG
    @State private var repaintToggle = false
    #endif

    private let viewModel: {ViewModel}
    private let operations: {Operations}

    public var body: some View {
        VStack {
            Text(viewModel.pageTitle)
                .font(.title)
                .padding()

            switch viewModel.state {
            case .idle:
                Button(action: startFlow) {
                    HStack {
                        Spacer()
                        Text(viewModel.startButtonLabel)
                        Spacer()
                    }
                }
                .buttonStyle(.borderedProminent)

            case .selectingItem:
                ItemSelectorView.bind(appState: .init())

            case .itemSelected(let itemId):
                statusView

                ItemDetailView.bind(
                    appState: .init(
                        itemId: itemId,
                        isActive: viewModel.isActive,
                        level: viewModel.level
                    )
                )

                if appState.item != nil, viewModel.isActive {
                    Button(action: proceedToNext) {
                        HStack {
                            Spacer()
                            Text(viewModel.nextButtonLabel)
                            Spacer()
                        }
                    }
                    .buttonStyle(.borderedProminent)
                }

            case .selectingDetails:
                DetailSelectorView.bind(appState: .init())

            case .completed(let itemId, let detailId):
                statusView

                ItemDetailView.bind(
                    appState: .init(
                        itemId: itemId,
                        isActive: viewModel.isActive,
                        level: viewModel.level
                    )
                )

                DetailInfoView.bind(
                    appState: .init(
                        detailId: detailId,
                        isEnabled: viewModel.isEnabled,
                        status: viewModel.status
                    )
                )
            }

            Spacer()
        }
        .padding([.leading, .trailing])
        #if DEBUG
        .testDataTransporter(viewModelOps: operations, repaintToggle: $repaintToggle)
        #endif
    }

    public init(viewModel: {ViewModel}) {
        self.viewModel = viewModel
        self.operations = viewModel.operations
    }
}

private extension {ViewName}View {
    func startFlow() {
        appState.state = .selectingItem
        operations.startFlow()
        toggleRepaint()
    }

    func proceedToNext() {
        guard case .itemSelected(let itemId) = viewModel.state else {
            return
        }
        appState.state = .selectingDetails(itemId: itemId)
        operations.proceedToDetails()
        toggleRepaint()
    }

    var statusView: some View {
        HStack {
            Text(viewModel.statusLabel)
            Image(systemName: viewModel.isActive ? "checkmark.circle.fill" : "circle")
            Text(viewModel.isActive ? viewModel.activeText : viewModel.inactiveText)
        }
        .padding(.bottom)
    }

    func toggleRepaint() {
        #if DEBUG
        repaintToggle.toggle()
        #endif
    }
}

#if DEBUG
#Preview("Idle") {
    {ViewName}View.previewHost(
        bundle: MyAppResourceAccess.localizationBundle,
        viewModel: .stub(state: .idle)
    )
    .environment(AppState.stub())
}

#Preview("Item Selected") {
    {ViewName}View.previewHost(
        bundle: MyAppResourceAccess.localizationBundle,
        viewModel: .stub(
            state: .itemSelected(itemId: .init()),
            isActive: true,
            level: .high
        )
    )
    .environment(AppState.stub())
}

#Preview("Completed") {
    {ViewName}View.previewHost(
        bundle: MyAppResourceAccess.localizationBundle,
        viewModel: .stub(
            state: .completed(itemId: .init(), detailId: .init()),
            isActive: true,
            isEnabled: true
        )
    )
    .environment(AppState.stub())
}
#endif
```

---

# Template 6: List View with Selection

**For views with selectable lists** - Manages selection state and item interaction.

**Location:** `Sources/{ViewsTarget}/{Feature}/{ViewName}View.swift`

```swift
// {ViewName}View.swift
//
// Copyright (c) 2026 Your Organization. All rights reserved.
// License: Your License

import FOSMVVM
import Foundation
import SwiftUI
import {ViewModelsTarget}

/// List view for selecting {description}
public struct {ViewName}View: ViewModelView {
    @State private var items: [ItemData] = []
    @State private var selectedId: ModelIdType?
    @State private var isProcessing: Bool = false
    @State private var error: Error?

    #if DEBUG
    @State private var repaintToggle = false
    #endif

    private let viewModel: {ViewModel}
    private let operations: {Operations}

    public var body: some View {
        VStack {
            Text(viewModel.title)
                .font(.headline)
                .padding(.top)

            HStack {
                Text(viewModel.listHeaderLabel)
                Spacer()
                Text(isProcessing ? viewModel.processingLabel : viewModel.scanningLabel)
            }
            .padding(.horizontal)

            Divider()

            ScrollView {
                VStack(alignment: .leading) {
                    if orderedItems.isEmpty {
                        Text(viewModel.emptyStateMessage)
                            .foregroundStyle(.secondary)
                    }

                    ForEach(orderedItems) { item in
                        Button { selectItem(id: item.id) } label: {
                            HStack {
                                Text(item.displayName)

                                if item.id == selectedId {
                                    Spacer()
                                    if isProcessing {
                                        ProgressView()
                                    } else {
                                        Image(systemName: "checkmark.circle.fill")
                                    }
                                }
                            }
                        }
                        .padding(.vertical, 8)
                        .padding(.horizontal)
                        .background(
                            item.id == selectedId
                                ? Color.accentColor.opacity(0.2)
                                : Color.clear
                        )

                        Divider()
                    }
                }
            }

            Spacer()

            HStack {
                Button(role: .cancel, action: cancel) {
                    Text(viewModel.cancelButtonLabel)
                        .foregroundStyle(.red)
                }

                Spacer()

                Button(errorBinding: $error, asyncAction: submit) {
                    Text(viewModel.submitButtonLabel)
                        .fontWeight(.semibold)
                        .frame(minWidth: 120)
                }
                .buttonStyle(.borderedProminent)
                .disabled(selectedId == nil || isProcessing)
            }
            .padding()
        }
        .task(errorBinding: $error) { try await loadItems() }
        .alert(
            errorBinding: $error,
            title: viewModel.errorTitle,
            message: viewModel.errorMessage,
            dismissButtonLabel: viewModel.dismissButtonLabel
        )
        #if DEBUG
        .testDataTransporter(viewModelOps: operations, repaintToggle: $repaintToggle)
        #endif
    }

    public init(viewModel: {ViewModel}) {
        self.viewModel = viewModel
        self.operations = viewModel.operations
    }
}

private extension {ViewName}View {
    func loadItems() async throws {
        let stream = operations.loadItems()
        toggleRepaint()

        for try await nextItem in stream {
            items.append(nextItem)
        }
    }

    func cancel() {
        operations.cancel()
        toggleRepaint()
    }

    func selectItem(id: ModelIdType) {
        if selectedId == id {
            selectedId = nil
        } else {
            selectedId = id
        }
        toggleRepaint()
    }

    @Sendable func submit() async throws {
        guard
            let selectedId,
            let item = items.first(where: { $0.id == selectedId })
        else {
            return
        }

        operations.cancel()
        isProcessing = true

        try await operations.submit(item: item)

        isProcessing = false
        toggleRepaint()
    }

    var orderedItems: [ItemData] {
        items.sorted(by: { $0.displayName < $1.displayName })
    }

    func toggleRepaint() {
        #if DEBUG
        repaintToggle.toggle()
        #endif
    }
}

#if DEBUG
#Preview {
    {ViewName}View.previewHost(
        bundle: MyAppResourceAccess.localizationBundle
    )
}
#endif
```

---

# Quick Reference

## View Component Checklist

**All Views:**
- [ ] Conforms to `ViewModelView`
- [ ] `private let viewModel: {ViewModel}`
- [ ] `public init(viewModel:)`
- [ ] Previews with `.previewHost()`

**Interactive Views (with operations):**
- [ ] `private let operations: {Operations}`
- [ ] `@State private var repaintToggle = false` (DEBUG)
- [ ] `.testDataTransporter(viewModelOps:repaintToggle:)` (DEBUG)
- [ ] `toggleRepaint()` called after all operations
- [ ] Operations stored from `viewModel.operations` in init

**Form Views:**
- [ ] `@Environment(Validations.self) private var validations`
- [ ] `@Environment(\.focusState) private var focusField`
- [ ] `FormFieldView` for each input field
- [ ] `.disabled(validations.hasError)` on submit button
- [ ] Separate handling for validation errors vs general errors

**Container Views:**
- [ ] `@Environment(AppState.self) private var appState`
- [ ] Child views use `.bind(appState:)`
- [ ] AppState created from ViewModel data

## Common Patterns

### Error Handling

```swift
@State private var error: Error?

.alert(
    errorBinding: $error,
    title: viewModel.errorTitle,
    message: viewModel.errorMessage,
    dismissButtonLabel: viewModel.dismissButtonLabel
)
```

### Async Actions

```swift
Button(errorBinding: $error, asyncAction: submit) {
    Text(viewModel.submitLabel)
}

private func submit() async {
    do {
        try await operations.submit()
    } catch {
        self.error = error
    }
    toggleRepaint()
}
```

### Task on Appear

```swift
.task(errorBinding: $error) {
    try await loadData()
}

private func loadData() async throws {
    try await operations.loadData()
    toggleRepaint()
}
```

### Conditional Rendering

```swift
if viewModel.isEmpty {
    Text(viewModel.emptyStateMessage)
} else {
    ForEach(viewModel.items) { item in
        ItemRow(item: item)
    }
}
```

### Child View Binding

```swift
ChildView.bind(
    appState: .init(
        id: viewModel.selectedId,
        isActive: viewModel.isActive
    )
)
```

## Preview Patterns

```swift
#if DEBUG
// Basic preview
#Preview {
    MyView.previewHost(
        bundle: MyAppResourceAccess.localizationBundle
    )
    .environment(AppState())
}

// Named preview with data
#Preview("With Items") {
    MyView.previewHost(
        bundle: MyAppResourceAccess.localizationBundle,
        viewModel: .stub(
            items: [.stub(), .stub()],
            isEmpty: false
        )
    )
    .environment(AppState())
}

// Multiple states
#Preview("Loading") {
    MyView.previewHost(
        bundle: MyAppResourceAccess.localizationBundle,
        viewModel: .stub(isLoading: true)
    )
}

#Preview("Empty") {
    MyView.previewHost(
        bundle: MyAppResourceAccess.localizationBundle,
        viewModel: .stub(isEmpty: true)
    )
}
#endif
```

---

# Checklists

## Before Creating a View:
- [ ] ViewModel exists and is understood
- [ ] Determined if operations are needed
- [ ] Identified if form with validation
- [ ] Identified if container with child views
- [ ] Reviewed ViewModel properties to understand data

## After Creating a View:
- [ ] View conforms to ViewModelView
- [ ] Init stores viewModel (and operations if needed)
- [ ] Test infrastructure added if operations present
- [ ] Previews added for different states
- [ ] Error handling in place if async operations
- [ ] Validation handling in place if form
- [ ] Child view bindings correct if container


Security scan verdicts — ClawScan: clean | static analysis: suspicious | VirusTotal: clean | SkillSpector: clean (LOW)