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

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, 100ms 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: Sloan Haywood

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 #nonLive aria-hidden="true" class="mat-mdc-snack-bar-container-non-live">
+      <ng-template cdkPortalOutlet></ng-template>
+    </div>
+
+    <!-- Will recieve the snack bar content from the non-live div, move will happen a short delay after opening -->
+    <div #live [attr.aria-live]="_live" class="mat-mdc-snack-bar-container-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,
@@ -49,7 +50,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 +60,23 @@ const MDC_SNACKBAR_LABEL_CLASS = 'mdc-snackbar__label';
 })
 export class MatSnackBarContainer extends BasePortalOutlet
     implements _SnackBarContainer, AfterViewChecked, OnDestroy {
+  /** Timeout for moving content to the live region for screen reader announcement. */
+  private _announceTimeoutId: number;
+
+  /** The number of milliseconds to wait after before moving content to the live region. */
+  readonly _announceDelay = 100;
+
+  /** 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;
@@ -100,20 +109,29 @@ export class MatSnackBarContainer extends BasePortalOutlet
    */
   @ViewChild('label', {static: true}) _label: ElementRef;
 
+  /**
+   * The div container that is hidden from screen readers and initially holds to snack bar
+   * content.
+   */
+  @ViewChild('nonLive', {static: true}) _nonLiveElementRef: ElementRef<HTMLElement>;
+
+  /** The div container that is a live region and will have the snack bar content move into. */
+  @ViewChild('live', {static: true}) _liveElementRef: ElementRef<HTMLElement>;
+
   constructor(
       private _elementRef: ElementRef<HTMLElement>,
       public snackBarConfig: MatSnackBarConfig,
       private _platform: Platform) {
     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 inconsitent 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 +159,19 @@ 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();
+
+    // Stop the timeout for announcing the snack bar to screen readers.
+    // If the announcement hasn't already been made the snack bar hasn't
+    // been open long enough for a sighted user to read it either.
+    clearTimeout(this._announceTimeoutId);
+
     return this._onExit;
   }
 
@@ -188,4 +213,37 @@ 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._announceTimeoutId = setTimeout(() => {
+        const nonLiveEle: HTMLElement = this._nonLiveElementRef.nativeElement;
+        const liveEle: HTMLElement = this._liveElementRef.nativeElement;
+
+        // 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 previouslyFocusedEle: HTMLElement | null = null;
+        if (document.activeElement instanceof HTMLElement &&
+            nonLiveEle.contains(document.activeElement)) {
+          previouslyFocusedEle = document.activeElement;
+        }
+
+        const nodes = Array.from(nonLiveEle.childNodes);
+        for (const node of nodes) {
+          liveEle.appendChild(node);
+        }
+
+        if (previouslyFocusedEle) {
+          previouslyFocusedEle.focus();
+        }
+
+        this._onAnnounce.next();
+        this._onAnnounce.complete();
+      }, this._announceDelay);
+    }
+  }
 }

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

@@ -60,44 +60,101 @@ 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 non-live region', () => {
+    snackBar.open('Snack time!', 'Chew');
+    viewContainerFixture.detectChanges();
+
+    const containerElement = overlayContainerElement.querySelector('mat-mdc-snack-bar-container')!;
+    const nonLiveElement = containerElement.querySelector('.mat-mdc-snack-bar-container-non-live')!;
+
+    expect(nonLiveElement.getAttribute('aria-hidden'))
+      .toBe('true', 'Expected the non-live region to be aria-hidden');
+    expect(nonLiveElement.textContent).toContain('Snack time!',
+        'Expected non-live region to contain the snack bar content');
+
+    const liveElement = containerElement.querySelector('.mat-mdc-snack-bar-container-live')!;
+    expect(liveElement.childNodes.length)
+        .toBe(0, 'Expected live region to not contain any content');
+  });
+
+  it('should move content to the live region after 100ms', fakeAsync(() => {
+    snackBar.open('Snack time!', 'Chew');
+    viewContainerFixture.detectChanges();
+
+    const containerElement = overlayContainerElement.querySelector('mat-mdc-snack-bar-container')!;
+    const liveElement = containerElement.querySelector('.mat-mdc-snack-bar-container-live')!;
+    tick(100);
+
+    expect(liveElement.textContent).toContain('Snack time!',
+        'Expected live region to contain the snack bar content');
+
+    const nonLiveElement = containerElement.querySelector('.mat-mdc-snack-bar-container-non-live')!;
+    expect(nonLiveElement.childNodes.length)
+        .toBe(0, '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();
+
+    const actionButton = overlayContainerElement
+        .querySelector('.mat-mdc-simple-snack-bar .mat-mdc-snack-bar-action')! as HTMLElement;
+    actionButton.focus();
+    tick(100);
+
+    expect(document.activeElement)
+        .toBe(actionButton, 'Expected the focus to remain on the action button');
+    flush();
+  }));
+
+  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('.mat-mdc-snack-bar-container-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('.mat-mdc-snack-bar-container-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('.mat-mdc-snack-bar-container-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('.mat-mdc-snack-bar-container-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 +254,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 +270,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('.mat-mdc-snack-bar-container-live');
   private _simpleSnackBarMessage =
       this.locatorFor('.mat-mdc-simple-snack-bar .mat-mdc-snack-bar-label');
   private _simpleSnackBarActionButton =
@@ -36,11 +38,12 @@ 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.
+   * 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 getRole(): Promise<'alert'|'status'|null> {
-    return (await this.host()).getAttribute('role') as Promise<'alert'|'status'|null>;
+  async getAriaLive(): Promise<AriaLivePoliteness> {
+    return (await this._simpleSnackBarLiveRegion())
+        .getAttribute('aria-live') as Promise<AriaLivePoliteness>;
   }
 
   /**

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 #nonLive aria-hidden="true" class="snack-bar-container-non-live">
+  <ng-template cdkPortalOutlet></ng-template>
+</div>
+
+<!-- Will recieve the snack bar content from the non-live div, move will happen a short delay after opening -->
+<div #live [attr.aria-live]="_live" class="snack-bar-container-live"></div>