@mmstack/router-core 19.3.15 → 19.3.17

package/lib/link.d.ts

@@ -51,7 +51,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 }),
+ *   ],
+ * });
+ * ```
+ */
 export 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>
+ * ```
+ */
 export declare class Link {
     private readonly routerLink;
     private readonly req;

package/lib/nav/nav-config.d.ts

@@ -1,26 +1,74 @@
 import { type Provider } from '@angular/core';
 import { type IsActiveMatchOptions } from '@angular/router';
+import { type CreateNavItem } from './nav';
+/**
+ * Per-scope fallback descriptor: a static array or a factory returning one.
+ */
+export type NavDefaultsForScope<TMeta = Record<string, unknown>> = CreateNavItem<TMeta>[] | (() => CreateNavItem<TMeta>[]);
 /**
  * Global configuration for the nav system.
  * @see provideNavConfig
  */
-export type NavConfig = {
+export 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
+ * ```ts
+ * bootstrapApplication(AppComponent, {
+ *   providers: [
+ *     provideRouter(routes),
+ *     provideNavConfig({
+ *       activeMatch: { queryParams: 'ignored' },
+ *       defaults: [
+ *         { label: 'Home', link: '/' },
+ *         { label: 'Docs', link: '/docs' },
+ *       ],
+ *     }),
+ *   ],
+ * });
+ * ```
  *
  * @example
- * ```typescript
- * provideNavConfig({
- *   activeMatch: { queryParams: 'ignored' },
- * }),
+ * ```ts
+ * // Factory form — read defaults from a service
+ * provideNavConfig(() => {
+ *   const role = inject(AuthStore).role();
+ *   return {
+ *     defaults: {
+ *       main: role === 'admin' ? adminNav : guestNav,
+ *     },
+ *   };
+ * });
  * ```
  */
-export declare function provideNavConfig(config?: NavConfig): Provider;
+export declare function provideNavConfig(config?: NavConfig | (() => NavConfig)): Provider;
 /** @internal */
 export declare function injectNavConfig(): NavConfig;

package/lib/nav/nav-resolver.d.ts

@@ -2,22 +2,54 @@ import { type ResolveFn } from '@angular/router';
 import { type CreateNavItem } from './nav';
 /**
  * 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' },
+ *     ]),
+ *   },
  * }
- * ```
  *
- * 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.
+ * // Multiple scopes
+ * {
+ *   path: 'app',
+ *   resolve: {
+ *     mainNav: createNavItems([...], { name: 'main' }),
+ *     sideNav: createNavItems([...], { name: 'side' }),
+ *   },
+ * }
+ *
+ * // Factory using inject()
+ * createNavItems(() => {
+ *   const auth = inject(AuthStore);
+ *   return auth.canAdmin() ? adminItems : userItems;
+ * });
+ * ```
  */
 export declare function createNavItems<TMeta = Record<string, unknown>>(itemsOrFactory: CreateNavItem<TMeta>[] | (() => CreateNavItem<TMeta>[]), options?: {
     name?: string;

package/lib/nav/nav-store.d.ts

@@ -8,10 +8,16 @@ type AnyInternalNavItem = InternalNavItem<unknown>;
 export declare class NavStore {
     private readonly map;
     private readonly leafRoutes;
+    private readonly router;
+    private readonly config;
+    private readonly injector;
+    private readonly defaultsCache;
     /** @internal */
     register(scope: ScopeName, routePath: string, items: AnyInternalNavItem[]): void;
     /** @internal */
     scope<TMeta = Record<string, unknown>>(name: ScopeName): Signal<NavItem<TMeta>[]>;
+    private getDefaultItems;
+    private buildDefaultItems;
     static ɵfac: i0.ɵɵFactoryDeclaration<NavStore, never>;
     static ɵprov: i0.ɵɵInjectableDeclaration<NavStore>;
 }
@@ -19,7 +25,9 @@ export declare class NavStore {
  * 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.

package/lib/preloading/preload-strategy.d.ts

@@ -1,6 +1,44 @@
 import { PreloadingStrategy, type Route } from '@angular/router';
 import { Observable } from 'rxjs';
 import * as i0 from "@angular/core";
+/**
+ * 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 } },
+ * ];
+ * ```
+ */
 export declare class PreloadStrategy implements PreloadingStrategy {
     private readonly loading;
     private readonly router;

package/lib/title/title-config.d.ts

@@ -32,7 +32,29 @@ export type InternalTitleConfig = {
     keepLastKnown: 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,
+ *     }),
+ *   ],
+ * });
+ * ```
  */
 export declare function provideTitleConfig(config?: TitleConfig): Provider;
 export declare function injectTitleConfig(): InternalTitleConfig;

package/lib/title/title-store.d.ts

@@ -9,13 +9,47 @@ export declare class TitleStore {
     static ɵprov: i0.ɵɵInjectableDeclaration<TitleStore>;
 }
 /**
+ * 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).
  *
- * Creates a title resolver function that can be used in Angular's router.
+ * 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
- * 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`.
+ * @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') }
+ *
+ * // Factory using inject()
+ * {
+ *   path: 'users/:id',
+ *   component: UserComponent,
+ *   title: createTitle(() => inject(ActivatedRoute).snapshot.params['id']),
+ * }
+ *
+ * // Reactive title from a signal store
+ * {
+ *   path: 'dashboard',
+ *   component: DashboardComponent,
+ *   title: createTitle(() => {
+ *     const user = inject(UserStore).current;
+ *     return computed(() => `Dashboard – ${user()?.name ?? 'Guest'}`);
+ *   }),
+ * }
+ * ```
  */
 export declare function createTitle(factoryOrValue: (() => string | (() => string)) | string, awaitValue?: boolean): ResolveFn<string>;

package/lib/util/leaf.store.d.ts

@@ -2,7 +2,19 @@ import { Signal } from '@angular/core';
 import { ActivatedRouteSnapshot } from '@angular/router';
 import * as i0 from "@angular/core";
 /**
- * @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).
  */
 export type ResolvedLeafRoute = {
     route: ActivatedRouteSnapshot;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mmstack/router-core",
-  "version": "19.3.15",
+  "version": "19.3.17",
   "keywords": [
     "angular",
     "signals",