feat(ScopeAware): introduce ScopeAware abstract class

Components that implement the ScopeAware scope setter, will get scope
set during compilation.

Currently, there is little incentive to use this, because Scope can be
injected in the Components. However, after PR/1269 Scope would not be
injectable and this would be the only way for components to obtain
scope.

Introducing this API earlier allows for clients to start using it and
not break when PR/1269 lands.

Closes #1360

lib/core/module.dart

@@ -76,6 +76,7 @@ export "package:angular/core/module_internal.dart" show
     PrototypeMap,
     RootScope,
     Scope,
+    ScopeAware,
     ScopeDigestTTL,
     ScopeEvent,
     ScopeStats,

lib/core/scope.dart

@@ -109,6 +109,36 @@ class ScopeLocals implements Map {
   dynamic putIfAbsent(key, fn) => _scope.putIfAbsent(key, fn);
 }
 
+/**
+ * When a [Component] or the root context class implements [ScopeAware] the scope setter will be
+ * called to set the [Scope] on this component.
+ *
+ * Typically classes implementing [ScopeAware] will declare a `Scope scope` property which will get
+ * initialized after the [Scope] is available. For this reason the `scope` property will not be
+ * initialized during the execution of the constructor - it will be immediately after.
+ *
+ * However, if you need to execute some code as soon as the scope is available you should implement
+ * a `scope` setter:
+ *
+ *     @Component(...)
+ *     class MyComponent implements ScopeAware {
+ *       Watch watch;
+ *
+ *       MyComponent(Dependency myDep) {
+ *         // It is an error to add a Scope / RootScope argument to the ctor and will result in a DI
+ *         // circular dependency error - the scope is never accessible in the class constructor
+ *       }
+ *
+ *       void set scope(Scope scope) {
+ *          // This setter gets called to initialize the scope
+ *          watch = scope.rootScope.watch("expression", (v, p) => ...);
+ *       }
+ *     }
+ */
+abstract class ScopeAware {
+  void set scope(Scope scope);
+}
+
 /**
  * [Scope] represents a collection of [watch]es [observer]s, and a [context] for the watchers,
  * observers and [eval]uations. Scopes structure loosely mimics the DOM structure. Scopes and

lib/core_dom/shadow_dom_component_factory.dart

@@ -187,6 +187,7 @@ class BoundShadowDomComponentFactory implements BoundComponentFactory {
         }
 
         var controller = shadowInjector.getByKey(_ref.typeKey);
+        if (controller is ScopeAware) controller.scope = shadowScope;
         BoundComponentFactory._setupOnShadowDomAttach(controller, templateLoader, shadowScope);
         shadowScope.context[_component.publishAs] = controller;
 

lib/core_dom/transcluding_component_factory.dart

@@ -122,6 +122,7 @@ class BoundTranscludingComponentFactory implements BoundComponentFactory {
 
       var controller = childInjector.getByKey(_ref.typeKey);
       shadowScope.context[_component.publishAs] = controller;
+      if (controller is ScopeAware) controller.scope = shadowScope;
       BoundComponentFactory._setupOnShadowDomAttach(controller, templateLoader, shadowScope);
 
       if (_viewFactoryFuture != null && _viewFactory == null) {

test/angular_spec.dart

@@ -151,6 +151,7 @@ main() {
         "angular.core_internal.Interpolate",
         "angular.core_internal.RootScope",
         "angular.core_internal.Scope",
+        "angular.core_internal.ScopeAware",
         "angular.core_internal.ScopeDigestTTL",
         "angular.core_internal.ScopeEvent",
         "angular.core_internal.ScopeStats",

test/core_dom/compiler_spec.dart

@@ -78,7 +78,8 @@ void main() {
           ..bind(MyChildController)
           ..bind(MyScopeModifyingController)
           ..bind(SameNameDecorator)
-          ..bind(SameNameTransclude);
+          ..bind(SameNameTransclude)
+          ..bind(ScopeAwareComponent);
     });
 
     beforeEach((TestBed tb) => _ = tb);
@@ -928,6 +929,14 @@ void main() {
 
         expect(element.text).toContain('my data');
       });
+
+      it('should call scope setter on ScopeAware components', async((TestBed _, Logger log) {
+        var element = _.compile('<scope-aware-cmp></scope-aware-cmp>');
+
+        _.rootScope.apply();
+
+        expect(log.result()).toEqual('Scope set');
+      }));
     });
 
 
@@ -1392,3 +1401,14 @@ class SameNameDecorator {
     scope.context['sameDecorator'] = this;
   }
 }
+
+@Component(
+    selector: 'scope-aware-cmp'
+)
+class ScopeAwareComponent implements ScopeAware {
+  Logger log;
+  ScopeAwareComponent(this.log) {}
+  void set scope(Scope scope) {
+    log('Scope set');
+  }
+}