@ngrdt/router 0.0.98 → 0.1.0

package/package.json

@@ -1,24 +1,24 @@
 {
   "name": "@ngrdt/router",
-  "version": "0.0.98",
+  "version": "0.1.0",
   "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.98",
-    "@ngrdt/core": "^0.0.98",
-    "@ngrdt/button": "^0.0.98"
+    "@ngrdt/utils": "^0.1.0",
+    "@ngrdt/core": "^0.1.0",
+    "@ngrdt/button": "^0.1.0"
   },
   "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}

@@ -1,10 +1,23 @@
 import * as i0 from '@angular/core';
 import { Provider, EnvironmentProviders, Type, Injector, InjectionToken, OnInit, OnChanges, SimpleChanges, DestroyRef } from '@angular/core';
 import * as i1 from '@angular/router';
-import { LoadChildrenCallback, Route, ResolveFn, CanActivateFn, CanDeactivateFn, CanActivateChildFn, RunGuardsAndResolvers, Data, Params, NavigationEnd, IsActiveMatchOptions, Router } from '@angular/router';
+import { LoadChildrenCallback, Route, ResolveFn, CanActivateFn, CanDeactivateFn, CanActivateChildFn, RunGuardsAndResolvers, Data, Params, NavigationEnd, IsActiveMatchOptions } 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,25 +388,31 @@ 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;
     private readonly location;
     private readonly router;
+    private readonly viewStateService;
     private _previousUrl;
     private _currentUrl;
     get previousUrl(): string | null;
@@ -370,7 +459,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,16 +558,29 @@ 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);
+    private readonly router;
     ensureGlobalGuards(): void;
     private ensureCanDeactivateGuards;
     static ɵfac: i0.ɵɵFactoryDeclaration<GlobalRouteGuardService, never>;
     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 };

package/README.md

