feat(portal): add new portal that projects DOM nodes

Adds a new type of portal called `DomPortal` which transfers the contents of a portal into the portal outlet and then restores them on destroy.

This was implemented initially for #14430.

Author: crisbeto

src/cdk-experimental/dialog/dialog-container.ts

@@ -12,7 +12,8 @@ import {
   BasePortalOutlet,
   ComponentPortal,
   PortalHostDirective,
-  TemplatePortal
+  TemplatePortal,
+  DomPortal
 } from '@angular/cdk/portal';
 import {DOCUMENT} from '@angular/common';
 import {
@@ -176,6 +177,19 @@ export class CdkDialogContainer extends BasePortalOutlet implements OnDestroy {
     return this._portalHost.attachTemplatePortal(portal);
   }
 
+  /**
+   * Attaches a DOM portal to the dialog container.
+   * @param portal Portal to be attached.
+   */
+  attachDomPortal(portal: DomPortal) {
+    if (this._portalHost.hasAttached()) {
+      throwDialogContentAlreadyAttachedError();
+    }
+
+    this._savePreviouslyFocusedElement();
+    return this._portalHost.attachDomPortal(portal);
+  }
+
   /** Emit lifecycle events based on animation `start` callback. */
   _onAnimationStart(event: AnimationEvent) {
     if (event.toState === 'enter') {

src/cdk/portal/dom-portal-outlet.ts

@@ -13,7 +13,7 @@ import {
   ApplicationRef,
   Injector,
 } from '@angular/core';
-import {BasePortalOutlet, ComponentPortal, TemplatePortal} from './portal';
+import {BasePortalOutlet, ComponentPortal, TemplatePortal, DomPortal} from './portal';
 
 
 /**
@@ -93,6 +93,28 @@ export class DomPortalOutlet extends BasePortalOutlet {
     return viewRef;
   }
 
+  /**
+   * Attaches a DOM portal by transferring its content into the outlet.
+   * @param portal Portal to be attached.
+   */
+  attachDomPortal(portal: DomPortal) {
+    // Note that we need to convert this into an array, because `childNodes`
+    // is a live collection which will be updated as we add/remove nodes.
+    let transferredNodes = Array.from(portal.element.childNodes);
+
+    for (let i = 0; i < transferredNodes.length; i++) {
+      this.outletElement.appendChild(transferredNodes[i]);
+    }
+
+    super.setDisposeFn(() => {
+      for (let i = 0; i < transferredNodes.length; i++) {
+        portal.element.appendChild(transferredNodes[i]);
+      }
+
+      transferredNodes = null!;
+    });
+  }
+
   /**
    * Clears out a portal from the DOM.
    */

src/cdk/portal/portal-directives.ts

@@ -19,7 +19,7 @@ import {
   TemplateRef,
   ViewContainerRef,
 } from '@angular/core';
-import {BasePortalOutlet, ComponentPortal, Portal, TemplatePortal} from './portal';
+import {BasePortalOutlet, ComponentPortal, Portal, TemplatePortal, DomPortal} from './portal';
 
 
 /**
@@ -141,7 +141,7 @@ export class CdkPortalOutlet extends BasePortalOutlet implements OnInit, OnDestr
   }
 
   /**
-   * Attach the given TemplatePortal to this PortlHost as an embedded View.
+   * Attach the given TemplatePortal to this PortalHost as an embedded View.
    * @param portal Portal to be attached.
    * @returns Reference to the created embedded view.
    */
@@ -156,6 +156,29 @@ export class CdkPortalOutlet extends BasePortalOutlet implements OnInit, OnDestr
 
     return viewRef;
   }
+
+  /**
+   * Attaches the given DomPortal to this PortalHost by moving all of the portal content into it.
+   * @param portal Portal to be attached.
+   */
+  attachDomPortal(portal: DomPortal) {
+    portal.setAttachedHost(this);
+
+    const origin = portal.element;
+    const transferredNodes: Node[] = [];
+    const nativeElement: Node = this._viewContainerRef.element.nativeElement;
+    const rootNode = nativeElement.nodeType === nativeElement.ELEMENT_NODE ?
+        nativeElement : nativeElement.parentNode!;
+
+    while (origin.firstChild) {
+      transferredNodes.push(rootNode.appendChild(origin.firstChild));
+    }
+
+    super.setDisposeFn(() => {
+      transferredNodes.forEach(node => portal.element.appendChild(node));
+      transferredNodes.length = 0;
+    });
+  }
 }
 
 

src/cdk/portal/portal.spec.ts

@@ -12,10 +12,11 @@ import {
   ApplicationRef,
   TemplateRef,
   ComponentRef,
+  ElementRef,
 } from '@angular/core';
 import {CommonModule} from '@angular/common';
 import {CdkPortal, CdkPortalOutlet, PortalModule} from './portal-directives';
-import {Portal, ComponentPortal, TemplatePortal} from './portal';
+import {Portal, ComponentPortal, TemplatePortal, DomPortal} from './portal';
 import {DomPortalOutlet} from './dom-portal-outlet';
 
 
@@ -76,6 +77,35 @@ describe('Portals', () => {
           .toHaveBeenCalledWith(testAppComponent.portalOutlet.attachedRef);
     });
 
+    it('should load a DOM portal', () => {
+      const testAppComponent = fixture.componentInstance;
+      const hostContainer = fixture.nativeElement.querySelector('.portal-container');
+      const innerContent = fixture.nativeElement.querySelector('.dom-portal-inner-content');
+      const domPortal = new DomPortal(testAppComponent.domPortalContent);
+
+      expect(innerContent).toBeTruthy('Expected portal content to be rendered.');
+      expect(domPortal.element.contains(innerContent))
+          .toBe(true, 'Expected content to be inside portal on init.');
+      expect(hostContainer.contains(innerContent))
+          .toBe(false, 'Expected content to be outside of portal outlet.');
+
+      testAppComponent.selectedPortal = domPortal;
+      fixture.detectChanges();
+
+      expect(domPortal.element.contains(innerContent))
+          .toBe(false, 'Expected content to be out of the portal on attach.');
+      expect(hostContainer.contains(innerContent))
+          .toBe(true, 'Expected content to be inside the outlet on attach.');
+
+      testAppComponent.selectedPortal = undefined;
+      fixture.detectChanges();
+
+      expect(domPortal.element.contains(innerContent))
+          .toBe(true, 'Expected content to be at initial position on detach.');
+      expect(hostContainer.contains(innerContent))
+          .toBe(false, 'Expected content to be removed from outlet on detach.');
+    });
+
     it('should project template context bindings in the portal', () => {
       let testAppComponent = fixture.componentInstance;
       let hostContainer = fixture.nativeElement.querySelector('.portal-container');
@@ -502,6 +532,20 @@ describe('Portals', () => {
       expect(spy).toHaveBeenCalled();
     });
 
+    it('should attach and detach a DOM portal', () => {
+      const fixture = TestBed.createComponent(PortalTestApp);
+      fixture.detectChanges();
+      const portal = new DomPortal(fixture.componentInstance.domPortalContent);
+
+      portal.attach(host);
+
+      expect(someDomElement.textContent).toContain('Hello there');
+
+      host.detach();
+
+      expect(someDomElement.textContent!.trim()).toBe('');
+    });
+
   });
 });
 
