plan-forge swiftui.instructions.md

SwiftUI Patterns

State Management

Property Wrappers Guide

Wrapper	Use Case
@State	Local view state (primitive types)
@Binding	Two-way binding from parent
@StateObject	Owned ViewModel (created by this view)
@ObservedObject	Injected ViewModel (created externally)
@EnvironmentObject	App-wide shared state
@Environment	System values (colorScheme, dismiss, etc.)

ViewModel Pattern

@MainActor
final class ItemListViewModel: ObservableObject {
    @Published private(set) var items: [Item] = []
    @Published private(set) var isLoading = false
    @Published var errorMessage: String?

    private let service: any ItemService

    init(service: some ItemService) {
        self.service = service
    }

    func load() async {
        isLoading = true
        defer { isLoading = false }
        do {
            items = try await service.fetchAll()
        } catch {
            errorMessage = error.localizedDescription
        }
    }
}

Rules

• Always @MainActor on ViewModels that publish to @Published
• Never call DispatchQueue.main.async — use @MainActor instead
• Inject services via init — not as globals or singletons
• Use @StateObject when the view owns the VM; @ObservedObject when injected

View Structure

struct ItemListView: View {
    @StateObject private var viewModel: ItemListViewModel

    init(service: some ItemService) {
        _viewModel = StateObject(wrappedValue: ItemListViewModel(service: service))
    }

    var body: some View {
        content
            .navigationTitle("Items")
            .task { await viewModel.load() }
            .alert("Error", isPresented: Binding(
                get: { viewModel.errorMessage != nil },
                set: { if !$0 { viewModel.errorMessage = nil } }
            )) {
                Button("OK") { viewModel.errorMessage = nil }
            } message: {
                Text(viewModel.errorMessage ?? "")
            }
    }

    @ViewBuilder
    private var content: some View {
        if viewModel.isLoading {
            ProgressView()
        } else {
            List(viewModel.items) { item in
                ItemRow(item: item)
            }
        }
    }
}