From 4da314c0ba3f209d42a9bce67710876c6e875feb Mon Sep 17 00:00:00 2001 From: Sluijsens Date: Tue, 10 Nov 2026 23:04:16 +0100 Subject: [PATCH] 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 --- aidlc-docs/active-features.md | 1 + .../features/contact-form-cms/aidlc-state.md | 55 +++++++++ aidlc-docs/features/contact-form-cms/audit.md | 59 +++++++++ .../functional-design/functional-design.md | 115 ++++++++++++++++++ .../infrastructure-design.md | 64 ++++++++++ .../contact-form-code-generation-plan.md | 31 +++++ .../inception/plans/execution-plan.md | 48 ++++++++ .../requirement-verification-questions.md | 56 +++++++++ .../inception/requirements/requirements.md | 44 +++++++ web/vite.config.ts | 18 ++- 10 files changed, 490 insertions(+), 1 deletion(-) create mode 100644 aidlc-docs/features/contact-form-cms/aidlc-state.md create mode 100644 aidlc-docs/features/contact-form-cms/audit.md create mode 100644 aidlc-docs/features/contact-form-cms/construction/contact-form/functional-design/functional-design.md create mode 100644 aidlc-docs/features/contact-form-cms/construction/contact-form/infrastructure-design/infrastructure-design.md create mode 100644 aidlc-docs/features/contact-form-cms/construction/plans/contact-form-code-generation-plan.md create mode 100644 aidlc-docs/features/contact-form-cms/inception/plans/execution-plan.md create mode 100644 aidlc-docs/features/contact-form-cms/inception/requirements/requirement-verification-questions.md create mode 100644 aidlc-docs/features/contact-form-cms/inception/requirements/requirements.md diff --git a/aidlc-docs/active-features.md b/aidlc-docs/active-features.md index 291c7d7..8f123ea 100644 --- a/aidlc-docs/active-features.md +++ b/aidlc-docs/active-features.md @@ -13,3 +13,4 @@ | Feature | prerendering | ✅ Complete (merged, PR #14) | feature/prerendering (worktree ../AndreaSlopFotografie-prerendering) | web/vite.config.ts, web/src/main.tsx, web/index.html, web/config/serverConfig.ts + web/deploy, CI workflow, web/lighthouserc.cjs, possibly Reveal/useReveal and hooks using media queries | 2026-10-31 | | Feature | testimonials-redesign | ✅ Complete (merged, PR #16) | feature/testimonials-redesign (worktree ../AndreaSlopFotografie-testimonials-redesign) | web/src/components/home/Testimonials (Testimonials, TestimonialSlide, TestimonialCarousel), web/src/recipes/carouselControl.ts, web/src/content (Testimonial type, testimonials.ts), possibly SectionHeading, LAYOUT.md, unit/e2e tests that reference the dots | 2026-11-05 | | Feature | cms-api-foundation | ✅ Complete (merged PR #17, 2026-11-10; follow-ups: ASF production, contact feature) | feature/cms-api-foundation (worktree ../AndreaSlopFotografie-cms-api-foundation) | Cross-repo: feature briefs for the SlpModularCms repo (new Api.AndreaSlopFotografie client, per-site theming, per-site module set); in this repo only docs, later web integration (CMS serves the site) | 2026-11-05 | +| Feature | contact-form-cms | 🔵 Inception | feature/contact-form-cms (worktree ../AndreaSlopFotografie-contact-form) | web/src/components/ContactForm, ContactFormGate, web/src/contact (submitContactForm), new web/src/cms-client (copied headless package), web/config/securityHeaders.ts, content/siteContent contactForm switch | 2026-11-10 | diff --git a/aidlc-docs/features/contact-form-cms/aidlc-state.md b/aidlc-docs/features/contact-form-cms/aidlc-state.md new file mode 100644 index 0000000..20d92d2 --- /dev/null +++ b/aidlc-docs/features/contact-form-cms/aidlc-state.md @@ -0,0 +1,55 @@ +# AI-DLC State Tracking + +## Project Information +- **Feature Name**: Contact form on the CMS API (ASF contact form talks to the SlpModularCms contact module, using the headless cms-client package) +- **Feature Slug**: contact-form-cms +- **Project Type**: Brownfield +- **Start Date**: 2026-11-10T21:42:54Z +- **Current Stage**: INCEPTION - Workflow Planning (awaiting approval) +- **Branch**: feature/contact-form-cms (from master 7d594ff) +- **Worktree**: K:\Development\SlpSoftware\Projects\AndreaSlopFotografie-contact-form + +## Workspace State +- **Existing Code**: Yes (web/src has ContactForm, ContactFormGate, submitContactForm stub, contactFormReducer) +- **Reverse Engineering Needed**: No (team agreement: no full RE refresh per feature) +- **Workspace Root**: K:\Development\SlpSoftware\Projects\AndreaSlopFotografie-contact-form + +## Code Location Rules +- **Application Code**: Workspace root, web code in web/ (NEVER in aidlc-docs/) +- **Feature Documentation**: aidlc-docs/features/contact-form-cms/ only +- **Shared Artifacts**: aidlc-docs/_shared/ +- **Server side**: lives in the SlpModularCms repo (branch feature/contact-forms-module, session "SLS Software - CMS"); NOT built from this session, only asked for + +## Language Configuration +- **Documentation Language**: English +- **Conversation Language**: User Language (Dutch) +- **Source**: inherited from aidlc-docs/language-preference.md (answer A) + +## Cross-session coordination +- Source package (read only): SlpSoftware repo, src/cms-client/ (branch feature/redesign-modern-timetravel), coordinated by session "SLP Software - SLS - Main" +- Server contract: contact-api-contract.md (v0.3.x) in the SlpSoftware repo +- Milestones (plan ready, built) are reported to "SLP Software - SLS - Main" +- Nothing is pushed, merged or deployed without Bryan; the form stays off in production until Bryan's explicit go + +## Extension Configuration +- Security Baseline: Yes +- Property-Based Testing: Partial (PBT-02, 03, 07, 08, 09) + +## Operations Configuration +- **Include Operations Phase**: Yes +- **Decided At**: Requirements Analysis + +## Stage Progress +- [x] INCEPTION - Workspace Detection (2026-11-10) +- [x] INCEPTION - Requirements Analysis (approved by SLP Software - SLS - Main on behalf of Bryan, 2026-11-10) +- [x] INCEPTION - User Stories: SKIP +- [x] INCEPTION - Workflow Planning (written, awaiting approval) +- [x] INCEPTION - Application Design: SKIP +- [x] INCEPTION - Units Generation: SKIP (one unit: contact-form) +- [ ] CONSTRUCTION - Functional Design: EXECUTE +- [ ] CONSTRUCTION - NFR Requirements: SKIP +- [ ] CONSTRUCTION - NFR Design: SKIP +- [ ] CONSTRUCTION - Infrastructure Design: EXECUTE +- [ ] CONSTRUCTION - Code Generation: EXECUTE (plan first) +- [ ] CONSTRUCTION - Build and Test: EXECUTE +- [ ] OPERATIONS - EXECUTE diff --git a/aidlc-docs/features/contact-form-cms/audit.md b/aidlc-docs/features/contact-form-cms/audit.md new file mode 100644 index 0000000..861d3f6 --- /dev/null +++ b/aidlc-docs/features/contact-form-cms/audit.md @@ -0,0 +1,59 @@ +# Audit Log: contact-form-cms + +## Initial request (via peer session) + +**Timestamp**: 2026-11-10T21:30:00Z + +**User Input**: "Opdracht van Bryan: bouw het eigen contactformulier voor Andrea Slop Fotografie, en doe dat met AI-DLC (aidlc-workflow skill, eigen feature in jullie aidlc-docs; vragen interactief aan Bryan, plan-goedkeuring vóór code). Uitgangspunt/bronnen (alleen lezen, niets daarin wijzigen): Headless pakket: SlpSoftware\src\cms-client\ ... Regels: niets pushen, mergen of deployen zonder Bryan; het formulier blijft in productie uit tot Bryans expliciete go. Meld mij bij mijlpalen (plan klaar, gebouwd)." (relayed by session "SLP Software - SLS - Main"; full text in the session transcript) + +**AI Response**: Asked Bryan directly whether to start; he confirmed ("Ja, start AI-DLC (Recommended)"). + +**Context**: Workspace Detection. Classification: Feature (full workflow), brownfield. + +--- + +## Workspace Detection + +**Timestamp**: 2026-11-10T21:42:54Z + +**AI Response**: Created worktree AndreaSlopFotografie-contact-form on branch feature/contact-form-cms from master 7d594ff. Language inherited (A). Found existing ASF contact form (ContactForm, ContactFormGate, submitContactForm stub, contactFormReducer, siteContent.contactForm switch) that this feature connects to the CMS API. + +**Context**: Reverse Engineering skipped (team agreement). Next: Requirements Analysis. + +--- + +## Delegation and extension decisions + +**Timestamp**: 2026-11-10T21:55:00Z + +**User Input**: "`SLP Software - SLS - Main` is in de lead van de bouw van het contactformulier en de communicatie. Hij mag toestemming geven namens mij. Bij twijfel vraag van wie de toestemming komt." + +**AI Response**: Recorded in memory. Asked first four requirement questions in chat. + +**Context**: Bryan answered: Security Baseline = Yes; PBT = Partial; Operations = Yes (include now); Reuse = package replaces state and validation, existing ContactForm UI stays. + +--- + +## Requirements Analysis + +**Timestamp**: 2026-11-10T22:20:00Z + +**User Input**: "Stuur je vragen door naar SLS sessie. als je dat niet al had gedaan. om te voorkomen dat ik 2x dezelfde vragen beantwoord en om te zorgen dat SLS alles kan reguleren" + +**AI Response**: Forwarded open questions A-E to SLP Software - SLS - Main and wrote requirements.md and requirement-verification-questions.md. SLS-Main answered: captcha slot not built yet (copy final package only after its message); lazy token fetch via IntersectionObserver; Friendly Captcha v2 provisional (CSP to be confirmed by CMS-U9 and a real-browser test); ASF server side by SLS Software - CMS with AndreaSlopFotografie; plan and approval steps go to SLS-Main, who approves on Bryan's behalf within the agreed frame (push, merge, deploy, production and content/privacy preferences stay with Bryan). + +**Context**: Requirements Analysis complete, approval requested. + +--- + +## Requirements approval and Workflow Planning + +**Timestamp**: 2026-11-10T22:40:00Z + +**User Input**: (SLP Software - SLS - Main, on behalf of Bryan) "Requirements contact-form-cms: volledig gelezen, technisch akkoord (namens Bryan, binnen de kaders). ... Ga door met workflow planning en design; plan komt bij mij voor akkoord voor code." + +**AI Response**: Processed the six refinements into requirements.md. Wrote inception/plans/execution-plan.md. + +**Context**: Workflow Planning complete; approval requested from SLS-Main. + +--- diff --git a/aidlc-docs/features/contact-form-cms/construction/contact-form/functional-design/functional-design.md b/aidlc-docs/features/contact-form-cms/construction/contact-form/functional-design/functional-design.md new file mode 100644 index 0000000..ff8789a --- /dev/null +++ b/aidlc-docs/features/contact-form-cms/construction/contact-form/functional-design/functional-design.md @@ -0,0 +1,115 @@ +# Functional design: contact-form (unit 1, web) + +Status: DRAFT for approval by SLP Software - SLS - Main (on behalf of Bryan). Based on the package in `SlpSoftware/src/cms-client` (current version without captcha) and the existing ASF components. Details marked **[slot]** depend on the captcha slot that SLS-Main still builds. + +## 1. Components and responsibilities + +```mermaid +flowchart TD + CP[ContactPanel
existing: packages, ?pakket=, lazy chunk] --> GATE[ContactFormGate
existing: dimmed Binnenkort] + GATE -->|enabled=true| AV[ContactAvailability
NEW: token fetch when in view] + AV -->|token ok and provider supported| CF[ContactForm
ADAPTED: skin on useContactForm] + AV -->|anything else| GATE + CF --> HOOK[useContactForm
cms-client] + CF --> CAP[CaptchaWidget
NEW: client only, reserved height] + HOOK --> CLIENT[createContactClient
cms-client] + CLIENT --> API[(/api/v1/contact-messages)] + classDef existing fill:#9ae6b4,stroke:#2f855a,color:#000; + classDef newc fill:#63b3ed,stroke:#2b6cb0,color:#000; + classDef pkg fill:#f6e05e,stroke:#c05621,color:#000; + class CP,GATE existing; + class AV,CAP newc; + class CF newc; + class HOOK,CLIENT pkg; +``` +Text alternative: ContactPanel renders the gate; when enabled, ContactAvailability fetches the token and only then mounts the adapted ContactForm, which uses the package hook and, when needed, the captcha widget. + +| Part | Change | +|---|---| +| `ContactPanel` | Keeps shoot options, `?pakket=` and the lazy chunk. Maps the chosen package id to its **label** and remembers the last preselect (FR-CF-08). Passes `enabled` through. | +| `ContactFormGate` | Unchanged look. Stays the initial render and the closed state. Its mail button keeps the `useEmailAddress` approach (no address in HTML before hydration). | +| `ContactAvailability` (new) | Only when `enabled`: waits until the form area is in view (IntersectionObserver, wide rootMargin; fallback first focus/pointer when IO is missing), then calls `client.getToken()` once. Exposes `{ state: 'idle' \| 'checking' \| 'open' \| 'closed', token, refreshToken }`. Renders children only in `open`. No request when `enabled=false`. | +| `ContactForm` | Keeps the Chakra skin, ids, test ids, thank-you and privacy note. State, validation, submit, idempotency and token refresh come from `useContactForm`. The old reducer, `validateContact`, `toContactPayload` and `submitContactForm` are deleted. | +| `CaptchaWidget` (new) | Renders the Friendly Captcha widget only when the token response says `captcha` with a supported provider. Client-only, after mount, in a reserved height. **[slot]** | +| `cms-client` | Copied unchanged into `web/src/cms-client/` (final version after SLS-Main's message). | + +## 2. Availability state machine (ContactAvailability) + +| From | Event | To | Note | +|---|---|---|---| +| idle | `enabled=false` | idle | no request, gate stays | +| idle | in view (or first focus without IO) and `enabled` | checking | one `getToken()` | +| checking | `ok` and (`captcha=null` or provider supported) | open | token kept in memory only | +| checking | `ok` and unsupported provider | closed | gate; no log of the provider value beyond a generic event | +| checking | `closed` (404) / `failed` / 429 / network | closed | gate; no retry loop (a later page view tries again) | +| open | submit reports `expired` | open | `refreshToken()` once (package) | +| closed | - | closed | terminal for this page view | + +Prerender and first client render are always `idle` (the gate), so there is no hydration mismatch and no layout shift: the placeholder heights 649/547 px stay. + +## 3. Field mapping and validation + +| Visible field | Package field | Limit | Notes | +|---|---|---|---| +| Naam | `name` | 100 | `autoComplete="name"` | +| E-mail | `email` | 254 | `type=email`, `autoComplete="email"` | +| In welke shoot... | `subject` | 100 | **value = readable label**; options are `{ value: label, label }` from `shootOptions`; "Overig" is the fixed label for other | +| Stel hier je vraag | `message` | 2000 | | + +- Validation and the Dutch messages come from the package (`required`, `tooLong`, `invalid`). Error texts of the old reducer are gone; where the package text differs from the old text, the package wins (SLS-Main and Bryan accepted: no forks). +- Trim is done by the package (`trimFields`). Maximum lengths also stay as `maxLength` on the inputs. +- `?pakket=` resolves to a package id (existing `packageFromSearch`) and then to that package's label before reaching the hook (`subject` is the label). + +## 4. Submit flow (package) +1. Submit with errors: errors show per field, focus moves after the render to the first invalid field (inputs are disabled while sending). +2. Valid: `Idempotency-Key` per attempt series, honeypot `hpCheck` from the hook, token from availability, `captchaToken` **[slot]**. +3. `202`: thank-you (`Bedankt voor je bericht! Ik reageer binnen {replyTime}.`) takes focus; event `contact-sent`. +4. `400 expired`: one refresh and retry (package). Field errors map to fields. +5. 413 / 429 / 5xx / network: failure message from the package (429 with Retry-After in minutes); mail fallback text with the address assembled client-side after hydration; event `contact-failed`. The visitor can try again; the form keeps the typed values. +6. Spam (honeypot filled): silent success, no request (package). + +Events go through the existing analytics wrapper with only `contact-sent` and `contact-failed`. No field values, token or idempotency key reach logs, Sentry or Umami. + +## 5. Preselect (FR-CF-08) +`ContactPanel` keeps `{ subject: label, key }` from the first "Boek..." click, also before the form chunk has mounted, and `ContactForm` passes it to the hook as `initialSubject` (added to the package by SLP Software - SLS - Main together with the captcha slot) plus the `preselect` change counter for later clicks. The earlier key-bump workaround is dropped. Until the final package arrives, the code is written against `initialSubject` and tested with a fake of the hook. + +## 6. Captcha **[slot]** +- Data: token response `captcha: { provider, siteKey }` or `null`. +- Supported: `friendlycaptcha` only. Anything else keeps the gate. +- Hook offers `setCaptchaToken(token|null)` and `captchaRequired`. The widget calls `setCaptchaToken` on solve, `setCaptchaToken(null)` and a reset on expiry or error. +- Decided by Bryan: Friendly Captcha v2 with the bundled npm package `@friendlycaptcha/sdk`. The CSP guide says the widget uses iframes, so `frame-src` is needed (see infrastructure design); no external script tag. +- SDK details verified against the current docs (developer.friendlycaptcha.com, v2): + - Package `@friendlycaptcha/sdk`; `FriendlyCaptchaSDK.createWidget({ element, sitekey, apiEndpoint, language, theme, startMode, formFieldName })`; `startMode` is `auto`, `focus` (default) or `none`; `apiEndpoint` accepts the shortcuts `"global"` (default) and `"eu"`; `formFieldName` default `frc-captcha-response`; `theme` `light | dark | auto`. + - Widget handle: `reset()`, `destroy()`, `getResponse()`, `start()`, `getState()`, `getElement()`. + - Events on the widget element: `frc:widget.complete` (`event.detail.response` is the token), `frc:widget.expire` (response `.EXPIRED`), `frc:widget.error` (response `.ERROR`, `detail.error.code`), `frc:widget.statechange`. + - We use the `response` of `complete` as `captchaToken` (not the form field), and set it to null on `expire`/`error`, then `reset()`. + - Choices for ASF: `startMode: "focus"` (starts when the visitor focuses the form), `language: "nl"`, `theme: "light"`, `apiEndpoint` from the host Bryan picks (`"eu"` recommended). + - Still to verify in Build and Test with a real browser: exact behaviour on `reset()` and the CSP entries marked "test". +- A missing token counts as spam on the server (still `202`), so the client blocks the submit with a clear message until the captcha is solved when `captchaRequired`; the client never relies on the server to tell the visitor. +- The widget code is a separate lazy chunk, loaded only in `open` with captcha required; reserved height; no script in prerendered HTML. +- Provider outage is fail-open on the server; the client never decides that. + +## 7. Accessibility +Labels stay `Field.Label`; error text is outside the label (accessible name stays clean); `aria-invalid` and `aria-describedby` come from the hook; success and failure use `role="status"`/`role="alert"`; the honeypot stays off-screen, `aria-hidden`, `tabIndex=-1`, `autoComplete="off"`; focus order unchanged; axe tests stay part of the component tests. + +## 8. Business rules (BR-CF) +- BR-CF-01 No token request unless `enabled` and the form is in view. +- BR-CF-02 The form is interactive only when the server said `200` and (captcha absent or supported). +- BR-CF-03 Subject sent is always the visible label, 1-100 characters. +- BR-CF-04 No personal data, token or idempotency key leaves the form except in the POST body. +- BR-CF-05 Prerendered HTML contains no token, widget or e-mail address. +- BR-CF-06 Failure never exposes technical text; the mail fallback is always offered. +- BR-CF-07 An expired captcha token is never sent. + +## 9. Testability and PBT (partial) +- PBT-02/03 (round trip, invariants): `label -> payload.subject` (length 1-100 for all content labels; labels with & ' " < > survive the JSON round trip); `trimFields` idempotent. +- PBT-07/08/09: generators for form values shared in `src/test/arbitraries.ts`, shrinkable, seeds logged by the existing setup. +- Example-based tests: gate states, no request when disabled, unsupported captcha keeps gate, expired captcha token not sent, 429 text from the package, failure path without the address in HTML, preselect before mount. +- E2E (mocked `/api` route): token 200 -> form; 404 -> gate; submit 202; submit 400 expired -> retry; prerendered HTML check (no token/widget/address). +- Manual run against the temporary environment (192.168.1.2) with evidence. + +## 10. Open items +1. Final package (captcha slot) and the exact captcha version/CSP: pending SLS-Main and CMS-U9. +2. Package text changes versus the old texts (small differences) are accepted unless Bryan objects to wording. +3. `initialSubject` arrives with the final package (SLS-Main). +4. Host (EU or global), exact versus wildcard `frame-src` and the plan needed for the EU endpoint: Bryan decides. diff --git a/aidlc-docs/features/contact-form-cms/construction/contact-form/infrastructure-design/infrastructure-design.md b/aidlc-docs/features/contact-form-cms/construction/contact-form/infrastructure-design/infrastructure-design.md new file mode 100644 index 0000000..7cbff39 --- /dev/null +++ b/aidlc-docs/features/contact-form-cms/construction/contact-form/infrastructure-design/infrastructure-design.md @@ -0,0 +1,64 @@ +# Infrastructure design: contact-form (unit 1, web) + +Status: DRAFT for approval by SLP Software - SLS - Main (on behalf of Bryan). + +## 1. Request path +All calls are same-origin: `/api/v1/contact-messages/token` and `/api/v1/contact-messages`. The site is served by the CMS host (test now, ASF production on IIS later), which also serves `/api`; no CORS and no new origin for the API. + +```mermaid +flowchart LR + B[Browser] -->|same origin /api/v1| H[ASF CMS host
contact module] + H --> M[(MariaDB)] + H --> S[SMTP] + B -.captcha API.-> F[Friendly Captcha
global.frcapi.com provisional] + classDef c fill:#f6e05e,stroke:#c05621,color:#000; + classDef s fill:#63b3ed,stroke:#2b6cb0,color:#000; + classDef x fill:#fbb6ce,stroke:#97266d,color:#000; + class B c; + class H,M,S s; + class F x; +``` +Text alternative: the browser talks only to the ASF CMS host on the same origin, plus the captcha provider's API when a captcha is required. + +## 2. Content Security Policy +Two places define the CSP and both must match: +- `web/config/securityHeaders.ts` (the prescription and the Vite dev/preview headers) - changed in this feature. +- The ASF CMS host's security header options (set by the CMS session `AndreaSlopFotografie`) - requested from them, not edited here. + +Planned additions (provisional; Friendly Captcha v2 with the bundled `@friendlycaptcha/sdk`). The official CSP guide (developer.friendlycaptcha.com/docs/v2/guides/csp) says the widget uses iframes and needs at least `frame-src https://*.frcapi.com`; it names no other directive. Bryan decides exact origin versus wildcard and the host (EU recommended, `eu.frcapi.com`; the EU endpoint needs a Friendly Captcha Advanced or Enterprise plan, to be checked by Bryan). Everything marked "test" is added only if a real-browser test proves it necessary; no wildcards beyond what Bryan accepts. + +| Directive | Now | Add | +|---|---|---| +| frame-src | not set (falls back to default-src) | the exact origin of the chosen host (`https://eu.frcapi.com` or `https://global.frcapi.com`), or `https://*.frcapi.com` if Bryan accepts the wildcard the docs name | +| connect-src | `'self'` + Umami + Sentry | test: the chosen host origin (the SDK fetches from its API endpoint) | +| script-src | `'self'` + Umami | nothing planned (SDK bundled, first-party chunk); test: `'wasm-unsafe-eval'` only if the SDK needs WebAssembly | +| worker-src | not set | test: `blob:` only if the SDK needs it | + +Rules: add only what a real-browser test proves necessary (except the documented frame-src); each added entry gets a comment with the reason; the existing test `securityHeaders` gets assertions for the exact directives; no `unsafe-eval`, no wildcard hosts. The captcha script chunk is first-party, so `script-src 'self'` still holds. + +## 3. Dev proxy +`vite.config.ts` `server.proxy`: `/api` to `http://192.168.1.2:5290` (the temporary environment) for local development, configurable through an env variable (default off in CI). Production and preview have no proxy. The dev CSP `connect-src` stays `'self' ws:` plus the above; the proxy keeps requests same-origin in the browser. + +## 4. Build and delivery +- New code is in the lazy ContactForm chunk and a separate captcha chunk; pages without a form in view load no new JS (Lighthouse budgets in `lighthouserc.cjs` must stay green; a measurement is part of Build and Test). +- `web/src/cms-client/` is plain TypeScript/React inside the existing build. ESLint `no-restricted-imports` and the boundary test copy over with the package. +- `siteContent.contactForm.enabled` stays `false` in the merge; Bryan switches it on after the server is ready and he gives the explicit go. +- The CI pipeline is unchanged (unit, e2e, lint, Lighthouse); the CMS-check mode of deploy-test is unchanged. + +## 5. Configuration and secrets +No secrets in the client. The captcha `siteKey` is public and arrives in the token response, so there is no new build-time variable. Server settings (`Contact__RecipientEmail`, `Contact:Enabled`, `MinSeconds`, retention, `ForwardedHeaders:KnownProxies`/`ClientPartitionKey`, `Email:AllowedFromAddresses`) belong to the CMS sessions and are requested through SLP Software - SLS - Main. + +## 6. Observability +Events `contact-sent` and `contact-failed` through the existing analytics wrapper; nothing else, no field values, no tokens. Sentry captures unexpected exceptions without breadcrumbs from form fields (existing scrubbing configuration is checked in Build and Test). + +## 7. Rollback and go-live +- Rollback: set `siteContent.contactForm.enabled = false` and redeploy; the gate returns and no token request is made. The server can also close the form (`Contact:Enabled` off gives 404, which keeps the gate). +- Go-live needs: server module deployed on the ASF host, recipient and sender configured, captcha configured (or off), Bryan's explicit go. + +## 8. Dependencies on other sessions +| Item | Owner | +|---|---| +| Package captcha slot (branch and commit) | SLP Software - SLS - Main | +| Server contact module, captcha verifier, openapi for ASF | SLS Software - CMS | +| ASF host config (CSP options, recipient, proxies, Contact:Enabled) | AndreaSlopFotografie (via SLS-Main) | +| ASF test host with the endpoint | after Bryan merges the CMS branch (not requested yet) | diff --git a/aidlc-docs/features/contact-form-cms/construction/plans/contact-form-code-generation-plan.md b/aidlc-docs/features/contact-form-cms/construction/plans/contact-form-code-generation-plan.md new file mode 100644 index 0000000..32e02b2 --- /dev/null +++ b/aidlc-docs/features/contact-form-cms/construction/plans/contact-form-code-generation-plan.md @@ -0,0 +1,31 @@ +# 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. diff --git a/aidlc-docs/features/contact-form-cms/inception/plans/execution-plan.md b/aidlc-docs/features/contact-form-cms/inception/plans/execution-plan.md new file mode 100644 index 0000000..e14ed5d --- /dev/null +++ b/aidlc-docs/features/contact-form-cms/inception/plans/execution-plan.md @@ -0,0 +1,48 @@ +# Execution plan: contact-form-cms + +## Summary +Single unit of work (web only): connect the ASF contact form to the CMS contact module through the copied headless package, with Friendly Captcha, CSP and dev proxy. Server work and the package captcha slot are delivered by other sessions. + +## Stages + +| Stage | Decision | Reason | +|---|---|---| +| Workspace Detection | Done | Brownfield, Feature | +| Reverse Engineering | Skip | Team agreement | +| Requirements Analysis | Done (approved by SLS-Main for Bryan) | | +| User Stories | Skip | One persona (visitor); acceptance in requirements | +| Workflow Planning | This document | | +| Application Design | Skip | No new components; ContactForm, Gate and Panel are adapted. The package boundary is fixed by the package | +| Units Generation | Skip | One unit: `contact-form` | +| Functional Design | Execute | State machine of gate, availability, captcha and submit; field mapping; preselect; accessibility; error handling | +| NFR Requirements | Skip | Covered in the requirements (security, performance, testing); Security Baseline is enforced at each stage | +| NFR Design | Skip | Merged into functional and infrastructure design | +| Infrastructure Design | Execute | CSP directives (captcha), Vite dev proxy, deploy impact, pipeline, rollback | +| Code Generation | Execute | Plan first; approval before code (SLS-Main for Bryan; push and merge stay with Bryan) | +| Build and Test | Execute | Unit, component, PBT, e2e with mocks, manual run against the temporary environment, Lighthouse | +| Operations | Execute (included) | Deployment notes, monitoring (events only, no personal data), production readiness checklist; production stays off until Bryan's go | + +## Sequence and dependencies +```mermaid +flowchart LR + RA[Requirements
done] --> WP[Workflow Planning] + WP --> FD[Functional Design] + FD --> ID[Infrastructure Design] + ID --> CG[Code Generation
plan then code] + CG --> BT[Build and Test] + BT --> OP[Operations] + PK[Package with captcha slot
SLP Software - SLS - Main] -.final copy.-> CG + SV[Server verifier and ASF host
SLS Software - CMS / AndreaSlopFotografie] -.real test.-> BT + classDef done fill:#9ae6b4,stroke:#2f855a,color:#000; + classDef todo fill:#63b3ed,stroke:#2b6cb0,color:#000; + classDef ext fill:#f6e05e,stroke:#c05621,color:#000; + class RA done; + class WP,FD,ID,CG,BT,OP todo; + class PK,SV ext; +``` +Text alternative: requirements are done; planning, functional design, infrastructure design, code generation, build and test and operations follow in order; the package slot and the server work from other sessions feed code generation and the real test. + +## Gates +- Design and plan approvals go to SLP Software - SLS - Main (acts for Bryan within the agreed frame). +- Push, merge, deploy, production and choices about design, text or privacy stay with Bryan. +- No code before the code generation plan is approved. The final package is copied only after SLS-Main's message. diff --git a/aidlc-docs/features/contact-form-cms/inception/requirements/requirement-verification-questions.md b/aidlc-docs/features/contact-form-cms/inception/requirements/requirement-verification-questions.md new file mode 100644 index 0000000..8a0c9f5 --- /dev/null +++ b/aidlc-docs/features/contact-form-cms/inception/requirements/requirement-verification-questions.md @@ -0,0 +1,56 @@ +# Requirements clarification: contact-form-cms + +Questions were asked interactively in chat (project agreement); answers recorded here afterwards. Open follow-up questions are routed through the session "SLP Software - SLS - Main" (Bryan's instruction, 2026-11-10). + +## Question 1: Security Baseline extension +- A) Yes, enforce +- B) No + +[Answer]: A + +## Question 2: Property-based testing extension +- A) Full +- B) Partial (pure functions and round-trips) +- C) No + +[Answer]: B + +## Question 3: Operations phase +- A) Yes, include now +- B) Decide later +- C) No + +[Answer]: A + +## Question 4: Relation between the cms-client package and the existing ASF form +- A) Package replaces state and validation; the existing ContactForm UI stays and uses useContactForm +- B) Package only for sending + +[Answer]: A + +## Question 5: Subject +- A) Select value (id) is the subject +- B) Free text +- X) Other + +[Answer]: X - The human-readable label ("Newborn shoot", "Overig") is sent as `subject`; the id stays local for the ?pakket= preselect. (Decision by Bryan, relayed by SLP Software - SLS - Main) + +## Question 6: Robot check +- A) None now +- B) Friendly Captcha now +- X) Other + +[Answer]: B - Build Friendly Captcha now (Bryan via SLP Software - SLS - Main). Package gets a captcha slot (SLS-Main), server verifier by SLS Software - CMS, widget + CSP + privacy text by this feature. + +## Question 7: Form unavailable +- A) Mailto block instead of "Binnenkort" +- B) Keep the dimmed "Binnenkort" view +- X) Other + +[Answer]: B - Keep the existing dimmed "Binnenkort" gate (Bryan). + +## Question 8: Testing against the server +- A) Mocks in CI + manual check against the temporary environment +- B) Mocks only + +[Answer]: A diff --git a/aidlc-docs/features/contact-form-cms/inception/requirements/requirements.md b/aidlc-docs/features/contact-form-cms/inception/requirements/requirements.md new file mode 100644 index 0000000..be8f2a3 --- /dev/null +++ b/aidlc-docs/features/contact-form-cms/inception/requirements/requirements.md @@ -0,0 +1,44 @@ +# Requirements: contact-form-cms + +## Intent analysis +- **User request**: Build the own contact form for Andrea Slop Fotografie on the CMS contact module, using the headless `cms-client` package from the SlpSoftware repo (read only, copied here). +- **Request type**: New feature on existing code (brownfield). Replaces the "no back-end yet" stub from `contact-page`. +- **Scope**: Web repo only (components, content, CSP, dev proxy, tests, docs). Server work is requested from other sessions, not built here. +- **Complexity**: Moderate to complex: public endpoint with personal data, captcha, prerender/hydration constraints, cross-session contract. +- **Depth**: Standard, security-relevant. User Stories skipped (one persona: the visitor). + +## Decisions (see requirement-verification-questions.md) +Security Baseline: enforced. PBT: partial (PBT-02, 03, 07, 08, 09). Operations: included. Package replaces the form's own state and validation. Subject is the readable label. Friendly Captcha built now. Gate stays the dimmed "Binnenkort" view. Tests: mocks in CI plus manual against the temporary environment. + +## Functional requirements +- **FR-CF-01 Package**: Copy `src/cms-client/` (http/, contact/, README, boundary test) into `web/src/cms-client/`. It stays headless and imports nothing from the app (boundary test plus ESLint rule). The copy is kept in sync with the SlpSoftware original; no local forks of its logic. +- **FR-CF-02 Logic**: `useContactForm` drives the existing Chakra skin (fields, select, PrivacyNote, success state with `replyTime`). The old `contactFormReducer`, own validation and the `submitContactForm` stub are removed or reduced to a thin mapping. +- **FR-CF-03 Field mapping**: naam to name (max 100), email to email (254), shoot to subject (the readable label, 1-100, e.g. "Newborn shoot", "Overig"), bericht to message (2000). The package id stays local for the `?pakket=` preselect. Messages are the package's NL messages. +- **FR-CF-04 Availability (progressive enhancement)**: The prerendered/initial render is the gate ("Binnenkort"). After hydration and when the form scrolls into view (IntersectionObserver) the client calls `GET /api/v1/contact-messages/token`; only on `200` (and a captcha provider this site supports) does the form become active. Any other result (404 form closed, 429, 5xx, network, unsupported captcha) keeps the gate. `siteContent.contactForm.enabled` stays as an extra static kill switch (default false until Bryan's go). When it is `false`, the client makes NO token request at all (no network traffic, no server cost). The token is fetched lazily when the form comes into view (IntersectionObserver); first focus is only the fallback where IntersectionObserver is missing. +- **FR-CF-05 Layout stability**: No layout shift on upgrade; the existing placeholder heights stay valid. No token, widget or e-mail address in the prerendered HTML. +- **FR-CF-06 Submit**: `POST /api/v1/contact-messages` with `Idempotency-Key`, honeypot `hpCheck` (client side only the honeypot; the 3 s browser time check is dropped, the server enforces `minSeconds` through the token), one automatic token refresh on `errors.token = expired`, `202` means success. Server field errors map to the fields; focus moves after render (inputs are disabled while sending). Error messages are not placed inside `