@kitbag/router 0.14.2 → 0.15.1

package/dist/kitbag-router.d.ts

@@ -1,3 +1,4 @@
+import { App } from 'vue';
 import { AsyncComponentLoader } from 'vue';
 import { Component } from 'vue';
 import { ComponentOptionsMixin } from 'vue';
@@ -6,7 +7,6 @@ import { ComputedRef } from 'vue';
 import { DefineComponent } from 'vue';
 import { FunctionalComponent } from 'vue';
 import { MaybeRefOrGetter } from 'vue';
-import { Plugin as Plugin_2 } from 'vue';
 import { PublicProps } from 'vue';
 import { Ref } from 'vue';
 import { UnwrapRef } from 'vue';
@@ -38,6 +38,17 @@ export declare type AddAfterRouteHook = (hook: AfterRouteHook) => RouteHookRemov
  */
 export declare type AddBeforeRouteHook = (hook: BeforeRouteHook) => RouteHookRemove;
 
+export declare type AddComponentAfterRouteHook = (hook: AfterRouteHookRegistration) => RouteHookRemove;
+
+export declare type AddComponentBeforeRouteHook = (hook: BeforeRouteHookRegistration) => RouteHookRemove;
+
+export declare type AddGlobalRouteHooks = (hooks: RouteHooks) => void;
+
+export declare type AfterHookContext = {
+    to: ResolvedRoute;
+    from: ResolvedRoute | null;
+};
+
 /**
  * Represents a function called after a route change has occurred.
  * @param to - {@link ResolvedRoute} The resolved route the router has navigated to.
@@ -56,6 +67,12 @@ export declare type AfterRouteHookContext = RouteHookContext;
  */
 export declare type AfterRouteHookLifecycle = 'onAfterRouteEnter' | 'onAfterRouteUpdate' | 'onAfterRouteLeave';
 
+export declare type AfterRouteHookRegistration = {
+    lifecycle: 'onAfterRouteEnter' | 'onAfterRouteUpdate' | 'onAfterRouteLeave';
+    hook: AfterRouteHook;
+    depth: number;
+};
+
 /**
  * Type for responses from an after route hook, which may indicate different outcomes such as success, push, or reject.
  * @template TRoutes - The type of the routes configuration.
@@ -66,6 +83,13 @@ declare type AllPropertiesAreOptional<T> = Record<string, unknown> extends T ? t
 
 declare type AsNamedRoute<T extends Route> = IsRouteUnnamed<T> extends true ? never : T;
 
+/**
+ * Converts a type to a string if it is a string, otherwise returns never.
+ * Specifically useful when using keyof T to produce a union of strings
+ * rather than string | number | symbol.
+ */
+declare type AsString<T> = T extends string ? T : never;
+
 /**
  * Converts a string to a valid URL.
  * @param value - The string to convert.
@@ -73,6 +97,11 @@ declare type AsNamedRoute<T extends Route> = IsRouteUnnamed<T> extends true ? ne
  */
 export declare function asUrl(value: string): Url;
 
+export declare type BeforeHookContext = {
+    to: ResolvedRoute;
+    from: ResolvedRoute | null;
+};
+
 /**
  * Represents a function called before a route change, potentially altering the routing operation.
  * @param to - {@link ResolvedRoute} The resolved route the router is navigating to.
@@ -94,15 +123,19 @@ export declare type BeforeRouteHookContext = RouteHookContext & {
  */
 export declare type BeforeRouteHookLifecycle = 'onBeforeRouteEnter' | 'onBeforeRouteUpdate' | 'onBeforeRouteLeave';
 
+export declare type BeforeRouteHookRegistration = {
+    lifecycle: 'onBeforeRouteEnter' | 'onBeforeRouteUpdate' | 'onBeforeRouteLeave';
+    hook: BeforeRouteHook;
+    depth: number;
+};
+
 /**
  * Type for responses from a before route hook, which may indicate different outcomes such as success, push, reject, or abort.
  * @template TRoutes - The type of the routes configuration.
  */
 export declare type BeforeRouteHookResponse = CallbackSuccessResponse | CallbackPushResponse | CallbackRejectResponse | CallbackAbortResponse;
 
-declare const builtInRejections: ['NotFound'];
-
-declare type BuiltInRejectionType = typeof builtInRejections[number];
+declare type BuiltInRejectionType = 'NotFound';
 
 /**
  * Defines the structure of an aborted callback response.
@@ -258,9 +291,11 @@ declare type CreateRouteOptionsMatched<TName extends string | undefined = string
  * const router = createRouter(routes)
  * ```
  */
