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:
+63
@@ -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
|
||||
+10
@@ -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)
|
||||
Reference in New Issue
Block a user