feat(typeahead): accessibility, options summary status message

Typeahead now announces the number of available results like 'no results available' or '3 results available' via the aria-live region

Closes #2197
Fixes #1945

src/typeahead/typeahead.module.ts

@@ -5,6 +5,7 @@ import {NgbHighlight} from './highlight';
 import {NgbTypeaheadWindow} from './typeahead-window';
 import {NgbTypeahead, NgbTypeaheadSelectItemEvent} from './typeahead';
 import {NgbTypeaheadConfig} from './typeahead-config';
+import {Live, ARIA_LIVE_DELAY, DEFAULT_ARIA_LIVE_DELAY} from './../util/accessibility/live';
 
 export {NgbHighlight} from './highlight';
 export {NgbTypeaheadWindow} from './typeahead-window';
@@ -18,5 +19,10 @@ export {NgbTypeahead, NgbTypeaheadSelectItemEvent} from './typeahead';
   entryComponents: [NgbTypeaheadWindow]
 })
 export class NgbTypeaheadModule {
-  static forRoot(): ModuleWithProviders { return {ngModule: NgbTypeaheadModule, providers: [NgbTypeaheadConfig]}; }
+  static forRoot(): ModuleWithProviders {
+    return {
+      ngModule: NgbTypeaheadModule,
+      providers: [Live, NgbTypeaheadConfig, {provide: ARIA_LIVE_DELAY, useValue: DEFAULT_ARIA_LIVE_DELAY}]
+    };
+  }
 }

src/typeahead/typeahead.spec.ts

@@ -12,6 +12,8 @@ import {NgbTypeaheadModule} from './typeahead.module';
 import {NgbTypeaheadConfig} from './typeahead-config';
 import {debounceTime, filter, map, merge} from 'rxjs/operators';
 
+import {ARIA_LIVE_DELAY} from '../util/accessibility/live';
+
 const createTestComponent = (html: string) =>
     createGenericTestComponent(html, TestComponent) as ComponentFixture<TestComponent>;
 
@@ -78,7 +80,8 @@ describe('ngb-typeahead', () => {
   beforeEach(() => {
     TestBed.configureTestingModule({
       declarations: [TestComponent, TestOnPushComponent, TestAsyncComponent],
-      imports: [NgbTypeaheadModule.forRoot(), FormsModule, ReactiveFormsModule]
+      imports: [NgbTypeaheadModule.forRoot(), FormsModule, ReactiveFormsModule],
+      providers: [{provide: ARIA_LIVE_DELAY, useValue: null}]
     });
   });
 

src/typeahead/typeahead.ts

@@ -21,6 +21,7 @@ import {positionElements, PlacementArray} from '../util/positioning';
 import {NgbTypeaheadWindow, ResultTemplateContext} from './typeahead-window';
 import {PopupService} from '../util/popup';
 import {toString, isDefined} from '../util/util';
+import {Live} from '../util/accessibility/live';
 import {NgbTypeaheadConfig} from './typeahead-config';
 import {map, switchMap, tap} from 'rxjs/operators';
 
@@ -153,7 +154,7 @@ export class NgbTypeahead implements ControlValueAccessor,
   constructor(
       private _elementRef: ElementRef, private _viewContainerRef: ViewContainerRef, private _renderer: Renderer2,
       private _injector: Injector, componentFactoryResolver: ComponentFactoryResolver, config: NgbTypeaheadConfig,
-      ngZone: NgZone) {
+      ngZone: NgZone, private _live: Live) {
     this.container = config.container;
     this.editable = config.editable;
     this.focusFirst = config.focusFirst;
@@ -355,6 +356,8 @@ export class NgbTypeahead implements ControlValueAccessor,
 
         this._showHint();
       }
+      const count = results.length;
+      this._live.say(count === 0 ? 'No results available' : `${count} result${count === 1 ? '' : 's'} available`);
     });
   }
 

src/util/accessibility/live.spec.ts

@@ -0,0 +1,55 @@
+import {TestBed, ComponentFixture, inject} from '@angular/core/testing';
+import {Component} from '@angular/core';
+import {By} from '@angular/platform-browser';
+import {Live, ARIA_LIVE_DELAY} from './live';
+
+
+
+function getLiveElement(): Element {
+  return document.body.querySelector('[aria-live]');
+}
+
+
+
+describe('LiveAnnouncer', () => {
+  let live: Live;
+  let liveElement: Element;
+  let fixture: ComponentFixture<TestComponent>;
+
+  const say = () => { fixture.debugElement.query(By.css('button')).nativeElement.click(); };
+
+  describe('live announcer', () => {
+    beforeEach(() => TestBed.configureTestingModule({
+      providers: [Live, {provide: ARIA_LIVE_DELAY, useValue: null}],
+      declarations: [TestComponent],
+    }));
+
+    beforeEach(inject([Live], (_live: Live) => {
+      live = _live;
+      liveElement = getLiveElement();
+      fixture = TestBed.createComponent(TestComponent);
+    }));
+
+    it('should correctly update the text message', () => {
+      say();
+      expect(liveElement.textContent).toBe('test');
+
+      live.ngOnDestroy();
+    });
+
+    it('should remove the used element from the DOM on destroy', () => {
+      say();
+      live.ngOnDestroy();
+
+      expect(getLiveElement()).toBeFalsy();
+    });
+  });
+});
+
+
+
+@Component({template: `<button (click)="say()">say</button>`})
+class TestComponent {
+  constructor(public live: Live) {}
+  say() { this.live.say('test'); }
+}

src/util/accessibility/live.ts

@@ -0,0 +1,51 @@
+import {Injectable, Inject, InjectionToken, OnDestroy} from '@angular/core';
+import {DOCUMENT} from '@angular/common';
+
+
+
+// usefulness (and default value) of delay documented in Material's CDK
+// https://github.com/angular/material2/blob/6405da9b8e8532a7e5c854c920ee1815c275d734/src/cdk/a11y/live-announcer/live-announcer.ts#L50
+export type ARIA_LIVE_DELAY_TYPE = number | null;
+export const ARIA_LIVE_DELAY = new InjectionToken<ARIA_LIVE_DELAY_TYPE>('live announcer delay');
+export const DEFAULT_ARIA_LIVE_DELAY: ARIA_LIVE_DELAY_TYPE = 100;
+
+
+
+function createLiveElement(document): HTMLElement {
+  const element = document.createElement('div');
+
+  element.setAttribute('aria-live', 'polite');
+  element.setAttribute('aria-atomic', 'true');
+
+  element.classList.add('sr-only');
+
+  document.body.appendChild(element);
+
+  return element;
+}
+
+
+
+@Injectable()
+export class Live implements OnDestroy {
+  private _element: HTMLElement;
+
+  constructor(@Inject(DOCUMENT) document: any, @Inject(ARIA_LIVE_DELAY) private _delay: ARIA_LIVE_DELAY_TYPE) {
+    this._element = createLiveElement(document);
+  }
+
+  ngOnDestroy() { this._element.parentElement.removeChild(this._element); }
+
+  say(message: string): void {
+    const element = this._element;
+    const delay = this._delay;
+
+    element.textContent = '';
+    const setText = () => element.textContent = message;
+    if (delay === null) {
+      setText();
+    } else {
+      setTimeout(setText, delay);
+    }
+  }
+}