@kitbag/router 0.7.0 → 0.7.2

package/README.md

@@ -11,7 +11,7 @@ Type safe router for Vue.js
 
 ## Getting Started
 
-Get Started with our [documentation](https://kitbag-router.netlify.app/)
+Get Started with our [documentation](https://kitbag-router.netlify.app/) or our [intro video](https://kitbag-router.netlify.app/)
 
 ## Installation
 
@@ -75,31 +75,32 @@ declare module '@kitbag/router' {
 To navigate to another route, you can use `router.push`. This method will update the URL for the browser and also add the URL into the history so when a user uses the back button on their browser it will behave as expected.
 
 ```ts
+import { defineAsyncComponent } from 'vue'
 import { createRoute, useRouter } from '@kitbag/router'
 
 const user = createRoute({
   name: 'user',
   path: '/user',
-  component: ...,
+  component: defineAsyncComponent(() => import('./UserPage.vue')),
 })
 
 const profile = createRoute({
   parent: user,
   name: 'profile',
   path: '/profile',
-  component: ...,
+  component: defineAsyncComponent(() => import('./ProfilePage.vue')),
 })
 
 const settings = createRoute({
   parent: user,
   name: 'settings',
   path: '/settings',
-  component: ...,
+  component: defineAsyncComponent(() => import('./SettingsPage.vue')),
 })
 
 const router = useRouter([user, profile, settings])
 
-router.push('user.settings')
+router.push('settings')
 ```
 
 The push method also accepts a plain string if you know the URL you want to go to.
@@ -109,14 +110,14 @@ router.push('/user/settings')
 router.push('https://github.com/kitbagjs/router')
 ```
 
-This `source` argument is type safe, expecting either a Url or a valid route "key". Url is any string that starts with "http", "https", or a forward slash "/". Route key is a string of route names joined by a period `.`. Additionally if using the route key, push will require params be passed in if there are any.
+This `source` argument is type safe, expecting either a [`Url`](/api/types/Url) or a valid route [`name`](/api/types/Route#name). URL is any string that starts with "http", "https", or a forward slash "/". Additionally if using the route name, push will require params be passed in if there are any.
 
 ## Update
 
 If you only wish to change the params on the current route you can use `router.route.update`.
 
 ```ts
-router.route.update('myParam': 123)
+router.route.update('myParam', 123)
 ```
 
 or for setting multiple params at once
@@ -162,6 +163,6 @@ This component gives the router the power to change the URL without reloading th
 [netlify-badge]: https://api.netlify.com/api/v1/badges/c12f79b8-49f9-4529-bc23-f8ffca8919a3/deploy-status
 [netlify-url]: https://app.netlify.com/sites/kitbag-router/deploys
 [discord-badge]: https://img.shields.io/discord/1079625926024900739?logo=discord&label=Discord
-[discord-url]: https://discord.gg/UT7JrAxU
+[discord-url]: https://discord.gg/zw7dpcc5HV
 [stackblitz-badge]: https://developer.stackblitz.com/img/open_in_stackblitz_small.svg
 [stackblitz-url]: https://stackblitz.com/~/github.com/kitbagjs/router-preview

package/dist/kitbag-router.d.ts

@@ -121,7 +121,7 @@ declare const builtInRejections: ['NotFound'];
 
 declare type BuiltInRejectionType = typeof builtInRejections[number];
 
-declare type CombineKey<TParentKey extends string | undefined, TChildKey extends string | undefined> = StringHasValue<TParentKey> extends true ? StringHasValue<TChildKey> extends true ? `${TParentKey}.${TChildKey}` : TParentKey : StringHasValue<TChildKey> extends true ? TChildKey : '';
+declare type CombineMeta<TParent extends Record<string, unknown>, TChild extends Record<string, unknown>> = TParent & TChild;
 
 declare type CombinePath<TParent extends Path, TChild extends Path> = ToPath<TParent> extends {
     path: infer TParentPath extends string;
@@ -141,6 +141,8 @@ declare type CombineQuery<TParent extends Query, TChild extends Query> = ToQuery
 
 declare type CombineQueryString<TParent extends string | undefined, TChild extends string | undefined> = StringHasValue<TParent> extends true ? StringHasValue<TChild> extends true ? `${TParent}&${TChild}` : TParent : TChild;
 
+declare type CombineState<TParent extends Record<string, Param>, TChild extends Record<string, Param>> = TParent & TChild;
+
 /**
  * Creates a component wrapper which has no props itself but mounts another component within while binding its props
  *
@@ -167,9 +169,9 @@ declare type ComponentPropsGetter<TComponent extends Component> = () => MaybePro
 
 declare type Constructor = new (...args: any) => any;
 
-export declare function createExternalRoute<const THost extends string | Host, const TName extends string | undefined = undefined, const TPath extends string | Path | undefined = undefined, const TQuery extends string | Query | undefined = undefined>(options: CreateRouteOptions<TName, TPath, TQuery> & WithHost<THost> & WithoutParent): Route<ToKey<TName>, ToHost<THost>, ToPath<TPath>, ToQuery<TQuery>>;
+export declare function createExternalRoute<const THost extends string | Host, const TName extends string | undefined = undefined, const TPath extends string | Path | undefined = undefined, const TQuery extends string | Query | undefined = undefined>(options: CreateRouteOptions<TName, TPath, TQuery> & WithHost<THost> & WithoutParent): Route<ToName<TName>, ToHost<THost>, ToPath<TPath>, ToQuery<TQuery>>;
 
-export declare function createExternalRoute<const TParent extends Route, const TName extends string | undefined = undefined, const TPath extends string | Path | undefined = undefined, const TQuery extends string | Query | undefined = undefined>(options: CreateRouteOptions<TName, TPath, TQuery> & WithoutHost & WithParent<TParent>): Route<CombineKey<TParent['key'], ToKey<TName>>, Host<'', {}>, CombinePath<TParent['path'], ToPath<TPath>>, CombineQuery<TParent['query'], ToQuery<TQuery>>>;
+export declare function createExternalRoute<const TParent extends Route, const TName extends string | undefined = undefined, const TPath extends string | Path | undefined = undefined, const TQuery extends string | Query | undefined = undefined>(options: CreateRouteOptions<TName, TPath, TQuery> & WithoutHost & WithParent<TParent>): Route<ToName<TName>, Host<'', {}>, CombinePath<TParent['path'], ToPath<TPath>>, CombineQuery<TParent['query'], ToQuery<TQuery>>>;
 
 export declare function createParam<TParam extends ParamWithDefault>(param: TParam): TParam;
 
@@ -177,17 +179,17 @@ export declare function createParam<TParam extends Param>(param: TParam): ParamG
 
 export declare function createParam<TParam extends Param>(param: TParam, defaultValue: ExtractParamType<TParam>): ParamWithDefault<TParam>;
 
-export declare function createRoute<const TName extends string | undefined = undefined, const TPath extends string | Path | undefined = undefined, const TQuery extends string | Query | undefined = undefined, const TMeta extends RouteMeta = RouteMeta>(options: CreateRouteOptions<TName, TPath, TQuery, TMeta> & WithHooks & WithoutComponents & WithoutParent): Route<ToKey<TName>, Host<'', {}>, ToPath<TPath>, ToQuery<TQuery>>;
+export declare function createRoute<const TName extends string | undefined = undefined, const TPath extends string | Path | undefined = undefined, const TQuery extends string | Query | undefined = undefined, const TMeta extends RouteMeta = RouteMeta, const TState extends Record<string, Param> = Record<string, Param>>(options: CreateRouteOptions<TName, TPath, TQuery, TMeta> & WithHooks & WithoutComponents & WithoutParent & (WithState<TState> | WithoutState)): Route<ToName<TName>, Host<'', {}>, ToPath<TPath>, ToQuery<TQuery>, TMeta, TState>;
 
-export declare function createRoute<const TParent extends Route, const TName extends string | undefined = undefined, const TPath extends string | Path | undefined = undefined, const TQuery extends string | Query | undefined = undefined, const TMeta extends RouteMeta = RouteMeta>(options: CreateRouteOptions<TName, TPath, TQuery, TMeta> & WithHooks & WithoutComponents & WithParent<TParent>): Route<CombineKey<TParent['key'], ToKey<TName>>, Host<'', {}>, CombinePath<TParent['path'], ToPath<TPath>>, CombineQuery<TParent['query'], ToQuery<TQuery>>>;
+export declare function createRoute<const TParent extends Route, const TName extends string | undefined = undefined, const TPath extends string | Path | undefined = undefined, const TQuery extends string | Query | undefined = undefined, const TMeta extends RouteMeta = RouteMeta, const TState extends Record<string, Param> = Record<string, Param>>(options: CreateRouteOptions<TName, TPath, TQuery, TMeta> & WithHooks & WithoutComponents & WithParent<TParent> & (WithState<TState> | WithoutState)): Route<ToName<TName>, Host<'', {}>, CombinePath<TParent['path'], ToPath<TPath>>, CombineQuery<TParent['query'], ToQuery<TQuery>>, CombineMeta<TMeta, TParent['meta']>, CombineState<TState, TParent['state']>>;
 
-export declare function createRoute<TComponent extends Component, const TName extends string | undefined = undefined, const TPath extends string | Path | undefined = undefined, const TQuery extends string | Query | undefined = undefined, const TMeta extends RouteMeta = RouteMeta>(options: CreateRouteOptions<TName, TPath, TQuery, TMeta> & WithHooks & WithComponent<TComponent, RouteParams<TPath, TQuery>> & WithoutParent): Route<ToKey<TName>, Host<'', {}>, ToPath<TPath>, ToQuery<TQuery>>;
+export declare function createRoute<TComponent extends Component, const TName extends string | undefined = undefined, const TPath extends string | Path | undefined = undefined, const TQuery extends string | Query | undefined = undefined, const TMeta extends RouteMeta = RouteMeta, const TState extends Record<string, Param> = Record<string, Param>>(options: CreateRouteOptions<TName, TPath, TQuery, TMeta> & WithHooks & WithComponent<TComponent, RouteParams<TPath, TQuery>> & WithoutParent & (WithState<TState> | WithoutState)): Route<ToName<TName>, Host<'', {}>, ToPath<TPath>, ToQuery<TQuery>, TMeta, TState>;
 
-export declare function createRoute<TComponent extends Component, const TParent extends Route, const TName extends string | undefined = undefined, const TPath extends string | Path | undefined = undefined, const TQuery extends string | Query | undefined = undefined, const TMeta extends RouteMeta = RouteMeta>(options: CreateRouteOptions<TName, TPath, TQuery, TMeta> & WithHooks & WithComponent<TComponent, RouteParams<TPath, TQuery, TParent>> & WithParent<TParent>): Route<CombineKey<TParent['key'], ToKey<TName>>, Host<'', {}>, CombinePath<TParent['path'], ToPath<TPath>>, CombineQuery<TParent['query'], ToQuery<TQuery>>>;
+export declare function createRoute<TComponent extends Component, const TParent extends Route, const TName extends string | undefined = undefined, const TPath extends string | Path | undefined = undefined, const TQuery extends string | Query | undefined = undefined, const TMeta extends RouteMeta = RouteMeta, const TState extends Record<string, Param> = Record<string, Param>>(options: CreateRouteOptions<TName, TPath, TQuery, TMeta> & WithHooks & WithComponent<TComponent, RouteParams<TPath, TQuery, TParent>> & WithParent<TParent> & (WithState<TState> | WithoutState)): Route<ToName<TName>, Host<'', {}>, CombinePath<TParent['path'], ToPath<TPath>>, CombineQuery<TParent['query'], ToQuery<TQuery>>, CombineMeta<TMeta, TParent['meta']>, CombineState<TState, TParent['state']>>;
 
-export declare function createRoute<TComponents extends Record<string, Component>, const TName extends string | undefined = undefined, const TPath extends string | Path | undefined = undefined, const TQuery extends string | Query | undefined = undefined, const TMeta extends RouteMeta = RouteMeta>(options: CreateRouteOptions<TName, TPath, TQuery, TMeta> & WithHooks & WithComponents<TComponents, RouteParams<TPath, TQuery>> & WithoutParent): Route<ToKey<TName>, Host<'', {}>, ToPath<TPath>, ToQuery<TQuery>>;
+export declare function createRoute<TComponents extends Record<string, Component>, const TName extends string | undefined = undefined, const TPath extends string | Path | undefined = undefined, const TQuery extends string | Query | undefined = undefined, const TMeta extends RouteMeta = RouteMeta, const TState extends Record<string, Param> = Record<string, Param>>(options: CreateRouteOptions<TName, TPath, TQuery, TMeta> & WithHooks & WithComponents<TComponents, RouteParams<TPath, TQuery>> & WithoutParent & (WithState<TState> | WithoutState)): Route<ToName<TName>, Host<'', {}>, ToPath<TPath>, ToQuery<TQuery>, TMeta, TState>;
 
-export declare function createRoute<TComponents extends Record<string, Component>, const TParent extends Route, const TName extends string | undefined = undefined, const TPath extends string | Path | undefined = undefined, const TQuery extends string | Query | undefined = undefined, const TMeta extends RouteMeta = RouteMeta>(options: CreateRouteOptions<TName, TPath, TQuery, TMeta> & WithHooks & WithComponents<TComponents, RouteParams<TPath, TQuery, TParent>> & WithParent<TParent>): Route<CombineKey<TParent['key'], ToKey<TName>>, Host<'', {}>, CombinePath<TParent['path'], ToPath<TPath>>, CombineQuery<TParent['query'], ToQuery<TQuery>>>;
+export declare function createRoute<TComponents extends Record<string, Component>, const TParent extends Route, const TName extends string | undefined = undefined, const TPath extends string | Path | undefined = undefined, const TQuery extends string | Query | undefined = undefined, const TMeta extends RouteMeta = RouteMeta, const TState extends Record<string, Param> = Record<string, Param>>(options: CreateRouteOptions<TName, TPath, TQuery, TMeta> & WithHooks & WithComponents<TComponents, RouteParams<TPath, TQuery, TParent>> & WithParent<TParent> & (WithState<TState> | WithoutState)): Route<ToName<TName>, Host<'', {}>, CombinePath<TParent['path'], ToPath<TPath>>, CombineQuery<TParent['query'], ToQuery<TQuery>>, CombineMeta<TMeta, TParent['meta']>, CombineState<TState, TParent['state']>>;
 
 export declare type CreateRouteOptions<TName extends string | undefined = string | undefined, TPath extends string | Path | undefined = string | Path | undefined, TQuery extends string | Query | undefined = string | Query | undefined, TMeta extends RouteMeta = RouteMeta> = {
     /**
@@ -211,7 +213,7 @@ export declare type CreateRouteOptions<TName extends string | undefined = string
 /**
  * The Route properties originally provided to `createRoute`. The only change is normalizing meta to always default to an empty object.
  */
-export declare type CreateRouteOptionsMatched = CreateRouteOptions & WithHooks & (WithHost | WithoutHost) & (WithComponent | WithComponents | WithoutComponents) & (WithParent | WithoutParent) & {
+declare type CreateRouteOptionsMatched = CreateRouteOptions & WithHooks & (WithHost | WithoutHost) & (WithComponent | WithComponents | WithoutComponents) & (WithParent | WithoutParent) & (WithState | WithoutState) & {
     meta: RouteMeta;
 };
 
@@ -243,8 +245,8 @@ export declare function createRouter<const T extends Routes>(routes: T, options?
 export declare function createRouter<const T extends Routes>(arrayOfRoutes: T[], options?: RouterOptions): Router<T>;
 
 /**
- * An error thrown when duplicate parameters are detected in a route when creating a router.
- * When defining routes, param names must be unique. This includes params defined in a path
+ * An error thrown when duplicate parameters are detected in a route.
+ * Param names must be unique. This includes params defined in a path
  * parent and params defined in the query.
  */
 export declare class DuplicateParamsError extends Error {
@@ -335,6 +337,14 @@ declare type ExtractRouteParamTypesWithoutLosingOptional<TRoute> = TRoute extend
     };
 } ? ExtractParamTypesWithoutLosingOptional<HostParams & PathParams & QueryParams> : Record<string, unknown>;
 
+declare type ExtractRouteStateParamsAsOptional<T extends Record<string, Param>> = ExtractParamTypes<{
+    [K in keyof T as K extends string ? `?${K}` : never]: T[K];
+}>;
+
+declare type ExtractStateParams<TRoute> = TRoute extends {
+    state: infer TState extends Record<string, Param>;
+} ? ExtractParamTypes<TState> : Record<string, unknown>;
+
 declare type Host<THost extends string = string, TParams extends HostParamsWithParamNameExtracted<THost> = Record<string, Param | undefined>> = {
     host: THost;
     params: string extends THost ? Record<string, Param> : Identity<ExtractParamsFromHostString<THost, TParams>>;
@@ -355,33 +365,33 @@ export declare function isParamWithDefault(param: Param): param is ParamWithDefa
 
 export declare function isRoute(route: unknown): route is RouterRoute;
 
-export declare function isRoute<TRoute extends RouterRoute, TRouteKey extends TRoute['key']>(route: TRoute, routeKey: TRouteKey, options: IsRouteOptions & {
+export declare function isRoute<TRoute extends RouterRoute, TRouteName extends TRoute['name']>(route: TRoute, routeName: TRouteName, options: IsRouteOptions & {
     exact: true;
 }): route is TRoute & {
-    key: TRouteKey;
+    name: TRouteName;
 };
 
-export declare function isRoute<TRoute extends RouterRoute, TRouteKey extends TRoute['key']>(route: TRoute, routeKey: TRouteKey, options?: IsRouteOptions): route is TRoute & {
-    key: `${TRouteKey}${string}`;
+export declare function isRoute<TRoute extends RouterRoute, TRouteName extends TRoute['name']>(route: TRoute, routeName: TRouteName, options?: IsRouteOptions): route is TRoute & {
+    name: `${TRouteName}${string}`;
 };
 
-export declare function isRoute<TRouteKey extends RegisteredRoutesKey>(route: unknown, routeKey: TRouteKey, options: IsRouteOptions & {
+export declare function isRoute<TRouteName extends RegisteredRoutesName>(route: unknown, routeName: TRouteName, options: IsRouteOptions & {
     exact: true;
 }): route is RegisteredRouterRoute & {
-    key: TRouteKey;
+    name: TRouteName;
 };
 
-export declare function isRoute<TRouteKey extends RegisteredRoutesKey>(route: unknown, routeKey: TRouteKey, options?: IsRouteOptions): route is RegisteredRouterRoute & {
-    key: `${TRouteKey}${string}`;
+export declare function isRoute<TRouteName extends RegisteredRoutesName>(route: unknown, routeName: TRouteName, options?: IsRouteOptions): route is RegisteredRouterRoute & {
+    name: `${TRouteName}${string}`;
 };
 
-export declare function isRoute(route: unknown, routeKey?: string, options?: IsRouteOptions): boolean;
+export declare function isRoute(route: unknown, routeName?: string, options?: IsRouteOptions): boolean;
 
 declare type IsRouteOptions = {
     exact?: boolean;
 };
 
-declare type IsRouteUnnamed<T extends Route> = StringHasValue<T['key']> extends true ? false : true;
+declare type IsRouteUnnamed<T extends Route> = StringHasValue<T['name']> extends true ? false : true;
 
 declare type MakeOptional<T> = {
     [P in WithOptionalProperties<T>]?: T[P];
@@ -564,7 +574,7 @@ export declare type RegisteredRejectionType = Register extends {
 } ? TRejections[number] : never;
 
 /**
- * Represents the a map of all possible RouteKeys with corresponding Route registered within {@link Register}
+ * Represents the a map of all possible route names with corresponding Route registered within {@link Register}
  */
 export declare type RegisteredRouteMap = RoutesMap<RegisteredRoutes>;
 
@@ -598,9 +608,9 @@ export declare type RegisteredRoutes = Register extends {
 } ? TRoutes : Route[];
 
 /**
- * Represents the union of all possible RouteKeys registered within {@link Register}
+ * Represents the union of all possible route names registered within {@link Register}
  */
-export declare type RegisteredRoutesKey = RoutesKey<RegisteredRoutes>;
+export declare type RegisteredRoutesName = RoutesName<RegisteredRoutes>;
 
 declare type RemoveLeadingQuestionMark<T extends PropertyKey> = T extends `?${infer TRest extends string}` ? TRest : T;
 
@@ -623,9 +633,9 @@ declare type ResolvedRoute<TRoute extends Route = Route> = Readonly<{
      */
     matches: TRoute['matches'];
     /**
-     * Unique identifier for the route, generated by joining route `name` by period. Key is used for routing and for matching.
+     * Unique identifier for the route. Name is used for routing and for matching.
      */
-    key: TRoute['key'];
+    name: TRoute['name'];
     /**
      * Accessor for query string values from user in the current browser location.
      */
@@ -634,6 +644,10 @@ declare type ResolvedRoute<TRoute extends Route = Route> = Readonly<{
      * Key value pair for route params, values will be the user provided value from current browser location.
      */
     params: ExtractRouteParamTypes<TRoute>;
+    /**
+     * Type for additional data intended to be stored in history state.
+     */
+    state: ExtractRouteStateParamsAsOptional<TRoute['state']>;
 }>;
 
 declare type ResolvedRouteQuery = {
@@ -643,26 +657,24 @@ declare type ResolvedRouteQuery = {
 
 /**
  * Represents the structure of a route within the application. Return value of `createRoute`
- * @template TKey - Represents the unique key identifying the route, typically a string.
+ * @template TName - Represents the unique name identifying the route, typically a string.
  * @template TPath - The type or structure of the route's path.
  * @template TQuery - The type or structure of the query parameters associated with the route.
  */
-export declare type Route<TKey extends string = string, THost extends Host = Host, TPath extends Path = Path, TQuery extends Query = Query, TMeta extends RouteMeta = RouteMeta> = {
+export declare type Route<TName extends string = string, THost extends Host = Host, TPath extends Path = Path, TQuery extends Query = Query, TMeta extends RouteMeta = RouteMeta, TState extends Record<string, Param> = Record<string, Param>> = {
     /**
      * The specific route properties that were matched in the current route.
      */
-    matched: CreateRouteOptionsMatched & {
-        meta: TMeta;
-    };
+    matched: CreateRouteOptionsMatched;
     /**
      * The specific route properties that were matched in the current route, including any ancestors.
      * Order of routes will be from greatest ancestor to narrowest matched.
      */
     matches: CreateRouteOptionsMatched[];
     /**
-     * Unique identifier for the route, generated by joining route `name` by period. Key is used for routing and for matching.
+     * Unique identifier for the route. Name is used for routing and for matching.
      */
-    key: TKey;
+    name: TName;
     /**
      * Represents the host for this route. Used for external routes.
      */
@@ -675,10 +687,18 @@ export declare type Route<TKey extends string = string, THost extends Host = Hos
      * Represents the structured query of the route, including query params.
      */
     query: TQuery;
+    /**
+     * Represents additional metadata associated with a route, combined with any parents.
+     */
+    meta: TMeta;
+    /**
+     * Represents the schema of the route state, combined with any parents.
+     */
+    state: TState;
     depth: number;
 };
 
-declare type RouteGetByKey<TRoutes extends Routes, TKey extends RoutesKey<TRoutes>> = RoutesMap<TRoutes>[TKey];
+declare type RouteGetByKey<TRoutes extends Routes, TKey extends RoutesName<TRoutes>> = RoutesMap<TRoutes>[TKey];
 
 /**
  * Generic type representing a route hook, which can be either before or after a route change.
@@ -834,11 +854,11 @@ export declare type Router<TRoutes extends Routes = any> = Plugin_2 & {
 };
 
 declare type RouterFind<TRoutes extends Routes> = {
-    <TSource extends RoutesKey<TRoutes>>(source: TSource, ...args: RouterFindArgs<TRoutes, TSource>): ResolvedRoute | undefined;
-    (source: Url): ResolvedRoute | undefined;
+    <TSource extends RoutesName<TRoutes>>(name: TSource, ...args: RouterFindArgs<TRoutes, TSource>): ResolvedRoute | undefined;
+    (url: Url): ResolvedRoute | undefined;
 };
 
-declare type RouterFindArgs<TRoutes extends Routes, TSource extends RoutesKey<TRoutes>, TParams = RouteParamsByKey<TRoutes, TSource>> = AllPropertiesAreOptional<TParams> extends true ? [params?: TParams] : [params: TParams];
+declare type RouterFindArgs<TRoutes extends Routes, TSource extends RoutesName<TRoutes>, TParams = RouteParamsByKey<TRoutes, TSource>> = AllPropertiesAreOptional<TParams> extends true ? [params?: TParams] : [params: TParams];
 
 declare type RouterHistoryMode = 'auto' | 'browser' | 'memory' | 'hash';
 
@@ -882,21 +902,29 @@ export declare type RouterOptions = {
      */
     initialUrl?: string;
     /**
-     * Specifies the history mode for the router, such as 'hash', 'history', or 'abstract'.
+     * Specifies the history mode for the router, such as "browser", "memory", or "hash".
+     *
+     * @default "auto"
      */
     historyMode?: RouterHistoryMode;
+    /**
+     * Base path to be prepended to any URL. Can be used for Vue applications that run in nested folder for domain.
+     * For example having `base` of `/foo` would assume all routes should start with `your.domain.com/foo`.
+     */
+    base?: string;
 } & RouterRejectionComponents;
 
 declare type RouterPush<TRoutes extends Routes = any> = {
-    <TSource extends RoutesKey<TRoutes>>(source: TSource, ...args: RouterPushArgs<TRoutes, TSource>): Promise<void>;
-    (source: Url, options?: RouterPushOptions): Promise<void>;
+    <TSource extends RoutesName<TRoutes>>(name: TSource, ...args: RouterPushArgs<TRoutes, TSource>): Promise<void>;
+    (url: Url, options?: RouterPushOptions): Promise<void>;
 };
 
-declare type RouterPushArgs<TRoutes extends Routes, TSource extends RoutesKey<TRoutes>, TParams = RouteParamsByKey<TRoutes, TSource>> = AllPropertiesAreOptional<TParams> extends true ? [params?: TParams, options?: RouterPushOptions] : [params: TParams, options?: RouterPushOptions];
+declare type RouterPushArgs<TRoutes extends Routes, TSource extends RoutesName<TRoutes>> = AllPropertiesAreOptional<RouteParamsByKey<TRoutes, TSource>> extends true ? [params?: RouteParamsByKey<TRoutes, TSource>, options?: RouterPushOptions<RouteStateByName<TRoutes, TSource>>] : [params: RouteParamsByKey<TRoutes, TSource>, options?: RouterPushOptions<RouteStateByName<TRoutes, TSource>>];
 
-declare type RouterPushOptions = {
+declare type RouterPushOptions<TState = unknown> = {
     query?: Record<string, string>;
     replace?: boolean;
+    state?: Partial<TState>;
 };
 
 export declare type RouterReject = (type: RouterRejectionType) => void;
@@ -915,29 +943,33 @@ export declare const routerRejectionKey: InjectionKey<RouterRejection>;
 declare type RouterRejectionType = BuiltInRejectionType | RegisteredRejectionType;
 
 declare type RouterReplace<TRoutes extends Routes> = {
-    <TSource extends RoutesKey<TRoutes>>(source: TSource, ...args: RouterReplaceArgs<TRoutes, TSource>): Promise<void>;
-    (source: Url, options?: RouterReplaceOptions): Promise<void>;
+    <TSource extends RoutesName<TRoutes>>(name: TSource, ...args: RouterReplaceArgs<TRoutes, TSource>): Promise<void>;
+    (url: Url, options?: RouterReplaceOptions): Promise<void>;
 };
 
-declare type RouterReplaceArgs<TRoutes extends Routes, TSource extends RoutesKey<TRoutes>, TParams = RouteParamsByKey<TRoutes, TSource>> = AllPropertiesAreOptional<TParams> extends true ? [params?: TParams, options?: RouterReplaceOptions] : [params: TParams, options?: RouterReplaceOptions];
+declare type RouterReplaceArgs<TRoutes extends Routes, TSource extends RoutesName<TRoutes>, TParams = RouteParamsByKey<TRoutes, TSource>> = AllPropertiesAreOptional<TParams> extends true ? [params?: TParams, options?: RouterReplaceOptions<RouteStateByName<TRoutes, TSource>>] : [params: TParams, options?: RouterReplaceOptions<RouteStateByName<TRoutes, TSource>>];
 
-declare type RouterReplaceOptions = Omit<RouterPushOptions, 'replace'>;
+declare type RouterReplaceOptions<TState = unknown> = {
+    query?: Record<string, string>;
+    state?: Partial<TState>;
+};
 
 declare type RouterResolve<TRoutes extends Routes> = {
-    <TSource extends RoutesKey<TRoutes>>(source: TSource, ...args: RouterResolveArgs<TRoutes, TSource>): string;
-    (source: Url, options?: RouterResolveOptions): string;
+    <TSource extends RoutesName<TRoutes>>(name: TSource, ...args: RouterResolveArgs<TRoutes, TSource>): string;
+    (url: Url, options?: RouterResolveOptions): string;
 };
 
-declare type RouterResolveArgs<TRoutes extends Routes, TSource extends RoutesKey<TRoutes>, TParams = RouteParamsByKey<TRoutes, TSource>> = AllPropertiesAreOptional<TParams> extends true ? [params?: TParams, options?: RouterResolveOptions] : [params: TParams, options?: RouterResolveOptions];
+declare type RouterResolveArgs<TRoutes extends Routes, TSource extends RoutesName<TRoutes>, TParams = RouteParamsByKey<TRoutes, TSource>> = AllPropertiesAreOptional<TParams> extends true ? [params?: TParams, options?: RouterResolveOptions] : [params: TParams, options?: RouterResolveOptions];
 
 declare type RouterResolveOptions = {
     query?: Record<string, string>;
 };
 
 declare type RouterRoute<TRoute extends ResolvedRoute = ResolvedRoute> = Readonly<{
-    key: TRoute['key'];
+    name: TRoute['name'];
     matched: TRoute['matched'];
     matches: TRoute['matches'];
+    state: TRoute['state'];
     query: ResolvedRouteQuery;
     params: Writable<TRoute['params']>;
     update: RouteUpdate<TRoute>;
@@ -957,18 +989,24 @@ name?: string | undefined;
 }>>>, {}, {}>, Readonly<{
     default?: ((props: {
         route: Readonly<{
-            key: string;
-            matched: CreateRouteOptionsMatched & {
+            name: string;
+            matched: CreateRouteOptions & WithHooks & (WithHost | WithoutHost) & (WithoutComponents | WithComponent | WithComponents) & (WithoutParent | WithParent) & (WithoutState | WithState) & {
+                meta: Record<string, unknown>;
+            };
+            matches: (CreateRouteOptions & WithHooks & (WithHost | WithoutHost) & (WithoutComponents | WithComponent | WithComponents) & (WithoutParent | WithParent) & (WithoutState | WithState) & {
                 meta: Record<string, unknown>;
+            })[];
+            state: {
+                [x: string]: any;
+                [x: number]: any;
             };
-            matches: CreateRouteOptionsMatched[];
             query: ResolvedRouteQuery;
             params: Writable<    {
             [x: string]: any;
             [x: number]: any;
             }>;
             update: {
-                (key: string, value: unknown, options?: RouterPushOptions | undefined): Promise<void>;
+                (paramName: string, paramValue: unknown, options?: RouterPushOptions | undefined): Promise<void>;
                 (params: Partial<{
                     [x: string]: any;
                     [x: number]: any;
@@ -986,18 +1024,24 @@ name?: string | undefined;
 }> & {
     default?: ((props: {
         route: Readonly<{
-            key: string;
-            matched: CreateRouteOptionsMatched & {
+            name: string;
+            matched: CreateRouteOptions & WithHooks & (WithHost | WithoutHost) & (WithoutComponents | WithComponent | WithComponents) & (WithoutParent | WithParent) & (WithoutState | WithState) & {
                 meta: Record<string, unknown>;
             };
-            matches: CreateRouteOptionsMatched[];
+            matches: (CreateRouteOptions & WithHooks & (WithHost | WithoutHost) & (WithoutComponents | WithComponent | WithComponents) & (WithoutParent | WithParent) & (WithoutState | WithState) & {
+                meta: Record<string, unknown>;
+            })[];
+            state: {
+                [x: string]: any;
+                [x: number]: any;
+            };
             query: ResolvedRouteQuery;
             params: Writable<    {
             [x: string]: any;
             [x: number]: any;
             }>;
             update: {
-                (key: string, value: unknown, options?: RouterPushOptions | undefined): Promise<void>;
+                (paramName: string, paramValue: unknown, options?: RouterPushOptions | undefined): Promise<void>;
                 (params: Partial<{
                     [x: string]: any;
                     [x: number]: any;
@@ -1019,17 +1063,19 @@ name?: string | undefined;
  */
 export declare type Routes = Readonly<Route[]>;
 
-declare type RoutesKey<TRoutes extends Routes> = string & keyof RoutesMap<TRoutes>;
-
 declare type RoutesMap<TRoutes extends Routes = []> = {
-    [K in TRoutes[number] as AsNamedRoute<K>['key']]: AsNamedRoute<K>;
+    [K in TRoutes[number] as AsNamedRoute<K>['name']]: AsNamedRoute<K>;
 };
 
+declare type RoutesName<TRoutes extends Routes> = string & keyof RoutesMap<TRoutes>;
+
+declare type RouteStateByName<TRoutes extends Routes, TName extends string> = ExtractStateParams<RouteGetByKey<TRoutes, TName>>;
+
 declare type RouteUpdate<TRoute extends ResolvedRoute = ResolvedRoute> = ResolvedRoute extends TRoute ? {
-    (key: string, value: unknown, options?: RouterPushOptions): Promise<void>;
+    (paramName: string, paramValue: unknown, options?: RouterPushOptions): Promise<void>;
     (params: Partial<TRoute['params']>, options?: RouterPushOptions): Promise<void>;
 } : {
-    <TKey extends keyof TRoute['params']>(key: TKey, value: TRoute['params'][TKey], options?: RouterPushOptions): Promise<void>;
+    <TParamName extends keyof TRoute['params']>(paramName: TParamName, paramValue: TRoute['params'][TParamName], options?: RouterPushOptions): Promise<void>;
     (params: Partial<TRoute['params']>, options?: RouterPushOptions): Promise<void>;
 };
 
@@ -1039,7 +1085,7 @@ declare type ToCallback = (resolve: RegisteredRouter['resolve']) => string;
 
 declare type ToHost<T extends string | Host | undefined> = T extends string ? Host<T, {}> : T extends undefined ? Host<'', {}> : unknown extends T ? Host<'', {}> : T;
 
-declare type ToKey<T extends string | undefined> = T extends string ? T : '';
+declare type ToName<T extends string | undefined> = T extends string ? T : '';
 
 declare type ToPath<T extends string | Path | undefined> = T extends string ? Path<T, {}> : T extends undefined ? Path<'', {}> : unknown extends T ? Path<'', {}> : T;
 
@@ -1079,17 +1125,17 @@ export declare type UseLink = {
  * or resolved URL to discover route details. Also exports some useful context about routes relationship to current URL and convenience methods
  * for navigating.
  *
- * @param source - The key of the route or the URL value.
- * @param params - If providing route key, this argument will expect corresponding params.
+ * @param source - The name of the route or the URL value.
+ * @param params - If providing route name, this argument will expect corresponding params.
  * @param options - {@link RouterResolveOptions}Same options as router resolve.
  * @returns {UseLink} Reactive context values for as well as navigation methods.
  *
  */
-export declare function useLink<TRouteKey extends RegisteredRoutesKey>(routeKey: MaybeRefOrGetter<TRouteKey>, ...args: UseLinkArgs<TRouteKey>): UseLink;
+export declare function useLink<TRouteKey extends RegisteredRoutesName>(name: MaybeRefOrGetter<TRouteKey>, ...args: UseLinkArgs<TRouteKey>): UseLink;
 
 export declare function useLink(url: MaybeRefOrGetter<Url>): UseLink;
 
-declare type UseLinkArgs<TSource extends RegisteredRoutesKey, TParams = RouteParamsByKey<RegisteredRoutes, TSource>> = AllPropertiesAreOptional<TParams> extends true ? [params?: MaybeRefOrGetter<TParams>, options?: MaybeRefOrGetter<RouterResolveOptions>] : [params: MaybeRefOrGetter<TParams>, options?: MaybeRefOrGetter<RouterResolveOptions>];
+declare type UseLinkArgs<TSource extends RegisteredRoutesName, TParams = RouteParamsByKey<RegisteredRoutes, TSource>> = AllPropertiesAreOptional<TParams> extends true ? [params?: MaybeRefOrGetter<TParams>, options?: MaybeRefOrGetter<RouterResolveOptions>] : [params: MaybeRefOrGetter<TParams>, options?: MaybeRefOrGetter<RouterResolveOptions>];
 
 /**
  * A composition to access the router's rejection state.
@@ -1102,29 +1148,29 @@ declare type UseLinkArgs<TSource extends RegisteredRoutesKey, TParams = RoutePar
 export declare function useRejection(): RouterRejection;
 
 /**
- * A composition to access the current route or verify a specific route key within a Vue component.
+ * A composition to access the current route or verify a specific route name within a Vue component.
  * This function provides two overloads:
  * 1. When called without arguments, it returns the current route from the router without types.
- * 2. When called with a route key, it checks if the current active route includes the specified route key.
+ * 2. When called with a route name, it checks if the current active route includes the specified route name.
  *
- * @template TRouteKey - A string type that should match route key of RegisteredRouteMap, ensuring the route key exists.
- * @param routeKey - Optional. The key of the route to validate against the current active routes.
- * @returns The current router route. If a route key is provided, it validates the route key first.
- * @throws {UseRouteInvalidError} Throws an error if the provided route key is not valid or does not match the current route.
+ * @template TRouteName - A string type that should match route name of RegisteredRouteMap, ensuring the route name exists.
+ * @param routeName - Optional. The name of the route to validate against the current active routes.
+ * @returns The current router route. If a route name is provided, it validates the route name first.
+ * @throws {UseRouteInvalidError} Throws an error if the provided route name is not valid or does not match the current route.
  *
- * The function also sets up a reactive watcher on the route object from the router to continually check the validity of the route key
+ * The function also sets up a reactive watcher on the route object from the router to continually check the validity of the route name
  * if provided, throwing an error if the validation fails at any point during the component's lifecycle.
  */
 export declare function useRoute(): RegisteredRouterRoute;
 
-export declare function useRoute<TRouteKey extends RegisteredRoutesKey>(routeKey: TRouteKey, options: IsRouteOptions & {
+export declare function useRoute<TRouteName extends RegisteredRoutesName>(routeName: TRouteName, options: IsRouteOptions & {
     exact: true;
 }): RegisteredRouterRoute & {
-    key: TRouteKey;
+    name: TRouteName;
 };
 
-export declare function useRoute<TRouteKey extends RegisteredRoutesKey>(routeKey: TRouteKey, options?: IsRouteOptions): RegisteredRouterRoute & {
-    key: `${TRouteKey}${string}`;
+export declare function useRoute<TRouteName extends RegisteredRoutesName>(routeName: TRouteName, options?: IsRouteOptions): RegisteredRouterRoute & {
+    name: `${TRouteName}${string}`;
 };
 
 /**
@@ -1206,10 +1252,21 @@ declare type WithoutParent = {
     parent?: never;
 };
 
+declare type WithoutState = {
+    state?: never;
+};
+
 declare type WithParent<TParent extends Route = Route> = {
     parent: TParent;
 };
 
+declare type WithState<TState extends Record<string, Param> = Record<string, Param>> = {
+    /**
+     * Type params for additional data intended to be stored in history state, all keys will be optional unless a default is provided.
+     */
+    state: TState;
+};
+
 declare type Writable<T> = {
     -readonly [P in keyof T]: T[P];
 };
@@ -1217,7 +1274,7 @@ declare type Writable<T> = {
 export { }
 
 
-declare module '@vue/runtime-core' {
+declare module 'vue' {
     interface GlobalComponents {
         RouterView: typeof RouterView;
         RouterLink: typeof RouterLink;