@real-router/react 0.4.3 → 0.4.4

package/src/RouterProvider.tsx

@@ -0,0 +1,64 @@
+// packages/react/modules/RouterProvider.tsx
+
+import { getNavigator } from "@real-router/core";
+import { useMemo, useSyncExternalStore } from "react";
+
+import { NavigatorContext, RouteContext, RouterContext } from "./context";
+
+import type { RouteState } from "./types";
+import type { Router } from "@real-router/core";
+import type { FC, ReactNode } from "react";
+
+export interface RouteProviderProps {
+  router: Router;
+  children: ReactNode;
+}
+
+export const RouterProvider: FC<RouteProviderProps> = ({
+  router,
+  children,
+}) => {
+  // Get navigator instance from router
+  const navigator = useMemo(() => getNavigator(router), [router]);
+
+  // Local store state to hold route information
+  const store = useMemo(() => {
+    let currentState: RouteState = {
+      route: router.getState(),
+      previousRoute: undefined,
+    };
+
+    // This will be called to return the current state snapshot
+    const getSnapshot = () => currentState;
+
+    // Subscribe to router updates and notify React when state changes
+    const subscribe = (callback: () => void) => {
+      const unsubscribe = router.subscribe(({ route, previousRoute }) => {
+        currentState = { route, previousRoute };
+        callback(); // Notify React to trigger re-render
+      });
+
+      // Note: router.subscribe() always returns a function, no need to check
+      return unsubscribe;
+    };
+
+    return { getSnapshot, subscribe };
+  }, [router]);
+
+  // Using useSyncExternalStore to manage subscription and state updates
+  const state = useSyncExternalStore(store.subscribe, store.getSnapshot);
+
+  // Memoize RouteContext value to prevent unnecessary re-renders
+  const routeContextValue = useMemo(
+    () => ({ navigator, ...state }),
+    [navigator, state],
+  );
+
+  return (
+    <RouterContext value={router}>
+      <NavigatorContext value={navigator}>
+        <RouteContext value={routeContextValue}>{children}</RouteContext>
+      </NavigatorContext>
+    </RouterContext>
+  );
+};

package/src/components/BaseLink.tsx

