@real-router/vue 0.15.1 → 0.15.3

package/src/composables/useIsActiveRoute.ts

@@ -1,61 +0,0 @@
-import { createActiveRouteSource } from "@real-router/sources";
-
-import { useRefFromSource } from "../useRefFromSource";
-import { useRouter } from "./useRouter";
-
-import type { Params } from "@real-router/core";
-import type { ShallowRef } from "vue";
-
-/**
- * Options object for `useIsActiveRoute`. Replaces the previous trailing
- * positional booleans (`strict`, `ignoreQueryParams`) — positional flags at
- * call sites read as magic numbers and the order was easy to swap silently.
- *
- * The composable is `@internal` (consumed by `<Link>` and tests only), so
- * the signature changes without a deprecation cycle.
- */
-export interface UseIsActiveRouteOptions {
-  /**
-   * Match the route name exactly (no descendant match). Default: `false`.
-   */
-  strict?: boolean;
-  /**
-   * Ignore query params when comparing the active route. Default: `true`.
-   */
-  ignoreQueryParams?: boolean;
-  /**
-   * Hash-aware active state (#532) — when provided, the route is active only
-   * if `state.context.url.hash` equals this value. Default: `undefined`
-   * (hash is ignored).
-   */
-  hash?: string;
-}
-
-/**
- * @internal Consumed by `<Link>` via `createActiveRouteSource`. Not exported
- * from `@real-router/vue`.
- */
-export function useIsActiveRoute(
-  routeName: string,
-  params?: Params,
-  options?: UseIsActiveRouteOptions,
-): ShallowRef<boolean> {
-  const router = useRouter();
-  const strict = options?.strict ?? false;
-  const ignoreQueryParams = options?.ignoreQueryParams ?? true;
-  const hash = options?.hash;
-
-  // The `hash` argument (#532) participates in the cache key when defined.
-  // exactOptionalPropertyTypes forbids `{ hash: undefined }` literally — we
-  // conditionally include the key only when a value is provided.
-  const source = createActiveRouteSource(
-    router,
-    routeName,
-    params,
-    hash === undefined
-      ? { strict, ignoreQueryParams }
-      : { strict, ignoreQueryParams, hash },
-  );
-
-  return useRefFromSource(source);
-}

package/src/composables/useNavigator.ts

@@ -1,15 +0,0 @@
-import { inject } from "vue";
-
-import { NavigatorKey } from "../context";
-
-import type { Navigator } from "@real-router/core";
-
-export const useNavigator = (): Navigator => {
-  const navigator = inject(NavigatorKey);
-
-  if (!navigator) {
-    throw new Error("useNavigator must be used within a RouterProvider");
-  }
-
-  return navigator;
-};

package/src/composables/useRoute.ts

@@ -1,34 +0,0 @@
-import { inject } from "vue";
-
-import { RouteKey } from "../context";
-
-import type { RouteContext } from "../types";
-import type { Params, State } from "@real-router/core";
-import type { Ref } from "vue";
-
-/**
- * Return shape for `useRoute()` — `RouteContext<P>` with `route` narrowed
- * to the non-nullable variant. The composable throws when `route.value`
- * would be `undefined`, so consumers can read `.value.params.x` without a
- * nullable guard. Extracted from inline duplication at two call sites.
- */
-export type UseRouteReturn<P extends Params = Params> = Omit<
-  RouteContext<P>,
-  "route"
-> & { route: Readonly<Ref<State<P>>> };
-
-export const useRoute = <P extends Params = Params>(): UseRouteReturn<P> => {
-  const routeContext = inject(RouteKey);
-
-  if (!routeContext) {
-    throw new Error("useRoute must be used within a RouterProvider");
-  }
-
-  if (!routeContext.route.value) {
-    throw new Error(
-      "useRoute called with no active route. Did you forget to await router.start() before rendering, or is the router stopped/disposed?",
-    );
-  }
-
-  return routeContext as UseRouteReturn<P>;
-};

package/src/composables/useRouteEnter.ts

