Skip to content

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

TypeScript

docs(Lightbox): record the out-of-range index and the paged-away video (#10617)

Christopher Chedeau31dc63fd5f5c
diff --git a/docs/specs/components/Lightbox/Lightbox.spec.md b/docs/specs/components/Lightbox/Lightbox.spec.md
index 0227e9719c..cdf87d6a07 100644
--- a/docs/specs/components/Lightbox/Lightbox.spec.md
+++ b/docs/specs/components/Lightbox/Lightbox.spec.md
@@ -107,6 +107,9 @@ 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
@@ -155,6 +158,8 @@ 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 |
+| 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 |
### Allowed variation
@@ -339,6 +344,8 @@ 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` |
+| 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` |
| FR14 | Source boundary check and bundle analysis | A page with Lightbox and another touch component | A second copy of a touch module or a Lightbox-owned gesture listener fails. | `audit:Lightbox/touch` |
diff --git a/packages/core/src/Lightbox/Lightbox.test.tsx b/packages/core/src/Lightbox/Lightbox.test.tsx
index 6a7c6299c5..a73146f8b9 100644
--- a/packages/core/src/Lightbox/Lightbox.test.tsx
+++ b/packages/core/src/Lightbox/Lightbox.test.tsx
@@ -521,22 +521,48 @@ describe('Lightbox', () => {
});
it('shows the last item as the current one for an index past the end', () => {
- render(
- <Lightbox
- isOpen={true}
- onOpenChange={() => {}}
- media={media}
- index={media.length + 2}
- />,
- );
- const photo = screen.getByAltText('Image C');
- expect(photo).not.toHaveAttribute('aria-hidden');
- const page = photo.closest('[data-lightbox-page]')!;
- expect(page).toHaveAttribute('data-current');
- expect(page).not.toHaveAttribute('inert');
- expect(
- screen.getByText(`${media.length} / ${media.length}`),
- ).toBeTruthy();
+ for (const props of [
+ {index: media.length + 2},
+ {defaultIndex: media.length + 2},
+ ]) {
+ const {unmount} = render(
+ <Lightbox
+ isOpen={true}
+ onOpenChange={() => {}}
+ media={media}
+ {...props}
+ />,
+ );
+ const photo = screen.getByAltText('Image C');
+ expect(photo).not.toHaveAttribute('aria-hidden');
+ const page = photo.closest('[data-lightbox-page]')!;
+ expect(page).toHaveAttribute('data-current');
+ expect(page).not.toHaveAttribute('inert');
+ expect(
+ screen.getByText(`${media.length} / ${media.length}`),
+ ).toBeTruthy();
+ unmount();
+ }
+ });
+
+ it('shows the first item as the current one for an index below 0', () => {
+ for (const props of [{index: -1}, {defaultIndex: -3}]) {
+ const {unmount} = render(
+ <Lightbox
+ isOpen={true}
+ onOpenChange={() => {}}
+ media={media}
+ {...props}
+ />,
+ );
+ const photo = screen.getByAltText('Image A');
+ expect(photo).not.toHaveAttribute('aria-hidden');
+ const page = photo.closest('[data-lightbox-page]')!;
+ expect(page).toHaveAttribute('data-current');
+ expect(page).not.toHaveAttribute('inert');
+ expect(screen.getByText(`1 / ${media.length}`)).toBeTruthy();
+ unmount();
+ }
});
it('pauses a playing video once the viewer moves to another item', () => {
@@ -573,6 +599,41 @@ describe('Lightbox', () => {
expect(pause).toHaveBeenCalledTimes(1);
});
+ it("keeps a paged-away video's element and time once the viewer pages back", () => {
+ const items = [
+ {src: '/clip.mp4', alt: 'A clip', type: 'video' as const},
+ {src: '/b.jpg', alt: 'Image B'},
+ ];
+ const view = (index: number) => (
+ <Lightbox
+ isOpen={true}
+ onOpenChange={() => {}}
+ media={items}
+ index={index}
+ />
+ );
+ const {rerender} = render(view(0));
+ const video = document.querySelector('video')!;
+ // Played for 12 s, then paged away from.
+ let time = 12;
+ Object.defineProperty(video, 'currentTime', {
+ configurable: true,
+ get: () => time,
+ set: (value: number) => {
+ time = value;
+ },
+ });
+ const load = vi.fn();
+ video.load = load;
+ video.pause = vi.fn();
+ rerender(view(1));
+ rerender(view(0));
+ // The same element, at the same time: nothing reloads or rewinds it.
+ expect(document.querySelector('video')).toBe(video);
+ expect(time).toBe(12);
+ expect(load).not.toHaveBeenCalled();
+ });
+
it('stays open on a click on the photo, with zoom off', () => {
const onOpenChange = vi.fn();
render(