From 3e639ee17ca87f3b5c65e99ecc809a5c35a7b746 Mon Sep 17 00:00:00 2001 From: Tim Ellenberger Date: Tue, 10 Nov 2026 11:22:04 -0700 Subject: [PATCH 1/6] test(pager): expect a wider window to keep the side images off the stage Widening the window shows the images beside the current one for a moment. Their positions are pixel offsets for the old stage width, so a wider stage holds part of a wide neighbor until the springs animate it back out. The unit test widens the stage and checks that, one frame later, the images beside the current one already sit at the new stage width. The browser test widens a window with a panorama beside the current image, at once and then in 40px steps, and checks that no frame shows an image other than the current one. translateX in the test helpers now reads percentages as well as pixels. These tests fail until the next commit. Co-Authored-By: Claude Opus 5.5 --- e2e/paging.spec.ts | 23 +++++++++++++++++++++++ src/__tests__/helpers.tsx | 8 +++++--- src/__tests__/paging.test.tsx | 12 ++++++++++++ 3 files changed, 40 insertions(+), 3 deletions(-) diff --git a/e2e/paging.spec.ts b/e2e/paging.spec.ts index 144cab6..03cdf46 100644 --- a/e2e/paging.spec.ts +++ b/e2e/paging.spec.ts @@ -468,3 +468,26 @@ test('keeps the current image centered when the window resizes', async ({ page } expect(await shownImage(page)).toBe('Image 3'); }); + +test.describe('widening the window', () => { + test.skip(({ isMobile }) => isMobile, 'A desktop window'); + + test('keeps the images beside the current one off the screen', async ({ page }) => { + await page.setViewportSize({ height: 720, width: 1280 }); + // The Panorama beside the Portrait is wide enough to reach into a stage that grows + await openHarness(page, 'variety&index=2'); + const stop = await recordImagesOnScreen(page); + + await page.setViewportSize({ height: 720, width: 1600 }); + await page.waitForTimeout(300); + for (let width = 1640; width <= 1920; width += 40) { + await page.setViewportSize({ height: 720, width }); + await page.waitForTimeout(40); + } + await settle(page); + const frames = await stop(); + + expect(frames.length).toBeGreaterThan(0); + expect(frames.filter((alts) => alts.some((alt) => alt !== 'Portrait'))).toEqual([]); + }); +}); diff --git a/src/__tests__/helpers.tsx b/src/__tests__/helpers.tsx index 1c0b777..802ab52 100644 --- a/src/__tests__/helpers.tsx +++ b/src/__tests__/helpers.tsx @@ -115,9 +115,11 @@ export const lightboxContainer = () => screen.getByTestId('lightbox-container'); const NUMBER = '(-?[\\d.]+(?:e[-+]?\\d+)?)'; -/** Pixel offset of an element's `translateX(...)` transform */ -export const translateX = (element: HTMLElement) => - Number(new RegExp(`translateX\\(${NUMBER}px\\)`).exec(element.style.transform)?.[1]); +/** Pixel offset of an element's `translateX(...)` transform, written in pixels or in percent of its width */ +export const translateX = (element: HTMLElement) => { + const [, value, unit] = new RegExp(`translateX\\(${NUMBER}(px|%)\\)`).exec(element.style.transform) ?? []; + return unit === '%' ? (Number(value) / 100) * element.clientWidth : Number(value); +}; /** The alt text of the image the pager has centered */ export const shownImage = () => diff --git a/src/__tests__/paging.test.tsx b/src/__tests__/paging.test.tsx index 186f8a8..c78a8ed 100644 --- a/src/__tests__/paging.test.tsx +++ b/src/__tests__/paging.test.tsx @@ -1111,6 +1111,18 @@ describe('page layout', () => { expect(translateX(pageOf(4))).toBe(1000); }); + test('a wider window puts the images beside the current one in their new places at once', async () => { + await openGallery(); + + layout.stage.width = 1000; + fireEvent(window, new Event('resize')); + await advance(FRAME); + + expect(translateX(pageOf(2))).toBe(-1000); + expect(translateX(pageOf(3))).toBe(0); + expect(translateX(pageOf(4))).toBe(1000); + }); + test('fits images to the stage height, minus 50px of room for controls', () => { render(); From 67d4198f3865c463de40b7c9905801995f0220e9 Mon Sep 17 00:00:00 2001 From: Tim Ellenberger Date: Tue, 10 Nov 2026 11:22:04 -0700 Subject: [PATCH 2/6] fix(pager): keep the side images off the stage as the window widens With 1.9.0, widening the window put part of a wide image beside the current one inside the stage, until the springs animated it back out. Widening from 1280px to 1600px showed up to 320px of a panorama for about 40 frames in Chromium. Each page now keeps the stage width its x was laid out for, and its transform is x as a percentage of that width. The browser moves the pages in the same layout that widens them, before the pager learns the new width. When the pager gets the new width, it rescales x and width together, so nothing moves on screen, and the pages at rest are already in their new places. Co-Authored-By: Claude Opus 5.5 --- .changeset/resize-keeps-neighbors-off.md | 26 +++++++++++++++++++ .../components/ImagePager/index.tsx | 23 +++++++++++++--- 2 files changed, 45 insertions(+), 4 deletions(-) create mode 100644 .changeset/resize-keeps-neighbors-off.md diff --git a/.changeset/resize-keeps-neighbors-off.md b/.changeset/resize-keeps-neighbors-off.md new file mode 100644 index 0000000..540f3da --- /dev/null +++ b/.changeset/resize-keeps-neighbors-off.md @@ -0,0 +1,26 @@ +--- +'react-spring-lightbox': patch +--- + +Widening the window no longer shows the images beside the current one sliding into view. + +- With 1.9.0, the positions of the images on either side of the current one were pixel offsets for the old stage width. A wider window put part of a wide neighbor inside the stage, and the lightbox then animated it back out. In Chromium, widening the window from 1280px to 1600px showed up to 320px of a panorama beside the current image in about 40 frames, about 0.7 seconds. Dragging the window wider showed it in about half the frames. Only images wide enough to reach past their own page showed this, such as panoramas and wide screenshots. +- Now each image's position is a percentage of the stage width it was laid out for, so the browser moves the images in the same layout that widens the stage. When the lightbox gets the new width, it rescales the positions without moving anything on screen. An image that was sliding when the window changed size keeps sliding from where it is. +- Narrowing the window never showed this, and still doesn't. +- Tested with the unit tests on React 19 and React 18.3.1, the Playwright tests in Chromium, Firefox, and mobile Chromium on React 19, and the Chromium Playwright tests on React 18.3.1. A frame-by-frame check in Chromium found no neighbor on screen in any frame, whether the window widened at once or in 40px steps. + +Upgrade notes: + +- If a test of your app reads the `transform` of a `.lightbox-image-pager` element and expects pixels, it now gets a percentage of the stage width. + + Before: + + ```js + expect(page.style.transform).toBe('translateX(-1280px)'); + ``` + + After: + + ```js + expect(page.style.transform).toBe('translateX(-100%)'); + ``` diff --git a/src/components/ImageStage/components/ImagePager/index.tsx b/src/components/ImageStage/components/ImagePager/index.tsx index 6e29f45..f2683b5 100644 --- a/src/components/ImageStage/components/ImagePager/index.tsx +++ b/src/components/ImageStage/components/ImagePager/index.tsx @@ -1,4 +1,4 @@ -import { animated, useSprings } from '@react-spring/web'; +import { animated, to, useSprings } from '@react-spring/web'; import { useGesture } from '@use-gesture/react'; import React, { useEffect, useRef, useState } from 'react'; @@ -79,7 +79,12 @@ const ImagePager = ({ * * @see https://www.react-spring.io/docs/hooks/use-springs */ - const [pagerSprings, springsApi] = useSprings(images.length, (i) => getPagePositions(i)); + // Each page also keeps the stage width its x was laid out for. Its transform is x as a percentage of that width, + // so a wider window moves the pages in the same layout that widens them, before the pager learns the new width. + const [pagerSprings, springsApi] = useSprings(images.length, (i) => ({ + ...getPagePositions(i), + width: imageStageWidth, + })); // Animate page change if currentIndex changes useEffect(() => { @@ -94,6 +99,13 @@ const ImagePager = ({ if (currentIndex === previous.index && imageStageWidth === previous.width) { return; } + if (imageStageWidth !== previous.width) { + // Rescale x with the width, so no page moves on screen. Pages at rest are then in their new places. + springsApi.set((_, ctrl) => ({ + width: imageStageWidth, + x: (ctrl.springs.x.get() * imageStageWidth) / previous.width, + })); + } const step = currentIndex - previous.index; // The old image's page holds another image now, as after images are added or swapped const replaced = images[previous.index]?.src !== previous.src; @@ -277,7 +289,7 @@ const ImagePager = ({ return (
- {pagerSprings.map(({ display, x }, i) => ( + {pagerSprings.map(({ display, width, x }, i) => ( `translateX(${xInterp}px)`), + transform: to( + [x, width], + (xValue, widthValue) => `translateX(${(xValue / widthValue) * 100}%)` + ), width: '100%', willChange: 'transform', }} From 4accd6dd64c46b15285c921b57d03f131860dc87 Mon Sep 17 00:00:00 2001 From: Tim Ellenberger Date: Tue, 10 Nov 2026 11:58:35 -0700 Subject: [PATCH 3/6] perf(pager): share one layout width and keep one observer per page The resize fix gave every page spring its own width, and its transform interpolated x and that width together. In the perf harness at 1,000 images, the open lightbox's JavaScript heap rose from 27.39MB to 28.15MB, and dragging took 15% more script time (p=0.032). Each render built 1,000 interpolations with two inputs, and the width spring added an object per image. The pages now share one useSpringValue for the width they were laid out for. Each transform observes only x and reads that width, which holds because a resize changes x along with the width, after the width. The heap is 27.52MB, and drag task and script times show no measurable difference from master, median of 5 alternating runs per side. Co-Authored-By: Claude Opus 5.5 --- .changeset/resize-keeps-neighbors-off.md | 2 +- .../components/ImagePager/index.tsx | 31 ++++++++----------- 2 files changed, 14 insertions(+), 19 deletions(-) diff --git a/.changeset/resize-keeps-neighbors-off.md b/.changeset/resize-keeps-neighbors-off.md index 540f3da..7ec512e 100644 --- a/.changeset/resize-keeps-neighbors-off.md +++ b/.changeset/resize-keeps-neighbors-off.md @@ -7,7 +7,7 @@ Widening the window no longer shows the images beside the current one sliding in - With 1.9.0, the positions of the images on either side of the current one were pixel offsets for the old stage width. A wider window put part of a wide neighbor inside the stage, and the lightbox then animated it back out. In Chromium, widening the window from 1280px to 1600px showed up to 320px of a panorama beside the current image in about 40 frames, about 0.7 seconds. Dragging the window wider showed it in about half the frames. Only images wide enough to reach past their own page showed this, such as panoramas and wide screenshots. - Now each image's position is a percentage of the stage width it was laid out for, so the browser moves the images in the same layout that widens the stage. When the lightbox gets the new width, it rescales the positions without moving anything on screen. An image that was sliding when the window changed size keeps sliding from where it is. - Narrowing the window never showed this, and still doesn't. -- Tested with the unit tests on React 19 and React 18.3.1, the Playwright tests in Chromium, Firefox, and mobile Chromium on React 19, and the Chromium Playwright tests on React 18.3.1. A frame-by-frame check in Chromium found no neighbor on screen in any frame, whether the window widened at once or in 40px steps. +- Tested with the unit tests on React 19 and React 18.3.1, the Playwright tests in Chromium, Firefox, and mobile Chromium on React 19, and the Chromium Playwright tests on React 18.3.1. A frame-by-frame check in Chromium found no neighbor on screen in any frame, whether the window widened at once or in 40px steps. In the repository's perf harness at 1,000 images, dragging showed no measurable change in task or script time, and the open lightbox used about 0.13MB more JavaScript heap, 27.52MB against 27.39MB without this change. Upgrade notes: diff --git a/src/components/ImageStage/components/ImagePager/index.tsx b/src/components/ImageStage/components/ImagePager/index.tsx index f2683b5..5cf9d24 100644 --- a/src/components/ImageStage/components/ImagePager/index.tsx +++ b/src/components/ImageStage/components/ImagePager/index.tsx @@ -1,4 +1,4 @@ -import { animated, to, useSprings } from '@react-spring/web'; +import { animated, useSpringValue, useSprings } from '@react-spring/web'; import { useGesture } from '@use-gesture/react'; import React, { useEffect, useRef, useState } from 'react'; @@ -79,12 +79,10 @@ const ImagePager = ({ * * @see https://www.react-spring.io/docs/hooks/use-springs */ - // Each page also keeps the stage width its x was laid out for. Its transform is x as a percentage of that width, - // so a wider window moves the pages in the same layout that widens them, before the pager learns the new width. - const [pagerSprings, springsApi] = useSprings(images.length, (i) => ({ - ...getPagePositions(i), - width: imageStageWidth, - })); + const [pagerSprings, springsApi] = useSprings(images.length, (i) => getPagePositions(i)); + // The stage width the pages' x was laid out for. Each page's transform is x as a percentage of it, so a wider + // window moves the pages in the same layout that widens them, before the pager learns the new width. + const layoutWidth = useSpringValue(imageStageWidth); // Animate page change if currentIndex changes useEffect(() => { @@ -100,11 +98,10 @@ const ImagePager = ({ return; } if (imageStageWidth !== previous.width) { - // Rescale x with the width, so no page moves on screen. Pages at rest are then in their new places. - springsApi.set((_, ctrl) => ({ - width: imageStageWidth, - x: (ctrl.springs.x.get() * imageStageWidth) / previous.width, - })); + // Rescale x with the width, so no page moves on screen. Pages at rest are then in their new places. The + // width changes first, because a page's transform reads it when its x changes. + layoutWidth.set(imageStageWidth); + springsApi.set((_, ctrl) => ({ x: (ctrl.springs.x.get() * imageStageWidth) / previous.width })); } const step = currentIndex - previous.index; // The old image's page holds another image now, as after images are added or swapped @@ -155,7 +152,7 @@ const ImagePager = ({ } return target; }); - }, [currentIndex, getPagePositions, imageStageWidth, images, shownSrc, springsApi]); + }, [currentIndex, getPagePositions, imageStageWidth, images, layoutWidth, shownSrc, springsApi]); /** * Update each Image's visibility and translateX offset during dragging @@ -289,7 +286,7 @@ const ImagePager = ({ return (
- {pagerSprings.map(({ display, width, x }, i) => ( + {pagerSprings.map(({ display, x }, i) => ( `translateX(${(xValue / widthValue) * 100}%)` - ), + // Observing only x keeps one observer per page. A resize changes x along with the width. + transform: x.to((xValue: number) => `translateX(${(xValue / layoutWidth.get()) * 100}%)`), width: '100%', willChange: 'transform', }} From f9fe3f975b0d8c0b2adae206e02ebb2a28e2583b Mon Sep 17 00:00:00 2001 From: Tim Ellenberger Date: Tue, 10 Nov 2026 15:56:35 -0700 Subject: [PATCH 4/6] fix(perf): read percentage transforms in the jumps sampler The pages now write translateX in percent of their width, which the pixel-only pattern in perf/jumps.mjs read as NaN. On this branch every page change showed NaN for where the new image starts and 0 frames for the old image. With the fix, the branch's numbers match master's. Co-Authored-By: Claude Opus 5.5 --- perf/jumps.mjs | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/perf/jumps.mjs b/perf/jumps.mjs index 04563be..4acd3b4 100644 --- a/perf/jumps.mjs +++ b/perf/jumps.mjs @@ -81,10 +81,14 @@ const startSampling = () => { const sample = (time) => { const pages = [...document.querySelectorAll('.lightbox-image-pager')] .filter((span) => getComputedStyle(span).display !== 'none') - .map((span) => [ - Number(span.querySelector('img').alt.replace('Image ', '')), - Number(/translateX\((-?[\d.e+-]+)px\)/.exec(span.style.transform)?.[1]), - ]); + .map((span) => { + // A page writes translateX in pixels, or in percent of its own width + const [, value, unit] = /translateX\((-?[\d.e+-]+)(px|%)\)/.exec(span.style.transform) ?? []; + return [ + Number(span.querySelector('img').alt.replace('Image ', '')), + unit === '%' ? (Number(value) / 100) * span.offsetWidth : Number(value), + ]; + }); state.frames.push({ pages, time }); if (state.recording) { requestAnimationFrame(sample); From 005bcec22d17fbc90447dfa2b127aa91d9d7b823 Mon Sep 17 00:00:00 2001 From: Tim Ellenberger Date: Tue, 10 Nov 2026 15:56:35 -0700 Subject: [PATCH 5/6] test(pager): require the current image in every frame while the window widens Without it, frames that recorded no image at all would pass. Co-Authored-By: Claude Opus 5.5 --- e2e/paging.spec.ts | 1 + 1 file changed, 1 insertion(+) diff --git a/e2e/paging.spec.ts b/e2e/paging.spec.ts index 03cdf46..54d6296 100644 --- a/e2e/paging.spec.ts +++ b/e2e/paging.spec.ts @@ -488,6 +488,7 @@ test.describe('widening the window', () => { const frames = await stop(); expect(frames.length).toBeGreaterThan(0); + expect(frames.filter((alts) => !alts.includes('Portrait'))).toEqual([]); expect(frames.filter((alts) => alts.some((alt) => alt !== 'Portrait'))).toEqual([]); }); }); From 7f49f10d4d704b6eef68811a6edbd18fba3de759 Mon Sep 17 00:00:00 2001 From: Tim Ellenberger Date: Tue, 10 Nov 2026 15:56:35 -0700 Subject: [PATCH 6/6] docs(changeset): say Firefox was checked and zoomed resizes were not Co-Authored-By: Claude Opus 5.5 --- .changeset/resize-keeps-neighbors-off.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.changeset/resize-keeps-neighbors-off.md b/.changeset/resize-keeps-neighbors-off.md index 7ec512e..46a9844 100644 --- a/.changeset/resize-keeps-neighbors-off.md +++ b/.changeset/resize-keeps-neighbors-off.md @@ -7,7 +7,7 @@ Widening the window no longer shows the images beside the current one sliding in - With 1.9.0, the positions of the images on either side of the current one were pixel offsets for the old stage width. A wider window put part of a wide neighbor inside the stage, and the lightbox then animated it back out. In Chromium, widening the window from 1280px to 1600px showed up to 320px of a panorama beside the current image in about 40 frames, about 0.7 seconds. Dragging the window wider showed it in about half the frames. Only images wide enough to reach past their own page showed this, such as panoramas and wide screenshots. - Now each image's position is a percentage of the stage width it was laid out for, so the browser moves the images in the same layout that widens the stage. When the lightbox gets the new width, it rescales the positions without moving anything on screen. An image that was sliding when the window changed size keeps sliding from where it is. - Narrowing the window never showed this, and still doesn't. -- Tested with the unit tests on React 19 and React 18.3.1, the Playwright tests in Chromium, Firefox, and mobile Chromium on React 19, and the Chromium Playwright tests on React 18.3.1. A frame-by-frame check in Chromium found no neighbor on screen in any frame, whether the window widened at once or in 40px steps. In the repository's perf harness at 1,000 images, dragging showed no measurable change in task or script time, and the open lightbox used about 0.13MB more JavaScript heap, 27.52MB against 27.39MB without this change. +- Tested with the unit tests on React 19 and React 18.3.1, the Playwright tests in Chromium, Firefox, and mobile Chromium on React 19, and the Chromium Playwright tests on React 18.3.1. A frame-by-frame check in Chromium and Firefox found no neighbor on screen in any frame, whether the window widened at once or in 40px steps. Resizing while an image is zoomed in was not tested. In the repository's perf harness at 1,000 images, dragging showed no measurable change in task or script time, and the open lightbox used about 0.13MB more JavaScript heap, 27.52MB against 27.39MB without this change. Upgrade notes: