fix(router): export DefaultRouteReuseStrategy to Router public_api (angular#31575)

export DefaultRouteStrategy class that was used internally and exposed, and add documentation for each one of methods

PR Close angular#31575

Author: abarghoud

goldens/public-api/router/router.d.ts

@@ -51,6 +51,14 @@ export declare class ActivationStart {
     toString(): string;
 }
 
+export declare abstract class BaseRouteReuseStrategy implements RouteReuseStrategy {
+    retrieve(route: ActivatedRouteSnapshot): DetachedRouteHandle | null;
+    shouldAttach(route: ActivatedRouteSnapshot): boolean;
+    shouldDetach(route: ActivatedRouteSnapshot): boolean;
+    shouldReuseRoute(future: ActivatedRouteSnapshot, curr: ActivatedRouteSnapshot): boolean;
+    store(route: ActivatedRouteSnapshot, detachedTree: DetachedRouteHandle): void;
+}
+
 export declare interface CanActivate {
     canActivate(route: ActivatedRouteSnapshot, state: RouterStateSnapshot): Observable<boolean | UrlTree> | Promise<boolean | UrlTree> | boolean | UrlTree;
 }

packages/router/src/index.ts

@@ -13,7 +13,7 @@ export {RouterLinkActive} from './directives/router_link_active';
 export {RouterOutlet} from './directives/router_outlet';
 export {ActivationEnd, ActivationStart, ChildActivationEnd, ChildActivationStart, Event, GuardsCheckEnd, GuardsCheckStart, NavigationCancel, NavigationEnd, NavigationError, NavigationStart, ResolveEnd, ResolveStart, RouteConfigLoadEnd, RouteConfigLoadStart, RouterEvent, RoutesRecognized, Scroll} from './events';
 export {CanActivate, CanActivateChild, CanDeactivate, CanLoad, Resolve} from './interfaces';
-export {DetachedRouteHandle, RouteReuseStrategy} from './route_reuse_strategy';
+export {BaseRouteReuseStrategy, DetachedRouteHandle, RouteReuseStrategy} from './route_reuse_strategy';
 export {Navigation, NavigationExtras, Router} from './router';
 export {ROUTES} from './router_config_loader';
 export {ExtraOptions, InitialNavigation, provideRoutes, ROUTER_CONFIGURATION, ROUTER_INITIALIZER, RouterModule} from './router_module';

packages/router/src/route_reuse_strategy.ts

@@ -60,20 +60,54 @@ export abstract class RouteReuseStrategy {
 }
 
 /**
- * Does not detach any subtrees. Reuses routes as long as their route config is the same.
+ * @description
+ *
+ * This base route reuse strategy only reuses routes when the matched router configs are
+ * identical. This prevents components from being destroyed and recreated
+ * when just the fragment or query parameters change
+ * (that is, the existing component is _reused_).
+ *
+ * This strategy does not store any routes for later reuse.
+ *
+ * Angular uses this strategy by default.
+ *
+ *
+ * It can be used as a base class for custom route reuse strategies, i.e. you can create your own
+ * class that extends the `BaseRouteReuseStrategy` one.
+ * @publicApi
  */
-export class DefaultRouteReuseStrategy implements RouteReuseStrategy {
+export abstract class BaseRouteReuseStrategy implements RouteReuseStrategy {
+  /**
+   * Whether the given route should detach for later reuse.
+   * Always returns false for `BaseRouteReuseStrategy`.
+   * */
   shouldDetach(route: ActivatedRouteSnapshot): boolean {
     return false;
   }
+
+  /**
+   * A no-op; the route is never stored since this strategy never detaches routes for later re-use.
+   */
   store(route: ActivatedRouteSnapshot, detachedTree: DetachedRouteHandle): void {}
+
+  /** Returns `false`, meaning the route (and its subtree) is never reattached */
   shouldAttach(route: ActivatedRouteSnapshot): boolean {
     return false;
   }
+
+  /** Returns `null` because this strategy does not store routes for later re-use. */
   retrieve(route: ActivatedRouteSnapshot): DetachedRouteHandle|null {
     return null;
   }
+
+  /**
+   * Determines if a route should be reused.
+   * This strategy returns `true` when the future route config and current route config are
+   * identical.
+   */
   shouldReuseRoute(future: ActivatedRouteSnapshot, curr: ActivatedRouteSnapshot): boolean {
     return future.routeConfig === curr.routeConfig;
   }
 }
+
+export class DefaultRouteReuseStrategy extends BaseRouteReuseStrategy {}