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:
@@ -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);
|
||||
}
|
||||
}
|
||||
},
|
||||
),
|
||||
);
|
||||
});
|
||||
});
|
||||
@@ -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;
|
||||
}
|
||||
}
|
||||
@@ -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);
|
||||
}
|
||||
}),
|
||||
);
|
||||
});
|
||||
});
|
||||
@@ -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;
|
||||
}
|
||||
@@ -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,
|
||||
);
|
||||
}),
|
||||
);
|
||||
});
|
||||
});
|
||||
@@ -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;
|
||||
}
|
||||
@@ -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);
|
||||
}),
|
||||
);
|
||||
});
|
||||
});
|
||||
@@ -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';
|
||||
}
|
||||
@@ -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);
|
||||
}),
|
||||
);
|
||||
});
|
||||
});
|
||||
@@ -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;
|
||||
}
|
||||
Reference in New Issue
Block a user