fix(material/snack-bar): flaky screen reader announcements for NVDA/JAWS (angular#20487)

Fixes a bug where NVDA won't announce polite snack bars and JAWS won't announce any.
This is because the live region (snack-bar-container) was added to the DOM, marked as a live
region, and content was added to it in the same operation. Some screen readers require the live
region to be added to the DOM, some time to pass, then content can be added. Now the snack bar
content is added to an aria-hidden div then, 150ms later, moved to a div with aria-live defined.
This won't cause any visual changes and keeps the snack bar content available immediatly after
opening. Also, no longer using the alert or status roles. Instead just using aria-live as testing
showed that NVDA will double announce with the alert role and JAWS won't announce any button text.

BREAKING CHANGE: matSnackBarHarness.getRole() replaced with .getAriaLive() due to using aria-live
rather than the alert and status roles.

Author: haywoodsloan

src/material-experimental/mdc-snack-bar/snack-bar-container.html

@@ -4,6 +4,12 @@
     the attached template/component does not contain it.
   -->
   <div class="mat-mdc-snack-bar-label" #label>
-    <ng-template cdkPortalOutlet></ng-template>
+    <!-- Initialy holds the snack bar content, will be empty after announcing to screen readers. -->
+    <div aria-hidden="true">
+      <ng-template cdkPortalOutlet></ng-template>
+    </div>
+
+    <!-- Will receive the snack bar content from the non-live div, move will happen a short delay after opening -->
+    <div [attr.aria-live]="_live"></div>
   </div>
 </div>

src/material-experimental/mdc-snack-bar/snack-bar-container.ts

@@ -6,6 +6,7 @@
  * found in the LICENSE file at https://angular.io/license
  */
 
+import {AriaLivePoliteness} from '@angular/cdk/a11y';
 import {
   BasePortalOutlet,
   CdkPortalOutlet,
@@ -19,6 +20,7 @@ import {
   ComponentRef,
   ElementRef,
   EmbeddedViewRef,
+  NgZone,
   OnDestroy,
   ViewChild,
   ViewEncapsulation
@@ -49,7 +51,6 @@ const MDC_SNACKBAR_LABEL_CLASS = 'mdc-snackbar__label';
   changeDetection: ChangeDetectionStrategy.Default,
   encapsulation: ViewEncapsulation.None,
   host: {
-    '[attr.role]': '_role',
     'class': 'mdc-snackbar mat-mdc-snack-bar-container',
     '[class.mat-snack-bar-container]': 'false',
     // Mark this element with a 'mat-exit' attribute to indicate that the snackbar has
@@ -60,14 +61,23 @@ const MDC_SNACKBAR_LABEL_CLASS = 'mdc-snackbar__label';
 })
 export class MatSnackBarContainer extends BasePortalOutlet
     implements _SnackBarContainer, AfterViewChecked, OnDestroy {
+  /** The number of milliseconds to wait before announcing the snack bar's content. */
+  private readonly _announceDelay: number = 150;
+
+  /** The timeout for announcing the snack bar's content. */
+  private _announceTimeoutId: number;
+
+  /** Subject for notifying that the snack bar has announced to screen readers. */
+  readonly _onAnnounce: Subject<void> = new Subject();
+
   /** Subject for notifying that the snack bar has exited from view. */
   readonly _onExit: Subject<void> = new Subject();
 
   /** Subject for notifying that the snack bar has finished entering the view. */
   readonly _onEnter: Subject<void> = new Subject();
 
-  /** ARIA role for the snack bar container. */
-  _role: 'alert' | 'status' | null;
+  /** aria-live value for the live region. */
+  _live: AriaLivePoliteness;
 
   /** Whether the snack bar is currently exiting. */
   _exiting = false;
@@ -103,17 +113,18 @@ export class MatSnackBarContainer extends BasePortalOutlet
   constructor(
       private _elementRef: ElementRef<HTMLElement>,
       public snackBarConfig: MatSnackBarConfig,
-      private _platform: Platform) {
+      private _platform: Platform,
+      private _ngZone: NgZone) {
     super();
 
-    // Based on the ARIA spec, `alert` and `status` roles have an
-    // implicit `assertive` and `polite` politeness respectively.
+    // Use aria-live rather than a live role like 'alert' or 'status'
+    // because NVDA and JAWS have show inconsistent behavior with live roles.
     if (snackBarConfig.politeness === 'assertive' && !snackBarConfig.announcementMessage) {
-      this._role = 'alert';
+      this._live = 'assertive';
     } else if (snackBarConfig.politeness === 'off') {
-      this._role = null;
+      this._live = 'off';
     } else {
-      this._role = 'status';
+      this._live = 'polite';
     }
 
     // `MatSnackBar` will use the config's timeout to determine when the snack bar should be closed.
@@ -141,12 +152,18 @@ export class MatSnackBarContainer extends BasePortalOutlet
     // MDC uses some browser APIs that will throw during server-side rendering.
     if (this._platform.isBrowser) {
       this._mdcFoundation.open();
+      this._screenReaderAnnounce();
     }
   }
 
   exit(): Observable<void> {
     this._exiting = true;
     this._mdcFoundation.close();
+
+    // If the snack bar hasn't been announced by the time it exits it wouldn't have been open
+    // long enough to visually read it either, so clear the timeout for announcing.
+    clearTimeout(this._announceTimeoutId);
+
     return this._onExit;
   }
 
@@ -188,4 +205,36 @@ export class MatSnackBarContainer extends BasePortalOutlet
       throw Error('Attempting to attach snack bar content after content is already attached');
     }
   }
+
+  /**
+   * Starts a timeout to move the snack bar content to the live region so screen readers will
+   * announce it.
+   */
+  private _screenReaderAnnounce() {
+    if (!this._announceTimeoutId) {
+      this._ngZone.runOutsideAngular(() => {
+        this._announceTimeoutId = setTimeout(() => {
+          const inertElement = this._elementRef.nativeElement.querySelector('[aria-hidden]');
+          const liveElement = this._elementRef.nativeElement.querySelector('[aria-live]');
+
+          if (inertElement && liveElement) {
+            // If an element in the snack bar content is focused before being moved
+            // track it and restore focus after moving to the live region.
+            let focusedElement: HTMLElement | null = null;
+            if (document.activeElement instanceof HTMLElement &&
+                inertElement.contains(document.activeElement)) {
+              focusedElement = document.activeElement;
+            }
+
+            inertElement.removeAttribute('aria-hidden');
+            liveElement.appendChild(inertElement);
+            focusedElement?.focus();
+
+            this._onAnnounce.next();
+            this._onAnnounce.complete();
+          }
+        }, this._announceDelay);
+      });
+    }
+  }
 }

