@lazycatcloud/vue-router-stack 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 LazycatCloud
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,282 @@
+# @lazycatcloud/vue-router-stack
+
+基于 Vue 3 和 vue-router 的页面栈路由库。它保留 vue-router 的路由定义和导航能力，同时提供类似移动端页面栈的 DOM 缓存、转场、页面生命周期和调试面板。
+
+当前版本适合浏览器端应用使用，暂不处理 SSR、手势返回识别、每个 tab 独立历史栈。
+
+## 安装
+
+```bash
+pnpm add @lazycatcloud/vue-router-stack vue vue-router
+```
+
+入口处引入样式：
+
+```ts
+import "@lazycatcloud/vue-router-stack/style.css";
+```
+
+## 基础使用
+
+创建 router 时使用 `createStackRouter`，其余路由写法保持 vue-router 风格。
+
+```ts
+import {
+  createStackRouter,
+  createWebHistory,
+  RouterView,
+} from "@lazycatcloud/vue-router-stack";
+
+export const router = createStackRouter({
+  history: createWebHistory(),
+  transition: "slide",
+  transitionDuration: 240,
+  routes: [
+    {
+      path: "/",
+      component: HomePage,
+    },
+    {
+      path: "/album",
+      component: RouterView,
+      children: [
+        { path: "detail", component: AlbumDetail },
+        { path: "map", component: AlbumMap },
+      ],
+    },
+  ],
+});
+```
+
+应用入口和普通 vue-router 一样：
+
+```ts
+import { createApp } from "vue";
+import App from "./App.vue";
+import { router } from "./router";
+
+createApp(App).use(router).mount("#app");
+```
+
+页面出口不要直接使用普通 `<router-view>`，使用 `RouterOutlet`：
+
+```vue
+<script setup lang="ts">
+import { RouterOutlet } from "@lazycatcloud/vue-router-stack";
+</script>
+
+<template>
+  <RouterOutlet />
+</template>
+```
+
+页面组件根节点使用 `RouterPage`：
+
+```vue
+<script setup lang="ts">
+import { RouterPage } from "@lazycatcloud/vue-router-stack";
+</script>
+
+<template>
+  <RouterPage>
+    <h1>Album Detail</h1>
+  </RouterPage>
+</template>
+```
+
+## 导航 API
+
+在组件里使用 `useStackRouter()`：
+
+```ts
+import { useStackRouter } from "@lazycatcloud/vue-router-stack";
+
+const stackRouter = useStackRouter();
+
+stackRouter.push("/album/detail");
+stackRouter.replace("/album/detail");
+stackRouter.back();
+stackRouter.forward();
+stackRouter.popTo("/album/detail");
+stackRouter.resetRoot("/");
+```
+
+单次导航可以控制方向、动画、时长和缓动：
+
+```ts
+stackRouter.push("/search/result", {
+  transition: "fade",
+});
+
+stackRouter.push("/timeline", {
+  direction: "none",
+});
+
+stackRouter.push("/detail", {
+  transition: "sheet",
+  duration: 300,
+  easing: "ease-out",
+});
+```
+
+`direction: "none"` 和 `direction: "root"` 会强制不播放转场，适合 tab 切换和清栈回首页。
+
+## 转场动画
+
+内置动画：
+
+- `slide`
+- `fade`
+- `scale`
+- `none`
+
+可以通过 `defineStackTransition` 注册自定义动画：
+
+```ts
+import { createStackRouter, defineStackTransition } from "@lazycatcloud/vue-router-stack";
+
+export const router = createStackRouter({
+  history: createWebHistory(),
+  transition: "slide",
+  transitions: {
+    sheet: defineStackTransition(({ direction }) => ({
+      entering:
+        direction === "back"
+          ? [{ transform: "translateY(-8%)" }, { transform: "translateY(0)" }]
+          : [{ transform: "translateY(100%)" }, { transform: "translateY(0)" }],
+      leaving:
+        direction === "back"
+          ? [{ transform: "translateY(0)" }, { transform: "translateY(100%)" }]
+          : [{ transform: "translateY(0)" }, { transform: "translateY(-8%)" }],
+    })),
+  },
+  routes,
+});
+```
+
+返回时会优先使用离开页面进入时记录的动画。例如用 `sheet` 打开详情页，返回时会按 `sheet` 收起。
+
+## 转场决策
+
+`shouldTransition` 用于业务侧决定本次导航是否播放动画。库只提供上下文，不内置 iOS 或具体设备判断。
+
+```ts
+const isIOS =
+  /iPad|iPhone|iPod/.test(navigator.userAgent) ||
+  (navigator.platform === "MacIntel" && navigator.maxTouchPoints > 1);
+
+export const router = createStackRouter({
+  history: createWebHistory(),
+  shouldTransition(ctx) {
+    if (isIOS && ctx.source === "external") return false;
+    return ctx.defaultResult;
+  },
+  routes,
+});
+```
+
+`ctx.source` 有两个值：
+
+- `stack`：由 `stackRouter.push/back/popTo/resetRoot` 等库 API 触发。
+- `external`：由浏览器 history 或系统手势等外部来源触发。
+
+## 页面生命周期
+
+页面被栈缓存时不会频繁卸载，可以使用页面生命周期处理进入和离开：
+
+```ts
+import {
+  onPageDidEnter,
+  onPageDidLeave,
+  onPageWillEnter,
+  onPageWillLeave,
+} from "@lazycatcloud/vue-router-stack";
+
+onPageWillEnter(() => {});
+onPageDidEnter(() => {});
+onPageWillLeave(() => {});
+onPageDidLeave(() => {});
+```
+
+触发顺序保持为：
+
+1. `onPageWillEnter`
+2. `onPageWillLeave`
+3. 转场动画
+4. `onPageDidLeave`
+5. `onPageDidEnter`
+
+## 缓存策略
+
+默认页面会缓存，返回时复用旧实例并保留滚动位置和组件状态。
+
+可以在路由 meta 中关闭某个页面的缓存：
+
+```ts
+{
+  path: "/search/result",
+  component: SearchResult,
+  meta: {
+    stackCache: false,
+  },
+}
+```
+
+也可以使用嵌套写法：
+
+```ts
+{
+  path: "/search/result",
+  component: SearchResult,
+  meta: {
+    stack: {
+      cache: false,
+    },
+  },
+}
+```
+
+通过 `maxStackSize` 限制最大缓存栈长度：
+
+```ts
+createStackRouter({
+  history: createWebHistory(),
+  maxStackSize: 30,
+  routes,
+});
+```
+
+## 调试面板
+
+开发时可以挂载 `StackRouterDebugPanel` 查看当前栈、缓存、转场和导航来源：
+
+```vue
+<script setup lang="ts">
+import { StackRouterDebugPanel } from "@lazycatcloud/vue-router-stack";
+</script>
+
+<template>
+  <RouterView />
+  <StackRouterDebugPanel />
+</template>
+```
+
+## Demo
+
+本仓库内置 PC 和 Mobile 两个 demo：
+
+- PC：左侧侧边栏 + 右侧内容区
+- Mobile：顶部内容区 + 底部栏切换
+
+```bash
+pnpm install
+pnpm dev
+```
+
+## 验证
+
+```bash
+pnpm run type-check
+pnpm test
+pnpm run build
+```

package/dist/components/RouterOutlet.d.ts

