navgo 3.0.5 → 3.0.6

package/index.d.ts

@@ -79,6 +79,11 @@ export interface Options {
 	before_navigate?(_nav: Navigation): void
 	/** Global hook fired after routing completes (data loaded, URL updated, handlers run). */
 	after_navigate?(_nav: Navigation): void
+	/** Optional hook awaited after `after_navigate` and before scroll handling.
+	 *  Useful for UI frameworks (e.g., Svelte) to flush DOM updates so anchor/top
+	 *  scrolling lands on the correct elements.
+	 */
+	tick?: () => void | Promise<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 }`).

package/index.js

@@ -3,6 +3,7 @@ import { parse } from 'regexparam'
 const ℹ = (...args) => {}
 
 export default class Navgo {
+	/** @type {Options} */
 	#opts = {
 		base: '/',
 		preload_delay: 20,
@@ -10,25 +11,36 @@ export default class Navgo {
 		before_navigate: undefined,
 		after_navigate: undefined,
 		url_changed: undefined,
+		tick: undefined,
 	}
+	/** @type {Array<{ pattern: RegExp, keys: string[]|null, data: RouteTuple }>} */
 	#routes = []
+	/** @type {string} */
 	#base = '/'
+	/** @type {RegExp} */
 	#base_rgx = /^\/+/
-	// preload cache: href -> { promise, data, error }
+	/** @type {Map<string, { promise?: Promise<any>, data?: any }>} */
 	#preloads = new Map()
-	// last matched route info
+	/** @type {{ url: URL|null, route: RouteTuple|null, params: Params }} */
 	#current = { url: null, route: null, params: {} }
+	/** @type {number} */
 	#route_idx = 0
-	#scroll = new Map()
+	/** @type {boolean} */
 	#hash_navigating = false
+	/** @type {Map<number, Map<string, { x: number, y: number }>>} */
+	#areas_pos = new Map()
 	// Latest-wins nav guard: monotonic id and currently active id
+	/** @type {number} */
 	#nav_seq = 0
+	/** @type {number} */
 	#nav_active = 0
+	/** @type {(e: Event) => void | null} */
+	#scroll_handler = null
 
 	//
 	// Event listeners
 	//
-	#click = e => {
+	#click = async e => {
 		ℹ('[🧭 event:click]', { type: e?.type, target: e?.target })
 		const info = this.#link_from_event(e, true)
 		if (!info) return
@@ -53,12 +65,23 @@ export default class Navgo {
 
 			// different hash on same path — let browser update URL + scroll
 			this.#hash_navigating = true
-			this.#save_scroll()
 			ℹ('[🧭 hash]', 'navigate', { href: url.href })
 			return
 		}
 
 		e.preventDefault()
+
+		// allow the browser to repaint before navigating —
+		// this prevents INP scores being penalised
+		await new Promise(fulfil => {
+			requestAnimationFrame(() => {
+				setTimeout(fulfil, 0)
+			})
+
+			// fallback for edge case where rAF doesn't fire because e.g. tab was backgrounded
+			setTimeout(fulfil, 100)
+		})
+
 		ℹ('[🧭 link]', 'intercept', { href: info.href })
 		this.goto(info.href, { replace: false }, 'link', e)
 	}
@@ -101,12 +124,28 @@ export default class Navgo {
 			history.replaceState(next_state, '', location.href)
 			this.#route_idx = next_idx
 			ℹ('[🧭 event:hashchange]', { idx: next_idx, href: location.href })
+		} else {
+			// hashchange via Back/Forward — restore previous position when hash is removed
+			const idx = history.state?.__navgo?.idx
+			if (typeof idx === 'number') this.#route_idx = idx
+			if (!location.hash) {
+				const pos = this.#areas_pos.get(this.#route_idx)?.get?.('window')
+				if (pos) {
+					scrollTo(pos.x, pos.y)
+					ℹ('[🧭 scroll]', 'restore hash-back', { idx: this.#route_idx, ...pos })
+				} else {
+					// no saved position for previous entry — default to top
+					scrollTo(0, 0)
+					ℹ('[🧭 scroll]', 'hash-back -> top')
+				}
+			}
 		}
 		// update current URL snapshot and notify
 		this.#current.url = new URL(location.href)
 		this.#opts.url_changed?.(this.#current)
 	}
 
+	/** @type {any} */
 	#hover_timer = null
 	#maybe_preload = ev => {
 		const info = this.#link_from_event(ev, ev.type === 'mousedown')
@@ -121,6 +160,24 @@ export default class Navgo {
 	}
 	#tap = ev => this.#maybe_preload(ev)
 
+	#on_scroll = e => {
+		// prevent hash from overwriting the previous entry’s saved position.
+		if (this.#hash_navigating) return
+
+		const el = e?.target
+		const id =
+			!el || el === window || el === document ? 'window' : el?.dataset?.scrollId || el?.id
+		if (!id) return
+		const pos =
+			id === 'window'
+				? { x: scrollX || 0, y: scrollY || 0 }
+				: { x: el.scrollLeft || 0, y: el.scrollTop || 0 }
+		const m = this.#areas_pos.get(this.#route_idx) || new Map()
+		m.set(String(id), pos)
+		this.#areas_pos.set(this.#route_idx, m)
+		ℹ('[🧭 scroll:set]', this.#route_idx, m)
+	}
+
 	#before_unload = ev => {
 		// persist scroll for refresh / session restore
 		try {
@@ -178,7 +235,6 @@ export default class Navgo {
 			!a.target &&
 			!a.download &&
 			a.host === location.host &&
-			href[0] != '#' &&
 			this.#base_rgx.test(a.pathname)
 			? { a, href }
 			: null
@@ -226,8 +282,6 @@ export default class Navgo {
 	}
 
 	/**
-	 * Programmatic navigation that runs loaders before changing URL.
-	 * Also used by popstate to unify the flow.
 	 * @param {string} [url_raw]
 	 * @param {{ replace?: boolean }} [opts]
 	 * @param {'goto'|'link'|'popstate'} [nav_type]
@@ -283,7 +337,6 @@ export default class Navgo {
 			from: nav.from?.url?.href,
 			to: url.href,
 		})
-		this.#save_scroll()
 		const hit = await this.match(path)
 		if (nav_id !== this.#nav_active) return
 
@@ -351,6 +404,7 @@ export default class Navgo {
 		})
 		// await so that apply_scroll is after potential async work
 		await this.#opts.after_navigate?.(nav)
+
 		if (nav_id !== this.#nav_active) return
 		ℹ('[🧭 navigate]', hit ? 'done' : 'done (404)', {
 			from: nav.from?.url?.href,
@@ -358,18 +412,33 @@ export default class Navgo {
 			type: nav.type,
 			idx: this.#route_idx,
 		})
+
+		// allow frameworks to flush DOM before scrolling
+		await this.#opts.tick?.()
+
 		this.#apply_scroll(nav)
 		this.#opts.url_changed?.(this.#current)
 	}
 
 	/**
 	 * Shallow push — updates the URL/state but DOES NOT call handlers or loaders.
-	 * URL changes, content stays put until a real nav.
 	 */
 	#commit_shallow(url, state, replace) {
 		const u = new URL(url || location.href, location.href)
-		// save scroll for current index before shallow change
-		this.#save_scroll()
+		// persist current entry's scroll into its state so Back after refresh restores it
+		const prev = history.state && typeof history.state == 'object' ? history.state : {}
+		history.replaceState(
+			{ ...prev, __navgo: { ...prev.__navgo, pos: { x: scrollX || 0, y: scrollY || 0 } } },
+			'',
+			location.href,
+		)
+		// also stash per-URL scroll in session storage as a fallback across reloads
+		try {
+			sessionStorage.setItem(
+				`__navgo_scroll:${location.href}`,
+				JSON.stringify({ x: scrollX || 0, y: scrollY || 0 }),
+			)
+		} catch {}
 		const idx = this.#route_idx + (replace ? 0 : 1)
 		const st = { ...state, __navgo: { ...state?.__navgo, shallow: true, idx } }
 		history[(replace ? 'replace' : 'push') + 'State'](st, '', u.href)
@@ -379,8 +448,10 @@ export default class Navgo {
 		})
 		// 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 })
+		// carry forward current window position for the shallow entry so Forward restores correctly
+		const m = this.#areas_pos.get(idx) || new Map()
+		m.set('window', { x: scrollX || 0, y: scrollY || 0 })
+		this.#areas_pos.set(idx, m)
 		if (!replace) this.#clear_onward_history()
 		// update current URL snapshot and notify
 		this.#current.url = u
@@ -511,6 +582,8 @@ export default class Navgo {
 		addEventListener('click', this.#click)
 		addEventListener('beforeunload', this.#before_unload)
 		addEventListener('hashchange', this.#on_hashchange)
+		this.#scroll_handler = throttle(this.#on_scroll, 100)
+		addEventListener('scroll', this.#scroll_handler, { capture: true })
 
 		if (this.#opts.preload_on_hover) {
 			// @ts-expect-error
@@ -545,18 +618,12 @@ export default class Navgo {
 		removeEventListener('mousedown', this.#tap)
 		removeEventListener('beforeunload', this.#before_unload)
 		removeEventListener('hashchange', this.#on_hashchange)
-	}
-
-	//
-	// Scroll
-	//
-	#save_scroll() {
-		this.#scroll.set(this.#route_idx, { x: scrollX, y: scrollY })
-		ℹ('[🧭 scroll]', 'save', { idx: this.#route_idx, x: scrollX, y: scrollY })
+		removeEventListener('scroll', this.#scroll_handler, { capture: true })
+		this.#areas_pos.clear()
 	}
 
 	#clear_onward_history() {
-		for (const k of this.#scroll.keys()) if (k > this.#route_idx) this.#scroll.delete(k)
+		for (const k of this.#areas_pos.keys()) if (k > this.#route_idx) this.#areas_pos.delete(k)
 		ℹ('[🧭 scroll]', 'clear onward', { upto: this.#route_idx })
 	}
 
@@ -579,18 +646,36 @@ export default class Navgo {
 			// 1) On back/forward, restore saved position if available
 			if (t === 'popstate') {
 				const ev_state = ctx?.state ?? ctx?.event?.state
-				const idx = ev_state?.__navgo?.idx
+				const st = ev_state?.__navgo
+				const idx = st?.idx
 				const target_idx = typeof idx === 'number' ? idx : this.#route_idx - 1
 				this.#route_idx = target_idx
-				const pos = this.#scroll.get(target_idx)
+				const m = this.#areas_pos.get(target_idx)
+				let pos = st?.pos || m?.get?.('window')
+				if (!pos) {
+					try {
+						const k = `__navgo_scroll:${location.href}`
+						pos = JSON.parse(sessionStorage.getItem(k)) || null
+						sessionStorage.removeItem(k)
+					} catch {}
+				}
 				if (pos) {
 					scrollTo(pos.x, pos.y)
-					ℹ('[🧭 scroll]', 'restore popstate', {
-						idx: target_idx,
-						...pos,
-					})
-					return
+					// re-apply on next tick to resist late reflows (e.g. images)
+					setTimeout(() => scrollTo(pos.x, pos.y), 0)
+					ℹ('[🧭 scroll]', 'restore popstate', { idx: target_idx, ...pos })
+				}
+				for (const [id, p] of m || []) {
+					if (id === 'window') continue
+					const sel = `[data-scroll-id="${CSS.escape(id)}"],` + `#${CSS.escape(id)}`
+					const el = document.querySelector(sel)
+					if (el) {
+						el.scrollTo?.(p.x, p.y)
+						el.scrollLeft = p.x
+						el.scrollTop = p.y
+					}
 				}
