router-kit 1.3.4 → 2.0.0

package/dist/components/route.js

@@ -4,14 +4,44 @@
  *
  * @example
  * ```tsx
- * <Route path="/users/:id" element={<UserProfile />} />
- * <Route path={["/about", "/about-us"]} element={<About />} />
- * <Route path="/dashboard" element={<Dashboard />}>
- *   <Route path="settings" element={<Settings />} />
+ * // Basic route
+ * <Route path="/users/:id" component={<UserProfile />} />
+ *
+ * // Multiple paths
+ * <Route path={["/about", "/about-us"]} component={<About />} />
+ *
+ * // Nested routes
+ * <Route path="/dashboard" component={<Dashboard />}>
+ *   <Route path="settings" component={<Settings />} />
+ *   <Route path="profile" component={<Profile />} />
  * </Route>
+ *
+ * // With loader
+ * <Route
+ *   path="/user/:id"
+ *   component={<UserPage />}
+ *   loader={async ({ params }) => fetchUser(params.id)}
+ * />
+ *
+ * // With guard
+ * <Route
+ *   path="/admin"
+ *   component={<AdminPanel />}
+ *   guard={() => isAdmin() || '/login'}
+ * />
+ *
+ * // With metadata
+ * <Route
+ *   path="/about"
+ *   component={<About />}
+ *   meta={{ title: 'About Us', description: 'Learn about us' }}
+ * />
+ *
+ * // Catch-all route
+ * <Route path="*" component={<NotFound />} />
  * ```
  */
