From 095f531977971de387c619024c284f0f4df375d6 Mon Sep 17 00:00:00 2001 From: Chris Thielen Date: Sat, 11 Aug 2018 11:10:46 -0700 Subject: [PATCH] docs(url): Move docs from interface level to UrlService/UrlConfig/UrlRules classes docs(*): Improve docs - Migrate to @publicapi from @coreapi - Improve file header comment consistency, i.e., @coreapi @module foo --- src/common/common.ts | 6 +- src/common/coreservices.ts | 178 ++-------- src/common/glob.ts | 5 +- src/common/index.ts | 2 +- src/common/predicates.ts | 3 +- src/common/queue.ts | 2 +- src/common/trace.ts | 3 +- src/globals.ts | 5 +- src/hooks/coreResolvables.ts | 2 +- src/hooks/ignoredTransition.ts | 2 +- src/hooks/invalidTransition.ts | 2 +- src/hooks/lazyLoad.ts | 2 +- src/hooks/onEnterExitRetain.ts | 3 +- src/hooks/redirectTo.ts | 2 +- src/hooks/resolve.ts | 3 +- src/hooks/updateGlobals.ts | 3 +- src/hooks/url.ts | 2 +- src/hooks/views.ts | 2 +- src/index.ts | 5 +- src/interface.ts | 6 +- src/params/index.ts | 6 +- src/params/interface.ts | 34 +- src/params/param.ts | 20 +- src/params/paramType.ts | 6 +- src/params/paramTypes.ts | 13 +- src/params/stateParams.ts | 6 +- src/path/index.ts | 2 +- src/path/pathNode.ts | 4 +- src/path/pathUtils.ts | 2 +- src/resolve/index.ts | 2 +- src/resolve/interface.ts | 5 +- src/resolve/resolvable.ts | 5 +- src/resolve/resolveContext.ts | 4 +- src/router.ts | 13 +- src/state/index.ts | 6 +- src/state/interface.ts | 5 +- src/state/stateBuilder.ts | 3 +- src/state/stateMatcher.ts | 2 +- src/state/stateObject.ts | 6 +- src/state/stateQueueManager.ts | 3 +- src/state/stateRegistry.ts | 5 +- src/state/stateService.ts | 8 +- src/state/targetState.ts | 5 +- src/transition/hookBuilder.ts | 6 +- src/transition/hookRegistry.ts | 5 +- src/transition/index.ts | 6 +- src/transition/interface.ts | 5 +- src/transition/rejectFactory.ts | 5 +- src/transition/transition.ts | 6 +- src/transition/transitionEventType.ts | 2 +- src/transition/transitionHook.ts | 6 +- src/transition/transitionService.ts | 22 +- src/url/index.ts | 5 +- src/url/interface.ts | 419 ++---------------------- src/url/urlConfig.ts | 180 ++++++++-- src/url/urlMatcher.ts | 7 +- src/url/urlMatcherFactory.ts | 106 ++---- src/url/urlRouter.ts | 10 +- src/url/urlRule.ts | 5 +- src/url/urlRules.ts | 223 ++++++++++++- src/url/urlService.ts | 202 ++++++++++-- src/vanilla.ts | 6 +- src/vanilla/baseLocationService.ts | 6 +- src/vanilla/browserLocationConfig.ts | 6 +- src/vanilla/hashLocationService.ts | 6 +- src/vanilla/index.ts | 7 +- src/vanilla/injector.ts | 6 +- src/vanilla/interface.ts | 6 +- src/vanilla/memoryLocationConfig.ts | 6 +- src/vanilla/memoryLocationService.ts | 6 +- src/vanilla/plugins.ts | 6 +- src/vanilla/pushStateLocationService.ts | 6 +- src/vanilla/q.ts | 6 +- src/vanilla/utils.ts | 6 +- src/view/index.ts | 5 +- src/view/interface.ts | 3 +- src/view/view.ts | 22 +- test/urlServiceSpec.ts | 10 +- typedoc.json | 4 +- 79 files changed, 795 insertions(+), 951 deletions(-) diff --git a/src/common/common.ts b/src/common/common.ts index e87bc64f..357538ec 100644 --- a/src/common/common.ts +++ b/src/common/common.ts @@ -3,10 +3,8 @@ * * These functions are exported, but are subject to change without notice. * - * @preferred - * @module common - */ -/** for typedoc */ + * @preferred @publicapi @module common + */ /** */ import { isFunction, isString, isArray, isRegExp, isDate } from './predicates'; import { all, any, prop, curry, not } from './hof'; import { services } from './coreservices'; diff --git a/src/common/coreservices.ts b/src/common/coreservices.ts index 09654834..ed188992 100644 --- a/src/common/coreservices.ts +++ b/src/common/coreservices.ts @@ -2,11 +2,11 @@ * This module is a stub for core services such as Dependency Injection or Browser Location. * Core services may be implemented by a specific framework, such as ng1 or ng2, or be pure javascript. * - * @module common - */ -/** for typedoc */ + * @publicapi @module common + */ /** */ import { IInjectable, Obj } from './common'; import { Disposable } from '../interface'; +import { UrlConfig, UrlService } from '../url'; const noImpl = (fnname: string) => () => { throw new Error(`No implementation for ${fnname}. The framework specific code did not implement this method.`); @@ -48,154 +48,48 @@ export interface CoreServices { $injector: $InjectorLike; } +/** + * Handles low level URL read/write + * + * This service handles low level reads and updates of the URL and listens for url changes. + * Implementors should pass these through to the underlying URL mechanism. + * The underlying URL mechanism might be browser APIs, framework APIs, or some 3rd party URL management library. + * + * UI-Router Core includes three basic implementations: + * + * - [[PushStateLocationService]] + * - [[HashLocationService]] + * - [[MemoryLocationService]] + */ export interface LocationServices extends Disposable { - /** - * Gets the current url string - * - * The URL is normalized using the internal [[path]]/[[search]]/[[hash]] values. - * - * For example, the URL may be stored in the hash ([[HashLocationServices]]) or - * have a base HREF prepended ([[PushStateLocationServices]]). - * - * The raw URL in the browser might be: - * - * ``` - * http://mysite.com/somepath/index.html#/internal/path/123?param1=foo#anchor - * ``` - * - * or - * - * ``` - * http://mysite.com/basepath/internal/path/123?param1=foo#anchor - * ``` - * - * then this method returns: - * - * ``` - * /internal/path/123?param1=foo#anchor - * ``` - * - * - * #### Example: - * ```js - * locationServices.url(); // "/some/path?query=value#anchor" - * ``` - * - * @returns the current value of the url, as a string. - */ - url(): string; - - /** - * Updates the url, or gets the current url - * - * Updates the url, changing it to the value in `newurl` - * - * #### Example: - * ```js - * locationServices.url("/some/path?query=value#anchor", true); - * ``` - * - * @param newurl The new value for the URL. - * This url should reflect only the new internal [[path]], [[search]], and [[hash]] values. - * It should not include the protocol, site, port, or base path of an absolute HREF. - * @param replace When true, replaces the current history entry (instead of appending it) with this new url - * @param state The history's state object, i.e., pushState (if the LocationServices implementation supports it) - * @return the url (after potentially being processed) - */ - url(newurl: string, replace?: boolean, state?: any): string; - - /** - * Gets the path part of the current url - * - * If the current URL is `/some/path?query=value#anchor`, this returns `/some/path` - * - * @return the path portion of the url - */ - path(): string; - - /** - * Gets the search part of the current url as an object - * - * If the current URL is `/some/path?query=value#anchor`, this returns `{ query: 'value' }` - * - * @return the search (querystring) portion of the url, as an object - */ - search(): { [key: string]: any }; - - /** - * Gets the hash part of the current url - * - * If the current URL is `/some/path?query=value#anchor`, this returns `anchor` - * - * @return the hash (anchor) portion of the url - */ - hash(): string; - - /** - * Registers a url change handler - * - * #### Example: - * ```js - * let deregisterFn = locationServices.onChange((evt) => console.log("url change", evt)); - * ``` - * - * @param callback a function that will be called when the url is changing - * @return a function that de-registers the callback - */ - onChange(callback: Function): Function; + /** See: [[UrlService.url]] */ url: UrlService['url']; + /** See: [[UrlService.path]] */ path: UrlService['path']; + /** See: [[UrlService.search]] */ search: UrlService['search']; + /** See: [[UrlService.hash]] */ hash: UrlService['hash']; + /** See: [[UrlService.onChange]] */ onChange: UrlService['onChange']; } /** - * This service returns the location configuration + * Returns low level URL configuration and metadata * * This service returns information about the location configuration. * This service is primarily used when building URLs (e.g., for `hrefs`) + * + * Implementors should pass these through to the underlying URL APIs. + * The underlying URL mechanism might be browser APIs, framework APIs, or some 3rd party URL management library. + * + * UI-Router Core includes two basic implementations: + * + * - [[BrowserLocationConfig]] + * - [[MemoryLocationConfig]] */ export interface LocationConfig extends Disposable { - /** - * Gets the port, e.g., `80` - * - * @return the port number - */ - port(): number; - /** - * Gets the protocol, e.g., `http` - * - * @return the protocol - */ - protocol(): string; - /** - * Gets the host, e.g., `localhost` - * - * @return the protocol - */ - host(): string; - /** - * Gets the base Href, e.g., `http://localhost/approot/` - * - * @return the application's base href - */ - baseHref(): string; - /** - * Returns true when running in pushstate mode - * - * @return true when running in pushstate mode - */ - html5Mode(): boolean; - /** - * Gets the hashPrefix (when not running in pushstate mode) - * - * If the current url is `http://localhost/app#!/uirouter/path/#anchor`, it returns `!` which is the prefix for the "hashbang" portion. - * - * @return the hash prefix - */ - hashPrefix(): string; - /** - * Sets the hashPrefix (when not running in pushstate mode) - * - * @return the new hash prefix - */ - hashPrefix(newprefix: string): string; + /** See: [[UrlConfig.port]] */ port: UrlConfig['port']; + /** See: [[UrlConfig.protocol]] */ protocol: UrlConfig['protocol']; + /** See: [[UrlConfig.host]] */ host: UrlConfig['host']; + /** See: [[UrlConfig.baseHref]] */ baseHref: UrlConfig['baseHref']; + /** See: [[UrlConfig.html5Mode]] */ html5Mode: UrlConfig['html5Mode']; + /** See: [[UrlConfig.hashPrefix]] */ hashPrefix: UrlConfig['hashPrefix']; } export { services }; diff --git a/src/common/glob.ts b/src/common/glob.ts index 14665cd2..4e92ff5a 100644 --- a/src/common/glob.ts +++ b/src/common/glob.ts @@ -1,7 +1,4 @@ -/** - * @coreapi - * @module core - */ +/** @publicapi @module core */ /** * Matches state names using glob-like pattern strings. * diff --git a/src/common/index.ts b/src/common/index.ts index 9a15c741..acb900d1 100644 --- a/src/common/index.ts +++ b/src/common/index.ts @@ -1,4 +1,4 @@ -/** @module common */ /** for typedoc */ +/** @publicapi @module common */ /** */ export * from './common'; export * from './coreservices'; export * from './glob'; diff --git a/src/common/predicates.ts b/src/common/predicates.ts index 081312ec..5f7652be 100644 --- a/src/common/predicates.ts +++ b/src/common/predicates.ts @@ -4,8 +4,7 @@ * Although these functions are exported, they are subject to change without notice. * * @module common_predicates - */ -/** */ + */ /** */ import { and, not, pipe, prop, or } from './hof'; import { Predicate } from './common'; // has or is using import { StateObject } from '../state/stateObject'; diff --git a/src/common/queue.ts b/src/common/queue.ts index 90c901e5..e450212e 100644 --- a/src/common/queue.ts +++ b/src/common/queue.ts @@ -1,4 +1,4 @@ -/** @module common */ +/** @publicapi @module common */ /** */ import { pushTo } from './common'; export class Queue { diff --git a/src/common/trace.ts b/src/common/trace.ts index a0ddd3c7..ada7fa33 100644 --- a/src/common/trace.ts +++ b/src/common/trace.ts @@ -30,8 +30,7 @@ * app.run($trace => $trace.enable()); * ``` * - * @coreapi - * @module trace + * @publicapi @module trace */ /* tslint:disable:no-console */ import { parse } from '../common/hof'; diff --git a/src/globals.ts b/src/globals.ts index 37b52f76..3daea8f1 100644 --- a/src/globals.ts +++ b/src/globals.ts @@ -1,7 +1,4 @@ -/** - * @coreapi - * @module core - */ /** */ +/** @publicapi @module core */ /** */ import { StateParams } from './params/stateParams'; import { StateDeclaration } from './state/interface'; import { StateObject } from './state/stateObject'; diff --git a/src/hooks/coreResolvables.ts b/src/hooks/coreResolvables.ts index af04db3a..1845b818 100644 --- a/src/hooks/coreResolvables.ts +++ b/src/hooks/coreResolvables.ts @@ -1,4 +1,4 @@ -/** @module hooks */ /** */ +/** @internalapi @module hooks */ /** */ import { Transition } from '../transition/transition'; import { UIRouter } from '../router'; import { TransitionService } from '../transition/transitionService'; diff --git a/src/hooks/ignoredTransition.ts b/src/hooks/ignoredTransition.ts index 9fbac988..25c1b71c 100644 --- a/src/hooks/ignoredTransition.ts +++ b/src/hooks/ignoredTransition.ts @@ -1,4 +1,4 @@ -/** @module hooks */ /** */ +/** @internalapi @module hooks */ /** */ import { trace } from '../common/trace'; import { Rejection } from '../transition/rejectFactory'; diff --git a/src/hooks/invalidTransition.ts b/src/hooks/invalidTransition.ts index 0a7698c3..25bdb453 100644 --- a/src/hooks/invalidTransition.ts +++ b/src/hooks/invalidTransition.ts @@ -1,4 +1,4 @@ -/** @module hooks */ /** */ +/** @internalapi @module hooks */ /** */ import { TransitionService } from '../transition/transitionService'; import { Transition } from '../transition/transition'; diff --git a/src/hooks/lazyLoad.ts b/src/hooks/lazyLoad.ts index b2dce5f7..ab5a88c7 100644 --- a/src/hooks/lazyLoad.ts +++ b/src/hooks/lazyLoad.ts @@ -1,4 +1,4 @@ -/** @module hooks */ /** */ +/** @internalapi @module hooks */ /** */ import { Transition } from '../transition/transition'; import { TransitionService } from '../transition/transitionService'; import { TransitionHookFn } from '../transition/interface'; diff --git a/src/hooks/onEnterExitRetain.ts b/src/hooks/onEnterExitRetain.ts index 22b34b24..f8df7fa0 100644 --- a/src/hooks/onEnterExitRetain.ts +++ b/src/hooks/onEnterExitRetain.ts @@ -1,5 +1,4 @@ -/** @module hooks */ -/** for typedoc */ +/** @internalapi @module hooks */ /** */ import { TransitionStateHookFn } from '../transition/interface'; import { Transition } from '../transition/transition'; import { TransitionService } from '../transition/transitionService'; diff --git a/src/hooks/redirectTo.ts b/src/hooks/redirectTo.ts index 566d3536..906efd16 100644 --- a/src/hooks/redirectTo.ts +++ b/src/hooks/redirectTo.ts @@ -1,4 +1,4 @@ -/** @module hooks */ /** */ +/** @internalapi @module hooks */ /** */ import { isString, isFunction } from '../common/predicates'; import { Transition } from '../transition/transition'; import { services } from '../common/coreservices'; diff --git a/src/hooks/resolve.ts b/src/hooks/resolve.ts index 96646e68..82b1734a 100644 --- a/src/hooks/resolve.ts +++ b/src/hooks/resolve.ts @@ -1,5 +1,4 @@ -/** @module hooks */ -/** for typedoc */ +/** @internalapi @module hooks */ /** */ import { noop } from '../common/common'; import { Transition } from '../transition/transition'; import { ResolveContext } from '../resolve/resolveContext'; diff --git a/src/hooks/updateGlobals.ts b/src/hooks/updateGlobals.ts index de23524e..7088b1d9 100644 --- a/src/hooks/updateGlobals.ts +++ b/src/hooks/updateGlobals.ts @@ -1,5 +1,4 @@ -/** @module hooks */ -/** for typedoc */ +/** @internalapi @module hooks */ /** */ import { Transition } from '../transition/transition'; import { copy } from '../common/common'; import { TransitionService } from '../transition/transitionService'; diff --git a/src/hooks/url.ts b/src/hooks/url.ts index 721a860f..9ff182b9 100644 --- a/src/hooks/url.ts +++ b/src/hooks/url.ts @@ -1,4 +1,4 @@ -/** @module hooks */ /** */ +/** @internalapi @module hooks */ /** */ import { UrlRouter } from '../url/urlRouter'; import { StateService } from '../state/stateService'; import { Transition } from '../transition/transition'; diff --git a/src/hooks/views.ts b/src/hooks/views.ts index 12ac02d3..9b95fc5a 100644 --- a/src/hooks/views.ts +++ b/src/hooks/views.ts @@ -1,4 +1,4 @@ -/** @module hooks */ /** for typedoc */ +/** @internalapi @module hooks */ /** */ import { noop } from '../common/common'; import { services } from '../common/coreservices'; import { Transition } from '../transition/transition'; diff --git a/src/index.ts b/src/index.ts index 3bb45647..3d0fb8c8 100644 --- a/src/index.ts +++ b/src/index.ts @@ -1,7 +1,4 @@ -/** - * @coreapi - * @module common - */ /** */ +/** @publicapi @module common */ /** */ export * from './common/index'; export * from './params/index'; diff --git a/src/interface.ts b/src/interface.ts index efe1ae1d..667daa05 100644 --- a/src/interface.ts +++ b/src/interface.ts @@ -4,10 +4,8 @@ * The classes and interfaces that are core to ui-router and do not belong * to a more specific subsystem (such as resolve). * - * @coreapi - * @preferred - * @module core - */ /** for typedoc */ + * @preferred @publicapi @module core + */ /** */ // Need to import or export at least one concrete something import { noop } from './common/common'; diff --git a/src/params/index.ts b/src/params/index.ts index 4d238b6f..4baeb684 100644 --- a/src/params/index.ts +++ b/src/params/index.ts @@ -3,10 +3,8 @@ * * See [[ParamDeclaration]] * - * @coreapi - * @preferred - * @module params - */ /** for typedoc */ + * @preferred @publicapi @module params + */ /** */ export * from './interface'; export * from './param'; export * from './paramTypes'; diff --git a/src/params/interface.ts b/src/params/interface.ts index 33d260b6..e7889559 100644 --- a/src/params/interface.ts +++ b/src/params/interface.ts @@ -1,8 +1,4 @@ -/** - * @coreapi - * @module params - */ /** for typedoc */ - +/** @publicapi @module params */ /** */ import { ParamType } from './paramType'; /** @@ -17,8 +13,6 @@ import { ParamType } from './paramType'; * folderId: 'inbox' * } * ``` - * - * @coreapi */ export interface RawParams { [key: string]: any; @@ -54,7 +48,6 @@ export interface RawParams { * } * } * ``` - * @coreapi */ export interface ParamDeclaration { /** @@ -351,9 +344,28 @@ export interface ParamDeclaration { inherit?: boolean; } -/** @internalapi */ +/** + * String replacement + * + * Represents an exact match string replacement. + * + * Note: `to` or `from` may be null or undefined, and will be tested using `===`. + */ export interface Replace { + /** + * The value to replace. + * + * May be `null` or `undefined`. + * The entire value must match using `===`. + * When found, the [[to]] value is used instead. + */ from: string; + + /** + * The new value + * + * Used instead of the [[from]] value. + */ to: string; } @@ -463,8 +475,8 @@ export interface Replace { * $state.go('list', { item: "Ringo" }); * ``` * - * See: [[UrlConfigApi.type]] - * @coreapi + * See: [[UrlConfig.type]] + * @publicapi */ export interface ParamTypeDefinition { /** diff --git a/src/params/param.ts b/src/params/param.ts index 35650686..8ba0b3f8 100644 --- a/src/params/param.ts +++ b/src/params/param.ts @@ -1,7 +1,4 @@ -/** - * @coreapi - * @module params - */ /** for typedoc */ +/** @publicapi @module params */ /** */ import { extend, filter, map, allTrueR, find } from '../common/common'; import { prop } from '../common/hof'; import { isInjectable, isDefined, isString, isArray, isUndefined } from '../common/predicates'; @@ -9,8 +6,8 @@ import { RawParams, ParamDeclaration } from '../params/interface'; import { services } from '../common/coreservices'; import { ParamType } from './paramType'; import { ParamTypes } from './paramTypes'; -import { UrlMatcherFactory } from '../url/urlMatcherFactory'; import { StateDeclaration } from '../state'; +import { UrlConfig } from '../url'; /** @hidden */ const hasOwn = Object.prototype.hasOwnProperty; @@ -27,6 +24,7 @@ enum DefType { } export { DefType }; +/** @internalapi */ function getParamDeclaration(paramName: string, location: DefType, state: StateDeclaration): ParamDeclaration { const noReloadOnSearch = (state.reloadOnSearch === false && location === DefType.SEARCH) || undefined; const dynamic = find([state.dynamic, noReloadOnSearch], isDefined); @@ -153,21 +151,15 @@ export class Param { return params.map(param => param.validates(values[param.id])).reduce(allTrueR, true); } - constructor( - id: string, - type: ParamType, - location: DefType, - urlMatcherFactory: UrlMatcherFactory, - state: StateDeclaration - ) { + constructor(id: string, type: ParamType, location: DefType, urlConfig: UrlConfig, state: StateDeclaration) { const config: ParamDeclaration = getParamDeclaration(id, location, state); - type = getType(config, type, location, id, urlMatcherFactory.paramTypes); + type = getType(config, type, location, id, urlConfig.paramTypes); const arrayMode = getArrayMode(); type = arrayMode ? type.$asArray(arrayMode, location === DefType.SEARCH) : type; const isOptional = config.value !== undefined || location === DefType.SEARCH; const dynamic = isDefined(config.dynamic) ? !!config.dynamic : !!type.dynamic; const raw = isDefined(config.raw) ? !!config.raw : !!type.raw; - const squash = getSquashPolicy(config, isOptional, urlMatcherFactory.defaultSquashPolicy()); + const squash = getSquashPolicy(config, isOptional, urlConfig.defaultSquashPolicy()); const replace = getReplace(config, arrayMode, isOptional, squash); const inherit = isDefined(config.inherit) ? !!config.inherit : !!type.inherit; diff --git a/src/params/paramType.ts b/src/params/paramType.ts index d5202727..4436b76b 100644 --- a/src/params/paramType.ts +++ b/src/params/paramType.ts @@ -1,8 +1,4 @@ -/** - * @coreapi - * @module params - */ -/** */ +/** @publicapi @module params */ /** */ import { extend, filter, map } from '../common/common'; import { isArray, isDefined } from '../common/predicates'; import { ParamTypeDefinition } from './interface'; diff --git a/src/params/paramTypes.ts b/src/params/paramTypes.ts index 0b609cce..86d9f6f8 100644 --- a/src/params/paramTypes.ts +++ b/src/params/paramTypes.ts @@ -1,8 +1,4 @@ -/** - * @coreapi - * @module params - */ -/** */ +/** @publicapi @module params */ /** */ import { fromJson, toJson, identity, equals, inherit, map, extend, pick } from '../common/common'; import { isDefined, isNullOrUndefined } from '../common/predicates'; import { is } from '../common/hof'; @@ -26,6 +22,12 @@ import { ParamTypeDefinition } from './interface'; * - [[date]] * - [[json]] * - [[any]] + * + * To register custom parameter types, use [[UrlConfig.type]], i.e., + * + * ```js + * router.urlService.config.type(customType) + * ``` */ export class ParamTypes { /** @@ -70,7 +72,6 @@ export class ParamTypes { * * This parameter type is used for the `#` parameter (the hash) * It behaves the same as the [[string]] parameter type. - * @coreapi */ static hash: ParamTypeDefinition; diff --git a/src/params/stateParams.ts b/src/params/stateParams.ts index 56b5b94b..ccdd729b 100644 --- a/src/params/stateParams.ts +++ b/src/params/stateParams.ts @@ -1,8 +1,4 @@ -/** - * @coreapi - * @module params - */ -/** */ +/** @publicapi @module params */ /** */ import { extend, ancestors, Obj } from '../common/common'; import { StateObject } from '../state/stateObject'; diff --git a/src/path/index.ts b/src/path/index.ts index fd085e17..177883fe 100644 --- a/src/path/index.ts +++ b/src/path/index.ts @@ -1,3 +1,3 @@ -/** @module path */ /** for typedoc */ +/** @internalapi @module path */ /** */ export * from './pathNode'; export * from './pathUtils'; diff --git a/src/path/pathNode.ts b/src/path/pathNode.ts index 81e790f6..63883043 100644 --- a/src/path/pathNode.ts +++ b/src/path/pathNode.ts @@ -1,4 +1,4 @@ -/** @module path */ /** for typedoc */ +/** @internalapi @module path */ /** */ import { extend, applyPairs, find, allTrueR, pairs, arrayTuples } from '../common/common'; import { propEq } from '../common/hof'; import { StateObject } from '../state/stateObject'; @@ -8,8 +8,6 @@ import { Resolvable } from '../resolve/resolvable'; import { ViewConfig } from '../view/interface'; /** - * @internalapi - * * A node in a [[TreeChanges]] path * * For a [[TreeChanges]] path, this class holds the stateful information for a single node in the path. diff --git a/src/path/pathUtils.ts b/src/path/pathUtils.ts index 6c2ff8d0..19eaf1ec 100644 --- a/src/path/pathUtils.ts +++ b/src/path/pathUtils.ts @@ -1,4 +1,4 @@ -/** @module path */ /** for typedoc */ +/** @internalapi @module path */ /** */ import { extend, diff --git a/src/resolve/index.ts b/src/resolve/index.ts index 994bd9f5..5fb5b632 100644 --- a/src/resolve/index.ts +++ b/src/resolve/index.ts @@ -1,4 +1,4 @@ -/** @module resolve */ /** for typedoc */ +/** @publicapi @module resolve */ /** */ export * from './interface'; export * from './resolvable'; export * from './resolveContext'; diff --git a/src/resolve/interface.ts b/src/resolve/interface.ts index 51c08ad1..7cb2823b 100644 --- a/src/resolve/interface.ts +++ b/src/resolve/interface.ts @@ -5,9 +5,8 @@ * * Typically, resolve is configured on a state using a [[StateDeclaration.resolve]] declaration. * - * @coreapi - * @module resolve - */ /** for typedoc */ + * @publicapi @module resolve + */ /** */ import { Resolvable } from './resolvable'; /** diff --git a/src/resolve/resolvable.ts b/src/resolve/resolvable.ts index 3fc7ddd2..98d36e3d 100644 --- a/src/resolve/resolvable.ts +++ b/src/resolve/resolvable.ts @@ -1,7 +1,4 @@ -/** - * @coreapi - * @module resolve - */ /** for typedoc */ +/** @publicapi @module resolve */ /** */ import { extend, equals, inArray, identity } from '../common/common'; import { services } from '../common/coreservices'; import { trace } from '../common/trace'; diff --git a/src/resolve/resolveContext.ts b/src/resolve/resolveContext.ts index 5f3f19c3..604aa8c7 100644 --- a/src/resolve/resolveContext.ts +++ b/src/resolve/resolveContext.ts @@ -1,5 +1,4 @@ -/** @module resolve */ -/** for typedoc */ +/** @publicapi @module resolve */ /** */ import { find, tail, uniqR, unnestR, inArray } from '../common/common'; import { propEq, not } from '../common/hof'; import { trace } from '../common/trace'; @@ -189,6 +188,7 @@ export class ResolveContext { } } +/** @internalapi */ class UIInjectorImpl implements UIInjector { native: $InjectorLike; diff --git a/src/router.ts b/src/router.ts index 98f68951..c36d6324 100644 --- a/src/router.ts +++ b/src/router.ts @@ -1,7 +1,4 @@ -/** - * @coreapi - * @module core - */ /** */ +/** @publicapi @module core */ /** */ import { UrlMatcherFactory } from './url/urlMatcherFactory'; import { UrlRouter } from './url/urlRouter'; import { TransitionService } from './transition/transitionService'; @@ -65,7 +62,7 @@ export class UIRouter { * Deprecated for public use. Use [[urlService]] instead. * @deprecated Use [[urlService]] instead */ - urlMatcherFactory: UrlMatcherFactory = new UrlMatcherFactory(); + urlMatcherFactory: UrlMatcherFactory = new UrlMatcherFactory(this); /** * Deprecated for public use. Use [[urlService]] instead. @@ -73,15 +70,15 @@ export class UIRouter { */ urlRouter: UrlRouter = new UrlRouter(this); + /** Provides services related to the URL */ + urlService: UrlService = new UrlService(this); + /** Provides a registry for states, and related registration services */ stateRegistry: StateRegistry = new StateRegistry(this); /** Provides services related to states */ stateService = new StateService(this); - /** Provides services related to the URL */ - urlService: UrlService = new UrlService(this); - /** @hidden plugin instances are registered here */ private _plugins: { [key: string]: UIRouterPlugin } = {}; diff --git a/src/state/index.ts b/src/state/index.ts index 65a43179..8572de31 100644 --- a/src/state/index.ts +++ b/src/state/index.ts @@ -16,10 +16,8 @@ * - Note: Bootstrap state registration differs by front-end framework. * - Get notified of state registration/deregistration using [[StateRegistry.onStatesChanged]]. * - * @coreapi - * @preferred - * @module state - */ /** for typedoc */ + * @preferred @publicapi @module state + */ /** */ export * from './interface'; export * from './stateBuilder'; export * from './stateObject'; diff --git a/src/state/interface.ts b/src/state/interface.ts index 7a819d86..3ef95431 100644 --- a/src/state/interface.ts +++ b/src/state/interface.ts @@ -1,7 +1,4 @@ -/** - * @coreapi - * @module state - */ /** for typedoc */ +/** @publicapi @module state */ /** */ import { ParamDeclaration, RawParams } from '../params/interface'; import { StateObject } from './stateObject'; import { ViewContext } from '../view/interface'; diff --git a/src/state/stateBuilder.ts b/src/state/stateBuilder.ts index e06ce3ba..7cf9e61e 100644 --- a/src/state/stateBuilder.ts +++ b/src/state/stateBuilder.ts @@ -1,5 +1,4 @@ -/** @module state */ -/** for typedoc */ +/** @publicapi @module state */ /** */ import { applyPairs, extend, identity, inherit, mapObj, noop, Obj, omit, tail, values } from '../common/common'; import { isArray, isDefined, isFunction, isString } from '../common/predicates'; import { stringify } from '../common/strings'; diff --git a/src/state/stateMatcher.ts b/src/state/stateMatcher.ts index 195a67a4..751e9856 100644 --- a/src/state/stateMatcher.ts +++ b/src/state/stateMatcher.ts @@ -1,4 +1,4 @@ -/** @module state */ /** for typedoc */ +/** @publicapi @module state */ /** */ import { isString } from '../common/predicates'; import { StateOrName } from './interface'; import { StateObject } from './stateObject'; diff --git a/src/state/stateObject.ts b/src/state/stateObject.ts index 546a6ea3..8e95277a 100644 --- a/src/state/stateObject.ts +++ b/src/state/stateObject.ts @@ -1,8 +1,4 @@ -/** - * @coreapi - * @module state - */ -/** for typedoc */ +/** @publicapi @module state */ /** */ import { StateDeclaration, _ViewDeclaration, _StateDeclaration, LazyLoadResult } from './interface'; import { defaults, values, find, inherit } from '../common/common'; import { propEq } from '../common/hof'; diff --git a/src/state/stateQueueManager.ts b/src/state/stateQueueManager.ts index 57c270ab..193a3b32 100644 --- a/src/state/stateQueueManager.ts +++ b/src/state/stateQueueManager.ts @@ -1,5 +1,4 @@ -/** @module state */ -/** for typedoc */ +/** @publicapi @module state */ /** */ import { inArray, isString, prop } from '../common'; import { _StateDeclaration } from './interface'; import { StateObject } from './stateObject'; diff --git a/src/state/stateRegistry.ts b/src/state/stateRegistry.ts index 5e94502d..3d28566a 100644 --- a/src/state/stateRegistry.ts +++ b/src/state/stateRegistry.ts @@ -1,7 +1,4 @@ -/** - * @coreapi - * @module state - */ /** for typedoc */ +/** @publicapi @module state */ /** */ import { StateObject } from './stateObject'; import { StateMatcher } from './stateMatcher'; diff --git a/src/state/stateService.ts b/src/state/stateService.ts index c0488515..adc38cea 100644 --- a/src/state/stateService.ts +++ b/src/state/stateService.ts @@ -1,8 +1,4 @@ -/** - * @coreapi - * @module state - */ -/** */ +/** @publicapi @module state */ /** */ import { createProxyFunctions, defaults, @@ -85,7 +81,7 @@ export class StateService { } /** @internalapi */ - constructor(private router: UIRouter) { + constructor(/** @hidden */ private router: UIRouter) { const getters = ['current', '$current', 'params', 'transition']; const boundFns = Object.keys(StateService.prototype).filter(not(inArray(getters))); createProxyFunctions(val(StateService.prototype), this, val(this), boundFns); diff --git a/src/state/targetState.ts b/src/state/targetState.ts index 357639d7..49251cbc 100644 --- a/src/state/targetState.ts +++ b/src/state/targetState.ts @@ -1,7 +1,4 @@ -/** - * @coreapi - * @module state - */ /** for typedoc */ +/** @publicapi @module state */ /** */ import { StateDeclaration, StateOrName, TargetStateDef } from './interface'; import { TransitionOptions } from '../transition/interface'; diff --git a/src/transition/hookBuilder.ts b/src/transition/hookBuilder.ts index 1af7ba55..03f3f8c2 100644 --- a/src/transition/hookBuilder.ts +++ b/src/transition/hookBuilder.ts @@ -1,8 +1,4 @@ -/** - * @coreapi - * @module transition - */ /** for typedoc */ - +/** @publicapi @module transition */ /** */ import { extend, tail, assertPredicate, unnestR, identity } from '../common/common'; import { isArray } from '../common/predicates'; diff --git a/src/transition/hookRegistry.ts b/src/transition/hookRegistry.ts index f41dec90..7830a339 100644 --- a/src/transition/hookRegistry.ts +++ b/src/transition/hookRegistry.ts @@ -1,7 +1,4 @@ -/** - * @coreapi - * @module transition - */ /** for typedoc */ +/** @publicapi @module transition */ /** */ import { isString, isFunction, Glob, extend, removeFrom, tail, values, identity, mapObj } from '../common'; import { PathNode } from '../path/pathNode'; import { diff --git a/src/transition/index.ts b/src/transition/index.ts index 56866ad0..bfd3fdac 100644 --- a/src/transition/index.ts +++ b/src/transition/index.ts @@ -8,10 +8,8 @@ * - [[Transition]] * - [[HookFn]], [[TransitionHookFn]], [[TransitionStateHookFn]], [[HookMatchCriteria]], [[HookResult]] * - * @coreapi - * @preferred - * @module transition - */ /** for typedoc */ + * @preferred @publicapi @module transition + */ /** */ export * from './interface'; export * from './hookBuilder'; export * from './hookRegistry'; diff --git a/src/transition/interface.ts b/src/transition/interface.ts index f3680e85..fa0a7bdd 100644 --- a/src/transition/interface.ts +++ b/src/transition/interface.ts @@ -1,7 +1,4 @@ -/** - * @coreapi - * @module transition - */ /** for typedoc */ +/** @publicapi @module transition */ /** */ import { StateDeclaration } from '../state/interface'; import { Predicate } from '../common/common'; diff --git a/src/transition/rejectFactory.ts b/src/transition/rejectFactory.ts index 927e704d..6e57a34d 100644 --- a/src/transition/rejectFactory.ts +++ b/src/transition/rejectFactory.ts @@ -1,7 +1,4 @@ -/** - * @coreapi - * @module transition - */ /** for typedoc */ +/** @publicapi @module transition */ /** */ 'use strict'; import { extend, silentRejection } from '../common/common'; import { stringify } from '../common/strings'; diff --git a/src/transition/transition.ts b/src/transition/transition.ts index b05392f3..bbef0ad1 100644 --- a/src/transition/transition.ts +++ b/src/transition/transition.ts @@ -1,8 +1,4 @@ -/** - * @coreapi - * @module transition - */ -/** for typedoc */ +/** @publicapi @module transition */ /** */ import { trace } from '../common/trace'; import { services } from '../common/coreservices'; import { stringify } from '../common/strings'; diff --git a/src/transition/transitionEventType.ts b/src/transition/transitionEventType.ts index 3baa3c9b..c489d6ae 100644 --- a/src/transition/transitionEventType.ts +++ b/src/transition/transitionEventType.ts @@ -1,4 +1,4 @@ -/** @module transition */ /** */ +/** @publicapi @module transition */ /** */ import { TransitionHookPhase, PathType } from './interface'; import { GetErrorHandler, GetResultHandler, TransitionHook } from './transitionHook'; /** diff --git a/src/transition/transitionHook.ts b/src/transition/transitionHook.ts index 23937ba8..af58faaf 100644 --- a/src/transition/transitionHook.ts +++ b/src/transition/transitionHook.ts @@ -1,8 +1,4 @@ -/** - * @coreapi - * @module transition - */ -/** for typedoc */ +/** @publicapi @module transition */ /** */ import { TransitionHookOptions, HookResult, TransitionHookPhase } from './interface'; import { defaults, noop, silentRejection } from '../common/common'; import { fnToString, maxLength } from '../common/strings'; diff --git a/src/transition/transitionService.ts b/src/transition/transitionService.ts index a78bc943..561e3066 100644 --- a/src/transition/transitionService.ts +++ b/src/transition/transitionService.ts @@ -1,8 +1,4 @@ -/** - * @coreapi - * @module transition - */ -/** for typedoc */ +/** @publicapi @module transition */ /** */ import { IHookRegistry, TransitionOptions, @@ -163,13 +159,15 @@ export class TransitionService implements IHookRegistry, Disposable { this._router = _router; this.$view = _router.viewService; this._deregisterHookFns = {}; - this._pluginapi = createProxyFunctions(val(this), {}, val(this), [ - '_definePathType', - '_defineEvent', - '_getPathTypes', - '_getEvents', - 'getHooks', - ]); + this._pluginapi = ( + createProxyFunctions(val(this), {}, val(this), [ + '_definePathType', + '_defineEvent', + '_getPathTypes', + '_getEvents', + 'getHooks', + ]) + ); this._defineCorePaths(); this._defineCoreEvents(); diff --git a/src/url/index.ts b/src/url/index.ts index 94b26e46..f9763d97 100644 --- a/src/url/index.ts +++ b/src/url/index.ts @@ -1,7 +1,4 @@ -/** - * @coreapi - * @module url - */ /** for typedoc */ +/** @publicapi @module url */ /** */ export * from './interface'; export * from './urlMatcher'; export * from './urlMatcherFactory'; diff --git a/src/url/interface.ts b/src/url/interface.ts index f0a816be..711f0407 100644 --- a/src/url/interface.ts +++ b/src/url/interface.ts @@ -5,20 +5,17 @@ * * The primary API is found in [[UrlService]], [[UrlService.config]], and [[UrlService.rules]]. * - * @preferred - * @coreapi - * @module url + * @preferred @publicapi @module url */ /** */ -import { LocationConfig } from '../common/coreservices'; -import { ParamType } from '../params/paramType'; +import { LocationConfig } from '../common'; import { UIRouter } from '../router'; -import { TargetState } from '../state/targetState'; -import { TargetStateDef } from '../state/interface'; +import { StateDeclaration, StateObject, TargetState, TargetStateDef } from '../state'; import { UrlMatcher } from './urlMatcher'; -import { StateObject } from '../state/stateObject'; -import { ParamTypeDefinition } from '../params'; -import { StateDeclaration } from '../state'; +import { UrlConfig } from './urlConfig'; +import { UrlRules } from './urlRules'; +import { UrlService } from './urlService'; +/** @internalapi */ export interface UrlMatcherCompileConfig { // If state is provided, use the configuration in the `params` block state?: StateDeclaration; @@ -26,394 +23,33 @@ export interface UrlMatcherCompileConfig { caseInsensitive?: boolean; } -/** - * An API to customize the URL behavior and retrieve URL configuration - * - * - * This API can customize the behavior of the URL. - * This includes optional trailing slashes ([[strictMode]]), case sensitivity ([[caseInsensitive]]), - * and custom parameter encoding (custom [[type]]). - * - * It also has information about the location (url) configuration such as [[port]] and [[baseHref]]. - * This information can be used to build absolute URLs, such as - * `https://example.com:443/basepath/state/substate?param1=a#hashvalue`; - * - * This API is found on [[UrlService.config]]. - */ +/** @internalapi @deprecated use [[UrlConfig]] */ export interface UrlConfigApi extends LocationConfig, UrlMatcherConfig {} +/** @internalapi @deprecated use [[UrlConfig]] */ export interface UrlMatcherConfig { - /** - * Defines whether URL matching should be case sensitive (the default behavior), or not. - * - * #### Example: - * ```js - * // Allow case insensitive url matches - * urlService.config.caseInsensitive(true); - * ``` - * - * @param value `false` to match URL in a case sensitive manner; otherwise `true`; - * @returns the current value of caseInsensitive - */ - caseInsensitive(value?: boolean): boolean; - - /** - * Defines whether URLs should match trailing slashes, or not (the default behavior). - * - * #### Example: - * ```js - * // Allow optional trailing slashes - * urlService.config.strictMode(false); - * ``` - * - * @param value `false` to match trailing slashes in URLs, otherwise `true`. - * @returns the current value of strictMode - */ - strictMode(value?: boolean): boolean; - - /** - * Sets the default behavior when generating or matching URLs with default parameter values. - * - * #### Example: - * ```js - * // Remove default parameter values from the url - * urlService.config.defaultSquashPolicy(true); - * ``` - * - * @param value A string that defines the default parameter URL squashing behavior. - * - `nosquash`: When generating an href with a default parameter value, do not squash the parameter value from the URL - * - `slash`: When generating an href with a default parameter value, squash (remove) the parameter value, and, if the - * parameter is surrounded by slashes, squash (remove) one slash from the URL - * - any other string, e.g. "~": When generating an href with a default parameter value, squash (remove) - * the parameter value from the URL and replace it with this string. - * @returns the current value of defaultSquashPolicy - */ - defaultSquashPolicy(value?: boolean | string): boolean | string; - - /** - * Creates and registers a custom [[ParamTypeDefinition]] object - * - * A custom parameter type can be used to generate URLs with typed parameters or custom encoding/decoding. - * - * #### Note: Register custom types *before using them* in a state definition. - * - * #### Example: - * ```js - * // Encode object parameter as JSON string - * urlService.config.type('myjson', { - * encode: (obj) => JSON.stringify(obj), - * decode: (str) => JSON.parse(str), - * is: (val) => typeof(val) === 'object', - * pattern: /[^/]+/, - * equals: (a, b) => _.isEqual(a, b), - * }); - * ``` - * - * @param name The type name. - * @param type The type definition. See [[ParamTypeDefinition]] for examples and information. - * - * @returns if only the `name` parameter was specified: the currently registered [[ParamType]] object, or undefined - */ - type(name: string, type?: ParamTypeDefinition): ParamType; + /** See: [[UrlConfig.caseInsensitive]] */ caseInsensitive: UrlConfig['caseInsensitive']; + /** See: [[UrlConfig.strictMode]] */ strictMode: UrlConfig['strictMode']; + /** See: [[UrlConfig.defaultSquashPolicy]] */ defaultSquashPolicy: UrlConfig['defaultSquashPolicy']; + /** See: [[UrlConfig.type]] */ type: UrlConfig['type']; } -/** @internalapi */ +/** @internalapi @deprecated use [[UrlService]] */ export interface UrlSyncApi { - /** - * Checks the URL for a matching [[UrlRule]] - * - * Checks the current URL for a matching url rule, then invokes that rule's handler. - * This method is called internally any time the URL has changed. - * - * This effectively activates the state which matches the current URL. - * - * #### Example: - * ```js - * urlService.deferIntercept(); - * - * $http.get('/states.json').then(function(resp) { - * resp.data.forEach(state => $stateRegistry.register(state)); - * urlService.listen(); - * // Find the matching URL and invoke the handler. - * urlService.sync(); - * }); - * ``` - */ - sync(evt?): void; - - /** - * Starts or stops listening for URL changes - * - * Call this sometime after calling [[deferIntercept]] to start monitoring the url. - * This causes [[UrlRouter]] to start listening for changes to the URL, if it wasn't already listening. - * - * If called with `false`, will stop listening. Call listen() again to start listening - * - * #### Example: - * ```js - * urlService.deferIntercept(); - * - * $http.get('/states.json').then(function(resp) { - * resp.data.forEach(state => $stateRegistry.register(state)); - * // Start responding to URL changes - * urlService.listen(); - * urlService.sync(); - * }); - * ``` - */ - listen(enabled?: boolean): Function; - - /** - * Disables monitoring of the URL. - * - * Call this method before UI-Router has bootstrapped. - * It will stop UI-Router from performing the initial url sync. - * - * This can be useful to perform some asynchronous initialization before the router starts. - * Once the initialization is complete, call [[listen]] to tell UI-Router to start watching and synchronizing the URL. - * - * #### Example: - * ```js - * // Prevent $urlRouter from automatically intercepting URL changes when it starts; - * urlService.deferIntercept(); - * - * $http.get('/states.json').then(function(resp) { - * resp.data.forEach(state => $stateRegistry.register(state)); - * urlService.listen(); - * urlService.sync(); - * }); - * ``` - * - * @param defer Indicates whether to defer location change interception. - * Passing no parameter is equivalent to `true`. - */ - deferIntercept(defer?: boolean); + /** See: [[UrlService.sync]] */ sync: UrlService['sync']; + /** See: [[UrlService.listen]] */ listen: UrlService['listen']; + /** See: [[UrlService.deferIntercept]] */ deferIntercept: UrlService['deferIntercept']; } -/** - * API for managing URL rules - * - * This API can be used to create and manage URL rules. - * URL rules are a mechanism to respond to specific URL patterns. - * - * The most commonly used methods are [[otherwise]] and [[when]]. - */ +/** @internalapi @deprecated use [[UrlRules]] */ export interface UrlRulesApi { - /** - * Defines URL Rule priorities - * - * More than one rule ([[UrlRule]]) might match a given URL. - * This `compareFn` is used to sort the rules by priority. - * Higher priority rules should sort earlier. - * - * The [[defaultRuleSortFn]] is used by default. - * - * You only need to call this function once. - * The `compareFn` will be used to sort the rules as each is registered. - * - * If called without any parameter, it will re-sort the rules. - * - * --- - * - * Url rules may come from multiple sources: states's urls ([[StateDeclaration.url]]), [[when]], and [[rule]]. - * Each rule has a (user-provided) [[UrlRule.priority]], a [[UrlRule.type]], and a [[UrlRule.$id]] - * The `$id` is is the order in which the rule was registered. - * - * The sort function should use these data, or data found on a specific type - * of [[UrlRule]] (such as [[StateRule.state]]), to order the rules as desired. - * - * #### Example: - * This compare function prioritizes rules by the order in which the rules were registered. - * A rule registered earlier has higher priority. - * - * ```js - * function compareFn(a, b) { - * return a.$id - b.$id; - * } - * ``` - * - * @param compareFn a function that compares to [[UrlRule]] objects. - * The `compareFn` should abide by the `Array.sort` compare function rules. - * Given two rules, `a` and `b`, return a negative number if `a` should be higher priority. - * Return a positive number if `b` should be higher priority. - * Return `0` if the rules are identical. - * - * See the [mozilla reference](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort#Description) - * for details. - */ - sort(compareFn?: (a: UrlRule, b: UrlRule) => number); - - /** - * Registers a `matcher` and `handler` for custom URLs handling. - * - * The `matcher` can be: - * - * - a [[UrlMatcher]]: See: [[UrlMatcherFactory.compile]] - * - a `string`: The string is compiled to a [[UrlMatcher]] - * - a `RegExp`: The regexp is used to match the url. - * - * The `handler` can be: - * - * - a string: The url is redirected to the value of the string. - * - a function: The url is redirected to the return value of the function. - * - * --- - * - * When the `handler` is a `string` and the `matcher` is a `UrlMatcher` (or string), the redirect - * string is interpolated with parameter values. - * - * #### Example: - * When the URL is `/foo/123` the rule will redirect to `/bar/123`. - * ```js - * .when("/foo/:param1", "/bar/:param1") - * ``` - * - * --- - * - * When the `handler` is a string and the `matcher` is a `RegExp`, the redirect string is - * interpolated with capture groups from the RegExp. - * - * #### Example: - * When the URL is `/foo/123` the rule will redirect to `/bar/123`. - * ```js - * .when(new RegExp("^/foo/(.*)$"), "/bar/$1"); - * ``` - * - * --- - * - * When the handler is a function, it receives the matched value, the current URL, and the `UIRouter` object (See [[UrlRuleHandlerFn]]). - * The "matched value" differs based on the `matcher`. - * For [[UrlMatcher]]s, it will be the matched state params. - * For `RegExp`, it will be the match array from `regexp.exec()`. - * - * If the handler returns a string, the URL is redirected to the string. - * - * #### Example: - * When the URL is `/foo/123` the rule will redirect to `/bar/123`. - * ```js - * .when(new RegExp("^/foo/(.*)$"), match => "/bar/" + match[1]); - * ``` - * - * Note: the `handler` may also invoke arbitrary code, such as `$state.go()` - * - * @param matcher A pattern `string` to match, compiled as a [[UrlMatcher]], or a `RegExp`. - * @param handler The path to redirect to, or a function that returns the path. - * @param options `{ priority: number }` - * - * @return the registered [[UrlRule]] - */ - when( - matcher: RegExp | UrlMatcher | string, - handler: string | UrlRuleHandlerFn, - options?: { priority: number } - ): UrlRule; - - /** - * Defines the state, url, or behavior to use when no other rule matches the URL. - * - * This rule is matched when *no other rule* matches. - * It is generally used to handle unknown URLs (similar to "404" behavior, but on the client side). - * - * - If `handler` a string, it is treated as a url redirect - * - * #### Example: - * When no other url rule matches, redirect to `/index` - * ```js - * .otherwise('/index'); - * ``` - * - * - If `handler` is an object with a `state` property, the state is activated. - * - * #### Example: - * When no other url rule matches, redirect to `home` and provide a `dashboard` parameter value. - * ```js - * .otherwise({ state: 'home', params: { dashboard: 'default' } }); - * ``` - * - * - If `handler` is a function, the function receives the current url ([[UrlParts]]) and the [[UIRouter]] object. - * The function can perform actions, and/or return a value. - * - * #### Example: - * When no other url rule matches, manually trigger a transition to the `home` state - * ```js - * .otherwise((matchValue, urlParts, router) => { - * router.stateService.go('home'); - * }); - * ``` - * - * #### Example: - * When no other url rule matches, go to `home` state - * ```js - * .otherwise((matchValue, urlParts, router) => { - * return { state: 'home' }; - * }); - * ``` - * - * @param handler The url path to redirect to, or a function which returns the url path (or performs custom logic). - */ - otherwise(handler: string | UrlRuleHandlerFn | TargetState | TargetStateDef): void; - - /** - * Defines the initial state, path, or behavior to use when the app starts. - * - * This rule defines the initial/starting state for the application. - * - * This rule is triggered the first time the URL is checked (when the app initially loads). - * The rule is triggered only when the url matches either `""` or `"/"`. - * - * Note: The rule is intended to be used when the root of the application is directly linked to. - * When the URL is *not* `""` or `"/"` and doesn't match other rules, the [[otherwise]] rule is triggered. - * This allows 404-like behavior when an unknown URL is deep-linked. - * - * #### Example: - * Start app at `home` state. - * ```js - * .initial({ state: 'home' }); - * ``` - * - * #### Example: - * Start app at `/home` (by url) - * ```js - * .initial('/home'); - * ``` - * - * #### Example: - * When no other url rule matches, go to `home` state - * ```js - * .initial((matchValue, url, router) => { - * console.log('initial state'); - * return { state: 'home' }; - * }) - * ``` - * - * @param handler The initial state or url path, or a function which returns the state or url path (or performs custom logic). - */ - initial(handler: string | UrlRuleHandlerFn | TargetState | TargetStateDef): void; - - /** - * Gets all registered rules - * - * @returns an array of all the registered rules - */ - rules(): UrlRule[]; - - /** - * Manually adds a URL Rule. - * - * Usually, a url rule is added using [[StateDeclaration.url]] or [[when]]. - * This api can be used directly for more control (to register [[BaseUrlRule]], for example). - * Rules can be created using [[UrlRouter.urlRuleFactory]], or create manually as simple objects. - * - * @return a function that deregisters the rule - */ - rule(rule: UrlRule): Function; - - /** - * Remove a rule previously registered - * - * @param rule the matcher rule that was previously registered using [[rule]] - */ - removeRule(rule: UrlRule): void; + /** See: [[UrlRules.sort]] */ sort: UrlRules['sort']; + /** See: [[UrlRules.when]] */ when: UrlRules['when']; + /** See: [[UrlRules.otherwise]] */ otherwise: UrlRules['otherwise']; + /** See: [[UrlRules.initial]] */ initial: UrlRules['initial']; + /** See: [[UrlRules.rules]] */ rules: UrlRules['rules']; + /** See: [[UrlRules.rule]] */ rule: UrlRules['rule']; + /** See: [[UrlRules.removeRule]] */ removeRule: UrlRules['removeRule']; } /** @@ -438,6 +74,7 @@ export interface MatchResult { /** The match result weight */ weight: number; } + /** * A function that matches the URL for a [[UrlRule]] * @@ -469,7 +106,9 @@ export type UrlRuleType = 'STATE' | 'URLMATCHER' | 'REGEXP' | 'RAW' | 'OTHER'; /** * The interface for a URL Rule * - * If you are creating a rule for use with [[UrlRulesApi.rule]], it should implement this interface. + * If you are creating a rule for use with [[UrlRules.rule]], it should implement this interface. + * + * @publicapi */ export interface UrlRule { /** diff --git a/src/url/urlConfig.ts b/src/url/urlConfig.ts index 2c56f9b1..db7225a4 100644 --- a/src/url/urlConfig.ts +++ b/src/url/urlConfig.ts @@ -1,28 +1,166 @@ -import { UrlConfigApi } from './interface'; +/** @publicapi @module url */ /** */ import { Disposable } from '../interface'; import { UIRouter } from '../router'; -import { ParamType, ParamTypeDefinition } from '../params'; +import { ParamTypeDefinition, ParamTypes } from '../params'; +import { isDefined, isString } from '../common'; -export class UrlConfig implements UrlConfigApi, Disposable { - constructor(private router: UIRouter) {} +/** + * An API to customize the URL behavior and retrieve URL configuration + * + * This API is used to customize the behavior of the URL. + * This includes optional trailing slashes ([[strictMode]]), case sensitivity ([[caseInsensitive]]), + * and custom parameter encoding (custom [[type]]). + * + * It also has information about the location (url) configuration such as [[port]] and [[baseHref]]. + * This information can be used to build absolute URLs, such as + * `https://example.com:443/basepath/state/substate?param1=a#hashvalue`; + * + * This API is a property of [[UrlService]] as [[UrlService.config]]. + */ +export class UrlConfig implements Disposable { + /** @hidden */ paramTypes = new ParamTypes(); + /** @hidden */ _isCaseInsensitive = false; + /** @hidden */ _isStrictMode = true; + /** @hidden */ _defaultSquashPolicy: boolean | string = false; - public dispose(router?: UIRouter) {} + /** @hidden */ constructor(/** @hidden */ private router: UIRouter) {} + /** @internalapi */ public dispose = () => this.paramTypes.dispose(); // Delegate these calls to the current LocationConfig implementation - /** @inheritDoc */ public baseHref = (): string => this.router.locationConfig.baseHref(); - /** @inheritDoc */ public hashPrefix = (newprefix?: string): string => - this.router.locationConfig.hashPrefix(newprefix); - /** @inheritDoc */ public host = (): string => this.router.locationConfig.host(); - /** @inheritDoc */ public html5Mode = (): boolean => this.router.locationConfig.html5Mode(); - /** @inheritDoc */ public port = (): number => this.router.locationConfig.port(); - /** @inheritDoc */ public protocol = (): string => this.router.locationConfig.protocol(); - - // Delegate these calls to the UrlMatcherFactory - /** @inheritDoc */ public caseInsensitive = (value?: boolean): boolean => - this.router.urlMatcherFactory.caseInsensitive(value); - /** @inheritDoc */ public defaultSquashPolicy = (value?: boolean | string): boolean | string => - this.router.urlMatcherFactory.defaultSquashPolicy(value); - /** @inheritDoc */ public strictMode = (value?: boolean): boolean => this.router.urlMatcherFactory.strictMode(value); - /** @inheritDoc */ public type = (name: string, type?: ParamTypeDefinition): ParamType => - this.router.urlMatcherFactory.type(name, type); + + /** + * Gets the base Href, e.g., `http://localhost/approot/` + * + * @return the application's base href + */ + public baseHref = (): string => this.router.locationConfig.baseHref(); + + /** + * Gets or sets the hashPrefix + * + * This only applies when not running in [[html5Mode]] (pushstate mode) + * + * If the current url is `http://localhost/app#!/uirouter/path/#anchor`, it returns `!` which is the prefix for the "hashbang" portion. + * + * @return the hash prefix + */ + + public hashPrefix = (newprefix?: string): string => this.router.locationConfig.hashPrefix(newprefix); + /** + * Gets the host, e.g., `localhost` + * + * @return the protocol + */ + public host = (): string => this.router.locationConfig.host(); + + /** + * Returns true when running in pushstate mode + * + * @return true when running in html5 mode (pushstate mode). + */ + public html5Mode = (): boolean => this.router.locationConfig.html5Mode(); + + /** + * Gets the port, e.g., `80` + * + * @return the port number + */ + public port = (): number => this.router.locationConfig.port(); + + /** + * Gets the protocol, e.g., `http` + * + * @return the protocol + */ + public protocol = (): string => this.router.locationConfig.protocol(); + + /** + * Defines whether URL matching should be case sensitive (the default behavior), or not. + * + * #### Example: + * ```js + * // Allow case insensitive url matches + * urlService.config.caseInsensitive(true); + * ``` + * + * @param value `false` to match URL in a case sensitive manner; otherwise `true`; + * @returns the current value of caseInsensitive + */ + public caseInsensitive(value?: boolean): boolean { + return (this._isCaseInsensitive = isDefined(value) ? value : this._isCaseInsensitive); + } + + /** + * Sets the default behavior when generating or matching URLs with default parameter values. + * + * #### Example: + * ```js + * // Remove default parameter values from the url + * urlService.config.defaultSquashPolicy(true); + * ``` + * + * @param value A string that defines the default parameter URL squashing behavior. + * - `nosquash`: When generating an href with a default parameter value, do not squash the parameter value from the URL + * - `slash`: When generating an href with a default parameter value, squash (remove) the parameter value, and, if the + * parameter is surrounded by slashes, squash (remove) one slash from the URL + * - any other string, e.g. "~": When generating an href with a default parameter value, squash (remove) + * the parameter value from the URL and replace it with this string. + * @returns the current value of defaultSquashPolicy + */ + public defaultSquashPolicy(value?: boolean | string) { + if (isDefined(value) && value !== true && value !== false && !isString(value)) + throw new Error(`Invalid squash policy: ${value}. Valid policies: false, true, arbitrary-string`); + return (this._defaultSquashPolicy = isDefined(value) ? value : this._defaultSquashPolicy); + } + + /** + * Defines whether URLs should match trailing slashes, or not (the default behavior). + * + * #### Example: + * ```js + * // Allow optional trailing slashes + * urlService.config.strictMode(false); + * ``` + * + * @param value `false` to match trailing slashes in URLs, otherwise `true`. + * @returns the current value of strictMode + */ + public strictMode(value?: boolean): boolean { + return (this._isStrictMode = isDefined(value) ? value : this._isStrictMode); + } + + /** + * Creates and registers a custom [[ParamType]] object + * + * A custom parameter type can be used to generate URLs with typed parameters or custom encoding/decoding. + * + * #### Note: Register custom types *before using them* in a state definition. + * + * #### Example: + * ```js + * // Encode object parameter as JSON string + * urlService.config.type('myjson', { + * encode: (obj) => JSON.stringify(obj), + * decode: (str) => JSON.parse(str), + * is: (val) => typeof(val) === 'object', + * pattern: /[^/]+/, + * equals: (a, b) => _.isEqual(a, b), + * }); + * ``` + * + * See [[ParamTypeDefinition]] for more examples + * + * @param name The type name. + * @param definition The type definition. See [[ParamTypeDefinition]] for information on the values accepted. + * @param definitionFn A function that is injected before the app runtime starts. + * The result of this function should be a [[ParamTypeDefinition]]. + * The result is merged into the existing `definition`. + * See [[ParamType]] for information on the values accepted. + * + * @returns if only the `name` parameter was specified: the currently registered [[ParamType]] object, or undefined + */ + type(name: string, definition?: ParamTypeDefinition, definitionFn?: () => ParamTypeDefinition) { + const type = this.paramTypes.type(name, definition, definitionFn); + return !isDefined(definition) ? type : this; + } } diff --git a/src/url/urlMatcher.ts b/src/url/urlMatcher.ts index e71165ca..6e4ea905 100644 --- a/src/url/urlMatcher.ts +++ b/src/url/urlMatcher.ts @@ -1,8 +1,4 @@ -/** - * @coreapi - * @module url - */ -/** for typedoc */ +/** @publicapi @module url */ /** */ import { map, inherit, identity, unnest, tail, find, Obj, allTrueR, unnestR, arrayTuples } from '../common/common'; import { prop, propEq } from '../common/hof'; import { isArray, isString, isDefined } from '../common/predicates'; @@ -59,6 +55,7 @@ interface MatchDetails { type: ParamType; } +/** @hidden */ const defaultConfig: UrlMatcherCompileConfig = { state: { params: {} }, strict: true, diff --git a/src/url/urlMatcherFactory.ts b/src/url/urlMatcherFactory.ts index 4e53612b..e82c565b 100644 --- a/src/url/urlMatcherFactory.ts +++ b/src/url/urlMatcherFactory.ts @@ -1,33 +1,26 @@ -/** - * @internalapi - * @module url - */ /** for typedoc */ -import { forEach, extend } from '../common/common'; -import { isObject, isDefined, isFunction, isString } from '../common/predicates'; +/** @publicapi @module url */ /** */ +import { extend, forEach, isDefined, isFunction, isObject } from '../common'; import { UrlMatcher } from './urlMatcher'; -import { Param, DefType } from '../params/param'; -import { ParamTypes } from '../params/paramTypes'; -import { ParamTypeDefinition } from '../params/interface'; -import { Disposable } from '../interface'; -import { ParamType } from '../params/paramType'; -import { UrlMatcherCompileConfig, UrlMatcherConfig } from './interface'; +import { DefType, Param, ParamType, ParamTypeDefinition } from '../params'; +import { UrlMatcherCompileConfig } from './interface'; import { StateDeclaration } from '../state'; +import { UIRouter } from '../router'; /** @internalapi */ export class ParamFactory { fromConfig(id: string, type: ParamType, state: StateDeclaration) { - return new Param(id, type, DefType.CONFIG, this.umf, state); + return new Param(id, type, DefType.CONFIG, this.router.urlService.config, state); } fromPath(id: string, type: ParamType, state: StateDeclaration) { - return new Param(id, type, DefType.PATH, this.umf, state); + return new Param(id, type, DefType.PATH, this.router.urlService.config, state); } fromSearch(id: string, type: ParamType, state: StateDeclaration) { - return new Param(id, type, DefType.SEARCH, this.umf, state); + return new Param(id, type, DefType.SEARCH, this.router.urlService.config, state); } - constructor(private umf: UrlMatcherFactory) {} + constructor(private router: UIRouter) {} } /** @@ -35,38 +28,18 @@ export class ParamFactory { * * The factory is available to ng1 services as * `$urlMatcherFactory` or ng1 providers as `$urlMatcherFactoryProvider`. + * + * @internalapi */ -export class UrlMatcherFactory implements Disposable, UrlMatcherConfig { - /** @hidden */ paramTypes = new ParamTypes(); - /** @hidden */ _isCaseInsensitive = false; - /** @hidden */ _isStrictMode = true; - /** @hidden */ _defaultSquashPolicy: boolean | string = false; - +export class UrlMatcherFactory { /** @internalapi Creates a new [[Param]] for a given location (DefType) */ - paramFactory = new ParamFactory(this); + paramFactory = new ParamFactory(this.router); // TODO: move implementations to UrlConfig (urlService.config) - constructor() { + constructor(/** @hidden */ private router: UIRouter) { extend(this, { UrlMatcher, Param }); } - /** @inheritdoc */ - caseInsensitive(value?: boolean): boolean { - return (this._isCaseInsensitive = isDefined(value) ? value : this._isCaseInsensitive); - } - - /** @inheritdoc */ - strictMode(value?: boolean): boolean { - return (this._isStrictMode = isDefined(value) ? value : this._isStrictMode); - } - - /** @inheritdoc */ - defaultSquashPolicy(value?: boolean | string) { - if (isDefined(value) && value !== true && value !== false && !isString(value)) - throw new Error(`Invalid squash policy: ${value}. Valid policies: false, true, arbitrary-string`); - return (this._defaultSquashPolicy = isDefined(value) ? value : this._defaultSquashPolicy); - } - /** * Creates a [[UrlMatcher]] for the specified pattern. * @@ -75,11 +48,12 @@ export class UrlMatcherFactory implements Disposable, UrlMatcherConfig { * @returns The UrlMatcher. */ compile(pattern: string, config?: UrlMatcherCompileConfig) { + const urlConfig = this.router.urlService.config; // backward-compatible support for config.params -> config.state.params const params = config && !config.state && (config as any).params; config = params ? { state: { params }, ...config } : config; - const globalConfig = { strict: this._isStrictMode, caseInsensitive: this._isCaseInsensitive }; - return new UrlMatcher(pattern, this.paramTypes, this.paramFactory, extend(globalConfig, config)); + const globalConfig = { strict: urlConfig._isStrictMode, caseInsensitive: urlConfig._isCaseInsensitive }; + return new UrlMatcher(pattern, urlConfig.paramTypes, this.paramFactory, extend(globalConfig, config)); } /** @@ -100,39 +74,25 @@ export class UrlMatcherFactory implements Disposable, UrlMatcherConfig { return result; } - /** - * Creates and registers a custom [[ParamType]] object - * - * A [[ParamType]] can be used to generate URLs with typed parameters. - * - * @param name The type name. - * @param definition The type definition. See [[ParamTypeDefinition]] for information on the values accepted. - * @param definitionFn A function that is injected before the app runtime starts. - * The result of this function should be a [[ParamTypeDefinition]]. - * The result is merged into the existing `definition`. - * See [[ParamType]] for information on the values accepted. - * - * @returns - if a type was registered: the [[UrlMatcherFactory]] - * - if only the `name` parameter was specified: the currently registered [[ParamType]] object, or undefined - * - * Note: Register custom types *before using them* in a state definition. - * - * See [[ParamTypeDefinition]] for examples - */ - type(name: string, definition?: ParamTypeDefinition, definitionFn?: () => ParamTypeDefinition) { - const type = this.paramTypes.type(name, definition, definitionFn); - return !isDefined(definition) ? type : this; - } - /** @hidden */ $get() { - this.paramTypes.enqueue = false; - this.paramTypes._flushTypeQueue(); + const urlConfig = this.router.urlService.config; + urlConfig.paramTypes.enqueue = false; + urlConfig.paramTypes._flushTypeQueue(); return this; } - /** @internalapi */ - dispose() { - this.paramTypes.dispose(); - } + /** @deprecated use [[UrlConfig.caseInsensitive]] */ + caseInsensitive = (value?: boolean) => this.router.urlService.config.caseInsensitive(value); + + /** @deprecated use [[UrlConfig.defaultSquashPolicy]] */ + defaultSquashPolicy = (value?: boolean | string) => this.router.urlService.config.defaultSquashPolicy(value); + + /** @deprecated use [[UrlConfig.strictMode]] */ + strictMode = (value?: boolean) => this.router.urlService.config.strictMode(value); + + /** @deprecated use [[UrlConfig.type]] */ + type = (name: string, definition?: ParamTypeDefinition, definitionFn?: () => ParamTypeDefinition) => { + return this.router.urlService.config.type(name, definition, definitionFn) || this; + }; } diff --git a/src/url/urlRouter.ts b/src/url/urlRouter.ts index fd182be9..f47cfa68 100644 --- a/src/url/urlRouter.ts +++ b/src/url/urlRouter.ts @@ -1,8 +1,4 @@ -/** - * @internalapi - * @module url - */ -/** for typedoc */ +/** @publicapi @module url */ /** */ import { stripLastPathElement } from '../common'; import { UrlMatcher } from './urlMatcher'; import { RawParams } from '../params'; @@ -25,7 +21,9 @@ function appendBasePath(url: string, isHtml5: boolean, absolute: boolean, baseHr * ### Deprecation warning: * This class is now considered to be an internal API * Use the [[UrlService]] instead. - * For configuring URL rules, use the [[UrlRulesApi]] which can be found as [[UrlService.rules]]. + * For configuring URL rules, use the [[UrlRules]] which can be found as [[UrlService.rules]]. + * + * @internalapi */ export class UrlRouter { /** used to create [[UrlRule]] objects for common cases */ diff --git a/src/url/urlRule.ts b/src/url/urlRule.ts index ed34d448..a8d93ed4 100644 --- a/src/url/urlRule.ts +++ b/src/url/urlRule.ts @@ -1,7 +1,4 @@ -/** - * @coreapi - * @module url - */ /** */ +/** @publicapi @module url */ /** */ import { UrlMatcher } from './urlMatcher'; import { isString, isDefined, isFunction } from '../common/predicates'; import { UIRouter } from '../router'; diff --git a/src/url/urlRules.ts b/src/url/urlRules.ts index be972681..69b354af 100644 --- a/src/url/urlRules.ts +++ b/src/url/urlRules.ts @@ -1,3 +1,4 @@ +/** @publicapi @module url */ /** */ import { UIRouter } from '../router'; import { Disposable } from '../interface'; import { MatcherUrlRule, UrlRule, UrlRuleHandlerFn, UrlRuleMatchFn, UrlRulesApi } from './interface'; @@ -32,14 +33,14 @@ const idSort = (a: UrlRule, b: UrlRule) => { * * Sorts rules by: * - * - Explicit priority (set rule priority using [[UrlRulesApi.when]]) + * - Explicit priority (set rule priority using [[UrlRules.when]]) * - Rule type (STATE: 4, URLMATCHER: 4, REGEXP: 3, RAW: 2, OTHER: 1) * - `UrlMatcher` specificity ([[UrlMatcher.compare]]): works for STATE and URLMATCHER types to pick the most specific rule. * - Rule registration order (for rule types other than STATE and URLMATCHER) * - Equally sorted State and UrlMatcher rules will each match the URL. * Then, the *best* match is chosen based on how many parameter values were matched. * - * @coreapi + * @publicapi */ let defaultRuleSortFn: (a: UrlRule, b: UrlRule) => number; defaultRuleSortFn = (a, b) => { @@ -55,6 +56,7 @@ defaultRuleSortFn = (a, b) => { return idSort(a, b); }; +/** @hidden */ function getHandlerFn(handler: string | UrlRuleHandlerFn | TargetState | TargetStateDef): UrlRuleHandlerFn { if (!isFunction(handler) && !isString(handler) && !is(TargetState)(handler) && !TargetState.isDef(handler)) { throw new Error("'handler' must be a string, function, TargetState, or have a state: 'newtarget' property"); @@ -62,7 +64,19 @@ function getHandlerFn(handler: string | UrlRuleHandlerFn | TargetState | TargetS return isFunction(handler) ? (handler as UrlRuleHandlerFn) : val(handler); } -export class UrlRules implements UrlRulesApi, Disposable { +/** + * API for managing URL rules + * + * This API is used to create and manage URL rules. + * URL rules are a mechanism to respond to specific URL patterns. + * + * The most commonly used methods are [[otherwise]] and [[when]]. + * + * This API is a property of [[UrlService]] as [[UrlService.rules]] + * + * @publicapi + */ +export class UrlRules implements Disposable { /** used to create [[UrlRule]] objects for common cases */ public urlRuleFactory: UrlRuleFactory; @@ -72,16 +86,52 @@ export class UrlRules implements UrlRulesApi, Disposable { /** @hidden */ private _rules: UrlRule[] = []; /** @hidden */ private _id = 0; - constructor(private router: UIRouter) { + /** @hidden */ + constructor(/** @hidden */ private router: UIRouter) { this.urlRuleFactory = new UrlRuleFactory(router); } + /** @hidden */ public dispose(router?: UIRouter) { this._rules = []; delete this._otherwiseFn; } - /** @inheritdoc */ + /** + * Defines the initial state, path, or behavior to use when the app starts. + * + * This rule defines the initial/starting state for the application. + * + * This rule is triggered the first time the URL is checked (when the app initially loads). + * The rule is triggered only when the url matches either `""` or `"/"`. + * + * Note: The rule is intended to be used when the root of the application is directly linked to. + * When the URL is *not* `""` or `"/"` and doesn't match other rules, the [[otherwise]] rule is triggered. + * This allows 404-like behavior when an unknown URL is deep-linked. + * + * #### Example: + * Start app at `home` state. + * ```js + * .initial({ state: 'home' }); + * ``` + * + * #### Example: + * Start app at `/home` (by url) + * ```js + * .initial('/home'); + * ``` + * + * #### Example: + * When no other url rule matches, go to `home` state + * ```js + * .initial((matchValue, url, router) => { + * console.log('initial state'); + * return { state: 'home' }; + * }) + * ``` + * + * @param handler The initial state or url path, or a function which returns the state or url path (or performs custom logic). + */ public initial(handler: string | UrlRuleHandlerFn | TargetState | TargetStateDef) { const handlerFn: UrlRuleHandlerFn = getHandlerFn(handler); const matchFn: UrlRuleMatchFn = (urlParts, router) => @@ -90,7 +140,49 @@ export class UrlRules implements UrlRulesApi, Disposable { this.rule(this.urlRuleFactory.create(matchFn, handlerFn)); } - /** @inheritdoc */ + /** + * Defines the state, url, or behavior to use when no other rule matches the URL. + * + * This rule is matched when *no other rule* matches. + * It is generally used to handle unknown URLs (similar to "404" behavior, but on the client side). + * + * - If `handler` a string, it is treated as a url redirect + * + * #### Example: + * When no other url rule matches, redirect to `/index` + * ```js + * .otherwise('/index'); + * ``` + * + * - If `handler` is an object with a `state` property, the state is activated. + * + * #### Example: + * When no other url rule matches, redirect to `home` and provide a `dashboard` parameter value. + * ```js + * .otherwise({ state: 'home', params: { dashboard: 'default' } }); + * ``` + * + * - If `handler` is a function, the function receives the current url ([[UrlParts]]) and the [[UIRouter]] object. + * The function can perform actions, and/or return a value. + * + * #### Example: + * When no other url rule matches, manually trigger a transition to the `home` state + * ```js + * .otherwise((matchValue, urlParts, router) => { + * router.stateService.go('home'); + * }); + * ``` + * + * #### Example: + * When no other url rule matches, go to `home` state + * ```js + * .otherwise((matchValue, urlParts, router) => { + * return { state: 'home' }; + * }); + * ``` + * + * @param handler The url path to redirect to, or a function which returns the url path (or performs custom logic). + */ public otherwise(handler: string | UrlRuleHandlerFn | TargetState | TargetStateDef) { const handlerFn: UrlRuleHandlerFn = getHandlerFn(handler); @@ -98,7 +190,11 @@ export class UrlRules implements UrlRulesApi, Disposable { this._sorted = false; } - /** @inheritdoc */ + /** + * Remove a rule previously registered + * + * @param rule the matcher rule that was previously registered using [[rule]] + */ public removeRule(rule): void { removeFrom(this._rules, rule); } @@ -108,7 +204,7 @@ export class UrlRules implements UrlRulesApi, Disposable { * * Usually, a url rule is added using [[StateDeclaration.url]] or [[when]]. * This api can be used directly for more control (to register a [[BaseUrlRule]], for example). - * Rules can be created using [[UrlRouter.urlRuleFactory]], or create manually as simple objects. + * Rules can be created using [[urlRuleFactory]], or created manually as simple objects. * * A rule should have a `match` function which returns truthy if the rule matched. * It should also have a `handler` function which is invoked if the rule is the best match. @@ -126,13 +222,58 @@ export class UrlRules implements UrlRulesApi, Disposable { return () => this.removeRule(rule); } - /** @inheritdoc */ + /** + * Gets all registered rules + * + * @returns an array of all the registered rules + */ public rules(): UrlRule[] { this.ensureSorted(); return this._rules.concat(this._otherwiseFn ? [this._otherwiseFn] : []); } - /** @inheritdoc */ + /** + * Defines URL Rule priorities + * + * More than one rule ([[UrlRule]]) might match a given URL. + * This `compareFn` is used to sort the rules by priority. + * Higher priority rules should sort earlier. + * + * The [[defaultRuleSortFn]] is used by default. + * + * You only need to call this function once. + * The `compareFn` will be used to sort the rules as each is registered. + * + * If called without any parameter, it will re-sort the rules. + * + * --- + * + * Url rules may come from multiple sources: states's urls ([[StateDeclaration.url]]), [[when]], and [[rule]]. + * Each rule has a (user-provided) [[UrlRule.priority]], a [[UrlRule.type]], and a [[UrlRule.$id]] + * The `$id` is is the order in which the rule was registered. + * + * The sort function should use these data, or data found on a specific type + * of [[UrlRule]] (such as [[StateRule.state]]), to order the rules as desired. + * + * #### Example: + * This compare function prioritizes rules by the order in which the rules were registered. + * A rule registered earlier has higher priority. + * + * ```js + * function compareFn(a, b) { + * return a.$id - b.$id; + * } + * ``` + * + * @param compareFn a function that compares to [[UrlRule]] objects. + * The `compareFn` should abide by the `Array.sort` compare function rules. + * Given two rules, `a` and `b`, return a negative number if `a` should be higher priority. + * Return a positive number if `b` should be higher priority. + * Return `0` if the rules are identical. + * + * See the [mozilla reference](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort#Description) + * for details. + */ sort(compareFn?: (a: UrlRule, b: UrlRule) => number) { const sorted = this.stableSort(this._rules, (this._sortFn = compareFn || this._sortFn)); @@ -149,10 +290,12 @@ export class UrlRules implements UrlRulesApi, Disposable { this._sorted = true; } + /** @hidden */ private ensureSorted() { this._sorted || this.sort(); } + /** @hidden */ private stableSort(arr, compareFn) { const arrOfWrapper = arr.map((elem, idx) => ({ elem, idx })); @@ -164,7 +307,65 @@ export class UrlRules implements UrlRulesApi, Disposable { return arrOfWrapper.map(wrapper => wrapper.elem); } - /** @inheritdoc */ + /** + * Registers a `matcher` and `handler` for custom URLs handling. + * + * The `matcher` can be: + * + * - a [[UrlMatcher]]: See: [[UrlMatcherFactory.compile]] + * - a `string`: The string is compiled to a [[UrlMatcher]] + * - a `RegExp`: The regexp is used to match the url. + * + * The `handler` can be: + * + * - a string: The url is redirected to the value of the string. + * - a function: The url is redirected to the return value of the function. + * + * --- + * + * When the `handler` is a `string` and the `matcher` is a `UrlMatcher` (or string), the redirect + * string is interpolated with parameter values. + * + * #### Example: + * When the URL is `/foo/123` the rule will redirect to `/bar/123`. + * ```js + * .when("/foo/:param1", "/bar/:param1") + * ``` + * + * --- + * + * When the `handler` is a string and the `matcher` is a `RegExp`, the redirect string is + * interpolated with capture groups from the RegExp. + * + * #### Example: + * When the URL is `/foo/123` the rule will redirect to `/bar/123`. + * ```js + * .when(new RegExp("^/foo/(.*)$"), "/bar/$1"); + * ``` + * + * --- + * + * When the handler is a function, it receives the matched value, the current URL, and the `UIRouter` object (See [[UrlRuleHandlerFn]]). + * The "matched value" differs based on the `matcher`. + * For [[UrlMatcher]]s, it will be the matched state params. + * For `RegExp`, it will be the match array from `regexp.exec()`. + * + * If the handler returns a string, the URL is redirected to the string. + * + * #### Example: + * When the URL is `/foo/123` the rule will redirect to `/bar/123`. + * ```js + * .when(new RegExp("^/foo/(.*)$"), match => "/bar/" + match[1]); + * ``` + * + * Note: the `handler` may also invoke arbitrary code, such as `$state.go()` + * + * @param matcher A pattern `string` to match, compiled as a [[UrlMatcher]], or a `RegExp`. + * @param handler The path to redirect to, or a function that returns the path. + * @param options `{ priority: number }` + * + * @return the registered [[UrlRule]] + */ public when( matcher: RegExp | UrlMatcher | string, handler: string | UrlRuleHandlerFn, diff --git a/src/url/urlService.ts b/src/url/urlService.ts index 7cca3946..4e3ddf64 100644 --- a/src/url/urlService.ts +++ b/src/url/urlService.ts @@ -1,7 +1,4 @@ -/** - * @coreapi - * @module url - */ /** */ +/** @publicapi @module url */ /** */ import { UIRouter } from '../router'; import { extend, is, isString, LocationServices, pattern } from '../common'; import { MatchResult, UrlParts, UrlRule, UrlSyncApi } from './interface'; @@ -15,36 +12,56 @@ export class UrlService implements LocationServices, UrlSyncApi { /** @hidden */ interceptDeferred = false; /** - * A nested API for managing URL rules and rewrites + * The nested [[UrlRules]] API for managing URL rules and rewrites * - * See: [[UrlRulesApi]] for details + * See: [[UrlRules]] for details */ public rules = new UrlRules(this.router); + /** - * A nested API to configure the URL and retrieve URL information + * The nested [[UrlConfig]] API to configure the URL and retrieve URL information * - * See: [[UrlConfigApi]] for details + * See: [[UrlConfig]] for details */ public config = new UrlConfig(this.router); - constructor(/** @hidden */ private router: UIRouter) {} + /** @hidden */ + constructor(/** @hidden */ private router: UIRouter) {} + /** @hidden */ public dispose() { this.listen(false); (this.rules as UrlRules).dispose(); } /** - * Returns the current URL parts + * Gets the current URL parts * - * This method returns the current URL components as a [[UrlParts]] object. - * - * @returns the current url parts + * This method returns the different parts of the current URL (the [[path]], [[search]], and [[hash]]) as a [[UrlParts]] object. */ public parts(): UrlParts { return { path: this.path(), search: this.search(), hash: this.hash() }; } - /** @inheritdoc */ + /** + * Activates the best rule for the current URL + * + * Checks the current URL for a matching [[UrlRule]], then invokes that rule's handler. + * This method is called internally any time the URL has changed. + * + * This effectively activates the state (or redirect, etc) which matches the current URL. + * + * #### Example: + * ```js + * urlService.deferIntercept(); + * + * fetch('/states.json').then(resp => resp.json()).then(data => { + * data.forEach(state => $stateRegistry.register(state)); + * urlService.listen(); + * // Find the matching URL and invoke the handler. + * urlService.sync(); + * }); + * ``` + */ public sync(evt?) { if (evt && evt.defaultPrevented) return; const { urlService, stateService } = this.router; @@ -61,7 +78,28 @@ export class UrlService implements LocationServices, UrlSyncApi { applyResult(best && best.rule.handler(best.match, url, this.router)); } - /** @inheritdoc */ + /** + * Starts or stops listening for URL changes + * + * Call this sometime after calling [[deferIntercept]] to start monitoring the url. + * This causes UI-Router to start listening for changes to the URL, if it wasn't already listening. + * + * If called with `false`, UI-Router will stop listening (call listen(true) to start listening again). + * + * #### Example: + * ```js + * urlService.deferIntercept(); + * + * fetch('/states.json').then(resp => resp.json()).then(data => { + * data.forEach(state => $stateRegistry.register(state)); + * // Start responding to URL changes + * urlService.listen(); + * urlService.sync(); + * }); + * ``` + * + * @param enabled `true` or `false` to start or stop listening to URL changes + */ public listen(enabled?: boolean): Function { if (enabled === false) { this._stopListeningFn && this._stopListeningFn(); @@ -71,16 +109,40 @@ export class UrlService implements LocationServices, UrlSyncApi { } } - /** @inheritdoc */ + /** + * Disables monitoring of the URL. + * + * Call this method before UI-Router has bootstrapped. + * It will stop UI-Router from performing the initial url sync. + * + * This can be useful to perform some asynchronous initialization before the router starts. + * Once the initialization is complete, call [[listen]] to tell UI-Router to start watching and synchronizing the URL. + * + * #### Example: + * ```js + * // Prevent UI-Router from automatically intercepting URL changes when it starts; + * urlService.deferIntercept(); + * + * fetch('/states.json').then(resp => resp.json()).then(data => { + * data.forEach(state => $stateRegistry.register(state)); + * urlService.listen(); + * urlService.sync(); + * }); + * ``` + * + * @param defer Indicates whether to defer location change interception. + * Passing no parameter is equivalent to `true`. + */ public deferIntercept(defer?: boolean) { if (defer === undefined) defer = true; this.interceptDeferred = defer; } /** - * Given a URL, check all rules and return the best [[MatchResult]] - * @param url - * @returns {MatchResult} + * Matches a URL + * + * Given a URL (as a [[UrlParts]] object), check all rules and determine the best matching rule. + * Return the result as a [[MatchResult]]. */ public match(url: UrlParts): MatchResult { url = extend({ path: '', search: {}, hash: '' }, url); @@ -110,10 +172,102 @@ export class UrlService implements LocationServices, UrlSyncApi { } // Delegate these calls to the current LocationServices implementation - /** @inheritdoc */ public url = (newurl?: string, replace?: boolean, state?: any): string => + /** + * Gets the current url, or updates the url + * + * ### Getting the current URL + * + * When no arguments are passed, returns the current URL. + * The URL is normalized using the internal [[path]]/[[search]]/[[hash]] values. + * + * For example, the URL may be stored in the hash ([[HashLocationServices]]) or + * have a base HREF prepended ([[PushStateLocationServices]]). + * + * The raw URL in the browser might be: + * + * ``` + * http://mysite.com/somepath/index.html#/internal/path/123?param1=foo#anchor + * ``` + * + * or + * + * ``` + * http://mysite.com/basepath/internal/path/123?param1=foo#anchor + * ``` + * + * then this method returns: + * + * ``` + * /internal/path/123?param1=foo#anchor + * ``` + * + * + * #### Example: + * ```js + * locationServices.url(); // "/some/path?query=value#anchor" + * ``` + * + * ### Updating the URL + * + * When `newurl` arguments is provided, changes the URL to reflect `newurl` + * + * #### Example: + * ```js + * locationServices.url("/some/path?query=value#anchor", true); + * ``` + * + * @param newurl The new value for the URL. + * This url should reflect only the new internal [[path]], [[search]], and [[hash]] values. + * It should not include the protocol, site, port, or base path of an absolute HREF. + * @param replace When true, replaces the current history entry (instead of appending it) with this new url + * @param state The history's state object, i.e., pushState (if the LocationServices implementation supports it) + * + * @return the url (after potentially being processed) + */ + public url = (newurl?: string, replace?: boolean, state?: any): string => this.router.locationService.url(newurl, replace, state); - /** @inheritdoc */ public path = (): string => this.router.locationService.path(); - /** @inheritdoc */ public search = (): { [key: string]: any } => this.router.locationService.search(); - /** @inheritdoc */ public hash = (): string => this.router.locationService.hash(); - /** @inheritdoc */ public onChange = (callback: Function): Function => this.router.locationService.onChange(callback); + + /** + * Gets the path part of the current url + * + * If the current URL is `/some/path?query=value#anchor`, this returns `/some/path` + * + * @return the path portion of the url + */ + public path = (): string => this.router.locationService.path(); + + /** + * Gets the search part of the current url as an object + * + * If the current URL is `/some/path?query=value#anchor`, this returns `{ query: 'value' }` + * + * @return the search (query) portion of the url, as an object + */ + public search = (): { [key: string]: any } => this.router.locationService.search(); + + /** + * Gets the hash part of the current url + * + * If the current URL is `/some/path?query=value#anchor`, this returns `anchor` + * + * @return the hash (anchor) portion of the url + */ + public hash = (): string => this.router.locationService.hash(); + + /** + * @internalapi + * + * Registers a low level url change handler + * + * Note: Because this is a low level handler, it's not recommended for general use. + * + * #### Example: + * ```js + * let deregisterFn = locationServices.onChange((evt) => console.log("url change", evt)); + * ``` + * + * @param callback a function that will be called when the url is changing + * @return a function that de-registers the callback + */ + public onChange = (callback: Function): Function => this.router.locationService.onChange(callback); } diff --git a/src/vanilla.ts b/src/vanilla.ts index 4c6f6076..7f93991b 100644 --- a/src/vanilla.ts +++ b/src/vanilla.ts @@ -1,6 +1,2 @@ -/** - * @internalapi - * @module vanilla - */ -/** */ +/** @internalapi @module vanilla */ /** */ export * from './vanilla/index'; diff --git a/src/vanilla/baseLocationService.ts b/src/vanilla/baseLocationService.ts index b359d296..f27d897e 100644 --- a/src/vanilla/baseLocationService.ts +++ b/src/vanilla/baseLocationService.ts @@ -1,8 +1,4 @@ -/** - * @internalapi - * @module vanilla - */ /** */ - +/** @internalapi @module vanilla */ /** */ import { deregAll, isDefined, LocationServices, removeFrom, root } from '../common'; import { Disposable } from '../interface'; import { UIRouter } from '../router'; diff --git a/src/vanilla/browserLocationConfig.ts b/src/vanilla/browserLocationConfig.ts index 7649896a..2c5ee7f3 100644 --- a/src/vanilla/browserLocationConfig.ts +++ b/src/vanilla/browserLocationConfig.ts @@ -1,8 +1,4 @@ -/** - * @internalapi - * @module vanilla - */ -/** */ +/** @internalapi @module vanilla */ /** */ import { isDefined, isUndefined } from '../common/predicates'; import { LocationConfig } from '../common/coreservices'; diff --git a/src/vanilla/hashLocationService.ts b/src/vanilla/hashLocationService.ts index 0a2c7c1e..501c24d0 100644 --- a/src/vanilla/hashLocationService.ts +++ b/src/vanilla/hashLocationService.ts @@ -1,8 +1,4 @@ -/** - * @internalapi - * @module vanilla - */ -/** */ +/** @internalapi @module vanilla */ /** */ import { root, trimHashVal } from '../common'; import { UIRouter } from '../router'; import { BaseLocationServices } from './baseLocationService'; diff --git a/src/vanilla/index.ts b/src/vanilla/index.ts index 5b1bc467..8885ded2 100644 --- a/src/vanilla/index.ts +++ b/src/vanilla/index.ts @@ -1,11 +1,8 @@ /** * Naive, pure JS implementation of core ui-router services * - * - * @internalapi - * @module vanilla - */ -/** */ + * @internalapi @module vanilla + */ /** */ export * from './interface'; export * from './q'; diff --git a/src/vanilla/injector.ts b/src/vanilla/injector.ts index 62fbf807..dbfe8a4f 100644 --- a/src/vanilla/injector.ts +++ b/src/vanilla/injector.ts @@ -1,8 +1,4 @@ -/** - * @internalapi - * @module vanilla - */ -/** */ +/** @internalapi @module vanilla */ /** */ import { extend, assertPredicate, diff --git a/src/vanilla/interface.ts b/src/vanilla/interface.ts index ee04ee5e..6ff1dd71 100644 --- a/src/vanilla/interface.ts +++ b/src/vanilla/interface.ts @@ -1,8 +1,4 @@ -/** - * @internalapi - * @module vanilla - */ -/** */ +/** @internalapi @module vanilla */ /** */ import { LocationConfig, LocationServices } from '../common/coreservices'; import { UIRouterPlugin } from '../interface'; import { $InjectorLike, $QLike } from '../common/index'; diff --git a/src/vanilla/memoryLocationConfig.ts b/src/vanilla/memoryLocationConfig.ts index 8eda8fc9..97cc4bf7 100644 --- a/src/vanilla/memoryLocationConfig.ts +++ b/src/vanilla/memoryLocationConfig.ts @@ -1,8 +1,4 @@ -/** - * @internalapi - * @module vanilla - */ -/** */ +/** @internalapi @module vanilla */ /** */ import { LocationConfig } from '../common/coreservices'; import { isDefined } from '../common/predicates'; import { noop } from '../common/common'; diff --git a/src/vanilla/memoryLocationService.ts b/src/vanilla/memoryLocationService.ts index 17252411..503ba8d5 100644 --- a/src/vanilla/memoryLocationService.ts +++ b/src/vanilla/memoryLocationService.ts @@ -1,8 +1,4 @@ -/** - * @internalapi - * @module vanilla - */ -/** */ +/** @internalapi @module vanilla */ /** */ import { BaseLocationServices } from './baseLocationService'; import { UIRouter } from '../router'; diff --git a/src/vanilla/plugins.ts b/src/vanilla/plugins.ts index 92620516..c5f54b6d 100644 --- a/src/vanilla/plugins.ts +++ b/src/vanilla/plugins.ts @@ -1,8 +1,4 @@ -/** - * @internalapi - * @module vanilla - */ -/** */ +/** @internalapi @module vanilla */ /** */ import { BrowserLocationConfig } from './browserLocationConfig'; import { HashLocationService } from './hashLocationService'; import { locationPluginFactory } from './utils'; diff --git a/src/vanilla/pushStateLocationService.ts b/src/vanilla/pushStateLocationService.ts index cd51dd37..9621d8a4 100644 --- a/src/vanilla/pushStateLocationService.ts +++ b/src/vanilla/pushStateLocationService.ts @@ -1,8 +1,4 @@ -/** - * @internalapi - * @module vanilla - */ -/** */ +/** @internalapi @module vanilla */ /** */ import { UIRouter } from '../router'; import { BaseLocationServices } from './baseLocationService'; import { LocationConfig, root, splitHash, splitQuery, stripLastPathElement } from '../common'; diff --git a/src/vanilla/q.ts b/src/vanilla/q.ts index 09c675b2..76355fc3 100644 --- a/src/vanilla/q.ts +++ b/src/vanilla/q.ts @@ -1,8 +1,4 @@ -/** - * @internalapi - * @module vanilla - */ -/** */ +/** @internalapi @module vanilla */ /** */ import { isArray, isObject, $QLike } from '../common/index'; /** diff --git a/src/vanilla/utils.ts b/src/vanilla/utils.ts index 998fa6a3..e7a93563 100644 --- a/src/vanilla/utils.ts +++ b/src/vanilla/utils.ts @@ -1,8 +1,4 @@ -/** - * @internalapi - * @module vanilla - */ -/** */ +/** @internalapi @module vanilla */ /** */ import { LocationConfig, LocationServices, diff --git a/src/view/index.ts b/src/view/index.ts index 693b7609..4b46a8f5 100644 --- a/src/view/index.ts +++ b/src/view/index.ts @@ -1,6 +1,3 @@ -/** - * @coreapi - * @module view - */ /** for typedoc */ +/** @publicapi @module view */ /** */ export * from './interface'; export * from './view'; diff --git a/src/view/interface.ts b/src/view/interface.ts index 3b2af4e3..fe27367b 100644 --- a/src/view/interface.ts +++ b/src/view/interface.ts @@ -1,9 +1,10 @@ -/** @module view */ /** for typedoc */ +/** @publicapi @module view */ /** */ import { _ViewDeclaration } from '../state/interface'; import { PathNode } from '../path/pathNode'; /** * The context ref can be anything that has a `name` and a `parent` reference to another IContextRef + * @internalapi */ export interface ViewContext { name: string; diff --git a/src/view/view.ts b/src/view/view.ts index 151bf01e..3913b90e 100644 --- a/src/view/view.ts +++ b/src/view/view.ts @@ -1,7 +1,4 @@ -/** - * @coreapi - * @module view - */ /** for typedoc */ +/** @publicapi @module view */ /** */ import { equals, applyPairs, removeFrom, TypedMap, inArray, find } from '../common/common'; import { curry, prop } from '../common/hof'; import { isString, isArray } from '../common/predicates'; @@ -50,12 +47,13 @@ export interface ViewSyncListener { * */ export class ViewService { - private _uiViews: ActiveUIView[] = []; - private _viewConfigs: ViewConfig[] = []; - private _rootContext: ViewContext; - private _viewConfigFactories: { [key: string]: ViewConfigFactory } = {}; - private _listeners: ViewSyncListener[] = []; + /** @hidden */ private _uiViews: ActiveUIView[] = []; + /** @hidden */ private _viewConfigs: ViewConfig[] = []; + /** @hidden */ private _rootContext: ViewContext; + /** @hidden */ private _viewConfigFactories: { [key: string]: ViewConfigFactory } = {}; + /** @hidden */ private _listeners: ViewSyncListener[] = []; + /** @internalapi */ public _pluginapi: ViewServicePluginAPI = { _rootViewContext: this._rootViewContext.bind(this), _viewConfigFactory: this._viewConfigFactory.bind(this), @@ -191,12 +189,14 @@ export class ViewService { return { uiViewName, uiViewContextAnchor }; } - constructor(private router: UIRouter) {} + /** @hidden */ + constructor(/** @hidden */ private router: UIRouter) {} + /** @hidden */ private _rootViewContext(context?: ViewContext): ViewContext { return (this._rootContext = context || this._rootContext); } - + /** @hidden */ private _viewConfigFactory(viewType: string, factory: ViewConfigFactory) { this._viewConfigFactories[viewType] = factory; } diff --git a/test/urlServiceSpec.ts b/test/urlServiceSpec.ts index 194a2fbc..2571cb9a 100644 --- a/test/urlServiceSpec.ts +++ b/test/urlServiceSpec.ts @@ -53,7 +53,7 @@ describe('Facades delegating to the UrlService classes', () => { expectProxyCall(() => router.urlRouter, () => router.urlService, 'deferIntercept'); }); - // UrlService -> LocationConfig + // UrlConfig -> LocationConfig it('should pass config.port() through to LocationConfig', () => { expectProxyCall(() => router.urlService.config, () => router.locationConfig, 'port'); @@ -82,19 +82,19 @@ describe('Facades delegating to the UrlService classes', () => { // UrlService.ConfigApi -> UrlMatcherFactory it('should pass config.type() through to UrlRouter', () => { - expectProxyCall(() => router.urlService.config, () => router.urlMatcherFactory, 'type', ['foo']); + expectProxyCall(() => router.urlMatcherFactory, () => router.urlService.config, 'type', ['foo']); }); it('should pass config.caseInsensitive() through to UrlRouter', () => { - expectProxyCall(() => router.urlService.config, () => router.urlMatcherFactory, 'caseInsensitive'); + expectProxyCall(() => router.urlMatcherFactory, () => router.urlService.config, 'caseInsensitive'); }); it('should pass config.strictMode() through to UrlRouter', () => { - expectProxyCall(() => router.urlService.config, () => router.urlMatcherFactory, 'strictMode'); + expectProxyCall(() => router.urlMatcherFactory, () => router.urlService.config, 'strictMode'); }); it('should pass config.defaultSquashPolicy() through to UrlRouter', () => { - expectProxyCall(() => router.urlService.config, () => router.urlMatcherFactory, 'defaultSquashPolicy'); + expectProxyCall(() => router.urlMatcherFactory, () => router.urlService.config, 'defaultSquashPolicy'); }); // UrlRouter -> UrlRules diff --git a/typedoc.json b/typedoc.json index 3aa4e57c..6ca541db 100644 --- a/typedoc.json +++ b/typedoc.json @@ -22,8 +22,8 @@ "name": "@uirouter/core", "theme": "node_modules/ui-router-typedoc-themes/bin/default", "out": "_doc", - "internal-aliases": "internal,coreapi", - "external-aliases": "internalapi,external", + "internal-aliases": "internal,publicapi", + "external-aliases": "external,internalapi", "navigation-label-globals": "@uirouter/core" } }