@liteforge/router 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SchildW3rk
+
+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

@@ -0,0 +1,296 @@
+# @liteforge/router
+
+Full-featured router for LiteForge with guards, middleware, and lazy loading.
+
+## Installation
+
+```bash
+npm install @liteforge/router @liteforge/core @liteforge/runtime
+```
+
+Peer dependencies: `@liteforge/core >= 0.1.0`, `@liteforge/runtime >= 0.1.0`
+
+## Overview
+
+`@liteforge/router` provides client-side routing with route guards, middleware, nested routes, lazy loading, and full TypeScript support.
+
+## Basic Usage
+
+```tsx
+import { createRouter, RouterOutlet, Link } from '@liteforge/router'
+import { createApp } from '@liteforge/runtime'
+
+const router = createRouter({
+  routes: [
+    { path: '/', component: Home },
+    { path: '/about', component: About },
+    { path: '/users/:id', component: UserDetail }
+  ]
+})
+
+const App = () => (
+  <div>
+    <nav>
+      <Link href="/">Home</Link>
+      <Link href="/about">About</Link>
+    </nav>
+    <RouterOutlet />
+  </div>
+)
+
+createApp({ router }).mount(App)
+```
+
+## API
+
+### createRouter
+
+Creates a router instance.
+
+```ts
+import { createRouter } from '@liteforge/router'
+
+const router = createRouter({
+  routes: [...],
+  
+  // Optional settings
+  base: '/app',              // Base path for all routes
+  hashMode: false,           // Use hash-based routing (#/path)
+  scrollBehavior: 'auto',    // 'auto' | 'smooth' | 'none'
+  
+  // Global guards
+  guards: {
+    auth: async (ctx) => {
+      if (!isLoggedIn()) return '/login'
+      return true
+    }
+  },
+  
+  // Global middleware
+  middleware: [loggerMiddleware]
+})
+```
+
+### Route Definition
+
+```ts
+const routes = [
+  // Basic route
+  { path: '/', component: Home },
+  
+  // With name (for programmatic navigation)
+  { path: '/about', name: 'about', component: About },
+  
+  // Dynamic parameters
+  { path: '/users/:id', component: UserDetail },
+  
+  // Optional parameters
+  { path: '/posts/:id?', component: Posts },
+  
+  // Wildcard (catch-all)
+  { path: '/docs/*', component: DocsPage },
+  
+  // With guard
+  { path: '/admin', component: Admin, guard: 'auth' },
+  
+  // Multiple guards
+  { path: '/admin', component: Admin, guard: ['auth', 'role:admin'] },
+  
+  // Nested routes
+  {
+    path: '/dashboard',
+    component: DashboardLayout,
+    children: [
+      { path: '/', component: DashboardHome },
+      { path: '/settings', component: Settings }
+    ]
+  },
+  
+  // Route metadata
+  {
+    path: '/private',
+    component: Private,
+    meta: { requiresAuth: true, title: 'Private Page' }
+  }
+]
+```
+
+### lazy
+
+Lazy-load components for code splitting.
+
+```ts
+import { lazy } from '@liteforge/router'
+
+const routes = [
+  {
+    path: '/admin',
+    component: lazy(() => import('./AdminPanel'), {
+      loading: () => <Spinner />,
+      error: ({ error, retry }) => <RetryButton onclick={retry} />,
+      delay: 200  // Show loading after 200ms
+    })
+  }
+]
+```
+
+### Navigation
+
+```tsx
+import { use } from '@liteforge/runtime'
+
+const MyComponent = () => {
+  const router = use('router')
+  
+  // Navigate programmatically
+  router.navigate('/users/123')
+  router.navigate('/users/123', { replace: true })
+  router.navigate({ name: 'user', params: { id: '123' } })
+  
+  // Go back/forward
+  router.back()
+  router.forward()
+  
+  // Reactive route data (signals)
+  router.path()           // '/users/123'
+  router.params()         // { id: '123' }
+  router.query()          // { tab: 'posts' }
+  router.hash()           // '#section'
+  router.route()          // Full matched route object
+  
+  return <div>Current path: {() => router.path()}</div>
+}
+```
+
+### Link and NavLink
+
+```tsx
+import { Link, NavLink } from '@liteforge/router'
+
+// Basic link
+<Link href="/about">About</Link>
+
+// With query params
+<Link href="/search" query={{ q: 'term' }}>Search</Link>
+
+// Replace history instead of push
+<Link href="/login" replace>Login</Link>
+
+// NavLink adds 'active' class when matched
+<NavLink href="/users" activeClass="nav-active">
+  Users
+</NavLink>
+
+// Exact matching (default matches partial paths)
+<NavLink href="/users" exact>Users</NavLink>
+```
+
+### RouterOutlet
+
+Renders the current route's component.
+
+```tsx
+import { RouterOutlet } from '@liteforge/router'
+
+const Layout = () => (
+  <div>
+    <Header />
+    <main>
+      <RouterOutlet />  {/* Current route renders here */}
+    </main>
+    <Footer />
+  </div>
+)
+
+// For nested routes, use additional outlets
+const Dashboard = () => (
+  <div>
+    <Sidebar />
+    <RouterOutlet />  {/* Nested route renders here */}
+  </div>
+)
+```
+
+### Guards
+
+Guards control access to routes.
+
+```ts
+import { defineGuard, createAuthGuard, createRoleGuard } from '@liteforge/router'
+
+// Custom guard
+const premiumGuard = defineGuard('premium', async (ctx) => {
+  const user = await getUser()
+  if (!user.isPremium) {
+    return '/upgrade'  // Redirect
+  }
+  return true  // Allow
+})
+
+// Built-in guards
+const authGuard = createAuthGuard({
+  isAuthenticated: () => !!token(),
+  redirectTo: '/login'
+})
+
+const adminGuard = createRoleGuard({
+  getCurrentRole: () => user()?.role,
+  allowedRoles: ['admin', 'superadmin'],
+  redirectTo: '/unauthorized'
+})
+
+const router = createRouter({
+  routes: [...],
+  guards: {
+    auth: authGuard,
+    premium: premiumGuard,
+    admin: adminGuard
+  }
+})
+```
+
+### Middleware
+
+Middleware runs on every navigation.
+
+```ts
+import { defineMiddleware, createLoggerMiddleware } from '@liteforge/router'
+
+// Custom middleware
+const analyticsMiddleware = defineMiddleware('analytics', (ctx, next) => {
+  trackPageView(ctx.to.path)
+  return next()
+})
+
+// Built-in middleware
+const logger = createLoggerMiddleware({ collapsed: true })
+const title = createTitleMiddleware({
+  default: 'My App',
+  template: (title) => `${title} | My App`
+})
+
+const router = createRouter({
+  routes: [...],
+  middleware: [logger, title, analyticsMiddleware]
+})
+```
+
+## Types
+
+```ts
+import type {
+  Router,
+  RouterOptions,
+  RouteDefinition,
+  MatchedRoute,
+  GuardFunction,
+  GuardContext,
+  MiddlewareFunction,
+  NavigateOptions,
+  LinkProps
+} from '@liteforge/router'
+```
+
+## License
+
+MIT

