Files
SlpSoftware/aidlc-docs/features/redesign-modern-timetravel/construction/contact-form/functional-design/business-rules.md
T

6.4 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 1 jaar." (changed from "12 maanden" on Bryan's request, 2026-11-11) (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.