fix(overlay): ensure proper stacking order when attaching

Fixes a case where the order of overlays can be invalid if one overlay is detached, while another is destroyed. Next time both of them are open, the one that was disposed will end up beneath the freshly-created one, no matter the order of attachment. This PR adds some logic that will ensure that all each newly-opened overlay will be at the top of the stacking order.

Fixes angular#3574.

src/lib/core/overlay/overlay-ref.ts

@@ -30,20 +30,21 @@ export class OverlayRef implements PortalHost {
    * @returns The portal attachment result.
    */
   attach(portal: Portal<any>): any {
-    if (this._state.hasBackdrop) {
-      this._attachBackdrop();
-    }
-
     let attachResult = this._portalHost.attach(portal);
 
     // Update the pane element with the given state configuration.
+    this._updateStackingOrder();
     this.updateSize();
     this.updateDirection();
     this.updatePosition();
 
     // Enable pointer events for the overlay pane element.
     this._togglePointerEvents(true);
 
+    if (this._state.hasBackdrop) {
+      this._attachBackdrop();
+    }
+
     return attachResult;
   }
 
@@ -153,6 +154,19 @@ export class OverlayRef implements PortalHost {
     });
   }
 
+  /**
+   * 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,
+   * that should be behind it, was destroyed. The next time both of them are opened,
+   * the stacking will be wrong, because the detached element's pane will still be
+   * in its original DOM position.
+   */
+  private _updateStackingOrder() {
+    if (this._pane.nextSibling) {
+      this._pane.parentNode.appendChild(this._pane);
+    }
+  }
+
   /** Detaches the backdrop (if any) associated with the overlay. */
   detachBackdrop(): void {
     let backdropToDetach = this._backdropElement;

src/lib/core/overlay/overlay.spec.ts

@@ -100,6 +100,31 @@ describe('Overlay', () => {
     expect(overlayContainerElement.textContent).toBe('');
   });
 
+  it('should ensure that the most-recently-attached overlay is on top', () => {
+    let pizzaOverlayRef = overlay.create();
+    let cakeOverlayRef = overlay.create();
+
+    pizzaOverlayRef.attach(componentPortal);
+    cakeOverlayRef.attach(templatePortal);
+
+    expect(pizzaOverlayRef.overlayElement.nextSibling)
+        .toBeTruthy('Expected pizza to be on the bottom.');
+    expect(cakeOverlayRef.overlayElement.nextSibling)
+        .toBeFalsy('Expected cake to be on top.');
+
+    pizzaOverlayRef.dispose();
+    cakeOverlayRef.detach();
+
+    pizzaOverlayRef = overlay.create();
+    pizzaOverlayRef.attach(componentPortal);
+    cakeOverlayRef.attach(templatePortal);
+
+    expect(pizzaOverlayRef.overlayElement.nextSibling)
+        .toBeTruthy('Expected pizza to still be on the bottom.');
+    expect(cakeOverlayRef.overlayElement.nextSibling)
+        .toBeFalsy('Expected cake to still be on top.');
+  });
+
   it('should set the direction', () => {
     const state = new OverlayState();
     state.direction = 'rtl';