@kitbag/router 0.1.1 → 0.3.0

package/README.md

@@ -2,14 +2,16 @@
 
 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/)
+## Getting Started
 
-## Installation
+Get Started with our [documentation](https://kitbag-router.netlify.app/)
 
-Install Kitbag Router with your favorite package manager
+## Installation
 
 ```bash
 # bun
@@ -152,3 +154,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

@@ -4,14 +4,21 @@ import { ComponentOptionsMixin } from 'vue';
 import { DeepReadonly } from 'vue';
 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]>>;
@@ -21,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;
@@ -127,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.
      */
@@ -144,10 +160,6 @@ export declare type ChildRouteProps = WithHooks & {
      * Query (aka search) part of URL.
      */
     query?: string | Query;
-    /**
-     * Type alias for Vue components, which can be either synchronous or asynchronous components.
-     */
-    component: RouteComponent;
     /**
      * Represents additional metadata associated with a route, customizable via declaration merging.
      */
@@ -174,6 +186,30 @@ declare type CombineQuery<TParent extends Query | undefined, TChild extends Quer
 
 declare type CombineQueryString<TParent extends string | undefined, TChild extends string | undefined> = StringHasValue<TParent> extends true ? StringHasValue<TChild> extends true ? `${TParent}&${TChild}` : 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 { createRoutes, component } from '@kitbag/router'
+ *
+ * export const routes = createRoutes([
+ *   {
+ *     name: 'User',
+ *     path: '/',
+ *     component: component(User, () => ({ userId: 1 }))
+ *   },
+ * ])
+ * ```
+ */
+export declare function component<TComponent extends Component>(component: TComponent, props: PropsGetter<TComponent>): Component;
+
+declare type Constructor = new (...args: any) => any;
+
 /**
  * Creates a router instance for a Vue application, equipped with methods for route handling, lifecycle hooks, and state management.
  *
@@ -228,11 +264,9 @@ export declare class DuplicateParamsError extends Error {
  */
 export declare type ExtractParamName<TParam extends string> = TParam extends `?${infer Param}` ? Param extends '' ? never : Param : TParam extends '' ? never : TParam;
 
-declare type ExtractParamsFromPathString<TPath extends string, TParams extends Record<string, Param | undefined> = Record<never, never>> = TPath extends `${infer Path}${ParamEnd}` ? ExtractParamsFromPathString<Path, TParams> : TPath extends `${string}:${infer Param}${ParamEnd}${infer Rest}` ? MergeParams<{
+declare type ExtractParamsFromPathString<TPath extends string, TParams extends Record<string, Param | undefined> = Record<never, never>> = TPath extends `${string}${ParamStart}${infer Param}${ParamEnd}${infer Rest}` ? MergeParams<{
     [P in ExtractParamName<Param>]: ExtractPathParamType<Param, TParams>;
-}, ExtractParamsFromPathString<Rest, TParams>> : TPath extends `${string}:${infer Param}` ? {
-    [P in ExtractParamName<Param>]: ExtractPathParamType<Param, TParams>;
-} : Record<never, never>;
+}, ExtractParamsFromPathString<Rest, TParams>> : Record<never, never>;
 
 /**
  * Extracts the actual type from a parameter type, handling getters, setters, and potential undefined values.
@@ -258,11 +292,9 @@ export declare type ExtractParamTypes<TParams extends Record<string, Param | und
  */
 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;
 
-declare type ExtractQueryParamsFromQueryString<TQuery extends string, TParams extends Record<string, Param | undefined> = Record<never, never>> = TQuery extends `${string}=:${infer Param}&${infer Rest}` ? MergeParams<{
-    [P in ExtractParamName<Param>]: ExtractPathParamType<Param, TParams>;
-}, ExtractQueryParamsFromQueryString<Rest, TParams>> : TQuery extends `${string}:${infer Param}` ? {
+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>;
-} : Record<never, never>;
+}, ExtractQueryParamsFromQueryString<Rest, TParams>> : Record<never, never>;
 
 declare type ExtractRouteChildren<TRoute extends RouteProps> = TRoute extends ParentRouteProps ? TRoute['children'] extends Route[] ? TRoute['children'] : [] : [];
 
