add docs for the Navigation API

files/en-us/web/api/navigateevent/index.md

@@ -0,0 +1,125 @@
+---
+title: NavigateEvent
+slug: Web/API/NavigateEvent
+page-type: web-api-interface
+tags:
+  - API
+  - History
+  - Interface
+  - Landing
+  - Navigate
+  - NavigateEvent
+  - Navigation API
+  - Scroll
+  - Traversal
+browser-compat: api.NavigateEvent
+---
+
+{{DefaultAPISidebar("Navigation API")}}
+
+The **`NavigateEvent`** interface of the {{domxref("Navigation API")}} is the event object for the {{domxref("Navigation/navigate_event", "navigate")}} event, which fires when [any type of navigation](https://github.com/WICG/navigation-api#appendix-types-of-navigations) is initiated (this includes usage of History API features like {{domxref("History.go()")}}). `NavigateEvent` provides access to information about that navigation, and allows developers to intercept and control the navigation handling.
+
+{{InheritanceDiagram}}
+
+## Constructor
+
+- {{domxref("NavigateEvent.NavigateEvent", "NavigateEvent()")}}
+  - : Creates a new `NavigateEvent` object instance.
+
+## Instance properties
+
+_Inherits properties from its parent, {{DOMxRef("Event")}}._
+
+- {{domxref("NavigateEvent.canIntercept", "canIntercept")}} {{ReadOnlyInline}}
+  - : Returns `true` if the navigation can be intercepted, or `false` otherwise (e.g. you can't intercept a cross-origin navigation).
+- {{domxref("NavigateEvent.destination", "destination")}} {{ReadOnlyInline}}
+  - : Returns the URL being navigated to.
+- {{domxref("NavigateEvent.downloadRequest", "downloadRequest")}} {{ReadOnlyInline}}
+  - : Returns the filename of the file requested for download, in the case of a download navigation (e.g. an {{htmlelement("a")}} or {{htmlelement("area")}} element with a `download` attribute), or `null` otherwise.
+- {{domxref("NavigateEvent.formData", "formData")}} {{ReadOnlyInline}}
+  - : Returns the {{domxref("FormData")}} object representing the submitted data in the case of a `POST` form submission, or null otherwise.
+- {{domxref("NavigateEvent.hashChange", "hashChange")}} {{ReadOnlyInline}}
+  - : Returns `true` if the navigation is a fragment navigation (i.e. to a fragment identifier in the same document), or `false` otherwise.
+- {{domxref("NavigateEvent.info", "info")}} {{ReadOnlyInline}}
+  - : Returns the `info` data value passed by the initiating navigation operation (e.g. {{domxref("Navigation.back()")}}, or {{domxref("Navigation.navigate()")}}), or `undefined` if no `info` data was passed.
+- {{domxref("NavigateEvent.navigationType", "navigationType")}} {{ReadOnlyInline}}
+  - : Returns the type of the navigation, which is one of `push`, `reload`, `replace`, or `traverse`.
+- {{domxref("NavigateEvent.signal", "signal")}} {{ReadOnlyInline}}
+  - : Returns an {{domxref("AbortSignal")}}, which will become aborted if the navigation is cancelled (e.g. by the user pressing the browser's "Stop" button).
+- {{domxref("NavigateEvent.userInitiated", "userInitiated")}} {{ReadOnlyInline}}
+  - : Returns `true` if the navigation was initiated by the user (e.g. by clicking a link, submitting a form, or pressing the browser's "Back"/"Forward" buttons), or `false` otherwise.
+
+## Instance methods
+
+_Inherits methods from its parent, {{DOMxRef("Event")}}._
+
+- {{domxref("NavigateEvent.intercept", "intercept()")}}
+  - : Intercepts this navigation, turning it into a same-document navigation to the {{domxref("NavigateEvent.destination", "destination")}} URL. It can accept a handler that defines what the navigation handling behavior should be, plus options to control autofocus ansd scroll behavior as desired.
+- {{domxref("NavigateEvent.scroll", "scroll()")}}
+  - : Can be called to manually trigger the browser-driven scrolling behavior that occurs in response to the navigation, if you want it to happen before the navigation handling has completed.
+
+## Examples
+
+### Handling a navigation using `intercept()`
+
+```js
+navigation.addEventListener('navigate', navigateEvent => {
+  // Exit early if this navigation shouldn't be intercepted, 
+  // e.g. if the navigation is cross-origin, or a download request
+  if (shouldNotIntercept(navigateEvent)) return;
+
+  const url = new URL(navigateEvent.destination.url);
+
+  if (url.pathname.startsWith('/articles/')) {
+    navigateEvent.intercept({
+      async handler() {
+        // The URL has already changed, so show a placeholder while
+        //fetching the new content, such as a spinner or loading page
+        renderArticlePagePlaceholder();
+
+        // Fetch the new content and display when ready
+        const articleContent = await getArticleContent(url.pathname);
+        renderArticlePage(articleContent);
+      },
+    });
+  }
+});
+```
+
+> **Note:** Previous to the Navigation API being available, to do something similar you'd have to listen for all click events on links, run `e.preventDefault()`, perform the appropriate {{domxref("History.pushState()")}} call, then set up the page view based on the new URL. And this wouldn't handle all navigations — only user-initiated link clicks.
+
+### Handling scrolling using `scroll()`
+
+```js
+navigation.addEventListener('navigate', navigateEvent => {
+  if (shouldNotIntercept(navigateEvent)) return;
+  const url = new URL(navigateEvent.destination.url);
+
+  if (url.pathname.startsWith('/articles/')) {
+    navigateEvent.intercept({
+      async handler() {
+        const articleContent = await getArticleContent(url.pathname);
+        renderArticlePage(articleContent);
+        navigateEvent.scroll();
+
+        const secondaryContent = await getSecondaryContent(url.pathname);
+        addSecondaryContent(secondaryContent);
+      },
+    });
+  }
+});
+```
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- [Modern client-side routing: the Navigation API](https://developer.chrome.com/docs/web-platform/navigation-api/)
+- [Navigation API explainer](https://github.com/WICG/navigation-api/blob/main/README.md)
+- Domenic Denicola's [Navigation API live demo](https://gigantic-honored-octagon.glitch.me/)

files/en-us/web/api/navigation/index.md

@@ -0,0 +1,141 @@
+---
+title: Navigation
+slug: Web/API/Navigation
+page-type: web-api-interface
+tags:
+  - API
+  - History
+  - Interface
+  - Landing
+  - Navigate
+  - Navigation
+  - Navigation API
+  - Scroll
+  - Traversal
+browser-compat: api.Navigation
+---
+
+{{DefaultAPISidebar("Navigation API")}}
+
+The **`Navigation`** interface of the {{domxref("Navigation API")}} allows control over all navigation actions for the current `window` in one central place, including initiating navigations programmatically, introspecting navigation history entries, and managing navigations as they happen.
+
+It is accessed via the {{domxref("Window.navigation")}} property.
+
+The Navigation API only creates history entries created directly in the application document (i.e. not {{htmlelement("iframe")}} navigations or cross-origin navigations), providing an accurate list of all previous history entries just for your app. This makes traversing the history a much less fragile proposition than the older {{domxref("History API")}}.
+
+{{InheritanceDiagram}}
+
+## Instance properties
+
+_Inherits properties from its parent, {{DOMxRef("EventTarget")}}._
+
+- {{domxref("Navigation.canGoBack", "canGoBack")}} {{ReadOnlyInline}}
+  - : Returns `true` if it is possible to navigate backwards in the navigation history
+    (i.e. the {{domxref("Navigation.currentEntry", "currentEntry")}} is not the first one in the history entry list),
+    and `false` if it is not.
+- {{domxref("Navigation.canGoForward", "canGoForward")}} {{ReadOnlyInline}}
+  - : Returns `true` if it is possible to navigate forwards in the navigation history
+    (i.e. the {{domxref("Navigation.currentEntry", "currentEntry")}} is not the last one in the history entry list),
+    and `false` if it is not.
+- {{domxref("Navigation.currentEntry", "currentEntry")}} {{ReadOnlyInline}}
+  - : Returns a {{domxref("NavigationHistoryEntry")}} object representing the location the user is currently
+    navigated to right now.
+- {{domxref("Navigation.transition", "transition")}} {{ReadOnlyInline}}
+  - : Returns a {{domxref("NavigationTransition")}} object representing the status of an in-progress navigation,
+    which can be used to track it. Returns `null` in no navigation is currently in progress.
+
+### `Navigation` events
+
+- {{domxref("Navigation/currententrychange_event", "currententrychange")}}
+  - : Fired when the {{domxref("Navigation.currentEntry")}} has changed.
+- {{domxref("Navigation/navigate_event", "navigate")}}
+  - : Fired when [any type of navigation](https://github.com/WICG/navigation-api#appendix-types-of-navigations) is initiated, allowing you to intercept as required.
+- {{domxref("Navigation/navigateerror_event", "navigateerror")}}
+  - : Fired when a navigation fails.
+- {{domxref("Navigation/navigatesuccess_event", "navigatesuccess")}}
+  - : Fired when a successful navigation has completed.
+
+## Instance methods
+
+_Inherits methods from its parent, {{DOMxRef("EventTarget")}}._
+
+- {{domxref("Navigation.back", "back()")}}
+  - : Navigates backwards by one entry in the navigation history.
+- {{domxref("Navigation.entries", "entries()")}}
+  - : Returns an array of {{domxref("NavigationHistoryEntry")}} objects representing all existing history entries.
+- {{domxref("Navigation.forward", "forward()")}}
+  - : Navigates forwards by one entry in the navigation history.
+- {{domxref("Navigation.navigate", "navigate()")}}
+  - : Navigates to a specific URL, updating any provided `state` in the history entries list.
+- {{domxref("Navigation.reload", "reload()")}}
+  - : Reloads the current URL, updating any provided `state` in the history entries list.
+- {{domxref("Navigation.traverseTo", "traverseTo()")}}
+  - : Navigates to a specific {{domxref("NavigationHistoryEntry")}} by {{domxref("NavigationHistoryEntry.key", "key")}},
+    passing any provided `info` to the corresponding {{domxref("NavigateEvent")}}.
+- {{domxref("Navigation.updateCurrentEntry", "updateCurrentEntry()")}}
+  - : Updates the `state` of the {{domxref("Navigation.currentEntry","currentEntry")}},
+    in cases where the state change will be independent from a navigation or reload.
+
+## Examples
+
+### Moving forwards and backwards in the history
+
+```js
+if(navigation.canGoBack) {
+  navigation.back();
+} else {
+  displayBanner('You are on the first page');
+}
+
+  ...
+
+if(navigation.canGoForward) {
+  navigation.forward();
+} else {
+  displayBanner('You are on the last page');
+}
+```
+
+### Traversing to a specific history entry
+
+```js
+// On JS startup, get the key of the first loaded page
+// so the user can always go back there.
+const {key} = navigation.currentEntry;
+backToHomeButton.onclick = () => navigation.traverseTo(key);
+
+// Navigate away, but the button will always work.
+await navigation.navigate('/another_url').finished;
+```
+
+### Navigating and updating state
+
+```js
+navigation.navigate(url, {state: newState});
+```
+
+Or
+
+```js
+navigation.reload({state: newState});
+```
+
+Or if the state is independent from a navigation or reload:
+
+```js
+navigation.updateCurrentEntry({state: newState});
+```
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- [Modern client-side routing: the Navigation API](https://developer.chrome.com/docs/web-platform/navigation-api/)
+- [Navigation API explainer](https://github.com/WICG/navigation-api/blob/main/README.md)
+- Domenic Denicola's [Navigation API live demo](https://gigantic-honored-octagon.glitch.me/)