@real-router/react 0.14.8 → 0.14.10

package/dist/cjs/RouterProvider-GwajvaK9.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RouterProvider-GwajvaK9.d.ts","names":[],"sources":["../../src/types.ts","../../src/components/Link.tsx","../../src/components/RouterErrorBoundary.tsx","../../src/hooks/useRouter.tsx","../../src/hooks/useNavigator.tsx","../../src/hooks/useRouteUtils.tsx","../../src/hooks/useRoute.tsx","../../src/hooks/useRouteNode.tsx","../../src/hooks/useRouterTransition.tsx","../../src/RouterProvider.tsx"],"mappings":";;;;;;UAQiB,UAAA,WAAqB,MAAA,GAAS,MAAA;EAC7C,KAAA,EAAO,KAAA,CAAM,CAAA;EACb,aAAA,GAAgB,KAAA;AAAA;AAAA,KAGN,YAAA;EACV,SAAA,EAAW,SAAA;AAAA,IACT,UAAA;AAAA,UAEa,SAAA,WACL,MAAA,GAAS,MAAA,UACX,cAAA,CAAe,iBAAA;EACvB,SAAA;EACA,WAAA,GAAc,CAAA;EACd,YAAA,GAAe,iBAAA;EACf,eAAA;EACA,YAAA;EACA,iBAAA;EACA,MAAA;EACA,OAAA,GAAU,iBAAA,CAAkB,iBAAA;EAC5B,WAAA,GAAc,iBAAA,CAAkB,iBAAA;AAAA;;;cCErB,IAAA,EAAM,EAAA,CAAG,SAAA;;;UCvBL,wBAAA;EAAA,SACN,QAAA,EAAU,SAAA;EAAA,SACV,QAAA,GAAW,KAAA,EAAO,WAAA,EAAa,UAAA,iBAA2B,SAAA;EAAA,SAC1D,OAAA,IACP,KAAA,EAAO,WAAA,EACP,OAAA,EAAS,KAAA,SACT,SAAA,EAAW,KAAA;AAAA;AAAA,iBAIC,mBAAA,CAAA;EACd,QAAA;EACA,QAAA;EACA;AAAA,GACC,wBAAA,GAA2B,GAAA,CAAI,OAAA;;;cCbrB,SAAA,QAAgB,MAAA;;;cCAhB,YAAA,QAAmB,SAAA;;;;;;;;AJAhC;;;;;;;;;;;;;;;;;cKuBa,aAAA,QAAoB,UAAA;;;cCvBpB,QAAA,QAAe,YAAA;;;iBCAZ,YAAA,CAAa,QAAA,WAAmB,YAAA;;;iBCDhC,mBAAA,CAAA,GAAuB,wBAAA;;;UCGtB,kBAAA;EACf,MAAA,EAAQ,MAAA;EACR,QAAA,EAAU,SAAA;EACV,kBAAA;AAAA;AAAA,cAGW,cAAA,EAAgB,EAAA,CAAG,kBAAA"}

package/dist/cjs/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/components/modern/RouteView/types.ts","../../src/components/modern/RouteView/components.tsx","../../src/components/modern/RouteView/RouteView.tsx"],"mappings":";;;;;;UAEiB,cAAA;;WAEN,QAAA;;WAEA,QAAA,EAAU,SAAA;AAAA;AAAA,UAGJ,UAAA;;WAEN,OAAA;EAPA;EAAA,SASA,KAAA;EAPU;EAAA,SASV,SAAA;EATmB;EAAA,SAWnB,QAAA,GAAW,SAAA;EARK;EAAA,SAUhB,QAAA,EAAU,SAAA;AAAA;AAAA,UAGJ,aAAA;EATN;EAAA,SAWA,QAAA,EAAU,SAAA;AAAA;;;iBCtBL,KAAA,CAAM,MAAA,EAAQ,UAAA;AAAA,kBAAd,KAAA;EAAA,IAAK,WAAA;AAAA;AAAA,iBAML,QAAA,CAAS,MAAA,EAAQ,aAAA;AAAA,kBAAjB,QAAA;EAAA,IAAQ,WAAA;AAAA;;;iBCCf,aAAA,CAAA;EACP,QAAA;EACA;AAAA,GACC,QAAA,CAAS,cAAA,IAAkB,YAAA;AAAA,kBAHrB,aAAA;EAAA,IAAa,WAAA;AAAA;AAAA,cAgCT,SAAA,SAAS,aAAA"}

