docs(Resolve): Document array or object option for resolve: property

docs(ng2.resolve): Document how ng2 component uses resolve data
feat(ng2.Resolve): implement ng2 provider-style injection.
feat(ng2.Resolve): Use root ng2 Injector for resolve system
feat(ng2.Resolve): Supply the current `Transition` as a Resolvable

Author: christopherthielen

src/ng2/interface.ts

@@ -1,7 +1,5 @@
 /** @module ng2 */ /** */
 import {StateDeclaration, _ViewDeclaration} from "../state/interface";
-import {ParamDeclaration} from "../params/interface";
-import {IInjectable} from "../common/common";
 import {Transition} from "../transition/transition";
 import {Type} from "@angular/core";
 
@@ -142,16 +140,11 @@ export interface Ng2StateDeclaration extends StateDeclaration, Ng2ViewDeclaratio
 
 export interface Ng2ViewDeclaration extends _ViewDeclaration {
   /**
-   * The class of the `Component` to use for this view.
+   * The `Component` class to use for this view.
    *
    * A property of [[Ng2StateDeclaration]] or [[Ng2ViewDeclaration]]:
    *
-   * The component class which will be used for this view.
-   *
-   * Resolve data can be provided to the component using Dependency Injection.  Currently, resolves must be injected
-   * into the component using `@Inject('key')`, where `key` is the name of the resolve.
-   *
-   * TODO: document ng2 shorthand, like ng1's shorthand: inside a "views:" block, a bare string `"foo"` is shorthand for `{ component: "foo" }`
+   * ### The component class which will be used for this view.
    *
    * @example
    * ```js
@@ -170,8 +163,9 @@ export interface Ng2ViewDeclaration extends _ViewDeclaration {
    *   }
    * }
    *
+   * // Named views shorthand:
+   * // Inside a "views:" block, a Component class (NavBar) is shorthand for { component: NavBar }
    * .state('contacts', {
-   *   // Inside a "views:" block, supplying only a Component class is shorthand for { component: NavBar }
    *   // use the <nav-bar></nav-bar> component for the view named 'header'
    *   // use the <contact-list></contact-list> component for the view named 'content'
    *   views: {
@@ -180,17 +174,62 @@ export interface Ng2ViewDeclaration extends _ViewDeclaration {
    *   }
    * }
    * ```
+   *
+   * ### Accessing Resolve Data
+   *
+   * The component can access the Transition's [[Ng2StateDeclaration.resolve]] data in one of two ways:
+   *
+   * 1) Using Dependency Injection in the component constructor
+   *
+   * (using Typescript)
+   * ```js
+   * class MyComponent {
+   *   constructor(@Inject("myResolveData") public resolveValueA, resolveValueB: public SomeClass) {
+   *   }
+   * }
+   * ```
+   *
+   * (using ES6/7/babel)
+   * ```js
+   * class MyComponent {
+   *   static get parameters() {
+   *     return [["myResolveData"], [MyResolveClass]];
+   *   }
+   *   constructor(resolveValueA, resolveValueB) {
+   *     this.resolveValueA = resolveValueA;
+   *     this.resolveValueB = resolveValueB;
+   *   }
+   * }
+   * ```
+   *
+   * See also: https://github.com/shuhei/babel-plugin-angular2-annotations
+   *
+   * 2) Using a component input
+   *
+   * Note: To bind a resolve to a component input, the resolves must `provide:` a string value
+   *
+   * ```js
+   * @Component() {
+   *   inputs: ['resolveValueA']
+   * }
+   * class MyComponent {
+   *   myResolveValueA;
+   *   @Input() resolveValueB;
+   *   @Input("resolveValueC") resolveValueC;
+   *
+   *   constructor() {
+   *   }
+   * }
+   * ```
    */
   component?: Type;
 
   /**
-   * @hidden
-   *
-   * An object which maps `resolve`s to [[component]] `bindings`.
+   * An object which maps `resolve` keys to [[component]] `bindings`.
    *
    * A property of [[Ng2StateDeclaration]] or [[Ng2ViewDeclaration]]:
    *
-   * When using a [[component]] declaration (`component: 'myComponent'`), each input binding for the component is supplied
+   * When using a [[component]] declaration (`component: MyComponent`), each input binding for the component is supplied
    * data from a resolve of the same name, by default.  You may supply data from a different resolve name by mapping it here.
    *
    * Each key in this object is the name of one of the component's input bindings.
@@ -226,10 +265,12 @@ export interface Ng2ViewDeclaration extends _ViewDeclaration {
    * ```
    *
    */
-  // bindings?: { [key: string]: string };
+  bindings?: { [key: string]: string };
 }
 
 /**
+ * @hidden
+ *
  * The shape of a controller for a view (and/or component), defining the controller callbacks.
  *
  * A view in UI-Router is comprised of either a `component` ([[Ng2ViewDeclaration.component]]) or a combination of a

src/ng2/providers.ts

@@ -46,7 +46,7 @@
  *
  * @preferred @module ng2
  */ /** */
