docs(guide): add dart version of hierarchical dependency injection

closes #683

public/docs/_examples/hierarchical-dependency-injection/dart/lib/edit_item.dart

@@ -0,0 +1,7 @@
+// #docregion
+class EditItem<T> {
+  bool editing = false;
+  T item;
+  EditItem(this.item);
+}
+// #enddocregion

public/docs/_examples/hierarchical-dependency-injection/dart/lib/hero.dart

@@ -0,0 +1,14 @@
+// #docregion
+import 'package:angular2/angular2.dart';
+
+class Hero {
+  String name;
+  String power;
+
+  Hero clone() {
+    return new Hero()
+      ..name = name
+      ..power = power;
+  }
+}
+// #enddocregion

public/docs/_examples/hierarchical-dependency-injection/dart/lib/hero_card_component.dart

@@ -0,0 +1,16 @@
+// #docregion
+import 'package:angular2/angular2.dart';
+import 'package:hierarchical_di/hero.dart';
+
+@Component(
+    selector: 'hero-card',
+    template: '''
+  <div>
+    <span>Name:</span>
+    <span>{{hero.name}}</span>
+  </div>
+  ''')
+class HeroCardComponent {
+  @Input() Hero hero;
+}
+// #docregion

public/docs/_examples/hierarchical-dependency-injection/dart/lib/hero_editor_component.dart

@@ -0,0 +1,47 @@
+// #docregion
+import 'package:angular2/angular2.dart';
+import 'package:hierarchical_di/restore_service.dart';
+import 'package:hierarchical_di/hero.dart';
+
+@Component(
+    selector: 'hero-editor',
+    // #docregion providers
+    providers: const [RestoreService],
+    // #enddocregion providers
+    template: '''
+  <div>
+    <span>Name:</span>
+    <input [(ngModel)]="hero.name"/>
+    <div>
+      <button (click)="onSaved()">save</button>
+      <button (click)="onCanceled()">cancel</button>
+    </div>
+  </div>
+  ''')
+class HeroEditorComponent {
+  @Output() final EventEmitter canceled = new EventEmitter();
+  @Output() final EventEmitter saved = new EventEmitter();
+
+  RestoreService<Hero> _restoreService;
+
+  HeroEditorComponent(this._restoreService);
+
+  @Input()
+  set hero(Hero hero) {
+    _restoreService.setItem(hero);
+  }
+
+  Hero get hero {
+    return _restoreService.getItem();
+  }
+
+  onSaved() {
+    saved.add(_restoreService.getItem());
+  }
+
+  onCanceled() {
+    hero = _restoreService.restoreItem();
+    canceled.add(hero);
+  }
+}
+// #enddocregion

public/docs/_examples/hierarchical-dependency-injection/dart/lib/heroes_list_component.dart

@@ -0,0 +1,53 @@
+// #docregion
+import 'package:angular2/angular2.dart';
+import 'package:hierarchical_di/hero.dart';
+import 'package:hierarchical_di/heroes_service.dart';
+import 'package:hierarchical_di/hero_editor_component.dart';
+import 'package:hierarchical_di/hero_card_component.dart';
+import 'package:hierarchical_di/edit_item.dart';
+
+@Component(
+    selector: 'heroes-list',
+    template: '''
+  <div>
+      <ul>
+        <li *ngFor="#editItem of heroes">
+          <hero-card
+            [hidden]="editItem.editing"
+            [hero]="editItem.item">
+          </hero-card>
+          <button
+            [hidden]="editItem.editing"
+            (click)="editItem.editing = true">
+              edit
+          </button>
+          <hero-editor
+            (saved)="onSaved(editItem, \$event)"
+            (canceled)="onCanceled(editItem)"
+            [hidden]="!editItem.editing"
+            [hero]="editItem.item">
+          </hero-editor>
+        </li>
+      </ul>
+    </div>
+  ''',
+    directives: const [HeroCardComponent, HeroEditorComponent])
+class HeroesListComponent {
+  List<EditItem<Hero>> heroes;
+  HeroesListComponent(HeroesService heroesService) {
+    heroes = heroesService
+        .getHeroes()
+        .map((Hero item) => new EditItem(item))
+        .toList();
+  }
+
+  onSaved(EditItem<Hero> editItem, Hero updatedHero) {
+    editItem.item = updatedHero;
+    editItem.editing = false;
+  }
+
+  onCanceled(EditItem<Hero> editItem) {
+    editItem.editing = false;
+  }
+}
+// #enddocregion

