@mmstack/router-core 21.0.3 → 21.0.4

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

@@ -1,9 +1,22 @@
+import * as i1 from '@angular/router';
+import { ActivatedRouteSnapshot, ResolveFn, Params, ActivatedRoute, UrlTree, IsActiveMatchOptions, PreloadingStrategy, Route, Router } from '@angular/router';
 import * as _angular_core from '@angular/core';
 import { Signal, InjectionToken, Provider, WritableSignal } from '@angular/core';
-import * as i1 from '@angular/router';
-import { ActivatedRouteSnapshot, ResolveFn, Params, ActivatedRoute, UrlTree, PreloadingStrategy, Route } from '@angular/router';
 import { Observable } from 'rxjs';
 
+/**
+ * @internal
+ */
+type ResolvedLeafRoute = {
+    route: ActivatedRouteSnapshot;
+    segment: {
+        path: string;
+        resolved: string;
+    };
+    path: string;
+    link: string;
+};
+
 /**
  * Represents a single breadcrumb item within the navigation path.
  * All dynamic properties are represented as Angular Signals to enable reactivity.
@@ -32,19 +45,6 @@ type Breadcrumb = {
     link: Signal<string>;
 };
 
-/**
- * @internal
- */
-type ResolvedLeafRoute = {
-    route: ActivatedRouteSnapshot;
-    segment: {
-        path: string;
-        resolved: string;
-    };
-    path: string;
-    link: string;
-};
-
 /**
  * A function that returns a custom label generation function.
  * The outer function is called in a root injection context
@@ -136,10 +136,11 @@ type CreateBreadcrumbOptions = {
 /**
  * Creates and registers a breadcrumb for a specific route.
  * This function is designed to be used as an Angular Route `ResolveFn`.
- * It handles the registration of the breadcrumb with the `BreadcrumbStore`
- * and ensures automatic deregistration when the route is destroyed.
  *
- * @param factory A function that returns a `CreateBreadcrumbOptions` object.
+ * 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 A static label, a static `CreateBreadcrumbOptions`, or a factory returning either.
  * @see CreateBreadcrumbOptions
  *
  * @example
@@ -149,25 +150,26 @@ type CreateBreadcrumbOptions = {
  *     path: 'home',
  *     component: HomeComponent,
  *     resolve: {
- *       breadcrumb: createBreadcrumb(() => ({
- *         label: 'Home',
- *       });
+ *       // shorthand for { label: 'Home' }
+ *       breadcrumb: createBreadcrumb('Home'),
  *     },
+ *   },
+ *   {
  *     path: 'users/:userId',
  *     component: UserProfileComponent,
  *     resolve: {
  *       breadcrumb: createBreadcrumb(() => {
  *         const userStore = inject(UserStore);
  *         return {
- *            label: () => userStore.user().name ?? 'Loading...
- *        };
- *      })
+ *           label: () => userStore.user().name ?? 'Loading...',
+ *         };
+ *       }),
  *     },
- *   }
+ *   },
  * ];
  * ```
  */
-declare function createBreadcrumb(factory: () => CreateBreadcrumbOptions): ResolveFn<void>;
+declare function createBreadcrumb(factoryOrValue: (() => CreateBreadcrumbOptions | string) | string | CreateBreadcrumbOptions): ResolveFn<void>;
 
 /**
  * Injects and provides access to a reactive list of breadcrumbs.
@@ -199,6 +201,38 @@ declare function createBreadcrumb(factory: () => CreateBreadcrumbOptions): Resol
  */
 declare function injectBreadcrumbs(): Signal<Breadcrumb[]>;
 
