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

package/package.json

@@ -50,19 +50,19 @@
         "vue": "^3.5.0 || ^2.7.0"
     },
     "dependencies": {
-        "@esmx/router": "3.0.0-rc.70"
+        "@esmx/router": "3.0.0-rc.71"
     },
     "devDependencies": {
         "@biomejs/biome": "1.9.4",
-        "@types/node": "^24.0.0",
+        "@types/node": "^24.10.0",
         "@vitest/coverage-v8": "3.2.4",
-        "typescript": "5.9.2",
-        "unbuild": "3.6.0",
+        "typescript": "5.9.3",
+        "unbuild": "3.6.1",
         "vitest": "3.2.4",
-        "vue": "3.5.13",
+        "vue": "3.5.23",
         "vue2": "npm:vue@2.7.16"
     },
-    "version": "3.0.0-rc.70",
+    "version": "3.0.0-rc.71",
     "type": "module",
     "private": false,
     "exports": {
@@ -81,5 +81,5 @@
         "template",
         "public"
     ],
-    "gitHead": "9aa452ae73e450d285e4ddbd35a4ac8b53427d95"
+    "gitHead": "1616c7a1f820387d4d14bac0babd42356f6f7f33"
 }

package/src/index.test.ts

@@ -25,6 +25,16 @@ 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', () => {
@@ -74,6 +84,7 @@ describe('index.ts - Package Entry Point', () => {
                 'useProvideRouter',
                 'useLink',
                 'useRouterViewDepth',
+                'getRouterViewDepth',
                 // Options API
                 'getRouter',
                 'getRoute',
@@ -100,6 +111,7 @@ describe('index.ts - Package Entry Point', () => {
                 'useProvideRouter',
                 'useLink',
                 'useRouterViewDepth',
+                'getRouterViewDepth',
                 'getRouter',
                 'getRoute',
                 'RouterLink',
@@ -121,11 +133,15 @@ describe('index.ts - Package Entry Point', () => {
             // These should throw expected errors when called without proper context
             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({
@@ -133,31 +149,23 @@ describe('index.ts - Package Entry Point', () => {
                     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({} as Record<string, unknown>);
-                } catch (error: unknown) {
-                    // Expected to throw context error when called without router
-                    expect((error as Error).message).toContain(
-                        'Router context not found'
-                    );
-                }
-            }).not.toThrow();
+                RouterVueModule.getRouter({} as Record<string, unknown>);
+            }).toThrow(
+                '[@esmx/router-vue] Router context not found. Please ensure useProvideRouter() is called in a parent component.'
+            );
 
             expect(() => {
-                try {
-                    RouterVueModule.getRoute({} as Record<string, unknown>);
-                } catch (error: unknown) {
-                    // Expected to throw context error when called without router
-                    expect((error as Error).message).toContain(
-                        'Router context not found'
-                    );
-                }
-            }).not.toThrow();
+                RouterVueModule.getRoute({} as Record<string, unknown>);
+            }).toThrow(
+                '[@esmx/router-vue] Router context not found. Please ensure useProvideRouter() is called in a parent component.'
+            );
         });
     });
 
@@ -200,7 +208,7 @@ describe('index.ts - Package Entry Point', () => {
             // Test plugin install signature - should throw for null input
             expect(() => {
                 RouterPlugin.install(null);
-            }).toThrow();
+            }).toThrow('[@esmx/router-vue] Invalid Vue app instance');
         });
     });
 
@@ -221,6 +229,8 @@ describe('index.ts - Package Entry Point', () => {
                 'useRoute',
                 'useProvideRouter',
                 'useLink',
+                'useRouterViewDepth',
+                'getRouterViewDepth',
                 'getRouter',
                 'getRoute'
             ];

package/src/index.ts

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

package/src/plugin.test.ts

@@ -45,7 +45,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('/');
@@ -88,13 +88,13 @@ 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(undefined);
-            }).toThrow();
+            }).toThrow('[@esmx/router-vue] Invalid Vue app instance');
         });
     });
 

package/src/plugin.ts

@@ -71,6 +71,10 @@ export const RouterPlugin = {
      * @param app Vue application instance (Vue 3) or Vue constructor (Vue 2)
      */
     install(app: unknown): void {
+        if (!app) {
+            throw new Error('[@esmx/router-vue] Invalid Vue app instance');
+        }
+
         const vueApp = app as VueApp;
         const target = vueApp.config?.globalProperties || vueApp.prototype;
 

package/src/router-link.test.ts

@@ -52,7 +52,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/')
         });
 
         // Initialize router and wait for it to be ready

package/src/router-view.test.ts

@@ -80,7 +80,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/')
         });
 
         // Initialize router to root path and wait for it to be ready
@@ -201,7 +201,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/')
             });
 
             // Initialize the router and wait for it to be ready
@@ -334,7 +334,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/')
             });
 
             // Initialize the router and wait for it to be ready
@@ -411,7 +411,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/')
             });
 
             // Initialize the router and wait for it to be ready
@@ -451,7 +451,7 @@ describe('router-view.ts - RouterView Component', () => {
                     }
                 ],
                 mode: RouterMode.memory,
-                base: new URL('http://localhost:3000/')
+                base: new URL('http://localhost:8000/')
             });
 
             // Initialize router with root path
@@ -504,7 +504,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/')
             });
 
             // Initialize the router and wait for it to be ready

