navgo 3.0.4 → 3.0.5

package/index.d.ts

@@ -7,23 +7,23 @@ export type Params = Record<string, string | null | undefined>
 
 /** Built-in validator helpers shape. */
 export interface ValidatorHelpers {
-	int(opts?: {
+	int(_opts?: {
 		min?: number | null
 		max?: number | null
-	}): (value: string | null | undefined) => boolean
-	oneOf(values: Iterable<string>): (value: string | null | undefined) => boolean
+	}): (_value: string | null | undefined) => boolean
+	one_of(_values: Iterable<string>): (_value: string | null | undefined) => boolean
 }
 
 /** Optional per-route hooks recognized by Navgo. */
 export interface Hooks {
 	/** Validate params with custom per-param validators. Return `false` to skip a match. */
-	param_validators?: Record<string, (value: string | null | undefined) => boolean>
+	param_validators?: Record<string, (_value: string | null | undefined) => boolean>
 	/** Load data for a route before navigation. May return a Promise or an array of values/promises. */
-	loaders?(params: Params): unknown | Promise<unknown> | Array<unknown | Promise<unknown>>
+	loaders?(_params: Params): unknown | Promise<unknown> | Array<unknown | Promise<unknown>>
 	/** Predicate used during match(); may be async. If it returns `false`, the route is skipped. */
-	validate?(params: Params): boolean | Promise<boolean>
+	validate?(_params: Params): boolean | Promise<boolean>
 	/** Route-level navigation guard, called on the current route when leaving it. Synchronous only; call `nav.cancel()` to prevent navigation. */
-	beforeRouteLeave?(nav: Navigation): void
+	before_route_leave?(_nav: Navigation): void
 }
 
 export interface NavigationTarget {
@@ -39,7 +39,7 @@ export interface Navigation {
 	type: 'link' | 'goto' | 'popstate' | 'leave'
 	from: NavigationTarget | null
 	to: NavigationTarget | null
-	willUnload: boolean
+	will_unload: boolean
 	cancelled: boolean
 	/** The original browser event that initiated navigation, when available. */
 	event?: Event
@@ -62,7 +62,7 @@ export type Router<T = unknown> = Navgo<T>
 export interface NavgoHistoryMeta {
 	/** Monotonic index of the current history entry for scroll restoration. */
 	idx: number
-	/** Present when the entry was created via shallow `pushState`/`replaceState`. */
+	/** Present when the entry was created via shallow `push_state`/`replace_state`. */
 	shallow?: boolean
 	/** Origin of the navigation that created this entry. */
 	type?: 'link' | 'goto' | 'popstate'
@@ -75,32 +75,32 @@ export interface Options {
 	preload_delay?: number
 	/** Disable hover/touch preloading when `false`. Default true. */
 	preload_on_hover?: boolean
-	/** Global hook fired after per-route `beforeRouteLeave`, before loaders/history change. Can cancel. */
-	before_navigate?(nav: Navigation): void
+	/** 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). */
-	after_navigate?(nav: Navigation): void
+	after_navigate?(_nav: Navigation): void
 	/** Global hook fired whenever the URL changes.
 	 *  Triggers for shallow pushes/replaces, hash changes, popstate-shallow, 404s, and full navigations.
 	 *  Receives the router's current snapshot (eg `{ url: URL, route: RouteTuple|null, params: Params }`).
 	 */
-	url_changed?(payload: any): void
+	url_changed?(_payload: any): void
 }
 
 /** Navgo default export: class-based router. */
 export default class Navgo<T = unknown> {
-	constructor(routes?: Array<RouteTuple<T>>, opts?: Options)
+	constructor(_routes?: Array<RouteTuple<T>>, _opts?: Options)
 	/** Format `url` relative to the configured base. */
-	format(url: string): string | false
+	format(_url: string): string | false
 	/** SvelteKit-like navigation that runs loaders before updating the URL. */
-	goto(url: string, opts?: { replace?: boolean }): Promise<void>
+	goto(_url: string, _opts?: { replace?: boolean }): Promise<void>
 	/** Shallow push — updates URL/state without triggering handlers. */
-	pushState(url?: string | URL, state?: any): void
+	push_state(_url?: string | URL, _state?: any): void
 	/** Shallow replace — updates URL/state without triggering handlers. */
-	replaceState(url?: string | URL, state?: any): void
+	replace_state(_url?: string | URL, _state?: any): void
 	/** Manually preload loaders for a URL (deduped). */
-	preload(url: string): Promise<unknown | void>
+	preload(_url: string): Promise<unknown | void>
 	/** Try to match `url`; returns route tuple and params or `null`. Supports async `validate`. */
-	match(url: string): Promise<MatchResult<T> | null>
+	match(_url: string): Promise<MatchResult<T> | null>
 	/** Attach history + click listeners and immediately process current location. */
 	init(): Promise<void>
 	/** Remove listeners installed by `init()`. */

package/index.js

@@ -135,12 +135,12 @@ export default class Navgo {
 		const nav = this.#make_nav({
 			type: 'leave',
 			to: null,
-			willUnload: true,
+			will_unload: true,
 			event: ev,
 		})
-		this.#current.route?.[1]?.beforeRouteLeave?.(nav)
+		this.#current.route?.[1]?.before_route_leave?.(nav)
 		if (nav.cancelled) {
-			ℹ('[🧭 navigate]', 'cancelled by beforeRouteLeave during unload')
+			ℹ('[🧭 navigate]', 'cancelled by before_route_leave during unload')
 			ev.preventDefault()
 			ev.returnValue = ''
 		}
@@ -163,7 +163,7 @@ export default class Navgo {
 	#resolve_url_and_path(url_raw) {
 		if (url_raw[0] == '/' && !this.#base_rgx.test(url_raw)) url_raw = this.#base + url_raw
 		const url = new URL(url_raw, location.href)
-		const path = this.format(url.pathname)?.match(/[^?#]*/)?.[0]
+		const path = this.format(url.pathname).match?.(/[^?#]*/)?.[0]
 		ℹ('[🧭 resolve]', { url_in: url_raw, url: url.href, path })
 		return path ? { url, path } : null
 	}
@@ -178,7 +178,8 @@ export default class Navgo {
 			!a.target &&
 			!a.download &&
 			a.host === location.host &&
-			(href[0] != '/' || this.#base_rgx.test(href))
+			href[0] != '#' &&
+			this.#base_rgx.test(a.pathname)
 			? { a, href }
 			: null
 	}
@@ -200,7 +201,7 @@ export default class Navgo {
 	/**
 	 * @returns {Navigation}
 	 */
-	#make_nav({ type, from = undefined, to = undefined, willUnload = false, event = undefined }) {
+	#make_nav({ type, from = undefined, to = undefined, will_unload = false, event = undefined }) {
 		const from_obj =
 			from !== undefined
 				? from
@@ -215,7 +216,7 @@ export default class Navgo {
 			type, // 'link' | 'goto' | 'popstate' | 'leave'
 			from: from_obj,
 			to,
-			willUnload,
+			will_unload,
 			cancelled: false,
 			event,
 			cancel() {
@@ -253,9 +254,9 @@ export default class Navgo {
 		})
 
 		//
-		// beforeRouteLeave
+		// before_route_leave
 		//
-		this.#current.route?.[1]?.beforeRouteLeave?.(nav)
+		this.#current.route?.[1]?.before_route_leave?.(nav)
 		if (nav.cancelled) {
 			// use history.go to cancel the nav, and jump back to where we are
 			if (is_popstate) {
@@ -270,7 +271,7 @@ export default class Navgo {
 					}
 				}
 			}
-			ℹ('[🧭 goto]', 'cancelled by beforeRouteLeave')
+			ℹ('[🧭 goto]', 'cancelled by before_route_leave')
 			return
 		}
 
@@ -370,13 +371,13 @@ export default class Navgo {
 		// save scroll for current index before shallow change
 		this.#save_scroll()
 		const idx = this.#route_idx + (replace ? 0 : 1)
-		const st = { ...state, __navaid: { ...state?.__navaid, shallow: true, idx } }
+		const st = { ...state, __navgo: { ...state?.__navgo, shallow: true, idx } }
 		history[(replace ? 'replace' : 'push') + 'State'](st, '', u.href)
-		ℹ('[🧭 history]', replace ? 'replaceState(shallow)' : 'pushState(shallow)', {
+		ℹ('[🧭 history]', replace ? 'replace_state(shallow)' : 'push_state(shallow)', {
 			idx,
 			href: u.href,
 		})
-		// Popstate handler checks state.__navaid.shallow and skips router processing
+		// Popstate handler checks state.__navgo.shallow and skips router processing
 		this.#route_idx = idx
 		// carry forward current scroll position for the shallow entry so Forward restores correctly
 		this.#scroll.set(idx, { x: scrollX, y: scrollY })
@@ -387,11 +388,11 @@ export default class Navgo {
 	}
 
 	/** @param {string|URL} [url] @param {any} [state] */
-	pushState(url, state) {
+	push_state(url, state) {
 		this.#commit_shallow(url, state, false)
 	}
 	/** @param {string|URL} [url] @param {any} [state] */
-	replaceState(url, state) {
+	replace_state(url, state) {
 		this.#commit_shallow(url, state, true)
 	}
 
@@ -627,7 +628,7 @@ export default class Navgo {
 				return true
 			}
 		},
-		oneOf(values) {
+		one_of(values) {
 			const set = new Set(values)
 			return v => set.has(v)
 		},

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "navgo",
-	"version": "3.0.4",
+	"version": "3.0.5",
 	"repository": {
 		"type": "git",
 		"url": "git+https://github.com/mustafa0x/navgo.git"
@@ -18,6 +18,7 @@
 		"build": "perl -0777 -i -pe 's/console.debug\\(...args\\)/{}/g' index.js",
 		"prepublishOnly": "pnpm run build",
 		"test": "vitest run index.test.js",
+		"test:e2e": "playwright test",
 		"types": "tsc -p test/types"
 	},
 	"files": [

package/readme.md

@@ -1,7 +1,7 @@
 ## Install
 
 ```
-$ pnpm install --dev navaid
+$ pnpm install --dev navgo
 ```
 
 ## Usage
@@ -26,7 +26,7 @@ const routes = [
       // load data before URL changes; result goes to after_navigate(...)
       loaders: params => fetch('/api/admin').then(r => r.json()),
       // per-route guard; cancel synchronously to block nav
-      beforeRouteLeave(nav) {
+      before_route_leave(nav) {
         if ((nav.type === 'link' || nav.type === 'nav') && !confirm('Enter admin?')) {
           nav.cancel()
         }
@@ -98,7 +98,7 @@ Notes:
 - `after_navigate`: `(nav: Navigation) => void`
   - App-level hook called after routing completes (URL updated, data loaded). `nav.to.data` holds any loader data.
 - `url_changed`: `(snapshot: any) => void`
-  - Fires on every URL change — shallow `pushState`/`replaceState`, 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.
   - 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`)
@@ -116,7 +116,7 @@ Important: Navgo only processes routes that match your `base` path.
   - Run before URL changes on `link`/`nav`. Results are cached per formatted path and forwarded to `after_navigate`.
 - validate?(params): `boolean | Promise<boolean>`
   - Predicate called during matching. If it returns or resolves to `false`, the route is skipped.
-- beforeRouteLeave?(nav): `(nav: Navigation) => void`
+- before_route_leave?(nav): `(nav: Navigation) => void`
   - Guard called once per navigation attempt on the current route (leave). Call `nav.cancel()` synchronously to prevent navigation. For `popstate`, cancellation auto-reverts the history jump.
 
 The `Navigation` object contains:
@@ -126,7 +126,7 @@ The `Navigation` object contains:
   type: 'link' | 'nav' | 'popstate' | 'leave',
   from: { url, params, route } | null,
   to:   { url, params, route } | null,
-  willUnload: boolean,
+  will_unload: boolean,
   cancelled: boolean,
   event?: Event,
   cancel(): void
@@ -152,7 +152,7 @@ const routes = [
         /* ... */
       },
       loaders: params => fetch('/api/admin/stats').then(r => r.json()),
-      beforeRouteLeave(nav) {
+      before_route_leave(nav) {
         if (nav.type === 'link' || nav.type === 'nav') {
           if (!confirm('Enter admin area?')) nav.cancel()
         }
@@ -204,7 +204,7 @@ The desired path to navigate. If it begins with `/` and does not match the confi
 Type: `Object`
 
 - replace: `Boolean` (default `false`)
-  - When `true`, uses `history.replaceState`; otherwise `history.pushState`.
+- When `true`, uses `history.replaceState`; otherwise `history.pushState`.
 
 ### init()
 
@@ -240,13 +240,13 @@ Returns: `Promise<unknown | void>`
 Preload a route's `loaders` data for a given `uri` without navigating. Concurrent calls for the same path are deduped.
 Note: Resolves to `undefined` when the matched route has no `loaders`.
 
-### pushState(url?, state?)
+### push_state(url?, state?)
 
 Returns: `void`
 
 Perform a shallow history push: updates the URL/state without triggering route processing.
 
-### replaceState(url?, state?)
+### replace_state(url?, state?)
 
 Returns: `void`
 
@@ -266,9 +266,8 @@ This section explains, in detail, how navigation is processed: matching, hooks,
 - `goto` — programmatic navigation via `router.goto(...)`.
 - `popstate` — browser back/forward.
 - `leave` — page is unloading (refresh, external navigation, tab close) via `beforeunload`.
-- `pushState` (shallow)?
 
-The router passes the type to your route-level `beforeRouteLeave(nav)` hook.
+The router passes the type to your route-level `before_route_leave(nav)` hook.
 
 ### Matching and Params
 
@@ -286,7 +285,7 @@ For `link` and `goto` navigations that match a route:
 
 ```
 [click <a>] or [router.goto()]
-        → beforeRouteLeave({ type })  // per-route guard
+        → before_route_leave({ type })  // per-route guard
         → before_navigate(nav)        // app-level start
             → cancelled? yes → stop
             → no → run loaders(params)  // may be value, Promise, or Promise[]
@@ -300,10 +299,10 @@ For `link` and `goto` navigations that match a route:
 
 ### Shallow Routing
 
-Use `pushState(url, state?)` or `replaceState(url, state?)` to update the URL/state without re-running routing logic.
+Use `push_state(url, state?)` or `replace_state(url, state?)` to update the URL/state without re-running routing logic.
 
 ```
-pushState/replaceState (shallow)
+push_state/replace_state (shallow)
     → updates history.state and URL
     → router does not process routing on shallow operations
 ```
@@ -323,7 +322,7 @@ Navgo manages scroll manually (sets `history.scrollRestoration = 'manual'`) and
   - If the URL has a `#hash`, scroll to the matching element `id` or `[name="..."]`.
   - Otherwise, scroll to the top `(0, 0)`.
 - On `popstate`: restore the saved position for the target history index; if not found but there is a `#hash`, scroll to the anchor instead.
-- Shallow `pushState`/`replaceState` never adjust scroll (routing is skipped).
+- Shallow `push_state`/`replace_state` never adjust scroll (routing is skipped).
 
 ```
 scroll flow
@@ -336,16 +335,16 @@ scroll flow
 
 - `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 `beforeRouteLeave('goto')`, calls global `before_navigate`, saves scroll, runs loaders, pushes/replaces, and completes via `after_navigate`.
+- `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.
-- `pushState(url?, state?)` — shallow push that updates the URL and `history.state` without route processing.
-- `replaceState(url?, state?)` — shallow replace that updates the URL and `history.state` without route processing.
+- `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.oneOf(iterable)` — `true` iff the value is in the provided set.
+- `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.