@@ -1,120 +0,0 @@
-import { watch } from "vue";
-
-import { useRoute } from "./useRoute";
-
-import type { State } from "@real-router/core";
-
-export interface RouteEnterContext {
-  /** The route that was just activated. */
-  route: State;
-  /** The route that was active immediately before this navigation. */
-  previousRoute: State;
-}
-
-export type RouteEnterHandler = (context: RouteEnterContext) => void;
-
-export interface UseRouteEnterOptions {
-  /**
-   * Skip the handler when `route.name === previousRoute.name`
-   * (sort/filter/query-only navigations on the same route). Default:
-   * `true`. Symmetric with `useRouteExit`'s same-name option.
-   */
-  skipSameRoute?: boolean;
-}
-
-/**
- * Fire `handler` once when the component mounts as a result of a
- * navigation. Mirror of `useRouteExit` for the entry side.
- *
- * What this composable covers that an ad-hoc `watch` + `useRoute()`
- * doesn't:
- *
- *   - **Skip-initial**: `watch` (with default `immediate: false`) plus the
- *     explicit `route.transition.from` guard ensures the handler doesn't
- *     fire on the very first state committed by `router.start()`.
- *   - **Same-route skip** (default): handler is skipped when
- *     `route.transition.from === route.name`. Sort/filter/query-only
- *     navigations re-trigger the watcher, but they are not "entries" in
- *     the animation / analytics sense. Opt out with
- *     `skipSameRoute: false`.
- *   - **Mount-time `route` / `previousRoute` snapshot**: handler receives
- *     the values that were live at the moment of the new state, not the
- *     latest ones (which may have moved on if the user navigated again
- *     before the watcher drained).
- *
- * **Handler reactivity (Vue):** Vue composables run **once** during
- * `setup()`; `handler` is captured in closure at the call site. To vary
- * behavior over time, read refs/computeds inside the handler body.
- *
- * @example Direction-aware entry animation
- * ```ts
- * useRouteEnter(({ route }) => {
- *   const direction = route.context.browser?.direction;
- *   ref.value?.classList.add(
- *     direction === "back" ? "slide-from-left" : "slide-from-right",
- *   );
- * });
- * ```
- *
- * @example Analytics page-enter event (skip-initial built-in)
- * ```ts
- * useRouteEnter(({ route, previousRoute }) => {
- *   analytics.track("page_enter", {
- *     route: route.name,
- *     from: previousRoute.name,
- *   });
- * });
- * ```
- *
- * @example Reading rich transition metadata via `route.transition`
- * ```ts
- * useRouteEnter(({ route }) => {
- *   if (route.transition.redirected) {
- *     showToast(`Redirected from ${route.transition.from}`);
- *   }
- * });
- * ```
- */
-export function useRouteEnter(
-  handler: RouteEnterHandler,
-  options?: UseRouteEnterOptions,
-): void {
-  const { route, previousRoute } = useRoute();
-  const skipSameRoute = options?.skipSameRoute ?? true;
-  let lastHandledRoute: State | null = null;
-
-  watch(route, (newRoute) => {
-    const prev = previousRoute.value;
-
-    // Early-exit guards, top-down:
-    //
-    //   - **Skip-initial**: `!transition.from` catches the first commit
-    //     from `router.start()`. Vue's `watch` (default `immediate: false`)
-    //     does not fire on the initial state — kept for parity with
-    //     React/Preact and v8-ignored.
-    //   - **Skip-same-route**: query-only navigations have
-    //     `transition.from === route.name`. Opt-out via
-    //     `skipSameRoute: false`.
-    //   - **Defensive dedupe + missing `previousRoute`**: same `route`
-    //     ref between watcher activations is unexpected on Vue (driven
-    //     off ref identity); `!prev` is unreachable once
-    //     `transition.from` is set (core populates them together). Both
-    //     kept for parity with React; v8-ignored.
-    /* v8 ignore start */
-    if (!newRoute.transition.from) {
-      return;
-    }
-    /* v8 ignore stop */
-    if (skipSameRoute && newRoute.transition.from === newRoute.name) {
-      return;
-    }
-    /* v8 ignore start */
-    if (lastHandledRoute === newRoute || !prev) {
-      return;
-    }
-    /* v8 ignore stop */
-
-    lastHandledRoute = newRoute;
-    handler({ route: newRoute, previousRoute: prev });
-  });
-}

