router-kit 1.3.3 → 2.0.0

package/dist/components/NavLink.d.ts

@@ -1,8 +1,45 @@
-import type { ReactNode } from "react";
-declare function NavLink({ to, children, className, activeClassName, }: {
-    to: string;
-    children: ReactNode;
-    className?: string;
-    activeClassName?: string;
-}): import("react/jsx-runtime").JSX.Element;
+import type { NavLinkProps } from "../types";
+/**
+ * NavLink component for navigation with active state styling
+ *
+ * Extends Link with automatic active state detection and styling.
+ * Perfect for navigation menus, tabs, and breadcrumbs.
+ *
+ * @example
+ * ```tsx
+ * // Basic usage with activeClassName
+ * <NavLink to="/about" activeClassName="active">About</NavLink>
+ *
+ * // With activeStyle
+ * <NavLink
+ *   to="/profile"
+ *   activeStyle={{ fontWeight: 'bold', color: 'blue' }}
+ * >
+ *   Profile
+ * </NavLink>
+ *
+ * // Exact matching with end prop
+ * <NavLink to="/" end activeClassName="active">Home</NavLink>
+ *
+ * // Custom active detection
+ * <NavLink
+ *   to="/users"
+ *   isActive={(match, location) => {
+ *     return location.pathname.startsWith('/users');
+ *   }}
+ * >
+ *   Users
+ * </NavLink>
+ *
+ * // Render prop for full control
+ * <NavLink to="/dashboard">
+ *   {({ isActive }) => (
+ *     <span className={isActive ? 'active' : ''}>
+ *       Dashboard {isActive && '✓'}
+ *     </span>
+ *   )}
+ * </NavLink>
+ * ```
+ */
+declare const NavLink: import("react").ForwardRefExoticComponent<NavLinkProps & import("react").RefAttributes<HTMLAnchorElement>>;
 export default NavLink;

package/dist/components/NavLink.js

@@ -1,14 +1,115 @@
 import { jsx as _jsx } from "react/jsx-runtime";
+import { forwardRef, } from "react";
+import { useLocation } from "../hooks/useLocation";
 import { useRouter } from "../hooks/useRouter";