@@ -0,0 +1,130 @@
+// packages/react/modules/components/BaseLink.tsx
+
+import { memo, useCallback, useMemo } from "react";
+
+import { EMPTY_PARAMS, EMPTY_OPTIONS } from "../constants";
+import { useIsActiveRoute } from "../hooks/useIsActiveRoute";
+import { useStableValue } from "../hooks/useStableValue";
+import { shouldNavigate } from "../utils";
+
+import type { BaseLinkProps } from "../types";
+import type { FC, MouseEvent } from "react";
+
+/**
+ * Optimized BaseLink component with memoization and performance improvements
+ */
+export const BaseLink: FC<BaseLinkProps> = memo(
+  ({
+    routeName,
+    routeParams = EMPTY_PARAMS,
+    routeOptions = EMPTY_OPTIONS,
+    className,
+    activeClassName = "active",
+    activeStrict = false,
+    ignoreQueryParams = true,
+    onClick,
+    target,
+    router,
+    children,
+    ...props
+  }) => {
+    // Stabilize object references to prevent unnecessary re-renders
+    const stableParams = useStableValue(routeParams);
+    const stableOptions = useStableValue(routeOptions);
+
+    // Use optimized hook for active state checking
+    const isActive = useIsActiveRoute(
+      router,
+      routeName,
+      stableParams,
+      activeStrict,
+      ignoreQueryParams,
+    );
+
+    // Build URL with memoization
+    const href = useMemo(() => {
+      // Use buildUrl if available (browser plugin installed)
+      // Otherwise fall back to buildPath (e.g., in SSR or without browser plugin)
+      if (typeof router.buildUrl === "function") {
+        return router.buildUrl(routeName, stableParams);
+      }
+
+      return router.buildPath(routeName, stableParams);
+    }, [router, routeName, stableParams]);
+
+    // Optimized click handler
+    const handleClick = useCallback(
+      (evt: MouseEvent<HTMLAnchorElement>) => {
+        // Call custom onClick if provided
+        if (onClick) {
+          onClick(evt);
+          // Respect preventDefault from custom handler
+          if (evt.defaultPrevented) {
+            return;
+          }
+        }
+
+        // Check if we should handle navigation
+        if (!shouldNavigate(evt) || target === "_blank") {
+          return;
+        }
+
+        // Prevent default link behavior
+        evt.preventDefault();
+
+        // Perform navigation (fire-and-forget)
+        router.navigate(routeName, stableParams, stableOptions).catch(() => {});
+      },
+      [onClick, target, router, routeName, stableParams, stableOptions],
+    );
+
+    // Build className efficiently
+    const finalClassName = useMemo(() => {
+      if (isActive && activeClassName) {
+        return className
+          ? `${className} ${activeClassName}`.trim()
+          : activeClassName;
+      }
+
+      return className ?? undefined;
+    }, [isActive, className, activeClassName]);
+
+    // Filter out previousRoute from props
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    const { previousRoute, ...restProps } = props;
+
+    return (
+      <a
+        {...restProps}
+        href={href}
+        className={finalClassName}
+        onClick={handleClick}
+        data-route={routeName} // For event delegation if needed
+        data-active={isActive} // For CSS selectors if needed
+      >
+        {children}
+      </a>
+    );
+  },
+  (prevProps, nextProps) => {
+    // Custom comparison for better memoization
+    // Check if props that affect rendering have changed
+    return (
+      prevProps.router === nextProps.router &&
+      prevProps.routeName === nextProps.routeName &&
+      JSON.stringify(prevProps.routeParams) ===
+        JSON.stringify(nextProps.routeParams) &&
+      JSON.stringify(prevProps.routeOptions) ===
+        JSON.stringify(nextProps.routeOptions) &&
+      prevProps.className === nextProps.className &&
+      prevProps.activeClassName === nextProps.activeClassName &&
+      prevProps.activeStrict === nextProps.activeStrict &&
+      prevProps.ignoreQueryParams === nextProps.ignoreQueryParams &&
+      prevProps.onClick === nextProps.onClick &&
+      prevProps.target === nextProps.target &&
+      prevProps.children === nextProps.children
+    );
+  },
+);
+
+BaseLink.displayName = "BaseLink";

package/src/components/ConnectedLink.tsx

@@ -0,0 +1,20 @@
+// packages/react/modules/components/ConnectedLink.tsx
+
+import { BaseLink } from "./BaseLink";
+import { useRoute } from "../hooks/useRoute";
+import { useRouter } from "../hooks/useRouter";
+
+import type { BaseLinkProps } from "./interfaces";
+import type { FC } from "react";
+
+export const ConnectedLink: FC<
+  Omit<BaseLinkProps, "router" | "route" | "previousRoute">
+> = (props) => {
+  const router = useRouter();
+  const { route } = useRoute();
+
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  const { routeOptions, ...linkProps } = props;
+
+  return <BaseLink router={router} route={route} {...linkProps} />;
+};

package/src/components/Link.tsx

@@ -0,0 +1,16 @@
+// packages/react/modules/components/Link.tsx
+
+import { BaseLink } from "./BaseLink";
+import { useRouter } from "../hooks/useRouter";
+
+import type { BaseLinkProps } from "./interfaces";
+import type { FC } from "react";
+
+export const Link: FC<Omit<BaseLinkProps, "router">> = (props) => {
+  const router = useRouter();
+
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  const { route, previousRoute, routeOptions, ...linkProps } = props;
+
+  return <BaseLink router={router} {...linkProps} />;
+};

package/src/components/interfaces.ts

