fix(modal): focus the dialog wrapper on present so screen readers can enter the modal (#31260)

Issue number: internal

---------

## What is the current behavior?
When a modal is opened with Android TalkBack enabled, the screen reader
cannot enter or navigate the modal's content. On present, focus is moved
to the modal host, but the host is role-less. The `role="dialog"`,
`aria-modal`, and the label live on the inner `.ion-overlay-wrapper` so
assistive technologies have no dialog to land on.

## What is the new behavior?
- `present()` now focuses the overlay's `[role="dialog"]` element (the
wrapper) instead of the role-less host, falling back to the host when
the role is on the host (action-sheet, loading).
- The modal wrapper gets `tabIndex="-1"` so it can receive that
programmatic focus (an element with only `role="dialog"` is not
focusable). Its focus ring is suppressed since the focus is
programmatic, not keyboard-driven.
- Clears text selection when gestures start to prevent Firefox from
interrupting swipe-to-close and sheet gestures.
- Adds an e2e test to `modal/test/a11y/modal.e2e.ts` to verify no
visible outline added to the wrapper.
- Adds e2e tests to `utils/test/overlays/overlays.e2e.ts` to verify the
focus is on the wrapper instead of the host for all modals.
- Fixes Playwright test helper to clear text selection immediately after
`mouse.down()` to prevent the selection from blocking gesture detection
in the test environment.

---------

Co-authored-by: Brandy Smith <brandyscarney@users.noreply.github.com>
Co-authored-by: Brandy Smith <6577830+brandyscarney@users.noreply.github.com>

Author: gnbm

core/src/components/modal/gestures/sheet.ts

@@ -299,6 +299,13 @@ export const createSheetGesture = (
   };
 
   const onStart = (detail: GestureDetail) => {
+    /**
+     * Firefox automatically selects the header text during drag
+     * due to the focusable wrapper (tabindex="-1"). Remove any
+     * selection that may have occurred.
+     */
+    window.getSelection()?.removeAllRanges();
+
     /**
      * If canDismiss is anything other than `true`
      * then users should be able to swipe down

core/src/components/modal/gestures/swipe-to-close.ts

@@ -116,6 +116,13 @@ export const createSwipeToCloseGesture = (
   const onStart = (detail: GestureDetail) => {
     const { deltaY } = detail;
 
+    /**
+     * Firefox automatically selects the header text during drag
+     * due to the focusable wrapper (tabindex="-1"). Remove any
+     * selection that may have occurred.
+     */
+    window.getSelection()?.removeAllRanges();
+
     /**
      * Get the initial scrollY value so
      * that we can correctly reset the scrollY

core/src/components/modal/modal.scss

@@ -84,6 +84,14 @@ ion-backdrop {
   z-index: 10;
 }
 
+/**
+ * The wrapper receives programmatic focus for screen readers but should not
+ * show a visible focus ring, which is meant only for keyboard navigation.
+ */
+.modal-wrapper {
+  outline: none;
+}
+
 .modal-shadow {
   position: absolute;
 

core/src/components/modal/modal.tsx

@@ -1644,10 +1644,17 @@ export class Modal implements ComponentInterface, OverlayInterface {
             same element. They must also be set inside the
             shadow DOM otherwise ion-button will not be highlighted
             when using VoiceOver: https://bugs.webkit.org/show_bug.cgi?id=247134
+
+            tabIndex={-1} is required so present() can move focus to this
+            element (which carries the dialog role) instead of the role-less
+            host. role="dialog" alone does not make an element focusable, so
+            without the tabindex focus() would be a no-op and screen readers
+            may not properly announce the dialog and its content when it opens.
           */
           role="dialog"
           {...inheritedAttributes}
           aria-modal="true"
+          tabIndex={-1}
           class="modal-wrapper ion-overlay-wrapper"
           part="content"
           ref={(el) => (this.wrapperEl = el)}

core/src/components/modal/test/a11y/modal.e2e.ts

@@ -19,5 +19,22 @@ configs({ modes: ['ios'], directions: ['ltr'] }).forEach(({ title, config }) =>
       const results = await new AxeBuilder({ page }).analyze();
       expect(results.violations).toEqual([]);
     });
+
+    // The focused wrapper must not show a focus ring when opened via keyboard.
+    test('should not render a focus ring on the wrapper when presented via keyboard', async ({ page }) => {
+      await page.goto(`/src/components/modal/test/a11y`, config);
+
+      const ionModalDidPresent = await page.spyOnEvent('ionModalDidPresent');
+      const button = page.locator('#open-modal');
+      const wrapper = page.locator('ion-modal .modal-wrapper');
+
+      // Open with the keyboard so :focus-visible applies to the wrapper.
+      await button.focus();
+      await page.keyboard.press('Enter');
+      await ionModalDidPresent.next();
+
+      await expect(wrapper).toBeFocused();
+      await expect(wrapper).toHaveCSS('outline-style', 'none');
+    });
   });
 });

core/src/utils/overlays.ts

