@real-router/react 0.27.2 → 0.27.4

package/src/RouterProvider.tsx

@@ -1,148 +0,0 @@
-import { getNavigator } from "@real-router/core";
-import { createRouteSource } from "@real-router/sources";
-import { useEffect, useMemo, useSyncExternalStore } from "react";
-
-import { NavigatorContext, RouteContext, RouterContext } from "./context";
-import {
-  createRouteAnnouncer,
-  createScrollRestoration,
-  createScrollSpy,
-  createViewTransitions,
-} from "./dom-utils";
-
-import type { ScrollRestorationOptions, ScrollSpyOptions } from "./dom-utils";
-import type { Router } from "@real-router/core";
-import type { FC, ReactNode } from "react";
-
-export interface RouteProviderProps {
-  router: Router;
-  children: ReactNode;
-  announceNavigation?: boolean;
-  scrollRestoration?: ScrollRestorationOptions;
-  scrollSpy?: ScrollSpyOptions;
-  viewTransitions?: boolean;
-}
-
-export const RouterProvider: FC<RouteProviderProps> = ({
-  router,
-  children,
-  announceNavigation,
-  scrollRestoration,
-  scrollSpy,
-  viewTransitions,
-}) => {
-  useEffect(() => {
-    if (!announceNavigation) {
-      return;
-    }
-
-    const announcer = createRouteAnnouncer(router);
-
-    return () => {
-      announcer.destroy();
-    };
-  }, [announceNavigation, router]);
-
-  // Primitive deps so inline `{ mode: "restore" }` doesn't thrash on every
-  // render. scrollContainer is a getter invoked lazily on every event inside
-  // the utility — swapping its reference doesn't change the resolved element,
-  // so we intentionally omit it from deps to keep inline getters stable.
-  const srMode = scrollRestoration?.mode;
-  const srAnchor = scrollRestoration?.anchorScrolling;
-  const srBehavior = scrollRestoration?.behavior;
-  const srStorageKey = scrollRestoration?.storageKey;
-  const srEnabled = scrollRestoration !== undefined;
-
-  useEffect(() => {
-    if (!srEnabled) {
-      return;
-    }
-
-    const sr = createScrollRestoration(router, {
-      mode: srMode,
-      anchorScrolling: srAnchor,
-      behavior: srBehavior,
-      storageKey: srStorageKey,
-      // srEnabled check above guarantees scrollRestoration is defined.
-      scrollContainer: scrollRestoration.scrollContainer,
-    });
-
-    return () => {
-      sr.destroy();
-    };
-    // scrollRestoration (for scrollContainer) omitted — see comment above.
-    // eslint-disable-next-line @eslint-react/exhaustive-deps
-  }, [router, srEnabled, srMode, srAnchor, srBehavior, srStorageKey]);
-
-  const spySelector = scrollSpy?.selector;
-  const spyRootMargin = scrollSpy?.rootMargin;
-  const spyEnabled =
-    scrollSpy !== undefined && spySelector !== undefined && spySelector !== "";
-
-  useEffect(() => {
-    if (!spyEnabled) {
-      return;
-    }
-
-    const spy = createScrollSpy(router, {
-      selector: spySelector,
-      rootMargin: spyRootMargin,
-      scrollContainer: scrollSpy.scrollContainer,
-    });
-
-    return () => {
-      spy.destroy();
-    };
-    // scrollSpy (for scrollContainer) omitted — same rationale as
-    // scrollRestoration above: getter is invoked lazily inside the utility,
-    // identity changes don't affect resolution.
-    // eslint-disable-next-line @eslint-react/exhaustive-deps
-  }, [router, spyEnabled, spySelector, spyRootMargin]);
-
-  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:
-  // subscribe connects to router on first listener, unsubscribes on last.
-  // This is Strict Mode safe — no useEffect cleanup needed.
-  const store = useMemo(() => createRouteSource(router), [router]);
-  // Use snapshot reference directly. createRouteSource via stabilizeState
-  // returns the SAME snapshot reference when route.path is unchanged, so
-  // useMemo below sees stable deps for idempotent navigations and
-  // RouteContext consumers do not re-render.
-  const snapshot = useSyncExternalStore(
-    store.subscribe,
-    store.getSnapshot,
-    store.getSnapshot, // SSR: router returns same state on server and client
-  );
-
-  const routeContextValue = useMemo(
-    () => ({
-      navigator,
-      route: snapshot.route,
-      previousRoute: snapshot.previousRoute,
-    }),
-    [navigator, snapshot],
-  );
-
-  return (
-    <RouterContext.Provider value={router}>
-      <NavigatorContext.Provider value={navigator}>
-        <RouteContext.Provider value={routeContextValue}>
-          {children}
-        </RouteContext.Provider>
-      </NavigatorContext.Provider>
-    </RouterContext.Provider>
-  );
-};