@@ -0,0 +1,28 @@
+// packages/react/modules/components/interfaces.ts
+
+import type {
+  NavigationOptions,
+  Params,
+  Router,
+  State,
+} from "@real-router/core";
+import type { HTMLAttributes, MouseEventHandler } from "react";
+
+export interface BaseLinkProps<
+  P extends Params = Params,
+  MP extends Params = Params,
+> extends HTMLAttributes<HTMLAnchorElement> {
+  router: Router;
+  routeName: string;
+  route?: State<P, MP> | undefined;
+  previousRoute?: State | undefined;
+  routeParams?: P;
+  routeOptions?: NavigationOptions;
+  className?: string;
+  activeClassName?: string;
+  activeStrict?: boolean;
+  ignoreQueryParams?: boolean;
+  target?: string;
+  onClick?: MouseEventHandler<HTMLAnchorElement>;
+  onMouseOver?: MouseEventHandler<HTMLAnchorElement>;
+}

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,95 @@
+// packages/react/modules/hooks/useIsActiveRoute.tsx
+
+import { areRoutesRelated } from "@real-router/helpers";
+import { useCallback, useMemo, useRef } from "react";
+
+import { useRouterSubscription } from "./useRouterSubscription";
+import { useStableValue } from "./useStableValue";
+import { EMPTY_PARAMS } from "../constants";
+import { createActiveCheckKey } from "../utils";
+
+import type { Params, Router, State, SubscribeState } from "@real-router/core";
+
+/**
+ * Optimized hook to check if a route is active.
+ * Minimizes unnecessary recalculations and re-renders.
+ */
+export function useIsActiveRoute(
+  router: Router,
+  routeName: string,
+  routeParams: Params = EMPTY_PARAMS,
+  activeStrict = false,
+  ignoreQueryParams = true,
+): boolean {
+  // Stabilize params reference to prevent unnecessary recalculations
+  const stableParams = useStableValue(routeParams);
+
+  // Create stable cache key
+  const cacheKey = useMemo(
+    () =>
+      createActiveCheckKey(
+        routeName,
+        stableParams,
+        activeStrict,
+        ignoreQueryParams,
+      ),
+    [routeName, stableParams, activeStrict, ignoreQueryParams],
+  );
+
+  // Cache the active state
+  const isActiveRef = useRef<boolean | undefined>(undefined);
+  const lastCacheKeyRef = useRef<string | undefined>(undefined);
+
+  if (lastCacheKeyRef.current !== cacheKey) {
+    isActiveRef.current = undefined;
+    lastCacheKeyRef.current = cacheKey;
+  }
+
+  // Optimize shouldUpdate to skip unrelated routes
+  const shouldUpdate = useCallback(
+    (newRoute: State, prevRoute?: State) => {
+      const isNewRelated = areRoutesRelated(routeName, newRoute.name);
+      const isPrevRelated =
+        prevRoute && areRoutesRelated(routeName, prevRoute.name);
+
+      return !!(isNewRelated || isPrevRelated);
+    },
+    [routeName],
+  );
+
+  // Selector that performs active check
+  const selector = useCallback(
+    (sub?: SubscribeState): boolean => {
+      const currentRoute = sub?.route ?? router.getState();
+
+      // Fast path: if no current route, not active
+      if (!currentRoute) {
+        isActiveRef.current = false;
+
+        return false;
+      }
+
+      // Fast path: skip unrelated routes
+      if (!areRoutesRelated(routeName, currentRoute.name)) {
+        isActiveRef.current = false;
+
+        return false;
+      }
+
+      // Full check for related routes
+      const isActive = router.isActiveRoute(
+        routeName,
+        stableParams,
+        activeStrict,
+        ignoreQueryParams,
+      );
+
+      isActiveRef.current = isActive;
+
+      return isActive;
+    },
+    [router, routeName, stableParams, activeStrict, ignoreQueryParams],
+  );
+
+  return useRouterSubscription(router, selector, shouldUpdate);
+}

