107 lines
3.1 KiB
Markdown
107 lines
3.1 KiB
Markdown
# View Models
|
|
|
|
## Definition
|
|
|
|
A **View Model** represents a **fully prepared UI state**.
|
|
|
|
It answers the question:
|
|
|
|
> “What does the UI need in order to render this screen without thinking?”
|
|
|
|
View Models are **UI-owned** classes.
|
|
They do not represent business truth and do not enforce domain rules.
|
|
|
|
**Uncle Bob says**: "Objects expose behavior, not data." ViewModels encapsulate the behavior of the UI.
|
|
|
|
---
|
|
|
|
## Responsibilities
|
|
|
|
A View Model MAY:
|
|
|
|
- accept an API DTO as input
|
|
- derive UI-specific fields
|
|
- combine or reshape data for rendering
|
|
- perform formatting (dates, numbers, labels), especially for **client-only context** (e.g., local timezone, relative "time ago")
|
|
- handle localization and presentation logic
|
|
- use **Display Objects** for reusable UI concerns and rich APIs
|
|
|
|
### Formatting Responsibility
|
|
|
|
While `ViewData Builders` handle formatting for SEO and initial render using **Formatters**, `View Models` are responsible for:
|
|
- **Client-specific formatting:** Data that depends on the browser's locale, timezone, or precise location.
|
|
- **Interactive formatting:** Updating display values in response to user input or state changes.
|
|
- **Rich APIs:** Providing **Display Objects** to the UI for multi-variant formatting (e.g., `date.short`, `date.relative`).
|
|
|
|
In the website SSR/RSC architecture, View Models MAY compute view-only derived values, but MUST NOT be the type passed into Templates.
|
|
|
|
A View Model MUST:
|
|
|
|
- be fully usable by the UI without further computation
|
|
- expose only data and UI-oriented helpers
|
|
- be created in a consistent, explicit way
|
|
|
|
---
|
|
|
|
## Restrictions
|
|
|
|
A View Model MUST NOT:
|
|
|
|
- contain business logic
|
|
- validate domain rules
|
|
- enforce permissions or authorization
|
|
- contain domain entities or value objects
|
|
- perform side effects
|
|
- be sent back to the server
|
|
|
|
If a View Model decides whether something is *allowed* or *correct*,
|
|
that logic belongs in the Core, not here.
|
|
|
|
---
|
|
|
|
## Ownership & Placement
|
|
|
|
- View Models belong to the **frontend**
|
|
- They live close to the UI, not in shared or core layers
|
|
- They are not shared with the backend
|
|
|
|
---
|
|
|
|
## Creation Rules
|
|
|
|
This repository distinguishes **Page DTO**, **ViewModel**, and **ViewData**:
|
|
|
|
- Page DTO: server-to-client payload (JSON-serializable)
|
|
- ViewModel: client-only class (never serialized)
|
|
- ViewData: template input (JSON-serializable)
|
|
|
|
Rules (website):
|
|
|
|
1) View Models are created in client code only.
|
|
2) View Models are created from **ViewData** (not from DTOs).
|
|
3) Templates MUST NOT accept View Models; Templates accept ViewData only.
|
|
4) View Models MUST compose Display Objects and produce rich UI APIs.
|
|
|
|
Authoritative reference: [plans/nextjs-rsc-viewmodels-concept.md](plans/nextjs-rsc-viewmodels-concept.md:1).
|
|
|
|
---
|
|
|
|
## Testing
|
|
|
|
View Models SHOULD be tested when they contain:
|
|
|
|
- formatting logic
|
|
- localization behavior
|
|
- non-trivial derived fields
|
|
|
|
View Models do NOT need tests if they only expose data without logic.
|
|
|
|
---
|
|
|
|
## Summary
|
|
|
|
- View Models describe **UI state**
|
|
- They are **presentation-focused**, not business-focused
|
|
- They reduce complexity in components
|
|
- They form a stable contract for the UI
|