feat(overlay): add keyboard dispatcher for targeting correct overlay

Author: willshowell

src/cdk/overlay/keyboard/overlay-keyboard-dispatcher.spec.ts

@@ -0,0 +1,97 @@
+import {TestBed, inject} from '@angular/core/testing';
+import {dispatchKeyboardEvent} from '@angular/cdk/testing';
+import {ESCAPE} from '@angular/cdk/keycodes';
+import {Overlay} from '../overlay';
+import {OverlayContainer} from '../overlay-container';
+import {OverlayModule} from '../index';
+import {OverlayKeyboardDispatcher} from './overlay-keyboard-dispatcher';
+
+describe('OverlayKeyboardDispatcher', () => {
+  let keyboardDispatcher: OverlayKeyboardDispatcher;
+  let overlay: Overlay;
+  let overlayContainerElement: HTMLElement;
+
+  beforeEach(() => {
+    TestBed.configureTestingModule({
+      imports: [OverlayModule],
+      providers: [
+        {provide: OverlayContainer, useFactory: () => {
+          overlayContainerElement = document.createElement('div');
+          return {getContainerElement: () => overlayContainerElement};
+        }}
+      ],
+    });
+  });
+
+  beforeEach(inject([OverlayKeyboardDispatcher, Overlay],
+        (kbd: OverlayKeyboardDispatcher, o: Overlay) => {
+    keyboardDispatcher = kbd;
+    overlay = o;
+  }));
+
+  it('should track overlays in order as they are attached and detached', () => {
+    const overlayOne = overlay.create();
+    const overlayTwo = overlay.create();
+
+    // Attach overlays
+    keyboardDispatcher.attach(overlayOne);
+    keyboardDispatcher.attach(overlayTwo);
+
+    expect(keyboardDispatcher._attachedOverlays.length)
+        .toBe(2, 'Expected both overlays to be tracked.');
+    expect(keyboardDispatcher._attachedOverlays[0]).toBe(overlayOne, 'Expected one to be first.');
+    expect(keyboardDispatcher._attachedOverlays[1]).toBe(overlayTwo, 'Expected two to be last.');
+
+    // Detach first one and re-attach it
+    keyboardDispatcher.detach(overlayOne);
+    keyboardDispatcher.attach(overlayOne);
+
+    expect(keyboardDispatcher._attachedOverlays[0])
+        .toBe(overlayTwo, 'Expected two to now be first.');
+    expect(keyboardDispatcher._attachedOverlays[1])
+        .toBe(overlayOne, 'Expected one to now be last.');
+  });
+
+  it('should dispatch body keyboard events to the most recently attached overlay', () => {
+    const overlayOne = overlay.create();
+    const overlayTwo = overlay.create();
+    const overlayOneSpy = jasmine.createSpy('overlayOne keyboard event spy');
+    const overlayTwoSpy = jasmine.createSpy('overlayOne keyboard event spy');
+
+    overlayOne.keyboardEvents().subscribe(overlayOneSpy);
+    overlayTwo.keyboardEvents().subscribe(overlayTwoSpy);
+
+    // Attach overlays
+    keyboardDispatcher.attach(overlayOne);
+    keyboardDispatcher.attach(overlayTwo);
+
+    dispatchKeyboardEvent(document.body, 'keydown', ESCAPE);
+
+    // Most recent overlay should receive event
+    expect(overlayOneSpy).not.toHaveBeenCalled();
+    expect(overlayTwoSpy).toHaveBeenCalled();
+  });
+
+  it('should dispatch targeted keyboard events to the overlay containing that target', () => {
+    const overlayOne = overlay.create();
+    const overlayTwo = overlay.create();
+    const overlayOneSpy = jasmine.createSpy('overlayOne keyboard event spy');
+    const overlayTwoSpy = jasmine.createSpy('overlayOne keyboard event spy');
+
+    overlayOne.keyboardEvents().subscribe(overlayOneSpy);
+    overlayTwo.keyboardEvents().subscribe(overlayTwoSpy);
+
+    // Attach overlays
+    keyboardDispatcher.attach(overlayOne);
+    keyboardDispatcher.attach(overlayTwo);
+
+    const overlayOnePane = overlayOne.overlayElement;
+
+    dispatchKeyboardEvent(document.body, 'keyup', ESCAPE, overlayOnePane);
+
+    // Targeted overlay should receive event
+    expect(overlayOneSpy).toHaveBeenCalled();
+    expect(overlayTwoSpy).not.toHaveBeenCalled();
+  });
+
+});

