build: support for lazily loading examples in dev-app or docs

Adds support for lazily loading examples in the dev-app, e2e-app or
eventually in the docs. Since we already have modules per component
and use Ivy in the docs, we can lazily load the examples and also
get rid of the large bulk `ExampleModule`.

Author: devversion

src/bazel-tsconfig-build.json

@@ -20,7 +20,9 @@
     "importHelpers": true,
     "strictBindCallApply": true,
     "newLine": "lf",
-    "module": "es2015",
+    // Bazel either uses "umd" or "esnext". We replicate this here for IDE support.
+    // https://github.com/bazelbuild/rules_typescript/blob/master/internal/common/tsconfig.bzl#L199
+    "module": "esnext",
     "moduleResolution": "node",
     "sourceMap": true,
     "inlineSources": true,

src/components-examples/example-data.ts

@@ -3,11 +3,10 @@
 import {EXAMPLE_COMPONENTS} from './example-module';
 
 /**
- * Example data with information about component name, selector, files used in example, and path to
- * examples.
+ * Example data with information about component name, selector, files used in
+ * example, and path to examples.
  */
 export class ExampleData {
-
   /** Description of the example. */
   description: string;
 
@@ -20,31 +19,24 @@ export class ExampleData {
   /** Name of the file that contains the example component. */
   indexFilename: string;
 
-  /**
-   * Name of the example component. For examples with multiple components, this property will
-   * include multiple components that are comma separated (e.g. dialog-overview)
-   */
-  componentName: string;
+  /** Names of the components being used in this example. */
+  componentNames: string[];
 
   constructor(example: string) {
     if (!example || !EXAMPLE_COMPONENTS.hasOwnProperty(example)) {
       return;
     }
 
-    const exampleConfig = EXAMPLE_COMPONENTS[example];
+    const {componentName, additionalFiles, additionalComponents, title} =
+        EXAMPLE_COMPONENTS[example];
+    const exampleName = example.replace(/(?:^\w|\b\w)/g, letter => letter.toUpperCase());
 
     // TODO(tinayuangao): Do not hard-code extensions
     this.exampleFiles = ['html', 'ts', 'css'].map(extension => `${example}-example.${extension}`);
     this.selectorName = this.indexFilename = `${example}-example`;
 
-    if (exampleConfig.additionalFiles) {
-      this.exampleFiles.push(...exampleConfig.additionalFiles);
-    }
-
-    const exampleName = example.replace(/(?:^\w|\b\w)/g, letter => letter.toUpperCase());
-
-    this.description = exampleConfig.title || exampleName.replace(/[\-]+/g, ' ') + ' Example';
-    this.componentName = exampleConfig.selectorName ||
-                          exampleName.replace(/[\-]+/g, '') + 'Example';
+    this.exampleFiles.push(...additionalFiles);
+    this.description = title || exampleName.replace(/[\-]+/g, ' ') + ' Example';
+    this.componentNames = [componentName, ...additionalComponents];
   }
 }

src/components-examples/load-example.ts

@@ -0,0 +1,26 @@
+/**
+ * @license
+ * Copyright Google LLC 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 {ComponentFactory, Injector, NgModuleFactory, Type} from '@angular/core';
+import {EXAMPLE_COMPONENTS} from './example-module';
+
+/** Asynchronously loads the specified example and returns its component factory. */
+export async function loadExampleFactory(name: string, injector: Injector)
+    : Promise<ComponentFactory<any>> {
+  const {componentName, module} = EXAMPLE_COMPONENTS[name];
+  // TODO(devversion): remove the NgFactory import when the `--config=view-engine` switch is gone.
+  const [moduleFactoryExports, moduleExports] = await Promise.all([
+    import(module.importSpecifier + '/index.ngfactory'),
+    import(module.importSpecifier)
+  ]);
+  const moduleFactory: NgModuleFactory<any> = moduleFactoryExports[`${module.name}NgFactory`];
+  const componentType: Type<any> = moduleExports[componentName];
+  return moduleFactory.create(injector)
+    .componentFactoryResolver.resolveComponentFactory(componentType);
+}
+

src/components-examples/public-api.ts

@@ -1,4 +1,5 @@
 export * from './example-data';
+export * from './load-example';
 
 // The example-module file will be auto-generated. As soon as the
 // examples are being compiled, the module file will be generated.

src/dev-app/example/example-module.ts

@@ -9,14 +9,13 @@
 import {CommonModule} from '@angular/common';
 import {NgModule} from '@angular/core';
 import {MatExpansionModule} from '@angular/material/expansion';
-import {ExampleModule as DocsExampleModule} from '@angular/components-examples';
 import {Example} from './example';
 
 
 import {ExampleList} from './example-list';
 
 @NgModule({
-  imports: [CommonModule, MatExpansionModule, DocsExampleModule],
+  imports: [CommonModule, MatExpansionModule],
   declarations: [Example, ExampleList],
   exports: [Example, ExampleList]
 })

src/dev-app/example/example.ts

@@ -7,9 +7,8 @@
  */
 
 import {BooleanInput, coerceBooleanProperty} from '@angular/cdk/coercion';
-import {Component, ElementRef, Injector, Input, OnInit} from '@angular/core';
-import {EXAMPLE_COMPONENTS} from '@angular/components-examples';
-import {createCustomElement} from '@angular/elements';
+import {EXAMPLE_COMPONENTS, loadExampleFactory} from '@angular/components-examples';
+import {Component, Injector, Input, OnInit, ViewContainerRef} from '@angular/core';
 
 @Component({
   selector: 'material-example',
@@ -55,21 +54,12 @@ export class Example implements OnInit {
 
   title: string;
 
-  constructor(private _elementRef: ElementRef<HTMLElement>, private _injector: Injector) { }
+  constructor(private _injector: Injector,
+              private _viewContainerRef: ViewContainerRef) {}
 
-  ngOnInit() {
-    let exampleElementCtor = customElements.get(this.id);
-
-    if (!exampleElementCtor) {
-      exampleElementCtor = createCustomElement(EXAMPLE_COMPONENTS[this.id].component, {
-        injector: this._injector
-      });
-
-      customElements.define(this.id, exampleElementCtor);
-    }
-
-    this._elementRef.nativeElement.appendChild(new exampleElementCtor(this._injector));
-    this.title = EXAMPLE_COMPONENTS[this.id] ? EXAMPLE_COMPONENTS[this.id].title : '';
+  async ngOnInit() {
+    this.title = EXAMPLE_COMPONENTS[this.id].title;
+    this._viewContainerRef.createComponent(await loadExampleFactory(this.id, this._injector));
   }
 
   static ngAcceptInputType_showLabel: BooleanInput;

src/e2e-app/devserver-configure.js

@@ -4,6 +4,9 @@ require.config({
   paths: {
     'moment': 'moment/min/moment.min',
 
+    // Support for lazy-loading of component examples.
+    '@angular/components-examples': 'angular_material/src/components-examples',
+
     // MDC Web
     '@material/animation': '@material/animation/dist/mdc.animation',
     '@material/auto-init': '@material/auto-init/dist/mdc.autoInit',

src/e2e-app/example-viewer/example-viewer-module.ts

@@ -8,12 +8,11 @@
 
 import {CommonModule} from '@angular/common';
 import {NgModule} from '@angular/core';
-import {ExampleModule as ExampleDataModule} from '@angular/components-examples';
 import {ExampleListViewer} from './example-list-viewer.component';
 import {ExampleViewer} from './example-viewer';
 
 @NgModule({
-  imports: [CommonModule, ExampleDataModule],
+  imports: [CommonModule],
   declarations: [ExampleViewer, ExampleListViewer],
   exports: [ExampleViewer, ExampleListViewer]
 })

src/e2e-app/example-viewer/example-viewer.ts

@@ -6,9 +6,8 @@
  * found in the LICENSE file at https://angular.io/license
  */
 
-import {Component, ElementRef, Injector, Input, OnInit} from '@angular/core';
-import {createCustomElement} from '@angular/elements';
-import {EXAMPLE_COMPONENTS} from '@angular/components-examples';
+import {loadExampleFactory} from '@angular/components-examples';
+import {Component, Injector, Input, OnInit, ViewContainerRef} from '@angular/core';
 
 /** Loads an example component from `@angular/components-examples` */
 @Component({
@@ -23,18 +22,10 @@ export class ExampleViewer implements OnInit {
   /** ID of the material example to display. */
   @Input() id: string;
 
-  constructor(private _elementRef: ElementRef<HTMLElement>, private _injector: Injector) {}
+  constructor(private _injector: Injector,
+              private _viewContainerRef: ViewContainerRef) {}
 
-  ngOnInit() {
-    let exampleElementCtor = customElements.get(this.id);
-
-    if (!exampleElementCtor) {
-      exampleElementCtor =
-          createCustomElement(EXAMPLE_COMPONENTS[this.id].component, {injector: this._injector});
-
-      customElements.define(this.id, exampleElementCtor);
-    }
-
-    this._elementRef.nativeElement.appendChild(new exampleElementCtor(this._injector));
+  async ngOnInit() {
+    this._viewContainerRef.createComponent(await loadExampleFactory(this.id, this._injector));
   }
 }

tools/example-module/example-module.template

@@ -1,43 +1,26 @@
 /**
  ******************************************************************************
  * DO NOT MANUALLY EDIT THIS FILE. THIS FILE IS AUTOMATICALLY GENERATED.
- *
- * IMPORTANT: Due to a bug with the bazel ng_module rule, this file is now
- * checked into the repository. Please rebuild the example module by running
- * the following command: "yarn gulp build-examples-module"
- *
- * BUG: https://github.com/angular/angular/issues/30259
  ******************************************************************************/
 
-import {NgModule} from '@angular/core';
-import {MAT_FORM_FIELD_DEFAULT_OPTIONS} from '@angular/material/form-field';
-
-${exampleImports}
-
 export interface LiveExample {
+  /** Title of the example. */
   title: string;
-  component: any;
-  additionalFiles?: string[];
-  selectorName?: string;
+  /** Name of the example component. */
+  componentName: string;
+  /** List of additional components which are part of the example. */
+  additionalComponents: string[];
+  /** List of additional files which are part of the example. */
+  additionalFiles: string[];
+  /** NgModule that declares this example. */
+  module: NgModuleInfo;
 }
 
-export const EXAMPLE_COMPONENTS: {[key: string]: LiveExample} = ${exampleComponents};
-
-export const EXAMPLE_MODULES = ${exampleModules};
-
-export const EXAMPLE_LIST = [${exampleList}];
-
-// Default MatFormField appearance to 'fill' as that is the new recommended approach and the
-// `legacy` and `standard` appearances are scheduled for deprecation in version 10.
-@NgModule({
-  imports: EXAMPLE_MODULES,
-  exports: EXAMPLE_MODULES,
-  providers: [
-    { provide: MAT_FORM_FIELD_DEFAULT_OPTIONS, useValue: { appearance: 'fill' } },
-  ],
-})
-export class ExampleModule { }
+export interface NgModuleInfo {
+  /** Name of the NgModule. */
+  name: string;
+  /** Import specifier that resolves to this NgModule. */
+  importSpecifier: string;
+}
 
-// Export all individual example components because ngtsc requires all
-// referenced components to be available in the top-level entry-point.
-export {${exampleList}}
+export const EXAMPLE_COMPONENTS: {[key: string]: LiveExample} = ${exampleComponents};