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,68 @@
# Application Design — Portfolio Page
Consolidated view of [components.md](components.md), [component-methods.md](component-methods.md), [services.md](services.md) and [component-dependency.md](component-dependency.md). Decisions: [application-design-plan.md](../plans/application-design-plan.md).
## Decisions
| # | Decision |
|---|---|
| Q1 | Three independent shared pieces (`PortfolioGrid`, `Lightbox`, `FilterBar`) connected by a page-specific `PortfolioGallery` in `components/portfolio/` |
| Q2 | Filter bar = group of toggle buttons with `aria-pressed`, one tab stop per button |
| Q3 | Filter style = text links in eyebrow style, active underlined in `accent.deep` (new recipe) |
| Q4 | Filter changes replace the URL (no history entry per change) |
| Q5 | Swipe logic extracted from the hero into `useSwipe` + `lib/swipeDirection`; hero behaviour unchanged |
| Q6 + 6a | CSS-only masonry in row order (row spans from the aspect ratio, container units); no preparation for JS measuring — rebuild later if ever needed |
| Q7 | `Lightbox` loaded lazily on first open or on tile hover/focus |
| — | Names as agreed with the parallel sessions; generic APIs; generic `GalleryItem` so shared components never see shoot types |
## Component Overview
```mermaid
graph TD
Route["routes/portfolio.tsx"] --> Intro["PageIntro"]
Route --> Gallery["portfolio/PortfolioGallery"]
Route --> Insta["InstagramGrid (shared)"]
Gallery --> Section["PageSection"]
Gallery --> Filter["FilterBar"]
Gallery --> Grid["PortfolioGrid"]
Gallery --> Box["Lightbox (lazy)"]
Grid --> Deferred["DeferredImage + Reveal"]
Box --> Dialog["Chakra Dialog"]
Box --> Swipe["useSwipe"]
Hero["Hero / useHeroSlider"] --> Swipe
Home["routes/index.tsx"] --> Insta
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;
class Gallery,Filter,Grid,Box,Swipe newpart;
class Route,Insta,Hero,Home changed;
class Intro,Section,Deferred,Dialog existing;
```
Text alternative: the portfolio route renders PageIntro, the page-specific PortfolioGallery and the shared InstagramGrid; the gallery composes PageSection, FilterBar, PortfolioGrid and the lazily loaded Lightbox; the grid reuses DeferredImage and Reveal, the lightbox builds on Chakra Dialog and the new useSwipe hook, which the hero also adopts; the homepage uses the moved InstagramGrid.
## Per Unit
| Unit | New | Changed |
|---|---|---|
| 1 Shared Instagram block | `content/instagramContent.ts`, `InstagramContent` | `InstagramGrid` moved, `homeContent` (instagram removed), homepage route |
| 2 Gallery building blocks | `PortfolioGrid`, `Lightbox`, `FilterBar`, `useSwipe`, recipe `filterControl`, `GalleryItem`/`ImageSource`, `lib/{wrapIndex, swipeDirection, masonryRowSpan, neighbourIndexes}`, arbitraries, possibly a `zIndex.lightbox` token | `useHeroSlider` (uses `useSwipe` and `wrapIndex`) |
| 3 Portfolio page | `PortfolioGallery`, `portfolioContent.ts`, `PortfolioPhoto`/`PortfolioContent`, `lib/{shootTypesWithPhotos, shootFromSearch, filterPhotos, filterOptions, toGalleryItems, photoCountLabel}`, `galleryImages` in `seo.ts`, 10 photos ×2, `og-portfolio.jpg` | portfolio route, `sitePages.ts`, `lighthouserc*.cjs`, LAYOUT.md, RE lines about `/portfolio` |
## State and Data Flow (summary)
- The **URL** owns the active filter (`?shoot=`, typed and allowlisted, replace navigation); **`PortfolioGallery`** owns which photo is open; everything else is derived by pure helpers.
- Shared components get data and report events through props; none import page content.
- See [services.md](services.md) and [component-dependency.md](component-dependency.md) for the flow diagram and the peer dependencies.
## Extension Compliance — Application Design
| Rule | Status | Note |
|---|---|---|
| SECURITY-04 headers | Compliant | No CSP change; no external resources |
| SECURITY-05 input validation | Compliant | `?shoot=` allowlisted in `validateSearch` and `shootFromSearch`; never rendered |
| SECURITY-10 supply chain | Compliant | No new dependency (Chakra `Dialog` is already in `@chakra-ui/react`) |
| SECURITY-11 secure design | Compliant | Misuse case (crafted parameter) handled by allowlist + fallback |
| SECURITY-13 integrity | Compliant | Lazy chunk is our own bundle; no CDN |
| Other SECURITY rules | N/A | No data stores, auth, server or infrastructure |
| PBT-01 | Planned | Every pure helper above is listed for property identification in Functional Design (units 2 and 3) |
| PBT-06 | Planned | Open-index state in `PortfolioGallery` + `Lightbox` navigation modelled in Functional Design |
| PBT-07 | Planned | Generators for `GalleryItem`, `PortfolioPhoto`, `ShootType` in `src/test/arbitraries.ts` |
| PBT-08 / 09 | Compliant | Existing seed logging and fast-check |
| Other PBT rules | Planned at Functional Design / Code Generation | |