# Business Rules — Unit 2: Gallery building blocks Decisions: [gallery-blocks-fd-questions.md](../../plans/gallery-blocks-fd-questions.md) (answered 2026-10-25), requirements FR-PF-03, 05–07, NFR-PF-01/02/05, application design Q1–Q7. ## Grid (`PortfolioGrid`) - **BR-GR-01 Order**: items render in the given order as `ul > li`; DOM, tab and reading order follow it (row order, left to right). - **BR-GR-02 Columns**: 1 column on phones, 2 from `md`, 3 from `lg` (the design's 2/3 steps on the theme breakpoints); column gap `gridGap`. - **BR-GR-03 Row span**: each item spans `masonryRowSpan(thumb) = round(K × height / width) + GAP_ROWS` implicit rows, with implicit row height = column width / K (container units). The photo fills the item minus the gap rows with `object-fit: cover`; the crop from rounding is at most half a row (≤ 1.25% of the height). No JavaScript measuring (Q6/6a). - **BR-GR-04 Loading**: the first `EAGER_COUNT` (3) items of the list as given load immediately with `fetchPriority="high"`; the rest use `DeferredImage`. Intrinsic width/height on every image. - **BR-GR-05 Tile = link**: each tile is ``. A plain click or Enter calls `onOpen(index)` and prevents navigation. A click with Ctrl/Cmd/Shift/Alt or the middle button is left to the browser (opens the large image as a normal link). Without JavaScript the link opens the large image. - **BR-GR-06 Name**: accessible name = alt text + " (groot bekijken)" (visually hidden suffix). *Q6 = A* - **BR-GR-07 Intent**: the first pointer enter or focus on any tile calls `onIntent()` once per mount (preload the lightbox code). - **BR-GR-08 Hover/focus**: zoom 1.05 + dark overlay (design `.portfolio-item`), `cursor: zoom-in`; under reduced motion no zoom, overlay only. The focus ring sits above neighbouring tiles. - **BR-GR-09 List change**: when the list changes (another filter), tiles swap immediately without animation; tiles that were never in view show at once (no fade-in replay). *Q9 = A* - **BR-GR-10 Empty list**: renders an empty list (no tiles, no error); the page decides whether to show the grid at all. ## Lightbox (`Lightbox`) - **BR-LB-01 Dialog**: Chakra `Dialog`, modal, named "Foto groot bekijken" (overridable); background inert, page does not scroll; dark backdrop. - **BR-LB-02 Image**: the current item's `full` image, whole (`object-fit: contain`), within the viewport; alt text from `thumb.alt`. - **BR-LB-03 Navigation**: next/previous wrap around (`wrapIndex`); Home → first, End → last (*Q10 = A*); ← → as previous/next; swipe left = next, swipe right = previous (`swipeDirection`, threshold 50 px, |dx| ≥ |dy|). No swipe-down to close (*Q4 = A*). - **BR-LB-04 Closing**: close button, Escape, click on the backdrop. Click/tap on the image itself does nothing (*Q3 = A*). - **BR-LB-05 Controls layout**: phones: bottom bar "vorige · teller · volgende", close top right; from `md`: previous/next at the left and right edges halfway, close top right, counter under the image (design). Controls never cover the image on phones. All targets ≥ 44 × 44 px. *Q2 = A* - **BR-LB-06 Counter and caption**: counter "n / total" (1-based); caption = `item.caption` when present. With one item: no previous/next, no counter, no Home/End/arrow handling. - **BR-LB-07 Announcement**: after every navigation (not on open), a polite live region says "Foto n van total" plus ", {caption}" when there is a caption. *Q5 = A* - **BR-LB-08 Focus**: on open, focus goes to the close button; Tab cycles inside the dialog; on close, focus returns to the grid tile of the item shown last (via the parent's `finalFocus`). - **BR-LB-09 List change while open**: if the list changes (another filter) while open, the lightbox closes (the parent resets `index` to `null`). The state reducer treats `listChanged` the same way. - **BR-LB-10 Transition**: a short crossfade (~0.3 s) on open, close and item change; none under `prefers-reduced-motion`. *Q1 = A* - **BR-LB-11 Loading**: while the large image loads, the thumb (already cached) is shown in its place at the same size; no empty flash, no layout jump. - **BR-LB-12 Load error**: if the large image fails, the thumb stays and a short message "Deze foto kon niet groot geladen worden" appears under it (in the caption area, polite live region); browsing keeps working and the message disappears on the next item. *Q7 = B* - **BR-LB-13 Preloading**: while open, the large images of up to `PRELOAD_RADIUS` (2) items on each side (wrapping, no duplicates, never the current one) are requested. *Q8 = B* ## Filter bar (`FilterBar`) - **BR-FB-01 Options**: one toggle button per option in the given order; exactly one is pressed (`aria-pressed="true"`), the one whose `id` equals `value`. - **BR-FB-02 Group**: `role="group"` with an accessible name (prop `label`); every button is a tab stop. - **BR-FB-03 Fewer than two options**: render nothing. - **BR-FB-04 Choosing**: clicking (or Enter/Space on) a button that is not pressed calls `onChange(id)`; clicking the pressed one does nothing. Focus stays on the button. - **BR-FB-05 Style**: eyebrow text style; pressed = `accent.deep` with a 2 px underline; others `ink.soft`; hover darkens to `ink`. Contrast ≥ 4.5:1 for text, ≥ 3:1 for the underline against `paper`. Targets ≥ 44 px high. - **BR-FB-06 Unknown value**: if `value` matches no option, no button is pressed (the page must pass a valid value; unit 3 guarantees it). ## Swipe (`useSwipe`, `swipeDirection`) - **BR-SW-01**: a swipe counts when |dx| ≥ 50 px and |dx| ≥ |dy|; dx < 0 → `next`, dx > 0 → `prev`; otherwise nothing. - **BR-SW-02**: a touch end without a recorded start does nothing; the start is cleared after every touch end. - **BR-SW-03 Hero**: `useHeroSlider` uses `useSwipe` and `wrapIndex`; its swipe and wrap behaviour are unchanged (existing hero tests pass unchanged). The hero keeps its own rule that swiping does nothing with fewer than two slides (`enabled`). ## Decision Flow — a key press in the open lightbox ```mermaid graph TD Key["Key press"] --> Esc{"Escape?"} Esc -->|"yes"| Close["Close (Chakra)"] Esc -->|"no"| Many{"More than one item?"} Many -->|"no"| Ignore["Ignore"] Many -->|"yes"| Which{"Which key?"} Which -->|"ArrowRight"| Next["wrapIndex(index + 1)"] Which -->|"ArrowLeft"| Prev["wrapIndex(index - 1)"] Which -->|"Home"| First["index 0"] Which -->|"End"| Last["index count - 1"] Which -->|"other"| Ignore Next --> Announce["Announce position and caption"] Prev --> Announce First --> Announce Last --> Announce classDef decision fill:#FF9800,stroke:#e65100,color:#000; classDef action fill:#2196F3,stroke:#0d47a1,color:#000; classDef stop fill:#e2e8f0,stroke:#4a5568,color:#000; class Esc,Many,Which decision; class Close,Next,Prev,First,Last,Announce action; class Ignore stop; ``` Text alternative: Escape always closes; with a single item other keys are ignored; otherwise the arrow keys wrap to the next or previous item, Home and End jump to the first and last, any other key is ignored, and every move is announced with position and caption.