package/dist/esm/RouterProvider-BuGQIoZ-.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RouterProvider-BuGQIoZ-.d.mts","names":[],"sources":["../../src/types.ts","../../src/components/Link.tsx","../../src/components/RouterErrorBoundary.tsx","../../src/hooks/useRouter.tsx","../../src/hooks/useNavigator.tsx","../../src/hooks/useRouteUtils.tsx","../../src/hooks/useRoute.tsx","../../src/hooks/useRouteNode.tsx","../../src/hooks/useRouterTransition.tsx","../../src/RouterProvider.tsx"],"mappings":";;;;;;UAQiB,UAAA,WAAqB,MAAA,GAAS,MAAA;EAC7C,KAAA,EAAO,KAAA,CAAM,CAAA;EACb,aAAA,GAAgB,KAAA;AAAA;AAAA,KAGN,YAAA;EACV,SAAA,EAAW,SAAA;AAAA,IACT,UAAA;AAAA,UAEa,SAAA,WACL,MAAA,GAAS,MAAA,UACX,cAAA,CAAe,iBAAA;EACvB,SAAA;EACA,WAAA,GAAc,CAAA;EACd,YAAA,GAAe,iBAAA;EACf,eAAA;EACA,YAAA;EACA,iBAAA;EACA,MAAA;EACA,OAAA,GAAU,iBAAA,CAAkB,iBAAA;EAC5B,WAAA,GAAc,iBAAA,CAAkB,iBAAA;AAAA;;;cCErB,IAAA,EAAM,EAAA,CAAG,SAAA;;;UCvBL,wBAAA;EAAA,SACN,QAAA,EAAU,SAAA;EAAA,SACV,QAAA,GAAW,KAAA,EAAO,WAAA,EAAa,UAAA,iBAA2B,SAAA;EAAA,SAC1D,OAAA,IACP,KAAA,EAAO,WAAA,EACP,OAAA,EAAS,KAAA,SACT,SAAA,EAAW,KAAA;AAAA;AAAA,iBAIC,mBAAA,CAAA;EACd,QAAA;EACA,QAAA;EACA;AAAA,GACC,wBAAA,GAA2B,GAAA,CAAI,OAAA;;;cCbrB,SAAA,QAAgB,MAAA;;;cCAhB,YAAA,QAAmB,SAAA;;;;;;;;AJAhC;;;;;;;;;;;;;;;;;cKuBa,aAAA,QAAoB,UAAA;;;cCvBpB,QAAA,QAAe,YAAA;;;iBCAZ,YAAA,CAAa,QAAA,WAAmB,YAAA;;;iBCDhC,mBAAA,CAAA,GAAuB,wBAAA;;;UCGtB,kBAAA;EACf,MAAA,EAAQ,MAAA;EACR,QAAA,EAAU,SAAA;EACV,kBAAA;AAAA;AAAA,cAGW,cAAA,EAAgB,EAAA,CAAG,kBAAA"}

package/dist/esm/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../../src/components/modern/RouteView/types.ts","../../src/components/modern/RouteView/components.tsx","../../src/components/modern/RouteView/RouteView.tsx"],"mappings":";;;;;;UAEiB,cAAA;;WAEN,QAAA;;WAEA,QAAA,EAAU,SAAA;AAAA;AAAA,UAGJ,UAAA;;WAEN,OAAA;EAPA;EAAA,SASA,KAAA;EAPU;EAAA,SASV,SAAA;EATmB;EAAA,SAWnB,QAAA,GAAW,SAAA;EARK;EAAA,SAUhB,QAAA,EAAU,SAAA;AAAA;AAAA,UAGJ,aAAA;EATN;EAAA,SAWA,QAAA,EAAU,SAAA;AAAA;;;iBCtBL,KAAA,CAAM,MAAA,EAAQ,UAAA;AAAA,kBAAd,KAAA;EAAA,IAAK,WAAA;AAAA;AAAA,iBAML,QAAA,CAAS,MAAA,EAAQ,aAAA;AAAA,kBAAjB,QAAA;EAAA,IAAQ,WAAA;AAAA;;;iBCCf,aAAA,CAAA;EACP,QAAA;EACA;AAAA,GACC,QAAA,CAAS,cAAA,IAAkB,YAAA;AAAA,kBAHrB,aAAA;EAAA,IAAa,WAAA;AAAA;AAAA,cAgCT,SAAA,SAAS,aAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@real-router/react",
-  "version": "0.14.8",
+  "version": "0.14.10",
   "type": "commonjs",
   "description": "React integration for Real-Router",
   "main": "./dist/cjs/index.js",
