@esmx/router-react 3.0.0-rc.105

package/dist/index.test.mjs

@@ -0,0 +1,169 @@
+import { describe, expect, it } from "vitest";
+import * as RouterReactModule from "./index.mjs";
+describe("index.ts - Package Entry Point", () => {
+  describe("Hook Exports", () => {
+    it("should export useRouter hook", () => {
+      expect(RouterReactModule.useRouter).toBeDefined();
+      expect(typeof RouterReactModule.useRouter).toBe("function");
+    });
+    it("should export useRoute hook", () => {
+      expect(RouterReactModule.useRoute).toBeDefined();
+      expect(typeof RouterReactModule.useRoute).toBe("function");
+    });
+    it("should export useLink hook", () => {
+      expect(RouterReactModule.useLink).toBeDefined();
+      expect(typeof RouterReactModule.useLink).toBe("function");
+    });
+    it("should export useRouterViewDepth hook", () => {
+      expect(RouterReactModule.useRouterViewDepth).toBeDefined();
+      expect(typeof RouterReactModule.useRouterViewDepth).toBe(
+        "function"
+      );
+    });
+  });
+  describe("Component Exports", () => {
+    it("should export RouterProvider component", () => {
+      expect(RouterReactModule.RouterProvider).toBeDefined();
+      expect(typeof RouterReactModule.RouterProvider).toBe("function");
+    });
+    it("should export RouterLink component", () => {
+      expect(RouterReactModule.RouterLink).toBeDefined();
+      expect(typeof RouterReactModule.RouterLink).toBe("object");
+    });
+    it("should export RouterView component", () => {
+      expect(RouterReactModule.RouterView).toBeDefined();
+      expect(typeof RouterReactModule.RouterView).toBe("function");
+    });
+  });
+  describe("Context Exports", () => {
+    it("should export RouterContext", () => {
+      expect(RouterReactModule.RouterContext).toBeDefined();
+      expect(RouterReactModule.RouterContext.displayName).toBe(
+        "RouterContext"
+      );
+    });
+    it("should export RouterViewDepthContext", () => {
+      expect(RouterReactModule.RouterViewDepthContext).toBeDefined();
+      expect(RouterReactModule.RouterViewDepthContext.displayName).toBe(
+        "RouterViewDepthContext"
+      );
+    });
+  });
+  describe("Export Completeness", () => {
+    it("should export all expected functions and components", () => {
+      const expectedExports = [
+        // Hooks
+        "useRouter",
+        "useRoute",
+        "useLink",
+        "useRouterViewDepth",
+        // Components
+        "RouterProvider",
+        "RouterLink",
+        "RouterView",
+        // Context
+        "RouterContext",
+        "RouterViewDepthContext"
+      ];
+      expectedExports.forEach((exportName) => {
+        expect(RouterReactModule).toHaveProperty(exportName);
+        expect(Object.hasOwn(RouterReactModule, exportName)).toBe(true);
+      });
+    });
+    it("should not export unexpected items", () => {
+      const actualExports = Object.keys(RouterReactModule);
+      const expectedExports = [
+        "useRouter",
+        "useRoute",
+        "useLink",
+        "useRouterViewDepth",
+        "RouterProvider",
+        "RouterLink",
+        "RouterView",
+        "RouterContext",
+        "RouterViewDepthContext"
+      ];
+      const unexpectedExports = actualExports.filter(
+        (exportName) => !expectedExports.includes(exportName)
+      );
+      expect(unexpectedExports).toEqual([]);
+    });
+  });
+  describe("Hook Error Handling", () => {
+    it("hooks should throw when used incorrectly", () => {
+      expect(() => {
+        RouterReactModule.useRouter();
+      }).toThrow();
+      expect(() => {
+        RouterReactModule.useRoute();
+      }).toThrow();
+    });
+  });
+  describe("Component Properties", () => {
+    it("should have RouterProvider with displayName", () => {
+      expect(RouterReactModule.RouterProvider.displayName).toBe(
+        "RouterProvider"
+      );
+    });
+    it("should have RouterView with displayName", () => {
+      expect(RouterReactModule.RouterView.displayName).toBe("RouterView");
+    });
+    it("should have RouterLink with displayName", () => {
+      expect(RouterReactModule.RouterLink.displayName).toBe("RouterLink");
+    });
+  });
+  describe("Module Structure", () => {
+    it("should be a proper ES module", () => {
+      expect(typeof RouterReactModule).toBe("object");
+      expect(RouterReactModule).not.toBeNull();
+      expect("default" in RouterReactModule).toBe(false);
+    });
+    it("should have consistent export naming", () => {
+      const hookExports = [
+        "useRouter",
+        "useRoute",
+        "useLink",
+        "useRouterViewDepth"
+      ];
+      hookExports.forEach((exportName) => {
+        expect(exportName).toMatch(/^use[A-Z][a-zA-Z]*$/);
+      });
+      const componentExports = [
+        "RouterProvider",
+        "RouterLink",
+        "RouterView",
+        "RouterContext",
+        "RouterViewDepthContext"
+      ];
+      componentExports.forEach((exportName) => {
+        expect(exportName).toMatch(/^[A-Z][a-zA-Z]*$/);
+      });
+    });
+  });
+  describe("TypeScript Types", () => {
+    it("should export RouterContextValue type (via typeof)", () => {
+      const context = RouterReactModule.RouterContext;
+      expect(context).toBeDefined();
+      expect(context.Provider).toBeDefined();
+      expect(context.Consumer).toBeDefined();
+    });
+    it("should have RouterViewDepthContext with correct default value", () => {
+      const context = RouterReactModule.RouterViewDepthContext;
+      expect(context).toBeDefined();
+      expect(context.Provider).toBeDefined();
+    });
+  });
+  describe("React Best Practices", () => {
+    it("RouterLink should be a forwardRef component", () => {
+      const link = RouterReactModule.RouterLink;
+      expect(link.$$typeof).toBeDefined();
+      expect(link.render || link.type).toBeDefined();
+    });
+    it("RouterProvider should accept router and children props", () => {
+      expect(RouterReactModule.RouterProvider).toBeDefined();
+    });
+    it("RouterView should accept fallback prop", () => {
+      expect(RouterReactModule.RouterView).toBeDefined();
+    });
+  });
+});

