Headless pakket src/cms-client met importgrens, formulier dat pas verschijnt als de API antwoordt (anders blijft de mailto-knop), honeypot, idempotentie, token-vernieuwing en property-based tests. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
6.5 KiB
6.5 KiB
Code Generation Plan — contact-form (U4)
Single source of truth for U4 Code Generation. Inputs: Functional Design (BR-U4-1..16), NFR Requirements/Design, Infrastructure Design, contract v0.3.x + CMS phase-1 handoff, application-design/component-methods.md, U2/U3 results.
Unit context
- Workspace root
K:\Development\SlpSoftware\Projects\SlpSoftware, branchfeature/redesign-modern-timetravel; modify in place; one commit; no push. - Dependencies: U1–U3 (done), contract. The CMS routes exist on the unmerged CMS branch only; everything here is built and tested against a mocked
fetchthat follows the contract. The live API answers 404 for the contact routes (not part of the production release) so the site keeps the mailto panel until the CMS side is released and switched on. - Not in U3/U4 scope: E skin (U5), CMS changes, nginx/CSP changes (Operations list).
Files (M modify, C create)
- C
src/cms-client/http/{apiUrl.ts,problem.ts,fetchJson.ts}(API base, problem+json parsing,ApiError, 10 s timeout) - C
src/cms-client/contact/{types.ts,validateContact.ts,contactFormReducer.ts,mapApiErrors.ts,messages.nl.ts,createContactClient.ts,useContactForm.ts,index.ts}; Csrc/cms-client/README.md(boundary and future package notes) - C
src/features/landing/components/{ContactPanel.tsx,MailtoPanel.tsx,ContactFormView.tsx,Honeypot.tsx}, Csrc/features/landing/hooks/useContactAvailability.ts, Csrc/shared/analytics/trackEvent.ts(Umamiwindow.umami?.track, no data) - M
src/features/landing/components/ContactSection.tsx(useContactPanel),src/features/landing/data/content.ts(form texts, privacy sentence, mail parts),eslint.config.js(boundary rule),package.json+pnpm-lock.yaml(dev dependencyfast-check) - C tests:
src/cms-client/contact/__tests__/{validateContact.test.ts,validateContact.property.test.ts,contactFormReducer.test.ts,contactFormReducer.property.test.ts,mapApiErrors.test.ts,createContactClient.test.ts,serialization.property.test.ts},src/cms-client/__tests__/boundary.test.ts,src/features/landing/__tests__/ContactForm.test.tsx,src/features/landing/__tests__/ContactAvailability.test.tsx; MSections.test.tsx(contact frame test) - Docs:
construction/contact-form/code/summary.md
Steps
- Step 1 — Dependency and boundary: add
fast-check(dev) respecting the release-age policy (stop and report if blocked); ESLintno-restricted-importsforsrc/cms-client/**forbidding../../features,../../components,../../shared,../../theme,../../utilsetc.; boundary test (lint rule via ESLint API or file-scan assertion thatsrc/cms-clientimports only inside itself andreact). - Step 2 — http layer:
apiUrl(VITE_API_BASE_URL ?? ''),fetchJsonwithAbortControllertimeout 10 s returning{status, headers, body}or throwingApiError('network' | 'timeout'),parseProblem(problem+json to{status, errors, retryAfter}). - Step 3 — Pure contact core:
types.ts,validateContact(trim, boundaries, control characters, email regex; first failing rule wins),contactFormReducer(events change/blur/submit/sending/succeeded/failed/fieldErrors/reset/preselect; invariants of BR-U4-5),mapApiErrors,retryAfterMinutes,messages.nl(field/code messages equal to the ASF texts, rate-limit/413/failure texts with{minutes}and{address}placeholders). - Step 4 — Client:
createContactClient({ baseUrl?, fetch? })withgetToken()(200 →{token, minSeconds, captcha}; 404/other → typed resultclosed) andsubmit(payload, { token, idempotencyKey })(202 → ok; 400/413/429/5xx/network → typed results; one automatic token refresh onexpiredis orchestrated by the hook). - Step 5 — Hook:
useContactForm({ idPrefix, subjectOptions, preselect, client, messages, fallbackAddress, onEvent })returning values, shown errors, status,getFieldProps,honeypotprops,formProps(noValidate,onSubmit),retry,reset,focusFirstError; idempotency key per attempt series (crypto.randomUUIDwith fallback); honeypot silent success; single token refresh; analytics viaonEventonly (sent/failed). - Step 6 — Availability + UI:
useContactAvailability(ref)(IntersectionObserver, fallback first focus; fetches token once;unknown | open | closed;captcha != null⇒closed),ContactPanel(min height, switches betweenMailtoPanelandContactFormView),ContactFormView(B skin: panel colours, underline inputs onbg-field, brand submit button, field errors, honeypot, privacy sentence, failurerole=alertwith mail address, successrole=statuswith focus and "Nog een bericht sturen"),Honeypot,trackEvent; subject options fromusePackagesQuery(+ "Overig"); preselect fromuseContactPreselect;ContactSectionusesContactPanel; mail address assembled after mount. - Step 7 — Tests: the seven acceptance tests of
frontend-components.md(validation tables + properties with fast-check; reducer invariants as properties; serialization round trips; client against a contract-following mockedfetch; hook/UI flows: success, honeypot, 400 mapping, token refresh once, 413, 429 minutes, 5xx/network keep input, retry same key, reset new key; availability 200/404/500/network/captcha, no request before the section nears the viewport; preselect; accessibility; no PII in console/Sentry/Umami spies; boundary). - Step 8 — Build and test (automatic, Step 13.5):
pnpm lint,pnpm test,pnpm build; fix and retry until green; report real counts. - Step 9 — Docs and commit:
construction/contact-form/code/summary.md(files, behaviour, how to enable end-to-end once the CMS is released, privacy/telemetry notes, move-to-package notes); one commit (Dutch message,Co-Authored-By), no push.
Explicitly NOT touched
Hero/nav/about/process/packages markup (U2/U3), theme code (U1), src/variants/e, CMS repos, nginx or CSP files.
Risks
- No end-to-end test against the real API is possible until the CMS branch is merged and released with both switches on; contract tests with a mocked
fetchcover the shapes (checked againstopenapi/slpsoftware.v1.jsonfield by field by reading it). - jsdom has no
IntersectionObserver: the hook falls back to first focus; tests install a controllable fake. fast-checkcould be blocked by the release-age policy: report instead of bypassing.
Traceability
FR-13..FR-19 (B part), NFR-4, NFR-5, NFR-6; BR-U4-1..16; NFR-U4-1..9; Security Baseline (see NFR Requirements).