-function NavLink({ to, children, className, activeClassName = "active", }) {
-    const { navigate, path } = useRouter();
-    const isActive = path === to;
-    const combinedClass = [className, isActive ? activeClassName : null]
+/**
+ * Checks if a link should trigger navigation or default browser behavior
+ */
+const shouldNavigate = (event, target) => {
+    return (!event.defaultPrevented &&
+        event.button === 0 &&
+        (!target || target === "_self") &&
+        !event.metaKey &&
+        !event.altKey &&
+        !event.ctrlKey &&
+        !event.shiftKey);
+};
+/**
+ * Default active matching logic
+ */
+const defaultIsActive = (pathname, to, end, caseSensitive) => {
+    const toPath = caseSensitive ? to : to.toLowerCase();
+    const currentPath = caseSensitive ? pathname : pathname.toLowerCase();
+    if (end) {
+        // Exact match (including trailing slash variations)
+        return currentPath === toPath || currentPath === `${toPath}/`;
+    }
+    // Partial match - pathname starts with to
+    return (currentPath.startsWith(toPath) &&
+        (currentPath.length === toPath.length || currentPath[toPath.length] === "/"));
+};
+/**
+ * NavLink component for navigation with active state styling
+ *
+ * Extends Link with automatic active state detection and styling.
+ * Perfect for navigation menus, tabs, and breadcrumbs.
+ *
+ * @example
+ * ```tsx
+ * // Basic usage with activeClassName
+ * <NavLink to="/about" activeClassName="active">About</NavLink>
+ *
+ * // With activeStyle
+ * <NavLink
+ *   to="/profile"
+ *   activeStyle={{ fontWeight: 'bold', color: 'blue' }}
+ * >
+ *   Profile
+ * </NavLink>
+ *
+ * // Exact matching with end prop
+ * <NavLink to="/" end activeClassName="active">Home</NavLink>
+ *
+ * // Custom active detection
+ * <NavLink
+ *   to="/users"
+ *   isActive={(match, location) => {
+ *     return location.pathname.startsWith('/users');
+ *   }}
+ * >
+ *   Users
+ * </NavLink>
+ *
+ * // Render prop for full control
+ * <NavLink to="/dashboard">
+ *   {({ isActive }) => (
+ *     <span className={isActive ? 'active' : ''}>
+ *       Dashboard {isActive && '✓'}
+ *     </span>
+ *   )}
+ * </NavLink>
+ * ```
+ */
+const NavLink = forwardRef(({ to, children, className, activeClassName = "active", activeStyle, isActive: customIsActive, end = false, caseSensitive = false, replace = false, state, preventScrollReset = false, target, rel, title, onClick, ...rest }, ref) => {
+    const { navigate, pathname, matches } = useRouter();
+    const location = useLocation();
+    // Determine active state
+    let isActive;
+    if (customIsActive) {
+        // Use custom isActive function
+        const currentMatch = matches.length > 0 ? matches[matches.length - 1] : null;
+        isActive = customIsActive(currentMatch, location);
+    }
+    else {
+        // Use default matching
+        isActive = defaultIsActive(pathname, to, end, caseSensitive);
+    }
+    // Compute class names
+    const computedClassName = [className, isActive ? activeClassName : null]
         .filter(Boolean)
-        .join(" ");
-    return (_jsx("a", { onClick: (e) => {
-            e.preventDefault();
-            navigate(to);
-        }, className: combinedClass, href: to, children: children }));
-}
+        .join(" ") || undefined;
+    // Compute styles
+    const computedStyle = isActive
+        ? activeStyle
+        : undefined;
+    // External link check
+    const isExternal = /^https?:\/\//i.test(to);
+    const handleClick = (event) => {
+        onClick === null || onClick === void 0 ? void 0 : onClick(event);
+        if (!isExternal && shouldNavigate(event, target)) {
+            event.preventDefault();
+            navigate(to, { replace, state, preventScrollReset });
+        }
+    };
+    // Security for external links
+    const computedRel = isExternal && target === "_blank" ? rel || "noopener noreferrer" : rel;
+    // Support render prop pattern
+    const renderChildren = typeof children === "function"
+        ? children({
+            isActive,
+        })
+        : children;
+    return (_jsx("a", { ref: ref, href: to, onClick: handleClick, className: computedClassName, style: computedStyle, target: target, rel: computedRel, title: title, "aria-current": isActive ? "page" : undefined, ...rest, children: renderChildren }));
+});
+NavLink.displayName = "NavLink";
 export default NavLink;

package/dist/components/Outlet.d.ts

@@ -0,0 +1,66 @@
+import { ReactNode } from "react";
+import { useOutletContext } from "../context/OutletContext";
+/**
+ * Outlet component props
+ */
+export interface OutletProps {
+    /** Custom context to pass to child routes */
+    context?: unknown;
+}
+/**
+ * Outlet Component
+ *
+ * Renders the child route's element when nested routes are used.
+ * This is the React Router-style component for rendering nested route content.
+ *
+ * @example
+ * ```tsx
+ * // Parent route component
+ * function Dashboard() {
+ *   return (
+ *     <div className="dashboard">
+ *       <Sidebar />
+ *       <main>
+ *         <Outlet /> {/* Renders child route content *\/}
+ *       </main>
+ *     </div>
+ *   );
+ * }
+ *
+ * // Routes configuration
+ * const routes = createRouter([
+ *   {
+ *     path: "dashboard",
+ *     component: <Dashboard />,
+ *     children: [
+ *       { path: "", component: <DashboardHome /> },
+ *       { path: "settings", component: <Settings /> },
+ *       { path: "profile", component: <Profile /> },
+ *     ],
+ *   },
+ * ]);
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Passing context to child routes
+ * function Layout() {
+ *   const user = useUser();
+ *   return (
+ *     <div>
+ *       <Header user={user} />
+ *       <Outlet context={{ user }} />
+ *     </div>
+ *   );
+ * }
+ *
+ * // Accessing context in child route
+ * function Profile() {
+ *   const { user } = useOutletContext<{ user: User }>();
+ *   return <h1>Welcome, {user.name}</h1>;
+ * }
+ * ```
+ */
+export declare function Outlet({ context }: OutletProps): ReactNode;
+export { useOutletContext };
+export default Outlet;

package/dist/components/Outlet.js

