docs(cdk/portal): update portal docs (#19869)

Add the DomPortal example in the cdk-portal-overview-example component and update the Portal markdown documentation adding TemplatePortal and DomPortal.

Author: norato

src/cdk/portal/portal.md

@@ -3,7 +3,7 @@ The `portals` package provides a flexible system for rendering dynamic content i
 ### Portals
 A `Portal` is a piece of UI that can be dynamically rendered to an open slot on the page.
 
-The "piece of UI" can be either a `Component` or a `TemplateRef` and the "open slot" is
+The "piece of UI" can be either a `Component`, a `TemplateRef` or a DOM element and the "open slot" is
 a `PortalOutlet`.
 
 Portals and PortalOutlets are low-level building blocks that other concepts, such as overlays, are
@@ -55,7 +55,43 @@ portals, it must be included in the `entryComponents` of its `NgModule`.
 
 Usage:
 ```ts
-this.userSettingsPortal = new ComponentPortal(UserSettingsComponent);
+ngAfterViewInit() {
+  this.userSettingsPortal = new ComponentPortal(UserSettingsComponent);
+}
+```
+
+##### `TemplatePortal`
+You can create a `TemplatePortal` from an `<ng-template>`. `TemplatePortal` allows you to take Angular content within one template and render it somewhere else.
+
+Usage:
+```html
+<ng-template #templatePortalContent>Some content here</ng-template>
+```
+
+```ts
+@ViewChild('templatePortalContent') templatePortalContent: TemplateRef<unknow>;
+
+ngAfterViewInit() {
+  this.templatePortal = new TemplatePortal(
+    this.templatePortalContent,
+    this._viewContainerRef
+  );
+}
+```
+
+##### `DomPortal`
+You can create a `DomPortal` from any native DOM element. `DomPortal` allows you to take any arbitrary DOM content and render it somewhere else. `DomPortal` moves content _as is_, so elements with Angular features like bindings or directives may no longer update if moved via `DomPortal`.
+
+Usage:
+```html
+<div #domPortalContent>Some content here</div>
+```
+
+```ts
+@ViewChild('domPortalContent', {static: false}) domPortalContent: ElementRef<HTMLElement>;
+ngAfterViewInit() {
+  this.domPortal = new DomPortal(this.domPortalContent);
+}
 ```
 
 

src/components-examples/cdk/portal/cdk-portal-overview/cdk-portal-overview-example.html

@@ -6,3 +6,6 @@ <h2>The portal outlet is below:</h2>
 
 <button (click)="selectedPortal = componentPortal">Render component portal</button>
 <button (click)="selectedPortal = templatePortal">Render template portal</button>
+<button (click)="selectedPortal = domPortal">Render DOM portal</button>
+
+<div #domPortalContent>Hello, this is a DOM portal</div>

src/components-examples/cdk/portal/cdk-portal-overview/cdk-portal-overview-example.ts

@@ -1,5 +1,12 @@
-import {Component, AfterViewInit, TemplateRef, ViewChild, ViewContainerRef} from '@angular/core';
-import {ComponentPortal, Portal, TemplatePortal} from '@angular/cdk/portal';
+import {ComponentPortal, DomPortal, Portal, TemplatePortal} from '@angular/cdk/portal';
+import {
+  AfterViewInit,
+  Component,
+  TemplateRef,
+  ViewChild,
+  ViewContainerRef,
+  ElementRef
+} from '@angular/core';
 
 /**
  * @title Portal overview
@@ -10,21 +17,28 @@ import {ComponentPortal, Portal, TemplatePortal} from '@angular/cdk/portal';
   styleUrls: ['cdk-portal-overview-example.css'],
 })
 export class CdkPortalOverviewExample implements AfterViewInit {
-  @ViewChild('templatePortalContent') templatePortalContent: TemplateRef<any>;
+  @ViewChild('templatePortalContent') templatePortalContent: TemplateRef<unknown>;
+  @ViewChild('domPortalContent', {static: true}) domPortalContent: ElementRef<HTMLElement>;
+
   selectedPortal: Portal<any>;
   componentPortal: ComponentPortal<ComponentPortalExample>;
   templatePortal: TemplatePortal<any>;
+  domPortal: DomPortal<any>;
 
-  constructor(private _viewContainerRef: ViewContainerRef) {}
+  constructor(private _viewContainerRef: ViewContainerRef) { }
 
   ngAfterViewInit() {
     this.componentPortal = new ComponentPortal(ComponentPortalExample);
-    this.templatePortal = new TemplatePortal(this.templatePortalContent, this._viewContainerRef);
+    this.templatePortal = new TemplatePortal(
+      this.templatePortalContent,
+      this._viewContainerRef
+    );
+    this.domPortal = new DomPortal(this.domPortalContent);
   }
 }
 
 @Component({
   selector: 'component-portal-example',
   template: 'Hello, this is a component portal'
 })
-export class ComponentPortalExample {}
+export class ComponentPortalExample { }