@mmstack/router-core 21.0.5 → 21.0.7

package/fesm2022/mmstack-router-core.mjs

@@ -331,31 +331,33 @@ function isInternalBreadcrumb(breadcrumb) {
 const token$2 = new InjectionToken('@mmstack/router-core:breadcrumb-config');
 /**
  * Provides configuration for the breadcrumb system.
- * @param config - A partial `BreadcrumbConfig` object with the desired settings. *
+ *
+ * @param config A partial {@link BreadcrumbConfig}. The `generation` field controls
+ *   automatic label generation: `'manual'` disables it (breadcrumbs only show when
+ *   {@link createBreadcrumb} explicitly registers them); a function provides a
+ *   custom label generator instead of the default route-title-based one.
+ * @returns A `Provider` to add to your app's providers array.
+ *
  * @see BreadcrumbConfig
+ *
  * @example
- * ```typescript
- * // In your app.module.ts or a standalone component's providers:
- * // import { provideBreadcrumbConfig } from './breadcrumb.config'; // Adjust path
- * // import { ResolvedLeafRoute } from './breadcrumb.type'; // Adjust path
+ * ```ts
+ * // Disable automatic generation — breadcrumbs only appear when createBreadcrumb is used
+ * bootstrapApplication(AppComponent, {
+ *   providers: [
+ *     provideRouter(routes),
+ *     provideBreadcrumbConfig({ generation: 'manual' }),
+ *   ],
+ * });
+ * ```
  *
- * // const customLabelStrategy: GenerateBreadcrumbFn = () => {
- * //   return (leaf: ResolvedLeafRoute): string => {
- * //     // Example: Prioritize a 'navTitle' data property
- * //     if (leaf.route.data?.['navTitle']) {
- * //       return leaf.route.data['navTitle'];
- * //     }
- * //     // Fallback to a default mechanism
- * //     return leaf.route.title || leaf.segment.resolved || 'Unnamed';
- * //   };
- * // };
+ * @example
+ * ```ts
+ * // Custom label strategy — outer fn runs in injection context, inner is reactive
+ * const customLabelStrategy = () => (leaf: ResolvedLeafRoute) =>
+ *   leaf.route.data?.['navTitle'] ?? leaf.route.title ?? 'Unnamed';
  *
- * export const appConfig = [
- *  // ...rest
- *  provideBreadcrumbConfig({
- *   generation: customLabelStrategy, // or 'manual' to disable auto-generation
- *  }),
- * ]
+ * provideBreadcrumbConfig({ generation: customLabelStrategy });
  * ```
  */
 function provideBreadcrumbConfig(config) {
@@ -514,17 +516,24 @@ function injectBreadcrumbs() {
 }
 
 /**
- * Creates and registers a breadcrumb for a specific route.
- * This function is designed to be used as an Angular Route `ResolveFn`.
+ * Creates and registers a breadcrumb for a specific route. Designed to be used
+ * as an Angular Route `ResolveFn` in the route's `resolve` map.
+ *
+ * Accepts a static label, a static options object, or a factory returning
+ * either — use a factory when you need `inject()` to read dynamic data.
  *
- * Accepts a static label (`string`), a static options object, or a factory returning either —
- * use a factory when you need `inject()` for dynamic data.
+ * @param factoryOrValue One of: a literal label string (shorthand for
+ *   `{ label: <string> }`), a static {@link CreateBreadcrumbOptions} object,
+ *   or a factory `() => string | CreateBreadcrumbOptions` invoked inside an
+ *   injection context (so it can use `inject()`).
+ * @returns An Angular `ResolveFn<void>` to wire into a route's `resolve` map.
+ *   The resolver registers the breadcrumb as a side effect; the resolved value
+ *   itself is unused.
  *
- * @param factoryOrValue A static label, a static `CreateBreadcrumbOptions`, or a factory returning either.
  * @see CreateBreadcrumbOptions
  *
  * @example
- * ```typescript
+ * ```ts
  * export const appRoutes: Routes = [
  *   {
  *     path: 'home',
@@ -541,7 +550,7 @@ function injectBreadcrumbs() {
  *       breadcrumb: createBreadcrumb(() => {
  *         const userStore = inject(UserStore);
  *         return {
- *           label: () => userStore.user().name ?? 'Loading...',
+ *           label: () => userStore.user().name ?? 'Loading…',
  *         };
  *       }),
  *     },
@@ -618,6 +627,44 @@ function hasSlowConnection() {
 function noPreload(route) {
     return route.data && route.data['preload'] === false;
 }
+/**
+ * Demand-driven preloading strategy for Angular's router. Unlike Angular's
+ * built-in `PreloadAllModules`, this strategy preloads a lazy route only
+ * when something explicitly requests it via {@link PreloadRequester} (e.g.
+ * the `mmLink` directive on hover or visibility, or {@link injectTriggerPreload}
+ * called imperatively).
+ *
+ * Skips preloading when:
+ * - the route has `data.preload === false`
+ * - the network is on `2g` or in `saveData` mode (cheap-data-mode users)
+ * - a load for the same path is already in flight
+ *
+ * Wire this into `provideRouter` to enable the `mmLink` preload pipeline:
+ *
+ * @example
+ * ```ts
+ * import { PreloadStrategy } from '@mmstack/router-core';
+ * import { provideRouter, withPreloading } from '@angular/router';
+ *
+ * bootstrapApplication(AppComponent, {
+ *   providers: [
+ *     provideRouter(routes, withPreloading(PreloadStrategy)),
+ *   ],
+ * });
+ *
+ * // Then in templates, `mmLink` (or `injectTriggerPreload`) requests
+ * // preloads that this strategy executes:
+ * // <a [mmLink]="'/users'">Users</a>
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Opt a route out of preloading:
+ * export const routes: Routes = [
+ *   { path: 'admin', loadChildren: () => import('./admin'), data: { preload: false } },
+ * ];
+ * ```
+ */
 class PreloadStrategy {
     loading = new Set();
     router = inject(Router);
@@ -705,6 +752,25 @@ function injectTriggerPreload() {
     };
 }
 const configToken = new InjectionToken('MMSTACK_LINK_CONFIG');
+/**
+ * Provide application-wide defaults for the `mmLink` directive. Each `[mmLink]`
+ * instance can still override per-link via its own `preloadOn` / `useMouseDown`
+ * inputs; this just shifts the default.
+ *
+ * @param config Partial override of `MMLinkConfig`. Unset keys fall back to:
+ *   - `preloadOn: 'hover'` — preload triggered when the user hovers a link
+ *   - `useMouseDown: false` — navigation triggered on click (not mousedown)
+ * @returns A `Provider` to add to your app's providers array.
+ *
+ * @example
+ * ```ts
+ * bootstrapApplication(AppComponent, {
+ *   providers: [
+ *     provideMMLinkDefaultConfig({ preloadOn: 'visible', useMouseDown: true }),
+ *   ],
+ * });
+ * ```
+ */
 function provideMMLinkDefaultConfig(config) {
     const cfg = {
         preloadOn: 'hover',
@@ -724,6 +790,36 @@ function injectConfig() {
         ...cfg,
     };
 }
+/**
+ * Drop-in replacement for `[routerLink]` that adds preloading on hover or
+ * visibility, optional mousedown-triggered navigation, and a `beforeNavigate`
+ * hook. Composes with Angular's `RouterLink` via `hostDirectives`, so every
+ * `RouterLink` input (`target`, `queryParams`, `fragment`, etc.) is forwarded.
+ *
+ * Preload behavior:
+ * - `preloadOn: 'hover'` (default) — preload when the user hovers the link
+ * - `preloadOn: 'visible'` — preload when the link scrolls into view
+ * - `preloadOn: null` — disable preloading on this link
+ *
+ * Navigation timing:
+ * - `useMouseDown: false` (default) — navigate on click
+ * - `useMouseDown: true` — navigate on mousedown (shaves ~50ms but breaks if the user
+ *   moves off the link before mouseup)
+ *
+ * Requires {@link PreloadStrategy} to be wired via `provideRouter(routes, withComponentInputBinding(), withPreloading(PreloadStrategy))`.
+ * Set app-wide defaults with {@link provideMMLinkDefaultConfig}.
+ *
+ * @example
+ * ```html
+ * <a [mmLink]="['/users', userId()]">View profile</a>
+ *
+ * <!-- Override per-link -->
+ * <a [mmLink]="'/heavy-page'" preloadOn="visible" useMouseDown>Heavy page</a>
+ *
+ * <!-- React to the preload starting -->
+ * <a [mmLink]="'/checkout'" (preloading)="onPreload()">Checkout</a>
+ * ```
+ */
 class Link {
     routerLink = inject(RouterLink, {
         self: true,
@@ -934,17 +1030,43 @@ function createInternalNavItem(input, router, relativeTo, configActiveMatch, par
 /** @internal */
 const token$1 = new InjectionToken('@mmstack/router-core:nav-config');
 /**
- * Provides global configuration for the nav system.
+ * Provides global configuration for the nav system. The factory form runs in
+ * an injection context, so it can use `inject()` to build defaults from app
+ * state.
+ *
+ * @param config Either a literal {@link NavConfig} object or a factory
+ *   `() => NavConfig`. Optional — without it, the nav system uses Angular's
+ *   default `activeMatch` options and renders nothing in scopes that have no
+ *   registered items.
+ * @returns A `Provider` to add to your app's providers array.
  *
  * @example
- * ```typescript
- * provideNavConfig({
- *   activeMatch: { queryParams: 'ignored' },
- *   defaults: [
- *     { label: 'Home', link: '/' },
- *     { label: 'Docs', link: '/docs' },
+ * ```ts
+ * bootstrapApplication(AppComponent, {
+ *   providers: [
+ *     provideRouter(routes),
+ *     provideNavConfig({
+ *       activeMatch: { queryParams: 'ignored' },
+ *       defaults: [
+ *         { label: 'Home', link: '/' },
+ *         { label: 'Docs', link: '/docs' },
+ *       ],
+ *     }),
  *   ],
- * }),
+ * });
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Factory form — read defaults from a service
+ * provideNavConfig(() => {
+ *   const role = inject(AuthStore).role();
+ *   return {
+ *     defaults: {
+ *       main: role === 'admin' ? adminNav : guestNav,
+ *     },
+ *   };
+ * });
  * ```
  */
 function provideNavConfig(config) {
@@ -1071,22 +1193,54 @@ function injectNavItems(name) {
 
 /**
  * Registers a set of nav items for the activating route under the given scope.
- * Mirrors `createBreadcrumb` / `createTitle` — designed to be used in a route's
- * `resolve` map.
+ * Mirrors {@link createBreadcrumb} / {@link createTitle} — designed to be used
+ * in a route's `resolve` map.
  *
- * Multiple scopes can be registered on a single route by giving each its own `name`
- * (and a unique key in the `resolve` map):
+ * Scope override semantics: when multiple routes in the active chain register
+ * items under the same scope, the deepest active registration wins. Navigating
+ * away restores the shallower registration. To explicitly render an empty nav
+ * (shadowing a default), pass `[]`.
  *
- * ```typescript
- * resolve: {
- *   mainNav: createNavItems([...], { name: 'main' }),
- *   sideNav: createNavItems([...], { name: 'side' }),
+ * @typeParam TMeta Optional per-item metadata type — flows through the
+ *   registered items so consumers reading via {@link injectNavItems} get
+ *   typed access to `item.meta`.
+ * @param itemsOrFactory Either a static array of {@link CreateNavItem} or a
+ *   factory `() => CreateNavItem<TMeta>[]` invoked inside an injection
+ *   context (so it can use `inject()` for dynamic items).
+ * @param options Optional `{ name }` for registering multiple scopes on a
+ *   single route. Omit to target the default (unnamed) scope.
+ * @returns An Angular `ResolveFn<void>` to wire into a route's `resolve` map.
+ *   The resolver registers items as a side effect; the resolved value itself
+ *   is unused.
+ *
+ * @example
+ * ```ts
+ * // Single default-scope nav
+ * {
+ *   path: 'app',
+ *   resolve: {
+ *     _nav: createNavItems([
+ *       { label: 'Dashboard', link: 'dashboard' },
+ *       { label: 'Reports', link: 'reports' },
+ *     ]),
+ *   },
+ * }
+ *
+ * // Multiple scopes
+ * {
+ *   path: 'app',
+ *   resolve: {
+ *     mainNav: createNavItems([...], { name: 'main' }),
+ *     sideNav: createNavItems([...], { name: 'side' }),
+ *   },
  * }
- * ```
  *
- * Scope override semantics: when multiple routes in the active chain register items
- * under the same scope, the deepest active registration wins. Navigating away restores
- * the shallower registration.
+ * // Factory using inject()
+ * createNavItems(() => {
+ *   const auth = inject(AuthStore);
+ *   return auth.canAdmin() ? adminItems : userItems;
+ * });
+ * ```
  */
 function createNavItems(itemsOrFactory, options) {
     const factory = typeof itemsOrFactory === 'function'
@@ -1216,7 +1370,29 @@ function queryParam(key, route = inject(ActivatedRoute)) {
 
 const token = new InjectionToken('@mmstack/router-core:title-config');
 /**
- * used to provide the title configuration, will not be applied unless a `createTitle` resolver is used
+ * Provide application-wide configuration for the title subsystem. The config
+ * is only consumed when at least one route uses a {@link createTitle} resolver;
+ * routes without `createTitle` are unaffected.
+ *
+ * @param config Optional {@link TitleConfig}. All fields are optional — pass
+ *   `prefix` to namespace titles (e.g. `"My App – "`), `initialTitle` to
+ *   override the fallback (defaults to the `<title>` from `index.html`), and
+ *   `keepLastKnownTitle: false` to clear the title on navigations to routes
+ *   without a title (the default keeps the previous one).
+ * @returns A `Provider` to add to your app's providers array.
+ *
+ * @example
+ * ```ts
+ * bootstrapApplication(AppComponent, {
+ *   providers: [
+ *     provideRouter(routes),
+ *     provideTitleConfig({
+ *       prefix: (title) => `${title} • My App`,
+ *       keepLastKnownTitle: true,
+ *     }),
+ *   ],
+ * });
+ * ```
  */
 function provideTitleConfig(config) {
     const prefix = config?.prefix ?? '';
@@ -1287,14 +1463,48 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.12", ngImpo
                 }]
         }], ctorParameters: () => [] });
 /**
+ * Creates an Angular router `ResolveFn<string>` that registers a title for the
+ * route it's attached to. Titles can be static strings, factory functions
+ * (called in an injection context, so they can use `inject()`), or signal
+ * factories (for reactive titles that change when underlying data does).
+ *
+ * The resolved title flows through any `prefix` configured via
+ * {@link provideTitleConfig}, and is wired into Angular's `Title` service
+ * via an effect. Nested routes pick the most-specific leaf's title; if a
+ * deeper route has no title and `keepLastKnownTitle` is `true` (default),
+ * the previous title is preserved.
+ *
+ * @param factoryOrValue Either a literal string title, a `() => string`
+ *   factory, or a `() => Signal<string>` factory for reactive titles. Factory
+ *   callbacks run inside an injection context, so they can use `inject()`.
+ * @param awaitValue When `true`, the resolver waits until the title signal
+ *   emits a truthy value before resolving — useful for SSR/SEO where the
+ *   resolved title should not be empty. Defaults to `false`.
+ * @returns An Angular `ResolveFn<string>` to wire into a route's `title` field
+ *   (or any other `resolve` slot — the return value isn't usually consumed).
+ *
+ * @example
+ * ```ts
+ * // Static title
+ * { path: 'about', component: AboutComponent, title: createTitle('About us') }
  *
- * Creates a title resolver function that can be used in Angular's router.
+ * // Factory using inject()
+ * {
+ *   path: 'users/:id',
+ *   component: UserComponent,
+ *   title: createTitle(() => inject(ActivatedRoute).snapshot.params['id']),
+ * }
  *
- * @param factoryOrValue
- * A function that returns a string or a Signal<string> representing the title or just the string directly.
- * @param awaitValue
- * If `true`, the resolver will wait until the title signal has a value before resolving.
- * Defaults to `false`.
+ * // Reactive title from a signal store
+ * {
+ *   path: 'dashboard',
+ *   component: DashboardComponent,
+ *   title: createTitle(() => {
+ *     const user = inject(UserStore).current;
+ *     return computed(() => `Dashboard – ${user()?.name ?? 'Guest'}`);
+ *   }),
+ * }
+ * ```
  */
 function createTitle(factoryOrValue, awaitValue = false) {
     const factory = typeof factoryOrValue === 'string' ? () => factoryOrValue : factoryOrValue;