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>
8.0 KiB
8.0 KiB
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-clientpackage 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) intoweb/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:
useContactFormdrives the existing Chakra skin (fields, select, PrivacyNote, success state withreplyTime). The oldcontactFormReducer, own validation and thesubmitContactFormstub 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 on200(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.enabledstays as an extra static kill switch (default false until Bryan's go). When it isfalse, 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-messageswithIdempotency-Key, honeypothpCheck(client side only the honeypot; the 3 s browser time check is dropped, the server enforcesminSecondsthrough the token), one automatic token refresh onerrors.token = expired,202means 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
useEmailAddressapproach stays). - FR-CF-08 Preselect: A package chosen via a "Boek..." link before the form has mounted is not lost:
ContactPanelremembers 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 tocaptchaToken, 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-sentandcontact-failed. - FR-CF-11 Dev proxy: Vite dev proxy for
/apito 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.cjsstay 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
/apiroute; 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 switchingenabledoff; 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 inEmail:AllowedFromAddresses,ForwardedHeaders:KnownProxies/ClientPartitionKeyon IIS,Contact:Enabled,MinSeconds, retention, CMS switch (sessionAndreaSlopFotografie, 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)
- Lazy token fetch via IntersectionObserver (first focus only as fallback).
- 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.
- Labels come from the existing shoot options in content; the label of "Overig" is fixed per site.
- Package captcha slot: the token response carries
captcha {provider, siteKey}or null; the hook offerssetCaptchaToken(token|null)andcaptchaRequired; an expired token meanssetCaptchaToken(null)and a widget reset. The final package is copied only after SLS-Main reports the branch and commit. - 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).