diff --git a/angularjs/angular-component-router.d.ts b/angularjs/angular-component-router.d.ts new file mode 100644 index 0000000000..da93596ca0 --- /dev/null +++ b/angularjs/angular-component-router.d.ts @@ -0,0 +1,429 @@ +// Type definitions for Angular JS 1.5 component router +// Project: http://angularjs.org +// Definitions by: David Reher +// Definitions: https://github.com/borisyankov/DefinitelyTyped + +/// +/// + +declare module angular { + /** + * `Instruction` is a tree of {@link ComponentInstruction}s with all the information needed + * to transition each component in the app to a given route, including all auxiliary routes. + * + * `Instruction`s can be created using {@link Router#generate}, and can be used to + * perform route changes with {@link Router#navigateByInstruction}. + * + * ### Example + * + * ``` + * import {Component} from 'angular2/core'; + * import {bootstrap} from 'angular2/platform/browser'; + * import {Router, ROUTER_DIRECTIVES, ROUTER_PROVIDERS, RouteConfig} from 'angular2/router'; + * + * @Component({directives: [ROUTER_DIRECTIVES]}) + * @RouteConfig([ + * {...}, + * ]) + * class AppCmp { + * constructor(router: Router) { + * var instruction = router.generate(['/MyRoute']); + * router.navigateByInstruction(instruction); + * } + * } + * + * bootstrap(AppCmp, ROUTER_PROVIDERS); + * ``` + */ + interface Instruction { + + urlPath(): string; + + urlParams(): string[]; + + specificity(): number; + + resolveComponent(): Promise; + + /** + * converts the instruction into a URL string + */ + toRootUrl(): string; + + toUrlQuery(): string; + + /** + * Returns a new instruction that shares the state of the existing instruction, but with + * the given child {@link Instruction} replacing the existing child. + */ + replaceChild(child: Instruction): Instruction; + + /** + * If the final URL for the instruction is `` + */ + toUrlPath(): string; + + /** + * default instructions override these + */ + toLinkUrl(): string; + } + + /** + * A router outlet is a placeholder that Angular dynamically fills based on the application's route. + * + * ## Use + * + * ``` + * + * ``` + */ + interface RouterOutlet { + name: string; + + /** + * Called by the Router to instantiate a new component during the commit phase of a navigation. + * This method in turn is responsible for calling the `routerOnActivate` hook of its child. + */ + activate(nextInstruction: ComponentInstruction): Promise; + + /** + * Called by the {@link Router} during the commit phase of a navigation when an outlet + * reuses a component between different routes. + * This method in turn is responsible for calling the `routerOnReuse` hook of its child. + */ + reuse(nextInstruction: ComponentInstruction): Promise; + + /** + * Called by the {@link Router} when an outlet disposes of a component's contents. + * This method in turn is responsible for calling the `routerOnDeactivate` hook of its child. + */ + deactivate(nextInstruction: ComponentInstruction): Promise; + + /** + * Called by the {@link Router} during recognition phase of a navigation. + * + * If this resolves to `false`, the given navigation is cancelled. + * + * This method delegates to the child component's `routerCanDeactivate` hook if it exists, + * and otherwise resolves to true. + */ + routerCanDeactivate(nextInstruction: ComponentInstruction): Promise; + + /** + * Called by the {@link Router} during recognition phase of a navigation. + * + * If the new child component has a different Type than the existing child component, + * this will resolve to `false`. You can't reuse an old component when the new component + * is of a different Type. + * + * Otherwise, this method delegates to the child component's `routerCanReuse` hook if it exists, + * or resolves to true if the hook is not present. + */ + routerCanReuse(nextInstruction: ComponentInstruction): Promise; + } + + interface RouteRegistry { + /** + * Given a component and a configuration object, add the route to this registry + */ + config(parentComponent: any, config: RouteDefinition): void; + + /** + * Reads the annotations of a component and configures the registry based on them + */ + configFromComponent(component: any): void; + + /** + * Given a URL and a parent component, return the most specific instruction for navigating + * the application into the state specified by the url + */ + recognize(url: string, ancestorInstructions: Instruction[]): Promise; + + /** + * Given a normalized list with component names and params like: `['user', {id: 3 }]` + * generates a url with a leading slash relative to the provided `parentComponent`. + * + * If the optional param `_aux` is `true`, then we generate starting at an auxiliary + * route boundary. + */ + generate(linkParams: any[], ancestorInstructions: Instruction[], _aux?: boolean): Instruction; + + hasRoute(name: string, parentComponent: any): boolean; + + generateDefault(componentCursor: any): Instruction; + } + + /** + * The `Router` is responsible for mapping URLs to components. + * + * You can see the state of the router by inspecting the read-only field `router.navigating`. + * This may be useful for showing a spinner, for instance. + * + * ## Concepts + * + * Routers and component instances have a 1:1 correspondence. + * + * The router holds reference to a number of {@link RouterOutlet}. + * An outlet is a placeholder that the router dynamically fills in depending on the current URL. + * + * When the router navigates from a URL, it must first recognize it and serialize it into an + * `Instruction`. + * The router uses the `RouteRegistry` to get an `Instruction`. + */ + interface Router { + navigating: boolean; + lastNavigationAttempt: string; + registry: RouteRegistry; + parent: Router; + hostComponent: any; + + /** + * Constructs a child router. You probably don't need to use this unless you're writing a reusable + * component. + */ + childRouter(hostComponent: any): Router; + + /** + * Constructs a child router. You probably don't need to use this unless you're writing a reusable + * component. + */ + auxRouter(hostComponent: any): Router; + + /** + * Register an outlet to be notified of primary route changes. + * + * You probably don't need to use this unless you're writing a reusable component. + */ + registerPrimaryOutlet(outlet: RouterOutlet): Promise; + + /** + * Register an outlet to notified of auxiliary route changes. + * + * You probably don't need to use this unless you're writing a reusable component. + */ + registerAuxOutlet(outlet: RouterOutlet): Promise; + + /** + * Given an instruction, returns `true` if the instruction is currently active, + * otherwise `false`. + */ + isRouteActive(instruction: Instruction): boolean; + + /** + * Dynamically update the routing configuration and trigger a navigation. + * + * ### Usage + * + * ``` + * router.config([ + * { 'path': '/', 'component': IndexComp }, + * { 'path': '/user/:id', 'component': UserComp }, + * ]); + * ``` + */ + config(definitions: RouteDefinition[]): Promise; + + /** + * Navigate based on the provided Route Link DSL. It's preferred to navigate with this method + * over `navigateByUrl`. + * + * ### Usage + * + * This method takes an array representing the Route Link DSL: + * ``` + * ['./MyCmp', {param: 3}] + * ``` + * See the {@link RouterLink} directive for more. + */ + navigate(linkParams: any[]): Promise; + + /** + * Navigate to a URL. Returns a promise that resolves when navigation is complete. + * It's preferred to navigate with `navigate` instead of this method, since URLs are more brittle. + * + * If the given URL begins with a `/`, router will navigate absolutely. + * If the given URL does not begin with `/`, the router will navigate relative to this component. + */ + navigateByUrl(url: string, _skipLocationChange?: boolean): Promise; + + /** + * Navigate via the provided instruction. Returns a promise that resolves when navigation is + * complete. + */ + navigateByInstruction(instruction: Instruction, + _skipLocationChange?: boolean): Promise; + + /** + * Updates this router and all descendant routers according to the given instruction + */ + commit(instruction: Instruction, _skipLocationChange?: boolean): Promise; + + /** + * Subscribe to URL updates from the router + */ + subscribe(onNext: (value: any) => void): Object; + + /** + * Removes the contents of this router's outlet and all descendant outlets + */ + deactivate(instruction: Instruction): Promise; + + /** + * Given a URL, returns an instruction representing the component graph + */ + recognize(url: string): Promise; + + /** + * Navigates to either the last URL successfully navigated to, or the last URL requested if the + * router has yet to successfully navigate. + */ + renavigate(): Promise; + + /** + * Generate an `Instruction` based on the provided Route Link DSL. + */ + generate(linkParams: any[]): Instruction; + } + + /** + * RouteData is an immutable map of additional data you can configure in your Route. + * You can inject RouteData into the constructor of a component to use it. + */ + interface RouteData { + data: {[key: string]: any}; + get(key: string): any; + } + + /** + * A `ComponentInstruction` represents the route state for a single component. An `Instruction` is + * composed of a tree of these `ComponentInstruction`s. + * + * `ComponentInstructions` is a public API. Instances of `ComponentInstruction` are passed + * to route lifecycle hooks, like {@link CanActivate}. + * + * `ComponentInstruction`s are [https://en.wikipedia.org/wiki/Hash_consing](hash consed). You should + * never construct one yourself with "new." Instead, rely on {@link Router/RouteRecognizer} to + * construct `ComponentInstruction`s. + * + * You should not modify this object. It should be treated as immutable. + */ + interface ComponentInstruction { + reuse: boolean; + routeData: RouteData; + urlPath: string; + urlParams: string[]; + data: RouteData; + componentType: any; + terminal: boolean; + specificity: number; + params: {[key: string]: any}; + } + + /** + * Defines route lifecycle method `routerOnActivate`, which is called by the router at the end of a + * successful route navigation. + * + * For a single component's navigation, only one of either {@link OnActivate} or {@link OnReuse} + * will be called depending on the result of {@link CanReuse}. + * + * The `routerOnActivate` hook is called with two {@link ComponentInstruction}s as parameters, the + * first + * representing the current route being navigated to, and the second parameter representing the + * previous route or `null`. + * + * If `routerOnActivate` returns a promise, the route change will wait until the promise settles to + * instantiate and activate child components. + * + * ### Example + * {@example router/ts/on_activate/on_activate_example.ts region='routerOnActivate'} + */ + interface OnActivate { + $routerOnActivate(next?: angular.ComponentInstruction, prev?: angular.ComponentInstruction): any; + } + + /** + * Defines route lifecycle method `routerCanDeactivate`, which is called by the router to determine + * if a component can be removed as part of a navigation. + * + * The `routerCanDeactivate` hook is called with two {@link ComponentInstruction}s as parameters, + * the + * first representing the current route being navigated to, and the second parameter + * representing the previous route. + * + * If `routerCanDeactivate` returns or resolves to `false`, the navigation is cancelled. If it + * returns or + * resolves to `true`, then the navigation continues, and the component will be deactivated + * (the {@link OnDeactivate} hook will be run) and removed. + * + * If `routerCanDeactivate` throws or rejects, the navigation is also cancelled. + * + * ### Example + * {@example router/ts/can_deactivate/can_deactivate_example.ts region='routerCanDeactivate'} + */ + interface CanDeactivate { + $routerCanDeactivate(next?: ComponentInstruction, prev?: ComponentInstruction): boolean | Promise; + } + + /** + * Defines route lifecycle method `routerOnDeactivate`, which is called by the router before + * destroying + * a component as part of a route change. + * + * The `routerOnDeactivate` hook is called with two {@link ComponentInstruction}s as parameters, the + * first + * representing the current route being navigated to, and the second parameter representing the + * previous route. + * + * If `routerOnDeactivate` returns a promise, the route change will wait until the promise settles. + * + * ### Example + * {@example router/ts/on_deactivate/on_deactivate_example.ts region='routerOnDeactivate'} + */ + interface OnDeactivate { + $routerOnDeactivate(next?: angular.ComponentInstruction, prev?: angular.ComponentInstruction): any; + } + + /** + * Defines route lifecycle method `routerCanReuse`, which is called by the router to determine + * whether a + * component should be reused across routes, or whether to destroy and instantiate a new component. + * + * The `routerCanReuse` hook is called with two {@link ComponentInstruction}s as parameters, the + * first + * representing the current route being navigated to, and the second parameter representing the + * previous route. + * + * If `routerCanReuse` returns or resolves to `true`, the component instance will be reused and the + * {@link OnDeactivate} hook will be run. If `routerCanReuse` returns or resolves to `false`, a new + * component will be instantiated, and the existing component will be deactivated and removed as + * part of the navigation. + * + * If `routerCanReuse` throws or rejects, the navigation will be cancelled. + * + * ### Example + * {@example router/ts/reuse/reuse_example.ts region='reuseCmp'} + */ + interface CanReuse { + $routerCanReuse(next?: angular.ComponentInstruction, prev?: angular.ComponentInstruction): boolean | Promise; + } + + /** + * Defines route lifecycle method `routerOnReuse`, which is called by the router at the end of a + * successful route navigation when {@link CanReuse} is implemented and returns or resolves to true. + * + * For a single component's navigation, only one of either {@link OnActivate} or {@link OnReuse} + * will be called, depending on the result of {@link CanReuse}. + * + * The `routerOnReuse` hook is called with two {@link ComponentInstruction}s as parameters, the + * first + * representing the current route being navigated to, and the second parameter representing the + * previous route or `null`. + * + * ### Example + * {@example router/ts/reuse/reuse_example.ts region='reuseCmp'} + */ + interface OnReuse { + $routerOnReuse(next?: angular.ComponentInstruction, prev?: angular.ComponentInstruction): any; + } +} diff --git a/angularjs/angular.d.ts b/angularjs/angular.d.ts index 97477e9a81..14ccdbf043 100644 --- a/angularjs/angular.d.ts +++ b/angularjs/angular.d.ts @@ -1632,18 +1632,99 @@ declare module angular { // see http://angularjs.blogspot.com.br/2015/11/angularjs-15-beta2-and-14-releases.html // and http://toddmotto.com/exploring-the-angular-1-5-component-method/ /////////////////////////////////////////////////////////////////////////// + /** + * Runtime representation a type that a Component or other object is instances of. + * + * An example of a `Type` is `MyCustomComponent` class, which in JavaScript is be represented by + * the `MyCustomComponent` constructor function. + */ + interface Type extends Function { + } + /** + * `RouteDefinition` defines a route within a {@link RouteConfig} decorator. + * + * Supported keys: + * - `path` or `aux` (requires exactly one of these) + * - `component`, `loader`, `redirectTo` (requires exactly one of these) + * - `name` or `as` (optional) (requires exactly one of these) + * - `data` (optional) + * + * See also {@link Route}, {@link AsyncRoute}, {@link AuxRoute}, and {@link Redirect}. + */ + interface RouteDefinition { + path?: string; + aux?: string; + component?: Type | ComponentDefinition | string; + loader?: Function; + redirectTo?: any[]; + as?: string; + name?: string; + data?: any; + useAsDefault?: boolean; + } + + /** + * Represents either a component type (`type` is `component`) or a loader function + * (`type` is `loader`). + * + * See also {@link RouteDefinition}. + */ + interface ComponentDefinition { + type: string; + loader?: Function; + component?: Type; + } + + /** + * Component definition object (a simplified directive definition object) + */ interface IComponentOptions { - bindings?: Object; + /** + * Controller constructor function that should be associated with newly created scope or the name of a registered + * controller if passed as a string. Empty function by default. + */ controller?: string | Function; + /** + * An identifier name for a reference to the controller. If present, the controller will be published to scope under + * the controllerAs name. If not present, this will default to be the same as the component name. + */ controllerAs?: string; - isolate?: boolean; - template?: string | IComponentTemplateFn; - templateUrl?: string | IComponentTemplateFn; + /** + * html template as a string or a function that returns an html template as a string which should be used as the + * contents of this component. Empty string by default. + * If template is a function, then it is injected with the following locals: + * $element - Current element + * $attrs - Current attributes object for the element + */ + template?: string | Function; + /** + * path or function that returns a path to an html template that should be used as the contents of this component. + * If templateUrl is a function, then it is injected with the following locals: + * $element - Current element + * $attrs - Current attributes object for the element + */ + templateUrl?: string | Function; + /** + * Define DOM attribute binding to component properties. Component properties are always bound to the component + * controller and not to the scope. + */ + bindings?: any; + /** + * Whether transclusion is enabled. Enabled by default. + */ transclude?: boolean; + /** + * Whether the new scope is isolated. Isolated by default. + */ + isolate?: boolean; + /** + * String of subset of EACM which restricts the component to specific directive declaration style. If omitted, + * this defaults to 'E'. + */ restrict?: string; - $canActivate?: Function; - $routeConfig?: Object; + $canActivate?: () => boolean; + $routeConfig?: RouteDefinition[]; } interface IComponentTemplateFn {