@real-router/vue 0.7.0 → 0.9.0

package/src/components/RouteView/helpers.ts

@@ -2,12 +2,18 @@ import { UNKNOWN_ROUTE } from "@real-router/core";
 import { startsWithSegment } from "@real-router/route-utils";
 import { Fragment, isVNode } from "vue";
 
-import { Match, NotFound } from "./components";
+import { Match, NotFound, Self } from "./components";
 
 import type { VNode } from "vue";
 
 type FallbackType = VNode | (() => VNode) | undefined;
 
+interface FallbackSlots {
+  selfVNode: VNode | null;
+  selfFallback: FallbackType;
+  notFoundChildren: unknown;
+}
+
 function isSegmentMatch(
   routeName: string,
   fullSegmentName: string,
@@ -46,7 +52,11 @@ export function collectElements(children: unknown, result: VNode[]): void {
   const vnodes = normalizeChildren(children);
 
   for (const child of vnodes) {
-    if (child.type === Match || child.type === NotFound) {
+    if (
+      child.type === Match ||
+      child.type === Self ||
+      child.type === NotFound
+    ) {
       result.push(child);
     } else if (child.type === Fragment) {
       collectElements(child.children, result);
@@ -54,6 +64,71 @@ export function collectElements(children: unknown, result: VNode[]): void {
   }
 }
 
+function recordFallback(child: VNode, slots: FallbackSlots): boolean {
+  if (child.type === NotFound) {
+    slots.notFoundChildren = child.children;
+
+    return true;
+  }
+
+  if (child.type === Self) {
+    if (slots.selfVNode === null) {
+      slots.selfVNode = child;
+      const props = child.props as { fallback?: FallbackType } | null;
+
+      slots.selfFallback = props?.fallback;
+    }
+
+    return true;
+  }
+
+  return false;
+}
+
+function evaluateMatch(
+  child: VNode,
+  routeName: string,
+  nodeName: string,
+): { isActive: boolean; fallback: FallbackType } {
+  const props = child.props as {
+    segment: string;
+    exact?: boolean;
+    fallback?: FallbackType;
+  } | null;
+  const segment = props?.segment ?? "";
+  const exact = props?.exact ?? false;
+  const fullSegmentName = nodeName ? `${nodeName}.${segment}` : segment;
+  const isActive = isSegmentMatch(routeName, fullSegmentName, exact);
+
+  return { isActive, fallback: props?.fallback };
+}
+
+function appendFallback(
+  rendered: VNode[],
+  routeName: string,
+  nodeName: string,
+  slots: FallbackSlots,
+  elements: VNode[],
+): FallbackType {
+  if (slots.selfVNode !== null && routeName === nodeName) {
+    rendered.push(slots.selfVNode);
+
+    return slots.selfFallback;
+  }
+
+  if (routeName === UNKNOWN_ROUTE && slots.notFoundChildren !== null) {
+    const nfElements = elements.filter((element) => element.type === NotFound);
+    /* v8 ignore next 3 */
+    const lastNf = nfElements.at(-1);
+
+    if (lastNf) {
+      rendered.push(lastNf);
+    }
+  }
+
+  return undefined;
+}
+
 export function buildRenderList(
   elements: VNode[],
   routeName: string,
@@ -63,47 +138,35 @@ export function buildRenderList(
   activeMatchFound: boolean;
   fallback?: FallbackType;
 } {
-  let notFoundChildren: unknown = null;
+  const slots: FallbackSlots = {
+    selfVNode: null,
+    selfFallback: undefined,
+    notFoundChildren: null,
+  };
   let activeMatchFound = false;
   let fallback: FallbackType = undefined;
   const rendered: VNode[] = [];
 
   for (const child of elements) {
-    if (child.type === NotFound) {
-      notFoundChildren = child.children;
+    if (recordFallback(child, slots)) {
       continue;
     }
 
-    const props = child.props as {
-      segment: string;
-      exact?: boolean;
-      fallback?: FallbackType;
-    } | null;
-    const segment = props?.segment ?? "";
-    const exact = props?.exact ?? false;
-    const fullSegmentName = nodeName ? `${nodeName}.${segment}` : segment;
-    const isActive =
-      !activeMatchFound && isSegmentMatch(routeName, fullSegmentName, exact);
-
-    if (isActive) {
+    if (activeMatchFound) {
+      continue;
+    }
+
+    const result = evaluateMatch(child, routeName, nodeName);
+
+    if (result.isActive) {
       activeMatchFound = true;
-      fallback = props?.fallback;
+      fallback = result.fallback;
       rendered.push(child);
     }
   }
 
-  if (
-    !activeMatchFound &&
-    routeName === UNKNOWN_ROUTE &&
-    notFoundChildren !== null
-  ) {
-    const nfElements = elements.filter((element) => element.type === NotFound);
-    /* v8 ignore next 3 */
-    const lastNf = nfElements.at(-1);
-
-    if (lastNf) {
-      rendered.push(lastNf);
-    }
+  if (!activeMatchFound) {
+    fallback = appendFallback(rendered, routeName, nodeName, slots, elements);
   }
 
   return { rendered, activeMatchFound, fallback };

package/src/components/RouteView/index.ts

@@ -3,5 +3,6 @@ export { RouteView } from "./RouteView";
 export type {
   RouteViewProps,
   RouteViewMatchProps,
+  RouteViewSelfProps,
   RouteViewNotFoundProps,
 } from "./RouteView";

package/src/components/RouteView/types.ts

@@ -12,4 +12,9 @@ export interface MatchProps {
   readonly keepAlive?: boolean;
 }
 
+export interface SelfProps {
+  /** Fallback content while children are suspended. */
+  readonly fallback?: VNode | (() => VNode);
+}
+
 export type NotFoundProps = Record<string, never>;

package/src/composables/useRouteEnter.ts

@@ -0,0 +1,124 @@
+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:
+    //
+    //   - **Defensive + skip-initial**: `route` may be undefined during
+    //     SSR / pre-start hydration; `!transition.from` would catch the
+    //     first commit from `router.start()`. Vue's `watch` (default
+    //     `immediate: false`) does not fire on the initial state, so
+    //     both are unreachable in Vue (covered by React/Preact tests).
+    //   - **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) {
+      return;
+    }
+    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

@@ -0,0 +1,116 @@
+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/index.ts

@@ -21,6 +21,10 @@ export { useRouteNode } from "./composables/useRouteNode";
 
 export { useRouterTransition } from "./composables/useRouterTransition";
 
+export { useRouteExit } from "./composables/useRouteExit";
+
+export { useRouteEnter } from "./composables/useRouteEnter";
+
 // Plugin
 export { createRouterPlugin } from "./createRouterPlugin";
 
@@ -42,6 +46,18 @@ export type {
   RouteViewNotFoundProps,
 } from "./components/RouteView";
 
+export type {
+  RouteExitContext,
+  RouteExitHandler,
+  UseRouteExitOptions,
+} from "./composables/useRouteExit";
+
+export type {
+  RouteEnterContext,
+  RouteEnterHandler,
+  UseRouteEnterOptions,
+} from "./composables/useRouteEnter";
+
 export type { Navigator } from "@real-router/core";
 
 export type { RouterTransitionSnapshot } from "@real-router/sources";