@real-router/react 0.19.0 → 0.21.0

package/src/RouterProvider.tsx

@@ -3,7 +3,11 @@ import { createRouteSource } from "@real-router/sources";
 import { useEffect, useMemo, useSyncExternalStore } from "react";
 
 import { NavigatorContext, RouteContext, RouterContext } from "./context";
-import { createRouteAnnouncer, createScrollRestoration } from "./dom-utils";
+import {
+  createRouteAnnouncer,
+  createScrollRestoration,
+  createViewTransitions,
+} from "./dom-utils";
 
 import type { ScrollRestorationOptions } from "./dom-utils";
 import type { Router } from "@real-router/core";
@@ -14,6 +18,7 @@ export interface RouteProviderProps {
   children: ReactNode;
   announceNavigation?: boolean;
   scrollRestoration?: ScrollRestorationOptions;
+  viewTransitions?: boolean;
 }
 
 export const RouterProvider: FC<RouteProviderProps> = ({
@@ -21,6 +26,7 @@ export const RouterProvider: FC<RouteProviderProps> = ({
   children,
   announceNavigation,
   scrollRestoration,
+  viewTransitions,
 }) => {
   useEffect(() => {
     if (!announceNavigation) {
@@ -61,6 +67,18 @@ export const RouterProvider: FC<RouteProviderProps> = ({
     // eslint-disable-next-line @eslint-react/exhaustive-deps
   }, [router, srEnabled, srMode, srAnchor]);
 
+  useEffect(() => {
+    if (!viewTransitions) {
+      return;
+    }
+
+    const vt = createViewTransitions(router);
+
+    return () => {
+      vt.destroy();
+    };
+  }, [router, viewTransitions]);
+
   const navigator = useMemo(() => getNavigator(router), [router]);
 
   // useSyncExternalStore manages the router subscription lifecycle:

package/src/components/modern/RouteView/RouteView.tsx

@@ -1,6 +1,6 @@
 import { useMemo, useRef } from "react";
 
-import { Match, NotFound } from "./components";
+import { Match, NotFound, Self } from "./components";
 import { buildRenderList, collectElements } from "./helpers";
 import { useRouteNode } from "../../../hooks/useRouteNode";
 
@@ -49,10 +49,15 @@ function RouteViewRoot({
 
 RouteViewRoot.displayName = "RouteView";
 
-export const RouteView = Object.assign(RouteViewRoot, { Match, NotFound });
+export const RouteView = Object.assign(RouteViewRoot, {
+  Match,
+  Self,
+  NotFound,
+});
 
 export type {
   RouteViewProps,
   MatchProps as RouteViewMatchProps,
+  SelfProps as RouteViewSelfProps,
   NotFoundProps as RouteViewNotFoundProps,
 } from "./types";

package/src/components/modern/RouteView/components.tsx

@@ -1,4 +1,4 @@
-import type { MatchProps, NotFoundProps } from "./types";
+import type { MatchProps, NotFoundProps, SelfProps } from "./types";
 
 export function Match(_props: MatchProps): null {
   return null;
@@ -6,6 +6,12 @@ export function Match(_props: MatchProps): null {
 
 Match.displayName = "RouteView.Match";
 
+export function Self(_props: SelfProps): null {
+  return null;
+}
+
+Self.displayName = "RouteView.Self";
+
 export function NotFound(_props: NotFoundProps): null {
   return null;
 }

package/src/components/modern/RouteView/helpers.tsx

@@ -2,11 +2,18 @@ import { UNKNOWN_ROUTE } from "@real-router/core";
 import { startsWithSegment } from "@real-router/route-utils";
 import { Activity, Children, Fragment, Suspense, isValidElement } from "react";
 
-import { Match, NotFound } from "./components";
+import { Match, NotFound, Self } from "./components";
 
-import type { MatchProps, NotFoundProps } from "./types";
+import type { MatchProps, NotFoundProps, SelfProps } from "./types";
 import type { ReactElement, ReactNode } from "react";
 
+interface FallbackSlots {
+  selfChildren: ReactNode;
+  selfFallback: ReactNode | undefined;
+  selfFound: boolean;
+  notFoundChildren: ReactNode;
+}
+
 function isSegmentMatch(
   routeName: string,
   fullSegmentName: string,
@@ -33,7 +40,11 @@ export function collectElements(
       continue;
     }
 
-    if (child.type === Match || child.type === NotFound) {
+    if (
+      child.type === Match ||
+      child.type === Self ||
+      child.type === NotFound
+    ) {
       result.push(child);
     } else {
       collectElements(
@@ -44,29 +55,127 @@ export function collectElements(
   }
 }
 
-function renderMatchElement(
-  matchChildren: ReactNode,
-  fullSegmentName: string,
+function renderSlotElement(
+  slotChildren: ReactNode,
+  key: string,
   keepAlive: boolean,
   mode: "visible" | "hidden",
   fallback?: ReactNode,
 ): ReactElement {
   const content =
     fallback === undefined ? (
-      matchChildren
+      slotChildren
     ) : (
-      <Suspense fallback={fallback}>{matchChildren}</Suspense>
+      <Suspense fallback={fallback}>{slotChildren}</Suspense>
     );
 
   if (keepAlive) {
     return (
-      <Activity mode={mode} key={fullSegmentName}>
+      <Activity mode={mode} key={key}>
         {content}
       </Activity>
     );
   }
 
-  return <Fragment key={fullSegmentName}>{content}</Fragment>;
+  return <Fragment key={key}>{content}</Fragment>;
+}
+
+function recordFallback(child: ReactElement, slots: FallbackSlots): boolean {
+  if (child.type === NotFound) {
+    slots.notFoundChildren = (child.props as NotFoundProps).children;
+
+    return true;
+  }
+
+  if (child.type === Self) {
+    // First-wins: subsequent <Self> elements are ignored, mirroring NotFound.
+    if (!slots.selfFound) {
+      slots.selfChildren = (child.props as SelfProps).children;
+      slots.selfFallback = (child.props as SelfProps).fallback;
+      slots.selfFound = true;
+    }
+
+    return true;
+  }
+
+  return false;
+}
+
+function processMatch(
+  child: ReactElement,
+  routeName: string,
+  nodeName: string,
+  hasBeenActivated: Set<string>,
+  alreadyActive: boolean,
+): { rendered: ReactElement | null; matched: boolean } {
+  const {
+    segment,
+    exact = false,
+    keepAlive = false,
+    fallback,
+  } = child.props as MatchProps;
+  const fullSegmentName = nodeName ? `${nodeName}.${segment}` : segment;
+  const isActive =
+    !alreadyActive && isSegmentMatch(routeName, fullSegmentName, exact);
+
+  if (isActive) {
+    hasBeenActivated.add(fullSegmentName);
+
+    return {
+      rendered: renderSlotElement(
+        (child.props as MatchProps).children,
+        fullSegmentName,
+        keepAlive,
+        "visible",
+        fallback,
+      ),
+      matched: true,
+    };
+  }
+
+  if (keepAlive && hasBeenActivated.has(fullSegmentName)) {
+    return {
+      rendered: renderSlotElement(
+        (child.props as MatchProps).children,
+        fullSegmentName,
+        keepAlive,
+        "hidden",
+        fallback,
+      ),
+      matched: false,
+    };
+  }
+
+  return { rendered: null, matched: false };
+}
+
+function appendFallback(
+  rendered: ReactElement[],
+  routeName: string,
+  nodeName: string,
+  slots: FallbackSlots,
+): void {
+  if (slots.selfFound && routeName === nodeName) {
+    rendered.push(
+      renderSlotElement(
+        slots.selfChildren,
+        "__route-view-self__",
+        false,
+        "visible",
+        slots.selfFallback,
+      ),
+    );
+
+    return;
+  }
+
+  if (routeName === UNKNOWN_ROUTE && slots.notFoundChildren !== null) {
+    rendered.push(
+      <Fragment key="__route-view-not-found__">
+        {slots.notFoundChildren}
+      </Fragment>,
+    );
+  }
 }
 
 export function buildRenderList(
@@ -75,59 +184,39 @@ export function buildRenderList(
   nodeName: string,
   hasBeenActivated: Set<string>,
 ): { rendered: ReactElement[]; activeMatchFound: boolean } {
-  let notFoundChildren: ReactNode = null;
+  const slots: FallbackSlots = {
+    selfChildren: null,
+    selfFallback: undefined,
+    selfFound: false,
+    notFoundChildren: null,
+  };
   let activeMatchFound = false;
   const rendered: ReactElement[] = [];
 
   for (const child of elements) {
-    if (child.type === NotFound) {
-      notFoundChildren = (child.props as NotFoundProps).children;
+    if (recordFallback(child, slots)) {
       continue;
     }
 
-    const {
-      segment,
-      exact = false,
-      keepAlive = false,
-      fallback,
-    } = child.props as MatchProps;
-    const fullSegmentName = nodeName ? `${nodeName}.${segment}` : segment;
-    const isActive =
-      !activeMatchFound && isSegmentMatch(routeName, fullSegmentName, exact);
-
-    if (isActive) {
+    const result = processMatch(
+      child,
+      routeName,
+      nodeName,
+      hasBeenActivated,
+      activeMatchFound,
+    );
+
+    if (result.matched) {
       activeMatchFound = true;
-      hasBeenActivated.add(fullSegmentName);
-      rendered.push(
-        renderMatchElement(
-          (child.props as MatchProps).children,
-          fullSegmentName,
-          keepAlive,
-          "visible",
-          fallback,
-        ),
-      );
-    } else if (keepAlive && hasBeenActivated.has(fullSegmentName)) {
-      rendered.push(
-        renderMatchElement(
-          (child.props as MatchProps).children,
-          fullSegmentName,
-          keepAlive,
-          "hidden",
-          fallback,
-        ),
-      );
+    }
+
+    if (result.rendered !== null) {
+      rendered.push(result.rendered);
     }
   }
 
-  if (
-    !activeMatchFound &&
-    routeName === UNKNOWN_ROUTE &&
-    notFoundChildren !== null
-  ) {
-    rendered.push(
-      <Fragment key="__route-view-not-found__">{notFoundChildren}</Fragment>,
-    );
+  if (!activeMatchFound) {
+    appendFallback(rendered, routeName, nodeName, slots);
   }
 
   return { rendered, activeMatchFound };

package/src/components/modern/RouteView/index.ts

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

package/src/components/modern/RouteView/types.ts

@@ -3,7 +3,7 @@ import type { ReactNode } from "react";
 export interface RouteViewProps {
   /** Route tree node name to subscribe to. "" for root. */
   readonly nodeName: string;
-  /** <RouteView.Match> and <RouteView.NotFound> elements. */
+  /** <RouteView.Match>, <RouteView.Self>, and <RouteView.NotFound> elements. */
   readonly children: ReactNode;
 }
 
@@ -20,6 +20,18 @@ export interface MatchProps {
   readonly children: ReactNode;
 }
 
+export interface SelfProps {
+  /**
+   * Fallback content to show while children are suspended.
+   *
+   * Symmetric with `<RouteView.Match fallback>` — wraps children in
+   * `<Suspense>` when defined.
+   */
+  readonly fallback?: ReactNode;
+  /** Content to render when the active route name equals the parent RouteView's nodeName. */
+  readonly children: ReactNode;
+}
+
 export interface NotFoundProps {
   /** Content to render on UNKNOWN_ROUTE. */
   readonly children: ReactNode;

package/src/hooks/useRouteEnter.tsx

@@ -0,0 +1,156 @@
+import { useEffect, useLayoutEffect, useRef } from "react";
+
+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 hook covers that ad-hoc `useEffect` + `useRoute()` doesn't:
+ *
+ *   - **Skip-initial**: handler is skipped when there is no
+ *     `previousRoute` (i.e. first-load mount). Most consumers want to
+ *     fire side effects only on real navigations, not on hydration.
+ *   - **Same-route skip** (default): handler is skipped when
+ *     `route.name === previousRoute.name`. Sort/filter/query-only
+ *     navigations re-run the effect (because `route` reference changes
+ *     in `useRoute`'s snapshot), but they are not "entries" in the
+ *     animation / analytics sense — the component instance has stayed
+ *     mounted throughout. Opt out with `skipSameRoute: false` when
+ *     the handler legitimately needs to fire on every navigation
+ *     (e.g. analytics tracking each query-param flip).
+ *   - **StrictMode double-mount immunity**: in dev, React's StrictMode
+ *     runs every effect twice to surface bugs. Without a guard,
+ *     analytics fire twice, animations restart, focus jumps. The hook
+ *     tracks the last-handled `route` reference and short-circuits the
+ *     second pass.
+ *   - **Latest-handler ref**: the handler can change identity on every
+ *     render without re-running the effect — the registered wrapper
+ *     dispatches to whatever `handlerRef.current` points to.
+ *   - **Mount-time `route` / `previousRoute` snapshot**: the handler
+ *     receives the values that were live at the moment of mount, not
+ *     the latest ones (which may have moved on if the user navigated
+ *     again before the effect drained).
+ *
+ * Race-safety: `useRoute()` is wired through `useSyncExternalStore` from
+ * `@real-router/sources`, so by the time the new component's effect
+ * runs, the snapshot is the post-commit one. This is the reason we can
+ * read mount-time context from `useRoute()` instead of subscribing to
+ * `router.subscribe` directly (which fires before React schedules a
+ * re-render — the well-known race in distributed components).
+ *
+ * @example Direction-aware entry animation
+ * ```tsx
+ * useRouteEnter(({ route }) => {
+ *   const direction = route.context.browser?.direction;
+ *   ref.current?.classList.add(
+ *     direction === "back" ? "slide-from-left" : "slide-from-right",
+ *   );
+ * });
+ * ```
+ *
+ * @example Source-aware focus management
+ * ```tsx
+ * useRouteEnter(({ route }) => {
+ *   if (route.context.browser?.source === "navigate") {
+ *     headingRef.current?.focus();
+ *   }
+ * });
+ * ```
+ *
+ * @example Analytics page-enter event (skip-initial built-in)
+ * ```tsx
+ * useRouteEnter(({ route, previousRoute }) => {
+ *   analytics.track("page_enter", {
+ *     route: route.name,
+ *     from: previousRoute.name,
+ *   });
+ * });
+ * ```
+ *
+ * @example Reading rich transition metadata via `route.transition`
+ * ```tsx
+ * useRouteEnter(({ route }) => {
+ *   // route.transition: TransitionMeta — populated by core for every state
+ *   if (route.transition.redirected) {
+ *     showToast(`Redirected from ${route.transition.from}`);
+ *   }
+ *   if (route.transition.segments.activated.includes("products")) {
+ *     // products subtree just became active (could be products or
+ *     // products.detail). Useful for subtree-scoped side effects.
+ *   }
+ * });
+ * ```
+ */
+export function useRouteEnter(
+  handler: RouteEnterHandler,
+  options?: UseRouteEnterOptions,
+): void {
+  const { route, previousRoute } = useRoute();
+  const handlerRef = useRef(handler);
+  const lastHandledRouteRef = useRef<State | null>(null);
+  const skipSameRoute = options?.skipSameRoute ?? true;
+
+  // Keep the latest handler reference accessible without re-running
+  // the effect. useLayoutEffect (synchronous, post-render, pre-paint)
+  // updates the ref before the effect can read it.
+  useLayoutEffect(() => {
+    handlerRef.current = handler;
+  });
+
+  useEffect(() => {
+    // Early-exit guards, top-down:
+    //
+    //   - **Defensive**: `route` / `previousRoute` may be undefined
+    //     during SSR or pre-start hydration. Not testable from vitest
+    //     (tests start the router before render), so v8-ignored.
+    //   - **Skip-initial**: `state.transition.from` is undefined only
+    //     for the very first state committed by `router.start()`.
+    //   - **Skip-same-route**: query-only navigations have
+    //     `transition.from === route.name`. Opt-out via
+    //     `skipSameRoute: false`.
+    //   - **StrictMode dedupe**: same `route` ref between effect
+    //     cleanup + re-run in dev's strict pass. Not testable from
+    //     vitest (`NODE_ENV === "test"` disables React's strict-mode
+    //     double-run), so v8-ignored.
+    /* v8 ignore start */
+    if (!route) {
+      return;
+    }
+    /* v8 ignore stop */
+    if (!route.transition.from) {
+      return;
+    }
+    if (skipSameRoute && route.transition.from === route.name) {
+      return;
+    }
+    /* v8 ignore start */
+    if (lastHandledRouteRef.current === route || !previousRoute) {
+      return;
+    }
+    /* v8 ignore stop */
+
+    lastHandledRouteRef.current = route;
+    handlerRef.current({ route, previousRoute });
+  }, [route, previousRoute, skipSameRoute]);
+}

package/src/hooks/useRouteExit.tsx

@@ -0,0 +1,159 @@
+import { useEffect, useLayoutEffect, useRef } from "react";
+
+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. `signal.addEventListener(
+ *     "abort", ...)` does not fire retroactively, so without this guard
+ *     downstream cleanup would never trigger.
+ *   - **Same-route skip**: by default, `route.name === nextRoute.name`
+ *     short-circuits the handler — query-only navigations (sort, filter,
+ *     pagination) skip the work. Opt out with `skipSameRoute: false`.
+ *   - **Stable handler reference**: the handler can change identity on
+ *     every render without causing resubscription — internal ref keeps
+ *     the latest handler accessible to the long-lived subscription.
+ *
+ * Returns nothing — the subscription's lifecycle is bound to the
+ * component's mount.
+ *
+ * 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` (existing core behavior, no change here).
+ *
+ * @example Animation
+ * ```tsx
+ * const ref = useRef<HTMLDivElement>(null);
+ *
+ * useRouteExit(async ({ signal }) => {
+ *   const el = ref.current;
+ *   if (!el) return;
+ *   el.classList.add("fade-out");
+ *   const cleanup = () => el.classList.remove("fade-out");
+ *   signal.addEventListener("abort", cleanup, { once: true });
+ *   try {
+ *     el.getBoundingClientRect();   // style flush
+ *     await Promise.allSettled(el.getAnimations().map((a) => a.finished));
+ *   } finally {
+ *     cleanup();
+ *   }
+ * });
+ * ```
+ *
+ * @example Auto-save form draft
+ * ```tsx
+ * useRouteExit(async ({ signal }) => {
+ *   if (formState.dirty) await api.saveDraft(formState, { signal });
+ * });
+ * ```
+ *
+ * @example Cancel inflight requests
+ * ```tsx
+ * useRouteExit(() => {
+ *   inflightController.abort();
+ * });
+ * ```
+ *
+ * @example Library-coordinated exit (motion / framer-motion)
+ * ```tsx
+ * const exitResolverRef = useRef<(() => void) | null>(null);
+ *
+ * useRouteExit(({ signal }) => {
+ *   return new Promise<void>((resolve) => {
+ *     exitResolverRef.current = resolve;
+ *     signal.addEventListener("abort", () => resolve(), { once: true });
+ *   });
+ * });
+ *
+ * const onExitComplete = () => exitResolverRef.current?.();
+ * // pass onExitComplete to <AnimatePresence>
+ * ```
+ *
+ * @example Reading rich transition metadata via `nextRoute.transition`
+ * ```tsx
+ * useRouteExit(({ route, nextRoute }) => {
+ *   // nextRoute.transition: TransitionMeta — preview of the upcoming nav
+ *   if (nextRoute.transition.segments.deactivated.includes("products")) {
+ *     // leaving the products subtree entirely — flush product-related caches
+ *     productCache.clear();
+ *   }
+ *   if (nextRoute.transition.redirected) {
+ *     // skip animation when navigation arrived via redirect
+ *     return;
+ *   }
+ * });
+ * ```
+ */
+export function useRouteExit(
+  handler: RouteExitHandler,
+  options?: UseRouteExitOptions,
+): void {
+  const router = useRouter();
+  const handlerRef = useRef(handler);
+  const skipSameRoute = options?.skipSameRoute ?? true;
+
+  // Keep the latest handler accessible to the subscription without
+  // resubscribing on every render — the subscription registers the
+  // wrapper once and dispatches to whatever ref points to.
+  // useLayoutEffect (synchronous, post-render, pre-paint) updates the
+  // ref before the browser can dispatch any router events that could
+  // observe a stale closure.
+  useLayoutEffect(() => {
+    handlerRef.current = handler;
+  });
+
+  useEffect(() => {
+    return router.subscribeLeave(({ route, nextRoute, signal }) => {
+      if (skipSameRoute && route.name === nextRoute.name) {
+        return;
+      }
+
+      // Reentrant abort: signal is already aborted when listener fires
+      // (e.g. a newer navigate superseded this one before subscribeLeave
+      // even ran). addEventListener("abort", ...) does not fire
+      // retroactively, so we skip the handler entirely — any cleanup the
+      // handler would have wired via abort listener must not run because
+      // the corresponding `add` work never happened.
+      if (signal.aborted) {
+        return;
+      }
+
+      return handlerRef.current({ route, nextRoute, signal });
+    });
+  }, [router, skipSameRoute]);
+}