-export declare function createRouter<const TRoutes extends Routes, const TOptions extends RouterOptions>(routes: TRoutes, options?: TOptions): Router<TRoutes, TOptions>;
+export declare function createRouter<const TRoutes extends Routes, const TOptions extends RouterOptions, const TPlugin extends RouterPlugin = EmptyRouterPlugin>(routes: TRoutes, options?: TOptions, plugins?: TPlugin[]): Router<TRoutes, TOptions, TPlugin>;
+
+export declare function createRouter<const TRoutes extends Routes, const TOptions extends RouterOptions, const TPlugin extends RouterPlugin = EmptyRouterPlugin>(routes: TRoutes[], options?: TOptions, plugins?: TPlugin[]): Router<TRoutes, TOptions, TPlugin>;
 
-export declare function createRouter<const TRoutes extends Routes, const TOptions extends RouterOptions>(arrayOfRoutes: TRoutes[], options?: TOptions): Router<TRoutes, TOptions>;
+export declare function createRouterPlugin<TRoutes extends Routes = [], TRejections extends Record<string, Component> = {}>(plugin: Partial<RouterPlugin<TRoutes, TRejections>>): RouterPlugin<TRoutes, TRejections>;
 
 /**
  * An error thrown when duplicate parameters are detected in a route.
@@ -276,6 +311,11 @@ export declare class DuplicateParamsError extends Error {
     constructor(paramName: string);
 }
 
+declare type EmptyRouterPlugin = {
+    routes: [];
+    rejections: {};
+};
+
 /**
  * Extracts the parameter name from a string, handling optional parameters denoted by a leading '?'.
  * @template TParam - The string from which to extract the parameter name.
@@ -452,6 +492,11 @@ declare type IsRouteUnnamed<T extends Route> = StringHasValue<T['name']> extends
  */
 export declare function isUrl(value: unknown): value is Url;
 