@@ -0,0 +1,20 @@
+import { type Component, type ComponentPublicInstance, type Ref } from "vue";
+import type { RouteLocationMatched } from "vue-router";
+import type { RouteInfo } from "../router/types";
+interface ViewItem {
+    id: string;
+    key: string;
+    routeInfo: RouteInfo;
+    matchedRoute: RouteLocationMatched;
+    component: Component;
+    props: Record<string, unknown>;
+    pageElement?: HTMLElement;
+    componentRef: Ref<ComponentPublicInstance | undefined>;
+    mounted: boolean;
+}
+export declare const RouterOutlet: import("vue").DefineComponent<{}, {
+    injectedRoute: import("vue-router").RouteLocationNormalizedLoadedGeneric;
+    viewItems: import("vue").ShallowRef<ViewItem[], ViewItem[]>;
+    registerStackPage: (viewItem: ViewItem, element: HTMLElement) => void;
+}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<{}> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
+export {};

package/dist/components/RouterPage.d.ts

@@ -0,0 +1,15 @@
+export declare const RouterPage: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
+    registerStackPage: {
+        type: FunctionConstructor;
+        default: undefined;
+    };
+}>, () => import("vue").VNode<import("vue").RendererNode, import("vue").RendererElement, {
+    [key: string]: any;
+}>, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<import("vue").ExtractPropTypes<{
+    registerStackPage: {
+        type: FunctionConstructor;
+        default: undefined;
+    };
+}>> & Readonly<{}>, {
+    registerStackPage: Function;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;

package/dist/components/StackRouterDebugPanel.d.ts

@@ -0,0 +1,15 @@
+export declare const StackRouterDebugPanel: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
+    initialOpen: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+}>, () => import("vue").VNode<import("vue").RendererNode, import("vue").RendererElement, {
+    [key: string]: any;
+}>, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<import("vue").ExtractPropTypes<{
+    initialOpen: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+}>> & Readonly<{}>, {
+    initialOpen: boolean;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;

package/dist/composables/lifecycle.d.ts

@@ -0,0 +1,10 @@
+import { type ComponentInternalInstance } from "vue";
+export declare const PAGE_WILL_ENTER = "onPageWillEnter";
+export declare const PAGE_DID_ENTER = "onPageDidEnter";
+export declare const PAGE_WILL_LEAVE = "onPageWillLeave";
+export declare const PAGE_DID_LEAVE = "onPageDidLeave";
+export type PageLifecycleName = typeof PAGE_WILL_ENTER | typeof PAGE_DID_ENTER | typeof PAGE_WILL_LEAVE | typeof PAGE_DID_LEAVE;
+export declare const onPageWillEnter: (hook: () => void, target?: ComponentInternalInstance | null) => void;
+export declare const onPageDidEnter: (hook: () => void, target?: ComponentInternalInstance | null) => void;
+export declare const onPageWillLeave: (hook: () => void, target?: ComponentInternalInstance | null) => void;
+export declare const onPageDidLeave: (hook: () => void, target?: ComponentInternalInstance | null) => void;

package/dist/composables/useStackRouter.d.ts

@@ -0,0 +1,14 @@
+import type { NavigationFailure, RouteLocationRaw } from "vue-router";
+import type { StackNavigationOptions, StackRouter, StackVueRouter } from "../router/types";
+export interface UseStackRouterResult {
+    router: StackVueRouter;
+    canGoBack: (deep?: number) => boolean;
+    push: (to: RouteLocationRaw, options?: StackNavigationOptions) => Promise<void | NavigationFailure | undefined>;
+    replace: (to: RouteLocationRaw, options?: StackNavigationOptions) => Promise<void | NavigationFailure | undefined>;
+    popTo: (to: RouteLocationRaw, options?: StackNavigationOptions) => boolean;
+    resetRoot: (to: RouteLocationRaw, options?: StackNavigationOptions) => Promise<void | NavigationFailure | undefined>;
+    back: () => void;
+    forward: () => void;
+}
+export declare function useStackRouter(): UseStackRouterResult;
+export declare function useStackRouterInternal(): StackRouter;

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+import "./styles/core.css";
+export { createStackRouter, stackRouterKey, } from "./router/createStackRouter";
+export { type RouteAction, type RouteDirection, type RouteInfo, type StackNavigationOptions, type StackNavigationSource, type StackRouter, type StackRouterNavigation, type StackRouterOptions, type StackShouldTransition, type StackShouldTransitionContext, type StackTransitionContext, type StackTransitionDefinition, type StackTransitionFactory, type StackTransitionName, type StackTransitionRegistry, type StackVueRouter, } from "./router/types";
+export { defineStackTransition } from "./router/transitions";
+export { RouterOutlet } from "./components/RouterOutlet";
+export { RouterPage } from "./components/RouterPage";
+export { StackRouterDebugPanel } from "./components/StackRouterDebugPanel";
+export { useStackRouter, type UseStackRouterResult } from "./composables/useStackRouter";
+export { onPageDidEnter, onPageDidLeave, onPageWillEnter, onPageWillLeave, } from "./composables/lifecycle";
+export { createWebHashHistory, createWebHistory, createMemoryHistory, RouterLink, RouterView, useRoute, useRouter, } from "vue-router";

package/dist/router/createStackRouter.d.ts

@@ -0,0 +1,4 @@
+import { InjectionKey } from "vue";
+import type { StackRouter, StackRouterOptions, StackVueRouter } from "./types";
+export declare const stackRouterKey: InjectionKey<StackRouter>;
+export declare function createStackRouter(options: StackRouterOptions): StackVueRouter;

package/dist/router/id.d.ts

@@ -0,0 +1 @@
+export declare function createId(type?: string): string;

package/dist/router/transitions.d.ts

@@ -0,0 +1,7 @@
+import type { StackTransitionContext, StackTransitionFactory, StackTransitionName, StackTransitionRegistry } from "./types";
+export declare const DEFAULT_STACK_TRANSITION = "slide";
+export declare const DEFAULT_STACK_TRANSITION_EASING = "cubic-bezier(0.2, 0, 0, 1)";
+export declare function defineStackTransition(factory: StackTransitionFactory): StackTransitionFactory;
+export declare const builtinStackTransitions: StackTransitionRegistry;
+export declare function resolveStackTransition(name: StackTransitionName, transitions: StackTransitionRegistry): StackTransitionFactory;
+export declare function runStackTransition(factory: StackTransitionFactory, context: StackTransitionContext): Promise<void>;

package/dist/router/types.d.ts

@@ -0,0 +1,104 @@
+import type { NavigationFailure, RouteLocationNormalizedLoaded, RouteLocationRaw, Router, RouterOptions } from "vue-router";
+declare module "vue-router" {
+    interface RouteMeta {
+        stackCache?: boolean;
+        stack?: {
+            cache?: boolean;
+        };
+    }
+}
+export type RouteAction = "push" | "pop" | "replace";
+export type RouteDirection = "forward" | "back" | "root" | "none";
+export type StackNavigationSource = "stack" | "external";
+export type StackTransitionName = "slide" | "fade" | "scale" | "none" | (string & {});
+export interface StackTransitionContext {
+    direction: RouteDirection;
+    action: RouteAction;
+    routeInfo: RouteInfo;
+    enteringElement: HTMLElement;
+    leavingElement: HTMLElement;
+    duration: number;
+    easing: string;
+}
+export interface StackShouldTransitionContext {
+    action: RouteAction;
+    direction: RouteDirection;
+    source: StackNavigationSource;
+    entering: RouteInfo;
+    leaving?: RouteInfo;
+    defaultResult: boolean;
+}
+export type StackShouldTransition = (context: StackShouldTransitionContext) => boolean;
+export interface StackTransitionDefinition {
+    entering?: Keyframe[] | PropertyIndexedKeyframes;
+    leaving?: Keyframe[] | PropertyIndexedKeyframes;
+    options?: KeyframeAnimationOptions;
+}
+export type StackTransitionFactory = (context: StackTransitionContext) => StackTransitionDefinition;
+export type StackTransitionRegistry = Record<string, StackTransitionFactory>;
+export interface StackNavigationOptions {
+    direction?: RouteDirection;
+    transition?: StackTransitionName;
+    duration?: number;
+    easing?: string;
+}
+export interface RouteInfo {
+    id: string;
+    key: string;
+    fullPath: string;
+    pathname: string;
+    params: RouteLocationNormalizedLoaded["params"];
+    query: RouteLocationNormalizedLoaded["query"];
+    action: RouteAction;
+    direction: RouteDirection;
+    source: StackNavigationSource;
+    entryDirection: RouteDirection;
+    lastPathname?: string;
+    pushedByRoute?: string;
+    position: number;
+    delta?: number;
+    transition?: StackTransitionName;
+    transitionDuration?: number;
+    transitionEasing?: string;
+    cache: boolean;
+    isStackFallback?: boolean;
+}
+export interface StackRouterOptions extends RouterOptions {
+    transitionDuration?: number;
+    transitionEasing?: string;
+    transition?: StackTransitionName;
+    transitions?: StackTransitionRegistry;
+    maxStackSize?: number;
+    shouldTransition?: StackShouldTransition;
+}
+export interface PendingNavigation {
+    action: RouteAction;
+    direction: RouteDirection;
+    source: StackNavigationSource;
+    delta?: number;
+    transition?: StackTransitionName;
+    duration?: number;
+    easing?: string;
+    resetRoot?: boolean;
+}
+export interface StackRouterNavigation {
+    push: (to: RouteLocationRaw, options?: StackNavigationOptions) => Promise<void | NavigationFailure | undefined>;
+    replace: (to: RouteLocationRaw, options?: StackNavigationOptions) => Promise<void | NavigationFailure | undefined>;
+    popTo: (to: RouteLocationRaw, options?: StackNavigationOptions) => boolean;
+    resetRoot: (to: RouteLocationRaw, options?: StackNavigationOptions) => Promise<void | NavigationFailure | undefined>;
+    back: () => void;
+    forward: () => void;
+}
+export interface StackRouter extends StackRouterNavigation {
+    router: StackVueRouter;
+    transitionDuration: number;
+    transitionEasing: string;
+    transition: StackTransitionName;
+    transitions: StackTransitionRegistry;
+    maxStackSize: number;
+    shouldTransition?: StackShouldTransition;
+    current: Readonly<import("vue").ShallowRef<RouteInfo | undefined>>;
+    history: readonly RouteInfo[];
+    canGoBack: (deep?: number) => boolean;
+}
+export type StackVueRouter = Router & StackRouterNavigation;

package/dist/utils/lifecycle.d.ts

@@ -0,0 +1,3 @@
+import type { ComponentPublicInstance, Ref } from "vue";
+import type { PageLifecycleName } from "../composables/lifecycle";
+export declare function fireLifecycle(componentRef: Ref<ComponentPublicInstance | undefined>, lifecycle: PageLifecycleName): void;

package/dist/vue-router-stack.cjs

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const i=require("vue"),b=require("vue-router"),J={};function z(e="route"){const r=(J[e]??0)+1;return J[e]=r,`${e}-${r}`}const v="slide",re="cubic-bezier(0.2, 0, 0, 1)";function oe(e){return e}const ne=({direction:e})=>{const r=e==="back";return{entering:r?[{transform:"translateX(-18%)",opacity:.96},{transform:"translateX(0)",opacity:1}]:[{transform:"translateX(100%)"},{transform:"translateX(0)"}],leaving:r?[{transform:"translateX(0)",opacity:1},{transform:"translateX(100%)",opacity:1}]:[{transform:"translateX(0)",opacity:1},{transform:"translateX(-18%)",opacity:.96}]}},ae=()=>({entering:[{opacity:0},{opacity:1}],leaving:[{opacity:1},{opacity:0}]}),ce=({direction:e})=>{const r=e==="back";return{entering:r?[{transform:"scale(0.98)",opacity:0},{transform:"scale(1)",opacity:1}]:[{transform:"scale(1.04)",opacity:0},{transform:"scale(1)",opacity:1}],leaving:r?[{transform:"scale(1)",opacity:1},{transform:"scale(1.04)",opacity:0}]:[{transform:"scale(1)",opacity:1},{transform:"scale(0.98)",opacity:0}]}},ie=()=>({}),se={slide:ne,fade:ae,scale:ce,none:ie};function ue(e,r){const n=r[e];return n||r[v]}function Q(e,r,n){if(!r||!e.animate||Number(n.duration)<=0)return Promise.resolve();const l=e.animate(r,n);return l.finished.then(()=>l.cancel())}async function le(e,r){const n=e(r),l={duration:r.duration,easing:r.easing,fill:"both",...n.options};await Promise.all([Q(r.enteringElement,n.entering,l),Q(r.leavingElement,n.leaving,l)])}const H=Symbol("stack-router");function fe(){const e=window.history.state;return typeof(e==null?void 0:e.position)=="number"?e.position:window.history.length}function M(e,r){return r||(e==="pop"?"back":e==="replace"?"none":"forward")}function de(e){const r=b.createRouter(e),n=[],l=i.shallowRef(),f=e.transitionDuration??240,T=e.transitionEasing??re,S=e.transition??v,p={...se,...e.transitions},E=e.maxStackSize??30;let d=-1,s,g=!1;const P=(c,a,u,h,k=!1,w="stack")=>{s={action:c,direction:M(c,a),source:w,delta:u,transition:h==null?void 0:h.transition,duration:h==null?void 0:h.duration,easing:h==null?void 0:h.easing,resetRoot:k}},F=(c,a)=>{const u=(s==null?void 0:s.action)??"push",h=M(u,s==null?void 0:s.direction),k=l.value,w=u==="push"&&h==="forward",te=L(c);return{id:z("route"),key:c.fullPath,fullPath:c.fullPath,pathname:c.path,params:c.params,query:c.query,action:u,direction:h,source:(s==null?void 0:s.source)??"stack",entryDirection:h,lastPathname:(k==null?void 0:k.pathname)||(a.name?a.path:void 0),pushedByRoute:w?k==null?void 0:k.pathname:k==null?void 0:k.pushedByRoute,position:fe(),delta:s==null?void 0:s.delta,transition:(s==null?void 0:s.transition)??S,transitionDuration:(s==null?void 0:s.duration)??f,transitionEasing:(s==null?void 0:s.easing)??T,cache:te}},L=c=>{const a=c.meta.stack;return c.meta.stackCache!==!1&&(a==null?void 0:a.cache)!==!1},x=()=>{if(E<=0||n.length<=E)return;const c=n.length-E;n.splice(0,c),d=Math.max(0,d-c)},W=c=>{if(c.action==="pop"){let a=-1;if(c.direction==="forward"||(c.delta??0)>0){for(let u=d+1;u<n.length;u++)if(n[u].key===c.key){a=u;break}}else for(let u=d-1;u>=0;u--)if(n[u].key===c.key){a=u;break}if(a>=0){const u=n[a];n[a]={...u,...c,id:u.id,source:c.source,entryDirection:u.entryDirection,transition:u.transition,transitionDuration:u.transitionDuration,transitionEasing:u.transitionEasing},d=a}else n.push({...c,direction:"none",entryDirection:"none",transition:"none",isStackFallback:!0}),d=n.length-1}else if(c.action==="replace"){if(s!=null&&s.resetRoot){n.splice(0,n.length,c),d=0,l.value=n[d];return}d>=0?n[d]=c:(n.push(c),d=0)}else d<n.length-1&&n.splice(d+1),n.push(c),d=n.length-1;x(),l.value=n[d]};e.history.listen((c,a,u)=>{const h="delta"in u?u.delta:void 0,k=u.direction==="back"?"back":u.direction==="forward"?"forward":void 0;s?(s.delta=h,s.direction=M(s.action,s.direction??k)):P(u.type==="pop"?"pop":u.type,k,h,void 0,!1,"external")}),r.beforeEach(c=>!((s==null?void 0:s.action)==="pop"&&g&&!n.some(a=>a.fullPath===c.fullPath))),r.afterEach((c,a,u)=>{if(u){s=void 0;return}W(F(c,a)),s=void 0});const B=r.push.bind(r),A=r.replace.bind(r),G=r.back.bind(r),V=r.forward.bind(r),$=r.go.bind(r),j=(c,a)=>(P("push",(a==null?void 0:a.direction)??"forward",void 0,a),B(c)),K=(c,a)=>(P("replace",(a==null?void 0:a.direction)??"root",void 0,a),A(c)),t=(c,a)=>{const u=r.resolve(c).fullPath;let h=-1;for(let w=d;w>=0;w--)if(n[w].fullPath===u){h=w;break}if(h<0)return!1;const k=h-d;return k===0||(P("pop",(a==null?void 0:a.direction)??"back",k,a),$(k)),!0},o=(c,a)=>{const u=r.resolve(c).fullPath;if(d>=0&&r.currentRoute.value.fullPath===u){const h=n[d],k={...h,id:z("route"),action:"replace",direction:(a==null?void 0:a.direction)??"root",source:"stack",entryDirection:(a==null?void 0:a.direction)??"root",delta:void 0,transition:(a==null?void 0:a.transition)??h.transition,transitionDuration:(a==null?void 0:a.duration)??h.transitionDuration,transitionEasing:(a==null?void 0:a.easing)??h.transitionEasing,cache:!0,isStackFallback:!1};return n.splice(0,n.length,k),d=0,g=!0,l.value=k,Promise.resolve(void 0)}return P("replace",(a==null?void 0:a.direction)??"root",void 0,a,!0),g=!0,A(c)},m=()=>{P("pop","back",-1),G()},R=()=>{P("pop","forward",1),V()},y=r;y.push=j,y.replace=K,y.popTo=t,y.resetRoot=o,y.back=m,y.forward=R;const _={router:y,transitionDuration:f,transitionEasing:T,transition:S,transitions:p,maxStackSize:E,shouldTransition:e.shouldTransition,current:l,get history(){return n},canGoBack:(c=1)=>d-c>=0,push:j,replace:K,popTo:t,resetRoot:o,back:m,forward:R},X=r.install.bind(r);return r.install=c=>{c.provide(H,_),X(c)},y}const Y="onPageWillEnter",U="onPageDidEnter",Z="onPageWillLeave",N="onPageDidLeave";function he(e,r,n){if(!n)throw new Error(`${e} must be called inside setup().`);const l=n.proxy,f=l[e]??[];f.push(()=>{n.isUnmounted||r()}),l[e]=f,n.exposed&&(n.exposed[e]=f)}function C(e){return(r,n=i.getCurrentInstance())=>he(e,r,n)}const me=C(Y),ye=C(U),ke=C(Z),pe=C(N);function Re(){const e=i.inject(H);if(!e)throw new Error("useStackRouter must be used after createStackRouter().");return{router:e.router,canGoBack:e.canGoBack,push:e.push,replace:e.replace,popTo:e.popTo,resetRoot:e.resetRoot,back:e.back,forward:e.forward}}function O(){const e=i.inject(H);if(!e)throw new Error("RouterOutlet must be used with createStackRouter().");return e}function D(e,r){const n=e.value;if(!n)return;const l=n[r];Array.isArray(l)?l.forEach(f=>f()):typeof l=="function"&&l.call(n)}function I(e){e.classList.remove("rs-page-hidden","rs-page-invisible"),e.removeAttribute("aria-hidden")}function q(e){e.classList.add("rs-page-hidden"),e.setAttribute("aria-hidden","true")}function ee(e){var r;return(r=e.components)==null?void 0:r.default}function be(e){const r=ee(e);return r!==void 0&&typeof r=="object"&&"name"in r&&r.name==="RouterView"}const Pe=i.defineComponent({name:"RouterOutlet",setup(){const e=O(),r=b.useRoute(),n=i.inject(b.routeLocationKey),l=i.inject(b.matchedRouteKey,void 0),f=i.computed(()=>{const t=l==null?void 0:l.value;if(!t)return 0;const o=r.matched.findIndex(m=>m===t);return o>=0?o+1:0}),T=i.computed(()=>r.matched[f.value]),S=i.computed(()=>{for(let t=f.value;t<r.matched.length;t++){const o=r.matched[t];if(!be(o))return o}return T.value}),p=i.shallowRef([]),E=i.ref("");let d=0;i.provide(b.matchedRouteKey,S);const s=t=>p.value.find(o=>o.key===t),g=t=>{p.value.forEach(o=>{o.pageElement&&(o===t?I(o.pageElement):q(o.pageElement))})},P=t=>{const o=p.value.findIndex(m=>m===t);o>=0&&(p.value=p.value.slice(0,o+1))},F=t=>{p.value=p.value.filter(o=>o!==t)},L=t=>{const o=new Set(e.history.map(m=>m.key));p.value=p.value.filter(m=>m===t||m.routeInfo.cache&&o.has(m.key))},x=t=>{var m;const o=t.props.default;return o?o===!0?((m=e.current.value)==null?void 0:m.params)??{}:typeof o=="function"?o(n):o:{}},W=(t,o)=>t.routeInfo.action==="pop"?o.routeInfo.transition??t.routeInfo.transition??e.transition:t.routeInfo.transition??e.transition,B=(t,o)=>!(t.routeInfo.isStackFallback||t.routeInfo.direction==="none"||t.routeInfo.direction==="root"||t.routeInfo.action==="pop"&&(o.routeInfo.entryDirection==="none"||o.routeInfo.entryDirection==="root"||o.routeInfo.transition==="none")),A=(t,o)=>{var R;const m=B(t,o);return((R=e.shouldTransition)==null?void 0:R.call(e,{action:t.routeInfo.action,direction:t.routeInfo.direction,source:t.routeInfo.source,entering:t.routeInfo,leaving:o.routeInfo,defaultResult:m}))??m},G=(t,o)=>t.routeInfo.action==="pop"?o.routeInfo.transitionDuration??t.routeInfo.transitionDuration??e.transitionDuration:t.routeInfo.transitionDuration??e.transitionDuration,V=(t,o)=>t.routeInfo.action==="pop"?o.routeInfo.transitionEasing??t.routeInfo.transitionEasing??e.transitionEasing:t.routeInfo.transitionEasing??e.transitionEasing,$=async(t,o)=>{const m=++d;await i.nextTick();const R=t.pageElement;if(!R)return;if(D(t.componentRef,Y),!o||o===t||!o.pageElement){I(R),D(t.componentRef,U),L(t),g(t);return}const y=o.pageElement,_=A(t,o),X=_?W(t,o):"none",c=_?G(t,o):0,a=V(t,o),u=ue(X||v,e.transitions);D(o.componentRef,Z),I(R),I(y),await le(u,{direction:t.routeInfo.direction,action:t.routeInfo.action,routeInfo:t.routeInfo,enteringElement:R,leavingElement:y,duration:c,easing:a}),m===d&&(q(y),D(o.componentRef,N),D(t.componentRef,U),t.routeInfo.action==="pop"?P(t):t.routeInfo.action==="replace"&&F(o),L(t),g(t))},j=async()=>{const t=S.value,o=e.current.value;if(!t||!o)return;const m=ee(t);if(!m)return;const R=s(E.value);let y=s(o.key);y?(y.routeInfo=o,y.matchedRoute=t,y.component=m,y.props=x(t),y.mounted=!0):(y={id:z("view"),key:o.key,routeInfo:o,matchedRoute:t,component:m,props:x(t),componentRef:i.ref(),mounted:!0},p.value=[...p.value,y]),E.value=y.key,await $(y,R)};return i.watch(()=>{var t;return[(t=e.current.value)==null?void 0:t.id,S.value]},()=>{j()},{immediate:!0}),i.onUnmounted(()=>{d++,p.value=[]}),{injectedRoute:n,viewItems:p,registerStackPage:(t,o)=>{t.pageElement=o,t.key===E.value?I(o):q(o)}}},render(){return i.h("div",{class:"rs-outlet"},this.viewItems.filter(e=>e.mounted).map(e=>i.h(e.component,{key:e.id,ref:e.componentRef,...e.props,registerStackPage:r=>this.registerStackPage(e,r)})))}}),Ee=i.defineComponent({name:"RouterPage",props:{registerStackPage:{type:Function,default:void 0}},setup(e,{attrs:r,slots:n}){const l=i.ref();return i.onMounted(()=>{var f;l.value&&((f=e.registerStackPage)==null||f.call(e,l.value))}),()=>{var f;return i.h("section",{...r,ref:l,class:["rs-page",r.class]},(f=n.default)==null?void 0:f.call(n))}}}),we=i.defineComponent({name:"StackRouterDebugPanel",props:{initialOpen:{type:Boolean,default:!1}},setup(e){const r=O(),n=i.ref(e.initialOpen);return()=>{const l=r.current.value;return i.h("aside",{class:"rs-debug-panel"},[i.h("button",{class:"rs-debug-toggle",type:"button",onClick:()=>{n.value=!n.value}},n.value?"Stack x":"Stack"),n.value?i.h("section",{class:"rs-debug-body"},[i.h("header",[i.h("strong","Router Stack"),i.h("span",`${r.history.length} pages`)]),i.h("dl",[i.h("dt","current"),i.h("dd",(l==null?void 0:l.fullPath)??"-"),i.h("dt","canGoBack"),i.h("dd",String(r.canGoBack()))]),i.h("ol",r.history.map(f=>i.h("li",{key:f.id,class:{"rs-debug-active":f.id===(l==null?void 0:l.id),"rs-debug-no-cache":!f.cache}},[i.h("code",f.fullPath),i.h("span",[`${f.action}/${f.direction}`,` source:${f.source}`,` entry:${f.entryDirection}`,` cache:${f.cache?"yes":"no"}`,` transition:${f.transition??"-"}`])])))]):void 0])}}});Object.defineProperty(exports,"RouterLink",{enumerable:!0,get:()=>b.RouterLink});Object.defineProperty(exports,"RouterView",{enumerable:!0,get:()=>b.RouterView});Object.defineProperty(exports,"createMemoryHistory",{enumerable:!0,get:()=>b.createMemoryHistory});Object.defineProperty(exports,"createWebHashHistory",{enumerable:!0,get:()=>b.createWebHashHistory});Object.defineProperty(exports,"createWebHistory",{enumerable:!0,get:()=>b.createWebHistory});Object.defineProperty(exports,"useRoute",{enumerable:!0,get:()=>b.useRoute});Object.defineProperty(exports,"useRouter",{enumerable:!0,get:()=>b.useRouter});exports.RouterOutlet=Pe;exports.RouterPage=Ee;exports.StackRouterDebugPanel=we;exports.createStackRouter=de;exports.defineStackTransition=oe;exports.onPageDidEnter=ye;exports.onPageDidLeave=pe;exports.onPageWillEnter=me;exports.onPageWillLeave=ke;exports.stackRouterKey=H;exports.useStackRouter=Re;

package/dist/vue-router-stack.css

@@ -0,0 +1 @@
+.rs-outlet{position:relative;display:block;width:100%;height:100%;overflow:hidden;contain:layout size style}.rs-page{position:absolute;top:0;right:0;bottom:0;left:0;display:flex;min-width:0;min-height:0;flex-direction:column;overflow:hidden;background:var(--rs-page-background, #fff);z-index:0}.rs-page-hidden,[hidden].rs-page{display:none!important}.rs-page-invisible{opacity:0}.rs-debug-panel{position:fixed;right:12px;bottom:12px;z-index:9999;color:#d9e5ef;font:12px/1.45 ui-monospace,SFMono-Regular,Menlo,Monaco,Consolas,Liberation Mono,monospace}.rs-debug-toggle{min-width:72px;border:0;border-radius:6px;padding:8px 10px;color:#f8fafc;background:#111827;cursor:pointer}.rs-debug-body{width:min(420px,calc(100vw - 24px));max-height:min(520px,calc(100vh - 96px));overflow:auto;margin-top:8px;border:1px solid rgb(148 163 184 / 28%);border-radius:8px;padding:12px;background:#0f172af0;box-shadow:0 18px 48px #0f172a4d}.rs-debug-body header{display:flex;align-items:center;justify-content:space-between;gap:12px;margin-bottom:10px}.rs-debug-body dl{display:grid;grid-template-columns:auto minmax(0,1fr);gap:4px 10px;margin:0 0 10px}.rs-debug-body dt{color:#94a3b8}.rs-debug-body dd{min-width:0;margin:0;overflow-wrap:anywhere}.rs-debug-body ol{display:grid;gap:6px;margin:0;padding:0;list-style:none}.rs-debug-body li{display:grid;gap:3px;border-radius:6px;padding:7px;background:#ffffff0f}.rs-debug-body code{overflow-wrap:anywhere;color:#f8fafc}.rs-debug-body li span{color:#a7b7c8}.rs-debug-body .rs-debug-active{background:#14b8a638}.rs-debug-body .rs-debug-no-cache{outline:1px solid rgb(248 113 113 / 55%)}

package/dist/vue-router-stack.js

@@ -0,0 +1,566 @@
+import { shallowRef as tt, getCurrentInstance as st, inject as F, defineComponent as Q, h as k, computed as z, ref as B, provide as it, watch as ut, onUnmounted as lt, nextTick as ft, onMounted as dt } from "vue";
+import { createRouter as ht, useRoute as mt, routeLocationKey as yt, matchedRouteKey as v } from "vue-router";
+import { RouterLink as Kt, RouterView as jt, createMemoryHistory as zt, createWebHashHistory as Ut, createWebHistory as Mt, useRoute as qt, useRouter as Jt } from "vue-router";
+const N = {};
+function q(t = "route") {
+  const r = (N[t] ?? 0) + 1;
+  return N[t] = r, `${t}-${r}`;
+}
+const Y = "slide", kt = "cubic-bezier(0.2, 0, 0, 1)";
+function Lt(t) {
+  return t;
+}
+const pt = ({ direction: t }) => {
+  const r = t === "back";
+  return {
+    entering: r ? [
+      { transform: "translateX(-18%)", opacity: 0.96 },
+      { transform: "translateX(0)", opacity: 1 }
+    ] : [{ transform: "translateX(100%)" }, { transform: "translateX(0)" }],
+    leaving: r ? [
+      { transform: "translateX(0)", opacity: 1 },
+      { transform: "translateX(100%)", opacity: 1 }
+    ] : [
+      { transform: "translateX(0)", opacity: 1 },
+      { transform: "translateX(-18%)", opacity: 0.96 }
+    ]
+  };
+}, Rt = () => ({
+  entering: [{ opacity: 0 }, { opacity: 1 }],
+  leaving: [{ opacity: 1 }, { opacity: 0 }]
+}), bt = ({ direction: t }) => {
+  const r = t === "back";
+  return {
+    entering: r ? [
+      { transform: "scale(0.98)", opacity: 0 },
+      { transform: "scale(1)", opacity: 1 }
+    ] : [
+      { transform: "scale(1.04)", opacity: 0 },
+      { transform: "scale(1)", opacity: 1 }
+    ],
+    leaving: r ? [
+      { transform: "scale(1)", opacity: 1 },
+      { transform: "scale(1.04)", opacity: 0 }
+    ] : [
+      { transform: "scale(1)", opacity: 1 },
+      { transform: "scale(0.98)", opacity: 0 }
+    ]
+  };
+}, Et = () => ({}), Pt = {
+  slide: pt,
+  fade: Rt,
+  scale: bt,
+  none: Et
+};
+function wt(t, r) {
+  const n = r[t];
+  return n || r[Y];
+}
+function O(t, r, n) {
+  if (!r || !t.animate || Number(n.duration) <= 0)
+    return Promise.resolve();
+  const u = t.animate(r, n);
+  return u.finished.then(() => u.cancel());
+}
+async function It(t, r) {
+  const n = t(r), u = {
+    duration: r.duration,
+    easing: r.easing,
+    fill: "both",
+    ...n.options
+  };
+  await Promise.all([
+    O(r.enteringElement, n.entering, u),
+    O(r.leavingElement, n.leaving, u)
+  ]);
+}
+const Z = Symbol("stack-router");
+function St() {
+  const t = window.history.state;
+  return typeof (t == null ? void 0 : t.position) == "number" ? t.position : window.history.length;
+}
+function U(t, r) {
+  return r || (t === "pop" ? "back" : t === "replace" ? "none" : "forward");
+}
+function At(t) {
+  const r = ht(t), n = [], u = tt(), l = t.transitionDuration ?? 240, T = t.transitionEasing ?? kt, w = t.transition ?? Y, p = {
+    ...Pt,
+    ...t.transitions
+  }, E = t.maxStackSize ?? 30;
+  let f = -1, s, I = !1;
+  const b = (c, a, i, d, y = !1, P = "stack") => {
+    s = {
+      action: c,
+      direction: U(c, a),
+      source: P,
+      delta: i,
+      transition: d == null ? void 0 : d.transition,
+      duration: d == null ? void 0 : d.duration,
+      easing: d == null ? void 0 : d.easing,
+      resetRoot: y
+    };
+  }, C = (c, a) => {
+    const i = (s == null ? void 0 : s.action) ?? "push", d = U(i, s == null ? void 0 : s.direction), y = u.value, P = i === "push" && d === "forward", ct = g(c);
+    return {
+      id: q("route"),
+      key: c.fullPath,
+      fullPath: c.fullPath,
+      pathname: c.path,
+      params: c.params,
+      query: c.query,
+      action: i,
+      direction: d,
+      source: (s == null ? void 0 : s.source) ?? "stack",
+      entryDirection: d,
+      lastPathname: (y == null ? void 0 : y.pathname) || (a.name ? a.path : void 0),
+      pushedByRoute: P ? y == null ? void 0 : y.pathname : y == null ? void 0 : y.pushedByRoute,
+      position: St(),
+      delta: s == null ? void 0 : s.delta,
+      transition: (s == null ? void 0 : s.transition) ?? w,
+      transitionDuration: (s == null ? void 0 : s.duration) ?? l,
+      transitionEasing: (s == null ? void 0 : s.easing) ?? T,
+      cache: ct
+    };
+  }, g = (c) => {
+    const a = c.meta.stack;
+    return c.meta.stackCache !== !1 && (a == null ? void 0 : a.cache) !== !1;
+  }, x = () => {
+    if (E <= 0 || n.length <= E) return;
+    const c = n.length - E;
+    n.splice(0, c), f = Math.max(0, f - c);
+  }, H = (c) => {
+    if (c.action === "pop") {
+      let a = -1;
+      if (c.direction === "forward" || (c.delta ?? 0) > 0) {
+        for (let i = f + 1; i < n.length; i++)
+          if (n[i].key === c.key) {
+            a = i;
+            break;
+          }
+      } else
+        for (let i = f - 1; i >= 0; i--)
+          if (n[i].key === c.key) {
+            a = i;
+            break;
+          }
+      if (a >= 0) {
+        const i = n[a];
+        n[a] = {
+          ...i,
+          ...c,
+          id: i.id,
+          source: c.source,
+          entryDirection: i.entryDirection,
+          transition: i.transition,
+          transitionDuration: i.transitionDuration,
+          transitionEasing: i.transitionEasing
+        }, f = a;
+      } else
+        n.push({
+          ...c,
+          direction: "none",
+          entryDirection: "none",
+          transition: "none",
+          isStackFallback: !0
+        }), f = n.length - 1;
+    } else if (c.action === "replace") {
+      if (s != null && s.resetRoot) {
+        n.splice(0, n.length, c), f = 0, u.value = n[f];
+        return;
+      }
+      f >= 0 ? n[f] = c : (n.push(c), f = 0);
+    } else
+      f < n.length - 1 && n.splice(f + 1), n.push(c), f = n.length - 1;
+    x(), u.value = n[f];
+  };
+  t.history.listen((c, a, i) => {
+    const d = "delta" in i ? i.delta : void 0, y = i.direction === "back" ? "back" : i.direction === "forward" ? "forward" : void 0;
+    s ? (s.delta = d, s.direction = U(
+      s.action,
+      s.direction ?? y
+    )) : b(
+      i.type === "pop" ? "pop" : i.type,
+      y,
+      d,
+      void 0,
+      !1,
+      "external"
+    );
+  }), r.beforeEach((c) => !((s == null ? void 0 : s.action) === "pop" && I && !n.some((a) => a.fullPath === c.fullPath))), r.afterEach((c, a, i) => {
+    if (i) {
+      s = void 0;
+      return;
+    }
+    H(C(c, a)), s = void 0;
+  });
+  const V = r.push.bind(r), L = r.replace.bind(r), $ = r.back.bind(r), W = r.forward.bind(r), X = r.go.bind(r), A = (c, a) => (b(
+    "push",
+    (a == null ? void 0 : a.direction) ?? "forward",
+    void 0,
+    a
+  ), V(c)), K = (c, a) => (b(
+    "replace",
+    (a == null ? void 0 : a.direction) ?? "root",
+    void 0,
+    a
+  ), L(c)), e = (c, a) => {
+    const i = r.resolve(c).fullPath;
+    let d = -1;
+    for (let P = f; P >= 0; P--)
+      if (n[P].fullPath === i) {
+        d = P;
+        break;
+      }
+    if (d < 0) return !1;
+    const y = d - f;
+    return y === 0 || (b(
+      "pop",
+      (a == null ? void 0 : a.direction) ?? "back",
+      y,
+      a
+    ), X(y)), !0;
+  }, o = (c, a) => {
+    const i = r.resolve(c).fullPath;
+    if (f >= 0 && r.currentRoute.value.fullPath === i) {
+      const d = n[f], y = {
+        ...d,
+        id: q("route"),
+        action: "replace",
+        direction: (a == null ? void 0 : a.direction) ?? "root",
+        source: "stack",
+        entryDirection: (a == null ? void 0 : a.direction) ?? "root",
+        delta: void 0,
+        transition: (a == null ? void 0 : a.transition) ?? d.transition,
+        transitionDuration: (a == null ? void 0 : a.duration) ?? d.transitionDuration,
+        transitionEasing: (a == null ? void 0 : a.easing) ?? d.transitionEasing,
+        cache: !0,
+        isStackFallback: !1
+      };
+      return n.splice(0, n.length, y), f = 0, I = !0, u.value = y, Promise.resolve(void 0);
+    }
+    return b(
+      "replace",
+      (a == null ? void 0 : a.direction) ?? "root",
+      void 0,
+      a,
+      !0
+    ), I = !0, L(c);
+  }, h = () => {
+    b("pop", "back", -1), $();
+  }, R = () => {
+    b("pop", "forward", 1), W();
+  }, m = r;
+  m.push = A, m.replace = K, m.popTo = e, m.resetRoot = o, m.back = h, m.forward = R;
+  const _ = {
+    router: m,
+    transitionDuration: l,
+    transitionEasing: T,
+    transition: w,
+    transitions: p,
+    maxStackSize: E,
+    shouldTransition: t.shouldTransition,
+    current: u,
+    get history() {
+      return n;
+    },
+    canGoBack: (c = 1) => f - c >= 0,
+    push: A,
+    replace: K,
+    popTo: e,
+    resetRoot: o,
+    back: h,
+    forward: R
+  }, j = r.install.bind(r);
+  return r.install = (c) => {
+    c.provide(Z, _), j(c);
+  }, m;
+}
+const et = "onPageWillEnter", J = "onPageDidEnter", rt = "onPageWillLeave", ot = "onPageDidLeave";
+function Dt(t, r, n) {
+  if (!n)
+    throw new Error(`${t} must be called inside setup().`);
+  const u = n.proxy, l = u[t] ?? [];
+  l.push(() => {
+    n.isUnmounted || r();
+  }), u[t] = l, n.exposed && (n.exposed[t] = l);
+}
+function G(t) {
+  return (r, n = st()) => Dt(t, r, n);
+}
+const _t = G(et), Ft = G(J), Bt = G(rt), Gt = G(ot);
+function Ct() {
+  const t = F(Z);
+  if (!t)
+    throw new Error("useStackRouter must be used after createStackRouter().");
+  return {
+    router: t.router,
+    canGoBack: t.canGoBack,
+    push: t.push,
+    replace: t.replace,
+    popTo: t.popTo,
+    resetRoot: t.resetRoot,
+    back: t.back,
+    forward: t.forward
+  };
+}
+function nt() {
+  const t = F(Z);
+  if (!t)
+    throw new Error("RouterOutlet must be used with createStackRouter().");
+  return t;
+}
+function S(t, r) {
+  const n = t.value;
+  if (!n) return;
+  const u = n[r];
+  Array.isArray(u) ? u.forEach((l) => l()) : typeof u == "function" && u.call(n);
+}
+function D(t) {
+  t.classList.remove("rs-page-hidden", "rs-page-invisible"), t.removeAttribute("aria-hidden");
+}
+function M(t) {
+  t.classList.add("rs-page-hidden"), t.setAttribute("aria-hidden", "true");
+}
+function at(t) {
+  var r;
+  return (r = t.components) == null ? void 0 : r.default;
+}
+function Tt(t) {
+  const r = at(t);
+  return r !== void 0 && typeof r == "object" && "name" in r && r.name === "RouterView";
+}
+const Ht = Q({
+  name: "RouterOutlet",
+  setup() {
+    const t = nt(), r = mt(), n = F(yt), u = F(v, void 0), l = z(() => {
+      const e = u == null ? void 0 : u.value;
+      if (!e) return 0;
+      const o = r.matched.findIndex(
+        (h) => h === e
+      );
+      return o >= 0 ? o + 1 : 0;
+    }), T = z(() => r.matched[l.value]), w = z(() => {
+      for (let e = l.value; e < r.matched.length; e++) {
+        const o = r.matched[e];
+        if (!Tt(o))
+          return o;
+      }
+      return T.value;
+    }), p = tt([]), E = B("");
+    let f = 0;
+    it(v, w);
+    const s = (e) => p.value.find((o) => o.key === e), I = (e) => {
+      p.value.forEach((o) => {
+        o.pageElement && (o === e ? D(o.pageElement) : M(o.pageElement));
+      });
+    }, b = (e) => {
+      const o = p.value.findIndex((h) => h === e);
+      o >= 0 && (p.value = p.value.slice(0, o + 1));
+    }, C = (e) => {
+      p.value = p.value.filter((o) => o !== e);
+    }, g = (e) => {
+      const o = new Set(
+        t.history.map((h) => h.key)
+      );
+      p.value = p.value.filter(
+        (h) => h === e || h.routeInfo.cache && o.has(h.key)
+      );
+    }, x = (e) => {
+      var h;
+      const o = e.props.default;
+      return o ? o === !0 ? ((h = t.current.value) == null ? void 0 : h.params) ?? {} : typeof o == "function" ? o(n) : o : {};
+    }, H = (e, o) => e.routeInfo.action === "pop" ? o.routeInfo.transition ?? e.routeInfo.transition ?? t.transition : e.routeInfo.transition ?? t.transition, V = (e, o) => !(e.routeInfo.isStackFallback || e.routeInfo.direction === "none" || e.routeInfo.direction === "root" || e.routeInfo.action === "pop" && (o.routeInfo.entryDirection === "none" || o.routeInfo.entryDirection === "root" || o.routeInfo.transition === "none")), L = (e, o) => {
+      var R;
+      const h = V(e, o);
+      return ((R = t.shouldTransition) == null ? void 0 : R.call(t, {
+        action: e.routeInfo.action,
+        direction: e.routeInfo.direction,
+        source: e.routeInfo.source,
+        entering: e.routeInfo,
+        leaving: o.routeInfo,
+        defaultResult: h
+      })) ?? h;
+    }, $ = (e, o) => e.routeInfo.action === "pop" ? o.routeInfo.transitionDuration ?? e.routeInfo.transitionDuration ?? t.transitionDuration : e.routeInfo.transitionDuration ?? t.transitionDuration, W = (e, o) => e.routeInfo.action === "pop" ? o.routeInfo.transitionEasing ?? e.routeInfo.transitionEasing ?? t.transitionEasing : e.routeInfo.transitionEasing ?? t.transitionEasing, X = async (e, o) => {
+      const h = ++f;
+      await ft();
+      const R = e.pageElement;
+      if (!R) return;
+      if (S(e.componentRef, et), !o || o === e || !o.pageElement) {
+        D(R), S(e.componentRef, J), g(e), I(e);
+        return;
+      }
+      const m = o.pageElement, _ = L(e, o), j = _ ? H(e, o) : "none", c = _ ? $(e, o) : 0, a = W(e, o), i = wt(
+        j || Y,
+        t.transitions
+      );
+      S(o.componentRef, rt), D(R), D(m), await It(i, {
+        direction: e.routeInfo.direction,
+        action: e.routeInfo.action,
+        routeInfo: e.routeInfo,
+        enteringElement: R,
+        leavingElement: m,
+        duration: c,
+        easing: a
+      }), h === f && (M(m), S(o.componentRef, ot), S(e.componentRef, J), e.routeInfo.action === "pop" ? b(e) : e.routeInfo.action === "replace" && C(o), g(e), I(e));
+    }, A = async () => {
+      const e = w.value, o = t.current.value;
+      if (!e || !o) return;
+      const h = at(e);
+      if (!h) return;
+      const R = s(E.value);
+      let m = s(o.key);
+      m ? (m.routeInfo = o, m.matchedRoute = e, m.component = h, m.props = x(e), m.mounted = !0) : (m = {
+        id: q("view"),
+        key: o.key,
+        routeInfo: o,
+        matchedRoute: e,
+        component: h,
+        props: x(e),
+        componentRef: B(),
+        mounted: !0
+      }, p.value = [...p.value, m]), E.value = m.key, await X(m, R);
+    };
+    return ut(
+      () => {
+        var e;
+        return [(e = t.current.value) == null ? void 0 : e.id, w.value];
+      },
+      () => {
+        A();
+      },
+      { immediate: !0 }
+    ), lt(() => {
+      f++, p.value = [];
+    }), {
+      injectedRoute: n,
+      viewItems: p,
+      registerStackPage: (e, o) => {
+        e.pageElement = o, e.key === E.value ? D(o) : M(o);
+      }
+    };
+  },
+  render() {
+    return k(
+      "div",
+      { class: "rs-outlet" },
+      this.viewItems.filter((t) => t.mounted).map(
+        (t) => k(t.component, {
+          key: t.id,
+          ref: t.componentRef,
+          ...t.props,
+          registerStackPage: (r) => this.registerStackPage(t, r)
+        })
+      )
+    );
+  }
+}), Vt = Q({
+  name: "RouterPage",
+  props: {
+    registerStackPage: {
+      type: Function,
+      default: void 0
+    }
+  },
+  setup(t, { attrs: r, slots: n }) {
+    const u = B();
+    return dt(() => {
+      var l;
+      u.value && ((l = t.registerStackPage) == null || l.call(t, u.value));
+    }), () => {
+      var l;
+      return k(
+        "section",
+        {
+          ...r,
+          ref: u,
+          class: ["rs-page", r.class]
+        },
+        (l = n.default) == null ? void 0 : l.call(n)
+      );
+    };
+  }
+}), $t = Q({
+  name: "StackRouterDebugPanel",
+  props: {
+    initialOpen: {
+      type: Boolean,
+      default: !1
+    }
+  },
+  setup(t) {
+    const r = nt(), n = B(t.initialOpen);
+    return () => {
+      const u = r.current.value;
+      return k("aside", { class: "rs-debug-panel" }, [
+        k(
+          "button",
+          {
+            class: "rs-debug-toggle",
+            type: "button",
+            onClick: () => {
+              n.value = !n.value;
+            }
+          },
+          n.value ? "Stack x" : "Stack"
+        ),
+        n.value ? k("section", { class: "rs-debug-body" }, [
+          k("header", [
+            k("strong", "Router Stack"),
+            k("span", `${r.history.length} pages`)
+          ]),
+          k("dl", [
+            k("dt", "current"),
+            k("dd", (u == null ? void 0 : u.fullPath) ?? "-"),
+            k("dt", "canGoBack"),
+            k("dd", String(r.canGoBack()))
+          ]),
+          k(
+            "ol",
+            r.history.map(
+              (l) => k(
+                "li",
+                {
+                  key: l.id,
+                  class: {
+                    "rs-debug-active": l.id === (u == null ? void 0 : u.id),
+                    "rs-debug-no-cache": !l.cache
+                  }
+                },
+                [
+                  k("code", l.fullPath),
+                  k("span", [
+                    `${l.action}/${l.direction}`,
+                    ` source:${l.source}`,
+                    ` entry:${l.entryDirection}`,
+                    ` cache:${l.cache ? "yes" : "no"}`,
+                    ` transition:${l.transition ?? "-"}`
+                  ])
+                ]
+              )
+            )
+          )
+        ]) : void 0
+      ]);
+    };
+  }
+});
+export {
+  Kt as RouterLink,
+  Ht as RouterOutlet,
+  Vt as RouterPage,
+  jt as RouterView,
+  $t as StackRouterDebugPanel,
+  zt as createMemoryHistory,
+  At as createStackRouter,
+  Ut as createWebHashHistory,
+  Mt as createWebHistory,
+  Lt as defineStackTransition,
+  Ft as onPageDidEnter,
+  Gt as onPageDidLeave,
+  _t as onPageWillEnter,
+  Bt as onPageWillLeave,
+  Z as stackRouterKey,
+  qt as useRoute,
+  Jt as useRouter,
+  Ct as useStackRouter
+};

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@lazycatcloud/vue-router-stack",
+  "version": "0.0.1",
+  "description": "Page stack, caching, transitions, and lifecycle utilities built on vue-router.",
+  "private": false,
+  "type": "module",
+  "license": "MIT",
+  "main": "./dist/vue-router-stack.cjs",
+  "module": "./dist/vue-router-stack.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/vue-router-stack.js",
+      "require": "./dist/vue-router-stack.cjs"
+    },
+    "./style.css": "./dist/vue-router-stack.css"
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": [
+    "*.css",
+    "**/*.css"
+  ],
+  "keywords": [
+    "vue",
+    "vue-router",
+    "router",
+    "stack",
+    "transition",
+    "keep-alive"
+  ],
+  "scripts": {
+    "dev": "vite --config demo/vite.config.ts --port 2244 --host",
+    "build": "pnpm run type-check && pnpm run build:lib && pnpm run build:demo",
+    "build:lib": "vite build && vue-tsc --declaration --emitDeclarationOnly -p tsconfig.build.json",
+    "build:demo": "vite build --config demo/vite.config.ts",
+    "type-check": "vue-tsc --noEmit -p tsconfig.app.json",
+    "test": "vitest run"
+  },
+  "peerDependencies": {
+    "vue": "^3.3.0",
+    "vue-router": "^4.2.0"
+  },
+  "devDependencies": {
+    "@vitejs/plugin-vue": "^5.2.4",
+    "@vue/test-utils": "^2.4.6",
+    "jsdom": "^25.0.1",
+    "typescript": "^5.8.3",
+    "vite": "^6.3.5",
+    "vitest": "^3.2.4",
+    "vue": "^3.5.16",
+    "vue-router": "^4.5.1",
+    "vue-tsc": "^2.2.10"
+  }
+}