@real-router/react 0.27.2 → 0.27.4

package/src/components/Streamed.tsx

@@ -1,30 +0,0 @@
-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

@@ -1,69 +0,0 @@
-import { useMemo, useRef } from "react";
-
-import { Match, NotFound, Self } from "./components";
-import { buildRenderList, collectElements } from "./helpers";
-import { useRouteNode } from "../../../hooks/useRouteNode";
-
-import type { RouteViewProps } from "./types";
-import type { ReactElement } from "react";
-
-function RouteViewRoot({
-  nodeName,
-  children,
-}: Readonly<RouteViewProps>): ReactElement | null {
-  const { route } = useRouteNode(nodeName);
-  const hasBeenActivatedRef = useRef<Set<string> | null>(null);
-
-  // 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.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[] = [];
-
-    collectElements(children, collected);
-
-    return collected;
-  }, [children]);
-
-  if (!route) {
-    return null;
-  }
-
-  const { rendered } = buildRenderList(
-    elements,
-    route.name,
-    nodeName,
-    // eslint-disable-next-line @eslint-react/refs -- stable Set ref read for keepAlive tracking (never reassigned)
-    hasBeenActivatedRef.current,
-  );
-
-  if (rendered.length > 0) {
-    return <>{rendered}</>;
-  }
-
-  return null;
-}
-
-RouteViewRoot.displayName = "RouteView";
-
-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,19 +0,0 @@
-import type { MatchProps, NotFoundProps, SelfProps } from "./types";
-
-export function Match(_props: MatchProps): null {
-  return 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;
-}
-
-NotFound.displayName = "RouteView.NotFound";

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

@@ -1,231 +0,0 @@
-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, Self } from "./components";
-
-import type { MatchProps, NotFoundProps, SelfProps } from "./types";
-import type { ReactElement, ReactNode } from "react";
-
-const MARKER_TYPES: ReadonlySet<unknown> = new Set([Match, Self, NotFound]);
-
-interface FallbackSlots {
-  selfChildren: ReactNode;
-  selfFallback: ReactNode | undefined;
-  selfFound: boolean;
-  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,
-  exact: boolean,
-): boolean {
-  if (fullSegmentName === "") {
-    return false;
-  }
-
-  if (exact) {
-    return routeName === fullSegmentName;
-  }
-
-  return startsWithSegment(routeName, fullSegmentName);
-}
-
-export function collectElements(
-  children: ReactNode,
-  result: ReactElement[],
-): void {
-  // 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)) {
-      return;
-    }
-
-    if (MARKER_TYPES.has(child.type)) {
-      result.push(child);
-    } else {
-      collectElements(
-        (child.props as { readonly children: ReactNode }).children,
-        result,
-      );
-    }
-  });
-}
-
-function renderSlotElement(
-  slotChildren: ReactNode,
-  key: string,
-  keepAlive: boolean,
-  mode: "visible" | "hidden",
-  fallback?: ReactNode,
-): ReactElement {
-  const content =
-    fallback === undefined ? (
-      slotChildren
-    ) : (
-      <Suspense fallback={fallback}>{slotChildren}</Suspense>
-    );
-
-  if (keepAlive) {
-    return (
-      <Activity mode={mode} key={key}>
-        {content}
-      </Activity>
-    );
-  }
-
-  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 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);
-
-  if (isActive) {
-    hasBeenActivated.add(fullSegmentName);
-
-    return {
-      rendered: renderSlotElement(
-        matchProps.children,
-        fullSegmentName,
-        keepAlive,
-        "visible",
-        fallback,
-      ),
-      matched: true,
-    };
-  }
-
-  if (keepAlive && hasBeenActivated.has(fullSegmentName)) {
-    return {
-      rendered: renderSlotElement(
-        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,
-        SELF_KEY,
-        false,
-        "visible",
-        slots.selfFallback,
-      ),
-    );
-
-    return;
-  }
-
-  if (routeName === UNKNOWN_ROUTE && slots.notFoundChildren !== null) {
-    rendered.push(
-      <Fragment key={NOT_FOUND_KEY}>{slots.notFoundChildren}</Fragment>,
-    );
-  }
-}
-
-export function buildRenderList(
-  elements: ReactElement[],
-  routeName: string,
-  nodeName: string,
-  hasBeenActivated: Set<string>,
-): { rendered: ReactElement[]; activeMatchFound: boolean } {
-  const slots: FallbackSlots = {
-    selfChildren: null,
-    selfFallback: undefined,
-    selfFound: false,
-    notFoundChildren: null,
-  };
-  let activeMatchFound = false;
-  const rendered: ReactElement[] = [];
-
-  for (const child of elements) {
-    if (recordFallback(child, slots)) {
-      continue;
-    }
-
-    const result = processMatch(
-      child,
-      routeName,
-      nodeName,
-      hasBeenActivated,
-      activeMatchFound,
-    );
-
-    if (result.matched) {
-      activeMatchFound = true;
-    }
-
-    if (result.rendered !== null) {
-      rendered.push(result.rendered);
-    }
-  }
-
-  if (!activeMatchFound) {
-    appendFallback(rendered, routeName, nodeName, slots);
-  }
-
-  return { rendered, activeMatchFound };
-}

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