package/dist/router-link.d.ts

@@ -0,0 +1,35 @@
+import type { RouteLayerOptions, RouteLocationInput, RouteMatchType, RouterLinkType } from '@esmx/router';
+import { type CSSProperties, type ReactNode } from 'react';
+/**
+ * Props for RouterLink component.
+ * Similar to RouterLinkProps from @esmx/router with React-specific additions.
+ */
+export interface RouterLinkComponentProps {
+    /** Target route location (required) */
+    to: RouteLocationInput;
+    /** Navigation type */
+    type?: RouterLinkType;
+    /** @deprecated Use type='replace' instead */
+    replace?: boolean;
+    /** Active matching mode */
+    exact?: RouteMatchType;
+    /** CSS class for active state */
+    activeClass?: string;
+    /** Event(s) that trigger navigation */
+    event?: string | string[];
+    /** HTML tag to render */
+    tag?: string;
+    /** Layer navigation options */
+    layerOptions?: RouteLayerOptions;
+    /** Hook function called before navigation */
+    beforeNavigate?: (event: Event, eventName: string) => void;
+    /** Link content */
+    children?: ReactNode;
+    /** Additional CSS class name */
+    className?: string;
+    /** Inline styles */
+    style?: CSSProperties;
+}
+export declare const RouterLink: React.ForwardRefExoticComponent<RouterLinkComponentProps & {
+    [key: string]: any;
+} & React.RefAttributes<HTMLAnchorElement>>;

package/dist/router-link.mjs

