Change { replace: true } to { history: "replace" }

We can then introduce { history: "push" } which explicitly errors if we're in a convert-to-replace situation. Closes #111.

This also fixes a preexisting omission where we were not properly doing replace navigations before the document is loaded.

Author: domenic

README.md

@@ -45,7 +45,7 @@ backButtonEl.addEventListener("click", () => {
     navigation.back();
   } else {
     // If the user arrived here by typing the URL directly:
-    navigation.navigate("/product-listing", { replace: true });
+    navigation.navigate("/product-listing", { history: "replace" });
   }
 });
 ```
@@ -225,7 +225,7 @@ The current entry can be replaced with a new entry, with a new `NavigationHistor
 
 - Via `history.replaceState()`.
 
-- Via cross-document replace navigations generated by `location.replace()` or `navigation.navigate(url, { replace: true, ... })`. Note that if the navigation is cross-origin, then we'll end up in a separate navigation API history entry list for that other origin, where `key` will not be preserved.
+- Via cross-document replace navigations generated by `location.replace()` or `navigation.navigate(url, { history: "replace", ... })`. Note that if the navigation is cross-origin, then we'll end up in a separate navigation API history entry list for that other origin, where `key` will not be preserved.
 
 - When using the `navigate` event to [convert a cross-document replace navigation into a same-document navigation](#navigation-monitoring-and-interception).
 
@@ -445,7 +445,7 @@ navigation.addEventListener("navigate", e => {
         await fetch("/form-submit", { body: e.formData });
 
         // Perform a client-side "redirect" to /destination.
-        await navigation.navigate("/destination", { replace: true }).finished;
+        await navigation.navigate("/destination", { history: "replace" }).finished;
       }()));
       break;
     }
@@ -746,22 +746,24 @@ Note how unlike `history.pushState()`, `navigation.navigate()` will by default p
 
 Regardless of whether the navigation gets converted or not, calling `navigation.navigate()` in this form will clear any future entries in the joint session history. (This includes entries coming from frame navigations, or cross-origin entries: so, it can have an impact beyond just the `navigation.entries()` list.)
 
-`navigation.navigate()` also takes a `replace` option, which indicates that it will replace the current history entry in a similar manner to `location.replace()`. It is used as follows:
+`navigation.navigate()` also takes a `history` option, which controls whether the navigation will replace the current history entry in a similar manner to `location.replace()`. It is used as follows:
 
 ```js
 // Performs a navigation to the given URL, but replace the current history entry
 // instead of pushing a new one.
 // (equivalent to `location.replace(url)`)
-navigation.navigate(url, { replace: true });
+navigation.navigate(url, { history: "replace" });
 
 // Replace the URL and state at the same time.
-navigation.navigate(url, { replace: true, state });
+navigation.navigate(url, { history: "replace", state });
 
 // You can still pass along info:
-navigation.navigate(url, { replace: true, state, info });
+navigation.navigate(url, { history: "replace", state, info });
 ```
 
-Again, unlike `history.replaceState()`, `navigation.navigate(url, { replace: true })` will by default perform a full navigation. And again, single-page apps will usually intercept these using `navigate`.
+Again, unlike `history.replaceState()`, `navigation.navigate(url, { history: "replace" })` will by default perform a full navigation. And again, single-page apps will usually intercept these using `navigate`.
+
+There are two other values the `history` option can take: `"auto"`, which will usually perform a push navigation but will perform a replace navigation under special circumstances (such as when on the initial `about:blank` document or when navigating to the current URL); and `"push"`, which will always either perform a push navigation or fail if called under those special circumstances. Most developers will be fine either omitting the `history` option (which has `"auto"` behavior) or using `"replace"`.
 
 Finally, we have `navigation.reload()`. This can be used as a replacement for `location.reload()`, but it also allows passing `info` and `state`, which are useful when a single-page app intercepts the reload using the `navigate` event:
 
@@ -993,7 +995,7 @@ This can be useful for cleaning up any information in secondary stores, such as
 
 ### Current entry change monitoring
 
-The `window.navigation` object has an event, `currententrychange`, which allows the application to react to any updates to the `navigation.currentEntry` property. This includes both navigations that change its value to a new `NavigationHistoryEntry`, and calls to APIs like `history.replaceState()`, `navigation.updateCurrentEntry()`, or intercepted `navigation.navigate(url, { replace: true, state: newState })` calls that change its state or URL.
+The `window.navigation` object has an event, `currententrychange`, which allows the application to react to any updates to the `navigation.currentEntry` property. This includes both navigations that change its value to a new `NavigationHistoryEntry`, and calls to APIs like `history.replaceState()`, `navigation.updateCurrentEntry()`, or intercepted `navigation.navigate(url, { history: "replace", state: newState })` calls that change its state or URL.
 
 Unlike `navigate`, this event occurs *after* the navigation is committed. As such, it cannot be intercepted or canceled; it's just an after-the-fact notification.
 
@@ -1094,7 +1096,7 @@ For web developers using the API, here's a guide to explain how you would replac
 
 Instead of using `history.pushState(state, "", url)`, use `navigation.navigate(url, { state })` and combine it with a `navigate` handler to convert the default cross-document navigation into a same-document navigation.
 
