@real-router/react 0.27.2 → 0.27.4

package/src/hooks/useRouteEnter.tsx

@@ -1,148 +0,0 @@
-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:
-    //
-    //   - **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.
-    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

@@ -1,159 +0,0 @@
-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]);
-}

package/src/hooks/useRouteNode.tsx

@@ -1,37 +0,0 @@
-import { getNavigator } from "@real-router/core";
-import { createRouteNodeSource } from "@real-router/sources";
-import { useMemo, useSyncExternalStore } from "react";
-
-import { useRouter } from "./useRouter";
-
-import type { RouteContext } from "../types";
-
-export function useRouteNode(nodeName: string): RouteContext {
-  const router = useRouter();
-
-  const store = useMemo(
-    () => createRouteNodeSource(router, nodeName),
-    [router, nodeName],
-  );
-
-  // Use snapshot reference directly. createRouteNodeSource via stabilizeState
-  // returns the SAME snapshot when the node-relevant state did not change,
-  // so memoization on `[navigator, snapshot]` preserves identity for consumers.
-  const snapshot = useSyncExternalStore(
-    store.subscribe,
-    store.getSnapshot,
-    store.getSnapshot, // SSR: router returns same state on server and client
-  );
-
-  // getNavigator is WeakMap-cached in core; additional useMemo is redundant.
-  const navigator = getNavigator(router);
-
-  return useMemo(
-    (): RouteContext => ({
-      navigator,
-      route: snapshot.route,
-      previousRoute: snapshot.previousRoute,
-    }),
-    [navigator, snapshot],
-  );
-}

package/src/hooks/useRouteUtils.tsx

@@ -1,35 +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";
-
-/**
- * Returns a pre-computed {@link RouteUtils} instance for the current router.
- *
- * `getRouteUtils` is WeakMap-cached per `RouteTreeNode` inside
- * `@real-router/route-utils`, so the same router always returns the same
- * `RouteUtils` instance across renders — no local cache needed in the adapter.
- *
- * @returns RouteUtils instance with pre-computed chains and siblings
- *
- * @example
- * ```tsx
- * const utils = useRouteUtils();
- *
- * utils.getChain("users.profile");
- * // → ["users", "users.profile"]
- *
- * utils.getSiblings("users");
- * // → ["admin"]
- *
- * utils.isDescendantOf("users.profile", "users");
- * // → true
- * ```
- */
-export const useRouteUtils = (): RouteUtils => {
-  const router = useRouter();
-
-  return getRouteUtils(getPluginApi(router).getTree());
-};

package/src/hooks/useRouter.tsx

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

package/src/hooks/useRouterTransition.tsx

@@ -1,17 +0,0 @@
-import { getTransitionSource } from "@real-router/sources";
-import { useSyncExternalStore } from "react";
-
-import { useRouter } from "./useRouter";
-
-import type { RouterTransitionSnapshot } from "@real-router/sources";
-
-export function useRouterTransition(): RouterTransitionSnapshot {
-  const router = useRouter();
-  const store = getTransitionSource(router);
-
-  return useSyncExternalStore(
-    store.subscribe,
-    store.getSnapshot,
-    store.getSnapshot,
-  );
-}

package/src/index.react-server.ts

@@ -1,33 +0,0 @@
-// React Server entry — type-only re-exports under `react-server` condition (RSC bundlers). See CLAUDE.md.
-//
-// SSR-feature prop types (`AwaitProps`, `StreamedProps`, `ClientOnlyProps`,
-// `ServerOnlyProps`) live in the `/ssr.react-server` entry — Server
-// Components that need them import from `@real-router/react/ssr` (resolves
-// to types only under the `react-server` condition).
-
-export type { LinkProps } from "./types";
-
-export type {
-  RouteExitContext,
-  RouteExitHandler,
-  UseRouteExitOptions,
-} from "./hooks/useRouteExit";
-
-export type {
-  RouteEnterContext,
-  RouteEnterHandler,
-  UseRouteEnterOptions,
-} from "./hooks/useRouteEnter";
-
-export type {
-  RouteViewProps,
-  RouteViewMatchProps,
-  RouteViewSelfProps,
-  RouteViewNotFoundProps,
-} from "./components/modern/RouteView";
-
-export type { RouterErrorBoundaryProps } from "./components/RouterErrorBoundary";
-
-export type { Navigator } from "@real-router/core";
-
-export type { RouterTransitionSnapshot } from "@real-router/sources";

