@loozo/angular-router 0.0.7 → 0.0.9

package/types/loozo-angular-router-_generated.d.ts

@@ -1,5 +1,5 @@
-import { ActivatedRouteSnapshot, PartialMatchRouteSnapshot, RedirectFunction, Route, UrlTree } from "@angular/router";
-import { AnyRoute, ParamsOf, SearchOf, UrlValues } from "@loozo/angular-router/_core";
+import { ActivatedRoute, ActivatedRouteSnapshot, NavigationBehaviorOptions, PartialMatchRouteSnapshot, RedirectFunction, Route, Router, UrlTree } from "@angular/router";
+import { AnyRoute, FragmentsOf, ParamsOf, PathUrlValues, PathlessUrlValues, SearchFieldOf, SearchOf, TitleOf, UrlValues } from "@loozo/angular-router/_core";
 import { Signal } from "@angular/core";
 interface RecordBinding {
   readonly definition: () => AnyRoute;
@@ -23,6 +23,8 @@ interface Job {
     parse(raw: string): unknown;
   };
 }
+/** The generated declaration identity carried as the record's own route data, if any. */
+declare function routeIdentity(snapshot: Pick<ActivatedRouteSnapshot, "routeConfig">): unknown;
 declare function hasIdentity(snapshot: Pick<ActivatedRouteSnapshot, "routeConfig">, id: string): boolean;
 export declare function assertIdentity(snapshot: Pick<ActivatedRouteSnapshot, "routeConfig">, id: string): void;
 declare function validateRaw(key: string, raws: readonly unknown[], array: boolean): asserts raws is readonly string[];
@@ -34,6 +36,7 @@ declare function runPathJobs(jobs: readonly Job[]): Readonly<Record<string, unkn
 /**
  * Parses a declaration's effective search. It never fails on input: a missing,
  * repeated or invalid value reads as the key's fallback, or leaves it absent.
+ * An array key reads every value, or `[]` when it is missing or any value is invalid.
  */
 declare function parseSearch(definition: AnyRoute, snapshot: Pick<ActivatedRouteSnapshot, "queryParamMap">): Readonly<Record<string, unknown>>;
 /** The effective inputs of a complete snapshot, shared by guards, resolvers and handles. */