@@ -0,0 +1,85 @@
+import {
+  createElement,
+  forwardRef,
+  useCallback,
+  useMemo
+} from "react";
+import { useRouter } from "./context.mjs";
+function RouterLinkInner(props, ref) {
+  const {
+    to,
+    type = "push",
+    replace,
+    exact = "include",
+    activeClass,
+    event = "click",
+    tag = "a",
+    layerOptions,
+    beforeNavigate,
+    children,
+    className,
+    style,
+    ...rest
+  } = props;
+  const router = useRouter();
+  const linkResolved = useMemo(() => {
+    return router.resolveLink({
+      to,
+      type,
+      replace,
+      exact,
+      activeClass,
+      event,
+      tag,
+      layerOptions,
+      beforeNavigate
+    });
+  }, [
+    router,
+    to,
+    type,
+    replace,
+    exact,
+    activeClass,
+    event,
+    tag,
+    layerOptions,
+    beforeNavigate
+  ]);
+  const handleClick = useCallback(
+    async (e) => {
+      beforeNavigate == null ? void 0 : beforeNavigate(e, "click");
+      if (e.defaultPrevented) return;
+      if (e.metaKey || e.altKey || e.ctrlKey || e.shiftKey) return;
+      if (e.button !== 0) return;
+      e.preventDefault();
+      await linkResolved.navigate(e);
+    },
+    [linkResolved, beforeNavigate]
+  );
+  const computedClassName = useMemo(() => {
+    const classes = [];
+    if (linkResolved.attributes.class) {
+      classes.push(linkResolved.attributes.class);
+    }
+    if (className) {
+      classes.push(className);
+    }
+    return classes.join(" ") || void 0;
+  }, [linkResolved.attributes.class, className]);
+  const elementProps = {
+    ref,
+    href: linkResolved.attributes.href,
+    target: linkResolved.attributes.target,
+    rel: linkResolved.attributes.rel,
+    className: computedClassName,
+    style,
+    onClick: handleClick,
+    ...rest
+  };
+  return createElement(tag, elementProps, children);
+}
+export const RouterLink = forwardRef(
+  RouterLinkInner
+);
+RouterLink.displayName = "RouterLink";

package/dist/router-provider.d.ts

@@ -0,0 +1,61 @@
+import type { RouterProviderProps } from './types';
+/**
+ * RouterProvider component that provides router context to the React tree.
+ * This must wrap your application to enable routing functionality.
+ * Uses useSyncExternalStore for optimal React 18+ integration with concurrent features.
+ *
+ * @param props - Component props
+ * @param props.router - Router instance to provide
+ * @param props.children - Child components
+ *
+ * @example
+ * ```tsx
+ * import { Router, RouterMode } from '@esmx/router';
+ * import { RouterProvider } from '@esmx/router-react';
+ *
+ * const routes = [
+ *   { path: '/', component: Home },
+ *   { path: '/about', component: About }
+ * ];
+ *
+ * const router = new Router({
+ *   routes,
+ *   mode: RouterMode.history
+ * });
+ *
+ * function App() {
+ *   return (
+ *     <RouterProvider router={router}>
+ *       <Layout>
+ *         <RouterView />
+ *       </Layout>
+ *     </RouterProvider>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // SSR usage - initialize router with server URL
+ * import { Router, RouterMode } from '@esmx/router';
+ * import { RouterProvider } from '@esmx/router-react';
+ *
+ * const router = new Router({
+ *   routes,
+ *   mode: RouterMode.history,
+ *   base: new URL(serverUrl)
+ * });
+ *
+ * function ServerApp() {
+ *   return (
+ *     <RouterProvider router={router}>
+ *       <App />
+ *     </RouterProvider>
+ *   );
+ * }
+ * ```
+ */
+export declare function RouterProvider({ router, children }: RouterProviderProps): React.ReactElement;
+export declare namespace RouterProvider {
+    var displayName: string;
+}

package/dist/router-provider.mjs

@@ -0,0 +1,34 @@
+import { createElement, useCallback, useSyncExternalStore } from "react";
+import { RouterContext } from "./context.mjs";
+export function RouterProvider({
+  router,
+  children
+}) {
+  const subscribe = useCallback(
+    (callback) => {
+      return router.afterEach(callback);
+    },
+    [router]
+  );
+  const getSnapshot = useCallback(() => {
+    return router.route;
+  }, [router]);
+  const getServerSnapshot = useCallback(() => {
+    return router.route;
+  }, [router]);
+  const route = useSyncExternalStore(
+    subscribe,
+    getSnapshot,
+    getServerSnapshot
+  );
+  const contextValue = {
+    router,
+    route
+  };
+  return createElement(
+    RouterContext.Provider,
+    { value: contextValue },
+    children
+  );
+}
+RouterProvider.displayName = "RouterProvider";