package/src/components/Await.tsx

@@ -1,46 +0,0 @@
-import { use } from "react";
-
-import { useDeferred } from "../hooks/useDeferred";
-
-import type { ReactNode } from "react";
-
-export interface AwaitProps<T> {
-  /** Deferred key declared in the loader's `defer({ deferred: { <name>: ... } })`. */
-  readonly name: string;
-  /** Render the resolved value. Suspends while pending; throws inside the
-   * nearest Error Boundary on rejection. */
-  readonly children: (value: T) => ReactNode;
-}
-
-/**
- * Ergonomic wrapper around `useDeferred(name)` + React 19's `use(promise)`.
- *
- * ```tsx
- * <Suspense fallback={<Spinner />}>
- *   <Await<Review[]> name="reviews">
- *     {(reviews) => <ReviewList items={reviews} />}
- *   </Await>
- * </Suspense>
- * ```
- *
- * Equivalent to:
- *
- * ```tsx
- * function Inner() {
- *   const reviews = use(useDeferred<Review[]>("reviews"));
- *   return <ReviewList items={reviews} />;
- * }
- * ```
- *
- * Pick `<Await>` for cross-adapter consistency with the SvelteKit
- * `{#await}` / Solid `<Await/>` shape; pick the inline `use(useDeferred(...))`
- * form if you prefer one fewer abstraction.
- */
-export function Await<T = unknown>({
-  name,
-  children,
-}: AwaitProps<T>): ReactNode {
-  const value = use(useDeferred<T>(name));
-
-  return children(value);
-}

package/src/components/ClientOnly.tsx

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

package/src/components/HttpStatusCode.tsx

@@ -1,66 +0,0 @@
-import { useContext } from "react";
-
-import { HttpStatusContext } from "./HttpStatusProvider";
-
-import type { ReactNode } from "react";
-
-export interface HttpStatusCodeProps {
-  /** HTTP status to apply to the response. Common values: 404, 410, 451, 503. */
-  readonly code: number;
-}
-
-/**
- * Render-time HTTP status declaration. Mount inside a route component (typical
- * use case: a glob `*` route's NotFound page) when the status is decided by
- * the rendered tree rather than a loader.
- *
- * Writes `code` to the nearest `<HttpStatusProvider>`'s sink during render and
- * returns `null`. With no provider mounted (the standard client-side case)
- * the component is a silent no-op — same component tree hydrates without
- * touching the DOM or warning about mismatches.
- *
- * Loader-driven errors (`LoaderNotFound` → 404, `LoaderRedirect` → 30x) keep
- * working as before; this component covers render-time decisions only.
- *
- * Last write wins when several `<HttpStatusCode />` instances mount in the
- * same render pass — sink reflects the last component that ran.
- *
- * ```tsx
- * // entry-server.tsx
- * import { renderToString } from "react-dom/server";
- * import { createHttpStatusSink, HttpStatusProvider } from "@real-router/react/ssr";
- *
- * const sink = createHttpStatusSink();
- * const html = renderToString(
- *   <HttpStatusProvider sink={sink}>
- *     <RouterProvider router={router}>
- *       <App />
- *     </RouterProvider>
- *   </HttpStatusProvider>,
- * );
- * response.status(sink.code ?? 200).send(html);
- * ```
- *
- * **Streaming SSR (`renderToReadableStream`):** the response status MUST be
- * sent before the first body byte flushes. If `<HttpStatusCode />` is mounted
- * inside a late-resolving `<Suspense>` boundary, the sink write may happen
- * AFTER the headers are already on the wire — the override is then lost.
- * Either mount the component in the shell (above every `<Suspense>` that
- * could delay it) or `await stream.allReady` before reading `sink.code`
- * (which forfeits streaming benefits). For non-streaming SSR
- * (`renderToString`) there is no such ordering concern.
- *
- * **Valid `code` range:** Node's `res.end()` throws `Invalid status code` on
- * `NaN`, `0`, negative values, or values `> 999` — this surfaces as a 5xx /
- * dropped connection, not silent corruption. Pass a real HTTP status integer
- * (commonly 4xx/5xx; 100-999 is what Node accepts).
- */
-export function HttpStatusCode({ code }: HttpStatusCodeProps): ReactNode {
-  const sink = useContext(HttpStatusContext);
-
-  if (sink) {
-    sink.code = code;
-  }
-
-  return null;
-}

