docs(upgrade): add API docs for downgradeModule() (#18487) (#18487)

PR Close #18487

PR Close #18487

packages/examples/upgrade/static/ts/full/e2e_test/static_full_spec.ts

@@ -7,16 +7,15 @@
  */
 
 import {browser, by, element} from 'protractor';
-import {verifyNoBrowserErrors} from '../../../../_common/e2e_util';
+import {verifyNoBrowserErrors} from '../../../../../_common/e2e_util';
 
-function loadPage(url: string) {
-  browser.ng12Hybrid = true;
+function loadPage() {
   browser.rootEl = 'example-app';
-  browser.get(url);
+  browser.get('/upgrade/static/ts/full/');
 }
 
-describe('upgrade(static)', () => {
-  beforeEach(() => { loadPage('/upgrade/static/ts/'); });
+describe('upgrade/static (full)', () => {
+  beforeEach(loadPage);
   afterEach(verifyNoBrowserErrors);
 
   it('should render the `ng2-heroes` component', () => {

packages/examples/upgrade/static/ts/full/module.ts

@@ -5,11 +5,14 @@
  * 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 {Component, Directive, ElementRef, EventEmitter, Inject, Injectable, Injector, Input, NgModule, Output, SimpleChanges} from '@angular/core';
+
+import {Component, Directive, ElementRef, EventEmitter, Inject, Injectable, Injector, Input, NgModule, Output} from '@angular/core';
 import {BrowserModule} from '@angular/platform-browser';
 import {platformBrowserDynamic} from '@angular/platform-browser-dynamic';
 import {UpgradeComponent, UpgradeModule, downgradeComponent, downgradeInjectable} from '@angular/upgrade/static';
 
+declare var angular: ng.IAngularStatic;
+
 interface Hero {
   name: string;
   description: string;
@@ -116,7 +119,6 @@ class Ng2AppModule {
 // #docregion Angular 1 Stuff
 // #docregion ng1-module
 // This Angular 1 module represents the AngularJS pieces of the application
-declare var angular: ng.IAngularStatic;
 const ng1AppModule = angular.module('ng1AppModule', []);
 // #enddocregion
 
@@ -136,7 +138,7 @@ ng1AppModule.component('ng1Hero', {
 // This AngularJS service will be "upgraded" to be used in Angular
 ng1AppModule.factory(
     'titleCase',
-    (() => (value: string) => value.replace(/((^|\s)[a-z])/g, (_, c) => c.toUpperCase())) as any);
+    () => (value: string) => value.replace(/((^|\s)[a-z])/g, (_, c) => c.toUpperCase()));
 // #enddocregion
 
 // #docregion downgrade-ng2-heroes-service
@@ -145,7 +147,7 @@ ng1AppModule.factory('heroesService', downgradeInjectable(HeroesService) as any)
 // #enddocregion
 
 // #docregion ng2-heroes-wrapper
-// This is directive will act as the interface to the "downgraded" Angular component
+// This directive will act as the interface to the "downgraded" Angular component
 ng1AppModule.directive('ng2Heroes', downgradeComponent({component: Ng2HeroesComponent}));
 // #enddocregion
 
@@ -155,20 +157,18 @@ ng1AppModule.component('exampleApp', {
   // We inject the "downgraded" HeroesService into this AngularJS component
   // (We don't need the `HeroesService` type for AngularJS DI - it just helps with TypeScript
   // compilation)
-  controller:
-      [
-        'heroesService',
-        function(heroesService: HeroesService) { this.heroesService = heroesService; }
-      ],
-      // This template make use of the downgraded `ng2-heroes` component
-      // Note that because its element is compiled by AngularJS we must use kebab-case attributes
-      // for inputs and outputs
-      template: `<link rel="stylesheet" href="./styles.css">
-             <ng2-heroes [heroes]="$ctrl.heroesService.heroes" (add-hero)="$ctrl.heroesService.addHero()" (remove-hero)="$ctrl.heroesService.removeHero($event)">
-               <h1>Heroes</h1>
-               <p class="extra">There are {{ $ctrl.heroesService.heroes.length }} heroes.</p>
-             </ng2-heroes>`
-} as any);
+  controller: [
+    'heroesService', function(heroesService: HeroesService) { this.heroesService = heroesService; }
+  ],
+  // This template makes use of the downgraded `ng2-heroes` component
+  // Note that because its element is compiled by AngularJS we must use kebab-case attributes
+  // for inputs and outputs
+  template: `<link rel="stylesheet" href="./styles.css">
+          <ng2-heroes [heroes]="$ctrl.heroesService.heroes" (add-hero)="$ctrl.heroesService.addHero()" (remove-hero)="$ctrl.heroesService.removeHero($event)">
+            <h1>Heroes</h1>
+            <p class="extra">There are {{ $ctrl.heroesService.heroes.length }} heroes.</p>
+          </ng2-heroes>`
+});
 // #enddocregion
 // #enddocregion
 

packages/examples/upgrade/static/ts/lite/e2e_test/e2e_util.ts

@@ -0,0 +1,64 @@
+/**
+ * @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 {ElementFinder, by} from 'protractor';
+
+declare global {
+  namespace jasmine {
+  interface Matchers {
+    toBeAHero(): Promise<void>;
+    toHaveName(exectedName: string): Promise<void>;
+  }
+  }
+}
+
+const isTitleCased = (text: string) =>
+    text.split(/\s+/).every(word => word[0] === word[0].toUpperCase());
+
+export function addCustomMatchers() {
+  jasmine.addMatchers({
+    toBeAHero:
+        () => ({
+          compare(actualNg1Hero: ElementFinder | undefined) {
+            const getText = (selector: string) =>
+                actualNg1Hero !.element(by.css(selector)).getText();
+            const result = {
+              message: 'Expected undefined to be an `ng1Hero` ElementFinder.',
+              pass: !!actualNg1Hero &&
+                  Promise.all(['.title', 'h2', 'p'].map(getText) as PromiseLike<string>[])
+                      .then(([actualTitle, actualName, actualDescription]) => {
+                        const pass = (actualTitle === 'Super Hero') && isTitleCased(actualName) &&
+                            (actualDescription.length > 0);
+
+                        const actualHero =
+                            `Hero(${actualTitle}, ${actualName}, ${actualDescription})`;
+                        result.message =
+                            `Expected ${actualHero}'${pass ? ' not' : ''} to be a real hero.`;
+
+                        return pass;
+                      })
+            };
+            return result;
+          }
+        }),
+        toHaveName: () => ({
+          compare(actualNg1Hero: ElementFinder | undefined, expectedName: string) {
+            const result = {
+              message: 'Expected undefined to be an `ng1Hero` ElementFinder.',
+              pass: !!actualNg1Hero && actualNg1Hero.element(by.css('h2')).getText().then(actualName => {
+                const pass = actualName === expectedName;
+                result.message =
+                    `Expected Hero(${actualName})${pass ? ' not' : ''} to have name '${expectedName}'.`;
+                return pass;
+              })
+            };
+            return result;
+          }
+        }),
+  } as any);
+}

packages/examples/upgrade/static/ts/lite/e2e_test/static_lite_spec.ts

@@ -0,0 +1,89 @@
+/**
+ * @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 {ElementArrayFinder, ElementFinder, browser, by, element} from 'protractor';
+
+import {verifyNoBrowserErrors} from '../../../../../_common/e2e_util';
+import {addCustomMatchers} from './e2e_util';
+
+function loadPage() {
+  browser.rootEl = 'example-app';
+  browser.get('/upgrade/static/ts/lite/');
+}
+
+describe('upgrade/static (lite)', () => {
+  let showHideBtn: ElementFinder;
+  let ng2Heroes: ElementFinder;
+  let ng2HeroesHeader: ElementFinder;
+  let ng2HeroesExtra: ElementFinder;
+  let ng2HeroesAddBtn: ElementFinder;
+  let ng1Heroes: ElementArrayFinder;
+
+  const expectHeroes = (isShown: boolean, ng1HeroCount = 3, statusMessage = 'Ready') => {
+    // Verify the show/hide button text.
+    expect(showHideBtn.getText()).toBe(isShown ? 'Hide heroes' : 'Show heroes');
+
+    // Verify the `<ng2-heroes>` component.
+    expect(ng2Heroes.isPresent()).toBe(isShown);
+    if (isShown) {
+      expect(ng2HeroesHeader.getText()).toBe('Heroes');
+      expect(ng2HeroesExtra.getText()).toBe(`Status: ${statusMessage}`);
+    }
+
+    // Verify the `<ng1-hero>` components.
+    expect(ng1Heroes.count()).toBe(isShown ? ng1HeroCount : 0);
+    if (isShown) {
+      ng1Heroes.each(ng1Hero => expect(ng1Hero).toBeAHero());
+    }
+  };
+
+  beforeEach(() => {
+    showHideBtn = element(by.binding('toggleBtnText'));
+
+    ng2Heroes = element(by.css('.ng2-heroes'));
+    ng2HeroesHeader = ng2Heroes.element(by.css('h1'));
+    ng2HeroesExtra = ng2Heroes.element(by.css('.extra'));
+    ng2HeroesAddBtn = ng2Heroes.element(by.buttonText('Add Hero'));
+
+    ng1Heroes = element.all(by.css('.ng1-hero'));
+  });
+  beforeEach(addCustomMatchers);
+  beforeEach(loadPage);
+  afterEach(verifyNoBrowserErrors);
+
+  it('should initially not render the heroes', () => expectHeroes(false));
+
+  it('should toggle the heroes when clicking the "show/hide" button', () => {
+    showHideBtn.click();
+    expectHeroes(true);
+
+    showHideBtn.click();
+    expectHeroes(false);
+  });
+
+  it('should add a new hero when clicking the "add" button', () => {
+    showHideBtn.click();
+    ng2HeroesAddBtn.click();
+
+    expectHeroes(true, 4, 'Added hero Kamala Khan');
+    expect(ng1Heroes.last()).toHaveName('Kamala Khan');
+  });
+
+  it('should remove a hero when clicking its "remove" button', () => {
+    showHideBtn.click();
+
+    const firstHero = ng1Heroes.first();
+    expect(firstHero).toHaveName('Superman');
+
+    const removeBtn = firstHero.element(by.buttonText('Remove'));
+    removeBtn.click();
+
+    expectHeroes(true, 2, 'Removed hero Superman');
+    expect(ng1Heroes.first()).not.toHaveName('Superman');
+  });
+});

packages/examples/upgrade/static/ts/lite/module.ts

@@ -0,0 +1,220 @@
+/**
+ * @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
+ */
+
+// #docplaster
+import {Component, Directive, ElementRef, EventEmitter, Inject, Injectable, Injector, Input, NgModule, Output, StaticProvider} from '@angular/core';
+import {BrowserModule} from '@angular/platform-browser';
+// #docregion basic-how-to
+// Alternatively, we could import and use an `NgModuleFactory` instead:
+// import {MyLazyAngularModuleNgFactory} from './my-lazy-angular-module.ngfactory';
+import {platformBrowserDynamic} from '@angular/platform-browser-dynamic';
+// #enddocregion
+/* tslint:disable: no-duplicate-imports */
+import {UpgradeComponent} from '@angular/upgrade/static';
+import {downgradeComponent} from '@angular/upgrade/static';
+import {downgradeInjectable} from '@angular/upgrade/static';
+// #docregion basic-how-to
+import {downgradeModule} from '@angular/upgrade/static';
+// #enddocregion
+/* tslint:enable: no-duplicate-imports */
+
+
+declare var angular: ng.IAngularStatic;
+
+interface Hero {
+  name: string;
+  description: string;
+}
+
+
+// This Angular service will use an "upgraded" AngularJS service.
+@Injectable()
+class HeroesService {
+  heroes: Hero[] = [
+    {name: 'superman', description: 'The man of steel'},
+    {name: 'wonder woman', description: 'Princess of the Amazons'},
+    {name: 'thor', description: 'The hammer-wielding god'}
+  ];
+
+  constructor(@Inject('titleCase') titleCase: (v: string) => string) {
+    // Change all the hero names to title case, using the "upgraded" AngularJS service.
+    this.heroes.forEach((hero: Hero) => hero.name = titleCase(hero.name));
+  }
+
+  addHero() {
+    const newHero: Hero = {name: 'Kamala Khan', description: 'Epic shape-shifting healer'};
+    this.heroes = this.heroes.concat([newHero]);
+    return newHero;
+  }
+
+  removeHero(hero: Hero) { this.heroes = this.heroes.filter((item: Hero) => item !== hero); }
+}
+
+
+// This Angular component will be "downgraded" to be used in AngularJS.
+@Component({
+  selector: 'ng2-heroes',
+  // This template uses the "upgraded" `ng1-hero` component
+  // (Note that because its element is compiled by Angular we must use camelCased attribute names.)
+  template: `
+    <div class="ng2-heroes">
+      <header><ng-content selector="h1"></ng-content></header>
+      <ng-content selector=".extra"></ng-content>
+      <div *ngFor="let hero of this.heroesService.heroes">
+        <ng1-hero [hero]="hero" (onRemove)="onRemoveHero(hero)">
+          <strong>Super Hero</strong>
+        </ng1-hero>
+      </div>
+      <button (click)="onAddHero()">Add Hero</button>
+    </div>
+  `,
+})
+class Ng2HeroesComponent {
+  @Output() private addHero = new EventEmitter<Hero>();
+  @Output() private removeHero = new EventEmitter<Hero>();
+
+  constructor(
+      @Inject('$rootScope') private $rootScope: ng.IRootScopeService,
+      public heroesService: HeroesService) {}
+
+  onAddHero() {
+    const newHero = this.heroesService.addHero();
+    this.addHero.emit(newHero);
+
+    // When a new instance of an "upgraded" component - such as `ng1Hero` - is created, we want to
+    // run a `$digest` to initialize its bindings. Here, the component will be created by `ngFor`
+    // asynchronously, thus we have to schedule the `$digest` to also happen asynchronously.
+    this.$rootScope.$applyAsync();
+  }
+
+  onRemoveHero(hero: Hero) {
+    this.heroesService.removeHero(hero);
+    this.removeHero.emit(hero);
+  }
+}
+
+
+// This Angular directive will act as an interface to the "upgraded" AngularJS component.
+@Directive({selector: 'ng1-hero'})
+class Ng1HeroComponentWrapper extends UpgradeComponent {
+  // The names of the input and output properties here must match the names of the
+  // `<` and `&` bindings in the AngularJS component that is being wrapped.
+  @Input() hero: Hero;
+  @Output() onRemove: EventEmitter<void>;
+
+  constructor(elementRef: ElementRef, injector: Injector) {
+    // We must pass the name of the directive as used by AngularJS to the super.
+    super('ng1Hero', elementRef, injector);
+  }
+}
+
+
+// This Angular module represents the Angular pieces of the application.
+@NgModule({
+  imports: [BrowserModule],
+  declarations: [Ng2HeroesComponent, Ng1HeroComponentWrapper],
+  providers: [
+    HeroesService,
+    // Register an Angular provider whose value is the "upgraded" AngularJS service.
+    {provide: 'titleCase', useFactory: (i: any) => i.get('titleCase'), deps: ['$injector']}
+  ],
+  // All components that are to be "downgraded" must be declared as `entryComponents`.
+  entryComponents: [Ng2HeroesComponent]
+  // Note that there are no `bootstrap` components, since the "downgraded" component
+  // will be instantiated by ngUpgrade.
+})
+class MyLazyAngularModule {
+  // Empty placeholder method to prevent the `Compiler` from complaining.
+  ngDoBootstrap() {}
+}
+
+
+// #docregion basic-how-to
+
+
+// The function that will bootstrap the Angular module (when/if necessary).
+// (This would be omitted if we provided an `NgModuleFactory` directly.)
+const ng2BootstrapFn = (extraProviders: StaticProvider[]) =>
+    platformBrowserDynamic(extraProviders).bootstrapModule(MyLazyAngularModule);
+// #enddocregion
+// (We are using the dynamic browser platform, as this example has not been compiled AoT.)
+
+
+// #docregion basic-how-to
+
+
+// This AngularJS module represents the AngularJS pieces of the application.
+const myMainAngularJsModule = angular.module('myMainAngularJsModule', [
+  // We declare a dependency on the "downgraded" Angular module.
+  downgradeModule(ng2BootstrapFn)
+  // or
+  // downgradeModule(MyLazyAngularModuleFactory)
+]);
+// #enddocregion
+
+
+// This AngularJS component will be "upgraded" to be used in Angular.
+myMainAngularJsModule.component('ng1Hero', {
+  bindings: {hero: '<', onRemove: '&'},
+  transclude: true,
+  template: `
+    <div class="ng1-hero">
+      <div class="title" ng-transclude></div>
+      <h2>{{ $ctrl.hero.name }}</h2>
+      <p>{{ $ctrl.hero.description }}</p>
+      <button ng-click="$ctrl.onRemove()">Remove</button>
+    </div>
+  `
+});
+
+
+// This AngularJS service will be "upgraded" to be used in Angular.
+myMainAngularJsModule.factory(
+    'titleCase', () => (value: string) => value.replace(/(^|\s)[a-z]/g, m => m.toUpperCase()));
+
+
+// This directive will act as the interface to the "downgraded" Angular component.
+myMainAngularJsModule.directive(
+    'ng2Heroes', downgradeComponent({
+      component: Ng2HeroesComponent,
+      // Optionally, disable `$digest` propagation to avoid unnecessary change detection.
+      // (Change detection is still run when the inputs of a "downgraded" component change.)
+      propagateDigest: false
+    }));
+
+
+// This is our top level application component.
+myMainAngularJsModule.component('exampleApp', {
+  // This template makes use of the "downgraded" `ng2-heroes` component,
+  // but loads it lazily only when/if the user clicks the button.
+  // (Note that because its element is compiled by AngularJS,
+  //  we must use kebab-case attributes for inputs and outputs.)
+  template: `
+    <link rel="stylesheet" href="./styles.css">
+    <button ng-click="$ctrl.toggleHeroes()">{{ $ctrl.toggleBtnText() }}</button>
+    <ng2-heroes
+        ng-if="$ctrl.showHeroes"
+        (add-hero)="$ctrl.setStatusMessage('Added hero ' + $event.name)"
+        (remove-hero)="$ctrl.setStatusMessage('Removed hero ' + $event.name)">
+      <h1>Heroes</h1>
+      <p class="extra">Status: {{ $ctrl.statusMessage }}</p>
+    </ng2-heroes>
+  `,
+  controller: function() {
+    this.showHeroes = false;
+    this.statusMessage = 'Ready';
+
+    this.setStatusMessage = (msg: string) => this.statusMessage = msg;
+    this.toggleHeroes = () => this.showHeroes = !this.showHeroes;
+    this.toggleBtnText = () => `${this.showHeroes ? 'Hide' : 'Show'} heroes`;
+  }
+});
+
+
+// We bootstrap the Angular module as we would do in a normal Angular app.
+angular.bootstrap(document.body, [myMainAngularJsModule.name]);

packages/examples/upgrade/static/ts/lite/styles.css

@@ -0,0 +1,17 @@
+ng2-heroes {
+  border: solid black 2px;
+  display: block;
+  padding: 5px;
+}
+
+ng1-hero {
+  border: solid green 2px;
+  margin-top: 5px;
+  padding: 5px;
+  display: block;
+}
+
+.title {
+  background-color: blue;
+  color: white;
+}