---

name: fosmvvm-viewmodel-generator description: Generate FOSMVVM ViewModels - the bridge between server-side data and client-side Views. Use when creating new screens, pages, components, or any UI that displays data.

FOSMVVM ViewModel Generator

Generate ViewModels following FOSMVVM architecture patterns.

Conceptual Foundation

For full architecture context, see FOSMVVMArchitecture.md

A ViewModel is the bridge in the Model-View-ViewModel architecture:

Copy┌─────────────┐      ┌─────────────────┐      ┌─────────────┐
│    Model    │ ───► │    ViewModel    │ ───► │    View     │
│   (Data)    │      │  (The Bridge)   │      │  (SwiftUI)  │
└─────────────┘      └─────────────────┘      └─────────────┘

Key insight: In FOSMVVM, ViewModels are:

• Created by a Factory (either server-side or client-side)
• Localized during encoding (resolves all @LocalizedString references)
• Consumed by Views which just render the localized data

---

First Decision: Hosting Mode

This is a per-ViewModel decision. An app can mix both modes - for example, a standalone iPhone app with server-based sign-in.

The key question: Where does THIS ViewModel's data come from?

Server-Hosted Mode

When data comes from a server:

• Factory is hand-written on server (ViewModelFactory protocol)
• Factory queries database, builds ViewModel
• Server localizes during JSON encoding
• Client receives fully localized ViewModel

Examples: Sign-in screen, user profile from API, dashboard with server data

Client-Hosted Mode

When data is local to the device:

• Use @ViewModel(options: [.clientHostedFactory])
• Macro auto-generates factory from init parameters
• Client bundles YAML resources
• Client localizes during encoding

Examples: Settings screen, onboarding, offline-first features, error display

Error Display Pattern

Error display is a classic client-hosted scenario. You already have the data from ResponseError - just wrap it in a specific ViewModel for that error:

Copy// Specific ViewModel for MoveIdeaRequest errors
@ViewModel(options: [.clientHostedFactory])
struct MoveIdeaErrorViewModel {
    let message: LocalizableString
    let errorCode: String

    public var vmId = ViewModelId()

    // Takes the specific ResponseError
    init(responseError: MoveIdeaRequest.ResponseError) {
        self.message = responseError.message
        self.errorCode = responseError.code.rawValue
    }
}

Usage:

Copycatch let error as MoveIdeaRequest.ResponseError {
    let vm = MoveIdeaErrorViewModel(responseError: error)
    return try await req.view.render("Shared/ToastView", vm)
}

Each error scenario gets its own ViewModel:

• MoveIdeaErrorViewModel for MoveIdeaRequest.ResponseError
• CreateIdeaErrorViewModel for CreateIdeaRequest.ResponseError
• SettingsValidationErrorViewModel for settings form errors

Don't create a generic "ToastViewModel" or "ErrorViewModel" - that's unified error architecture, which we avoid.

Key insights:

• No server request needed - you already caught the error
• The LocalizableString properties in ResponseError are already localized (server did it)
• Standard ViewModel → View encoding chain handles this correctly; already-localized strings pass through unchanged
• Client-hosted ViewModel wraps existing data; the macro generates the factory

Hybrid Apps

Many apps use both:

Copy┌───────────────────────────────────────────────┐
│               iPhone App                       │
├───────────────────────────────────────────────┤
│ SettingsViewModel           → Client-Hosted   │
│ OnboardingViewModel         → Client-Hosted   │
│ MoveIdeaErrorViewModel      → Client-Hosted   │  ← Error display
│ SignInViewModel             → Server-Hosted   │
│ UserProfileViewModel        → Server-Hosted   │
└───────────────────────────────────────────────┘

Same ViewModel patterns work in both modes - only the factory creation differs.

Core Responsibility: Shaping Data

A ViewModel's job is shaping data for presentation. This happens in two places:

1. Factory - what data is needed, how to transform it
2. Localization - how to present it in context (including locale-aware ordering)

The View just renders - it should never compose, format, or reorder ViewModel properties.

What a ViewModel Contains

A ViewModel answers: "What does the View need to display?"

What a ViewModel Does NOT Contain

