feat(live-announcer): add ability to clear live element

Currently when we announce a message, we leave the element in place, however this can cause the element to be read out again when the user continues navigating using the arrow keys. These changes add an API where the consumer can clear the element manually or after a duration. Doing this automatically is tricky, because we'd have to make a lot of assumptions that might not be correct in all cases or may break some screen readers. These are some alternatives that were considered:

* Removing the element from the a11y tree via `aria-hidden` after the screen reader has started announcing it. This works, but because of the politeness, we can't know exactly when the screen reader will announce the text, which could end up hiding it too early.
* Clearing the element on the next `keydown`/`click`/`focus`. This could be flaky and might end up interrupting the screen reader when it doesn't have to (e.g. clicking on a non-focusable element).
* Moving the element to a different place in the DOM (e.g. prepending it to the `body` instead of appending). This works, but we'd have to keep moving the element based on the focus direction.

Fixes #11991.

Author: crisbeto

src/cdk/a11y/live-announcer/live-announcer.spec.ts

@@ -60,6 +60,34 @@ describe('LiveAnnouncer', () => {
       expect(ariaLiveElement.getAttribute('aria-live')).toBe('polite');
     }));
 
+    it('should be able to clear out the aria-live element manually', fakeAsync(() => {
+      announcer.announce('Hey Google');
+      tick(100);
+      expect(ariaLiveElement.textContent).toBe('Hey Google');
+
+      announcer.clear();
+      expect(ariaLiveElement.textContent).toBeFalsy();
+    }));
+
+    it('should be able to clear out the aria-live element by setting a duration', fakeAsync(() => {
+      announcer.announce('Hey Google', 2000);
+      tick(100);
+      expect(ariaLiveElement.textContent).toBe('Hey Google');
+
+      tick(2000);
+      expect(ariaLiveElement.textContent).toBeFalsy();
+    }));
+
+    it('should clear the duration of previous messages when announcing a new one', fakeAsync(() => {
+      announcer.announce('Hey Google', 2000);
+      tick(100);
+      expect(ariaLiveElement.textContent).toBe('Hey Google');
+
+      announcer.announce('Hello there');
+      tick(2500);
+      expect(ariaLiveElement.textContent).toBe('Hello there');
+    }));
+
     it('should remove the aria-live element from the DOM on destroy', fakeAsync(() => {
       announcer.announce('Hey Google');
 

src/cdk/a11y/live-announcer/live-announcer.ts

@@ -30,6 +30,7 @@ export type AriaLivePoliteness = 'off' | 'polite' | 'assertive';
 @Injectable({providedIn: 'root'})
 export class LiveAnnouncer implements OnDestroy {
   private readonly _liveElement: HTMLElement;
+  private _previousMessageTimeout: number;
 
   constructor(
       @Optional() @Inject(LIVE_ANNOUNCER_ELEMENT_TOKEN) elementToken: any,
@@ -43,15 +44,55 @@ export class LiveAnnouncer implements OnDestroy {
 
   /**
    * Announces a message to screenreaders.
-   * @param message Message to be announced to the screenreader
-   * @param politeness The politeness of the announcer element
+   * @param message Message to be announced to the screenreader.
    * @returns Promise that will be resolved when the message is added to the DOM.
    */
-  announce(message: string, politeness: AriaLivePoliteness = 'polite'): Promise<void> {
-    this._liveElement.textContent = '';
+  announce(message: string): Promise<void>;
+
+  /**
+   * Announces a message to screenreaders.
+   * @param message Message to be announced to the screenreader.
+   * @param politeness The politeness of the announcer element.
+   * @returns Promise that will be resolved when the message is added to the DOM.
+   */
+  announce(message: string, politeness?: AriaLivePoliteness): Promise<void>;
+
+  /**
+   * Announces a message to screenreaders.
+   * @param message Message to be announced to the screenreader.
+   * @param duration Time in milliseconds after which to clear out the announcer element. Note
+   *   that this takes effect after the message has been added to the DOM, which can be up to
+   *   100ms after `announce` has been called.
+   * @returns Promise that will be resolved when the message is added to the DOM.
+   */
+  announce(message: string, duration?: number): Promise<void>;
+
+  /**
+   * Announces a message to screenreaders.
+   * @param message Message to be announced to the screenreader.
+   * @param politeness The politeness of the announcer element.
+   * @param duration Time in milliseconds after which to clear out the announcer element. Note
+   *   that this takes effect after the message has been added to the DOM, which can be up to
+   *   100ms after `announce` has been called.
+   * @returns Promise that will be resolved when the message is added to the DOM.
+   */
+  announce(message: string, politeness?: AriaLivePoliteness, duration?: number): Promise<void>;
+
+  announce(message: string, ...args: any[]): Promise<void> {
+    let politeness: AriaLivePoliteness;
+    let duration: number;
+
+    if (args.length === 1 && typeof args[0] === 'number') {
+      duration = args[0];
+    } else {
+      [politeness, duration] = args;
+    }
+
+    this.clear();
+    clearTimeout(this._previousMessageTimeout);
 
     // TODO: ensure changing the politeness works on all environments we support.
-    this._liveElement.setAttribute('aria-live', politeness);
+    this._liveElement.setAttribute('aria-live', politeness! || 'polite');
 
     // This 100ms timeout is necessary for some browser + screen-reader combinations:
     // - Both JAWS and NVDA over IE11 will not announce anything without a non-zero timeout.
@@ -62,10 +103,25 @@ export class LiveAnnouncer implements OnDestroy {
       setTimeout(() => {
         this._liveElement.textContent = message;
         resolve();
+
+        if (typeof duration === 'number') {
+          this._previousMessageTimeout = setTimeout(() => this.clear(), duration);
+        }
       }, 100);
     });
   }
 
+  /**
+   * Clears the current text from the announcer element. Can be used to prevent
+   * screen readers from reading the text out again while the user is going
+   * through the page landmarks.
+   */
+  clear() {
+    if (this._liveElement) {
+      this._liveElement.textContent = '';
+    }
+  }
+
   ngOnDestroy() {
     if (this._liveElement && this._liveElement.parentNode) {
       this._liveElement.parentNode.removeChild(this._liveElement);

src/demo-app/live-announcer/live-announcer-demo.ts

@@ -19,6 +19,6 @@ export class LiveAnnouncerDemo {
   constructor(private live: LiveAnnouncer) {}
 
   announceText(message: string) {
-    this.live.announce(message);
+    this.live.announce(message, 1500);
   }
 }

src/lib/snack-bar/snack-bar.ts

@@ -197,6 +197,10 @@ export class MatSnackBar {
       if (this._openedSnackBarRef == snackBarRef) {
         this._openedSnackBarRef = null;
       }
+
+      if (config.announcementMessage) {
+        this._live.clear();
+      }
     });
 
     if (this._openedSnackBarRef) {