@mmstack/router-core 21.0.4 → 21.0.6

package/types/mmstack-router-core.d.ts

@@ -5,7 +5,19 @@ import { Signal, InjectionToken, Provider, WritableSignal } from '@angular/core'
 import { Observable } from 'rxjs';
 
 /**
- * @internal
+ * A flattened view of one route in the active router chain, used by the
+ * breadcrumb and title subsystems. Each `ResolvedLeafRoute` describes one
+ * "step" in the chain from root to current leaf.
+ *
+ * Exposed publicly because custom breadcrumb generators (see
+ * {@link BreadcrumbConfig}'s `generation` callback) receive instances of
+ * this type and need to read its fields.
+ *
+ * - `route` — the underlying `ActivatedRouteSnapshot`.
+ * - `segment.path` — the route config segment (e.g. `:userId`).
+ * - `segment.resolved` — the resolved value of that segment (e.g. `'42'`).
+ * - `path` — the full route-config path from root (with raw segments like `:userId`).
+ * - `link` — the full resolved URL from root (with substituted values).
  */
 type ResolvedLeafRoute = {
     route: ActivatedRouteSnapshot;
@@ -78,31 +90,33 @@ type BreadcrumbConfig = {
 };
 /**
  * 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
- *
- * // 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';
- * //   };
- * // };
- *
- * export const appConfig = [
- *  // ...rest
- *  provideBreadcrumbConfig({
- *   generation: customLabelStrategy, // or 'manual' to disable auto-generation
- *  }),
- * ]
+ * ```ts
+ * // Disable automatic generation — breadcrumbs only appear when createBreadcrumb is used
+ * bootstrapApplication(AppComponent, {
+ *   providers: [
+ *     provideRouter(routes),
+ *     provideBreadcrumbConfig({ generation: 'manual' }),
+ *   ],
+ * });
+ * ```
+ *
+ * @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';
+ *
+ * provideBreadcrumbConfig({ generation: customLabelStrategy });
  * ```
  */
 declare function provideBreadcrumbConfig(config: Partial<BreadcrumbConfig>): {
@@ -134,17 +148,24 @@ type CreateBreadcrumbOptions = {
     awaitValue?: boolean;
 };
 /**
- * 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 (`string`), a static options object, or a factory returning either —
- * use a factory when you need `inject()` for dynamic data.
+ * Accepts a static label, a static options object, or a factory returning
+ * either — use a factory when you need `inject()` to read 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',
@@ -161,7 +182,7 @@ type CreateBreadcrumbOptions = {
  *       breadcrumb: createBreadcrumb(() => {
  *         const userStore = inject(UserStore);
  *         return {
- *           label: () => userStore.user().name ?? 'Loading...',
+ *           label: () => userStore.user().name ?? 'Loading…',
  *         };
  *       }),
  *     },
@@ -250,7 +271,56 @@ type MMLinkConfig = {
      */
     useMouseDown: boolean;
 };
+/**
+ * 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 }),
+ *   ],
+ * });
+ * ```
+ */
 declare function provideMMLinkDefaultConfig(config: Partial<MMLinkConfig>): Provider;
+/**
+ * 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>
+ * ```
+ */
 declare class Link {
     private readonly routerLink;
     private readonly req;
@@ -355,47 +425,126 @@ type NavItem<TMeta = Record<string, unknown>> = {
     children: Signal<NavItem<TMeta>[]>;
 };
 
+/**
+ * Per-scope fallback descriptor: a static array or a factory returning one.
+ */
+type NavDefaultsForScope<TMeta = Record<string, unknown>> = CreateNavItem<TMeta>[] | (() => CreateNavItem<TMeta>[]);
 /**
  * Global configuration for the nav system.
  * @see provideNavConfig
  */
-type NavConfig = {
+type NavConfig<TMeta = Record<string, unknown>> = {
     /**
      * Default match options used when computing `NavItem.active`. Per-item `activeMatch`
      * (and the router's built-in `subsetMatchOptions`) are still merged on top.
      */
     activeMatch?: Partial<IsActiveMatchOptions>;
+    /**
+     * Fallback nav items rendered when no route in the active chain has registered items
+     * for the requested scope. Relative `link`s resolve from `/`.
+     *
+     * Forms:
+     * - Array (or factory): fallback for the default (unnamed) scope.
+     * - Record: keys match the `name` passed to `createNavItems`. The unnamed scope can
+     *   also be provided via this record using the empty-string key `''`.
+     *
+     * A route that wants to render an *empty* nav explicitly should register
+     * `createNavItems([])`, which shadows these defaults via the normal deepest-wins rule.
+     */
+    defaults?: NavDefaultsForScope<TMeta> | Record<string, NavDefaultsForScope<TMeta>>;
 };
 /**
- * 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' },
- * }),
+ * ```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,
+ *     },
+ *   };
+ * });
  * ```
  */
-declare function provideNavConfig(config?: NavConfig): Provider;
+declare function provideNavConfig(config?: NavConfig | (() => NavConfig)): Provider;
 
 /**
  * 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.
+ *
+ * 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 `[]`.
+ *
+ * @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.
  *
- * Multiple scopes can be registered on a single route by giving each its own `name`
- * (and a unique key in the `resolve` map):
+ * @example
+ * ```ts
+ * // Single default-scope nav
+ * {
+ *   path: 'app',
+ *   resolve: {
+ *     _nav: createNavItems([
+ *       { label: 'Dashboard', link: 'dashboard' },
+ *       { label: 'Reports', link: 'reports' },
+ *     ]),
+ *   },
+ * }
  *
- * ```typescript
- * resolve: {
- *   mainNav: createNavItems([...], { name: 'main' }),
- *   sideNav: createNavItems([...], { name: 'side' }),
+ * // 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;
+ * });
+ * ```
  */
 declare function createNavItems<TMeta = Record<string, unknown>>(itemsOrFactory: CreateNavItem<TMeta>[] | (() => CreateNavItem<TMeta>[]), options?: {
     name?: string;
@@ -405,7 +554,9 @@ declare function createNavItems<TMeta = Record<string, unknown>>(itemsOrFactory:
  * Returns a reactive list of nav items for the requested scope.
  *
  * The returned signal reflects the nearest active ancestor route that registered items
- * for `name` via `createNavItems`. Hidden items are filtered out.
+ * for `name` via `createNavItems`. If no active route has registered items for the
+ * scope, falls back to `NavConfig.defaults` (when provided via `provideNavConfig`).
+ * Hidden items are filtered out.
  *
  * @typeParam TMeta The shape of `NavItem.meta` for the consuming code. Untyped at the
  * registration site — this is a consumer-side assertion.
@@ -426,6 +577,44 @@ declare function createNavItems<TMeta = Record<string, unknown>>(itemsOrFactory:
  */
 declare function injectNavItems<TMeta = Record<string, unknown>>(name?: string): Signal<NavItem<TMeta>[]>;
 
+/**
+ * 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 } },
+ * ];
+ * ```
+ */
 declare class PreloadStrategy implements PreloadingStrategy {
     private readonly loading;
     private readonly router;
@@ -537,19 +726,75 @@ type TitleConfig = {
     keepLastKnownTitle?: boolean;
 };
 /**
- * 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,
+ *     }),
+ *   ],
+ * });
+ * ```
  */
 declare function provideTitleConfig(config?: TitleConfig): Provider;
 
 /**
+ * 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).
  *
- * Creates a title resolver function that can be used in Angular's router.
+ * @example
+ * ```ts
+ * // Static title
+ * { path: 'about', component: AboutComponent, title: createTitle('About us') }
+ *
+ * // 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'}`);
+ *   }),
+ * }
+ * ```
  */
 declare function createTitle(factoryOrValue: (() => string | (() => string)) | string, awaitValue?: boolean): ResolveFn<string>;