Files
AndreaSlopFotografie/aidlc-docs/features/homepage-sections/construction/plans/contact-code-generation-plan.md
SluijsensandClaude Opus 5.5 0fce403ebc Adds the Contact section to the homepage
Adds the contact form with the live fields, validation and browser-side
anti-spam, behind a coming-soon notice with a mail button until the API
exists. A "Boek" link on a price card selects its package, tidies the
URL and moves focus to the form. The form loads only when it comes near
the screen, so the hero does not wait for it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-21 00:36:43 +02:00

6.7 KiB
Raw Permalink Blame History

Code Generation Plan — Unit 5: Contact

This plan is the single source of truth for Code Generation of unit 5.

Unit context

  • Requirements: FR-HP-06, FR-HP-07, FR-HP-08, FR-HP-09, NFR-HP-01/02/03/04/05/06
  • Functional design: contact/functional-design/ — BR-FORM-01…13, BR-SEND-01…04, BR-SPAM-01…03, BR-GATE-01…03, BR-MAIL-01, BR-PARAM-02/04, BR-FOCUS-01
  • Depends on: unit 1 (HomeSection, SectionHeading, Reveal), unit 3 (packages, visiblePackages, packageFromSearch, pakket search), existing emailAddress, linkButton and link recipes
  • PBT: full — all pure helpers plus a stateful test of the form reducer (PBT-06)
  • Conventions as in units 1–4.

Steps

Types and content

  • Step 1 — src/contact/types.ts: ContactField, ContactValues, ContactErrors, ContactPayload, ShootOption, CONTACT_LIMITS (naam 100, email 254, bericht 2000). content/types.ts: HomeContent.contact { title; lead }, SiteContent.contactForm { enabled }. Content: homeContent.contact, siteContent.contactForm = { enabled: false }.

Pure helpers (src/lib/, each with example and property tests)

  • Step 2 — shootOptions.ts: shown packages (visiblePackages) + Overig.
  • Step 3 — validateContact.ts: validateField and validateContact with the exact messages of BR-FORM-01…07.
  • Step 4 — toContactPayload.ts: trimmed payload.
  • Step 5 — isLikelySpam.ts: honeypot or under MIN_FILL_MS = 3000.
  • Step 6 — mailLink.ts: mailSubject(packageName?), mailtoLink(address, subject).
  • Step 7 — contactFormReducer.ts: state { status, values, touched, errors }, events edit, blur, preselect, submit, resolved, rejected (BR-FORM-10…12, BR-SEND-01…04, BR-SPAM-02). Stateful property test with random event sequences checking the invariants of business-logic-model.md.
  • Step 8 — test/arbitraries.ts: contactValues (valid), anyContactValues, contactEvent.

Adapter

  • Step 9 — src/contact/submitContactForm.ts (+ test): async (payload) => { throw new Error(...) } today, with a comment pointing to POST /api/contact and the captcha token; generic, no details shown to visitors.

Styling

  • Step 10 — recipes/formControl.ts: the design's square fields (white, line border, 0.95 × 1.1 rem padding, weight 300, accent border + soft ring on focus, error border with sufficient contrast), applied to Input, Textarea and NativeSelect.Field; register in theme.ts. Add a panel shadow token (design --shadow-md) for the notice; error colour token if needed (≥ 4.5:1 on paper).

Components

  • Step 11 — components/ContactForm/ContactForm.tsx: reducer, shownAt, Chakra Field per field (labels in the eyebrow style, ink.soft), name + e-mail side by side from sm, select with placeholder, textarea, honeypot, empty data-robot-check slot, failure status (role="alert", mail link), submit button (accent linkButton style, "Versturen…" while sending), thank-you replacing the form (role="status", focused); preselect prop applied on change of its key; injectable submit.
  • Step 12 — components/ContactForm/ContactFormGate.tsx: off → dimmed, inert wrapper + notice (eyebrow, text with underline mail link, "Stuur een e-mail" button), text only when the address is invalid; on → children.
  • Step 13 — components/home/ContactSection/ContactSection.tsx: HomeSection id="contact" width="narrow", heading (tabIndex={-1}) and lead, gate + form; resolves pakket, preselects, removes it from the URL (navigate replace, keep #contact, no scroll reset) and focuses the heading (BR-PARAM-02, BR-FOCUS-01).
  • Step 14 — Tests: ContactForm.test.tsx (labels; blur shows errors only after typing; messages per rule; submit focuses first invalid; errors clear while typing; spam → thank-you, submit not called; success → thank-you focused; failure → alert with mail link, values kept; double submit ignored; preselect; axe), ContactFormGate.test.tsx (inert form, notice, mailto with subject, invalid address → text only, enabled → form only, axe both), ContactSection.test.tsx (preselect from pakket, URL cleaned with replace, heading focused, unknown value ignored and cleaned, no focus move without pakket).

Route

  • Step 15 — routes/index.tsx: render ContactSection after Testimonials with homeContent.contact, packages, siteContent.contactForm.enabled, siteContent.email and pakket from Route.useSearch().
  • Step 16 — app.test.tsx: "Contact" in the page order; /?pakket=newborn → shoot "Newborn" selected, URL without pakket, focus on the Contact heading.

Verification and wrap-up

  • Step 17 — pnpm check; Lighthouse home mobile compared with a 5-run median against the unit 4 build. If the form code costs measurable performance (as the carousel did), load the form (not the heading and notice) when the section comes near the screen, as in unit 4. Visual check at 1440 / 390 (gate on), and with the gate switched on locally for one screenshot of the working form.
  • Step 18 — construction/contact/code/code-summary.md.
  • Step 19 — Commit ("Adds the Contact section to the homepage" + attribution). Not pushed.

Fixes during Step 17

  • Step 17a — Lighthouse median 0.83 → 0.80: the form moved to its own chunk, loaded when the section is within 200 px of the screen or at once via "Boek …", and stays once loaded; placeholder of the measured height.
  • Step 17b — Remaining 0.81: a new shared chunk (Chakra's slot-recipe factory) was fetched by the route on load. PriceCard's List and TestimonialSlide's Blockquote replaced by plain elements with the same styling; median back to 0.83.

Requirement / rule traceability

Item Steps
FR-HP-06 / BR-FORM-* 1–3, 7, 10, 11, 14
FR-HP-07 / BR-GATE-* 1, 12, 14
FR-HP-08 / BR-SPAM-* 5, 7, 11, 14
FR-HP-09 11 (slot)
BR-SEND-* 4, 7, 9, 11, 14
BR-MAIL-01 6, 11, 12, 14
BR-PARAM-02/04, BR-FOCUS-01 13, 14, 16
NFR-HP-05 17

Extension compliance (planned)

  • Security: client-side limits/format checks (server-side in the API feature, SECURITY-05); misuse covered by gate + honeypot + time check (SECURITY-11); generic failure text (SECURITY-15); e-mail never literal in HTML or bundle; no new dependencies or external resources; CSP unchanged.
  • PBT: PBT-02 (mailto round-trip), PBT-03 (validation invariants), PBT-04 (payload idempotency), PBT-05 (spam and e-mail oracles), PBT-06 (reducer state machine), PBT-07 (generators), PBT-08/09 (existing), PBT-10 (example tests).