fix(overlay): make config immutable for existing refs

This changes makes the OverlayConfig instance in OverlatRef immutable.
Calling `getConfig` will now return a clone of the config to make clear
that it cannot be modified directly to change the state of the overlay.
This also updates the `updateSize` method to accept a partial config to
apply to the existing config (and make a new config instance)

BREAKING CHANGE: OverlayRef.getConfig returns a clone of the config
object.

BREAKING CHANGE: OverlayRef.updateSize now accepts a OverlaySizeConfig
rather than being based on the existing config object.

Author: jelbourn

src/cdk/overlay/overlay-ref.ts

@@ -6,8 +6,8 @@
  * found in the LICENSE file at https://angular.io/license
  */
 
-import {NgZone} from '@angular/core';
-import {PortalHost, Portal} from '@angular/cdk/portal';
+import {NgZone, ComponentRef, EmbeddedViewRef} from '@angular/core';
+import {PortalHost, Portal, ComponentPortal, TemplatePortal} from '@angular/cdk/portal';
 import {OverlayConfig} from './overlay-config';
 import {Observable} from 'rxjs/Observable';
 import {Subject} from 'rxjs/Subject';
@@ -39,8 +39,14 @@ export class OverlayRef implements PortalHost {
     return this._pane;
   }
 
+  attach<T>(portal: ComponentPortal<T>): ComponentRef<T>;
+  attach<T>(portal: TemplatePortal<T>): EmbeddedViewRef<T>;
+  attach(portal: any): any;
+
   /**
-   * Attaches the overlay to a portal instance and adds the backdrop.
+   * Attaches content, given via a Portal, to the overlay.
+   * If the overlay is configured to have a backdrop, it will be created.
+   *
    * @param portal Portal instance to which to attach the overlay.
    * @returns The portal attachment result.
    */
@@ -53,8 +59,8 @@ export class OverlayRef implements PortalHost {
 
     // Update the pane element with the given configuration.
     this._updateStackingOrder();
-    this.updateSize();
-    this.updateDirection();
+    this._updateElementSize();
+    this._updateDirection();
     this.updatePosition();
 
     if (this._config.scrollStrategy) {
@@ -107,9 +113,7 @@ export class OverlayRef implements PortalHost {
     return detachmentResult;
   }
 
-  /**
-   * Cleans up the overlay from the DOM.
-   */
+  /** Cleans up the overlay from the DOM. */
   dispose(): void {
     if (this._config.positionStrategy) {
       this._config.positionStrategy.dispose();
@@ -127,35 +131,30 @@ export class OverlayRef implements PortalHost {
     this._detachments.complete();
   }
 
-  /**
-   * Checks whether the overlay has been attached.
-   */
+  /** Whether the overlay has attached content. */
   hasAttached(): boolean {
     return this._portalHost.hasAttached();
   }
 
-  /**
-   * Returns an observable that emits when the backdrop has been clicked.
-   */
+  /** Gets an observable that emits when the backdrop has been clicked. */
   backdropClick(): Observable<void> {
     return this._backdropClick.asObservable();
   }
 
-  /** Returns an observable that emits when the overlay has been attached. */
+  /** Gets an observable that emits when the overlay has been attached. */
   attachments(): Observable<void> {
     return this._attachments.asObservable();
   }
 
-  /** Returns an observable that emits when the overlay has been detached. */
+  /** Gets an observable that emits when the overlay has been detached. */
   detachments(): Observable<void> {
     return this._detachments.asObservable();
   }
 
-  /**
-   * Gets the current config of the overlay.
-   */
+  /** Gets a clone of the the current overlay configuration. */
   getConfig(): OverlayConfig {
-    return this._config;
+    // Clone the config so that it cannot be modified outside of this class.
+    return {...this._config};
   }
 
   /** Updates the position of the overlay based on the position strategy. */
@@ -165,13 +164,19 @@ export class OverlayRef implements PortalHost {
     }
   }
 
+  /** Update the size properties of the overlay. */
+  updateSize(sizeConfig: OverlaySizeConfig) {
+    this._config = {...this._config, ...sizeConfig};
+    this._updateElementSize();
+  }
+
   /** Updates the text direction of the overlay panel. */
-  private updateDirection() {
+  private _updateDirection() {
     this._pane.setAttribute('dir', this._config.direction!);
   }
 
-  /** Updates the size of the overlay based on the overlay config. */
-  updateSize() {
+  /** Updates the size of the overlay element based on the overlay config. */
+  private _updateElementSize() {
     if (this._config.width || this._config.width === 0) {
       this._pane.style.width = formatCssUnit(this._config.width);
     }
@@ -220,10 +225,12 @@ export class OverlayRef implements PortalHost {
     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');
-      }
+    this._ngZone.runOutsideAngular(() => {
+      requestAnimationFrame(() => {
+        if (this._backdropElement) {
+          this._backdropElement.classList.add('cdk-overlay-backdrop-showing');
+        }
+      });
     });
   }
 
@@ -284,3 +291,14 @@ export class OverlayRef implements PortalHost {
 function formatCssUnit(value: number | string) {
   return typeof value === 'string' ? value as string : `${value}px`;
 }
+
+
+/** Size properties for an overlay. */
+export interface OverlaySizeConfig {
+  width?: number | string;
+  height?: number | string;
+  minWidth?: number | string;
+  minHeight?: number | string;
+  maxWidth?: number | string;
+  maxHeight?: number | string;
+};

src/cdk/portal/portal.ts

@@ -179,6 +179,10 @@ export abstract class BasePortalHost implements PortalHost {
     return !!this._attachedPortal;
   }
 
+  attach<T>(portal: ComponentPortal<T>): ComponentRef<T>;
+  attach<T>(portal: TemplatePortal<T>): EmbeddedViewRef<T>;
+  attach(portal: any): any;
+
   attach(portal: Portal<any>): any {
     if (!portal) {
       throwNullPortalError();

src/cdk/scrolling/scrolling.md

@@ -1,3 +1,3 @@
 ### Scrolling
 
-Some things to help with scrollling.
+Some things to help with scrollling.

src/lib/autocomplete/autocomplete-trigger.ts

@@ -451,8 +451,7 @@ export class MdAutocompleteTrigger implements ControlValueAccessor, OnDestroy {
       this._overlayRef = this._overlay.create(this._getOverlayConfig());
     } else {
       /** Update the panel width, in case the host width has changed */
-      this._overlayRef.getConfig().width = this._getHostWidth();
-      this._overlayRef.updateSize();
+      this._overlayRef.updateSize({width: this._getHostWidth()});
     }
 
     if (this._overlayRef && !this._overlayRef.hasAttached()) {