-Instead of using `history.replaceState(state, "", url)`, use `navigation.navigate(url, { replace: true, state })`, again combined with a `navigate` handler. Note that if you omit the state value, i.e. if you say `navigation.navigate(url, { replace: true })`, then this will overwrite the entry's state with `undefined`.
+Instead of using `history.replaceState(state, "", url)`, use `navigation.navigate(url, { history: "replace", state })`, again combined with a `navigate` handler. Note that if you omit the state value, i.e. if you say `navigation.navigate(url, { history: "replace" })`, then this will overwrite the entry's state with `undefined`.
 
 Instead of using `history.back()` and `history.forward()`, use `navigation.back()` and `navigation.forward()`. Note that unlike the `history` APIs, the `navigation` APIs will ignore other frames when determining where to navigate to. This means it might move through multiple entries in the joint session history, skipping over any entries that were generated purely by other-frame navigations.
 

navigation_api.d.ts

@@ -89,7 +89,7 @@ interface NavigationOptions {
 
 interface NavigationNavigateOptions extends NavigationOptions {
   state?: unknown;
-  replace?: boolean;
+  history?: "auto"|"push"|"replace";
 }
 
 interface NavigationReloadOptions extends NavigationOptions {

spec.bs

@@ -189,7 +189,7 @@ dictionary NavigationOptions {
 
 dictionary NavigationNavigateOptions : NavigationOptions {
   any state;
-  boolean replace = false;
+  NavigationHistoryBehavior history = "auto";
 };
 
 dictionary NavigationReloadOptions : NavigationOptions {
@@ -200,6 +200,12 @@ dictionary NavigationResult {
   Promise<NavigationHistoryEntry> committed;
   Promise<NavigationHistoryEntry> finished;
 };
+
+enum NavigationHistoryBehavior {
+  "auto",
+  "push",
+  "replace"
+};
 </xmp>
 
 Each {{Navigation}} object has an associated <dfn for="Navigation">entry list</dfn>, a [=list=] of {{NavigationHistoryEntry}} objects, initially empty.
@@ -750,7 +756,7 @@ An <dfn>navigation API method navigation</dfn> is a [=struct=] with the followin
   <dd>
     <p>Navigates the current page to the given <var ignore>url</var>. <var ignore>options</var> can contain the following values:
 
-    * {{NavigationNavigateOptions/replace}} can be set to true to replace the current session history entry, instead of pushing a new one.
+    * {{NavigationNavigateOptions/history}} can be set to "{{NavigationHistoryBehavior/replace}}" to replace the current session history entry, instead of pushing a new one.
     * {{NavigationOptions/info}} can be set to any value; it will populate the {{NavigateEvent/info}} property of the corresponding {{Navigation/navigate}} event.
     * {{NavigationNavigateOptions/state}} can be set to any [=serializable object|serializable=] value; it will populate the state retrieved by {{NavigationHistoryEntry/getState()|navigation.currentEntry.getState()}} once the navigation completes, for same-document navigations. (It will be ignored for navigations that end up cross-document.)
 
@@ -787,6 +793,23 @@ An <dfn>navigation API method navigation</dfn> is a [=struct=] with the followin
 
   1. <a spec="HTML" lt="parse a URL">Parse</a> |url| relative to [=this=]'s [=relevant settings object=]. If that returns failure, then return [=an early error result=] for a "{{SyntaxError}}" {{DOMException}}. Otherwise, let |urlRecord| be the <a spec="HTML">resulting URL record</a>.
 
+  1. Let |document| be [=this=]'s [=relevant global object=]'s [=associated document=].
+
+  1. If |options|["{{NavigationNavigateOptions/history}}"] is "{{NavigationHistoryBehavior/push}}", and any of the following are true:
+
+     * |document|'s <a spec="HTML">is initial about:blank</a> is true;
+     * |document| is not <a spec="HTML">completely loaded</a>;
+     * |url| equals |document|'s [=Document/URL=]; or
+     * |url|'s [=url/scheme=] is "`javascript`"
+
+     then return [=an early error result=] for a "{{NotSupportedError}}" {{DOMException}}.
+
+     <div class="note">
+      <p>These are the conditions under which a push navigation will be converted into a replace navigation by the <a spec="HTML">navigate</a> algorithm or by the below step. If the developer explicitly requested a push, we fail to let them know it won't happen.
+
+      <p>In the future, we could consider loosening some of these conditions, e.g., allowing explicitly-requested push navigations to the current URL or before the document is completely loaded.
+     </div>
+
   1. Let |serializedState| be null.
 
   1. If |options|["{{NavigationNavigateOptions/state}}"] [=map/exists=], then set |serializedState| to [$StructuredSerializeForStorage$](|options|["{{NavigationNavigateOptions/state}}"]). If this throws an exception, then return [=an early error result=] for that exception.
@@ -795,7 +818,7 @@ An <dfn>navigation API method navigation</dfn> is a [=struct=] with the followin
 
   1. Let |info| be |options|["{{NavigationOptions/info}}"] if it exists; otherwise, undefined.
 
-  1. Let |historyHandling| be "<a for="history handling behavior">`replace`</a>" if |options|["{{NavigationNavigateOptions/replace}}"] is true; otherwise, "<a for="history handling behavior">`default`</a>".
+  1. Let |historyHandling| be "<a for="history handling behavior">`replace`</a>" if |options|["{{NavigationNavigateOptions/history}}"] is "{{NavigationHistoryBehavior/replace}}" or if |document| is not <a spec="HTML">completely loaded</a>; otherwise, "<a for="history handling behavior">`default`</a>".
 
   1. Return the result of [=performing a non-traverse navigation API navigation=] given [=this=], |urlRecord|, |serializedState|, |info|, and |historyHandling|.
 </div>