@mmstack/router-core 20.5.2 → 20.5.4

package/README.md

@@ -407,6 +407,35 @@ createNavItems(() => [
 ]);
 ```
 
+#### Default (fallback) items
+
+Routes register items on-demand, so any URL with no registration in its active chain renders an empty menu. `provideNavConfig({ defaults })` declares fallback items rendered on those URLs — handy for landing pages, error routes, or app shells where a few items should always be visible:
+
+```typescript
+provideNavConfig({
+  defaults: [
+    { label: 'Home', link: '/' },
+    { label: 'Docs', link: '/docs' },
+  ],
+}),
+```
+
+Relative `link`s on defaults resolve from `/` (the router root), so `link: 'home'` becomes `/home`. Absolute links and `UrlTree`s pass through unchanged.
+
+Named scopes are supported via the record form:
+
+```typescript
+provideNavConfig({
+  defaults: {
+    '': [{ label: 'Home', link: '/' }],          // default scope
+    main: [{ label: 'Home', link: '/' }],         // injectNavItems('main')
+    side: () => [{ label: 'Settings', link: '/settings' }], // factory
+  },
+}),
+```
+
+Shadowing follows the usual deepest-wins rule — any active route that calls `createNavItems` (including `createNavItems([])` to render an explicitly empty menu) replaces the defaults for that scope.
+
 #### Typed metadata
 
 `CreateNavItem` and `NavItem` carry a `TMeta` generic so consumers can attach app-specific fields (icons, badges, etc.) without the library imposing a shape:

package/fesm2022/mmstack-router-core.mjs

@@ -1,5 +1,5 @@
 import * as i0 from '@angular/core';
-import { InjectionToken, inject, computed, Injectable, input, booleanAttribute, output, untracked, effect, HostListener, Directive, isSignal, linkedSignal } from '@angular/core';
+import { InjectionToken, inject, computed, Injectable, input, booleanAttribute, output, untracked, effect, HostListener, Directive, isSignal, EnvironmentInjector, runInInjectionContext, linkedSignal } from '@angular/core';
 import * as i1 from '@angular/router';
 import { EventType, Router, PRIMARY_OUTLET, createUrlTreeFromSnapshot, UrlTree, RouterLink, RouterLinkWithHref, ActivatedRoute } from '@angular/router';
 import { mutable, mapArray, until, elementVisibility, toWritable } from '@mmstack/primitives';
@@ -14,31 +14,33 @@ import { Title } from '@angular/platform-browser';
 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 injectSnapshotPathResolver() {
 }
 
 /**
- * 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',
@@ -541,7 +550,7 @@ function injectSnapshotPathResolver() {
  *       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,
@@ -839,19 +935,50 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.17", ngImpo
 /** @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' },
- * }),
+ * ```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) {
+    const fn = typeof config === 'function' ? config : () => ({ ...config });
     return {
         provide: token$1,
-        useValue: { ...config },
+        useFactory: fn,
     };
 }
 /** @internal */
@@ -961,6 +1088,10 @@ const DEFAULT_NAV_SCOPE = Symbol('mmstack.nav.default');
 class NavStore {
     map = mutable(new Map());
     leafRoutes = injectLeafRoutes();
+    router = inject(Router);
+    config = injectNavConfig();
+    injector = inject(EnvironmentInjector);
+    defaultsCache = new Map();
     /** @internal */
     register(scope, routePath, items) {
         this.map.inline((m) => {
@@ -976,18 +1107,55 @@ class NavStore {
     scope(name) {
         return computed(() => {
             const scopeMap = this.map().get(name);
-            if (!scopeMap)
-                return [];
-            const leaves = this.leafRoutes();
-            for (let i = leaves.length - 1; i >= 0; i--) {
-                const items = scopeMap.get(leaves[i].path);
-                if (items) {
-                    return items.filter((it) => !it.hidden());
+            if (scopeMap) {
+                const leaves = this.leafRoutes();
+                for (let i = leaves.length - 1; i >= 0; i--) {
+                    const items = scopeMap.get(leaves[i].path);
+                    if (items) {
+                        return items.filter((it) => !it.hidden());
+                    }
                 }
             }
+            const defaults = this.getDefaultItems(name);
+            if (defaults) {
+                return defaults.filter((it) => !it.hidden());
+            }
             return [];
         });
     }
+    getDefaultItems(scope) {
+        const cached = this.defaultsCache.get(scope);
+        if (cached !== undefined)
+            return cached;
+        const built = this.buildDefaultItems(scope);
+        this.defaultsCache.set(scope, built);
+        return built;
+    }
+    buildDefaultItems(scope) {
+        const defaults = this.config.defaults;
+        if (!defaults)
+            return null;
+        let entry;
+        if (Array.isArray(defaults) || typeof defaults === 'function') {
+            if (scope === DEFAULT_NAV_SCOPE)
+                entry = defaults;
+        }
+        else {
+            const key = scope === DEFAULT_NAV_SCOPE ? '' : scope;
+            entry = defaults[key];
+        }
+        if (!entry)
+            return null;
+        const resolved = entry;
+        return untracked(() => runInInjectionContext(this.injector, () => {
+            const inputs = typeof resolved === 'function' ? resolved() : resolved;
+            const rootSnapshot = this.router.routerState.snapshot.root;
+            const prefix = scope === DEFAULT_NAV_SCOPE
+                ? '__defaults__'
+                : `__defaults__:${scope}`;
+            return inputs.map((input, i) => createInternalNavItem(input, this.router, rootSnapshot, this.config.activeMatch, NEVER_TRUE, NEVER_TRUE, `${prefix}#${i}`));
+        }));
+    }
     static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "20.3.17", ngImport: i0, type: NavStore, deps: [], target: i0.ɵɵFactoryTarget.Injectable });
     static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "20.3.17", ngImport: i0, type: NavStore, providedIn: 'root' });
 }
@@ -999,7 +1167,9 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.17", ngImpo
  * 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.
@@ -1025,22 +1195,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'
@@ -1170,7 +1372,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 ?? '';
@@ -1241,14 +1465,48 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.17", 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).
  *
- * 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'}`);
+ *   }),
+ * }
+ * ```
  */
 function createTitle(factoryOrValue, awaitValue = false) {
     const factory = typeof factoryOrValue === 'string' ? () => factoryOrValue : factoryOrValue;