package/src/composables/useRouteExit.ts

@@ -1,116 +0,0 @@
-import { onScopeDispose } from "vue";
-
-import { useRouter } from "./useRouter";
-
-import type { State } from "@real-router/core";
-
-export interface RouteExitContext {
-  /** The route being left. */
-  route: State;
-  /** The route being navigated to. */
-  nextRoute: State;
-  /**
-   * AbortSignal that fires when this navigation is superseded by a later
-   * one (rapid clicks). Already filtered: when the handler runs,
-   * `signal.aborted` is guaranteed to be `false`. Use
-   * `signal.addEventListener("abort", cleanup, { once: true })` for
-   * cleanup that must run on cancellation.
-   */
-  signal: AbortSignal;
-}
-
-export interface UseRouteExitOptions {
-  /**
-   * Skip the handler when `route.name === nextRoute.name`
-   * (sort/filter/query-only navigations on the same route). Default:
-   * `true`.
-   */
-  skipSameRoute?: boolean;
-}
-
-export type RouteExitHandler = (
-  context: RouteExitContext,
-) => void | Promise<void>;
-
-/**
- * Subscribe to the router's leave-window with the universal guards baked
- * in. Wraps `router.subscribeLeave` so consumers don't repeat the same
- * boilerplate every time:
- *
- *   - **Reentrant abort pre-check**: if `signal.aborted` is already `true`
- *     when the handler would run (rapid navigation superseded a slower
- *     one), the handler is skipped entirely.
- *   - **Same-route skip**: by default, `route.name === nextRoute.name`
- *     short-circuits the handler — query-only navigations skip the work.
- *     Opt out with `skipSameRoute: false`.
- *
- * Cleanup is bound to the component's effect scope via `onScopeDispose`.
- *
- * If the handler returns a Promise, the router blocks on it. If the
- * Promise resolves, navigation proceeds. If it rejects, the router emits
- * `TRANSITION_CANCELLED`.
- *
- * **Handler reactivity (Vue):** Vue composables run **once** during
- * `setup()`; `handler` is captured in closure at the call site. To vary
- * behavior over time, read refs/computeds inside the handler body — do
- * not rely on swapping the handler reference.
- *
- * @example Animation
- * ```ts
- * const ref = useTemplateRef<HTMLDivElement>("box");
- *
- * useRouteExit(async ({ signal }) => {
- *   const el = ref.value;
- *   if (!el) return;
- *   el.classList.add("fade-out");
- *   const cleanup = () => el.classList.remove("fade-out");
- *   signal.addEventListener("abort", cleanup, { once: true });
- *   try {
- *     el.getBoundingClientRect();
- *     await Promise.allSettled(el.getAnimations().map((a) => a.finished));
- *   } finally {
- *     cleanup();
- *   }
- * });
- * ```
- *
- * @example Auto-save form draft
- * ```ts
- * useRouteExit(async ({ signal }) => {
- *   if (formState.value.dirty) {
- *     await api.saveDraft(formState.value, { signal });
- *   }
- * });
- * ```
- *
- * @example Reading rich transition metadata via `nextRoute.transition`
- * ```ts
- * useRouteExit(({ route, nextRoute }) => {
- *   if (nextRoute.transition.segments.deactivated.includes("products")) {
- *     productCache.clear();
- *   }
- *   if (nextRoute.transition.redirected) return;
- * });
- * ```
- */
-export function useRouteExit(
-  handler: RouteExitHandler,
-  options?: UseRouteExitOptions,
-): void {
-  const router = useRouter();
-  const skipSameRoute = options?.skipSameRoute ?? true;
-
-  const off = router.subscribeLeave(({ route, nextRoute, signal }) => {
-    if (skipSameRoute && route.name === nextRoute.name) {
-      return;
-    }
-
-    if (signal.aborted) {
-      return;
-    }
-
-    return handler({ route, nextRoute, signal });
-  });
-
-  onScopeDispose(off);
-}

