feat(common): Add experimental support for the Navigation API (angular#63406)

The navigation API is part of interop 2025. You can find the
implementation status for each major browser here:

https://wpt.fyi/results/navigation-api?label=master&label=experimental&aligned&view=interop&q=label%3Ainterop-2025-navigation

https://developer.mozilla.org/en-US/docs/Web/API/Navigation_API

BREAKING CHANGE: (test only) - `TestBed` now provides a fake `PlatformLocation`
implementation that supports the Navigation API. This may break some
tests, though we have not observed any failures internally. You can revert to the
old default for `TestBed` by providing the `MockPlatformLocation` from
`@angular/common/testing` in your providers:
`{provide: PlatformLocation, useClass: MockPlatformLocation}`

PR Close angular#63406

Author: atscott

goldens/public-api/common/index.api.md

@@ -32,6 +32,16 @@ import { TrackByFunction } from '@angular/core';
 import { Type } from '@angular/core';
 import { Version } from '@angular/core';
 import { ViewContainerRef } from '@angular/core';
+import { ɵNavigateEvent } from '@angular/core';
+import { ɵNavigation } from '@angular/core';
+import { ɵNavigationCurrentEntryChangeEvent } from '@angular/core';
+import { ɵNavigationHistoryEntry } from '@angular/core';
+import { ɵNavigationNavigateOptions } from '@angular/core';
+import { ɵNavigationOptions } from '@angular/core';
+import { ɵNavigationReloadOptions } from '@angular/core';
+import { ɵNavigationResult } from '@angular/core';
+import { ɵNavigationTransition } from '@angular/core';
+import { ɵNavigationUpdateCurrentEntryOptions } from '@angular/core';
 
 // @public
 export const APP_BASE_HREF: InjectionToken<string>;
@@ -842,6 +852,50 @@ export abstract class PlatformLocation {
     static ɵprov: i0.ɵɵInjectableDeclaration<PlatformLocation>;
 }
 
+// @public
+export abstract class PlatformNavigation implements ɵNavigation {
+    // (undocumented)
+    abstract addEventListener(type: unknown, listener: unknown, options?: unknown): void;
+    // (undocumented)
+    abstract back(options?: ɵNavigationOptions | undefined): ɵNavigationResult;
+    // (undocumented)
+    abstract canGoBack: boolean;
+    // (undocumented)
+    abstract canGoForward: boolean;
+    // (undocumented)
+    abstract currentEntry: ɵNavigationHistoryEntry | null;
+    // (undocumented)
+    abstract dispatchEvent(event: Event): boolean;
+    // (undocumented)
+    abstract entries(): ɵNavigationHistoryEntry[];
+    // (undocumented)
+    abstract forward(options?: ɵNavigationOptions | undefined): ɵNavigationResult;
+    // (undocumented)
+    abstract navigate(url: string, options?: ɵNavigationNavigateOptions | undefined): ɵNavigationResult;
+    // (undocumented)
+    abstract oncurrententrychange: ((this: ɵNavigation, ev: ɵNavigationCurrentEntryChangeEvent) => any) | null;
+    // (undocumented)
+    abstract onnavigate: ((this: ɵNavigation, ev: ɵNavigateEvent) => any) | null;
+    // (undocumented)
+    abstract onnavigateerror: ((this: ɵNavigation, ev: ErrorEvent) => any) | null;
+    // (undocumented)
+    abstract onnavigatesuccess: ((this: ɵNavigation, ev: Event) => any) | null;
+    // (undocumented)
+    abstract reload(options?: ɵNavigationReloadOptions | undefined): ɵNavigationResult;
+    // (undocumented)
+    abstract removeEventListener(type: unknown, listener: unknown, options?: unknown): void;
+    // (undocumented)
+    abstract transition: ɵNavigationTransition | null;
+    // (undocumented)
+    abstract traverseTo(key: string, options?: ɵNavigationOptions | undefined): ɵNavigationResult;
+    // (undocumented)
+    abstract updateCurrentEntry(options: ɵNavigationUpdateCurrentEntryOptions): void;
+    // (undocumented)
+    static ɵfac: i0.ɵɵFactoryDeclaration<PlatformNavigation, never>;
+    // (undocumented)
+    static ɵprov: i0.ɵɵInjectableDeclaration<PlatformNavigation>;
+}
+
 // @public @deprecated
 export enum Plural {
     // (undocumented)

packages/common/src/common.ts

@@ -17,6 +17,7 @@ export {formatDate} from './i18n/format_date';
 export {formatCurrency, formatNumber, formatPercent} from './i18n/format_number';
 export {NgLocaleLocalization, NgLocalization} from './i18n/localization';
 export {registerLocaleData} from './i18n/locale_data';
+export {PlatformNavigation} from './navigation/platform_navigation';
 export {
   Plural,
   NumberFormatStyle,

packages/common/src/navigation/platform_navigation.ts

@@ -23,6 +23,11 @@ import {
 /**
  * This class wraps the platform Navigation API which allows server-specific and test
  * implementations.
+ *
+ * Browser support is limited, so this API may not be available in all environments,
+ * may contain bugs, and is experimental.
+ *
+ * @experimental 21.0.0
  */
 @Injectable({providedIn: 'platform', useFactory: () => (window as any).navigation})
 export abstract class PlatformNavigation implements Navigation {

packages/common/src/private_export.ts

@@ -11,4 +11,3 @@ export {
   getDOM as ɵgetDOM,
   setRootDomAdapter as ɵsetRootDomAdapter,
 } from './dom_adapter';
-export {PlatformNavigation as ɵPlatformNavigation} from './navigation/platform_navigation';

packages/common/test/navigation/navigation_spec.ts

@@ -0,0 +1,25 @@
+/**
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.dev/license
+ */
+
+import {ɵFakeNavigation as FakeNavigation} from '../../testing';
+import {PlatformNavigation} from '../../index';
+import {TestBed} from '@angular/core/testing';
+
+describe('Navigation', () => {
+  it('provides fake navigation by default', () => {
+    const nav = TestBed.inject(PlatformNavigation);
+    expect(nav).toBeInstanceOf(FakeNavigation);
+  });
+
+  it('can inject and use the navigation API by default', async () => {
+    const nav = TestBed.inject(PlatformNavigation);
+    expect(nav.entries().length).toBe(1);
+    await nav.navigate('/someUrl').finished;
+    expect(nav.entries().length).toBe(2);
+  });
+});

packages/common/testing/src/mock_platform_location.ts

@@ -11,7 +11,7 @@ import {
   LocationChangeEvent,
   LocationChangeListener,
   PlatformLocation,
-  ɵPlatformNavigation as PlatformNavigation,
+  PlatformNavigation,
 } from '../../index';
 import {Inject, inject, Injectable, InjectionToken, Optional} from '@angular/core';
 import {Subject} from 'rxjs';

packages/common/testing/src/navigation/provide_fake_platform_navigation.ts

@@ -6,11 +6,7 @@
  * found in the LICENSE file at https://angular.dev/license
  */
 
-import {
-  DOCUMENT,
-  PlatformLocation,
-  ɵPlatformNavigation as PlatformNavigation,
-} from '../../../index';
+import {DOCUMENT, PlatformLocation, PlatformNavigation} from '../../../index';
 import {inject, InjectionToken, Provider} from '@angular/core';
 
 import {

packages/platform-browser/testing/src/browser.ts

@@ -5,8 +5,7 @@
  * Use of this source code is governed by an MIT-style license that can be
  * found in the LICENSE file at https://angular.dev/license
  */
-import {PlatformLocation} from '@angular/common';
-import {MockPlatformLocation} from '@angular/common/testing';
+import {ɵprovideFakePlatformNavigation} from '@angular/common/testing';
 import {
   APP_ID,
   createPlatformFactory,
@@ -40,7 +39,7 @@ export const platformBrowserTesting: (extraProviders?: StaticProvider[]) => Plat
     {provide: APP_ID, useValue: 'a'},
     internalProvideZoneChangeDetection({}),
     {provide: ChangeDetectionScheduler, useExisting: ChangeDetectionSchedulerImpl},
-    {provide: PlatformLocation, useClass: MockPlatformLocation},
+    ɵprovideFakePlatformNavigation(),
     {provide: TestComponentRenderer, useClass: DOMTestComponentRenderer},
   ],
 })