@kitbag/router 0.6.0 → 0.7.0

package/README.md

@@ -109,7 +109,7 @@ router.push('/user/settings')
 router.push('https://github.com/kitbagjs/router')
 ```
 
-This `source` argument is type safe, expecting either a Url or a valid route "key". Url is any string that starts with "http", "https", or a forward slash "/". Route key is a string of route names joined by a period `.` that lead to a non-disabled route. Additionally if using the route key, push will require params be passed in if there are any.
+This `source` argument is type safe, expecting either a Url or a valid route "key". Url is any string that starts with "http", "https", or a forward slash "/". Route key is a string of route names joined by a period `.`. Additionally if using the route key, push will require params be passed in if there are any.
 
 ## Update
 

package/dist/kitbag-router.d.ts

@@ -88,6 +88,8 @@ export declare type AfterRouteHookResponse<TRoutes extends Routes> = RouteHookSu
 
 declare type AllPropertiesAreOptional<T> = Record<string, unknown> extends T ? true : IsEmptyObject<OnlyRequiredProperties<T>>;
 
+declare type AsNamedRoute<T extends Route> = IsRouteUnnamed<T> extends true ? never : T;
+
 /**
  * Represents a function called before a route change, potentially altering the routing operation.
  * @param to - {@link ResolvedRoute} The resolved route the router is navigating to.
@@ -157,13 +159,17 @@ declare type CombineQueryString<TParent extends string | undefined, TChild exten
  * })
  * ```
  */
-export declare function component<TComponent extends Component>(component: TComponent, props: PropsGetter<TComponent>): Component;
+export declare function component<TComponent extends Component>(component: TComponent, props: ComponentPropsGetter<TComponent>): Component;
+
+export declare type ComponentProps<TComponent extends Component> = TComponent extends Constructor ? InstanceType<TComponent>['$props'] : TComponent extends AsyncComponentLoader<infer T extends Component> ? ComponentProps<T> : TComponent extends FunctionalComponent<infer T> ? T : never;
+
+declare type ComponentPropsGetter<TComponent extends Component> = () => MaybePromise<ComponentProps<TComponent>>;
 
 declare type Constructor = new (...args: any) => any;
 
-export declare function createExternalRoute<const TName extends string | undefined = undefined, const TPath extends string | Path | undefined = undefined, const TQuery extends string | Query | undefined = undefined, const THost extends string | Host | undefined = undefined>(options: CreateRouteOptionsWithoutParent<TName, TPath, TQuery, THost>): Route<ToKey<TName>, ToHost<THost>, ToPath<TPath>, ToQuery<TQuery>>;
+export declare function createExternalRoute<const THost extends string | Host, const TName extends string | undefined = undefined, const TPath extends string | Path | undefined = undefined, const TQuery extends string | Query | undefined = undefined>(options: CreateRouteOptions<TName, TPath, TQuery> & WithHost<THost> & WithoutParent): Route<ToKey<TName>, ToHost<THost>, ToPath<TPath>, ToQuery<TQuery>>;
 
-export declare function createExternalRoute<const TParent extends Route, const TName extends string | undefined = undefined, const TPath extends string | Path | undefined = undefined, const TQuery extends string | Query | undefined = undefined>(options: CreateRouteOptionsWithParent<TParent, TName, TPath, TQuery, Host<'', {}>>): Route<CombineKey<TParent['key'], ToKey<TName>>, ToHost<Host<'', {}>>, CombinePath<TParent['path'], ToPath<TPath>>, CombineQuery<TParent['query'], ToQuery<TQuery>>>;
+export declare function createExternalRoute<const TParent extends Route, const TName extends string | undefined = undefined, const TPath extends string | Path | undefined = undefined, const TQuery extends string | Query | undefined = undefined>(options: CreateRouteOptions<TName, TPath, TQuery> & WithoutHost & WithParent<TParent>): Route<CombineKey<TParent['key'], ToKey<TName>>, Host<'', {}>, CombinePath<TParent['path'], ToPath<TPath>>, CombineQuery<TParent['query'], ToQuery<TQuery>>>;
 
 export declare function createParam<TParam extends ParamWithDefault>(param: TParam): TParam;
 
