Document when and how the beforeunload dialog is shown

[hyunbinseo]

Describe the problem

beforeNavigate((navigation) => {
  if (!confirm('Hello World')) navigation.cancel();
});

This code is sufficient to trigger the browser-generated dialog.

Leave site? Changes that you made may not be saved. — Google Chrome

This can be reproduced by:

1. Calling the beforeNavigate in the root page component.
2. Starting a development server and navigating to the / page.
3. Interact with the page and then attempt to close the tab (window).

This can confuse users, since the provided "Hello World" message is not used.

Instead, the browser provided generic dialog is shown. (which is intended)

Describe the proposed solution

In the beforeNavigate documentation:

---

1. State that if navigation.willUnload is true, custom alerts cannot be shown.
2. State the reason why the browser default dialog is shown in the following usage.

beforeNavigate((navigation) => {
  if (!confirm('Hello World')) navigation.cancel();
});

---

1. Provide a way to reproduce the browser default behavior - such as calling the preventDefault() method in the beforeunload event's object.

Alternatives considered

I wasn't able to create a docs PR because I was uncertain about the way this works.

Is is because

• When the navigation.willUnload is true,
• The beforeunload event handler is used with a preventDefault()?

addEventListener("beforeunload", (event) => {});

Importance

nice to have

Additional Information

No response