@angular-wave/angular.ts 0.0.16 → 0.0.17

package/types/router/core/state/stateService.d.ts

@@ -0,0 +1,350 @@
+import { HookResult, TransitionOptions } from '../transition/interface';
+import { Transition } from '../transition/transition';
+import { HrefOptions, LazyLoadResult, StateDeclaration, StateOrName, TransitionPromise } from './interface';
+import { StateObject } from './stateObject';
+import { TargetState } from './targetState';
+import { RawParams } from '../params/interface';
+import { UIRouter } from '../router';
+import { UIInjector } from '../interface';
+import { StateParams } from '../params/stateParams';
+export declare type OnInvalidCallback = (toState?: TargetState, fromState?: TargetState, injector?: UIInjector) => HookResult;
+/**
+ * Provides services related to ui-router states.
+ *
+ * This API is located at `router.stateService` ([[UIRouter.stateService]])
+ */
+export declare class StateService {
+    private router;
+    /** @internal */
+    invalidCallbacks: OnInvalidCallback[];
+    /**
+     * The [[Transition]] currently in progress (or null)
+     *
+     * @deprecated This is a passthrough through to [[UIRouterGlobals.transition]]
+     */
+    transition: Transition;
+    /**
+     * The latest successful state parameters
+     *
+     * @deprecated This is a passthrough through to [[UIRouterGlobals.params]]
+     */
+    params: StateParams;
+    /**
+     * The current [[StateDeclaration]]
+     *
+     * @deprecated This is a passthrough through to [[UIRouterGlobals.current]]
+     */
+    current: StateDeclaration;
+    /**
+     * The current [[StateObject]] (an internal API)
+     *
+     * @deprecated This is a passthrough through to [[UIRouterGlobals.$current]]
+     */
+    $current: StateObject;
+    /** @internal */
+    constructor(/** @internal */ router: UIRouter);
+    /** @internal */
+    dispose(): void;
+    /**
+     * Handler for when [[transitionTo]] is called with an invalid state.
+     *
+     * Invokes the [[onInvalid]] callbacks, in natural order.
+     * Each callback's return value is checked in sequence until one of them returns an instance of TargetState.
+     * The results of the callbacks are wrapped in $q.when(), so the callbacks may return promises.
+     *
+     * If a callback returns an TargetState, then it is used as arguments to $state.transitionTo() and the result returned.
+     *
+     * @internal
+     */
+    private _handleInvalidTargetState;
+    /**
+     * Registers an Invalid State handler
+     *
+     * Registers a [[OnInvalidCallback]] function to be invoked when [[StateService.transitionTo]]
+     * has been called with an invalid state reference parameter
+     *
+     * Example:
+     * ```js
+     * stateService.onInvalid(function(to, from, injector) {
+     *   if (to.name() === 'foo') {
+     *     let lazyLoader = injector.get('LazyLoadService');
+     *     return lazyLoader.load('foo')
+     *         .then(() => stateService.target('foo'));
+     *   }
+     * });
+     * ```
+     *
+     * @param {function} callback invoked when the toState is invalid
+     *   This function receives the (invalid) toState, the fromState, and an injector.
+     *   The function may optionally return a [[TargetState]] or a Promise for a TargetState.
+     *   If one is returned, it is treated as a redirect.
+     *
+     * @returns a function which deregisters the callback
+     */
+    onInvalid(callback: OnInvalidCallback): Function;
+    /**
+     * Reloads the current state
+     *
+     * A method that force reloads the current state, or a partial state hierarchy.
+     * All resolves are re-resolved, and components reinstantiated.
+     *
+     * #### Example:
+     * ```js
+     * let app angular.module('app', ['ui.router']);
+     *
+     * app.controller('ctrl', function ($scope, $state) {
+     *   $scope.reload = function(){
+     *     $state.reload();
+     *   }
+     * });
+     * ```
+     *
+     * Note: `reload()` is just an alias for:
+     *
+     * ```js
+     * $state.transitionTo($state.current, $state.params, {
+     *   reload: true, inherit: false
+     * });
+     * ```
+     *
+     * @param reloadState A state name or a state object.
+     *    If present, this state and all its children will be reloaded, but ancestors will not reload.
+     *
+     * #### Example:
+     * ```js
+     * //assuming app application consists of 3 states: 'contacts', 'contacts.detail', 'contacts.detail.item'
+     * //and current state is 'contacts.detail.item'
+     * let app angular.module('app', ['ui.router']);
+     *
+     * app.controller('ctrl', function ($scope, $state) {
+     *   $scope.reload = function(){
+     *     //will reload 'contact.detail' and nested 'contact.detail.item' states
+     *     $state.reload('contact.detail');
+     *   }
+     * });
+     * ```
+     *
+     * @returns A promise representing the state of the new transition. See [[StateService.go]]
+     */
+    reload(reloadState?: StateOrName): Promise<StateObject>;
+    /**
+     * Transition to a different state and/or parameters
+     *
+     * Convenience method for transitioning to a new state.
+     *
+     * `$state.go` calls `$state.transitionTo` internally but automatically sets options to
+     * `{ location: true, inherit: true, relative: router.globals.$current, notify: true }`.
+     * This allows you to use either an absolute or relative `to` argument (because of `relative: router.globals.$current`).
+     * It also allows you to specify * only the parameters you'd like to update, while letting unspecified parameters
+     * inherit from the current parameter values (because of `inherit: true`).
+     *
+     * #### Example:
+     * ```js
+     * let app = angular.module('app', ['ui.router']);
+     *
+     * app.controller('ctrl', function ($scope, $state) {
+     *   $scope.changeState = function () {
+     *     $state.go('contact.detail');
+     *   };
+     * });
+     * ```
+     *
+     * @param to Absolute state name, state object, or relative state path (relative to current state).
+     *
+     * Some examples:
+     *
+     * - `$state.go('contact.detail')` - will go to the `contact.detail` state
+     * - `$state.go('^')` - will go to the parent state
+     * - `$state.go('^.sibling')` - if current state is `home.child`, will go to the `home.sibling` state
+     * - `$state.go('.child.grandchild')` - if current state is home, will go to the `home.child.grandchild` state
+     *
+     * @param params A map of the parameters that will be sent to the state, will populate $stateParams.
+     *
+     *    Any parameters that are not specified will be inherited from current parameter values (because of `inherit: true`).
+     *    This allows, for example, going to a sibling state that shares parameters defined by a parent state.
+     *
+     * @param options Transition options
+     *
+     * @returns {promise} A promise representing the state of the new transition.
+     */
+    go(to: StateOrName, params?: RawParams, options?: TransitionOptions): TransitionPromise;
+    /**
+     * Creates a [[TargetState]]
+     *
+     * This is a factory method for creating a TargetState
+     *
+     * This may be returned from a Transition Hook to redirect a transition, for example.
+     */
+    target(identifier: StateOrName, params?: RawParams, options?: TransitionOptions): TargetState;
+    /** @internal */
+    private getCurrentPath;
+    /**
+     * Low-level method for transitioning to a new state.
+     *
+     * The [[go]] method (which uses `transitionTo` internally) is recommended in most situations.
+     *
+     * #### Example:
+     * ```js
+     * let app = angular.module('app', ['ui.router']);
+     *
+     * app.controller('ctrl', function ($scope, $state) {
+     *   $scope.changeState = function () {
+     *     $state.transitionTo('contact.detail');
+     *   };
+     * });
+     * ```
+     *
+     * @param to State name or state object.
+     * @param toParams A map of the parameters that will be sent to the state,
+     *      will populate $stateParams.
+     * @param options Transition options
+     *
+     * @returns A promise representing the state of the new transition. See [[go]]
+     */
+    transitionTo(to: StateOrName, toParams?: RawParams, options?: TransitionOptions): TransitionPromise;
+    /**
+     * Checks if the current state *is* the provided state
+     *
+     * Similar to [[includes]] but only checks for the full state name.
+     * If params is supplied then it will be tested for strict equality against the current
+     * active params object, so all params must match with none missing and no extras.
+     *
+     * #### Example:
+     * ```js
+     * $state.$current.name = 'contacts.details.item';
+     *
+     * // absolute name
+     * $state.is('contact.details.item'); // returns true
+     * $state.is(contactDetailItemStateObject); // returns true
+     * ```
+     *
+     * // relative name (. and ^), typically from a template
+     * // E.g. from the 'contacts.details' template
+     * ```html
+     * <div ng-class="{highlighted: $state.is('.item')}">Item</div>
+     * ```
+     *
+     * @param stateOrName The state name (absolute or relative) or state object you'd like to check.
+     * @param params A param object, e.g. `{sectionId: section.id}`, that you'd like
+     * to test against the current active state.
+     * @param options An options object. The options are:
+     *   - `relative`: If `stateOrName` is a relative state name and `options.relative` is set, .is will
+     *     test relative to `options.relative` state (or name).
+     *
+     * @returns Returns true if it is the state.
+     */
+    is(stateOrName: StateOrName, params?: RawParams, options?: {
+        relative?: StateOrName;
+    }): boolean;
+    /**
+     * Checks if the current state *includes* the provided state
+     *
+     * A method to determine if the current active state is equal to or is the child of the
+     * state stateName. If any params are passed then they will be tested for a match as well.
+     * Not all the parameters need to be passed, just the ones you'd like to test for equality.
+     *
+     * #### Example when `$state.$current.name === 'contacts.details.item'`
+     * ```js
+     * // Using partial names
+     * $state.includes("contacts"); // returns true
+     * $state.includes("contacts.details"); // returns true
+     * $state.includes("contacts.details.item"); // returns true
+     * $state.includes("contacts.list"); // returns false
+     * $state.includes("about"); // returns false
+     * ```
+     *
+     * #### Glob Examples when `* $state.$current.name === 'contacts.details.item.url'`:
+     * ```js
+     * $state.includes("*.details.*.*"); // returns true
+     * $state.includes("*.details.**"); // returns true
+     * $state.includes("**.item.**"); // returns true
+     * $state.includes("*.details.item.url"); // returns true
+     * $state.includes("*.details.*.url"); // returns true
+     * $state.includes("*.details.*"); // returns false
+     * $state.includes("item.**"); // returns false
+     * ```
+     *
+     * @param stateOrName A partial name, relative name, glob pattern,
+     *   or state object to be searched for within the current state name.
+     * @param params A param object, e.g. `{sectionId: section.id}`,
+     *   that you'd like to test against the current active state.
+     * @param options An options object. The options are:
+     *   - `relative`: If `stateOrName` is a relative state name and `options.relative` is set, .is will
+     *     test relative to `options.relative` state (or name).
+     *
+     * @returns {boolean} Returns true if it does include the state
+     */
+    includes(stateOrName: StateOrName, params?: RawParams, options?: TransitionOptions): boolean;
+    /**
+     * Generates a URL for a state and parameters
+     *
+     * Returns the url for the given state populated with the given params.
+     *
+     * #### Example:
+     * ```js
+     * expect($state.href("about.person", { person: "bob" })).toEqual("/about/bob");
+     * ```
+     *
+     * @param stateOrName The state name or state object you'd like to generate a url from.
+     * @param params An object of parameter values to fill the state's required parameters.
+     * @param options Options object. The options are:
+     *
+     * @returns {string} compiled state url
+     */
+    href(stateOrName: StateOrName, params?: RawParams, options?: HrefOptions): string;
+    /** @internal */
+    private _defaultErrorHandler;
+    /**
+     * Sets or gets the default [[transitionTo]] error handler.
+     *
+     * The error handler is called when a [[Transition]] is rejected or when any error occurred during the Transition.
+     * This includes errors caused by resolves and transition hooks.
+     *
+     * Note:
+     * This handler does not receive certain Transition rejections.
+     * Redirected and Ignored Transitions are not considered to be errors by [[StateService.transitionTo]].
+     *
+     * The built-in default error handler logs the error to the console.
+     *
+     * You can provide your own custom handler.
+     *
+     * #### Example:
+     * ```js
+     * stateService.defaultErrorHandler(function() {
+     *   // Do not log transitionTo errors
+     * });
+     * ```
+     *
+     * @param handler a global error handler function
+     * @returns the current global error handler
+     */
+    defaultErrorHandler(handler?: (error: any) => void): (error: any) => void;
+    /**
+     * Gets a registered [[StateDeclaration]] object
+     *
+     * Returns the state declaration object for any specific state, or for all registered states.
+     *
+     * @param stateOrName (absolute or relative) If provided, will only get the declaration object for the requested state.
+     * If not provided, returns an array of ALL states.
+     * @param base When `stateOrName` is a relative state reference (such as `.bar.baz`), the state will be retrieved relative to this state.
+     *
+     * @returns a [[StateDeclaration]] object (or array of all registered [[StateDeclaration]] objects.)
+     * @deprecated use [[StateRegistry.get]]
+     */
+    get(stateOrName: StateOrName, base: StateOrName): StateDeclaration;
+    get(stateOrName: StateOrName): StateDeclaration;
+    get(): StateDeclaration[];
+    /**
+     * Lazy loads a state
+     *
+     * Explicitly runs a state's [[StateDeclaration.lazyLoad]] function.
+     *
+     * @param stateOrName the state that should be lazy loaded
+     * @param transition the optional Transition context to use (if the lazyLoad function requires an injector, etc)
+     * Note: If no transition is provided, a noop transition is created using the from the current state to the current state.
+     * This noop transition is not actually run.
+     *
+     * @returns a promise to lazy load
+     */
+    lazyLoad(stateOrName: StateOrName, transition?: Transition): Promise<LazyLoadResult>;
+}

