feat(cdk/a11y): add input to control the duration of the aria live directive (#15275)

Adds an input that allows the consumer to control how long it takes before the messages
that are announced by `CdkAriaLive` to be cleared from the DOM.

Author: crisbeto

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

@@ -1,8 +1,8 @@
 import {MutationObserverFactory} from '@angular/cdk/observers';
-import {Component, Input} from '@angular/core';
+import {Component} from '@angular/core';
 import {ComponentFixture, fakeAsync, flush, inject, TestBed, tick} from '@angular/core/testing';
 import {By} from '@angular/platform-browser';
-import {A11yModule, AriaLivePoliteness} from '../index';
+import {A11yModule} from '../index';
 import {LiveAnnouncer} from './live-announcer';
 import {
   LIVE_ANNOUNCER_ELEMENT_TOKEN,
@@ -280,7 +280,7 @@ describe('CdkAriaLive', () => {
     invokeMutationCallbacks();
     flush();
 
-    expect(announcer.announce).toHaveBeenCalledWith('New content', 'polite');
+    expect(announcer.announce).toHaveBeenCalledWith('New content', 'polite', undefined);
   }));
 
   it('should dynamically update the politeness', fakeAsync(() => {
@@ -289,7 +289,7 @@ describe('CdkAriaLive', () => {
     invokeMutationCallbacks();
     flush();
 
-    expect(announcer.announce).toHaveBeenCalledWith('New content', 'polite');
+    expect(announcer.announce).toHaveBeenCalledWith('New content', 'polite', undefined);
 
     announcerSpy.calls.reset();
     fixture.componentInstance.politeness = 'off';
@@ -307,7 +307,7 @@ describe('CdkAriaLive', () => {
     invokeMutationCallbacks();
     flush();
 
-    expect(announcer.announce).toHaveBeenCalledWith('Newest content', 'assertive');
+    expect(announcer.announce).toHaveBeenCalledWith('Newest content', 'assertive', undefined);
   }));
 
   it('should not announce the same text multiple times', fakeAsync(() => {
@@ -324,6 +324,16 @@ describe('CdkAriaLive', () => {
 
     expect(announcer.announce).toHaveBeenCalledTimes(1);
   }));
+
+  it('should be able to pass in a duration', fakeAsync(() => {
+    fixture.componentInstance.content = 'New content';
+    fixture.componentInstance.duration = 1337;
+    fixture.detectChanges();
+    invokeMutationCallbacks();
+    flush();
+
+    expect(announcer.announce).toHaveBeenCalledWith('New content', 'polite', 1337);
+  }));
 });
 
 function getLiveElement(): Element {
@@ -339,8 +349,14 @@ class TestApp {
   }
 }
 
-@Component({template: `<div [cdkAriaLive]="politeness ? politeness : null">{{content}}</div>`})
+@Component({
+  template: `
+    <div
+      [cdkAriaLive]="politeness ? politeness : null"
+      [cdkAriaLiveDuration]="duration">{{content}}</div>`,
+})
 class DivWithCdkAriaLive {
-  @Input() politeness: AriaLivePoliteness;
-  @Input() content = 'Initial content';
+  politeness = 'polite';
+  content = 'Initial content';
+  duration: number;
 }

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

@@ -198,7 +198,7 @@ export class CdkAriaLive implements OnDestroy {
           // The `MutationObserver` fires also for attribute
           // changes which we don't want to announce.
           if (elementText !== this._previousAnnouncedText) {
-            this._liveAnnouncer.announce(elementText, this._politeness);
+            this._liveAnnouncer.announce(elementText, this._politeness, this.duration);
             this._previousAnnouncedText = elementText;
           }
         });
@@ -207,6 +207,9 @@ export class CdkAriaLive implements OnDestroy {
   }
   private _politeness: AriaLivePoliteness = 'polite';
 
+  /** Time in milliseconds after which to clear out the announcer element. */
+  @Input('cdkAriaLiveDuration') duration: number;
+
   private _previousAnnouncedText?: string;
   private _subscription: Subscription | null;
 

tools/public_api_guard/cdk/a11y.md

@@ -67,12 +67,13 @@ export const CDK_DESCRIBEDBY_ID_PREFIX = "cdk-describedby-message";
 // @public
 export class CdkAriaLive implements OnDestroy {
     constructor(_elementRef: ElementRef, _liveAnnouncer: LiveAnnouncer, _contentObserver: ContentObserver, _ngZone: NgZone);
+    duration: number;
     // (undocumented)
     ngOnDestroy(): void;
     get politeness(): AriaLivePoliteness;
     set politeness(value: AriaLivePoliteness);
     // (undocumented)
-    static ɵdir: i0.ɵɵDirectiveDeclaration<CdkAriaLive, "[cdkAriaLive]", ["cdkAriaLive"], { "politeness": "cdkAriaLive"; }, {}, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<CdkAriaLive, "[cdkAriaLive]", ["cdkAriaLive"], { "politeness": "cdkAriaLive"; "duration": "cdkAriaLiveDuration"; }, {}, never>;
     // (undocumented)
     static ɵfac: i0.ɵɵFactoryDeclaration<CdkAriaLive, never>;
 }