@@ -15,7 +15,6 @@
   },
   "exports": {
     ".": {
-      "development": "./src/index.ts",
       "types": {
         "import": "./dist/esm/index.d.mts",
         "require": "./dist/cjs/index.d.ts"
@@ -24,7 +23,6 @@
       "require": "./dist/cjs/index.js"
     },
     "./legacy": {
-      "development": "./src/legacy.ts",
       "types": {
         "import": "./dist/esm/legacy.d.mts",
         "require": "./dist/cjs/legacy.d.ts"
@@ -34,7 +32,8 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "src"
   ],
   "homepage": "https://github.com/greydragon888/real-router",
   "repository": {
@@ -63,9 +62,9 @@
   "license": "MIT",
   "sideEffects": false,
   "dependencies": {
-    "@real-router/core": "^0.45.1",
-    "@real-router/route-utils": "^0.1.12",
-    "@real-router/sources": "^0.4.2"
+    "@real-router/core": "^0.46.0",
+    "@real-router/route-utils": "^0.1.14",
+    "@real-router/sources": "^0.4.4"
   },
   "devDependencies": {
     "@testing-library/dom": "10.4.1",
@@ -73,8 +72,8 @@
     "@testing-library/react": "16.3.2",
     "@testing-library/user-event": "14.6.1",
     "vitest-react-profiler": "1.12.0",
-    "@real-router/browser-plugin": "^0.11.5",
-    "dom-utils": "^0.2.7"
+    "@real-router/browser-plugin": "^0.11.7",
+    "dom-utils": "^0.2.8"
   },
   "peerDependencies": {
     "@types/react": ">=18.0.0",
@@ -85,10 +84,11 @@
   "scripts": {
     "build": "tsdown --config-loader unrun",
     "test": "vitest",
+    "test:properties": "vitest run --config vitest.config.properties.mts",
     "test:stress": "vitest run --config vitest.config.stress.mts",
     "type-check": "tsc --noEmit",
     "lint": "eslint --cache --ext .ts,.tsx src/ tests/ --fix --max-warnings 0",
-    "lint:package": "bash ../../scripts/publint-filter.sh",
+    "lint:package": "publint",
     "lint:types": "attw --pack .",
     "build:dist-only": "tsdown --config-loader unrun"
   }

package/src/RouterProvider.tsx

@@ -0,0 +1,58 @@
+import { getNavigator } from "@real-router/core";
+import { createRouteSource } from "@real-router/sources";
+import { createRouteAnnouncer } from "dom-utils";
+import { useEffect, useMemo, useSyncExternalStore } from "react";
+
+import { NavigatorContext, RouteContext, RouterContext } from "./context";
+
+import type { Router } from "@real-router/core";
+import type { FC, ReactNode } from "react";
+
+export interface RouteProviderProps {
+  router: Router;
+  children: ReactNode;
+  announceNavigation?: boolean;
+}
+
+export const RouterProvider: FC<RouteProviderProps> = ({
+  router,
+  children,
+  announceNavigation,
+}) => {
+  useEffect(() => {
+    if (!announceNavigation) {
+      return;
+    }
+
+    const announcer = createRouteAnnouncer(router);
+
+    return () => {
+      announcer.destroy();
+    };
+  }, [announceNavigation, router]);
+
+  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]);
+  const { route, previousRoute } = useSyncExternalStore(
+    store.subscribe,
+    store.getSnapshot,
+    store.getSnapshot, // SSR: router returns same state on server and client
+  );
+
+  const routeContextValue = useMemo(
+    () => ({ navigator, route, previousRoute }),
+    [navigator, route, previousRoute],
+  );
+
+  return (
+    <RouterContext value={router}>
+      <NavigatorContext value={navigator}>
+        <RouteContext value={routeContextValue}>{children}</RouteContext>
+      </NavigatorContext>
+    </RouterContext>
+  );
+};

package/src/components/Link.tsx

@@ -0,0 +1,101 @@
+import { shouldNavigate, buildHref, buildActiveClassName } from "dom-utils";
+import { memo, useCallback, useMemo } from "react";
+
+import { EMPTY_PARAMS, EMPTY_OPTIONS } from "../constants";
+import { useIsActiveRoute } from "../hooks/useIsActiveRoute";
+import { useRouter } from "../hooks/useRouter";
+import { useStableValue } from "../hooks/useStableValue";
+
+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 &&
+    JSON.stringify(prev.routeParams) === JSON.stringify(next.routeParams) &&
+    JSON.stringify(prev.routeOptions) === JSON.stringify(next.routeOptions)
+  );
+}
+
+export const Link: FC<LinkProps> = memo(
+  ({
+    routeName,
+    routeParams = EMPTY_PARAMS,
+    routeOptions = EMPTY_OPTIONS,
+    className,
+    activeClassName = "active",
+    activeStrict = false,
+    ignoreQueryParams = true,
+    onClick,
+    target,
+    children,
+    ...props
+  }) => {
+    const router = useRouter();
+
+    const stableParams = useStableValue(routeParams);
+    const stableOptions = useStableValue(routeOptions);
+
+    const isActive = useIsActiveRoute(
+      routeName,
+      stableParams,
+      activeStrict,
+      ignoreQueryParams,
+    );
+
+    const href = useMemo(
+      () => buildHref(router, routeName, stableParams),
+      [router, routeName, stableParams],
+    );
+
+    const handleClick = useCallback(
+      (evt: MouseEvent<HTMLAnchorElement>) => {
+        if (onClick) {
+          onClick(evt);
+
+          if (evt.defaultPrevented) {
+            return;
+          }
+        }
+
+        if (!shouldNavigate(evt.nativeEvent) || target === "_blank") {
+          return;
+        }
+
+        evt.preventDefault();
+        router.navigate(routeName, stableParams, stableOptions).catch(() => {});
+      },
+      [onClick, target, router, routeName, stableParams, stableOptions],
+    );
+
+    const finalClassName = useMemo(
+      () => buildActiveClassName(isActive, activeClassName, className),
+      [isActive, activeClassName, className],
+    );
+
+    return (
+      <a
+        {...props}
+        href={href}
+        className={finalClassName}
+        onClick={handleClick}
+      >
+        {children}
+      </a>
+    );
+  },
+  areLinkPropsEqual,
+);
+
+Link.displayName = "Link";

package/src/components/RouterErrorBoundary.tsx

@@ -0,0 +1,55 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+
+import { useRouterError } from "../hooks/useRouterError";
+
+import type { RouterError, State } from "@real-router/core";
+import type { ReactNode, JSX } 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): JSX.Element {
+  const snapshot = useRouterError();
+  const [dismissedVersion, setDismissedVersion] = useState(-1);
+
+  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;
+
+  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]);
+
+  const visibleError =
+    snapshot.version > dismissedVersion ? snapshot.error : null;
+
+  const resetError = useCallback(() => {
+    setDismissedVersion(snapshot.version);
+  }, [snapshot.version]);
+
+  return (
+    <>
+      {children}
+      {visibleError ? fallback(visibleError, resetError) : null}
+    </>
+  );
+}

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

