refactor(overlay): use component to render backdrop

Uses an Angular component to render the backdrop, instead of managing a DOM element manually. This has the advantage of being able to leverage the animations API to transition in/out, as well as not having to worry about the cases where the backdrop animation is disabled.

These changes also enable the backdrop transition for the dialog (previously it would be removed immediately on close).

Author: crisbeto

src/cdk/overlay/_overlay.scss

@@ -63,8 +63,9 @@ $backdrop-animation-timing-function: cubic-bezier(0.25, 0.8, 0.25, 1) !default;
     transition: opacity $backdrop-animation-duration $backdrop-animation-timing-function;
     opacity: 0;
 
-    &.cdk-overlay-backdrop-showing {
-      opacity: 0.48;
+    // Prevent the user from interacting while the backdrop is animating.
+    &.ng-animating {
+      pointer-events: none;
     }
   }
 

src/cdk/overlay/backdrop.ts

@@ -0,0 +1,57 @@
+/**
+ * @license
+ * Copyright Google LLC 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 {
+  Component,
+  ViewEncapsulation,
+  ChangeDetectionStrategy,
+  OnDestroy,
+  ElementRef,
+} from '@angular/core';
+import {animate, AnimationEvent, state, style, transition, trigger} from '@angular/animations';
+import {Subject} from 'rxjs/Subject';
+
+/**
+ * Semi-transparent backdrop that will be rendered behind an overlay.
+ * @docs-private
+ */
+@Component({
+  moduleId: module.id,
+  template: '',
+  host: {
+    'class': 'cdk-overlay-backdrop',
+    '[@state]': '_animationState',
+    '(@state.done)': '_animationStream.next($event)',
+    '(click)': '_clickStream.next()',
+  },
+  animations: [
+    trigger('state', [
+      state('void', style({opacity: '0'})),
+      state('visible', style({opacity: '0.48'})),
+      transition('* => *', animate('400ms cubic-bezier(0.25, 0.8, 0.25, 1)')),
+    ])
+  ],
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  encapsulation: ViewEncapsulation.None,
+  preserveWhitespaces: false,
+})
+export class MatBackdrop implements OnDestroy {
+  _animationState = 'visible';
+  _clickStream = new Subject<void>();
+  _animationStream = new Subject<AnimationEvent>();
+
+  constructor(private _element: ElementRef) {}
+
+  _setClass(cssClass: string) {
+    this._element.nativeElement.classList.add(cssClass);
+  }
+
+  ngOnDestroy() {
+    this._clickStream.complete();
+  }
+}

src/cdk/overlay/overlay-directives.spec.ts

@@ -1,6 +1,7 @@
 import {Component, ViewChild} from '@angular/core';
 import {By} from '@angular/platform-browser';
 import {ComponentFixture, TestBed, async, inject} from '@angular/core/testing';
+import {NoopAnimationsModule} from '@angular/platform-browser/animations';
 import {Directionality} from '@angular/cdk/bidi';
 import {dispatchKeyboardEvent} from '@angular/cdk/testing';
 import {ESCAPE} from '@angular/cdk/keycodes';
