@mmstack/router-core 20.5.1 → 20.5.3

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';
@@ -11,7 +11,7 @@ import { Title } from '@angular/platform-browser';
 /**
  * @internal
  */
-const token$1 = new InjectionToken('MMSTACK_BREADCRUMB_CONFIG');
+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. *
@@ -43,7 +43,7 @@ const token$1 = new InjectionToken('MMSTACK_BREADCRUMB_CONFIG');
  */
 function provideBreadcrumbConfig(config) {
     return {
-        provide: token$1,
+        provide: token$2,
         useValue: {
             ...config,
         },
@@ -53,7 +53,7 @@ function provideBreadcrumbConfig(config) {
  * @internal
  */
 function injectBreadcrumbConfig() {
-    return (inject(token$1, {
+    return (inject(token$2, {
         optional: true,
     }) ?? {});
 }
@@ -95,8 +95,9 @@ function isNavigationEnd(e) {
  * }
  * ```
  */
-function url() {
-    const router = inject(Router);
+function url(router) {
+    if (!router)
+        router = inject(Router);
     return toSignal(router.events.pipe(filter(isNavigationEnd), map((e) => e.urlAfterRedirects)), {
         initialValue: router.url,
     });
@@ -515,10 +516,11 @@ function injectSnapshotPathResolver() {
 /**
  * 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
@@ -528,25 +530,34 @@ function injectSnapshotPathResolver() {
  *     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...',
+ *         };
+ *       }),
  *     },
- *   }
+ *   },
  * ];
  * ```
  */
-function createBreadcrumb(factory) {
+function createBreadcrumb(factoryOrValue) {
+    const factory = typeof factoryOrValue === 'string'
+        ? () => ({ label: factoryOrValue })
+        : typeof factoryOrValue === 'function'
+            ? () => {
+                const result = factoryOrValue();
+                return typeof result === 'string' ? { label: result } : result;
+            }
+            : () => factoryOrValue;
     return async (route) => {
         const router = inject(Router);
         const store = inject(BreadcrumbStore);
@@ -650,6 +661,38 @@ function treeToSerializedUrl(router, urlTree) {
         return null;
     return router.serializeUrl(urlTree);
 }
+/**
+ * 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);
+ *     });
+ *   }
+ * }
+ * ```
+ */
 function injectTriggerPreload() {
     const req = inject(PreloadRequester);
     const router = inject(Router);
@@ -793,6 +836,277 @@ 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.
+ *
+ * @example
+ * ```typescript
+ * provideNavConfig({
+ *   activeMatch: { queryParams: 'ignored' },
+ *   defaults: [
+ *     { label: 'Home', link: '/' },
+ *     { label: 'Docs', link: '/docs' },
+ *   ],
+ * }),
+ * ```
+ */
+function provideNavConfig(config) {
+    const fn = typeof config === 'function' ? config : () => ({ ...config });
+    return {
+        provide: token$1,
+        useFactory: fn,
+    };
+}
+/** @internal */
+function injectNavConfig() {
+    return inject(token$1, { optional: true }) ?? {};
+}
+
+/** @internal */
+const NEVER_TRUE = computed(() => false, ...(ngDevMode ? [{ debugName: "NEVER_TRUE" }] : []));
+function wrap(value, fallback) {
+    if (value === undefined)
+        return fallback ? fallback : computed(() => undefined);
+    if (typeof value === 'function')
+        return isSignal(value) ? value : computed(value);
+    return computed(() => value);
+}
+function isAbsoluteCommandArray(commands) {
+    return (commands.length > 0 &&
+        typeof commands[0] === 'string' &&
+        commands[0].startsWith('/'));
+}
+function resolveLinkTree(input, router, relativeTo) {
+    const raw = typeof input === 'function' ? input() : input;
+    if (raw === undefined || raw === null)
+        return null;
+    if (raw instanceof UrlTree)
+        return raw;
+    if (typeof raw === 'string') {
+        if (raw.startsWith('/'))
+            return router.parseUrl(raw);
+        const parsed = router.parseUrl('/' + raw);
+        const primary = parsed.root.children['primary'];
+        const segments = primary ? primary.segments.map((s) => s.path) : [];
+        return createUrlTreeFromSnapshot(relativeTo, segments, parsed.queryParams, parsed.fragment);
+    }
+    if (isAbsoluteCommandArray(raw))
+        return router.createUrlTree(raw);
+    return createUrlTreeFromSnapshot(relativeTo, raw);
+}
+function resolveMeta(input) {
+    if (input === undefined)
+        return {};
+    return typeof input === 'function' ? input() : input;
+}
+/**
+ * @internal
+ * Recursively builds an {@link InternalNavItem} tree from {@link CreateNavItem} input.
+ * Cascades parent `disabled`/`hidden` to descendants and computes `active` against the
+ * current router URL using `Router.isActive`.
+ */
+function createInternalNavItem(input, router, relativeTo, configActiveMatch, parentDisabled, parentHidden, fallbackId) {
+    const label = wrap(input.label);
+    const ariaLabel = input.ariaLabel ? wrap(input.ariaLabel) : label;
+    const linkTree = computed(() => resolveLinkTree(input.link, router, relativeTo), ...(ngDevMode ? [{ debugName: "linkTree" }] : []));
+    const link = computed(() => {
+        const tree = linkTree();
+        return tree ? router.serializeUrl(tree) : null;
+    }, ...(ngDevMode ? [{ debugName: "link" }] : []));
+    const ownDisabled = wrap(input.disabled, NEVER_TRUE);
+    const ownHidden = wrap(input.hidden, NEVER_TRUE);
+    const disabled = computed(() => parentDisabled() || ownDisabled(), ...(ngDevMode ? [{ debugName: "disabled" }] : []));
+    const hidden = computed(() => parentHidden() || ownHidden(), ...(ngDevMode ? [{ debugName: "hidden" }] : []));
+    const metaInput = input.meta;
+    const meta = computed(() => resolveMeta(metaInput), ...(ngDevMode ? [{ debugName: "meta" }] : []));
+    const id = input.id !== undefined
+        ? wrap(input.id)
+        : computed(() => link() ?? fallbackId);
+    const childItems = (input.children ?? []).map((childInput, i) => createInternalNavItem(childInput, router, relativeTo, configActiveMatch, disabled, hidden, `${fallbackId}.${i}`));
+    const children = computed(() => childItems.filter((c) => !c.hidden()), ...(ngDevMode ? [{ debugName: "children" }] : []));
+    const mergedActiveMatch = {
+        ...configActiveMatch,
+        ...input.activeMatch,
+    };
+    const trackNavigation = url(router);
+    const finalOptions = {
+        paths: 'subset',
+        fragment: 'ignored',
+        matrixParams: 'ignored',
+        queryParams: 'subset',
+        ...mergedActiveMatch,
+    };
+    const ownActive = computed(() => {
+        trackNavigation();
+        const tree = linkTree();
+        return tree ? router.isActive(tree, finalOptions) : false;
+    }, ...(ngDevMode ? [{ debugName: "ownActive" }] : []));
+    const orWithChildren = input.matchesWhenChildActive ?? input.activeMatch === undefined;
+    const active = computed(() => ownActive() ||
+        (orWithChildren &&
+            !!childItems.length &&
+            childItems.some((c) => c.active())), ...(ngDevMode ? [{ debugName: "active" }] : []));
+    return {
+        id,
+        label,
+        ariaLabel,
+        link,
+        active,
+        disabled,
+        hidden,
+        meta,
+        children,
+    };
+}
+
+/** @internal */
+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) => {
+            let scopeMap = m.get(scope);
+            if (!scopeMap) {
+                scopeMap = new Map();
+                m.set(scope, scopeMap);
+            }
+            scopeMap.set(routePath, items);
+        });
+    }
+    /** @internal */
+    scope(name) {
+        return computed(() => {
+            const scopeMap = this.map().get(name);
+            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' });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.17", ngImport: i0, type: NavStore, decorators: [{
+            type: Injectable,
+            args: [{ providedIn: 'root' }]
+        }] });
+/**
+ * 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`. 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.
+ *
+ * @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();
+ * }
+ * ```
+ */
+function injectNavItems(name) {
+    const store = inject(NavStore);
+    return store.scope(name ?? DEFAULT_NAV_SCOPE);
+}
+
+/**
+ * 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.
+ */
+function createNavItems(itemsOrFactory, options) {
+    const factory = typeof itemsOrFactory === 'function'
+        ? itemsOrFactory
+        : () => itemsOrFactory;
+    return async (route) => {
+        const router = inject(Router);
+        const store = inject(NavStore);
+        const resolveRoutePath = injectSnapshotPathResolver();
+        const config = injectNavConfig();
+        const routePath = resolveRoutePath(route);
+        const scope = options?.name ?? DEFAULT_NAV_SCOPE;
+        const items = factory().map((input, i) => createInternalNavItem(input, router, route, config.activeMatch, NEVER_TRUE, NEVER_TRUE, `${routePath}#${i}`));
+        store.register(scope, routePath, items);
+        return Promise.resolve();
+    };
+}
+
 /**
  * Creates a WritableSignal that synchronizes with a specific URL query parameter,
  * enabling two-way binding between the signal's state and the URL.
@@ -902,7 +1216,7 @@ function queryParam(key, route = inject(ActivatedRoute)) {
     return toWritable(queryParam, set);
 }
 
-const token = new InjectionToken('MMSTACK_TITLE_CONFIG');
+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
  */
@@ -914,6 +1228,7 @@ function provideTitleConfig(config) {
     return {
         provide: token,
         useValue: {
+            initialTitle: config?.initialTitle ?? '',
             parser: prefixFn,
             keepLastKnown: config?.keepLastKnownTitle ?? true,
         },
@@ -926,25 +1241,28 @@ function injectTitleConfig() {
     return (inject(token, {
         optional: true,
     }) ?? {
+        initialTitle: '',
         parser: identity,
         keepLastKnown: true,
     });
 }
 
 class TitleStore {
-    title = inject(Title);
     map = mutable(new Map());
-    leafRoutes = injectLeafRoutes();
     constructor() {
-        const reverseLeaves = computed(() => this.leafRoutes().toReversed(), ...(ngDevMode ? [{ debugName: "reverseLeaves" }] : []));
+        const { keepLastKnown, initialTitle } = injectTitleConfig();
+        const leafRoutes = injectLeafRoutes();
+        const title = inject(Title);
+        const fallbackTitle = initialTitle || untracked(() => title.getTitle());
+        const reverseLeaves = computed(() => leafRoutes().toReversed(), ...(ngDevMode ? [{ debugName: "reverseLeaves" }] : []));
         const currentResolvedTitles = computed(() => {
             const map = this.map();
             return reverseLeaves()
-                .map((leaf) => map.get(leaf.path)?.() ?? leaf.route.title)
-                .filter((v) => !!v);
+                .map((leaf) => map.get(leaf.path)?.() ?? leaf.route.title ?? null)
+                .filter((v) => v !== null);
         }, ...(ngDevMode ? [{ debugName: "currentResolvedTitles" }] : []));
         const currentTitle = computed(() => currentResolvedTitles().at(0) ?? '', ...(ngDevMode ? [{ debugName: "currentTitle" }] : []));
-        const heldTitle = injectTitleConfig().keepLastKnown
+        const heldTitle = keepLastKnown
             ? linkedSignal({
                 source: () => currentTitle(),
                 computation: (value, prev) => {
@@ -955,7 +1273,7 @@ class TitleStore {
             })
             : currentTitle;
         effect(() => {
-            this.title.setTitle(heldTitle());
+            title.setTitle(heldTitle() || fallbackTitle);
         });
     }
     register(id, titleFn) {
@@ -974,19 +1292,20 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.17", ngImpo
  *
  * 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`.
  */
-function createTitle(fn, awaitValue = false) {
+function createTitle(factoryOrValue, awaitValue = false) {
+    const factory = typeof factoryOrValue === 'string' ? () => factoryOrValue : factoryOrValue;
     return async (route) => {
         const store = inject(TitleStore);
         const resolver = injectSnapshotPathResolver();
         const fp = resolver(route);
         const { parser } = injectTitleConfig();
-        const resolved = fn();
+        const resolved = factory();
         const titleSignal = typeof resolved === 'string'
             ? computed(() => resolved)
             : computed(resolved);
@@ -1002,5 +1321,5 @@ function createTitle(fn, awaitValue = false) {
  * Generated bundle index. Do not edit.
  */
 
-export { Link, PreloadStrategy, createBreadcrumb, createTitle, injectBreadcrumbs, injectTriggerPreload, provideBreadcrumbConfig, provideMMLinkDefaultConfig, provideTitleConfig, queryParam, url };
+export { Link, PreloadStrategy, createBreadcrumb, createNavItems, createTitle, injectBreadcrumbs, injectNavItems, injectTriggerPreload, provideBreadcrumbConfig, provideMMLinkDefaultConfig, provideNavConfig, provideTitleConfig, queryParam, url };
 //# sourceMappingURL=mmstack-router-core.mjs.map