@real-router/vue 0.4.1 → 0.5.1

package/src/composables/useRouterTransition.ts

@@ -1,4 +1,4 @@
-import { createTransitionSource } from "@real-router/sources";
+import { getTransitionSource } from "@real-router/sources";
 
 import { useRefFromSource } from "../useRefFromSource";
 import { useRouter } from "./useRouter";
@@ -8,8 +8,7 @@ import type { ShallowRef } from "vue";
 
 export function useRouterTransition(): ShallowRef<RouterTransitionSnapshot> {
   const router = useRouter();
-
-  const source = createTransitionSource(router);
+  const source = getTransitionSource(router);
 
   return useRefFromSource(source);
 }

package/src/createRouterPlugin.ts

@@ -1,32 +1,27 @@
-import { getNavigator } from "@real-router/core";
-import { createRouteSource } from "@real-router/sources";
-import { shallowRef } from "vue";
-
 import { NavigatorKey, RouteKey, RouterKey } from "./context";
-import { setDirectiveRouter } from "./directives/vLink";
+import { pushDirectiveRouter } from "./directives/vLink";
+import { setupRouteProvision } from "./setupRouteProvision";
 
 import type { Router } from "@real-router/core";
-import type { Plugin } from "vue";
+import type { App, Plugin } from "vue";
 
 export function createRouterPlugin(router: Router): Plugin<[]> {
   return {
     install(app): void {
-      const navigator = getNavigator(router);
-
-      setDirectiveRouter(router);
-
-      const source = createRouteSource(router);
-      const initialSnapshot = source.getSnapshot();
-
-      const route = shallowRef(initialSnapshot.route);
-      const previousRoute = shallowRef(initialSnapshot.previousRoute);
-
-      source.subscribe(() => {
-        const snapshot = source.getSnapshot();
-
-        route.value = snapshot.route;
-        previousRoute.value = snapshot.previousRoute;
-      });
+      const releaseDirective = pushDirectiveRouter(router);
+
+      const { navigator, route, previousRoute, unsubscribe } =
+        setupRouteProvision(router);
+
+      // Vue 3.5+ exposes app.onUnmount for plugin cleanup.
+      // On older versions (3.3–3.4), the subscription is cleaned up
+      // when the router is garbage-collected (same as vue-router).
+      if ("onUnmount" in app) {
+        (app as App & { onUnmount: (fn: () => void) => void }).onUnmount(() => {
+          releaseDirective();
+          unsubscribe();
+        });
+      }
 
       app.provide(RouterKey, router);
       app.provide(NavigatorKey, navigator);

package/src/directives/vLink.ts

@@ -9,28 +9,100 @@ export interface LinkDirectiveValue {
   options?: NavigationOptions;
 }
 
-let _router: Router | null = null;
+/**
+ * Router stack for nested RouterProviders. The active router is the top of
+ * the stack. RouterProvider pushes its router on mount and pops it on unmount,
+ * which preserves the parent context when an inner provider tears down.
+ *
+ * Without the stack, an unmounted child provider would leave the directive
+ * pointing at a disposed router, and v-link in the still-mounted parent would
+ * navigate via the wrong (or torn-down) instance.
+ */
+const routerStack: Router[] = [];
+
+/**
+ * Pushes a router onto the active stack. Returns a release function that
+ * removes that exact router from the stack regardless of position — safe
+ * across out-of-order provider unmount sequences.
+ *
+ * @internal Used by RouterProvider during setup/teardown.
+ */
+export function pushDirectiveRouter(router: Router): () => void {
+  routerStack.push(router);
+
+  return () => {
+    const idx = routerStack.lastIndexOf(router);
+
+    if (idx !== -1) {
+      routerStack.splice(idx, 1);
+    }
+  };
+}
+
+/**
+ * Backwards-compatible alias. Replaces the active router unconditionally and
+ * does NOT participate in the stack — use {@link pushDirectiveRouter} from
+ * provider code instead. Kept for tests and direct callers.
+ */
+export function setDirectiveRouter(router: Router | null): void {
+  if (router === null) {
+    routerStack.length = 0;
+
+    return;
+  }
+  if (routerStack.length === 0) {
+    routerStack.push(router);
+
+    return;
+  }
 
-export function setDirectiveRouter(router: Router): void {
-  _router = router;
+  routerStack[routerStack.length - 1] = router;
 }
 
 export function getDirectiveRouter(): Router {
-  if (!_router) {
-    /* v8 ignore next 3 -- @preserve Defensive: router always initialized by RouterProvider */
+  const top = routerStack.at(-1);
+
+  if (!top) {
     throw new Error(
       "v-link directive requires a RouterProvider ancestor. Make sure RouterProvider is mounted.",
     );
   }
 
-  return _router;
+  return top;
+}
+
+interface Handlers {
+  click: (evt: MouseEvent) => void;
+  keydown: (evt: KeyboardEvent) => void;
 }
 
-const clickHandlers = new WeakMap<HTMLElement, (evt: MouseEvent) => void>();
-const keydownHandlers = new WeakMap<
-  HTMLElement,
-  (evt: KeyboardEvent) => void
->();
+// Single WeakMap halves per-element bookkeeping vs two parallel maps.
+const handlers = new WeakMap<HTMLElement, Handlers>();
+
+/**
+ * Validates a directive binding value before attaching handlers.
+ * Returns false (and warns once per call) when the value is missing or
+ * has no `name` — silently doing nothing is preferable to a runtime crash
+ * inside a click handler.
+ */
+function isValidBinding(value: unknown): value is LinkDirectiveValue {
+  if (value === null || value === undefined) {
+    console.error(
+      "[real-router] v-link directive received null/undefined value. The element will not be wired for navigation.",
+    );
+
+    return false;
+  }
+  if (typeof (value as { name?: unknown }).name !== "string") {
+    console.error(
+      "[real-router] v-link directive value is missing a string `name` field. The element will not be wired for navigation.",
+    );
+
+    return false;
+  }
+
+  return true;
+}
 
 function createClickHandler(
   router: Router,
@@ -67,29 +139,23 @@ function attachHandlers(
   router: Router,
   value: LinkDirectiveValue,
 ): void {
-  const handleClick = createClickHandler(router, value);
-  const handleKeyDown = createKeydownHandler(router, value, element);
+  const click = createClickHandler(router, value);
+  const keydown = createKeydownHandler(router, value, element);
 
-  element.addEventListener("click", handleClick);
-  element.addEventListener("keydown", handleKeyDown);
+  element.addEventListener("click", click);
+  element.addEventListener("keydown", keydown);
 
-  clickHandlers.set(element, handleClick);
-  keydownHandlers.set(element, handleKeyDown);
+  handlers.set(element, { click, keydown });
 }
 
 function detachHandlers(element: HTMLElement): void {
-  const clickHandler = clickHandlers.get(element);
-  const keydownHandler = keydownHandlers.get(element);
+  const entry = handlers.get(element);
 
-  if (clickHandler) {
-    element.removeEventListener("click", clickHandler);
-  }
-  if (keydownHandler) {
-    element.removeEventListener("keydown", keydownHandler);
+  if (entry) {
+    element.removeEventListener("click", entry.click);
+    element.removeEventListener("keydown", entry.keydown);
+    handlers.delete(element);
   }
-
-  clickHandlers.delete(element);
-  keydownHandlers.delete(element);
 }
 
 export const vLink: Directive<HTMLElement, LinkDirectiveValue> = {
@@ -100,6 +166,10 @@ export const vLink: Directive<HTMLElement, LinkDirectiveValue> = {
 
     element.style.cursor = "pointer";
 
+    if (!isValidBinding(binding.value)) {
+      return;
+    }
+
     attachHandlers(element, router, binding.value);
   },
 
@@ -107,6 +177,11 @@ export const vLink: Directive<HTMLElement, LinkDirectiveValue> = {
     const router = getDirectiveRouter();
 
     detachHandlers(element);
+
+    if (!isValidBinding(binding.value)) {
+      return;
+    }
+
     attachHandlers(element, router, binding.value);
   },
 

package/src/setupRouteProvision.ts

@@ -0,0 +1,42 @@
+// packages/vue/src/setupRouteProvision.ts
+
+import { getNavigator } from "@real-router/core";
+import { createRouteSource } from "@real-router/sources";
+import { shallowRef } from "vue";
+
+import type { Router, Navigator, State } from "@real-router/core";
+import type { ShallowRef } from "vue";
+
+/**
+ * Shared setup for `RouterProvider` (component-scoped) and
+ * `createRouterPlugin` (app-scoped). Builds the reactive route refs +
+ * subscription bookkeeping in one place; callers wire the result into their
+ * provide/inject mechanism and own teardown lifecycle.
+ *
+ * @internal
+ */
+export interface RouteProvision {
+  navigator: Navigator;
+  route: ShallowRef<State | undefined>;
+  previousRoute: ShallowRef<State | undefined>;
+  /** Call when the owning scope tears down to release the router subscription. */
+  unsubscribe: () => void;
+}
+
+export function setupRouteProvision(router: Router): RouteProvision {
+  const navigator = getNavigator(router);
+  const source = createRouteSource(router);
+  const initial = source.getSnapshot();
+
+  const route = shallowRef<State | undefined>(initial.route);
+  const previousRoute = shallowRef<State | undefined>(initial.previousRoute);
+
+  const unsubscribe = source.subscribe(() => {
+    const snapshot = source.getSnapshot();
+
+    route.value = snapshot.route;
+    previousRoute.value = snapshot.previousRoute;
+  });
+
+  return { navigator, route, previousRoute, unsubscribe };
+}

package/src/types.ts

@@ -4,12 +4,18 @@ import type {
   Navigator,
   State,
 } from "@real-router/core";
-import type { ShallowRef } from "vue";
+import type { Ref } from "vue";
 
+/**
+ * `route`/`previousRoute` are read-only reactive references. They may be
+ * implemented as `shallowRef` or `computed` depending on the composable
+ * (`useRoute` mirrors via `shallowRef`, `useRouteNode` derives via `computed`),
+ * but consumers only need `.value` read access — typed as `Readonly<Ref<…>>`.
+ */
 export interface RouteContext {
   navigator: Navigator;
-  route: ShallowRef<State | undefined>;
-  previousRoute: ShallowRef<State | undefined>;
+  route: Readonly<Ref<State | undefined>>;
+  previousRoute: Readonly<Ref<State | undefined>>;
 }
 
 export interface LinkProps<P extends Params = Params> {

package/src/composables/useRouterError.ts

@@ -1,23 +0,0 @@
-import { createErrorSource } from "@real-router/sources";
-
-import { useRefFromSource } from "../useRefFromSource";
-import { useRouter } from "./useRouter";
-
-import type { Router } from "@real-router/core";
-import type { RouterErrorSnapshot, RouterSource } from "@real-router/sources";
-import type { ShallowRef } from "vue";
-
-const cache = new WeakMap<Router, RouterSource<RouterErrorSnapshot>>();
-
-export function useRouterError(): ShallowRef<RouterErrorSnapshot> {
-  const router = useRouter();
-
-  let source = cache.get(router);
-
-  if (!source) {
-    source = createErrorSource(router);
-    cache.set(router, source);
-  }
-
-  return useRefFromSource(source);
-}