@@ -1,8 +0,0 @@
-export { RouteView } from "./RouteView";
-
-export type {
-  RouteViewProps,
-  RouteViewMatchProps,
-  RouteViewSelfProps,
-  RouteViewNotFoundProps,
-} from "./RouteView";

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

@@ -1,38 +0,0 @@
-import type { ReactNode } from "react";
-
-export interface RouteViewProps {
-  /** Route tree node name to subscribe to. "" for root. */
-  readonly nodeName: string;
-  /** <RouteView.Match>, <RouteView.Self>, and <RouteView.NotFound> elements. */
-  readonly children: ReactNode;
-}
-
-export interface MatchProps {
-  /** Route segment to match against. */
-  readonly segment: string;
-  /** Exact match only (no descendants). Defaults to false. */
-  readonly exact?: boolean;
-  /** Preserve component state when deactivated (React Activity). Defaults to false. */
-  readonly keepAlive?: boolean;
-  /** Fallback content to show while children are suspended. */
-  readonly fallback?: ReactNode;
-  /** Content to render when matched. */
-  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/constants.ts

@@ -1,10 +0,0 @@
-export const EMPTY_PARAMS = Object.freeze({});
-
-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,14 +0,0 @@
-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);
-
-export const NavigatorContext = createContext<Navigator | null>(null);

package/src/hooks/useDeferred.tsx

@@ -1,34 +0,0 @@
-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,47 +0,0 @@
-import { createActiveRouteSource } from "@real-router/sources";
-import { useMemo, useSyncExternalStore } from "react";
-
-import { useRouter } from "./useRouter";
-
-import type { Params } from "@real-router/core";
-
-export function useIsActiveRoute(
-  routeName: string,
-  params?: Params,
-  strict = false,
-  ignoreQueryParams = true,
-  hash?: string,
-): boolean {
-  const router = useRouter();
-
-  // createActiveRouteSource is per-router + canonical-args cached in
-  // @real-router/sources, so passing params by reference is safe — equivalent
-  // param shapes hit the same cache entry regardless of key order. The
-  // `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 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(
-    store.subscribe,
-    store.getSnapshot,
-    store.getSnapshot,
-  );
-}

package/src/hooks/useNavigator.tsx

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

package/src/hooks/useRoute.tsx

@@ -1,32 +0,0 @@
-import { useContext } from "react";
-
-import { RouteContext } from "../context";
-
-import type { RouteContext as RouteContextType } from "../types";
-import type { Params, State } from "@real-router/core";
-
-/**
- * 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> };
-
-export const useRoute = <P extends Params = Params>(): RouteHookResult<P> => {
-  const routeContext = useContext(RouteContext);
-
-  if (!routeContext) {
-    throw new Error("useRoute must be used within a RouterProvider");
-  }
-
-  if (!routeContext.route) {
-    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 RouteHookResult<P>;
-};