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: https://github.com/ionic-team/ionic-framework/blob/35ab6b4816bd627239de8d8b25ce0c86db8c74b4/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. -->

Author: averyjohnston

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);
+ });
+});