package/types/router/core/state/targetState.d.ts

@@ -0,0 +1,100 @@
+import { StateDeclaration, StateOrName, TargetStateDef } from './interface';
+import { TransitionOptions } from '../transition/interface';
+import { StateObject } from './stateObject';
+import { StateRegistry } from './stateRegistry';
+import { RawParams } from '../params';
+/**
+ * Encapsulate the target (destination) state/params/options of a [[Transition]].
+ *
+ * This class is frequently used to redirect a transition to a new destination.
+ *
+ * See:
+ *
+ * - [[HookResult]]
+ * - [[TransitionHookFn]]
+ * - [[TransitionService.onStart]]
+ *
+ * To create a `TargetState`, use [[StateService.target]].
+ *
+ * ---
+ *
+ * This class wraps:
+ *
+ * 1) an identifier for a state
+ * 2) a set of parameters
+ * 3) and transition options
+ * 4) the registered state object (the [[StateDeclaration]])
+ *
+ * Many UI-Router APIs such as [[StateService.go]] take a [[StateOrName]] argument which can
+ * either be a *state object* (a [[StateDeclaration]] or [[StateObject]]) or a *state name* (a string).
+ * The `TargetState` class normalizes those options.
+ *
+ * A `TargetState` may be valid (the state being targeted exists in the registry)
+ * or invalid (the state being targeted is not registered).
+ */
+export declare class TargetState {
+    private _stateRegistry;
+    private _identifier;
+    private _definition;
+    private _params;
+    private _options;
+    /** Returns true if the object has a state property that might be a state or state name */
+    static isDef: (obj: any) => obj is TargetStateDef;
+    /**
+     * The TargetState constructor
+     *
+     * Note: Do not construct a `TargetState` manually.
+     * To create a `TargetState`, use the [[StateService.target]] factory method.
+     *
+     * @param _stateRegistry The StateRegistry to use to look up the _definition
+     * @param _identifier An identifier for a state.
+     *    Either a fully-qualified state name, or the object used to define the state.
+     * @param _params Parameters for the target state
+     * @param _options Transition options.
+     *
+     * @internal
+     */
+    constructor(_stateRegistry: StateRegistry, _identifier: StateOrName, _params?: RawParams, _options?: TransitionOptions);
+    /** The name of the state this object targets */
+    name(): string;
+    /** The identifier used when creating this TargetState */
+    identifier(): StateOrName;
+    /** The target parameter values */
+    params(): RawParams;
+    /** The internal state object (if it was found) */
+    $state(): StateObject;
+    /** The internal state declaration (if it was found) */
+    state(): StateDeclaration;
+    /** The target options */
+    options(): TransitionOptions;
+    /** True if the target state was found */
+    exists(): boolean;
+    /** True if the object is valid */
+    valid(): boolean;
+    /** If the object is invalid, returns the reason why */
+    error(): string;
+    toString(): string;
+    /**
+     * Returns a copy of this TargetState which targets a different state.
+     * The new TargetState has the same parameter values and transition options.
+     *
+     * @param state The new state that should be targeted
+     */
+    withState(state: StateOrName): TargetState;
+    /**
+     * Returns a copy of this TargetState, using the specified parameter values.
+     *
+     * @param params the new parameter values to use
+     * @param replace When false (default) the new parameter values will be merged with the current values.
+     *                When true the parameter values will be used instead of the current values.
+     */
+    withParams(params: RawParams, replace?: boolean): TargetState;
+    /**
+     * Returns a copy of this TargetState, using the specified Transition Options.
+     *
+     * @param options the new options to use
+     * @param replace When false (default) the new options will be merged with the current options.
+     *                When true the options will be used instead of the current options.
+     */
+    withOptions(options: TransitionOptions, replace?: boolean): TargetState;
+}