+				if (pos || m) return
 			}
 			// 2) If there is a hash, prefer anchor scroll
 			if (hash && this.#scroll_to_hash(hash)) {
@@ -635,6 +720,27 @@ export default class Navgo {
 	}
 }
 
+function throttle(fn, ms) {
+	let t,
+		last = 0
+	return e => {
+		const now = Date.now()
+		if (now - last >= ms) {
+			last = now
+			fn(e)
+		} else {
+			clearTimeout(t)
+			t = setTimeout(
+				() => {
+					last = Date.now()
+					fn(e)
+				},
+				ms - (now - last),
+			)
+		}
+	}
+}
+
 /** @typedef {import('./index.d.ts').Options} Options */
 /** @typedef {import('./index.d.ts').RouteTuple} RouteTuple */
 /** @typedef {import('./index.d.ts').MatchResult} MatchResult */

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "navgo",
-	"version": "3.0.5",
+	"version": "3.0.6",
 	"repository": {
 		"type": "git",
 		"url": "git+https://github.com/mustafa0x/navgo.git"
@@ -16,9 +16,10 @@
 	},
 	"scripts": {
 		"build": "perl -0777 -i -pe 's/console.debug\\(...args\\)/{}/g' index.js",
-		"prepublishOnly": "pnpm run build",
+		"prepublishOnly": "pnpm test && pnpm run build",
 		"test": "vitest run index.test.js",
 		"test:e2e": "playwright test",
+		"start:testsite": "pnpm vite dev test/site --port 5714",
 		"types": "tsc -p test/types"
 	},
 	"files": [

package/readme.md

@@ -51,6 +51,9 @@ const router = new Navgo(routes, {
 
     console.log('after_navigate', nav.to?.url.pathname, nav.to?.data)
   },
+  // let your framework flush DOM before scroll
+  // e.g. in Svelte: `import { tick } from 'svelte'`
+  tick: tick,
   url_changed(cur) {
     // fires on shallow/hash/popstate-shallow/404 and full navigations
     // `cur` is the router snapshot: { url: URL, route, params }
@@ -97,6 +100,8 @@ Notes:
   - App-level hook called once per navigation attempt after the per-route guard and before loaders/URL update. May call `nav.cancel()` synchronously to prevent navigation.
 - `after_navigate`: `(nav: Navigation) => void`
   - App-level hook called after routing completes (URL updated, data loaded). `nav.to.data` holds any loader data.
+- `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.
   - Receives the router's current snapshot: an object like `{ url: URL, route: RouteTuple|null, params: Params }`.
@@ -233,6 +238,26 @@ Notes:
 
 On `beforeunload`, the current scroll position is saved to `sessionStorage` and restored on the next load of the same URL (e.g., refresh or tab restore).
 
+### Scroll Restoration (areas)
+
+Navgo caches/restores scroll positions for the window and any scrollable element that has a stable identifier:
+
+- Give your element either an `id` or `data-scroll-id="..."`.
+- Navgo listens to `scroll` globally (capture) and records positions per history entry.
+- On `popstate`, it restores matching elements before paint.
+
+Example:
+
+```html
+<div id="pane" class="overflow-auto">...</div>
+```
+
+Or with a custom id:
+
+```html
+<div data-scroll-id="pane">...</div>
+```
+
 ### preload(uri)
 
 Returns: `Promise<unknown | void>`
@@ -292,6 +317,8 @@ For `link` and `goto` navigations that match a route:
             → cache data by formatted path
             → history.push/replaceState(new URL)
             → after_navigate(nav)
+            → tick()?                 // optional app-provided await before scroll
+            → scroll restore/hash/top
 ```
 
 - If a loader throws/rejects, navigation continues and `after_navigate(..., with nav.to.data = { __error })` is delivered so UI can render an error state.
@@ -348,3 +375,11 @@ scroll flow
 - `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.
+
+# Credits
+
+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