@kitbag/router 0.20.12 → 0.22.0

package/README.md

@@ -7,6 +7,15 @@ Type safe router for Vue.js
 [![Discord chat][discord-badge]][discord-url]
 [![Open in StackBlitz][stackblitz-badge]][stackblitz-url]
 
+[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/zw7dpcc5HV
+[stackblitz-badge]: https://developer.stackblitz.com/img/open_in_stackblitz_small.svg
+[stackblitz-url]: https://stackblitz.com/~/github.com/kitbagjs/router-preview
+
 <img src="https://kitbag.dev/kitbag-logo.svg" width="20%" />
 
 ## Getting Started
@@ -15,6 +24,8 @@ Get Started with our [documentation](https://kitbag-router.netlify.app/) or our
 
 ## Installation
 
+Install Kitbag Router with your favorite package manager
+
 ```bash
 # bun
 bun add @kitbag/router
@@ -24,43 +35,52 @@ yarn add @kitbag/router
 npm install @kitbag/router
 ```
 
-## Define Basic Routes
+## Define Routes
 
-Create an array of possible routes. Learn more about [defining routes](https://kitbag-router.netlify.app/core-concepts/defining-routes).
+Routes are created individually using the [`createRoute`](https://kitbag-router.netlify.app/api/functions/createRoute) utility. Learn more about [defining routes](https://kitbag-router.netlify.app/core-concepts/routes).
 
 ```ts
-// /routes.ts
 import { createRoute } from '@kitbag/router'
 
 const Home = { template: '<div>Home</div>' }
 const About = { template: '<div>About</div>' }
 
-export const routes = [
+const routes = [
   createRoute({ name: 'home', path: '/', component: Home }),
   createRoute({ name: 'path', path: '/about', component: About }),
 ] as const
 ```
 
-## Plugin
+> [!NOTE] Type Safety
+> Using `as const` when defining routes is important as it ensures the types are correctly inferred.
 
-Create a router instance and pass it to the app as a plugin
+## Create Router
+
+A router is created using the [`createRouter`](https://kitbag-router.netlify.app/api/functions/createRouter) utility and passing in the routes.
 
 ```ts
-import { createApp } from 'vue'
 import { createRouter } from '@kitbag/router'
-import { routes } from '/routes'
-import App from './App.vue'
 
 const router = createRouter(routes)
+```
+
+## Vue Plugin
+
+Create a router instance and pass it to the app as a plugin
+
+```ts {6}
+import { createApp } from 'vue'
+import App from './App.vue'
+
 const app = createApp(App)
 
 app.use(router)
 app.mount('#app')
 ```
 
-## Update Registered Router
+## Type Safety
 
-This block utilizes [declaration merging](https://www.typescriptlang.org/docs/handbook/declaration-merging.html) to provide the internal types to match the actual router you're using. You put this in main.ts right after you call `createRouter`, or you can export your router and put this interface inside of a `router.d.ts` file, anywhere that your tsconfig can find it.
+Kitbag Router utilizes [declaration merging](https://www.typescriptlang.org/docs/handbook/declaration-merging.html) to provide the internal types to match the actual router you're using.
 
 ```ts
 declare module '@kitbag/router' {
@@ -70,99 +90,30 @@ declare module '@kitbag/router' {
 }
 ```
 
-## Push
-
-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: defineAsyncComponent(() => import('./UserPage.vue')),
-})
-
-const profile = createRoute({
-  parent: user,
-  name: 'profile',
-  path: '/profile',
-  component: defineAsyncComponent(() => import('./ProfilePage.vue')),
-})
-
-const settings = createRoute({
-  parent: user,
-  name: 'settings',
-  path: '/settings',
-  component: defineAsyncComponent(() => import('./SettingsPage.vue')),
-})
-
-const router = useRouter([user, profile, settings])
-
-router.push('settings')
-```
-
-The push method also accepts a plain string if you know the URL you want to go to.
-
-```ts
-router.push('/user/settings')
-router.push('https://github.com/kitbagjs/router')
-```
-
-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)
-```
-
-or for setting multiple params at once
-
-```ts
-router.route.update({
-  myParam: 123,
-  tab: 'github',
-})
-```
+This means then when you import a component, composition, or hook from `@kitbag/router` it will be correctly typed. Alternatively, you can create your own typed router assets by using the [`createRouterAssets`](https://kitbag-router.netlify.app/api/functions/createRouterAssets) utility. This approach is especially useful for projects that use multiple routers.
 
 ## RouterView
 
 Give your route components a place to be mounted
 
-```html {4-5}
-<!-- App.vue -->
+```html
 <div class="app">
-  ...
-  <!-- matched route.component gets rendered here -->
   <router-view />
 </div>
 ```
 
-This component can be mounted anywhere you want route components to be mounted. Nested routes can also have a nested `RouterView` which would be responsible for rendering any children that route may have. Read more about [nested routes](https://kitbag-router.netlify.app/core-concepts/defining-routes#nested-routes).
+This component can be mounted anywhere you want route components to be mounted. Nested routes can also have a nested `RouterView` which would be responsible for rendering any children that route may have. Read more about [nested routes](https://kitbag-router.netlify.app/core-concepts/routes#parent).
 
 ## RouterLink
 
 Use RouterLink for navigating between routes.
 
-```html {3-4}
+```html
 <template>
-  ...
-  <!-- router-link renders as <a> with href -->
-  <router-link :to="(resolve) => resolve('home')">Go somewhere</router-link>
+  <router-link :to="(resolve) => resolve('home')">Home</router-link>
 </template>
 ```
 
-This component gives the router the power to change the URL without reloading the page.
+### Type Safety in RouterLink
 
-[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/zw7dpcc5HV
-[stackblitz-badge]: https://developer.stackblitz.com/img/open_in_stackblitz_small.svg
-[stackblitz-url]: https://stackblitz.com/~/github.com/kitbagjs/router-preview
+The `to` prop accepts a callback function or a [`Url`](https://kitbag-router.netlify.app/api/types/Url) string. When using a callback function, the router will provide a `resolve` function that is a type safe way to create link for your pre-defined routes.

package/dist/components/routerLink.d.ts

@@ -1,4 +1,4 @@
-import { Url } from '../types/url';
+import { UrlString } from '../types/urlString';
 import { ResolvedRoute } from '../types/resolved';
 import { EmitsOptions, InjectionKey, SlotsType, VNode } from 'vue';
 import { Router } from '../types/router';
@@ -14,7 +14,7 @@ type RouterLinkSlots = {
     }) => VNode[];
 };
 export declare function createRouterLink<TRouter extends Router>(routerKey: InjectionKey<TRouter>): import('vue').DefineSetupFnComponent<RouterLinkProps<TRouter>, EmitsOptions, SlotsType<RouterLinkSlots>, import('../main').RouterPushOptions & {
-    to: Url | Readonly<{
+    to: Readonly<{
         id: string;
         matched: import('../main').CreatedRouteOptions;
         matches: import('../main').CreatedRouteOptions[];
@@ -25,9 +25,9 @@ export declare function createRouterLink<TRouter extends Router>(routerKey: Inje
             [x: string]: unknown;
         };
         state: import('../types/state').ExtractRouteStateParamsAsOptional<Record<string, import('../main').Param>>;
-        href: Url;
-        hooks: import('../models/RouterRouteHooks').RouterRouteHooks[];
-    }> | ToCallback<TRouter>;
+        href: UrlString;
+        hooks: import('../models/hooks').Hooks[];
+    }> | UrlString | ToCallback<TRouter>;
     prefetch?: import('../main').PrefetchConfig;
 } & ({
     [x: `on${Capitalize<string>}`]: ((...args: any[]) => any) | undefined;

package/dist/compositions/useLink.d.ts

@@ -1,14 +1,14 @@
 import { InjectionKey, MaybeRefOrGetter } from 'vue';
 import { ResolvedRoute } from '../types/resolved';
 import { RouteParamsByKey } from '../types/routeWithParams';
-import { Url } from '../types/url';
+import { UrlString } from '../types/urlString';
 import { AllPropertiesAreOptional } from '../types/utilities';
 import { Router, RouterRouteName, RouterRoutes } from '../types/router';
 import { UseLink, UseLinkOptions } from '../types/useLink';
 type UseLinkArgs<TRouter extends Router, TSource extends RouterRouteName<TRouter>, TParams = RouteParamsByKey<RouterRoutes<TRouter>, TSource>> = AllPropertiesAreOptional<TParams> extends true ? [params?: MaybeRefOrGetter<TParams>, options?: MaybeRefOrGetter<UseLinkOptions>] : [params: MaybeRefOrGetter<TParams>, options?: MaybeRefOrGetter<UseLinkOptions>];
 type UseLinkFunction<TRouter extends Router> = {
     <TRouteKey extends RouterRouteName<TRouter>>(name: MaybeRefOrGetter<TRouteKey>, ...args: UseLinkArgs<TRouter, TRouteKey>): UseLink;
-    (url: MaybeRefOrGetter<Url>, options?: MaybeRefOrGetter<UseLinkOptions>): UseLink;
+    (url: MaybeRefOrGetter<UrlString>, options?: MaybeRefOrGetter<UseLinkOptions>): UseLink;
     (resolvedRoute: MaybeRefOrGetter<ResolvedRoute | undefined>, options?: MaybeRefOrGetter<UseLinkOptions>): UseLink;
     (source: MaybeRefOrGetter<string | ResolvedRoute | undefined>, paramsOrOptions?: MaybeRefOrGetter<Record<PropertyKey, unknown> | UseLinkOptions>, maybeOptions?: MaybeRefOrGetter<UseLinkOptions>): UseLink;
 };

package/dist/devtools/createRouterDevtools.d.ts

@@ -0,0 +1,13 @@
+import { App } from 'vue';
+import { Router } from '../types/router';
+import { Routes } from '../types/route';
+type RouterDevtoolsProps = {
+    router: Router;
+    app: App;
+    routes: Routes;
+};
+/**
+ * Sets up Vue DevTools integration for Kitbag Router.
+ */
+export declare function setupRouterDevtools({ router, app, routes }: RouterDevtoolsProps): void;
+export {};

package/dist/devtools/filters.d.ts

@@ -0,0 +1,12 @@
+import { Route } from '../types/route';
+import { InspectorTreePayload } from './types';
+type RouteFilterOptions = {
+    route: Route;
+    payload: InspectorTreePayload;
+};
+type RouteFilter = (options: RouteFilterOptions) => boolean;
+/**
+ * Checks if a route should be shown based on multiple filters.
+ */
+export declare const shouldShowRoute: RouteFilter;
+export {};

package/dist/devtools/getDevtoolsLabel.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Generates a DevTools label with optional router instance ID.
+ * If the router ID is greater than 1, appends the ID to the label.
+ *
+ * @param label - Base label for the DevTools element
+ * @param routerId - Router instance ID (string from createUniqueIdSequence)
+ * @returns Label with ID appended if routerId > '1'
+ *
+ * @example
+ * getDevtoolsLabel('Routes', '1') // 'Routes'
+ * getDevtoolsLabel('Routes', '2') // 'Routes 2'
+ */
+export declare function getDevtoolsLabel(label: string, routerId: string): string;

package/dist/devtools/types.d.ts

@@ -0,0 +1,10 @@
+import { setupDevtoolsPlugin } from '@vue/devtools-api';
+type ExtractAPIFromCallback = Parameters<Parameters<typeof setupDevtoolsPlugin>[1]>[0];
+type ExtractInspectorTreeHandler = Parameters<ExtractAPIFromCallback['on']['getInspectorTree']>[0];
+type ExtractInspectorStateHandler = Parameters<ExtractAPIFromCallback['on']['getInspectorState']>[0];
+type ExtractInspectorStatePayload = Parameters<ExtractInspectorStateHandler>[0];
+type InspectorTreePayload = Parameters<ExtractInspectorTreeHandler>[0];
+type CustomInspectorNode = InspectorTreePayload['rootNodes'][number];
+type InspectorNodeTag = NonNullable<CustomInspectorNode['tags']>[number];
+type CustomInspectorState = ExtractInspectorStatePayload['state'];
+export type { CustomInspectorNode, InspectorTreePayload, InspectorNodeTag, CustomInspectorState };

package/dist/errors/contextAbortError.d.ts

@@ -1,6 +1,6 @@
-import { CallbackAbortResponse } from '../services/createCallbackContext';
+import { CallbackContextAbort } from '../types/callbackContext';
 import { ContextError } from './contextError';
 export declare class ContextAbortError extends ContextError {
-    response: CallbackAbortResponse;
+    response: CallbackContextAbort;
     constructor();
 }

package/dist/errors/contextPushError.d.ts

@@ -1,6 +1,6 @@
-import { CallbackPushResponse } from '../services/createCallbackContext';
+import { CallbackContextPush } from '../types/callbackContext';
 import { ContextError } from './contextError';
 export declare class ContextPushError extends ContextError {
-    response: CallbackPushResponse;
+    response: CallbackContextPush;
     constructor(to: unknown[]);
 }

package/dist/errors/contextRejectionError.d.ts

@@ -1,6 +1,6 @@
-import { CallbackRejectResponse } from '../services/createCallbackContext';
+import { CallbackContextReject } from '../types/callbackContext';
 import { ContextError } from './contextError';
 export declare class ContextRejectionError extends ContextError {
-    response: CallbackRejectResponse;
+    response: CallbackContextReject;
     constructor(type: string);
 }

package/dist/errors/invalidRouteRedirectError.d.ts

@@ -0,0 +1,11 @@
+/**
+ * An error thrown when a route does not support redirects.
+ * @group Errors
+ */
+export declare class InvalidRouteRedirectError extends Error {
+    /**
+     * Constructs a new InvalidRouteRedirectError instance with a message indicating the problematic route redirect.
+     * @param routeName - The name of the route that does not support redirects.
+     */
+    constructor(routeName: string);
+}

package/dist/errors/multipleRouteRedirectsError.d.ts

@@ -0,0 +1,13 @@
+/**
+ * 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 MultipleRouteRedirectsError extends Error {
+    /**
+     * Constructs a new MultipleRouteRedirectsError instance with a message indicating the problematic route redirect.
+     * @param routeName - The name of the route that has multiple redirects.
+     */
+    constructor(routeName: string);
+}

package/dist/keys.d.ts

@@ -1,3 +1 @@
-import { InjectionKey } from 'vue';
-import { RegisteredRouter } from './types/register';
-export declare const routerInjectionKey: InjectionKey<RegisteredRouter>;
+export declare const routerInjectionKey: unique symbol;