package/types/router/core/transition/hookBuilder.d.ts

@@ -0,0 +1,45 @@
+import { TreeChanges, TransitionHookPhase } from './interface';
+import { Transition } from './transition';
+import { TransitionHook } from './transitionHook';
+import { TransitionEventType } from './transitionEventType';
+import { RegisteredHook } from './hookRegistry';
+/**
+ * This class returns applicable TransitionHooks for a specific Transition instance.
+ *
+ * Hooks ([[RegisteredHook]]) may be registered globally, e.g., $transitions.onEnter(...), or locally, e.g.
+ * myTransition.onEnter(...).  The HookBuilder finds matching RegisteredHooks (where the match criteria is
+ * determined by the type of hook)
+ *
+ * The HookBuilder also converts RegisteredHooks objects to TransitionHook objects, which are used to run a Transition.
+ *
+ * The HookBuilder constructor is given the $transitions service and a Transition instance.  Thus, a HookBuilder
+ * instance may only be used for one specific Transition object. (side note: the _treeChanges accessor is private
+ * in the Transition class, so we must also provide the Transition's _treeChanges)
+ */
+export declare class HookBuilder {
+    private transition;
+    constructor(transition: Transition);
+    buildHooksForPhase(phase: TransitionHookPhase): TransitionHook[];
+    /**
+     * Returns an array of newly built TransitionHook objects.
+     *
+     * - Finds all RegisteredHooks registered for the given `hookType` which matched the transition's [[TreeChanges]].
+     * - Finds [[PathNode]] (or `PathNode[]`) to use as the TransitionHook context(s)
+     * - For each of the [[PathNode]]s, creates a TransitionHook
+     *
+     * @param hookType the type of the hook registration function, e.g., 'onEnter', 'onFinish'.
+     */
+    buildHooks(hookType: TransitionEventType): TransitionHook[];
+    /**
+     * Finds all RegisteredHooks from:
+     * - The Transition object instance hook registry
+     * - The TransitionService ($transitions) global hook registry
+     *
+     * which matched:
+     * - the eventType
+     * - the matchCriteria (to, from, exiting, retained, entering)
+     *
+     * @returns an array of matched [[RegisteredHook]]s
+     */
+    getMatchingHooks(hookType: TransitionEventType, treeChanges: TreeChanges, transition: Transition): RegisteredHook[];
+}

