olova-router 1.0.19 → 1.0.21

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Olova Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,8 +1,31 @@
 # olova-router
 
-Standalone router package for Olova.
+A powerful, feature-rich router for Olova framework with advanced routing capabilities, middleware support, and lazy loading.
 
-## Main API
+## Features
+
+- 🚀 **Browser History & Hash Modes** - Support for both history and hash-based routing
+- 🛡️ **Route Guards** - Protect routes with beforeEnter guards and middleware
+- 🎯 **Dynamic Routes** - Support for dynamic params like `/blog/:slug` and wildcards
+- 📦 **Lazy Loading** - Code splitting with lazy component loading
+- 🔗 **Named Routes** - Reference routes by name instead of path
+- 🎨 **Active Link Styling** - Automatic active state detection for links
+- 📍 **Breadcrumbs** - Built-in breadcrumb generation utilities
+- 🔄 **Middleware Chain** - Composable middleware for cross-cutting concerns
+- 📜 **Route History** - Track navigation history with utilities
+- ⚡ **Type Safe** - Full TypeScript support with comprehensive types
+
+## Installation
+
+```bash
+npm install olova-router
+# or
+pnpm add olova-router
+# or
+yarn add olova-router
+```
+
+## Quick Start
 
 ```olova
 <script>
@@ -23,7 +46,7 @@ Standalone router package for Olova.
       name: "about"
     },
     {
-      path: "/blog/:blogName",
+      path: "/blog/:slug",
       component: Blog,
       name: "blog.show"
     }
@@ -35,70 +58,396 @@ Standalone router package for Olova.
   <Link name="about">About</Link>
   <Link
     name="blog.show"
-    params={{ blogName: "colors" }}
+    params={{ slug: "getting-started" }}
     activeClass="text-emerald-300"
   >
-    Colors
+    Blog
   </Link>
 </nav>
 
 <BrowserRouter routes={routes} />
 ```
 
-## Exports
-
-- `Router`
-- `BrowserRouter`
-- `HashRouter`
-- `Link`
-- `Outlet`
-- `useRouter()`
-- `useRoute()`
-- `useParams()`
-- `useQuery()`
-- `navigate()`
-- `matchPath()`
-
-## Route Features
-
-- browser history mode without `#`
-- hash mode for static hosting
-- dynamic params like `/blog/:slug`
-- wildcard routes like `/docs/*`
-- named routes
-- redirects
-- route guards with `beforeEnter`
-- nested routes with `children`
-- layout routes with `Outlet`
-- active link styling
-- object targets with `params`, `query`, and `hash`
-
-## Nested Routes
+## Core API
 
-```olova
-<script>
-  import { BrowserRouter, Outlet } from "olova-router";
+### Router Components
 
-  const routes = [
-    {
-      path: "/dashboard",
-      component: DashboardLayout,
-      children: [
-        { index: true, component: DashboardHome },
-        { path: "settings", component: DashboardSettings }
-      ]
-    }
+- `Router` - Base router component
+- `BrowserRouter` - History mode router (recommended)
+- `HashRouter` - Hash mode router (for static hosting)
+- `Link` - Navigation link component
+- `Outlet` - Nested route outlet
+
+### Router Hooks
+
+```typescript
+import { useRouter, useRoute, useParams, useQuery } from "olova-router";
+
+// Get full router API
+const router = useRouter();
+
+// Get current route location
+const route = useRoute();
+
+// Get route parameters
+const params = useParams();
+
+// Get query parameters
+const query = useQuery();
+```
+
+### Navigation
+
+```typescript
+import { navigate, link } from "olova-router";
+
+// Programmatic navigation
+navigate("/about");
+navigate({ name: "blog.show", params: { slug: "hello" } });
+
+// With options
+navigate("/home", { replace: true, scroll: true });
+
+// Link handler
+const handleClick = link("/about");
+```
+
+## Advanced Features
+
+### Route Guards
+
+Protect routes with guards and middleware:
+
+```typescript
+import { createConditionalGuard, createParamGuard } from "olova-router/guards";
+
+const routes = [
+  {
+    path: "/admin",
+    component: AdminPanel,
+    beforeEnter: createConditionalGuard(
+      () => isUserAdmin(),
+      "/unauthorized"
+    )
+  },
+  {
+    path: "/user/:id",
+    component: UserProfile,
+    beforeEnter: createParamGuard(
+      "id",
+      (id) => /^\d+$/.test(id),
+      "/not-found"
+    )
+  }
+];
+```
+
+### Middleware Chain
+
+Compose multiple middleware for route transitions:
+
+```typescript
+import {
+  createMiddlewareChain,
+  createAuthMiddleware,
+  createAnalyticsMiddleware,
+  createScrollMiddleware
+} from "olova-router/middleware";
+
+const middleware = createMiddlewareChain()
+  .use(createAuthMiddleware(() => isAuthenticated(), "/login"))
+  .use(createAnalyticsMiddleware((path) => trackPageView(path)))
+  .use(createScrollMiddleware(true));
+
+// Execute middleware
+const result = await middleware.execute(context);
+```
+
+### Lazy Loading
+
+Code split components with lazy loading:
+
+```typescript
+import { lazyComponent, lazyComponentWithFallback } from "olova-router/lazy";
+
+const routes = [
+  {
+    path: "/dashboard",
+    component: lazyComponent(() => import("./Dashboard.olova"))
+  },
+  {
+    path: "/settings",
+    component: lazyComponentWithFallback(
+      () => import("./Settings.olova"),
+      LoadingSpinner,
+      ErrorFallback
+    )
+  }
+];
+```
+
+### Breadcrumbs
+
+Generate breadcrumbs from route location:
+
+```typescript
+import { generateBreadcrumbs, generateBreadcrumbsFromMatches } from "olova-router/breadcrumbs";
+
+const route = useRoute();
+const breadcrumbs = generateBreadcrumbs(route, {
+  home: "Home",
+  blog: "Blog",
+  settings: "Settings"
+});
+
+// Or from route matches
+const breadcrumbs = generateBreadcrumbsFromMatches(route.matches);
+```
+
+### Route History
+
+Track navigation history:
+
+```typescript
+import { createRouterHistory } from "olova-router/history";
+
+const history = createRouterHistory(50); // max 50 entries
+
+history.push("/home");
+history.push("/about");
+
+const prev = history.back(); // { path: "/home", timestamp: ... }
+const next = history.forward(); // { path: "/about", timestamp: ... }
+
+const entries = history.getHistory();
+```
+
+## Route Configuration
+
+### Basic Route
+
+```typescript
+{
+  path: "/about",
+  component: About,
+  name: "about"
+}
+```
+
+### Dynamic Route
+
+```typescript
+{
+  path: "/blog/:slug",
+  component: BlogPost,
+  name: "blog.post"
+}
+```
+
+### Wildcard Route
+
+```typescript
+{
+  path: "/docs/*",
+  component: DocsLayout,
+  name: "docs"
+}
+```
+
+### Nested Routes
+
+```typescript
+{
+  path: "/dashboard",
+  component: DashboardLayout,
+  children: [
+    { index: true, component: DashboardHome },
+    { path: "settings", component: DashboardSettings },
+    { path: "profile", component: DashboardProfile }
   ]
-</script>
+}
+```
 
-<BrowserRouter routes={routes} />
+### Route with Guards
+
+```typescript
+{
+  path: "/admin",
+  component: AdminPanel,
+  beforeEnter: async (context) => {
+    if (!isAdmin()) {
+      return "/unauthorized";
+    }
+    return true;
+  }
+}
 ```
 
-Then inside `DashboardLayout.olova`:
+### Route with Props
+
+```typescript
+{
+  path: "/user/:id",
+  component: UserProfile,
+  props: (context) => ({
+    userId: context.params.id,
+    isAdmin: context.query.admin === "true"
+  })
+}
+```
+
+### Route Redirect
+
+```typescript
+{
+  path: "/old-path",
+  redirect: "/new-path"
+}
+```
+
+## Link Component
 
 ```olova