-export function Route(props) {
+export function Route(_props) {
     // This component doesn't render anything directly
     // It's used as a declarative way to define routes that will be processed by Router
     return null;

package/dist/context/OutletContext.d.ts

@@ -0,0 +1,41 @@
+import { ReactNode } from "react";
+import type { Route, RouteMatch } from "../types";
+/**
+ * Outlet context for nested route rendering
+ */
+export interface OutletContextType {
+    /** Current outlet content to render */
+    outlet: ReactNode;
+    /** Remaining child routes */
+    childRoutes: Route[];
+    /** Current route matches */
+    matches: RouteMatch[];
+    /** Current depth in route tree */
+    depth: number;
+    /** Custom context data passed to outlet */
+    context?: unknown;
+}
+/**
+ * Context for outlet data
+ */
+export declare const OutletDataContext: import("react").Context<OutletContextType | null>;
+/**
+ * Hook to access outlet context
+ */
+export declare function useOutletContext<T = unknown>(): T;
+/**
+ * Hook to check if there's an outlet available
+ */
+export declare function useOutlet(): ReactNode;
+/**
+ * Provider for outlet context
+ */
+export declare function OutletProvider({ children, outlet, childRoutes, matches, depth, context, }: {
+    children: ReactNode;
+    outlet: ReactNode;
+    childRoutes?: Route[];
+    matches?: RouteMatch[];
+    depth?: number;
+    context?: unknown;
+}): import("react/jsx-runtime").JSX.Element;
+export default OutletDataContext;

package/dist/context/OutletContext.js

@@ -0,0 +1,31 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useContext } from "react";
+/**
+ * Context for outlet data
+ */
+export const OutletDataContext = createContext(null);
+/**
+ * Hook to access outlet context
+ */
+export function useOutletContext() {
+    const context = useContext(OutletDataContext);
+    if (!context) {
+        throw new Error("useOutletContext must be used within a route component");
+    }
+    return context.context;
+}
+/**
+ * Hook to check if there's an outlet available
+ */
+export function useOutlet() {
+    var _a;
+    const context = useContext(OutletDataContext);
+    return (_a = context === null || context === void 0 ? void 0 : context.outlet) !== null && _a !== void 0 ? _a : null;
+}
+/**
+ * Provider for outlet context
+ */
+export function OutletProvider({ children, outlet, childRoutes = [], matches = [], depth = 0, context, }) {
+    return (_jsx(OutletDataContext.Provider, { value: { outlet, childRoutes, matches, depth, context }, children: children }));
+}
+export default OutletDataContext;

package/dist/context/RouterContext.d.ts

@@ -1,3 +1,12 @@
 import type { RouterContextType } from "../types";
+/**
+ * Router context - provides routing state and navigation functions
+ * throughout the application
+ */
 declare const RouterContext: import("react").Context<RouterContextType | undefined>;
+/**
+ * Internal hook to access router context with validation
+ * @internal
+ */
+export declare function useRouterContext(): RouterContextType;
 export default RouterContext;

package/dist/context/RouterContext.js

@@ -1,3 +1,23 @@
-import { createContext } from "react";
+import { createContext, useContext } from "react";
+/**
+ * Router context - provides routing state and navigation functions
+ * throughout the application
+ */
 const RouterContext = createContext(undefined);
+/**
+ * Display name for debugging
+ */
+RouterContext.displayName = "RouterContext";
+/**
+ * Internal hook to access router context with validation
+ * @internal
+ */
+export function useRouterContext() {
+    const context = useContext(RouterContext);
+    if (context === undefined) {
+        throw new Error("[router-kit] useRouter must be used within a RouterProvider. " +
+            "Wrap your application with <RouterProvider> or use createRouter().");
+    }
+    return context;
+}
 export default RouterContext;

package/dist/context/RouterProvider.d.ts

@@ -1,5 +1,16 @@
-import type { Route } from "../types";
-declare const RouterProvider: ({ routes }: {
-    routes: Route[];
-}) => import("react/jsx-runtime").JSX.Element;
+import type { RouterProviderProps } from "../types";
+/**
+ * RouterProvider - Professional-grade router provider component
+ *
+ * Features:
+ * - Static and dynamic route matching with priority
+ * - Route params extraction
+ * - Nested routes support
+ * - Route guards and redirects
+ * - Loader data support
+ * - Navigation transitions
+ * - Scroll restoration
+ * - History management
+ */
+declare const RouterProvider: ({ routes, basename, fallbackElement, }: RouterProviderProps) => import("react/jsx-runtime").JSX.Element;
 export default RouterProvider;

package/dist/context/RouterProvider.js

@@ -1,9 +1,13 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-import { useEffect, useState } from "react";
+import { Suspense, useCallback, useEffect, useMemo, useRef, useState, useTransition, } from "react";
 import join from "url-join";
 import Page404 from "../pages/404";
 import { createRouterError, RouterErrorCode, RouterErrors, } from "../utils/error/errors";
+import { OutletProvider } from "./OutletContext";
 import RouterContext from "./RouterContext";
+/**
+ * Validates a URL string
+ */
 const validateUrl = (url) => {
     try {
         new URL(url, window.location.origin);
@@ -13,101 +17,218 @@ const validateUrl = (url) => {
         return false;
     }
 };
-const RouterProvider = ({ routes }) => {
-    const [path, setPath] = useState("");
-    const [fullPathWithParams, setFullPathWithParams] = useState("");
-    let page404 = null;
-    useEffect(() => {
-        setPath(window.location.pathname);
-        const patchHistory = (method) => {
-            const original = window.history[method];
-            return function (state, title, url) {
-                const result = original.apply(this, [state, title, url]);
-                window.dispatchEvent(new Event("locationchange"));
-                return result;
-            };
-        };
-        const originalPush = window.history.pushState;
-        const originalReplace = window.history.replaceState;
-        window.history.pushState = patchHistory("pushState");
-        window.history.replaceState = patchHistory("replaceState");
-        const handleLocationChange = () => {
-            setPath(window.location.pathname);
-        };
-        window.addEventListener("popstate", handleLocationChange);
-        window.addEventListener("locationchange", handleLocationChange);
-        return () => {
-            window.history.pushState = originalPush;
-            window.history.replaceState = originalReplace;
-            window.removeEventListener("popstate", handleLocationChange);
-            window.removeEventListener("locationchange", handleLocationChange);
+/**
+ * Creates a unique key for location tracking
+ */
+const createKey = () => {
+    return Math.random().toString(36).substring(2, 10);
+};
+/**
+ * Gets current location from window
+ */
+const getCurrentLocation = () => {
+    if (typeof window === "undefined") {
+        return {
+            pathname: "/",
+            search: "",
+            hash: "",
+            state: null,
+            key: "default",
         };
-    }, []);
-    const pathValidation = (routeFullPath, currentPath) => {
-        const routePaths = routeFullPath.split("|");
-        for (const routePath of routePaths) {
-            const routeParts = routePath.split("/").filter(Boolean);
-            const pathParts = currentPath.split("/").filter(Boolean);
-            if (routeParts.length !== pathParts.length)
-                continue;
-            let isMatch = true;
-            for (let i = 0; i < routeParts.length; i++) {
-                const r = routeParts[i];
-                const p = pathParts[i];
-                if (r.startsWith(":"))
-                    continue;
-                if (r !== p) {
-                    isMatch = false;
-                    break;
-                }
+    }
+    return {
+        pathname: window.location.pathname,
+        search: window.location.search,
+        hash: window.location.hash,
+        state: window.history.state,
+        key: createKey(),
+    };
+};
+/**
+ * Extracts params from a path using a pattern
+ */
+const extractParams = (pattern, pathname) => {
+    const patternParts = pattern.split("/").filter(Boolean);
+    const pathParts = pathname.split("/").filter(Boolean);
+    if (patternParts.length !== pathParts.length) {
+        // Check for catch-all pattern
+        const hasCatchAll = patternParts.some((p) => p.startsWith("*"));
+        if (!hasCatchAll)
+            return null;
+    }
+    const params = {};
+    for (let i = 0; i < patternParts.length; i++) {
+        const patternPart = patternParts[i];
+        const pathPart = pathParts[i];
+        // Catch-all segment (*splat or **)
+        if (patternPart.startsWith("*")) {
+            const paramName = patternPart.slice(1) || "splat";
+            params[paramName] = pathParts.slice(i).join("/");
+            return params;
+        }
+        // Dynamic segment (:param)
+        if (patternPart.startsWith(":")) {
+            const paramName = patternPart.slice(1);
+            // Handle optional params (:param?)
+            if (paramName.endsWith("?")) {
+                params[paramName.slice(0, -1)] = pathPart !== null && pathPart !== void 0 ? pathPart : "";
+            }
+            else {
+                if (pathPart === undefined)
+                    return null;
+                params[paramName] = pathPart;
             }
-            if (isMatch)
-                return routePath;
+            continue;
         }
-        return false;
-    };
-    const getComponent = (routesList, currentPath, parentPath = "/") => {
+        // Static segment - must match exactly
+        if (patternPart !== pathPart)
+            return null;
+    }
+    return params;
+};
+/**
+ * RouterProvider - Professional-grade router provider component
+ *
+ * Features:
+ * - Static and dynamic route matching with priority
+ * - Route params extraction
+ * - Nested routes support
+ * - Route guards and redirects
+ * - Loader data support
+ * - Navigation transitions
+ * - Scroll restoration
+ * - History management
+ */
+const RouterProvider = ({ routes, basename = "", fallbackElement, }) => {
+    const [location, setLocation] = useState(getCurrentLocation);
+    const [pattern, setPattern] = useState("");
+    const [params, setParams] = useState({});
+    const [matches, setMatches] = useState([]);
+    const [loaderData, setLoaderData] = useState(null);
+    const [meta, setMeta] = useState(null);
+    const [isPending, startTransition] = useTransition();
+    const page404Ref = useRef(null);
+    const scrollPositions = useRef(new Map());
+    const isNavigatingRef = useRef(false);
+    /**
+     * Normalize pathname by removing basename
+     */
+    const normalizePathname = useCallback((pathname) => {
+        if (basename && pathname.startsWith(basename)) {
+            return pathname.slice(basename.length) || "/";
+        }
+        return pathname;
+    }, [basename]);
+    /**
+     * Match a single path pattern against current pathname
+     */
+    const matchPath = useCallback((routePattern, currentPath) => {
+        const patterns = routePattern.split("|");
+        for (const pat of patterns) {
+            const extractedParams = extractParams(pat, currentPath);
+            if (extractedParams !== null) {
+                return { match: true, params: extractedParams, pattern: pat };
+            }
+        }
+        return null;
+    }, []);
+    /**
+     * Get component and match info from routes
+     */
+    const getComponent = useCallback((routesList, currentPath, parentPath = "/") => {
         const staticRoutes = [];
         const dynamicRoutes = [];
+        const catchAllRoutes = [];
         for (const route of routesList) {
             const is404 = route.path === "404" || route.path === "/404";
             if (is404) {
-                page404 = route.component;
+                page404Ref.current = route.component;
                 continue;
             }
             const pathArray = Array.isArray(route.path) ? route.path : [route.path];
+            const hasCatchAll = pathArray.some((p) => p.includes("*"));
             const hasDynamicParams = pathArray.some((p) => p.includes(":"));
-            if (hasDynamicParams) {
+            if (hasCatchAll) {
+                catchAllRoutes.push(route);
+            }
+            else if (hasDynamicParams) {
                 dynamicRoutes.push(route);
             }
             else {
                 staticRoutes.push(route);
             }
         }
-        for (const route of staticRoutes) {
+        // Priority: static > dynamic > catch-all
+        const orderedRoutes = [
+            ...staticRoutes,
+            ...dynamicRoutes,
+            ...catchAllRoutes,
+        ];
+        for (const route of orderedRoutes) {
             const fullPath = join(parentPath, `/${route.path}`);
-            const matchedPath = pathValidation(fullPath, currentPath);
-            if (matchedPath) {
-                if (matchedPath !== fullPathWithParams) {
-                    setFullPathWithParams(matchedPath);
+            const matchResult = matchPath(fullPath, currentPath);
+            if (matchResult) {
+                // Handle redirects
+                if (route.redirectTo) {
+                    // Schedule redirect in next tick to avoid state update during render
+                    setTimeout(() => navigate(route.redirectTo), 0);
+                    return null;
                 }
-                return route.component;
-            }
-            if (route.children) {
-                const childMatch = getComponent(route.children, currentPath, fullPath);
-                if (childMatch)
-                    return childMatch;
-            }
-        }
-        for (const route of dynamicRoutes) {
-            const fullPath = join(parentPath, `/${route.path}`);
-            const matchedPath = pathValidation(fullPath, currentPath);
-            if (matchedPath) {
-                if (matchedPath !== fullPathWithParams) {
-                    setFullPathWithParams(matchedPath);
+                // Handle guards
+                if (route.guard) {
+                    const guardResult = route.guard({
+                        pathname: currentPath,
+                        params: matchResult.params,
+                        search: location.search,
+                    });
+                    if (typeof guardResult === "string") {
+                        setTimeout(() => navigate(guardResult), 0);
+                        return null;
+                    }
+                    if (guardResult === false) {
+                        continue; // Skip this route
+                    }
+                }
+                // Update matches state
+                const newMatch = {
+                    route,
+                    params: matchResult.params,
+                    pathname: currentPath,
+                    pathnameBase: parentPath,
+                    pattern: matchResult.pattern,
+                };
+                if (pattern !== matchResult.pattern) {
+                    setPattern(matchResult.pattern);
+                }
+                if (JSON.stringify(params) !== JSON.stringify(matchResult.params)) {
+                    setParams(matchResult.params);
+                }
+                setMatches((prev) => [...prev, newMatch]);
+                // Handle route meta
+                if (route.meta) {
+                    setMeta(route.meta);
+                    if (route.meta.title && typeof document !== "undefined") {
+                        document.title = route.meta.title;
+                    }
+                }
+                // Handle loader
+                if (route.loader) {
+                    const abortController = new AbortController();
+                    Promise.resolve(route.loader({
+                        params: matchResult.params,
+                        request: new Request(window.location.href),
+                        signal: abortController.signal,
+                    })).then(setLoaderData);
+                }
+                // Handle nested routes with Outlet support
+                if (route.children && route.children.length > 0) {
+                    const childComponent = getComponent(route.children, currentPath, fullPath);
+                    // Wrap parent component with OutletProvider to render children via Outlet
+                    return (_jsx(OutletProvider, { outlet: childComponent, childRoutes: route.children, matches: matches, depth: parentPath.split("/").filter(Boolean).length, children: route.component }));
                 }
                 return route.component;
             }
+            // Check children routes (for routes without matching parent)
             if (route.children) {
                 const childMatch = getComponent(route.children, currentPath, fullPath);
                 if (childMatch)
@@ -115,32 +236,148 @@ const RouterProvider = ({ routes }) => {
             }
         }
         return null;
-    };
-    const navigate = (to, options) => {
+    }, [location.search, matchPath, params, pattern]);
+    /**
+     * Navigate to a new location
+     */
+    const navigate = useCallback((to, options) => {
+        // Handle numeric (delta) navigation
+        if (typeof to === "number") {
+            window.history.go(to);
+            return;
+        }
+        // Normalize path
+        let targetPath = to;
         if (!/^https?:\/\//i.test(to)) {
-            to = to.startsWith("/") ? to : `/${to}`;
+            targetPath = to.startsWith("/") ? to : `/${to}`;
+            if (basename) {
+                targetPath = join(basename, targetPath);
+            }
         }
-        if (!validateUrl(to)) {
+        // Validate URL
+        if (!validateUrl(targetPath)) {
             RouterErrors.invalidRoute(to, "Invalid URL format");
             return;
         }
         try {
+            // Save scroll position before navigation
+            if (!(options === null || options === void 0 ? void 0 : options.preventScrollReset)) {
+                scrollPositions.current.set(location.key, window.scrollY);
+            }
+            isNavigatingRef.current = true;
             if (options === null || options === void 0 ? void 0 : options.replace) {
-                window.history.replaceState((options === null || options === void 0 ? void 0 : options.state) || {}, "", to);
+                window.history.replaceState({ ...options === null || options === void 0 ? void 0 : options.state, key: createKey() }, "", targetPath);
             }
             else {
-                window.history.pushState((options === null || options === void 0 ? void 0 : options.state) || {}, "", to);
+                window.history.pushState({ ...options === null || options === void 0 ? void 0 : options.state, key: createKey() }, "", targetPath);
+            }
+            // Use transition for better UX
+            startTransition(() => {
+                setLocation(getCurrentLocation());
+                setMatches([]); // Reset matches for new route
+            });
+            // Scroll to top unless prevented
+            if (!(options === null || options === void 0 ? void 0 : options.preventScrollReset)) {
+                window.scrollTo(0, 0);
             }
-            setPath(to);
         }
         catch (error) {
             const navError = createRouterError(RouterErrorCode.NAVIGATION_ABORTED, `Navigation to "${to}" failed: ${error instanceof Error ? error.message : String(error)}`, { to, error });
             console.error(navError.toConsoleMessage());
             throw navError;
         }
-    };
-    const matchedComponent = getComponent(routes, path);
-    const component = matchedComponent !== null && matchedComponent !== void 0 ? matchedComponent : (page404 || _jsx(Page404, {}));
-    return (_jsx(RouterContext.Provider, { value: { path, fullPathWithParams, navigate }, children: component }));
+        finally {
+            isNavigatingRef.current = false;
+        }
+    }, [basename, location.key]);
+    /**
+     * Go back in history
+     */
+    const back = useCallback(() => {
+        window.history.back();
+    }, []);
+    /**
+     * Go forward in history
+     */
+    const forward = useCallback(() => {
+        window.history.forward();
+    }, []);
+    /**
+     * Setup history listeners
+     */
+    useEffect(() => {
+        const handleLocationChange = () => {
+            startTransition(() => {
+                setLocation(getCurrentLocation());
+                setMatches([]); // Reset matches for new route
+            });
+        };
+        // Patch history methods to dispatch custom event
+        const patchHistory = (method) => {
+            const original = window.history[method];
+            return function (state, title, url) {
+                const result = original.apply(this, [state, title, url]);
+                window.dispatchEvent(new CustomEvent("locationchange", {
+                    detail: { action: method === "pushState" ? "PUSH" : "REPLACE" },
+                }));
+                return result;
+            };
+        };
+        const originalPush = window.history.pushState;
+        const originalReplace = window.history.replaceState;
+        window.history.pushState = patchHistory("pushState");
+        window.history.replaceState = patchHistory("replaceState");
+        window.addEventListener("popstate", handleLocationChange);
+        window.addEventListener("locationchange", handleLocationChange);
+        return () => {
+            window.history.pushState = originalPush;
+            window.history.replaceState = originalReplace;
+            window.removeEventListener("popstate", handleLocationChange);
+            window.removeEventListener("locationchange", handleLocationChange);
+        };
+    }, []);
+    /**
+     * Compute matched component
+     */
+    const normalizedPath = normalizePathname(location.pathname);
+    const matchedComponent = useMemo(() => getComponent(routes, normalizedPath), [routes, normalizedPath, getComponent]);
+    const component = matchedComponent !== null && matchedComponent !== void 0 ? matchedComponent : (page404Ref.current || _jsx(Page404, {}));
+    /**
+     * Build context value with memoization
+     */
+    const contextValue = useMemo(() => ({
+        // New API
+        pathname: normalizedPath,
+        pattern,
+        search: location.search,
+        hash: location.hash,
+        state: location.state,
+        params,
+        matches,
+        navigate,
+        back,
+        forward,
+        isNavigating: isPending || isNavigatingRef.current,
+        loaderData,
+        meta,
+        // Legacy aliases for backward compatibility
+        path: normalizedPath,
+        fullPathWithParams: pattern,
+    }), [
+        normalizedPath,
+        pattern,
+        location.search,
+        location.hash,
+        location.state,
+        params,
+        matches,
+        navigate,
+        back,
+        forward,
+        isPending,
+        loaderData,
+        meta,
+    ]);
+    return (_jsx(RouterContext.Provider, { value: contextValue, children: fallbackElement && isPending ? (_jsx(Suspense, { fallback: fallbackElement, children: component })) : (component) }));
 };
 export default RouterProvider;