src/material-experimental/mdc-snack-bar/snack-bar.spec.ts

@@ -34,6 +34,9 @@ describe('MatSnackBar', () => {
   let simpleMessage = 'Burritos are here!';
   let simpleActionLabel = 'pickup';
 
+  const announceDelay = 150;
+  const animationFrameDelay = 16;
+
   beforeEach(fakeAsync(() => {
     TestBed.configureTestingModule({
       imports: [MatSnackBarModule, SnackBarTestModule, NoopAnimationsModule],
@@ -60,44 +63,102 @@ describe('MatSnackBar', () => {
     testViewContainerRef = viewContainerFixture.componentInstance.childViewContainer;
   });
 
-  it('should have the role of `alert` with an `assertive` politeness if no announcement message ' +
-      'is provided', () => {
+  it('should open with content first in the inert region', () => {
+    snackBar.open('Snack time!', 'Chew');
+    viewContainerFixture.detectChanges();
+
+    const containerElement = overlayContainerElement.querySelector('mat-mdc-snack-bar-container')!;
+    const inertElement = containerElement.querySelector('[aria-hidden]')!;
+
+    expect(inertElement.getAttribute('aria-hidden'))
+      .toBe('true', 'Expected the non-live region to be aria-hidden');
+    expect(inertElement.textContent).toContain('Snack time!',
+        'Expected non-live region to contain the snack bar content');
+
+    const liveElement = containerElement.querySelector('[aria-live]')!;
+    expect(liveElement.childNodes.length)
+        .toBe(0, 'Expected live region to not contain any content');
+  });
+
+  it('should move content to the live region after 150ms', fakeAsync(() => {
+    snackBar.open('Snack time!', 'Chew');
+    viewContainerFixture.detectChanges();
+
+    const containerElement = overlayContainerElement.querySelector('mat-mdc-snack-bar-container')!;
+    const liveElement = containerElement.querySelector('[aria-live]')!;
+    tick(announceDelay);
+
+    expect(liveElement.textContent).toContain('Snack time!',
+        'Expected live region to contain the snack bar content');
+
+    const inertElement = containerElement.querySelector('[aria-hidden]')!;
+    expect(inertElement).toBeFalsy('Expected non-live region to not contain any content');
+    flush();
+  }));
+
+  it('should preserve focus when moving content to the live region', fakeAsync(() => {
+    snackBar.open('Snack time!', 'Chew');
+    viewContainerFixture.detectChanges();
+    tick(animationFrameDelay);
+
+    const actionButton = overlayContainerElement
+        .querySelector('.mat-mdc-simple-snack-bar .mat-mdc-snack-bar-action')! as HTMLElement;
+    actionButton.focus();
+    expect(document.activeElement)
+        .toBe(actionButton, 'Expected the focus to move to the action button');
+
+    flush();
+    expect(document.activeElement)
+        .toBe(actionButton, 'Expected the focus to remain on the action button');
+  }));
+
+  it('should have aria-live of `assertive` with an `assertive` politeness if no announcement ' +
+      'message is provided', () => {
     snackBar.openFromComponent(BurritosNotification,
         {announcementMessage: '', politeness: 'assertive'});
 
     viewContainerFixture.detectChanges();
 
     const containerElement = overlayContainerElement.querySelector('mat-mdc-snack-bar-container')!;
-    expect(containerElement.getAttribute('role'))
-        .toBe('alert', 'Expected snack bar container to have role="alert"');
+    const liveElement = containerElement.querySelector('[aria-live]')!;
+
+    expect(liveElement.getAttribute('aria-live')).toBe('assertive',
+        'Expected snack bar container live region to have aria-live="assertive"');
   });
 
-  it('should have the role of `status` with an `assertive` politeness if an announcement message ' +
-      'is provided', () => {
+  it('should have aria-live of `polite` with an `assertive` politeness if an announcement ' +
+      'message is provided', () => {
     snackBar.openFromComponent(BurritosNotification,
         {announcementMessage: 'Yay Burritos', politeness: 'assertive'});
     viewContainerFixture.detectChanges();
 
     const containerElement = overlayContainerElement.querySelector('mat-mdc-snack-bar-container')!;
-    expect(containerElement.getAttribute('role'))
-        .toBe('status', 'Expected snack bar container to have role="status"');
+    const liveElement = containerElement.querySelector('[aria-live]')!;
+
+    expect(liveElement.getAttribute('aria-live'))
+        .toBe('polite', 'Expected snack bar container live region to have aria-live="polite"');
   });
 
-  it('should have the role of `status` with a `polite` politeness', () => {
+  it('should have aria-live of `polite` with a `polite` politeness', () => {
     snackBar.openFromComponent(BurritosNotification, {politeness: 'polite'});
     viewContainerFixture.detectChanges();
 
     const containerElement = overlayContainerElement.querySelector('mat-mdc-snack-bar-container')!;
-    expect(containerElement.getAttribute('role'))
-        .toBe('status', 'Expected snack bar container to have role="status"');
+    const liveElement = containerElement.querySelector('[aria-live]')!;
+
+    expect(liveElement.getAttribute('aria-live'))
+        .toBe('polite', 'Expected snack bar container live region to have aria-live="polite"');
   });
 
   it('should remove the role if the politeness is turned off', () => {
     snackBar.openFromComponent(BurritosNotification, {politeness: 'off'});
     viewContainerFixture.detectChanges();
 
     const containerElement = overlayContainerElement.querySelector('mat-mdc-snack-bar-container')!;
-    expect(containerElement.getAttribute('role')).toBeFalsy('Expected role to be removed');
+    const liveElement = containerElement.querySelector('[aria-live]')!;
+
+    expect(liveElement.getAttribute('aria-live'))
+        .toBe('off', 'Expected snack bar container live region to have aria-live="off"');
   });
 
   it('should have exactly one MDC label element when opened through simple snack bar', () => {
@@ -197,6 +258,7 @@ describe('MatSnackBar', () => {
 
     snackBar.open(simpleMessage, undefined, {announcementMessage: simpleMessage});
     viewContainerFixture.detectChanges();
+    flush();
 
     expect(overlayContainerElement.childElementCount)
         .toBe(1, 'Expected the overlay with the default announcement message to be added');
@@ -212,6 +274,7 @@ describe('MatSnackBar', () => {
       politeness: 'assertive'
     });
     viewContainerFixture.detectChanges();
+    flush();
 
     expect(overlayContainerElement.childElementCount)
         .toBe(1, 'Expected the overlay with a custom `announcementMessage` to be added');

src/material-experimental/mdc-snack-bar/testing/BUILD.bazel

@@ -10,6 +10,7 @@ ts_library(
     ),
     module_name = "@angular/material-experimental/mdc-snack-bar/testing",
     deps = [
+        "//src/cdk/a11y",
         "//src/cdk/testing",
     ],
 )

src/material-experimental/mdc-snack-bar/testing/snack-bar-harness.ts

@@ -6,6 +6,7 @@
  * found in the LICENSE file at https://angular.io/license
  */
 
+import {AriaLivePoliteness} from '@angular/cdk/a11y';
 import {ComponentHarness, HarnessPredicate} from '@angular/cdk/testing';
 import {SnackBarHarnessFilters} from './snack-bar-harness-filters';
 
@@ -20,6 +21,7 @@ export class MatSnackBarHarness extends ComponentHarness {
   static hostSelector = '.mat-mdc-snack-bar-container:not([mat-exit])';
 
   private _simpleSnackBar = this.locatorForOptional('.mat-mdc-simple-snack-bar');
+  private _simpleSnackBarLiveRegion = this.locatorFor('[aria-live]');
   private _simpleSnackBarMessage =
       this.locatorFor('.mat-mdc-simple-snack-bar .mat-mdc-snack-bar-label');
   private _simpleSnackBarActionButton =
@@ -38,11 +40,21 @@ export class MatSnackBarHarness extends ComponentHarness {
   /**
    * Gets the role of the snack-bar. The role of a snack-bar is determined based
    * on the ARIA politeness specified in the snack-bar config.
+   * @deprecated @breaking-change 13.0.0 Use `getAriaLive` instead.
    */
   async getRole(): Promise<'alert'|'status'|null> {
     return (await this.host()).getAttribute('role') as Promise<'alert'|'status'|null>;
   }
 
+  /**
+   * Gets the aria-live of the snack-bar's live region. The aria-live of a snack-bar is
+   * determined based on the ARIA politeness specified in the snack-bar config.
+   */
+  async getAriaLive(): Promise<AriaLivePoliteness> {
+    return (await this._simpleSnackBarLiveRegion())
+        .getAttribute('aria-live') as Promise<AriaLivePoliteness>;
+  }
+
   /**
    * Whether the snack-bar has an action. Method cannot be used for snack-bar's with custom content.
    */

src/material/snack-bar/snack-bar-container.html

@@ -1 +1,7 @@
-<ng-template cdkPortalOutlet></ng-template>
+<!-- Initialy holds the snack bar content, will be empty after announcing to screen readers. -->
+<div aria-hidden="true">
+  <ng-template cdkPortalOutlet></ng-template>
+</div>
+
+<!-- Will receive the snack bar content from the non-live div, move will happen a short delay after opening -->
+<div [attr.aria-live]="_live"></div>