Merge branch 'master' into gh-2673

sveltejs · Dec 13, 2023 · 65bd271 · 65bd271
2 parents b42f774 + f82df6c
commit 65bd271
Show file tree

Hide file tree

Showing 3 changed files with 15 additions and 6 deletions.
diff --git a/.changeset/violet-rockets-smoke.md b/.changeset/violet-rockets-smoke.md
@@ -0,0 +1,5 @@
+---
+'@sveltejs/kit': patch
+---
+
+fix: correct documentation for beforeNavigate
diff --git a/packages/kit/src/runtime/app/navigation.js b/packages/kit/src/runtime/app/navigation.js
@@ -89,10 +89,12 @@ export const preloadCode = /* @__PURE__ */ client_method('preload_code');
 
 /**
  * A navigation interceptor that triggers before we navigate to a new URL, whether by clicking a link, calling `goto(...)`, or using the browser back/forward controls.
- * Calling `cancel()` will prevent the navigation from completing. If the navigation would have directly unloaded the current page, calling `cancel` will trigger the native
- * browser unload confirmation dialog. In these cases, `navigation.willUnload` is `true`.
  *
- * When a navigation isn't client side, `navigation.to.route.id` will be `null`.
+ * Calling `cancel()` will prevent the navigation from completing. If `navigation.type === 'leave'` — meaning the user is navigating away from the app (or closing the tab) — calling `cancel` will trigger the native browser unload confirmation dialog. In this case, the navigation may or may not be cancelled depending on the user's response.
+ *
+ * When a navigation isn't to a SvelteKit-owned route (and therefore controlled by SvelteKit's client-side router), `navigation.to.route.id` will be `null`.
+ *
+ * If the navigation will (if not cancelled) cause the document to unload — in other words `'leave'` navigations and `'link'` navigations where `navigation.to.route === null` — `navigation.willUnload` is `true`.
  *
  * `beforeNavigate` must be called during a component initialization. It remains active as long as the component is mounted.
  * @type {(callback: (navigation: import('@sveltejs/kit').BeforeNavigate) => void) => void}

diff --git a/packages/kit/types/index.d.ts b/packages/kit/types/index.d.ts
@@ -1973,10 +1973,12 @@ declare module '$app/navigation' {
 	export const preloadCode: (...urls: string[]) => Promise<void>;
 	/**
 	 * A navigation interceptor that triggers before we navigate to a new URL, whether by clicking a link, calling `goto(...)`, or using the browser back/forward controls.
-	 * Calling `cancel()` will prevent the navigation from completing. If the navigation would have directly unloaded the current page, calling `cancel` will trigger the native
-	 * browser unload confirmation dialog. In these cases, `navigation.willUnload` is `true`.
 	 *
-	 * When a navigation isn't client side, `navigation.to.route.id` will be `null`.
+	 * Calling `cancel()` will prevent the navigation from completing. If `navigation.type === 'leave'` — meaning the user is navigating away from the app (or closing the tab) — calling `cancel` will trigger the native browser unload confirmation dialog. In this case, the navigation may or may not be cancelled depending on the user's response.
+	 *
+	 * When a navigation isn't to a SvelteKit-owned route (and therefore controlled by SvelteKit's client-side router), `navigation.to.route.id` will be `null`.
+	 *
+	 * If the navigation will (if not cancelled) cause the document to unload — in other words `'leave'` navigations and `'link'` navigations where `navigation.to.route === null` — `navigation.willUnload` is `true`.
 	 *
 	 * `beforeNavigate` must be called during a component initialization. It remains active as long as the component is mounted.
 	 * */