@@ -0,0 +1,69 @@
+import { useOutlet, useOutletContext } from "../context/OutletContext";
+/**
+ * Outlet Component
+ *
+ * Renders the child route's element when nested routes are used.
+ * This is the React Router-style component for rendering nested route content.
+ *
+ * @example
+ * ```tsx
+ * // Parent route component
+ * function Dashboard() {
+ *   return (
+ *     <div className="dashboard">
+ *       <Sidebar />
+ *       <main>
+ *         <Outlet /> {/* Renders child route content *\/}
+ *       </main>
+ *     </div>
+ *   );
+ * }
+ *
+ * // Routes configuration
+ * const routes = createRouter([
+ *   {
+ *     path: "dashboard",
+ *     component: <Dashboard />,
+ *     children: [
+ *       { path: "", component: <DashboardHome /> },
+ *       { path: "settings", component: <Settings /> },
+ *       { path: "profile", component: <Profile /> },
+ *     ],
+ *   },
+ * ]);
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Passing context to child routes
+ * function Layout() {
+ *   const user = useUser();
+ *   return (
+ *     <div>
+ *       <Header user={user} />
+ *       <Outlet context={{ user }} />
+ *     </div>
+ *   );
+ * }
+ *
+ * // Accessing context in child route
+ * function Profile() {
+ *   const { user } = useOutletContext<{ user: User }>();
+ *   return <h1>Welcome, {user.name}</h1>;
+ * }
+ * ```
+ */
+export function Outlet({ context }) {
+    const outlet = useOutlet();
+    // If context is provided, we could wrap outlet with context
+    // For now, just return the outlet content
+    if (context !== undefined) {
+        // Context is passed through OutletProvider in RouterProvider
+        console.warn("Outlet context prop is for documentation purposes. " +
+            "Use useOutletContext() in child components to access parent context.");
+    }
+    return outlet;
+}
+// Re-export useOutletContext for convenience
+export { useOutletContext };
+export default Outlet;

package/dist/components/Router.d.ts

@@ -0,0 +1,69 @@
+import { type ReactNode } from "react";
+/**
+ * Router props
+ */
+interface RouterProps {
+    /** Route children as JSX */
+    children: ReactNode;
+    /** Base path for all routes */
+    basename?: string;
+    /** Fallback element shown during lazy loading */
+    fallback?: ReactNode;
+}
+/**
+ * Router component for declarative routing
+ *
+ * Provides an alternative JSX-based approach to defining routes.
+ * Supports all route configuration options through props.
+ *
+ * @example
+ * ```tsx
+ * // Basic usage
+ * <Router>
+ *   <Route path="/" component={<Home />} />
+ *   <Route path="/about" component={<About />} />
+ *   <Route path="/users/:id" component={<UserProfile />} />
+ *   <Route path="/dashboard" component={<Dashboard />}>
+ *     <Route path="settings" component={<Settings />} />
+ *     <Route path="profile" component={<Profile />} />
+ *   </Route>
+ *   <Route path="/404" component={<NotFound />} />
+ * </Router>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With basename
+ * <Router basename="/app">
+ *   <Route path="/" component={<Home />} />
+ * </Router>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With lazy loading
+ * const LazyAbout = lazy(() => import('./pages/About'));
+ *
+ * <Router fallback={<Loading />}>
+ *   <Route path="/about" component={<LazyAbout />} />
+ * </Router>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With guards and loaders
+ * <Router>
+ *   <Route
+ *     path="/admin"
+ *     component={<Admin />}
+ *     guard={() => isAdmin() || '/login'}
+ *     loader={async () => fetchAdminData()}
+ *   />
+ * </Router>
+ * ```
+ */
+declare const Router: {
+    ({ children, basename, fallback }: RouterProps): import("react/jsx-runtime").JSX.Element;
+    displayName: string;
+};
+export default Router;

package/dist/components/Router.js

