docs

docs/architecture/website/DISPLAY_OBJECTS.md

@@ -0,0 +1,125 @@
+# 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.