feat(router): Option to correctly restore history on failed navigation (

#43289)

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

@@ -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;

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';
 
   /**