FF148 NavigationPrecommitController.addHandler() docs (mdn#43004)

* FF148 NavigationPrecommitController.addHandler() docs

* Update examples

* Update intercept

Author: hamishwillee

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

@@ -117,6 +117,38 @@ The `precommitHandler()` callback takes a {{domxref("NavigationPrecommitControll
 > [!NOTE]
 > Because `precommitHandler()` can be used to cancel navigations, it will only work as expected when the event's {{domxref("Event.cancelable")}} property is `true`. Calling `intercept()` with a `precommitHandler()` on a non-cancelable event results in a `SecurityError` being thrown.
 
+### Scheduling post-commit actions in `precommitHandler()`
+
+As we saw above, you can specify a `handler()` callback in the object passed to the `intercept()` method in order to preform actions after a navigation is is committed.
+This approach works well if the actions required after commit do not depend on any actions run in the pre-commit phase.
+If they do, then you can use {{domxref("NavigationPrecommitController.addHandler()")}} in `precommitHandler()` to dynamically add a handler that will run after the navigation commits.
+
+For example, consider this code that extends the previous example for redirecting a logged-out user to a sign-in page.
+The code uses `addHandler()` to add a post-commit handler callback that shows a message explaining the redirect reason.
+Note that the handler only runs for the specific case of a redirect to the sign-in page.
+
+```js
+navigation.addEventListener("navigate", (event) => {
+  const url = new URL(event.destination.url);
+
+  if (url.pathname.startsWith("/restricted/") && !userSignedIn) {
+    event.intercept({
+      async precommitHandler(controller) {
+        controller.redirect("/signin/", {
+          state: "signin-redirect",
+          history: "push",
+        });
+
+        // Use addHandler to trigger logic once the /signin/ page commits
+        controller.addHandler(() => {
+          showMessage("Please sign in to view that content.");
+        });
+      },
+    });
+  }
+});
+```
+
 ### Responding to navigation success or failure
 
 When the promises returned by the `intercept()` handler functions fulfill, the `Navigation` object's {{domxref("Navigation/navigatesuccess_event", "navigatesuccess")}} event fires, allowing you to run cleanup code after a successful navigation has completed. If those promises reject, meaning the navigation has failed, {{domxref("Navigation/navigateerror_event", "navigateerror")}} fires instead, allowing you to gracefully handle the failure case.
@@ -137,7 +169,8 @@ Both `precommitHandler()` and `handler()` callbacks can be included inside the s
    - When the `handler()` promise fulfills and the `navigatesuccess` event fires, the navigation `finished` promise fulfills as well, to indicate the navigation is finished.
    - If `handler()` rejects, the `navigateerror` event fires, the `finished` promise rejects, and the navigation is canceled.
 
-Note that the above process is upheld even across multiple `intercept()` calls on the same `NavigateEvent`. All `precommitHandler()` callbacks are called first, and when all of them resolve, the navigation commits, and all the `handler()` callbacks are called.
+Note that the above process is upheld even across multiple `intercept()` calls on the same `NavigateEvent`, and for `handler()` callbacks added in the `precommitHandler()`.
+All `precommitHandler()` callbacks are called first, and when all of them resolve, the navigation commits, and all the `handler()` callbacks are called.
 
 ### Controlling focus behavior
 

files/en-us/web/api/navigationprecommitcontroller/addhandler/index.md

@@ -0,0 +1,75 @@
+---
+title: "NavigationPrecommitController: addHandler() method"
+short-title: addHandler()
+slug: Web/API/NavigationPrecommitController/addHandler
+page-type: web-api-instance-method
+browser-compat: api.NavigationPrecommitController.addHandler
+---
+
+{{APIRef("Navigation API")}}
+
+The **`addHandler()`** method of the {{domxref("NavigationPrecommitController")}} interface allows you to dynamically add a handler callback function in precommit code, which will then be run after the navigation has committed.
+
+This is useful when the navigation workflow depends on information that is not know until precommit code has started running.
+If the precommit and (post-commit) handler are independent, the handler can be specified in the in the [`options.handler`](/en-US/docs/Web/API/NavigateEvent/intercept#handler) argument passed to {{domxref("NavigateEvent.intercept()")}}.
+
+## Syntax
+
+```js-nolint
+addHandler(handler);
+```
+
+### Parameters
+
+- `handler`
+  - : A callback function that defines the post-commit navigation handling behavior should be; it returns a promise.
+
+    The handler callback is invoked as though it was passed to the `NavigateEvent.intercept()` method, and will run after the {{domxref("Navigation.currentEntry", "currentEntry")}} property has been updated.
+
+### Return value
+
+None (`undefined`).
+
+### Exceptions
+
+- `InvalidStateError` {{domxref("DOMException")}}
+  - : Thrown if:
+    - The originating {{domxref("NavigateEvent")}} was not intercepted or has been canceled.
+    - The {{domxref("Document")}} is not fully active.
+- `SecurityError` {{domxref("DOMException")}}
+  - : Thrown if the event {{domxref("Event/isTrusted","isTrusted")}} attribute is `false`.
+
+## Examples
+
+For more examples see {{domxref("NavigationPrecommitController")}}.
+
+### Basic usage
+
+This example shows a `precommitHandler` implementation that fetches data for a page and uses `addHandler()` to add different handlers based on the page type (the implementations of the `fetchConfig`, `setupVideoPlayer()` and `setupArticleView()` are not given).
+
+```js
+navigation.addEventListener("navigate", (event) => {
+  event.intercept({
+    async precommitHandler(controller) {
+      const pageData = await fetchConfig();
+      if (pageData.type === "video") {
+        controller.addHandler(() => setupVideoPlayer());
+      } else {
+        controller.addHandler(() => setupArticleView());
+      }
+    },
+  });
+});
+```
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- [Modern client-side routing: the Navigation API](https://developer.chrome.com/docs/web-platform/navigation-api/)

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

@@ -7,20 +7,30 @@ browser-compat: api.NavigationPrecommitController
 
 {{APIRef("Navigation API")}}
 
-The **`NavigationPrecommitController`** interface of the {{domxref("Navigation API", "Navigation API", "", "nocode")}} defines redirect behavior for a navigation [precommit handler](/en-US/docs/Web/API/NavigateEvent/intercept#precommithandler).
+The **`NavigationPrecommitController`** interface of the {{domxref("Navigation API", "Navigation API", "", "nocode")}} is passed as an argument to a navigation [precommit handler](/en-US/docs/Web/API/NavigateEvent/intercept#precommithandler) callback.
+
+The callback is used to handle any modifications to the navigation that are required before it is committed (and the destination URL is actually displayed in the browser), such as cancelling or redirecting it somewhere else as required.
+This interface provides methods to redirect to a new URL and update history and state, and to dynamically configure post-commit navigation behavior.
 
 {{InheritanceDiagram}}
 
 ## Instance methods
 
+- {{domxref("NavigationPrecommitController/addHandler", "addHandler()")}}
+  - : Adds a handler callback function that will be run after the navigation has committed, as though it has been added to {{domxref("NavigateEvent.intercept()")}} using the [`options.handler`](/en-US/docs/Web/API/NavigateEvent/intercept#handler) argument.
 - {{domxref("NavigationPrecommitController.redirect", "redirect()")}}
   - : Redirects the browser to a specified URL and specifies history behavior and any desired state information.
 
 ## Description
 
 When specifying same-document navigation behavior via the {{domxref("NavigateEvent.intercept()")}} method, it is possible to specify navigation precommit actions via the [`precommitHandler`](/en-US/docs/Web/API/NavigateEvent/intercept#precommithandler) callback. Precommit actions are used to modify or cancel in-flight navigation, or to perform work while the navigation is ongoing and before it is committed (see [Basic precommit navigation example](#basic_precommit_navigation_example)).
 
-To specify the redirect behavior, you pass a `NavigationPrecommitController` object into the `precommitHandler` callback function. Inside the function body, you can call the `NavigationPrecommitController.redirect()` method, which takes as an argument an object containing the redirect URL, plus any required history behavior and state information.
+To specify the redirect behavior, you use the `NavigationPrecommitController` object that is passed into your the `precommitHandler` callback function.
+Inside the function body, you can call the `NavigationPrecommitController.redirect()` method, which takes as an argument an object containing the redirect URL, plus any required history behavior and state information.
+
+After a navigation is committed, a post-commit handler callback can be run in order to perform operations such as fetching and rendering content.
+If the post-commit navigation code depends on data gathered at runtime in your `precommitHandler`, you can call the {{domxref("NavigationPrecommitController/addHandler", "addHandler()")}} in your precommit handler to dynamically add this post-commit handler callback.
+Note that if the post-commit code is independent of the pre-commit code you can instead pass the [`handler`](/en-US/docs/Web/API/NavigateEvent/intercept#handler) callback to the {{domxref("NavigateEvent.intercept()")}} method.
 
 See the [`intercept()` description](/en-US/docs/Web/API/NavigateEvent/intercept#description) for additional context.
 
@@ -49,6 +59,36 @@ navigation.addEventListener("navigate", (event) => {
 
 This pattern is simpler than the alternative of canceling the original navigation and starting a new one to the redirect location, because it avoids exposing the intermediate state. For example, only one {{domxref("Navigation.navigatesuccess_event", "navigatesuccess")}} or {{domxref("Navigation.navigateerror_event", "navigateerror")}} event fires, and if the navigation was triggered by a call to {{domxref("Navigation.navigate()")}}, the promise only fulfills once the redirect destination is reached.
 
+### Add handler that is conditional on precommit behavior
+
+This is a small modification of the previous example that also shows a message to the user indicating the reason they have landed on the sign-in page after the redirection.
+This uses `addHandler()` in the pre-commit handler to add the post-commit handler that displays the message.
+
+```js
+navigation.addEventListener("navigate", (event) => {
+  const url = new URL(event.destination.url);
+
+  if (url.pathname.startsWith("/restricted/") && !userSignedIn) {
+    event.intercept({
+      async precommitHandler(controller) {
+        controller.redirect("/signin/", {
+          state: "signin-redirect",
+          history: "push",
+        });
+
+        // Use addHandler to trigger logic once the /signin/ page commits
+        controller.addHandler(() => {
+          showMessage("Please sign in to view that content.");
+        });
+      },
+    });
+  }
+});
+```
+
+One benefit of this approach is that the handler only runs if the redirect is committed.
+The handler would be run for all events if it were added by passing [`options.handler`](/en-US/docs/Web/API/NavigateEvent/intercept) to `intercept()`.
+
 ## Specifications
 
 {{Specifications}}