[feat] beforeNavigate and afterNavigate lifecycle functions (#3293)

* feature/add-onBeforeNavigate-listner

* minor fixes

* naming

* minor naming changs

* minor improvements

* implement requested changes

* add newline

* newline fix

* docs fixes

* docs fixes #2

* docs fixes #2

* docs spacing

* minor docs fix

* speeling fix

* remove if(browser) check

* types

* snake_case

* snake case #2

* naming

* Update documentation/docs/05-modules.md

Co-authored-by: Ben McCann <[email protected]>

* Update pnpm-lock.yaml

* add onNavigate method

* Update packages/kit/src/runtime/client/router.js

Co-authored-by: Bjorn Lu <[email protected]>

* Update packages/kit/test/test.js

Co-authored-by: Bjorn Lu <[email protected]>

* minor naming and types improvements

* add docs

* mroe docs fixes

* snake case

* improve back/forwar browser handling

* improve sveltekit:index

* remove custom event, add callbacks.

* typo fix

* docs

* remove logs

* namig

* Update packages/kit/src/runtime/client/router.js

Co-authored-by: Bjorn Lu <[email protected]>

* fixes

* improve types

* nicer format

* Added second parameter to `goto` function in tests

* Fixed `history.state` when fixing trailing slash

* Added tests for `onBeforeNavigate`

* lints

* add more tests

* reafactor

* fix if statement

* fix if statement 2

* remove unused files

* fix test

* patch changeset

* rename to beforeNavigate/afterNavigate

* typo

* make beforeNavigate callbacks synchronous

* rename internal functions

* make _navigate take non-position arguments. bit clearer

* remove sveltekit:index tests - this is non-user-facing implementation detail

* typo

* remove more sveltekit:index stuff

* separate out beforeNavigate tests

* simplify tests

* rename tests

* handle no-router case

* simplify some stuff

* only pass scroll/keepfocus to renderer

* focus beforeNavigate tests

* manage history index inside _navigate

* neaten up

* allow _navigate to handle external links; centralise logic

* pass { from, to, cancel } to beforeNavigate callbacks

* lint

* block unload if appropriate

* make goto work with external urls

* unfocus tests

* typechecking

* no longer needs to be async

* update docs

* call afterNavigate callbacks on page load

* typechecking

* Update documentation/docs/05-modules.md

Co-authored-by: Ben McCann <[email protected]>

Co-authored-by: pavelBelyaev98 <[email protected]>
Co-authored-by: Pavel Belyaev <[email protected]>
Co-authored-by: Ben McCann <[email protected]>
Co-authored-by: Bjorn Lu <[email protected]>
Co-authored-by: Patrick <[email protected]>
Co-authored-by: Ignatius Bagus <[email protected]>

Author: 6 people

.changeset/hot-dogs-fry.md

@@ -0,0 +1,5 @@
+---
+'@sveltejs/kit': patch
+---
+
+Adds beforeNavigate/afterNavigate lifecycle functions

documentation/docs/05-modules.md

@@ -19,9 +19,19 @@ import { amp, browser, dev, mode, prerendering } from '$app/env';
 ### $app/navigation
 
 ```js
-import { disableScrollHandling, goto, invalidate, prefetch, prefetchRoutes } from '$app/navigation';
+import {
+	disableScrollHandling,
+	goto,
+	invalidate,
+	prefetch,
+	prefetchRoutes,
+	beforeNavigate,
+	afterNavigate
+} from '$app/navigation';
 ```
 
+- `afterNavigate(({ from, to }: { from: URL, to: URL }) => void)` - a lifecycle function that runs when the components mounts, and after subsequent navigations while the component remains mounted
+- `beforeNavigate(({ from, to, cancel }: { from: URL, to: URL | null, cancel: () => void }) => void)` — a function that runs whenever navigation is triggered whether by clicking a link, calling `goto`, or using the browser back/forward controls. This includes navigation to external sites. `to` will be `null` if the user is closing the page. Calling `cancel` will prevent the navigation from proceeding
 - `disableScrollHandling` will, if called when the page is being updated following a navigation (in `onMount` or an action, for example), prevent SvelteKit from applying its normal scroll management. You should generally avoid this, as breaking user expectations of scroll behaviour can be disorienting.
 - `goto(href, { replaceState, noscroll, keepfocus, state })` returns a `Promise` that resolves when SvelteKit navigates (or fails to navigate, in which case the promise rejects) to the specified `href`. The second argument is optional:
   - `replaceState` (boolean, default `false`) If `true`, will replace the current `history` entry rather than creating a new one with `pushState`

packages/kit/.eslintrc.json

@@ -8,6 +8,8 @@
 		"goto": true,
 		"invalidate": true,
 		"prefetch": true,
-		"prefetchRoutes": true
+		"prefetchRoutes": true,
+		"beforeNavigate": true,
+		"afterNavigate": true
 	}
 }