package/src/index.ts

@@ -1,61 +0,0 @@
-// Main entry point — React 19.2+
-//
-// Client-side hooks + components. SSR-aware components and hooks
-// (`<ClientOnly>`, `<ServerOnly>`, `<Await>`, `<Streamed>`, `useDeferred`)
-// have moved to the `/ssr` subpath — import them from
-// `@real-router/react/ssr` to opt into the SSR-feature surface.
-
-// Components
-export { RouteView } from "./components/modern/RouteView";
-
-export { Link } from "./components/Link";
-
-export { RouterErrorBoundary } from "./components/RouterErrorBoundary";
-
-// Hooks
-export { useRouter } from "./hooks/useRouter";
-
-export { useNavigator } from "./hooks/useNavigator";
-
-export { useRouteUtils } from "./hooks/useRouteUtils";
-
-export { useRoute } from "./hooks/useRoute";
-
-export { useRouteNode } from "./hooks/useRouteNode";
-
-export { useRouterTransition } from "./hooks/useRouterTransition";
-
-export { useRouteExit } from "./hooks/useRouteExit";
-
-export { useRouteEnter } from "./hooks/useRouteEnter";
-
-// Context
-export { RouterProvider } from "./RouterProvider";
-
-// Types
-export type { LinkProps } from "./types";
-
-export type {
-  RouteExitContext,
-  RouteExitHandler,
-  UseRouteExitOptions,
-} from "./hooks/useRouteExit";
-
-export type {
-  RouteEnterContext,
-  RouteEnterHandler,
-  UseRouteEnterOptions,
-} from "./hooks/useRouteEnter";
-
-export type {
-  RouteViewProps,
-  RouteViewMatchProps,
-  RouteViewSelfProps,
-  RouteViewNotFoundProps,
-} from "./components/modern/RouteView";
-
-export type { RouterErrorBoundaryProps } from "./components/RouterErrorBoundary";
-
-export type { Navigator } from "@real-router/core";
-
-export type { RouterTransitionSnapshot } from "@real-router/sources";

package/src/ink-types.ts

@@ -1,25 +0,0 @@
-import type { NavigationOptions, Params, Router } from "@real-router/core";
-import type { ReactNode } from "react";
-
-export interface InkLinkProps<P extends Params = Params> {
-  routeName: string;
-  routeParams?: P;
-  routeOptions?: NavigationOptions;
-  activeStrict?: boolean;
-  ignoreQueryParams?: boolean;
-  children?: ReactNode;
-  color?: string;
-  activeColor?: string;
-  focusColor?: string;
-  inverse?: boolean;
-  activeInverse?: boolean;
-  focusInverse?: boolean;
-  id?: string;
-  autoFocus?: boolean;
-  onSelect?: () => void;
-}
-
-export interface InkRouterProviderProps {
-  router: Router;
-  children?: ReactNode;
-}

package/src/ink.ts

@@ -1,30 +0,0 @@
-// Ink entry point — React 19.2+ & Ink 7+
-
-// Components
-export { InkLink } from "./components/InkLink";
-
-export { InkRouterProvider } from "./components/InkRouterProvider";
-
-export { RouterErrorBoundary } from "./components/RouterErrorBoundary";
-
-// Hooks
-export { useRouteNode } from "./hooks/useRouteNode";
-
-export { useRoute } from "./hooks/useRoute";
-
-export { useNavigator } from "./hooks/useNavigator";
-
-export { useRouter } from "./hooks/useRouter";
-
-export { useRouteUtils } from "./hooks/useRouteUtils";
-
-export { useRouterTransition } from "./hooks/useRouterTransition";
-
-// Types
-export type { InkLinkProps, InkRouterProviderProps } from "./ink-types";
-
-export type { RouterErrorBoundaryProps } from "./components/RouterErrorBoundary";
-
-export type { Navigator } from "@real-router/core";
-
-export type { RouterTransitionSnapshot } from "@real-router/sources";

