Skip to content

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

TypeScript

[Component Audit] Lightbox: screen readers hear the open viewer, and 0 resets the zoom (#10775)

Cindy Zhang117bc6eadd1e
diff --git a/.changeset/lightbox-announces-inside-viewer.md b/.changeset/lightbox-announces-inside-viewer.md
new file mode 100644
index 0000000000..5686114520
--- /dev/null
+++ b/.changeset/lightbox-announces-inside-viewer.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[fix] `Lightbox`: a screen reader now hears the viewer's own messages while it is open. Moving to another item ("Mountain lake, 2 of 4") and zooming in or out are announced inside the open viewer; before, they went to the page behind the modal viewer, where a screen reader does not read them. The `0` key now returns a zoomed photo to its fitted size. The docs list the `0` key, and no longer say that the lightbox is only for images.
+
+@cixzhang
diff --git a/.github/a11y-audit-axe.json b/.github/a11y-audit-axe.json
index 155c073071..20449dbcd0 100644
--- a/.github/a11y-audit-axe.json
+++ b/.github/a11y-audit-axe.json
@@ -64,5 +64,9 @@
"core-layout--dual-panels",
"core-layout--content-width-with-start-panel"
]
+ },
+ "Lightbox": {
+ "stories": ["core-lightbox--open-viewer"],
+ "readySelector": "dialog[open]"
}
}
diff --git a/apps/storybook/stories/Lightbox.stories.tsx b/apps/storybook/stories/Lightbox.stories.tsx
index ef85628989..59297bca0a 100644
--- a/apps/storybook/stories/Lightbox.stories.tsx
+++ b/apps/storybook/stories/Lightbox.stories.tsx
@@ -330,3 +330,30 @@ export const WithHook: Story = {
);
},
};
+
+/**
+ * The gallery viewer, open when the page loads, so a page-level
+ * accessibility check reaches the open viewer.
+ */
+export const OpenViewer: Story = {
+ name: 'Open Viewer',
+ // Kept off the docs page because the viewer opens on load.
+ tags: ['!autodocs'],
+ render: () => {
+ const [isOpen, setIsOpen] = useState(true);
+ const [index, setIndex] = useState(0);
+ return (
+ <>
+ <button onClick={() => setIsOpen(true)}>Open viewer</button>
+ <Lightbox
+ isOpen={isOpen}
+ onOpenChange={setIsOpen}
+ media={GALLERY_MEDIA}
+ index={index}
+ onIndexChange={setIndex}
+ hasZoom
+ />
+ </>
+ );
+ },
+};
diff --git a/packages/core/src/Lightbox/Lightbox.doc.mjs b/packages/core/src/Lightbox/Lightbox.doc.mjs
index b8324276bf..6a908e3418 100644
--- a/packages/core/src/Lightbox/Lightbox.doc.mjs
+++ b/packages/core/src/Lightbox/Lightbox.doc.mjs
@@ -99,7 +99,7 @@ export const docs = {
name: 'hasZoom',
type: 'boolean',
description:
- 'Enable zoom (images only): pinch (or ctrl-wheel), or double-tap or double-click to zoom in at that point and back; Enter/Space/+/- zoom 2× about the centre and back. When zoomed, drag or scroll a trackpad to pan, or use arrow keys; on a phone or a tablet, the pan has momentum.',
+ 'Enable zoom (images only): pinch (or ctrl-wheel), or double-tap or double-click to zoom in at that point and back; Enter/Space/+/- zoom 2× about the centre and back, and 0 returns to the fitted size. When zoomed, drag or scroll a trackpad to pan, or use arrow keys; on a phone or a tablet, the pan has momentum.',
default: 'false',
},
{
@@ -149,7 +149,7 @@ export const docs = {
{
guidance: false,
description:
- 'Use the lightbox for non-image content; it is specialized for images.',
+ 'Use the lightbox for content other than images and videos; it shows one media item at a time.',
},
{
guidance: false,
@@ -214,7 +214,7 @@ export const docsZh = {
name: 'hasZoom',
type: 'boolean',
description:
- '启用缩放(仅图片):双指捏合(或按住 Ctrl 滚动滚轮),或双点按、双击在该处放大并还原;Enter/Space/+/- 键以中心放大 2 倍并还原。缩放后可拖动或在触控板上滚动平移,或用方向键平移;在手机或平板上,平移带惯性。',
+ '启用缩放(仅图片):双指捏合(或按住 Ctrl 滚动滚轮),或双点按、双击在该处放大并还原;Enter/Space/+/- 键以中心放大 2 倍并还原,0 键恢复到适合大小。缩放后可拖动或在触控板上滚动平移,或用方向键平移;在手机或平板上,平移带惯性。',
default: 'false',
},
{
@@ -250,7 +250,7 @@ export const docsZh = {
{
guidance: false,
description:
- 'Use the lightbox for non-image content; it is specialized for images.',
+ 'Use the lightbox for content other than images and videos; it shows one media item at a time.',
},
{
guidance: false,
@@ -283,7 +283,8 @@ export const docsDense = {
},
{
guidance: false,
- description: 'Use for non-image content; specialized for images.',
+ description:
+ 'Use for content other than images and videos; one media item at a time.',
},
{
guidance: false,
@@ -301,7 +302,7 @@ export const docsDense = {
onIndexChange:
'Callback when gallery index changes (buttons, keys or a swipe).',
hasZoom:
- 'Enable zoom (pinch or ctrl-wheel, double-tap or double-click, Enter/Space, or +/-) and pan (drag, trackpad scroll, or arrow keys) for images.',
+ 'Enable zoom (pinch or ctrl-wheel, double-tap or double-click, Enter/Space, or +/-; 0 resets) and pan (drag, trackpad scroll, or arrow keys) for images.',
xstyle: 'StyleX styles for layout customization.',
},
};
diff --git a/packages/core/src/Lightbox/Lightbox.test.tsx b/packages/core/src/Lightbox/Lightbox.test.tsx
index 90bda9e23f..7a0c431f7a 100644
--- a/packages/core/src/Lightbox/Lightbox.test.tsx
+++ b/packages/core/src/Lightbox/Lightbox.test.tsx
@@ -1155,6 +1155,76 @@ describe('Lightbox', () => {
expect(zoomTarget()).toHaveAttribute('aria-pressed', 'true');
});
+ it('returns a zoomed photo to its fitted size with 0', () => {
+ render(
+ <Lightbox
+ isOpen={true}
+ onOpenChange={() => {}}
+ media={{src: '/photo.jpg', alt: 'Photo'}}
+ hasZoom
+ />,
+ );
+ const dialog = document.querySelector('dialog')!;
+ fireEvent.keyDown(dialog, {key: '+'});
+ expect(zoomTarget()).toHaveAttribute('aria-pressed', 'true');
+ fireEvent.keyDown(dialog, {key: '0'});
+ expect(zoomTarget()).toHaveAttribute('aria-pressed', 'false');
+ // At the fitted size, 0 leaves the photo there.
+ fireEvent.keyDown(dialog, {key: '0'});
+ expect(zoomTarget()).toHaveAttribute('aria-pressed', 'false');
+ });
+
+ it('leaves Ctrl+0 and Cmd+0 to the browser', () => {
+ render(
+ <Lightbox
+ isOpen={true}
+ onOpenChange={() => {}}
+ media={{src: '/photo.jpg', alt: 'Photo'}}
+ hasZoom
+ />,
+ );
+ const dialog = document.querySelector('dialog')!;
+ fireEvent.keyDown(dialog, {key: '+'});
+ expect(fireEvent.keyDown(dialog, {key: '0', ctrlKey: true})).toBe(true);
+ expect(fireEvent.keyDown(dialog, {key: '0', metaKey: true})).toBe(true);
+ expect(zoomTarget()).toHaveAttribute('aria-pressed', 'true');
+ });
+
+ it('announces a zoom inside the open modal viewer', async () => {
+ // jsdom has no :modal; treat an open dialog as modal, as showModal()
+ // makes it in a browser.
+ const matches = Element.prototype.matches;
+ const spy = vi
+ .spyOn(Element.prototype, 'matches')
+ .mockImplementation(function (this: Element, selector: string) {
+ return selector === ':modal'
+ ? this instanceof HTMLDialogElement && this.open
+ : matches.call(this, selector);
+ });
+ try {
+ render(
+ <Lightbox
+ isOpen={true}
+ onOpenChange={() => {}}
+ media={{src: '/photo.jpg', alt: 'Photo'}}
+ hasZoom
+ />,
+ );
+ const dialog = document.querySelector('dialog')!;
+ fireEvent.keyDown(dialog, {key: '+'});
+ await waitFor(() => {
+ expect(
+ dialog.querySelector(
+ ':scope > [data-astryx-modal-live-region="polite"]',
+ ),
+ ).toHaveTextContent('Zoomed in');
+ });
+ expect(politeRegion()?.textContent ?? '').toBe('');
+ } finally {
+ spy.mockRestore();
+ }
+ });
+
it('pans with arrow keys while zoomed instead of navigating the gallery', () => {
const onIndexChange = vi.fn();
render(
diff --git a/packages/core/src/Lightbox/Lightbox.tsx b/packages/core/src/Lightbox/Lightbox.tsx
index b273a6accf..aa83fd2f27 100644
--- a/packages/core/src/Lightbox/Lightbox.tsx
+++ b/packages/core/src/Lightbox/Lightbox.tsx
@@ -47,7 +47,7 @@ import {
} from '../theme/tokens.stylex';
import {Icon} from '../Icon';
import {IconButton} from '../IconButton';
-import {useAnnounce} from '../hooks/useAnnounce';
+import {announceInModal} from '../hooks/useAnnounce';
import {useScrollLock} from '../hooks/useScrollLock';
import {useIsomorphicLayoutEffect} from '../hooks/useIsomorphicLayoutEffect';
import {useAttachment} from '../hooks/useAttachment';
@@ -147,9 +147,10 @@ export interface LightboxProps extends BaseProps<HTMLDialogElement> {
* Enable zoom (images only). A pinch or a ctrl-wheel zooms about the
* fingers or the pointer. A double tap fills the viewer and a double-click
* zooms 2×, about that point, and the next goes back. Enter, Space, `+` and
- * `-` zoom 2× about the centre and back. When zoomed, drag or scroll a
- * trackpad to pan, or use the arrow keys. On a phone or a tablet, the pan
- * has momentum. The gestures work for every pointer.
+ * `-` zoom 2× about the centre and back, and `0` returns to the fitted
+ * size. When zoomed, drag or scroll a trackpad to pan, or use the arrow
+ * keys. On a phone or a tablet, the pan has momentum. The gestures work
+ * for every pointer.
* @default false
*/
hasZoom?: boolean;
@@ -470,7 +471,7 @@ const KEYBOARD_PAN_OFFSETS: Record<string, [number, number]> = {
const VIDEO_CONTROLS_BAND = 48;
/**
- * A fullscreen overlay for viewing images at full resolution.
+ * A fullscreen overlay for viewing images and videos at full resolution.
*
* Supports single image and gallery modes. In gallery mode, it provides
* prev/next navigation via buttons and arrow keys. The arrow keys follow the
@@ -480,10 +481,11 @@ const VIDEO_CONTROLS_BAND = 48;
* Optionally supports zoom like a photo viewer. A pinch or a ctrl-wheel zooms
* about the fingers or the pointer, gives past the limits and springs back. A
* double tap or a double-click zooms in at that point and back. Enter or
- * Space on the image, and `+` or `-` from the keyboard, zoom too. When zoomed,
- * a drag or a trackpad's scroll pans. On a phone or a tablet, the pan has
- * momentum and a rubber band at the edges. The arrow keys pan a zoomed photo
- * and navigate the gallery otherwise.
+ * Space on the image, and `+` or `-` from the keyboard, zoom too, and `0`
+ * returns to the fitted size. When zoomed, a drag or a trackpad's scroll
+ * pans. On a phone or a tablet, the pan has momentum and a rubber band at the
+ * edges. The arrow keys pan a zoomed photo and navigate the gallery
+ * otherwise.
*
* Uses the native `<dialog>` element with `showModal()` for focus
* trapping and top-layer placement. Dismiss via Escape, close button,
@@ -600,7 +602,14 @@ export function Lightbox({
// already-open session — not on mount, not when opening (even at a new
// index, since the dialog's aria-label already names the current image), and
// not on close.
- const announce = useAnnounce();
+ // While the modal viewer is open, a screen reader reads only messages
+ // inside it.
+ const announce = useCallback((message: string) => {
+ const dialog = dialogRef.current;
+ if (dialog != null) {
+ announceInModal(dialog, message);
+ }
+ }, []);
const prevIndexRef = useRef(index);
const wasOpenRef = useRef(isOpen);
useEffect(() => {
@@ -1232,6 +1241,12 @@ export function Lightbox({
stage.zoomOut();
return;
}
+ // Ctrl or Cmd with 0 resets the browser's page zoom; leave it.
+ if (e.key === '0' && !e.ctrlKey && !e.metaKey && !e.altKey) {
+ e.preventDefault();
+ stage.zoomOut();
+ return;
+ }
if (stage.isZoomed() && KEYBOARD_PAN_OFFSETS[e.key] !== undefined) {
e.preventDefault();
const [dx, dy] = KEYBOARD_PAN_OFFSETS[e.key];
diff --git a/packages/core/src/Lightbox/LightboxKeyboard.a11y.browser.spec.ts b/packages/core/src/Lightbox/LightboxKeyboard.a11y.browser.spec.ts
index d179b26e6f..f8c9db949c 100644
--- a/packages/core/src/Lightbox/LightboxKeyboard.a11y.browser.spec.ts
+++ b/packages/core/src/Lightbox/LightboxKeyboard.a11y.browser.spec.ts
@@ -6,8 +6,9 @@
* @input Built Lightbox stories (LTR and the RTL story global) and real
* Chromium/WebKit keyboard input
* @output Browser evidence that the gallery's Left/Right arrow keys move in
- * the direction of the matching on-screen button, in both directions, and
- * that Tab and Shift+Tab wrap inside the open viewer at both ends
+ * the direction of the matching on-screen button, in both directions, that
+ * Tab and Shift+Tab wrap inside the open viewer at both ends, and that the
+ * zoom keys work and are announced inside the open viewer
* @position Cross-browser proof for Lightbox's direction-aware gallery keys
* (design:bidirectionality DR6, DR11)
*/
@@ -137,3 +138,32 @@ test('Tab and Shift+Tab wrap inside an open single image, zoomed or not', async
await page.keyboard.press('+');
await expectTabWrapsInside(page);
});
+
+test('+ zooms and is announced inside the viewer, and 0 returns to the fitted size', async ({
+ page,
+}) => {
+ // A local picture stands in for the remote photo, so the zoom has a size.
+ await page.route(/picsum\.photos/, async route =>
+ route.fulfill({
+ contentType: 'image/svg+xml',
+ body: '<svg xmlns="http://www.w3.org/2000/svg" width="1200" height="800"><rect width="1200" height="800" fill="#5b7f6a"/></svg>',
+ }),
+ );
+ await page.goto(
+ `${storybook.origin}/iframe.html?id=core-lightbox--with-zoom&viewMode=story`,
+ );
+ await page.getByRole('button', {name: 'Open with zoom'}).click();
+ const dialog = page.getByRole('dialog');
+ await expect(dialog).toBeVisible();
+ const zoom = dialog.getByRole('button', {name: 'Zoom'});
+ await expect(zoom).toHaveAttribute('aria-pressed', 'false');
+
+ await page.keyboard.press('+');
+ await expect(zoom).toHaveAttribute('aria-pressed', 'true');
+ await expect(
+ page.locator('dialog[open] > [data-astryx-modal-live-region="polite"]'),
+ ).toContainText('Zoomed in');
+
+ await page.keyboard.press('0');
+ await expect(zoom).toHaveAttribute('aria-pressed', 'false');
+});
diff --git a/packages/core/src/Lightbox/__tests__/LightboxAudit.a11y.chromium.spec.ts b/packages/core/src/Lightbox/__tests__/LightboxAudit.a11y.chromium.spec.ts
new file mode 100644
index 0000000000..410e848ca8
--- /dev/null
+++ b/packages/core/src/Lightbox/__tests__/LightboxAudit.a11y.chromium.spec.ts
@@ -0,0 +1,490 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+// @pr-a11y audit Lightbox
+
+/**
+ * @file LightboxAudit.a11y.chromium.spec.ts
+ * @input Exact-head Core/Lightbox stories across themes, modes, direction, and width
+ * @output Screenshots and fail-closed sensor receipts for the Lightbox whole-component audit
+ * @position Component-owned Night Watch browser evidence; CI runs it only for a Lightbox audit pull request
+ */
+
+import {createHash} from 'node:crypto';
+import {execFileSync} from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {expect, test, type Page} from '@astryxdesign/a11y-spec/playwright';
+import {holdMotionStill} from '@astryxdesign/a11y-spec/chromium';
+import {
+ DEFAULT_STORYBOOK_DIR,
+ serveStorybook,
+ type StaticServer,
+} from '@astryxdesign/a11y-spec/storybook';
+
+const OUTPUT = path.resolve('lightbox-audit-evidence');
+const WIDE = {width: 1280, height: 800};
+const NARROW = {width: 320, height: 640};
+
+type Mode = 'light' | 'dark';
+type Theme = 'neutral' | 'butter';
+type Direction = 'ltr' | 'rtl';
+type Story = 'gallery-with-zoom' | 'default' | 'video';
+
+type AuditCase = {
+ key: string;
+ story: Story;
+ mode: Mode;
+ theme: Theme;
+ direction: Direction;
+ viewport: {width: number; height: number};
+};
+
+type AuditReceipt = {
+ passed: boolean;
+ expected: Record<string, unknown>;
+ failures: string[];
+};
+
+// The button each story opens the viewer with.
+const OPENER: Record<Story, string> = {
+ 'gallery-with-zoom': 'Open gallery with zoom',
+ default: 'Open lightbox',
+ video: 'Open video',
+};
+
+const cases: AuditCase[] = [];
+function add(
+ story: Story,
+ options: {
+ theme?: Theme;
+ direction?: Direction;
+ modes?: Mode[];
+ viewport?: {width: number; height: number};
+ suffix?: string;
+ } = {},
+) {
+ const theme = options.theme ?? 'neutral';
+ const direction = options.direction ?? 'ltr';
+ for (const mode of options.modes ?? ['light', 'dark']) {
+ const parts: string[] = [story, options.suffix ?? '', theme];
+ if (direction === 'rtl') {
+ parts.push('rtl');
+ }
+ cases.push({
+ key: `${parts.filter(Boolean).join('-')}-${mode}`,
+ story,
+ mode,
+ theme,
+ direction,
+ viewport: options.viewport ?? WIDE,
+ });
+ }
+}
+
+add('gallery-with-zoom');
+add('gallery-with-zoom', {theme: 'butter', modes: ['light']});
+add('gallery-with-zoom', {direction: 'rtl', modes: ['light']});
+add('gallery-with-zoom', {
+ suffix: 'narrow',
+ modes: ['light'],
+ viewport: NARROW,
+});
+add('default');
+add('video', {modes: ['light']});
+
+test.describe.configure({retries: 0});
+let server: StaticServer;
+let checkoutSha: string;
+let storybookSha: string;
+
+// The stories' photos are remote. Each is replaced by one local picture, so
+// every frame is the same on every run.
+const PHOTO = `<svg xmlns="http://www.w3.org/2000/svg" width="1200" height="800" viewBox="0 0 1200 800"><rect width="1200" height="800" fill="#5b7f6a"/><rect x="0" y="520" width="1200" height="280" fill="#3d5a48"/><circle cx="900" cy="220" r="110" fill="#e9d8a6"/></svg>`;
+
+function storyUrl(item: AuditCase) {
+ return `${server.origin}/iframe.html?id=core-lightbox--${item.story}&viewMode=story&globals=colorMode:${item.mode};astryxTheme:${item.theme};direction:${item.direction}`;
+}
+
+async function settle(page: Page) {
+ await holdMotionStill(page);
+ await page.evaluate(async () => document.fonts.ready);
+ await page.evaluate(
+ async () =>
+ new Promise<void>(resolve =>
+ requestAnimationFrame(() => requestAnimationFrame(() => resolve())),
+ ),
+ );
+ await page.waitForTimeout(60);
+}
+
+async function observe(page: Page) {
+ return page.evaluate(() => {
+ const round = (value: number) => Math.round(value * 10) / 10;
+ function box(element: Element | null) {
+ if (element == null) {
+ return null;
+ }
+ const rect = element.getBoundingClientRect();
+ return {
+ left: round(rect.left),
+ top: round(rect.top),
+ right: round(rect.right),
+ bottom: round(rect.bottom),
+ width: round(rect.width),
+ height: round(rect.height),
+ };
+ }
+ const dialog = document.querySelector('dialog.astryx-lightbox');
+ const isDisabled = (button: HTMLButtonElement) =>
+ button.disabled || button.getAttribute('aria-disabled') === 'true';
+ const buttonNamed = (name: string) =>
+ Array.from(dialog?.querySelectorAll('button') ?? []).find(
+ button => button.getAttribute('aria-label') === name,
+ ) ?? null;
+ const close = buttonNamed('Close');
+ const previous = buttonNamed('Previous');
+ const next = buttonNamed('Next');
+ const zoom = dialog?.querySelector('[aria-pressed]') ?? null;
+ const active = document.activeElement;
+ const modalRegion = dialog?.querySelector(
+ ':scope > [data-astryx-modal-live-region="polite"]',
+ );
+ const sharedRegion = document.querySelector(
+ '[data-astryx-live-region="polite"]',
+ );
+ return {
+ theme: document
+ .querySelector('[data-astryx-theme]')
+ ?.getAttribute('data-astryx-theme'),
+ mode: document.documentElement.getAttribute('data-theme'),
+ viewport: {width: innerWidth, height: innerHeight},
+ dpr: devicePixelRatio,
+ reducedMotion: matchMedia('(prefers-reduced-motion: reduce)').matches,
+ fonts: document.fonts.status,
+ storybookError:
+ document.querySelector('.sb-show-errordisplay') != null ||
+ document.body.classList.contains('sb-show-errordisplay'),
+ dialog:
+ dialog == null
+ ? null
+ : {
+ isModal: dialog.matches(':modal'),
+ name: dialog.getAttribute('aria-label'),
+ targets: Array.from(dialog.classList).filter(name =>
+ name.startsWith('astryx-'),
+ ),
+ direction: getComputedStyle(dialog).direction,
+ box: box(dialog),
+ text: (dialog as HTMLElement).innerText,
+ },
+ focusInside: dialog != null && active != null && dialog.contains(active),
+ buttons: {
+ close: close == null ? null : {box: box(close)},
+ previous:
+ previous == null
+ ? null
+ : {box: box(previous), disabled: isDisabled(previous)},
+ next:
+ next == null ? null : {box: box(next), disabled: isDisabled(next)},
+ },
+ zoomPressed: zoom?.getAttribute('aria-pressed') ?? null,
+ video: dialog?.querySelector('video')?.hasAttribute('controls') ?? null,
+ modalRegion: modalRegion?.textContent ?? null,
+ sharedRegion: sharedRegion?.textContent ?? null,
+ };
+ });
+}
+
+test.beforeAll(async () => {
+ fs.mkdirSync(OUTPUT, {recursive: true});
+ checkoutSha = execFileSync('git', ['rev-parse', 'HEAD'], {
+ encoding: 'utf8',
+ }).trim();
+ const expected = process.env.ASTRYX_HEAD_SHA;
+ if (expected && expected !== checkoutSha) {
+ throw new Error(
+ `checkout ${checkoutSha} does not match expected head ${expected}`,
+ );
+ }
+ server = await serveStorybook(
+ process.env.ASTRYX_STORYBOOK_DIR ?? DEFAULT_STORYBOOK_DIR,
+ );
+ const response = await fetch(`${server.origin}/astryx-build-sha.txt`);
+ if (!response.ok) {
+ throw new Error(`Storybook build has no SHA stamp (${response.status})`);
+ }
+ storybookSha = (await response.text()).trim();
+ if (storybookSha !== checkoutSha) {
+ throw new Error(
+ `Storybook ${storybookSha} does not match checkout ${checkoutSha}`,
+ );
+ }
+});
+
+test.afterAll(async () => {
+ await server?.close();
+});
+
+for (const item of cases) {
+ test(item.key, async ({browser}) => {
+ const context = await browser.newContext({
+ viewport: item.viewport,
+ deviceScaleFactor: 2,
+ colorScheme: item.mode,
+ reducedMotion: 'reduce',
+ });
+ const page = await context.newPage();
+ const pageErrors: string[] = [];
+ page.on('pageerror', error => pageErrors.push(String(error)));
+ await page.route(/picsum\.photos/, async route =>
+ route.fulfill({contentType: 'image/svg+xml', body: PHOTO}),
+ );
+ // The video is remote too; without it the frame shows the empty player.
+ await page.route(/\.webm$/, async route => route.abort());
+ await page.goto(storyUrl(item), {waitUntil: 'load'});
+ await page.getByRole('button', {name: OPENER[item.story]}).click();
+ await page.locator('dialog.astryx-lightbox[open]').waitFor();
+ await settle(page);
+
+ const failures: string[] = [];
+ const check = (condition: boolean, message: string) => {
+ if (!condition) {
+ failures.push(message);
+ }
+ };
+ const frames: {state: string; file: string; sha256: string}[] = [];
+ const observations: Record<string, unknown> = {};
+ async function capture(state: string) {
+ await settle(page);
+ const png = await page.screenshot({animations: 'disabled'});
+ check(png.length > 1000, `${state} screenshot is empty`);
+ const file = `${item.key}-${state}.png`;
+ fs.writeFileSync(path.join(OUTPUT, file), png);
+ frames.push({
+ state,
+ file,
+ sha256: createHash('sha256').update(png).digest('hex'),
+ });
+ }
+
+ const opened = await observe(page);
+ observations.opened = opened;
+ check(storybookSha === checkoutSha, 'storybook build mismatch');
+ check(!opened.storybookError, 'storybook error display');
+ check(opened.theme === item.theme, `theme ${opened.theme}`);
+ check(opened.mode === item.mode, `mode ${opened.mode}`);
+ check(
+ opened.viewport.width === item.viewport.width &&
+ opened.viewport.height === item.viewport.height,
+ 'viewport mismatch',
+ );
+ check(opened.dpr === 2, `dpr ${opened.dpr}`);
+ check(opened.reducedMotion, 'reduced motion not applied');
+ check(opened.fonts === 'loaded', `fonts ${opened.fonts}`);
+ check(opened.dialog != null, 'no open viewer');
+ check(opened.dialog?.isModal === true, 'the viewer is not modal');
+ check(
+ JSON.stringify(opened.dialog?.targets) === '["astryx-lightbox"]',
+ `targets ${opened.dialog?.targets.join(' ')}`,
+ );
+ check(
+ opened.dialog?.direction === item.direction,
+ `direction ${opened.dialog?.direction}`,
+ );
+ check(opened.focusInside, 'focus is not inside the open viewer');
+ check(opened.buttons.close != null, 'no Close button');
+
+ if (item.story === 'gallery-with-zoom') {
+ check(
+ opened.dialog?.name === 'Forest path',
+ `name ${opened.dialog?.name}`,
+ );
+ check(
+ opened.dialog?.text.includes('1 / 4') === true,
+ 'counter does not read 1 / 4',
+ );
+ check(
+ opened.buttons.previous?.disabled === true &&
+ opened.buttons.next?.disabled === false,
+ `at the start, previous ${opened.buttons.previous?.disabled} next ${opened.buttons.next?.disabled}`,
+ );
+ const close = opened.buttons.close?.box;
+ const previous = opened.buttons.previous?.box;
+ const next = opened.buttons.next?.box;
+ if (previous != null && next != null) {
+ // Next sits at the inline end: the right in LTR, the left in RTL.
+ check(
+ next.left > previous.left === (item.direction === 'ltr'),
+ `previous ${previous.left} next ${next.left} in ${item.direction}`,
+ );
+ }
+ for (const [name, target] of Object.entries({close, previous, next})) {
+ check(
+ target != null && target.width >= 24 && target.height >= 24,
+ `${name} target ${JSON.stringify(target)}`,
+ );
+ }
+ await capture('first');
+
+ // Moving to another item announces it with its position, inside the
+ // open viewer, where a screen reader hears it.
+ await page.keyboard.press(
+ item.direction === 'rtl' ? 'ArrowLeft' : 'ArrowRight',
+ );
+ await page.waitForFunction(() =>
+ document
+ .querySelector('dialog.astryx-lightbox')
+ ?.getAttribute('aria-label')
+ ?.includes('Mountain lake'),
+ );
+ await page.waitForTimeout(250);
+ const paged = await observe(page);
+ observations.paged = paged;
+ check(
+ paged.dialog?.text.includes('2 / 4') === true,
+ 'counter does not read 2 / 4 after paging',
+ );
+ check(
+ paged.modalRegion?.includes('Mountain lake, 2 of 4') === true,
+ `position message inside the viewer: ${JSON.stringify(paged.modalRegion)}; on the page: ${JSON.stringify(paged.sharedRegion)}`,
+ );
+ check(
+ !(paged.sharedRegion ?? '').includes('Mountain lake'),
+ `position message reached the page: ${JSON.stringify(paged.sharedRegion)}`,
+ );
+
+ // Keyboard zoom: + zooms in and is announced inside the viewer; 0
+ // returns the photo to its fitted size.
+ await page.keyboard.press('+');
+ await page.waitForTimeout(400);
+ const zoomed = await observe(page);
+ observations.zoomed = zoomed;
+ check(zoomed.zoomPressed === 'true', `zoom ${zoomed.zoomPressed}`);
+ check(
+ zoomed.modalRegion?.includes('Zoomed in') === true,
+ `zoom message inside the viewer: ${JSON.stringify(zoomed.modalRegion)}; on the page: ${JSON.stringify(zoomed.sharedRegion)}`,
+ );
+ check(
+ !(zoomed.sharedRegion ?? '').includes('Zoomed'),
+ `zoom message reached the page: ${JSON.stringify(zoomed.sharedRegion)}`,
+ );
+ check(zoomed.focusInside, 'focus left the viewer while zoomed');
+ await capture('zoomed');
+ await page.keyboard.press('0');
+ await page.waitForTimeout(400);
+ const reset = await observe(page);
+ observations.reset = reset;
+ check(
+ reset.zoomPressed === 'false',
+ `after 0 the zoom is ${reset.zoomPressed}`,
+ );
+ await capture('fitted');
+ } else if (item.story === 'default') {
+ check(
+ opened.dialog?.name === 'Forest path',
+ `name ${opened.dialog?.name}`,
+ );
+ check(
+ opened.buttons.previous == null && opened.buttons.next == null,
+ 'a single item shows gallery buttons',
+ );
+ check(
+ opened.dialog?.text.includes('A winding path through the forest') ===
+ true,
+ 'caption missing',
+ );
+ check(!/\d+ \/ \d+/.test(opened.dialog?.text ?? ''), 'counter shown');
+ check(opened.zoomPressed == null, 'zoom target without hasZoom');
+ await capture('open');
+ } else {
+ check(opened.video === true, `video controls ${opened.video}`);
+ await capture('open');
+ }
+
+ // Escape closes the viewer and focus returns to its opener.
+ await page.keyboard.press('Escape');
+ await page.waitForTimeout(200);
+ const closed = await page.evaluate(() => ({
+ open: document
+ .querySelector('dialog.astryx-lightbox')
+ ?.hasAttribute('open'),
+ focused: document.activeElement?.textContent ?? null,
+ }));
+ observations.closed = closed;
+ check(closed.open !== true, 'Escape did not close the viewer');
+ check(
+ closed.focused === OPENER[item.story],
+ `focus after close: ${closed.focused}`,
+ );
+ check(pageErrors.length === 0, `page errors: ${pageErrors.join(' | ')}`);
+
+ const receipt = {
+ schemaVersion: 1,
+ expected: {
+ build: checkoutSha,
+ storyId: `core-lightbox--${item.story}`,
+ mode: item.mode,
+ theme: item.theme,
+ direction: item.direction,
+ viewport: item.viewport,
+ viewer:
+ 'one modal dialog carrying only the astryx-lightbox target, in the page direction, named by the active item, with focus inside and a Close button',
+ gallery:
+ item.story === 'gallery-with-zoom'
+ ? 'counter 1 / 4; Previous disabled at the start; Next at the inline end; targets at least 24px; paging announces "<alt>, 2 of 4" inside the open viewer and not on the page; + zooms in, is announced inside the viewer and not on the page, and 0 returns to the fitted size'
+ : 'not applicable',
+ close: 'Escape closes the viewer and focus returns to the opener',
+ },
+ observed: {build: storybookSha, ...observations, pageErrors},
+ frames,
+ failures,
+ passed: failures.length === 0,
+ };
+ fs.writeFileSync(
+ path.join(OUTPUT, `${item.key}.sensors.json`),
+ `${JSON.stringify(receipt, null, 2)}\n`,
+ );
+ await context.close();
+ expect(failures).toEqual([]);
+ });
+}
+
+test('manifest is complete', async () => {
+ const receipts = cases.map(item => {
+ const file = path.join(OUTPUT, `${item.key}.sensors.json`);
+ return {
+ key: item.key,
+ receipt: fs.existsSync(file)
+ ? (JSON.parse(fs.readFileSync(file, 'utf8')) as AuditReceipt)
+ : null,
+ };
+ });
+ fs.writeFileSync(
+ path.join(OUTPUT, 'manifest.json'),
+ `${JSON.stringify(
+ {
+ schemaVersion: 1,
+ component: 'core/Lightbox',
+ build: checkoutSha,
+ cases: cases.map(item => ({
+ key: item.key,
+ receipt: `${item.key}.sensors.json`,
+ })),
+ },
+ null,
+ 2,
+ )}\n`,
+ );
+ expect(
+ receipts.filter(({receipt}) => receipt == null).map(({key}) => key),
+ ).toEqual([]);
+ expect(
+ receipts
+ .filter(({receipt}) => receipt?.expected.build !== checkoutSha)
+ .map(({key}) => key),
+ ).toEqual([]);
+ expect(
+ receipts
+ .filter(({receipt}) => receipt?.passed !== true)
+ .map(({key, receipt}) => ({case: key, failures: receipt?.failures})),
+ ).toEqual([]);
+});
diff --git a/packages/core/src/hooks/useAnnounce.modal.test.tsx b/packages/core/src/hooks/useAnnounce.modal.test.tsx
index afd54d2459..39fbc5fec2 100644
--- a/packages/core/src/hooks/useAnnounce.modal.test.tsx
+++ b/packages/core/src/hooks/useAnnounce.modal.test.tsx
@@ -318,6 +318,24 @@ describe('useAnnounce inside Astryx modals (spec:AST-086 FR14)', () => {
expect(shared()?.textContent ?? '').toBe('');
});
+ it("routes Lightbox's own position message into its open viewer", async () => {
+ render(
+ <Lightbox
+ isOpen
+ onOpenChange={() => {}}
+ media={[
+ {src: '/a.jpg', alt: 'Harbour'},
+ {src: '/b.jpg', alt: 'Lighthouse'},
+ ]}
+ />,
+ );
+ fireEvent.click(screen.getByRole('button', {name: 'Next'}));
+ await nextFrame();
+ const dialog = screen.getByRole('dialog', {name: 'Lighthouse'});
+ expect(regionIn(dialog)).toHaveTextContent('Lighthouse, 2 of 2');
+ expect(shared()?.textContent ?? '').toBe('');
+ });
+
it('keeps the shared channel inside a non-modal sheet with no modal above it', async () => {
render(
<BottomSheet