• Database relationships (@Parent, @Siblings)
• Business logic or validation (that's in Fields protocols)
• Raw database IDs exposed to templates (use typed properties)
• Unlocalized strings that Views must look up

Anti-Pattern: Composition in Views

Copy// ❌ WRONG - View is composing
Text(viewModel.firstName) + Text(" ") + Text(viewModel.lastName)

// ✅ RIGHT - ViewModel provides shaped result
Text(viewModel.fullName)  // via @LocalizedCompoundString

If you see + or string interpolation in a View, the shaping belongs in the ViewModel.

ViewModel Protocol Hierarchy

Copypublic protocol ViewModel: ServerRequestBody, RetrievablePropertyNames, Identifiable, Stubbable {
    var vmId: ViewModelId { get }
}

public protocol RequestableViewModel: ViewModel {
    associatedtype Request: ViewModelRequest
}

ViewModel provides:

• ServerRequestBody - Can be sent over HTTP as JSON
• RetrievablePropertyNames - Enables @LocalizedString binding (via @ViewModel macro)
• Identifiable - Has vmId for SwiftUI identity
• Stubbable - Has stub() for testing/previews

RequestableViewModel adds:

• Associated Request type for fetching from server

Two Categories of ViewModels

1. Top-Level (RequestableViewModel)

Represents a full page or screen. Has:

• An associated ViewModelRequest type
• A ViewModelFactory that builds it from database
• Child ViewModels embedded within it

Copy@ViewModel
public struct DashboardViewModel: RequestableViewModel {
    public typealias Request = DashboardRequest

    @LocalizedString public var pageTitle
    public let cards: [CardViewModel]  // Children
    public var vmId: ViewModelId = .init()
}

2. Child (plain ViewModel)

Nested components built by their parent's factory. No Request type.

Copy@ViewModel
public struct CardViewModel: Codable, Sendable {
    public let id: ModelIdType
    public let title: String
    public let createdAt: LocalizableDate
    public var vmId: ViewModelId = .init()
}

---

Display vs Form ViewModels

ViewModels serve two distinct purposes:

Display ViewModels

For showing data - cards, rows, lists, detail views:

Copy@ViewModel
public struct UserCardViewModel {
    public let id: ModelIdType
    public let name: String
    @LocalizedString public var roleDisplayName
    public let createdAt: LocalizableDate
    public var vmId: ViewModelId = .init()
}

Characteristics:

• Properties are let (read-only)
• No validation needed
• No FormField definitions
• Just projects Model data for display

Form ViewModels

For collecting input - create forms, edit forms, settings:

Copy@ViewModel
public struct UserFormViewModel: UserFields {  // ← Adopts Fields!
    public var id: ModelIdType?
    public var email: String
    public var firstName: String
    public var lastName: String

    public let userValidationMessages: UserFieldsMessages
    public var vmId: ViewModelId = .init()
}

Characteristics:

• Properties are var (editable)
• Adopts a Fields protocol for validation
• Gets FormField definitions from Fields
• Gets validation logic from Fields
• Gets localized error messages from Fields

The Connection

Copy┌─────────────────────────────────────────────────────────────────┐
│                    UserFields Protocol                          │
│        (defines editable properties + validation)               │
│                                                                 │
│  Adopted by:                                                    │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐ │
│  │ CreateUserReq   │  │ UserFormVM      │  │ User (Model)    │ │
│  │ .RequestBody    │  │ (UI form)       │  │ (persistence)   │ │
│  └─────────────────┘  └─────────────────┘  └─────────────────┘ │
│                                                                 │
│  Same validation logic everywhere!                              │
└─────────────────────────────────────────────────────────────────┘

Quick Decision Guide

The key question: "Is the user editing data in this ViewModel?"

• No → Display ViewModel (no Fields)
• Yes → Form ViewModel (adopt Fields)

---

When to Use This Skill

• Creating a new page or screen
• Adding a new UI component (card, row, modal, etc.)
• Displaying data from the database in a View
• Following an implementation plan that requires new ViewModels

What This Skill Generates

Server-Hosted: Top-Level ViewModel (4 files)

Client-Hosted: Top-Level ViewModel (2 files)

No Request or Factory files needed - macro generates them!

Child ViewModels (1-2 files, either mode)

Project Structure Configuration

How to Use This Skill

Invocation: /fosmvvm-viewmodel-generator

Prerequisites:

• View requirements understood from conversation context
• Data source determined (server/database vs local state)
• Display vs Form decision made (if user input involved, Fields protocol exists)

Workflow integration: This skill is typically used after discussing View requirements or reading specification files. The skill references conversation context automatically—no file paths or Q&A needed. For Form ViewModels, run fosmvvm-fields-generator first to create the Fields protocol.

Pattern Implementation

This skill references conversation context to determine ViewModel structure:

Hosting Mode Detection

From conversation context, the skill identifies:

• Data source (server/database vs local state/preferences)
• Server-hosted → Hand-written factory, server-side localization
• Client-hosted → Macro-generated factory, client-side localization

ViewModel Design

From requirements already in context:

• View purpose (page, modal, card, row component)
• Data needs (from database query, from AppState, from caught error)
• Static UI text (titles, labels, buttons requiring @LocalizedString)
• Child ViewModels (nested components)
• Hierarchy level (top-level RequestableViewModel vs child ViewModel)

Property Planning

Based on View requirements:

• Display properties (data to render)
• Localization requirements (which properties use @LocalizedString)
• Identity strategy (singleton vmId vs instance-based vmId)
• Form adoption (whether ViewModel adopts Fields protocol)

File Generation

Server-Hosted Top-Level:

1. ViewModel struct (with RequestableViewModel)
2. Request type
3. YAML localization
4. Factory implementation

Client-Hosted Top-Level:

1. ViewModel struct (with clientHostedFactory option)
2. YAML localization

Child (either mode):

1. ViewModel struct
2. YAML localization (if needed)

Context Sources

Skill references information from:

• Prior conversation: View requirements, data sources discussed with user
• Specification files: If Claude has read UI specs or feature docs into context
• Fields protocols: From codebase or previous fosmvvm-fields-generator invocation

Key Patterns

The @ViewModel Macro

Always use the @ViewModel macro - it generates the propertyNames() method required for localization binding.

Server-Hosted (basic macro):

Copy@ViewModel
public struct MyViewModel: RequestableViewModel {
    public typealias Request = MyRequest
    @LocalizedString public var title
    public var vmId: ViewModelId = .init()
    public init() {}
}

Client-Hosted (with factory generation):

Copy@ViewModel(options: [.clientHostedFactory])
public struct SettingsViewModel {
    @LocalizedString public var pageTitle
    public var vmId: ViewModelId = .init()

    public init(theme: Theme, notifications: NotificationSettings) {
        // Init parameters become AppState properties
    }
}

// Macro auto-generates:
// - typealias Request = ClientHostedRequest
// - struct AppState { let theme: Theme; let notifications: NotificationSettings }
// - class ClientHostedRequest: ViewModelRequest { ... }
// - static func model(context:) async throws -> Self { ... }

Stubbable Pattern

All ViewModels must support stub() for testing and SwiftUI previews:

Copypublic extension MyViewModel {
    static func stub() -> Self {
        .init(/* default values */)
    }
}

Identity: vmId

Every ViewModel needs a vmId for SwiftUI's identity system:

Singleton (one per page): vmId = .init(type: Self.self) Instance (multiple per page): vmId = .init(id: id) where id: ModelIdType

Localization

Static UI text uses @LocalizedString:

Copy@LocalizedString public var pageTitle

With corresponding YAML:

Copyen:
  MyViewModel:
    pageTitle: "Welcome"

Dates and Numbers

Never send pre-formatted strings. Use localizable types:

Copypublic let createdAt: LocalizableDate    // NOT String
public let itemCount: LocalizableInt     // NOT String

The client formats these according to user's locale and timezone.

Enum Localization Pattern

For dynamic enum values (status, state, category), use a stored LocalizableString - NOT @LocalizedString.

@LocalizedString always looks up the same key (the property name). A stored LocalizableString carries the dynamic key from the enum case.

Copy// Enum provides localizableString
public enum SessionState: String, CaseIterable, Codable, Sendable {
    case pending, running, completed, failed

    public var localizableString: LocalizableString {
        .localized(for: Self.self, propertyName: rawValue)
    }
}

// ViewModel stores it (NOT @LocalizedString)
@ViewModel
public struct SessionCardViewModel {
    public let state: SessionState                // Raw enum for data attributes
    public let stateDisplay: LocalizableString   // Localized display text

    public init(session: Session) {
        self.state = session.state
        self.stateDisplay = session.state.localizableString
    }
}

Copy# YAML keys match enum type and case names
en:
  SessionState:
    pending: "Pending"
    running: "Running"
    completed: "Completed"
    failed: "Failed"

Constraint: LocalizableString only works in ViewModels encoded with localizingEncoder(). Do not use in Fluent JSONB fields or other persisted types.

Child ViewModels

Top-level ViewModels contain their children:

Copy@ViewModel
public struct BoardViewModel: RequestableViewModel {
    public let columns: [ColumnViewModel]
    public let cards: [CardViewModel]
}

The Factory builds all children when building the parent.

Codable and Computed Properties

Swift's synthesized Codable only encodes stored properties. Since ViewModels are serialized (for JSON transport, Leaf rendering, etc.), computed properties won't be available.

Copy// Computed - NOT encoded, invisible after serialization
public var hasCards: Bool { !cards.isEmpty }

// Stored - encoded, available after serialization
public let hasCards: Bool

When to pre-compute:

For Leaf templates, you can often use Leaf's built-in functions directly:

• #if(count(cards) > 0) - no need for hasCards property
• #count(cards) - no need for cardCount property

Pre-compute only when:

• Direct array subscripts needed (firstCard - array indexing not documented in Leaf)
• Complex logic that's cleaner in Swift than in template
• Performance-sensitive repeated calculations

See fosmvvm-leaf-view-generator for Leaf template patterns.

File Templates

See reference.md for complete file templates.

Naming Conventions

See Also

• Architecture Patterns - Mental models (errors are data, type safety, etc.)
• FOSMVVMArchitecture.md - Full FOSMVVM architecture
• fosmvvm-fields-generator - For form validation
• fosmvvm-fluent-datamodel-generator - For Fluent persistence layer
• fosmvvm-leaf-view-generator - For Leaf templates that render ViewModels
• reference.md - Complete file templates

Version History