Display Objects

Definition

A Display Object encapsulates reusable, UI-only display logic.

In this codebase, a Display Object is a Frontend Value Object:

class-based
immutable
deterministic
side-effect free

It answers the question:

“How should this specific piece of information be shown?”

Display Objects are not screen-specific. They exist to avoid duplicating presentation logic across View Models.

Responsibilities

A Display Object MAY:

format values (money, dates, durations)
handle localization and language-specific rules
map codes to labels
encapsulate UI display conventions
be reused across multiple View Models

In addition, a Display Object MAY:

normalize presentation inputs (for example trimming/casing)
expose multiple explicit display variants (for example shortLabel, longLabel)

A Display Object MUST:

be deterministic
be side-effect free
operate only on presentation data

A Display Object MUST:

be implemented as a class with a small, explicit API
accept only primitives/plain data in its constructor (or static factory)
expose only primitive outputs (strings/numbers/booleans)

Restrictions

A Display Object MUST NOT:

contain business logic
enforce domain invariants
perform validation
influence system behavior
be sent back to the server
depend on backend or infrastructure concerns

In this repository, a Display Object MUST NOT:

call Intl.*
call Date.toLocaleString() / Date.toLocaleDateString() / Date.toLocaleTimeString()

Reason: these are runtime-locale/timezone dependent and cause SSR/hydration mismatches.

If a rule affects system correctness or persistence, it does not belong in a Display Object.

Ownership & Placement

Display Objects belong to the presentation layer
They are frontend-only
They are not shared with the backend or core

Placement rule (strict):

Display Objects live under apps/website/lib/display-objects/*.

Relationship to View Models

View Models MAY use Display Objects
Display Objects MUST NOT depend on View Models
Display Objects represent parts
View Models represent screens

Additional strict rules:

View Models SHOULD compose Display Objects.
Display Objects MUST NOT be serialized or passed across boundaries.
- They must not appear in server-to-client DTOs.
- Templates should receive primitive display outputs, not Display Object instances.

Testing

Display Objects SHOULD be tested because they often contain:

locale-specific behavior
formatting rules
edge cases visible to users

Additionally:

test determinism by running the same inputs under Node and browser contexts (where applicable)
test boundary rules (no Intl.*, no toLocale*)

Summary

Display Objects encapsulate how something looks
View Models encapsulate what a screen needs
Both are presentation concerns
Neither contains business truth

In one sentence: Display Objects are Value Objects for UI display, not utility functions.

3.0 KiB Raw Blame History