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:

┌─────────────┐      ┌─────────────────┐      ┌─────────────┐
│    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

// 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:

catch 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:

┌───────────────────────────────────────────────┐
│               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?"

@LocalizedString

LocalizableString

@LocalizedSubs

@LocalizedCompoundString

LocalizableDate

createdAt: LocalizableDate

LocalizableInt

totalCount: LocalizableInt

content: String

count: Int

cards: [CardViewModel]

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

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

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

If you see

+

ViewModel Protocol Hierarchy

public 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

@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.

@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:

@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:

@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

┌─────────────────────────────────────────────────────────────────┐
│                    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)

UserCardViewModel

UserRowViewModel

UserDetailViewModel

UserFormViewModel

UserFields

CreateUserViewModel

UserFields

EditUserViewModel

UserFields

SettingsViewModel

SettingsFields

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)

{Name}ViewModel.swift

{ViewModelsTarget}/

{Name}Request.swift

{ViewModelsTarget}/

{Name}ViewModel.yml

{ResourcesPath}/

{Name}ViewModel+Factory.swift

{WebServerTarget}/

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

{Name}ViewModel.swift

{ViewModelsTarget}/

clientHostedFactory

{Name}ViewModel.yml

{ResourcesPath}/

No Request or Factory files needed - macro generates them!

Child ViewModels (1-2 files, either mode)

{Name}ViewModel.swift

{ViewModelsTarget}/

{Name}ViewModel.yml

{ResourcesPath}/

@LocalizedString

Note: If child is only used by one parent and represents a summary/reference (not a full ViewModel), nest it inside the parent file instead. See Nested Child Types Pattern under Key Patterns.

Project Structure Configuration

{ViewModelsTarget}

ViewModels

{ResourcesPath}

Sources/Resources

{WebServerTarget}

WebServer

AppServer

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

propertyNames()

Server-Hosted (basic macro):

@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):

@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()

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

Identity: vmId

Every ViewModel needs a

vmId

Singleton (one per page):

vmId = .init(type: Self.self)

vmId = .init(id: id)

id: ModelIdType

Localization

Static UI text uses

@LocalizedString

@LocalizedString public var pageTitle

With corresponding YAML:

en:
  MyViewModel:
    pageTitle: "Welcome"

Dates and Numbers

Never send pre-formatted strings. Use localizable types:

public 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

@LocalizedString

@LocalizedString

LocalizableString

// 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
    }
}

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

Constraint:

LocalizableString

localizingEncoder()

Child ViewModels

Top-level ViewModels contain their children:

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

The Factory builds all children when building the parent.

Nested Child Types Pattern

When a child type is only used by one parent and represents a summary or reference (not a full ViewModel), nest it inside the parent:

@ViewModel
public struct GovernancePrincipleCardViewModel: Codable, Sendable, Identifiable {
    // Properties come first
    public let versionHistory: [GovernancePrincipleVersionSummary]?
    public let referencingDecisions: [GovernanceDecisionReference]?

    // MARK: - Nested Types

    /// Summary of a principle version for display in version history.
    public struct GovernancePrincipleVersionSummary: Codable, Sendable, Identifiable, Stubbable {
        public let id: ModelIdType
        public let version: Int
        public let createdAt: Date

        public init(id: ModelIdType, version: Int, createdAt: Date) {
            self.id = id
            self.version = version
            self.createdAt = createdAt
        }
    }

    /// Reference to a decision that cites this principle.
    public struct GovernanceDecisionReference: Codable, Sendable, Identifiable, Stubbable {
        public let id: ModelIdType
        public let title: String
        public let decisionNumber: String
        public let createdAt: Date

        public init(id: ModelIdType, title: String, decisionNumber: String, createdAt: Date) {
            self.id = id
            self.title = title
            self.decisionNumber = decisionNumber
            self.createdAt = createdAt
        }
    }

    // vmId and parent init follow
    public let vmId: ViewModelId
    // ...
}

Reference:

Sources/KairosModels/Governance/GovernancePrincipleCardViewModel.swift

Placement rules:

1. Nested types go AFTER the properties that reference them
2. Before

   vmId

   and the parent's init
3. Use

   // MARK: - Nested Types

   section marker
4. Each nested type gets its own doc comment

Conformances for nested types:

• Codable

  - for ViewModel encoding

• Sendable

  - for Swift 6 concurrency

• Identifiable

  - for SwiftUI ForEach if used in arrays

• Stubbable

  - for testing/previews

Two-Tier Stubbable Pattern:

Nested types use fully qualified names in their extensions:

public extension GovernancePrincipleCardViewModel.GovernancePrincipleVersionSummary {
    // Tier 1: Zero-arg convenience (ALWAYS delegates to tier 2)
    static func stub() -> Self {
        .stub(id: .init())
    }

    // Tier 2: Full parameterized with defaults
    static func stub(
        id: ModelIdType = .init(),
        version: Int = 1,
        createdAt: Date = .now
    ) -> Self {
        .init(id: id, version: version, createdAt: createdAt)
    }
}

public extension GovernancePrincipleCardViewModel.GovernanceDecisionReference {
    static func stub() -> Self {
        .stub(id: .init())
    }

    static func stub(
        id: ModelIdType = .init(),
        title: String = "A Title",
        decisionNumber: String = "DEC-12345",
        createdAt: Date = .now
    ) -> Self {
        .init(id: id, title: title, decisionNumber: decisionNumber, createdAt: createdAt)
    }
}

Why two tiers:

• Tests often just need

  [.stub()]

  without caring about values
• Other tests need specific values:

  .stub(name: "Specific Name")

• Zero-arg ALWAYS calls parameterized version (single source of truth)

When to nest vs keep top-level:

Examples:

Card with nested summaries:

@ViewModel
public struct TaskCardViewModel {
    public let assignees: [AssigneeSummary]?

    public struct AssigneeSummary: Codable, Sendable, Identifiable, Stubbable {
        public let id: ModelIdType
        public let name: String
        public let avatarUrl: String?
        // ...
    }
}

List with nested references:

@ViewModel
public struct ProjectListViewModel {
    public let relatedProjects: [ProjectReference]?

    public struct ProjectReference: Codable, Sendable, Identifiable, Stubbable {
        public let id: ModelIdType
        public let title: String
        public let status: String
        // ...
    }
}

Codable and Computed Properties

Swift's synthesized

Codable

// 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

{Name}ViewModel

DashboardViewModel

{Name}Request

DashboardRequest

{Name}ViewModel+Factory.swift

DashboardViewModel+Factory.swift

{Name}ViewModel.yml

DashboardViewModel.yml

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