@astryxdesign/core 0.7.5 → 0.7.6-canary.5cd7a15

package/src/Dialog/Dialog.test.tsx

@@ -13,7 +13,14 @@ import {useState, type SyntheticEvent} from 'react';
 import {readFileSync} from 'node:fs';
 import {describe, it, expect, vi, beforeEach, afterEach} from 'vitest';
 import type {MockInstance} from 'vitest';
-import {render, screen, fireEvent} from '@testing-library/react';
+import {
+  render,
+  screen,
+  fireEvent,
+  within,
+  cleanup,
+} from '@testing-library/react';
+import {createPortal} from 'react-dom';
 import {
   Dialog,
   dialogFullscreenSafeAreaPaddingContract,
@@ -21,7 +28,10 @@ import {
 } from './Dialog';
 import {DialogHeader} from './DialogHeader';
 import {defineTheme, generateThemeCSS} from '../theme';
-import {__resetInteractionModalityForTest} from '../utils/interactionModality';
+import {
+  __resetInteractionModalityForTest,
+  getInteractionModality,
+} from '../utils/interactionModality';
 
 function generateThemeTestCSS(
   theme: Parameters<typeof generateThemeCSS>[0],
@@ -555,6 +565,210 @@ describe('Dialog', () => {
       }).not.toThrow();
       expect(dialog).not.toHaveAttribute('open');
     });