+/**
+ * Extracts the keys of a union type.
+ */
+declare type KeysOfUnion<T> = T extends T ? keyof T : never;
+
 declare type MakeOptional<T> = {
     [P in WithOptionalProperties<T>]?: T[P];
 } & {
@@ -586,7 +631,7 @@ declare type PathParamsWithParamNameExtracted<TPath extends string> = {
 /**
  * Determines what assets are prefetched. A boolean enables or disables all prefetching.
  */
-declare type PrefetchConfig = boolean | PrefetchStrategy | PrefetchConfigOptions;
+export declare type PrefetchConfig = boolean | PrefetchStrategy | PrefetchConfigOptions;
 
 declare type PrefetchConfigOptions = {
     /**
@@ -606,12 +651,12 @@ declare type PrefetchConfigOptions = {
  * eager: Fetched immediately
  * lazy: Fetched when visible
  */
-declare type PrefetchStrategy = 'eager' | 'lazy';
+export declare type PrefetchStrategy = 'eager' | 'lazy' | 'intent';
 
 /**
  * Context provided to props callback functions
  */
-declare type PropsCallbackContext = {
+export declare type PropsCallbackContext = {
     push: CallbackContext['push'];
     replace: CallbackContext['replace'];
     reject: CallbackContext['reject'];
@@ -649,7 +694,7 @@ declare type QueryParamsWithParamNameExtracted<T extends string> = {
     [K in keyof ExtractQueryParamsFromQueryString<T> as ExtractParamName<K>]?: Param;
 };
 
-declare type QuerySource = ConstructorParameters<typeof URLSearchParams>[0];
+export declare type QuerySource = ConstructorParameters<typeof URLSearchParams>[0];
 
 /**
  * Represents the state of currently registered router, and route meta. Used to provide correct type context for
@@ -671,8 +716,8 @@ export declare interface Register {
 /**
  * Represents the possible Rejections registered within {@link Register}
  */
-export declare type RegisteredRejectionType = Register extends {
-    router: Router<infer __TRoutes extends Routes, infer TOptions extends RouterOptions>;
+export declare type RegisteredRejectionType<T = Register> = T extends {
+    router: Router<Routes, infer TOptions extends RouterOptions>;
 } ? keyof TOptions['rejections'] | BuiltInRejectionType : BuiltInRejectionType;
 
 /**
@@ -683,7 +728,7 @@ export declare type RegisteredRouteMap = RoutesMap<RegisteredRoutes>;
 /**
  * Represents the Router property within {@link Register}
  */
-export declare type RegisteredRouter = Register extends {
+export declare type RegisteredRouter<T = Register> = T extends {
     router: infer TRouter;
 } ? TRouter : Router;
 
@@ -710,7 +755,7 @@ export declare type RegisteredRouterRoute = RegisteredRouter['route'];
 /**
  * Represents the Router routes property within {@link Register}
  */
-export declare type RegisteredRoutes = Register extends {
+export declare type RegisteredRoutes<T = Register> = T extends {
     router: Router<infer TRoutes extends Routes>;
 } ? TRoutes : Route[];
 
@@ -831,6 +876,10 @@ declare type RouteGetByKey<TRoutes extends Routes, TKey extends RoutesName<TRout
  */
 export declare type RouteHook = BeforeRouteHook | AfterRouteHook;
 
+export declare type RouteHookAfterRunner = (context: AfterHookContext) => Promise<AfterRouteHookResponse>;
+
+export declare type RouteHookBeforeRunner = (context: BeforeHookContext) => Promise<BeforeRouteHookResponse>;
+
 /**
  * Context provided to route hooks, containing context of previous route and functions for triggering rejections and push/replace to another route.
  */
@@ -857,24 +906,40 @@ export declare type RouteHookRemove = () => void;
  */
 export declare type RouteHookResponse = BeforeRouteHookResponse | AfterRouteHookResponse;
 
+declare class RouteHooks {
+    onBeforeRouteEnter: Set<BeforeRouteHook>;
+    onBeforeRouteUpdate: Set<BeforeRouteHook>;
+    onBeforeRouteLeave: Set<BeforeRouteHook>;
+    onAfterRouteEnter: Set<AfterRouteHook>;
+    onAfterRouteUpdate: Set<AfterRouteHook>;
+    onAfterRouteLeave: Set<AfterRouteHook>;
+}
+
+export declare type RouteHookTiming = 'global' | 'component';
+
 /**
  * Represents additional metadata associated with a route, customizable via declaration merging.
  */
-export declare type RouteMeta = Register extends {
+export declare type RouteMeta<T = Register> = T extends {
     routeMeta: infer RouteMeta extends Record<string, unknown>;
 } ? RouteMeta : Record<string, unknown>;
 
 declare type RouteParamsByKey<TRoutes extends Routes, TKey extends string> = ExtractRouteParamTypesWithoutLosingOptional<RouteGetByKey<TRoutes, TKey>>;
 
-export declare type Router<TRoutes extends Routes = any, __TOptions extends RouterOptions = any> = Plugin_2 & {
+export declare type Router<TRoutes extends Routes = any, TOptions extends RouterOptions = any, TPlugin extends RouterPlugin = any> = {
+    /**
+     * Installs the router into a Vue application instance.
+     * @param app The Vue application instance to install the router into
+     */
+    install: (app: App) => void;
     /**
      * Manages the current route state.
      */
-    route: RouterRoutes<TRoutes>;
+    route: RouterRoutes<TRoutes> | RouterRoutes<TPlugin['routes']>;
     /**
      * Creates a ResolvedRoute record for a given route name and params.
      */
-    resolve: RouterResolve<TRoutes>;
+    resolve: RouterResolve<TRoutes | TPlugin['routes']>;
     /**
      * Creates a ResolvedRoute record for a given URL.
      */
@@ -882,15 +947,15 @@ export declare type Router<TRoutes extends Routes = any, __TOptions extends Rout
     /**
      * Navigates to a specified path or route object in the history stack, adding a new entry.
      */
-    push: RouterPush<TRoutes>;
+    push: RouterPush<TRoutes | TPlugin['routes']>;
     /**
      * Replaces the current entry in the history stack with a new one.
      */
-    replace: RouterReplace<TRoutes>;
+    replace: RouterReplace<TRoutes | TPlugin['routes']>;
     /**
      * Handles route rejection based on a specified rejection type.
      */
-    reject: RouterReject;
+    reject: RouterReject<keyof TOptions['rejections'] | KeysOfUnion<TPlugin['rejections']>>;
     /**
      * Forces the router to re-evaluate the current route.
      */
@@ -943,13 +1008,14 @@ export declare type Router<TRoutes extends Routes = any, __TOptions extends Rout
      * Initializes the router based on the initial route. Automatically called when the router is installed. Calling this more than once has no effect.
      */
     start: () => Promise<void>;
+    /**
+     * Stops the router and teardown any listeners.
+     */
+    stop: () => void;
 };
 
 declare type RouterHistoryMode = 'auto' | 'browser' | 'memory' | 'hash';
 
-/**
- * @ignore
- */
 export declare const RouterLink: __VLS_WithTemplateSlots_2<DefineComponent<    {
 /**
 * The url string to navigate to or a callback that returns a url string
@@ -968,9 +1034,9 @@ to: Url | ResolvedRoute | ToCallback;
 * Determines what assets are prefetched when router-link is rendered for this route. Overrides route level prefetch.
 */
 prefetch?: PrefetchConfig;
-} & RouterPushOptions & {}>, {
+} & RouterPushOptions> & Readonly<{}>, {
 prefetch: PrefetchConfig;
-}, {}, {}, {}, string, ComponentProvideOptions, false, {}>, Readonly<{
+}, {}, {}, {}, string, ComponentProvideOptions, false, {}, HTMLAnchorElement>, Readonly<{
     default?: (props: {
         route: ResolvedRoute | undefined;
         isMatch: boolean;
@@ -997,7 +1063,7 @@ export declare class RouterNotInstalledError extends Error {
 /**
  * Options to initialize a {@link Router} instance.
  */
-export declare type RouterOptions = {
+export declare type RouterOptions = WithHooks & {
     /**
      * Initial URL for the router to use. Required if using Node environment. Defaults to window.location when using browser.
      *
@@ -1025,6 +1091,17 @@ export declare type RouterOptions = {
     rejections?: Partial<Record<string, Component>>;
 };
 
+export declare type RouterPlugin<TRoutes extends Routes = Routes, TRejections extends Record<string, Component> = Record<string, Component>> = {
+    routes: TRoutes;
+    rejections: TRejections;
+    onBeforeRouteEnter?: MaybeArray<BeforeRouteHook>;
+    onAfterRouteEnter?: MaybeArray<AfterRouteHook>;
+    onBeforeRouteUpdate?: MaybeArray<BeforeRouteHook>;
+    onAfterRouteUpdate?: MaybeArray<AfterRouteHook>;
+    onBeforeRouteLeave?: MaybeArray<BeforeRouteHook>;
+    onAfterRouteLeave?: MaybeArray<AfterRouteHook>;
+};
+
 declare type RouterPush<TRoutes extends Routes = any> = {
     <TSource extends RoutesName<TRoutes>>(name: TSource, ...args: RouterPushArgs<TRoutes, TSource>): Promise<void>;
     (route: ResolvedRoute, options?: RouterPushOptions): Promise<void>;
@@ -1033,17 +1110,29 @@ declare type RouterPush<TRoutes extends Routes = any> = {
 
 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<TState = unknown> = {
+export declare type RouterPushOptions<TState = unknown> = {
+    /**
+     * The query string to add to the url.
+     */
     query?: QuerySource;
+    /**
+     * The hash to append to the url.
+     */
     hash?: string;
+    /**
+     * Whether to replace the current history entry.
+     */
     replace?: boolean;
+    /**
+     * State values to pass to the route.
+     */
     state?: Partial<TState>;
 };
 
-export declare type RouterReject = (type: RegisteredRejectionType) => void;
+declare type RouterReject<TRejectionType extends PropertyKey> = (type: AsString<TRejectionType> | BuiltInRejectionType) => void;
 
 declare type RouterRejection = Ref<null | {
-    type: RegisteredRejectionType;
+    type: string;
     component: Component;
 }>;
 
@@ -1071,7 +1160,7 @@ declare type RouterResolveOptions<TState = unknown> = {
     state?: Partial<TState>;
 };
 
-declare type RouterRoute<TRoute extends ResolvedRoute = ResolvedRoute> = {
+export declare type RouterRoute<TRoute extends ResolvedRoute = ResolvedRoute> = {
     readonly id: TRoute['id'];
     readonly name: TRoute['name'];
     readonly matched: TRoute['matched'];
@@ -1092,14 +1181,11 @@ export declare type RouterRoutes<TRoutes extends Routes> = {
     [K in keyof TRoutes]: RouterRoute<ResolvedRoute<TRoutes[K]>>;
 }[number];
 
-/**
- * @ignore
- */
 export declare const RouterView: __VLS_WithTemplateSlots<DefineComponent<    {
 name?: string;
 }, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<{
 name?: string;
-} & {}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {}>, Readonly<{
+}> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {}, any>, Readonly<{
     default?: (props: {
         route: RouterRoute;
         component: Component;
@@ -1138,7 +1224,7 @@ declare type RouteWithMatch<TRoute extends RouterRoute, TRouteName extends TRout
 
 declare type StringHasValue<T> = string extends T ? true : '' extends T ? false : T extends string ? true : false;
 
-declare type ToCallback = (resolve: RegisteredRouter['resolve']) => ResolvedRoute | Url | undefined;
+export declare type ToCallback = (resolve: RegisteredRouter['resolve']) => ResolvedRoute | Url | undefined;
 
 declare type ToHash<T extends string | Hash | undefined> = T extends string ? Hash<T> : T extends undefined ? Hash<''> : unknown extends T ? Hash<''> : T;
 
@@ -1295,7 +1381,7 @@ export declare function withDefault<TParam extends Param>(param: TParam, default
 /**
  * Defines route hooks that can be applied before entering, updating, or leaving a route, as well as after these events.
  */
-declare type WithHooks = {
+export declare type WithHooks = {
     onBeforeRouteEnter?: MaybeArray<BeforeRouteHook>;
     onBeforeRouteUpdate?: MaybeArray<BeforeRouteHook>;
     onBeforeRouteLeave?: MaybeArray<BeforeRouteHook>;