@esmx/router-react 3.0.0-rc.105

package/src/router-provider.ts

@@ -0,0 +1,104 @@
+import type { Route } from '@esmx/router';
+import { createElement, useCallback, useSyncExternalStore } from 'react';
+import { RouterContext } from './context';
+import type { RouterContextValue, 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 function RouterProvider({
+    router,
+    children
+}: RouterProviderProps): React.ReactElement {
+    // Subscribe to route changes using useSyncExternalStore
+    // This ensures proper integration with React 18's concurrent features
+    const subscribe = useCallback(
+        (callback: () => void) => {
+            return router.afterEach(callback);
+        },
+        [router]
+    );
+
+    const getSnapshot = useCallback((): Route => {
+        return router.route;
+    }, [router]);
+
+    const getServerSnapshot = useCallback((): Route => {
+        return router.route;
+    }, [router]);
+
+    // Subscribe to route changes with useSyncExternalStore for concurrent mode safety
+    const route = useSyncExternalStore(
+        subscribe,
+        getSnapshot,
+        getServerSnapshot
+    );
+
+    // Create stable context value
+    const contextValue: RouterContextValue = {
+        router,
+        route
+    };
+
+    // Use createElement instead of JSX
+    return createElement(
+        RouterContext.Provider,
+        { value: contextValue },
+        children
+    );
+}
+
+RouterProvider.displayName = 'RouterProvider';

package/src/router-view.ts

@@ -0,0 +1,113 @@
+import {
+    type ComponentType,
+    createElement,
+    isValidElement,
+    type ReactElement,
+    useMemo
+} from 'react';
+import {
+    RouterViewDepthContext,
+    useRoute,
+    useRouterViewDepth
+} from './context';
+import type { RouterViewProps } from './types';
+import { resolveComponent } from './util';
+
+/**
+ * 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 function RouterView({ fallback }: RouterViewProps): ReactElement | null {
+    const route = useRoute();
+    const depth = useRouterViewDepth();
+
+    // Get the matched route at current depth
+    const matchedRoute = route.matched[depth];
+
+    // Resolve the component from the matched route
+    const Component = useMemo(() => {
+        if (!matchedRoute?.component) {
+            return null;
+        }
+        return resolveComponent(matchedRoute.component) as ComponentType<any>;
+    }, [matchedRoute?.component]);
+
+    // Render fallback if no component found
+    if (!Component) {
+        if (fallback) {
+            // If fallback is already a ReactElement, return it
+            if (isValidElement(fallback)) {
+                return fallback;
+            }
+            // If fallback is a component, render it
+            if (typeof fallback === 'function') {
+                return createElement(fallback as ComponentType);
+            }
+            // Return null for other cases (shouldn't happen with proper typing)
+            return null;
+        }
+        return null;
+    }
+
+    // Provide incremented depth for nested RouterViews using createElement
+    return createElement(
+        RouterViewDepthContext.Provider,
+        { value: depth + 1 },
+        createElement(Component, { key: matchedRoute.compilePath })
+    );
+}
+
+RouterView.displayName = 'RouterView';

package/src/types.ts

@@ -0,0 +1,30 @@
+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/src/use-link.ts

@@ -0,0 +1,138 @@
+import type { RouterLinkProps, RouterLinkResolved } from '@esmx/router';
+import { useMemo } from 'react';
+import { useRouter } from './context';
+
+/**
+ * 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 function useLink(props: RouterLinkProps): RouterLinkResolved {
+    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/src/util.ts

@@ -0,0 +1,38 @@
+/**
+ * Check if a value is an ES module.
+ * @param obj - The object to check
+ * @returns True if the object is an ES module
+ */
+export function isESModule(obj: unknown): obj is Record<string | symbol, any> {
+    if (!obj || typeof obj !== 'object') return false;
+    const module = obj as Record<string | symbol, any>;
+    return (
+        Boolean(module.__esModule) || module[Symbol.toStringTag] === 'Module'
+    );
+}
+
+/**
+ * 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 function resolveComponent(component: unknown): unknown {
+    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 as { default: unknown }).default;
+    }
+
+    return component;
+}