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.3 KiB
6.3 KiB
Business Rules — contact-form (U4)
| Id | Rule |
|---|---|
| BR-U4-1 | Fixed fields: name, email, subject, message, all required (no builder, no phone, no "aanvraag/vraag" switch). |
| BR-U4-2 | Progressive enhancement: the contact panel starts as the mailto call-to-action (as in U2). When the contact section comes near the viewport the client fetches the token (GET /api/v1/contact-messages/token). 200 and no captcha → the panel switches to the form; 404, any other status, network error, or captcha != null (no widget implemented in this repo) → the mailto panel stays. There is no build-time flag: the server (host switch + CMS switch) decides. |
| BR-U4-3 | Token: one token per page view, fetched once when the section nears the viewport (IntersectionObserver with fallback to the first focus where unavailable); not on page load, not in static HTML. On errors.token = ["expired"] one fresh token is fetched and the submit is repeated once automatically; a second failure shows the generic failure message. |
| BR-U4-4 | Validation is the same pure function on the client and (by contract) on the server: first failing rule per field wins (required, then length, then format). Errors appear on blur of a touched field or on submit and disappear as soon as the field is valid; on a stopped submit the focus moves to the first invalid field. The form uses noValidate and shows its own messages. |
| BR-U4-5 | States: `editing → sending → sent |
| BR-U4-6 | Idempotency: one UUID per attempt series, reused when the visitor retries after failed until success, renewed after success/reset. Sent as Idempotency-Key. |
| BR-U4-7 | Honeypot: a visually hidden field (off-screen, aria-hidden, tabindex=-1, autocomplete=off, implausible DOM name) sent as hpCheck. If it is filled the client does not call the API but shows the normal success state (silent drop); the server repeats the check. The server-signed token replaces any client time check (no Date.now needed). |
| BR-U4-8 | Responses: 202 → success state. 400 with errors → map codes to messages per field (and token as above); unknown codes → generic failure. 413 → "Je bericht is te groot." 429 → message with the minutes from Retry-After (rounded up, min 1). 404/5xx/network → generic failure with the mailto fallback address. No automatic retry other than the token case. |
| BR-U4-9 | Preselect: when the contact preselect key changes (package CTA from U3), the subject is set to its subject if that value exists in the subject options; unknown values are ignored. A later manual choice stays until the next click (key change). |
| BR-U4-10 | Mailto fallback: the address is assembled in the browser after mount from contactInfo parts, not as a literal in prerendered HTML (the site is a SPA, so this is defence in depth); the existing mailto button and the visible address of the section stay. |
| BR-U4-11 | Subject options: the packages from the offerings query (value = slug, label = title, in API order, banner packages included) plus "Overig" (other); first option is a disabled placeholder "Kies een onderwerp". While offerings load or fail, only "Overig" is available. |
| BR-U4-12 | Privacy: below the submit button the sentence "Je gegevens gebruik ik alleen om op je bericht te reageren; ik bewaar ze maximaal 12 maanden." (no checkbox, no link). |
| BR-U4-13 | Success: the form is replaced by "Bedankt!" with "Je bericht is verstuurd. Je hoort binnen één werkdag van me." (role=status, focus moves to it) and a button "Nog een bericht sturen" that resets to an empty form with a new idempotency key. |
| BR-U4-14 | Privacy of telemetry: no field values or the API token/idempotency key are logged, sent to Sentry (breadcrumbs, extra context) or Umami; the only analytics events are contact-sent and contact-failed without data. Errors reported to Sentry carry no request/response bodies. |
| BR-U4-15 | Accessibility: real <label>s, errors linked with aria-describedby and aria-invalid, role=alert on the failure message, role=status + focus on success, visible focus, touch targets ≥ 44px, no animation dependency, honeypot invisible to assistive technology. |
| BR-U4-16 | Headless boundary: all logic (reducer, validation, hook, client) lives in src/cms-client/ without imports from the app; the B skin (markup/classes) lives in the landing feature. Texts are injectable with Dutch defaults. |
Decision flow: availability
graph TD
S([Contact section near viewport]) --> T[GET token]
T --> R{Status 200}
R -->|"no"| M[Keep mailto panel]
R -->|"yes"| C{Captcha required}
C -->|"yes"| M
C -->|"no"| F[Show form]
classDef start fill:#CE93D8,stroke:#6A1B9A,color:#000;
classDef decision fill:#FFF59D,stroke:#F57F17,color:#000;
classDef step fill:#63b3ed,stroke:#2b6cb0,color:#000;
class S start;
class R,C decision;
class T,M,F step;
Text alternative: when the section nears the viewport the token is requested; only a 200 without captcha shows the form, otherwise the mailto panel stays.
Decision flow: submit
graph TD
A([Submit]) --> B{Sending already}
B -->|"yes"| X[Ignore]
B -->|"no"| V{Valid}
V -->|"no"| E[Show errors and focus first]
V -->|"yes"| H{Honeypot filled}
H -->|"yes"| OK[Show success without call]
H -->|"no"| P[POST with idempotency key]
P --> S{Result}
S -->|"202"| OK
S -->|"token expired"| T[Fetch token and repeat once]
S -->|"400 fields"| E
S -->|"429 or other"| FL[Failed with message and mailto]
classDef start fill:#CE93D8,stroke:#6A1B9A,color:#000;
classDef decision fill:#FFF59D,stroke:#F57F17,color:#000;
classDef step fill:#63b3ed,stroke:#2b6cb0,color:#000;
classDef bad fill:#ffab91,stroke:#bf360c,color:#000;
class A start;
class B,V,H,S decision;
class X,E,P,T,OK step;
class FL bad;
Text alternative: a submit is ignored while sending, validated, dropped silently if the honeypot is filled, otherwise posted; success, an expired token (one retry), field errors or a failure result.