@esmx/router-react 3.0.0-rc.105

package/package.json

@@ -0,0 +1,85 @@
+{
+    "name": "@esmx/router-react",
+    "description": "React integration for @esmx/router - A powerful router with React 18+ support using modern hooks and context patterns",
+    "keywords": [
+        "react",
+        "router",
+        "routing",
+        "react-router",
+        "hooks",
+        "typescript",
+        "navigation",
+        "esmx",
+        "esm",
+        "single-page-application",
+        "spa",
+        "framework",
+        "frontend"
+    ],
+    "template": "library",
+    "scripts": {
+        "lint:js": "biome check --write --no-errors-on-unmatched",
+        "lint:css": "pnpm run lint:js",
+        "lint:type": "tsc --noEmit",
+        "test": "vitest run --pass-with-no-tests",
+        "coverage": "vitest run --coverage --pass-with-no-tests",
+        "build": "unbuild"
+    },
+    "contributors": [
+        {
+            "name": "lzxb",
+            "url": "https://github.com/lzxb"
+        },
+        {
+            "name": "RockShi1994",
+            "url": "https://github.com/RockShi1994"
+        },
+        {
+            "name": "jerrychan7",
+            "url": "https://github.com/jerrychan7"
+        },
+        {
+            "name": "wesloong",
+            "url": "https://github.com/wesloong"
+        }
+    ],
+    "peerDependencies": {
+        "react": "^18.0.0 || ^19.0.0"
+    },
+    "dependencies": {
+        "@esmx/router": "3.0.0-rc.105"
+    },
+    "devDependencies": {
+        "@biomejs/biome": "2.3.7",
+        "@types/node": "^24.0.0",
+        "@types/react": "^19.1.8",
+        "@types/react-dom": "^19.1.6",
+        "@vitest/coverage-v8": "3.2.4",
+        "happy-dom": "^20.0.10",
+        "react": "^19.1.0",
+        "react-dom": "^19.1.0",
+        "typescript": "5.9.3",
+        "unbuild": "3.6.1",
+        "vitest": "3.2.4"
+    },
+    "version": "3.0.0-rc.105",
+    "type": "module",
+    "private": false,
+    "exports": {
+        ".": {
+            "import": "./dist/index.mjs",
+            "types": "./dist/index.d.ts"
+        }
+    },
+    "module": "dist/index.mjs",
+    "types": "./dist/index.d.ts",
+    "files": [
+        "lib",
+        "src",
+        "dist",
+        "*.mjs",
+        "template",
+        "public"
+    ],
+    "gitHead": "db0f4a2a8a54a932f900d0b4f09ef0bf1ca9243f"
+}

package/src/context.ts

@@ -0,0 +1,109 @@
+import type { Route, Router } from '@esmx/router';
+import { createContext, useContext } from 'react';
+import type { RouterContextValue } from './types';
+
+/**
+ * React Context for router state.
+ * Contains the router instance and current route.
+ * Using null as default to detect missing provider.
+ */
+export const RouterContext = createContext<RouterContextValue | null>(null);
+RouterContext.displayName = 'RouterContext';
+
+/**
+ * React Context for RouterView depth tracking.
+ * Used for nested routing to determine which matched route to render.
+ */
+export const RouterViewDepthContext = createContext<number>(0);
+RouterViewDepthContext.displayName = 'RouterViewDepthContext';
+
+/**
+ * Get the router context value.
+ * @throws {Error} If used outside of RouterProvider
+ * @internal
+ */
+export function useRouterContext(): RouterContextValue {
+    const context = useContext(RouterContext);
+    if (!context) {
+        throw new Error(
+            '[@esmx/router-react] Router context not found. ' +
+                'Please ensure your component is wrapped in a RouterProvider.'
+        );
+    }
+    return context;
+}
+
+/**
+ * Get the router instance for navigation.
+ * Must be used within a RouterProvider.
+ *
+ * @returns Router instance with navigation methods
+ * @throws {Error} If used outside of RouterProvider
+ *
+ * @example
+ * ```tsx
+ * import { useRouter } from '@esmx/router-react';
+ *
+ * function NavigationButton() {
+ *   const router = useRouter();
+ *
+ *   const handleClick = () => {
+ *     router.push('/dashboard');
+ *   };
+ *
+ *   return <button onClick={handleClick}>Go to Dashboard</button>;
+ * }
+ * ```
+ */
+export function useRouter(): Router {
+    return useRouterContext().router;
+}
+
+/**
+ * Get the current route information.
+ * Returns a reactive route object that updates when navigation occurs.
+ * Must be used within a RouterProvider.
+ *
+ * @returns Current route object with path, params, query, etc.
+ * @throws {Error} If used outside of RouterProvider
+ *
+ * @example
+ * ```tsx
+ * import { useRoute } from '@esmx/router-react';
+ *
+ * function CurrentPath() {
+ *   const route = useRoute();
+ *
+ *   return (
+ *     <div>
+ *       <p>Path: {route.path}</p>
+ *       <p>Params: {JSON.stringify(route.params)}</p>
+ *       <p>Query: {JSON.stringify(route.query)}</p>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export function useRoute(): Route {
+    return useRouterContext().route;
+}
+
+/**
+ * Get the current RouterView depth.
+ * Used internally by RouterView for nested routing.
+ *
+ * @returns Current depth level (0 for root, 1 for first nested, etc.)
+ *
+ * @example
+ * ```tsx
+ * import { useRouterViewDepth } from '@esmx/router-react';
+ *
+ * function DebugView() {
+ *   const depth = useRouterViewDepth();
+ *   return <div>Current depth: {depth}</div>;
+ * }
+ * ```
+ */
+export function useRouterViewDepth(): number {
+    return useContext(RouterViewDepthContext);
+}