@@ -171,19 +177,23 @@ export declare function createParam<TParam extends Param>(param: TParam): ParamG
 
 export declare function createParam<TParam extends Param>(param: TParam, defaultValue: ExtractParamType<TParam>): ParamWithDefault<TParam>;
 
-export declare function createRoute<const TName extends string | undefined = undefined, const TPath extends string | Path | undefined = undefined, const TQuery extends string | Query | undefined = undefined>(options: CreateRouteOptionsWithoutParent<TName, TPath, TQuery>): Route<ToKey<TName>, Host<'', {}>, ToPath<TPath>, ToQuery<TQuery>>;
+export declare function createRoute<const TName extends string | undefined = undefined, const TPath extends string | Path | undefined = undefined, const TQuery extends string | Query | undefined = undefined, const TMeta extends RouteMeta = RouteMeta>(options: CreateRouteOptions<TName, TPath, TQuery, TMeta> & WithHooks & WithoutComponents & WithoutParent): Route<ToKey<TName>, Host<'', {}>, ToPath<TPath>, ToQuery<TQuery>>;
+
+export declare function createRoute<const TParent extends Route, const TName extends string | undefined = undefined, const TPath extends string | Path | undefined = undefined, const TQuery extends string | Query | undefined = undefined, const TMeta extends RouteMeta = RouteMeta>(options: CreateRouteOptions<TName, TPath, TQuery, TMeta> & WithHooks & WithoutComponents & WithParent<TParent>): Route<CombineKey<TParent['key'], ToKey<TName>>, Host<'', {}>, CombinePath<TParent['path'], ToPath<TPath>>, CombineQuery<TParent['query'], ToQuery<TQuery>>>;
 
-export declare function createRoute<const TParent extends Route, const TName extends string | undefined = undefined, const TPath extends string | Path | undefined = undefined, const TQuery extends string | Query | undefined = undefined>(options: CreateRouteOptionsWithParent<TParent, TName, TPath, TQuery>): Route<CombineKey<TParent['key'], ToKey<TName>>, Host<'', {}>, CombinePath<TParent['path'], ToPath<TPath>>, CombineQuery<TParent['query'], ToQuery<TQuery>>>;
+export declare function createRoute<TComponent extends Component, const TName extends string | undefined = undefined, const TPath extends string | Path | undefined = undefined, const TQuery extends string | Query | undefined = undefined, const TMeta extends RouteMeta = RouteMeta>(options: CreateRouteOptions<TName, TPath, TQuery, TMeta> & WithHooks & WithComponent<TComponent, RouteParams<TPath, TQuery>> & WithoutParent): Route<ToKey<TName>, Host<'', {}>, ToPath<TPath>, ToQuery<TQuery>>;
 
