Files
AndreaSlopFotografie/aidlc-docs/features/portfolio-page/construction/gallery-blocks/functional-design/business-logic-model.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

4.5 KiB
Raw Blame History

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) 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).