Files
AndreaSlopFotografie/aidlc-docs/features/portfolio-page/construction/gallery-blocks/functional-design/business-rules.md
T
SluijsensandClaude Opus 5.5 18bf0311ef 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>
2026-10-25 23:22:43 +01:00

7.0 KiB
Raw Blame History

Business Rules — Unit 2: Gallery building blocks

Decisions: 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 href={full.src}>. 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

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.