package/src/use.test.ts

@@ -4,8 +4,15 @@ import { type Route, Router, RouterMode } from '@esmx/router';
  */
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import { nextTick } from 'vue';
-import { createApp, h } from 'vue';
-import { useProvideRouter, useRoute, useRouter } from './use';
+import { createApp, defineComponent, getCurrentInstance, h } from 'vue';
+import { RouterView } from './router-view';
+import {
+    getRouterViewDepth,
+    useProvideRouter,
+    useRoute,
+    useRouter,
+    useRouterViewDepth
+} from './use';
 
 describe('Router Vue Integration', () => {
     let app: ReturnType<typeof createApp>;
@@ -22,7 +29,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/')
         });
 
         // Ensure navigation to initial route is complete
@@ -214,4 +221,259 @@ describe('Router Vue Integration', () => {
             expect(childRoute?.path).toBe('/new-path');
         });
     });
+
+    describe('RouterView Depth', () => {
+        it('should get depth in single RouterView', async () => {
+            let observedDepth: number | undefined;
+
+            const LeafProbe = defineComponent({
+                setup() {
+                    const p = getCurrentInstance()!.proxy as any;
+                    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: number | undefined;
+
+            const LeafProbe = defineComponent({
+                setup() {
+                    const p = getCurrentInstance()!.proxy as any;
+                    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: number | undefined;
+
+            const LeafProbe = defineComponent({
+                setup() {
+                    const p = getCurrentInstance()!.proxy as any;
+                    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: (() => void) | undefined;
+
+            const Probe = defineComponent({
+                setup() {
+                    const p = getCurrentInstance()!.proxy as any;
+                    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);
+        });
+    });
 });

package/src/use.ts

@@ -24,21 +24,19 @@ 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: string) =>
-        `[@esmx/router-vue] ${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.'
-} as const;
-
 const routerContextProperty =
     createSymbolProperty<RouterContext>(ROUTER_CONTEXT_KEY);
 
-function getCurrentProxy(functionName: string): VueInstance {
+const routerViewDepthProperty = createSymbolProperty<number>(
+    ROUTER_VIEW_DEPTH_KEY
+);
+
+function getCurrentProxy(): VueInstance {
     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;
 }
@@ -46,7 +44,7 @@ function getCurrentProxy(functionName: string): VueInstance {
 function findRouterContext(vm?: VueInstance): RouterContext {
     // If no vm provided, try to get current instance
     if (!vm) {
-        vm = getCurrentProxy('findRouterContext');
+        vm = getCurrentProxy();
     }
 
     let context = routerContextProperty.get(vm);
@@ -64,7 +62,9 @@ function findRouterContext(vm?: VueInstance): RouterContext {
         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.'
+    );
 }
 
 /**
@@ -143,7 +143,7 @@ export function getRoute(instance?: VueInstance): Route {
  * Get router context using the optimal method available.
  * First tries provide/inject (works in setup), then falls back to hierarchy traversal.
  */
-function useRouterContext(functionName: string): RouterContext {
+function useRouterContext(): RouterContext {
     // First try to get context from provide/inject (works in setup)
     const injectedContext = inject<RouterContext>(ROUTER_INJECT_KEY);
     if (injectedContext) {
@@ -151,7 +151,7 @@ function useRouterContext(functionName: string): RouterContext {
     }
 
     // Fallback to component hierarchy traversal (works after mount)
-    const proxy = getCurrentProxy(functionName);
+    const proxy = getCurrentProxy();
     return findRouterContext(proxy);
 }
 
@@ -188,7 +188,7 @@ function useRouterContext(functionName: string): RouterContext {
  * ```
  */
 export function useRouter(): Router {
-    return useRouterContext('useRouter').router;
+    return useRouterContext().router;
 }
 
 /**
@@ -224,7 +224,7 @@ export function useRouter(): Router {
  * ```
  */
 export function useRoute(): Route {
-    return useRouterContext('useRoute').route;
+    return useRouterContext().route;
 }
 
 /**
@@ -257,7 +257,7 @@ export function useRoute(): Route {
  * ```
  */
 export function useProvideRouter(router: Router): void {
-    const proxy = getCurrentProxy('useProvideRouter');
+    const proxy = getCurrentProxy();
 
     const dep = ref(0);
 
@@ -313,13 +313,12 @@ export function useProvideRouter(router: Router): void {
  * ```
  */
 export function _useRouterViewDepth(isRender?: boolean): number {
-    // Get current RouterView depth from parent RouterView (if any)
-    // Default to 0 if no parent RouterView is found
     const depth = inject(ROUTER_VIEW_DEPTH_KEY, 0);
 
     if (isRender) {
-        // Provide depth + 1 to child RouterView components
         provide(ROUTER_VIEW_DEPTH_KEY, depth + 1);
+        const proxy = getCurrentProxy();
+        routerViewDepthProperty.set(proxy, depth + 1);
     }
 
     return depth;
@@ -354,6 +353,26 @@ export function useRouterViewDepth(): number {
     return _useRouterViewDepth();
 }
 
+/**
+ * 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 function getRouterViewDepth(instance: VueInstance): number {
+    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.'
+    );
+}
+
 /**
  * Create reactive link helpers for navigation elements.
  * Returns computed properties for link attributes, classes, and event handlers.