Starts the contact form feature: AI-DLC inception and design, dev proxy for /api

Adds the contact-form-cms feature docs (requirements, execution plan,
functional and infrastructure design, code generation plan) and an optional
Vite dev proxy for /api through API_PROXY_TARGET.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-11-10 23:04:16 +01:00
co-authored by Claude Sonnet 5.5
parent 7d594ffa1d
commit 4da314c0ba
10 changed files with 490 additions and 1 deletions
+1
View File
@@ -13,3 +13,4 @@
| Feature | prerendering | ✅ Complete (merged, PR #14) | feature/prerendering (worktree ../AndreaSlopFotografie-prerendering) | web/vite.config.ts, web/src/main.tsx, web/index.html, web/config/serverConfig.ts + web/deploy, CI workflow, web/lighthouserc.cjs, possibly Reveal/useReveal and hooks using media queries | 2026-10-31 |
| Feature | testimonials-redesign | ✅ Complete (merged, PR #16) | feature/testimonials-redesign (worktree ../AndreaSlopFotografie-testimonials-redesign) | web/src/components/home/Testimonials (Testimonials, TestimonialSlide, TestimonialCarousel), web/src/recipes/carouselControl.ts, web/src/content (Testimonial type, testimonials.ts), possibly SectionHeading, LAYOUT.md, unit/e2e tests that reference the dots | 2026-11-05 |
| Feature | cms-api-foundation | ✅ Complete (merged PR #17, 2026-11-10; follow-ups: ASF production, contact feature) | feature/cms-api-foundation (worktree ../AndreaSlopFotografie-cms-api-foundation) | Cross-repo: feature briefs for the SlpModularCms repo (new Api.AndreaSlopFotografie client, per-site theming, per-site module set); in this repo only docs, later web integration (CMS serves the site) | 2026-11-05 |
| Feature | contact-form-cms | 🔵 Inception | feature/contact-form-cms (worktree ../AndreaSlopFotografie-contact-form) | web/src/components/ContactForm, ContactFormGate, web/src/contact (submitContactForm), new web/src/cms-client (copied headless package), web/config/securityHeaders.ts, content/siteContent contactForm switch | 2026-11-10 |
@@ -0,0 +1,55 @@
# AI-DLC State Tracking
## Project Information
- **Feature Name**: Contact form on the CMS API (ASF contact form talks to the SlpModularCms contact module, using the headless cms-client package)
- **Feature Slug**: contact-form-cms
- **Project Type**: Brownfield
- **Start Date**: 2026-11-10T21:42:54Z
- **Current Stage**: INCEPTION - Workflow Planning (awaiting approval)
- **Branch**: feature/contact-form-cms (from master 7d594ff)
- **Worktree**: K:\Development\SlpSoftware\Projects\AndreaSlopFotografie-contact-form
## Workspace State
- **Existing Code**: Yes (web/src has ContactForm, ContactFormGate, submitContactForm stub, contactFormReducer)
- **Reverse Engineering Needed**: No (team agreement: no full RE refresh per feature)
- **Workspace Root**: K:\Development\SlpSoftware\Projects\AndreaSlopFotografie-contact-form
## Code Location Rules
- **Application Code**: Workspace root, web code in web/ (NEVER in aidlc-docs/)
- **Feature Documentation**: aidlc-docs/features/contact-form-cms/ only
- **Shared Artifacts**: aidlc-docs/_shared/
- **Server side**: lives in the SlpModularCms repo (branch feature/contact-forms-module, session "SLS Software - CMS"); NOT built from this session, only asked for
## Language Configuration
- **Documentation Language**: English
- **Conversation Language**: User Language (Dutch)
- **Source**: inherited from aidlc-docs/language-preference.md (answer A)
## Cross-session coordination
- Source package (read only): SlpSoftware repo, src/cms-client/ (branch feature/redesign-modern-timetravel), coordinated by session "SLP Software - SLS - Main"
- Server contract: contact-api-contract.md (v0.3.x) in the SlpSoftware repo
- Milestones (plan ready, built) are reported to "SLP Software - SLS - Main"
- Nothing is pushed, merged or deployed without Bryan; the form stays off in production until Bryan's explicit go
## Extension Configuration
- Security Baseline: Yes
- Property-Based Testing: Partial (PBT-02, 03, 07, 08, 09)
## Operations Configuration
- **Include Operations Phase**: Yes
- **Decided At**: Requirements Analysis
## Stage Progress
- [x] INCEPTION - Workspace Detection (2026-11-10)
- [x] INCEPTION - Requirements Analysis (approved by SLP Software - SLS - Main on behalf of Bryan, 2026-11-10)
- [x] INCEPTION - User Stories: SKIP
- [x] INCEPTION - Workflow Planning (written, awaiting approval)
- [x] INCEPTION - Application Design: SKIP
- [x] INCEPTION - Units Generation: SKIP (one unit: contact-form)
- [ ] CONSTRUCTION - Functional Design: EXECUTE
- [ ] CONSTRUCTION - NFR Requirements: SKIP
- [ ] CONSTRUCTION - NFR Design: SKIP
- [ ] CONSTRUCTION - Infrastructure Design: EXECUTE
- [ ] CONSTRUCTION - Code Generation: EXECUTE (plan first)
- [ ] CONSTRUCTION - Build and Test: EXECUTE
- [ ] OPERATIONS - EXECUTE
@@ -0,0 +1,59 @@
# Audit Log: contact-form-cms
## Initial request (via peer session)
**Timestamp**: 2026-11-10T21:30:00Z
**User Input**: "Opdracht van Bryan: bouw het eigen contactformulier voor Andrea Slop Fotografie, en doe dat met AI-DLC (aidlc-workflow skill, eigen feature in jullie aidlc-docs; vragen interactief aan Bryan, plan-goedkeuring vóór code). Uitgangspunt/bronnen (alleen lezen, niets daarin wijzigen): Headless pakket: SlpSoftware\src\cms-client\ ... Regels: niets pushen, mergen of deployen zonder Bryan; het formulier blijft in productie uit tot Bryans expliciete go. Meld mij bij mijlpalen (plan klaar, gebouwd)." (relayed by session "SLP Software - SLS - Main"; full text in the session transcript)
**AI Response**: Asked Bryan directly whether to start; he confirmed ("Ja, start AI-DLC (Recommended)").
**Context**: Workspace Detection. Classification: Feature (full workflow), brownfield.
---
## Workspace Detection
**Timestamp**: 2026-11-10T21:42:54Z
**AI Response**: Created worktree AndreaSlopFotografie-contact-form on branch feature/contact-form-cms from master 7d594ff. Language inherited (A). Found existing ASF contact form (ContactForm, ContactFormGate, submitContactForm stub, contactFormReducer, siteContent.contactForm switch) that this feature connects to the CMS API.
**Context**: Reverse Engineering skipped (team agreement). Next: Requirements Analysis.
---
## Delegation and extension decisions
**Timestamp**: 2026-11-10T21:55:00Z
**User Input**: "`SLP Software - SLS - Main` is in de lead van de bouw van het contactformulier en de communicatie. Hij mag toestemming geven namens mij. Bij twijfel vraag van wie de toestemming komt."
**AI Response**: Recorded in memory. Asked first four requirement questions in chat.
**Context**: Bryan answered: Security Baseline = Yes; PBT = Partial; Operations = Yes (include now); Reuse = package replaces state and validation, existing ContactForm UI stays.
---
## Requirements Analysis
**Timestamp**: 2026-11-10T22:20:00Z
**User Input**: "Stuur je vragen door naar SLS sessie. als je dat niet al had gedaan. om te voorkomen dat ik 2x dezelfde vragen beantwoord en om te zorgen dat SLS alles kan reguleren"
**AI Response**: Forwarded open questions A-E to SLP Software - SLS - Main and wrote requirements.md and requirement-verification-questions.md. SLS-Main answered: captcha slot not built yet (copy final package only after its message); lazy token fetch via IntersectionObserver; Friendly Captcha v2 provisional (CSP to be confirmed by CMS-U9 and a real-browser test); ASF server side by SLS Software - CMS with AndreaSlopFotografie; plan and approval steps go to SLS-Main, who approves on Bryan's behalf within the agreed frame (push, merge, deploy, production and content/privacy preferences stay with Bryan).
**Context**: Requirements Analysis complete, approval requested.
---
## Requirements approval and Workflow Planning
**Timestamp**: 2026-11-10T22:40:00Z
**User Input**: (SLP Software - SLS - Main, on behalf of Bryan) "Requirements contact-form-cms: volledig gelezen, technisch akkoord (namens Bryan, binnen de kaders). ... Ga door met workflow planning en design; plan komt bij mij voor akkoord voor code."
**AI Response**: Processed the six refinements into requirements.md. Wrote inception/plans/execution-plan.md.
**Context**: Workflow Planning complete; approval requested from SLS-Main.
---
@@ -0,0 +1,115 @@
# Functional design: contact-form (unit 1, web)
Status: DRAFT for approval by SLP Software - SLS - Main (on behalf of Bryan). Based on the package in `SlpSoftware/src/cms-client` (current version without captcha) and the existing ASF components. Details marked **[slot]** depend on the captcha slot that SLS-Main still builds.
## 1. Components and responsibilities
```mermaid
flowchart TD
CP[ContactPanel<br/>existing: packages, ?pakket=, lazy chunk] --> GATE[ContactFormGate<br/>existing: dimmed Binnenkort]
GATE -->|enabled=true| AV[ContactAvailability<br/>NEW: token fetch when in view]
AV -->|token ok and provider supported| CF[ContactForm<br/>ADAPTED: skin on useContactForm]
AV -->|anything else| GATE
CF --> HOOK[useContactForm<br/>cms-client]
CF --> CAP[CaptchaWidget<br/>NEW: client only, reserved height]
HOOK --> CLIENT[createContactClient<br/>cms-client]
CLIENT --> API[(/api/v1/contact-messages)]
classDef existing fill:#9ae6b4,stroke:#2f855a,color:#000;
classDef newc fill:#63b3ed,stroke:#2b6cb0,color:#000;
classDef pkg fill:#f6e05e,stroke:#c05621,color:#000;
class CP,GATE existing;
class AV,CAP newc;
class CF newc;
class HOOK,CLIENT pkg;
```
Text alternative: ContactPanel renders the gate; when enabled, ContactAvailability fetches the token and only then mounts the adapted ContactForm, which uses the package hook and, when needed, the captcha widget.
| Part | Change |
|---|---|
| `ContactPanel` | Keeps shoot options, `?pakket=` and the lazy chunk. Maps the chosen package id to its **label** and remembers the last preselect (FR-CF-08). Passes `enabled` through. |
| `ContactFormGate` | Unchanged look. Stays the initial render and the closed state. Its mail button keeps the `useEmailAddress` approach (no address in HTML before hydration). |
| `ContactAvailability` (new) | Only when `enabled`: waits until the form area is in view (IntersectionObserver, wide rootMargin; fallback first focus/pointer when IO is missing), then calls `client.getToken()` once. Exposes `{ state: 'idle' \| 'checking' \| 'open' \| 'closed', token, refreshToken }`. Renders children only in `open`. No request when `enabled=false`. |
| `ContactForm` | Keeps the Chakra skin, ids, test ids, thank-you and privacy note. State, validation, submit, idempotency and token refresh come from `useContactForm`. The old reducer, `validateContact`, `toContactPayload` and `submitContactForm` are deleted. |
| `CaptchaWidget` (new) | Renders the Friendly Captcha widget only when the token response says `captcha` with a supported provider. Client-only, after mount, in a reserved height. **[slot]** |
| `cms-client` | Copied unchanged into `web/src/cms-client/` (final version after SLS-Main's message). |
## 2. Availability state machine (ContactAvailability)
| From | Event | To | Note |
|---|---|---|---|
| idle | `enabled=false` | idle | no request, gate stays |
| idle | in view (or first focus without IO) and `enabled` | checking | one `getToken()` |
| checking | `ok` and (`captcha=null` or provider supported) | open | token kept in memory only |
| checking | `ok` and unsupported provider | closed | gate; no log of the provider value beyond a generic event |
| checking | `closed` (404) / `failed` / 429 / network | closed | gate; no retry loop (a later page view tries again) |
| open | submit reports `expired` | open | `refreshToken()` once (package) |
| closed | - | closed | terminal for this page view |
Prerender and first client render are always `idle` (the gate), so there is no hydration mismatch and no layout shift: the placeholder heights 649/547 px stay.
## 3. Field mapping and validation
| Visible field | Package field | Limit | Notes |
|---|---|---|---|
| Naam | `name` | 100 | `autoComplete="name"` |
| E-mail | `email` | 254 | `type=email`, `autoComplete="email"` |
| In welke shoot... | `subject` | 100 | **value = readable label**; options are `{ value: label, label }` from `shootOptions`; "Overig" is the fixed label for other |
| Stel hier je vraag | `message` | 2000 | |
- Validation and the Dutch messages come from the package (`required`, `tooLong`, `invalid`). Error texts of the old reducer are gone; where the package text differs from the old text, the package wins (SLS-Main and Bryan accepted: no forks).
- Trim is done by the package (`trimFields`). Maximum lengths also stay as `maxLength` on the inputs.
- `?pakket=` resolves to a package id (existing `packageFromSearch`) and then to that package's label before reaching the hook (`subject` is the label).
## 4. Submit flow (package)
1. Submit with errors: errors show per field, focus moves after the render to the first invalid field (inputs are disabled while sending).
2. Valid: `Idempotency-Key` per attempt series, honeypot `hpCheck` from the hook, token from availability, `captchaToken` **[slot]**.
3. `202`: thank-you (`Bedankt voor je bericht! Ik reageer binnen {replyTime}.`) takes focus; event `contact-sent`.
4. `400 expired`: one refresh and retry (package). Field errors map to fields.
5. 413 / 429 / 5xx / network: failure message from the package (429 with Retry-After in minutes); mail fallback text with the address assembled client-side after hydration; event `contact-failed`. The visitor can try again; the form keeps the typed values.
6. Spam (honeypot filled): silent success, no request (package).
Events go through the existing analytics wrapper with only `contact-sent` and `contact-failed`. No field values, token or idempotency key reach logs, Sentry or Umami.
## 5. Preselect (FR-CF-08)
`ContactPanel` keeps `{ subject: label, key }` from the first "Boek..." click, also before the form chunk has mounted, and `ContactForm` passes it to the hook as `initialSubject` (added to the package by SLP Software - SLS - Main together with the captcha slot) plus the `preselect` change counter for later clicks. The earlier key-bump workaround is dropped. Until the final package arrives, the code is written against `initialSubject` and tested with a fake of the hook.
## 6. Captcha **[slot]**
- Data: token response `captcha: { provider, siteKey }` or `null`.
- Supported: `friendlycaptcha` only. Anything else keeps the gate.
- Hook offers `setCaptchaToken(token|null)` and `captchaRequired`. The widget calls `setCaptchaToken` on solve, `setCaptchaToken(null)` and a reset on expiry or error.
- Decided by Bryan: Friendly Captcha v2 with the bundled npm package `@friendlycaptcha/sdk`. The CSP guide says the widget uses iframes, so `frame-src` is needed (see infrastructure design); no external script tag.
- SDK details verified against the current docs (developer.friendlycaptcha.com, v2):
- Package `@friendlycaptcha/sdk`; `FriendlyCaptchaSDK.createWidget({ element, sitekey, apiEndpoint, language, theme, startMode, formFieldName })`; `startMode` is `auto`, `focus` (default) or `none`; `apiEndpoint` accepts the shortcuts `"global"` (default) and `"eu"`; `formFieldName` default `frc-captcha-response`; `theme` `light | dark | auto`.
- Widget handle: `reset()`, `destroy()`, `getResponse()`, `start()`, `getState()`, `getElement()`.
- Events on the widget element: `frc:widget.complete` (`event.detail.response` is the token), `frc:widget.expire` (response `.EXPIRED`), `frc:widget.error` (response `.ERROR`, `detail.error.code`), `frc:widget.statechange`.
- We use the `response` of `complete` as `captchaToken` (not the form field), and set it to null on `expire`/`error`, then `reset()`.
- Choices for ASF: `startMode: "focus"` (starts when the visitor focuses the form), `language: "nl"`, `theme: "light"`, `apiEndpoint` from the host Bryan picks (`"eu"` recommended).
- Still to verify in Build and Test with a real browser: exact behaviour on `reset()` and the CSP entries marked "test".
- A missing token counts as spam on the server (still `202`), so the client blocks the submit with a clear message until the captcha is solved when `captchaRequired`; the client never relies on the server to tell the visitor.
- The widget code is a separate lazy chunk, loaded only in `open` with captcha required; reserved height; no script in prerendered HTML.
- Provider outage is fail-open on the server; the client never decides that.
## 7. Accessibility
Labels stay `Field.Label`; error text is outside the label (accessible name stays clean); `aria-invalid` and `aria-describedby` come from the hook; success and failure use `role="status"`/`role="alert"`; the honeypot stays off-screen, `aria-hidden`, `tabIndex=-1`, `autoComplete="off"`; focus order unchanged; axe tests stay part of the component tests.
## 8. Business rules (BR-CF)
- BR-CF-01 No token request unless `enabled` and the form is in view.
- BR-CF-02 The form is interactive only when the server said `200` and (captcha absent or supported).
- BR-CF-03 Subject sent is always the visible label, 1-100 characters.
- BR-CF-04 No personal data, token or idempotency key leaves the form except in the POST body.
- BR-CF-05 Prerendered HTML contains no token, widget or e-mail address.
- BR-CF-06 Failure never exposes technical text; the mail fallback is always offered.
- BR-CF-07 An expired captcha token is never sent.
## 9. Testability and PBT (partial)
- PBT-02/03 (round trip, invariants): `label -> payload.subject` (length 1-100 for all content labels; labels with & ' " < > survive the JSON round trip); `trimFields` idempotent.
- PBT-07/08/09: generators for form values shared in `src/test/arbitraries.ts`, shrinkable, seeds logged by the existing setup.
- Example-based tests: gate states, no request when disabled, unsupported captcha keeps gate, expired captcha token not sent, 429 text from the package, failure path without the address in HTML, preselect before mount.
- E2E (mocked `/api` route): token 200 -> form; 404 -> gate; submit 202; submit 400 expired -> retry; prerendered HTML check (no token/widget/address).
- Manual run against the temporary environment (192.168.1.2) with evidence.
## 10. Open items
1. Final package (captcha slot) and the exact captcha version/CSP: pending SLS-Main and CMS-U9.
2. Package text changes versus the old texts (small differences) are accepted unless Bryan objects to wording.
3. `initialSubject` arrives with the final package (SLS-Main).
4. Host (EU or global), exact versus wildcard `frame-src` and the plan needed for the EU endpoint: Bryan decides.
@@ -0,0 +1,64 @@
# Infrastructure design: contact-form (unit 1, web)
Status: DRAFT for approval by SLP Software - SLS - Main (on behalf of Bryan).
## 1. Request path
All calls are same-origin: `/api/v1/contact-messages/token` and `/api/v1/contact-messages`. The site is served by the CMS host (test now, ASF production on IIS later), which also serves `/api`; no CORS and no new origin for the API.
```mermaid
flowchart LR
B[Browser] -->|same origin /api/v1| H[ASF CMS host<br/>contact module]
H --> M[(MariaDB)]
H --> S[SMTP]
B -.captcha API.-> F[Friendly Captcha<br/>global.frcapi.com provisional]
classDef c fill:#f6e05e,stroke:#c05621,color:#000;
classDef s fill:#63b3ed,stroke:#2b6cb0,color:#000;
classDef x fill:#fbb6ce,stroke:#97266d,color:#000;
class B c;
class H,M,S s;
class F x;
```
Text alternative: the browser talks only to the ASF CMS host on the same origin, plus the captcha provider's API when a captcha is required.
## 2. Content Security Policy
Two places define the CSP and both must match:
- `web/config/securityHeaders.ts` (the prescription and the Vite dev/preview headers) - changed in this feature.
- The ASF CMS host's security header options (set by the CMS session `AndreaSlopFotografie`) - requested from them, not edited here.
Planned additions (provisional; Friendly Captcha v2 with the bundled `@friendlycaptcha/sdk`). The official CSP guide (developer.friendlycaptcha.com/docs/v2/guides/csp) says the widget uses iframes and needs at least `frame-src https://*.frcapi.com`; it names no other directive. Bryan decides exact origin versus wildcard and the host (EU recommended, `eu.frcapi.com`; the EU endpoint needs a Friendly Captcha Advanced or Enterprise plan, to be checked by Bryan). Everything marked "test" is added only if a real-browser test proves it necessary; no wildcards beyond what Bryan accepts.
| Directive | Now | Add |
|---|---|---|
| frame-src | not set (falls back to default-src) | the exact origin of the chosen host (`https://eu.frcapi.com` or `https://global.frcapi.com`), or `https://*.frcapi.com` if Bryan accepts the wildcard the docs name |
| connect-src | `'self'` + Umami + Sentry | test: the chosen host origin (the SDK fetches from its API endpoint) |
| script-src | `'self'` + Umami | nothing planned (SDK bundled, first-party chunk); test: `'wasm-unsafe-eval'` only if the SDK needs WebAssembly |
| worker-src | not set | test: `blob:` only if the SDK needs it |
Rules: add only what a real-browser test proves necessary (except the documented frame-src); each added entry gets a comment with the reason; the existing test `securityHeaders` gets assertions for the exact directives; no `unsafe-eval`, no wildcard hosts. The captcha script chunk is first-party, so `script-src 'self'` still holds.
## 3. Dev proxy
`vite.config.ts` `server.proxy`: `/api` to `http://192.168.1.2:5290` (the temporary environment) for local development, configurable through an env variable (default off in CI). Production and preview have no proxy. The dev CSP `connect-src` stays `'self' ws:` plus the above; the proxy keeps requests same-origin in the browser.
## 4. Build and delivery
- New code is in the lazy ContactForm chunk and a separate captcha chunk; pages without a form in view load no new JS (Lighthouse budgets in `lighthouserc.cjs` must stay green; a measurement is part of Build and Test).
- `web/src/cms-client/` is plain TypeScript/React inside the existing build. ESLint `no-restricted-imports` and the boundary test copy over with the package.
- `siteContent.contactForm.enabled` stays `false` in the merge; Bryan switches it on after the server is ready and he gives the explicit go.
- The CI pipeline is unchanged (unit, e2e, lint, Lighthouse); the CMS-check mode of deploy-test is unchanged.
## 5. Configuration and secrets
No secrets in the client. The captcha `siteKey` is public and arrives in the token response, so there is no new build-time variable. Server settings (`Contact__RecipientEmail`, `Contact:Enabled`, `MinSeconds`, retention, `ForwardedHeaders:KnownProxies`/`ClientPartitionKey`, `Email:AllowedFromAddresses`) belong to the CMS sessions and are requested through SLP Software - SLS - Main.
## 6. Observability
Events `contact-sent` and `contact-failed` through the existing analytics wrapper; nothing else, no field values, no tokens. Sentry captures unexpected exceptions without breadcrumbs from form fields (existing scrubbing configuration is checked in Build and Test).
## 7. Rollback and go-live
- Rollback: set `siteContent.contactForm.enabled = false` and redeploy; the gate returns and no token request is made. The server can also close the form (`Contact:Enabled` off gives 404, which keeps the gate).
- Go-live needs: server module deployed on the ASF host, recipient and sender configured, captcha configured (or off), Bryan's explicit go.
## 8. Dependencies on other sessions
| Item | Owner |
|---|---|
| Package captcha slot (branch and commit) | SLP Software - SLS - Main |
| Server contact module, captcha verifier, openapi for ASF | SLS Software - CMS |
| ASF host config (CSP options, recipient, proxies, Contact:Enabled) | AndreaSlopFotografie (via SLS-Main) |
| ASF test host with the endpoint | after Bryan merges the CMS branch (not requested yet) |
@@ -0,0 +1,31 @@
# Code generation plan: contact-form (unit 1, web)
Status: DRAFT for approval by SLP Software - SLS - Main (on behalf of Bryan). No code until approved. All paths under `web/` in the worktree `AndreaSlopFotografie-contact-form`, branch `feature/contact-form-cms`. Nothing is pushed or merged without Bryan.
Order matters: steps 1-2 can start with the current package (without captcha); the final package (captcha slot and `initialSubject`) is copied in step 9 after SLS-Main's message, and steps 10-12 need it.
## Steps
- [ ] **1. Copy the current package**: `src/cms-client/` (http/, contact/, README, tests, boundary test) copied unchanged from `SlpSoftware/src/cms-client` (read only). Add the ESLint `no-restricted-imports` rule for `src/cms-client/**`. Check: boundary test and the package's own tests pass in this repo.
- [ ] **2. Client factory**: `src/contact/contactClient.ts` creating `createContactClient` with same-origin base `/api/v1`; no logging of bodies.
- [ ] **3. Subject options by label**: `src/lib/shootOptions.ts` returns `{ value: label, label }` plus the id-to-label map for `?pakket=`; test that every content label is 1-100 characters and that `& ' " < >` survive the payload (PBT-02/03).
- [ ] **4. ContactAvailability**: new `src/components/ContactForm/ContactAvailability.tsx` with the state machine of the functional design (no request when disabled; IntersectionObserver with the `useInView` hook; first-focus fallback; `idle/checking/open/closed`; token in memory; `refreshToken`). Tests: no request when disabled, one request when in view, 404/429/5xx/network keep the gate, unsupported provider keeps the gate, first-focus fallback.
- [ ] **5. ContactPanel + Gate wiring**: Gate stays the initial render; Panel renders Availability inside Gate when `enabled`; Panel remembers the last preselect as `{ subject: label, key }`; placeholder heights unchanged. Tests: prerendered HTML has no token/widget/address; hydration test stays green.
- [ ] **6. ContactForm on `useContactForm`**: replace reducer, validation, 3 s check and submit prop; keep Chakra skin, ids, test ids, thank-you and PrivacyNote; error text outside the label; honeypot from `honeypotProps`; failure message from the package with address assembled after hydration (`useEmailAddress`); events `contact-sent`/`contact-failed` through the analytics wrapper. Tests: component tests incl. axe, field errors, focus after render, 429 text, failure path without address in HTML.
- [ ] **7. Remove dead code**: `src/lib/contactFormReducer.ts`, `validateContact.ts`, `toContactPayload.ts`, `isLikelySpam`, `src/contact/submitContactForm.ts` and `types.ts` (as far as unused), plus their tests; update `src/test/arbitraries.ts` (form generators) and references.
- [ ] **8. Dev proxy and CSP**: `vite.config.ts` `server.proxy` for `/api` (env-configurable, default off in CI); `config/securityHeaders.ts` additions per the infrastructure design (frame-src decided by Bryan; others only after the real-browser test) with reason comments; extend the `securityHeaders` tests.
- [ ] **9. Final package** (after SLS-Main's message): replace `src/cms-client/` by the final version (captcha slot, `initialSubject`); re-run boundary and package tests.
- [ ] **10. CaptchaWidget**: new lazy chunk `src/components/ContactForm/CaptchaWidget.tsx` using `@friendlycaptcha/sdk` (`createWidget`, `startMode: focus`, `language: nl`, `apiEndpoint` per Bryan's host choice); complete -> `setCaptchaToken(response)`; expire/error -> `setCaptchaToken(null)` and `reset()`; `destroy()` on unmount; reserved height; add the pinned dependency (check `minimumReleaseAge` rules of pnpm). Tests with a fake SDK: expired token not sent, error resets, unsupported or missing provider keeps the gate, submit blocked with message until solved.
- [ ] **11. Preselect with `initialSubject`**: Panel passes the remembered preselect to the form, the form to the hook; test "Boek..." before the form is mounted.
- [ ] **12. Privacy text**: PrivacyNote and the privacy page name the captcha provider and what the form stores (wording needs Bryan's approval; draft goes to SLS-Main for routing).
- [ ] **13. PBT and e2e**: fast-check properties (PBT-02/03/07/08/09) for the label/payload mapping and trim; e2e with a mocked `/api` route: token 200 -> form, 404 -> gate, 202 success, 400 expired -> retry, prerendered HTML check; extend `noJs` e2e (gate and mail button without JS).
- [ ] **14. Documentation**: update `LAYOUT.md` if the contact block changes; README note for the copied package (source and sync rule); `aidlc-docs` code summary.
- [ ] **15. Automatic build and test (Step 13.5)**: `pnpm` typecheck, lint, unit tests, e2e where available, build and prerender; fix and repeat; report any decision only Bryan can make.
## Not in this plan
- Server module, verifier, openapi, ASF host configuration (other sessions).
- Switching `siteContent.contactForm.enabled` to true, push, merge, deploy (Bryan).
- Real-browser CSP verification and manual run against the temporary environment: Build and Test stage.
## Traceability
FR-CF-01 -> 1, 9; FR-CF-02 -> 6, 7; FR-CF-03 -> 3, 6; FR-CF-04/05 -> 4, 5; FR-CF-06/07 -> 6; FR-CF-08 -> 5, 11; FR-CF-09 -> 10; FR-CF-10 -> 12; FR-CF-11 -> 8; FR-CF-12 -> 6; NFR-CF-01 -> 8, 10; NFR-CF-02 -> 4, 10 (lazy chunks); NFR-CF-03 -> 3, 4, 6, 10, 13.
@@ -0,0 +1,48 @@
# Execution plan: contact-form-cms
## Summary
Single unit of work (web only): connect the ASF contact form to the CMS contact module through the copied headless package, with Friendly Captcha, CSP and dev proxy. Server work and the package captcha slot are delivered by other sessions.
## Stages
| Stage | Decision | Reason |
|---|---|---|
| Workspace Detection | Done | Brownfield, Feature |
| Reverse Engineering | Skip | Team agreement |
| Requirements Analysis | Done (approved by SLS-Main for Bryan) | |
| User Stories | Skip | One persona (visitor); acceptance in requirements |
| Workflow Planning | This document | |
| Application Design | Skip | No new components; ContactForm, Gate and Panel are adapted. The package boundary is fixed by the package |
| Units Generation | Skip | One unit: `contact-form` |
| Functional Design | Execute | State machine of gate, availability, captcha and submit; field mapping; preselect; accessibility; error handling |
| NFR Requirements | Skip | Covered in the requirements (security, performance, testing); Security Baseline is enforced at each stage |
| NFR Design | Skip | Merged into functional and infrastructure design |
| Infrastructure Design | Execute | CSP directives (captcha), Vite dev proxy, deploy impact, pipeline, rollback |
| Code Generation | Execute | Plan first; approval before code (SLS-Main for Bryan; push and merge stay with Bryan) |
| Build and Test | Execute | Unit, component, PBT, e2e with mocks, manual run against the temporary environment, Lighthouse |
| Operations | Execute (included) | Deployment notes, monitoring (events only, no personal data), production readiness checklist; production stays off until Bryan's go |
## Sequence and dependencies
```mermaid
flowchart LR
RA[Requirements<br/>done] --> WP[Workflow Planning]
WP --> FD[Functional Design]
FD --> ID[Infrastructure Design]
ID --> CG[Code Generation<br/>plan then code]
CG --> BT[Build and Test]
BT --> OP[Operations]
PK[Package with captcha slot<br/>SLP Software - SLS - Main] -.final copy.-> CG
SV[Server verifier and ASF host<br/>SLS Software - CMS / AndreaSlopFotografie] -.real test.-> BT
classDef done fill:#9ae6b4,stroke:#2f855a,color:#000;
classDef todo fill:#63b3ed,stroke:#2b6cb0,color:#000;
classDef ext fill:#f6e05e,stroke:#c05621,color:#000;
class RA done;
class WP,FD,ID,CG,BT,OP todo;
class PK,SV ext;
```
Text alternative: requirements are done; planning, functional design, infrastructure design, code generation, build and test and operations follow in order; the package slot and the server work from other sessions feed code generation and the real test.
## Gates
- Design and plan approvals go to SLP Software - SLS - Main (acts for Bryan within the agreed frame).
- Push, merge, deploy, production and choices about design, text or privacy stay with Bryan.
- No code before the code generation plan is approved. The final package is copied only after SLS-Main's message.
@@ -0,0 +1,56 @@
# Requirements clarification: contact-form-cms
Questions were asked interactively in chat (project agreement); answers recorded here afterwards. Open follow-up questions are routed through the session "SLP Software - SLS - Main" (Bryan's instruction, 2026-11-10).
## Question 1: Security Baseline extension
- A) Yes, enforce
- B) No
[Answer]: A
## Question 2: Property-based testing extension
- A) Full
- B) Partial (pure functions and round-trips)
- C) No
[Answer]: B
## Question 3: Operations phase
- A) Yes, include now
- B) Decide later
- C) No
[Answer]: A
## Question 4: Relation between the cms-client package and the existing ASF form
- A) Package replaces state and validation; the existing ContactForm UI stays and uses useContactForm
- B) Package only for sending
[Answer]: A
## Question 5: Subject
- A) Select value (id) is the subject
- B) Free text
- X) Other
[Answer]: X - The human-readable label ("Newborn shoot", "Overig") is sent as `subject`; the id stays local for the ?pakket= preselect. (Decision by Bryan, relayed by SLP Software - SLS - Main)
## Question 6: Robot check
- A) None now
- B) Friendly Captcha now
- X) Other
[Answer]: B - Build Friendly Captcha now (Bryan via SLP Software - SLS - Main). Package gets a captcha slot (SLS-Main), server verifier by SLS Software - CMS, widget + CSP + privacy text by this feature.
## Question 7: Form unavailable
- A) Mailto block instead of "Binnenkort"
- B) Keep the dimmed "Binnenkort" view
- X) Other
[Answer]: B - Keep the existing dimmed "Binnenkort" gate (Bryan).
## Question 8: Testing against the server
- A) Mocks in CI + manual check against the temporary environment
- B) Mocks only
[Answer]: A
@@ -0,0 +1,44 @@
# Requirements: contact-form-cms
## Intent analysis
- **User request**: Build the own contact form for Andrea Slop Fotografie on the CMS contact module, using the headless `cms-client` package from the SlpSoftware repo (read only, copied here).
- **Request type**: New feature on existing code (brownfield). Replaces the "no back-end yet" stub from `contact-page`.
- **Scope**: Web repo only (components, content, CSP, dev proxy, tests, docs). Server work is requested from other sessions, not built here.
- **Complexity**: Moderate to complex: public endpoint with personal data, captcha, prerender/hydration constraints, cross-session contract.
- **Depth**: Standard, security-relevant. User Stories skipped (one persona: the visitor).
## Decisions (see requirement-verification-questions.md)
Security Baseline: enforced. PBT: partial (PBT-02, 03, 07, 08, 09). Operations: included. Package replaces the form's own state and validation. Subject is the readable label. Friendly Captcha built now. Gate stays the dimmed "Binnenkort" view. Tests: mocks in CI plus manual against the temporary environment.
## Functional requirements
- **FR-CF-01 Package**: Copy `src/cms-client/` (http/, contact/, README, boundary test) into `web/src/cms-client/`. It stays headless and imports nothing from the app (boundary test plus ESLint rule). The copy is kept in sync with the SlpSoftware original; no local forks of its logic.
- **FR-CF-02 Logic**: `useContactForm` drives the existing Chakra skin (fields, select, PrivacyNote, success state with `replyTime`). The old `contactFormReducer`, own validation and the `submitContactForm` stub are removed or reduced to a thin mapping.
- **FR-CF-03 Field mapping**: naam to name (max 100), email to email (254), shoot to subject (the readable label, 1-100, e.g. "Newborn shoot", "Overig"), bericht to message (2000). The package id stays local for the `?pakket=` preselect. Messages are the package's NL messages.
- **FR-CF-04 Availability (progressive enhancement)**: The prerendered/initial render is the gate ("Binnenkort"). After hydration and when the form scrolls into view (IntersectionObserver) the client calls `GET /api/v1/contact-messages/token`; only on `200` (and a captcha provider this site supports) does the form become active. Any other result (404 form closed, 429, 5xx, network, unsupported captcha) keeps the gate. `siteContent.contactForm.enabled` stays as an extra static kill switch (default false until Bryan's go). When it is `false`, the client makes NO token request at all (no network traffic, no server cost). The token is fetched lazily when the form comes into view (IntersectionObserver); first focus is only the fallback where IntersectionObserver is missing.
- **FR-CF-05 Layout stability**: No layout shift on upgrade; the existing placeholder heights stay valid. No token, widget or e-mail address in the prerendered HTML.
- **FR-CF-06 Submit**: `POST /api/v1/contact-messages` with `Idempotency-Key`, honeypot `hpCheck` (client side only the honeypot; the 3 s browser time check is dropped, the server enforces `minSeconds` through the token), one automatic token refresh on `errors.token = expired`, `202` means success. Server field errors map to the fields; focus moves after render (inputs are disabled while sending). Error messages are not placed inside `<label>`.
- **FR-CF-07 Failure**: 429, 5xx, 503 or network errors give a generic failure message with the mailto fallback; visitors never see technical text. The 429 message comes from the package (Retry-After in minutes), no own text. The mailto fallback after a failed send keeps the address out of the HTML (the `useEmailAddress` approach stays).
- **FR-CF-08 Preselect**: A package chosen via a "Boek..." link before the form has mounted is not lost: `ContactPanel` remembers the last preselect and passes it as initial value.
- **FR-CF-09 Captcha (Friendly Captcha)**: When the token endpoint returns `captcha = {provider, siteKey}`, the widget is shown client-only after hydration in a reserved height, its token goes to `captchaToken`, and it resets on expiry. The package provides the slot (SLP Software - SLS - Main), the server verifies (SLS Software - CMS); this feature builds the widget, loads it only when needed, and adds the CSP entries for the exact provider and version. Fail-open on a provider outage is a server decision already taken.
- **FR-CF-10 Privacy**: The privacy statement names the captcha provider and what the form stores. No personal data in logs, Sentry or Umami; only the events `contact-sent` and `contact-failed`.
- **FR-CF-11 Dev proxy**: Vite dev proxy for `/api` to the temporary environment (`http://192.168.1.2:5290`). Production is same-origin through the host/IIS proxy; no CORS.
- **FR-CF-12 Accessibility**: Labelled fields, focus handling for errors, live region for success/failure, honeypot hidden from assistive tech, keyboard operable, widget with reserved height.
## Non-functional requirements
- **NFR-CF-01 Security** (Security Baseline enforced): CSP `connect-src 'self'` plus captcha origins only (script/frame entries per provider and version, nothing wider); no secrets in the client (the siteKey is public); no personal data, tokens or idempotency keys logged; input limits identical to the server; honeypot and idempotency handled; dependency audit stays clean.
- **NFR-CF-02 Performance**: No new JS on pages without a form in view; the captcha script loads only when the form is active; Lighthouse budgets of `lighthouserc.cjs` stay green.
- **NFR-CF-03 Testing**: Unit and component tests for mapping, gate states, preselect and submit paths with a mocked API; fast-check on mapping/validation round-trips (PBT-02/03/07/08/09); e2e with a mocked `/api` route; manual verification against the temporary environment (CMS 192.168.1.2:5175, API :5290, smtp4dev :5301) with evidence in the construction docs. Tests of the old reducer are replaced. Extra cases: an unknown or missing captcha provider keeps the gate; an expired captcha token is never sent; every subject label is 1-100 characters and a label containing & ' " < > does not break the payload (mail encoding is server-side, the payload is tested here).
- **NFR-CF-04 Compatibility**: Works with hydration of the prerendered site (PR #14); no hydration mismatch; with JS off the gate and the mail button show.
- **NFR-CF-05 Operations**: CSP and dev-proxy changes deploy through the existing pipeline; production stays off (`enabled: false`) until Bryan's explicit go; rollback is switching `enabled` off; checklist in the Operations phase.
## Out of scope / asked of others
- Server module, captcha verifier, openapi (SLS Software - CMS); package captcha slot (SLP Software - SLS - Main).
- Per-site server config for ASF: `Contact__RecipientEmail` (env only), sender in `Email:AllowedFromAddresses`, `ForwardedHeaders:KnownProxies`/`ClientPartitionKey` on IIS, `Contact:Enabled`, `MinSeconds`, retention, CMS switch (session `AndreaSlopFotografie`, routed by SLP Software - SLS - Main).
- ASF production hosting (IIS) and the production go-live.
## Resolved with SLP Software - SLS - Main (approved on behalf of Bryan, 2026-11-10)
1. Lazy token fetch via IntersectionObserver (first focus only as fallback).
2. Friendly Captcha: provisionally v2 (bundled SDK, script-src 'self'; API origin https://global.frcapi.com in connect-src and possibly frame-src; possibly worker-src blob: and 'wasm-unsafe-eval'). Final directives per version come from CMS-U9 and a test in a real browser; no wildcards.
3. Labels come from the existing shoot options in content; the label of "Overig" is fixed per site.
4. Package captcha slot: the token response carries `captcha {provider, siteKey}` or null; the hook offers `setCaptchaToken(token|null)` and `captchaRequired`; an expired token means `setCaptchaToken(null)` and a widget reset. The final package is copied only after SLS-Main reports the branch and commit.
5. Server side for ASF is done by SLS Software - CMS (module, captcha) with AndreaSlopFotografie (host); an ASF test host with the endpoint exists only after the CMS branch is merged and deployed (not requested yet).
+17 -1
View File
@@ -59,7 +59,23 @@ export default defineConfig(({ mode }) => ({
tsconfigPaths: true,
},
// Dev: zelfde headers, met alleen de uitzonderingen die Vite nodig heeft
server: { headers: securityHeaders('development') },
server: {
headers: securityHeaders('development'),
// Alleen als API_PROXY_TARGET gezet is (bijv. http://192.168.1.2:5290):
// /api gaat dan via de dev-server naar die API, dus voor de browser
// same-origin, net als in productie (geen CORS, connect-src 'self').
// Zonder de variabele (ook in CI) is er geen proxy.
...(process.env.API_PROXY_TARGET
? {
proxy: {
'/api': {
target: process.env.API_PROXY_TARGET,
changeOrigin: true,
},
},
}
: {}),
},
// Preview: de strenge productieset
preview: { headers: securityHeaders('production') },
test: {