Add onNavigate lifecycle function, to enable view transitions

.changeset/fifty-plants-repeat.md

@@ -0,0 +1,5 @@
+---
+'@sveltejs/kit': minor
+---
+
+feat: onNavigate lifecycle function

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

@@ -19,4 +19,5 @@ export const invalidateAll = BROWSER ? client.invalidateAll : guard('invalidateA
 export const preloadData = BROWSER ? client.preload_data : guard('preloadData');
 export const preloadCode = BROWSER ? client.preload_code : guard('preloadCode');
 export const beforeNavigate = BROWSER ? client.before_navigate : () => {};
+export const onNavigate = BROWSER ? client.on_navigate : () => {};
 export const afterNavigate = BROWSER ? client.after_navigate : () => {};

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

@@ -89,6 +89,9 @@ export function create_client(app, target) {
 		/** @type {Array<(navigation: import('types').BeforeNavigate) => void>} */
 		before_navigate: [],
 
+		/** @type {Array<(navigation: import('types').OnNavigate) => (() => void) | void>} */
+		on_navigate: [],
+
 		/** @type {Array<(navigation: import('types').AfterNavigate) => void>} */
 		after_navigate: []
 	};
@@ -261,6 +264,7 @@ export function create_client(app, target) {
 	 * @param {import('./types').NavigationIntent | undefined} intent
 	 * @param {URL} url
 	 * @param {string[]} redirect_chain
+	 * @param {import('types').NavigationType} [type]
 	 * @param {number} [previous_history_index]
 	 * @param {{hash?: string, scroll: { x: number, y: number } | null, keepfocus: boolean, details: { replaceState: boolean, state: any } | null}} [opts]
 	 * @param {{}} [nav_token] To distinguish between different navigation events and determine the latest. Needed for example for redirects to keep the original token
@@ -270,6 +274,7 @@ export function create_client(app, target) {
 		intent,
 		url,
 		redirect_chain,
+		type,
 		previous_history_index,
 		opts,
 		nav_token = {},
@@ -372,13 +377,47 @@ export function create_client(app, target) {
 		load_cache = null;
 
 		if (started) {
+			/** @type {import('types').OnNavigate} */
+			const navigation = {
+				from: {
+					params: current.params,
+					route: { id: current.route?.id ?? null },
+					url: current.url
+				},
+				to: {
+					params: intent?.params ?? null,
+					route: { id: intent?.route?.id ?? null },
+					url
+				},
+				willUnload: false,
+				type: /** @type {import('types').NavigationType} */ (type)
+			};
+
 			current = navigation_result.state;
 
 			// reset url before updating page store
 			if (navigation_result.props.page) {
 				navigation_result.props.page.url = url;
 			}
 
+			const after_navigate = (
+				await Promise.all(callbacks.on_navigate.map((fn) => fn(navigation)))
+			).filter((value) => typeof value === 'function');
+
+			if (after_navigate.length > 0) {
+				function cleanup() {
+					callbacks.after_navigate = callbacks.after_navigate.filter(
+						// @ts-ignore
+						(fn) => !after_navigate.includes(fn)
+					);
+				}
+
+				after_navigate.push(cleanup);
+
+				// @ts-ignore
+				callbacks.after_navigate.push(...after_navigate);
+			}
+
 			root.$set(navigation_result.props);
 		} else {
 			initialize(navigation_result);
@@ -1158,6 +1197,7 @@ export function create_client(app, target) {
 			intent,
 			url,
 			redirect_chain,
+			type,
 			previous_history_index,
 			{
 				scroll,
@@ -1364,6 +1404,17 @@ export function create_client(app, target) {
 			});
 		},
 
+		on_navigate: (fn) => {
+			onMount(() => {
+				callbacks.on_navigate.push(fn);
+
+				return () => {
+					const i = callbacks.on_navigate.indexOf(fn);
+					callbacks.on_navigate.splice(i, 1);
+				};
+			});
+		},
+
 		disable_scroll_handling: () => {
 			if (DEV && started && !updating) {
 				throw new Error('Can only disable scroll handling during navigation');

packages/kit/src/runtime/client/types.d.ts

@@ -2,6 +2,7 @@ import { applyAction } from '$app/forms';
 import {
 	afterNavigate,
 	beforeNavigate,
+	onNavigate,
 	goto,
 	invalidate,
 	invalidateAll,
@@ -51,6 +52,7 @@ export interface Client {
 	// public API, exposed via $app/navigation
 	after_navigate: typeof afterNavigate;
 	before_navigate: typeof beforeNavigate;
+	on_navigate: typeof onNavigate;
 	disable_scroll_handling(): void;
 	goto: typeof goto;
 	invalidate: typeof invalidate;

packages/kit/test/apps/basics/src/routes/after-navigate/a/+page.svelte → packages/kit/test/apps/basics/src/routes/navigation-lifecycle/after-navigate/a/+page.svelte

@@ -14,4 +14,4 @@
 </script>
 
 <h1>{from?.url.pathname} -> {to?.url.pathname}</h1>
-<a href="/after-navigate/b">/b</a>
+<a href="/navigation-lifecycle/after-navigate/b">/b</a>

packages/kit/test/apps/basics/src/routes/after-navigate/b/+page.svelte → packages/kit/test/apps/basics/src/routes/navigation-lifecycle/after-navigate/b/+page.svelte

@@ -14,4 +14,4 @@
 </script>
 
 <h1>{from?.url.pathname} -> {to?.url.pathname}</h1>
-<a href="/after-navigate/a">/a</a>
+<a href="/navigation-lifecycle/after-navigate/a">/a</a>

packages/kit/test/apps/basics/src/routes/before-navigate/prevent-navigation/+page.svelte → packages/kit/test/apps/basics/src/routes/navigation-lifecycle/before-navigate/prevent-navigation/+page.svelte

@@ -15,9 +15,9 @@
 </script>
 
 <h1>prevent navigation</h1>
-<a href="/before-navigate/a">a</a>
-<a href="/before-navigate/redirect">redirect</a>
-<a href="/before-navigate/prevent-navigation?x=1">self</a>
+<a href="/navigation-lifecycle/before-navigate/a">a</a>
+<a href="/navigation-lifecycle/before-navigate/redirect">redirect</a>
+<a href="/navigation-lifecycle/before-navigate/prevent-navigation?x=1">self</a>
 <a href="https://google.com" target="_blank" rel="noreferrer">_blank</a>
 <a href="https://google.de">external</a>
 <pre>{times_triggered} {unload} {navigation_type}</pre>

packages/kit/test/apps/basics/src/routes/navigation-lifecycle/before-navigate/redirect/+page.js

@@ -0,0 +1,5 @@
+import { redirect } from '@sveltejs/kit';
+
+export function load() {
+	throw redirect(307, '/navigation-lifecycle/before-navigate/prevent-navigation');
+}

packages/kit/test/apps/basics/src/routes/navigation-lifecycle/on-navigate/[x]/+page.svelte

@@ -0,0 +1,21 @@
+<script>
+	import { onNavigate } from '$app/navigation';
+
+	/** @type {import('@sveltejs/kit').NavigationTarget} */
+	let from;
+
+	/** @type {import('@sveltejs/kit').NavigationTarget} */
+	let to;
+
+	/** @type {Omit<import('@sveltejs/kit').NavigationType, 'enter' | 'leave'>} */
+	let type;
+
+	onNavigate((navigation) => {
+		from = navigation.from;
+		to = navigation.to;
+		type = navigation.type;
+	});
+</script>
+
+<h1>{from?.url.pathname} -> {to?.url.pathname} ({type ?? '...'})</h1>
+<a href="/navigation-lifecycle/on-navigate/b">/b</a>

packages/kit/test/apps/basics/test/cross-platform/client.test.js

@@ -111,55 +111,63 @@ test.describe('a11y', () => {
 	});
 });
 
-test.describe('beforeNavigate', () => {
-	test('prevents navigation triggered by link click', async ({ page, baseURL }) => {
-		await page.goto('/before-navigate/prevent-navigation');
+test.describe.only('Navigation lifecycle functions', () => {
+	test('beforeNavigate prevents navigation triggered by link click', async ({ page, baseURL }) => {
+		await page.goto('/navigation-lifecycle/before-navigate/prevent-navigation');
 
-		await page.click('[href="/before-navigate/a"]');
+		await page.click('[href="/navigation-lifecycle/before-navigate/a"]');
 		await page.waitForLoadState('networkidle');
 
-		expect(page.url()).toBe(baseURL + '/before-navigate/prevent-navigation');
+		expect(page.url()).toBe(baseURL + '/navigation-lifecycle/before-navigate/prevent-navigation');
 		expect(await page.innerHTML('pre')).toBe('1 false link');
 	});
 
-	test('prevents navigation to external', async ({ page, baseURL }) => {
-		await page.goto('/before-navigate/prevent-navigation');
+	test('beforeNavigate prevents navigation to external', async ({ page, baseURL }) => {
+		await page.goto('/navigation-lifecycle/before-navigate/prevent-navigation');
 		await page.click('h1'); // The browsers block attempts to prevent navigation on a frame that's never had a user gesture.
 
 		page.on('dialog', (dialog) => dialog.dismiss());
 
 		page.click('a[href="https://google.de"]'); // do NOT await this, promise only resolves after successful navigation, which never happens
 		await page.waitForTimeout(500);
 		await expect(page.locator('pre')).toHaveText('1 true link');
-		expect(page.url()).toBe(baseURL + '/before-navigate/prevent-navigation');
+		expect(page.url()).toBe(baseURL + '/navigation-lifecycle/before-navigate/prevent-navigation');
 	});
 
-	test('prevents navigation triggered by goto', async ({ page, app, baseURL }) => {
-		await page.goto('/before-navigate/prevent-navigation');
-		await app.goto('/before-navigate/a');
-		expect(page.url()).toBe(baseURL + '/before-navigate/prevent-navigation');
+	test('beforeNavigate prevents navigation triggered by goto', async ({ page, app, baseURL }) => {
+		await page.goto('/navigation-lifecycle/before-navigate/prevent-navigation');
+		await app.goto('/navigation-lifecycle/before-navigate/a');
+		expect(page.url()).toBe(baseURL + '/navigation-lifecycle/before-navigate/prevent-navigation');
 		expect(await page.innerHTML('pre')).toBe('1 false goto');
 	});
 
-	test('prevents external navigation triggered by goto', async ({ page, app, baseURL }) => {
-		await page.goto('/before-navigate/prevent-navigation');
+	test('beforeNavigate prevents external navigation triggered by goto', async ({
+		page,
+		app,
+		baseURL
+	}) => {
+		await page.goto('/navigation-lifecycle/before-navigate/prevent-navigation');
 		await app.goto('https://google.de');
-		expect(page.url()).toBe(baseURL + '/before-navigate/prevent-navigation');
+		expect(page.url()).toBe(baseURL + '/navigation-lifecycle/before-navigate/prevent-navigation');
 		expect(await page.innerHTML('pre')).toBe('1 true goto');
 	});
 
-	test('prevents navigation triggered by back button', async ({ page, app, baseURL }) => {
-		await page.goto('/before-navigate/a');
-		await app.goto('/before-navigate/prevent-navigation');
+	test('beforeNavigate prevents navigation triggered by back button', async ({
+		page,
+		app,
+		baseURL
+	}) => {
+		await page.goto('/navigation-lifecycle/before-navigate/a');
+		await app.goto('/navigation-lifecycle/before-navigate/prevent-navigation');
 		await page.click('h1'); // The browsers block attempts to prevent navigation on a frame that's never had a user gesture.
 
 		await page.goBack();
 		expect(await page.innerHTML('pre')).toBe('1 false popstate');
-		expect(page.url()).toBe(baseURL + '/before-navigate/prevent-navigation');
+		expect(page.url()).toBe(baseURL + '/navigation-lifecycle/before-navigate/prevent-navigation');
 	});
 
-	test('prevents unload', async ({ page }) => {
-		await page.goto('/before-navigate/prevent-navigation');
+	test('beforeNavigate prevents unload', async ({ page }) => {
+		await page.goto('/navigation-lifecycle/before-navigate/prevent-navigation');
 		await page.click('h1'); // The browsers block attempts to prevent navigation on a frame that's never had a user gesture.
 		const type = new Promise((fulfil) => {
 			page.on('dialog', async (dialog) => {
@@ -173,46 +181,68 @@ test.describe('beforeNavigate', () => {
 		expect(await page.innerHTML('pre')).toBe('1 true leave');
 	});
 
-	test('is not triggered on redirect', async ({ page, baseURL }) => {
-		await page.goto('/before-navigate/prevent-navigation');
+	test('beforeNavigate is not triggered on redirect', async ({ page, baseURL }) => {
+		await page.goto('/navigation-lifecycle/before-navigate/prevent-navigation');
 
-		await page.click('[href="/before-navigate/redirect"]');
+		await page.click('[href="/navigation-lifecycle/before-navigate/redirect"]');
 		await page.waitForLoadState('networkidle');
 
-		expect(page.url()).toBe(baseURL + '/before-navigate/prevent-navigation');
+		expect(page.url()).toBe(baseURL + '/navigation-lifecycle/before-navigate/prevent-navigation');
 		expect(await page.innerHTML('pre')).toBe('1 false link');
 	});
 
-	test('is not triggered on target=_blank', async ({ page, baseURL }) => {
-		await page.goto('/before-navigate/prevent-navigation');
+	test('beforeNavigate is not triggered on target=_blank', async ({ page, baseURL }) => {
+		await page.goto('/navigation-lifecycle/before-navigate/prevent-navigation');
 
 		await page.click('a[href="https://google.com"]');
 		await page.waitForTimeout(500);
 
-		expect(page.url()).toBe(baseURL + '/before-navigate/prevent-navigation');
+		expect(page.url()).toBe(baseURL + '/navigation-lifecycle/before-navigate/prevent-navigation');
 		expect(await page.innerHTML('pre')).toBe('0 false undefined');
 	});
 
-	test('is not triggered on click or popstate for hash links', async ({ page }) => {
-		await page.goto('/before-navigate/hash-links');
+	test('beforeNavigate is not triggered on click or popstate for hash links', async ({ page }) => {
+		await page.goto('/navigation-lifecycle/before-navigate/hash-links');
 
 		await page.click('a[href="#x"]');
 		await page.goBack();
 		expect(await page.textContent('h1')).toBe('before_navigate_ran: false');
 	});
 
-	test('cancel() on an unloading navigation does not prevent subsequent beforeNavigate callbacks', async ({
+	test('beforeNavigate cancel() on an unloading navigation does not prevent subsequent beforeNavigate callbacks', async ({
 		page,
 		app
 	}) => {
-		await page.goto('/before-navigate/prevent-navigation');
+		await page.goto('/navigation-lifecycle/before-navigate/prevent-navigation');
 		await page.click('h1'); // The browsers block attempts to prevent navigation on a frame that's never had a user gesture.
 
 		await app.goto('https://google.de');
-		await app.goto('/before-navigate/prevent-navigation?x=1');
+		await app.goto('/navigation-lifecycle/before-navigate/prevent-navigation?x=1');
 
 		expect(await page.innerHTML('pre')).toBe('2 false goto');
 	});
+
+	test('afterNavigate calls callback', async ({ page, clicknav }) => {
+		await page.goto('/navigation-lifecycle/after-navigate/a');
+		expect(await page.textContent('h1')).toBe(
+			'undefined -> /navigation-lifecycle/after-navigate/a'
+		);
+
+		await clicknav('[href="/navigation-lifecycle/after-navigate/b"]');
+		expect(await page.textContent('h1')).toBe(
+			'/navigation-lifecycle/after-navigate/a -> /navigation-lifecycle/after-navigate/b'
+		);
+	});
+
+	test('onNavigate calls callback', async ({ page, clicknav }) => {
+		await page.goto('/navigation-lifecycle/on-navigate/a');
+		expect(await page.textContent('h1')).toBe('undefined -> undefined (...)');
+
+		await clicknav('[href="/navigation-lifecycle/on-navigate/b"]');
+		expect(await page.textContent('h1')).toBe(
+			'/navigation-lifecycle/on-navigate/a -> /navigation-lifecycle/on-navigate/b (link)'
+		);
+	});
 });
 
 test.describe('Scrolling', () => {
@@ -404,16 +434,6 @@ test.describe('Scrolling', () => {
 	});
 });
 
-test.describe('afterNavigate', () => {
-	test('calls callback', async ({ page, clicknav }) => {
-		await page.goto('/after-navigate/a');
-		expect(await page.textContent('h1')).toBe('undefined -> /after-navigate/a');
-
-		await clicknav('[href="/after-navigate/b"]');
-		expect(await page.textContent('h1')).toBe('/after-navigate/a -> /after-navigate/b');
-	});
-});
-
 test.describe('CSS', () => {
 	test('applies generated component styles (hides announcer)', async ({ page, clicknav }) => {
 		await page.goto('/css');

packages/kit/types/ambient.d.ts

@@ -162,7 +162,9 @@ declare module '$app/forms' {
 }
 
 declare module '$app/navigation' {
-	import { BeforeNavigate, AfterNavigate } from '@sveltejs/kit';
+	import { BeforeNavigate, OnNavigate, AfterNavigate } from '@sveltejs/kit';
+
+	type MaybePromise<T> = T | Promise<T>;
 
 	/**
 	 * If called when the page is being updated following a navigation (in `onMount` or `afterNavigate` or an action, for example), this disables SvelteKit's built-in scroll handling.
@@ -263,6 +265,15 @@ declare module '$app/navigation' {
 	 * `afterNavigate` must be called during a component initialization. It remains active as long as the component is mounted.
 	 */
 	export function afterNavigate(callback: (navigation: AfterNavigate) => void): void;
+
+	/**
+	 * A lifecycle function that runs the supplied `callback` immediately before we navigate to a new URL.
+	 * 
+	 * If a function is returned from the callback, it will be called once the DOM has updated.
+	 *
+	 * `onNavigate` must be called during a component initialization. It remains active as long as the component is mounted.
+	 */
+	export function onNavigate(callback: (navigation: OnNavigate) => MaybePromise<(() => void) | void>): void;
 }
 
 declare module '$app/paths' {