src/cdk/overlay/keyboard/overlay-keyboard-dispatcher.ts

@@ -0,0 +1,97 @@
+/**
+ * @license
+ * Copyright Google Inc. All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.io/license
+ */
+
+import {Injectable, Optional, SkipSelf, OnDestroy} from '@angular/core';
+import {OverlayRef} from '../overlay-ref';
+import {Observable} from 'rxjs/Observable';
+import {Subject} from 'rxjs/Subject';
+import {RxChain, filter, takeUntil} from '@angular/cdk/rxjs';
+import {fromEvent} from 'rxjs/observable/fromEvent';
+import {merge} from 'rxjs/observable/merge';
+
+/**
+ * Service for dispatching keyboard events that land on the body to appropriate overlay ref,
+ * if any. It maintains a list of attached overlays to determine best suited overlay based
+ * on event target and order of overlay opens.
+ */
+@Injectable()
+export class OverlayKeyboardDispatcher implements OnDestroy {
+
+  /** Currently attached overlays in the order they were attached. */
+  _attachedOverlays: OverlayRef[] = [];
+
+  /** Emits when the service is destroyed. */
+  private _onDestroy = new Subject<void>();
+
+  constructor() {
+    this._dispatchKeyboardEvents();
+  }
+
+  ngOnDestroy() {
+    this._onDestroy.next();
+    this._onDestroy.complete();
+  }
+
+  /** Add a new overlay to the list of attached overlay refs. */
+  attach(overlayRef: OverlayRef): void {
+    this._attachedOverlays.push(overlayRef);
+  }
+
+  /** Remove an overlay from the list of attached overlay refs. */
+  detach(overlayRef: OverlayRef): void {
+    const index = this._attachedOverlays.indexOf(overlayRef);
+    if (index > -1) {
+      this._attachedOverlays.splice(index, 1);
+    }
+  }
+
+  /**
+   * Subscribe to all key events that land on the body and dipatch those
+   * events to the appropriate overlay.
+   */
+  private _dispatchKeyboardEvents(): void {
+    const bodyKeyboardEvents = merge(
+        fromEvent(document.body, 'keydown'),
+        fromEvent(document.body, 'keypress'),
+        fromEvent(document.body, 'keyup')) as Observable<KeyboardEvent>;
+
+    RxChain.from(bodyKeyboardEvents)
+      .call(filter, () => !!this._attachedOverlays.length)
+      .call(takeUntil, this._onDestroy)
+      .subscribe(event => {
+        // Dispatch keyboard event to correct overlay reference
+        this._selectOverlayFromEvent(this._attachedOverlays, event)
+            ._dispatchedKeyboardEvents.next(event);
+      });
+  }
+
+  /** Select the appropriate overlay from a list of overlays and a keyboard event. */
+  private _selectOverlayFromEvent(overlays: OverlayRef[], event: KeyboardEvent): OverlayRef {
+    // Check if any overlays contain the event
+    const targetedOverlay = this._attachedOverlays.find(overlay =>
+        overlay.overlayElement.contains(event.target as HTMLElement));
+
+    return targetedOverlay ? targetedOverlay : overlays[overlays.length - 1];
+  }
+
+}
+
+/** @docs-private */
+export function OVERLAY_KEYBOARD_DISPATCHER_PROVIDER_FACTORY(
+      dispatcher: OverlayKeyboardDispatcher) {
+  return dispatcher || new OverlayKeyboardDispatcher();
+}
+
+/** @docs-private */
+export const OVERLAY_KEYBOARD_DISPATCHER_PROVIDER = {
+  // If there is already an OverlayKeyboardDispatcher available, use that.
+  // Otherwise, provide a new one.
+  provide: OverlayKeyboardDispatcher,
+  deps: [[new Optional(), new SkipSelf(), OverlayKeyboardDispatcher]],
+  useFactory: OVERLAY_KEYBOARD_DISPATCHER_PROVIDER_FACTORY
+};