package/src/hooks/useNavigator.tsx

@@ -0,0 +1,17 @@
+// packages/react/modules/hooks/useNavigator.tsx
+
+import { use } from "react";
+
+import { NavigatorContext } from "../context";
+
+import type { Navigator } from "@real-router/core";
+
+export const useNavigator = (): Navigator => {
+  const navigator = use(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 { use } from "react";
+
+import { RouteContext } from "../context";
+
+import type { RouteContext as RouteContextType } from "../types";
+
+export const useRoute = (): RouteContextType => {
+  const routeContext = use(RouteContext);
+
+  if (!routeContext) {
+    throw new Error("useRoute must be used within a RouteProvider");
+  }
+
+  return routeContext;
+};

package/src/hooks/useRouteNode.tsx

@@ -0,0 +1,74 @@
+// packages/react/modules/hooks/useRouteNode.tsx
+
+import { getNavigator } from "@real-router/core";
+import { useCallback, useMemo } from "react";
+
+import { useRouter } from "./useRouter";
+import { useRouterSubscription } from "./useRouterSubscription";
+import { getCachedShouldUpdate } from "../utils";
+
+import type { RouteContext, RouteState } from "../types";
+import type { State, SubscribeState } from "@real-router/core";
+
+/**
+ * Hook that subscribes to a specific route node with optimizations.
+ * Provides the current and previous route when the node is affected.
+ */
+export function useRouteNode(nodeName: string): RouteContext {
+  // Get router from context with error handling
+  const router = useRouter();
+
+  // Get cached shouldUpdate function to avoid recreation
+  const shouldUpdate = useMemo(
+    () => getCachedShouldUpdate(router, nodeName),
+    [router, nodeName],
+  );
+
+  // Stable state factory
+  // useRouteNode.tsx
+  const stateFactory = useCallback(
+    (sub?: SubscribeState): RouteState => {
+      const currentRoute = sub?.route ?? router.getState();
+
+      // Проверяем, активен ли узел
+      if (currentRoute && nodeName !== "") {
+        // Корневой узел всегда активен
+        const isNodeActive =
+          currentRoute.name === nodeName ||
+          currentRoute.name.startsWith(`${nodeName}.`);
+
+        if (!isNodeActive) {
+          return {
+            route: undefined,
+            previousRoute: sub?.previousRoute,
+          };
+        }
+      }
+
+      return {
+        route: currentRoute,
+        previousRoute: sub?.previousRoute,
+      };
+    },
+    [router, nodeName],
+  );
+
+  // Subscribe to router with optimization
+  const state = useRouterSubscription<RouteState>(
+    router,
+    stateFactory,
+    shouldUpdate as (newRoute: State, prevRoute?: State) => boolean,
+  );
+
+  // Return memoized context - useMemo ensures stable reference when deps unchanged
+  const navigator = useMemo(() => getNavigator(router), [router]);
+
+  return useMemo(
+    (): RouteContext => ({
+      navigator,
+      route: state.route,
+      previousRoute: state.previousRoute,
+    }),
+    [navigator, state.route, state.previousRoute],
+  );
+}

package/src/hooks/useRouter.tsx

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

package/src/hooks/useRouterSubscription.tsx

@@ -0,0 +1,81 @@
+// packages/react/modules/hooks/useRouterSubscription.tsx
+
+import { useCallback, useRef, useSyncExternalStore } from "react";
+
+import type { Router, State, SubscribeState } from "@real-router/core";
+
+/**
+ * Generic hook for subscribing to router changes with optimization.
+ *
+ * @param router - Real Router instance
+ * @param selector - Function to derive state from router subscription
+ * @param shouldUpdate - Optional predicate to filter updates
+ */
+export function useRouterSubscription<T>(
+  router: Router,
+  selector: (sub?: SubscribeState) => T,
+  shouldUpdate?: (newRoute: State, prevRoute?: State) => boolean,
+): T {
+  // Store current value
+  const stateRef = useRef<T | undefined>(undefined);
+  const selectorRef = useRef(selector);
+  const shouldUpdateRef = useRef(shouldUpdate);
+
+  // Update refs to avoid stale closures
+  selectorRef.current = selector;
+  shouldUpdateRef.current = shouldUpdate;
+
+  // Lazy initialization
+  if (stateRef.current === undefined) {
+    // Get initial state from router
+    const currentState = router.getState();
+
+    // Check if initial state is relevant for this subscription
+    const shouldInitialize =
+      !shouldUpdateRef.current ||
+      (currentState && shouldUpdateRef.current(currentState));
+
+    stateRef.current = selectorRef.current(
+      shouldInitialize && currentState
+        ? { route: currentState, previousRoute: undefined }
+        : undefined,
+    );
+  }
+
+  // Stable snapshot getter
+  const getSnapshot = useCallback(() => stateRef.current as T, []);
+
+  // Subscribe function with optimization
+  const subscribe = useCallback(
+    (onStoreChange: () => void) => {
+      return router.subscribe((next) => {
+        // Check if we should process this update
+        let shouldProcess = true;
+
+        if (shouldUpdateRef.current) {
+          shouldProcess = shouldUpdateRef.current(
+            next.route,
+            next.previousRoute,
+          );
+        }
+
+        if (!shouldProcess) {
+          return;
+        }
+
+        // Calculate new value
+        const newValue = selectorRef.current(next);
+
+        // Only trigger update if value actually changed
+        if (!Object.is(stateRef.current, newValue)) {
+          stateRef.current = newValue;
+
+          onStoreChange();
+        }
+      });
+    },
+    [router],
+  );
+
+  return useSyncExternalStore(subscribe, getSnapshot, 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 react-hooks/exhaustive-deps
+  return useMemo(() => value, [serialized]);
+}

package/src/index.ts

@@ -0,0 +1,27 @@
+// packages/react/modules/index.ts
+
+// Components
+export { BaseLink } from "./components/BaseLink";
+
+export type { BaseLinkProps } from "./types";
+
+export { Link } from "./components/Link";
+
+export { ConnectedLink } from "./components/ConnectedLink";
+
+// Hooks
+export { useRouteNode } from "./hooks/useRouteNode";
+
+export { useRoute } from "./hooks/useRoute";
+
+export { useNavigator } from "./hooks/useNavigator";
+
+// Context
+export { RouterProvider } from "./RouterProvider";
+
+export { RouterContext, RouteContext, NavigatorContext } from "./context";
+
+export { useRouter } from "./hooks/useRouter";
+
+// Types
+export type { Navigator } from "@real-router/core";

package/src/types.ts

@@ -0,0 +1,36 @@
+// packages/react/modules/types.ts
+
+import type { Params, Navigator, Router, State } from "@real-router/core";
+import type { MouseEvent, ReactNode } from "react";
+
+export interface RouteState<
+  P extends Params = Params,
+  MP extends Params = Params,
+> {
+  route: State<P, MP> | undefined;
+  previousRoute?: State | undefined;
+}
+
+export type RouteContext = {
+  navigator: Navigator;
+} & RouteState;
+
+export interface BaseLinkProps {
+  [key: string]: unknown;
+  router: Router;
+  routeName: string;
+  routeParams?: Params;
+  routeOptions?: {
+    [key: string]: unknown;
+    reload?: boolean;
+    replace?: boolean;
+  };
+  className?: string;
+  activeClassName?: string;
+  activeStrict?: boolean;
+  ignoreQueryParams?: boolean;
+  onClick?: (evt: MouseEvent<HTMLAnchorElement>) => void;
+  target?: string;
+  children?: ReactNode;
+  previousRoute?: State;
+}