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>
7.4 KiB
7.4 KiB
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 (unit 2 row), 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)
- Step 1 —
content/types.ts:ImageSource,GalleryItem,FilterOption(domain-entities.md). - 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. - Step 3 —
lib/swipeDirection.ts(exportsSWIPE_THRESHOLD = 50) + test: examples (left, right, short, vertical, exactly 50) and properties: mirror flips, translation invariance, below threshold / more vertical →null. - Step 4 —
lib/masonryRowSpan.ts(exportsROWS_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. - Step 5 —
lib/neighbourIndexes.ts+ test: examples (count 1, 2, 3, 10) and properties: no duplicates, excludes index, in range, sizemin(2·radius, count − 1), oracle against a brute-force set. - 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. - Step 7 —
test/arbitraries.ts:imageSize(positive integer width/height within realistic photo bounds),galleryItem/galleryItems(unique ids),lightboxEvent.
Hook and hero refactor
- Step 8 —
hooks/useSwipe.ts+useSwipe.test.tsx: callsonNext/onPrevperswipeDirection, nothing whenenabledis false or without a start, start cleared after each end. - Step 9 —
components/Hero/useHeroSlider.ts: useuseSwipe({ onPrev: prev, onNext: next, enabled: count > 1 })andwrapIndexingo; remove the inline touch handlers and the local threshold. Existing hero tests pass unchanged.
Theme
- Step 10 —
theme.ts: duration tokenswap(0.3 s, lightbox crossfade); new reciperecipes/filterControl.ts(eyebrow style, pressed stateaccent.deep+ 2 px underline, hoverink, min height 44 px) registered underrecipes; runpnpm typegen.
Components (example-based tests + axe)
- Step 11 —
components/FilterBar/FilterBar.tsx+ test: group name, one pressed button, order,onChangeonly for a non-pressed button, nothing rendered for < 2 options, no button pressed for an unknown value, axe clean. - Step 12 —
components/PortfolioGrid/PortfolioGrid.tsx+ test: list in order, tile names (alt + " (groot bekijken)"), href = full image, first 3 eager withfetchpriority="high"and the rest deferred, row spans frommasonryRowSpan, plain click →onOpen(index)+ prevented, Ctrl/Meta click not intercepted,onIntentonce, empty list, axe clean. - Step 13 —
components/Lightbox/Lightbox.tsx(default export, forReact.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 callonClose; 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. - Step 14 —
test/galleryFixtures.ts: a fewGalleryItems built from existing assets (home intro photos) for the component tests.
Verification and docs
- Step 15 — Search: no leftover inline swipe code or
SWIPE_THRESHOLDduplicate in the hero; no duplicate component files. - Step 16 — Check ListAgents for parallel sessions and follow the 4173 protocol if any is active; run
pnpm checkinweb/(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. - 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.
- Step 18 — Update the reverse engineering lines for the new shared components, hook and helpers (code-structure, architecture, api-documentation; own lines only).
- Step 19 — Write
aidlc-docs/features/portfolio-page/construction/gallery-blocks/code/code-summary.md. - 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 |