Files
AndreaSlopFotografie/aidlc-docs/features/homepage-sections/construction/plans/contact-code-generation-plan.md
T
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

66 lines
6.7 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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/](../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
- [x] **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)
- [x] **Step 2** — `shootOptions.ts`: shown packages (`visiblePackages`) + Overig.
- [x] **Step 3** — `validateContact.ts`: `validateField` and `validateContact` with the exact messages of BR-FORM-01…07.
- [x] **Step 4** — `toContactPayload.ts`: trimmed payload.
- [x] **Step 5** — `isLikelySpam.ts`: honeypot or under `MIN_FILL_MS = 3000`.
- [x] **Step 6** — `mailLink.ts`: `mailSubject(packageName?)`, `mailtoLink(address, subject)`.
- [x] **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.
- [x] **Step 8** — `test/arbitraries.ts`: `contactValues` (valid), `anyContactValues`, `contactEvent`.
### Adapter
- [x] **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
- [x] **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
- [x] **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`.
- [x] **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.
- [x] **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).
- [x] **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
- [x] **Step 15** — `routes/index.tsx`: render `ContactSection` after `Testimonials` with `homeContent.contact`, `packages`, `siteContent.contactForm.enabled`, `siteContent.email` and `pakket` from `Route.useSearch()`.
- [x] **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
- [x] **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.
- [x] **Step 18** — `construction/contact/code/code-summary.md`.
- [x] **Step 19** — Commit ("Adds the Contact section to the homepage" + attribution). Not pushed.
### Fixes during Step 17
- [x] **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.
- [x] **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).