@kitbag/router 0.27.0 → 0.29.0

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/view.d.ts

@@ -0,0 +1,58 @@
+import { Component } from 'vue';
+import { ComponentProps } from '../services/component';
+import { TransformerOptions } from '../services/payload';
+import { PrefetchConfig } from './prefetch';
+import { RouteContext, RouteContextToRejection, RouteContextToRoute } from './routeContext';
+import { ResolvedRouteWithDataUnion } from './resolved';
+import { Routes } from './route';
+import { RouterPush } from './routerPush';
+import { RouterReplace } from './routerReplace';
+import { RouterReject } from './routerReject';
+import { AnyFunction, MaybePromise } from './utilities';
+export declare const IS_VIEW_SYMBOL: unique symbol;
+export type ViewInternal = {
+    [IS_VIEW_SYMBOL]: true;
+};
+/**
+ * Navigation helpers available to a reusable view from its declared context.
+ */
+export type ViewCallbackContext<TContext extends readonly RouteContext[] = []> = {
+    push: RouterPush<RouteContextToRoute<[...TContext]>>;
+    replace: RouterReplace<RouteContextToRoute<[...TContext]>>;
+    reject: RouterReject<RouteContextToRejection<[...TContext]>>;
+    signal: AbortSignal;
+};
+export type ViewPropsGetter<TContext extends readonly RouteContext[], TProps, TRoutes extends Routes = Routes> = (route: ResolvedRouteWithDataUnion<TRoutes[number]>, context: ViewCallbackContext<TContext>) => TProps;
+/**
+ * Options for a reusable component and its props getter.
+ */
+export type CreateViewOptions<TComponent extends Component = Component, TContext extends readonly RouteContext[] = [], TProps extends MaybePromise<ComponentProps<TComponent>> | undefined = undefined, TRoutes extends Routes = Routes> = TransformerOptions<NoInfer<Awaited<TProps>>> & {
+    component: TComponent;
+    /**
+     * See [Context](https://kitbag-router.netlify.app/advanced-concepts/context).
+     */
+    context?: TContext;
+    prefetch?: PrefetchConfig;
+} & (Partial<ComponentProps<TComponent>> extends ComponentProps<TComponent> ? {
+    props?: ViewPropsGetter<TContext, TProps extends undefined ? MaybePromise<ComponentProps<TComponent>> : TProps, TRoutes>;
+} : {
+    props: ViewPropsGetter<TContext, TProps extends undefined ? MaybePromise<ComponentProps<TComponent>> : TProps, TRoutes>;
+});
+/**
+ * Creates views with props callbacks typed to the router's resolved routes and loader data.
+ */
+export type CreateView<TRoutes extends Routes = Routes> = <TComponent extends Component, const TContext extends readonly RouteContext[] = [], TProps extends MaybePromise<ComponentProps<TComponent>> | undefined = undefined>(options: CreateViewOptions<TComponent, TContext, TProps, TRoutes>) => View<TProps, TContext>;
+/**
+ * A reusable view definition with its props getter's result and declared context.
+ */
+export type View<TProps = unknown, TContext extends readonly RouteContext[] = []> = TransformerOptions<Awaited<TProps>> & {
+    component: Component;
+    props?: AnyFunction<TProps>;
+    context: TContext;
+    prefetch?: PrefetchConfig;
+};
+export type AnyView = View<any, readonly RouteContext[]>;
+/**
+ * Determines whether a value is a reusable view.
+ */
+export declare function isView(value: unknown): value is AnyView & ViewInternal;

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/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/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: {};
+    readonly path: "/childB/[paramD]";
     loaders: {};
+    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: {};
+    readonly path: "/[paramC]";
     loaders: {};
+    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: {};
+    readonly path: "/parentB";
     loaders: {};
+    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: {};
+    readonly path: "/";
     loaders: {};
+    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.27.0",
+  "version": "0.29.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/language-core": "^3.3.12",
     "@vue/test-utils": "^2.5.1",
-    "arktype": "^2.2.5",
+    "arktype": "^2.2.8",
     "eslint": "^9.39.5",
-    "globals": "^17.12.0",
-    "happy-dom": "^20.14.5",
+    "globals": "^17.13.0",
+    "happy-dom": "^20.14.6",
     "typedoc": "^0.28.20",
     "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.1",
+    "vitest": "^5.0.3",
     "vue-tsc": "^3.3.8",
     "zod": "4.0.0"
   },

package/dist/services/createRouteRedirects.d.ts

@@ -1,10 +0,0 @@
-import { RouteRedirects } from '../types/redirects';
-import { Route } from '../types/route';
-type CreateRouteRedirectsContext = {
-    /**
-     * The to route for the redirectFrom callback and the from route for the redirectTo callback.
-     */
-    getRoute: () => Route;
-};
-export declare function createRouteRedirects({ getRoute }: CreateRouteRedirectsContext): RouteRedirects;
-export {};

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[];