feat(router): Expose the default matcher for Routes used by the `Ro…

…uter` (#46913)

This commit adds the `defaultUrlMatcher` from the Router to the public
API. `UrlMatcher` and `UrlMatchResult` are already in the public api so
the signature of the function as well as the return value are already
exposed. Any change to those or the implementation of `defaultUrlMatcher`
would already be breaking so there's no additional risk in exposing the
default matcher.

This function can be useful for developers who want to create a custom
matcher which builds on the default matcher of the Router. Currently,
the only way to do this would be to copy-paste the implementation.

fixes #35928

PR Close #46913

goldens/public-api/router/index.md

@@ -210,6 +210,9 @@ export class DefaultTitleStrategy extends TitleStrategy {
     static ɵprov: i0.ɵɵInjectableDeclaration<DefaultTitleStrategy>;
 }
 
+// @public
+export function defaultUrlMatcher(segments: UrlSegment[], segmentGroup: UrlSegmentGroup, route: Route): UrlMatchResult | null;
+
 // @public
 export class DefaultUrlSerializer implements UrlSerializer {
     parse(url: string): UrlTree;

packages/router/src/index.ts

@@ -22,7 +22,7 @@ export {provideRoutes, ROUTER_INITIALIZER, RouterModule} from './router_module';
 export {ChildrenOutletContexts, OutletContext} from './router_outlet_context';
 export {NoPreloading, PreloadAllModules, PreloadingStrategy, RouterPreloader} from './router_preloader';
 export {ActivatedRoute, ActivatedRouteSnapshot, RouterState, RouterStateSnapshot} from './router_state';
-export {convertToParamMap, ParamMap, Params, PRIMARY_OUTLET} from './shared';
+export {convertToParamMap, defaultUrlMatcher, ParamMap, Params, PRIMARY_OUTLET} from './shared';
 export {UrlHandlingStrategy} from './url_handling_strategy';
 export {DefaultUrlSerializer, IsActiveMatchOptions, UrlSegment, UrlSegmentGroup, UrlSerializer, UrlTree} from './url_tree';
 export {VERSION} from './version';

packages/router/src/shared.ts

@@ -118,7 +118,21 @@ export function convertToParamMap(params: Params): ParamMap {
   return new ParamsAsMap(params);
 }
 
-// Matches the route configuration (`route`) against the actual URL (`segments`).
+/**
+ * Matches the route configuration (`route`) against the actual URL (`segments`).
+ *
+ * When no matcher is defined on a `Route`, this is the matcher used by the Router by default.
+ *
+ * @param segments The remaining unmatched segments in the current navigation
+ * @param segmentGroup The current segment group being matched
+ * @param route The `Route` to match against.
+ *
+ * @see UrlMatchResult
+ * @see Route
+ *
+ * @returns The resulting match information or `null` if the `route` should not match.
+ * @publicApi
+ */
 export function defaultUrlMatcher(
     segments: UrlSegment[], segmentGroup: UrlSegmentGroup, route: Route): UrlMatchResult|null {
   const parts = route.path!.split('/');