Adds the shared gallery building blocks

A masonry photo grid that keeps the reading order (pure CSS, no measuring
in the browser), an accessible lightbox on Chakra's Dialog with wrap-around
browsing, keys, swipe and preloading, and a filter bar of toggle buttons.
They work on generic gallery items, so other pages can use them. The swipe
logic moves out of the hero into a shared hook; the hero behaves as before.
The rules behind them live in pure helpers with property-based tests.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-10-25 23:22:43 +01:00
co-authored by Claude Opus 5.5
parent e013f1436b
commit 18bf0311ef
38 changed files with 2392 additions and 43 deletions
@@ -0,0 +1,63 @@
# Code Generation Plan — Unit 2: Gallery building blocks
Single source of truth for code generation of this unit. Workspace root: `K:\Development\SlpSoftware\Projects\AndreaSlopFotografie-portfolio` (worktree); all code in `web/src/`. Branch `feature/portfolio-page` (on master 1bf28cb).
## Unit Context
- **Requirements**: FR-PF-03 (filter bar), FR-PF-05 (masonry grid), FR-PF-06 (lightbox), FR-PF-07 (image loading), NFR-PF-01 (accessibility), NFR-PF-02 (reuse, generic APIs, helpers in `lib/`), NFR-PF-03 (example + property-based tests), NFR-PF-05 (performance)
- **Design**: [application design](../../inception/application-design/application-design.md) (unit 2 row), [functional design](../gallery-blocks/functional-design/) — business rules BR-GR/LB/FB/SW, state machine, helper properties
- **Dependencies**: none on unit 3 or other features. Unit 3 (`PortfolioGallery`, route) builds on everything here. Components are tested with fixture data; they are not on a page yet
- **Touches existing code**: `components/Hero/useHeroSlider.ts` (swipe + wrap extracted; behaviour unchanged), `theme.ts` (one duration token, one recipe), `content/types.ts`, `test/arbitraries.ts`
- **Comments in English** in new code and in new comments in existing files
## Steps
### Types and pure helpers (`lib/`, 100% coverage, example + PBT)
- [x] **Step 1** — `content/types.ts`: `ImageSource`, `GalleryItem`, `FilterOption` (domain-entities.md).
- [x] **Step 2** — `lib/wrapIndex.ts` + `wrapIndex.test.ts`: examples (−1, count, large negatives) and properties: range, periodicity, idempotence, next-then-previous round-trip, oracle `((i % c) + c) % c`.
- [x] **Step 3** — `lib/swipeDirection.ts` (exports `SWIPE_THRESHOLD = 50`) + test: examples (left, right, short, vertical, exactly 50) and properties: mirror flips, translation invariance, below threshold / more vertical → `null`.
- [x] **Step 4** — `lib/masonryRowSpan.ts` (exports `ROWS_PER_COLUMN_WIDTH = 40`, `GAP_ROWS = 2`) + test: examples (portrait 2:3, landscape 3:2, square) and properties: minimum, monotonic in h/w, scale invariance, `|span − gapRows − K·h/w| ≤ 0.5`.
- [x] **Step 5** — `lib/neighbourIndexes.ts` + test: examples (count 1, 2, 3, 10) and properties: no duplicates, excludes index, in range, size `min(2·radius, count − 1)`, oracle against a brute-force set.
- [x] **Step 6** — `lib/lightboxReducer.ts` (`LightboxState`, `LightboxEvent`, `closedLightbox`) + test: examples per transition and a stateful property: random event sequences against a model; open index always in range.
- [x] **Step 7** — `test/arbitraries.ts`: `imageSize` (positive integer width/height within realistic photo bounds), `galleryItem` / `galleryItems` (unique ids), `lightboxEvent`.
### Hook and hero refactor
- [x] **Step 8** — `hooks/useSwipe.ts` + `useSwipe.test.tsx`: calls `onNext`/`onPrev` per `swipeDirection`, nothing when `enabled` is false or without a start, start cleared after each end.
- [x] **Step 9** — `components/Hero/useHeroSlider.ts`: use `useSwipe({ onPrev: prev, onNext: next, enabled: count > 1 })` and `wrapIndex` in `go`; remove the inline touch handlers and the local threshold. Existing hero tests pass unchanged.
### Theme
- [x] **Step 10** — `theme.ts`: duration token `swap` (0.3 s, lightbox crossfade); new recipe `recipes/filterControl.ts` (eyebrow style, pressed state `accent.deep` + 2 px underline, hover `ink`, min height 44 px) registered under `recipes`; run `pnpm typegen`.
### Components (example-based tests + axe)
- [x] **Step 11** — `components/FilterBar/FilterBar.tsx` + test: group name, one pressed button, order, `onChange` only for a non-pressed button, nothing rendered for < 2 options, no button pressed for an unknown value, axe clean.
- [x] **Step 12** — `components/PortfolioGrid/PortfolioGrid.tsx` + test: list in order, tile names (alt + " (groot bekijken)"), href = full image, first 3 eager with `fetchpriority="high"` and the rest deferred, row spans from `masonryRowSpan`, plain click → `onOpen(index)` + prevented, Ctrl/Meta click not intercepted, `onIntent` once, empty list, axe clean.
- [x] **Step 13** — `components/Lightbox/Lightbox.tsx` (default export, for `React.lazy`) + test: closed renders nothing; open shows the item's full image with alt, caption, counter; next/prev buttons and keys wrap; Home/End; Escape and close button call `onClose`; image click does nothing; single item hides prev/next/counter; announcement text after navigation; load error shows the message and keeps the thumb; neighbours preloaded (2 each side); focus on the close button when opened; axe clean while open.
- [x] **Step 14** — `test/galleryFixtures.ts`: a few `GalleryItem`s built from existing assets (home intro photos) for the component tests.
### Verification and docs
- [x] **Step 15** — Search: no leftover inline swipe code or `SWIPE_THRESHOLD` duplicate in the hero; no duplicate component files.
- [x] **Step 16** — Check ListAgents for parallel sessions and follow the 4173 protocol if any is active; run `pnpm check` in `web/` (lint, format, build, tests with coverage, audits, Lighthouse). Fix and rerun until green. *Outcome: all green except mobile Lighthouse on `/` and `/contact`, which fail identically on master (pre-existing budget issue); see code summary.*
- [x] **Step 17** — Visual check: the components are not on a page yet; their look is verified in unit 3 (browser check on the portfolio page). The hero swipe is covered by its unchanged tests.
- [x] **Step 18** — Update the reverse engineering lines for the new shared components, hook and helpers (code-structure, architecture, api-documentation; own lines only).
- [x] **Step 19** — Write `aidlc-docs/features/portfolio-page/construction/gallery-blocks/code/code-summary.md`.
- [x] **Step 20** — Commit on `feature/portfolio-page` ("Adds the shared gallery building blocks"), together with the unit 2 functional design docs. No push until asked.
## Files
- **Created**: `lib/{wrapIndex,swipeDirection,masonryRowSpan,neighbourIndexes,lightboxReducer}.ts` + tests; `hooks/useSwipe.ts` + test; `recipes/filterControl.ts`; `components/{FilterBar,PortfolioGrid,Lightbox}/*.tsx` + tests; `test/galleryFixtures.ts`
- **Modified**: `content/types.ts`, `test/arbitraries.ts`, `theme.ts` (+ generated Chakra types), `components/Hero/useHeroSlider.ts`
- **Docs**: RE own lines, unit code summary
## Extension Compliance (unit 2)
| Rule | Status | Rationale |
|---|---|---|
| SECURITY-10 | Compliant | No new dependencies (Chakra `Dialog`, `@iconify-icons/ant-design` and fast-check are already present) |
| SECURITY-13 | Compliant | Lazy chunk is our own bundle; no external resources |
| Other SECURITY rules | N/A | Presentational components and pure helpers; no data, endpoints, headers or input from outside (the URL parameter is unit 3) |
| PBT-01 | Compliant | Properties identified in business-logic-model.md, mapped to steps 2–6 |
| PBT-02 | Planned | Round-trip: `wrapIndex` next-then-previous (step 2) |
| PBT-03 | Planned | Invariants: steps 2–5 |
| PBT-04 | Planned | Idempotence: `wrapIndex` (step 2) |
| PBT-05 | Planned | Oracles: `wrapIndex` modular formula, `neighbourIndexes` brute force, hero behaviour via unchanged tests |
| PBT-06 | Planned | Stateful: `lightboxReducer` against a model (step 6) |
| PBT-07 | Planned | Domain generators in `test/arbitraries.ts` (step 7) |
| PBT-08 / 09 | Compliant | Existing seed logging and fast-check |
| PBT-10 | Planned | Every helper and component also has example-based tests |
@@ -0,0 +1,103 @@
# Functional Design-vragen — Unit 2: Galerijbouwstenen
Al vastgelegd (geen vraag nodig):
- **Bladeren** loopt rond: na de laatste foto komt de eerste, en andersom. Escape en een klik op de donkere achtergrond sluiten; ← en → bladeren; vegen naar links of rechts bladert (zelfde drempel als de hero: 50 px, en meer horizontaal dan verticaal).
- **Eén foto in de lijst**: geen vorige/volgende-knoppen en geen teller.
- **Focus**: bij openen in het venster, bij sluiten terug naar de tegel van de foto die als laatste te zien was.
- **Direct laden** geldt voor de eerste 3 tegels van de lijst die op dat moment getoond wordt.
- **De hero** werkt na het uitlichten van de veeglogica precies zoals nu.
- Deze bouwstenen kennen geen shoottypes, filters of URL; dat komt in unit 3.
*Beantwoord in de chat op 2026-10-25 en hier vastgelegd.* Vul per vraag de letter in na `[Answer]:`. Past geen enkele optie, kies dan de laatste (Anders) en licht toe.
---
## Vraag 1: Overgang tussen foto's in de lightbox
- A) **Korte overvloeier** (ongeveer 0,3 s) bij openen, sluiten en bladeren; bij "beweging beperken" in het besturingssysteem geen animatie (aanbevolen)
- B) **Geen animatie**: de foto wisselt direct
- C) **Schuiven** naar links of rechts, in de richting van het bladeren
- X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]: A
## Vraag 2: Plaats van de knoppen op een telefoon
In het ontwerp staan vorige en volgende halverwege links en rechts over de foto, en sluiten rechtsboven. Op een smal scherm liggen de knoppen dan over de foto heen.
- A) **Op telefoons een balk onderaan** (vorige · teller · volgende) en sluiten rechtsboven; **vanaf tablet** zoals het ontwerp, links en rechts naast de foto. Zo bedekken de knoppen de foto nergens en zitten ze binnen bereik van de duim (aanbevolen)
- B) **Overal zoals het ontwerp**: links en rechts halverwege, ook op telefoons
- X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]: A
## Vraag 3: Klikken of tikken op de grote foto zelf
- A) **Niets**: alleen de knoppen, toetsen, vegen en de achtergrond doen iets. Voorkomt per ongeluk sluiten of bladeren (aanbevolen)
- B) **Volgende foto**
- C) **Sluiten**
- X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]: A
## Vraag 4: Naar beneden vegen
- A) **Niet ondersteund**: sluiten gaat met de knop, Escape of de achtergrond (aanbevolen: eenvoudiger, geen conflict met scrollen of inzoomen)
- B) **Naar beneden vegen sluit** de lightbox, zoals in veel foto-apps
- X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]: A
## Vraag 5: Wat een screenreader hoort bij het bladeren
- A) **Positie en bijschrift**, bijvoorbeeld "Foto 3 van 10, Newbornshoot". De alt-tekst wordt voorgelezen als de focus op de foto komt (aanbevolen)
- B) **Positie, bijschrift en alt-tekst** in één keer. Volledig, maar lang bij snel bladeren
- C) **Alleen de positie**: "Foto 3 van 10"
- X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]: A
## Vraag 6: Naam van een tegel in het raster
Een tegel is een link die de lightbox opent. Zijn naam is de alt-tekst plus een aanwijzing.
- A) Alt-tekst + **"(groot bekijken)"**, bijvoorbeeld "Moeder met pasgeboren baby op bed (groot bekijken)" (aanbevolen)
- B) Alt-tekst + **"(vergroten)"**
- C) Alleen de alt-tekst
- X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]: A
## Vraag 7: Als de grote foto niet laadt
- A) De kleine foto uit het raster blijft staan (die is er al), zonder melding; bladeren blijft werken (aanbevolen)
- B) De kleine foto blijft staan met een korte melding "Deze foto kon niet groot geladen worden"
- X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]: B
## Vraag 8: Vooruit laden in de lightbox
- A) **De vorige en de volgende** grote foto (1 aan elke kant) (aanbevolen: snel bladeren, weinig extra data op een telefoon)
- B) **Twee aan elke kant**
- C) **Niets vooruit**; elke grote foto laadt pas als hij getoond wordt
- X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]: B
## Vraag 9: Het raster bij een ander filter
- A) **Direct wisselen** zonder animatie; nieuwe tegels verschijnen meteen, ook als ze nog niet in beeld waren geweest (aanbevolen: rustig, geen verspringende fade-ins)
- B) **Kort overvloeien** van het raster bij elke wissel
- X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]: A
## Vraag 10: Home en End in de lightbox
- A) **Ja**: Home springt naar de eerste foto, End naar de laatste (aanbevolen: handig en volgt het gebruikelijke patroon voor galerijen)
- B) **Nee**: alleen ← en →
- X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]: A
@@ -0,0 +1,10 @@
# Functional Design Plan — Unit 2: Gallery building blocks
Depth: standard. Scope from the execution plan: the rules and states of the generic `PortfolioGrid`, `Lightbox`, `FilterBar` and `useSwipe`, and the pure helpers behind them (`wrapIndex`, `swipeDirection`, `masonryRowSpan`, `neighbourIndexes`), with their testable properties (PBT-01). Questions: [gallery-blocks-fd-questions.md](gallery-blocks-fd-questions.md).
- [x] Collect and analyse the answers in `gallery-blocks-fd-questions.md`
- [x] `domain-entities.md` — `GalleryItem`, `ImageSource`, `FilterOption`, lightbox state (open index or closed), swipe points; how they relate
- [x] `business-rules.md` — grid rules (order, columns, row spans, eager count, link fallback, intent), lightbox rules (open/close, wrap, keys, swipe, counter, caption, focus return, preloading, single item, loading and error states, reduced motion), filter bar rules (options, active state, fewer than two options), swipe rules (threshold, direction), hero behaviour unchanged
- [x] `business-logic-model.md` — event flows (open from tile, browse, close, swipe) and the lightbox state machine; the pure helpers with their properties per PBT category (round-trip, invariant, idempotence, oracle, stateful)
- [x] `frontend-components.md` — component hierarchy, props and state per component, accessible names and live regions, keyboard map, test ids, recipes and tokens
- [x] Validate against requirements.md, application-design.md and the extension rules (Security Baseline, PBT)