feat(NgComponentOutlet): add NgComponentOutlet directive

Add NgComponentOutlet directive that can be used to dynamically create
host views from a supplied component.

Closes #11168
Takes over PR #11235

modules/@angular/common/src/common.ts

@@ -14,7 +14,7 @@
 export * from './location/index';
 export {NgLocaleLocalization, NgLocalization} from './localization';
 export {CommonModule} from './common_module';
-export {NgClass, NgFor, NgIf, NgPlural, NgPluralCase, NgStyle, NgSwitch, NgSwitchCase, NgSwitchDefault, NgTemplateOutlet} from './directives/index';
+export {NgClass, NgFor, NgIf, NgPlural, NgPluralCase, NgStyle, NgSwitch, NgSwitchCase, NgSwitchDefault, NgTemplateOutlet, NgComponentOutlet} from './directives/index';
 export {AsyncPipe, DatePipe, I18nPluralPipe, I18nSelectPipe, JsonPipe, LowerCasePipe, CurrencyPipe, DecimalPipe, PercentPipe, SlicePipe, UpperCasePipe, TitleCasePipe} from './pipes/index';
 export {VERSION} from './version';
 export {Version} from '@angular/core';

modules/@angular/common/src/directives/index.ts

@@ -9,6 +9,7 @@
 import {Provider} from '@angular/core';
 
 import {NgClass} from './ng_class';
+import {NgComponentOutlet} from './ng_component_outlet';
 import {NgFor} from './ng_for';
 import {NgIf} from './ng_if';
 import {NgPlural, NgPluralCase} from './ng_plural';
@@ -18,6 +19,7 @@ import {NgTemplateOutlet} from './ng_template_outlet';
 
 export {
   NgClass,
+  NgComponentOutlet,
   NgFor,
   NgIf,
   NgPlural,
@@ -29,12 +31,14 @@ export {
   NgTemplateOutlet
 };
 
+
 /**
  * A collection of Angular directives that are likely to be used in each and every Angular
  * application.
  */
 export const COMMON_DIRECTIVES: Provider[] = [
   NgClass,
+  NgComponentOutlet,
   NgFor,
   NgIf,
   NgTemplateOutlet,

modules/@angular/common/src/directives/ng_component_outlet.ts

@@ -0,0 +1,86 @@
+/**
+ * @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 {ComponentFactoryResolver, ComponentRef, Directive, Injector, Input, OnChanges, Provider, SimpleChanges, Type, ViewContainerRef} from '@angular/core';
+
+
+/**
+ * Instantiates a single {@link Component} type and inserts its Host View into current View.
+ * `NgComponentOutlet` provides a declarative approach for dynamic component creation.
+ *
+ * `NgComponentOutlet` requires a component type, if a falsy value is set the view will clear and
+ * any existing component will get destroyed.
+ *
+ * ### Fine tune control
+ *
+ * You can control the component creation process by using the following optional attributes:
+ *
+ * * `ngOutletInjector`: Optional custom {@link Injector} that will be used as parent for the
+ * Component.
+ * Defaults to the injector of the current view container.
+ *
+ * * `ngOutletProviders`: Optional injectable objects ({@link Provider}) that are visible to the
+ * component.
+ *
+ * * `ngOutletContent`: Optional list of projectable nodes to insert into the content
+ * section of the component, if exists. ({@link NgContent}).
+ *
+ *
+ * ### Syntax
+ *
+ * Simple
+ * ```
+ * <ng-container *ngComponentOutlet="componentTypeExpression"></ng-container>
+ * ```
+ *
+ * Customized
+ * ```
+ * <ng-container *ngComponentOutlet="componentTypeExpression;
+ *                                   injector: injectorExpression;
+ *                                   content: contentNodesExpression">
+ * </ng-container>
+ * ```
+ *
+ * # Example
+ *
+ * {@example common/ngComponentOutlet/ts/module.ts region='SimpleExample'}
+ *
+ * A more complete example with additional options:
+ *
+ * {@example common/ngComponentOutlet/ts/module.ts region='CompleteExample'}
+ *
+ * @experimental
+ */
+@Directive({selector: '[ngComponentOutlet]'})
+export class NgComponentOutlet implements OnChanges {
+  @Input() ngComponentOutlet: Type<any>;
+  @Input() ngComponentOutletInjector: Injector;
+  @Input() ngComponentOutletContent: any[][];
+
+  componentRef: ComponentRef<any>;
+
+  constructor(
+      private _cmpFactoryResolver: ComponentFactoryResolver,
+      private _viewContainerRef: ViewContainerRef) {}
+
+  ngOnChanges(changes: SimpleChanges) {
+    if (this.componentRef) {
+      this._viewContainerRef.remove(this._viewContainerRef.indexOf(this.componentRef.hostView));
+    }
+    this._viewContainerRef.clear();
+    this.componentRef = null;
+
+    if (this.ngComponentOutlet) {
+      let injector = this.ngComponentOutletInjector || this._viewContainerRef.parentInjector;
+
+      this.componentRef = this._viewContainerRef.createComponent(
+          this._cmpFactoryResolver.resolveComponentFactory(this.ngComponentOutlet),
+          this._viewContainerRef.length, injector, this.ngComponentOutletContent);
+    }
+  }
+}