Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

fix(Lightbox): a NaN or fractional index opens the nearest item (#10632)

Cindy Zhang4d3ec24c3753
diff --git a/.changeset/lightbox-nan-fractional-index.md b/.changeset/lightbox-nan-fractional-index.md
new file mode 100644
index 0000000000..bab5c61ad2
--- /dev/null
+++ b/.changeset/lightbox-nan-fractional-index.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[fix] An open Lightbox shows the nearest item when `index` or `defaultIndex` is NaN or a fraction between the first and last item. A fraction rounds to the nearest item, and NaN shows the first item. Before, the viewer rendered nothing for those values.
+
+@cixzhang
diff --git a/docs/specs/components/Lightbox/Lightbox.spec.md b/docs/specs/components/Lightbox/Lightbox.spec.md
index ed2ffc9d70..fe1b59e2a9 100644
--- a/docs/specs/components/Lightbox/Lightbox.spec.md
+++ b/docs/specs/components/Lightbox/Lightbox.spec.md
@@ -110,9 +110,6 @@ the requirement it misses and the person it affects.
`click` do not carry, and clears the flag a drag leaves for its click.
- **Touch exit (FR16).** On a touch screen the viewer disappears at once when
it closes.
-- **NaN or fractional index (FR17).** FR17 covers whole-number indices. With
- a NaN `index`, or a fractional one inside the range, an open Lightbox
- renders nothing, so a caller that passes one sees no viewer.
## Ownership boundary
@@ -161,7 +158,7 @@ FR21). Consumer props and usage remain documented in `Lightbox.doc.mjs`.
| FR14 | Gestures, paging, motion, and reduced motion run through Core's one shared set of internal touch modules; Lightbox bundles no copy of a module's primitive and adds no gesture listener outside them. | `architecture:react-component-runtime` INV13 | settled; implementation gap |
| FR15 | Lightbox supports a Picture-in-Picture window as its only second document; there it ranks Escape and platform close among that window's members. | `family:overlay-dismissal` FR8 | settled |
| FR16 | Under a coarse primary pointer, a close that is not a drag down (FR8), a pinch in (FR9), or a return into a source (FR12) plays the touch exit: Close, Escape, a platform close, and a tap beside the photo while the controls are shown (ORD3). The photo shrinks a little and fades out in place with the backdrop and controls, as the native viewer's zoom transition does without a source, on a spring from rest, `springs.settle` unless the motion table names another role, with the backdrop and controls fading on its pace (`spec:AST-094` FR7, FR45). `onOpenChange(false)` reports at the request, and the viewer takes no input while the exit plays. Under a fine pointer the viewer closes at once (FR11). | `spec:AST-094` FR7 | settled; implementation gap |
-| FR17 | For any whole-number `index`, controlled or default, the viewer opens on the nearest valid item: below 0 the first, past the last the last. | Current source and tests | settled |
+| FR17 | For any `index`, controlled or default, the viewer opens on the nearest valid item: below 0 the first, past the last the last. A fraction rounds to the nearest item, and NaN opens the first. | Current source and tests | settled |
| FR18 | In a gallery, a video on a neighbouring page stays mounted and paused while another item shows. Paging back to it shows it where it stopped, as the platform photo viewer does: paused, or playing on from there with `hasAutoPlay`. | Current source and tests | settled |
### Motion
@@ -361,7 +358,7 @@ a decision that they must remain unthemeable.
| FR11 | Fine-pointer browser tests | Double-click, click on the photo, drag, ctrl-wheel, trackpad scroll, mouse wheel notch | A double-click that does not zoom 2× about the point, a click that hides the controls, a fine-pointer close that animates, or a mouse wheel's notch that pans a zoomed photo fails. | `audit:Lightbox/touch` |
| FR6, AR1 | Touch test double-tapping a photo shaped like the screen and a landscape photo | 9:16 photo on a phone viewport, 3:2 photo | A double tap that zooms less than 2×, or not about the tapped point, fails. | `audit:Lightbox/touch` |
| FR16 | Touch tests closing by Close, Escape, platform close, and a tap beside the photo with the controls shown; Reduce Motion | With and without `experimental`; controls shown and hidden | A touch close without the exit, a literal timing, input reaching the viewer during the exit, or a tap beside the photo that closes while the controls are hidden fails. | `audit:Lightbox/touch` |
-| FR17 | `Lightbox.test.tsx` index cases | An index below 0 and past the end, controlled and default | An index past either end that opens an empty viewer, or any item but the nearest, fails. | `audit:Lightbox/anatomy` |
+| FR17 | `Lightbox.test.tsx` index cases | An index below 0 and past the end, NaN, and an in-range fraction (1.5, 0.4, 1.2), controlled and default | An index that opens an empty viewer, or any item but the nearest, fails. | `audit:Lightbox/anatomy` |
| FR18 | `Lightbox.test.tsx` video paging cases (pause, keep, autoplay) | A playing video paged away from and back to | A neighbouring video that unmounts, keeps playing, or starts again from its beginning fails. | `audit:Lightbox/anatomy` |
| FR12 | Opener and `sourceFor` tests, with and without `experimental` | Image opener, text-button opener, mid-entrance close | Any change to opening or closing without `experimental` fails. | `audit:Lightbox/touch` |
| FR13 | `hasZoom={false}` tests under a coarse pointer | Gallery, single image | A zoom, a pinch close, or a tap that hides the controls with `hasZoom={false}` fails. | `audit:Lightbox/touch` |
diff --git a/packages/core/src/Lightbox/Lightbox.test.tsx b/packages/core/src/Lightbox/Lightbox.test.tsx
index 937f28911e..90bda9e23f 100644
--- a/packages/core/src/Lightbox/Lightbox.test.tsx
+++ b/packages/core/src/Lightbox/Lightbox.test.tsx
@@ -564,6 +564,28 @@ describe('Lightbox', () => {
}
});
+ // An index that is not a whole number opens the nearest item, as an
+ // index past either end does.
+ it.each([
+ ['a controlled NaN index', {index: Number.NaN}, 'Image A', 1],
+ ['a default NaN index', {defaultIndex: Number.NaN}, 'Image A', 1],
+ ['a controlled index of 1.5', {index: 1.5}, 'Image C', 3],
+ ['a controlled index of 0.4', {index: 0.4}, 'Image A', 1],
+ ['a default index of 1.2', {defaultIndex: 1.2}, 'Image B', 2],
+ ])('opens the nearest item for %s', (_, indexProps, alt, position) => {
+ render(
+ <Lightbox
+ isOpen={true}
+ onOpenChange={() => {}}
+ media={media}
+ {...indexProps}
+ />,
+ );
+ const page = screen.getByAltText(alt).closest('[data-lightbox-page]')!;
+ expect(page).toHaveAttribute('data-current');
+ expect(screen.getByText(`${position} / ${media.length}`)).toBeTruthy();
+ });
+
it('pauses a playing video once the viewer moves to another item', () => {
const items = [
{src: '/clip.mp4', alt: 'A clip', type: 'video' as const},
diff --git a/packages/core/src/Lightbox/Lightbox.tsx b/packages/core/src/Lightbox/Lightbox.tsx
index a219aa915f..b273a6accf 100644
--- a/packages/core/src/Lightbox/Lightbox.tsx
+++ b/packages/core/src/Lightbox/Lightbox.tsx
@@ -566,10 +566,12 @@ export function Lightbox({
[media],
);
const isGallery = mediaArray.length > 1;
- // The item shown, current in every respect (its page, the counter, the
- // pager, the announcement): an index past either end shows the nearest
- // item. A NaN index stays NaN (the viewed-item check below).
- const index = Math.max(0, Math.min(requestedIndex, mediaArray.length - 1));
+ // The item shown is current in every respect: its page, the counter, the
+ // pager and the announcement.
+ const wholeIndex = Number.isNaN(requestedIndex)
+ ? 0
+ : Math.round(requestedIndex);
+ const index = Math.max(0, Math.min(wholeIndex, mediaArray.length - 1));
const currentItem = mediaArray.length > 0 ? mediaArray[index] : null;
const currentType = currentItem?.type ?? 'image';
const isVideo = currentType === 'video';
@@ -583,8 +585,6 @@ export function Lightbox({
// never paints as zoomed; the stage resets the photo before it paints.
const currentSrc = currentItem?.src;
const [viewedItem, setViewedItem] = useState({index, src: currentSrc});
- // Object.is, matching the dependency comparison of the effect this replaces:
- // a controlled index of NaN must not re-render forever.
if (
!Object.is(viewedItem.index, index) ||
!Object.is(viewedItem.src, currentSrc)