Files
AndreaSlopFotografie/aidlc-docs/features/contact-form-cms/construction/plans/contact-form-code-generation-plan.md
T
SluijsensandClaude Sonnet 5.5 4da314c0ba 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>
2026-11-10 23:04:16 +01:00

5.2 KiB

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.