src/cdk/overlay/overlay-ref.ts

@@ -22,6 +22,9 @@ export class OverlayRef implements PortalHost {
   private _backdropClick: Subject<any> = new Subject();
   private _attachments = new Subject<void>();
   private _detachments = new Subject<void>();
+  private _disposed = new Subject<void>();
+
+  _dispatchedKeyboardEvents = new Subject<KeyboardEvent>();
 
   constructor(
       private _portalHost: PortalHost,
@@ -114,6 +117,8 @@ export class OverlayRef implements PortalHost {
     this._backdropClick.complete();
     this._detachments.next();
     this._detachments.complete();
+    this._disposed.next();
+    this._disposed.complete();
   }
 
   /**
@@ -140,6 +145,16 @@ export class OverlayRef implements PortalHost {
     return this._detachments.asObservable();
   }
 
+  /** Returns an observable that emits when the overlay has been disposed. */
+  disposed(): Observable<void> {
+    return this._disposed.asObservable();
+  }
+
+  /** Returns an observable of keyboard events targeted to this overlay. */
+  keyboardEvents(): Observable<KeyboardEvent> {
+    return this._dispatchedKeyboardEvents.asObservable();
+  }
+
   /**
    * Gets the current state config of the overlay.
    */

src/cdk/overlay/overlay.spec.ts

@@ -195,19 +195,24 @@ describe('Overlay', () => {
 
   it('should emit and complete the observables when an overlay is disposed', () => {
     let overlayRef = overlay.create();
+    let detachSpy = jasmine.createSpy('detach spy');
     let disposeSpy = jasmine.createSpy('dispose spy');
     let attachCompleteSpy = jasmine.createSpy('attachCompleteSpy spy');
     let detachCompleteSpy = jasmine.createSpy('detachCompleteSpy spy');
+    let disposeCompleteSpy = jasmine.createSpy('disposeCompleteSpy spy');
 
     overlayRef.attachments().subscribe(undefined, undefined, attachCompleteSpy);
-    overlayRef.detachments().subscribe(disposeSpy, undefined, detachCompleteSpy);
+    overlayRef.detachments().subscribe(detachSpy, undefined, detachCompleteSpy);
+    overlayRef.disposed().subscribe(disposeSpy, undefined, disposeCompleteSpy);
 
     overlayRef.attach(componentPortal);
     overlayRef.dispose();
 
+    expect(detachSpy).toHaveBeenCalled();
     expect(disposeSpy).toHaveBeenCalled();
     expect(attachCompleteSpy).toHaveBeenCalled();
     expect(detachCompleteSpy).toHaveBeenCalled();
+    expect(disposeCompleteSpy).toHaveBeenCalled();
   });
 
   it('should complete the attachment observable before the detachment one', () => {

src/cdk/overlay/overlay.ts

@@ -14,9 +14,11 @@ import {
   NgZone,
 } from '@angular/core';
 import {DomPortalHost} from '@angular/cdk/portal';
+import {takeUntil} from '@angular/cdk/rxjs';
 import {OverlayState} from './overlay-state';
 import {OverlayRef} from './overlay-ref';
 import {OverlayPositionBuilder} from './position/overlay-position-builder';
+import {OverlayKeyboardDispatcher} from './keyboard/overlay-keyboard-dispatcher';
 import {OverlayContainer} from './overlay-container';
 import {ScrollStrategyOptions} from './scroll/index';
 
@@ -38,10 +40,12 @@ let defaultState = new OverlayState();
  */
 @Injectable()
 export class Overlay {
+
   constructor(public scrollStrategies: ScrollStrategyOptions,
               private _overlayContainer: OverlayContainer,
               private _componentFactoryResolver: ComponentFactoryResolver,
               private _positionBuilder: OverlayPositionBuilder,
+              private _keyboardDispatcher: OverlayKeyboardDispatcher,
               private _appRef: ApplicationRef,
               private _injector: Injector,
               private _ngZone: NgZone) { }
@@ -54,7 +58,9 @@ export class Overlay {
   create(state: OverlayState = defaultState): OverlayRef {
     const pane = this._createPaneElement();
     const portalHost = this._createPortalHost(pane);
-    return new OverlayRef(portalHost, pane, state, this._ngZone);
+    const overlayRef = new OverlayRef(portalHost, pane, state, this._ngZone);
+    this._trackOverlayAttachments(overlayRef);
+    return overlayRef;
   }
 
   /**
@@ -87,4 +93,18 @@ export class Overlay {
   private _createPortalHost(pane: HTMLElement): DomPortalHost {
     return new DomPortalHost(pane, this._componentFactoryResolver, this._appRef, this._injector);
   }
+  /**
+   * Subscribe to attach and detach events and register them accordingly
+   * with the keyboard dispatcher service.
+   */
+  private _trackOverlayAttachments(overlayRef: OverlayRef): void {
+    // Append overlay ref when attached
+    takeUntil.call(overlayRef.attachments(), overlayRef.disposed())
+      .subscribe(() => this._keyboardDispatcher.attach(overlayRef));
+
+    // Remove overlay ref when detached
+    takeUntil.call(overlayRef.detachments(), overlayRef.disposed())
+        .subscribe(() => this._keyboardDispatcher.detach(overlayRef));
+  }
+
 }

src/cdk/overlay/public_api.ts

@@ -15,13 +15,15 @@ import {
   OverlayOrigin,
 } from './overlay-directives';
 import {OverlayPositionBuilder} from './position/overlay-position-builder';
+import {OVERLAY_KEYBOARD_DISPATCHER_PROVIDER} from './keyboard/overlay-keyboard-dispatcher';
 import {OVERLAY_CONTAINER_PROVIDER} from './overlay-container';
 import {ScrollStrategyOptions} from './scroll/scroll-strategy-options';
 
 
 export const OVERLAY_PROVIDERS: Provider[] = [
   Overlay,
   OverlayPositionBuilder,
+  OVERLAY_KEYBOARD_DISPATCHER_PROVIDER,
   VIEWPORT_RULER_PROVIDER,
   OVERLAY_CONTAINER_PROVIDER,
   MD_CONNECTED_OVERLAY_SCROLL_STRATEGY_PROVIDER,

src/cdk/testing/dispatch-events.ts

@@ -20,8 +20,9 @@ export function dispatchFakeEvent(node: Node | Window, type: string): Event {
 }
 
 /** Shorthand to dispatch a keyboard event with a specified key code. */
-export function dispatchKeyboardEvent(node: Node, type: string, keyCode: number): KeyboardEvent {
-  return dispatchEvent(node, createKeyboardEvent(type, keyCode)) as KeyboardEvent;
+export function dispatchKeyboardEvent(node: Node, type: string, keyCode: number, target?: Element):
+    KeyboardEvent {
+  return dispatchEvent(node, createKeyboardEvent(type, keyCode, target)) as KeyboardEvent;
 }
 
 /** Shorthand to dispatch a mouse event on the specified coordinates. */

src/lib/dialog/dialog-ref.ts

@@ -96,6 +96,13 @@ export class MdDialogRef<T> {
     return this._overlayRef.backdropClick();
   }
 
+  /**
+   * Gets an observable that emits when keyboard events are targeted on the overlay.
+   */
+  keyboardEvents(): Observable<KeyboardEvent> {
+    return this._overlayRef.keyboardEvents();
+  }
+
   /**
    * Updates the dialog's position.
    * @param position New dialog position.