From f82df6cceed94f0d73aec5a6648da1cde4ed380c Mon Sep 17 00:00:00 2001 From: Rich Harris Date: Wed, 13 Dec 2023 14:49:13 -0500 Subject: [PATCH] fix: correct documentation for `beforeNavigate` (#11300) * changeset * lint * regenerate types --------- Co-authored-by: Rich Harris --- .changeset/violet-rockets-smoke.md | 5 +++++ packages/kit/src/runtime/app/navigation.js | 8 +++++--- packages/kit/types/index.d.ts | 8 +++++--- 3 files changed, 15 insertions(+), 6 deletions(-) create mode 100644 .changeset/violet-rockets-smoke.md diff --git a/.changeset/violet-rockets-smoke.md b/.changeset/violet-rockets-smoke.md new file mode 100644 index 000000000000..7d119b92c389 --- /dev/null +++ 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 index c04e047f7680..683dcd1fde11 100644 --- 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 index e576385295a9..e20c55d52c39 100644 --- a/packages/kit/types/index.d.ts +++ b/packages/kit/types/index.d.ts @@ -1972,10 +1972,12 @@ declare module '$app/navigation' { export const preloadCode: (...urls: string[]) => Promise; /** * 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. * */