package/src/legacy.ssr.ts

@@ -1,35 +0,0 @@
-// SSR-feature entry for the legacy (React 18+) entry point.
-//
-// `<Await>` is excluded — it depends on React 19's `use(promise)` which is
-// not available in React 18. React 18 consumers can compose the same
-// pattern manually with `<Suspense>` + a Suspense-aware data library.
-
-// Components
-export { ClientOnly } from "./components/ClientOnly";
-
-export { ServerOnly } from "./components/ServerOnly";
-
-export { Streamed } from "./components/Streamed";
-
-export { HttpStatusCode } from "./components/HttpStatusCode";
-
-export { HttpStatusProvider } from "./components/HttpStatusProvider";
-
-// Hooks
-export { useDeferred } from "./hooks/useDeferred";
-
-// Utilities
-export { createHttpStatusSink } from "./utils/createHttpStatusSink";
-
-// Types
-export type { ClientOnlyProps } from "./components/ClientOnly";
-
-export type { ServerOnlyProps } from "./components/ServerOnly";
-
-export type { StreamedProps } from "./components/Streamed";
-
-export type { HttpStatusCodeProps } from "./components/HttpStatusCode";
-
-export type { HttpStatusProviderProps } from "./components/HttpStatusProvider";
-
-export type { HttpStatusSink } from "./utils/createHttpStatusSink";

package/src/legacy.ts

@@ -1,35 +0,0 @@
-// Legacy entry point — React 18+
-//
-// SSR-aware components/hooks live at `@real-router/react/legacy/ssr`
-// (subset of the React 19+ `/ssr` surface — `<Await>` is excluded since
-// it depends on `use(promise)`).
-
-// Components
-export { Link } from "./components/Link";
-
-export { RouterErrorBoundary } from "./components/RouterErrorBoundary";
-
-// Hooks
-export { useRouteNode } from "./hooks/useRouteNode";
-
-export { useRoute } from "./hooks/useRoute";
-
-export { useNavigator } from "./hooks/useNavigator";
-
-export { useRouter } from "./hooks/useRouter";
-
-export { useRouteUtils } from "./hooks/useRouteUtils";
-
-export { useRouterTransition } from "./hooks/useRouterTransition";
-
-// Context
-export { RouterProvider } from "./RouterProvider";
-
-// Types
-export type { LinkProps } from "./types";
-
-export type { RouterErrorBoundaryProps } from "./components/RouterErrorBoundary";
-
-export type { Navigator } from "@real-router/core";
-
-export type { RouterTransitionSnapshot } from "@real-router/sources";

package/src/ssr.react-server.ts

@@ -1,21 +0,0 @@
-// SSR-feature entry — type-only re-exports under `react-server` condition.
-//
-// Server Components that consume `<ClientOnly>`/`<ServerOnly>`/`<Await>`/
-// `<Streamed>` props (e.g. for typing wrapper components rendered server-side)
-// import the prop types from `@real-router/react/ssr`. Under the
-// `react-server` condition this entry resolves to types only — no client
-// runtime is pulled into the Server Component bundle.
-
-export type { ClientOnlyProps } from "./components/ClientOnly";
-
-export type { ServerOnlyProps } from "./components/ServerOnly";
-
-export type { AwaitProps } from "./components/Await";
-
-export type { StreamedProps } from "./components/Streamed";
-
-export type { HttpStatusCodeProps } from "./components/HttpStatusCode";
-
-export type { HttpStatusProviderProps } from "./components/HttpStatusProvider";
-
-export type { HttpStatusSink } from "./utils/createHttpStatusSink";