From 3c6b653089837459809a370ebcaf8911c3bab9ed Mon Sep 17 00:00:00 2001
From: Andrew Scott <atscott@google.com>
Date: Mon, 30 Aug 2021 09:59:22 -0700
Subject: [PATCH] feat(router): Option to correctly restore history on failed
 navigation (#43289)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Exposes implementation from #38884 as a public opt-in option.

From that commit:
> We can’t determine whether the user actually meant the back or
> the forward using the popstate event (triggered by a browser
> back/forward)
> so we instead need to store information on the state and compute the
> distance the user is traveling withing the browser history.
> So by using the History#go method,
> we can bring the user back to the page where he is supposed to be after
> performing the action.

Resolves #13586

PR Close #43289
---
 goldens/public-api/router/router.md |  1 +
 packages/router/src/router.ts       | 19 ++++++++++---------
 2 files changed, 11 insertions(+), 9 deletions(-)

diff --git a/goldens/public-api/router/router.md b/goldens/public-api/router/router.md
index 96c07c34f2582..41b1855ba483b 100644
--- a/goldens/public-api/router/router.md
+++ b/goldens/public-api/router/router.md
@@ -467,6 +467,7 @@ export class RouteConfigLoadStart {
 // @public
 export class Router {
     constructor(rootComponentType: Type<any> | null, urlSerializer: UrlSerializer, rootContexts: ChildrenOutletContexts, location: Location_2, injector: Injector, loader: NgModuleFactoryLoader, compiler: Compiler, config: Routes);
+    canceledNavigationResolution: 'replace' | 'computed';
     // (undocumented)
     config: Routes;
     createUrlTree(commands: any[], navigationExtras?: UrlCreationOptions): UrlTree;
diff --git a/packages/router/src/router.ts b/packages/router/src/router.ts
index 280b671384ee0..c087670acfa18 100644
--- a/packages/router/src/router.ts
+++ b/packages/router/src/router.ts
@@ -535,19 +535,20 @@ export class Router {
    * Configures how the Router attempts to restore state when a navigation is cancelled.
    *
    * 'replace' - Always uses `location.replaceState` to set the browser state to the state of the
-   * router before the navigation started.
+   * router before the navigation started. This means that if the URL of the browser is updated
+   * _before_ the navigation is canceled, the Router will simply replace the item in history rather
+   * than trying to restore to the previous location in the session history. This happens most
+   * frequently with `urlUpdateStrategy: 'eager'` and navigations with the browser back/forward
+   * buttons.
    *
-   * 'computed' - Will always return to the same state that corresponds to the actual Angular route
-   * when the navigation gets cancelled right after triggering a `popstate` event.
+   * 'computed' - Will attempt to return to the same index in the session history that corresponds
+   * to the Angular route when the navigation gets cancelled. For example, if the browser back
+   * button is clicked and the navigation is cancelled, the Router will trigger a forward navigation
+   * and vice versa.
    *
-   * The default value is `replace`
+   * The default value is `replace`.
    *
-   * @internal
    */
-  // TODO(atscott): Determine how/when/if to make this public API
-  // This shouldn’t be an option at all but may need to be in order to allow migration without a
-  // breaking change. We need to determine if it should be made into public api (or if we forgo
-  // the option and release as a breaking change bug fix in a major version).
   canceledNavigationResolution: 'replace'|'computed' = 'replace';
 
   /**