@@ -329,6 +361,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];
 } & {
@@ -400,9 +456,11 @@ declare type OnlyRequiredProperties<T> = {
     [K in keyof T as Extract<T[K], undefined> extends never ? K : never]: T[K];
 };
 
-export declare type Param = ParamGetter | ParamGetSet | RegExp | BooleanConstructor | NumberConstructor | StringConstructor;
+export declare type Param = ParamGetter | ParamGetSet | RegExp | BooleanConstructor | NumberConstructor | StringConstructor | DateConstructor | JSON;
+
+export declare type ParamEnd = typeof paramEnd;
 
-declare type ParamEnd = '/';
+export declare const paramEnd = "]";
 
 export declare type ParamExtras = {
     invalid: (message?: string) => never;
@@ -417,10 +475,14 @@ export declare type ParamGetter<T = any> = (value: string, extras: ParamExtras)
 
 export declare type ParamSetter<T = any> = (value: T, extras: ParamExtras) => string;
 
+export declare type ParamStart = typeof paramStart;
+
+export declare const paramStart = "[";
+
 /**
  * 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.
      */
@@ -441,19 +503,15 @@ export declare type ParentRouteProps = WithHooks & {
      * Children routes, expected type comes from `createRoutes()`
      */
     children: Routes;
-    /**
-     * Type alias for Vue components, which can be either synchronous or asynchronous components.
-     */
-    component?: RouteComponent;
     /**
      * Represents additional metadata associated with a route, customizable via declaration merging.
      */
     meta?: RouteMeta;
 };
 
-declare type Path<T extends string = any, P extends PathParams<T> = any> = {
-    path: T;
-    params: Identity<ExtractParamsFromPathString<T, P>>;
+declare type Path<TPath extends string = any, TParams extends PathParams<TPath> = any> = {
+    path: TPath;
+    params: Identity<ExtractParamsFromPathString<TPath, TParams>>;
     toString: () => string;
 };
 
@@ -474,7 +532,7 @@ declare type Path<T extends string = any, P extends PathParams<T> = any> = {
  * export const routes = createRoutes([
  *   {
  *     name: 'home',
- *     path: path('/:foo', { foo: Number }),
+ *     path: path('/[foo]', { foo: Number }),
  *     component: Home
  *   },
  * ])
@@ -482,10 +540,14 @@ declare type Path<T extends string = any, P extends PathParams<T> = any> = {
  */
 export declare function path<TPath extends string, TParams extends PathParams<TPath>>(path: TPath, params: Identity<TParams>): Path<TPath, TParams>;
 
-declare type PathParams<T extends string> = {
-    [K in keyof ExtractParamsFromPathString<T>]?: Param;
+declare type PathParams<TPath extends string> = {
+    [K in keyof ExtractParamsFromPathString<TPath>]?: Param;
 };
 
+declare type Props<TComponent extends Component> = TComponent extends Constructor ? InstanceType<TComponent>['$props'] : TComponent extends AsyncComponentLoader<infer T extends Component> ? Props<T> : TComponent extends FunctionalComponent<infer T> ? T : never;
+
+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>>;
@@ -509,7 +571,7 @@ declare type Query<T extends string = any, P extends QueryParams<T> = any> = {
  * export const routes = createRoutes([
  *   {
  *     name: 'home',
- *     query: query('?bar=:bar', { bar: Boolean }),
+ *     query: query('bar=[bar]', { bar: Boolean }),
  *     component: Home
  *   },
  * ])
@@ -654,11 +716,6 @@ export declare type Route<TKey extends string | undefined = any, TPath extends s
     disabled: TDisabled extends boolean ? TDisabled : false;
 };
 
-/**
- * Type alias for Vue components, which can be either synchronous or asynchronous components.
- */
-export declare type RouteComponent = Component | DefineComponent | AsyncComponentLoader;
-
 declare type RouteGetByKey<TRoutes extends Routes, TKey extends RoutesKey<TRoutes>> = RoutesMap<TRoutes>[TKey];
 
 /**
@@ -838,22 +895,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;
 }>;
@@ -897,11 +954,11 @@ export declare type RouterReject = (type: RouterRejectionType) => void;
 
 declare type RouterRejection = Ref<null | {
     type: RouterRejectionType;
-    component: RouteComponent;
+    component: Component;
 }>;
 
 declare type RouterRejectionComponents = {
-    rejections?: Partial<Record<RouterRejectionType, RouteComponent>>;
+    rejections?: Partial<Record<RouterRejectionType, Component>>;
 };
 
 export declare const routerRejectionKey: InjectionKey<RouterRejection>;
@@ -931,18 +988,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: RouteComponent;
-    }) => unknown) | undefined;
+        component: Component;
+        rejection: {
+            type: "NotFound";
+            component: Component;
+        } | null;
+    }) => VNode<RendererNode, RendererElement, {
+        [key: string]: any;
+    }>) | undefined;
 }> & {
     default?: ((props: {
         route: RouterRoute;
-        component: RouteComponent;
-    }) => unknown) | undefined;
+        component: Component;
+        rejection: {
+            type: "NotFound";
+            component: Component;
+        } | null;
+    }) => VNode<RendererNode, RendererElement, {
+        [key: string]: any;
+    }>) | undefined;
 }>;
 
 /**
@@ -973,6 +1047,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.
  *
@@ -997,7 +1115,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;
 
@@ -1014,6 +1132,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.
  *
@@ -1023,6 +1145,20 @@ 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>;
+};
+
 /**
  * Defines route hooks that can be applied before entering, updating, or leaving a route, as well as after these events.
  */