feat(router): Add info property to NavigationExtras

goldens/public-api/router/index.md

@@ -409,6 +409,7 @@ export interface Navigation {
 
 // @public
 export interface NavigationBehaviorOptions {
+    readonly info?: unknown;
     onSameUrlNavigation?: OnSameUrlNavigation;
     replaceUrl?: boolean;
     skipLocationChange?: boolean;

packages/router/src/models.ts

@@ -1269,4 +1269,30 @@ export interface NavigationBehaviorOptions {
    *
    */
   state?: {[k: string]: any};
+
+  /**
+   * Use this to convey transient information about this particular navigation, such as how it
+   * happened. In this way, it's different from the persisted value `state` that will be set to
+   * `history.state`. This object is assigned directly to the Router's current `Navigation`
+   * (it is not copied or cloned), so it should be mutated with caution.
+   *
+   * One example of how this might be used is to trigger different single-page navigation animations
+   * depending on how a certain route was reached. For example, consider a photo gallery app, where
+   * you can reach the same photo URL and state via various routes:
+   *
+   * - Clicking on it in a gallery view
+   * - Clicking
+   * - "next" or "previous" when viewing another photo in the album
+   * - Etc.
+   *
+   * Each of these wants a different animation at navigate time. This information doesn't make sense
+   * to store in the persistent URL or history entry state, but it's still important to communicate
+   * from the rest of the application, into the router.
+   *
+   * This information could be used in coordination with the View Transitions feature and the
+   * `onViewTransitionCreated` callback. The information might be used in the callback to set
+   * classes on the document in order to control the transition animations and remove the classes
+   * when the transition has finished animating.
+   */
+  readonly info?: unknown;
 }

packages/router/src/router.ts

@@ -190,6 +190,8 @@ export class Router {
             const mergedTree =
                 this.urlHandlingStrategy.merge(e.url, currentTransition.currentRawUrl);
             const extras = {
+              // Persist transient navigation info from the original navigation request.
+              info: currentTransition.extras.info,
               skipLocationChange: currentTransition.extras.skipLocationChange,
               // The URL is already updated at this point if we have 'eager' URL
               // updates or if the navigation was triggered by the browser (back

packages/router/test/integration.spec.ts

@@ -142,6 +142,48 @@ describe('Integration', () => {
       expectEvents(events, []);
     });
 
+    it('should set transient navigation info', async () => {
+      let observedInfo: unknown;
+      const router = TestBed.inject(Router);
+      router.resetConfig([
+        {
+          path: 'simple',
+          component: SimpleCmp,
+          canActivate: [() => {
+            observedInfo = coreInject(Router).getCurrentNavigation()?.extras?.info;
+            return true;
+          }]
+        },
+      ]);
+
+      await router.navigateByUrl('/simple', {info: 'navigation info'});
+      expect(observedInfo).toEqual('navigation info');
+    });
+
+    it('should make transient navigation info available in redirect', async () => {
+      let observedInfo: unknown;
+      const router = TestBed.inject(Router);
+      router.resetConfig([
+        {
+          path: 'redirect',
+          component: SimpleCmp,
+          canActivate: [() => coreInject(Router).parseUrl('/simple')]
+        },
+        {
+          path: 'simple',
+          component: SimpleCmp,
+          canActivate: [() => {
+            observedInfo = coreInject(Router).getCurrentNavigation()?.extras?.info;
+            return true;
+          }]
+        },
+      ]);
+
+      await router.navigateByUrl('/redirect', {info: 'navigation info'});
+      expect(observedInfo).toBe('navigation info');
+      expect(router.url).toEqual('/simple');
+    });
+
     it('should ignore empty paths in relative links',
        fakeAsync(inject([Router], (router: Router) => {
          router.resetConfig([{