package/types/router/core/transition/hookRegistry.d.ts

@@ -0,0 +1,93 @@
+import { IHookRegistry } from './interface';
+import { HookRegOptions, HookMatchCriteria, TreeChanges, HookMatchCriterion, IMatchingNodes, HookFn } from './interface';
+import { Transition } from './transition';
+import { StateObject } from '../state/stateObject';
+import { TransitionEventType } from './transitionEventType';
+import { TransitionService } from './transitionService';
+/**
+ * Determines if the given state matches the matchCriteria
+ *
+ * @internal
+ *
+ * @param state a State Object to test against
+ * @param criterion
+ * - If a string, matchState uses the string as a glob-matcher against the state name
+ * - If an array (of strings), matchState uses each string in the array as a glob-matchers against the state name
+ *   and returns a positive match if any of the globs match.
+ * - If a function, matchState calls the function with the state and returns true if the function's result is truthy.
+ * @returns {boolean}
+ */
+export declare function matchState(state: StateObject, criterion: HookMatchCriterion, transition: Transition): boolean;
+/**
+ * The registration data for a registered transition hook
+ */
+export declare class RegisteredHook {
+    tranSvc: TransitionService;
+    eventType: TransitionEventType;
+    callback: HookFn;
+    matchCriteria: HookMatchCriteria;
+    removeHookFromRegistry: (hook: RegisteredHook) => void;
+    priority: number;
+    bind: any;
+    invokeCount: number;
+    invokeLimit: number;
+    _deregistered: boolean;
+    constructor(tranSvc: TransitionService, eventType: TransitionEventType, callback: HookFn, matchCriteria: HookMatchCriteria, removeHookFromRegistry: (hook: RegisteredHook) => void, options?: HookRegOptions);
+    /**
+     * Gets the matching [[PathNode]]s
+     *
+     * Given an array of [[PathNode]]s, and a [[HookMatchCriterion]], returns an array containing
+     * the [[PathNode]]s that the criteria matches, or `null` if there were no matching nodes.
+     *
+     * Returning `null` is significant to distinguish between the default
+     * "match-all criterion value" of `true` compared to a `() => true` function,
+     * when the nodes is an empty array.
+     *
+     * This is useful to allow a transition match criteria of `entering: true`
+     * to still match a transition, even when `entering === []`.  Contrast that
+     * with `entering: (state) => true` which only matches when a state is actually
+     * being entered.
+     */
+    private _matchingNodes;
+    /**
+     * Gets the default match criteria (all `true`)
+     *
+     * Returns an object which has all the criteria match paths as keys and `true` as values, i.e.:
+     *
+     * ```js
+     * {
+     *   to: true,
+     *   from: true,
+     *   entering: true,
+     *   exiting: true,
+     *   retained: true,
+     * }
+     */
+    private _getDefaultMatchCriteria;
+    /**
+     * Gets matching nodes as [[IMatchingNodes]]
+     *
+     * Create a IMatchingNodes object from the TransitionHookTypes that is roughly equivalent to:
+     *
+     * ```js
+     * let matches: IMatchingNodes = {
+     *   to:       _matchingNodes([tail(treeChanges.to)],   mc.to),
+     *   from:     _matchingNodes([tail(treeChanges.from)], mc.from),
+     *   exiting:  _matchingNodes(treeChanges.exiting,      mc.exiting),
+     *   retained: _matchingNodes(treeChanges.retained,     mc.retained),
+     *   entering: _matchingNodes(treeChanges.entering,     mc.entering),
+     * };
+     * ```
+     */
+    private _getMatchingNodes;
+    /**
+     * Determines if this hook's [[matchCriteria]] match the given [[TreeChanges]]
+     *
+     * @returns an IMatchingNodes object, or null. If an IMatchingNodes object is returned, its values
+     * are the matching [[PathNode]]s for each [[HookMatchCriterion]] (to, from, exiting, retained, entering)
+     */
+    matches(treeChanges: TreeChanges, transition: Transition): IMatchingNodes;
+    deregister(): void;
+}
+/** Return a registration function of the requested type. */
+export declare function makeEvent(registry: IHookRegistry, transitionService: TransitionService, eventType: TransitionEventType): (matchObject: any, callback: any, options?: {}) => any;

package/types/router/core/transition/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * # Transition subsystem
+ *
+ * This module contains APIs related to a Transition.
+ *
+ * See:
+ * - [[TransitionService]]
+ * - [[Transition]]
+ * - [[HookFn]], [[TransitionHookFn]], [[TransitionStateHookFn]], [[HookMatchCriteria]], [[HookResult]]
+ *
+ * @packageDocumentation @preferred
+ */
+export * from './interface';
+export * from './hookBuilder';
+export * from './hookRegistry';
+export * from './rejectFactory';
+export * from './transition';
+export * from './transitionHook';
+export * from './transitionEventType';
+export * from './transitionService';