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:
2026-10-25 23:22:43 +01:00
co-authored by Claude Opus 5.5
parent e013f1436b
commit 18bf0311ef
38 changed files with 2392 additions and 43 deletions
@@ -0,0 +1,66 @@
# Domain Entities — Unit 2: Gallery building blocks
Generic entities only; nothing here knows about shoot types, filters on the portfolio, or the URL (that is unit 3).
## Relationships
```mermaid
graph TD
Item["GalleryItem"] -->|"thumb"| Thumb["ContentImage (grid size, alt)"]
Item -->|"full"| Full["ImageSource (lightbox size)"]
Item -->|"caption?"| Caption["visible caption text"]
Grid["PortfolioGrid"] -->|"shows list of"| Item
Box["Lightbox"] -->|"shows one of"| Item
Box -->|"driven by"| State["LightboxState"]
Filter["FilterBar"] -->|"offers list of"| Option["FilterOption"]
Swipe["useSwipe"] -->|"compares"| Points["two Points"]
classDef entity fill:#2196F3,stroke:#0d47a1,color:#000;
classDef comp fill:#4CAF50,stroke:#2e7d32,color:#000;
classDef value fill:#e2e8f0,stroke:#4a5568,color:#000;
class Item,State,Option entity;
class Grid,Box,Filter,Swipe comp;
class Thumb,Full,Caption,Points value;
```
Text alternative: a GalleryItem has a grid image with alt text, a large image and an optional caption; the grid shows a list of items, the lightbox shows one item at a time driven by a LightboxState; the filter bar offers FilterOptions; useSwipe compares two touch points.
## Entities
### GalleryItem
| Field | Type | Rule |
|---|---|---|
| `id` | `string` | Unique within a list; used as React key and test id suffix |
| `thumb` | `ContentImage` (`src`, `alt`, `width`, `height`) | Grid size (~800 px wide), photo's own aspect ratio; `alt` is the description for both sizes |
| `full` | `ImageSource` (`src`, `width`, `height`) | Lightbox size (~1600–2000 px); same aspect ratio as `thumb` (± rounding) |
| `caption?` | `string` | Visible under the large image; empty or missing → no caption element |
### ImageSource
`{ src: string; width: number; height: number }` — `width`, `height` positive integers (intrinsic size).
### FilterOption
| Field | Type | Rule |
|---|---|---|
| `id` | `string` | Unique within the options |
| `label` | `string` | Visible text (Dutch) |
### LightboxState
A closed lightbox, or an open one at a position in the current list.
| Variant | Shape | Meaning |
|---|---|---|
| closed | `{ open: false }` | No dialog |
| open | `{ open: true; index: number; count: number }` | Showing item `index` of a list of `count` (0 ≤ index < count, count ≥ 1) |
Events: `open(index, count)`, `next`, `prev`, `first`, `last`, `close`, `listChanged(count)` (see business-rules BR-LB-09).
### Point
`{ x: number; y: number }` — a touch position in CSS pixels (start and end of a swipe).
### Masonry dimensions
| Name | Value | Meaning |
|---|---|---|
| `ROWS_PER_COLUMN_WIDTH` (K) | 40 | One implicit grid row is 1/40 of the column width |
| `GAP_ROWS` | 2 | Vertical gap between photos, in rows (≈ 5% of the column width) |
| `EAGER_COUNT` | 3 | First items in the list that load immediately |
| `PRELOAD_RADIUS` | 2 | Large images preloaded on each side of the current one |
| `SWIPE_THRESHOLD` | 50 px | Minimum horizontal travel for a swipe (same as the hero today) |