@@ -559,12 +603,17 @@ class ArbitraryViewContainerRefComponent {
   </ng-template>
 
   <ng-template #templateRef let-data> {{fruit}} - {{ data?.status }}!</ng-template>
+
+  <div #domPortalContent>
+    <p class="dom-portal-inner-content">Hello there</p>
+  </div>
   `,
 })
 class PortalTestApp {
   @ViewChildren(CdkPortal) portals: QueryList<CdkPortal>;
   @ViewChild(CdkPortalOutlet, {static: true}) portalOutlet: CdkPortalOutlet;
-  @ViewChild('templateRef', { read: TemplateRef , static: true}) templateRef: TemplateRef<any>;
+  @ViewChild('templateRef', {read: TemplateRef, static: true}) templateRef: TemplateRef<any>;
+  @ViewChild('domPortalContent', {static: true}) domPortalContent: ElementRef<HTMLElement>;
 
   selectedPortal: Portal<any>|undefined;
   fruit: string = 'Banana';

src/cdk/portal/portal.ts

@@ -153,6 +153,21 @@ export class TemplatePortal<C = any> extends Portal<EmbeddedViewRef<C>> {
   }
 }
 
+/**
+ * A `DomPortal` is a portal whose content will be taken from its current position
+ * in the DOM and moved into a portal outlet, when it is attached. On detach, the content
+ * will be restored to its original position.
+ */
+export class DomPortal extends Portal<HTMLElement> {
+  /** DOM node hosting the portal's content. */
+  readonly element: HTMLElement;
+
+  constructor(element: HTMLElement | ElementRef<HTMLElement>) {
+    super();
+    this.element = element instanceof ElementRef ? element.nativeElement : element;
+  }
+}
+
 
 /** A `PortalOutlet` is an space that can contain a single `Portal`. */
 export interface PortalOutlet {
@@ -213,6 +228,10 @@ export abstract class BasePortalOutlet implements PortalOutlet {
     } else if (portal instanceof TemplatePortal) {
       this._attachedPortal = portal;
       return this.attachTemplatePortal(portal);
+      // @breaking-change 8.0.0 remove null check for `this.attachDomPortal`.
+    } else if (this.attachDomPortal && portal instanceof DomPortal) {
+      this._attachedPortal = portal;
+      return this.attachDomPortal(portal);
     }
 
     throwUnknownPortalTypeError();
@@ -222,6 +241,9 @@ export abstract class BasePortalOutlet implements PortalOutlet {
 
   abstract attachTemplatePortal<C>(portal: TemplatePortal<C>): EmbeddedViewRef<C>;
 
+  // @breaking-change 8.0.0 `attachDomPortal` to become a required method.
+  abstract attachDomPortal?(portal: DomPortal): any;
+
   /** Detaches a previously attached portal. */
   detach(): void {
     if (this._attachedPortal) {

src/dev-app/portal/portal-demo.html

@@ -15,6 +15,10 @@ <h2> The portal outlet is here: </h2>
   Science joke
 </button>
 
+<button type="button" (click)="selectedPortal = dadJoke">
+  Dad joke
+</button>
+
 <!-- Template vars on <ng-template> elements can't be accessed _in_ the template because Angular
     doesn't support grabbing the instance / TemplateRef this way because the variable may be
     referring to something *in* the template (such as #item in ngFor). As such, the component
@@ -29,3 +33,8 @@ <h2> The portal outlet is here: </h2>
  <p> - Did you hear about this year's Fibonacci Conference? </p>
  <p> - It's going to be as big as the last two put together. </p>
 </div>
+
+<div class="demo-dad-joke" #domPortalSource>
+  <p> - Scientists got bored of watching the moon for 24 hours </p>
+  <p> - So they called it a day. </p>
+</div>

src/dev-app/portal/portal-demo.scss

@@ -5,3 +5,7 @@
   width: 500px;
   height: 100px;
 }
+
+.demo-dad-joke {
+  opacity: 0.25;
+}

src/dev-app/portal/portal-demo.ts

@@ -6,8 +6,8 @@
  * found in the LICENSE file at https://angular.io/license
  */
 
-import {ComponentPortal, Portal, CdkPortal} from '@angular/cdk/portal';
-import {Component, QueryList, ViewChildren} from '@angular/core';
+import {ComponentPortal, Portal, CdkPortal, DomPortal} from '@angular/cdk/portal';
+import {Component, QueryList, ViewChildren, ElementRef, ViewChild} from '@angular/core';
 
 
 @Component({
@@ -18,6 +18,7 @@ import {Component, QueryList, ViewChildren} from '@angular/core';
 })
 export class PortalDemo {
   @ViewChildren(CdkPortal) templatePortals: QueryList<Portal<any>>;
+  @ViewChild('domPortalSource', {static: false}) domPortalSource: ElementRef<HTMLElement>;
 
   selectedPortal: Portal<any>;
 
@@ -32,6 +33,10 @@ export class PortalDemo {
   get scienceJoke() {
     return new ComponentPortal(ScienceJoke);
   }
+
+  get dadJoke() {
+    return new DomPortal(this.domPortalSource);
+  }
 }
 
 

src/material/bottom-sheet/bottom-sheet-container.ts

@@ -26,6 +26,7 @@ import {
   ComponentPortal,
   TemplatePortal,
   CdkPortalOutlet,
+  DomPortal,
 } from '@angular/cdk/portal';
 import {BreakpointObserver, Breakpoints} from '@angular/cdk/layout';
 import {MatBottomSheetConfig} from './bottom-sheet-config';
@@ -122,6 +123,14 @@ export class MatBottomSheetContainer extends BasePortalOutlet implements OnDestr
     return this._portalOutlet.attachTemplatePortal(portal);
   }
 
+  /** Attaches a DOM portal to the bottom sheet container. */
+  attachDomPortal(portal: DomPortal) {
+    this._validatePortalAttached();
+    this._setPanelClass();
+    this._savePreviouslyFocusedElement();
+    return this._portalOutlet.attachDomPortal(portal);
+  }
+
   /** Begin animation of bottom sheet entrance into view. */
   enter(): void {
     if (!this._destroyed) {

src/material/dialog/dialog-container.ts

@@ -26,7 +26,8 @@ import {
   BasePortalOutlet,
   ComponentPortal,
   CdkPortalOutlet,
-  TemplatePortal
+  TemplatePortal,
+  DomPortal
 } from '@angular/cdk/portal';
 import {FocusTrap, FocusTrapFactory} from '@angular/cdk/a11y';
 import {MatDialogConfig} from './dialog-config';
@@ -130,6 +131,19 @@ export class MatDialogContainer extends BasePortalOutlet {
     return this._portalOutlet.attachTemplatePortal(portal);
   }
 
+  /**
+   * Attaches a DOM portal to the dialog container.
+   * @param portal Portal to be attached.
+   */
+  attachDomPortal(portal: DomPortal) {
+    if (this._portalOutlet.hasAttached()) {
+      throwMatDialogContentAlreadyAttachedError();
+    }
+
+    this._savePreviouslyFocusedElement();
+    return this._portalOutlet.attachDomPortal(portal);
+  }
+
   /** Moves the focus inside the focus trap. */
   private _trapFocus() {
     if (!this._focusTrap) {

src/material/snack-bar/snack-bar-container.ts

@@ -12,6 +12,7 @@ import {
   CdkPortalOutlet,
   ComponentPortal,
   TemplatePortal,
+  DomPortal,
 } from '@angular/cdk/portal';
 import {
   ChangeDetectionStrategy,
@@ -107,6 +108,13 @@ export class MatSnackBarContainer extends BasePortalOutlet implements OnDestroy
     return this._portalOutlet.attachTemplatePortal(portal);
   }
 
+  /** Attaches a DOM portal to the snack bar container. */
+  attachDomPortal(portal: DomPortal) {
+    this._assertNotAttached();
+    this._applySnackBarClasses();
+    return this._portalOutlet.attachDomPortal(portal);
+  }
+
   /** Handle end of animations, updating the state of the snackbar. */
   onAnimationEnd(event: AnimationEvent) {
     const {fromState, toState} = event;

tools/public_api_guard/material/bottom-sheet.d.ts

@@ -39,6 +39,7 @@ export declare class MatBottomSheetContainer extends BasePortalOutlet implements
     _onAnimationDone(event: AnimationEvent): void;
     _onAnimationStart(event: AnimationEvent): void;
     attachComponentPortal<T>(portal: ComponentPortal<T>): ComponentRef<T>;
+    attachDomPortal(portal: DomPortal): void;
     attachTemplatePortal<C>(portal: TemplatePortal<C>): EmbeddedViewRef<C>;
     enter(): void;
     exit(): void;

tools/public_api_guard/material/dialog.d.ts

@@ -93,6 +93,7 @@ export declare class MatDialogContainer extends BasePortalOutlet {
     _onAnimationStart(event: AnimationEvent): void;
     _startExitAnimation(): void;
     attachComponentPortal<T>(portal: ComponentPortal<T>): ComponentRef<T>;
+    attachDomPortal(portal: DomPortal): void;
     attachTemplatePortal<C>(portal: TemplatePortal<C>): EmbeddedViewRef<C>;
 }