package/dist/router-view.d.ts

@@ -0,0 +1,63 @@
+import { type ReactElement } from 'react';
+import type { RouterViewProps } from './types';
+/**
+ * RouterView component that renders the matched route component.
+ * Acts as a placeholder where route components are rendered based on the current route.
+ * Supports nested routing with automatic depth tracking.
+ *
+ * @param props - Component props
+ * @param props.fallback - Optional fallback component when no route matches
+ *
+ * @example
+ * ```tsx
+ * // Basic usage
+ * import { RouterView } from '@esmx/router-react';
+ *
+ * function App() {
+ *   return (
+ *     <div>
+ *       <nav>
+ *         <RouterLink to="/">Home</RouterLink>
+ *         <RouterLink to="/about">About</RouterLink>
+ *       </nav>
+ *       <RouterView />
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Nested routing
+ * // Routes: [
+ * //   { path: '/users', component: UsersLayout, children: [
+ * //     { path: ':id', component: UserProfile }
+ * //   ]}
+ * // ]
+ *
+ * function UsersLayout() {
+ *   return (
+ *     <div>
+ *       <h1>Users</h1>
+ *       <RouterView /> // Renders UserProfile for /users/:id
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With fallback
+ * import { RouterView } from '@esmx/router-react';
+ *
+ * function App() {
+ *   return (
+ *     <RouterView fallback={<div>Page not found</div>} />
+ *   );
+ * }
+ * ```
+ */
+export declare function RouterView({ fallback }: RouterViewProps): ReactElement | null;
+export declare namespace RouterView {
+    var displayName: string;
+}

package/dist/router-view.mjs

@@ -0,0 +1,40 @@
+import {
+  createElement,
+  isValidElement,
+  useMemo
+} from "react";
+import {
+  RouterViewDepthContext,
+  useRoute,
+  useRouterViewDepth
+} from "./context.mjs";
+import { resolveComponent } from "./util.mjs";
+export function RouterView({ fallback }) {
+  const route = useRoute();
+  const depth = useRouterViewDepth();
+  const matchedRoute = route.matched[depth];
+  const Component = useMemo(() => {
+    if (!(matchedRoute == null ? void 0 : matchedRoute.component)) {
+      return null;
+    }
+    return resolveComponent(matchedRoute.component);
+  }, [matchedRoute == null ? void 0 : matchedRoute.component]);
+  if (!Component) {
+    if (fallback) {
+      if (isValidElement(fallback)) {
+        return fallback;
+      }
+      if (typeof fallback === "function") {
+        return createElement(fallback);
+      }
+      return null;
+    }
+    return null;
+  }
+  return createElement(
+    RouterViewDepthContext.Provider,
+    { value: depth + 1 },
+    createElement(Component, { key: matchedRoute.compilePath })
+  );
+}
+RouterView.displayName = "RouterView";

package/dist/types.d.ts

@@ -0,0 +1,27 @@
+import type { Route, Router } from '@esmx/router';
+/**
+ * Interface for the router context value.
+ * Contains the router instance and current route.
+ */
+export interface RouterContextValue {
+    /** Router instance for navigation */
+    router: Router;
+    /** Current route object */
+    route: Route;
+}
+/**
+ * Props for the RouterProvider component.
+ */
+export interface RouterProviderProps {
+    /** Router instance to provide to child components */
+    router: Router;
+    /** Child components */
+    children: React.ReactNode;
+}
+/**
+ * Props for the RouterView component.
+ */
+export interface RouterViewProps {
+    /** Optional fallback component to render when no route matches */
+    fallback?: React.ComponentType | React.ReactNode;
+}

package/dist/use-link.d.ts

