feat(router): Opt-in for binding Router information to component inputs (#49633)

atscott · dylhunn · commit f982a3f96599 · 2023-03-30T16:10:54.000-07:00
Adds ability for `RouterOutlet` to bind `Router` information to the routed component's inputs. This commit also exposes some helpers for implementers of custom outlets to do their own input binding if desired. Resolves #18967 PR Close #49633
diff --git a/goldens/public-api/router/index.md b/goldens/public-api/router/index.md
@@ -293,6 +293,7 @@ export const enum EventType {
 
 // @public
 export interface ExtraOptions extends InMemoryScrollingOptions, RouterConfigOptions {
+    bindToComponentInputs?: boolean;
     enableTracing?: boolean;
     // @deprecated
     errorHandler?: (error: any) => any;
@@ -688,6 +689,7 @@ export class Router {
     constructor();
     // @deprecated
     canceledNavigationResolution: 'replace' | 'computed';
+    readonly componentInputBindingEnabled: boolean;
     // (undocumented)
     config: Routes;
     createUrlTree(commands: any[], navigationExtras?: UrlCreationOptions): UrlTree;
@@ -780,7 +782,7 @@ export interface RouterFeature<FeatureKind extends RouterFeatureKind> {
 }
 
 // @public
-export type RouterFeatures = PreloadingFeature | DebugTracingFeature | InitialNavigationFeature | InMemoryScrollingFeature | RouterConfigurationFeature | NavigationErrorHandlerFeature;
+export type RouterFeatures = PreloadingFeature | DebugTracingFeature | InitialNavigationFeature | InMemoryScrollingFeature | RouterConfigurationFeature | NavigationErrorHandlerFeature | ComponentInputBindingFeature;
 
 // @public
 export type RouterHashLocationFeature = RouterFeature<RouterFeatureKind.RouterHashLocationFeature>;
@@ -892,6 +894,8 @@ export class RouterOutlet implements OnDestroy, OnInit, RouterOutletContract {
     // (undocumented)
     ngOnInit(): void;
     // (undocumented)
+    readonly supportsBindingToComponentInputs = true;
+    // (undocumented)
     static ɵdir: i0.ɵɵDirectiveDeclaration<RouterOutlet, "router-outlet", ["outlet"], { "name": { "alias": "name"; "required": false; }; }, { "activateEvents": "activate"; "deactivateEvents": "deactivate"; "attachEvents": "attach"; "detachEvents": "detach"; }, never, never, true, never>;
     // (undocumented)
     static ɵfac: i0.ɵɵFactoryDeclaration<RouterOutlet, never>;
@@ -911,6 +915,7 @@ export interface RouterOutletContract {
     detach(): ComponentRef<unknown>;
     detachEvents?: EventEmitter<unknown>;
     isActivated: boolean;
+    readonly supportsBindingToComponentInputs?: true;
 }
 
 // @public
@@ -1092,6 +1097,9 @@ export class UrlTree {
 // @public (undocumented)
 export const VERSION: Version;
 
+// @public
+export function withComponentInputBinding(): ComponentInputBindingFeature;
+
 // @public
 export function withDebugTracing(): DebugTracingFeature;
 
diff --git a/packages/core/test/bundling/router/bundle.golden_symbols.json b/packages/core/test/bundling/router/bundle.golden_symbols.json
@@ -275,6 +275,9 @@
   {
     "name": "INJECTOR_SCOPE"
   },
+  {
+    "name": "INPUT_BINDER"
+  },
   {
     "name": "INTERNAL_APPLICATION_ERROR_HANDLER"
   },
diff --git a/packages/router/src/directives/router_outlet.ts b/packages/router/src/directives/router_outlet.ts
@@ -6,7 +6,9 @@
  * found in the LICENSE file at https://angular.io/license
  */
 
-import {ChangeDetectorRef, ComponentRef, Directive, EnvironmentInjector, EventEmitter, inject, Injector, Input, OnDestroy, OnInit, Output, SimpleChanges, ViewContainerRef, ɵRuntimeError as RuntimeError,} from '@angular/core';
+import {ChangeDetectorRef, ComponentRef, Directive, EnvironmentInjector, EventEmitter, inject, Injectable, InjectionToken, Injector, Input, OnDestroy, OnInit, Output, reflectComponentType, SimpleChanges, ViewContainerRef, ɵRuntimeError as RuntimeError,} from '@angular/core';
+import {combineLatest, Subscription} from 'rxjs';
+import {switchMap} from 'rxjs/operators';
 
 import {RuntimeErrorCode} from '../errors';
 import {Data} from '../models';
@@ -96,6 +98,16 @@ export interface RouterOutletContract {
    * subtree.
    */
   detachEvents?: EventEmitter<unknown>;
+
+  /**
+   * Used to indicate that the outlet is able to bind data from the `Router` to the outlet
+   * component's inputs.
+   *
+   * When this is `undefined` or `false` and the developer has opted in to the
+   * feature using `withComponentInputBinding`, a warning will be logged in dev mode if this outlet
+   * is used in the application.
+   */
+  readonly supportsBindingToComponentInputs?: true;
 }
 
 /**
@@ -156,6 +168,10 @@ export interface RouterOutletContract {
 })
 export class RouterOutlet implements OnDestroy, OnInit, RouterOutletContract {
   private activated: ComponentRef<any>|null = null;
+  /** @internal */
+  get activatedComponentRef(): ComponentRef<any>|null {
+    return this.activated;
+  }
   private _activatedRoute: ActivatedRoute|null = null;
   /**
    * The name of the outlet
@@ -181,6 +197,9 @@ export class RouterOutlet implements OnDestroy, OnInit, RouterOutletContract {
   private location = inject(ViewContainerRef);
   private changeDetector = inject(ChangeDetectorRef);
   private environmentInjector = inject(EnvironmentInjector);
+  private inputBinder = inject(INPUT_BINDER, {optional: true});
+  /** @nodoc */
+  readonly supportsBindingToComponentInputs = true;
 
   /** @nodoc */
   ngOnChanges(changes: SimpleChanges) {
@@ -208,6 +227,7 @@ export class RouterOutlet implements OnDestroy, OnInit, RouterOutletContract {
     if (this.isTrackedInParentContexts(this.name)) {
       this.parentContexts.onChildOutletDestroyed(this.name);
     }
+    this.inputBinder?.unsubscribeFromRouteData(this);
   }
 
   private isTrackedInParentContexts(outletName: string) {
@@ -293,6 +313,7 @@ export class RouterOutlet implements OnDestroy, OnInit, RouterOutletContract {
     this.activated = ref;
     this._activatedRoute = activatedRoute;
     this.location.insert(ref.hostView);
+    this.inputBinder?.bindActivatedRouteToOutletComponent(this);
     this.attachEvents.emit(ref.instance);
   }
 
@@ -328,6 +349,7 @@ export class RouterOutlet implements OnDestroy, OnInit, RouterOutletContract {
     // Calling `markForCheck` to make sure we will run the change detection when the
     // `RouterOutlet` is inside a `ChangeDetectionStrategy.OnPush` component.
     this.changeDetector.markForCheck();
+    this.inputBinder?.bindActivatedRouteToOutletComponent(this);
     this.activateEvents.emit(this.activated.instance);
   }
 }
@@ -349,3 +371,70 @@ class OutletInjector implements Injector {
     return this.parent.get(token, notFoundValue);
   }
 }
+
+export const INPUT_BINDER = new InjectionToken<RoutedComponentInputBinder>('');
+
+/**
+ * Injectable used as a tree-shakable provider for opting in to binding router data to component
+ * inputs.
+ *
+ * The RouterOutlet registers itself with this service when an `ActivatedRoute` is attached or
+ * activated. When this happens, the service subscribes to the `ActivatedRoute` observables (params,
+ * queryParams, data) and sets the inputs of the component using `ComponentRef.setInput`.
+ * Importantly, when an input does not have an item in the route data with a matching key, this
+ * input is set to `undefined`. If it were not done this way, the previous information would be
+ * retained if the data got removed from the route (i.e. if a query parameter is removed).
+ *
+ * The `RouterOutlet` should unregister itself when destroyed via `unsubscribeFromRouteData` so that
+ * the subscriptions are cleaned up.
+ */
+@Injectable()
+export class RoutedComponentInputBinder {
+  private outletDataSubscriptions = new Map<RouterOutlet, Subscription>;
+
+  bindActivatedRouteToOutletComponent(outlet: RouterOutlet) {
+    this.unsubscribeFromRouteData(outlet);
+    this.subscribeToRouteData(outlet);
+  }
+
+  unsubscribeFromRouteData(outlet: RouterOutlet) {
+    this.outletDataSubscriptions.get(outlet)?.unsubscribe();
+    this.outletDataSubscriptions.delete(outlet);
+  }
+
+  private subscribeToRouteData(outlet: RouterOutlet) {
+    const {activatedRoute} = outlet;
+    const dataSubscription =
+        combineLatest([
+          activatedRoute.queryParams,
+          activatedRoute.params,
+          activatedRoute.data,
+        ])
+            .pipe(switchMap(([queryParams, params, data]) => {
+              // Promise.resolve is used to avoid synchronously writing the wrong data when two of
+              // the Observables in the `combineLatest` stream emit one after another.
+              return Promise.resolve({...queryParams, ...params, ...data});
+            }))
+            .subscribe(data => {
+              // Outlet may have been deactivated or changed names to be associated with a different
+              // route
+              if (!outlet.isActivated || !outlet.activatedComponentRef ||
+                  outlet.activatedRoute !== activatedRoute || activatedRoute.component === null) {
+                this.unsubscribeFromRouteData(outlet);
+                return;
+              }
+
+              const mirror = reflectComponentType(activatedRoute.component);
+              if (!mirror) {
+                this.unsubscribeFromRouteData(outlet);
+                return;
+              }
+
+              for (const {templateName} of mirror.inputs) {
+                outlet.activatedComponentRef.setInput(templateName, data[templateName]);
+              }
+            });
+
+    this.outletDataSubscriptions.set(outlet, dataSubscription);
+  }
+}
diff --git a/packages/router/src/index.ts b/packages/router/src/index.ts
@@ -16,7 +16,7 @@ export {CanActivateChildFn, CanActivateFn, CanDeactivateFn, CanLoadFn, CanMatchF
 export * from './models_deprecated';
 export {Navigation, NavigationExtras, UrlCreationOptions} from './navigation_transition';
 export {DefaultTitleStrategy, TitleStrategy} from './page_title_strategy';
-export {DebugTracingFeature, DisabledInitialNavigationFeature, EnabledBlockingInitialNavigationFeature, InitialNavigationFeature, InMemoryScrollingFeature, NavigationErrorHandlerFeature, PreloadingFeature, provideRouter, provideRoutes, RouterConfigurationFeature, RouterFeature, RouterFeatures, RouterHashLocationFeature, withDebugTracing, withDisabledInitialNavigation, withEnabledBlockingInitialNavigation, withHashLocation, withInMemoryScrolling, withNavigationErrorHandler, withPreloading, withRouterConfig} from './provide_router';
+export {DebugTracingFeature, DisabledInitialNavigationFeature, EnabledBlockingInitialNavigationFeature, InitialNavigationFeature, InMemoryScrollingFeature, NavigationErrorHandlerFeature, PreloadingFeature, provideRouter, provideRoutes, RouterConfigurationFeature, RouterFeature, RouterFeatures, RouterHashLocationFeature, withComponentInputBinding, withDebugTracing, withDisabledInitialNavigation, withEnabledBlockingInitialNavigation, withHashLocation, withInMemoryScrolling, withNavigationErrorHandler, withPreloading, withRouterConfig} from './provide_router';
 export {BaseRouteReuseStrategy, DetachedRouteHandle, RouteReuseStrategy} from './route_reuse_strategy';
 export {Router} from './router';
 export {ExtraOptions, InitialNavigation, InMemoryScrollingOptions, ROUTER_CONFIGURATION, RouterConfigOptions} from './router_config';
diff --git a/packages/router/src/navigation_transition.ts b/packages/router/src/navigation_transition.ts
@@ -11,6 +11,7 @@ import {BehaviorSubject, combineLatest, EMPTY, Observable, of, Subject} from 'rx
 import {catchError, defaultIfEmpty, filter, finalize, map, switchMap, take, tap} from 'rxjs/operators';
 
 import {createRouterState} from './create_router_state';
+import {INPUT_BINDER} from './directives/router_outlet';
 import {Event, GuardsCheckEnd, GuardsCheckStart, IMPERATIVE_NAVIGATION, NavigationCancel, NavigationCancellationCode, NavigationEnd, NavigationError, NavigationSkipped, NavigationSkippedCode, NavigationStart, NavigationTrigger, ResolveEnd, ResolveStart, RouteConfigLoadEnd, RouteConfigLoadStart, RoutesRecognized} from './events';
 import {NavigationBehaviorOptions, QueryParamsHandling, Route, Routes} from './models';
 import {isNavigationCancelingError, isRedirectingNavigationCancelingError, redirectingNavigationError} from './navigation_canceling_error';
@@ -292,6 +293,7 @@ export class NavigationTransitions {
   private readonly environmentInjector = inject(EnvironmentInjector);
   private readonly urlSerializer = inject(UrlSerializer);
   private readonly rootContexts = inject(ChildrenOutletContexts);
+  private readonly inputBindingEnabled = inject(INPUT_BINDER, {optional: true}) !== null;
   navigationId = 0;
   get hasRequestedNavigation() {
     return this.navigationId !== 0;
@@ -641,7 +643,7 @@ export class NavigationTransitions {
 
                          activateRoutes(
                              this.rootContexts, router.routeReuseStrategy,
-                             (evt: Event) => this.events.next(evt)),
+                             (evt: Event) => this.events.next(evt), this.inputBindingEnabled),
 
                          tap({
                            next: (t: NavigationTransition) => {
diff --git a/packages/router/src/operators/activate_routes.ts b/packages/router/src/operators/activate_routes.ts
@@ -17,20 +17,24 @@ import {ActivatedRoute, advanceActivatedRoute, RouterState} from '../router_stat
 import {getClosestRouteInjector} from '../utils/config';
 import {nodeChildrenAsMap, TreeNode} from '../utils/tree';
 
+let warnedAboutUnsupportedInputBinding = false;
+
 export const activateRoutes =
     (rootContexts: ChildrenOutletContexts, routeReuseStrategy: RouteReuseStrategy,
-     forwardEvent: (evt: Event) => void): MonoTypeOperatorFunction<NavigationTransition> =>
-        map(t => {
-          new ActivateRoutes(
-              routeReuseStrategy, t.targetRouterState!, t.currentRouterState, forwardEvent)
-              .activate(rootContexts);
-          return t;
-        });
+     forwardEvent: (evt: Event) => void,
+     inputBindingEnabled: boolean): MonoTypeOperatorFunction<NavigationTransition> => map(t => {
+      new ActivateRoutes(
+          routeReuseStrategy, t.targetRouterState!, t.currentRouterState, forwardEvent,
+          inputBindingEnabled)
+          .activate(rootContexts);
+      return t;
+    });
 
 export class ActivateRoutes {
   constructor(
       private routeReuseStrategy: RouteReuseStrategy, private futureState: RouterState,
-      private currState: RouterState, private forwardEvent: (evt: Event) => void) {}
+      private currState: RouterState, private forwardEvent: (evt: Event) => void,
+      private inputBindingEnabled: boolean) {}
 
   activate(parentContexts: ChildrenOutletContexts): void {
     const futureRoot = this.futureState._root;
@@ -210,5 +214,16 @@ export class ActivateRoutes {
         this.activateChildRoutes(futureNode, null, parentContexts);
       }
     }
+    if ((typeof ngDevMode === 'undefined' || ngDevMode)) {
+      const context = parentContexts.getOrCreateContext(future.outlet);
+      const outlet = context.outlet;
+      if (outlet && this.inputBindingEnabled && !outlet.supportsBindingToComponentInputs &&
+          !warnedAboutUnsupportedInputBinding) {
+        console.warn(
+            `'withComponentInputBinding' feature is enabled but ` +
+            `this application is using an outlet that may not support binding to component inputs.`);
+        warnedAboutUnsupportedInputBinding = true;
+      }
+    }
   }
 }
diff --git a/packages/router/src/provide_router.ts b/packages/router/src/provide_router.ts
@@ -7,11 +7,11 @@
  */
 
 import {HashLocationStrategy, LOCATION_INITIALIZED, LocationStrategy, ViewportScroller} from '@angular/common';
-import {APP_BOOTSTRAP_LISTENER, APP_INITIALIZER, ApplicationRef, ComponentRef, ENVIRONMENT_INITIALIZER, EnvironmentInjector, EnvironmentProviders, inject, InjectFlags, InjectionToken, Injector, makeEnvironmentProviders, NgZone, Provider, Type} from '@angular/core';
+import {APP_BOOTSTRAP_LISTENER, APP_INITIALIZER, ApplicationRef, Component, ComponentRef, ENVIRONMENT_INITIALIZER, EnvironmentInjector, EnvironmentProviders, inject, InjectFlags, InjectionToken, Injector, makeEnvironmentProviders, NgZone, Provider, Type} from '@angular/core';
 import {of, Subject} from 'rxjs';
-import {filter, map, take} from 'rxjs/operators';
 
-import {Event, NavigationCancel, NavigationCancellationCode, NavigationEnd, NavigationError, stringifyEvent} from './events';
+import {INPUT_BINDER, RoutedComponentInputBinder} from './directives/router_outlet';
+import {Event, NavigationError, stringifyEvent} from './events';
 import {Routes} from './models';
 import {NavigationTransitions} from './navigation_transition';
 import {Router} from './router';
@@ -648,6 +648,46 @@ export function withNavigationErrorHandler(fn: (error: NavigationError) => void)
   return routerFeature(RouterFeatureKind.NavigationErrorHandlerFeature, providers);
 }
 
+/**
+ * A type alias for providers returned by `withComponentInputBinding` for use with `provideRouter`.
+ *
+ * @see `withComponentInputBinding`
+ * @see `provideRouter`
+ *
+ * @publicApi
+ */
+export type ComponentInputBindingFeature =
+    RouterFeature<RouterFeatureKind.ComponentInputBindingFeature>;
+
+/**
+ * Enables binding information from the `Router` state directly to the inputs of the component in
+ * `Route` configurations.
+ *
+ * @usageNotes
+ *
+ * Basic example of how you can enable the feature:
+ * ```
+ * const appRoutes: Routes = [];
+ * bootstrapApplication(AppComponent,
+ *   {
+ *     providers: [
+ *       provideRouter(appRoutes, withComponentInputBinding())
+ *     ]
+ *   }
+ * );
+ * ```
+ *
+ * @returns A set of providers for use with `provideRouter`.
+ */
+export function withComponentInputBinding(): ComponentInputBindingFeature {
+  const providers = [
+    RoutedComponentInputBinder,
+    {provide: INPUT_BINDER, useExisting: RoutedComponentInputBinder},
+  ];
+
+  return routerFeature(RouterFeatureKind.ComponentInputBindingFeature, providers);
+}
+
 /**
  * A type alias that represents all Router features available for use with `provideRouter`.
  * Features can be enabled by adding special functions to the `provideRouter` call.
@@ -658,8 +698,9 @@ export function withNavigationErrorHandler(fn: (error: NavigationError) => void)
  *
  * @publicApi
  */
-export type RouterFeatures = PreloadingFeature|DebugTracingFeature|InitialNavigationFeature|
-    InMemoryScrollingFeature|RouterConfigurationFeature|NavigationErrorHandlerFeature;
+export type RouterFeatures =
+    PreloadingFeature|DebugTracingFeature|InitialNavigationFeature|InMemoryScrollingFeature|
+    RouterConfigurationFeature|NavigationErrorHandlerFeature|ComponentInputBindingFeature;
 
 /**
  * The list of features as an enum to uniquely type each feature.
@@ -673,4 +714,5 @@ export const enum RouterFeatureKind {
   RouterConfigurationFeature,
   RouterHashLocationFeature,
   NavigationErrorHandlerFeature,
+  ComponentInputBindingFeature,
 }
diff --git a/packages/router/src/router.ts b/packages/router/src/router.ts
@@ -11,6 +11,7 @@ import {inject, Injectable, NgZone, Type, ɵConsole as Console, ɵInitialRenderP
 import {Observable, of, SubscriptionLike} from 'rxjs';
 
 import {createSegmentGroupFromRoute, createUrlTreeFromSegmentGroup} from './create_url_tree';
+import {INPUT_BINDER} from './directives/router_outlet';
 import {RuntimeErrorCode} from './errors';
 import {Event, IMPERATIVE_NAVIGATION, NavigationTrigger} from './events';
 import {NavigationBehaviorOptions, OnSameUrlNavigation, Routes} from './models';
@@ -307,6 +308,14 @@ export class Router {
   private readonly urlSerializer = inject(UrlSerializer);
   private readonly location = inject(Location);
 
+  /**
+   * Indicates whether the the application has opted in to binding Router data to component inputs.
+   *
+   * This option is enabled by the `withComponentInputBinding` feature of `provideRouter` or
+   * `bindToComponentInputs` in the `ExtraOptions` of `RouterModule.forRoot`.
+   */
+  readonly componentInputBindingEnabled = !!inject(INPUT_BINDER, {optional: true});
+
   constructor() {
     this.isNgZoneEnabled = inject(NgZone) instanceof NgZone && NgZone.isInAngularZone();
 
diff --git a/packages/router/src/router_config.ts b/packages/router/src/router_config.ts
diff --git a/packages/router/src/router_module.ts b/packages/router/src/router_module.ts
diff --git a/packages/router/test/directives/router_outlet.spec.ts b/packages/router/test/directives/router_outlet.spec.ts

Original file line number	Diff line number	Diff line change
`@@ -275,6 +275,9 @@`
`275`	`275`	`{`
`276`	`276`	`"name": "INJECTOR_SCOPE"`
`277`	`277`	`},`
	`278`	`+ {`
	`279`	`+ "name": "INPUT_BINDER"`
	`280`	`+ },`
`278`	`281`	`{`
`279`	`282`	`"name": "INTERNAL_APPLICATION_ERROR_HANDLER"`
`280`	`283`	`},`