-import {Provider, provide} from "@angular/core";
+import {Injector} from "@angular/core";
 import {UIRouter} from "../router";
 import {PathNode} from "../path/node";
 import {StateRegistry} from "../state/stateRegistry";
@@ -61,8 +61,10 @@ import {Ng2ViewDeclaration} from "./interface";
 import {UIRouterConfig} from "./uiRouterConfig";
 import {UIRouterGlobals} from "../globals";
 import {UIRouterLocation} from "./location";
+import {services} from "../common/coreservices";
 
-let uiRouterFactory = (routerConfig: UIRouterConfig, location: UIRouterLocation) => {
+let uiRouterFactory = (routerConfig: UIRouterConfig, location: UIRouterLocation, injector: Injector) => {
+  services.$injector.get = injector.get.bind(injector);
   let router = new UIRouter();
 
   location.init();
@@ -95,25 +97,33 @@ let uiRouterFactory = (routerConfig: UIRouterConfig, location: UIRouterLocation)
  * ]);
  * ```
  */
-export const UIROUTER_PROVIDERS: Provider[] = [
-  provide(UIRouter, { useFactory: uiRouterFactory, deps: [UIRouterConfig, UIRouterLocation] }),
 
-  provide(UIRouterLocation, { useClass: UIRouterLocation }),
+export const UIROUTER_PROVIDERS: ProviderLike[] = [
+  { provide: UIRouter, useFactory: uiRouterFactory, deps: [UIRouterConfig, UIRouterLocation, Injector] },
 
-  provide(StateService, { useFactory: (r: UIRouter) => { return r.stateService; }, deps: [UIRouter]}),
+  { provide: UIRouterLocation, useClass: UIRouterLocation },
 
-  provide(TransitionService, { useFactory: (r: UIRouter) => { return r.transitionService; }, deps: [UIRouter]}),
+  { provide: StateService, useFactory: (r: UIRouter) => { return r.stateService; }, deps: [UIRouter]},
 
-  provide(UrlMatcherFactory, { useFactory: (r: UIRouter) => { return r.urlMatcherFactory; }, deps: [UIRouter]}),
+  { provide: TransitionService, useFactory: (r: UIRouter) => { return r.transitionService; }, deps: [UIRouter]},
 
-  provide(UrlRouter, { useFactory: (r: UIRouter) => { return r.urlRouter; }, deps: [UIRouter]}),
+  { provide: UrlMatcherFactory, useFactory: (r: UIRouter) => { return r.urlMatcherFactory; }, deps: [UIRouter]},
 
-  provide(ViewService, { useFactory: (r: UIRouter) => { return r.viewService; }, deps: [UIRouter]}),
+  { provide: UrlRouter, useFactory: (r: UIRouter) => { return r.urlRouter; }, deps: [UIRouter]},
 
-  provide(StateRegistry, { useFactory: (r: UIRouter) => { return r.stateRegistry; }, deps: [UIRouter]}),
+  { provide: ViewService, useFactory: (r: UIRouter) => { return r.viewService; }, deps: [UIRouter]},
 
-  provide(UIRouterGlobals, { useFactory: (r: UIRouter) => { return r.globals; }, deps: [UIRouter]}),
+  { provide: StateRegistry, useFactory: (r: UIRouter) => { return r.stateRegistry; }, deps: [UIRouter]},
 
-  provide(UiView.PARENT_INJECT, { useFactory: (r: StateRegistry) => { return { fqn: null, context: r.root() } }, deps: [StateRegistry]} )
+  { provide: UIRouterGlobals, useFactory: (r: UIRouter) => { return r.globals; }, deps: [UIRouter]},
+
+  { provide: UiView.PARENT_INJECT, useFactory: (r: StateRegistry) => { return { fqn: null, context: r.root() } }, deps: [StateRegistry]}
 ];
 
+export interface ProviderLike {
+  provide: any,
+  useClass?: any,
+  useFactory?: Function,
+  deps?: any[]
+}
+

src/state/interface.ts

@@ -147,26 +147,53 @@ export interface StateDeclaration {
   $$state?: () => State;
 
   /**
-   * Resolve - a mechanism to fetch data, which participates in the transition lifecycle
+   * Resolve - a mechanism to asynchronously fetch data, while participating in the Transition lifecycle
    *
-   * An object which defines dynamic dependencies/data that can then be injected into this state (or its children)
-   * during a Transition.
+   * The `resolve:` property defines data (or other dependencies) to be fetched asynchronously when the state
+   * is being entered.  After the data is fetched, it can be used in views, transition hooks or other resolves
+   * that belong to this state or any nested states.
+   *
+   * ### As an array
+   *
+   * Each array element should either be a [[Resolvable]] or an Angular 2 style
+   * [provider literal](https://angular.io/docs/ts/latest/cookbook/dependency-injection.html#!#provide).
+   *
+   * Note:
+   * ```new Resolvable('token', (http) => http.get('/'), [ Http ])```
+   * is roughly  equivalent to this provider literal:
+   * ```{ provide: "token", useFactory: (http) => http.get('/'), deps: [ Http ] }```
+   *
+   * @example
+   * ```js
+   *
+   * import {Resolvable} from "ui-router-ng2"; // or "angular-ui-router"
+   * ...
+   *
+   * // ng2 example
+   * resolve: [
+   *   // If you inject `myStateDependency` into a component, you'll get "abc"
+   *   { provide: 'myStateDependency', useFactory: () => 'abc' },
+   *   new Resolvable('myFoos', (http, trans) => http.get(`/foos/${trans.params().fooId}`), [Http, Transition])
+   * ]
+   * ```
+   *
+   * ### As an object
    *
-   * Define a new dependency by adding a key/value to the `resolve` property of the [[StateDeclaration]].
    * - The key (string) is the name of the dependency.
    * - The value (function) is an injectable function which returns the dependency, or a promise for the dependency.
    *
    * @example
    * ```js
    *
