fix(overlays): ensure that only topmost overlay is announced by screen readers (#28997)

Issue number: resolves #23472

---------

<!-- Please do not submit updates to dependencies unless it fixes an
issue. -->

<!-- Please try to limit your pull request to one type (bugfix, feature,
etc). Submit multiple pull requests if needed. -->

## What is the current behavior?
<!-- Please describe the current behavior that you are modifying. -->

If multiple overlays are presented at the same time, none of them
receive `aria-hidden="true"`. This means that screen readers can read
contents from overlays behind the current one, which can be confusing
for users.

The original issue also reports router outlets getting `aria-hidden`
removed when any overlay is dismissed, not just the last one, but we've
since fixed that:
35ab6b4816/core/src/utils/overlays.ts (L573-L576)

## What is the new behavior?
<!-- Please describe the behavior or changes that are being added by
this PR. -->

All overlays besides the topmost one now receive `aria-hidden="true"`.
This means that screen readers will only announce the topmost overlay.

## Does this introduce a breaking change?

- [ ] Yes
- [x] No

<!--
  If this introduces a breaking change:
1. Describe the impact and migration path for existing applications
below.
  2. Update the BREAKING.md file with the breaking change.
3. Add "BREAKING CHANGE: [...]" to the commit description when merging.
See
https://github.com/ionic-team/ionic-framework/blob/main/.github/CONTRIBUTING.md#footer
for more information.
-->


## Other information

<!-- Any other information that is important to this PR such as
screenshots of how the component looks before and after the change. -->

core/src/utils/overlays.ts

@@ -491,6 +491,16 @@ export const present = async <OverlayPresentOptions>(
 
   setRootAriaHidden(true);
 
+  /**
+   * Hide all other overlays from screen readers so only this one
+   * can be read. Note that presenting an overlay always makes
+   * it the topmost one.
+   */
+  if (doc !== undefined) {
+    const presentedOverlays = getPresentedOverlays(doc);
+    presentedOverlays.forEach((o) => o.setAttribute('aria-hidden', 'true'));
+  }
+
   overlay.presented = true;
   overlay.willPresent.emit();
   overlay.willPresentShorthand?.emit();
@@ -528,6 +538,15 @@ export const present = async <OverlayPresentOptions>(
   if (overlay.keyboardClose && (document.activeElement === null || !overlay.el.contains(document.activeElement))) {
     overlay.el.focus();
   }
+
+  /**
+   * If this overlay was previously dismissed without being
+   * the topmost one (such as by manually calling dismiss()),
+   * it would still have aria-hidden on being presented again.
+   * Removing it here ensures the overlay is visible to screen
+   * readers.
+   */
+  overlay.el.removeAttribute('aria-hidden');
 };
 
 /**
@@ -625,6 +644,15 @@ export const dismiss = async <OverlayDismissOptions>(
   }
 
   overlay.el.remove();
+
+  /**
+   * If there are other overlays presented, unhide the new
+   * topmost one from screen readers.
+   */
+  if (doc !== undefined) {
+    getPresentedOverlay(doc)?.removeAttribute('aria-hidden');
+  }
+
   return true;
 };
 

core/src/utils/test/overlays/index.html

@@ -62,7 +62,7 @@
             </ion-toolbar>
           </ion-header>
           <ion-content class="ion-padding">
-            Modal Content
+            Modal ${id}
 
             <ion-item>
               <ion-input label="Text Input" class="modal-input modal-input-${id}"></ion-input>

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

@@ -129,3 +129,68 @@ describe('setRootAriaHidden()', () => {
     expect(routerOutlet.hasAttribute('aria-hidden')).toEqual(false);
   });
 });
+
+describe('aria-hidden on individual overlays', () => {
+  it('should hide non-topmost overlays from screen readers', async () => {
+    const page = await newSpecPage({
+      components: [Modal],
+      html: `
+        <ion-modal id="one"></ion-modal>
+        <ion-modal id="two"></ion-modal>
+      `,
+    });
+
+    const modalOne = page.body.querySelector<HTMLIonModalElement>('ion-modal#one')!;
+    const modalTwo = page.body.querySelector<HTMLIonModalElement>('ion-modal#two')!;
+
+    await modalOne.present();
+    await modalTwo.present();
+
+    expect(modalOne.hasAttribute('aria-hidden')).toEqual(true);
+    expect(modalTwo.hasAttribute('aria-hidden')).toEqual(false);
+  });
+
+  it('should unhide new topmost overlay from screen readers when topmost is dismissed', async () => {
+    const page = await newSpecPage({
+      components: [Modal],
+      html: `
+        <ion-modal id="one"></ion-modal>
+        <ion-modal id="two"></ion-modal>
+      `,
+    });
+
+    const modalOne = page.body.querySelector<HTMLIonModalElement>('ion-modal#one')!;
+    const modalTwo = page.body.querySelector<HTMLIonModalElement>('ion-modal#two')!;
+
+    await modalOne.present();
+    await modalTwo.present();
+
+    // dismiss modalTwo so that modalOne becomes the new topmost overlay
+    await modalTwo.dismiss();
+
+    expect(modalOne.hasAttribute('aria-hidden')).toEqual(false);
+  });
+
+  it('should not keep overlays hidden from screen readers if presented after being dismissed while non-topmost', async () => {
+    const page = await newSpecPage({
+      components: [Modal],
+      html: `
+        <ion-modal id="one"></ion-modal>
+        <ion-modal id="two"></ion-modal>
+      `,
+    });
+
+    const modalOne = page.body.querySelector<HTMLIonModalElement>('ion-modal#one')!;
+    const modalTwo = page.body.querySelector<HTMLIonModalElement>('ion-modal#two')!;
+
+    await modalOne.present();
+    await modalTwo.present();
+
+    // modalOne is not the topmost overlay at this point and is hidden from screen readers
+    await modalOne.dismiss();
+
+    // modalOne will become the topmost overlay; ensure it isn't still hidden from screen readers
+    await modalOne.present();
+    expect(modalOne.hasAttribute('aria-hidden')).toEqual(false);
+  });
+});