package/src/composables/useRouteNode.ts

@@ -1,31 +0,0 @@
-import { getNavigator } from "@real-router/core";
-import { createRouteNodeSource } from "@real-router/sources";
-import { computed } from "vue";
-
-import { useRefFromSource } from "../useRefFromSource";
-import { useRouter } from "./useRouter";
-
-import type { RouteContext } from "../types";
-
-export function useRouteNode(nodeName: string): RouteContext {
-  const router = useRouter();
-
-  const source = createRouteNodeSource(router, nodeName);
-  const snapshot = useRefFromSource(source);
-
-  // getNavigator is WeakMap-cached in core; no useMemo equivalent needed.
-  const navigator = getNavigator(router);
-
-  // Derive route/previousRoute via computed instead of mirroring with a sync
-  // watch into two extra shallowRefs. computed shares snapshot's identity so
-  // when the underlying source emits the same reference (idempotent or
-  // out-of-node nav), consumers don't see a new ref.
-  const route = computed(() => snapshot.value.route);
-  const previousRoute = computed(() => snapshot.value.previousRoute);
-
-  return {
-    navigator,
-    route,
-    previousRoute,
-  };
-}

package/src/composables/useRouteUtils.ts

@@ -1,12 +0,0 @@
-import { getPluginApi } from "@real-router/core/api";
-import { getRouteUtils } from "@real-router/route-utils";
-
-import { useRouter } from "./useRouter";
-
-import type { RouteUtils } from "@real-router/route-utils";
-
-export const useRouteUtils = (): RouteUtils => {
-  const router = useRouter();
-
-  return getRouteUtils(getPluginApi(router).getTree());
-};

package/src/composables/useRouter.ts

@@ -1,15 +0,0 @@
-import { inject } from "vue";
-
-import { RouterKey } from "../context";
-
-import type { Router } from "@real-router/core";
-
-export const useRouter = (): Router => {
-  const router = inject(RouterKey);
-
-  if (!router) {
-    throw new Error("useRouter must be used within a RouterProvider");
-  }
-
-  return router;
-};

package/src/composables/useRouterTransition.ts

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

package/src/constants.ts

@@ -1,9 +0,0 @@
-/**
- * Stable empty object for default params
- */
-export const EMPTY_PARAMS = Object.freeze({});
-
-/**
- * Stable empty options object
- */
-export const EMPTY_OPTIONS = Object.freeze({});

package/src/context.ts

@@ -1,13 +0,0 @@
-import type { RouteContext as RouteContextType } from "./types";
-import type { HttpStatusSink } from "./utils/createHttpStatusSink";
-import type { Router, Navigator } from "@real-router/core";
-import type { InjectionKey } from "vue";
-
-export const RouterKey: InjectionKey<Router> = Symbol("RouterKey");
-
-export const NavigatorKey: InjectionKey<Navigator> = Symbol("NavigatorKey");
-
-export const RouteKey: InjectionKey<RouteContextType> = Symbol("RouteKey");
-
-export const HTTP_STATUS_KEY: InjectionKey<HttpStatusSink> =
-  Symbol("HttpStatusSink");

package/src/createRouterPlugin.ts

@@ -1,31 +0,0 @@
-import { NavigatorKey, RouteKey, RouterKey } from "./context";
-import { pushDirectiveRouter } from "./directives/vLink";
-import { setupRouteProvision } from "./setupRouteProvision";
-
-import type { Router } from "@real-router/core";
-import type { App, Plugin } from "vue";
-
-export function createRouterPlugin(router: Router): Plugin<[]> {
-  return {
-    install(app): void {
-      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);
-      app.provide(RouteKey, { navigator, route, previousRoute });
-    },
-  };
-}

package/src/directives/vLink.ts