-export declare type CreateRouteOptions<TName extends string | undefined = string, TPath extends string | Path | undefined = string | Path | undefined, TQuery extends string | Query | undefined = string | Query | undefined, THost extends string | Host | undefined = string | Host | undefined, _TParent extends Route | undefined = undefined> = WithComponent & WithHooks & {
+export declare function createRoute<TComponent extends Component, const TParent extends Route, const TName extends string | undefined = undefined, const TPath extends string | Path | undefined = undefined, const TQuery extends string | Query | undefined = undefined, const TMeta extends RouteMeta = RouteMeta>(options: CreateRouteOptions<TName, TPath, TQuery, TMeta> & WithHooks & WithComponent<TComponent, RouteParams<TPath, TQuery, TParent>> & WithParent<TParent>): Route<CombineKey<TParent['key'], ToKey<TName>>, Host<'', {}>, CombinePath<TParent['path'], ToPath<TPath>>, CombineQuery<TParent['query'], ToQuery<TQuery>>>;
+
+export declare function createRoute<TComponents extends Record<string, Component>, const TName extends string | undefined = undefined, const TPath extends string | Path | undefined = undefined, const TQuery extends string | Query | undefined = undefined, const TMeta extends RouteMeta = RouteMeta>(options: CreateRouteOptions<TName, TPath, TQuery, TMeta> & WithHooks & WithComponents<TComponents, RouteParams<TPath, TQuery>> & WithoutParent): Route<ToKey<TName>, Host<'', {}>, ToPath<TPath>, ToQuery<TQuery>>;
+
+export declare function createRoute<TComponents extends Record<string, Component>, const TParent extends Route, const TName extends string | undefined = undefined, const TPath extends string | Path | undefined = undefined, const TQuery extends string | Query | undefined = undefined, const TMeta extends RouteMeta = RouteMeta>(options: CreateRouteOptions<TName, TPath, TQuery, TMeta> & WithHooks & WithComponents<TComponents, RouteParams<TPath, TQuery, TParent>> & WithParent<TParent>): Route<CombineKey<TParent['key'], ToKey<TName>>, Host<'', {}>, CombinePath<TParent['path'], ToPath<TPath>>, CombineQuery<TParent['query'], ToQuery<TQuery>>>;
+
+export declare type CreateRouteOptions<TName extends string | undefined = string | undefined, TPath extends string | Path | undefined = string | Path | undefined, TQuery extends string | Query | undefined = string | Query | undefined, TMeta extends RouteMeta = RouteMeta> = {
     /**
      * Name for route, used to create route keys and in navigation.
      */
     name?: TName;
-    /**
-     * Host part of URL.
-     */
-    host?: THost;
     /**
      * Path part of URL.
      */
@@ -195,25 +205,16 @@ export declare type CreateRouteOptions<TName extends string | undefined = string
     /**
      * Represents additional metadata associated with a route, customizable via declaration merging.
      */
-    meta?: RouteMeta;
-    disabled?: boolean;
+    meta?: TMeta;
 };
 
 /**
  * The Route properties originally provided to `createRoute`. The only change is normalizing meta to always default to an empty object.
  */
-export declare type CreateRouteOptionsWithMeta = CreateRouteOptions & {
+export declare type CreateRouteOptionsMatched = CreateRouteOptions & WithHooks & (WithHost | WithoutHost) & (WithComponent | WithComponents | WithoutComponents) & (WithParent | WithoutParent) & {
     meta: RouteMeta;
 };
 
-declare type CreateRouteOptionsWithoutParent<TName extends string | undefined = undefined, TPath extends string | Path | undefined = undefined, TQuery extends string | Query | undefined = undefined, THost extends string | Host | undefined = undefined> = CreateRouteOptions<TName, TPath, TQuery, THost> & {
-    parent?: never;
-};
-
-declare type CreateRouteOptionsWithParent<TParent extends Route, TName extends string | undefined = undefined, TPath extends string | Path | undefined = undefined, TQuery extends string | Query | undefined = undefined, THost extends string | Host | undefined = undefined> = CreateRouteOptions<TName, TPath, TQuery, THost, TParent> & {
-    parent: TParent;
-};
-
 /**
  * Creates a router instance for a Vue application, equipped with methods for route handling, lifecycle hooks, and state management.
  *
@@ -376,10 +377,6 @@ export declare function isRoute<TRouteKey extends RegisteredRoutesKey>(route: un
 
 export declare function isRoute(route: unknown, routeKey?: string, options?: IsRouteOptions): boolean;
 
-declare type IsRouteDisabled<T extends Route> = T extends {
-    disabled: true;
-} ? true : false;
-
 declare type IsRouteOptions = {
     exact?: boolean;
 };
@@ -471,6 +468,10 @@ declare const paramStart = "[";
 
 export declare type ParamWithDefault<TParam extends Param = Param> = Required<ParamGetSet<ExtractParamType<TParam>>>;
 
+declare type ParentPath<TParent extends Route | undefined> = TParent extends Route ? TParent['path'] : Path<'', {}>;
+
+declare type ParentQuery<TParent extends Route | undefined> = TParent extends Route ? TParent['query'] : Query<'', {}>;
+
 declare type Path<TPath extends string = string, TParams extends PathParamsWithParamNameExtracted<TPath> = Record<string, Param | undefined>> = {
     path: TPath;
     params: string extends TPath ? Record<string, Param> : Identity<ExtractParamsFromPathString<TPath, TParams>>;
@@ -504,10 +505,6 @@ declare type PathParamsWithParamNameExtracted<TPath extends string> = {
     [K in keyof ExtractParamsFromPathString<TPath> as ExtractParamName<K>]?: 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<TQuery extends string = string, TQueryParams extends QueryParamsWithParamNameExtracted<TQuery> = Record<string, Param | undefined>> = {
     query: TQuery;
     params: string extends TQuery ? Record<string, Param> : Identity<ExtractQueryParamsFromQueryString<TQuery, TQueryParams>>;
@@ -542,7 +539,7 @@ declare type QueryParamsWithParamNameExtracted<T extends string> = {
 };
 
 /**
- * Represents the state of currently registered router, and rejections. Used to provide correct type context for
+ * Represents the state of currently registered router, rejections, and route meta. Used to provide correct type context for
  * components like `RouterLink`, as well as for composables like `useRouter`, `useRoute`, and hooks.
  *
  * @example
@@ -550,6 +547,8 @@ declare type QueryParamsWithParamNameExtracted<T extends string> = {
  * declare module '@kitbag/router' {
  *   interface Register {
  *     router: typeof router
+ *     rejections: ["NotAuthorized"],
+ *     routeMeta: { public?: boolean }
  *   }
  * }
  * ```
@@ -591,19 +590,12 @@ export declare type RegisteredRouterReplace = RouterReplace<RegisteredRoutes>;
  */
 export declare type RegisteredRouterRoute = RegisteredRouter['route'];
 
-/**
- * Represents the State property registered within {@link Register}
- */
-export declare type RegisteredRouterState = Register extends {
-    state: infer TState;
-} ? TState : {};
-
 /**
  * Represents the Router routes property within {@link Register}
  */
 export declare type RegisteredRoutes = Register extends {
     router: Router<infer TRoutes extends Routes>;
-} ? TRoutes : Route<string, Host, Path, Query, false>[];
+} ? TRoutes : Route[];
 
 /**
  * Represents the union of all possible RouteKeys registered within {@link Register}
@@ -654,18 +646,19 @@ declare type ResolvedRouteQuery = {
  * @template TKey - Represents the unique key identifying the route, typically a string.
  * @template TPath - The type or structure of the route's path.
  * @template TQuery - The type or structure of the query parameters associated with the route.
- * @template TDisabled - Indicates whether the route is disabled, which could affect routing logic.
  */
-export declare type Route<TKey extends string = string, THost extends Host = Host, TPath extends Path = Path, TQuery extends Query = Query, TDisabled extends boolean = boolean> = {
+export declare type Route<TKey extends string = string, THost extends Host = Host, TPath extends Path = Path, TQuery extends Query = Query, TMeta extends RouteMeta = RouteMeta> = {
     /**
      * The specific route properties that were matched in the current route.
      */
-    matched: CreateRouteOptionsWithMeta;
+    matched: CreateRouteOptionsMatched & {
+        meta: TMeta;
+    };
     /**
      * 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: CreateRouteOptionsWithMeta[];
+    matches: CreateRouteOptionsMatched[];
     /**
      * Unique identifier for the route, generated by joining route `name` by period. Key is used for routing and for matching.
      */
@@ -683,10 +676,6 @@ export declare type Route<TKey extends string = string, THost extends Host = Hos
      */
     query: TQuery;
     depth: number;
-    /**
-     * Indicates if the route is disabled.
-     */
-    disabled: TDisabled;
 };
 
 declare type RouteGetByKey<TRoutes extends Routes, TKey extends RoutesKey<TRoutes>> = RoutesMap<TRoutes>[TKey];
@@ -758,21 +747,14 @@ declare type RouteHookSuccessResponse = {
     status: 'SUCCESS';
 };
 
-declare type RouteIsNamedAndNotDisabled<T extends Route> = IsRouteDisabled<T> extends true ? never : IsRouteUnnamed<T> extends true ? never : T;
-
 /**
  * Represents additional metadata associated with a route, customizable via declaration merging.
- * @example
- * ```ts
- * declare module '@kitbag/router' {
- *   interface RouteMeta {
- *     pageTitle?: string
- *   }
- * }
- * ```
  */
-export declare interface RouteMeta extends Record<string, unknown> {
-}
+export declare type RouteMeta = Register extends {
+    routeMeta: infer RouteMeta extends Record<string, unknown>;
+} ? RouteMeta : Record<string, unknown>;
+
+declare type RouteParams<TPath extends string | Path | undefined, TQuery extends string | Query | undefined, TParent extends Route | undefined = undefined> = ExtractParamTypes<Identity<CombinePath<ParentPath<TParent>, ToPath<TPath>>['params'] & CombineQuery<ParentQuery<TParent>, ToQuery<TQuery>>['params']>>;
 
 declare type RouteParamsByKey<TRoutes extends Routes, TKey extends string> = ExtractRouteParamTypesWithoutLosingOptional<RouteGetByKey<TRoutes, TKey>>;
 
@@ -976,8 +958,10 @@ name?: string | undefined;
     default?: ((props: {
         route: Readonly<{
             key: string;
-            matched: CreateRouteOptionsWithMeta;
-            matches: CreateRouteOptionsWithMeta[];
+            matched: CreateRouteOptionsMatched & {
+                meta: Record<string, unknown>;
+            };
+            matches: CreateRouteOptionsMatched[];
             query: ResolvedRouteQuery;
             params: Writable<    {
             [x: string]: any;
@@ -1003,8 +987,10 @@ name?: string | undefined;
     default?: ((props: {
         route: Readonly<{
             key: string;
-            matched: CreateRouteOptionsWithMeta;
-            matches: CreateRouteOptionsWithMeta[];
+            matched: CreateRouteOptionsMatched & {
+                meta: Record<string, unknown>;
+            };
+            matches: CreateRouteOptionsMatched[];
             query: ResolvedRouteQuery;
             params: Writable<    {
             [x: string]: any;
@@ -1036,7 +1022,7 @@ export declare type Routes = Readonly<Route[]>;
 declare type RoutesKey<TRoutes extends Routes> = string & keyof RoutesMap<TRoutes>;
 
 declare type RoutesMap<TRoutes extends Routes = []> = {
-    [K in TRoutes[number] as RouteIsNamedAndNotDisabled<K>['key']]: RouteIsNamedAndNotDisabled<K>;
+    [K in TRoutes[number] as AsNamedRoute<K>['key']]: AsNamedRoute<K>;
 };
 
 declare type RouteUpdate<TRoute extends ResolvedRoute = ResolvedRoute> = ResolvedRoute extends TRoute ? {
@@ -1163,13 +1149,22 @@ export declare class UseRouteInvalidError extends Error {
  */
 export declare function useRouter(): RegisteredRouter;
 
-declare type WithComponent = Partial<WithSingleComponent | WithComponentRecord>;
+declare type WithComponent<TComponent extends Component = Component, TParams extends Record<string, unknown> = Record<string, unknown>> = {
+    /**
+     * A Vue component, which can be either synchronous or asynchronous components.
+     */
+    component: TComponent;
+    props?: (params: TParams) => TComponent extends Component ? MaybePromise<ComponentProps<TComponent>> : {};
+};
 
-declare type WithComponentRecord = {
+declare type WithComponents<TComponents extends Record<string, Component> = Record<string, Component>, TParams extends Record<string, unknown> = Record<string, unknown>> = {
     /**
      * Multiple components for named views, which can be either synchronous or asynchronous components.
      */
-    components: Record<string, Component>;
+    components: TComponents;
+    props?: {
+        [TKey in keyof TComponents]?: (params: TParams) => TComponents[TKey] extends Component ? MaybePromise<ComponentProps<TComponents[TKey]>> : {};
+    };
 };
 
 export declare function withDefault<TParam extends Param>(param: TParam, defaultValue: ExtractParamType<TParam>): ParamWithDefault<TParam>;
@@ -1186,15 +1181,33 @@ declare type WithHooks = {
     onAfterRouteLeave?: MaybeArray<AfterRouteHook>;
 };
 
+declare type WithHost<THost extends string | Host = string | Host> = {
+    /**
+     * Host part of URL.
+     */
+    host: THost;
+};
+
 declare type WithOptionalProperties<T> = {
     [P in keyof T]-?: undefined extends T[P] ? P : never;
 }[keyof T];
 
-declare type WithSingleComponent = {
-    /**
-     * A Vue component, which can be either synchronous or asynchronous components.
-     */
-    component: Component;
+declare type WithoutComponents = {
+    component?: never;
+    components?: never;
+    props?: never;
+};
+
+declare type WithoutHost = {
+    host?: never;
+};
+
+declare type WithoutParent = {
+    parent?: never;
+};
+
+declare type WithParent<TParent extends Route = Route> = {
+    parent: TParent;
 };
 
 declare type Writable<T> = {