navgo 3.0.6 → 3.0.8

package/index.d.ts

@@ -75,6 +75,8 @@ export interface Options {
 	preload_delay?: number
 	/** Disable hover/touch preloading when `false`. Default true. */
 	preload_on_hover?: boolean
+	/** Attach instance to window as `window.navgo`. Default true. */
+	attach_to_window?: boolean
 	/** Global hook fired after per-route `before_route_leave`, before loaders/history change. Can cancel. */
 	before_navigate?(_nav: Navigation): void
 	/** Global hook fired after routing completes (data loaded, URL updated, handlers run). */
@@ -110,6 +112,14 @@ export default class Navgo<T = unknown> {
 	init(): Promise<void>
 	/** Remove listeners installed by `init()`. */
 	destroy(): void
+	/** Writable store with current { url, route, params }. */
+	readonly route: import('svelte/store').Writable<{
+		url: URL
+		route: RouteTuple<T> | null
+		params: Params
+	}>
+	/** Writable store indicating active navigation. */
+	readonly is_navigating: import('svelte/store').Writable<boolean>
 	/** Built-in validator helpers (namespaced). */
 	static validators: ValidatorHelpers
 }

package/index.js

@@ -1,4 +1,6 @@
 import { parse } from 'regexparam'
+import { tick } from 'svelte'
+import { writable } from 'svelte/store'
 
 const ℹ = (...args) => {}
 
@@ -11,7 +13,8 @@ export default class Navgo {
 		before_navigate: undefined,
 		after_navigate: undefined,
 		url_changed: undefined,
-		tick: undefined,
+		tick,
+		attach_to_window: true,
 	}
 	/** @type {Array<{ pattern: RegExp, keys: string[]|null, data: RouteTuple }>} */
 	#routes = []
@@ -36,6 +39,8 @@ export default class Navgo {
 	#nav_active = 0
 	/** @type {(e: Event) => void | null} */
 	#scroll_handler = null
+	route = writable({ url: new URL(location.href), route: null, params: {} })
+	is_navigating = writable(false)
 
 	//
 	// Event listeners
@@ -99,7 +104,7 @@ export default class Navgo {
 			this.#current.url = target
 			ℹ('  - [🧭 event:popstate]', 'same path+search; skip loaders')
 			this.#apply_scroll(ev)
-			this.#opts.url_changed?.(this.#current)
+			this.route.set(this.#current)
 			return
 		}
 		// Explicit shallow entries (pushState/replaceState) regardless of path
@@ -107,7 +112,7 @@ export default class Navgo {
 			this.#current.url = target
 			ℹ('  - [🧭 event:popstate]', 'shallow entry; skip loaders')
 			this.#apply_scroll(ev)
-			this.#opts.url_changed?.(this.#current)
+			this.route.set(this.#current)
 			return
 		}
 
@@ -142,7 +147,7 @@ export default class Navgo {
 		}
 		// update current URL snapshot and notify
 		this.#current.url = new URL(location.href)
-		this.#opts.url_changed?.(this.#current)
+		this.route.set(this.#current)
 	}
 
 	/** @type {any} */
@@ -296,6 +301,7 @@ export default class Navgo {
 			ℹ('[🧭 goto]', 'invalid url', { url: url_raw })
 			return
 		}
+		this.is_navigating.set(true)
 		const { url, path } = info
 
 		const is_popstate = nav_type === 'popstate'
@@ -325,6 +331,7 @@ export default class Navgo {
 					}
 				}
 			}
+			if (nav_id === this.#nav_active) this.is_navigating.set(false)
 			ℹ('[🧭 goto]', 'cancelled by before_route_leave')
 			return
 		}
@@ -417,7 +424,8 @@ export default class Navgo {
 		await this.#opts.tick?.()
 
 		this.#apply_scroll(nav)
-		this.#opts.url_changed?.(this.#current)
+		this.route.set(this.#current)
+		if (nav_id === this.#nav_active) this.is_navigating.set(false)
 	}
 
 	/**
@@ -455,7 +463,7 @@ export default class Navgo {
 		if (!replace) this.#clear_onward_history()
 		// update current URL snapshot and notify
 		this.#current.url = u
-		this.#opts.url_changed?.(this.#current)
+		this.route.set(this.#current)
 	}
 
 	/** @param {string|URL} [url] @param {any} [state] */
@@ -563,6 +571,11 @@ export default class Navgo {
 			return pat
 		})
 
+		// TODO: deprecated, remove later
+		this.route.subscribe(() => {
+			this.#opts.url_changed?.(this.#current)
+		})
+
 		ℹ('[🧭 init]', {
 			base: this.#base,
 			routes: this.#routes.length,
@@ -608,6 +621,7 @@ export default class Navgo {
 		}
 
 		ℹ('[🧭 init]', 'initial goto')
+		if (this.#opts.attach_to_window) window.navgo = this
 		return this.goto()
 	}
 	destroy() {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "navgo",
-	"version": "3.0.6",
+	"version": "3.0.8",
 	"repository": {
 		"type": "git",
 		"url": "git+https://github.com/mustafa0x/navgo.git"
@@ -16,7 +16,7 @@
 	},
 	"scripts": {
 		"build": "perl -0777 -i -pe 's/console.debug\\(...args\\)/{}/g' index.js",
-		"prepublishOnly": "pnpm test && pnpm run build",
+		"prepublishOnly": "pnpm run build",
 		"test": "vitest run index.test.js",
 		"test:e2e": "playwright test",
 		"start:testsite": "pnpm vite dev test/site --port 5714",
@@ -34,6 +34,9 @@
 	"dependencies": {
 		"regexparam": "^3.0.0"
 	},
+	"peerDependencies": {
+		"svelte": "5"
+	},
 	"devDependencies": {
 		"@eslint/js": "^9.37.0",
 		"@playwright/test": "^1.56.0",

package/readme.md

@@ -103,16 +103,38 @@ Notes:
 - `tick`: `() => void | Promise<void>`
   - Awaited after `after_navigate` and before scroll handling; useful for frameworks to flush DOM so anchor/top scrolling lands correctly.
 - `url_changed`: `(snapshot: any) => void`
-  - Fires on every URL change — shallow `push_state`/`replace_state`, hash changes, `popstate` shallow entries, 404s, and full navigations.
+  - Fires on every URL change -- shallow `push_state`/`replace_state`, hash changes, `popstate` shallow entries, 404s, and full navigations. (deprecated; subscribe to `.route` instead.)
   - Receives the router's current snapshot: an object like `{ url: URL, route: RouteTuple|null, params: Params }`.
   - The snapshot type is intentionally `any` and may evolve without a breaking change.
 - `preload_delay`: `number` (default `20`)
   - Delay in ms before hover preloading triggers.
 - `preload_on_hover`: `boolean` (default `true`)
   - When `false`, disables hover/touch preloading.
+- `attach_to_window`: `boolean` (default `true`)
+  - When `true`, `init()` attaches the instance to `window.navgo` for convenience.
 
 Important: Navgo only processes routes that match your `base` path.
 
+### Instance stores
+
+- `router.route` -- `Writable<{ url: URL; route: RouteTuple|null; params: Params }>`
+  - Readonly property that holds the current snapshot.
+  - Subscribe to react to changes; Navgo updates it on every URL change.
+- `router.is_navigating` -- `Writable<boolean>`
+  - `true` while a navigation is in flight (between start and completion/cancel).
+
+Example:
+
+```svelte
+Current path: {$route.path}
+<div class="request-indicator" class:active={$is_navigating}></div>
+
+<script>
+const router = new Navgo(...)
+const {route, is_navigating} = router
+</script>
+```
+
 ### Route Hooks
 
 - param_validators?: `Record<string, (value: string|null|undefined) => boolean>`
@@ -225,8 +247,8 @@ While listening, link clicks are intercepted and translated into `goto()` naviga
 
 In addition, `init()` wires preloading listeners (enabled by default) so route data can be fetched early:
 
-- `mousemove` (hover) — after a short delay, hovering an in-app link triggers `preload(href)`.
-- `touchstart` and `mousedown` (tap) — tapping or pressing on an in-app link also triggers `preload(href)`.
+- `mousemove` (hover) -- after a short delay, hovering an in-app link triggers `preload(href)`.
+- `touchstart` and `mousedown` (tap) -- tapping or pressing on an in-app link also triggers `preload(href)`.
 
 Preloading applies only to in-app anchors that match the configured [`base`](#base). You can tweak this behavior with the `preload_delay` and `preload_on_hover` options.
 
@@ -287,10 +309,10 @@ This section explains, in detail, how navigation is processed: matching, hooks,
 
 ### Navigation Types
 
-- `link` — user clicked an in-app `<a>` that matches `base`.
-- `goto` — programmatic navigation via `router.goto(...)`.
-- `popstate` — browser back/forward.
-- `leave` — page is unloading (refresh, external navigation, tab close) via `beforeunload`.
+- `link` -- user clicked an in-app `<a>` that matches `base`.
+- `goto` -- programmatic navigation via `router.goto(...)`.
+- `popstate` -- browser back/forward.
+- `leave` -- page is unloading (refresh, external navigation, tab close) via `beforeunload`.
 
 The router passes the type to your route-level `before_route_leave(nav)` hook.
 
@@ -360,19 +382,19 @@ scroll flow
 
 ### Method-by-Method Semantics
 
-- `format(uri)` — normalizes a path relative to `base`. Returns `false` when `uri` is outside of `base`.
-- `match(uri)` — returns a Promise of `{ route, params } | null` using string/RegExp patterns and validators. Awaits an async `validate(params)` if provided.
-- `goto(uri, { replace? })` — fires route-level `before_route_leave('goto')`, calls global `before_navigate`, saves scroll, runs loaders, pushes/replaces, and completes via `after_navigate`.
-- `init()` — wires global listeners (`popstate`, `pushstate`, `replacestate`, click) and optional hover/tap preloading; immediately processes the current location.
-- `destroy()` — removes listeners added by `init()`.
-- `preload(uri)` — pre-executes a route's `loaders` for a path and caches the result; concurrent calls are deduped.
-- `push_state(url?, state?)` — shallow push that updates the URL and `history.state` without route processing.
-- `replace_state(url?, state?)` — shallow replace that updates the URL and `history.state` without route processing.
+- `format(uri)` -- normalizes a path relative to `base`. Returns `false` when `uri` is outside of `base`.
+- `match(uri)` -- returns a Promise of `{ route, params } | null` using string/RegExp patterns and validators. Awaits an async `validate(params)` if provided.
+- `goto(uri, { replace? })` -- fires route-level `before_route_leave('goto')`, calls global `before_navigate`, saves scroll, runs loaders, pushes/replaces, and completes via `after_navigate`.
+- `init()` -- wires global listeners (`popstate`, `pushstate`, `replacestate`, click) and optional hover/tap preloading; immediately processes the current location.
+- `destroy()` -- removes listeners added by `init()`.
+- `preload(uri)` -- pre-executes a route's `loaders` for a path and caches the result; concurrent calls are deduped.
+- `push_state(url?, state?)` -- shallow push that updates the URL and `history.state` without route processing.
+- `replace_state(url?, state?)` -- shallow replace that updates the URL and `history.state` without route processing.
 
 ### Built-in Validators
 
-- `Navgo.validators.int({ min?, max? })` — `true` iff the value is an integer within optional bounds.
-- `Navgo.validators.one_of(iterable)` — `true` iff the value is in the provided set.
+- `Navgo.validators.int({ min?, max? })` -- `true` iff the value is an integer within optional bounds.
+- `Navgo.validators.one_of(iterable)` -- `true` iff the value is in the provided set.
 
 Attach validators via a route tuple's `data.param_validators` to constrain matches.
 
@@ -380,6 +402,6 @@ Attach validators via a route tuple's `data.param_validators` to constrain match
 
 This router integrates ideas and small portions of code from these fantastic projects:
 
-- SvelteKit — https://github.com/sveltejs/kit
-- navaid — https://github.com/lukeed/navaid
-- TanStack Router — https://github.com/TanStack/router
+- SvelteKit -- https://github.com/sveltejs/kit
+- navaid -- https://github.com/lukeed/navaid
+- TanStack Router -- https://github.com/TanStack/router