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>
4.5 KiB
Business Logic Model — Unit 2: Gallery building blocks
Flow — open, browse, close
sequenceDiagram
box rgba(246,224,94,0.4) Visitor
participant V as Visitor
end
box rgba(99,179,237,0.4) Components
participant G as PortfolioGrid
participant P as Parent
participant L as Lightbox
end
V->>G: hover or focus a tile
G->>P: onIntent once
P->>P: start loading the lightbox code
V->>G: click tile n
G->>P: onOpen with index n
P->>L: render with index n
L->>L: focus close button, show thumb, load full, preload two each side
V->>L: arrow, Home, End or swipe
L->>P: onIndexChange with the wrapped index
L->>V: announce position and caption
V->>L: Escape, close button or backdrop
L->>P: onClose
P->>G: focus the tile of the last shown item
Text alternative: hovering or focusing a tile asks the parent to load the lightbox code; clicking a tile opens the lightbox at that index; the lightbox focuses its close button, shows the thumb while the large image and its neighbours load; browsing reports the wrapped index to the parent and announces the position; closing returns focus to the tile of the last shown item.
Lightbox State Machine
The parent owns the state (application design: PortfolioGallery owns the open item). A pure reducer lightboxReducer(state, event) makes the transitions testable.
graph TD
Closed["closed"] -->|"open(i, count), count at least 1"| Open["open at index i"]
Open -->|"next / prev"| Open
Open -->|"first / last"| Open
Open -->|"close"| Closed
Open -->|"listChanged(count)"| Closed
Closed -->|"next, prev, first, last, close, listChanged"| Closed
classDef state fill:#2196F3,stroke:#0d47a1,color:#000;
class Closed,Open state;
Text alternative: a closed lightbox opens at an index when the list is not empty; while open, next/prev/first/last stay open at a new index and close or a list change closes it; every other event leaves a closed lightbox closed.
Rules: open(i, count) clamps i into range with wrapIndex; count = 0 keeps it closed. next/prev use wrapIndex(index ± 1, count); first → 0; last → count − 1.
Pure Helpers and Testable Properties (PBT-01)
All in web/src/lib/, 100% coverage threshold, example-based tests plus property-based tests with generators in src/test/arbitraries.ts (PBT-07).
| Helper | Purpose | Properties (category) |
|---|---|---|
wrapIndex(index, count) |
Position in 0..count−1, wrapping both ways |
Result in range for any integer index and count ≥ 1 (invariant); wrapIndex(wrapIndex(i)+1)−1 returns to wrapIndex(i) (round-trip); wrapIndex(i + k·count) = wrapIndex(i) (invariant, periodicity); wrapIndex(wrapIndex(i)) = wrapIndex(i) (idempotence); equals ((i % c) + c) % c (oracle) |
swipeDirection(start, end, threshold = 50) |
'next', 'prev' or null |
Mirroring dx flips next ↔ prev (invariant); below threshold or more vertical than horizontal → null (invariant); translating both points by the same offset does not change the result (invariant) |
masonryRowSpan({ width, height }, K = 40, gapRows = 2) |
Implicit rows an item spans | Always ≥ gapRows + 1 (range); non-decreasing in height/width (invariant, monotonic); scaling width and height by the same factor gives the same span (invariant); ` |
neighbourIndexes(index, count, radius = 2) |
Large images to preload | No duplicates, never contains index, all in range (invariant); size = min(2·radius, count − 1) (invariant); symmetric: contains wrapIndex(index ± d) for d ≤ radius when count is large enough (oracle against a brute-force set) |
lightboxReducer(state, event) |
Lightbox transitions | Stateful PBT: random event sequences against a simple model ({open, index} with modular arithmetic) — after every event the states match and an open index is in range (PBT-06) |
Components with no extra properties beyond these helpers: PortfolioGrid, Lightbox, FilterBar (presentational; example-based tests and axe cover them — PBT-10 complementary).
Hero Refactor
useHeroSlider.go(to)useswrapIndex(to, count)instead of(to + count) % count(same results for the values it receives).- Its inline
onTouchStart/onTouchEndare replaced byuseSwipe({ onPrev: prev, onNext: next, enabled: count > 1 }). Existing hero tests must pass unchanged (oracle: today's behaviour).