@@ -0,0 +1,109 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Children, isValidElement, Suspense } from "react";
+import RouterProvider from "../context/RouterProvider";
+import createRouter from "../core/createRouter";
+import { Route } from "./route";
+/**
+ * Extracts route configurations from JSX Route elements
+ * @param children React children containing Route elements
+ * @returns Array of route configurations
+ */
+function extractRoutesFromJSX(children) {
+    const routes = [];
+    Children.forEach(children, (child) => {
+        var _a;
+        if (isValidElement(child)) {
+            // Check if this is a Route component
+            const isRouteComponent = child.type === Route ||
+                ((_a = child.type) === null || _a === void 0 ? void 0 : _a.displayName) === "Route" ||
+                (typeof child.type === "function" && child.type.name === "Route");
+            if (isRouteComponent) {
+                const props = child.props;
+                const route = {
+                    path: props.path,
+                    component: props.component,
+                    // Pass through all route configuration options
+                    index: props.index,
+                    lazy: props.lazy,
+                    loader: props.loader,
+                    errorElement: props.errorElement,
+                    redirectTo: props.redirectTo,
+                    guard: props.guard,
+                    meta: props.meta,
+                };
+                // Handle nested routes
+                if (props.children) {
+                    const childRoutes = extractRoutesFromJSX(props.children);
+                    if (childRoutes.length > 0) {
+                        route.children = childRoutes;
+                    }
+                }
+                routes.push(route);
+            }
+        }
+    });
+    return routes;
+}
+/**
+ * Router component for declarative routing
+ *
+ * Provides an alternative JSX-based approach to defining routes.
+ * Supports all route configuration options through props.
+ *
+ * @example
+ * ```tsx
+ * // Basic usage
+ * <Router>
+ *   <Route path="/" component={<Home />} />
+ *   <Route path="/about" component={<About />} />
+ *   <Route path="/users/:id" component={<UserProfile />} />
+ *   <Route path="/dashboard" component={<Dashboard />}>
+ *     <Route path="settings" component={<Settings />} />
+ *     <Route path="profile" component={<Profile />} />
+ *   </Route>
+ *   <Route path="/404" component={<NotFound />} />
+ * </Router>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With basename
+ * <Router basename="/app">
+ *   <Route path="/" component={<Home />} />
+ * </Router>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With lazy loading
+ * const LazyAbout = lazy(() => import('./pages/About'));
+ *
+ * <Router fallback={<Loading />}>
+ *   <Route path="/about" component={<LazyAbout />} />
+ * </Router>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With guards and loaders
+ * <Router>
+ *   <Route
+ *     path="/admin"
+ *     component={<Admin />}
+ *     guard={() => isAdmin() || '/login'}
+ *     loader={async () => fetchAdminData()}
+ *   />
+ * </Router>
+ * ```
+ */
+const Router = ({ children, basename, fallback }) => {
+    const routes = extractRoutesFromJSX(children);
+    const content = (_jsx(RouterProvider, { routes: createRouter(routes), basename: basename, fallbackElement: fallback }));
+    // Wrap in Suspense if fallback is provided
+    if (fallback) {
+        return _jsx(Suspense, { fallback: fallback, children: content });
+    }
+    return content;
+};
+Router.displayName = "Router";
+export default Router;

package/dist/components/route.d.ts

@@ -0,0 +1,77 @@
+import { ComponentType, LazyExoticComponent, ReactElement } from "react";
+import type { RouteGuard, RouteLoader, RouteMeta } from "../types";
+/**
+ * Route component props for declarative routing
+ */
+export interface RouteProps {
+    /** Path pattern(s) for the route */
+    path: string | string[];
+    /** Component to render when route matches */
+    component: ReactElement;
+    /** Nested route children */
+    children?: ReactElement<RouteProps> | ReactElement<RouteProps>[];
+    /** Index route - renders when parent path matches exactly */
+    index?: boolean;
+    /** Lazy-loaded component */
+    lazy?: LazyExoticComponent<ComponentType<any>>;
+    /** Route loader for data fetching */
+    loader?: RouteLoader;
+    /** Error boundary element */
+    errorElement?: ReactElement;
+    /** Redirect to another path */
+    redirectTo?: string;
+    /** Route guard function */
+    guard?: RouteGuard;
+    /** Route metadata */
+    meta?: RouteMeta;
+    /** Case-sensitive matching */
+    caseSensitive?: boolean;
+}
+/**
+ * Route component - used for declarative route definitions
+ * This is a placeholder component that will be processed by the Router
+ *
+ * @example
+ * ```tsx
+ * // 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 declare function Route(_props: RouteProps): null;
+export declare namespace Route {
+    var displayName: string;
+}
+export default Route;

package/dist/components/route.js

@@ -0,0 +1,51 @@
+/**
+ * Route component - used for declarative route definitions
+ * This is a placeholder component that will be processed by the Router
+ *
+ * @example
+ * ```tsx
+ * // 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) {
+    // 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;
+}
+// Add displayName for better debugging and component recognition
+Route.displayName = "Route";
+export default Route;

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;