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,56 @@
+/**
+ * @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 {
+  Component,
+  ViewEncapsulation,
+  ChangeDetectionStrategy,
+  OnDestroy,
+  Renderer2,
+  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({
+  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,
+})
+export class MatBackdrop implements OnDestroy {
+  _animationState = 'visible';
+  _clickStream = new Subject<void>();
+  _animationStream = new Subject<AnimationEvent>();
+
+  constructor(private _element: ElementRef, private _renderer: Renderer2) {}
+
+  _setClass(cssClass: string) {
+    this._renderer.addClass(this._element.nativeElement, 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} 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';
@@ -17,7 +18,7 @@ describe('Overlay directives', () => {
 
   beforeEach(() => {
     TestBed.configureTestingModule({
-      imports: [OverlayModule],
+      imports: [OverlayModule, NoopAnimationsModule],
       declarations: [ConnectedOverlayDirectiveTest, ConnectedOverlayPropertyInitOrder],
       providers: [
         {provide: OverlayContainer, useFactory: () => {

src/cdk/overlay/overlay-module.ts

@@ -19,6 +19,7 @@ import {
 } from './overlay-directives';
 import {OverlayPositionBuilder} from './position/overlay-position-builder';
 import {ScrollStrategyOptions} from './scroll/scroll-strategy-options';
+import {MatBackdrop} from './backdrop';
 
 export const OVERLAY_PROVIDERS: Provider[] = [
   Overlay,
@@ -30,8 +31,9 @@ export const OVERLAY_PROVIDERS: Provider[] = [
 
 @NgModule({
   imports: [BidiModule, PortalModule, ScrollDispatchModule],
-  exports: [ConnectedOverlayDirective, OverlayOrigin, ScrollDispatchModule],
-  declarations: [ConnectedOverlayDirective, OverlayOrigin],
+  exports: [ConnectedOverlayDirective, MatBackdrop, OverlayOrigin, ScrollDispatchModule],
+  declarations: [ConnectedOverlayDirective, MatBackdrop, OverlayOrigin],
   providers: [OVERLAY_PROVIDERS, ScrollStrategyOptions],
+  entryComponents: [MatBackdrop],
 })
 export class OverlayModule {}

src/cdk/overlay/overlay-ref.ts

@@ -11,22 +11,25 @@ import {PortalHost, Portal} from '@angular/cdk/portal';
 import {OverlayConfig} from './overlay-config';
 import {Observable} from 'rxjs/Observable';
 import {Subject} from 'rxjs/Subject';
-import {first} from 'rxjs/operator/first';
+import {MatBackdrop} from './backdrop';
+import {ComponentPortal} from '@angular/cdk/portal';
+import {first} from '@angular/cdk/rxjs';
+import {empty} from 'rxjs/observable/empty';
 
 
 /**
  * Reference to an overlay that has been created with the Overlay service.
  * Used to manipulate or dispose of said overlay.
  */
 export class OverlayRef implements PortalHost {
-  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;
 
   constructor(
       private _portalHost: PortalHost,
       private _pane: HTMLElement,
+      private _backdropHost: PortalHost | null,
       private _config: OverlayConfig,
       private _ngZone: NgZone) {
 
@@ -46,7 +49,7 @@ export class OverlayRef implements PortalHost {
    * @returns The portal attachment result.
    */
   attach(portal: Portal<any>): any {
-    let attachResult = this._portalHost.attach(portal);
+    const attachResult = this._portalHost.attach(portal);
 
     if (this._config.positionStrategy) {
       this._config.positionStrategy.attach(this);
@@ -71,14 +74,15 @@ export class OverlayRef implements PortalHost {
     // 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);
       }
@@ -95,7 +99,9 @@ export class OverlayRef implements PortalHost {
    * @returns The portal detachment result.
    */
   detach(): any {
-    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
@@ -130,10 +136,9 @@ export class OverlayRef implements PortalHost {
       this._config.scrollStrategy.disable();
     }
 
-    this.detachBackdrop();
+    this.disposeBackdrop();
     this._portalHost.dispose();
     this._attachments.complete();
-    this._backdropClick.complete();
     this._detachments.next();
     this._detachments.complete();
   }
@@ -149,7 +154,7 @@ export class OverlayRef implements PortalHost {
    * Returns 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>();
   }
 
   /** Returns an observable that emits when the overlay has been attached. */
@@ -213,31 +218,6 @@ export class OverlayRef implements PortalHost {
     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.
-    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,
@@ -251,43 +231,19 @@ export class OverlayRef implements PortalHost {
     }
   }
 
-  /** 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);
+  /** Animates out and disposes of the backdrop. */
+  disposeBackdrop(): void {
+    if (this._backdropHost) {
+      if (this._backdropHost.hasAttached()) {
+        this._backdropHost.detach();
 
-      // 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';
-
-      // 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);
-      });
+        first.call(this._backdropInstance!._animationStream).subscribe(() => {
+          this._backdropHost!.dispose();
+          this._backdropHost = this._backdropInstance = null;
+        });
+      } else {
+        this._backdropHost.dispose();
+      }
     }
   }
 }

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,
@@ -26,7 +27,7 @@ describe('Overlay', () => {
 
   beforeEach(async(() => {
     TestBed.configureTestingModule({
-      imports: [OverlayModule, PortalModule, OverlayTestModule],
+      imports: [OverlayModule, PortalModule, OverlayTestModule, NoopAnimationsModule],
       providers: [{
         provide: OverlayContainer,
         useFactory: () => {
@@ -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)
@@ -181,6 +183,8 @@ describe('Overlay', () => {
     let overlayRef = overlay.create();
 
     overlayRef.detachments().subscribe(() => {
+      viewContainerFixture.detectChanges();
+
       expect(overlayContainerElement.querySelector('pizza'))
           .toBeFalsy('Expected the overlay to have been detached.');
     });
@@ -336,7 +340,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);
@@ -379,27 +382,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

@@ -52,9 +52,12 @@ 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._createPortalHost(backdrop) : null;
     const pane = this._createPaneElement();
     const portalHost = this._createPortalHost(pane);
-    return new OverlayRef(portalHost, pane, config, this._ngZone);
+
+    return new OverlayRef(portalHost, pane, backdropHost, config, this._ngZone);
   }
 
   /**
@@ -70,7 +73,7 @@ export class Overlay {
    * @returns Newly-created pane element
    */
   private _createPaneElement(): HTMLElement {
-    let pane = document.createElement('div');
+    const pane = document.createElement('div');
 
     pane.id = `cdk-overlay-${nextUniqueId++}`;
     pane.classList.add('cdk-overlay-pane');
@@ -79,6 +82,16 @@ export class Overlay {
     return pane;
   }
 
+  /**
+   * 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.