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.mdindex 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 whenit 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.tsxindex 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(