@vobs/router 0.3.0 → 1.1.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 vobsjs
+Copyright (c) 2026 vobs 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

package/README.md

@@ -0,0 +1,63 @@
+# @vobs/router
+
+Signals-first client router for Vobs with guards, route loaders, and cancellation of superseded navigations.
+
+## Install
+
+```bash
+npm install @vobs/router
+```
+
+## Quick start
+
+```ts
+import { createVobs, createText } from '@vobs/vobs'
+import { createRouter, createMemoryHistory, RouterView, routerPlugin } from '@vobs/router'
+
+const router = createRouter({
+  history: createMemoryHistory('/'),
+  routes: [
+    { path: '/', name: 'home', component: () => createText('home') },
+    { path: '/users/:id', name: 'user', component: () => createText('user') }
+  ]
+})
+
+// Guards return undefined (allow), false (cancel), or a redirect target.
+router.beforeEach(to => (to.path.startsWith('/admin') ? '/login' : undefined))
+
+const app = createVobs({
+  render: () => RouterView({ loading: () => createText('loading'), notFound: () => createText('not-found') }),
+  plugins: [routerPlugin({ router })]
+})
+
+await router.push({ name: 'user', params: { id: '7' }, query: { tab: 'activity' } })
+router.currentRoute.value.fullPath // '/users/7?tab=activity'
+```
+
+## API
+
+| Signature | Description |
+| --- | --- |
+| `createRouter(options: RouterOptions): Router` | Creates a router; defaults to browser history in the DOM and memory history otherwise. |
+| `router.currentRoute: Signal<RouteLocation>` | Reactive current route with `path`, `params`, `query`, `hash`, `meta`, and `matched` records. |
+| `router.push(to: RouteTarget)` | Navigates and resolves to the new `RouteLocation`, or `false` when a guard cancels. |
+| `router.replace(to: RouteTarget)` | Like `push` but replaces the history entry. |
+| `router.resolve(to: RouteTarget): RouteLocation` | Resolves a target to a location without navigating. |
+| `router.back(): void` | Goes back in history. |
+| `router.beforeEach(guard: NavigationGuard): () => void` | Registers a global guard and returns its unregister function. |
+| `router.getViewState(route: RouteLocation): RouterViewState` | Resolves `ready`, `loading`, `error`, or `not-found` for the matched components. |
+| `router.devtools: RouterDevToolsAPI` | Navigation traces, data-request tracking, errors, metrics, and revalidation. |
+| `router.destroy(): void` | Stops history listening and disposes internal signals. |
+| `routerPlugin(options?: RouterPluginOptions): VobsPlugin` | Provides the router through `ROUTER_KEY`. |
+| `RouterView(props?: RouterViewProps): VobsNode` | Renders the matched component with nested layouts plus `loading`, `notFound`, and `error` slots. |
+| `useRouter(): Router` | Injects the router inside components. |
+| `useRoute(): Signal<RouteLocation>` | Injects the current-route signal. |
+| `lazy(loader: RouteComponentLoader): LazyRouteComponent` | Wraps a dynamic import as a lazy route component. |
+| `createMemoryHistory(initial?): RouterHistory` | In-memory history for tests and SSR. |
+| `createBrowserHistory(base?): RouterHistory` | History API adapter with `popstate` support. |
+
+Guards and route `loader`s run before a navigation commits. A newer navigation cancels the pending one: its promise rejects with `NavigationCancelledError`, and a late loader result cannot overwrite the current route or history. Guard redirects are capped at 10 hops (`NavigationRedirectError`).
+
+## Types
+
+`RouteLocation`, `RouteRecord`, `RouteComponent`, `RouteComponentProps`, `RouteComponentModule`, `RouteComponentLoader`, `RouteComponentDefinition`, `LazyRouteComponent`, `RouteLoader`, `RouteLoaderContext`, `NavigationGuard`, `NavigationGuardResult`, `RouteTarget`, `RouteLocationRaw`, `RouteQueryInput`, `RouteParams`, `RouteQuery`, `RouteQueryValue`, `RouteMeta`, `RouterOptions`, `RouterHistory`, `RouterViewState`, `Router`, `RouterViewProps`, `RouterPluginOptions`, `NavigationState`, `NavigationTrace`, `RouteErrorTrace`, `NavigationCancelledError`, `NavigationRedirectError`, `RouterPerformanceMetrics`, `RouterDevToolsAPI`, `RouterDevToolsEvent`, `RouterDataRequestKind`, `RouterDataRequestTrace`, `RouterDataRequestOptions`, `RouteDebugNode`, `RouterDebugEvent`, `RouterDebugEventType`

package/package.json

@@ -1,44 +1,21 @@
 {
-  "name": "@vobs/router",
-  "version": "0.3.0",
-  "description": "Client and server route resolution for vobs pages.",
-  "type": "module",
-  "publishConfig": {
-    "access": "public"
-  },
   "license": "MIT",
-  "author": "vobsjs",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/vobsjs/vobs.git",
-    "directory": "packages/features/router"
-  },
-  "bugs": {
-    "url": "https://github.com/vobsjs/vobs/issues"
-  },
-  "homepage": "https://github.com/vobsjs/vobs#readme",
-  "dependencies": {
-    "@vobs/reactivity": "0.3.0",
-    "@vobs/runtime-core": "0.3.0"
-  },
   "files": [
-    "dist"
+    "src",
+    "README.md",
+    "LICENSE"
   ],
+  "name": "@vobs/router",
+  "version": "1.1.0",
+  "type": "module",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
   "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
-    },
-    "./package.json": "./package.json"
+    ".": "./src/index.ts"
   },
-  "types": "./dist/index.d.ts",
-  "module": "./dist/index.js",
-  "main": "./dist/index.js",
-  "sideEffects": false,
-  "devDependencies": {
-    "@vobs/resource": "0.3.0"
-  },
-  "engines": {
-    "node": ">=22.12.0"
+  "dependencies": {
+    "@vobs/reactivity": "1.1.0",
+    "@vobs/vobs": "1.1.0",
+    "@vobs/runtime": "1.1.0"
   }
 }

package/src/debug.ts

@@ -0,0 +1,41 @@
+import type { RuntimeDebugContext } from '@vobs/runtime'
+
+export type RouterDebugEventType =
+  | 'navigation:start'
+  | 'navigation:end'
+  | 'route:update'
+  | 'data-request'
+  | 'error'
+
+export interface RouterDebugEvent {
+  readonly routerId: string
+  readonly type: RouterDebugEventType
+  readonly payload: unknown
+  readonly context?: RuntimeDebugContext
+}
+
+type RouterDebugListener = (event: RouterDebugEvent) => void
+
+const listeners = new Set<RouterDebugListener>()
+let nextRouterId = 1
+
+export function createRouterDebugId(): string {
+  return `router-${nextRouterId++}`
+}
+
+export function subscribeRouterDebug(listener: RouterDebugListener): () => void {
+  listeners.add(listener)
+  return () => listeners.delete(listener)
+}
+
+export function emitRouterDebug(
+  routerId: string,
+  type: RouterDebugEventType,
+  payload: unknown,
+  context?: RuntimeDebugContext
+): void {
+  const event: RouterDebugEvent = { routerId, type, payload, context }
+  for (const listener of [...listeners]) {
+    try { listener(event) } catch { /* diagnostics must not affect navigation */ }
+  }
+}