Records unit 2 of the Contact page as generated

Functional design, code generation plan and summary of the shared
contact blocks, plus the coordination with the parallel features.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-10-25 18:26:48 +01:00
co-authored by Claude Opus 5.5
parent 9bb341dae7
commit ad85e3fe5b
10 changed files with 621 additions and 3 deletions
@@ -0,0 +1,69 @@
# Business Logic Model — Unit 2: Shared contact blocks
## Pure logic
### `contactChannels(email: EmailAddress, socials: readonly SocialLink[]): ContactChannel[]`
New, in `lib/contactChannels.ts` (100% coverage threshold applies to `lib/`). Implements BR-CD-01..04 and the `external` flag of BR-CD-05, using the existing `emailAddress`, `mailtoLink`, `mailSubject`, `visibleSocials` and the platform names. `ContactDetails` only renders what it returns (and renders nothing for an empty list, BR-CD-06).
### Reused unchanged
`shootOptions`, `packageFromSearch`, `visiblePackages`, `mailSubject`, `contactFormReducer` (the form's state machine).
## Flows
### Card
```mermaid
graph TD
Content["siteContent: email, socials"] --> Fn["contactChannels()"]
Fn --> Empty{"Empty list?"}
Empty -->|"yes"| Nothing(["null"])
Empty -->|"no"| Render["ContactDetails renders heading, list, one row per channel"]
classDef data fill:#9ae6b4,stroke:#2f855a,stroke-width:1px,color:#000;
classDef logic fill:#FFA726,stroke:#E65100,stroke-width:1px,color:#000;
classDef decision fill:#FFF59D,stroke:#F57F17,stroke-width:1px,color:#000;
class Content data;
class Fn,Render,Nothing logic;
class Empty decision;
```
Text alternative: the site content goes through contactChannels; an empty result renders nothing, otherwise the card renders a heading and one row per channel.
### Panel
```mermaid
graph TD
In["packages, enabled, email, replyTime, pakket, load"] --> Opts["shootOptions(packages)"]
In --> Pk{"New pakket value?"}
Pk -->|"valid id"| Pre["preselect key + 1, subject with package name"]
Pk -->|"invalid or none"| Keep["no change"]
Opts --> Gate{"enabled?"}
Pre --> Gate
Keep --> Gate
Gate -->|"no"| Notice["Gate: dimmed inert form, notice, mail button, privacy line"]
Gate -->|"yes"| FormOnly["Form only"]
Notice --> Load{"load"}
FormOnly --> Load
Load -->|"eager"| Now["Form rendered now"]
Load -->|"lazy"| Near{"Near screen or pakket?"}
Near -->|"no"| Placeholder["Placeholder of form height"]
Near -->|"yes"| Lazy["Load form chunk, keep it loaded"]
classDef data fill:#9ae6b4,stroke:#2f855a,stroke-width:1px,color:#000;
classDef logic fill:#FFA726,stroke:#E65100,stroke-width:1px,color:#000;
classDef decision fill:#FFF59D,stroke:#F57F17,stroke-width:1px,color:#000;
class In data;
class Opts,Pre,Keep,Notice,FormOnly,Now,Placeholder,Lazy logic;
class Pk,Gate,Load,Near decision;
```
Text alternative: the panel derives the shoot options, applies a valid new package value as preselect with a matching mail subject, wraps the form in the gate when the form is off, and renders the form now (eager) or when it comes near the screen or a package value arrives (lazy), keeping a placeholder until then.
## Properties for property-based testing (PBT-01)
| Function | Property | Category |
|---|---|---|
| `contactChannels` | The e-mail channel is present and first ⇔ `emailAddress(email)` is not null | Invariant |
| `contactChannels` | The social channels are exactly `visibleSocials(socials)` in the same order (same platforms and hrefs) | Invariant / oracle |
| `contactChannels` | Every social channel's label is its trimmed label when non-empty, otherwise the platform name; never empty | Invariant |
| `contactChannels` | Every `href` is `mailto:` or `https:`; never `javascript:` or another scheme | Invariant (security) |
| `contactChannels` | `external` is true exactly for social channels | Invariant |
| `contactChannels` | Length ≤ 1 + `socials.length` | Invariant |
Generators: extend `src/test/arbitraries.ts` — `socialLink` gets an optional `label` (absent, empty, whitespace, text), reuse `anyEmail` and `anyHref`. `ContactPanel` behaviour is covered by example-based component tests (it is UI wiring over already property-tested helpers).
@@ -0,0 +1,71 @@
# Business Rules — Unit 2: Shared contact blocks
Answers: [shared-contact-blocks-fd-questions.md](../../plans/shared-contact-blocks-fd-questions.md) (Q1 A, Q2 A, Q3 B, Q4 A).
## Contact channels (`ContactDetails`)
| Id | Rule |
|---|---|
| BR-CD-01 | The card lists the e-mail channel first, then the social links in the order of the content. *Q1 = A* |
| BR-CD-02 | The e-mail channel exists only when `emailAddress()` gives a valid address. Its link text is the address; its link is `mailto:` with the subject "Vraag via andreaslop.nl" (`mailSubject()`). The address is assembled in the browser only. |
| BR-CD-03 | A social channel exists only for links that `visibleSocials()` keeps (valid https). Invalid links are skipped; the order of the rest is kept. |
| BR-CD-04 | A social channel's link text is its `label` after trimming; an empty or missing label falls back to the platform name ("Instagram", "Facebook"). *Q2 = A* |
| BR-CD-05 | Social channels open in a new tab with `rel="noopener noreferrer"` and the visually hidden text "(opent in nieuw tabblad)", as in the footer. The e-mail channel opens in the same tab. |
| BR-CD-06 | No valid channel → the card is not rendered at all (no empty heading). |
| BR-CD-07 | Each channel shows its icon (platform icon or mail icon), hidden from assistive technology. |
| BR-CD-08 | Hover: the link text turns to the accent colour; the icon keeps its own colour; no underline. Keyboard focus: the theme focus ring. Each row is at least 44 px high. *Q4 = A* |
```mermaid
graph TD
Start(["Site content"]) --> E{"Valid e-mail address?"}
E -->|"yes"| AddE["Add e-mail channel first"]
E -->|"no"| S
AddE --> S["Take social links in content order"]
S --> V{"Valid https link?"}
V -->|"no"| Skip["Skip it"]
V -->|"yes"| L{"Non-empty label?"}
L -->|"yes"| UseL["Link text = label"]
L -->|"no"| UseN["Link text = platform name"]
UseL --> Next["Next link"]
UseN --> Next
Skip --> Next
Next --> Any{"Any channel?"}
Any -->|"no"| None(["Render nothing"])
Any -->|"yes"| Card(["Render the card"])
classDef start fill:#CE93D8,stroke:#6A1B9A,stroke-width:1px,color:#000;
classDef decision fill:#FFF59D,stroke:#F57F17,stroke-width:1px,color:#000;
classDef step fill:#9ae6b4,stroke:#2f855a,stroke-width:1px,color:#000;
class Start,None,Card start;
class E,V,L,Any decision;
class AddE,S,Skip,UseL,UseN,Next step;
```
Text alternative: a valid e-mail address becomes the first channel; each social link in content order is skipped when its link is invalid, otherwise it becomes a channel with its label or the platform name; the card is rendered only when at least one channel exists.
## Privacy line
| Id | Rule |
|---|---|
| BR-PR-01 | The text "Lees in de privacyverklaring wat ik met je gegevens doe." with "privacyverklaring" as an underlined router link to `/privacyverklaring`. |
| BR-PR-02 | Shown under the submit button inside `ContactForm` (every form that uses it). |
| BR-PR-03 | While the form is gated, the same line is also shown under the "Binnenkort" notice, so it can be read and followed now. *Q3 = B* |
| BR-PR-04 | One shared component renders the line in both places, so the text and link never drift apart. |
## Reply time
| Id | Rule |
|---|---|
| BR-RT-01 | The thank-you message is "Bedankt voor je bericht! Ik reageer binnen {replyTime}." with `replyTime` from `siteContent.contactForm.replyTime`. |
| BR-RT-02 | No other place hard-codes a reply time. |
## `ContactPanel` — behaviour kept from the homepage
| Id | Rule |
|---|---|
| BR-CPN-01 | Shoot options = the shown packages in their order, then "Overig" (`shootOptions`). |
| BR-CPN-02 | A raw `pakket` value is validated with `packageFromSearch` against the shown packages; only a known id preselects. A new valid value (also the same one again) re-applies the preselect (`key` increments); an invalid value changes nothing. |
| BR-CPN-03 | The mail subject is "Aanvraag fotoshoot: {package name}" after a valid preselect, otherwise "Vraag via andreaslop.nl". It is used by the gate's mail button and the form's failure message. |
| BR-CPN-04 | `load="lazy"`: the form loads when its spot comes near the screen (`DEFERRED_LOAD_MARGIN`) or immediately when a `pakket` value arrives; until then a placeholder keeps its height (604 px on phones, 502 px from `sm`); once loaded it stays loaded. |
| BR-CPN-05 | `load="eager"`: the form is part of the page and renders right away, without a placeholder. |
| BR-CPN-06 | The gate is shown whenever `enabled` is false, with the mail button (subject per BR-CPN-03) and the privacy line (BR-PR-03). |
| BR-CPN-07 | Not the panel's job: heading, URL clean-up, scrolling and focus. On the homepage `ContactSection` keeps doing these exactly as today. |
@@ -0,0 +1,55 @@
# Domain Entities — Unit 2: Shared contact blocks
## Entity relationships
```mermaid
graph TD
Site["SiteContent"] -->|"has"| Email["EmailAddress (user, domain)"]
Site -->|"has 0..n, in display order"| Social["SocialLink (platform, href, label?)"]
Site -->|"has"| FormCfg["contactForm (enabled, replyTime)"]
Social -->|"platform refers to"| Platform["socialPlatforms entry (name, icon)"]
Email -->|"becomes 0..1"| Channel["ContactChannel"]
Social -->|"becomes 0..1 when valid"| Channel
Packages["PricingPackage list"] -->|"gives"| Options["ShootOption list (+ Overig)"]
Panel["ContactPanel input"] -->|"uses"| FormCfg
Panel -->|"uses"| Options
Panel -->|"raw pakket"| Preselect["Preselect (shoot id, key)"]
classDef content fill:#9ae6b4,stroke:#2f855a,stroke-width:1px,color:#000;
classDef derived fill:#FFA726,stroke:#E65100,stroke-width:1px,color:#000;
classDef registry fill:#e2e8f0,stroke:#4a5568,stroke-width:1px,color:#000;
class Site,Email,Social,FormCfg,Packages content;
class Channel,Options,Preselect,Panel derived;
class Platform registry;
```
Text alternative: site content holds the e-mail address, the social links and the form settings; each valid e-mail or social link becomes one contact channel; the packages give the shoot options; the panel combines form settings, options and the preselect derived from the raw package value.
## Content entities (API-shaped, `content/types.ts`)
| Entity | Field | Type | Change | Notes |
|---|---|---|---|---|
| `SocialLink` | `platform` | `SocialPlatform` | — | `facebook` or `instagram` |
| | `href` | `string` | — | shown only as a valid https URL |
| | `label` | `string?` | **new** | visible link text in the contact card; without it, the platform name |
| `SiteContent` | `contactForm.enabled` | `boolean` | — | the gate switch |
| | `contactForm.replyTime` | `string` | **new** | e.g. "1-2 werkdagen"; one value for the thank-you and the contact page intro |
| | `socials` | `SocialLink[]` | **order changed** | Instagram first, then Facebook (Q1 = A); footer follows |
### Values in `siteContent.ts`
- Instagram: `href` unchanged, `label: '@andreaslopfotografie'`
- Facebook: `href` unchanged, `label: 'Andrea Slop Fotografie'` (Q2 = A)
- `contactForm: { enabled: false, replyTime: '1-2 werkdagen' }`
## Derived entities (pure, not stored)
### `ContactChannel` (`lib/contactChannels.ts`)
| Field | Type | Meaning |
|---|---|---|
| `kind` | `'email' \| 'social'` | which kind of channel |
| `platform` | `SocialPlatform?` | for `social` only; selects name and icon |
| `href` | `string` | `mailto:` link with the default subject, or the profile URL |
| `label` | `string` | visible link text |
| `external` | `boolean` | `true` for socials: open in a new tab with the hidden hint |
### `ContactPanel` input
`idPrefix`, `packages`, `enabled`, `email`, `replyTime`, raw `pakket?`, `load: 'lazy' | 'eager'` (see [component-methods.md](../../../inception/application-design/component-methods.md)). The preselect `{ shoot, key }` and the mail subject are derived inside, exactly as `ContactSection` does today.
@@ -0,0 +1,63 @@
# Frontend Components — Unit 2: Shared contact blocks
## Hierarchy
```mermaid
graph TD
Home["routes/index.tsx"] --> Section["home/ContactSection (heading, URL clean-up, scroll, focus)"]
Section --> Panel["ContactPanel (load lazy)"]
Panel --> Gate["ContactFormGate"]
Gate --> Privacy1["PrivacyNote (under the notice)"]
Panel --> Form["ContactForm (lazy chunk or direct)"]
Form --> Privacy2["PrivacyNote (under the submit button)"]
Details["ContactDetails (used by the contact page in unit 3)"] --> Eyebrow["Eyebrow as h2"]
Details --> Row["channel row: icon + link"]
classDef page fill:#2196F3,stroke:#0d47a1,color:#000;
classDef shared fill:#4CAF50,stroke:#2e7d32,color:#000;
classDef small fill:#e2e8f0,stroke:#4a5568,color:#000;
class Home,Section page;
class Panel,Gate,Form,Details shared;
class Privacy1,Privacy2,Eyebrow,Row small;
```
Text alternative: the homepage renders ContactSection, which renders ContactPanel; the panel wraps the form in the gate; both the gate notice and the form show PrivacyNote; ContactDetails (for the contact page) renders an eyebrow-style h2 and one row per channel.
## Components
### `ContactPanel` (new, `components/ContactPanel/`)
- **Props**: see [component-methods.md](../../../inception/application-design/component-methods.md).
- **State**: `seenPakket`, `preselect { shoot, key }`, `chosenName` (moved from `ContactSection`); `formLoaded` for `lazy`.
- **Test ids**: keeps `contact-gate`, `contact-gate-notice`, `contact-gate-mail`, `contact-form*` from the existing components.
- **Accessibility**: unchanged (gate uses `inert`; the notice is outside the inert part).
### `home/ContactSection` (changed)
- Keeps `TITLE_ID`, heading, `PageSection id="contact"`, the `?pakket=` clean-up effect (navigate replace, hash scroll respecting reduced motion, focus on the heading).
- Renders `<ContactPanel idPrefix="home-contact" load="lazy" ... />` inside its `Reveal`.
### `ContactForm` (changed)
- New prop `replyTime`; thank-you text per BR-RT-01.
- `PrivacyNote` under the submit button (BR-PR-02).
### `ContactFormGate` (changed)
- `PrivacyNote` under the mail button in the notice (BR-PR-03), only when the gate is shown.
### `PrivacyNote` (new, small, `components/PrivacyNote/`)
- Renders BR-PR-01: `Text` in small size, `ink.soft`, with `Link variant="underline"` + `RouterLink to="/privacyverklaring"`.
- Test id: `privacy-note`.
### `ContactDetails` (new, `components/ContactDetails/`)
- **Props**: `titleId`, `title`, `email`, `socials`, `portrait?`, `data-testid?`.
- **Structure**: a card (`bg` white, border `line`, shadow `panel`); header: optional round portrait (decorative, `alt=""`) next to the h2 (`Eyebrow as="h2"` with `id={titleId}`); a `ul` with `aria-labelledby={titleId}`; one `li` per channel with a link containing the icon (`aria-hidden`) and the label (+ hidden new-tab hint for socials).
- **Styling**: rows `minH="44px"`, icon in `accent.deep`, text `ink.soft` → `accent.deep` on hover, theme focus ring (BR-CD-08); all from theme tokens.
- **Test ids**: `{testid}` on the card, `contact-details-{kind or platform}` on each link.
- **Portrait size and layout variants** are used in unit 3; in this unit the component supports the prop and is tested with and without it.
## Interactions
- E-mail row: opens the mail app (`mailto:` with subject).
- Social rows: open the profile in a new tab.
- Privacy link: in-app navigation to `/privacyverklaring`.
- Homepage: unchanged flows ("Boek …" → preselect → URL clean-up → scroll → focus).
## Visible change on existing pages
- Homepage contact section: the privacy line under the "Binnenkort" notice (and under the form once enabled).
- Footer: Instagram now listed before Facebook (content order, Q1 = A).