Files
AndreaSlopFotografie/aidlc-docs/features/portfolio-page/construction/gallery-blocks/functional-design/frontend-components.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.3 KiB

Frontend Components — Unit 2: Gallery building blocks

Component Hierarchy (unit 2 parts, with the unit 3 parent for context)

graph TD
    Parent["PortfolioGallery (unit 3, owns index)"] --> Filter["FilterBar"]
    Parent --> Grid["PortfolioGrid"]
    Parent --> Lazy["Suspense + lazy Lightbox"]
    Grid --> Tile["tile link per item"]
    Tile --> Deferred["DeferredImage or eager Image"]
    Lazy --> Box["Lightbox"]
    Box --> Dialog["Chakra Dialog"]
    Box --> Figure["figure: image, caption, error message"]
    Box --> Controls["close, previous, next, counter"]
    Box --> Live["live region"]
    Box --> SwipeHook["useSwipe"]
    Hero["Hero / useHeroSlider"] --> SwipeHook
    classDef root fill:#4CAF50,stroke:#2e7d32,color:#000;
    classDef ui fill:#2196F3,stroke:#0d47a1,color:#000;
    classDef hook fill:#9C27B0,stroke:#4a148c,color:#000;
    class Parent root;
    class Filter,Grid,Tile,Deferred,Lazy,Box,Dialog,Figure,Controls,Live,Hero ui;
    class SwipeHook hook;

Text alternative: the unit 3 parent renders the FilterBar, the PortfolioGrid with one link tile per item, and the lazily loaded Lightbox inside Suspense; the Lightbox wraps a Chakra Dialog with the figure, the controls and a live region and uses useSwipe, which the hero also uses.

PortfolioGrid

  • Props: items: readonly GalleryItem[], eagerCount = 3, onOpen(index), onIntent?(), 'data-testid'? (default portfolio-grid)
  • State: none except a ref "intent already reported"
  • Markup: wrapper with container-type: inline-size; ul grid (columns per BR-GR-02, grid-auto-rows = column width / 40 via cqi); li with gridRowEnd: span {masonryRowSpan}; a (data-testid="portfolio-tile-{n}", 1-based) → image (Image with fetchPriority="high" for n ≤ eagerCount, else DeferredImage) + VisuallyHidden " (groot bekijken)"
  • Styling: overlay via _after, zoom via _groupHover/_groupFocusVisible like InstagramGrid; _motionReduce removes zoom; Reveal around the list (not per tile, so a filter change does not replay fades — BR-GR-09)

Lightbox

  • Props: items, index: number | null, onIndexChange(index), onClose(), label = 'Foto groot bekijken', finalFocusEl?: () => HTMLElement | null
  • Internal state: loaded/failed for the current full image (reset on index change); announcement text
  • Markup: Dialog.Root (controlled open={index !== null}, onOpenChange → onClose, initialFocusEl → close button, finalFocusEl), Dialog.Backdrop (dark), Dialog.Positioner → Dialog.Content (data-testid="lightbox") with: figure (image, figcaption with caption or the error message), close button (lightbox-close), previous (lightbox-prev), next (lightbox-next), counter (lightbox-counter), visually hidden live region (aria-live="polite")
  • Buttons: iconControl recipe on the dark backdrop (white, focus ring white), 44 px min; labels "Sluiten", "Vorige foto", "Volgende foto"; icons from @iconify-icons/ant-design (already a dependency)
  • Keyboard: per the decision flow in business-rules (Escape via Chakra)
  • Swipe: useSwipe handlers on the figure
  • Preloading: new Image().src = full.src for neighbourIndexes(index, count, 2) while open
  • Theme: a new duration token swap (0.3 s) for the crossfade; the dialog's z-index from Chakra's modal layer, above the header (verified in tests/visually)

FilterBar

  • Props: options: readonly FilterOption[], value: string, onChange(id), label: string
  • Markup: div role="group" aria-label={label} (data-testid="filter-bar") → button type="button" aria-pressed per option (data-testid="filter-{id}")
  • Styling: new recipe filterControl (eyebrow text style, pressed state per BR-FB-05)

useSwipe

  • Signature: useSwipe({ onPrev, onNext, enabled = true }) → { onTouchStart, onTouchEnd }
  • State: a ref with the start point

Accessibility Summary

Element Name Role/state
Grid tile alt + " (groot bekijken)" link
Lightbox "Foto groot bekijken" dialog, modal
Lightbox buttons "Sluiten", "Vorige foto", "Volgende foto" button
Counter visible "3 / 10" text (announcement carries "Foto 3 van 10")
Live region — aria-live="polite": position + caption, or the load error
Filter group prop label group of buttons with aria-pressed