+
+    describe('in a second document', () => {
+      // An app can render a Dialog into a same-origin iframe or a Document
+      // Picture-in-Picture window through a portal. The control that opens it
+      // is focused in that document; the page's document reports only the
+      // iframe element.
+      let frame: HTMLIFrameElement;
+      let secondDocument: Document;
+
+      beforeEach(() => {
+        frame = document.createElement('iframe');
+        document.body.appendChild(frame);
+        secondDocument = frame.contentDocument!;
+        // The showModal/close stand-ins above, on the second window's own
+        // prototype.
+        const {prototype} = secondDocument.defaultView!.HTMLDialogElement;
+        prototype.showModal = HTMLDialogElement.prototype.showModal;
+        prototype.close = HTMLDialogElement.prototype.close;
+      });
+
+      afterEach(() => {
+        // Unmount before the frame goes, or React removes nodes from a
+        // document that no longer exists.
+        cleanup();
+        frame.remove();
+      });
+
+      function SecondDocumentDialog({isOpen}: {isOpen: boolean}) {
+        return createPortal(
+          <>
+            <button type="button">Open dialog</button>
+            <Dialog isOpen={isOpen} onOpenChange={() => {}} aria-label="Review">
+              <button type="button">Inside</button>
+            </Dialog>
+          </>,
+          secondDocument.body,
+        );
+      }
+
+      function PageOpensSecondDocumentDialog({isOpen}: {isOpen: boolean}) {
+        return (
+          <>
+            <button type="button">Open from the page</button>
+            {createPortal(
+              <Dialog
+                isOpen={isOpen}
+                onOpenChange={() => {}}
+                aria-label="Review">
+                <button type="button">Inside</button>
+              </Dialog>,
+              secondDocument.body,
+            )}
+          </>
+        );
+      }
+
+      function SecondDocumentFieldDialog({isOpen}: {isOpen: boolean}) {
+        return createPortal(
+          <>
+            <input aria-label="Search" />
+            <Dialog isOpen={isOpen} onOpenChange={() => {}} aria-label="Review">
+              <button type="button">Inside</button>
+            </Dialog>
+          </>,
+          secondDocument.body,
+        );
+      }
+
+      function SecondDocumentDialogs({count}: {count: number}) {
+        return createPortal(
+          <>
+            {count > 0 && (
+              <Dialog isOpen={false} onOpenChange={() => {}} aria-label="First">
+                First
+              </Dialog>
+            )}
+            {count > 1 && (
+              <Dialog
+                isOpen={false}
+                onOpenChange={() => {}}
+                aria-label="Second">
+                Second
+              </Dialog>
+            )}
+          </>,
+          secondDocument.body,
+        );
+      }
+
+      it('returns focus to the control that opened it, in its own document', () => {
+        const {rerender} = render(<SecondDocumentDialog isOpen={false} />);
+        const view = within(secondDocument.body);
+        const opener = view.getByRole('button', {name: 'Open dialog'});
+        opener.focus();
+        expect(document.activeElement).toBe(frame);
+
+        rerender(<SecondDocumentDialog isOpen={true} />);
+        view.getByRole('button', {name: 'Inside', hidden: true}).focus();
+
+        rerender(<SecondDocumentDialog isOpen={false} />);
+        expect(opener).toHaveFocus();
+      });
+
+      it('returns focus to a control in the page that opened it', () => {
+        const {rerender} = render(
+          <PageOpensSecondDocumentDialog isOpen={false} />,
+        );
+        const opener = screen.getByRole('button', {name: 'Open from the page'});
+        opener.focus();
+
+        rerender(<PageOpensSecondDocumentDialog isOpen={true} />);
+        within(secondDocument.body)
+          .getByRole('button', {name: 'Inside', hidden: true})
+          .focus();
+
+        rerender(<PageOpensSecondDocumentDialog isOpen={false} />);
+        expect(opener).toHaveFocus();
+      });
+
+      it('takes the ring from the last input in its own document', () => {
+        __resetInteractionModalityForTest();
+        const {rerender} = render(<SecondDocumentDialog isOpen={false} />);
+        const opener = within(secondDocument.body).getByRole('button', {
+          name: 'Open dialog',
+        });
+        // The page's last input was a pointer press (say, on the control that
+        // popped the window out); the dialog then closes from the keyboard in
+        // its own document.
+        fireEvent.pointerDown(document.body);
+        opener.focus();
+        rerender(<SecondDocumentDialog isOpen={true} />);
+        fireEvent.keyDown(secondDocument.body, {key: 'Escape'});
+        const focus = vi.spyOn(
+          secondDocument.defaultView!.HTMLElement.prototype,
+          'focus',
+        );
+
+        rerender(<SecondDocumentDialog isOpen={false} />);
+        expect(opener).toHaveFocus();
+        expect(
+          focus.mock.calls.filter(
+            (_call, index) => focus.mock.contexts[index] === opener,
+          ),
+        ).toEqual([[]]);
+        focus.mockRestore();
+      });
+
+      it('keeps plain focus on a text field that opened it after a pointer close', () => {
+        const {rerender} = render(<SecondDocumentFieldDialog isOpen={false} />);
+        const field = within(secondDocument.body).getByRole('textbox', {
+          name: 'Search',
+        });
+        field.focus();
+        rerender(<SecondDocumentFieldDialog isOpen={true} />);
+        const inside = within(secondDocument.body).getByRole('button', {
+          name: 'Inside',
+          hidden: true,
+        });
+        inside.focus();
+        fireEvent.pointerDown(inside);
+        // The field's own window's prototype: a field there is never an
+        // instance of the page's constructors.
+        const {prototype} = secondDocument.defaultView!.HTMLElement;
+        const focus = vi.spyOn(prototype, 'focus');
+        const blur = vi.spyOn(prototype, 'blur');
+
+        rerender(<SecondDocumentFieldDialog isOpen={false} />);
+        expect(field).toHaveFocus();
+        expect(
+          focus.mock.calls.filter(
+            (_call, index) => focus.mock.contexts[index] === field,
+          ),
+        ).toEqual([[]]);
+        expect(blur.mock.contexts).not.toContain(field);
+        focus.mockRestore();
+        blur.mockRestore();
+      });
+
+      it('tracks its document while any Dialog there is mounted, and releases it after the last', () => {
+        const removeEventListener = vi.spyOn(
+          secondDocument,
+          'removeEventListener',
+        );
+        const removedModalityListeners = () =>
+          removeEventListener.mock.calls
+            .map(([type]) => type)
+            .filter(type => type === 'pointerdown' || type === 'keydown')
+            .sort();
+        const {rerender} = render(<SecondDocumentDialogs count={2} />);
+        fireEvent.pointerDown(secondDocument.body);
+        expect(getInteractionModality(secondDocument)).toBe('pointer');
+
+        rerender(<SecondDocumentDialogs count={1} />);
+        fireEvent.keyDown(secondDocument.body, {key: 'Tab'});
+        expect(getInteractionModality(secondDocument)).toBe('keyboard');
+        expect(removedModalityListeners()).toEqual([]);
+
+        rerender(<SecondDocumentDialogs count={0} />);
+        expect(removedModalityListeners()).toEqual(['keydown', 'pointerdown']);
+        fireEvent.pointerDown(secondDocument.body);
+        expect(getInteractionModality(secondDocument)).toBe('keyboard');
+        removeEventListener.mockRestore();
+      });
+    });
   });
 
   // jsdom draws no focus ring, so these prove only which focus call Dialog

package/src/Dialog/Dialog.tsx

@@ -69,14 +69,18 @@ import {
   overlayPaddingReset,
 } from '../Layout/padding.stylex';
 import type {SpacingStep} from '../utils/types';
