@ngrdt/router 0.0.97 → 0.0.99

package/package.json

@@ -1,24 +1,24 @@
 {
   "name": "@ngrdt/router",
-  "version": "0.0.97",
+  "version": "0.0.99",
   "peerDependencies": {
-    "@angular/common": ">=20.0.0",
-    "@angular/core": ">=20.0.0",
-    "@angular/router": ">=20.0.0",
+    "@angular/common": ">=21.0.0",
+    "@angular/core": ">=21.0.0",
+    "@angular/router": ">=21.0.0",
     "rxjs": ">=7.0.0",
-    "@ngrdt/utils": "^0.0.97",
-    "@ngrdt/core": "^0.0.97",
-    "@ngrdt/button": "^0.0.97"
+    "@ngrdt/utils": "^0.0.99",
+    "@ngrdt/core": "^0.0.99",
+    "@ngrdt/button": "^0.0.99"
   },
   "sideEffects": false,
   "module": "fesm2022/ngrdt-router.mjs",
-  "typings": "index.d.ts",
+  "typings": "types/ngrdt-router.d.ts",
   "exports": {
     "./package.json": {
       "default": "./package.json"
     },
     ".": {
-      "types": "./index.d.ts",
+      "types": "./types/ngrdt-router.d.ts",
       "default": "./fesm2022/ngrdt-router.mjs"
     }
   },

package/{index.d.ts → types/ngrdt-router.d.ts}

@@ -4,7 +4,20 @@ import * as i1 from '@angular/router';
 import { LoadChildrenCallback, Route, ResolveFn, CanActivateFn, CanDeactivateFn, CanActivateChildFn, RunGuardsAndResolvers, Data, Params, NavigationEnd, IsActiveMatchOptions, Router } from '@angular/router';
 import * as _ngrdt_router from '@ngrdt/router';
 import { Observable } from 'rxjs';
+import { RdtGuardedContainer } from '@ngrdt/core';
 
+/**
+ * Bridges an `RdtRoute` to Angular's `Route` config.
+ * Obtained via `RdtRoute.toAngularRoute()`. Use the fluent API to attach
+ * components, guards, resolvers, and providers, then call `build()` to produce
+ * the Angular `Route` object.
+ *
+ * `build()` validates that children defined on the `RdtRoute` match the children
+ * passed via `withChildren()` — a mismatch throws at startup, catching misconfiguration early.
+ *
+ * When a route has both a component and children, `build()` automatically restructures
+ * the output into Angular's required wrapper format (parent with empty-path child for the component).
+ */
 declare class RdtAngularRoute<T extends object> {
     private route;
     private children;
@@ -103,6 +116,22 @@ declare class RdtRouteBase<T extends object> {
     get children(): RdtRoute<any>[];
 }
 
+/**
+ * Fluent builder for creating `RdtRoute` instances.
+ * Routes are defined once in a central file and referenced everywhere by object, eliminating string-based path typos.
+ *
+ * @example
+ * ```ts
+ * const USER_DETAIL = new RdtRouteBuilder<{ userId: number }>()
+ *   .withName('User Detail')
+ *   .withPath(':userId')
+ *   .withParam('userId', 'number')
+ *   .withCanBeEntered((route, params) => params.params.userId !== 0)
+ *   .build();
+ * ```
+ *
+ * @typeParam T - Shape of the route's parameters. Enforced at compile time when navigating or creating URLs.
+ */
 declare class RdtRouteBuilder<T extends object = any> extends RdtRouteBase<T> {
     get canBeEntered(): RdtCanBeEnteredFn<T>;
     get orderedParams(): string[];
@@ -150,14 +179,14 @@ declare class RdtRouteBuilder<T extends object = any> extends RdtRouteBase<T> {
     setData(data: Data): this;
     /**
      * Defines parameter type and lets framework parse it.
-     * @param paramName
-     * @param type
+     * @param paramName Name of the parameter in the path.
+     * @param type 'string', 'number', or an array of allowed string values (enum).
      */
-    withParam(paramName: keyof T, type: 'string' | 'number'): this;
+    withParam(paramName: keyof T, type: 'string' | 'number' | string[]): this;
     /**
      * @deprecated Use withParam() instead.
      */
-    setParam(paramName: keyof T, type: 'string' | 'number'): this;
+    setParam(paramName: keyof T, type: 'string' | 'number' | string[]): this;
     /**
      * Sets name to display in breadcrumb, etc.
      */
@@ -177,6 +206,19 @@ declare class RdtRouteBuilder<T extends object = any> extends RdtRouteBase<T> {
     build(): RdtRoute<T>;
 }
 
+/**
+ * Immutable, type-safe route definition. Created via `RdtRouteBuilder.build()`.
+ *
+ * Each instance represents a single route in the hierarchy and holds its path pattern,
+ * parameter types, parent reference, and access guard. Use `withStaticParams()`,
+ * `withQueryParams()`, or `withStateParams()` to create derived instances with
+ * pre-filled values (the original is never mutated).
+ *
+ * To bridge to Angular's router, call `toAngularRoute()` to get an `RdtAngularRoute`
+ * builder that produces an Angular `Route` config object.
+ *
+ * @typeParam T - Shape of this route's own parameters.
+ */
 declare class RdtRoute<T extends object = any> extends RdtRouteBase<T> {
     private _absoluteRegex?;
     protected _staticParams: Partial<T>;
@@ -264,23 +306,49 @@ declare class RdtRoute<T extends object = any> extends RdtRouteBase<T> {
      * this route and its parents (NOT children).
      */
     clone(): RdtRoute<T>;
+    private static getGroup;
     private setRegex;
     static fromBuilder<T extends object>(builder: RdtRouteBuilder<T>): RdtRoute<T>;
     private static readonly groups;
 }
 
+/**
+ * Defines how a route parameter is matched and parsed.
+ * - `'string'` — matches any non-slash character (`[^/]+`), value is URI-decoded.
+ * - `'number'` — matches digits only (`\d+`), value is parsed to a number.
+ * - `string[]` — enum: matches only the listed values exactly. Invalid values are rejected at both URL creation and parsing time.
+ */
+type ParamType = 'string' | 'number' | string[];
 type ParamTypeMap<T> = {
-    [key in keyof T]?: 'string' | 'number';
+    [key in keyof T]?: ParamType;
 };
+/**
+ * Maps between a database/model field name and the URL parameter name.
+ * Used with `RdtRoute.withParamMappings()` when the URL param (e.g. `:id`)
+ * differs from the property name on the data object (e.g. `userId`).
+ */
 interface ParamMapping {
+    /** Parameter name as it appears in the URL path (e.g. `'id'` for `:id`). */
     urlName: string;
+    /** Property name on the data object (e.g. `'userId'`). */
     tableName: string;
 }
 interface StaticRouteParams {
     [absolutePath: string]: object;
 }
 type RdtRedirectReturnType = string | void | undefined;
+/**
+ * Function invoked when a route's `canBeEntered` guard returns false.
+ * Return a URL string to redirect to, or `undefined` to block navigation without redirect.
+ * Runs in injection context — you can call `inject()` inside.
+ */
 type RdtRedirectFn = (currentPath: string, targetPath: string, targetRoute: RdtRoute) => RdtRedirectReturnType;
+/**
+ * Type-safe container for route parameters keyed by route instance.
+ * Stores params for multiple routes in a hierarchy (e.g. parent + child params from a single URL).
+ * Parameters are keyed internally by absolute path, so two different `RdtRoute` instances
+ * with the same path share the same slot.
+ */
 declare class RdtParameters {
     private params;
     constructor(params?: StaticRouteParams);
@@ -291,11 +359,26 @@ declare class RdtParameters {
     [Symbol.iterator](): Generator<(string | object)[], void, unknown>;
 }
 type LoadComponentCallback = Route['loadComponent'];
+/**
+ * Synchronous guard function that determines whether a route can be entered.
+ * Used by `[rdtRouterLink]` and `RdtMenu` to hide/disable links, and by the
+ * built-in `canActivate` guard to block navigation.
+ * Runs in injection context when an `Injector` is available — you can call `inject()` inside.
+ *
+ * The entire parent chain is evaluated: if any ancestor's guard returns `false`, the route is blocked.
+ */
 type RdtCanBeEnteredFn<T extends object> = (route: RdtRoute<T>, params: RdtCombinedRouteParams<T>) => boolean;
+/**
+ * Combined parameters available to guard functions and URL parsing results.
+ */
 interface RdtCombinedRouteParams<T extends object> {
+    /** Parameters extracted for the specific route being evaluated. */
     params: Partial<T>;
+    /** Parameters for all routes in the hierarchy (parent + child), keyed by route. */
     route: RdtParameters;
+    /** Query string parameters. */
     query: Params;
+    /** `history.state` parameters. */
     state: Params;
 }
 
@@ -305,20 +388,25 @@ interface RdtCombinedRouteParams<T extends object> {
  */
 declare const RDT_CANNOT_BE_ENTERED_PROVIDER: InjectionToken<RdtRedirectFn | RdtRedirectReturnType>;
 
-declare const RDT_CONFIRM_DATA_LOSS_SERVICE: InjectionToken<RdtConfirmDataLossService>;
-declare abstract class RdtConfirmDataLossService {
-    abstract confirmDataLoss(): Observable<boolean>;
-}
-declare class RdtConfirmDataLossServiceAlert extends RdtConfirmDataLossService {
-    confirmDataLoss(): Observable<boolean>;
-}
-
+/**
+ * Additional options for `RdtRouterService.navigate()`.
+ * These take priority over any params set on the route via `withQueryParams()` / `withStateParams()`.
+ */
 interface RdtNavigateExtras {
+    /** Data passed via `history.state`. */
     state?: Params;
+    /** Query string parameters appended to the URL. */
     query?: Params;
+    /** Window target. Use `'_blank'` to open in a new tab. Defaults to `'_self'`. */
     target?: '_blank' | '_self' | '_parent' | '_top';
+    /** Replace the current history entry instead of pushing a new one. */
     replaceUrl?: boolean;
 }
+/**
+ * Central navigation service for type-safe routing.
+ * Wraps Angular's `Router` with `RdtRoute`-based navigation, URL parsing, and history tracking.
+ * Requires `RDT_ROUTES_PROVIDER` to be configured with all application routes.
+ */
 declare class RdtRouterService {
     readonly allRoutes: RdtRoute<any>[] | null;
     readonly baseHref: string;
@@ -370,7 +458,29 @@ declare class RdtRouterService {
     static ɵprov: i0.ɵɵInjectableDeclaration<RdtRouterService>;
 }
 
+/**
+ * Injection token holding all application routes as a flat array.
+ * Used internally by `RdtRouterService` to match URLs and enable type-safe navigation.
+ * Prefer using `provideRdtRoutes()` instead of providing this token directly.
+ */
 declare const RDT_ROUTES_PROVIDER: InjectionToken<RdtRoute<any>[]>;
+/**
+ * Provides all application routes to `RdtRouterService`.
+ * Accepts either a route module object (`import * as routes from './routes'`)
+ * or a plain array of `RdtRoute` instances.
+ *
+ * @example
+ * ```ts
+ * import * as ALL_ROUTES from './rdt-routes';
+ *
+ * export const appConfig: ApplicationConfig = {
+ *   providers: [
+ *     provideRdtRoutes(ALL_ROUTES),
+ *   ],
+ * };
+ * ```
+ */
+declare function provideRdtRoutes(routes: Record<string, unknown> | RdtRoute[]): EnvironmentProviders;
 
 declare enum RdtNavigationSource {
     BREADCRUMB = "breadcrumb"
@@ -447,6 +557,15 @@ declare class RdtRouterLinkDirective<T extends object> {
     static ɵdir: i0.ɵɵDirectiveDeclaration<RdtRouterLinkDirective<any>, "[rdtRouterLink]", never, { "routeInput": { "alias": "rdtRouterLink"; "required": true; "isSignal": true; }; "target": { "alias": "target"; "required": false; "isSignal": true; }; "params": { "alias": "params"; "required": false; "isSignal": true; }; "queryParams": { "alias": "queryParams"; "required": false; "isSignal": true; }; "stateParams": { "alias": "stateParams"; "required": false; "isSignal": true; }; "disabled": { "alias": "rdtDisabled"; "required": false; "isSignal": true; }; }, {}, never, never, true, [{ directive: typeof i1.RouterLink; inputs: { "target": "target"; "replaceUrl": "replaceUrl"; }; outputs: {}; }]>;
 }
 
+/**
+ * Ensures that `preventDataLossGuardFn` is applied to every route at runtime,
+ * even if it was not explicitly added in the route definition.
+ * Call `ensureGlobalGuards()` once during app initialization.
+ *
+ * Also patches the browser back button behavior: replaces the URL back to the
+ * previous value during guard checks so the address bar doesn't flash the new URL
+ * before the guard potentially rejects it.
+ */
 declare class GlobalRouteGuardService {
     private router;
     constructor(router: Router);
@@ -456,7 +575,12 @@ declare class GlobalRouteGuardService {
     static ɵprov: i0.ɵɵInjectableDeclaration<GlobalRouteGuardService>;
 }
 
-declare const preventDataLossGuardFn: CanDeactivateFn<any>;
+/**
+ * `CanDeactivate` guard that blocks navigation when there are unsaved changes.
+ * The routed component must implement `RdtGuardedContainer` from `@ngrdt/core`.
+ * Add to routes via `RdtAngularRoute.addCanDeactivate(preventDataLossGuardFn)`.
+ */
+declare const preventDataLossGuardFn: CanDeactivateFn<RdtGuardedContainer>;
 
-export { GlobalRouteGuardService, PERMISSION_DISABLED_KEY, RDT_CANNOT_BE_ENTERED_PROVIDER, RDT_CONFIRM_DATA_LOSS_SERVICE, RDT_ROUTES_PROVIDER, RdtAngularRoute, RdtAnyRouteActiveDirective, RdtBackLinkDirective, RdtConfirmDataLossService, RdtConfirmDataLossServiceAlert, RdtNavigationSource, RdtParameters, RdtRoute, RdtRouteBuilder, RdtRouterLinkDirective, RdtRouterService, preventDataLossGuardFn };
+export { GlobalRouteGuardService, PERMISSION_DISABLED_KEY, RDT_CANNOT_BE_ENTERED_PROVIDER, RDT_ROUTES_PROVIDER, RdtAngularRoute, RdtAnyRouteActiveDirective, RdtBackLinkDirective, RdtNavigationSource, RdtParameters, RdtRoute, RdtRouteBuilder, RdtRouterLinkDirective, RdtRouterService, preventDataLossGuardFn, provideRdtRoutes };
 export type { RdtCanBeEnteredFn, RdtNavigateExtras };