@kitbag/router 0.2.0 → 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

@@ -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.
      */
@@ -350,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];
 } & {
@@ -447,7 +482,7 @@ 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.
      */
@@ -468,10 +503,6 @@ 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.
      */
@@ -864,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;
 }>;
@@ -957,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: 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 +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.
  *
@@ -1023,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;
 
@@ -1040,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.
  *
@@ -1049,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.
  */