@kitbag/router 0.13.2 → 0.13.3

package/dist/kitbag-router.d.ts

@@ -5,7 +5,6 @@ import { ComponentProvideOptions } from 'vue';
 import { ComputedRef } from 'vue';
 import { DefineComponent } from 'vue';
 import { FunctionalComponent } from 'vue';
-import { InjectionKey } from 'vue';
 import { MaybeRefOrGetter } from 'vue';
 import { Plugin as Plugin_2 } from 'vue';
 import { PublicProps } from 'vue';
@@ -13,60 +12,6 @@ import { Ref } from 'vue';
 import { UnwrapRef } from 'vue';
 import { VNode } from 'vue';
 
-declare const __VLS_component: DefineComponent<    {
-name?: string;
-}, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<{
-name?: string;
-} & {}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {}>;
-
-declare const __VLS_component_2: DefineComponent<RouterLinkProps & RouterPushOptions, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<RouterLinkProps & RouterPushOptions & {}>, {
-prefetch: PrefetchConfig;
-}, {}, {}, {}, string, ComponentProvideOptions, false, {}>;
-
-declare function __VLS_template(): {
-    slots: Readonly<{
-        default?: (props: {
-            route: RouterRoute;
-            component: Component;
-            rejection: UnwrapRef<RouterRejection>;
-        }) => VNode;
-    }> & {
-        default?: (props: {
-            route: RouterRoute;
-            component: Component;
-            rejection: UnwrapRef<RouterRejection>;
-        }) => VNode;
-    };
-    refs: {};
-    attrs: Partial<{}>;
-};
-
-declare function __VLS_template_2(): {
-    slots: Readonly<{
-        default?: (props: {
-            resolved: string;
-            isMatch: boolean;
-            isExactMatch: boolean;
-            isExternal: boolean;
-        }) => unknown;
-    }> & {
-        default?: (props: {
-            resolved: string;
-            isMatch: boolean;
-            isExactMatch: boolean;
-            isExternal: boolean;
-        }) => unknown;
-    };
-    refs: {
-        element: HTMLAnchorElement;
-    };
-    attrs: Partial<{}>;
-};
-
-declare type __VLS_TemplateResult = ReturnType<typeof __VLS_template>;
-
-declare type __VLS_TemplateResult_2 = ReturnType<typeof __VLS_template_2>;
-
 declare type __VLS_WithTemplateSlots<T, S> = T & {
     new (): {
         $slots: S;
@@ -104,7 +49,7 @@ export declare type AfterRouteHook = (to: ResolvedRoute, context: AfterRouteHook
 /**
  * Context provided to route hooks, containing context of previous route and functions for triggering rejections and push/replace to another route.
  */
-declare type AfterRouteHookContext = RouteHookContext;
+export declare type AfterRouteHookContext = RouteHookContext;
 
 /**
  * Enumerates the lifecycle events for after route hooks.
@@ -121,6 +66,11 @@ declare type AllPropertiesAreOptional<T> = Record<string, unknown> extends T ? t
 
 declare type AsNamedRoute<T extends Route> = IsRouteUnnamed<T> extends true ? never : T;
 
+/**
+ * Converts a string to a valid URL.
+ * @param value - The string to convert.
+ * @returns The valid URL.
+ */
 export declare function asUrl(value: string): Url;
 
 /**
@@ -135,7 +85,7 @@ export declare type BeforeRouteHook = (to: ResolvedRoute, context: BeforeRouteHo
  * Context provided to route hooks, containing context of previous route and functions for triggering rejections, push/replace to another route,
  * as well as aborting current route change.
  */
-declare type BeforeRouteHookContext = RouteHookContext & {
+export declare type BeforeRouteHookContext = RouteHookContext & {
     abort: CallbackContextAbort;
 };
 
@@ -224,29 +174,7 @@ declare type CombineQueryString<TParent extends string | undefined, TChild exten
 
 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
- *
- * @param component The component to mount
- * @param props A callback that returns the props or attributes to bind to the component
- * @returns A component
- *
- * @example
- * ```ts
- * import { createRoute, component } from '@kitbag/router'
- *
- * export const routes = createRoute({
- *   name: 'User',
- *   path: '/',
- *   component: component(User, () => ({ userId: 1 }))
- * })
- * ```
- */
-export declare function component<TComponent extends Component>(component: TComponent, props: ComponentPropsGetter<TComponent>): Component;
-
-export declare type ComponentProps<TComponent extends Component> = TComponent extends Constructor ? InstanceType<TComponent>['$props'] : TComponent extends AsyncComponentLoader<infer T extends Component> ? ComponentProps<T> : TComponent extends FunctionalComponent<infer T> ? T : never;
-
-declare type ComponentPropsGetter<TComponent extends Component> = () => MaybePromise<ComponentProps<TComponent>>;
+declare type ComponentProps<TComponent extends Component> = TComponent extends Constructor ? InstanceType<TComponent>['$props'] : TComponent extends AsyncComponentLoader<infer T extends Component> ? ComponentProps<T> : TComponent extends FunctionalComponent<infer T> ? T : never;
 
 declare type Constructor = new (...args: any) => any;
 
@@ -338,6 +266,7 @@ export declare function createRouter<const TRoutes extends Routes, const TOption
  * 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.
+ * @group Errors
  */
 export declare class DuplicateParamsError extends Error {
     /**
@@ -448,30 +377,65 @@ declare type Identity<T> = T extends object ? {} & {
 
 declare type IsEmptyObject<T> = T extends Record<string, never> ? (keyof T extends never ? true : false) : false;
 
-export declare function isParamWithDefault(param: Param): param is ParamWithDefault;
-
+/**
+ * A type guard for determining if a value is a valid RouterRoute.
+ * @param route - The value to check.
+ * @returns `true` if the value is a valid RouterRoute, otherwise `false`.
+ * @group Type Guards
+ */
 export declare function isRoute(route: unknown): route is RouterRoute;
 
+/**
+ * A type guard for determining if a value is a valid RouterRoute with an exact match.
+ * @param route - The value to check.
+ * @param routeName - The expected route name.
+ * @returns `true` if the value is a valid RouterRoute with an exact match, otherwise `false`.
+ * @group Type Guards
+ */
 export declare function isRoute<TRoute extends RouterRoute, TRouteName extends TRoute['name']>(route: TRoute, routeName: TRouteName, options: IsRouteOptions & {
     exact: true;
 }): route is TRoute & {
     name: TRouteName;
 };
 
-export declare function isRoute<TRoute extends RouterRoute, TRouteName extends TRoute['name']>(route: TRoute, routeName: TRouteName, options?: IsRouteOptions): route is TRoute & {
-    name: `${TRouteName}${string}`;
-};
+/**
+ * A type guard for determining if a value is a valid RouterRoute with a partial match.
+ * @param route - The value to check.
+ * @param routeName - The expected route name.
+ * @returns `true` if the value is a valid RouterRoute with a partial match, otherwise `false`.
+ * @group Type Guards
+ */
+export declare function isRoute<TRoute extends RouterRoute, TRouteName extends TRoute['name']>(route: TRoute, routeName: TRouteName, options?: IsRouteOptions): route is RouteWithMatch<TRoute, TRouteName>;
 
+/**
+ * A type guard for determining if a value is a valid RegisteredRouterRoute with an exact match.
+ * @param route - The value to check.
+ * @param routeName - The expected route name.
+ * @returns `true` if the value is a valid RegisteredRouterRoute with an exact match, otherwise `false`.
+ * @group Type Guards
+ */
 export declare function isRoute<TRouteName extends RegisteredRoutesName>(route: unknown, routeName: TRouteName, options: IsRouteOptions & {
     exact: true;
 }): route is RegisteredRouterRoute & {
     name: TRouteName;
 };
 
-export declare function isRoute<TRouteName extends RegisteredRoutesName>(route: unknown, routeName: TRouteName, options?: IsRouteOptions): route is RegisteredRouterRoute & {
-    name: `${TRouteName}${string}`;
-};
+/**
+ * A type guard for determining if a value is a valid RegisteredRouterRoute with a partial match.
+ * @param route - The value to check.
+ * @param routeName - The expected route name.
+ * @returns `true` if the value is a valid RegisteredRouterRoute with a partial match, otherwise `false`.
+ * @group Type Guards
+ */
+export declare function isRoute<TRouteName extends RegisteredRoutesName>(route: unknown, routeName: TRouteName, options?: IsRouteOptions): route is RouteWithMatch<RegisteredRouterRoute, TRouteName>;
 
+/**
+ * A type guard for determining if a value is a valid RouterRoute.
+ * @param route - The value to check.
+ * @param routeName - The expected route name.
+ * @returns `true` if the value is a valid RouterRoute, otherwise `false`.
+ * @group Type Guards
+ */
 export declare function isRoute(route: unknown, routeName?: string, options?: IsRouteOptions): boolean;
 
 declare type IsRouteOptions = {
@@ -480,6 +444,12 @@ declare type IsRouteOptions = {
 
 declare type IsRouteUnnamed<T extends Route> = StringHasValue<T['name']> extends true ? false : true;
 
+/**
+ * A type guard for determining if a value is a valid URL.
+ * @param value - The value to check.
+ * @returns `true` if the value is a valid URL, otherwise `false`.
+ * @group Type Guards
+ */
 export declare function isUrl(value: unknown): value is Url;
 
 declare type MakeOptional<T> = {
@@ -492,12 +462,22 @@ declare type MaybeArray<T> = T | T[];
 
 declare type MaybePromise<T> = T | Promise<T>;
 
+/**
+ * An error thrown when a parent's meta has the same key as a child and the types are not compatible.
+ * A child's meta can override properties of the parent, however the types must match!
+ * @group Errors
+ */
+export declare class MetaPropertyConflict extends Error {
+    constructor(property?: string);
+}
+
 /**
  * Registers a hook that is called after a route has been entered. Must be called during setup.
  * This allows performing actions right after the component becomes active, such as fetching data or setting up event listeners.
  *
  * @param AfterRouteHook - The hook callback function
  * @returns {RouteHookRemove} A function that removes the added hook.
+ * @group Hooks
  */
 export declare const onAfterRouteEnter: AddAfterRouteHook;
 
@@ -507,6 +487,7 @@ export declare const onAfterRouteEnter: AddAfterRouteHook;
  *
  * @param AfterRouteHook - The hook callback function
  * @returns {RouteHookRemove} A function that removes the added hook.
+ * @group Hooks
  */
 export declare const onAfterRouteLeave: AddAfterRouteHook;
 
@@ -516,6 +497,7 @@ export declare const onAfterRouteLeave: AddAfterRouteHook;
  *
  * @param AfterRouteHook - The hook callback function
  * @returns {RouteHookRemove} A function that removes the added hook.
+ * @group Hooks
  */
 export declare const onAfterRouteUpdate: AddAfterRouteHook;
 
@@ -525,6 +507,7 @@ export declare const onAfterRouteUpdate: AddAfterRouteHook;
  *
  * @param BeforeRouteHook - The hook callback function
  * @returns {RouteHookRemove} A function that removes the added hook.
+ * @group Hooks
  */
 export declare const onBeforeRouteLeave: AddBeforeRouteHook;
 
@@ -534,6 +517,7 @@ export declare const onBeforeRouteLeave: AddBeforeRouteHook;
  *
  * @param BeforeRouteHook - The hook callback function
  * @returns {RouteHookRemove} A function that removes the added hook.
+ * @group Hooks
  */
 export declare const onBeforeRouteUpdate: AddBeforeRouteHook;
 
@@ -565,7 +549,7 @@ declare type ParamStart = typeof paramStart;
 
 declare const paramStart = "[";
 
-export declare type ParamWithDefault<TParam extends Param = Param> = Required<ParamGetSet<ExtractParamType<TParam>>>;
+declare type ParamWithDefault<TParam extends Param = Param> = Required<ParamGetSet<ExtractParamType<TParam>>>;
 
 declare type Path<TPath extends string = string, TParams extends PathParamsWithParamNameExtracted<TPath> = Record<string, Param | undefined>> = {
     value: TPath;
@@ -624,6 +608,15 @@ declare type PrefetchConfigOptions = {
  */
 declare type PrefetchStrategy = 'eager' | 'lazy';
 
+/**
+ * Context provided to props callback functions
+ */
+declare type PropsCallbackContext = {
+    push: CallbackContext['push'];
+    replace: CallbackContext['replace'];
+    reject: CallbackContext['reject'];
+};
+
 declare type Query<TQuery extends string = string, TQueryParams extends QueryParamsWithParamNameExtracted<TQuery> = Record<string, Param | undefined>> = {
     value: TQuery;
     params: string extends TQuery ? Record<string, Param> : Identity<ExtractQueryParamsFromQueryString<TQuery, TQueryParams>>;
@@ -736,7 +729,7 @@ declare type RemoveLeadingQuestionMarkFromKeys<T extends Record<string, unknown>
  * Represents a route that the router has matched to current browser location.
  * @template TRoute - Underlying Route that has been resolved.
  */
-declare type ResolvedRoute<TRoute extends Route = Route> = Readonly<{
+export declare type ResolvedRoute<TRoute extends Route = Route> = Readonly<{
     /**
      * Unique identifier for the route, generated by router.
      */
@@ -853,9 +846,9 @@ export declare type RouteHook = BeforeRouteHook | AfterRouteHook;
  */
 declare type RouteHookContext = {
     from: ResolvedRoute | null;
-    reject: RouterReject;
-    push: RegisteredRouterPush;
-    replace: RegisteredRouterReplace;
+    reject: CallbackContext['reject'];
+    push: CallbackContext['push'];
+    replace: CallbackContext['replace'];
 };
 
 /**
@@ -971,23 +964,48 @@ declare type RouterFindArgs<TRoutes extends Routes, TSource extends RoutesName<T
 
 declare type RouterHistoryMode = 'auto' | 'browser' | 'memory' | 'hash';
 
-export declare const routerInjectionKey: InjectionKey<RegisteredRouter>;
-
-export declare const RouterLink: __VLS_WithTemplateSlots_2<typeof __VLS_component_2, __VLS_TemplateResult_2["slots"]>;
-
-declare type RouterLinkProps = {
-    /**
-     * The url string to navigate to or a callback that returns a url string
-     */
-    to: Url | ToCallback;
-    /**
-     * Determines what assets are prefetched when router-link is rendered for this route. Overrides route level prefetch.
-     */
-    prefetch?: PrefetchConfig;
-};
+/**
+ * @ignore
+ */
+export declare const RouterLink: __VLS_WithTemplateSlots_2<DefineComponent<    {
+/**
+* The url string to navigate to or a callback that returns a url string
+*/
+to: Url | ((resolve: RegisteredRouter["resolve"]) => Url);
+/**
+* Determines what assets are prefetched when router-link is rendered for this route. Overrides route level prefetch.
+*/
+prefetch?: PrefetchConfig;
+} & RouterPushOptions, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<{
+/**
+* The url string to navigate to or a callback that returns a url string
+*/
+to: Url | ((resolve: RegisteredRouter["resolve"]) => Url);
+/**
+* Determines what assets are prefetched when router-link is rendered for this route. Overrides route level prefetch.
+*/
+prefetch?: PrefetchConfig;
+} & RouterPushOptions & {}>, {
+prefetch: PrefetchConfig;
+}, {}, {}, {}, string, ComponentProvideOptions, false, {}>, Readonly<{
+    default?: (props: {
+        resolved: string;
+        isMatch: boolean;
+        isExactMatch: boolean;
+        isExternal: boolean;
+    }) => unknown;
+}> & {
+    default?: (props: {
+        resolved: string;
+        isMatch: boolean;
+        isExactMatch: boolean;
+        isExternal: boolean;
+    }) => unknown;
+}>;
 
 /**
  * An error thrown when an attempt is made to use routing functionality before the router has been installed.
+ * @group Errors
  */
 export declare class RouterNotInstalledError extends Error {
     constructor();
@@ -1045,8 +1063,6 @@ declare type RouterRejection = Ref<null | {
     component: Component;
 }>;
 
-export declare const routerRejectionKey: InjectionKey<RouterRejection>;
-
 declare type RouterReplace<TRoutes extends Routes> = {
     <TSource extends RoutesName<TRoutes>>(name: TSource, ...args: RouterReplaceArgs<TRoutes, TSource>): Promise<void>;
     (url: Url, options?: RouterReplaceOptions): Promise<void>;
@@ -1092,7 +1108,26 @@ export declare type RouterRoutes<TRoutes extends Routes> = {
     [K in keyof TRoutes]: RouterRoute<ResolvedRoute<TRoutes[K]>>;
 }[number];
 
-export declare const RouterView: __VLS_WithTemplateSlots<typeof __VLS_component, __VLS_TemplateResult["slots"]>;
+/**
+ * @ignore
+ */
+export declare const RouterView: __VLS_WithTemplateSlots<DefineComponent<    {
+name?: string;
+}, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<{
+name?: string;
+} & {}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {}>, Readonly<{
+    default?: (props: {
+        route: RouterRoute;
+        component: Component;
+        rejection: UnwrapRef<RouterRejection>;
+    }) => VNode;
+}> & {
+    default?: (props: {
+        route: RouterRoute;
+        component: Component;
+        rejection: UnwrapRef<RouterRejection>;
+    }) => VNode;
+}>;
 
 /**
  * Represents an immutable array of Route instances. Return value of `createRoute`, expected param for `createRouter`.
@@ -1115,9 +1150,9 @@ declare type RouteUpdate<TRoute extends ResolvedRoute = ResolvedRoute> = Resolve
     (params: Partial<TRoute['params']>, options?: RouterPushOptions): Promise<void>;
 };
 
-declare type StringHasValue<T> = string extends T ? true : '' extends T ? false : T extends string ? true : false;
+declare type RouteWithMatch<TRoute extends RouterRoute, TRouteName extends TRoute['name']> = TRoute extends RouterRoute ? TRouteName extends TRoute['matches'][number]['name'] ? TRoute : never : never;
 
-declare type ToCallback = (resolve: RegisteredRouter['resolve']) => Url;
+declare type StringHasValue<T> = string extends T ? true : '' extends T ? false : T extends string ? true : false;
 
 declare type ToHash<T extends string | Hash | undefined> = T extends string ? Hash<T> : T extends undefined ? Hash<''> : unknown extends T ? Hash<''> : T;
 
@@ -1180,11 +1215,11 @@ 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 name of the route or the URL value.
+ * @param source - The name of the route or a valid URL.
  * @param params - If providing route name, this argument will expect corresponding params.
- * @param options - {@link RouterResolveOptions}Same options as router resolve.
+ * @param options - {@link RouterResolveOptions} Same options as router resolve.
  * @returns {UseLink} Reactive context values for as well as navigation methods.
- *
+ * @group Compositions
  */
 export declare function useLink<TRouteKey extends RegisteredRoutesName>(name: MaybeRefOrGetter<TRouteKey>, ...args: UseLinkArgs<TRouteKey>): UseLink;
 
@@ -1196,29 +1231,20 @@ export declare type UseLinkOptions = RouterResolveOptions & {
     prefetch?: PrefetchConfig;
 };
 
-/**
- * A composition to access the router's rejection state.
- *
- * @returns {RouterRejection} The rejection state object from the router, which can be used to handle route rejections
- *          such as authentication failures or permission denials.
- * @throws {Error} Throws an error if the router's rejection state is not available, typically indicating
- *         that createRouter was never called.
- */
-export declare function useRejection(): RouterRejection;
-
 /**
  * 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 name, it checks if the current active route includes the specified route name.
  *
+ * 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.
+ *
  * @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 name
- * if provided, throwing an error if the validation fails at any point during the component's lifecycle.
+ * @group Compositions
  */
 export declare function useRoute(): RegisteredRouterRoute;
 
@@ -1234,6 +1260,7 @@ export declare function useRoute<TRouteName extends RegisteredRoutesName>(routeN
 
 /**
  * An error thrown when there is a mismatch between an expected route and the one actually used.
+ * @group Errors
  */
 export declare class UseRouteInvalidError extends Error {
     /**
@@ -1251,6 +1278,7 @@ export declare class UseRouteInvalidError extends Error {
  * @returns The registered router instance.
  * @throws {RouterNotInstalledError} Throws an error if the router has not been installed,
  *         ensuring the component does not operate without routing functionality.
+ * @group Compositions
  */
 export declare function useRouter(): RegisteredRouter;
 
@@ -1259,7 +1287,7 @@ declare type WithComponent<TComponent extends Component = Component, TRoute exte
      * A Vue component, which can be either synchronous or asynchronous components.
      */
     component: TComponent;
-    props?: (route: ResolvedRoute<TRoute>, context: CallbackContext) => TComponent extends Component ? MaybePromise<ComponentProps<TComponent>> : {};
+    props?: (route: ResolvedRoute<TRoute>, context: PropsCallbackContext) => TComponent extends Component ? MaybePromise<ComponentProps<TComponent>> : {};
 };
 
 declare type WithComponents<TComponents extends Record<string, Component> = Record<string, Component>, TRoute extends Route = Route> = {
@@ -1268,7 +1296,7 @@ declare type WithComponents<TComponents extends Record<string, Component> = Reco
      */
     components: TComponents;
     props?: {
-        [TKey in keyof TComponents]?: (route: ResolvedRoute<TRoute>, context: CallbackContext) => TComponents[TKey] extends Component ? MaybePromise<ComponentProps<TComponents[TKey]>> : {};
+        [TKey in keyof TComponents]?: (route: ResolvedRoute<TRoute>, context: PropsCallbackContext) => TComponents[TKey] extends Component ? MaybePromise<ComponentProps<TComponents[TKey]>> : {};
     };
 };