@kitbag/router 0.26.1 → 0.28.0

package/dist/types/routerNavigationInternal.d.ts

@@ -0,0 +1,29 @@
+import { ResolvedRoute } from './resolved';
+import { Routes } from './route';
+import { RedirectStatus } from './router';
+import { RouterPush, RouterPushOptions } from './routerPush';
+import { RouterReplace, RouterReplaceOptions } from './routerReplace';
+import { RouteParamsByKey } from './routeWithParams';
+import { RoutesName } from './routesMap';
+import { RouteStateByName } from './state';
+import { UrlString } from './urlString';
+/**
+ * Push and replace as the router itself calls them, which may carry the status a server responds with for
+ * the redirect. The router exposes {@link RouterPush} and {@link RouterReplace} instead.
+ */
+export type RouterPushOptionsInternal<TState = unknown> = RouterPushOptions<TState> & {
+    redirectStatus?: RedirectStatus;
+};
+export type RouterReplaceOptionsInternal<TState = unknown> = RouterReplaceOptions<TState> & {
+    redirectStatus?: RedirectStatus;
+};
+export type RouterPushInternal<TRoutes extends Routes> = RouterPush<TRoutes> & {
+    <TSource extends RoutesName<TRoutes>>(name: TSource, params: RouteParamsByKey<TRoutes, TSource> | undefined, options: RouterPushOptionsInternal<RouteStateByName<TRoutes, TSource>>): Promise<void>;
+    (route: ResolvedRoute, options: RouterPushOptionsInternal): Promise<void>;
+    (url: UrlString, options: RouterPushOptionsInternal): Promise<void>;
+};
+export type RouterReplaceInternal<TRoutes extends Routes> = RouterReplace<TRoutes> & {
+    <TSource extends RoutesName<TRoutes>>(name: TSource, params: RouteParamsByKey<TRoutes, TSource> | undefined, options: RouterReplaceOptionsInternal<RouteStateByName<TRoutes, TSource>>): Promise<void>;
+    (route: ResolvedRoute, options: RouterReplaceOptionsInternal): Promise<void>;
+    (url: UrlString, options: RouterReplaceOptionsInternal): Promise<void>;
+};

package/dist/types/routerPush.d.ts

@@ -1,3 +1,4 @@
+import { NavigationBehavior } from './navigation';
 import { Routes } from './route';
 import { RoutesName } from './routesMap';
 import { RouteParamsByKey } from './routeWithParams';
@@ -6,6 +7,7 @@ import { UrlString } from './urlString';
 import { AllPropertiesAreOptional } from './utilities';
 import { QuerySource } from './querySource';
 import { ResolvedRoute } from './resolved';
