@kitbag/router 0.2.0 → 0.4.0

package/README.md

@@ -2,14 +2,18 @@
 
 Type safe router for Vue.js
 
-[![Npm Version](https://img.shields.io/npm/v/@kitbag/router.svg)](https://www.npmjs.org/package/@kitbag/router)
-[![Netlify Status](https://api.netlify.com/api/v1/badges/c12f79b8-49f9-4529-bc23-f8ffca8919a3/deploy-status)](https://app.netlify.com/sites/kitbag-router/deploys)
+[![NPM Version][npm-badge]][npm-url]
+[![Netlify Status][netlify-badge]][netlify-url]
+[![Discord chat][discord-badge]][discord-url]
+[![Open in StackBlitz][stackblitz-badge]][stackblitz-url]
 
-Get started with the [documentation](https://kitbag-router.netlify.app/)
+<img src="https://kitbag.dev/kitbag-logo.svg" width="20%" />
 
-## Installation
+## Getting Started
+
+Get Started with our [documentation](https://kitbag-router.netlify.app/)
 
-Install Kitbag Router with your favorite package manager
+## Installation
 
 ```bash
 # bun
@@ -152,3 +156,12 @@ Use RouterLink for navigating between routes.
 ```
 
 This component gives the router the power to change the URL without reloading the page.
+
+[npm-badge]: https://img.shields.io/npm/v/@kitbag/router.svg
+[npm-url]: https://www.npmjs.org/package/@kitbag/router
+[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
+[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

@@ -6,13 +6,19 @@ import { DefineComponent } from 'vue';
 import { ExtractPropTypes } from 'vue';
 import { FunctionalComponent } from 'vue';
 import { InjectionKey } from 'vue';
+import { MaybeRefOrGetter } from 'vue';
 import { Plugin as Plugin_2 } from 'vue';
 import { PropType } from 'vue';
 import { PublicProps } from 'vue';
 import { Ref } from 'vue';
+import { RendererElement } from 'vue';
+import { RendererNode } from 'vue';
+import { VNode } from 'vue';
 
 declare type __VLS_NonUndefinedable<T> = T extends undefined ? never : T;
 
+declare type __VLS_NonUndefinedable_2<T> = T extends undefined ? never : T;
+
 declare type __VLS_TypePropsToRuntimeProps<T> = {
     [K in keyof T]-?: {} extends Pick<T, K> ? {
         type: PropType<__VLS_NonUndefinedable<T[K]>>;
@@ -22,6 +28,15 @@ declare type __VLS_TypePropsToRuntimeProps<T> = {
     };
 };
 
+declare type __VLS_TypePropsToRuntimeProps_2<T> = {
+    [K in keyof T]-?: {} extends Pick<T, K> ? {
+        type: PropType<__VLS_NonUndefinedable_2<T[K]>>;
+    } : {
+        type: PropType<T[K]>;
+        required: true;
+    };
+};
+
 declare type __VLS_WithTemplateSlots<T, S> = T & {
     new (): {
         $slots: S;
@@ -128,7 +143,7 @@ declare type BuiltInRejectionType = typeof builtInRejections[number];
 /**
  * Represents properties for child routes, including required component, name, and path.
  */
-export declare type ChildRouteProps = WithHooks & {
+export declare type ChildRouteProps = (WithComponent | WithComponents) & WithHooks & {
     /**
      * Name for route, used to create route keys and in navigation.
      */
@@ -145,10 +160,6 @@ export declare type ChildRouteProps = WithHooks & {
      * Query (aka search) part of URL.
      */
     query?: string | Query;
-    /**
-     * A Vue component, which can be either synchronous or asynchronous components.
-     */
-    component: Component;
     /**
      * Represents additional metadata associated with a route, customizable via declaration merging.
      */
@@ -259,27 +270,34 @@ declare type ExtractParamsFromPathString<TPath extends string, TParams extends R
 
 /**
  * Extracts the actual type from a parameter type, handling getters, setters, and potential undefined values.
+ * This type also is responsible for narrowing possibly undefined values when the param has a default value.
  * @template TParam - The parameter type.
  * @returns The extracted type, or 'string' as a fallback.
  */
-export declare type ExtractParamType<TParam extends Param | undefined> = TParam extends ParamGetSet<infer Type> ? undefined extends TParam ? Type | undefined : Type : TParam extends ParamGetter ? undefined extends TParam ? ReturnType<TParam> | undefined : ReturnType<TParam> : undefined extends TParam ? undefined : string;
+export declare type ExtractParamType<TParam extends Param> = TParam extends ParamGetSet<infer Type> ? TParam extends IsOptionalParam ? TParam extends ParamWithDefault ? Type : Type | undefined : Type : TParam extends ParamGetter ? ReturnType<TParam> : string;
 
 /**
  * Transforms a record of parameter types into a type with optional properties where the original type allows undefined.
  * @template TParams - The record of parameter types, possibly including undefined.
  * @returns A new type with the appropriate properties marked as optional.
  */
-export declare type ExtractParamTypes<TParams extends Record<string, Param | undefined>> = Identity<MakeOptional<{
+export declare type ExtractParamTypes<TParams extends Record<string, Param>> = Identity<MakeOptional<{
     [K in keyof TParams]: ExtractParamType<TParams[K]>;
 }>>;
 
+declare type ExtractParamTypesWithoutLosingOptional<TParams extends Record<string, Param>> = Identity<MakeOptional<{
+    [K in keyof TParams]: ExtractParamTypeWithoutLosingOptional<TParams[K]>;
+}>>;
+
+declare type ExtractParamTypeWithoutLosingOptional<TParam extends Param> = TParam extends ParamGetSet<infer Type> ? TParam extends IsOptionalParam ? Type | undefined : Type : TParam extends ParamGetter ? ReturnType<TParam> : string;
+
 /**
  * Determines the type of a path parameter from a record of parameter types, considering optional parameters.
  * @template TParam - The parameter name string.
  * @template TParams - The record object mapping parameter names to their types.
  * @returns The type associated with the parameter, or StringConstructor if unspecified; may be undefined for optional parameters.
  */
-export declare type ExtractPathParamType<TParam extends string, TParams extends Record<string, Param | undefined>> = TParam extends `?${infer OptionalParam}` ? OptionalParam extends keyof TParams ? TParams[OptionalParam] | undefined : StringConstructor | undefined : TParam extends keyof TParams ? TParams[TParam] : StringConstructor;
+export declare type ExtractPathParamType<TParam extends string, TParams extends Record<string, Param | undefined>> = TParam extends `?${infer OptionalParam}` ? OptionalParam extends keyof TParams ? TParams[OptionalParam] extends Param ? OptionalParamGetSet<TParams[OptionalParam]> : OptionalParamGetSet<StringConstructor> : OptionalParamGetSet<StringConstructor> : TParam extends keyof TParams ? TParams[TParam] : StringConstructor;
 
 declare type ExtractQueryParamsFromQueryString<TQuery extends string, TParams extends Record<string, Param | undefined> = Record<never, never>> = TQuery extends `${string}=${ParamStart}${infer Param}${ParamEnd}${infer Rest}` ? MergeParams<{
     [P in ExtractParamName<Param>]: ExtractPathParamType<Param, TParams>;
@@ -289,24 +307,27 @@ declare type ExtractRouteChildren<TRoute extends RouteProps> = TRoute extends Pa
 
 /**
  * Extracts combined types of path and query parameters for a given route, creating a unified parameter object.
+ * This parameter object type represents the expected type when accessing params from router.route or useRoute.
  * @template TRoute - The route type from which to extract and merge parameter types.
  * @returns A record of parameter names to their respective types, extracted and merged from both path and query parameters.
  */
-export declare type ExtractRouteParamTypes<TRoute extends {
+export declare type ExtractRouteParamTypes<TRoute> = TRoute extends {
     path: {
-        params: Record<string, unknown>;
+        params: infer PathParams extends Record<string, Param>;
     };
     query: {
-        params: Record<string, unknown>;
+        params: infer QueryParams extends Record<string, Param>;
     };
-}> = TRoute extends {
+} ? ExtractParamTypes<MergeParams<PathParams, QueryParams>> : Record<string, unknown>;
+
+declare type ExtractRouteParamTypesWithoutLosingOptional<TRoute> = TRoute extends {
     path: {
-        params: infer PathParams extends Record<string, Param | undefined>;
+        params: infer PathParams extends Record<string, Param>;
     };
     query: {
-        params: infer QueryParams extends Record<string, Param | undefined>;
+        params: infer QueryParams extends Record<string, Param>;
     };
-} ? ExtractParamTypes<MergeParams<PathParams, QueryParams>> : Record<string, unknown>;
+} ? ExtractParamTypesWithoutLosingOptional<MergeParams<PathParams, QueryParams>> : Record<string, unknown>;
 
 declare type Flatten<T extends any[]> = T extends [infer First, ...infer Rest] ? First extends unknown[] ? Flatten<[...First, ...Flatten<Rest>]> : [First, ...Flatten<Rest>] : [];
 
@@ -329,6 +350,10 @@ declare type Identity<T> = T extends object ? {} & {
 
 declare type IsEmptyObject<T> = T extends Record<string, never> ? (keyof T extends never ? true : false) : false;
 
+declare type IsOptionalParam = {
+    [optionalParamKey]: true;
+};
+
 /**
  * Type guard to check if a value conforms to the ParamGetSet type.
  * @param value - The value to check.
@@ -343,6 +368,8 @@ export declare function isParamGetSet(value: Param): value is ParamGetSet;
  */
 export declare function isParamGetter(value: Param): value is ParamGetter;
 
+export declare function isParamWithDefault(param: Param): param is ParamWithDefault;
+
 /**
  * Type guard function to determine if a given route configuration is a parent route, based on the presence of children.
  * @param value - The route configuration to check.
@@ -350,6 +377,30 @@ export declare function isParamGetter(value: Param): value is ParamGetter;
  */
 export declare function isParentRoute(value: RouteProps): value is ParentRouteProps;
 
+export declare function isParentRouteWithoutComponent(value: RouteProps): value is Omit<ParentRouteProps, 'component' | 'components'>;
+
+export declare function isRoute(route: unknown): route is RouterRoute;
+
+export declare function isRoute<TRouteKey extends RegisteredRoutesKey>(route: unknown, routeKey: TRouteKey, options?: IsRouteOptions): route is RouterRoute<ResolvedRoute<RegisteredRouteMap[TRouteKey]>>;
+
+declare type IsRouteOptions = {
+    exact?: boolean;
+};
+
+declare const isRouterRouteSymbol: unique symbol;
+
+export declare function isRouteWithComponent(value: RouteProps): value is RouteProps & WithComponent;
+
+export declare function isRouteWithComponent(value: Readonly<RouteProps>): value is Readonly<RouteProps & WithComponent>;
+
+export declare function isRouteWithComponent(value: DeepReadonly<RouteProps>): value is DeepReadonly<RouteProps & WithComponent>;
+
+export declare function isRouteWithComponents(value: RouteProps): value is RouteProps & WithComponents;
+
+export declare function isRouteWithComponents(value: Readonly<RouteProps>): value is Readonly<RouteProps & WithComponents>;
+
+export declare function isRouteWithComponents(value: DeepReadonly<RouteProps>): value is DeepReadonly<RouteProps & WithComponents>;
+
 declare type MakeOptional<T> = {
     [P in WithOptionalProperties<T>]?: T[P];
 } & {
@@ -421,6 +472,10 @@ declare type OnlyRequiredProperties<T> = {
     [K in keyof T as Extract<T[K], undefined> extends never ? K : never]: T[K];
 };
 
+declare type OptionalParamGetSet<TParam extends Param> = TParam extends ParamGetSet ? TParam & IsOptionalParam : ParamGetSet<ExtractParamType<TParam>> & IsOptionalParam;
+
+declare const optionalParamKey: unique symbol;
+
 export declare type Param = ParamGetter | ParamGetSet | RegExp | BooleanConstructor | NumberConstructor | StringConstructor | DateConstructor | JSON;
 
 export declare type ParamEnd = typeof paramEnd;
@@ -434,6 +489,7 @@ export declare type ParamExtras = {
 export declare type ParamGetSet<T = any> = {
     get: ParamGetter<T>;
     set: ParamSetter<T>;
+    defaultValue?: T;
 };
 
 export declare type ParamGetter<T = any> = (value: string, extras: ParamExtras) => T;
@@ -444,10 +500,12 @@ export declare type ParamStart = typeof paramStart;
 
 export declare const paramStart = "[";
 
+export declare type ParamWithDefault<TParam extends Param = Param> = Required<ParamGetSet<ExtractParamType<TParam>>>;
+
 /**
  * Represents properties common to parent routes in a route configuration, including hooks, path, and optional query parameters.
  */
-export declare type ParentRouteProps = WithHooks & {
+export declare type ParentRouteProps = Partial<WithComponent | WithComponents> & WithHooks & {
     /**
      * Name for route, used to create route keys and in navigation.
      */
@@ -468,19 +526,15 @@ export declare type ParentRouteProps = WithHooks & {
      * Children routes, expected type comes from `createRoutes()`
      */
     children: Routes;
-    /**
-     * A Vue component, which can be either synchronous or asynchronous components.
-     */
-    component?: Component;
     /**
      * Represents additional metadata associated with a route, customizable via declaration merging.
      */
     meta?: RouteMeta;
 };
 
-declare type Path<TPath extends string = any, TParams extends PathParams<TPath> = any> = {
+declare type Path<TPath extends string = string, TParams extends PathParams<TPath> = Record<string, Param | undefined>> = {
     path: TPath;
-    params: Identity<ExtractParamsFromPathString<TPath, TParams>>;
+    params: string extends TPath ? Record<string, Param> : Identity<ExtractParamsFromPathString<TPath, TParams>>;
     toString: () => string;
 };
 
@@ -517,9 +571,9 @@ declare type Props<TComponent extends Component> = TComponent extends Constructo
 
 declare type PropsGetter<TComponent extends Component> = () => MaybePromise<Props<TComponent>>;
 
-declare type Query<T extends string = any, P extends QueryParams<T> = any> = {
-    query: T;
-    params: Identity<ExtractQueryParamsFromQueryString<T, P>>;
+declare type Query<TQuery extends string = string, TQueryParams extends QueryParams<TQuery> = Record<string, Param | undefined>> = {
+    query: TQuery;
+    params: string extends TQuery ? Record<string, Param> : Identity<ExtractQueryParamsFromQueryString<TQuery, TQueryParams>>;
     toString: () => string;
 };
 
@@ -629,7 +683,7 @@ declare type ResolvedRoute<TRoute extends Route = BaseResolvedRoute> = DeepReado
      * 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: RouteProps[];
+    matches: TRoute['matches'];
     /**
      * Unique identifier for the route, generated by joining route `name` by period. Key is used for routing and for matching.
      */
@@ -641,7 +695,7 @@ declare type ResolvedRoute<TRoute extends Route = BaseResolvedRoute> = DeepReado
     /**
      * Key value pair for route params, values will be the user provided value from current browser location.
      */
-    params: ExtractRouteParamTypes<TRoute>;
+    params: BaseResolvedRoute extends TRoute ? Record<string, unknown> : ExtractRouteParamTypes<TRoute>;
 }>;
 
 declare type ResolvedRouteQuery = {
@@ -768,7 +822,7 @@ declare type RouteHookSuccessResponse = {
 export declare interface RouteMeta extends Record<string, unknown> {
 }
 
-declare type RouteParamsByKey<TRoutes extends Routes, TKey extends string> = ExtractRouteParamTypes<RouteGetByKey<TRoutes, TKey>>;
+declare type RouteParamsByKey<TRoutes extends Routes, TKey extends string> = ExtractRouteParamTypesWithoutLosingOptional<RouteGetByKey<TRoutes, TKey>>;
 
 /**
  * Unifies the properties of both parent and child routes, ensuring type safety and consistency across route configurations.
@@ -864,22 +918,22 @@ declare type RouterHistoryMode = 'auto' | 'browser' | 'memory' | 'hash';
 
 export declare const routerInjectionKey: InjectionKey<RegisteredRouter>;
 
-export declare const RouterLink: __VLS_WithTemplateSlots_2<DefineComponent<__VLS_TypePropsToRuntimeProps<{
+export declare const RouterLink: __VLS_WithTemplateSlots_2<DefineComponent<__VLS_TypePropsToRuntimeProps_2<{
 to: Url | ToCallback;
-} & RouterPushOptions>, {}, unknown, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<ExtractPropTypes<__VLS_TypePropsToRuntimeProps<{
+} & RouterPushOptions>, {}, unknown, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<ExtractPropTypes<__VLS_TypePropsToRuntimeProps_2<{
 to: Url | ToCallback;
 } & RouterPushOptions>>>, {}, {}>, Readonly<{
     default?: ((props: {
         resolved: string;
-        match: boolean;
-        exactMatch: boolean;
+        isMatch: boolean;
+        isExactMatch: boolean;
         isExternal: boolean;
     }) => unknown) | undefined;
 }> & {
     default?: ((props: {
         resolved: string;
-        match: boolean;
-        exactMatch: boolean;
+        isMatch: boolean;
+        isExactMatch: boolean;
         isExternal: boolean;
     }) => unknown) | undefined;
 }>;
@@ -957,18 +1011,35 @@ declare type RouterResolveOptions = {
 declare type RouterRoute<TRoute extends ResolvedRoute = ResolvedRoute> = Omit<ResolvedRoute, 'params'> & Readonly<{
     params: Writable<TRoute['params']>;
     update: RouteUpdate<TRoute>;
+    [isRouterRouteSymbol]: true;
 }>;
 
-export declare const RouterView: __VLS_WithTemplateSlots<DefineComponent<    {}, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<ExtractPropTypes<    {}>>, {}, {}>, Readonly<{
+export declare const RouterView: __VLS_WithTemplateSlots<DefineComponent<__VLS_TypePropsToRuntimeProps<{
+name?: string | undefined;
+}>, {}, unknown, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<ExtractPropTypes<__VLS_TypePropsToRuntimeProps<{
+name?: string | undefined;
+}>>>, {}, {}>, Readonly<{
     default?: ((props: {
         route: RouterRoute;
         component: Component;
-    }) => unknown) | undefined;
+        rejection: {
+            type: "NotFound";
+            component: Component;
+        } | null;
+    }) => VNode<RendererNode, RendererElement, {
+        [key: string]: any;
+    }>) | undefined;
 }> & {
     default?: ((props: {
         route: RouterRoute;
         component: Component;
-    }) => unknown) | undefined;
+        rejection: {
+            type: "NotFound";
+            component: Component;
+        } | null;
+    }) => VNode<RendererNode, RendererElement, {
+        [key: string]: any;
+    }>) | undefined;
 }>;
 
 /**
@@ -999,6 +1070,50 @@ declare type ToQuery<T extends string | Query | undefined> = T extends string ?
 
 declare type Url = `http://${string}` | `https://${string}` | `/${string}` | '/';
 
+export declare type UseLink = {
+    /**
+     * ResolvedRoute if matched. Same value as `router.find`
+     */
+    route: Ref<ResolvedRoute | undefined>;
+    /**
+     * Resolved URL with params interpolated and query applied. Same value as `router.resolve`.
+     */
+    href: Ref<string>;
+    /**
+     * True if route matches current URL or is ancestor of route that matches current URL
+     */
+    isMatch: Ref<boolean>;
+    /**
+     * True if route matches current URL. Route is the same as what's currently stored at `router.route`.
+     */
+    isExactMatch: Ref<boolean>;
+    /**
+     * Convenience method for executing `router.push` with route context passed in.
+     */
+    push: (options?: RouterPushOptions) => Promise<void>;
+    /**
+     * Convenience method for executing `router.replace` with route context passed in.
+     */
+    replace: (options?: RouterReplaceOptions) => Promise<void>;
+};
+
+/**
+ * A composition to export much of the functionality that drives RouterLink component. Can be given route details to discover resolved URL,
+ * 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 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 string & keyof RegisteredRouteMap>(routeKey: MaybeRefOrGetter<TRouteKey>, ...args: UseLinkArgs<TRouteKey>): UseLink;
+
+export declare function useLink(url: MaybeRefOrGetter<Url>): UseLink;
+
+declare type UseLinkArgs<TSource extends string & keyof RegisteredRouteMap, 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.
  *
@@ -1023,7 +1138,7 @@ export declare function useRejection(): RouterRejection;
  * The function also sets up a reactive watcher on the route object from the router to continually check the validity of the route key
  * if provided, throwing an error if the validation fails at any point during the component's lifecycle.
  */
-export declare function useRoute<TRouteKey extends string & keyof RegisteredRouteMap>(routeKey: TRouteKey): RouterRoute<ResolvedRoute<RegisteredRouteMap[TRouteKey]>>;
+export declare function useRoute<TRouteKey extends string & keyof RegisteredRouteMap>(routeKey: TRouteKey, options?: UseRouteOptions): RouterRoute<ResolvedRoute<RegisteredRouteMap[TRouteKey]>>;
 
 export declare function useRoute(): RouterRoute;
 
@@ -1040,6 +1155,10 @@ export declare class UseRouteInvalidError extends Error {
     constructor(routeName: string, actualRouteName: string);
 }
 
+export declare type UseRouteOptions = {
+    exact?: boolean;
+};
+
 /**
  * A composition to access the registered router instance within a Vue component.
  *
@@ -1049,6 +1168,22 @@ export declare class UseRouteInvalidError extends Error {
  */
 export declare function useRouter(): RegisteredRouter;
 
+declare type WithComponent = {
+    /**
+     * A Vue component, which can be either synchronous or asynchronous components.
+     */
+    component: Component;
+};
+
+declare type WithComponents = {
+    /**
+     * Multiple components for named views, which can be either synchronous or asynchronous components.
+     */
+    components: Record<string, Component>;
+};
+
+export declare function withDefault<TParam extends Param>(param: TParam, defaultValue: ExtractParamType<TParam>): ParamWithDefault<TParam>;
+
 /**
  * Defines route hooks that can be applied before entering, updating, or leaving a route, as well as after these events.
  */