Files
SlpSoftware/aidlc-docs/features/redesign-modern-timetravel/construction/plans/contact-form-code-generation-plan.md
T
SluijsensandClaude Sonnet 5.5 aa843a5675 Contactformulier: cms-client (validatie, reducer, client, hook), formulier in stijl B en beschikbaarheid
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>
2026-11-10 13:13:24 +01:00

6.5 KiB
Raw Blame History

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, branch feature/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 fetch that 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}; C src/cms-client/README.md (boundary and future package notes)
  • C src/features/landing/components/{ContactPanel.tsx,MailtoPanel.tsx,ContactFormView.tsx,Honeypot.tsx}, C src/features/landing/hooks/useContactAvailability.ts, C src/shared/analytics/trackEvent.ts (Umami window.umami?.track, no data)
  • M src/features/landing/components/ContactSection.tsx (use ContactPanel), src/features/landing/data/content.ts (form texts, privacy sentence, mail parts), eslint.config.js (boundary rule), package.json + pnpm-lock.yaml (dev dependency fast-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; M Sections.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); ESLint no-restricted-imports for src/cms-client/** forbidding ../../features, ../../components, ../../shared, ../../theme, ../../utils etc.; boundary test (lint rule via ESLint API or file-scan assertion that src/cms-client imports only inside itself and react).
  • Step 2 — http layer: apiUrl (VITE_API_BASE_URL ?? ''), fetchJson with AbortController timeout 10 s returning {status, headers, body} or throwing ApiError('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? }) with getToken() (200 → {token, minSeconds, captcha}; 404/other → typed result closed) and submit(payload, { token, idempotencyKey }) (202 → ok; 400/413/429/5xx/network → typed results; one automatic token refresh on expired is orchestrated by the hook).
  • Step 5 — Hook: useContactForm({ idPrefix, subjectOptions, preselect, client, messages, fallbackAddress, onEvent }) returning values, shown errors, status, getFieldProps, honeypot props, formProps (noValidate, onSubmit), retry, reset, focusFirstError; idempotency key per attempt series (crypto.randomUUID with fallback); honeypot silent success; single token refresh; analytics via onEvent only (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 between MailtoPanel and ContactFormView), ContactFormView (B skin: panel colours, underline inputs on bg-field, brand submit button, field errors, honeypot, privacy sentence, failure role=alert with mail address, success role=status with focus and "Nog een bericht sturen"), Honeypot, trackEvent; subject options from usePackagesQuery (+ "Overig"); preselect from useContactPreselect; ContactSection uses ContactPanel; 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 mocked fetch; 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 fetch cover the shapes (checked against openapi/slpsoftware.v1.json field by field by reading it).
  • jsdom has no IntersectionObserver: the hook falls back to first focus; tests install a controllable fake.
  • fast-check could 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).