docs(architecture/ts): proofread

- e2e tests now also cover the tax calculator.
- Dart app updated to match TS (it had no sales tax calculator).
- TS sample source cleanup (e.g. removed many unnecessary `docregions`).
- Prose updated to include @kwalrath's revisions from a while ago, with
some of my edits as well.

Contributes to angular#1598 and angular#1508.

Author: chalin

public/docs/_examples/architecture/e2e-spec.ts

@@ -1,63 +1,113 @@
 /// <reference path='../_protractor/e2e.d.ts' />
 'use strict';
-describe('Architecture', function () {
-
-  let title = 'Hero List';
-
-  beforeAll(function () {
-    browser.get('');
-  });
-
-  function itReset(name: string, func: () => any) {
-    it(name, function() {
-      browser.get('').then(func);
-    });
-  }
-
-  it(`should display correct title: ${title}`, function () {
-    expect(element(by.css('h2')).getText()).toEqual(title);
-  });
-
-  it('should display correct detail after selection', function() {
-    let detailView = element(by.css('hero-detail'));
-    expect(detailView.isPresent()).toBe(false);
-    // select the 2nd element
-    let selectEle = element.all(by.css('hero-list > div')).get(1);
-    selectEle.click().then(function() {
-      return selectEle.getText();
-    }).then(function(selectedHeroName) {
-      // works but too specific if we change the app
-      // expect(selectedHeroName).toEqual('Mr. Nice');
-      expect(detailView.isDisplayed()).toBe(true);
-      let detailTitleEle = element(by.css('hero-detail > h4'));
-      expect(detailTitleEle.getText()).toContain(selectedHeroName);
-    });
-  });
-
-  itReset('should display correct detail after modification', function() {
-    let detailView = element(by.css('hero-detail'));
-    expect(detailView.isPresent()).toBe(false);
-    // select the 2nd element
-    let selectEle = element.all(by.css('hero-list > div')).get(1);
-    selectEle.click().then(function () {
-      return selectEle.getText();
-    }).then(function (selectedHeroName) {
-      let detailTitleEle = element(by.css('hero-detail > h4'));
-      expect(detailTitleEle.getText()).toContain(selectedHeroName);
-      let heroNameEle = element.all(by.css('hero-detail input')).get(0);
-
-      // check that both the initial selected item and the detail title reflect changes
-      // made to the input box.
-      // heroNameEle.sendKeys('foo');
-      sendKeys(heroNameEle, 'foo');
-      expect(detailTitleEle.getText()).toContain('foo');
-      expect(selectEle.getText()).toContain('foo');
-
-      // getText on an input element always returns null
-      // http://stackoverflow.com/questions/20310442/how-to-gettext-on-an-input-in-protractor
-      // expect(heroNameEle.getText()).toEqual(selectedHeroName);
-      expect(heroNameEle.getAttribute('value')).toEqual(selectedHeroName + 'foo');
-    });
+
+const nameSuffix = 'X';
+type WPromise<T> = webdriver.promise.Promise<T>;
+
+class Hero {
+  id: number;
+  name: string;
+}
+
+describe('Architecture', () => {
+
+  const expectedTitle = 'Architecture of Angular 2';
+  const expectedH2 = ['Hero List', 'Sales Tax Calculator'];
+
+  beforeAll(() => browser.get(''));
+
+  it(`has title '${expectedTitle}'`, () => {
+    expect(browser.getTitle()).toEqual(expectedTitle);
+  });
+
+  it(`has h2 '${expectedH2}'`, () => {
+    let h2 = element.all(by.css('h2')).map((elt) => elt.getText());
+    expect(h2).toEqual(expectedH2);
   });
 
+  describe('Hero', heroTests);
+  describe('Salex tax', salesTaxTests);
 });
+
+function heroTests() {
+
+  const targetHero: Hero = { id: 2, name: 'Mr. Nice' };
+
+  it('has the right number of heroes', () => {
+    let page = getPageElts();
+    expect(page.heroes.count()).toEqual(3);
+  });
+
+  it('has no hero details initially', function () {
+    let page = getPageElts();
+    expect(page.heroDetail.isPresent()).toBeFalsy('no hero detail');
+  });
+
+  it(`selects ${targetHero.name} from hero list`, function () {
+    let hero = element(by.cssContainingText('li', targetHero.name));
+    hero.click();
+    // Nothing specific to expect other than lack of exceptions.
+  });
+
+  it('shows selected hero details', async () => {
+    let page = getPageElts();
+    let hero = await heroFromDetail(page.heroDetail);
+    expect(hero.id).toEqual(targetHero.id);
+    expect(hero.name).toEqual(targetHero.name);
+  });
+
+  it(`can update hero name`, () => {
+    addToHeroName(nameSuffix);
+    // Nothing specific to expect other than lack of exceptions.
+  });
+
+  it(`shows updated hero name in details`, async () => {
+    let page = getPageElts();
+    let hero = await heroFromDetail(page.heroDetail);
+    let newName = targetHero.name + nameSuffix;
+    expect(hero.id).toEqual(targetHero.id);
+    expect(hero.name).toEqual(newName);
+  });
+}
+
+function salesTaxTests() {
+  it('has no sales tax initially', function () {
+    let page = getPageElts();
+    expect(page.salesTaxDetail.isPresent()).toBeFalsy('no sales tax info');
+  });
+
+  it('shows sales tax', async function () {
+    let page = getPageElts();
+    await sendKeys(page.salesTaxAmountInput, '10');
+    // Note: due to Dart bug USD is shown instead of $
+    let re = /The sales tax is (\$|USD)1.00/;
+    expect(page.salesTaxDetail.getText()).toMatch(re);
+  });
+}
+
+// Helper functions
+
+function getPageElts() {
+  return {
+    heroes: element.all(by.css('my-app li')),
+    heroDetail: element(by.css('my-app hero-detail')),
+    salesTaxAmountInput: element(by.css('my-app sales-tax input')),
+    salesTaxDetail: element(by.css('my-app sales-tax div'))
+  };
+}
+
+function addToHeroName(text: string): WPromise<void> {
+    let input = element.all(by.css('input')).first();
+    return sendKeys(input, text);
+}
+
+async function heroFromDetail(detail: protractor.ElementFinder): Promise<Hero> {
+  // Get hero id from the first <div>
+  let _id = await detail.all(by.css('div')).first().getText();
+  // Get name from the h2
+  let _name = await detail.element(by.css('h4')).getText();
+  return {
+    id: +_id.substr(_id.indexOf(' ') + 1),
+    name: _name.substr(0, _name.lastIndexOf(' '))
+  };
+}

public/docs/_examples/architecture/ts/app/hero-detail.component.html

@@ -2,8 +2,8 @@
 <h4>{{hero.name}} Detail</h4>
 <div>Id: {{hero.id}}</div>
 <div>Name:
-<!-- #docregion ngModel -->
-<input [(ngModel)]="hero.name">
-<!-- #enddocregion ngModel -->
+  <!-- #docregion ngModel -->
+  <input [(ngModel)]="hero.name">
+  <!-- #enddocregion ngModel -->
 </div>
-<div>Power:<input [(ngModel)]="hero.power"></div>
+<div>Power:<input [(ngModel)]="hero.power"></div>

public/docs/_examples/architecture/ts/app/hero-list.component.1.html

@@ -1,12 +1,9 @@
 <!--#docregion binding  -->
-<div>{{hero.name}}</div>
+<li>{{hero.name}}</li>
 <hero-detail [hero]="selectedHero"></hero-detail>
-<div (click)="selectHero(hero)"></div>
-
+<li (click)="selectHero(hero)"></li>
 <!--#enddocregion binding -->
 
 <!--#docregion structural  -->
-<div *ngFor="let hero of heroes"></div>
+<li *ngFor="let hero of heroes"></li>
 <hero-detail *ngIf="selectedHero"></hero-detail>
-
-<!--#enddocregion structural -->

public/docs/_examples/architecture/ts/app/hero-list.component.html

@@ -2,8 +2,10 @@
 <h2>Hero List</h2>
 
 <p><i>Pick a hero from the list</i></p>
-<div *ngFor="let hero of heroes" (click)="selectHero(hero)">
-  {{hero.name}}
-</div>
+<ul>
+  <li *ngFor="let hero of heroes" (click)="selectHero(hero)">
+    {{hero.name}}
+  </li>
+</ul>
 
 <hero-detail *ngIf="selectedHero" [hero]="selectedHero"></hero-detail>

public/docs/_examples/architecture/ts/app/hero-list.component.ts

@@ -1,40 +1,32 @@
-// #docplaster
 import { Component, OnInit }   from '@angular/core';
 
 import { Hero }                from './hero';
 import { HeroDetailComponent } from './hero-detail.component';
 import { HeroService }         from './hero.service';
 
-// #docregion metadata
-// #docregion providers
+// #docregion metadata, providers
 @Component({
-// #enddocregion providers
+  // #enddocregion providers
   selector:    'hero-list',
   templateUrl: 'app/hero-list.component.html',
   directives:  [HeroDetailComponent],
-// #docregion providers
+  // #docregion providers
   providers:   [HeroService]
 })
-// #enddocregion providers
-// #enddocregion metadata
-/*
-// #docregion metadata, providers
-export class HeroesComponent { ... }
-// #enddocregion metadata, providers
-*/
 // #docregion class
 export class HeroListComponent implements OnInit {
+  // #enddocregion metadata, providers
   heroes: Hero[];
   selectedHero: Hero;
 
-// #docregion ctor
+  // #docregion ctor
   constructor(private service: HeroService) { }
-// #enddocregion ctor
+  // #enddocregion ctor
 
   ngOnInit() {
     this.heroes = this.service.getHeroes();
   }
 
   selectHero(hero: Hero) { this.selectedHero = hero; }
+  // #docregion metadata, providers
 }
-// #enddocregion class

public/docs/_examples/architecture/ts/app/hero.service.ts

@@ -9,11 +9,9 @@ import { Logger } from './logger.service';
 export class HeroService {
   private heroes: Hero[] = [];
 
-  // #docregion ctor
   constructor(
     private backend: BackendService,
     private logger: Logger) { }
-  // #enddocregion ctor
 
   getHeroes() {
     this.backend.getAll(Hero).then( (heroes: Hero[]) => {
@@ -23,4 +21,3 @@ export class HeroService {
     return this.heroes;
   }
 }
-// #enddocregion class

public/docs/_examples/architecture/ts/app/logger.service.ts

@@ -1,4 +1,3 @@
-// #docregion
 import { Injectable } from '@angular/core';
 
 @Injectable()
@@ -8,4 +7,3 @@ export class Logger {
   error(msg: any) { console.error(msg); }
   warn(msg: any)  { console.warn(msg); }
 }
-// #enddocregion class

public/docs/_examples/architecture/ts/app/sales-tax.component.ts

@@ -1,42 +1,25 @@
-// #docplaster
-// #docregion
 import { Component }       from '@angular/core';
 
 import { SalesTaxService } from './sales-tax.service';
 import { TaxRateService }  from './tax-rate.service';
 
-// #docregion metadata
-// #docregion providers
 @Component({
-// #enddocregion providers
   selector:    'sales-tax',
   template: `
     <h2>Sales Tax Calculator</h2>
-    Amount: <input #amountBox (change)="0">
+    Amount: <input #amountBox (input)="0" type="number">
 
     <div *ngIf="amountBox.value">
     The sales tax is
      {{ getTax(amountBox.value) | currency:'USD':true:'1.2-2' }}
     </div>
   `,
-// #docregion providers
   providers:   [SalesTaxService, TaxRateService]
 })
-// #enddocregion providers
-// #enddocregion metadata
-/*
-// #docregion metadata, providers
-export class SalesTaxComponent { ... }
-// #enddocregion metadata, providers
-*/
-// #docregion class
 export class SalesTaxComponent {
-// #docregion ctor
   constructor(private salesTaxService: SalesTaxService) { }
-// #enddocregion ctor
 
   getTax(value: string | number) {
     return this.salesTaxService.getVAT(value);
   }
 }
-// #enddocregion class

public/docs/_examples/architecture/ts/app/sales-tax.service.ts

@@ -1,20 +1,14 @@
-// #docregion
 import { Injectable } from '@angular/core';
 
 import { TaxRateService } from './tax-rate.service';
 
-// #docregion class
 @Injectable()
 export class SalesTaxService {
   constructor(private rateService: TaxRateService) { }
+
   getVAT(value: string | number) {
-    let amount: number;
-    if (typeof value === 'string') {
-      amount = parseFloat(value);
-    } else {
-      amount = value;
-    }
+    let amount = (typeof value === 'string') ?
+      parseFloat(value) : value;
     return (amount || 0) * this.rateService.getRate('VAT');
   }
 }
-// #enddocregion class

public/docs/_examples/architecture/ts/app/tax-rate.service.ts

@@ -1,9 +1,6 @@
-// #docregion
 import { Injectable } from '@angular/core';
 
-// #docregion class
 @Injectable()
 export class TaxRateService {
-  getRate(rateName: string) {return 0.10; } // always 10% everywhere
+  getRate(rateName: string) { return 0.10; } // 10% everywhere
 }
-// #enddocregion class