@esmx/router-vue 3.0.0-rc.69 → 3.0.0-rc.71

package/README.md

@@ -29,7 +29,7 @@
 
 
 
-## Features
+## 🚀 Features
 
 ✨ **Universal Vue Support** - Works with both Vue 2.7+ and Vue 3  
 🎯 **Composition API First** - Built for modern Vue development  
@@ -38,13 +38,20 @@
 ⚡ **High Performance** - Optimized for production use  
 🔄 **SSR Compatible** - Server-side rendering support  
 
-## Installation
+## 📦 Installation
 
 ```bash
+# npm
 npm install @esmx/router @esmx/router-vue
+
+# pnpm
+pnpm add @esmx/router @esmx/router-vue
+
+# yarn
+yarn add @esmx/router @esmx/router-vue
 ```
 
-## Quick Start
+## 🚀 Quick Start
 
 ### Vue 3
 
@@ -189,7 +196,7 @@ export default defineComponent({
 </script>
 ```
 
-## API Reference
+## 📚 API Reference
 
 ### Components
 
@@ -553,11 +560,11 @@ app.use(RouterPlugin);
 
 We welcome contributions! Please feel free to submit issues and pull requests.
 
-## License
+## 📄 License
 
 MIT © [Esmx Team](https://github.com/esmnext/esmx)
 
 ## Related Packages
 
 - [@esmx/router](https://github.com/esmnext/esmx/tree/master/packages/router) - Core router package
-- [@esmx/core](https://github.com/esmnext/esmx/tree/master/packages/core) - Esmx core framework 
+- [@esmx/core](https://github.com/esmnext/esmx/tree/master/packages/core) - Esmx core framework 

package/README.zh-CN.md

@@ -29,7 +29,7 @@
 
 
 
-## 特性
+## 🚀 特性
 
 ✨ **通用 Vue 支持** - 同时支持 Vue 2.7+ 和 Vue 3  
 🎯 **组合式 API 优先** - 为现代 Vue 开发而构建  
@@ -38,13 +38,20 @@
 ⚡ **高性能** - 为生产环境优化  
 🔄 **SSR 兼容** - 支持服务端渲染  
 
-## 安装
+## 📦 安装
 
 ```bash
+# npm
 npm install @esmx/router @esmx/router-vue
+
+# pnpm
+pnpm add @esmx/router @esmx/router-vue
+
+# yarn
+yarn add @esmx/router @esmx/router-vue
 ```
 
-## 快速开始
+## 🚀 快速开始
 
 ### Vue 3
 
@@ -189,7 +196,7 @@ export default defineComponent({
 </script>
 ```
 
-## API 参考
+## 📚 API 参考
 
 ### 组件
 
@@ -553,7 +560,7 @@ app.use(RouterPlugin);
 
 我们欢迎贡献！请随时提交 issues 和 pull requests。
 
-## 许可证
+## 📄 许可证
 
 MIT © [Esmx 团队](https://github.com/esmnext/esmx)
 

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 export type * from './vue2';
 export type * from './vue3';
-export { useRouter, useRoute, useProvideRouter, useLink, useRouterViewDepth, getRoute, getRouter } from './use';
+export { useRouter, useRoute, useProvideRouter, useLink, useRouterViewDepth, getRouterViewDepth, getRoute, getRouter } from './use';
 export { RouterLink } from './router-link';
 export { RouterView } from './router-view';
 export { RouterPlugin } from './plugin';

package/dist/index.mjs

@@ -4,6 +4,7 @@ export {
   useProvideRouter,
   useLink,
   useRouterViewDepth,
+  getRouterViewDepth,
   getRoute,
   getRouter
 } from "./use.mjs";

package/dist/index.test.mjs

@@ -18,6 +18,14 @@ describe("index.ts - Package Entry Point", () => {
       expect(RouterVueModule.useLink).toBeDefined();
       expect(typeof RouterVueModule.useLink).toBe("function");
     });
+    it("should export useRouterViewDepth function", () => {
+      expect(RouterVueModule.useRouterViewDepth).toBeDefined();
+      expect(typeof RouterVueModule.useRouterViewDepth).toBe("function");
+    });
+    it("should export getRouterViewDepth function", () => {
+      expect(RouterVueModule.getRouterViewDepth).toBeDefined();
+      expect(typeof RouterVueModule.getRouterViewDepth).toBe("function");
+    });
   });
   describe("Options API Exports", () => {
     it("should export getRouter function", () => {
@@ -61,6 +69,7 @@ describe("index.ts - Package Entry Point", () => {
         "useProvideRouter",
         "useLink",
         "useRouterViewDepth",
+        "getRouterViewDepth",
         // Options API
         "getRouter",
         "getRoute",
@@ -85,6 +94,7 @@ describe("index.ts - Package Entry Point", () => {
         "useProvideRouter",
         "useLink",
         "useRouterViewDepth",
+        "getRouterViewDepth",
         "getRouter",
         "getRoute",
         "RouterLink",
@@ -101,37 +111,35 @@ describe("index.ts - Package Entry Point", () => {
     it("should have correct function signatures for Composition API", () => {
       expect(() => {
         RouterVueModule.useRouter();
-      }).toThrow("useRouter() can only be called during setup()");
+      }).toThrow(
+        "[@esmx/router-vue] Must be used within setup() or other composition functions"
+      );
       expect(() => {
         RouterVueModule.useRoute();
-      }).toThrow("useRoute() can only be called during setup()");
+      }).toThrow(
+        "[@esmx/router-vue] Must be used within setup() or other composition functions"
+      );
       expect(() => {
         RouterVueModule.useLink({
           to: "/test",
           type: "push",
           exact: "include"
         });
-      }).toThrow("useRouter() can only be called during setup()");
+      }).toThrow(
+        "[@esmx/router-vue] Must be used within setup() or other composition functions"
+      );
     });
     it("should have correct function signatures for Options API", () => {
       expect(() => {
-        try {
-          RouterVueModule.getRouter({});
-        } catch (error) {
-          expect(error.message).toContain(
-            "Router context not found"
-          );
-        }
-      }).not.toThrow();
+        RouterVueModule.getRouter({});
+      }).toThrow(
+        "[@esmx/router-vue] Router context not found. Please ensure useProvideRouter() is called in a parent component."
+      );
       expect(() => {
-        try {
-          RouterVueModule.getRoute({});
-        } catch (error) {
-          expect(error.message).toContain(
-            "Router context not found"
-          );
-        }
-      }).not.toThrow();
+        RouterVueModule.getRoute({});
+      }).toThrow(
+        "[@esmx/router-vue] Router context not found. Please ensure useProvideRouter() is called in a parent component."
+      );
     });
   });
   describe("Component Properties", () => {
@@ -161,7 +169,7 @@ describe("index.ts - Package Entry Point", () => {
       expect(typeof RouterPlugin.install).toBe("function");
       expect(() => {
         RouterPlugin.install(null);
-      }).toThrow();
+      }).toThrow("[@esmx/router-vue] Invalid Vue app instance");
     });
   });
   describe("Module Structure", () => {
@@ -176,6 +184,8 @@ describe("index.ts - Package Entry Point", () => {
         "useRoute",
         "useProvideRouter",
         "useLink",
+        "useRouterViewDepth",
+        "getRouterViewDepth",
         "getRouter",
         "getRoute"
       ];

package/dist/plugin.mjs

@@ -9,6 +9,9 @@ export const RouterPlugin = {
    */
   install(app) {
     var _a;
+    if (!app) {
+      throw new Error("[@esmx/router-vue] Invalid Vue app instance");
+    }
     const vueApp = app;
     const target = ((_a = vueApp.config) == null ? void 0 : _a.globalProperties) || vueApp.prototype;
     if (!target) {

package/dist/plugin.test.mjs

@@ -34,7 +34,7 @@ describe("plugin.ts - RouterPlugin", () => {
     router = new Router({
       mode: RouterMode.memory,
       routes,
-      base: new URL("http://localhost:3000/")
+      base: new URL("http://localhost:8000/")
     });
     await router.replace("/");
     await nextTick();
@@ -71,12 +71,12 @@ describe("plugin.ts - RouterPlugin", () => {
     it("should throw error for null app instance", () => {
       expect(() => {
         RouterPlugin.install(null);
-      }).toThrow();
+      }).toThrow("[@esmx/router-vue] Invalid Vue app instance");
     });
     it("should throw error for undefined app instance", () => {
       expect(() => {
         RouterPlugin.install(void 0);
-      }).toThrow();
+      }).toThrow("[@esmx/router-vue] Invalid Vue app instance");
     });
   });
   describe("Global Properties Injection", () => {

package/dist/router-link.test.mjs

@@ -41,7 +41,7 @@ describe("router-link.ts - RouterLink Component", () => {
       root: "#test-app",
       routes,
       mode: RouterMode.memory,
-      base: new URL("http://localhost:3000/")
+      base: new URL("http://localhost:8000/")
     });
     await router.replace("/");
     await nextTick();

package/dist/router-view.test.mjs

@@ -63,7 +63,7 @@ describe("router-view.ts - RouterView Component", () => {
       root: "#test-app",
       routes,
       mode: RouterMode.memory,
-      base: new URL("http://localhost:3000/")
+      base: new URL("http://localhost:8000/")
     });
     await router.replace("/");
     await new Promise((resolve) => setTimeout(resolve, 10));
@@ -149,7 +149,7 @@ describe("router-view.ts - RouterView Component", () => {
         root: "#test-app",
         routes,
         mode: RouterMode.memory,
-        base: new URL("http://localhost:3000/")
+        base: new URL("http://localhost:8000/")
       });
       await functionRouter.replace("/function");
       await new Promise((resolve) => setTimeout(resolve, 10));
@@ -251,7 +251,7 @@ describe("router-view.ts - RouterView Component", () => {
         root: "#test-app",
         routes: nestedRoutes,
         mode: RouterMode.memory,
-        base: new URL("http://localhost:3000/")
+        base: new URL("http://localhost:8000/")
       });
       await nestedRouter.replace("/level1/level2");
       await new Promise((resolve) => setTimeout(resolve, 10));
@@ -313,7 +313,7 @@ describe("router-view.ts - RouterView Component", () => {
         root: "#test-app",
         routes: routesWithNull,
         mode: RouterMode.memory,
-        base: new URL("http://localhost:3000/")
+        base: new URL("http://localhost:8000/")
       });
       await nullRouter.replace("/null-component");
       await new Promise((resolve) => setTimeout(resolve, 10));
@@ -346,7 +346,7 @@ describe("router-view.ts - RouterView Component", () => {
           }
         ],
         mode: RouterMode.memory,
-        base: new URL("http://localhost:3000/")
+        base: new URL("http://localhost:8000/")
       });
       await nonExistentRouter.replace("/");
       await new Promise((resolve) => setTimeout(resolve, 10));
@@ -385,7 +385,7 @@ describe("router-view.ts - RouterView Component", () => {
         root: "#test-app",
         routes: malformedRoutes,
         mode: RouterMode.memory,
-        base: new URL("http://localhost:3000/")
+        base: new URL("http://localhost:8000/")
       });
       await malformedRouter.replace("/malformed");
       await new Promise((resolve) => setTimeout(resolve, 10));

package/dist/use.d.ts

@@ -224,6 +224,15 @@ export declare function _useRouterViewDepth(isRender?: boolean): number;
  * ```
  */
 export declare function useRouterViewDepth(): number;
+/**
+ * Get injected RouterView depth from a Vue instance's ancestors.
+ * Traverses parent chain to find the value provided under ROUTER_VIEW_DEPTH_KEY.
+ *
+ * @param instance - Vue component instance to start from
+ * @returns Injected RouterView depth value from nearest ancestor
+ * @throws {Error} If no ancestor provided ROUTER_VIEW_DEPTH_KEY
+ */
+export declare function getRouterViewDepth(instance: VueInstance): number;
 /**
  * Create reactive link helpers for navigation elements.
  * Returns computed properties for link attributes, classes, and event handlers.

package/dist/use.mjs

@@ -10,21 +10,22 @@ import { createDependentProxy, createSymbolProperty } from "./util.mjs";
 const ROUTER_CONTEXT_KEY = Symbol("router-context");
 const ROUTER_INJECT_KEY = Symbol("router-inject");
 const ROUTER_VIEW_DEPTH_KEY = Symbol("router-view-depth");
-const ERROR_MESSAGES = {
-  SETUP_ONLY: (fnName) => "[@esmx/router-vue] ".concat(fnName, "() can only be called during setup()"),
-  CONTEXT_NOT_FOUND: "[@esmx/router-vue] Router context not found. Please ensure useProvideRouter() is called in a parent component."
-};
 const routerContextProperty = createSymbolProperty(ROUTER_CONTEXT_KEY);
-function getCurrentProxy(functionName) {
+const routerViewDepthProperty = createSymbolProperty(
+  ROUTER_VIEW_DEPTH_KEY
+);
+function getCurrentProxy() {
   const instance = getCurrentInstance();
   if (!instance || !instance.proxy) {
-    throw new Error(ERROR_MESSAGES.SETUP_ONLY(functionName));
+    throw new Error(
+      "[@esmx/router-vue] Must be used within setup() or other composition functions"
+    );
   }
   return instance.proxy;
 }
 function findRouterContext(vm) {
   if (!vm) {
-    vm = getCurrentProxy("findRouterContext");
+    vm = getCurrentProxy();
   }
   let context = routerContextProperty.get(vm);
   if (context) {
@@ -39,7 +40,9 @@ function findRouterContext(vm) {
     }
     current = current.$parent;
   }
-  throw new Error(ERROR_MESSAGES.CONTEXT_NOT_FOUND);
+  throw new Error(
+    "[@esmx/router-vue] Router context not found. Please ensure useProvideRouter() is called in a parent component."
+  );
 }
 export function getRouter(instance) {
   return findRouterContext(instance).router;
@@ -47,22 +50,22 @@ export function getRouter(instance) {
 export function getRoute(instance) {
   return findRouterContext(instance).route;
 }
-function useRouterContext(functionName) {
+function useRouterContext() {
   const injectedContext = inject(ROUTER_INJECT_KEY);
   if (injectedContext) {
     return injectedContext;
   }
-  const proxy = getCurrentProxy(functionName);
+  const proxy = getCurrentProxy();
   return findRouterContext(proxy);
 }
 export function useRouter() {
-  return useRouterContext("useRouter").router;
+  return useRouterContext().router;
 }
 export function useRoute() {
-  return useRouterContext("useRoute").route;
+  return useRouterContext().route;
 }
 export function useProvideRouter(router) {
-  const proxy = getCurrentProxy("useProvideRouter");
+  const proxy = getCurrentProxy();
   const dep = ref(0);
   const proxiedRouter = createDependentProxy(router, dep);
   const proxiedRoute = createDependentProxy(router.route, dep);
@@ -84,12 +87,25 @@ export function _useRouterViewDepth(isRender) {
   const depth = inject(ROUTER_VIEW_DEPTH_KEY, 0);
   if (isRender) {
     provide(ROUTER_VIEW_DEPTH_KEY, depth + 1);
+    const proxy = getCurrentProxy();
+    routerViewDepthProperty.set(proxy, depth + 1);
   }
   return depth;
 }
 export function useRouterViewDepth() {
   return _useRouterViewDepth();
 }
+export function getRouterViewDepth(instance) {
+  let current = instance.$parent;
+  while (current) {
+    const value = routerViewDepthProperty.get(current);
+    if (typeof value === "number") return value;
+    current = current.$parent;
+  }
+  throw new Error(
+    "[@esmx/router-vue] RouterView depth not found. Please ensure a RouterView exists in ancestor components."
+  );
+}
 export function useLink(props) {
   const router = useRouter();
   return computed(() => {

package/dist/use.test.mjs

@@ -1,8 +1,15 @@
 import { Router, RouterMode } from "@esmx/router";
 import { afterEach, beforeEach, describe, expect, it } from "vitest";
 import { nextTick } from "vue";
-import { createApp, h } from "vue";
-import { useProvideRouter, useRoute, useRouter } from "./use.mjs";
+import { createApp, defineComponent, getCurrentInstance, h } from "vue";
+import { RouterView } from "./router-view.mjs";
+import {
+  getRouterViewDepth,
+  useProvideRouter,
+  useRoute,
+  useRouter,
+  useRouterViewDepth
+} from "./use.mjs";
 describe("Router Vue Integration", () => {
   let app;
   let router;
@@ -16,7 +23,7 @@ describe("Router Vue Integration", () => {
         { path: "/user/:id", component: {} },
         { path: "/new-path", component: {} }
       ],
-      base: new URL("http://localhost:3000/")
+      base: new URL("http://localhost:8000/")
     });
     await router.replace("/initial");
     mountPoint = document.createElement("div");
@@ -156,4 +163,214 @@ describe("Router Vue Integration", () => {
       expect(childRoute == null ? void 0 : childRoute.path).toBe("/new-path");
     });
   });
+  describe("RouterView Depth", () => {
+    it("should get depth in single RouterView", async () => {
+      let observedDepth;
+      const LeafProbe = defineComponent({
+        setup() {
+          const p = getCurrentInstance().proxy;
+          observedDepth = getRouterViewDepth(p);
+          return () => h("div");
+        }
+      });
+      const Level1 = defineComponent({
+        setup() {
+          return () => h("div", [h(LeafProbe)]);
+        }
+      });
+      router = new Router({
+        mode: RouterMode.memory,
+        routes: [{ path: "/level1", component: Level1 }],
+        base: new URL("http://localhost:8000/")
+      });
+      await router.replace("/level1");
+      const TestApp = defineComponent({
+        setup() {
+          useProvideRouter(router);
+          return () => h("div", [h(RouterView)]);
+        }
+      });
+      app = createApp(TestApp);
+      app.mount("#app");
+      await nextTick();
+      expect(observedDepth).toBe(1);
+    });
+    it("should get depth in nested RouterView", async () => {
+      let observedDepth;
+      const LeafProbe = defineComponent({
+        setup() {
+          const p = getCurrentInstance().proxy;
+          observedDepth = getRouterViewDepth(p);
+          return () => h("div");
+        }
+      });
+      const Level1 = defineComponent({
+        setup() {
+          return () => h("div", [h(RouterView)]);
+        }
+      });
+      const Leaf = defineComponent({
+        setup() {
+          return () => h("div", [h(LeafProbe)]);
+        }
+      });
+      router = new Router({
+        mode: RouterMode.memory,
+        routes: [
+          {
+            path: "/level1",
+            component: Level1,
+            children: [{ path: "leaf", component: Leaf }]
+          }
+        ],
+        base: new URL("http://localhost:8000/")
+      });
+      await router.replace("/level1/leaf");
+      const TestApp = defineComponent({
+        setup() {
+          useProvideRouter(router);
+          return () => h("div", [h(RouterView)]);
+        }
+      });
+      app = createApp(TestApp);
+      app.mount("#app");
+      await nextTick();
+      expect(observedDepth).toBe(2);
+    });
+    it("should get depth in double-nested RouterViews", async () => {
+      let observedDepth;
+      const LeafProbe = defineComponent({
+        setup() {
+          const p = getCurrentInstance().proxy;
+          observedDepth = getRouterViewDepth(p);
+          return () => h("div");
+        }
+      });
+      const Level1 = defineComponent({
+        setup() {
+          return () => h("div", [h(RouterView)]);
+        }
+      });
+      const Level2 = defineComponent({
+        setup() {
+          return () => h("div", [h(RouterView)]);
+        }
+      });
+      const Leaf = defineComponent({
+        setup() {
+          return () => h("div", [h(LeafProbe)]);
+        }
+      });
+      router = new Router({
+        mode: RouterMode.memory,
+        routes: [
+          {
+            path: "/level1",
+            component: Level1,
+            children: [
+              {
+                path: "level2",
+                component: Level2,
+                children: [{ path: "leaf", component: Leaf }]
+              }
+            ]
+          }
+        ],
+        base: new URL("http://localhost:8000/")
+      });
+      await router.replace("/level1/level2/leaf");
+      const TestApp = defineComponent({
+        setup() {
+          useProvideRouter(router);
+          return () => h("div", [h(RouterView)]);
+        }
+      });
+      app = createApp(TestApp);
+      app.mount("#app");
+      await nextTick();
+      expect(observedDepth).toBe(3);
+    });
+    it("should throw when no RouterView ancestor exists", async () => {
+      let callDepth;
+      const Probe = defineComponent({
+        setup() {
+          const p = getCurrentInstance().proxy;
+          callDepth = () => getRouterViewDepth(p);
+          return () => h("div");
+        }
+      });
+      const TestApp = defineComponent({
+        setup() {
+          useProvideRouter(router);
+          return () => h(Probe);
+        }
+      });
+      app = createApp(TestApp);
+      app.mount("#app");
+      await nextTick();
+      expect(() => callDepth()).toThrow(
+        new Error(
+          "[@esmx/router-vue] RouterView depth not found. Please ensure a RouterView exists in ancestor components."
+        )
+      );
+    });
+    it("should return 0 for useRouterViewDepth without RouterView", async () => {
+      let observed = -1;
+      const Probe = defineComponent({
+        setup() {
+          observed = useRouterViewDepth();
+          return () => h("div");
+        }
+      });
+      const TestApp = defineComponent({
+        setup() {
+          useProvideRouter(router);
+          return () => h(Probe);
+        }
+      });
+      app = createApp(TestApp);
+      app.mount("#app");
+      await nextTick();
+      expect(observed).toBe(0);
+    });
+    it("should reflect depth via useRouterViewDepth at each level", async () => {
+      let level1Depth = -1;
+      let level2Depth = -1;
+      const Level2 = defineComponent({
+        setup() {
+          level2Depth = useRouterViewDepth();
+          return () => h("div");
+        }
+      });
+      const Level1 = defineComponent({
+        setup() {
+          level1Depth = useRouterViewDepth();
+          return () => h("div", [h(RouterView)]);
+        }
+      });
+      router = new Router({
+        mode: RouterMode.memory,
+        routes: [
+          {
+            path: "/level1",
+            component: Level1,
+            children: [{ path: "level2", component: Level2 }]
+          }
+        ],
+        base: new URL("http://localhost:8000/")
+      });
+      await router.replace("/level1/level2");
+      const TestApp = defineComponent({
+        setup() {
+          useProvideRouter(router);
+          return () => h("div", [h(RouterView)]);
+        }
+      });
+      app = createApp(TestApp);
+      app.mount("#app");
+      await nextTick();
+      expect(level1Depth).toBe(1);
+      expect(level2Depth).toBe(2);
+    });
+  });
 });