Proposal: Break `beforeNavigate` into `beforeUnload` and `beforeNavigate`

[oodavid]

Describe the problem

I've been thinking a lot about the beforeNavigate interface, as you can see by my recent issues:

• We can't access goto props during beforeNavigate #8605
• beforeNavigate doesn't trigger default browser behaviour as-per the docs #8597
• beforeNavigate shouldn't trigger when <a target="_blank"> #8482

I'd like to propose breaking beforeNavigate up into two methods: beforeUnload and beforeNavigate. This would help simplify the documentation and make it explicit in how to deal with the different behaviours.

Describe the proposed solution

Here's what the documentation could look like (and thus, influence the logic)

---

beforeUnload

A navigation interceptor that triggers before SvelteKit unloads. Calling navigation.confirm() will trigger the native browser unload confirmation dialog.

beforeUnload must be called during a component initialization. It remains active as long as the component is mounted.

beforeUnload((navigation: BeforeUnload) => {
  navigation.confirm();
});

beforeNavigate

A navigation interceptor that triggers when navigating to a new URL handled by SvelteKit. Navigation can be resolved or rejected, allowing you to prompt the user for confirmation.

beforeNavigate must be called during a component initialization. It remains active as long as the component is mounted.

Basic example using window.confirm

beforeNavigate((navigation: BeforeNavigate) => {
	if(window.confirm('Are you sure?')){
		navigation.resolve();
	} else {
		navigation.reject();
	}
});

Using a custom interface

<script lang="ts">
	let attemptedNavigation: BeforeNavigate | undefined;
	beforeNavigate((navigation: BeforeNavigate) => {
		attemptedNavigation = navigation;
	});
	const cancel = () => {
		attemptedNavigation.reject();
		attemptedNavigation = undefined;
	}
	const confirm = () => {
		attemptedNavigation.resolve();
		attemptedNavigation = undefined;
	}
</script>

{#if attemptedNavigation}
	<div>
		<p>Are you sure?</p>
		<p>
			<button on:click={cancel}>Cancel</button>
			<button on:click={confirm}>Confirm</button>
		</p>
	</div>
{/if}

---

Alternatives considered

No response

Importance

would make my life easier

Additional Information

I've purposefully chosen different methods than navigation.cancel() so that we can be clear in the change of behaviour.

[dummdidumm]

Thoughts related to this: #8597 (comment)

[Rich-Harris]

I've opened #11300 which addresses the confusion around the current behaviour.

On reflection, aside from the bad docs, I think the current behaviour is what we want. As described in #8597 (comment), skipping beforeNavigate for external link clicks and leave navigations would prevent us from showing custom 'are you sure?' UI (in the external link click case) and force us to duplicate logic between beforeNavigate callbacks and beforeunload handlers.

The navigation.resolve() idea is intriguing, but I think it probably adds too much complexity. It would be burdensome for developers to always have to call resolve() (and impossible to tell when they had forgotten to call it, as opposed to not having called it yet), and it would get somewhat hairy if there was another navigation that happened in the meantime (at that point, does the from of the suspended navigation change? Or is it aborted automatically? In general we want to avoid APIs where these sorts of questions are possible).

I take the point that it's mildly cumbersome to know the intent of a navigation (i.e. the 'yes I'm sure' following an 'are you sure?' confirmation dialog) but I think that's better solved in other ways. (In most cases you can just have a local force variable that is true when you hit 'confirm', and is reset inside the beforeNavigate callback.)

As such, I'll close this issue.