@@ -18,7 +19,7 @@ describe('Overlay directives', () => {
 
   beforeEach(() => {
     TestBed.configureTestingModule({
-      imports: [OverlayModule],
+      imports: [OverlayModule, NoopAnimationsModule],
       declarations: [ConnectedOverlayDirectiveTest, ConnectedOverlayPropertyInitOrder],
       providers: [
         {provide: Directionality, useFactory: () => {

src/cdk/overlay/overlay-module.ts

@@ -20,6 +20,7 @@ import {
 import {OverlayPositionBuilder} from './position/overlay-position-builder';
 import {OVERLAY_KEYBOARD_DISPATCHER_PROVIDER} from './keyboard/overlay-keyboard-dispatcher';
 import {ScrollStrategyOptions} from './scroll/scroll-strategy-options';
+import {MatBackdrop} from './backdrop';
 
 export const OVERLAY_PROVIDERS: Provider[] = [
   Overlay,
@@ -32,8 +33,9 @@ export const OVERLAY_PROVIDERS: Provider[] = [
 
 @NgModule({
   imports: [BidiModule, PortalModule, ScrollDispatchModule],
-  exports: [CdkConnectedOverlay, CdkOverlayOrigin, ScrollDispatchModule],
-  declarations: [CdkConnectedOverlay, CdkOverlayOrigin],
+  exports: [CdkConnectedOverlay, CdkOverlayOrigin, MatBackdrop, ScrollDispatchModule],
+  declarations: [CdkConnectedOverlay, CdkOverlayOrigin, MatBackdrop],
   providers: [OVERLAY_PROVIDERS, ScrollStrategyOptions],
+  entryComponents: [MatBackdrop],
 })
 export class OverlayModule {}

src/cdk/overlay/overlay-ref.ts

@@ -14,6 +14,8 @@ import {take} from 'rxjs/operators/take';
 import {Subject} from 'rxjs/Subject';
 import {OverlayKeyboardDispatcher} from './keyboard/overlay-keyboard-dispatcher';
 import {OverlayConfig} from './overlay-config';
+import {MatBackdrop} from './backdrop';
+import {empty} from 'rxjs/observable/empty';
 
 
 /** An object where all of its properties cannot be written. */
@@ -26,17 +28,18 @@ export type ImmutableObject<T> = {
  * Used to manipulate or dispose of said overlay.
  */
 export class OverlayRef implements PortalOutlet {
-  private _backdropElement: HTMLElement | null = null;
   private _backdropClick: Subject<any> = new Subject();
   private _attachments = new Subject<void>();
   private _detachments = new Subject<void>();
+  private _backdropInstance: MatBackdrop | null;
 
   /** Stream of keydown events dispatched to this overlay. */
   _keydownEvents = new Subject<KeyboardEvent>();
 
   constructor(
       private _portalOutlet: PortalOutlet,
       private _pane: HTMLElement,
+      private _backdropHost: PortalOutlet | null,
       private _config: ImmutableObject<OverlayConfig>,
       private _ngZone: NgZone,
       private _keyboardDispatcher: OverlayKeyboardDispatcher) {
@@ -63,7 +66,7 @@ export class OverlayRef implements PortalOutlet {
    * @returns The portal attachment result.
    */
   attach(portal: Portal<any>): any {
-    let attachResult = this._portalOutlet.attach(portal);
+    const attachResult = this._portalOutlet.attach(portal);
 
     if (this._config.positionStrategy) {
       this._config.positionStrategy.attach(this);
@@ -88,14 +91,15 @@ export class OverlayRef implements PortalOutlet {
     // Enable pointer events for the overlay pane element.
     this._togglePointerEvents(true);
 
-    if (this._config.hasBackdrop) {
-      this._attachBackdrop();
+    if (this._backdropHost) {
+      this._backdropInstance = this._backdropHost.attach(new ComponentPortal(MatBackdrop)).instance;
+      this._backdropInstance!._setClass(this._config.backdropClass!);
     }
 
     if (this._config.panelClass) {
       // We can't do a spread here, because IE doesn't support setting multiple classes.
       if (Array.isArray(this._config.panelClass)) {
-        this._config.panelClass.forEach(cls => this._pane.classList.add(cls));
+        this._config.panelClass.forEach(cssClass => this._pane.classList.add(cssClass));
       } else {
         this._pane.classList.add(this._config.panelClass);
       }
@@ -119,7 +123,9 @@ export class OverlayRef implements PortalOutlet {
       return;
     }
 
-    this.detachBackdrop();
+    if (this._backdropHost && this._backdropHost.hasAttached()) {
+      this._backdropHost.detach();
+    }
 
     // When the overlay is detached, the pane element should disable pointer events.
     // This is necessary because otherwise the pane element will cover the page and disable
@@ -157,7 +163,7 @@ export class OverlayRef implements PortalOutlet {
       this._config.scrollStrategy.disable();
     }
 
-    this.detachBackdrop();
+    this.disposeBackdrop();
     this._keyboardDispatcher.remove(this);
     this._portalOutlet.dispose();
     this._attachments.complete();
@@ -178,7 +184,7 @@ export class OverlayRef implements PortalOutlet {
 
   /** Gets an observable that emits when the backdrop has been clicked. */
   backdropClick(): Observable<void> {
-    return this._backdropClick.asObservable();
+    return this._backdropInstance ? this._backdropInstance._clickStream : empty<void>();
   }
 
   /** Gets an observable that emits when the overlay has been attached. */
@@ -257,33 +263,6 @@ export class OverlayRef implements PortalOutlet {
     this._pane.style.pointerEvents = enablePointer ? 'auto' : 'none';
   }
 
-  /** Attaches a backdrop for this overlay. */
-  private _attachBackdrop() {
-    this._backdropElement = document.createElement('div');
-    this._backdropElement.classList.add('cdk-overlay-backdrop');
-
-    if (this._config.backdropClass) {
-      this._backdropElement.classList.add(this._config.backdropClass);
-    }
-
-    // Insert the backdrop before the pane in the DOM order,
-    // in order to handle stacked overlays properly.
-    this._pane.parentElement!.insertBefore(this._backdropElement, this._pane);
-
-    // Forward backdrop clicks such that the consumer of the overlay can perform whatever
-    // action desired when such a click occurs (usually closing the overlay).
-    this._backdropElement.addEventListener('click', () => this._backdropClick.next(null));
-
-    // Add class to fade-in the backdrop after one frame.
-    this._ngZone.runOutsideAngular(() => {
-      requestAnimationFrame(() => {
-        if (this._backdropElement) {
-          this._backdropElement.classList.add('cdk-overlay-backdrop-showing');
-        }
-      });
-    });
-  }
-
   /**
    * Updates the stacking order of the element, moving it to the top if necessary.
    * This is required in cases where one overlay was detached, while another one,
@@ -297,45 +276,29 @@ export class OverlayRef implements PortalOutlet {
     }
   }
 
-  /** Detaches the backdrop (if any) associated with the overlay. */
-  detachBackdrop(): void {
-    let backdropToDetach = this._backdropElement;
-
-    if (backdropToDetach) {
-      let finishDetach = () => {
-        // It may not be attached to anything in certain cases (e.g. unit tests).
-        if (backdropToDetach && backdropToDetach.parentNode) {
-          backdropToDetach.parentNode.removeChild(backdropToDetach);
-        }
-
-        // It is possible that a new portal has been attached to this overlay since we started
-        // removing the backdrop. If that is the case, only clear the backdrop reference if it
-        // is still the same instance that we started to remove.
-        if (this._backdropElement == backdropToDetach) {
-          this._backdropElement = null;
-        }
-      };
-
-      backdropToDetach.classList.remove('cdk-overlay-backdrop-showing');
-
-      if (this._config.backdropClass) {
-        backdropToDetach.classList.remove(this._config.backdropClass);
-      }
-
-      backdropToDetach.addEventListener('transitionend', finishDetach);
-
-      // If the backdrop doesn't have a transition, the `transitionend` event won't fire.
-      // In this case we make it unclickable and we try to remove it after a delay.
-      backdropToDetach.style.pointerEvents = 'none';
+  /** Animates out and disposes of the backdrop. */
+  disposeBackdrop(): void {
+    if (this._backdropHost) {
+      if (this._backdropHost.hasAttached()) {
+        this._backdropHost.detach();
 
-      // Run this outside the Angular zone because there's nothing that Angular cares about.
-      // If it were to run inside the Angular zone, every test that used Overlay would have to be
-      // either async or fakeAsync.
-      this._ngZone.runOutsideAngular(() => {
-        setTimeout(finishDetach, 500);
-      });
+        this._backdropInstance!._animationStream.pipe(take(1)).subscribe(() => {
+          this._backdropHost!.dispose();
+          this._backdropHost = this._backdropInstance = null;
+        });
+      } else {
+        this._backdropHost.dispose();
+      }
     }
   }
+
+  /**
+   * Detaches the backdrop (if any) associated with the overlay.
+   * @deprecated Use `disposeBackdrop` instead.
+   */
+  detachBackdrop(): void {
+    this.disposeBackdrop();
+  }
 }
 
 function formatCssUnit(value: number | string) {

src/cdk/overlay/overlay.spec.ts

@@ -1,5 +1,6 @@
 import {async, fakeAsync, tick, ComponentFixture, inject, TestBed} from '@angular/core/testing';
 import {Component, NgModule, ViewChild, ViewContainerRef} from '@angular/core';
+import {NoopAnimationsModule} from '@angular/platform-browser/animations';
 import {
   ComponentPortal,
   PortalModule,
@@ -27,7 +28,7 @@ describe('Overlay', () => {
 
   beforeEach(async(() => {
     TestBed.configureTestingModule({
-      imports: [OverlayModule, PortalModule, OverlayTestModule]
+      imports: [OverlayModule, PortalModule, OverlayTestModule, NoopAnimationsModule]
     }).compileComponents();
   }));
 
@@ -81,6 +82,7 @@ describe('Overlay', () => {
       .toBe('auto', 'Expected the overlay pane to enable pointerEvents when attached.');
 
     overlayRef.detach();
+    viewContainerFixture.detectChanges();
 
     expect(paneElement.childNodes.length).toBe(0);
     expect(paneElement.style.pointerEvents)
@@ -201,6 +203,8 @@ describe('Overlay', () => {
     let overlayRef = overlay.create();
 
     overlayRef.detachments().subscribe(() => {
+      viewContainerFixture.detectChanges();
+
       expect(overlayContainerElement.querySelector('pizza'))
           .toBeFalsy('Expected the overlay to have been detached.');
     });
@@ -356,7 +360,6 @@ describe('Overlay', () => {
       viewContainerFixture.detectChanges();
       let backdrop = overlayContainerElement.querySelector('.cdk-overlay-backdrop') as HTMLElement;
       expect(backdrop).toBeTruthy();
-      expect(backdrop.classList).not.toContain('cdk-overlay-backdrop-showing');
 
       let backdropClickHandler = jasmine.createSpy('backdropClickHander');
       overlayRef.backdropClick().subscribe(backdropClickHandler);
@@ -399,27 +402,13 @@ describe('Overlay', () => {
       expect(backdrop.classList).toContain('cdk-overlay-transparent-backdrop');
     });
 
-    it('should disable the pointer events of a backdrop that is being removed', () => {
-      let overlayRef = overlay.create(config);
-      overlayRef.attach(componentPortal);
-
-      viewContainerFixture.detectChanges();
-      let backdrop = overlayContainerElement.querySelector('.cdk-overlay-backdrop') as HTMLElement;
-
-      expect(backdrop.style.pointerEvents).toBeFalsy();
-
-      overlayRef.detach();
-
-      expect(backdrop.style.pointerEvents).toBe('none');
-    });
-
     it('should insert the backdrop before the overlay pane in the DOM order', () => {
       let overlayRef = overlay.create(config);
       overlayRef.attach(componentPortal);
 
       viewContainerFixture.detectChanges();
 
-      let backdrop = overlayContainerElement.querySelector('.cdk-overlay-backdrop');
+      let backdrop = overlayContainerElement.querySelector('.cdk-overlay-backdrop')!.parentNode;
       let pane = overlayContainerElement.querySelector('.cdk-overlay-pane');
       let children = Array.prototype.slice.call(overlayContainerElement.children);
 

src/cdk/overlay/overlay.ts

@@ -59,9 +59,13 @@ export class Overlay {
    * @returns Reference to the created overlay.
    */
   create(config: OverlayConfig = defaultConfig): OverlayRef {
+    const backdrop = config.hasBackdrop ? this._createBackdropElement() : null;
+    const backdropHost = backdrop ? this._createPortalOutlet(backdrop) : null;
     const pane = this._createPaneElement();
     const portalOutlet = this._createPortalOutlet(pane);
-    return new OverlayRef(portalOutlet, pane, config, this._ngZone, this._keyboardDispatcher);
+
+    return new OverlayRef(portalOutlet, pane, backdropHost,
+        config, this._ngZone, this._keyboardDispatcher);
   }
 
   /**
@@ -91,6 +95,19 @@ export class Overlay {
    * Create a DomPortalOutlet into which the overlay content can be loaded.
    * @param pane The DOM element to turn into a portal outlet.
    * @returns A portal outlet for the given DOM element.
+   * Creates the DOM element that will wrap the backdrop and adds it to the overlay container.
+   * @returns Newly-created backdrop host.
+   */
+  private _createBackdropElement(): HTMLElement {
+    const pane = document.createElement('div');
+    this._overlayContainer.getContainerElement().appendChild(pane);
+    return pane;
+  }
+
+  /**
+   * Create a DomPortalHost into which the overlay content can be loaded.
+   * @param pane The DOM element to turn into a portal host.
+   * @returns A portal host for the given DOM element.
    */
   private _createPortalOutlet(pane: HTMLElement): DomPortalOutlet {
     return new DomPortalOutlet(pane, this._componentFactoryResolver, this._appRef, this._injector);