+   * // ng1 example
    * resolve: {
    *   // If you inject `myStateDependency` into a controller, you'll get "abc"
    *   myStateDependency: function() {
    *     return "abc";
    *   },
-   *   myAsyncData: function($http) {
+   *   myAsyncData: function($http, $transition$) {
    *     // Return a promise (async) for the data
-   *     return $http.get("/api/v1/data");
+   *     return $http.get("/foos/" + $transition$.params().foo);
    *   }
    * }
    * ```
@@ -197,25 +224,33 @@ export interface StateDeclaration {
    * Since resolve functions are injected, a common pattern is to inject a custom service such as `UserService`
    * and delegate to a custom service method, such as `UserService.list()`;
    *
-   * A resolve function can inject some special values:
+   * #### Angular 1
+   *
+   * An Angular 1 resolve function can inject some special values:
    * - `$transition$`: The current [[Transition]] object; information and API about the current transition, such as
    *    "to" and "from" State Parameters and transition options.
    * - Other resolves: This resolve can depend on another resolve, either from the same state, or from any parent state.
    * - `$stateParams`: (deprecated) The parameters for the current state (Note: these parameter values are
    *
+   * #### Angular 2
+   *
+   * An Angular 2 resolve function can inject some special values:
+   * - `Transition`: The current [[Transition]] object; information and API about the current transition, such as
+   *    "to" and "from" State Parameters and transition options.
+   * - Other resolves: This resolve can depend on another resolve, either from the same state, or from any parent state.
+   *
    * @example
    * ```js
    *
-   * resolve: {
-   *   // Define a resolve 'allusers' which delegates to the UserService
-   *   allusers: function(UserService) {
-   *     return UserService.list(); // list() returns a promise (async) for all the users
-   *   },
+   * // Injecting a resolve into another resolve
+   * resolve: [
+   *   // Define a resolve 'allusers' which delegates to the UserService.list()
+   *   // which returns a promise (async) for all the users
+   *   { provide: 'allusers', useFactory: (UserService) => UserService.list(), deps: [UserService] },
+   *
    *   // Define a resolve 'user' which depends on the allusers resolve.
    *   // This resolve function is not called until 'allusers' is ready.
-   *   user: function(allusers, $transition$) {
-   *     return _.find(allusers, $transition$.params().userId);
-   *   }
+   *   { provide: 'user', (allusers, trans) => _.find(allusers, trans.params().userId, deps: ['allusers', Transition] }
    * }
    * ```
    */

src/state/stateBuilder.ts

@@ -131,14 +131,15 @@ function includesBuilder(state: State) {
 export function resolvablesBuilder(state: State): Resolvable[] {
   const obj2Array         = obj => Object.keys(obj || {}).map(token => ({token, val: obj[token], deps: undefined}));
   const annotate          = fn  => fn.$inject || services.$injector.annotate(fn, services.$injector.strictDi);
-  const isLikeNg2Provider = obj => obj.token && (obj.useValue || obj.useFactory || obj.useExisting || obj.useClass);
+  const isLikeNg2Provider = obj => !!((obj.provide || obj.token) && (obj.useValue || obj.useFactory || obj.useExisting || obj.useClass));
+  const provideToken = p => p.provide || p.token;
 
   /** Given a provider, returns a Resolvable */
   const provider2Resolvable = pattern([
-    [prop('useFactory'),  p => new Resolvable(p.token, p.useFactory, p.dependencies)],
-    [prop('useClass'),    p => new Resolvable(p.token, () => new (<any>p.useClass)(), [])],
-    [prop('useValue'),    p => new Resolvable(p.token, () => p.useValue, [], p.useValue)],
-    [prop('useExisting'), p => new Resolvable(p.token, (x) => x, [p.useExisting])],
+    [prop('useFactory'),  p => new Resolvable(provideToken(p), p.useFactory, (p.deps || p.dependencies))],
+    [prop('useClass'),    p => new Resolvable(provideToken(p), () => new (<any>p.useClass)(), [])],
+    [prop('useValue'),    p => new Resolvable(provideToken(p), () => p.useValue, [], p.useValue)],
+    [prop('useExisting'), p => new Resolvable(provideToken(p), (x) => x, [p.useExisting])],
   ]);
 
   const item2Resolvable = <(any) => Resolvable> pattern([

src/transition/transition.ts

@@ -154,6 +154,7 @@ export class Transition implements IHookRegistry {
     PathFactory.bindResolveContexts(this._treeChanges.to);
 
     let rootResolvables: Resolvable[] = [
+      new Resolvable(Transition, () => this, [], this),
       new Resolvable('$transition$', () => this, [], this),
       new Resolvable('$stateParams', () => this.params(), [], this.params())
     ];