@@ -0,0 +1,97 @@
+import type { RouterLinkProps, RouterLinkResolved } from '@esmx/router';
+/**
+ * Hook to create reactive link helpers for custom navigation components.
+ * Returns a resolved link object with attributes, state, and event handlers.
+ *
+ * This hook is useful when you need to build custom link components
+ * with full control over rendering while retaining router functionality.
+ *
+ * @param props - RouterLink properties
+ * @returns Resolved link object with attributes, state, and navigation methods
+ *
+ * @example
+ * ```tsx
+ * import { useLink } from '@esmx/router-react';
+ *
+ * function CustomNavButton({ to, children }) {
+ *   const link = useLink({ to, type: 'push', exact: 'include' });
+ *
+ *   return (
+ *     <button
+ *       onClick={(e) => link.navigate(e)}
+ *       className={link.isActive ? 'active' : ''}
+ *       disabled={link.isExactActive}
+ *     >
+ *       {children}
+ *       {link.isActive && <span>✓</span>}
+ *     </button>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Building a custom navigation card
+ * import { useLink } from '@esmx/router-react';
+ *
+ * interface NavCardProps {
+ *   to: string;
+ *   title: string;
+ *   description: string;
+ *   icon: React.ReactNode;
+ * }
+ *
+ * function NavCard({ to, title, description, icon }: NavCardProps) {
+ *   const link = useLink({ to });
+ *
+ *   return (
+ *     <div
+ *       className={`nav-card ${link.isActive ? 'active' : ''}`}
+ *       onClick={(e) => link.navigate(e)}
+ *       role="link"
+ *       tabIndex={0}
+ *     >
+ *       <div className="icon">{icon}</div>
+ *       <h3>{title}</h3>
+ *       <p>{description}</p>
+ *       {link.isExternal && <span className="external-badge">↗</span>}
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Using all resolved properties
+ * import { useLink } from '@esmx/router-react';
+ *
+ * function DebugLink({ to }) {
+ *   const link = useLink({ to, exact: 'exact' });
+ *
+ *   return (
+ *     <div>
+ *       <a
+ *         href={link.attributes.href}
+ *         target={link.attributes.target}
+ *         rel={link.attributes.rel}
+ *         className={link.attributes.class}
+ *         onClick={(e) => {
+ *           e.preventDefault();
+ *           link.navigate(e);
+ *         }}
+ *       >
+ *         Link Text
+ *       </a>
+ *       <pre>
+ *         isActive: {String(link.isActive)}
+ *         isExactActive: {String(link.isExactActive)}
+ *         isExternal: {String(link.isExternal)}
+ *         type: {link.type}
+ *         tag: {link.tag}
+ *       </pre>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export declare function useLink(props: RouterLinkProps): RouterLinkResolved;

package/dist/use-link.mjs

@@ -0,0 +1,40 @@
+import { useMemo } from "react";
+import { useRouter } from "./context.mjs";
+export function useLink(props) {
+  const router = useRouter();
+  const {
+    to,
+    type,
+    replace,
+    exact,
+    activeClass,
+    event,
+    tag,
+    layerOptions,
+    beforeNavigate
+  } = props;
+  return useMemo(() => {
+    return router.resolveLink({
+      to,
+      type,
+      replace,
+      exact,
+      activeClass,
+      event,
+      tag,
+      layerOptions,
+      beforeNavigate
+    });
+  }, [
+    router,
+    to,
+    type,
+    replace,
+    exact,
+    activeClass,
+    event,
+    tag,
+    layerOptions,
+    beforeNavigate
+  ]);
+}

package/dist/util.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Check if a value is an ES module.
+ * @param obj - The object to check
+ * @returns True if the object is an ES module
+ */
+export declare function isESModule(obj: unknown): obj is Record<string | symbol, any>;
+/**
+ * Resolve a component from potentially wrapped module format.
+ * Handles ES modules with default exports.
+ * @param component - The component to resolve
+ * @returns The resolved component
+ */
+export declare function resolveComponent(component: unknown): unknown;

package/dist/util.mjs

@@ -0,0 +1,15 @@
+export function isESModule(obj) {
+  if (!obj || typeof obj !== "object") return false;
+  const module = obj;
+  return Boolean(module.__esModule) || module[Symbol.toStringTag] === "Module";
+}
+export function resolveComponent(component) {
+  if (!component) return null;
+  if (isESModule(component)) {
+    return component.default || component;
+  }
+  if (component && typeof component === "object" && !Array.isArray(component) && "default" in component && Object.keys(component).length === 1) {
+    return component.default;
+  }
+  return component;
+}