+import { ViewTransitionConfig } from './viewTransition';
 export type RouterPushOptions<TState = unknown> = {
     /**
      * The query string to add to the url.
@@ -19,10 +21,16 @@ export type RouterPushOptions<TState = unknown> = {
      * Whether to replace the current history entry.
      */
     replace?: boolean;
+    /** Overrides the route and router navigation behavior. */
+    navigation?: NavigationBehavior;
     /**
      * State values to pass to the route.
      */
     state?: Partial<TState>;
+    /**
+     * Animates the navigation with the View Transitions API. Overrides route and router level viewTransition.
+     */
+    viewTransition?: ViewTransitionConfig;
 };
 type RouterPushArgs<TRoutes extends Routes, TSource extends RoutesName<TRoutes>> = AllPropertiesAreOptional<RouteParamsByKey<TRoutes, TSource>> extends true ? [params?: RouteParamsByKey<TRoutes, TSource>, options?: RouterPushOptions<RouteStateByName<TRoutes, TSource>>] : [params: RouteParamsByKey<TRoutes, TSource>, options?: RouterPushOptions<RouteStateByName<TRoutes, TSource>>];
 export type RouterPush<TRoutes extends Routes = any> = {

package/dist/types/routerReplace.d.ts

@@ -1,3 +1,4 @@
+import { NavigationBehavior } from './navigation';
 import { Routes } from './route';
 import { RoutesName } from './routesMap';
 import { RouteParamsByKey } from './routeWithParams';
@@ -8,6 +9,8 @@ import { QuerySource } from './querySource';
 import { ResolvedRoute } from './resolved';
 export type RouterReplaceOptions<TState = unknown> = {
     query?: QuerySource;
+    /** Overrides the route and router navigation behavior. */
+    navigation?: NavigationBehavior;
     hash?: string;
     state?: Partial<TState>;
 };

package/dist/types/routerRoute.d.ts

@@ -29,9 +29,13 @@ export type RouterRoute<TRoute extends ResolvedRoute = ResolvedRoute> = {
      */
     readonly update: RouteUpdate<TRoute>;
     /**
-     * String value of the resolved URL.
+     * String value of the resolved URL. When the route was matched through an alias this is the alias url.
      */
     readonly href: TRoute['href'];
+    /**
+     * String value of the route's own URL. The same as `href` unless the route was matched through an alias.
+     */
+    readonly canonical: TRoute['canonical'];
     /**
      * Title of the route.
      */

package/dist/types/useLink.d.ts

@@ -37,6 +37,11 @@ export type UseLink = {
      *
      */
     isExternal: ComputedRef<boolean>;
+    /**
+     * True while a view transition to this link's location is in flight, so the elements it animates from
+     * can be named before the page is captured.
+     */
+    isTransitioning: ComputedRef<boolean>;
     /**
      * Convenience method for executing `router.push` with route context passed in.
      */

package/dist/types/viewTransition.d.ts

@@ -0,0 +1,49 @@
+import { ResolvedRoute, RouterResolvedRouteUnion } from './resolved';
+import { CreatedRouteOptions, Routes } from './route';
+/**
+ * Types set on a view transition, which css targets with `:active-view-transition-type()`.
+ */
+export type ViewTransitionTypes = string[];
+/**
+ * The navigation a view transition animates. There is always a route to animate from, since the first
+ * navigation never transitions.
+ */
+export type ViewTransitionContext = {
+    to: ResolvedRoute;
+    from: ResolvedRoute;
+};
+/**
+ * Decides the types for a navigation. Returning `false` skips the transition for that navigation.
+ */
+export type ViewTransitionTypesCallback = (context: ViewTransitionContext) => ViewTransitionTypes | false;
+export type ViewTransitionConfigOptions = {
+    /**
+     * Types set on the transition, combined with the types of every other level that applies.
+     */
+    types?: ViewTransitionTypes | ViewTransitionTypesCallback;
+};
+/**
+ * Whether a navigation animates with the View Transitions API. A boolean enables or disables the
+ * transition, an array of types or an options object enables it.
+ */
+export type ViewTransitionConfig = boolean | ViewTransitionTypes | ViewTransitionConfigOptions;
+export type ViewTransitionConfigs = {
+    routerViewTransition?: ViewTransitionConfig;
+    routeViewTransition?: ViewTransitionConfig;
+    navigationViewTransition?: ViewTransitionConfig;
+};
+/**
+ * The view transition in flight, from the moment a navigation is decided to transition until its
+ * animation finishes. `to` and `from` are known throughout, so the page being left can prepare its elements
+ * before it is captured. `transition` is set once the browser has been asked to transition.
+ */
+export type RouterViewTransition<TRoutes extends Routes = Routes> = {
+    readonly isTransitioning: boolean;
+    readonly to: RouterResolvedRouteUnion<TRoutes> | undefined;
+    readonly from: RouterResolvedRouteUnion<TRoutes> | undefined;
+    readonly types: ViewTransitionTypes;
+    readonly transition: ViewTransition | undefined;
+};
+export declare function hasViewTransition(match: CreatedRouteOptions): match is CreatedRouteOptions & {
+    viewTransition: ViewTransitionConfig;
+};

package/dist/utilities/components.d.ts

@@ -10,9 +10,13 @@ export declare function isAsyncComponent(component: Component): component is Com
  * Decides which of a route's views to load.
  */
 export type AsyncComponentFilter = (match: CreatedRouteOptions, view: RouteView<unknown>) => boolean;
+/**
+ * The async components a route renders, or only those the filter keeps.
+ */
+export declare function getAsyncComponents(route: ResolvedRoute, filter?: AsyncComponentFilter): ComponentWithAsyncLoader[];
 /**
  * Loads the async components a route renders, or only those the filter keeps, so they are ready to render
- * synchronously.
+ * synchronously. Each load is reported on its own.
  */
-export declare function loadAsyncComponents(route: ResolvedRoute, filter?: AsyncComponentFilter): Promise<unknown>;
+export declare function loadAsyncComponents(route: ResolvedRoute, filter?: AsyncComponentFilter): Promise<unknown>[];
 export {};

package/dist/utilities/getRegexMatcher.d.ts

@@ -0,0 +1 @@
+export declare function getRegexMatcher(regex: RegExp): RegExp;

package/dist/utilities/getRegexMatcher.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/utilities/navigation.d.ts

@@ -0,0 +1,15 @@
+import { NavigationBehavior } from '../types/navigation';
+import { ResolvedRoute } from '../types/resolved';
+type NavigationOptions = {
+    routerNavigation?: NavigationBehavior;
+    routeNavigation?: NavigationBehavior;
+    navigation?: NavigationBehavior;
+};
+type NavigationOption = {
+    navigation: NavigationBehavior;
+    isBlockingNavigation: boolean;
+    isProgressiveNavigation: boolean;
+};
+export declare function getRouteNavigationOption(to: ResolvedRoute | null): NavigationBehavior | undefined;
+export declare function getNavigationOption(options: NavigationOptions): NavigationOption;
+export {};

package/dist/utilities/percentEncoding.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Encodes the characters in a param value that would otherwise be read as syntax: a percent sign starts
+ * an escape, and square brackets mark a param. Everything else is left for the url to encode.
+ */
+export declare function encodeParamValue(value: string): string;
+/**
+ * Decodes a param value taken from a url. A malformed escape is kept as written rather than thrown on,
+ * and a missing value stays missing.
+ */
+export declare function decodeParamValue(value: string | undefined): string | undefined;

package/dist/utilities/percentEncoding.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/utilities/promises.d.ts

@@ -1 +1,5 @@
 export declare function isPromise(value: unknown): value is Promise<unknown>;
+/**
+ * Resolves when the signal aborts, including an already aborted signal.
+ */
+export declare function createAbortPromise(signal: AbortSignal): Promise<void>;

package/dist/utilities/promises.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/utilities/testHelpers.d.ts

@@ -14,7 +14,7 @@ export declare const routes: readonly [import('../types/routeWithMethods').Route
 }>, [Omit<{
     readonly name: "parentA";
     readonly path: "/parentA/[paramA]";
-}, "meta" | "component" | "components" | "name" | "parent"> & {
+}, "meta" | "name" | "parent"> & {
     id: string;
     name: "parentA";
     meta: Readonly<{}>;
@@ -34,7 +34,7 @@ export declare const routes: readonly [import('../types/routeWithMethods').Route
 }>, [Omit<{
     readonly name: "parentA";
     readonly path: "/parentA/[paramA]";
-}, "meta" | "component" | "components" | "name" | "parent"> & {
+}, "meta" | "name" | "parent"> & {
     id: string;
     name: "parentA";
     meta: Readonly<{}>;
@@ -47,7 +47,7 @@ export declare const routes: readonly [import('../types/routeWithMethods').Route
     }>, [Omit<{
         readonly name: "parentA";
         readonly path: "/parentA/[paramA]";
-    }, "meta" | "component" | "components" | "name" | "parent"> & {
+    }, "meta" | "name" | "parent"> & {
         id: string;
         name: "parentA";
         meta: Readonly<{}>;
@@ -56,7 +56,7 @@ export declare const routes: readonly [import('../types/routeWithMethods').Route
     }]>;
     readonly name: "parentA.childA";
     readonly path: "/childA/[?paramB]";
-}, "meta" | "component" | "components" | "name" | "parent"> & {
+}, "meta" | "name" | "parent"> & {
     id: string;
     name: "parentA.childA";
     meta: Readonly<{}>;
@@ -76,37 +76,21 @@ export declare const routes: readonly [import('../types/routeWithMethods').Route
 }>, [Omit<{
     readonly name: "parentA";
     readonly path: "/parentA/[paramA]";
-}, "meta" | "component" | "components" | "name" | "parent"> & {
+}, "meta" | "name" | "parent"> & {
     id: string;
     name: "parentA";
     meta: Readonly<{}>;
     views: {};
     loaders: {};
-}, Omit<{
-    readonly parent: import('../types/routeWithMethods').RouteWithMethods<import('../types/url').ToUrl<{
-        readonly name: "parentA";
-        readonly path: "/parentA/[paramA]";
-    }>, [Omit<{
-        readonly name: "parentA";
-        readonly path: "/parentA/[paramA]";
-    }, "meta" | "component" | "components" | "name" | "parent"> & {
-        id: string;
-        name: "parentA";
-        meta: Readonly<{}>;
-        views: {};
-        loaders: {};
-    }]>;
-    readonly name: "parentA.childB";
-    readonly path: "/childB/[paramD]";
-    readonly component: {
-        template: string;
-    };
-}, "meta" | "component" | "components" | "name" | "parent"> & {
+}, {
+    meta: Readonly<{}>;
     id: string;
     name: "parentA.childB";
-    meta: Readonly<{}>;
-    views: {};
     loaders: {};
+    readonly path: "/childB/[paramD]";
+    views: {
+        default: import('../types/routeViews').RouteView;
+    };
 }]>, import('../types/routeWithMethods').RouteWithMethods<import('../main').Url<{
     paramA: {
         param: StringConstructor;
@@ -126,7 +110,7 @@ export declare const routes: readonly [import('../types/routeWithMethods').Route
 }>, [Omit<{
     readonly name: "parentA";
     readonly path: "/parentA/[paramA]";
-}, "meta" | "component" | "components" | "name" | "parent"> & {
+}, "meta" | "name" | "parent"> & {
     id: string;
     name: "parentA";
     meta: Readonly<{}>;
@@ -139,7 +123,7 @@ export declare const routes: readonly [import('../types/routeWithMethods').Route
     }>, [Omit<{
         readonly name: "parentA";
         readonly path: "/parentA/[paramA]";
-    }, "meta" | "component" | "components" | "name" | "parent"> & {
+    }, "meta" | "name" | "parent"> & {
         id: string;
         name: "parentA";
         meta: Readonly<{}>;
@@ -148,95 +132,43 @@ export declare const routes: readonly [import('../types/routeWithMethods').Route
     }]>;
     readonly name: "parentA.childA";
     readonly path: "/childA/[?paramB]";
-}, "meta" | "component" | "components" | "name" | "parent"> & {
+}, "meta" | "name" | "parent"> & {
     id: string;
     name: "parentA.childA";
     meta: Readonly<{}>;
     views: {};
     loaders: {};
-}, Omit<{
-    readonly parent: import('../types/routeWithMethods').RouteWithMethods<import('../main').Url<{
-        paramA: {
-            param: StringConstructor;
-            isOptional: false;
-            isGreedy: false;
-        };
-        paramB: {
-            param: StringConstructor;
-            isOptional: true;
-            isGreedy: false;
-        };
-    }>, [Omit<{
-        readonly name: "parentA";
-        readonly path: "/parentA/[paramA]";
-    }, "meta" | "component" | "components" | "name" | "parent"> & {
-        id: string;
-        name: "parentA";
-        meta: Readonly<{}>;
-        views: {};
-        loaders: {};
-    }, Omit<{
-        readonly parent: import('../types/routeWithMethods').RouteWithMethods<import('../types/url').ToUrl<{
-            readonly name: "parentA";
-            readonly path: "/parentA/[paramA]";
-        }>, [Omit<{
-            readonly name: "parentA";
-            readonly path: "/parentA/[paramA]";
-        }, "meta" | "component" | "components" | "name" | "parent"> & {
-            id: string;
-            name: "parentA";
-            meta: Readonly<{}>;
-            views: {};
-            loaders: {};
-        }]>;
-        readonly name: "parentA.childA";
-        readonly path: "/childA/[?paramB]";
-    }, "meta" | "component" | "components" | "name" | "parent"> & {
-        id: string;
-        name: "parentA.childA";
-        meta: Readonly<{}>;
-        views: {};
-        loaders: {};
-    }]>;
-    readonly name: "parentA.childA.grandChildA";
-    readonly path: "/[paramC]";
-    readonly component: {
-        template: string;
-    };
-}, "meta" | "component" | "components" | "name" | "parent"> & {
+}, {
+    meta: Readonly<{}>;
     id: string;
     name: "parentA.childA.grandChildA";
-    meta: Readonly<{}>;
-    views: {};
     loaders: {};
+    readonly path: "/[paramC]";
+    views: {
+        default: import('../types/routeViews').RouteView;
+    };
 }]>, import('../types/routeWithMethods').RouteWithMethods<import('../types/url').ToUrl<{
     readonly name: "parentB";
     readonly path: "/parentB";
-}>, [Omit<{
-    readonly name: "parentB";
-    readonly path: "/parentB";
-    readonly component: {
-        template: string;
-    };
-}, "meta" | "component" | "components" | "name" | "parent"> & {
+}>, [{
+    meta: Readonly<{}>;
     id: string;
     name: "parentB";
-    meta: Readonly<{}>;
-    views: {};
     loaders: {};
+    readonly path: "/parentB";
+    views: {
+        default: import('../types/routeViews').RouteView;
+    };
 }]>, import('../types/routeWithMethods').RouteWithMethods<import('../types/url').ToUrl<{
     readonly name: "parentC";
     readonly path: "/";
-}>, [Omit<{
-    readonly name: "parentC";
-    readonly path: "/";
-    readonly component: {
-        template: string;
-    };
-}, "meta" | "component" | "components" | "name" | "parent"> & {
+}>, [{
+    meta: Readonly<{}>;
     id: string;
     name: "parentC";
-    meta: Readonly<{}>;
-    views: {};
     loaders: {};
+    readonly path: "/";
+    views: {
+        default: import('../types/routeViews').RouteView;
+    };
 }]>];

package/dist/utilities/viewTransition.d.ts

@@ -0,0 +1,11 @@
+import { ViewTransitionConfigs, ViewTransitionContext, ViewTransitionTypes } from '../types/viewTransition';
+/**
+ * The types to transition with, or `false` when the navigation should not transition. The nearest level
+ * that sets the option decides whether it is on, and the types of every level that is on are combined.
+ */
+export declare function getViewTransitionTypes({ routerViewTransition, routeViewTransition, navigationViewTransition, ...context }: ViewTransitionConfigs & ViewTransitionContext): ViewTransitionTypes | false;
+export declare function supportsViewTransitions(): boolean;
+/**
+ * Passing types to a browser that predates them throws, so they are only passed where a transition has them.
+ */
+export declare function supportsViewTransitionTypes(): boolean;

package/dist/utilities/viewTransition.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@kitbag/router",
   "private": false,
-  "version": "0.26.1",
+  "version": "0.28.0",
   "license": "MIT",
   "bugs": {
     "url": "https://github.com/kitbagjs/router/issues"
@@ -45,21 +45,22 @@
   "devDependencies": {
     "@kitbag/eslint-config": "1.0.6",
     "@vitejs/plugin-vue": "^6.0.8",
-    "@vue/language-core": "^3.3.11",
-    "@vue/test-utils": "^2.5.0",
-    "arktype": "^2.2.3",
+    "@vue/language-core": "^3.3.12",
+    "@vue/test-utils": "^2.5.1",
+    "arktype": "^2.2.8",
     "eslint": "^9.39.5",
-    "globals": "^17.12.0",
-    "happy-dom": "^20.14.3",
+    "globals": "^17.13.0",
+    "happy-dom": "^20.14.6",
     "typedoc": "^0.28.20",
-    "typedoc-plugin-markdown": "^4.13.0",
+    "typedoc-plugin-markdown": "^4.13.1",
     "typedoc-vitepress-theme": "^1.1.4",
     "typescript": "^6.0.3",
     "valibot": "^1.0.0",
+    "view-transitions-mock": "^1.1.0",
     "vite": "^8.2.0",
     "vite-plugin-dts": "^5.0.3",
     "vitepress": "^1.6.4",
-    "vitest": "^5.0.0",
+    "vitest": "^5.0.3",
     "vue-tsc": "^3.3.8",
     "zod": "4.0.0"
   },

package/dist/services/createNavigationIds.d.ts

@@ -1,6 +0,0 @@
-export type NavigationIds = {
-    getNavigationId: () => string;
-    isCurrentNavigationId: (id: string) => boolean;
-    stopNavigationIds: () => void;
-};
-export declare function createNavigationIds(): NavigationIds;

package/dist/services/createRouteViews.d.ts

@@ -1,16 +0,0 @@
-import { CreateRouteOptions, CreateRouteProps } from '../types/createRouteOptions';
-import { RouteViews } from '../types/routeViews';
-export declare const DEFAULT_VIEW_NAME = "default";
-/**
- * Builds the initial views for a route, seeding components from the (deprecated) `component`/`components`
- * options and prop getters from the props argument. Subsequent views are added via the route's `addView`.
- *
- * This is where the props argument's two shapes — a single getter for the unnamed view, or a record keyed
- * by view name — are normalized, so the rest of the router only deals with views keyed by name.
- */
-export declare function createRouteViews(options: CreateRouteOptions, props?: CreateRouteProps): RouteViews;
-/**
- * The names of the views that have a props getter. A view without one is never computed, so waiting on it
- * would never settle.
- */
-export declare function viewNamesWithProps(views: RouteViews): string[];