Plans the Contact page and records unit 1 as generated

Workspace detection, a reverse engineering delta, requirements with the
approved layout mockups, the execution plan and the application design
for the Contact page, plus the code generation plan and summary of the
webPage helper. Corrects the contact payload in the shared API notes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-10-25 16:59:38 +01:00
co-authored by Claude Opus 5.5
parent a58bc1c1d6
commit 4c257b7ac0
23 changed files with 1766 additions and 1 deletions
@@ -0,0 +1,68 @@
# Application Design Plan — Contact Page
Depth: minimal. Business rules (what `ContactPanel` must keep from the homepage, which channels the card shows, the `?pakket=` handling on this page, the responsive photo) follow in Functional Design for units 2 and 3.
## Plan
- [x] Answer the design questions below
- [x] Generate `components.md` — new and changed components with responsibilities and interfaces
- [x] Generate `component-methods.md` — props and function signatures (incl. `webPage()`)
- [x] Generate `services.md` — composition in the routes (there is no service layer in this SPA)
- [x] Generate `component-dependency.md` — dependency matrix and data flow
- [x] Generate `application-design.md` — consolidated design
- [x] Validate completeness and consistency against requirements.md
## Already decided (no question needed)
- **`webPage(type: WebPageType, path: RoutePath, extra = {})`** in `seo.ts`, as agreed with portfolio-page and soorten-fotoshoots-page: `@context`, `@type`, `@id` = `url` = `canonicalUrl(path)`, `name`/`description` from `sitePages[path]`, `inLanguage: 'nl-NL'`, then `...extra`. `WebPageType = 'WebPage' | 'AboutPage' | 'ContactPage' | 'ImageGallery' | 'CollectionPage'`. `aboutPage()` keeps its signature and becomes `webPage('AboutPage', path, { mainEntity: person(...) })`. A new `contactPage(path)` = `webPage('ContactPage', path, { about: { '@id': businessId } })`.
- **Icons**: the card reuses the existing platform registry (`content/socialPlatforms.ts`: name + offline icon for Facebook and Instagram) plus one mail icon from the same set (`@iconify-icons/ant-design`). No new dependency.
- **Privacy line**: part of `ContactForm` itself (under the submit button), so every form that uses it has the line. Link target `/privacyverklaring` as a typed route.
- **Reply time**: one value in `SiteContent` (e.g. `contactForm: { enabled, replyTime: '1-2 werkdagen' }`), passed to `ContactForm` for the thank-you message and used by the contact page intro.
- **Folders**: shared pieces at the top level of `components/` (`ContactPanel/`, `ContactDetails/`), page-specific pieces in `components/contact/` (like `components/about/` for Over mij). Content in `content/contactContent.ts` with a `ContactPageContent` interface in `content/types.ts`.
---
Vul per vraag de letter in na `[Answer]:`. Past geen enkele optie, kies dan de laatste (Anders) en licht toe.
## Vraag 1: Wat gaat er mee in `ContactPanel`?
Het contactblok op de homepage (`ContactSection`) doet nu zes dingen: (1) de kop "Contact", (2) de gate, (3) het formulier lazy laden met een placeholder, (4) de shoot-opties uit de pakketten, (5) de voorselectie uit `?pakket=` plus het mailonderwerp, en (6) `?pakket=` uit de adresbalk halen, naar `#contact` scrollen en de focus op de kop zetten.
- A) **Punt 2 t/m 5 gaan in `ContactPanel`**, met een prop voor het laden (`lazy` op de homepage, direct op de contactpagina). Punt 1 en 6 blijven bij de pagina, omdat ze per pagina verschillen: de homepage scrollt en verplaatst de focus, de contactpagina ruimt alleen de URL op. (aanbevolen)
- B) **Alleen punt 2, 4 en 5** in `ContactPanel`. Het lazy laden (3) blijft in `ContactSection`, dat het formulier dan als `children` aan het panel geeft. Het panel blijft kleiner, maar de koppeling tussen gate, formulier en placeholder wordt omslachtiger.
- C) **Ook punt 6** in `ContactPanel`, met opties voor wel of niet scrollen en de focus verplaatsen. Alles op één plek, maar het panel moet dan de router en de pagina kennen.
- X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]: A
## Vraag 2: Hoe komt de contactkaart op twee plekken?
Op brede schermen staat de kaart rechts, over de foto, ná het formulier. Op smalle schermen staat hij bovenaan, vóór het formulier en met het kleine portret. Voor toetsenbord- en screenreadergebruikers moet de volgorde in de HTML gelijk zijn aan wat je ziet.
- A) **Twee keer renderen, per schermbreedte één zichtbaar**: één kaart in de rechterkolom (alleen breed), één boven het formulier met portret (alleen smal). De verborgen kaart is met `display: none` volledig weg, ook voor screenreaders. Ze krijgen elk een eigen id, zodat er geen dubbele ids zijn. De volgorde klopt dan altijd. (aanbevolen)
- B) **Eén keer renderen, vóór het formulier in de HTML**. Op brede schermen zet CSS hem rechts. Op desktop komt de toetsenbordfocus dan eerst langs de kaart en pas daarna bij het formulier, terwijl je het formulier links als eerste ziet.
- C) **Eén keer renderen, op de plek die past bij de schermbreedte**: React kiest met een media query waar hij staat. Na het laden kan hij één keer verspringen als de schermbreedte bekend wordt.
- X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]: A
## Vraag 3: De tekst bij Instagram en Facebook in de kaart
Bij e-mail is het adres de linktekst. Voor Instagram en Facebook heeft de content nu alleen het platform en de URL.
- A) **Een optioneel `label` per sociale link in de content** (bijvoorbeeld "@andreaslopfotografie"). Zonder label toont de kaart de naam van het platform ("Instagram"). Andrea kan het straks in het CMS aanpassen. (aanbevolen)
- B) **Afleiden uit de URL**: "@" plus het laatste stuk van het pad (`instagram.com/andreaslopfotografie/` → "@andreaslopfotografie"). Geen extra veld, maar dat werkt niet voor elke link (bijvoorbeeld een Facebook-pagina met een id-URL).
- C) **Altijd de naam van het platform** ("Instagram", "Facebook"), zoals in de footer
- X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]: A
## Vraag 4: Het blok "foto met kaart erover"
De rechterkolom (foto 4:5 met de kaart over de onderrand) is nu alleen voor deze pagina. Het lijkt op `FramedImage` (foto met een zandkleurig vlak erachter), maar dan met inhoud over de foto heen.
- A) **Een paginacomponent in `components/contact/`** (werktitel `ContactAside`), die `ContactDetails` en de foto samenstelt. Wordt het later ook elders nodig, dan maken we hem dan algemeen. (aanbevolen)
- B) **Nu al een algemene component** (werktitel `MediaCard`: foto met een willekeurige kaart erover), voor eventueel later gebruik op andere pagina's
- X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]: A
@@ -0,0 +1,170 @@
# Execution Plan — Contact Page
## Detailed Analysis Summary
### Transformation Scope (Brownfield)
- **Transformation Type**: Single component (`web/`), application-level only
- **Primary Changes**: replace the `/contact` placeholder with the real page (layout proposal 1a); extract the homepage contact form wiring into a shared `ContactPanel`; a new shared `ContactDetails` card; a privacy line and one reply-time value shared by both forms; a generic `webPage()` structured-data helper (consumed by two parallel features); page SEO (indexing, title/description, `ContactPage` JSON-LD, own preview image); Over mij links to `/contact`
- **Related Components**: `web/src/routes/contact.tsx`, `web/src/components/{ContactForm,home/ContactSection}`, new `ContactPanel` and `ContactDetails`, `web/src/content/` (`siteContent`, new contact content, `aboutContent`), `web/src/seo.ts`, `web/src/sitePages.ts`, `web/lighthouserc*.cjs`, `web/public/`, `web/src/assets/`, [LAYOUT.md](../../../../../LAYOUT.md)
### Change Impact Assessment
- **User-facing changes**: Yes — a new page; the homepage contact section gains the privacy line and must otherwise look and behave exactly as before; two Over mij links change target
- **Structural changes**: Minor — two shared components extracted/added; no architectural change
- **Data model changes**: Yes (small) — new contact page content interface; a reply-time value in `SiteContent`
- **API changes**: No external API. Internal: `webPage()` + `WebPageType` become a shared contract for portfolio-page and soorten-fotoshoots-page; `/contact?pakket=<packageId>` becomes a URL contract for soorten-fotoshoots-page
- **NFR impact**: Yes — SEO (indexed, structured data), accessibility (heading outline with a visually hidden h2, icon list), performance (form loads with the page; the large photo is the LCP on wide screens and must not load on phones)
### Component Relationships
```mermaid
graph TD
Route["routes/contact.tsx (new page)"] --> PageIntro["PageIntro (existing)"]
Route --> PageSection["PageSection (existing)"]
Route --> Panel["ContactPanel (new, extracted)"]
Route --> Details["ContactDetails (new)"]
Route --> Content["content: contact page content (new)"]
Route --> Seo["seo.ts: webPage + ContactPage (new)"]
HomeContact["home/ContactSection"] --> Panel
Panel --> Gate["ContactFormGate (existing)"]
Panel --> Form["ContactForm (privacy line, reply time)"]
Details --> SiteContent["siteContent (reply time added)"]
Form --> SiteContent
Seo --> AboutPage["aboutPage (rebuilt on webPage)"]
Seo --> Peers["portfolio-page and soorten-fotoshoots-page"]
AboutContent["aboutContent: links to /contact"] --> Route
classDef newpart fill:#FFA726,stroke:#E65100,stroke-width:1px,color:#000;
classDef changed fill:#63b3ed,stroke:#2b6cb0,stroke-width:1px,color:#000;
classDef existing fill:#e2e8f0,stroke:#4a5568,stroke-width:1px,color:#000;
classDef peer fill:#CE93D8,stroke:#6A1B9A,stroke-width:1px,color:#000;
class Route,Panel,Details,Content,Seo newpart;
class HomeContact,Form,SiteContent,AboutPage,AboutContent changed;
class PageIntro,PageSection,Gate existing;
class Peers peer;
```
Text alternative: the new contact route composes the existing PageIntro and PageSection with the new ContactPanel and ContactDetails, new content and the new webPage-based structured data; the homepage contact section switches to ContactPanel; the form gains the privacy line and the shared reply time; aboutPage is rebuilt on webPage, which the two parallel features also use; Over mij content links to the new page.
- **Primary Component**: `web` (front-end SPA)
- **Shared Components**: `seo.ts` (Minor, new `webPage()`; `aboutPage()` output unchanged), `ContactPanel` (new, used by the homepage), `ContactForm` (Minor: privacy line, reply time from content), `ContactDetails` (new)
- **Dependent Components**: homepage `ContactSection`; Over mij content; portfolio-page and soorten-fotoshoots-page (consume `webPage()` and the `?pakket=` contract)
- **Supporting Components**: Lighthouse CI config (Configuration-only), LAYOUT.md (documentation)
### Coordination with Parallel Features
- **Critical path for others**: unit 1 (`webPage()`) — portfolio-page and soorten-fotoshoots-page cherry-pick its commit; hash sent to both sessions right after it is committed.
- **Incoming**: soorten-fotoshoots-page commits `siteContent.serviceArea` + `professionalService()` changes in `seo.ts`; whoever commits second rebases. No functional dependency for this page (the description text is static in `sitePages.ts`).
- **Hot files**: own entries only in `sitePages.ts`, `lighthouserc*.cjs`, `active-features.md`.
### Risk Assessment
- **Risk Level**: Low to medium — the `ContactPanel` extraction touches the most intricate homepage section (lazy loading, `?pakket=` clean-up, focus, scroll); everything else is additive
- **Rollback Complexity**: Easy (one branch, commits per unit; unit 1 independent)
- **Testing Complexity**: Moderate — existing `ContactSection`, `ContactForm` and route tests guard the homepage behaviour; new tests for the page, the card, the URL parameter and the responsive photo; Lighthouse for `/contact`
## Workflow Visualization
```mermaid
flowchart TD
Start(["User Request"])
subgraph INCEPTION["🔵 INCEPTION PHASE"]
WD["Workspace Detection<br/><b>COMPLETED</b>"]
RE["Reverse Engineering<br/><b>COMPLETED</b>"]
RA["Requirements Analysis<br/><b>COMPLETED</b>"]
US["User Stories<br/><b>SKIP</b>"]
WP["Workflow Planning<br/><b>IN PROGRESS</b>"]
AD["Application Design<br/><b>EXECUTE</b>"]
UG["Units Generation<br/><b>SKIP</b>"]
end
subgraph CONSTRUCTION["🟢 CONSTRUCTION PHASE"]
FD["Functional Design<br/><b>EXECUTE (units 2 and 3)</b>"]
NFRA["NFR Requirements<br/><b>SKIP</b>"]
NFRD["NFR Design<br/><b>SKIP</b>"]
ID["Infrastructure Design<br/><b>SKIP</b>"]
CG["Code Generation<br/>(Planning + Generation)<br/><b>EXECUTE</b>"]
BT["Build and Test<br/><b>EXECUTE</b>"]
end
Start --> WD
WD --> RE
RE --> RA
RA --> WP
WP --> AD
AD --> FD
FD --> CG
CG --> BT
BT --> End(["Complete"])
style WD fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff
style RE fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff
style RA fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff
style WP fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff
style CG fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff
style BT fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff
style AD fill:#FFA726,stroke:#E65100,stroke-width:3px,stroke-dasharray: 5 5,color:#000
style FD fill:#FFA726,stroke:#E65100,stroke-width:3px,stroke-dasharray: 5 5,color:#000
style US fill:#BDBDBD,stroke:#424242,stroke-width:2px,stroke-dasharray: 5 5,color:#000
style UG fill:#BDBDBD,stroke:#424242,stroke-width:2px,stroke-dasharray: 5 5,color:#000
style NFRA fill:#BDBDBD,stroke:#424242,stroke-width:2px,stroke-dasharray: 5 5,color:#000
style NFRD fill:#BDBDBD,stroke:#424242,stroke-width:2px,stroke-dasharray: 5 5,color:#000
style ID fill:#BDBDBD,stroke:#424242,stroke-width:2px,stroke-dasharray: 5 5,color:#000
style INCEPTION fill:#BBDEFB,stroke:#1565C0,stroke-width:3px,color:#000
style CONSTRUCTION fill:#C8E6C9,stroke:#2E7D32,stroke-width:3px,color:#000
style Start fill:#CE93D8,stroke:#6A1B9A,stroke-width:3px,color:#000
style End fill:#CE93D8,stroke:#6A1B9A,stroke-width:3px,color:#000
linkStyle default stroke:#333,stroke-width:2px
```
Text alternative: completed Workspace Detection, Reverse Engineering and Requirements Analysis lead to Workflow Planning, then Application Design, Functional Design (units 2 and 3), Code Generation per unit and Build and Test; User Stories, Units Generation, NFR Requirements, NFR Design, Infrastructure Design and the Operations phase are skipped.
## Phases to Execute
### 🔵 INCEPTION PHASE
- [x] Workspace Detection (COMPLETED)
- [x] Reverse Engineering (COMPLETED — delta)
- [x] Requirements Analysis (COMPLETED)
- [x] User Stories (SKIPPED)
- **Rationale**: one persona (the visitor), concrete FRs with texts, targets and an approved mockup
- [x] Execution Plan (IN PROGRESS)
- [ ] Application Design - EXECUTE (minimal depth)
- **Rationale**: new shared components and a shared contract need agreed boundaries before code: `webPage()` signature and its properties (already announced to two sessions), `ContactPanel` (what moves out of `ContactSection`, lazy vs eager), `ContactDetails` (props, data source, label per channel), where the privacy line and the reply time live, and the content interface for the page
- [ ] Units Generation - SKIP
- **Rationale**: the split is fixed below (three units); no separate unit-of-work artifacts needed
### 🟢 CONSTRUCTION PHASE
- [ ] Functional Design - EXECUTE for units 2 and 3 (minimal depth)
- **Rationale**: unit 2 has rules worth pinning down before code (which homepage behaviour `ContactPanel` must keep, which channels the card shows and with what label, PBT properties per PBT-01); unit 3 has the `?pakket=` handling on this page (clean-up without focus move), the responsive photo rule (LCP on wide screens, not downloaded on phones) and the content model. Unit 1 is a small pure helper whose properties are set in Application Design
- [ ] NFR Requirements - SKIP
- **Rationale**: NFRs are set at requirements level (NFR-CP-01..06) and the stack is fixed
- [ ] NFR Design - SKIP
- **Rationale**: no new NFR patterns; the responsive-photo approach is decided in Functional Design of unit 3; existing patterns (DeferredImage, Reveal, jsonLdScript, focus ring) are reused
- [ ] Infrastructure Design - SKIP
- **Rationale**: static assets only; no server config, CSP or deployment changes
- [ ] Code Generation - EXECUTE (ALWAYS, per unit)
- **Rationale**: implementation and tests
- [ ] Build and Test - EXECUTE (ALWAYS)
- **Rationale**: full `pnpm check` incl. Lighthouse for `/`, `/over-mij` and `/contact`
### 🟡 OPERATIONS PHASE
- [ ] Deployment Setup, Monitoring Setup, Production Readiness Validation - SKIP
- **Rationale**: Operations Configuration = No; the existing pipeline deploys to test on merge
## Units of Work (in order)
| # | Unit | Scope | Requirements |
|---|---|---|---|
| 1 | **webPage helper** | `webPage()` + `WebPageType` in `seo.ts`; `aboutPage()` rebuilt on it with identical output; example and property tests. Only `seo.ts` and `seo.test.ts`. One commit; hash sent to portfolio-page and soorten-fotoshoots-page. | SEO-CP-03 (helper part) |
| 2 | **Shared contact blocks** | Extract `ContactPanel` from `ContactSection` (homepage unchanged apart from the privacy line); privacy line under the form; reply time as one `siteContent` value used by the thank-you message; new `ContactDetails` card (icons, valid channels only). | FR-CP-02 (shared parts), FR-CP-04, FR-CP-06, FR-CP-07, FR-CP-08, NFR-CP-02 |
| 3 | **Contact page** | Photos (original resized, small portrait crop, 1200×630 preview) with alt texts; page content + types; the route with layout 1a and the narrow-screen card; `?pakket=` preselect; SEO (indexed, title/description, `ogImage`, `ContactPage` JSON-LD, Lighthouse indexed paths); Over mij links to `/contact`; LAYOUT.md. | FR-CP-01..05, FR-CP-09..11, SEO-CP-01..05, NFR-CP-01, 03..06 |
Unit 1 goes first because two other features wait for it and it is independent of the rest. Unit 2 before unit 3 because the page builds on its components. Each unit: one or more commits on `feature/contact-page`, full `pnpm check` (incl. Lighthouse) before its completion message; one PR to master at the end.
## Estimated Timeline
- **Total Stages to execute from here**: 6 (Application Design, Functional Design ×2 units, Code Generation ×3 units, Build and Test)
- **Estimated Duration**: two working sessions
## Success Criteria
- **Primary Goal**: a finished, indexed Contact page in the approved layout, reusing the homepage form
- **Key Deliverables**: `/contact` page; `webPage()` (shared with two features); `ContactPanel`, `ContactDetails`, privacy line, shared reply time; contact content; resized photos, portrait crop and preview image; updated Over mij links, LAYOUT.md and Lighthouse config
- **Quality Gates**: `pnpm check` passes (lint, format, tests with coverage thresholds, build, audits, Lighthouse: accessibility 1.0, best practices 1.0, performance ≥ 0.9 for `/contact`, homepage and Over mij budgets unchanged); axe clean; homepage contact section unchanged in behaviour after unit 2; `aboutPage()` output unchanged after unit 1
- **Integration Testing**: route tests render `/`, `/over-mij` and `/contact` in the shell; `/contact?pakket=newborn` preselects Newborn and cleans the URL; Over mij links reach `/contact`