Plans the portfolio page

Records the requirements, execution plan and application design for the
portfolio page: the ten live photos in a filterable masonry grid with an
accessible lightbox, filters per shoot type in the URL, the Instagram
block shared with the homepage, and an indexed page with image gallery
structured data. Built alongside the contact and shoot type pages, with
shared pieces split between them.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-10-25 21:32:48 +01:00
co-authored by Claude Opus 5.5
parent 1bf28cb569
commit b35b1c2404
11 changed files with 1100 additions and 0 deletions
@@ -0,0 +1,100 @@
# Application Design Plan — Portfolio Page
Depth: standard. Business rules (filtering, wrap-around, lightbox states, masonry spans, `?shoot=` parsing, gallery structured data) follow in Functional Design for units 2 and 3.
## Plan
- [x] Answer the design questions below
- [x] Generate `components.md` — new and changed components with responsibilities and interfaces
- [x] Generate `component-methods.md` — props, hooks and pure function signatures
- [x] Generate `services.md` — composition in the route (there is no service layer in this SPA)
- [x] Generate `component-dependency.md` — dependency matrix, data flow, and where the peer commits slot in
- [x] Generate `application-design.md` — consolidated design
- [x] Validate completeness and consistency against requirements.md
## Already decided (no question needed)
- **Names as claimed with the other sessions**: `PortfolioGrid`, `Lightbox`, and `InstagramGrid` (moved). Despite the name, `PortfolioGrid` gets a generic API (a list of images, no knowledge of shoot types), so other pages can use it.
- **Gallery data for the components**: the components work with a generic item, roughly `{ id, thumb: ContentImage, full: { src, width, height }, caption? }`. The page maps its portfolio photos (with `shootType`) to that, taking the caption from `shootLabel`. So `Lightbox` and `PortfolioGrid` never import shoot types.
- **Portfolio content**: `content/portfolioContent.ts` + a `PortfolioContent` / `PortfolioPhoto` type in `content/types.ts`; photos reference `ShootTypeId` only. Instagram content: `content/instagramContent.ts` + `InstagramContent` (split off from `HomeContent`); the homepage passes the same object.
- **URL state**: `?shoot=` is read through the route's `validateSearch` and checked by a pure function in `lib/` against the shoot types that have photos, like `packageFromSearch` for `?pakket=`. The route is the single source of truth for the active filter; it navigates to change it.
- **Lightbox on Chakra `Dialog`** (focus trap, focus return, Escape, inert background and scroll lock come from Chakra/Ark); our part is the content, prev/next, counter, caption, swipe and preloading.
- **SEO**: `galleryImages(...)`-style pure builders in `seo.ts` produce the `ImageObject` list; the route's `head()` combines `pageHead('/portfolio')` with one `structuredDataScript(webPage('ImageGallery', '/portfolio', { associatedMedia }))`.
---
Vul per vraag de letter in na `[Answer]:`. Past geen enkele optie, kies dan de laatste (Anders) en licht toe.
## Vraag 1: Hoe raster, lightbox en filter samenwerken
- A) **Drie losse onderdelen plus één pagina-onderdeel dat ze verbindt**: `PortfolioGrid` toont foto's en meldt "foto X geopend"; `Lightbox` toont een lijst foto's vanaf een startpositie; de filterbalk meldt "filter gekozen". Een pagina-specifiek onderdeel in `components/portfolio/` (bijvoorbeeld `PortfolioGallery`) bewaart welke foto open is en geeft het gefilterde lijstje aan beide door. Elk onderdeel is los te testen en los te hergebruiken, bijvoorbeeld een `Lightbox` bij de shootfoto's op Soorten fotoshoots (aanbevolen)
- B) **Raster met ingebouwde lightbox**: `PortfolioGrid` opent zelf zijn `Lightbox`. Minder losse delen, maar de lightbox is dan niet zonder raster te gebruiken
- C) Alles in de route opbouwen, zonder pagina-specifiek onderdeel
- X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]: A
## Vraag 2: Hoe de filterbalk werkt (voor toetsenbord en screenreader)
- A) **Een groep schakelknoppen**: elke knop is een tab-stop, de actieve heeft `aria-pressed="true"`, en de groep heeft een naam ("Filter op soort shoot"). Eenvoudig en voorspelbaar (aanbevolen)
- B) **Een keuzerondjesgroep** (radiogroup): één tab-stop, je kiest met de pijltjestoetsen. Compacter voor het toetsenbord, maar minder bekend voor wie het niet kent
- C) **Tabbladen** (tablist): semantisch bedoeld voor wisselende inhoud in vaste panelen, wat hier niet helemaal past
- X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]: A
## Vraag 3: Hoe de filterbalk eruitziet
Het ontwerp heeft geen filters, dus dit is nieuw.
- A) **Tekstlinks in labelstijl** (zoals de eyebrows: kleine hoofdletters, ruime spatiëring), de actieve onderstreept in `accent.deep`. Rustig en past bij de typografie van de site; als nieuwe variant in een recipe (aanbevolen)
- B) **Omlijnde knoppen** in de stijl van `LinkButton` `outline`, de actieve gevuld met de accentkleur. Duidelijker als "knoppen", maar zwaarder boven een fotoraster
- X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]: A
## Vraag 4: Filter wisselen en de terugknop
- A) **Vervangen**: wisselen van filter past de URL aan zonder een stap in de geschiedenis. De terugknop verlaat de pagina, ook na vijf keer wisselen (aanbevolen)
- B) **Toevoegen**: elke filterwissel is een stap; de terugknop gaat terug naar het vorige filter
- X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]: A
## Vraag 5: Vegen in de lightbox
De hero heeft al veeglogica, maar die zit vast in `useHeroSlider`.
- A) **Uit de hero halen** naar een gedeelde hook (bijvoorbeeld `useSwipe({ onPrev, onNext })`) en die in de hero en de lightbox gebruiken. Eén plek voor drempel en gedrag; de hero blijft precies zo werken (aanbevolen)
- B) De lightbox krijgt eigen veeglogica; de hero blijft ongemoeid
- X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]: A
## Vraag 6: Techniek voor de masonry in rijvolgorde
- A) **Alleen CSS**: een raster met hele kleine rijen, waarbij elke foto zoveel rijen beslaat als past bij zijn verhouding. Dat aantal rekent een losse functie uit met de breedte en hoogte uit de data, en de rijhoogte schaalt mee met de kolombreedte (container-eenheden). Geen meten in de browser, dus geen verspringen bij het laden (aanbevolen)
- B) **Meten met JavaScript**: na het laden de echte hoogtes meten (ResizeObserver) en de foto's positioneren. Precies, maar het raster kan verspringen en het werkt pas als JavaScript draait
- X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]: A, als het later nodig kunnen we het alsnog ombouwen
## Vraag 7: Lightbox-code apart laden
- A) **Apart laden**: de code van de lightbox laadt pas zodra je een foto opent, of al vooruit als je met muis of focus op een foto komt. De eerste weergave van de pagina blijft lichter (helpt de prestatiescore) (aanbevolen)
- B) **Direct meeladen** met de pagina. Eenvoudiger, de eerste keer openen is altijd direct
- X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]: A
---
## Vervolgvraag 6a: "A, als het later nodig"
Je antwoord op vraag 6 lijkt halverwege afgebroken. Wat bedoel je?
- A) **CSS-masonry nu; meten met JavaScript alleen als CSS later tekortschiet.** Ik ontwerp de grid zo dat de berekening van de rijen op één plek zit, zodat die later vervangen kan worden zonder de rest aan te passen. Wat "tekortschiet" is, leg ik vast: zichtbare gaten groter dan één rij-eenheid, of verkeerd bijgesneden foto's in een browser die we ondersteunen (aanbevolen)
- B) **CSS-masonry, en verder niets voorbereiden.** Als het later nodig is, bouwen we het dan om
- X) Anders (beschrijf hieronder na de [Answer]:-tag)
[Answer]: B
@@ -0,0 +1,167 @@
# Execution Plan — Portfolio Page
## Detailed Analysis Summary
### Transformation Scope (Brownfield)
- **Transformation Type**: Single component (`web/`), application-level only
- **Primary Changes**: replace the `/portfolio` placeholder with the real page; new shared gallery building blocks (masonry `PortfolioGrid`, `Lightbox`, a generic filter bar) with pure helpers in `lib/`; `InstagramGrid` moved to a shared component with its own content; page-specific SEO (indexing, `ImageGallery` JSON-LD via the shared `webPage()`, own preview image); 10 photos in two sizes
- **Related Components**: `web/src/routes/portfolio.tsx`, `web/src/routes/index.tsx`, `web/src/components/{home/InstagramGrid → InstagramGrid, PortfolioGrid, Lightbox, filter bar}`, `web/src/lib/`, `web/src/content/` (+ `types.ts`), `web/src/seo.ts`, `web/src/sitePages.ts`, `web/lighthouserc*.cjs`, `web/src/theme.ts` (possibly a `zIndex` token), `web/src/test/arbitraries.ts`, `web/public/`, `web/src/assets/portfolio/`, [LAYOUT.md](../../../../../LAYOUT.md)
### Change Impact Assessment
- **User-facing changes**: Yes — a new page with filters and a lightbox; the homepage Instagram block must look and behave exactly as before
- **Structural changes**: Minor — one component moved, new shared components; no architectural change
- **Data model changes**: Yes — new portfolio photo content (two image sizes, `ShootTypeId`), `InstagramContent` split from `HomeContent`
- **API changes**: No external API; new URL search parameter `?shoot=` on `/portfolio`; internal props for the new components
- **NFR impact**: Yes — SEO (indexed, structured data, preview image), accessibility (modal dialog, focus management, announcements), performance (photo-heavy page, Lighthouse budget 0.9 on mobile)
### Component Relationships
```mermaid
graph TD
Route["routes/portfolio.tsx"] --> PageIntro["PageIntro (existing)"]
Route --> Filter["Filter bar (new, generic)"]
Route --> Grid["PortfolioGrid (new, masonry)"]
Grid --> Lightbox["Lightbox (new, Chakra Dialog)"]
Grid --> Deferred["DeferredImage + Reveal (existing)"]
Route --> Insta["InstagramGrid (moved to shared)"]
Home["routes/index.tsx"] --> Insta
Insta --> InstaContent["content/instagramContent.ts (new)"]
Route --> PfContent["content/portfolioContent.ts (new)"]
PfContent --> ShootTypes["content/shootTypes.ts (from soorten-fotoshoots)"]
Filter --> Lib["lib/ helpers (new, pure)"]
Grid --> Lib
Lightbox --> Lib
Route --> Seo["seo.ts webPage() (from contact-page) + sitePages.ts"]
Seo --> Lhci["lighthouserc*.cjs (indexed paths)"]
classDef newpart fill:#FFA726,stroke:#E65100,stroke-width:1px,color:#000;
classDef changed fill:#63b3ed,stroke:#2b6cb0,stroke-width:1px,color:#000;
classDef existing fill:#e2e8f0,stroke:#4a5568,stroke-width:1px,color:#000;
classDef peer fill:#CE93D8,stroke:#6A1B9A,stroke-width:1px,color:#000;
class Route,Filter,Grid,Lightbox,InstaContent,PfContent,Lib newpart;
class Insta,Home,Seo,Lhci changed;
class PageIntro,Deferred existing;
class ShootTypes peer;
```
Text alternative: the new route composes PageIntro, a generic filter bar, the new masonry PortfolioGrid (which opens the new Lightbox and reuses DeferredImage and Reveal) and the shared InstagramGrid (also used by the homepage, with its own content); portfolio content references the shoot types delivered by soorten-fotoshoots (purple); filter, grid and lightbox rely on new pure helpers in lib; SEO uses contact-page's webPage() and the Lighthouse config follows the page registry.
- **Primary Component**: `web` (front-end SPA)
- **Shared Components**: `InstagramGrid` (Minor: moved, content type split), `PortfolioGrid`, `Lightbox`, filter bar (new, generic), `lib/` (new helpers), `seo.ts` (Minor: gallery JSON-LD on top of `webPage()`)
- **Dependent Components**: the homepage route (import path and content source of `InstagramGrid` only)
- **Supporting Components**: Lighthouse CI config (Configuration-only), `theme.ts` (possibly one token), LAYOUT.md (documentation)
- **Peer dependencies**: contact-page (`webPage()` commit), soorten-fotoshoots-page (`shootTypes.ts` commit)
### Risk Assessment
- **Risk Level**: Medium — the lightbox (focus trap, inert background, swipe, preloading) and the row-order masonry are the most intricate UI in the site so far; two pieces come from parallel branches
- **Rollback Complexity**: Easy (one branch, commits per unit)
- **Testing Complexity**: Moderate — dialog behaviour in jsdom (focus, keys), URL state, stateful PBT for the lightbox; Lighthouse for a photo-heavy page
## Workflow Visualization
```mermaid
flowchart TD
Start(["User Request"])
subgraph INCEPTION["🔵 INCEPTION PHASE"]
WD["Workspace Detection<br/><b>COMPLETED</b>"]
RE["Reverse Engineering<br/><b>SKIP</b>"]
RA["Requirements Analysis<br/><b>COMPLETED</b>"]
US["User Stories<br/><b>SKIP</b>"]
WP["Workflow Planning<br/><b>IN PROGRESS</b>"]
AD["Application Design<br/><b>EXECUTE</b>"]
UG["Units Generation<br/><b>SKIP</b>"]
end
subgraph CONSTRUCTION["🟢 CONSTRUCTION PHASE"]
FD["Functional Design<br/><b>EXECUTE (units 2 and 3)</b>"]
NFRA["NFR Requirements<br/><b>SKIP</b>"]
NFRD["NFR Design<br/><b>SKIP</b>"]
ID["Infrastructure Design<br/><b>SKIP</b>"]
CG["Code Generation<br/>(Planning + Generation)<br/><b>EXECUTE</b>"]
BT["Build and Test<br/><b>EXECUTE</b>"]
end
Start --> WD
WD --> RA
RA --> WP
WP --> AD
AD --> FD
FD --> CG
CG --> BT
BT --> End(["Complete"])
style WD fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff
style RA fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff
style WP fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff
style CG fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff
style BT fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff
style AD fill:#FFA726,stroke:#E65100,stroke-width:3px,stroke-dasharray: 5 5,color:#000
style FD fill:#FFA726,stroke:#E65100,stroke-width:3px,stroke-dasharray: 5 5,color:#000
style RE fill:#BDBDBD,stroke:#424242,stroke-width:2px,stroke-dasharray: 5 5,color:#000
style US fill:#BDBDBD,stroke:#424242,stroke-width:2px,stroke-dasharray: 5 5,color:#000
style UG fill:#BDBDBD,stroke:#424242,stroke-width:2px,stroke-dasharray: 5 5,color:#000
style NFRA fill:#BDBDBD,stroke:#424242,stroke-width:2px,stroke-dasharray: 5 5,color:#000
style NFRD fill:#BDBDBD,stroke:#424242,stroke-width:2px,stroke-dasharray: 5 5,color:#000
style ID fill:#BDBDBD,stroke:#424242,stroke-width:2px,stroke-dasharray: 5 5,color:#000
style INCEPTION fill:#BBDEFB,stroke:#1565C0,stroke-width:3px,color:#000
style CONSTRUCTION fill:#C8E6C9,stroke:#2E7D32,stroke-width:3px,color:#000
style Start fill:#CE93D8,stroke:#6A1B9A,stroke-width:3px,color:#000
style End fill:#CE93D8,stroke:#6A1B9A,stroke-width:3px,color:#000
linkStyle default stroke:#333,stroke-width:2px
```
Text alternative: completed Workspace Detection and Requirements Analysis lead to Workflow Planning, then Application Design, Functional Design (units 2 and 3), Code Generation per unit and Build and Test; Reverse Engineering, User Stories, Units Generation, NFR Requirements, NFR Design, Infrastructure Design and the Operations phase are skipped.
## Phases to Execute
### 🔵 INCEPTION PHASE
- [x] Workspace Detection (COMPLETED)
- [x] Reverse Engineering (SKIPPED)
- **Rationale**: shared artifacts are current with the over-mij blocks; team agreement that each feature only updates the lines about its own route/components (done during Code Generation)
- [x] Requirements Analysis (COMPLETED)
- [x] User Stories (SKIPPED)
- **Rationale**: one persona (the visitor); concrete FRs with behaviour, texts and edge cases; stories would restate the requirements
- [x] Execution Plan (IN PROGRESS)
- [ ] Application Design - EXECUTE (standard depth)
- **Rationale**: several new shared components need agreed boundaries and props before code, generic enough for other pages: `PortfolioGrid`, `Lightbox`, the filter bar, the moved `InstagramGrid` and its content type, the portfolio content model (two image sizes, `ShootTypeId`), which pure helpers go into `lib/`, where URL state lives (route search params vs. component state), whether the hero's swipe logic is extracted, and how the peer commits slot in
- [ ] Units Generation - SKIP
- **Rationale**: the split is fixed below (three units); no separate unit-of-work artifacts needed
### 🟢 CONSTRUCTION PHASE
- [ ] Functional Design - EXECUTE for units 2 and 3 (standard depth)
- **Rationale**: unit 2 has real logic (filtering, wrap-around navigation, lightbox state machine, masonry spans, preloading) whose rules and properties must be defined first (PBT-01). Unit 3 has the photo proposals (shoot type and alt text per photo, to be approved by the user — clarification 4), the OG photo choice, the `?shoot=` parsing rules and the `ImageGallery` structured data rules. Unit 1 is a behaviour-preserving move with nothing to design beyond Application Design
- [ ] NFR Requirements - SKIP
- **Rationale**: NFRs are set at requirements level (NFR-PF-01..06) and the stack is fixed (no new dependencies)
- [ ] NFR Design - SKIP
- **Rationale**: no new NFR patterns beyond what Application/Functional Design covers; existing ones (DeferredImage, Reveal, theme focus ring, `jsonLdScript`, reduced motion) are reused
- [ ] Infrastructure Design - SKIP
- **Rationale**: static assets only; no server config, CSP or deployment changes
- [ ] Code Generation - EXECUTE (ALWAYS, per unit)
- **Rationale**: implementation and tests
- [ ] Build and Test - EXECUTE (ALWAYS)
- **Rationale**: full `pnpm check` incl. Lighthouse for `/` and `/portfolio`; browser check of the lightbox on desktop and phone
### 🟡 OPERATIONS PHASE
- [ ] Deployment Setup, Monitoring Setup, Production Readiness Validation - SKIP
- **Rationale**: Operations Configuration = No (decided at Requirements Analysis); the existing pipeline deploys to test on merge
## Units of Work (in order)
| # | Unit | Scope | Requirements | Peer dependency |
|---|---|---|---|---|
| 1 | **Shared Instagram block** | Move `InstagramGrid` to `components/InstagramGrid/` with its own `InstagramContent` (`content/instagramContent.ts`); homepage switched over with unchanged output | FR-PF-08, NFR-PF-02 | none |
| 2 | **Gallery building blocks** | Generic `PortfolioGrid` (row-order masonry, eager first N, link fallback), `Lightbox` (dialog, prev/next/wrap, keys, swipe, counter, caption, focus, preloading), generic filter bar; pure helpers in `lib/` with example and property-based tests; arbitraries; possibly a `zIndex` token and an extracted swipe hook. Tested with fixture data; not yet on a page | FR-PF-03, 05, 06, 07; NFR-PF-01..03, 05 | none |
| 3 | **Portfolio page** | 10 photos (download, two sizes, alt texts and shoot types as approved), `portfolioContent.ts` + types; route with intro, filters wired to shoot types and `?shoot=`, grid, lightbox, Instagram; SEO (indexed, `ImageGallery` JSON-LD, `ogImage`, Lighthouse indexed paths); LAYOUT.md; RE lines about `/portfolio` and the new components | FR-PF-01, 02, 04, 09; SEO-PF-01..05; NFR-PF-04, 06 | `webPage()` (contact-page) and `shootTypes.ts` (soorten-fotoshoots), cherry-picked at the start of the unit |
Units 1 and 2 have no peer dependency, so they can be built while the peers' commits are still pending. Unit 3 starts by cherry-picking both peer commits; if either is missing, it stops and reports (no parallel copy). Each unit: one or more commits on `feature/portfolio-page`, full `pnpm check` (incl. Lighthouse) before its completion message; one PR to master at the end. Whichever parallel feature merges first, the others rebase onto master; the hot files (`sitePages.ts`, `lighthouserc*.cjs`, `active-features.md`) only carry each feature's own entries.
## Estimated Timeline
- **Total stages to execute from here**: 7 (Application Design, Functional Design ×2 units, Code Generation ×3 units, Build and Test)
- **Estimated Duration**: two to three working sessions, plus waiting time on the two peer commits before unit 3
## Success Criteria
- **Primary Goal**: a finished, indexed portfolio page with filters and an accessible lightbox, matching the design, with the live photos
- **Key Deliverables**: `/portfolio` page; shared `PortfolioGrid`, `Lightbox`, filter bar and `InstagramGrid`; `portfolioContent.ts` and `instagramContent.ts`; pure helpers with example and property-based tests; 10 photos in two sizes with approved alt texts and a 1200×630 preview image; updated LAYOUT.md, Lighthouse config and RE lines
- **Quality Gates**: `pnpm check` passes (lint, format, tests with coverage thresholds, build, audits, Lighthouse: accessibility 1.0, best practices 1.0, SEO 1.0, performance ≥ 0.9 for `/portfolio`, homepage budgets unchanged); axe clean incl. the open lightbox; homepage output unchanged after unit 1
- **Integration Testing**: route tests render `/` and `/portfolio` in the shell; `/portfolio?shoot=<id>` starts filtered and an invalid value falls back to "Alles"; the lightbox opens from the grid and returns focus; canonical URL has no parameters