-<section>
-  <h1>Dashboard</h1>
-  <Outlet />
-</section>
+<script>
+  import { Link } from "olova-router";
+</script>
+
+<!-- Simple href -->
+<Link href="/about">About</Link>
+
+<!-- Named route -->
+<Link name="blog.post" params={{ slug: "hello" }}>Read Post</Link>
+
+<!-- With query and hash -->
+<Link
+  name="search"
+  query={{ q: "olova" }}
+  hash="results"
+>
+  Search
+</Link>
+
+<!-- Active styling -->
+<Link
+  href="/about"
+  class="nav-link"
+  activeClass="active"
+  inactiveClass="inactive"
+  exact
+>
+  About
+</Link>
+
+<!-- Custom attributes -->
+<Link
+  href="/external"
+  target="_blank"
+  rel="noopener noreferrer"
+  title="External Link"
+>
+  External
+</Link>
+```
+
+## Router Props
+
+```typescript
+type RouterProps = {
+  routes: RouterRoutes;
+  mode?: "auto" | "history" | "hash"; // default: "auto"
+  base?: string; // default: "/"
+  scroll?: boolean; // default: true
+};
 ```
+
+## TypeScript Support
+
+Full type safety with comprehensive types:
+
+```typescript
+import type {
+  RouteLocation,
+  RouteParams,
+  RouteQuery,
+  RouteTarget,
+  RouterApi,
+  RouteGuardContext
+} from "olova-router";
+```
+
+## Vite Plugin
+
+Auto-generate routes from file structure:
+
+```typescript
+// vite.config.ts
+import { olovaRouter } from "olova-router/vite";
+
+export default {
+  plugins: [olovaRouter()]
+};
+```
+
+## Best Practices
+
+1. **Use Named Routes** - More maintainable than hardcoded paths
+2. **Lazy Load Heavy Components** - Improve initial load time
+3. **Protect Sensitive Routes** - Use guards for auth/permissions
+4. **Handle 404s** - Always include a wildcard route
+5. **Scroll Management** - Enable scroll reset on navigation
+6. **Type Your Routes** - Leverage TypeScript for safety
+
+## Examples
+
+### Authentication Guard
+
+```typescript
+import { createConditionalGuard } from "olova-router/guards";
+
+const authGuard = createConditionalGuard(
+  async (context) => {
+    const token = localStorage.getItem("auth_token");
+    if (!token) return false;
+
+    const valid = await validateToken(token);
+    return valid;
+  },
+  "/login"
+);
+
+const routes = [
+  {
+    path: "/dashboard",
+    component: Dashboard,
+    beforeEnter: authGuard
+  }
+];
+```
+
+### Analytics Tracking
+
+```typescript
+import { createAnalyticsMiddleware } from "olova-router/middleware";
+
+const analyticsMiddleware = createAnalyticsMiddleware((path) => {
+  gtag.pageview({
+    page_path: path,
+    page_title: document.title
+  });
+});
+```
+
+### Composite Guards
+
+```typescript
+import { createCompositeGuard } from "olova-router/guards";
+
+const protectedGuard = createCompositeGuard([
+  createAuthMiddleware(() => isAuthenticated()),
+  createRoleMiddleware(() => userRole(), ["admin", "moderator"])
+]);
+```
+
+## License
+
+MIT