public/docs/_examples/hierarchical-dependency-injection/dart/lib/heroes_service.dart

@@ -0,0 +1,18 @@
+import 'package:angular2/angular2.dart';
+import 'package:hierarchical_di/hero.dart';
+
+@Injectable()
+class HeroesService {
+  List<Hero> _heroes = [
+    new Hero()
+      ..name = "RubberMan"
+      ..power = 'Flexibility',
+    new Hero()
+      ..name = "Tornado"
+      ..power = 'Weather changer'
+  ];
+
+  List<Hero> getHeroes() {
+    return _heroes;
+  }
+}

public/docs/_examples/hierarchical-dependency-injection/dart/lib/restore_service.dart

@@ -0,0 +1,29 @@
+// #docregion
+import 'package:angular2/angular2.dart';
+
+@Injectable()
+class RestoreService<T> {
+  T _originalItem;
+  T _currentItem;
+
+  setItem(T item) {
+    print(item.runtimeType);
+    _originalItem = item;
+    _currentItem = clone(item);
+  }
+
+  T getItem() {
+    return _currentItem;
+  }
+
+  T restoreItem() {
+    _currentItem = _originalItem;
+    return getItem();
+  }
+
+  T clone(T item) {
+    // super poor clone implementation
+    return item.clone();
+  }
+}
+// #enddocregion

public/docs/_examples/hierarchical-dependency-injection/dart/pubspec.yaml

@@ -0,0 +1,19 @@
+# #docregion
+name: 'hierarchical_di'
+version: 0.0.1
+description: hierarchical dependency injection example
+
+environment:
+  sdk: '>=1.0.0 <2.0.0'
+
+dependencies:
+  angular2: '2.0.0-beta.1'
+  browser: ^0.10.0
+  dart_to_js_script_rewriter: '^0.1.0'
+
+transformers:
+- angular2:
+    platform_directives:
+    - 'package:angular2/common.dart#COMMON_DIRECTIVES'
+    entry_points: web/main.dart
+- dart_to_js_script_rewriter

public/docs/_examples/hierarchical-dependency-injection/dart/web/index.html

@@ -0,0 +1,19 @@
+<!DOCTYPE html>
+
+<html>
+<head>
+    <meta charset="utf-8">
+    <meta http-equiv="X-UA-Compatible" content="IE=edge">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Hierarchical Injector</title>
+    <script defer src="main.dart" type="application/dart"></script>
+    <script defer src="packages/browser/dart.js"></script>
+</head>
+
+<body>
+<!-- #docregion heroes-list -->
+  <heroes-list>loading...</heroes-list>
+<!-- #enddocregion heroes-list -->
+
+</body>
+</html>

public/docs/_examples/hierarchical-dependency-injection/dart/web/main.dart

@@ -0,0 +1,15 @@
+// #docregion
+import 'package:angular2/bootstrap.dart';
+import 'package:hierarchical_di/heroes_service.dart';
+import 'package:hierarchical_di/heroes_list_component.dart';
+
+void main() {
+  bootstrap(HeroesListComponent, [HeroesService]);
+}
+
+/* Documentation artifact below
+// #docregion bad-alternative
+// Don't do this!
+bootstrap(HeroesListComponent, [HeroesService, RestoreService])
+// #enddocregion bad-alternative
+*/