Files
AndreaSlopFotografie/aidlc-docs/features/portfolio-page/construction/plans/gallery-blocks-code-generation-plan.md
T
SluijsensandClaude Opus 5.5 18bf0311ef 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>
2026-10-25 23:22:43 +01:00

7.4 KiB
Raw Blame History

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 (exports SWIPE_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 (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.
  • 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.
  • 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: calls onNext/onPrev per swipeDirection, nothing when enabled is false or without a start, start cleared after each end.
  • 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

  • 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)

  • 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.
  • 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.
  • 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.
  • Step 14 — test/galleryFixtures.ts: a few GalleryItems built from existing assets (home intro photos) for the component tests.

Verification and docs

  • Step 15 — Search: no leftover inline swipe code or SWIPE_THRESHOLD duplicate 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 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.
  • 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