@@ -0,0 +1,48 @@
+import { useRef } from "react";
+
+import { Match, NotFound } 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>>(new Set());
+
+  if (!route) {
+    return null;
+  }
+
+  const elements: ReactElement[] = [];
+
+  collectElements(children, elements);
+
+  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, NotFound });
+
+export type {
+  RouteViewProps,
+  MatchProps as RouteViewMatchProps,
+  NotFoundProps as RouteViewNotFoundProps,
+} from "./types";

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

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

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

@@ -0,0 +1,130 @@
+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 type { MatchProps, NotFoundProps } from "./types";
+import type { ReactElement, ReactNode } from "react";
+
+function isSegmentMatch(
+  routeName: string,
+  fullSegmentName: string,
+  exact: boolean,
+): boolean {
+  if (exact) {
+    return routeName === fullSegmentName;
+  }
+
+  return startsWithSegment(routeName, fullSegmentName);
+}
+
+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)) {
+    if (!isValidElement(child)) {
+      continue;
+    }
+
+    if (child.type === Match || child.type === NotFound) {
+      result.push(child);
+    } else {
+      collectElements(
+        (child.props as { readonly children: ReactNode }).children,
+        result,
+      );
+    }
+  }
+}
+
+function renderMatchElement(
+  matchChildren: ReactNode,
+  fullSegmentName: string,
+  keepAlive: boolean,
+  mode: "visible" | "hidden",
+  fallback?: ReactNode,
+): ReactElement {
+  const content =
+    fallback === undefined ? (
+      matchChildren
+    ) : (
+      <Suspense fallback={fallback}>{matchChildren}</Suspense>
+    );
+
+  if (keepAlive) {
+    return (
+      <Activity mode={mode} key={fullSegmentName}>
+        {content}
+      </Activity>
+    );
+  }
+
+  return <Fragment key={fullSegmentName}>{content}</Fragment>;
+}
+
+export function buildRenderList(
+  elements: ReactElement[],
+  routeName: string,
+  nodeName: string,
+  hasBeenActivated: Set<string>,
+): { rendered: ReactElement[]; activeMatchFound: boolean } {
+  let notFoundChildren: ReactNode = null;
+  let activeMatchFound = false;
+  const rendered: ReactElement[] = [];
+
+  for (const child of elements) {
+    if (child.type === NotFound) {
+      notFoundChildren = (child.props as NotFoundProps).children;
+      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) {
+      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 (
+    !activeMatchFound &&
+    routeName === UNKNOWN_ROUTE &&
+    notFoundChildren !== null
+  ) {
+    rendered.push(
+      <Fragment key="__route-view-not-found__">{notFoundChildren}</Fragment>,
+    );
+  }
+
+  return { rendered, activeMatchFound };
+}

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

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

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

@@ -0,0 +1,26 @@
+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. */
+  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 NotFoundProps {
+  /** Content to render on UNKNOWN_ROUTE. */
+  readonly children: ReactNode;
+}

package/src/constants.ts

@@ -0,0 +1,11 @@
+// packages/react/modules/constants.ts
+
+/**
+ * Stable empty object for default params
+ */
+export const EMPTY_PARAMS = Object.freeze({});
+
+/**
+ * Stable empty options object
+ */
+export const EMPTY_OPTIONS = Object.freeze({});

package/src/context.ts

@@ -0,0 +1,12 @@
+// packages/react/modules/context.ts
+
+import { createContext } from "react";
+
+import type { RouteContext as RouteContextType } from "./types";
+import type { Router, Navigator } from "@real-router/core";
+
+export const RouteContext = createContext<RouteContextType | null>(null);
+
+export const RouterContext = createContext<Router | null>(null);
+
+export const NavigatorContext = createContext<Navigator | null>(null);

package/src/hooks/useIsActiveRoute.tsx

@@ -0,0 +1,36 @@
+import { createActiveRouteSource } from "@real-router/sources";
+import { useMemo, useSyncExternalStore } from "react";
+
+import { useRouter } from "./useRouter";
+import { useStableValue } from "./useStableValue";
+
+import type { Params } from "@real-router/core";
+
+export function useIsActiveRoute(
+  routeName: string,
+  params?: Params,
+  strict = false,
+  ignoreQueryParams = true,
+): boolean {
+  const router = useRouter();
+
+  // useStableValue: JSON.stringify memoization of params object.
+  // Without it, every render with a new params reference (e.g.,
+  // <Link routeParams={{ id: '123' }} />) would recreate the store.
+  const stableParams = useStableValue(params);
+
+  const store = useMemo(
+    () =>
+      createActiveRouteSource(router, routeName, stableParams, {
+        strict,
+        ignoreQueryParams,
+      }),
+    [router, routeName, stableParams, strict, ignoreQueryParams],
+  );
+
+  return useSyncExternalStore(
+    store.subscribe,
+    store.getSnapshot,
+    store.getSnapshot, // SSR: router returns same state on server and client
+  );
+}

package/src/hooks/useNavigator.tsx

@@ -0,0 +1,17 @@
+// packages/react/modules/hooks/useNavigator.tsx
+
+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

@@ -0,0 +1,17 @@
+// packages/react/modules/hooks/useRoute.tsx
+
+import { useContext } from "react";
+
+import { RouteContext } from "../context";
+
+import type { RouteContext as RouteContextType } from "../types";
+
+export const useRoute = (): RouteContextType => {
+  const routeContext = useContext(RouteContext);
+
+  if (!routeContext) {
+    throw new Error("useRoute must be used within a RouteProvider");
+  }
+
+  return routeContext;
+};

package/src/hooks/useRouteNode.tsx

@@ -0,0 +1,29 @@
+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],
+  );
+
+  const { route, previousRoute } = useSyncExternalStore(
+    store.subscribe,
+    store.getSnapshot,
+    store.getSnapshot, // SSR: router returns same state on server and client
+  );
+
+  const navigator = useMemo(() => getNavigator(router), [router]);
+
+  return useMemo(
+    (): RouteContext => ({ navigator, route, previousRoute }),
+    [navigator, route, previousRoute],
+  );
+}

