@mmstack/router-core 20.4.1 → 21.0.1

package/README.md

@@ -1,322 +1,322 @@
-# @mmstack/router-core
-
-Core utilities and Signal-based primitives for enhancing development with `@angular/router`. This library provides helpers for common routing tasks, reactive integration with router state, and intelligent module preloading.
-
-Part of the `@mmstack` ecosystem, designed to complement [@mmstack/primitives](https://www.npmjs.com/package/@mmstack/primitives).
-
-[![npm version](https://badge.fury.io/js/%40mmstack%2Frouter-core.svg)](https://badge.fury.io/js/%40mmstack%2Frouter-core)
-
-## Installation
-
-```bash
-npm install @mmstack/router-core
-```
-
-## Signal Utilities
-
-This library includes helpers to interact with router state reactively using Angular Signals.
-
----
-
-### queryParam
-
-Creates a WritableSignal that synchronizes with a specific URL query parameter, enabling two-way binding between the signal's state and the URL.
-
-- Reading the signal returns the parameter's current value (string) or null if absent.
-- Setting the signal to a string updates the URL parameter.
-- Setting the signal to null removes the parameter from the URL.
-- Reacts to external navigation changes affecting the parameter.
-- Supports static or dynamic (function/signal) keys.
-
-```typescript
-@Component({
-  selector: 'app-search-page',
-  standalone: true,
-  imports: [FormsModule],
-  template: `
-    <label>
-      Search:
-      <input [(ngModel)]="searchTerm" placeholder="Enter search term..." />
-    </label>
-    <button (click)="searchTerm.set(null)" [disabled]="!searchTerm()">Clear</button>
-    <p>Current search: {{ searchTerm() ?? 'None' }}</p>
-  `,
-})
-export class SearchPageComponent {
-  // Two-way bind the 'q' query parameter (?q=...)
-  protected readonly searchTerm = queryParam('q');
-
-  constructor() {
-    effect(() => {
-      const currentTerm = this.searchTerm();
-      console.log('Search term changed:', currentTerm);
-      // Trigger API call, update results, etc. based on currentTerm
-    });
-  }
-}
-```
-
-### url
-
-Creates a read-only Signal that tracks the current router URL string.
-
-- Updates after each successful navigation.
-- Reflects the URL after any redirects (urlAfterRedirects).
-- Initializes with the router's current URL synchronously.
-
-```typescript
-import { Component, effect } from '@angular/core';
-import { url } from '@mmstack/router-core';
-
-@Component({
-  selector: 'app-header',
-  standalone: true,
-  template: `<nav>Current Path: {{ currentUrl() }}</nav>`,
-})
-export class HeaderComponent {
-  protected readonly currentUrl = url();
-}
-```
-
-## Preloading Utilities
-
----
-
-Enhance your application's performance by preloading Angular modules. This library provides a flexible directive and a smart preloading strategy to load modules just before they are needed.
-
-### PreloadStrategy
-
-This is a custom Angular PreloadingStrategy that works in tandem with the mmstack `Link` (via an internal `PreloadService`) to intelligently preload lazy-loaded modules.
-
-**Features**:
-
-- Listens for preload requests triggered by the `Link` directive.
-- Uses advanced path matching to identify the correct route to preload, even with route parameters and matrix parameters.
-- Avoids preloading if the connection is slow (e.g., '2g' effective type) or if the user has data-saving enabled in their browser.
-- Respects a `data: { preload: false }` flag in route configurations to explicitly disable preloading for specific routes.
-- Prevents redundant preloading attempts for the same route path.
-
-To enable this preloading strategy, you need to provide it in your application's main routing configuration.
-
-```typescript
-import { PreloadStrategy } from '@mmstack/router-core';
-import { ApplicationConfig } from '@angular/core';
-import { provideRouter, withPreloading } from '@angular/router';
-import { routes } from './app.routes';
-
-export const appConfig: ApplicationConfig = {
-  providers: [
-    //...other providers
-    provideRouter(routes, withPreloading(PreloadStrategy)),
-  ],
-};
-```
-
-### Link (mmLink)
-
-The `Link` directive (used with the `mmLink` attribute) is an enhancement for Angular's standard `RouterLink` directive. It adds the capability to preload the JavaScript modules associated with the linked route, based on user interaction or visibility. Other than the added `preloadOn` input & `preloading` output it directly proxies `RouterLink`.
-
-- `preloadOn`: `input<'hover' | 'visible' | null>()` [default: 'hover'] specifies when to preload, `null` disables preloading
-- `preloading` - `output<void>()` fires when route is registered for preloading (before load)
-
-To use it simply replace any exiting routerLinks that you would like to enable preloading on with the mmLink, you can keep all existing inputs the same. And add the mmstack `PreloadStrategy` in your configuration
-
-```typescript
-import { Link } from '@mmstack/router-core';
-import { RouterLink } from '@angular/router';
-
-@Component({
-  selector: 'app-navigation',
-  standalone: true,
-  imports: [Link, RouterLink],
-  template: `
-    <nav>
-      <!-- preload on hover -->
-      <a [mmLink]="['/features']" preloadOn="hover">Features</a>
-      <!-- preload on visible -->
-      <a [mmLink]="['/pricing']" preloadOn="visible">Pricing</a>
-      <!-- no preload -->
-      <a [mmLink]="['/contact']" [preloadOn]="null">Contact</a>
-      <!-- preload on hover -->
-      <a [mmLink]="['/about']">About</a>
-      <!-- no preload, or just use [preloadOn]="null" -->
-      <a [routerLink]="['/terms']">Terms & Conditions</a>
-    </nav>
-  `,
-})
-export class NavigationComponent {}
-```
-
-## Headless breadcrumb utilities
-
-This library includes a signal-based, headless toolkit for generating and managing breadcrumbs in your Angular application. It provides the logic to derive breadcrumb data from your routes, allowing you to easily build a completely custom breadcrumb UI component & let the library worry about active routes :)
-
-### Consuming breadcrumbs
-
-The primary way to access the breadcrumb data is via the `injectBreadcrumbs` function. It returns a `Signal<Breadcrumb[]>` that updates automatically as navigation changes. Each `Breadcrumb` object in the array contains reactive signals for its `label`, `link`, `ariaLabel`, and a static id for iteration purposes.
-
-```typescript
-import { Component } from '@angular/core';
-import { injectBreadcrumbs } from '@mmstack/router-core'; // Adjust path if needed
-
-@Component({
-  selector: 'app-breadcrumbs',
-  standalone: true,
-  template: `
-    <nav aria-label="breadcrumb">
-      <ol>
-        @for (crumb of breadcrumbs(); track crumb.id) {
-          <li>
-            <a [href]="crumb.link()" [attr.aria-label]="crumb.ariaLabel()">{{ crumb.label() }}</a>
-          </li>
-        }
-      </ol>
-    </nav>
-  `,
-})
-export class CustomBreadcrumbsComponent {
-  protected readonly breadcrumbs = injectBreadcrumbs();
-}
-```
-
-### Registering custom breadcrumbs
-
-For routes where automatic breadcrumb generation isn't sufficient or when you need more control, you can manually define breadcrumbs using the `createBreadcrumb` route resolver.
-
-This function allows you to specify the label (static or dynamic via a function) and other properties for a breadcrumb associated with a particular route.
-You can use injection in the factory function, as you would with any resolver, making translations or subscribing to dynamic data a breaze! :)
-
-```typescript
-import { Routes } from '@angular/router';
-import { createBreadcrumb } from '@mmstack/router-core';
-import { HomeComponent } from './home.component';
-import { UserProfileComponent } from './user-profile.component';
-import { UserStore } from './user.store';
-import { inject } from '@angular/core';
-import { AdminComponent } from './admin.component';
-
-export const appRoutes: Routes = [
-  {
-    path: 'home',
-    component: HomeComponent,
-    resolve: {
-      // Simple static breadcrumb
-      breadcrumb: createBreadcrumb(() => ({
-        label: 'Home',
-      })),
-    },
-  },
-  {
-    path: 'admin',
-    component: AdminComponent,
-    data: {
-      skipBreadcrumb: true, // opt out of auto-generation for this specific route
-    },
-  },
-  {
-    path: 'users/:userId',
-    component: UserProfileComponent,
-    resolve: {
-      breadcrumb: createBreadcrumb(() => {
-        const userStore = inject(UserStore);
-        return {
-          label: () => `Profile: ${userStore.currentUser().name}` ?? 'Loading...',
-          ariaLabel: () => `View profile for ${userStore.currentUser().name ?? 'user'}`,
-        };
-      }),
-    },
-  },
-];
-```
-
-### Configuration [optional]
-
-The breadcrumb system can be configured globally using `provideBreadcrumbConfig`. This allows you to, for example, set the system to 'manual' mode (disabling all automatic generation) or provide a custom function for generating breadcrumb labels.
-
-```typescript
-import { provideRouter } from '@angular/router';
-import { provideBreadcrumbConfig, BreadcrumbConfig, ResolvedLeafRoute } from '@mmstack/router-core'; // Adjust path
-import { appRoutes } from './app.routes';
-import { ApplicationConfig } from '@angular/core';
-
-// Example: Custom label generation strategy
-const customLabelStrategy = () => {
-  // you can inject root injectable services/stores here.
-  return (leaf: ResolvedLeafRoute): string => {
-    return leaf.route.data?.['navTitle'] || leaf.route.title || 'Default Title';
-  };
-};
-export const appConfig: ApplicationConfig = {
-  providers: [
-    // ...rest
-    provideBreadcrumbConfig({
-      // generation: 'manual' // When set to 'manual' the system only uses explicitly defined breadcrumbs
-      generation: customLabelStrategy, // Or provide a custom generation function
-    }),
-  ],
-};
-```
-
-## Title utilities
-
-This library provides a helper function, `createTitle`, to set the document title dynamically from within your route configuration. It integrates seamlessly with Angular's built-in `title` property on routes, allowing for both static and signal-based reactive titles.
-
-By default, the system will use a title defined on a route's `data` or `title` property. createTitle enhances this by allowing titles to be derived from reactive state.
-
-### Using `createTitle`
-
-The `createTitle` function is a route resolver that returns a title string. You use it directly in the `title` property of a route definition. It can accept a function that returns a static string or a function that returns a dynamic string (which will be converted to a `signal`).
-
-```typescript
-import { Routes } from '@angular/router';
-import { createTitle } from '@mmstack/router-core';
-import { inject } from '@angular/core';
-import { ProductStore } from './product.store';
-
-export const appRoutes: Routes = [
-  {
-    path: 'about',
-    // Example 1: Static title
-    resolve: {
-      title: createTitle(() => 'About Us'), // static
-    },
-    loadComponent: () => import('./about.component').then((m) => m.AboutComponent),
-  },
-  {
-    path: 'products/:id',
-    // Example 2: Dynamic, signal-based title from a store
-    resolve: {
-      title: createTitle(() => {
-        const productStore = inject(ProductStore);
-        // The inner function creates a computed signal under the hood
-        return () => `Product: ${productStore.product().name ?? 'Loading...'}`;
-      }),
-    },
-    loadComponent: () => import('./product-detail.component').then((m) => m.ProductComponent),
-  },
-];
-```
-
-### Configuration [optional]
-
-You can provide a global configuration to prepend or append text to all titles using provideTitleConfig.
-
-```typescript
-import { provideRouter } from '@angular/router';
-import { provideTitleConfig } from '@mmstack/router-core';
-import { appRoutes } from './app.routes';
-import { ApplicationConfig } from '@angular/core';
-
-export const appConfig: ApplicationConfig = {
-  providers: [
-    provideRouter(appRoutes),
-    provideTitleConfig({
-      // Prefix can be a static string...
-      // prefix: 'My Awesome App | '
-
-      // ...or a function for more control over the format
-      prefix: (title) => (title ? `${title} - MyApp` : 'MyApp'),
-    }),
-  ],
-};
-```
+# @mmstack/router-core
+
+Core utilities and Signal-based primitives for enhancing development with `@angular/router`. This library provides helpers for common routing tasks, reactive integration with router state, and intelligent module preloading.
+
+Part of the `@mmstack` ecosystem, designed to complement [@mmstack/primitives](https://www.npmjs.com/package/@mmstack/primitives).
+
+[![npm version](https://badge.fury.io/js/%40mmstack%2Frouter-core.svg)](https://badge.fury.io/js/%40mmstack%2Frouter-core)
+
+## Installation
+
+```bash
+npm install @mmstack/router-core
+```
+
+## Signal Utilities
+
+This library includes helpers to interact with router state reactively using Angular Signals.
+
+---
+
+### queryParam
+
+Creates a WritableSignal that synchronizes with a specific URL query parameter, enabling two-way binding between the signal's state and the URL.
+
+- Reading the signal returns the parameter's current value (string) or null if absent.
+- Setting the signal to a string updates the URL parameter.
+- Setting the signal to null removes the parameter from the URL.
+- Reacts to external navigation changes affecting the parameter.
+- Supports static or dynamic (function/signal) keys.
+
+```typescript
+@Component({
+  selector: 'app-search-page',
+  standalone: true,
+  imports: [FormsModule],
+  template: `
+    <label>
+      Search:
+      <input [(ngModel)]="searchTerm" placeholder="Enter search term..." />
+    </label>
+    <button (click)="searchTerm.set(null)" [disabled]="!searchTerm()">Clear</button>
+    <p>Current search: {{ searchTerm() ?? 'None' }}</p>
+  `,
+})
+export class SearchPageComponent {
+  // Two-way bind the 'q' query parameter (?q=...)
+  protected readonly searchTerm = queryParam('q');
+
+  constructor() {
+    effect(() => {
+      const currentTerm = this.searchTerm();
+      console.log('Search term changed:', currentTerm);
+      // Trigger API call, update results, etc. based on currentTerm
+    });
+  }
+}
+```
+
+### url
+
+Creates a read-only Signal that tracks the current router URL string.
+
+- Updates after each successful navigation.
+- Reflects the URL after any redirects (urlAfterRedirects).
+- Initializes with the router's current URL synchronously.
+
+```typescript
+import { Component, effect } from '@angular/core';
+import { url } from '@mmstack/router-core';
+
+@Component({
+  selector: 'app-header',
+  standalone: true,
+  template: `<nav>Current Path: {{ currentUrl() }}</nav>`,
+})
+export class HeaderComponent {
+  protected readonly currentUrl = url();
+}
+```
+
+## Preloading Utilities
+
+---
+
+Enhance your application's performance by preloading Angular modules. This library provides a flexible directive and a smart preloading strategy to load modules just before they are needed.
+
+### PreloadStrategy
+
+This is a custom Angular PreloadingStrategy that works in tandem with the mmstack `Link` (via an internal `PreloadService`) to intelligently preload lazy-loaded modules.
+
+**Features**:
+
+- Listens for preload requests triggered by the `Link` directive.
+- Uses advanced path matching to identify the correct route to preload, even with route parameters and matrix parameters.
+- Avoids preloading if the connection is slow (e.g., '2g' effective type) or if the user has data-saving enabled in their browser.
+- Respects a `data: { preload: false }` flag in route configurations to explicitly disable preloading for specific routes.
+- Prevents redundant preloading attempts for the same route path.
+
+To enable this preloading strategy, you need to provide it in your application's main routing configuration.
+
+```typescript
+import { PreloadStrategy } from '@mmstack/router-core';
+import { ApplicationConfig } from '@angular/core';
+import { provideRouter, withPreloading } from '@angular/router';
+import { routes } from './app.routes';
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    //...other providers
+    provideRouter(routes, withPreloading(PreloadStrategy)),
+  ],
+};
+```
+
+### Link (mmLink)
+
+The `Link` directive (used with the `mmLink` attribute) is an enhancement for Angular's standard `RouterLink` directive. It adds the capability to preload the JavaScript modules associated with the linked route, based on user interaction or visibility. Other than the added `preloadOn` input & `preloading` output it directly proxies `RouterLink`.
+
+- `preloadOn`: `input<'hover' | 'visible' | null>()` [default: 'hover'] specifies when to preload, `null` disables preloading
+- `preloading` - `output<void>()` fires when route is registered for preloading (before load)
+
+To use it simply replace any exiting routerLinks that you would like to enable preloading on with the mmLink, you can keep all existing inputs the same. And add the mmstack `PreloadStrategy` in your configuration
+
+```typescript
+import { Link } from '@mmstack/router-core';
+import { RouterLink } from '@angular/router';
+
+@Component({
+  selector: 'app-navigation',
+  standalone: true,
+  imports: [Link, RouterLink],
+  template: `
+    <nav>
+      <!-- preload on hover -->
+      <a [mmLink]="['/features']" preloadOn="hover">Features</a>
+      <!-- preload on visible -->
+      <a [mmLink]="['/pricing']" preloadOn="visible">Pricing</a>
+      <!-- no preload -->
+      <a [mmLink]="['/contact']" [preloadOn]="null">Contact</a>
+      <!-- preload on hover -->
+      <a [mmLink]="['/about']">About</a>
+      <!-- no preload, or just use [preloadOn]="null" -->
+      <a [routerLink]="['/terms']">Terms & Conditions</a>
+    </nav>
+  `,
+})
+export class NavigationComponent {}
+```
+
+## Headless breadcrumb utilities
+
+This library includes a signal-based, headless toolkit for generating and managing breadcrumbs in your Angular application. It provides the logic to derive breadcrumb data from your routes, allowing you to easily build a completely custom breadcrumb UI component & let the library worry about active routes :)
+
+### Consuming breadcrumbs
+
+The primary way to access the breadcrumb data is via the `injectBreadcrumbs` function. It returns a `Signal<Breadcrumb[]>` that updates automatically as navigation changes. Each `Breadcrumb` object in the array contains reactive signals for its `label`, `link`, `ariaLabel`, and a static id for iteration purposes.
+
+```typescript
+import { Component } from '@angular/core';
+import { injectBreadcrumbs } from '@mmstack/router-core'; // Adjust path if needed
+
+@Component({
+  selector: 'app-breadcrumbs',
+  standalone: true,
+  template: `
+    <nav aria-label="breadcrumb">
+      <ol>
+        @for (crumb of breadcrumbs(); track crumb.id) {
+          <li>
+            <a [href]="crumb.link()" [attr.aria-label]="crumb.ariaLabel()">{{ crumb.label() }}</a>
+          </li>
+        }
+      </ol>
+    </nav>
+  `,
+})
+export class CustomBreadcrumbsComponent {
+  protected readonly breadcrumbs = injectBreadcrumbs();
+}
+```
+
+### Registering custom breadcrumbs
+
+For routes where automatic breadcrumb generation isn't sufficient or when you need more control, you can manually define breadcrumbs using the `createBreadcrumb` route resolver.
+
+This function allows you to specify the label (static or dynamic via a function) and other properties for a breadcrumb associated with a particular route.
+You can use injection in the factory function, as you would with any resolver, making translations or subscribing to dynamic data a breaze! :)
+
+```typescript
+import { Routes } from '@angular/router';
+import { createBreadcrumb } from '@mmstack/router-core';
+import { HomeComponent } from './home.component';
+import { UserProfileComponent } from './user-profile.component';
+import { UserStore } from './user.store';
+import { inject } from '@angular/core';
+import { AdminComponent } from './admin.component';
+
+export const appRoutes: Routes = [
+  {
+    path: 'home',
+    component: HomeComponent,
+    resolve: {
+      // Simple static breadcrumb
+      breadcrumb: createBreadcrumb(() => ({
+        label: 'Home',
+      })),
+    },
+  },
+  {
+    path: 'admin',
+    component: AdminComponent,
+    data: {
+      skipBreadcrumb: true, // opt out of auto-generation for this specific route
+    },
+  },
+  {
+    path: 'users/:userId',
+    component: UserProfileComponent,
+    resolve: {
+      breadcrumb: createBreadcrumb(() => {
+        const userStore = inject(UserStore);
+        return {
+          label: () => `Profile: ${userStore.currentUser().name}` ?? 'Loading...',
+          ariaLabel: () => `View profile for ${userStore.currentUser().name ?? 'user'}`,
+        };
+      }),
+    },
+  },
+];
+```
+
+### Configuration [optional]
+
+The breadcrumb system can be configured globally using `provideBreadcrumbConfig`. This allows you to, for example, set the system to 'manual' mode (disabling all automatic generation) or provide a custom function for generating breadcrumb labels.
+
+```typescript
+import { provideRouter } from '@angular/router';
+import { provideBreadcrumbConfig, BreadcrumbConfig, ResolvedLeafRoute } from '@mmstack/router-core'; // Adjust path
+import { appRoutes } from './app.routes';
+import { ApplicationConfig } from '@angular/core';
+
+// Example: Custom label generation strategy
+const customLabelStrategy = () => {
+  // you can inject root injectable services/stores here.
+  return (leaf: ResolvedLeafRoute): string => {
+    return leaf.route.data?.['navTitle'] || leaf.route.title || 'Default Title';
+  };
+};
+export const appConfig: ApplicationConfig = {
+  providers: [
+    // ...rest
+    provideBreadcrumbConfig({
+      // generation: 'manual' // When set to 'manual' the system only uses explicitly defined breadcrumbs
+      generation: customLabelStrategy, // Or provide a custom generation function
+    }),
+  ],
+};
+```
+
+## Title utilities
+
+This library provides a helper function, `createTitle`, to set the document title dynamically from within your route configuration. It integrates seamlessly with Angular's built-in `title` property on routes, allowing for both static and signal-based reactive titles.
+
+By default, the system will use a title defined on a route's `data` or `title` property. createTitle enhances this by allowing titles to be derived from reactive state.
+
+### Using `createTitle`
+
+The `createTitle` function is a route resolver that returns a title string. You use it directly in the `title` property of a route definition. It can accept a function that returns a static string or a function that returns a dynamic string (which will be converted to a `signal`).
+
+```typescript
+import { Routes } from '@angular/router';
+import { createTitle } from '@mmstack/router-core';
+import { inject } from '@angular/core';
+import { ProductStore } from './product.store';
+
+export const appRoutes: Routes = [
+  {
+    path: 'about',
+    // Example 1: Static title
+    resolve: {
+      title: createTitle(() => 'About Us'), // static
+    },
+    loadComponent: () => import('./about.component').then((m) => m.AboutComponent),
+  },
+  {
+    path: 'products/:id',
+    // Example 2: Dynamic, signal-based title from a store
+    resolve: {
+      title: createTitle(() => {
+        const productStore = inject(ProductStore);
+        // The inner function creates a computed signal under the hood
+        return () => `Product: ${productStore.product().name ?? 'Loading...'}`;
+      }),
+    },
+    loadComponent: () => import('./product-detail.component').then((m) => m.ProductComponent),
+  },
+];
+```
+
+### Configuration [optional]
+
+You can provide a global configuration to prepend or append text to all titles using provideTitleConfig.
+
+```typescript
+import { provideRouter } from '@angular/router';
+import { provideTitleConfig } from '@mmstack/router-core';
+import { appRoutes } from './app.routes';
+import { ApplicationConfig } from '@angular/core';
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    provideRouter(appRoutes),
+    provideTitleConfig({
+      // Prefix can be a static string...
+      // prefix: 'My Awesome App | '
+
+      // ...or a function for more control over the format
+      prefix: (title) => (title ? `${title} - MyApp` : 'MyApp'),
+    }),
+  ],
+};
+```