package/src/components/HttpStatusProvider.tsx

@@ -1,26 +0,0 @@
-import { createContext } from "react";
-
-import type { HttpStatusSink } from "../utils/createHttpStatusSink";
-import type { ReactNode } from "react";
-
-export const HttpStatusContext = createContext<HttpStatusSink | null>(null);
-
-export interface HttpStatusProviderProps {
-  readonly sink: HttpStatusSink;
-  readonly children: ReactNode;
-}
-
-export function HttpStatusProvider({
-  sink,
-  children,
-}: HttpStatusProviderProps): ReactNode {
-  // `<HttpStatusContext.Provider value>` (not the React 19 `<HttpStatusContext value>`
-  // shorthand) — same component file is exported via `/legacy/ssr` for React 18
-  // consumers, where the shorthand throws "Element type is invalid: expected
-  // a string but got: object".
-  return (
-    <HttpStatusContext.Provider value={sink}>
-      {children}
-    </HttpStatusContext.Provider>
-  );
-}

package/src/components/InkLink.tsx

@@ -1,134 +0,0 @@
-import { Text, useFocus, useInput } from "ink";
-import { memo } from "react";
-
-import { EMPTY_OPTIONS, EMPTY_PARAMS } from "../constants";
-import { shallowEqual } from "../dom-utils";
-import { useIsActiveRoute } from "../hooks/useIsActiveRoute";
-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>,
-): boolean {
-  return (
-    prev.routeName === next.routeName &&
-    prev.activeStrict === next.activeStrict &&
-    prev.ignoreQueryParams === next.ignoreQueryParams &&
-    prev.color === next.color &&
-    prev.activeColor === next.activeColor &&
-    prev.focusColor === next.focusColor &&
-    prev.inverse === next.inverse &&
-    prev.activeInverse === next.activeInverse &&
-    prev.focusInverse === next.focusInverse &&
-    prev.id === next.id &&
-    prev.autoFocus === next.autoFocus &&
-    prev.onSelect === next.onSelect &&
-    prev.children === next.children &&
-    shallowEqual(prev.routeParams, next.routeParams) &&
-    shallowEqual(prev.routeOptions, next.routeOptions)
-  );
-}
-
-const InkLinkImpl: FC<InkLinkProps> = ({
-  routeName,
-  routeParams = EMPTY_PARAMS,
-  routeOptions = EMPTY_OPTIONS,
-  activeStrict = false,
-  ignoreQueryParams = true,
-  color,
-  activeColor,
-  focusColor,
-  inverse,
-  activeInverse,
-  focusInverse,
-  id,
-  autoFocus,
-  onSelect,
-  children,
-}) => {
-  const router = useRouter();
-  const { isFocused } = useFocus({
-    ...(id !== undefined && { id }),
-    ...(autoFocus !== undefined && { autoFocus }),
-  });
-  const isRouteActive = useIsActiveRoute(
-    routeName,
-    routeParams,
-    activeStrict,
-    ignoreQueryParams,
-  );
-
-  // 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) {
-        onSelect?.();
-        router.navigate(routeName, routeParams, routeOptions).catch(() => {});
-      }
-    },
-    { isActive: isFocused },
-  );
-
-  const finalColor = pickPriority(
-    isFocused,
-    isRouteActive,
-    focusColor,
-    activeColor,
-    color,
-  );
-  const finalInverse = pickPriority(
-    isFocused,
-    isRouteActive,
-    focusInverse,
-    activeInverse,
-    inverse,
-  );
-
-  const textProps: { color?: string; inverse?: boolean } = {};
-
-  if (finalColor !== undefined) {
-    textProps.color = finalColor;
-  }
-
-  if (finalInverse !== undefined) {
-    textProps.inverse = finalInverse;
-  }
-
-  return <Text {...textProps}>{children}</Text>;
-};
-
-export const InkLink: FC<InkLinkProps> = memo(
-  InkLinkImpl,
-  areInkLinkPropsEqual,
-);
-
-InkLink.displayName = "InkLink";

package/src/components/InkRouterProvider.tsx

@@ -1,9 +0,0 @@
-import { RouterProvider } from "../RouterProvider";
-
-import type { InkRouterProviderProps } from "../ink-types";
-import type { FC } from "react";
-
-export const InkRouterProvider: FC<InkRouterProviderProps> = ({
-  router,
-  children,
-}) => <RouterProvider router={router}>{children}</RouterProvider>;

package/src/components/Link.tsx