-import {mergeProps} from '../utils';
+import {mergeProps} from '../utils/mergeProps';
 import {chainEventHandlers} from '../utils/chainEventHandlers';
 import {devWarn} from '../utils/devWarning';
 import {DialogContext} from './DialogContext';
 import {themeProps} from '../utils/themeProps';
 import type {DialogVariantMap} from './index';
 import {focusOutlineProps} from '../utils/focusOutline.stylex';
-import {useInteractionModalityTracking} from '../utils/interactionModality';
+import {
+  getInteractionModality,
+  trackInteractionModalityIn,
+  useInteractionModalityTracking,
+} from '../utils/interactionModality';
 import {focusForLastInput} from '../utils/focusReturn';
 import {ModalAnnounceProvider} from '../hooks/ModalAnnounceProvider';
 
@@ -91,8 +95,11 @@ function getDialogDirection(
   distance = 16,
 ): {x: number; y: number} {
   const rect = triggerEl.getBoundingClientRect();
-  const dx = rect.left + rect.width / 2 - window.innerWidth / 2;
-  const dy = rect.top + rect.height / 2 - window.innerHeight / 2;
+  // The trigger's own window: its rect is measured in that window's viewport,
+  // which is not the page's when the dialog renders into a second document.
+  const view = triggerEl.ownerDocument.defaultView ?? window;
+  const dx = rect.left + rect.width / 2 - view.innerWidth / 2;
+  const dy = rect.top + rect.height / 2 - view.innerHeight / 2;
   const dist = Math.sqrt(dx * dx + dy * dy) || 1;
   return {
     x: Math.round((dx / dist) * distance),
@@ -534,6 +541,18 @@ export function Dialog({
 
   useInteractionModalityTracking();
 
+  // Input in a second document (a same-origin iframe, a Document
+  // Picture-in-Picture window) never reaches the page's listeners, so the
+  // dialog's own document keeps its own last input for the focus return while
+  // this Dialog is mounted, from before it opens until it unmounts.
+  useEffect(() => {
+    const ownerDocument = dialogRef.current?.ownerDocument;
+    if (ownerDocument == null || ownerDocument === document) {
+      return undefined;
+    }
+    return trackInteractionModalityIn(ownerDocument);
+  }, [isInline]);
+
   // This runs in a layout effect so the capture lands before any descendant's
   // passive mount effect: all layout effects run before any passive effect,
   // while a child's passive effect runs before this parent's passive effect.
@@ -545,7 +564,15 @@ export function Dialog({
     if (isInline || !isOpen) {
       return;
     }
-    triggerElementRef.current = document.activeElement as HTMLElement | null;
+    // The dialog's own document while it holds focus: an app can render a
+    // dialog into a second document (a same-origin iframe, a Document
+    // Picture-in-Picture window) through a portal, and a control there that
+    // opens it is focused in that document, which the page's document reports
+    // only as the iframe element, or not at all. A control in the page that
+    // opens such a dialog leaves focus in the page.
+    const dialogDocument = dialogRef.current?.ownerDocument ?? document;
+    const doc = dialogDocument.hasFocus() ? dialogDocument : document;
+    triggerElementRef.current = doc.activeElement as HTMLElement | null;
   }, [isOpen, isInline]);
 
   // Derive dismissal behavior from purpose
@@ -567,7 +594,7 @@ export function Dialog({
       // captured by the layout effect above, before any descendant effect
       // could move focus.
       const trigger = triggerElementRef.current;
-      if (trigger && trigger !== document.body) {
+      if (trigger && trigger !== trigger.ownerDocument.body) {
         const dir = getDialogDirection(trigger);
         dialog.style.setProperty('--dialog-dir-x', `${dir.x}px`);
         dialog.style.setProperty('--dialog-dir-y', `${dir.y}px`);
@@ -591,9 +618,15 @@ export function Dialog({
       if (dialog.open) {
         dialog.close();
       }
-      // Return focus to the element that opened the dialog
-      if (triggerElementRef.current) {
-        focusForLastInput(triggerElementRef.current);
+      // Return focus to the element that opened the dialog, with the ring
+      // the last input in that element's own document calls for.
+      const trigger = triggerElementRef.current;
+      if (trigger) {
+        focusForLastInput(
+          trigger,
+          undefined,
+          getInteractionModality(trigger.ownerDocument),
+        );
       }
       triggerElementRef.current = null;
     }

package/src/Dialog/DialogHeader.tsx

@@ -20,15 +20,16 @@ import {useEffect, useRef, type ReactNode} from 'react';
 import * as stylex from '@stylexjs/stylex';
 import {spacingVars, sizeVars, typeScaleVars} from '../theme/tokens.stylex';
 import {LayoutHeader} from '../Layout/LayoutHeader';
-import {Button} from '../Button';
-import {Icon} from '../Icon';
+import {Button} from '../Button/Button';
+import {Icon} from '../Icon/Icon';
 import {Heading} from '../Heading/Heading';
 import {Text} from '../Text/Text';
 import type {BaseProps} from '../BaseProps';
-import {isRenderable, mergeProps} from '../utils';
+import {isRenderable} from '../utils/isRenderable';
+import {mergeProps} from '../utils/mergeProps';
 import {themeProps} from '../utils/themeProps';
 import {useDialogContext} from './DialogContext';
-import {useTranslator} from '../i18n';
+import {useTranslator} from '../i18n/useTranslator';
 
 const styles = stylex.create({
   container: {

package/src/Dialog/__tests__/DialogSecondDocument.a11y.browser.spec.ts

@@ -0,0 +1,202 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+// @pr-a11y scope ^(packages/core/src/Dialog/|packages/core/src/utils/(focusReturn|interactionModality)\.ts|apps/storybook/stories/DialogSecondDocumentA11y)
+
+/**
+ * @file DialogSecondDocument.a11y.browser.spec.ts
+ * @input Uses @playwright/test, the a11y-spec static Storybook server, and the
+ *   checked-in DialogSecondDocumentA11y story
+ * @output Real-browser evidence that a Dialog rendered into a second document
+ *   (a same-origin iframe, a Document Picture-in-Picture window) returns focus
+ *   to the control that opened it when it closes, by Escape or by a control
+ *   inside it, exactly as the same Dialog does in the page, with the focus
+ *   ring that close's input calls for, a text field that opened it keeping
+ *   its ring with no extra blur; and that a Dialog in an iframe opened by a
+ *   control in the page returns focus to that control.
+ * @position The half of Dialog's focus return jsdom cannot reach: which
+ *   document holds focus, and the browser's own focus restore when a modal
+ *   dialog closes. The Vitest case in `Dialog/Dialog.test.tsx` models the
+ *   same rule with an iframe. Document Picture-in-Picture is Chromium's
+ *   alone, so the window's cases skip in other engines; the page and the
+ *   iframe run everywhere.
+ *
+ * SYNC: Fixture lives in
+ *   /apps/storybook/stories/DialogSecondDocumentA11y.stories.tsx.
+ */
+
+import {
+  expect,
+  test,
+  type Frame,
+  type Keyboard,
+  type Locator,
+  type Page,
+} from '@playwright/test';
+import {holdMotionStill} from '@astryxdesign/a11y-spec/chromium';
+import {
+  DEFAULT_STORYBOOK_DIR,
+  serveStorybook,
+  type StaticServer,
+} from '@astryxdesign/a11y-spec/storybook';
+
+const STORY_ID = 'a11y-dialog-in-a-second-document--second-documents';
+
+let storybook: StaticServer;
+
+test.beforeAll(async () => {
+  storybook = await serveStorybook(
+    process.env.ASTRYX_STORYBOOK_DIR ?? DEFAULT_STORYBOOK_DIR,
+  );
+});
+
+test.afterAll(async () => {
+  await storybook?.close();
+});
+
+type Where = 'page' | 'iframe' | 'Picture-in-Picture window';
+
+/** One document of the story: where its controls live and where keys go. */
+interface Surface {
+  frame: Frame;
+  keyboard: Keyboard;
+}
+
+/** Load the story and return the document the test drives. */
+async function mountStory(page: Page, where: Where): Promise<Surface> {
+  await page.goto(
+    `${storybook.origin}/iframe.html?id=${STORY_ID}&viewMode=story`,
+    {waitUntil: 'load'},
+  );
+  await holdMotionStill(page);
+  const popOut = page.getByRole('button', {name: 'Pop out'});
+  await popOut.waitFor();
+
+  if (where === 'page') {
+    return {frame: page.mainFrame(), keyboard: page.keyboard};
+  }
+  if (where === 'iframe') {
+    const element = await page
+      .locator('iframe[title="Second document"]')
+      .elementHandle();
+    const frame = await element?.contentFrame();
+    if (frame == null) {
+      throw new Error('the story renders no iframe');
+    }
+    await frame
+      .getByRole('button', {name: 'Open dialog', exact: true})
+      .waitFor();
+    // Key presses go to whichever frame holds focus; the clicks below put it
+    // in this one.
+    return {frame, keyboard: page.keyboard};
+  }
+  // Opening the window needs a user gesture; the click is one.
+  const [pictureInPicture] = await Promise.all([
+    page.context().waitForEvent('page'),
+    popOut.click(),
+  ]);
+  await pictureInPicture
+    .getByRole('button', {
+      name: 'Open dialog',
+      exact: true,
+    })
+    .waitFor();
+  return {
+    frame: pictureInPicture.mainFrame(),
+    keyboard: pictureInPicture.keyboard,
+  };
+}
+
+/** Whether the element matches `:focus-visible`, i.e. would show a ring. */
+async function showsRing(element: Locator): Promise<boolean> {
+  return element.evaluate(node => node.matches(':focus-visible'));
+}
+
+/** Open the dialog from its control with the pointer; returns the control. */
+async function open(frame: Frame): Promise<{opener: Locator; dialog: Locator}> {
+  const opener = frame.getByRole('button', {name: 'Open dialog', exact: true});
+  await opener.click();
+  const dialog = frame.getByRole('dialog', {name: 'Review changes'});
+  await expect(dialog).toBeVisible();
+  return {opener, dialog};
+}
+
+for (const where of [
+  'page',
+  'iframe',
+  'Picture-in-Picture window',
+] as const satisfies ReadonlyArray<Where>) {
+  test.describe(`a Dialog in the ${where}`, () => {
+    test.skip(
+      ({browserName}) =>
+        where === 'Picture-in-Picture window' && browserName !== 'chromium',
+      'Document Picture-in-Picture is a Chromium API',
+    );
+
+    test('closing with Escape returns focus to the control that opened it', async ({
+      page,
+    }) => {
+      const {frame, keyboard} = await mountStory(page, where);
+      const {opener, dialog} = await open(frame);
+
+      await keyboard.press('Escape');
+      await expect(dialog).toBeHidden();
+      await expect(opener).toBeFocused();
+      // A key closed it, so the ring shows (`architecture:interaction-modality`
+      // INV1), whatever the page's own last input was (a pointer press on Pop
+      // out, for the Picture-in-Picture window).
+      await expect.poll(async () => showsRing(opener)).toBe(true);
+    });
+
+    test('closing from a control inside returns focus to the control that opened it', async ({
+      page,
+    }) => {
+      const {frame} = await mountStory(page, where);
+      const {opener, dialog} = await open(frame);
+
+      await frame.getByRole('button', {name: 'Close dialog'}).click();
+      await expect(dialog).toBeHidden();
+      await expect(opener).toBeFocused();
+      // A pointer closed it, so no ring.
+      await expect.poll(async () => showsRing(opener)).toBe(false);
+    });
+
+    test('a text field that opened it keeps focus and its ring after a pointer close', async ({
+      page,
+    }) => {
+      const {frame} = await mountStory(page, where);
+      const field = frame.getByRole('textbox', {name: 'Search'});
+      await field.click();
+      await field.press('Enter');
+      const dialog = frame.getByRole('dialog', {name: 'Review changes'});
+      await expect(dialog).toBeVisible();
+      // Count the field's blurs from here on: the open already moved focus
+      // away, so any blur now would be the return's own.
+      await field.evaluate(node => {
+        node.dataset.blurs = '0';
+        node.addEventListener('blur', () => {
+          node.dataset.blurs = String(Number(node.dataset.blurs) + 1);
+        });
+      });
+
+      await frame.getByRole('button', {name: 'Close dialog'}).click();
+      await expect(dialog).toBeHidden();
+      await expect(field).toBeFocused();
+      // A text field shows where typing goes whatever moved focus there.
+      await expect.poll(async () => showsRing(field)).toBe(true);
+      await expect(field).toHaveAttribute('data-blurs', '0');
+    });
+  });
+}
+
+test.describe('a Dialog in the iframe that a control in the page opens', () => {
+  test('closing with Escape returns focus to that control', async ({page}) => {
+    const {frame, keyboard} = await mountStory(page, 'iframe');
+    const opener = page.getByRole('button', {name: 'Open dialog in the frame'});
+    await opener.click();
+    const dialog = frame.getByRole('dialog', {name: 'Opened from the page'});
+    await expect(dialog).toBeVisible();
+
+    await keyboard.press('Escape');
+    await expect(dialog).toBeHidden();
+    await expect(opener).toBeFocused();
+  });
+});

package/src/Divider/Divider.tsx

@@ -25,7 +25,8 @@ import {
   typeScaleVars,
   borderVars,
 } from '../theme/tokens.stylex';
-import {isRenderable, mergeProps} from '../utils';
+import {isRenderable} from '../utils/isRenderable';
+import {mergeProps} from '../utils/mergeProps';
 import {themeProps} from '../utils/themeProps';
 import type {DividerVariantMap} from './index';