@@ -57,12 +60,39 @@ declare function pathInputs(set: RouteSet, id: string, snapshot: PartialMatchRou
 declare function matchingInputs(set: RouteSet, id: string, snapshot: PartialMatchRouteSnapshot): Parsed | undefined;
 export declare function callbacks(set: RouteSet, id: string): Pick<Route, "canActivate" | "canActivateChild" | "canMatch" | "resolve" | "title">;
 export declare function redirect(definition: () => AnyRoute): RedirectFunction;
+/**
+ * One reader of the deepest active primary-outlet route of the set.
+ *
+ * @remarks
+ * The selection changes only after a navigation commits: the computed tracks
+ * `lastSuccessfulNavigation`, and a reader first read before its tree has committed
+ * returns undefined until the running navigation ends. The reader reads itself at each
+ * `NavigationEnd`, so it reconciles every commit even without a live consumer. It owns
+ * one entry per active ActivatedRoute, reused while that record stays in the chain;
+ * departed entries are released at the commit and keep their last values. Destroying
+ * the injection context releases the rest; the reader then keeps its last selection.
+ */
+export declare function injectGeneratedActiveRoute<Active>(set: RouteSet): Signal<Active | undefined>;
+interface RouteView {
+  readonly params: Signal<Readonly<Record<string, unknown>>>;
+  readonly search: Signal<Readonly<Record<string, unknown>>>;
+  readonly data: Signal<Readonly<Record<PropertyKey, unknown>>>;
+  readonly title: Signal<string | undefined>;
+}
+/**
+ * Signals of the route's committed snapshot. Angular replaces ActivatedRoute.snapshot
+ * only when a navigation activates, so a pending, cancelled or failed navigation
+ * leaves the values alone; params, search, data and title change together, from one snapshot.
+ * The caller owns the lifetime: `teardown` receives the function that stops following
+ * the route, after which the signals keep their last values.
+ */
+declare function observeRoute(set: RouteSet, id: string, activated: ActivatedRoute, router: Router, teardown: (release: () => void) => void): RouteView;
 declare const destinationBrand: unique symbol;
 /**
  * An inert nominal reference exported as `destination` by a route-local facade.
  *
  * @remarks
- * Use the exported object with a handle's link/navigate methods; no injection
+ * Pass the exported object as `to` in a handle's link/navigate record; no injection
  * context or target activation is needed. It selects its exact declaration,
  * not a canonical pathless winner. Only references from the caller's generated
  * set are accepted. Copies, spreads, fakes and authored routes are not references.
@@ -85,32 +115,53 @@ export declare class Destination<Target extends AnyRoute, Set = unknown, Id exte
   };
 }
 export declare function createDestination<Target extends AnyRoute, Set, Id extends string>(getSet: () => RouteSet, id: Id): Destination<Target, Set, Id>;
+/** The declaration a genuine destination of this set references. */
+export declare function destinationId(set: RouteSet, destination: unknown): string;
 type DataOf<Target> = Target extends {
   readonly __data?: infer Data;
 } ? Readonly<Data> : never;
 type IsUnion<Value, Whole = Value> = Value extends unknown ? [Whole] extends [Value] ? false : true : never;
+interface PathlessOwnLink<Search, Fragment> extends PathlessUrlValues<Search, Fragment> {
+  /** Omitted: this exact declaration, not its pathless winner. */
+  readonly to?: undefined;
+}
+interface PathOwnLink<Params, Search, Fragment> extends PathUrlValues<Params, Search, Fragment> {
+  /** Omitted: this exact declaration, not its pathless winner. */
+  readonly to?: undefined;
+}
+interface PathlessOwnNavigation<Search, Fragment> extends PathlessOwnLink<Search, Fragment>, NavigationBehaviorOptions {}
+interface PathOwnNavigation<Params, Search, Fragment> extends PathOwnLink<Params, Search, Fragment>, NavigationBehaviorOptions {}
+type OwnLink<Target extends AnyRoute, Keys extends keyof SearchOf<Target>> = keyof ParamsOf<Target> extends never ? PathlessOwnLink<SearchFieldOf<Target, Keys>, FragmentsOf<Target>> : PathOwnLink<ParamsOf<Target>, SearchFieldOf<Target, Keys>, FragmentsOf<Target>>;
+type OwnNavigation<Target extends AnyRoute, Keys extends keyof SearchOf<Target>> = keyof ParamsOf<Target> extends never ? PathlessOwnNavigation<SearchFieldOf<Target, Keys>, FragmentsOf<Target>> : PathOwnNavigation<ParamsOf<Target>, SearchFieldOf<Target, Keys>, FragmentsOf<Target>>;
 /**
  * The noncallable typed handle returned by a colocated `injectRoute()` facade.
  *
  * @remarks
  * Obtain it in an Angular injection context for the exact generated activated
  * record. Params, search and data are readonly Angular Signals of the route's
- * committed snapshot, with values from the first read. Data contains only local
- * resolver results, not static/ancestor data or title.
+ * committed snapshot, with values from the first read. Data holds the resolver
+ * results of the route's whole chain, ancestors first, a nearer key hiding an
+ * ancestor's key of the same name; native static data and the title stay out.
+ * Title is the resolved title of the nearest route in the chain that declares
+ * one: `string` when the route or an ancestor declares it, else `undefined`.
  *
  * While a navigation is pending, the signals keep the current snapshot's values;
- * when a navigation commits a new snapshot for this route, all three change
+ * when a navigation commits a new snapshot for this route, they change
  * together. Cancellation, failure or a same-URL skip leaves them unchanged. For
  * pending-navigation UI, read Angular's `Router.currentNavigation()`. There is no
  * resolved-data cache. Reading params or search throws only when a path codec
  * rejects a value it accepted while matching, a programming error.
  *
- * Selectors are single known authored literals, not concrete URLs or string
- * unions. `.` is exact-current; `..` selects the parent route: the nearest
- * ancestor with a shorter path, or the root for a top-level route. It and
- * absolute selectors use generated canonical targets. Every call supplies all
- * target values; there is no current-value reuse, extras argument or implicit
- * query merge.
+ * `link` and `navigate` take one target record. Its `to` selects the
+ * destination: omitted for this exact declaration, not its pathless winner; a
+ * single known absolute authored literal, never a concrete URL or string union;
+ * `..` for the parent route, the nearest ancestor with a shorter path or the
+ * root for a top-level route; or a same-set generated destination. Literal and
+ * `..` selectors use generated canonical targets. `params`, `search` and
+ * `fragment` are the destination's complete explicit values; there is no
+ * current-value reuse or implicit query merge. For `navigate`, the record's
+ * other keys are Angular's `NavigationBehaviorOptions`, passed to
+ * `Router.navigateByUrl` as given; `link` takes none, so set them on RouterLink.
  *
  * @typeParam Target - The bound declaration's schema.
  * @typeParam Absolute - Absolute literal selectors and their target schemas.
@@ -124,8 +175,9 @@ type IsUnion<Value, Whole = Value> = Value extends unknown ? [Whole] extends [Va
  * import { destination as report } from "../report/route.generated.js";
  *
  * const route = injectRoute(); // Inside an Angular injection context.
- * const link = route.link(report, { params: { reportId: 42 } });
- * // Bind link to Angular RouterLink, or call route.navigate with the same values.
+ * const link = route.link({ to: report, params: { reportId: 42 } });
+ * // Bind link to Angular RouterLink, or navigate with the same record and behavior options:
+ * void route.navigate({ to: report, params: { reportId: 42 }, replaceUrl: true });
  * ```
  */
 export interface Handle<Target extends AnyRoute, Absolute extends Record<string, AnyRoute> = {}, Parent extends AnyRoute = never, Set = unknown, References extends Record<string, AnyRoute> = {}> {
@@ -133,97 +185,95 @@ export interface Handle<Target extends AnyRoute, Absolute extends Record<string,
   readonly params: Signal<Readonly<ParamsOf<Target>>>;
   /** Effective declared search, from the same snapshot as params; absent keys have no value or fallback. */
   readonly search: Signal<Readonly<SearchOf<Target>>>;
-  /** Own native resolver results only, from the same snapshot as params. */
+  /** Effective resolver results of the route and its ancestors, from the same snapshot as params. */
   readonly data: Signal<DataOf<Target>>;
+  /** Resolved title of the nearest route in the chain that declares one, from the same snapshot as params. */
+  readonly title: Signal<TitleOf<Target>>;
   /**
-   * Creates a native UrlTree for this exact declaration without navigating.
+   * Creates a native UrlTree for this exact declaration, not its pathless winner, without navigating.
    *
-   * @param values - Explicit effective params/search and optional own fragment.
+   * @param target - No `to`, and this declaration's explicit params/search and optional own fragment.
    * @returns Router.parseUrl's result, suitable for Angular RouterLink.
-   * @throws Synchronous URL validation, encoding or stringifier failures before Angular.
+   * @throws Synchronous URL validation, encoding or stringifier failures, or a behavior option, before Angular.
    */
-  link<Keys extends keyof SearchOf<Target> = never>(values: UrlValues<Target, Keys>): UrlTree;
-  /**
-   * Creates a UrlTree for the exact bound declaration, not its pathless winner.
-   *
-   * @param selector - The exact-current literal `.`.
-   * @param values - Explicit values for this declaration, with no current-input reuse.
-   * @returns Router.parseUrl's result without navigating.
-   * @throws Synchronous URL validation, encoding or stringifier failures before Angular.
-   */
-  link<Keys extends keyof SearchOf<Target> = never>(selector: ".", values: UrlValues<Target, Keys>): UrlTree;
+  link<Keys extends keyof SearchOf<Target> = never>(target: OwnLink<Target, Keys>): UrlTree;
   /**
    * Creates a UrlTree for a statically admitted absolute authored selector.
    *
-   * @param selector - A single known template literal, never a concrete URL.
-   * @param values - The selected target's complete explicit values.
+   * @param target - `to`, a single known template literal, never a concrete URL, and the selected target's complete explicit values.
    * @returns Router.parseUrl's result without navigating.
-   * @throws Synchronously for unknown selectors or invalid URL values.
+   * @throws Synchronously for unknown selectors, invalid URL values or a behavior option.
    */
-  link<const Selector extends keyof Absolute & string, Keys extends keyof SearchOf<NoInfer<Absolute[Selector]>> = never>(selector: Selector & (IsUnion<Selector> extends true ? never : unknown), values: UrlValues<NoInfer<Absolute[Selector]>, Keys>): UrlTree;
+  link<const Selector extends keyof Absolute & string, Keys extends keyof SearchOf<NoInfer<Absolute[Selector]>> = never>(target: {
+    /** A single known absolute authored selector, never a concrete URL. */
+    readonly to: Selector & (IsUnion<Selector> extends true ? never : unknown);
+  } & UrlValues<NoInfer<Absolute[Selector]>, Keys>): UrlTree;
   /**
    * Creates a UrlTree for the parent route, when the bound declaration has one.
    *
-   * @param selector - The literal `..`.
-   * @param values - The parent route's complete explicit values.
+   * @param target - `to: ".."` and the parent route's complete explicit values.
    * @returns Router.parseUrl's result without navigating.
-   * @throws Synchronously for invalid URL values.
+   * @throws Synchronously for invalid URL values or a behavior option.
    */
-  link<Keys extends keyof SearchOf<Parent> = never>(selector: [Parent] extends [never] ? never : "..", values: UrlValues<Parent, Keys>): UrlTree;
+  link<Keys extends keyof SearchOf<Parent> = never>(target: {
+    /** The parent route: the nearest ancestor with a shorter path, or the root. */
+    readonly to: [Parent] extends [never] ? never : "..";
+  } & UrlValues<Parent, Keys>): UrlTree;
   /**
    * Creates a UrlTree for a generated reference's own exact declaration.
    *
-   * @param selector - A genuine destination exported by a facade in this route set.
-   * @param values - The referenced declaration's complete explicit values.
+   * @param target - `to`, a genuine destination exported by a facade in this route set, and the referenced declaration's complete explicit values.
    * @returns Router.parseUrl's result without navigating.
-   * @throws Synchronously for foreign/fake references or invalid URL values.
+   * @throws Synchronously for foreign/fake references, invalid URL values or a behavior option.
    */
-  link<const Id extends keyof References & string, Keys extends keyof SearchOf<NoInfer<References[Id]>> = never>(selector: Destination<NoInfer<References[Id]>, Set, Id> & (IsUnion<Id> extends true ? never : unknown), values: UrlValues<NoInfer<References[Id]>, Keys>): UrlTree;
+  link<const Id extends keyof References & string, Keys extends keyof SearchOf<NoInfer<References[Id]>> = never>(target: {
+    /** A genuine destination exported by a facade in this route set. */
+    readonly to: Destination<NoInfer<References[Id]>, Set, Id> & (IsUnion<Id> extends true ? never : unknown);
+  } & UrlValues<NoInfer<References[Id]>, Keys>): UrlTree;
   /**
-   * Navigates to this exact declaration via Router.navigateByUrl.
+   * Navigates to this exact declaration, not its pathless winner, via Router.navigateByUrl.
    *
-   * @param values - Explicit effective params/search and optional own fragment.
+   * @param target - No `to`; this declaration's explicit params/search and optional own fragment; and Angular's navigation behavior options.
    * @returns Angular's identical Promise; Angular owns skips, redirects and failures.
    * @throws Synchronous URL validation, encoding or stringifier failures before Angular.
    */
-  navigate<Keys extends keyof SearchOf<Target> = never>(values: UrlValues<Target, Keys>): Promise<boolean>;
-  /**
-   * Navigates to the exact bound declaration, not its pathless winner.
-   *
-   * @param selector - The exact-current literal `.`.
-   * @param values - Explicit values for this declaration, with no current-input reuse.
-   * @returns Angular's identical Router.navigateByUrl Promise.
-   * @throws Synchronous URL validation, encoding or stringifier failures before Angular.
-   */
-  navigate<Keys extends keyof SearchOf<Target> = never>(selector: ".", values: UrlValues<Target, Keys>): Promise<boolean>;
+  navigate<Keys extends keyof SearchOf<Target> = never>(target: OwnNavigation<Target, Keys>): Promise<boolean>;
   /**
    * Navigates to a statically admitted absolute authored selector.
    *
-   * @param selector - A single known template literal, never a concrete URL.
-   * @param values - The selected target's complete explicit values.
+   * @param target - `to`, a single known template literal, never a concrete URL; the selected target's complete explicit values; and Angular's navigation behavior options.
    * @returns Angular's identical Router.navigateByUrl Promise.
    * @throws Synchronously for unknown selectors or invalid URL values.
    */
-  navigate<const Selector extends keyof Absolute & string, Keys extends keyof SearchOf<NoInfer<Absolute[Selector]>> = never>(selector: Selector & (IsUnion<Selector> extends true ? never : unknown), values: UrlValues<NoInfer<Absolute[Selector]>, Keys>): Promise<boolean>;
+  navigate<const Selector extends keyof Absolute & string, Keys extends keyof SearchOf<NoInfer<Absolute[Selector]>> = never>(target: {
+    /** A single known absolute authored selector, never a concrete URL. */
+    readonly to: Selector & (IsUnion<Selector> extends true ? never : unknown);
+  } & UrlValues<NoInfer<Absolute[Selector]>, Keys> & NavigationBehaviorOptions): Promise<boolean>;
   /**
    * Navigates to the parent route, when the bound declaration has one.
    *
-   * @param selector - The literal `..`.
-   * @param values - The parent route's complete explicit values.
+   * @param target - `to: ".."`, the parent route's complete explicit values and Angular's navigation behavior options.
    * @returns Angular's identical Router.navigateByUrl Promise.
    * @throws Synchronously for invalid URL values.
    */
-  navigate<Keys extends keyof SearchOf<Parent> = never>(selector: [Parent] extends [never] ? never : "..", values: UrlValues<Parent, Keys>): Promise<boolean>;
+  navigate<Keys extends keyof SearchOf<Parent> = never>(target: {
+    /** The parent route: the nearest ancestor with a shorter path, or the root. */
+    readonly to: [Parent] extends [never] ? never : "..";
+  } & UrlValues<Parent, Keys> & NavigationBehaviorOptions): Promise<boolean>;
   /**
    * Navigates to a generated reference's own exact declaration.
    *
-   * @param selector - A genuine destination exported by a facade in this route set.
-   * @param values - The referenced declaration's complete explicit values.
+   * @param target - `to`, a genuine destination exported by a facade in this route set; the referenced declaration's complete explicit values; and Angular's navigation behavior options.
    * @returns Angular's identical Router.navigateByUrl Promise.
    * @throws Synchronously for foreign/fake references or invalid URL values.
    */
-  navigate<const Id extends keyof References & string, Keys extends keyof SearchOf<NoInfer<References[Id]>> = never>(selector: Destination<NoInfer<References[Id]>, Set, Id> & (IsUnion<Id> extends true ? never : unknown), values: UrlValues<NoInfer<References[Id]>, Keys>): Promise<boolean>;
+  navigate<const Id extends keyof References & string, Keys extends keyof SearchOf<NoInfer<References[Id]>> = never>(target: {
+    /** A genuine destination exported by a facade in this route set. */
+    readonly to: Destination<NoInfer<References[Id]>, Set, Id> & (IsUnion<Id> extends true ? never : unknown);
+  } & UrlValues<NoInfer<References[Id]>, Keys> & NavigationBehaviorOptions): Promise<boolean>;
 }
 export declare function nativeOptions(definition: AnyRoute): Record<string, unknown>;
 export declare function injectGeneratedRoute<Target extends AnyRoute, Absolute extends Record<string, AnyRoute>, Parent extends AnyRoute, Set, References extends Record<string, AnyRoute>>(set: RouteSet, id: string): Handle<Target, Absolute, Parent, Set, References>;
+/** A declaration's handle over the signals of one activated record. */
+export declare function createHandle<Target extends AnyRoute, Absolute extends Record<string, AnyRoute>, Parent extends AnyRoute, Set, References extends Record<string, AnyRoute>>(set: RouteSet, id: string, router: Router, view: RouteView): Handle<Target, Absolute, Parent, Set, References>;
 export type { RecordBinding, RouteSet };

package/types/loozo-angular-router.d.ts

@@ -1,2 +1,2 @@
-import { ParamCodec, Route, booleanParam, createUrl, defineRoute, enumParam, numberParam, stringParam, withFallback } from "@loozo/angular-router/_core";
-export { type ParamCodec, type Route, booleanParam, createUrl, defineRoute, enumParam, numberParam, stringParam, withFallback };
+import { ParamCodec, Route, arrayParam, booleanParam, createUrl, defineRoute, enumParam, numberParam, stringParam, withFallback } from "@loozo/angular-router/_core";
+export { type ParamCodec, type Route, arrayParam, booleanParam, createUrl, defineRoute, enumParam, numberParam, stringParam, withFallback };