gridpilot.gg/docs/architecture/website/DISPLAY_OBJECTS.md

Displays

Definition

A Display encapsulates reusable, UI-only display logic.

In this codebase, a Display 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?”

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

Naming Convention:

• Displays MUST end with Display suffix
• Displays MUST be reusable across multiple screens
• Valid examples: PriceDisplay, EmailDisplay, RatingDisplay
• Invalid examples: DashboardRatingDisplay, UserProfileDisplay

---

Responsibilities

A Display MAY:

• format values (money, dates, durations)
• handle localization only when localization inputs are deterministic (for example: mapping stable codes to stable labels)
• map codes to labels
• encapsulate UI display conventions
• be reused across multiple View Models

In addition, a Display MAY:

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

A Display MUST:

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

A Display 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 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 MUST NOT:

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

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

Localization rule (strict)

Localization MUST NOT depend on runtime locale APIs.

Allowed approaches:

• API returns the exact labels/strings for the current user context.
• Website maps stable codes to stable labels using a deterministic table.

Forbidden approaches:

• any usage of Intl.*
• any usage of toLocale*

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

---

Ownership & Placement

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

Placement rule (strict):

• Displays live under apps/website/lib/display-objects/*.
• Filenames MUST match the class name with .tsx extension (e.g., RatingDisplay.tsx contains class RatingDisplay)

---

Relationship to View Models

• View Models MAY use Displays
• Displays MUST NOT depend on View Models
• Displays represent parts
• View Models represent screens

Additional strict rules:

• View Models SHOULD compose Displays.
• Displays 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 instances.

---

Testing

Displays 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

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

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