package/src/hooks/useRouteUtils.tsx

@@ -0,0 +1,36 @@
+// packages/react/modules/hooks/useRouteUtils.tsx
+
+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.
+ *
+ * Internally retrieves the route tree via `getPluginApi` and delegates
+ * to `getRouteUtils`, which caches instances per tree reference (WeakMap).
+ *
+ * @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

@@ -0,0 +1,17 @@
+// packages/react/modules/hooks/useRouter.tsx
+
+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/useRouterError.tsx

@@ -0,0 +1,29 @@
+import { createErrorSource } from "@real-router/sources";
+import { useMemo, useSyncExternalStore } from "react";
+
+import { useRouter } from "./useRouter";
+
+import type { Router } from "@real-router/core";
+import type { RouterErrorSnapshot, RouterSource } from "@real-router/sources";
+
+const cache = new WeakMap<Router, RouterSource<RouterErrorSnapshot>>();
+
+export function useRouterError(): RouterErrorSnapshot {
+  const router = useRouter();
+  const store = useMemo(() => {
+    let source = cache.get(router);
+
+    if (!source) {
+      source = createErrorSource(router);
+      cache.set(router, source);
+    }
+
+    return source;
+  }, [router]);
+
+  return useSyncExternalStore(
+    store.subscribe,
+    store.getSnapshot,
+    store.getSnapshot,
+  );
+}

