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>
This commit is contained in:
2026-10-25 23:22:43 +01:00
co-authored by Claude Opus 5.5
parent e013f1436b
commit 18bf0311ef
38 changed files with 2392 additions and 43 deletions
+130
View File
@@ -0,0 +1,130 @@
import fc from 'fast-check';
import { describe, expect, it } from 'vitest';
import { lightboxEvent } from '../test/arbitraries';
import {
closedLightbox,
type LightboxEvent,
lightboxReducer,
type LightboxState,
} from './lightboxReducer';
const open = (index: number, count: number): LightboxState => ({
open: true,
index,
count,
});
describe('lightboxReducer', () => {
it('opens at the chosen photo', () => {
expect(
lightboxReducer(closedLightbox, {
type: 'open',
index: 2,
count: 5,
}),
).toEqual(open(2, 5));
});
it('stays closed when there are no photos', () => {
expect(
lightboxReducer(closedLightbox, {
type: 'open',
index: 0,
count: 0,
}),
).toEqual(closedLightbox);
});
it('wraps around when browsing past either end', () => {
expect(lightboxReducer(open(4, 5), { type: 'next' })).toEqual(
open(0, 5),
);
expect(lightboxReducer(open(0, 5), { type: 'prev' })).toEqual(
open(4, 5),
);
});
it('jumps to the first and the last photo', () => {
expect(lightboxReducer(open(3, 5), { type: 'first' })).toEqual(
open(0, 5),
);
expect(lightboxReducer(open(1, 5), { type: 'last' })).toEqual(
open(4, 5),
);
});
it('closes on close and when the list changes', () => {
expect(lightboxReducer(open(1, 5), { type: 'close' })).toEqual(
closedLightbox,
);
expect(
lightboxReducer(open(1, 5), { type: 'listChanged', count: 3 }),
).toEqual(closedLightbox);
});
it('ignores browsing while closed', () => {
for (const type of [
'next',
'prev',
'first',
'last',
'close',
] as const) {
expect(lightboxReducer(closedLightbox, { type })).toBe(
closedLightbox,
);
}
});
// Stateful property: any sequence of events gives the same result as a
// simple model that counts positions on a clock face
it('follows the model for any sequence of events (stateful)', () => {
type Model = { open: boolean; index: number; count: number };
const step = (model: Model, event: LightboxEvent): Model => {
if (event.type === 'open') {
return event.count < 1
? { open: false, index: 0, count: 0 }
: {
open: true,
index:
((event.index % event.count) + event.count) %
event.count,
count: event.count,
};
}
if (!model.open) return model;
if (event.type === 'next')
return { ...model, index: (model.index + 1) % model.count };
if (event.type === 'prev')
return {
...model,
index: (model.index + model.count - 1) % model.count,
};
if (event.type === 'first') return { ...model, index: 0 };
if (event.type === 'last')
return { ...model, index: model.count - 1 };
return { open: false, index: 0, count: 0 };
};
fc.assert(
fc.property(
fc.array(lightboxEvent, { maxLength: 40 }),
(events) => {
let state: LightboxState = closedLightbox;
let model: Model = { open: false, index: 0, count: 0 };
for (const event of events) {
state = lightboxReducer(state, event);
model = step(model, event);
expect(state.open).toBe(model.open);
if (state.open) {
expect(state.index).toBe(model.index);
expect(state.count).toBe(model.count);
expect(state.index).toBeGreaterThanOrEqual(0);
expect(state.index).toBeLessThan(state.count);
}
}
},
),
);
});
});
+49
View File
@@ -0,0 +1,49 @@
import { wrapIndex } from './wrapIndex';
// Whether the lightbox is open, and if so which photo of how many it shows
export type LightboxState =
{ open: false } | { open: true; index: number; count: number };
export type LightboxEvent =
| { type: 'open'; index: number; count: number }
| { type: 'next' }
| { type: 'prev' }
| { type: 'first' }
| { type: 'last' }
| { type: 'close' }
// The list of photos changed, e.g. another filter: the photo on screen
// may no longer be in it, so the lightbox closes
| { type: 'listChanged'; count: number };
export const closedLightbox: LightboxState = { open: false };
// The lightbox's transitions (functional design, state machine). Browsing
// wraps around; anything but opening leaves a closed lightbox closed.
export function lightboxReducer(
state: LightboxState,
event: LightboxEvent,
): LightboxState {
if (event.type === 'open') {
if (event.count < 1) return closedLightbox;
return {
open: true,
index: wrapIndex(event.index, event.count),
count: event.count,
};
}
if (!state.open) return state;
switch (event.type) {
case 'next':
return { ...state, index: wrapIndex(state.index + 1, state.count) };
case 'prev':
return { ...state, index: wrapIndex(state.index - 1, state.count) };
case 'first':
return { ...state, index: 0 };
case 'last':
return { ...state, index: state.count - 1 };
case 'close':
case 'listChanged':
return closedLightbox;
}
}
+80
View File
@@ -0,0 +1,80 @@
import fc from 'fast-check';
import { describe, expect, it } from 'vitest';
import { imageSize } from '../test/arbitraries';
import {
GAP_ROWS,
masonryRowSpan,
ROWS_PER_COLUMN_WIDTH,
} from './masonryRowSpan';
const K = ROWS_PER_COLUMN_WIDTH;
describe('masonryRowSpan', () => {
it('spans rows by aspect ratio plus the gap', () => {
// Portrait 2:3, landscape 3:2, square
expect(masonryRowSpan({ width: 800, height: 1200 })).toBe(
60 + GAP_ROWS,
);
expect(masonryRowSpan({ width: 1200, height: 800 })).toBe(
27 + GAP_ROWS,
);
expect(masonryRowSpan({ width: 800, height: 800 })).toBe(40 + GAP_ROWS);
});
it('gives even a very wide photo at least one row', () => {
expect(masonryRowSpan({ width: 10000, height: 10 })).toBe(1 + GAP_ROWS);
});
it('is at least one row plus the gap (invariant)', () => {
fc.assert(
fc.property(imageSize, (size) => {
expect(masonryRowSpan(size)).toBeGreaterThanOrEqual(
GAP_ROWS + 1,
);
}),
);
});
it('grows with the photo height relative to its width (invariant)', () => {
fc.assert(
fc.property(imageSize, imageSize, (a, b) => {
const ratioA = a.height / a.width;
const ratioB = b.height / b.width;
if (ratioA <= ratioB) {
expect(masonryRowSpan(a)).toBeLessThanOrEqual(
masonryRowSpan(b),
);
}
}),
);
});
it('depends on the shape, not the file size (invariant)', () => {
fc.assert(
fc.property(
imageSize,
fc.integer({ min: 2, max: 4 }),
(size, factor) => {
expect(
masonryRowSpan({
width: size.width * factor,
height: size.height * factor,
}),
).toBe(masonryRowSpan(size));
},
),
);
});
it('crops at most half a row (easy verification)', () => {
fc.assert(
fc.property(imageSize, (size) => {
const exact = (K * size.height) / size.width;
if (exact >= 1) {
const rows = masonryRowSpan(size) - GAP_ROWS;
expect(Math.abs(rows - exact)).toBeLessThanOrEqual(0.5);
}
}),
);
});
});
+22
View File
@@ -0,0 +1,22 @@
// The masonry grid is a CSS grid with very small implicit rows: one row is
// 1/ROWS_PER_COLUMN_WIDTH of the column width, so a photo's height in rows
// follows from its aspect ratio alone, at any screen width. No measuring in
// the browser, so nothing shifts while photos load.
export const ROWS_PER_COLUMN_WIDTH = 40;
// Vertical space between two photos, in rows (about 5% of the column width)
export const GAP_ROWS = 2;
// How many implicit rows a photo spans: its height at the column width, in
// rows, plus the gap below it. Rounding crops at most half a row.
export function masonryRowSpan(
image: { width: number; height: number },
rowsPerColumnWidth: number = ROWS_PER_COLUMN_WIDTH,
gapRows: number = GAP_ROWS,
): number {
const photoRows = Math.max(
1,
Math.round((rowsPerColumnWidth * image.height) / image.width),
);
return photoRows + gapRows;
}
+56
View File
@@ -0,0 +1,56 @@
import fc from 'fast-check';
import { describe, expect, it } from 'vitest';
import { neighbourIndexes } from './neighbourIndexes';
import { wrapIndex } from './wrapIndex';
// A list position together with the list length it belongs to
const position = fc.integer({ min: 1, max: 30 }).chain((count) =>
fc.record({
count: fc.constant(count),
index: fc.integer({ min: 0, max: count - 1 }),
radius: fc.integer({ min: 0, max: 4 }),
}),
);
describe('neighbourIndexes', () => {
it('lists the two photos on each side, nearest first', () => {
expect(neighbourIndexes(5, 10)).toEqual([6, 4, 7, 3]);
expect(neighbourIndexes(0, 10)).toEqual([1, 9, 2, 8]);
});
it('lists each photo once in a short list', () => {
expect(neighbourIndexes(0, 1)).toEqual([]);
expect(neighbourIndexes(0, 2)).toEqual([1]);
expect(neighbourIndexes(1, 3)).toEqual([2, 0]);
});
it('never repeats a photo or includes the current one (invariant)', () => {
fc.assert(
fc.property(position, ({ index, count, radius }) => {
const result = neighbourIndexes(index, count, radius);
expect(new Set(result).size).toBe(result.length);
expect(result).not.toContain(index);
for (const i of result) {
expect(i).toBeGreaterThanOrEqual(0);
expect(i).toBeLessThan(count);
}
expect(result).toHaveLength(Math.min(2 * radius, count - 1));
}),
);
});
it('matches all positions within the radius (oracle)', () => {
fc.assert(
fc.property(position, ({ index, count, radius }) => {
const expected = new Set<number>();
for (let d = -radius; d <= radius; d++) {
expected.add(wrapIndex(index + d, count));
}
expected.delete(index);
expect(new Set(neighbourIndexes(index, count, radius))).toEqual(
expected,
);
}),
);
});
});
+24
View File
@@ -0,0 +1,24 @@
import { wrapIndex } from './wrapIndex';
// The positions around `index` whose large photos the lightbox loads ahead,
// nearest first and alternating next/previous (next, previous, next+1, …).
// The list wraps around, so in a short list each photo appears once and the
// current one never.
export function neighbourIndexes(
index: number,
count: number,
radius: number = 2,
): number[] {
const result: number[] = [];
for (let distance = 1; distance <= radius; distance++) {
for (const candidate of [
wrapIndex(index + distance, count),
wrapIndex(index - distance, count),
]) {
if (candidate !== index && !result.includes(candidate)) {
result.push(candidate);
}
}
}
return result;
}
+63
View File
@@ -0,0 +1,63 @@
import fc from 'fast-check';
import { describe, expect, it } from 'vitest';
import { point } from '../test/arbitraries';
import { SWIPE_THRESHOLD, swipeDirection } from './swipeDirection';
const origin = { x: 200, y: 300 };
describe('swipeDirection', () => {
it('reads a swipe to the left as next and to the right as previous', () => {
expect(swipeDirection(origin, { x: 120, y: 310 })).toBe('next');
expect(swipeDirection(origin, { x: 280, y: 290 })).toBe('prev');
});
it('ignores short and mostly vertical touches', () => {
expect(swipeDirection(origin, { x: 160, y: 300 })).toBeNull();
expect(swipeDirection(origin, { x: 120, y: 420 })).toBeNull();
expect(swipeDirection(origin, origin)).toBeNull();
});
it('counts a swipe of exactly the threshold', () => {
expect(
swipeDirection(origin, { x: origin.x - SWIPE_THRESHOLD, y: 300 }),
).toBe('next');
});
it('flips direction when the swipe is mirrored (invariant)', () => {
fc.assert(
fc.property(point, point, (start, end) => {
const mirrored = { x: 2 * start.x - end.x, y: end.y };
const flip = { next: 'prev', prev: 'next' } as const;
const result = swipeDirection(start, end);
expect(swipeDirection(start, mirrored)).toBe(
result === null ? null : flip[result],
);
}),
);
});
it('does not depend on where on the screen the swipe happens (invariant)', () => {
fc.assert(
fc.property(point, point, point, (start, end, offset) => {
const moved = (p: { x: number; y: number }) => ({
x: p.x + offset.x,
y: p.y + offset.y,
});
expect(swipeDirection(moved(start), moved(end))).toBe(
swipeDirection(start, end),
);
}),
);
});
it('is no swipe when too short or more vertical than horizontal (invariant)', () => {
fc.assert(
fc.property(point, point, (start, end) => {
const dx = Math.abs(end.x - start.x);
const dy = Math.abs(end.y - start.y);
const result = swipeDirection(start, end);
expect(result === null).toBe(dx < SWIPE_THRESHOLD || dx < dy);
}),
);
});
});
+21
View File
@@ -0,0 +1,21 @@
export interface Point {
x: number;
y: number;
}
// Minimum horizontal travel in px before a touch counts as a swipe
export const SWIPE_THRESHOLD = 50;
// Which way a touch from `start` to `end` browses: a swipe to the left shows
// the next photo, to the right the previous one. Too short, or more vertical
// than horizontal (the visitor is scrolling), is no swipe.
export function swipeDirection(
start: Point,
end: Point,
threshold: number = SWIPE_THRESHOLD,
): 'next' | 'prev' | null {
const dx = end.x - start.x;
const dy = end.y - start.y;
if (Math.abs(dx) < threshold || Math.abs(dx) < Math.abs(dy)) return null;
return dx < 0 ? 'next' : 'prev';
}
+78
View File
@@ -0,0 +1,78 @@
import fc from 'fast-check';
import { describe, expect, it } from 'vitest';
import { wrapIndex } from './wrapIndex';
const count = fc.integer({ min: 1, max: 50 });
const index = fc.integer({ min: -1000, max: 1000 });
describe('wrapIndex', () => {
it('wraps past either end of the list', () => {
expect(wrapIndex(0, 5)).toBe(0);
expect(wrapIndex(5, 5)).toBe(0);
expect(wrapIndex(-1, 5)).toBe(4);
expect(wrapIndex(-6, 5)).toBe(4);
expect(wrapIndex(12, 5)).toBe(2);
expect(wrapIndex(3, 1)).toBe(0);
});
it('always lands inside the list (invariant)', () => {
fc.assert(
fc.property(index, count, (i, c) => {
const result = wrapIndex(i, c);
expect(Number.isInteger(result)).toBe(true);
expect(result).toBeGreaterThanOrEqual(0);
expect(result).toBeLessThan(c);
}),
);
});
it('is periodic in the list length (invariant)', () => {
fc.assert(
fc.property(
index,
count,
fc.integer({ min: -5, max: 5 }),
(i, c, k) => {
expect(wrapIndex(i + k * c, c)).toBe(wrapIndex(i, c));
},
),
);
});
it('changes nothing when applied twice (idempotence)', () => {
fc.assert(
fc.property(index, count, (i, c) => {
expect(wrapIndex(wrapIndex(i, c), c)).toBe(wrapIndex(i, c));
}),
);
});
it('returns to the same photo after next then previous (round-trip)', () => {
fc.assert(
fc.property(index, count, (i, c) => {
const start = wrapIndex(i, c);
const next = wrapIndex(start + 1, c);
expect(wrapIndex(next - 1, c)).toBe(start);
}),
);
});
it('matches stepping one by one through the list (oracle)', () => {
fc.assert(
fc.property(fc.integer({ min: -60, max: 60 }), count, (i, c) => {
let position = 0;
for (let step = 0; step < Math.abs(i); step++) {
position =
i > 0
? position === c - 1
? 0
: position + 1
: position === 0
? c - 1
: position - 1;
}
expect(wrapIndex(i, c)).toBe(position);
}),
);
});
});
+6
View File
@@ -0,0 +1,6 @@
// A position in a list of `count` items that wraps around both ways: one
// past the last is the first, one before the first is the last. Used for
// browsing photos in the hero and the lightbox.
export function wrapIndex(index: number, count: number): number {
return ((index % count) + count) % count;
}