package/dist/components.d.ts

@@ -0,0 +1,75 @@
+import type { LazyComponentWithMethods } from './lazy.js';
+/**
+ * RouterOutlet configuration
+ */
+export interface RouterOutletConfig {
+    /** Fallback component when no route matches */
+    fallback?: () => Node;
+}
+/**
+ * RouterOutlet renders the component for the current matched route.
+ *
+ * For nested routes, each RouterOutlet tracks its depth and renders
+ * the appropriate level of the route match chain.
+ *
+ * @example
+ * ```ts
+ * // Basic usage
+ * const outlet = RouterOutlet();
+ *
+ * // With fallback for no match
+ * const outlet = RouterOutlet({ fallback: () => document.createTextNode('Not Found') });
+ * ```
+ */
+export declare function RouterOutlet(config?: RouterOutletConfig): Node;
+/**
+ * Link component configuration
+ */
+export interface LinkConfig {
+    /** Target path or URL */
+    href: string;
+    /** Link content - string or Node */
+    children: string | Node;
+    /** Class added when path matches (prefix match by default, exact match if `exact` is true) */
+    activeClass?: string;
+    /** Class added when path matches exactly */
+    exactActiveClass?: string;
+    /** When true, activeClass requires exact path match instead of prefix match */
+    exact?: boolean;
+    /** Static CSS class */
+    class?: string;
+    /** Use replaceState instead of pushState */
+    replace?: boolean;
+    /** Target attribute for the link */
+    target?: string;
+    /** Additional attributes */
+    attrs?: Record<string, string>;
+    /**
+     * Preload the route's lazy component on hover.
+     * Can be true (preload on mouseenter) or a LazyComponent to preload.
+     */
+    preload?: boolean | LazyComponentWithMethods;
+}
+/**
+ * Link creates an anchor element with client-side navigation.
+ *
+ * @example
+ * ```ts
+ * // Basic link
+ * const link = Link({ href: '/about', children: 'About Us' });
+ *
+ * // With active class
+ * const navLink = Link({
+ *   href: '/users',
+ *   children: 'Users',
+ *   activeClass: 'nav-active',
+ *   exactActiveClass: 'nav-exact',
+ * });
+ * ```
+ */
+export declare function Link(config: LinkConfig): HTMLAnchorElement;
+/**
+ * NavLink is an alias for Link with navigation-focused defaults.
+ */
+export declare const NavLink: typeof Link;
+//# sourceMappingURL=components.d.ts.map

package/dist/components.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"components.d.ts","sourceRoot":"","sources":["../src/components.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,WAAW,CAAC;AAM1D;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,+CAA+C;IAC/C,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAC;CACvB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,YAAY,CAAC,MAAM,GAAE,kBAAuB,GAAG,IAAI,CA2XlE;AAMD;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,yBAAyB;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,oCAAoC;IACpC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,8FAA8F;IAC9F,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,4CAA4C;IAC5C,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,+EAA+E;IAC/E,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,uBAAuB;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,4CAA4C;IAC5C,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,oCAAoC;IACpC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,4BAA4B;IAC5B,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,GAAG,wBAAwB,CAAC;CAC9C;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,IAAI,CAAC,MAAM,EAAE,UAAU,GAAG,iBAAiB,CAoI1D;AAMD;;GAEG;AACH,eAAO,MAAM,OAAO,aAAO,CAAC"}