+/**
+ * Returns an imperative function that triggers preloading for an arbitrary link, using
+ * the same path resolution and {@link PreloadStrategy} pipeline as the {@link Link}
+ * (`mmLink`) directive.
+ *
+ * Use this when the `Link` directive isn't a fit — for example, preloading a route from
+ * an effect when a user opens a menu, hovers a non-link element, or reacts to a signal
+ * change — and you don't want to render an `<a [mmLink]>` just to request the preload.
+ *
+ * Requires {@link PreloadStrategy} to be wired up via `provideRouter(routes, withPreloading(PreloadStrategy))`,
+ * just like the directive.
+ *
+ * @returns A function accepting the same link descriptor shape as `mmLink` (`string`,
+ * commands array, `UrlTree`, or `null`). Passing `null` or an unresolvable link is a no-op.
+ *
+ * @example
+ * ```typescript
+ * @Component({ ... })
+ * export class CommandPaletteComponent {
+ *   private readonly triggerPreload = injectTriggerPreload();
+ *
+ *   protected readonly highlighted = signal<string | null>(null);
+ *
+ *   constructor() {
+ *     effect(() => {
+ *       const target = this.highlighted();
+ *       if (target) this.triggerPreload(target);
+ *     });
+ *   }
+ * }
+ * ```
+ */
 declare function injectTriggerPreload(): (link: string | any[] | UrlTree | null, relativeTo?: ActivatedRoute, queryParams?: Params, fragment?: string, queryParamsHandling?: "merge" | "preserve" | "") => void;
 /**
  * Configuration for the `mmLink` directive.
@@ -247,6 +281,151 @@ declare class Link {
     static ɵdir: _angular_core.ɵɵDirectiveDeclaration<Link, "[mmLink]", ["mmLink"], { "target": { "alias": "target"; "required": false; "isSignal": true; }; "queryParams": { "alias": "queryParams"; "required": false; "isSignal": true; }; "fragment": { "alias": "fragment"; "required": false; "isSignal": true; }; "queryParamsHandling": { "alias": "queryParamsHandling"; "required": false; "isSignal": true; }; "state": { "alias": "state"; "required": false; "isSignal": true; }; "info": { "alias": "info"; "required": false; "isSignal": true; }; "relativeTo": { "alias": "relativeTo"; "required": false; "isSignal": true; }; "skipLocationChange": { "alias": "skipLocationChange"; "required": false; "isSignal": true; }; "replaceUrl": { "alias": "replaceUrl"; "required": false; "isSignal": true; }; "mmLink": { "alias": "mmLink"; "required": false; "isSignal": true; }; "preloadOn": { "alias": "preloadOn"; "required": false; "isSignal": true; }; "useMouseDown": { "alias": "useMouseDown"; "required": false; "isSignal": true; }; "beforeNavigate": { "alias": "beforeNavigate"; "required": false; "isSignal": true; }; }, { "preloading": "preloading"; }, never, never, true, [{ directive: typeof i1.RouterLink; inputs: { "routerLink": "mmLink"; "target": "target"; "queryParams": "queryParams"; "fragment": "fragment"; "queryParamsHandling": "queryParamsHandling"; "state": "state"; "relativeTo": "relativeTo"; "skipLocationChange": "skipLocationChange"; "replaceUrl": "replaceUrl"; }; outputs: {}; }]>;
 }
 
+/**
+ * Description of a single navigation item.
+ *
+ * Reactive fields accept either a static value or a zero-arg function — the function
+ * form is wrapped in a `computed` so reading signals inside it produces a reactive value.
+ *
+ * @typeParam TMeta Arbitrary consumer-defined metadata round-tripped to {@link NavItem.meta}.
+ *
+ * @see createNavItems
+ * @see NavItem
+ */
+type CreateNavItem<TMeta = Record<string, unknown>> = {
+    /** Visible text. */
+    label: string | (() => string);
+    /**
+     * The navigation target. Resolved relative to the route the resolver is attached to —
+     * the same convention as Angular's `routerLink`:
+     *
+     * - `'a'` / `'a/b'` / `['a', 'b']` — relative segments, resolve to `${mount}/a` etc.
+     * - `'/foo'` / `['/foo', 'bar']` — absolute, leading-slash escape hatch.
+     * - A pre-built `UrlTree` is passed through unchanged.
+     *
+     * Omit (or return `null`) for a pure grouping header — `active` will then fall through
+     * to the children-active check.
+     */
+    link?: string | any[] | (() => string | any[] | null) | null;
+    /** Accessible label. Defaults to `label`. */
+    ariaLabel?: string | (() => string);
+    /** When true, the item is rendered but non-interactive. Cascades to descendants. */
+    disabled?: boolean | (() => boolean);
+    /** When true, the item (and its subtree) is filtered out of the consumer-facing array. */
+    hidden?: boolean | (() => boolean);
+    /** Arbitrary metadata round-tripped on the resulting `NavItem`. */
+    meta?: TMeta | (() => TMeta);
+    /**
+     * Override the match options used to compute `active`. Merged on top of the global default
+     * from `provideNavConfig`, which is in turn merged on top of `@angular/router`'s
+     * `subsetMatchOptions` defaults.
+     *
+     * Setting this also implicitly disables the default child-active OR — see
+     * {@link matchesWhenChildActive} to opt back in.
+     */
+    activeMatch?: Partial<IsActiveMatchOptions>;
+    /**
+     * Controls whether `active` ORs with descendant `active`.
+     *
+     * Default: `true` when `activeMatch` is omitted, `false` when `activeMatch` is set.
+     * Explicit values override the default.
+     */
+    matchesWhenChildActive?: boolean;
+    /** Optional stable id. Defaults to the serialized link when present. */
+    id?: string | (() => string);
+    /** Nested items. */
+    children?: CreateNavItem<TMeta>[];
+};
+/**
+ * A navigation item exposed by `injectNavItems`. All fields are signals so consumers can
+ * read reactively without caring whether the source was static or signal-derived.
+ *
+ * @typeParam TMeta Same as the corresponding {@link CreateNavItem}.
+ */
+type NavItem<TMeta = Record<string, unknown>> = {
+    id: Signal<string>;
+    label: Signal<string>;
+    ariaLabel: Signal<string>;
+    /** Serialized URL, or `null` for pure grouping items with no link. */
+    link: Signal<string | null>;
+    active: Signal<boolean>;
+    disabled: Signal<boolean>;
+    meta: Signal<TMeta>;
+    /** Children that survive the hidden filter. */
+    children: Signal<NavItem<TMeta>[]>;
+};
+
+/**
+ * Global configuration for the nav system.
+ * @see provideNavConfig
+ */
+type NavConfig = {
+    /**
+     * 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>;
+};
+/**
+ * Provides global configuration for the nav system.
+ *
+ * @example
+ * ```typescript
+ * provideNavConfig({
+ *   activeMatch: { queryParams: 'ignored' },
+ * }),
+ * ```
+ */
+declare function provideNavConfig(config?: 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.
+ *
+ * Multiple scopes can be registered on a single route by giving each its own `name`
+ * (and a unique key in the `resolve` map):
+ *
+ * ```typescript
+ * 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.
+ */
+declare function createNavItems<TMeta = Record<string, unknown>>(itemsOrFactory: CreateNavItem<TMeta>[] | (() => CreateNavItem<TMeta>[]), options?: {
+    name?: string;
+}): ResolveFn<void>;
+
+/**
+ * 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.
+ *
+ * @typeParam TMeta The shape of `NavItem.meta` for the consuming code. Untyped at the
+ * registration site — this is a consumer-side assertion.
+ *
+ * @example
+ * ```typescript
+ * @Component({
+ *   template: `
+ *     @for (item of items(); track item) {
+ *       <a [href]="item.link()" [class.active]="item.active()">{{ item.label() }}</a>
+ *     }
+ *   `,
+ * })
+ * export class TopBar {
+ *   protected readonly items = injectNavItems();
+ * }
+ * ```
+ */
+declare function injectNavItems<TMeta = Record<string, unknown>>(name?: string): Signal<NavItem<TMeta>[]>;
+
 declare class PreloadStrategy implements PreloadingStrategy {
     private readonly loading;
     private readonly router;
@@ -339,6 +518,12 @@ declare function queryParam(key: string | (() => string), route?: ActivatedRoute
  * @see {createTitle}
  */
 type TitleConfig = {
+    /**
+     * The base title to fallback to, by default Title.getTitle() is called on instantiation and that is used as a fallback,
+     * which in most cases should resolve to what is in index.html, unless you specifically call Title.setTitle() before any routes,
+     * are initialized.
+     */
+    initialTitle?: string;
     /**
      * The title to be used when no title is set.
      * If not provided it defaults to an empty string
@@ -360,13 +545,13 @@ declare function provideTitleConfig(config?: TitleConfig): Provider;
  *
  * Creates a title resolver function that can be used in Angular's router.
  *
- * @param fn
- * A function that returns a string or a Signal<string> representing the title.
+ * @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`.
  */
-declare function createTitle(fn: () => string | (() => string), awaitValue?: boolean): ResolveFn<string>;
+declare function createTitle(factoryOrValue: (() => string | (() => string)) | string, awaitValue?: boolean): ResolveFn<string>;
 
 /**
  * Creates a Signal that tracks the current router URL.
@@ -398,7 +583,7 @@ declare function createTitle(fn: () => string | (() => string), awaitValue?: boo
  * }
  * ```
  */
-declare function url(): Signal<string>;
+declare function url(router?: Router): Signal<string>;
 
-export { Link, PreloadStrategy, createBreadcrumb, createTitle, injectBreadcrumbs, injectTriggerPreload, provideBreadcrumbConfig, provideMMLinkDefaultConfig, provideTitleConfig, queryParam, url };
-export type { Breadcrumb, TitleConfig };
+export { Link, PreloadStrategy, createBreadcrumb, createNavItems, createTitle, injectBreadcrumbs, injectNavItems, injectTriggerPreload, provideBreadcrumbConfig, provideMMLinkDefaultConfig, provideNavConfig, provideTitleConfig, queryParam, url };
+export type { Breadcrumb, BreadcrumbConfig, CreateNavItem, NavConfig, NavItem, ResolvedLeafRoute, TitleConfig };