Pakketblok: elk aantal pakketten, filterchips, swipe-rij op mobiel en optionele banner

Pure logica (splitsen, chips, filter, labels), useSwipeRow en usePackageFilter,
ContactPreselect voor het formulier, kaarten in stijl B en tests.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-11-10 10:34:09 +01:00
co-authored by Claude Sonnet 5.5
parent e1d950cd33
commit 9661b64635
28 changed files with 1353 additions and 137 deletions
@@ -0,0 +1,27 @@
# Code Summary — packages-block (U3)
## What was built
- **Pure logic** (`src/shared/packages/packageLogic.ts`): `splitPackages`, `deriveChips`, `filterCards`, `resultLabel`, `initialIndex`, `activeIndexFromScroll`.
- **Hooks**: `usePackageFilter` (cards, banner packages, chips, active chip with fallback to "Alles", visible list, status label), `useSwipeRow` (start position on the featured card, rAF-throttled scroll sync for the dots, smooth `scrollTo` unless reduced motion).
- **Contact hand-over** (`src/shared/contact/`): `ContactPreselectContext`/`Provider`/`useContactPreselect` (`subject` = package slug, `key` increments per click); the provider is mounted in `RootLayout`; U4 consumes it.
- **Components**: `PackagesSection` (B styling: alt background, heading, intro, chips + live status line, list, banner, states), `FilterChips`, `PackageList` (one render path: scroll-snap swipe row below `sm`, grid 2 columns from `sm`, 3 above 1000px), `SwipeDots` (buttons with labels, `aria-current`, mobile only, hidden at one card), `PackageCard` (flat block, featured in brand red with "Meest gekozen" badge, CTA sets preselect and scrolls to `#contact`), `PackageBanner` (black "Past er niets bij?" block), `PackageCardSkeleton` (square, 3 in the same container).
- **Settings** (`content.ts`): `packagesSettings = { bannerSlugs: [], chipThreshold: 4, bannerTitle, bannerFallback }`; `PackageCardData` gains optional `category`, `categoryId`, `displayOrder`.
- **Token tweak**: B light `--color-surface-2` is now white (the card colour of the canvas).
- **Heading**: "Drie manieren om te starten." with exactly three card packages, otherwise "Manieren om te starten."
## How a site chooses card vs banner
Put the package slug in `packagesSettings.bannerSlugs` (e.g. `['maatwerk']`): it is then shown as the black banner under the cards (always visible, independent of the active chip) and not as a card; with no matching package the fallback texts are used. SLP Software keeps the list empty, so Maatwerk is a normal card. A later additive API field `layout: card | banner` can replace the setting.
## Verification (Step 13.5, real output)
- Before this unit (after U2): 13 files / 122 tests. After: **14 files / 154 tests passed**; `pnpm lint` 0 errors (same 2 warnings); `pnpm build` OK (JS 453 kB, CSS 57.8 kB). Snap utilities and the `min-[1001px]` breakpoint are generated.
- Tests cover: pure logic (split, chip threshold 3 vs 4, blank categories, filter, singular/plural label, initial index, scroll-to-index), the live three packages (no chips/banner, Maatwerk a card, heading), loading/error with retry/empty, six packages with chips and counts and filtering, banner via setting (kept for every chip, fallback, CTA preselect), preselect key increments and scroll to `#contact`, swipe row roles/classes/dots/click/reduced motion/scroll sync with mocked layout, accessibility attributes.
## Notes for review
- **No `category` yet in the live API**: chips stay hidden until the CMS-U1 API is deployed (by design); with the current three packages the block looks like before, in the new style.
- Real swipe feel, card widths at 360px and the dark look need a browser check (no layout engine in the tests).
- Prettier touched two unrelated files; both were reverted.
## Hand-offs
- U4: read `useContactPreselect()` in the form (subject options = packages + "Overig"; apply when `key` changes; unknown subject ignored).
- U5: reuse `packageLogic`, `usePackageFilter`, `useSwipeRow`, `ContactPreselect*`; only the presentation (2006 style) is new.
- CMS: optional future `layout` field on offerings (additive, not needed now).
@@ -0,0 +1,44 @@
# Business Logic Model — packages-block (U3)
## Data flow
```mermaid
sequenceDiagram
box rgba(99,179,237,0.4) Browser
participant V as Visitor
participant PS as PackagesSection
participant HK as usePackageFilter
end
box rgba(154,230,180,0.4) CMS API
participant A as offerings
end
PS->>A: GET offerings
A-->>PS: package array
PS->>HK: split and derive chips
HK-->>PS: cards, chips, banner
V->>PS: choose a chip
PS->>HK: set active chip
HK-->>PS: filtered cards
V->>PS: click Kies button
PS->>PS: set preselect and scroll to contact
```
Text alternative: the section loads the offerings, the filter hook splits cards and banner and derives chips, a chip choice filters the cards, and a Kies button sets the contact preselect and scrolls.
## Pure functions (unit-testable, `src/shared/packages/`)
- `splitPackages(packages, bannerSlugs) -> { cards, banners }`
- `deriveChips(cards, threshold) -> Chip[] | null` (null = no chips)
- `filterCards(cards, activeId) -> PackageCardData[]`
- `resultLabel(count, hasBanner) -> string` ("1 pakket ...", "3 pakketten ...")
- `initialIndex(visible) -> number` (index of the featured card, else 0)
- `activeIndexFromScroll(scrollLeft, itemWidths|itemOffsets, viewportWidth) -> number` (nearest snap position)
## Hooks
- `usePackageFilter(packages, settings)`: state `activeId`; returns `{ cards, banners, chips, activeId, setActive, visible, label }`; resets `activeId` to `all` when the chosen category disappears.
- `useSwipeRow(itemCount, initialIndex)`: returns `{ ref, activeIndex, scrollToIndex }`; on mount and when `itemCount`/filter key changes scrolls to `initialIndex` (instant); listens to `scroll` (throttled by `requestAnimationFrame`) to update `activeIndex`; uses `scrollTo({behavior})` with `smooth` unless reduced motion.
- `useContactPreselect` (context from U3, consumed by U4): `{ subject, key, select(subject) }`.
## Error handling
- API error: error state with retry (`refetch`); loading: skeletons; empty list: info text.
- Unknown/absent `category`: package only under "Alles".
- `bannerSlugs` containing an unknown slug: fallback banner from settings.
- No `ResizeObserver`/`IntersectionObserver` required (scroll event + offsets); jsdom-safe.
@@ -0,0 +1,38 @@
# Business Rules — packages-block (U3)
| Id | Rule |
|---|---|
| BR-U3-1 | The block works with any number of packages (0..n) from the API; nothing is hard-coded to three. Array order = display order; no client-side sorting. |
| BR-U3-2 | **Split**: packages whose `slug` is in `packagesSettings.bannerSlugs` are *banner packages*; all others are *card packages*. Default (empty list): everything is a card, so Maatwerk is a card at SLP Software. |
| BR-U3-3 | **Chips** appear only when the number of card packages is at least `chipThreshold` (4) **and** there is at least one category. Chips: "Alles" plus the distinct non-empty categories of card packages in order of first appearance, each with its count. Selecting a chip shows only that category; "Alles" shows all card packages. Packages without category show only under "Alles". Chip state is not persisted. |
| BR-U3-4 | **Result count**: below the chips a polite status line "N pakket(ten) met vaste prijs" (plus ", plus maatwerk" when a banner is shown); announced to screen readers when the filter changes. |
| BR-U3-5 | **Layout**: from the `sm` breakpoint up a grid (3 columns, 2 columns up to 1000px); below it a **horizontal swipe row** (CSS scroll-snap, `snap-x snap-mandatory`, cards ~85% wide so the next card peeks) for any number of packages. The row works without JavaScript; JS only drives the dots and the initial position. |
| BR-U3-6 | **Banner**: when banner packages exist (or `bannerSlugs` is non-empty without a match, using `bannerFallback`), a black banner is shown below the cards with title, text, price label/note and a CTA to `#contact`. The banner is always visible regardless of the active chip. With an empty `bannerSlugs` no banner is rendered. (Both presentations remain possible per site; a later additive API field `layout: card \| banner` can replace the setting without changing the UI.) |
| BR-U3-7 | **Featured**: the featured package is styled with the brand colour and the "Meest gekozen" corner badge. In the swipe row the featured card is scrolled into view on first display (centered); if none is featured, the first card. After a filter change the row returns to its start (or the featured card if it is still visible). |
| BR-U3-8 | **Dots** (mobile only): one real `<button>` per visible card, `aria-label="Pakket {n} van {total}: {title}"`, `aria-current` on the active one; clicking scrolls that card into view. The active dot follows the scroll position. Hidden when there is only one card. |
| BR-U3-9 | **CTA** "Kies …" (card) and the banner CTA: sets the preselect (`subject = slug`, `key + 1`) and scrolls to `#contact`. Without JavaScript the link still jumps to `#contact`. |
| BR-U3-10 | **Loading**: skeletons while loading — 3 in the grid, in the swipe row too (no layout shift). **Error**: message "Pakketten konden niet worden geladen." with a "Opnieuw proberen" button (refetch). **Empty** (0 packages): short text "Binnenkort meer informatie. Neem contact op voor een voorstel." and the banner when configured. |
| BR-U3-11 | **Accessibility**: section labelled by its heading; chips are buttons with `aria-pressed`; cards are `article`s with an `h3`; the price is plain text; focus order = chips → cards (links) → banner; all touch targets ≥ 44px; swipe row is focusable/keyboard scrollable (`tabindex=0`, `role="group"`, `aria-label="Pakketten"`); animation (smooth scroll) respects reduced motion. |
| BR-U3-12 | **Theme**: B light/dark tokens; E styling is U5. Square corners, flat blocks, as in the canvas. |
## Decision flow: split and chips
```mermaid
graph TD
S([Packages loaded]) --> SP{Slug in bannerSlugs}
SP -->|"yes"| B[Banner package]
SP -->|"no"| C[Card package]
C --> T{Card count at least threshold and a category exists}
T -->|"yes"| CH[Show chips and counts]
T -->|"no"| NC[No chips]
B --> BN[Show banner under the cards]
CH --> V[Filter cards by active chip]
NC --> V
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 SP,T decision;
class B,C,CH,NC,BN,V step;
```
Text alternative: packages are split into cards and banner packages by slug; chips show when enough cards with categories exist; the active chip filters the cards; banner packages render under the cards.
@@ -0,0 +1,43 @@
# Domain Entities — packages-block (U3)
```mermaid
graph TD
API[GET api v1 offerings] -->|"array of"| PK[PackageCardData]
PK -->|"optional"| CAT[category name or null]
PK -->|"flag"| FEA[featured]
CFG[Site settings bannerSlugs] -->|"selects"| BAN[Banner package]
PK -->|"split by settings"| CARDS[Card packages]
PK -->|"split by settings"| BAN
CARDS -->|"derives"| CHIPS[FilterChip list]
CHIPS -->|"active id"| VIS[Visible cards]
VIS --> ROW[Grid or swipe row]
ROW -->|"CTA click"| PRE[Preselect subject and key]
classDef data fill:#63b3ed,stroke:#2b6cb0,color:#000;
classDef derived fill:#9ae6b4,stroke:#2f855a,color:#000;
classDef cfg fill:#f6e05e,stroke:#c05621,color:#000;
class API,PK,CAT,FEA data;
class CARDS,BAN,CHIPS,VIS,ROW,PRE derived;
class CFG cfg;
```
Text alternative: offerings from the API are split into card packages and banner packages by a site setting; the cards produce filter chips, the active chip selects the visible cards shown in a grid or swipe row; a card button creates a preselect for the contact form.
## PackageCardData (extended)
| Field | Type | Notes |
|---|---|---|
| `id`, `slug`, `title`, `description`, `price`, `priceNote`, `features[]`, `ctaLabel`, `featured?` | as before | `price` is rendered verbatim |
| `category?` | `string \| null` | category name from the CMS (CMS-U1); `null`/absent = no chip |
| `categoryId?`, `displayOrder?` | additive CMS fields | ignored by the UI |
## Site settings (content.ts)
| Setting | Type | Default | Meaning |
|---|---|---|---|
| `packagesSettings.bannerSlugs` | `string[]` | `[]` | packages shown as the black "Past er niets bij?" banner instead of a card. SLP: empty (Maatwerk is a card); Andrea-style sites may list `maatwerk` |
| `packagesSettings.chipThreshold` | `number` | `4` | chips appear when the number of card packages is at least this (FR-8) |
| `packagesSettings.bannerFallback` | `{ title, text, priceLabel, priceNote, ctaLabel }` | design texts | used only when `bannerSlugs` is non-empty and no package matches |
## FilterChip (derived)
`{ id: 'all' | categoryName, label, count }`; "Alles" first; categories in order of first appearance among card packages; counts only count card packages; packages without category appear only under "Alles".
## Preselect (shared with U4)
`ContactPreselect { subject: string | null; key: number }`: `subject` = package `slug`; `key` increments on every CTA click.
@@ -0,0 +1,65 @@
# Frontend Components — packages-block (U3)
## Component hierarchy
```mermaid
graph TD
pg[LandingPage] --> ps[PackagesSection]
ps --> hd[SectionHeading]
ps --> fc[FilterChips]
ps --> st[ResultStatus]
ps --> sk[PackageSkeletons]
ps --> er[PackagesError]
ps --> em[PackagesEmpty]
ps --> pl[PackageList]
pl --> sr[SwipeRow]
pl --> pc[PackageCard]
sr --> dt[SwipeDots]
ps --> bn[PackageBanner]
ps -.uses.-> q[usePackagesQuery]
ps -.uses.-> f[usePackageFilter]
sr -.uses.-> sw[useSwipeRow]
pc -.uses.-> pre[useContactPreselect]
bn -.uses.-> pre
classDef page fill:#2196F3,stroke:#0d47a1,color:#000;
classDef ui fill:#4CAF50,stroke:#2e7d32,color:#000;
classDef hook fill:#9C27B0,stroke:#4a148c,color:#000;
class pg,ps page;
class hd,fc,st,sk,er,em,pl,sr,dt,pc,bn ui;
class q,f,sw,pre hook;
```
Text alternative: the packages section shows a heading, optional filter chips, a status line, then skeletons, an error, an empty note or the package list (grid or swipe row with dots) and an optional banner; hooks provide data, filtering, swipe state and the contact preselect.
## Components
| Component | Props / state |
|---|---|
| `PackagesSection` | none; data from `usePackagesQuery`, settings from `content.ts`; renders `#pakketten` as `<section aria-labelledby>` on `bg-surface` (alt colour) |
| `FilterChips` | `chips`, `activeId`, `onSelect`; `role="group" aria-label="Filter pakketten"`; square chips, active = ink background |
| `ResultStatus` | `label`; `aria-live="polite"` |
| `PackageList` | `packages`, `featuredIndex`; grid on `sm+`, `SwipeRow` below (same cards rendered once, layout switched by CSS: `flex snap-x` below `sm`, `grid` above) |
| `SwipeDots` | `count`, `activeIndex`, `titles`, `onSelect`; `sm:hidden` |
| `PackageCard` | `pkg`; featured styling; CTA link `#contact` with `onClick` select + scroll; `data-testid=package-card-{id}` |
| `PackageBanner` | `pkg` or fallback; black block; CTA like the card |
| `PackageSkeletons`, `PackagesError` (retry), `PackagesEmpty` | as BR-U3-10 |
## User interaction flows
- Chip click → filter, row resets, status line announces the new count.
- Swipe/scroll → active dot follows; dot click → smooth scroll to the card.
- "Kies …" → preselect + scroll to `#contact`.
## Form validation rules
None.
## API integration points
`GET /api/v1/offerings` via the existing `usePackagesQuery` (type gains `category?`).
## Acceptance tests
1. 3 packages, empty `bannerSlugs`: 3 cards, no chips, no banner, Maatwerk is a card.
2. 6 packages with 2 categories: chips "Alles (6)", categories with counts; selecting filters; packages without category only under "Alles"; threshold boundary 3 vs 4.
3. `bannerSlugs=['maatwerk']`: that package is rendered as the banner, not as a card, and stays visible when a chip is active; fallback banner when the slug does not match.
4. Result label singular/plural and announcement on change.
5. Swipe row: scroll container has snap classes, group role and label; initial scroll position at the featured card; dots count/labels/`aria-current`; dot click scrolls; scroll updates the active dot (jsdom with mocked offsets); reduced motion → non-smooth.
6. CTA sets preselect (`slug`, key increments) and anchors to `#contact`.
7. Loading skeletons, error with retry (refetch called), empty state.
8. Pure functions table-driven (split, chips, filter, label, initialIndex, activeIndexFromScroll).
9. Accessibility: chips `aria-pressed`, cards `h3`, touch target classes, landmark label.