@@ -1,208 +0,0 @@
-import { shouldNavigate, applyLinkA11y } from "../dom-utils";
-
-import type { Router, NavigationOptions, Params } from "@real-router/core";
-import type { Directive } from "vue";
-
-export interface LinkDirectiveValue {
-  name: string;
-  params?: Params;
-  options?: NavigationOptions;
-}
-
-/**
- * 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. Not exported from the package entry; retained for
- * unit tests and rare standalone-directive setups (where v-link is mounted
- * outside any RouterProvider).
- *
- * @internal
- */
-export function setDirectiveRouter(router: Router | null): void {
-  if (router === null) {
-    routerStack.length = 0;
-
-    return;
-  }
-  if (routerStack.length === 0) {
-    routerStack.push(router);
-
-    return;
-  }
-
-  routerStack[routerStack.length - 1] = router;
-}
-
-export function getDirectiveRouter(): Router {
-  const top = routerStack.at(-1);
-
-  if (!top) {
-    throw new Error(
-      "v-link directive requires a RouterProvider ancestor. Make sure RouterProvider is mounted.",
-    );
-  }
-
-  return top;
-}
-
-interface Handlers {
-  click: (evt: MouseEvent) => void;
-  keydown: (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,
-  value: LinkDirectiveValue,
-): (evt: MouseEvent) => void {
-  return (evt: MouseEvent) => {
-    if (!shouldNavigate(evt)) {
-      return;
-    }
-
-    evt.preventDefault();
-    router
-      .navigate(value.name, value.params ?? {}, value.options ?? {})
-      .catch(() => {});
-  };
-}
-
-function createKeydownHandler(
-  router: Router,
-  value: LinkDirectiveValue,
-  element: HTMLElement,
-): (evt: KeyboardEvent) => void {
-  return (evt: KeyboardEvent) => {
-    if (evt.key === "Enter" && !(element instanceof HTMLButtonElement)) {
-      router
-        .navigate(value.name, value.params ?? {}, value.options ?? {})
-        .catch(() => {});
-    }
-  };
-}
-
-function attachHandlers(
-  element: HTMLElement,
-  router: Router,
-  value: LinkDirectiveValue,
-): void {
-  const click = createClickHandler(router, value);
-  const keydown = createKeydownHandler(router, value, element);
-
-  element.addEventListener("click", click);
-  element.addEventListener("keydown", keydown);
-
-  handlers.set(element, { click, keydown });
-}
-
-function detachHandlers(element: HTMLElement): void {
-  const entry = handlers.get(element);
-
-  if (entry) {
-    element.removeEventListener("click", entry.click);
-    element.removeEventListener("keydown", entry.keydown);
-    handlers.delete(element);
-  }
-}
-
-export const vLink: Directive<HTMLElement, LinkDirectiveValue> = {
-  mounted(element, binding) {
-    const router = getDirectiveRouter();
-
-    applyLinkA11y(element);
-
-    element.style.cursor = "pointer";
-
-    if (!isValidBinding(binding.value)) {
-      return;
-    }
-
-    attachHandlers(element, router, binding.value);
-  },
-
-  updated(element, binding) {
-    // Hot-path guard: Vue invokes `updated` on every parent re-render even
-    // when the directive's binding value reference has not changed. Without
-    // this short-circuit, every parent rerender (which is the common case on
-    // Link-heavy pages — any unrelated state change triggers the parent's
-    // render fn) would detach + reattach the click/keydown listeners.
-    // Comparing references is enough: when consumers pass a stable
-    // `LinkDirectiveValue` object (the recommended pattern, since Vue's
-    // template compiler hoists `v-link="{ name: 'home' }"` to a stable
-    // literal), this guard collapses the work to zero.
-    if (binding.value === binding.oldValue) {
-      return;
-    }
-
-    const router = getDirectiveRouter();
-
-    detachHandlers(element);
-
-    if (!isValidBinding(binding.value)) {
-      return;
-    }
-
-    attachHandlers(element, router, binding.value);
-  },
-
-  beforeUnmount(element) {
-    detachHandlers(element);
-  },
-};