@@ -593,7 +593,29 @@ export const present = async <OverlayPresentOptions>(
    * to the overlay container.
    */
   if (overlay.keyboardClose && (document.activeElement === null || !overlay.el.contains(document.activeElement))) {
-    overlay.el.focus();
+    /**
+     * Some overlays (e.g. modal) put the dialog role and accessible label
+     * on the `.ion-overlay-wrapper` instead of the host. Screen readers
+     * need focus on the element with `role="dialog"` to properly announce
+     * and navigate the dialog.
+     *
+     * We only target wrappers with `tabindex`, since `role="dialog"` alone
+     * does not make an element focusable. If no focusable dialog wrapper
+     * exists (e.g. picker-legacy), we fall back to the host.
+     */
+    const overlayWrapper = getElementRoot(overlay.el).querySelector<HTMLElement>('[role="dialog"][tabindex]');
+    const focusTarget = overlayWrapper ?? overlay.el;
+    /**
+     * `preventScroll` keeps this a pure focus move so the viewport does not
+     * jump when the wrapper is partially off-screen (e.g. a sheet modal).
+     * Guard the options call so an older engine that mishandles it can never
+     * reject present(); we fall back to a plain focus() in that case.
+     */
+    try {
+      focusTarget.focus({ preventScroll: true });
+    } catch {
+      focusTarget.focus();
+    }
   }
 
   /**

core/src/utils/test/overlays/overlays.e2e.ts

@@ -421,5 +421,87 @@ configs({ modes: ['ios'], directions: ['ltr'] }).forEach(({ title, config }) =>
       // verify focus is in correct location
       await expect(input).toBeFocused();
     });
+
+    // Focus the role="dialog" wrapper on present so screen readers can enter.
+    test('should focus the modal wrapper on present', async ({ page }, testInfo) => {
+      testInfo.annotations.push({
+        type: 'issue',
+        description: 'FW-7611',
+      });
+      await page.setContent(
+        `
+        <ion-modal>
+          <ion-content>Modal Content</ion-content>
+        </ion-modal>
+      `,
+        config
+      );
+
+      const ionModalDidPresent = await page.spyOnEvent('ionModalDidPresent');
+      const modal = page.locator('ion-modal');
+      const wrapper = page.locator('ion-modal .modal-wrapper');
+
+      await modal.evaluate((el: HTMLIonModalElement) => el.present());
+      await ionModalDidPresent.next();
+
+      await expect(wrapper).toHaveAttribute('role', 'dialog');
+      await expect(wrapper).toBeFocused();
+    });
+
+    test('should focus the sheet modal wrapper on present', async ({ page }, testInfo) => {
+      testInfo.annotations.push({
+        type: 'issue',
+        description: 'FW-7611',
+      });
+      await page.setContent(
+        `
+        <ion-modal initial-breakpoint="0.5" breakpoints="[0, 0.5, 1]">
+          <ion-content>Sheet Modal Content</ion-content>
+        </ion-modal>
+      `,
+        config
+      );
+
+      const ionModalDidPresent = await page.spyOnEvent('ionModalDidPresent');
+      const modal = page.locator('ion-modal');
+      const wrapper = page.locator('ion-modal .modal-wrapper');
+
+      await modal.evaluate((el: HTMLIonModalElement) => el.present());
+      await ionModalDidPresent.next();
+
+      await expect(wrapper).toHaveAttribute('role', 'dialog');
+      await expect(wrapper).toBeFocused();
+    });
+
+    test('should focus the card modal wrapper on present', async ({ page }, testInfo) => {
+      testInfo.annotations.push({
+        type: 'issue',
+        description: 'FW-7611',
+      });
+      await page.setContent(
+        `
+        <div class="ion-page">
+          <ion-content>Root Content</ion-content>
+        </div>
+        <ion-modal>
+          <ion-content>Card Modal Content</ion-content>
+        </ion-modal>
+      `,
+        config
+      );
+
+      const ionModalDidPresent = await page.spyOnEvent('ionModalDidPresent');
+      const modal = page.locator('ion-modal');
+      const wrapper = page.locator('ion-modal .modal-wrapper');
+
+      await modal.evaluate((el: HTMLIonModalElement) => {
+        el.presentingElement = document.querySelector<HTMLElement>('.ion-page')!;
+        return el.present();
+      });
+      await ionModalDidPresent.next();
+
+      await expect(wrapper).toHaveAttribute('role', 'dialog');
+      await expect(wrapper).toBeFocused();
+    });
   });
 });

core/src/utils/test/playwright/drag-element.ts

@@ -35,6 +35,12 @@ export const dragElementBy = async (
 
   await page.mouse.down();
 
+  // Firefox treats focusable elements (tabindex="-1") as draggable text and
+  // initiates text selection on mouse.down(). In Playwright, this selection
+  // locks in before the gesture detector fires, blocking pointer events.
+  // Clearing it here allows the drag gesture to proceed normally.
+  await page.evaluate(() => window.getSelection()?.removeAllRanges());
+
   // Drag the element.
   await moveElement(page, startX, startY, dragByX, dragByY);