packages/kit/src/runtime/app/navigation.js

@@ -19,6 +19,8 @@ export const goto = import.meta.env.SSR ? guard('goto') : goto_;
 export const invalidate = import.meta.env.SSR ? guard('invalidate') : invalidate_;
 export const prefetch = import.meta.env.SSR ? guard('prefetch') : prefetch_;
 export const prefetchRoutes = import.meta.env.SSR ? guard('prefetchRoutes') : prefetchRoutes_;
+export const beforeNavigate = import.meta.env.SSR ? () => {} : beforeNavigate_;
+export const afterNavigate = import.meta.env.SSR ? () => {} : afterNavigate_;
 
 /**
  * @type {import('$app/navigation').goto}
@@ -61,3 +63,17 @@ async function prefetchRoutes_(pathnames) {
 
 	await Promise.all(promises);
 }
+
+/**
+ * @type {import('$app/navigation').beforeNavigate}
+ */
+function beforeNavigate_(fn) {
+	if (router) router.before_navigate(fn);
+}
+
+/**
+ * @type {import('$app/navigation').afterNavigate}
+ */
+function afterNavigate_(fn) {
+	if (router) router.after_navigate(fn);
+}

packages/kit/src/runtime/client/renderer.js

@@ -291,7 +291,7 @@ export class Renderer {
 
 		// opts must be passed if we're navigating
 		if (opts) {
-			const { hash, scroll, keepfocus } = opts;
+			const { scroll, keepfocus } = opts;
 
 			if (!keepfocus) {
 				getSelection()?.removeAllRanges();
@@ -302,7 +302,7 @@ export class Renderer {
 			await tick();
 
 			if (this.autoscroll) {
-				const deep_linked = hash && document.getElementById(hash.slice(1));
+				const deep_linked = info.url.hash && document.getElementById(info.url.hash.slice(1));
 				if (scroll) {
 					scrollTo(scroll.x, scroll.y);
 				} else if (deep_linked) {
@@ -378,6 +378,11 @@ export class Renderer {
 		});
 
 		this.started = true;
+
+		if (this.router) {
+			const navigation = { from: null, to: new URL(location.href) };
+			this.router.callbacks.after_navigate.forEach((fn) => fn(navigation));
+		}
 	}
 
 	/**

packages/kit/src/runtime/client/router.js

@@ -1,3 +1,4 @@
+import { onMount } from 'svelte';
 import { get_base_uri } from './utils';
 
 function scroll_state() {
@@ -53,8 +54,21 @@ export class Router {
 		// make it possible to reset focus
 		document.body.setAttribute('tabindex', '-1');
 
-		// create initial history entry, so we can return here
-		history.replaceState(history.state || {}, '', location.href);
+		// keeping track of the history index in order to prevent popstate navigation events if needed
+		this.current_history_index = history.state?.['sveltekit:index'] ?? 0;
+
+		if (this.current_history_index === 0) {
+			// create initial history entry, so we can return here
+			history.replaceState({ ...history.state, 'sveltekit:index': 0 }, '', location.href);
+		}
+
+		this.callbacks = {
+			/** @type {Array<({ from, to, cancel }: { from: URL, to: URL | null, cancel: () => void }) => void>} */
+			before_navigate: [],
+
+			/** @type {Array<({ from, to }: { from: URL | null, to: URL }) => void>} */
+			after_navigate: []
+		};
 	}
 
 	init_listeners() {
@@ -66,8 +80,23 @@ export class Router {
 		// Reset scrollRestoration to auto when leaving page, allowing page reload
 		// and back-navigation from other pages to use the browser to restore the
 		// scrolling position.
-		addEventListener('beforeunload', () => {
-			history.scrollRestoration = 'auto';
+		addEventListener('beforeunload', (e) => {
+			let should_block = false;
+
+			const intent = {
+				from: this.renderer.current.url,
+				to: null,
+				cancel: () => (should_block = true)
+			};
+
+			this.callbacks.before_navigate.forEach((fn) => fn(intent));
+
+			if (should_block) {
+				e.preventDefault();
+				e.returnValue = '';
+			} else {
+				history.scrollRestoration = 'auto';
+			}
 		});
 
 		// Setting scrollRestoration to manual again when returning to this page.
@@ -122,7 +151,7 @@ export class Router {
 		addEventListener('sveltekit:trigger_prefetch', trigger_prefetch);
 
 		/** @param {MouseEvent} event */
-		addEventListener('click', (event) => {
+		addEventListener('click', async (event) => {
 			if (!this.enabled) return;
 
 			// Adapted from https://github.com/visionmedia/page.js
@@ -155,8 +184,6 @@ export class Router {
 			// Ignore if <a> has a target
 			if (a instanceof SVGAElement ? a.target.baseVal : a.target) return;
 
-			if (!this.owns(url)) return;
-
 			// Check if new url only differs by hash
 			if (url.href.split('#')[0] === location.href.split('#')[0]) {
 				// Call `pushState` to add url to history so going back works.
@@ -169,20 +196,48 @@ export class Router {
 				return;
 			}
 
-			const noscroll = a.hasAttribute('sveltekit:noscroll');
-			this._navigate(url, noscroll ? scroll_state() : null, false, [], url.hash, {}, 'pushState');
-			event.preventDefault();
+			this._navigate({
+				url,
+				scroll: a.hasAttribute('sveltekit:noscroll') ? scroll_state() : null,
+				keepfocus: false,
+				chain: [],
+				details: {
+					state: {},
+					replaceState: false
+				},
+				accepted: () => event.preventDefault(),
+				blocked: () => event.preventDefault()
+			});
 		});
 
 		addEventListener('popstate', (event) => {
 			if (event.state && this.enabled) {
-				const url = new URL(location.href);
-				this._navigate(url, event.state['sveltekit:scroll'], false, [], url.hash, null, null);
+				// if a popstate-driven navigation is cancelled, we need to counteract it
+				// with history.go, which means we end up back here, hence this check
+				if (event.state['sveltekit:index'] === this.current_history_index) return;
+
+				this._navigate({
+					url: new URL(location.href),
+					scroll: event.state['sveltekit:scroll'],
+					keepfocus: false,
+					chain: [],
+					details: null,
+					accepted: () => {
+						this.current_history_index = event.state['sveltekit:index'];
+					},
+					blocked: () => {
+						const delta = this.current_history_index - event.state['sveltekit:index'];
+						history.go(delta);
+					}
+				});
 			}
 		});
 	}
 
-	/** @param {URL} url */
+	/**
+	 * Returns true if `url` has the same origin and basepath as the app
+	 * @param {URL} url
+	 */
 	owns(url) {
 		return url.origin === location.origin && url.pathname.startsWith(this.base);
 	}
@@ -218,16 +273,19 @@ export class Router {
 	) {
 		const url = new URL(href, get_base_uri(document));
 
-		if (this.enabled && this.owns(url)) {
-			return this._navigate(
+		if (this.enabled) {
+			return this._navigate({
 				url,
-				noscroll ? scroll_state() : null,
+				scroll: noscroll ? scroll_state() : null,
 				keepfocus,
 				chain,
-				url.hash,
-				state,
-				replaceState ? 'replaceState' : 'pushState'
-			);
+				details: {
+					state,
+					replaceState
+				},
+				accepted: () => {},
+				blocked: () => {}
+			});
 		}
 
 		location.href = url.href;
@@ -258,22 +316,73 @@ export class Router {
 		return this.renderer.load(info);
 	}
 
+	/** @param {({ from, to }: { from: URL | null, to: URL }) => void} fn */
+	after_navigate(fn) {
+		onMount(() => {
+			this.callbacks.after_navigate.push(fn);
+
+			return () => {
+				const i = this.callbacks.after_navigate.indexOf(fn);
+				this.callbacks.after_navigate.splice(i, 1);
+			};
+		});
+	}
+
 	/**
-	 * @param {URL} url
-	 * @param {{ x: number, y: number }?} scroll
-	 * @param {boolean} keepfocus
-	 * @param {string[]} chain
-	 * @param {string} hash
-	 * @param {any} state
-	 * @param {'pushState' | 'replaceState' | null} method
+	 * @param {({ from, to, cancel }: { from: URL, to: URL | null, cancel: () => void }) => void} fn
 	 */
-	async _navigate(url, scroll, keepfocus, chain, hash, state, method) {
-		const info = this.parse(url);
+	before_navigate(fn) {
+		onMount(() => {
+			this.callbacks.before_navigate.push(fn);
+
+			return () => {
+				const i = this.callbacks.before_navigate.indexOf(fn);
+				this.callbacks.before_navigate.splice(i, 1);
+			};
+		});
+	}
 
+	/**
+	 * @param {{
+	 *   url: URL;
+	 *   scroll: { x: number, y: number } | null;
+	 *   keepfocus: boolean;
+	 *   chain: string[];
+	 *   details: {
+	 *     replaceState: boolean;
+	 *     state: any;
+	 *   } | null;
+	 *   accepted: () => void;
+	 *   blocked: () => void;
+	 * }} opts
+	 */
+	async _navigate({ url, scroll, keepfocus, chain, details, accepted, blocked }) {
+		const from = this.renderer.current.url;
+		let should_block = false;
+
+		const intent = {
+			from,
+			to: url,
+			cancel: () => (should_block = true)
+		};
+
+		this.callbacks.before_navigate.forEach((fn) => fn(intent));
+
+		if (should_block) {
+			blocked();
+			return;
+		}
+
+		const info = this.parse(url);
 		if (!info) {
-			throw new Error('Attempted to navigate to a URL that does not belong to this app');
+			location.href = url.href;
+			return new Promise(() => {
+				// never resolves
+			});
 		}
 
+		accepted();
+
 		if (!this.navigating) {
 			dispatchEvent(new CustomEvent('sveltekit:navigation-start'));
 		}
@@ -289,13 +398,24 @@ export class Router {
 		}
 
 		info.url = new URL(url.origin + pathname + url.search + url.hash);
-		if (method) history[method](state, '', info.url);
 
-		await this.renderer.handle_navigation(info, chain, false, { hash, scroll, keepfocus });
+		if (details) {
+			const change = details.replaceState ? 0 : 1;
+			details.state['sveltekit:index'] = this.current_history_index += change;
+			history[details.replaceState ? 'replaceState' : 'pushState'](details.state, '', info.url);
+		}
+
+		await this.renderer.handle_navigation(info, chain, false, {
+			scroll,
+			keepfocus
+		});
 
 		this.navigating--;
 		if (!this.navigating) {
 			dispatchEvent(new CustomEvent('sveltekit:navigation-end'));
+
+			const navigation = { from, to: url };
+			this.callbacks.after_navigate.forEach((fn) => fn(navigation));
 		}
 	}
 }

packages/kit/test/ambient.d.ts

@@ -18,6 +18,8 @@ declare global {
 
 	const invalidate: (url: string) => Promise<void>;
 	const prefetch: (url: string) => Promise<void>;
+	const beforeNavigate: (fn: (url: URL) => void | boolean) => void;
+	const afterNavigate: (fn: () => void) => void;
 	const prefetchRoutes: (urls?: string[]) => Promise<void>;
 }