@@ -1,255 +0,0 @@
-# @ngrdt/router
-
-Main use for this package is to define routes and their parameters in one place in app. It is recommended to define special `routes` module in every app using `@ngrdt/router` where all `RdtRoute` objects are defined using `RdtRouteBuilder`. Individual application modules then import these objects, define Angular routes and provide implementation details such as which component is rendered, state, guards, etc.
-
-This approach ensures that each route is defined exactly once and can be easily edited if necessary. `@ngrdt/router` also provides set of useful tools to help you with common routing tasks.
-
-### Instalation
-
-`npm install @ngrdt/router`
-
-## Basic usage
-
-### Application routes file
-
-Create special `nx` library (not `NgModule`) for instance `@example-app/routes`. In this library you will create file called `routes.ts` and in it individual `RdtRoute` objects like so:
-
-```typescript
-export const DASHBOARD_ITEM_ROUTE = new RdtRouteBuilder()
-  .setName('Dashboard item')
-  .setPath(':id')
-  .setParam('id', 'number')
-  .build();
-
-export const DASHBOARD_ROUTE = new RdtRouteBuilder()
-  .setName('Dashboard')
-  .setPath('dashboard')
-  .setChildren(DASHBOARD_ITEM_ROUTE)
-  .build();
-
-export const SETTINGS_ROUTE = new RdtRouteBuilder()
-  .setName('Settings')
-  .setPath('settings')
-  .setCanBeEntered(() => 
-    inject(ExampleAppPermissionService).hasPermission('SETTINGS_ACCESS')
-  )
-  .build();
-```
-
-This file should only contain imports to interfaces used by `RdtRouteBuilder` as template parameter. No component, ngModule or guards such as `CanActivateFn` should be imported here. This approach will save you later headache with circular dependency.
-
-`RdtRouterService` needs to be aware of all routes defined therefore you must provide it in your `ApplicationConfig` like so:
-
-```typescript
-import { RDT_ROUTES_PROVIDER, RdtRoute } from '@ngrdt/router';
-import * as ALL_ROUTES_OBJ from './rdt-routes';
-const ALL_ROUTES = Object.values(ALL_ROUTES_OBJ) as RdtRoute[];
-
-export const appConfig: ApplicationConfig = {
-  providers: [
-    {
-      provide: RDT_ROUTES_PROVIDER,
-      useValue: ALL_ROUTES,
-    },
-  ]
-}
-```
-
-### Angular routes files
-
-Now you have to bind `RdtRoute` objects to individual modules, components, states, effects, guards and other implementation details. Instead of defining routes directly you import `RdtRoute` from `@example-app/routes` and then define `routes.ts` like so:
-
-```typescript
-export const routes: Route[] = [
-  DASHBOARD_ROUTE.toAngularRoute()
-    .setComponent(DashboardComponent)
-    .setChildren(
-      DASHBOARD_ITEM_ROUTE.toAngularRoute()
-        .setComponent(DashboardItemComponent)
-        .addCanDeactivate(preventDataLossGuardFn)
-        .build()
-    )
-    .build(),
-]
-```
-
-This array is then used as in regular Angular project. Note that child routes must be added as children here as well.
-
-
-### Child routes and parameters
-
-You may nest child routes and also create routes with typed parameters to link them with particular type.
-
-For instance lets say there's a route displaying users which has a child route to display more information about a single user. By providing `User` type to `RdtRouteBuilder` and defining types of parameters we can use `RdtRoute` object to parse path to extract parameters.
-
-```typescript
-interface User {
-  userId: number;
-  name: string;
-}
-
-export const USER_DETAIL_ROUTE = new RdtRouteBuilder<User>()
-  .setName('User detail')
-  .setPath(':userId/:name')
-  .setParam('userId', 'number')
-  .setParam('name', 'string')
-  .build();
-
-export const USER_LIST_ROUTE = new RdtRouteBuilder()
-  .setName('Users')
-  .setPath('users')
-  .setChildren(USER_DETAIL_ROUTE)
-  .build();
-```
-
-Then we navigate to user detail like so:
-
-```typescript
-const params: Partial<User> = {
-  userId: 123,
-  name: 'Josef',
-};
-
-inject(RdtRouterService).navigate(USER_DETAIL_ROUTE, params);
-```
-
-`RdtRouterService` is aware of the type so you can use it to parse absolute path into `User` object. Route knows `userId` is `number` so it will parse it. If parameter is missing or is of wrong type, then `parseAbsoluteUrl` returns `null`. Return value is a wrapper object with `get(route: RdtRoute)` method to get parsed parameters of given route or its parents.
-
-
-```typescript
-const user: User = USER_DETAIL_ROUTE
-  .parse('/users/123/Josef')
-  .get(USER_DETAIL_ROUTE);
-```
-
-### More parameter examples
-
-#### Static parameters
-
-Imagine your app contains list of users and each user has set of tasks. The routes are defined as follows:
-
-```typescript
-interface User {
-  userId: number,
-  name: string,
-  address: string,
-  tasks: Task[]
-}
-
-interface Task {
-  taskId: number,
-  description: string
-}
-
-
-export const TASK_DETAIL_ROUTE = new RdtRouteBuilder<Task>()
-  .setName('Task detail')
-  .setPath('task/:taskId')
-  .setParam('taskId', 'number')
-  .build();
-
-export const USER_DETAIL_ROUTE = new RdtRouteBuilder<User>()
-  .setName('User detail')
-  .setPath(':userId')
-  .setParam('userId', 'number')
-  .setChildren(TASK_DETAIL_ROUTE)
-  .build();
-
-export const USER_LIST_ROUTE = new RdtRouteBuilder()
-  .setName('Users')
-  .setPath('user')
-  .setChildren(USER_DETAIL_ROUTE)
-  .build();
-```
-
-This translates into path `/user/:userId/task/:taskId` for task detail route.
-
-Now inside `UserDetailComponent` there's a for loop rendering individual tasks and you want to have links to them. You cannot use directly:
-
-```html
-<button [rdtRouterLink]="TASK_DETAIL_ROUTE" [params]="task"></button>
-```
-Because task does not specify `userId`. For this you must provide static parameters for every parent route - `User` for `USER_DETAIL_ROUTE` in this case:
-
-```typescript
-@Input()
-user!: User;
-
-taskRoute!: RdtRoute<Task>;
-
-ngOnInit() {
-  this.taskRoute = TASK_DETAIL_ROUTE.withStaticParams(USER_DETAIL_ROUTE, this.user);
-}
-```
-Method `withStaticParams()` returns clone of `TASK_DETAIL_ROUTE` and all of its parent routes while fixing parameters. You can chain calling `withStaticParams` with itself or other method calls.
-
-```html
-<button [rdtRouterLink]="taskRoute" [params]="task"></button>
-```
-
-## Ecosystem
-
-### RdtRouterLink
-
-`RdtRouterLink` is equivalent of `RouterLink` in Angular. It supports basically the same functionality, but adds type safety. `RdtRouterLink` will be disabled if `canBeEntered` of its route returns `false`.
-
-```typescript
-readonly userRoute = USER_DETAIL_ROUTE;
-readonly user$ = inject(UserService).getUser$();
-```
-
-```html
-<button 
-  [rdtRouterLink]="userRoute" 
-  [params]="user$ | async"
-  target="_blank">
-Link to user
-</button>
-```
-
-### RdtMenu
-
-`RdtRoute` can be passed directly into `RdtMenuItem`. If `canBeEntered` returns `false`, then the item won't be visible. This is useful to hide items user has no permission for.
-
-Method `withStaticParams` lets us provide parameters for given `RdtRoute`, because `RdtMenuItem` does not accept route parameters.
-
-```typescript
-public getMenuItems(): RdtMenuItem[] {
-  const user: Partial<User> = {
-    userId: 123,
-    name: 'Josef'
-  };
-
-  return [
-    {
-      label: 'All users',
-      routerLink: USER_LIST_ROUTE
-    },
-    {
-      label: 'Josef',
-      routerLink: USER_DETAIL_ROUTE.withStaticParams(user)
-    }
-  ];
-}
-```
-
-### RdtAngularRoute
-
-`RdtAngularRoute` is a container class for `RdtRoute` which functionally does two things: verifies that routes were defined correctly and enables you to provide guards, effects, component or module. Don't forget to call `build()` for it to generate Angular `Route`.
-
-### RdtRouterService
-
-`RdtRouterService` has similar features as Angular `Router`.
-
-#### `parseAbsoluteUrl()`
-Method will parse absolute path, recognize `RdtRoute` and parse its parameters. If no parameter is provided, then window location is used.
-
-#### `navigateBack()`
-
-Will push parent route to navigation stack. Function works anywhere in the app unlike similar Angular-based solution using `ActivatedRoute`.
-
-Hitting native browser back button will take you back forward. In case you want true back function, use `inject(Location).back()` which removes from navigation stack, but can potentially take you outside of the app or close browser window.
-
-#### `previousUrl` and `currentUrl`
-
-Cached sync values of previous and current path values. For example `/dashboard` or `/user/123/task/xyz`.