@real-router/react 0.24.1 → 0.26.0

package/src/components/InkLink.tsx

@@ -1,5 +1,5 @@
 import { Text, useFocus, useInput } from "ink";
-import { memo, useCallback } from "react";
+import { memo } from "react";
 
 import { EMPTY_OPTIONS, EMPTY_PARAMS } from "../constants";
 import { shallowEqual } from "../dom-utils";
@@ -9,6 +9,30 @@ import { useRouter } from "../hooks/useRouter";
 import type { InkLinkProps } from "../ink-types";
 import type { FC } from "react";
 
+/**
+ * Pick the most specific value across focus / active / base priority.
+ * Focus wins over active; active wins over base. Each layer falls through
+ * to the next when its value is undefined, matching the original explicit
+ * if/else cascade for both `color` and `inverse`.
+ */
+function pickPriority<T>(
+  isFocused: boolean,
+  isRouteActive: boolean,
+  focusValue: T | undefined,
+  activeValue: T | undefined,
+  baseValue: T | undefined,
+): T | undefined {
+  if (isFocused) {
+    return focusValue ?? activeValue ?? baseValue;
+  }
+
+  if (isRouteActive) {
+    return activeValue ?? baseValue;
+  }
+
+  return baseValue;
+}
+
 function areInkLinkPropsEqual(
   prev: Readonly<InkLinkProps>,
   next: Readonly<InkLinkProps>,
@@ -61,35 +85,33 @@ const InkLinkImpl: FC<InkLinkProps> = ({
     ignoreQueryParams,
   );
 
-  const activate = useCallback(() => {
-    onSelect?.();
-    router.navigate(routeName, routeParams, routeOptions).catch(() => {});
-  }, [onSelect, router, routeName, routeParams, routeOptions]);
-
+  // No useCallback: `useInput` consumes the handler via its own internal
+  // ref; a stable identity provides no cache-bail-out benefit here. Same
+  // reasoning as Link's handleClick.
   useInput(
     (_input, key) => {
       if (key.return) {
-        activate();
+        onSelect?.();
+        router.navigate(routeName, routeParams, routeOptions).catch(() => {});
       }
     },
     { isActive: isFocused },
   );
 
-  let finalColor = color;
-
-  if (isFocused) {
-    finalColor = focusColor ?? activeColor ?? color;
-  } else if (isRouteActive) {
-    finalColor = activeColor ?? color;
-  }
-
-  let finalInverse = inverse;
-
-  if (isFocused) {
-    finalInverse = focusInverse ?? activeInverse ?? inverse;
-  } else if (isRouteActive) {
-    finalInverse = activeInverse ?? inverse;
-  }
+  const finalColor = pickPriority(
+    isFocused,
+    isRouteActive,
+    focusColor,
+    activeColor,
+    color,
+  );
+  const finalInverse = pickPriority(
+    isFocused,
+    isRouteActive,
+    focusInverse,
+    activeInverse,
+    inverse,
+  );
 
   const textProps: { color?: string; inverse?: boolean } = {};
 

package/src/components/Link.tsx

@@ -1,4 +1,4 @@
-import { memo, useCallback, useMemo } from "react";
+import { memo, useMemo } from "react";
 
 import { EMPTY_PARAMS, EMPTY_OPTIONS } from "../constants";
 import {
@@ -66,47 +66,43 @@ const LinkImpl: FC<LinkProps> = ({
     hash,
   );
 
-  const href = useMemo(
-    () =>
-      buildHref(
-        router,
-        routeName,
-        routeParams,
-        hash === undefined ? undefined : { hash },
-      ),
-    [router, routeName, routeParams, hash],
-  );
-
-  const handleClick = useCallback(
-    (evt: MouseEvent<HTMLAnchorElement>) => {
-      if (onClick) {
-        onClick(evt);
+  // No useMemo: outer memo()+shallowEqual prevents Link re-render unless a
+  // prop actually changed. When this body runs, either `hash` differs from
+  // last render or another prop changed — in both cases the `{ hash }` alloc
+  // is unavoidable. The useMemo wrapper added one closure + deps slot per
+  // render without saving an allocation.
+  const hashOption = hash === undefined ? undefined : { hash };
+  const href = buildHref(router, routeName, routeParams, hashOption);
 
-        if (evt.defaultPrevented) {
-          return;
-        }
-      }
+  // useCallback was wasteful: 7 deps recreated the closure on every meaningful
+  // render anyway, and `<a onClick>` does not benefit from a stable function
+  // identity (no child-memo-bail-out chain past it). Inline arrow function is
+  // what React Compiler emits automatically for this shape.
+  const handleClick = (evt: MouseEvent<HTMLAnchorElement>) => {
+    if (onClick) {
+      onClick(evt);
 
-      if (!shouldNavigate(evt.nativeEvent) || target === "_blank") {
+      if (evt.defaultPrevented) {
         return;
       }
+    }
 
-      evt.preventDefault();
-      navigateWithHash(
-        router,
-        routeName,
-        routeParams,
-        hash,
-        routeOptions,
-      ).catch(() => {});
-    },
-    [onClick, target, router, routeName, routeParams, routeOptions, hash],
-  );
+    if (!shouldNavigate(evt.nativeEvent) || target === "_blank") {
+      return;
+    }
+
+    evt.preventDefault();
+    navigateWithHash(router, routeName, routeParams, hash, routeOptions).catch(
+      () => {},
+    );
+  };
 
-  const finalClassName = buildActiveClassName(
-    isActive,
-    activeClassName,
-    className,
+  // Memoize the joined class string. parseTokens + Set + join on every render
+  // adds up on pages with N Links navigating frequently; deps cover every
+  // input the function reads so cache invalidation is exact.
+  const finalClassName = useMemo(
+    () => buildActiveClassName(isActive, activeClassName, className),
+    [isActive, activeClassName, className],
   );
 
   return (

package/src/components/RouterErrorBoundary.tsx

@@ -1,10 +1,16 @@
 import { createDismissableError } from "@real-router/sources";
-import { useEffect, useRef, useSyncExternalStore } from "react";
+import {
+  useEffect,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+  useSyncExternalStore,
+} from "react";
 
 import { useRouter } from "../hooks/useRouter";
 
 import type { RouterError, State } from "@real-router/core";
-import type { ReactNode, JSX } from "react";
+import type { ReactElement, ReactNode } from "react";
 
 export interface RouterErrorBoundaryProps {
   readonly children: ReactNode;
@@ -20,9 +26,12 @@ export function RouterErrorBoundary({
   children,
   fallback,
   onError,
-}: RouterErrorBoundaryProps): JSX.Element {
+}: RouterErrorBoundaryProps): ReactElement {
   const router = useRouter();
-  const store = createDismissableError(router);
+  // Per-router cached in @real-router/sources — the WeakMap lookup is cheap,
+  // but useMemo avoids it entirely on stable-router re-renders (the common
+  // case for boundaries mounted in app shells).
+  const store = useMemo(() => createDismissableError(router), [router]);
   const snapshot = useSyncExternalStore(
     store.subscribe,
     store.getSnapshot,
@@ -31,8 +40,14 @@ export function RouterErrorBoundary({
 
   const onErrorRef = useRef(onError);
 
-  // eslint-disable-next-line @eslint-react/refs -- "latest ref" pattern: sync callback to ref to avoid effect re-runs
-  onErrorRef.current = onError;
+  // "Latest ref" pattern shared with useRouteEnter/useRouteExit: sync the
+  // callback to the ref via useLayoutEffect (synchronous, post-render,
+  // pre-paint) so the snapshot effect below reads the freshest callback
+  // without listing `onError` as a dep — and StrictMode's double-effect
+  // pass writes the same value twice harmlessly.
+  useLayoutEffect(() => {
+    onErrorRef.current = onError;
+  });
 
   useEffect(() => {
     if (snapshot.error) {

package/src/components/ServerOnly.tsx

@@ -0,0 +1,26 @@
+import { useEffect, useState } from "react";
+
+import type { ReactNode } from "react";
+
+export interface ServerOnlyProps {
+  readonly children: ReactNode;
+  readonly fallback?: ReactNode;
+}
+
+export function ServerOnly({
+  children,
+  fallback = null,
+}: ServerOnlyProps): ReactNode {
+  const [mounted, setMounted] = useState(false);
+
+  useEffect(() => {
+    // SSR/hydration boundary: server emits the children branch, client matches
+    // it on first paint, then this effect flips state to swap in the fallback
+    // (or hide entirely). The intentional re-render keeps markup consistent
+    // across renders.
+    // eslint-disable-next-line @eslint-react/set-state-in-effect -- intentional post-hydration swap
+    setMounted(true);
+  }, []);
+
+  return mounted ? fallback : children;
+}

package/src/components/Streamed.tsx

@@ -0,0 +1,30 @@
+import { Suspense } from "react";
+
+import type { ReactNode } from "react";
+
+export interface StreamedProps {
+  /** Shown while any descendant `use(promise)` / `<Await>` is pending. */
+  readonly fallback: ReactNode;
+  readonly children: ReactNode;
+}
+
+/**
+ * Cross-adapter alias for `<Suspense fallback={…}>`. Pairs with `<Await>`
+ * for symmetry with `<Streamed>` boundaries in the SvelteKit / Solid
+ * deferred-data conventions.
+ *
+ * ```tsx
+ * <Streamed fallback={<Spinner />}>
+ *   <Await<Review[]> name="reviews">
+ *     {(reviews) => <ReviewList items={reviews} />}
+ *   </Await>
+ * </Streamed>
+ * ```
+ *
+ * The component is a thin wrapper around React's native `<Suspense>` — no
+ * additional behaviour. Use plain `<Suspense>` directly if you don't need
+ * the cross-framework naming alignment.
+ */
+export function Streamed({ fallback, children }: StreamedProps): ReactNode {
+  return <Suspense fallback={fallback}>{children}</Suspense>;
+}

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

@@ -17,9 +17,15 @@ function RouteViewRoot({
   // eslint-disable-next-line @eslint-react/refs -- lazy init: assign once when null to avoid `new Set()` allocation on every render
   hasBeenActivatedRef.current ??= new Set();
 
-  // Skip the Children.toArray + collectElements traversal when children
-  // reference is unchanged. children only changes when the parent re-renders
-  // with a new ReactNode, so this caches the steady-state.
+  // Skip the Children.forEach + collectElements traversal when the children
+  // reference is unchanged. The common SPA case is a stable JSX tree across
+  // re-renders, so the cache hits on every render except the first.
+  //
+  // Streaming SSR caveat: with `renderToReadableStream`, React may invoke
+  // RouteView multiple times across chunks with a fresh `children` reference
+  // each time. The useMemo misses on each new render and the traversal runs
+  // again — this is the expected SSR cost; the alternative would be build-
+  // time codegen of the static route tree, which is out of scope here.
   const elements = useMemo(() => {
     const collected: ReactElement[] = [];
 

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

@@ -14,6 +14,12 @@ interface FallbackSlots {
   notFoundChildren: ReactNode;
 }
 
+// Fixed keys used by appendFallback to distinguish the Self / NotFound
+// render slots from user-supplied <Match> children. Match render slots key
+// off `fullSegmentName` instead — these two are the only synthetic keys.
+const SELF_KEY = "__route-view-self__";
+const NOT_FOUND_KEY = "__route-view-not-found__";
+
 function isSegmentMatch(
   routeName: string,
   fullSegmentName: string,
@@ -34,10 +40,20 @@ export function collectElements(
   children: ReactNode,
   result: ReactElement[],
 ): void {
-  // eslint-disable-next-line @eslint-react/no-children-to-array
-  for (const child of Children.toArray(children)) {
+  // Recurses into Fragment-like wrappers (anything that isn't Match / Self /
+  // NotFound) to flatten the slot tree. No explicit depth guard: typical
+  // RouteView shape is `<RouteView><Match/>...<NotFound/></RouteView>` —
+  // depth ≤ 3 in real apps. A pathological hand-written tree of N Fragments
+  // recurses N times; the call stack, not this function, is the bound.
+  //
+  // `Children.forEach` iterates without `Children.toArray`'s array allocation
+  // and per-child clone-with-synthetic-key step. We don't read child.key here
+  // (Match/Self/NotFound carry their own segment-derived keys further down),
+  // so the cheaper iterator is functionally equivalent.
+  // eslint-disable-next-line @eslint-react/no-children-for-each -- intentional: collectElements is a render-hot pipeline; toArray's array+key clone is wasteful here
+  Children.forEach(children, (child) => {
     if (!isValidElement(child)) {
-      continue;
+      return;
     }
 
     if (
@@ -52,7 +68,7 @@ export function collectElements(
         result,
       );
     }
-  }
+  });
 }
 
 function renderSlotElement(
@@ -108,12 +124,8 @@ function processMatch(
   hasBeenActivated: Set<string>,
   alreadyActive: boolean,
 ): { rendered: ReactElement | null; matched: boolean } {
-  const {
-    segment,
-    exact = false,
-    keepAlive = false,
-    fallback,
-  } = child.props as MatchProps;
+  const matchProps = child.props as MatchProps;
+  const { segment, exact = false, keepAlive = false, fallback } = matchProps;
   const fullSegmentName = nodeName ? `${nodeName}.${segment}` : segment;
   const isActive =
     !alreadyActive && isSegmentMatch(routeName, fullSegmentName, exact);
@@ -123,7 +135,7 @@ function processMatch(
 
     return {
       rendered: renderSlotElement(
-        (child.props as MatchProps).children,
+        matchProps.children,
         fullSegmentName,
         keepAlive,
         "visible",
@@ -136,7 +148,7 @@ function processMatch(
   if (keepAlive && hasBeenActivated.has(fullSegmentName)) {
     return {
       rendered: renderSlotElement(
-        (child.props as MatchProps).children,
+        matchProps.children,
         fullSegmentName,
         keepAlive,
         "hidden",
@@ -159,7 +171,7 @@ function appendFallback(
     rendered.push(
       renderSlotElement(
         slots.selfChildren,
-        "__route-view-self__",
+        SELF_KEY,
         false,
         "visible",
         slots.selfFallback,
@@ -171,9 +183,7 @@ function appendFallback(
 
   if (routeName === UNKNOWN_ROUTE && slots.notFoundChildren !== null) {
     rendered.push(
-      <Fragment key="__route-view-not-found__">
-        {slots.notFoundChildren}
-      </Fragment>,
+      <Fragment key={NOT_FOUND_KEY}>{slots.notFoundChildren}</Fragment>,
     );
   }
 }

package/src/constants.ts

@@ -1,11 +1,10 @@
-// packages/react/src/constants.ts
-
-/**
- * Stable empty object for default params
- */
 export const EMPTY_PARAMS = Object.freeze({});
 
-/**
- * Stable empty options object
- */
 export const EMPTY_OPTIONS = Object.freeze({});
+
+// Singleton forever-pending promise — module-scope so `useDeferred(unknownKey)`
+// returns a stable reference across calls (Suspense boundary doesn't retry).
+export const NEVER_PROMISE = new Promise<never>(() => {
+  // Intentionally never resolves — surfaces a forever-pending Suspense boundary
+  // when a key is requested that the loader never declared.
+});

package/src/context.ts

@@ -1,10 +1,12 @@
-// packages/react/src/context.ts
-
 import { createContext } from "react";
 
 import type { RouteContext as RouteContextType } from "./types";
 import type { Router, Navigator } from "@real-router/core";
 
+// All three contexts use the `<T | null>` shape with a `null` default. Hooks
+// (useRouter / useRoute / useNavigator) treat a `null` read as
+// "RouterProvider missing" and throw — this surfaces wiring mistakes loudly
+// instead of letting consumers chase an undefined router instance.
 export const RouteContext = createContext<RouteContextType | null>(null);
 
 export const RouterContext = createContext<Router | null>(null);

package/src/hooks/useDeferred.tsx

@@ -0,0 +1,34 @@
+import { NEVER_PROMISE } from "../constants";
+import { useRoute } from "./useRoute";
+
+interface DeferredContext {
+  ssrDataDeferred?: Record<string, Promise<unknown>>;
+}
+
+/**
+ * Read a deferred promise published by `defer({ deferred: { <key>: Promise } })`
+ * inside an SSR data loader.
+ *
+ * - **Server render**: returns the actual loader-returned promise. Combine
+ *   with `<Suspense>` + `use(promise)` for native streaming via React 19's
+ *   `renderToReadableStream`.
+ * - **Post-hydration**: returns a registry-backed promise; the inline
+ *   `<script>__rrDefer__("key", json)</script>` tags emitted by the server
+ *   stream resolve it. `use()` returns synchronously once the registry
+ *   settles.
+ * - **Unknown key**: returns a never-resolving promise — Suspense boundary
+ *   stays in fallback. This surfaces consumer/loader key drift as a visible
+ *   loading state instead of a silent runtime error.
+ *
+ * The hook subscribes to `RouteContext`, so it re-runs on every navigation.
+ * Promise reference identity is stable across renders within the same
+ * navigation — `use()` will not re-suspend on rerenders.
+ */
+export function useDeferred<T = unknown>(key: string): Promise<T> {
+  const { route } = useRoute();
+  const context = route.context as DeferredContext;
+  const deferred = context.ssrDataDeferred;
+  const promise = deferred?.[key];
+
+  return (promise ?? NEVER_PROMISE) as Promise<T>;
+}

package/src/hooks/useIsActiveRoute.tsx

@@ -1,5 +1,5 @@
 import { createActiveRouteSource } from "@real-router/sources";
-import { useSyncExternalStore } from "react";
+import { useMemo, useSyncExternalStore } from "react";
 
 import { useRouter } from "./useRouter";
 
@@ -20,15 +20,23 @@ export function useIsActiveRoute(
   // `hash` argument (#532) is part of the cache key when defined: a Link
   // pointing to `/settings#account` shares its source only with other
   // consumers using the same routeName + params + hash.
+  //
+  // The useMemo wrap skips `canonicalJson(params)` + cache lookup on every
+  // render when all primitive deps and the `params` reference are stable —
+  // the common case once memo()+shallowEqual has bailed out further up
+  // (or when the parent re-renders for a non-Link reason). For inline
+  // `params={{id:1}}` the dep changes per render and the lookup still
+  // runs, but that path was already the slow path before this memo.
   // exactOptionalPropertyTypes forbids `{ hash: undefined }` literally, so
-  // we conditionally include the key only when the caller passed a value.
-  const store = createActiveRouteSource(
-    router,
-    routeName,
-    params,
-    hash === undefined
-      ? { strict, ignoreQueryParams }
-      : { strict, ignoreQueryParams, hash },
+  // we conditionally spread the key only when the caller passed a value.
+  const store = useMemo(
+    () =>
+      createActiveRouteSource(router, routeName, params, {
+        strict,
+        ignoreQueryParams,
+        ...(hash !== undefined && { hash }),
+      }),
+    [router, routeName, params, strict, ignoreQueryParams, hash],
   );
 
   return useSyncExternalStore(

package/src/hooks/useNavigator.tsx

@@ -1,5 +1,3 @@
-// packages/react/src/hooks/useNavigator.tsx
-
 import { useContext } from "react";
 
 import { NavigatorContext } from "../context";

package/src/hooks/useRoute.tsx

@@ -1,5 +1,3 @@
-// packages/react/src/hooks/useRoute.tsx
-
 import { useContext } from "react";
 
 import { RouteContext } from "../context";
@@ -7,10 +5,17 @@ import { RouteContext } from "../context";
 import type { RouteContext as RouteContextType } from "../types";
 import type { Params, State } from "@real-router/core";
 
-export const useRoute = <P extends Params = Params>(): Omit<
+/**
+ * Return shape of `useRoute<P>()` — the context with `route` narrowed to
+ * `State<P>` (non-nullable). Promoting the intersection to a named alias
+ * keeps the function signature and the cast site in sync.
+ */
+type RouteHookResult<P extends Params = Params> = Omit<
   RouteContextType<P>,
   "route"
-> & { route: State<P> } => {
+> & { route: State<P> };
+
+export const useRoute = <P extends Params = Params>(): RouteHookResult<P> => {
   const routeContext = useContext(RouteContext);
 
   if (!routeContext) {
@@ -23,7 +28,5 @@ export const useRoute = <P extends Params = Params>(): Omit<
     );
   }
 
-  return routeContext as Omit<RouteContextType<P>, "route"> & {
-    route: State<P>;
-  };
+  return routeContext as RouteHookResult<P>;
 };

package/src/hooks/useRouter.tsx

@@ -1,5 +1,3 @@
-// packages/react/src/hooks/useRouter.tsx
-
 import { useContext } from "react";
 
 import { RouterContext } from "../context";

package/src/index.react-server.ts

@@ -0,0 +1,33 @@
+// 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,4 +1,9 @@
 // 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";

package/src/legacy.ssr.ts

@@ -0,0 +1,35 @@
+// 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,4 +1,8 @@
 // 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";