# Business Logic Model — Unit 2: Gallery building blocks ## Flow — open, browse, close ```mermaid 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. ```mermaid 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); `|span − gapRows − K·h/w| ≤ 0.5` (easy verification) | | `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)` uses `wrapIndex(to, count)` instead of `(to + count) % count` (same results for the values it receives). - Its inline `onTouchStart`/`onTouchEnd` are replaced by `useSwipe({ onPrev: prev, onNext: next, enabled: count > 1 })`. Existing hero tests must pass unchanged (oracle: today's behaviour).