package/src/index.test.ts

@@ -0,0 +1,215 @@
+/**
+ * @vitest-environment happy-dom
+ */
+import { describe, expect, it } from 'vitest';
+import * as RouterReactModule from './index';
+
+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'); // forwardRef returns 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'
+            ];
+
+            // Check that we don't have unexpected exports
+            const unexpectedExports = actualExports.filter(
+                (exportName) => !expectedExports.includes(exportName)
+            );
+
+            expect(unexpectedExports).toEqual([]);
+        });
+    });
+
+    describe('Hook Error Handling', () => {
+        it('hooks should throw when used incorrectly', () => {
+            // React hooks cannot be called outside of components
+            // This is expected React behavior - hooks depend on internal React state
+            // The error message varies depending on the React version and environment
+            expect(() => {
+                RouterReactModule.useRouter();
+            }).toThrow(); // Will throw "Invalid hook call" or similar
+
+            expect(() => {
+                RouterReactModule.useRoute();
+            }).toThrow(); // Will throw "Invalid hook call" or similar
+        });
+    });
+
+    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();
+
+            // Verify it's not a default export
+            expect('default' in RouterReactModule).toBe(false);
+        });
+
+        it('should have consistent export naming', () => {
+            // All hooks should start with 'use'
+            const hookExports = [
+                'useRouter',
+                'useRoute',
+                'useLink',
+                'useRouterViewDepth'
+            ];
+
+            hookExports.forEach((exportName) => {
+                expect(exportName).toMatch(/^use[A-Z][a-zA-Z]*$/);
+            });
+
+            // Component exports should be PascalCase
+            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)', () => {
+            // Types are compile-time only, but we can verify the runtime shape
+            const context = RouterReactModule.RouterContext;
+            expect(context).toBeDefined();
+            expect(context.Provider).toBeDefined();
+            expect(context.Consumer).toBeDefined();
+        });
+
+        it('should have RouterViewDepthContext with correct default value', () => {
+            // RouterViewDepthContext should default to 0
+            const context = RouterReactModule.RouterViewDepthContext;
+            expect(context).toBeDefined();
+            expect(context.Provider).toBeDefined();
+        });
+    });
+
+    describe('React Best Practices', () => {
+        it('RouterLink should be a forwardRef component', () => {
+            // forwardRef components have $$typeof and render properties
+            const link = RouterReactModule.RouterLink as any;
+            expect(link.$$typeof).toBeDefined();
+            // The render property exists on forwardRef components
+            expect(link.render || link.type).toBeDefined();
+        });
+
+        it('RouterProvider should accept router and children props', () => {
+            // Function components show their parameter count
+            // RouterProvider should be a regular function component
+            expect(RouterReactModule.RouterProvider).toBeDefined();
+        });
+
+        it('RouterView should accept fallback prop', () => {
+            expect(RouterReactModule.RouterView).toBeDefined();
+        });
+    });
+});

package/src/index.ts

@@ -0,0 +1,21 @@
+// Components
+
+// Hooks
+export {
+    RouterContext,
+    RouterViewDepthContext,
+    useRoute,
+    useRouter,
+    useRouterViewDepth
+} from './context';
+export type { RouterLinkComponentProps } from './router-link';
+export { RouterLink } from './router-link';
+export { RouterProvider } from './router-provider';
+export { RouterView } from './router-view';
+// Types
+export type {
+    RouterContextValue,
+    RouterProviderProps,
+    RouterViewProps
+} from './types';
+export { useLink } from './use-link';

package/src/router-link.ts