@@ -1,117 +0,0 @@
-import { memo, useMemo } from "react";
-
-import { EMPTY_PARAMS, EMPTY_OPTIONS } from "../constants";
-import {
-  shouldNavigate,
-  buildHref,
-  buildActiveClassName,
-  navigateWithHash,
-  shallowEqual,
-} from "../dom-utils";
-import { useIsActiveRoute } from "../hooks/useIsActiveRoute";
-import { useRouter } from "../hooks/useRouter";
-
-import type { LinkProps } from "../types";
-import type { FC, MouseEvent } from "react";
-
-function areLinkPropsEqual(
-  prev: Readonly<LinkProps>,
-  next: Readonly<LinkProps>,
-): boolean {
-  return (
-    prev.routeName === next.routeName &&
-    prev.className === next.className &&
-    prev.activeClassName === next.activeClassName &&
-    prev.activeStrict === next.activeStrict &&
-    prev.ignoreQueryParams === next.ignoreQueryParams &&
-    prev.onClick === next.onClick &&
-    prev.target === next.target &&
-    prev.style === next.style &&
-    prev.children === next.children &&
-    prev.hash === next.hash &&
-    shallowEqual(prev.routeParams, next.routeParams) &&
-    shallowEqual(prev.routeOptions, next.routeOptions)
-  );
-}
-
-const LinkImpl: FC<LinkProps> = ({
-  routeName,
-  routeParams = EMPTY_PARAMS,
-  routeOptions = EMPTY_OPTIONS,
-  className,
-  activeClassName = "active",
-  activeStrict = false,
-  ignoreQueryParams = true,
-  hash,
-  onClick,
-  target,
-  children,
-  ...props
-}) => {
-  // memo + areLinkPropsEqual guarantees that on bail-out the component does
-  // not render; on render, routeParams/routeOptions either changed reference
-  // (true change) or comparator failed (e.g., BigInt fallback to identity),
-  // so they're safe to use directly in hook deps.
-
-  const router = useRouter();
-
-  // When `hash` prop is set, active state requires both route AND hash to
-  // match (#532). Without this, three tab links sharing routeName="settings"
-  // would all be marked active by route-name alone, defeating tab semantics.
-  const isActive = useIsActiveRoute(
-    routeName,
-    routeParams,
-    activeStrict,
-    ignoreQueryParams,
-    hash,
-  );
-
-  // 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);
-
-  // 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 (evt.defaultPrevented) {
-        return;
-      }
-    }
-
-    if (!shouldNavigate(evt.nativeEvent) || target === "_blank") {
-      return;
-    }
-
-    evt.preventDefault();
-    navigateWithHash(router, routeName, routeParams, hash, routeOptions).catch(
-      () => {},
-    );
-  };
-
-  // 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 (
-    <a {...props} href={href} className={finalClassName} onClick={handleClick}>
-      {children}
-    </a>
-  );
-};
-
-export const Link: FC<LinkProps> = memo(LinkImpl, areLinkPropsEqual);
-
-Link.displayName = "Link";

package/src/components/RouterErrorBoundary.tsx

@@ -1,69 +0,0 @@
-import { createDismissableError } from "@real-router/sources";
-import {
-  useEffect,
-  useLayoutEffect,
-  useMemo,
-  useRef,
-  useSyncExternalStore,
-} from "react";
-
-import { useRouter } from "../hooks/useRouter";
-
-import type { RouterError, State } from "@real-router/core";
-import type { ReactElement, ReactNode } from "react";
-
-export interface RouterErrorBoundaryProps {
-  readonly children: ReactNode;
-  readonly fallback: (error: RouterError, resetError: () => void) => ReactNode;
-  readonly onError?: (
-    error: RouterError,
-    toRoute: State | null,
-    fromRoute: State | null,
-  ) => void;
-}
-
-export function RouterErrorBoundary({
-  children,
-  fallback,
-  onError,
-}: RouterErrorBoundaryProps): ReactElement {
-  const router = useRouter();
-  // 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,
-    store.getSnapshot,
-  );
-
-  const onErrorRef = useRef(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) {
-      onErrorRef.current?.(
-        snapshot.error,
-        snapshot.toRoute,
-        snapshot.fromRoute,
-      );
-    }
-    // eslint-disable-next-line @eslint-react/exhaustive-deps -- onError tracked via ref, snapshot fields accessed inside callback
-  }, [snapshot.version]);
-
-  return (
-    <>
-      {children}
-      {snapshot.error ? fallback(snapshot.error, snapshot.resetError) : null}
-    </>
-  );
-}

package/src/components/ServerOnly.tsx

@@ -1,26 +0,0 @@
-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;
-}