package/src/hooks/useRouterTransition.tsx

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

package/src/hooks/useStableValue.tsx

@@ -0,0 +1,29 @@
+// packages/react/modules/hooks/useStableValue.tsx
+
+import { useMemo } from "react";
+
+/**
+ * Stabilizes a value reference based on deep equality (via JSON serialization).
+ * Returns the same reference until the serialized value changes.
+ *
+ * Useful for object/array dependencies in hooks like useMemo, useCallback, useEffect
+ * to prevent unnecessary re-renders when the value is structurally the same.
+ *
+ * @example
+ * ```tsx
+ * const stableParams = useStableValue(routeParams);
+ * const href = useMemo(() => {
+ *   return router.buildUrl(routeName, stableParams);
+ * }, [router, routeName, stableParams]);
+ * ```
+ *
+ * @param value - The value to stabilize
+ * @returns A stable reference to the value
+ */
+export function useStableValue<T>(value: T): T {
+  const serialized = JSON.stringify(value);
+
+  // We intentionally use serialized in deps to detect deep changes
+  // eslint-disable-next-line @eslint-react/exhaustive-deps
+  return useMemo(() => value, [serialized]);
+}

package/src/index.ts

@@ -0,0 +1,39 @@
+// Main entry point — React 19.2+
+
+// 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";
+
+// Context
+export { RouterProvider } from "./RouterProvider";
+
+// Types
+export type { LinkProps } from "./types";
+
+export type {
+  RouteViewProps,
+  RouteViewMatchProps,
+  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/legacy.ts

@@ -0,0 +1,31 @@
+// Legacy entry point — React 18+
+
+// 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/types.ts

@@ -0,0 +1,30 @@
+import type {
+  NavigationOptions,
+  Params,
+  Navigator,
+  State,
+} from "@real-router/core";
+import type { HTMLAttributes, MouseEventHandler } from "react";
+
+export interface RouteState<P extends Params = Params> {
+  route: State<P> | undefined;
+  previousRoute?: State | undefined;
+}
+
+export type RouteContext = {
+  navigator: Navigator;
+} & RouteState;
+
+export interface LinkProps<
+  P extends Params = Params,
+> extends HTMLAttributes<HTMLAnchorElement> {
+  routeName: string;
+  routeParams?: P;
+  routeOptions?: NavigationOptions;
+  activeClassName?: string;
+  activeStrict?: boolean;
+  ignoreQueryParams?: boolean;
+  target?: string;
+  onClick?: MouseEventHandler<HTMLAnchorElement>;
+  onMouseOver?: MouseEventHandler<HTMLAnchorElement>;
+}