@kitbag/router 0.20.11 → 0.21.0

package/README.md

@@ -15,6 +15,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 +26,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 +81,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

@@ -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[];
@@ -26,8 +26,8 @@ export declare function createRouterLink<TRouter extends Router>(routerKey: Inje
         };
         state: import('../types/state').ExtractRouteStateParamsAsOptional<Record<string, import('../main').Param>>;
         href: Url;
-        hooks: import('../models/RouterRouteHooks').RouterRouteHooks[];
-    }> | ToCallback<TRouter>;
+        hooks: import('../models/hooks').Hooks[];
+    }> | Url | ToCallback<TRouter>;
     prefetch?: import('../main').PrefetchConfig;
 } & ({
     [x: `on${Capitalize<string>}`]: ((...args: any[]) => any) | undefined;

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/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;