Thema-fundament: variant (B/E) x modus (licht/donker), tijdreis-knop en overgang

Vervangt rood/paars door tokens per variant en modus, voegt ModeToggle en
icoon-knop VariantToggle toe, VariantRenderer met lazy E-chunk, dither-overgang
(uit bij minder beweging), theme-init.js tegen themaflits en tests.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-11-09 21:14:11 +01:00
co-authored by Claude Sonnet 5.5
parent 1047c738b5
commit 0854e3a096
37 changed files with 1389 additions and 269 deletions
@@ -502,3 +502,15 @@
**Context**: Code Generation U1 Part 2 starts.
---
## Builder CMS-U3 Accepted
**Timestamp**: 2026-11-10T05:10:00Z
**User Input**: "(cross-session message from SLS Software - CMS: CMS-U3 contact-core done, commit b9af7df; summary at K:\Development\Projects\SlpModularCms-contact-forms\aidlc-docs\features\contact-forms-module\construction\cms-u3-contact-core\code\summary.md)"
**AI Response**: "Accepted on the basis of the builder's report (not yet read in full): Modules.Contact + Tests, migration InitialCreate, public routes with [PublicSiteEndpoint], 404 gate behind IContactFormGate, spam path, idempotency, retention job; tests against a temporary MariaDB (Contact.Tests 113, Core 205, Availability 95, Offerings 86, Identity 37, Master 57, Api 4 passed). Contract deviations adopted: hpCheck JSON name fixed, missing hpCheck counts as empty, unbindable body gives 400 errors.body=['invalid']. Sentry events contain the IP (SendDefaultPii) but no form data; no IP in the database (to mention in the privacy statement review). Builder may send CMS-U3b and CMS-U4 plans together."
**Context**: Leading the builder. Summary file to be read when preparing the frontend handoff (U4).
---
@@ -22,19 +22,19 @@ Single source of truth for U1 Code Generation. Inputs: `unit-of-work.md` (U1), F
- Docs: C `aidlc-docs/features/redesign-modern-timetravel/construction/theme-foundation/code/summary.md`
## Steps
- [ ] **Step 0 — Preparation**: commit the AI-DLC inception/design documents separately (`aidlc-docs/`) on the branch so code commits stay clean. Verify the baseline: `pnpm test`, `pnpm lint`, `pnpm build` are green before changes (record the numbers).
- [ ] **Step 1 — Dependency and fonts**: add `@fontsource-variable/archivo` (variable weight + width axis) respecting the repo's pnpm settings; if the package is blocked by the release-age policy or missing, stop and report instead of working around it. Import it in `src/fonts.ts` next to the existing fonts (old fonts are removed in U2); add Tailwind `fontFamily.archivo`.
- [ ] **Step 2 — Tokens (pure logic)**: rewrite `src/theme/tokens.ts`: types `Variant`, `Mode`, `ModeSource`; constants `MODE_STORAGE_KEY = 'slp-software-mode'`, `LEGACY_THEME_STORAGE_KEY = 'slp-software-theme'`; pure functions `isValidMode`, `resolveInitialMode(stored, systemPrefersDark)` returning `{ mode, source }`. (BR-U1-1, 2, 11)
- [ ] **Step 3 — Media-query hooks**: `usePrefersReducedMotion`, `usePrefersDark` (SSR-safe, subscribe/unsubscribe, jsdom-safe when `matchMedia` is missing → defaults false). (BR-U1-3, 9)
- [ ] **Step 4 — CSS tokens**: in `src/index.css` replace `.theme-red/.theme-purple` with `html[data-variant='b'][data-mode='light'|'dark']` and E placeholders (`'e'`, light/dark, accent `#AC0000`) with the semantic variables; B accent `#7A1414`; transitions guarded by `prefers-reduced-motion`; add the dither overlay classes (checker mask + `steps()` keyframes, accent colored), all disabled under reduced motion. (FR-3, BR-U1-9)
- [ ] **Step 5 — No-flash script**: create `public/theme-init.js` (plain ES5, guarded storage access, sets `data-variant="b"` and `data-mode` on `<html>`, mirrors `resolveInitialMode`); add `<script src="/theme-init.js"></script>` (blocking, in `<head>`) in `index.html`. No inline script. (BR-U1-5)
- [ ] **Step 6 — ThemeProvider**: rewrite with `variant`, `mode`, `modeSource`, `toggleMode`, `toggleVariant`, `transition`, `announce`; follow system changes while source is `system`; persist mode on user toggle (guarded); remove the legacy key once; apply data attributes in an effect; `toggleVariant` runs the phases cover → swap → reveal (timers, ~300 ms each), scrolls to top and moves focus to `#main` after the swap, immediate under reduced motion. (BR-U1-1..10, FR-5)
- [ ] **Step 7 — UI components**: `ModeToggle` (aria-pressed = dark, label "Donkere weergave", ≥44px target on mobile, `data-testid="mode-toggle-button"`), icon-only `VariantToggle` (label "Tijdreis: bekijk de site zoals vroeger" / "Terug naar nu", tooltip = label, `data-testid="variant-toggle-button"`), `TransitionOverlay`, `LiveRegion`, `EBoundary`, `VariantRenderer` (B eager, E via `React.lazy(() => import('../../variants/e/LandingE'))`, `Suspense` fallback = cover, error → B + alert + retry). Delete `ThemeToggle.tsx`. (FR-4, FR-6, BR-U1-6..8, 12)
- [ ] **Step 8 — Layout integration**: `Nav.tsx` shows `ModeToggle` then `VariantToggle` (desktop and mobile bar); `RootLayout.tsx` wraps content in `<main id="main" tabIndex={-1}>`, renders `VariantRenderer` (B shell = Nav + page + Footer), `TransitionOverlay`, `LiveRegion`; `LandingE` is a minimal placeholder ("Tijdreis — in aanbouw") with its own nav containing the two toggles so the round trip is testable. `src/routes/__root.tsx` composition order unchanged.
- [ ] **Step 9 — Tests**: per the acceptance list in `frontend-components.md` (8 items): table-driven `resolveInitialMode`; ThemeProvider (first render, legacy key removal, system change following, user click stops following, persistence, storage failure, variant never persisted); variant switch (scroll to top, focus on `#main`, announcement, reduced-motion path with no overlay, failure path with alert + retry); accessibility attributes of both buttons; Nav test updates. Replace obsolete red/purple assertions.
- [ ] **Step 10 — Build and test (automatic, Step 13.5)**: `pnpm lint`, `pnpm test`, `pnpm build` (runs `tsc -b`). Fix and retry until green; report real counts. Manual smoke check of both modes via `pnpm build` output is not required.
- [ ] **Step 11 — Docs**: write `construction/theme-foundation/code/summary.md` (files, behaviour, how to use the hooks, notes for U2..U5, the `/theme-init.js` CSP/nginx note for Operations: must be served same-origin and not cached long).
- [ ] **Step 12 — Commit**: one commit for U1 code (Dutch message in the repo's style, `Co-Authored-By` line as required). No push.
- [x] **Step 0 — Preparation**: commit the AI-DLC inception/design documents separately (`aidlc-docs/`) on the branch so code commits stay clean. Verify the baseline: `pnpm test`, `pnpm lint`, `pnpm build` are green before changes (record the numbers).
- [x] **Step 1 — Dependency and fonts**: add `@fontsource-variable/archivo` (variable weight + width axis) respecting the repo's pnpm settings; if the package is blocked by the release-age policy or missing, stop and report instead of working around it. Import it in `src/fonts.ts` next to the existing fonts (old fonts are removed in U2); add Tailwind `fontFamily.archivo`.
- [x] **Step 2 — Tokens (pure logic)**: rewrite `src/theme/tokens.ts`: types `Variant`, `Mode`, `ModeSource`; constants `MODE_STORAGE_KEY = 'slp-software-mode'`, `LEGACY_THEME_STORAGE_KEY = 'slp-software-theme'`; pure functions `isValidMode`, `resolveInitialMode(stored, systemPrefersDark)` returning `{ mode, source }`. (BR-U1-1, 2, 11)
- [x] **Step 3 — Media-query hooks**: `usePrefersReducedMotion`, `usePrefersDark` (SSR-safe, subscribe/unsubscribe, jsdom-safe when `matchMedia` is missing → defaults false). (BR-U1-3, 9)
- [x] **Step 4 — CSS tokens**: in `src/index.css` replace `.theme-red/.theme-purple` with `html[data-variant='b'][data-mode='light'|'dark']` and E placeholders (`'e'`, light/dark, accent `#AC0000`) with the semantic variables; B accent `#7A1414`; transitions guarded by `prefers-reduced-motion`; add the dither overlay classes (checker mask + `steps()` keyframes, accent colored), all disabled under reduced motion. (FR-3, BR-U1-9)
- [x] **Step 5 — No-flash script**: create `public/theme-init.js` (plain ES5, guarded storage access, sets `data-variant="b"` and `data-mode` on `<html>`, mirrors `resolveInitialMode`); add `<script src="/theme-init.js"></script>` (blocking, in `<head>`) in `index.html`. No inline script. (BR-U1-5)
- [x] **Step 6 — ThemeProvider**: rewrite with `variant`, `mode`, `modeSource`, `toggleMode`, `toggleVariant`, `transition`, `announce`; follow system changes while source is `system`; persist mode on user toggle (guarded); remove the legacy key once; apply data attributes in an effect; `toggleVariant` runs the phases cover → swap → reveal (timers, ~300 ms each), scrolls to top and moves focus to `#main` after the swap, immediate under reduced motion. (BR-U1-1..10, FR-5)
- [x] **Step 7 — UI components**: `ModeToggle` (aria-pressed = dark, label "Donkere weergave", ≥44px target on mobile, `data-testid="mode-toggle-button"`), icon-only `VariantToggle` (label "Tijdreis: bekijk de site zoals vroeger" / "Terug naar nu", tooltip = label, `data-testid="variant-toggle-button"`), `TransitionOverlay`, `LiveRegion`, `EBoundary`, `VariantRenderer` (B eager, E via `React.lazy(() => import('../../variants/e/LandingE'))`, `Suspense` fallback = cover, error → B + alert + retry). Delete `ThemeToggle.tsx`. (FR-4, FR-6, BR-U1-6..8, 12)
- [x] **Step 8 — Layout integration**: `Nav.tsx` shows `ModeToggle` then `VariantToggle` (desktop and mobile bar); `RootLayout.tsx` wraps content in `<main id="main" tabIndex={-1}>`, renders `VariantRenderer` (B shell = Nav + page + Footer), `TransitionOverlay`, `LiveRegion`; `LandingE` is a minimal placeholder ("Tijdreis — in aanbouw") with its own nav containing the two toggles so the round trip is testable. `src/routes/__root.tsx` composition order unchanged.
- [x] **Step 9 — Tests**: per the acceptance list in `frontend-components.md` (8 items): table-driven `resolveInitialMode`; ThemeProvider (first render, legacy key removal, system change following, user click stops following, persistence, storage failure, variant never persisted); variant switch (scroll to top, focus on `#main`, announcement, reduced-motion path with no overlay, failure path with alert + retry); accessibility attributes of both buttons; Nav test updates. Replace obsolete red/purple assertions.
- [x] **Step 10 — Build and test (automatic, Step 13.5)**: `pnpm lint`, `pnpm test`, `pnpm build` (runs `tsc -b`). Fix and retry until green; report real counts. Manual smoke check of both modes via `pnpm build` output is not required.
- [x] **Step 11 — Docs**: write `construction/theme-foundation/code/summary.md` (files, behaviour, how to use the hooks, notes for U2..U5, the `/theme-init.js` CSP/nginx note for Operations: must be served same-origin and not cached long).
- [x] **Step 12 — Commit**: one commit for U1 code (Dutch message in the repo's style, `Co-Authored-By` line as required). No push.
## Explicitly NOT touched in U1
Section content and layout (Hero, About, Packages, Process, Contact), `content.ts`, `usePackagesQuery`, Sentry/Umami wiring, nginx configs, router. Old fonts stay until U2. The E variant's real content is U5.
@@ -0,0 +1,29 @@
# Code Summary — theme-foundation (U1)
## What was built
- **Theme model**: variant (`b` | `e`) × mode (`light` | `dark`). The old red/purple themes are gone. The variant is always `b` at startup and never stored or in the URL; the mode follows the system preference until the first click, after which it is persisted under `slp-software-mode`. The legacy key `slp-software-theme` is removed once (BR-U1-1..4, 10, 11).
- **No theme flash**: `public/theme-init.js` is a blocking same-origin script (no inline script) that sets `data-variant` and `data-mode` on `<html>` before first paint; `ThemeProvider` keeps them in sync (BR-U1-5).
- **Tokens**: `src/index.css` defines the semantic CSS variables for B light, B dark (accent `#7A1414` light / `#E5524A` dark for text contrast), and base tokens for E light/dark (accent `#AC0000` light, a lighter red in dark; refined per era in U5). Tailwind color names are unchanged.
- **Buttons**: `ModeToggle` (aria-pressed, label "Donkere weergave") and icon-only `VariantToggle` (label changes: "Tijdreis: bekijk de site zoals vroeger" / "Terug naar nu"), both real buttons with 44px touch targets on mobile, in the nav of B and in the E placeholder (BR-U1-12).
- **Variant switching**: `ThemeProvider.toggleVariant` runs the time-travel transition (cover → swap → reveal, 300 ms phases, zero under reduced motion): E is preloaded via `loadVariant` (lazy chunk `LandingE`), the page scrolls to the top, focus moves to `#main`, and a live region announces the result. A load failure keeps B and shows `VariantAlert` with retry; a crash in E is caught by `EBoundary` (BR-U1-6..9).
- **Transition effect**: `TransitionOverlay` + `.tt-overlay` CSS (pixel-dither checker, `steps()` animation); not rendered under `prefers-reduced-motion`.
- **Layout**: `RootLayout` renders `VariantRenderer` (B shell = Nav + `<main id="main" tabIndex=-1>` + Footer), `TransitionOverlay`, `LiveRegion`, `VariantAlert`.
- **Font**: `@fontsource-variable/archivo` (weight + width axes) added and imported; Tailwind `fontFamily.archivo`. The old families stay until U2.
- **E placeholder**: `src/variants/e/LandingE.tsx` (own nav with the two toggles, "in aanbouw" content). Real content is U5.
## Files
- Modified: `index.html`, `package.json`, `pnpm-lock.yaml`, `tailwind.config.ts`, `src/fonts.ts`, `src/index.css`, `src/theme/tokens.ts`, `src/theme/ThemeProvider.tsx`, `src/components/layout/Nav.tsx`, `src/components/layout/RootLayout.tsx`, `src/routes/__root.tsx`, `src/test/setup.ts`, tests `ThemeProvider.test.tsx`, `Nav.test.tsx`.
- Created: `public/theme-init.js`, `src/theme/loadVariant.ts`, `src/shared/hooks/{mediaQuery,usePrefersDark,usePrefersReducedMotion}.ts`, `src/components/ui/{ModeToggle,VariantToggle}.tsx`, `src/components/layout/{VariantRenderer,TransitionOverlay,LiveRegion,VariantAlert,EBoundary}.tsx`, `src/variants/e/LandingE.tsx`, `src/test/matchMedia.ts`, tests `tokens.test.ts`, `mediaQueryHooks.test.tsx`, `Toggles.test.tsx`, `VariantRenderer.test.tsx`.
- Deleted: `src/components/ui/ThemeToggle.tsx`.
## Verification (Step 13.5, real output)
- Baseline before changes: 6 test files / 24 tests passed, lint 0 errors (2 existing warnings), build OK.
- After: **10 test files / 56 tests passed**, `pnpm lint` 0 errors (same 2 warnings: `react-refresh/only-export-components` in `SentryTestButton.tsx` and `ThemeProvider.tsx`, the latter existed before as well), `pnpm build` OK (tsc -b + vite). E is a separate chunk (`LandingE-*.js`, 0.9 kB); main bundle 444.8 kB (baseline 438.3 kB, +Archivo CSS).
- `pnpm-lock.yaml` also contains peer-suffix (`supports-color`) churn produced by the local pnpm 12; the only real addition is `@fontsource-variable/archivo@5.3.0`.
## Notes for the next units
- Use `useTheme()` for `variant`/`mode`; use semantic Tailwind colors (`bg-bg`, `text-text`, `border-line`, `text-accent`...) so both modes and variants work. U2 restyles the sections to design B and then removes the old font families.
- **Interim look**: until U2 the existing sections use the new B tokens (light by default for many visitors).
- **Operations notes**: `/theme-init.js` must be served same-origin (CSP `script-src 'self'`) and must not be cached for long; the E chunk file name changes per build.
- jsdom helpers: `src/test/matchMedia.ts` (`mockMatchMedia`, `clearMatchMedia`) and a global `window.scrollTo` mock in `src/test/setup.ts`.
- Not done on purpose: mobile menu keeps the two toggles in the top bar (they are always visible); icons are inline SVG.
@@ -50,7 +50,7 @@ Request body:
| `email` | string | yes | trimmed, 1–254 chars, regex `^[^\s@]+@[^\s@]+\.[^\s@]{2,}$`, no control characters |
| `subject` | string | yes | trimmed, 1–100 chars; **opaque value** chosen by the site (a package id, slug, or `other`); no slug regex; stored as given, never validated against offerings. The label of `other` is per site (ASF: "Overig"). |
| `message` | string | yes | trimmed, 1–2000 chars |
| `hpCheck` | string | yes (key present) | **honeypot**; must be empty. Deliberately implausible name (not `website`/`url`) to avoid password-manager autofill; field is configurable per site; render with `autocomplete="off"`, `tabindex="-1"`, `aria-hidden`, off-screen |
| `hpCheck` | string | no (a missing key counts as empty; CMS-U3) | **honeypot**; must be empty. The JSON name is fixed `hpCheck`; the DOM name/id in the site is free. Deliberately implausible name (not `website`/`url`) to avoid password-manager autofill; render with `autocomplete="off"`, `tabindex="-1"`, `aria-hidden`, off-screen |
| `token` | string | yes | from 2.1 |
| `captchaToken` | string \| null | when `captcha` enabled | verified server-side |
@@ -71,7 +71,7 @@ Responses:
"errors": { "name": ["required"], "email": ["invalid"], "message": ["tooLong"] }
}
```
The `type` URI is configurable per host (`Contact:ProblemTypeBase`), default `about:blank`, so no site domain is hard-coded in a module used by two sites; clients map on `errors`, never on `type`. Codes: `required`, `tooLong`, `invalid`, `expired` (token only; also for forged/other-site tokens). The `errors` mapping is custom (not the default ASP.NET `ValidationProblemDetails`). Messages are **not** localized by the API; the client maps `messages[field][code]`. Client-side validation uses the same limits and codes.
The `type` URI is configurable per host (`Contact:ProblemTypeBase`), default `about:blank`, so no site domain is hard-coded in a module used by two sites; clients map on `errors`, never on `type`. Codes: `required`, `tooLong`, `invalid`, `expired` (token only; also for forged/other-site tokens). A body that cannot be bound (broken JSON, wrong types) answers `400` with `errors.body = ["invalid"]` in the same problem shape, without echoing values (implemented in CMS-U3). The `errors` mapping is custom (not the default ASP.NET `ValidationProblemDetails`). Messages are **not** localized by the API; the client maps `messages[field][code]`. Client-side validation uses the same limits and codes.
## 4. Server behaviour agreements
1. **Store first, mail after commit.** Validate → store and commit (`status: new`, `mailStatus: pending`) → respond 202. Mail is **not fire-and-forget** in the request scope: a `BackgroundService`/queue picks up `pending` rows, sends via `IEmailSender`/`IMailAvailability` (returns `MailSendResult`, does not throw) and updates `mailStatus` and `mailAttempts`. A short sweep (every few minutes) catches `pending` rows left by a crash; `failed` rows are retried with **backoff** up to a configurable max attempts (so a first outage does not mean 24 h delay). A mail failure never fails the request. If `Email:Smtp:Host` is not configured: store only, show a notice in the admin.