@@ -0,0 +1,222 @@
+import type {
+    RouteLayerOptions,
+    RouteLocationInput,
+    RouteMatchType,
+    RouterLinkResolved,
+    RouterLinkType
+} from '@esmx/router';
+import {
+    type CSSProperties,
+    createElement,
+    type ElementType,
+    forwardRef,
+    type MouseEvent,
+    type ReactElement,
+    type ReactNode,
+    type Ref,
+    useCallback,
+    useMemo
+} from 'react';
+import { useRouter } from './context';
+
+/**
+ * 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;
+}
+
+/**
+ * RouterLink component for declarative navigation.
+ * Renders an anchor tag with proper navigation behavior and active state management.
+ * Supports all navigation types: push, replace, pushWindow, replaceWindow, pushLayer.
+ *
+ * @param props - Component props
+ * @param props.to - Target route location
+ * @param props.type - Navigation type ('push' | 'replace' | 'pushWindow' | 'replaceWindow' | 'pushLayer')
+ * @param props.exact - Active matching mode ('include' | 'exact' | 'route')
+ * @param props.activeClass - CSS class for active state
+ * @param props.event - Event(s) that trigger navigation
+ * @param props.tag - HTML tag to render (default: 'a')
+ * @param props.layerOptions - Options for layer navigation
+ * @param props.beforeNavigate - Callback before navigation
+ * @param props.children - Link content
+ *
+ * @example
+ * ```tsx
+ * // Basic navigation
+ * <RouterLink to="/home">Home</RouterLink>
+ * <RouterLink to="/about">About</RouterLink>
+ *
+ * // With object location
+ * <RouterLink to={{ path: '/users', query: { page: '1' } }}>
+ *   Users
+ * </RouterLink>
+ *
+ * // Replace navigation (no history entry)
+ * <RouterLink to="/login" type="replace">Login</RouterLink>
+ *
+ * // Open in new window
+ * <RouterLink to="/external" type="pushWindow">External</RouterLink>
+ *
+ * // Custom active class
+ * <RouterLink
+ *   to="/dashboard"
+ *   activeClass="nav-active"
+ *   exact="exact"
+ * >
+ *   Dashboard
+ * </RouterLink>
+ *
+ * // Custom tag (button)
+ * <RouterLink to="/submit" tag="button" className="btn">
+ *   Submit
+ * </RouterLink>
+ *
+ * // With beforeNavigate callback
+ * <RouterLink
+ *   to="/protected"
+ *   beforeNavigate={(e, eventName) => {
+ *     if (!isAuthenticated) {
+ *       e.preventDefault();
+ *       showLoginModal();
+ *     }
+ *   }}
+ * >
+ *   Protected Page
+ * </RouterLink>
+ * ```
+ */
+function RouterLinkInner(
+    props: RouterLinkComponentProps & { [key: string]: any },
+    ref: Ref<HTMLAnchorElement>
+): ReactElement {
+    const {
+        to,
+        type = 'push',
+        replace,
+        exact = 'include',
+        activeClass,
+        event = 'click',
+        tag = 'a',
+        layerOptions,
+        beforeNavigate,
+        children,
+        className,
+        style,
+        ...rest
+    } = props;
+
+    const router = useRouter();
+
+    // Resolve the link using router's built-in resolver
+    const linkResolved: RouterLinkResolved = useMemo(() => {
+        return router.resolveLink({
+            to,
+            type,
+            replace,
+            exact,
+            activeClass,
+            event,
+            tag,
+            layerOptions,
+            beforeNavigate
+        });
+    }, [
+        router,
+        to,
+        type,
+        replace,
+        exact,
+        activeClass,
+        event,
+        tag,
+        layerOptions,
+        beforeNavigate
+    ]);
+
+    // Handle click event
+    const handleClick = useCallback(
+        async (e: MouseEvent<HTMLElement>) => {
+            // Call beforeNavigate callback if provided
+            beforeNavigate?.(e as unknown as Event, 'click');
+
+            // If default was prevented by beforeNavigate or by modifier keys, skip navigation
+            if (e.defaultPrevented) return;
+
+            // Check for modifier keys - let browser handle these
+            if (e.metaKey || e.altKey || e.ctrlKey || e.shiftKey) return;
+            if (e.button !== 0) return;
+
+            // Prevent default browser navigation
+            e.preventDefault();
+
+            // Navigate using the resolved link's navigate function
+            await linkResolved.navigate(e as unknown as Event);
+        },
+        [linkResolved, beforeNavigate]
+    );
+
+    // Build class names
+    const computedClassName = useMemo(() => {
+        const classes: string[] = [];
+        if (linkResolved.attributes.class) {
+            classes.push(linkResolved.attributes.class);
+        }
+        if (className) {
+            classes.push(className);
+        }
+        return classes.join(' ') || undefined;
+    }, [linkResolved.attributes.class, className]);
+
+    // Build props for the element
+    const elementProps = {
+        ref,
+        href: linkResolved.attributes.href,
+        target: linkResolved.attributes.target,
+        rel: linkResolved.attributes.rel,
+        className: computedClassName,
+        style,
+        onClick: handleClick,
+        ...rest
+    };
+
+    // Render the element with the appropriate tag using createElement
+    return createElement(tag as ElementType, elementProps, children);
+}
+
+// Cast needed to fix TypeScript forwardRef type inference issue
+// This is a common pattern when index signatures conflict with forwardRef's prop handling
+export const RouterLink = forwardRef(
+    RouterLinkInner as any
+) as React.ForwardRefExoticComponent<
+    RouterLinkComponentProps & {
+        [key: string]: any;
+    } & React.RefAttributes<HTMLAnchorElement>
+>;
+
+RouterLink.displayName = 'RouterLink';