@real-router/angular 0.11.1 → 0.11.3

package/src/dom-utils/view-transitions.ts

@@ -1,142 +0,0 @@
-import type { Router } from "@real-router/core";
-
-export interface ViewTransitions {
-  destroy: () => void;
-}
-
-const NOOP_INSTANCE: ViewTransitions = Object.freeze({
-  destroy: () => {
-    /* no-op */
-  },
-});
-
-export function createViewTransitions(router: Router): ViewTransitions {
-  if (
-    typeof document === "undefined" ||
-    typeof document.startViewTransition !== "function"
-  ) {
-    return NOOP_INSTANCE;
-  }
-
-  let closeVT: (() => void) | null = null;
-  let currentVT: { skipTransition?: () => void } | null = null;
-  // Tracks whether TRANSITION_SUCCESS fired for the current leave. Used to
-  // distinguish "benign cleanup abort" (router's async path aborts its own
-  // controller in a finally block after successful navigation) from "real
-  // cancellation" (concurrent navigate, guard rejection, dispose).
-  let successFired = false;
-
-  const resolveAndClear = (): void => {
-    closeVT?.();
-    closeVT = null;
-  };
-
-  const offLeave = router.subscribeLeave(({ signal }) => {
-    // Reentrant abort: signal already aborted when we're called. Open no VT
-    // — router will fall through to TRANSITION_CANCELLED via isCurrentNav()
-    // after leave resolves. addEventListener("abort", ...) does not re-fire
-    // for past events, so skipping startViewTransition is the safe path.
-    if (signal.aborted) {
-      return;
-    }
-
-    successFired = false;
-    resolveAndClear();
-
-    // Return a Promise so the router awaits until the browser invokes
-    // updateCallback. This ensures old DOM snapshot is captured BEFORE the
-    // router commits the new state — giving correct exit→state→entry
-    // ordering (vs fire-and-forget, where URL changes before VT captures).
-    return new Promise<void>((resolveLeave) => {
-      // Capture the resolver synchronously BEFORE startViewTransition() is
-      // called. The browser invokes updateCallback in a later task, but
-      // router.subscribe (TRANSITION_SUCCESS) can fire before that. If we
-      // captured `resolve` inside the callback, subscribe would see closeVT
-      // still null and skip resolving — the deferred would hang for 4s
-      // until the VT API aborts with TimeoutError.
-      const deferred = new Promise<void>((resolve) => {
-        closeVT = resolve;
-      });
-
-      signal.addEventListener(
-        "abort",
-        () => {
-          if (successFired) {
-            // Router's async path (#finishAsyncNavigation) aborts its own
-            // controller in a finally block AFTER completeTransition (and
-            // thus AFTER subscribe fired). This is cleanup, not
-            // cancellation — VT is progressing normally, do nothing.
-            return;
-          }
-
-          // Real cancellation (concurrent navigate, dispose). Resolve the
-          // deferred so updateCallback can complete, skip the VT so no
-          // stale animation leaks, and unblock the router if the abort
-          // fires before updateCallback was invoked.
-          resolveAndClear();
-          currentVT?.skipTransition?.();
-          resolveLeave();
-        },
-        { once: true },
-      );
-
-      try {
-        currentVT = document.startViewTransition(() => {
-          // Resolving here unblocks the router at the moment the browser
-          // enters updateCallback — by spec, old DOM snapshot is captured
-          // before this callback runs. Router now proceeds through
-          // activation guards and setState; the VT animation waits on
-          // `deferred`, which is resolved from router.subscribe after a
-          // task-queue tick (see NOTE on setTimeout below).
-          resolveLeave();
-
-          return deferred;
-        });
-      } catch {
-        // Defensive: spec says startViewTransition doesn't throw under
-        // normal conditions, but Chromium has had edge cases (detached
-        // document, extension interference). Clean up and unblock router.
-        resolveAndClear();
-        resolveLeave();
-      }
-    });
-  });
-
-  const offSuccess = router.subscribe(() => {
-    const resolver = closeVT;
-
-    successFired = true;
-    closeVT = null;
-
-    if (resolver === null) {
-      currentVT = null;
-    } else {
-      // CRITICAL: CANNOT use requestAnimationFrame here. When the router
-      // takes the async path (leave returned a Promise), subscribe fires
-      // AFTER the browser has already transitioned VT into the
-      // "update-callback-called" phase. In that phase Chromium sets
-      // rendering suppression to true, which ALSO blocks rAF callbacks.
-      // rAF would never fire → deferred never resolves → browser aborts
-      // vt.ready with TimeoutError after 4s (observed in Chromium).
-      //
-      // setTimeout runs on the task queue independent of the rendering
-      // pipeline, so it fires regardless of suppression. React's scheduler
-      // uses MessageChannel tasks, which are queued before our setTimeout,
-      // so the new DOM is committed by the time our callback runs.
-      setTimeout(() => {
-        resolver();
-        currentVT = null;
-      }, 0);
-    }
-  });
-
-  return {
-    destroy: () => {
-      offLeave();
-      offSuccess();
-      currentVT?.skipTransition?.();
-      currentVT = null;
-      resolveAndClear();
-    },
-  };
-}

package/src/functions/index.ts

@@ -1,29 +0,0 @@
-export { injectRouter } from "./injectRouter";
-
-export { injectNavigator } from "./injectNavigator";
-
-export { injectRoute } from "./injectRoute";
-
-export { injectRouteNode } from "./injectRouteNode";
-
-export { injectRouteUtils } from "./injectRouteUtils";
-
-export { injectRouterTransition } from "./injectRouterTransition";
-
-export { injectIsActiveRoute } from "./injectIsActiveRoute";
-
-export { injectRouteExit } from "./injectRouteExit";
-
-export { injectRouteEnter } from "./injectRouteEnter";
-
-export type {
-  RouteExitContext,
-  RouteExitHandler,
-  UseRouteExitOptions,
-} from "./injectRouteExit";
-
-export type {
-  RouteEnterContext,
-  RouteEnterHandler,
-  UseRouteEnterOptions,
-} from "./injectRouteEnter";

package/src/functions/injectIsActiveRoute.ts

@@ -1,31 +0,0 @@
-import { assertInInjectionContext } from "@angular/core";
-import { createActiveRouteSource } from "@real-router/sources";
-
-import { buildActiveRouteOptions } from "../internal/buildActiveRouteOptions";
-import { sourceToSignal } from "../sourceToSignal";
-import { injectRouter } from "./injectRouter";
-
-import type { Signal } from "@angular/core";
-import type { Params } from "@real-router/core";
-
-export function injectIsActiveRoute(
-  routeName: string,
-  params?: Params,
-  options?: { strict?: boolean; ignoreQueryParams?: boolean; hash?: string },
-): Signal<boolean> {
-  assertInInjectionContext(injectIsActiveRoute);
-
-  const router = injectRouter();
-  const source = createActiveRouteSource(
-    router,
-    routeName,
-    params,
-    buildActiveRouteOptions(
-      options?.strict ?? false,
-      options?.ignoreQueryParams ?? true,
-      options?.hash,
-    ),
-  );
-
-  return sourceToSignal(source);
-}

package/src/functions/injectNavigator.ts

@@ -1,12 +0,0 @@
-import { assertInInjectionContext } from "@angular/core";
-
-import { injectOrThrow } from "./injectOrThrow";
-import { NAVIGATOR } from "../providers";
-
-import type { Navigator } from "@real-router/core";
-
-export function injectNavigator(): Navigator {
-  assertInInjectionContext(injectNavigator);
-
-  return injectOrThrow(NAVIGATOR, "injectNavigator");
-}

package/src/functions/injectOrThrow.ts

@@ -1,19 +0,0 @@
-import { inject } from "@angular/core";
-
-import type { InjectionToken } from "@angular/core";
-
-export function injectOrThrow<T>(token: InjectionToken<T>, fnName: string): T {
-  const value = inject(token, { optional: true });
-
-  // Explicit null / undefined check — falsy guard would misfire on
-  // legitimately falsy values (`0`, `""`, `false`) if the token were ever
-  // typed for primitives. Today all our tokens hold object instances, but
-  // pinning the check keeps the function safe for future typing changes.
-  if (value === null || value === undefined) {
-    throw new Error(
-      `${fnName} must be used within a provideRealRouter context`,
-    );
-  }
-
-  return value;
-}

package/src/functions/injectRoute.ts

@@ -1,39 +0,0 @@
-import { assertInInjectionContext } from "@angular/core";
-
-import { injectOrThrow } from "./injectOrThrow";
-import { ROUTE } from "../providers";
-
-import type { RouteSignals } from "../types";
-import type { Signal } from "@angular/core";
-import type { Params, State } from "@real-router/core";
-import type { RouteSnapshot } from "@real-router/sources";
-
-type NonNullRouteSignals<P extends Params> = Omit<
-  RouteSignals<P>,
-  "routeState"
-> & {
-  readonly routeState: Signal<
-    Omit<RouteSnapshot<P>, "route"> & { route: State<P> }
-  >;
-};
-
-export function injectRoute<
-  P extends Params = Params,
->(): NonNullRouteSignals<P> {
-  assertInInjectionContext(injectRoute);
-
-  const signals = injectOrThrow(ROUTE, "injectRoute") as RouteSignals<P>;
-
-  // Read the snapshot once: the signal is reactive, but the throw-guard
-  // and any future use of the snapshot within this call should observe the
-  // SAME value to avoid races.
-  const snapshot = signals.routeState();
-
-  if (!snapshot.route) {
-    throw new Error(
-      "injectRoute called with no active route. Did you forget to await router.start() before rendering, or is the router stopped/disposed?",
-    );
-  }
-
-  return signals as NonNullRouteSignals<P>;
-}

package/src/functions/injectRouteEnter.ts

@@ -1,117 +0,0 @@
-import { assertInInjectionContext, effect } from "@angular/core";
-
-import { injectRoute } from "./injectRoute";
-
-import type { State } from "@real-router/core";
-
-export interface RouteEnterContext {
-  /** The route that was just activated. */
-  route: State;
-  /** The route that was active immediately before this navigation. */
-  previousRoute: State;
-}
-
-export type RouteEnterHandler = (context: RouteEnterContext) => void;
-
-export interface UseRouteEnterOptions {
-  /**
-   * Skip the handler when `route.name === previousRoute.name`
-   * (sort/filter/query-only navigations on the same route). Default:
-   * `true`. Symmetric with `injectRouteExit`'s same-name option.
-   */
-  skipSameRoute?: boolean;
-}
-
-/**
- * Fire `handler` once when the component is created as a result of a
- * navigation. Mirror of `injectRouteExit` for the entry side.
- *
- * What this function covers that an ad-hoc `effect()` + `injectRoute()`
- * doesn't:
- *
- *   - **Skip-initial**: handler is skipped when there is no
- *     `route.transition.from` (i.e. first-load mount). Most consumers
- *     want to fire side effects only on real navigations, not on
- *     hydration.
- *   - **Same-route skip** (default): handler is skipped when
- *     `route.transition.from === route.name`. Sort/filter/query-only
- *     navigations re-run the effect (because the `route` reference
- *     changes), but they are not "entries" in the animation / analytics
- *     sense. Opt out with `skipSameRoute: false`.
- *   - **Mount-time `route` / `previousRoute` snapshot**: handler receives
- *     the values that were live at the moment of effect activation.
- *
- * Effect cleanup is wired through the injection context's `DestroyRef`
- * (Angular's `effect()` ties into the active context automatically).
- * Must be called within an injection context (constructor, field
- * initializer, or `runInInjectionContext`).
- *
- * **Handler reactivity (Angular):** `inject*` functions run **once**
- * during component construction; `handler` is captured in closure at the
- * call site. The common Angular pattern is to pass a class method —
- * its identity is stable across change detection. To vary behavior
- * over time, read signals **inside** the handler body.
- *
- * @example Direction-aware entry animation
- * ```ts
- * \@Component({ ... })
- * class PageComponent {
- *   private el = inject(ElementRef<HTMLElement>);
- *
- *   constructor() {
- *     injectRouteEnter(({ route }) => {
- *       const direction = route.context.browser?.direction;
- *       this.el.nativeElement.classList.add(
- *         direction === "back" ? "slide-from-left" : "slide-from-right",
- *       );
- *     });
- *   }
- * }
- * ```
- *
- * @example Analytics page-enter event (skip-initial built-in)
- * ```ts
- * injectRouteEnter(({ route, previousRoute }) => {
- *   analytics.track("page_enter", {
- *     route: route.name,
- *     from: previousRoute.name,
- *   });
- * });
- * ```
- */
-export function injectRouteEnter(
-  handler: RouteEnterHandler,
-  options?: UseRouteEnterOptions,
-): void {
-  assertInInjectionContext(injectRouteEnter);
-
-  const { routeState } = injectRoute();
-  const skipSameRoute = options?.skipSameRoute ?? true;
-
-  effect(() => {
-    const { route, previousRoute } = routeState();
-
-    // Early-exit guards, top-down:
-    //
-    //   - **Skip-initial**: `state.transition.from` is undefined only
-    //     for the very first state committed by `router.start()`.
-    //   - **Skip-same-route**: query-only navigations have
-    //     `transition.from === route.name`. Opt-out via
-    //     `skipSameRoute: false`.
-    if (!route.transition.from) {
-      return;
-    }
-    if (skipSameRoute && route.transition.from === route.name) {
-      return;
-    }
-    // `previousRoute` is guaranteed populated whenever `route.transition.from`
-    // is set — core writes them together. The dead-code throw-guard that used
-    // to live here (review §8a LOW) is removed; the narrowing below is the
-    // type-safe equivalent and avoids the no-non-null-assertion lint.
-    if (!previousRoute) {
-      return;
-    }
-
-    handler({ route, previousRoute });
-  });
-}

package/src/functions/injectRouteExit.ts

@@ -1,118 +0,0 @@
-import { DestroyRef, assertInInjectionContext, inject } from "@angular/core";
-
-import { injectRouter } from "./injectRouter";
-
-import type { State } from "@real-router/core";
-
-export interface RouteExitContext {
-  /** The route being left. */
-  route: State;
-  /** The route being navigated to. */
-  nextRoute: State;
-  /**
-   * AbortSignal that fires when this navigation is superseded by a later
-   * one (rapid clicks). Already filtered: when the handler runs,
-   * `signal.aborted` is guaranteed to be `false`. Use
-   * `signal.addEventListener("abort", cleanup, { once: true })` for
-   * cleanup that must run on cancellation.
-   */
-  signal: AbortSignal;
-}
-
-export interface UseRouteExitOptions {
-  /**
-   * Skip the handler when `route.name === nextRoute.name`
-   * (sort/filter/query-only navigations on the same route). Default:
-   * `true`.
-   */
-  skipSameRoute?: boolean;
-}
-
-export type RouteExitHandler = (
-  context: RouteExitContext,
-) => void | Promise<void>;
-
-/**
- * Subscribe to the router's leave-window with the universal guards baked
- * in. Wraps `router.subscribeLeave` so consumers don't repeat the same
- * boilerplate every time:
- *
- *   - **Reentrant abort pre-check**: if `signal.aborted` is already `true`
- *     when the handler would run (rapid navigation superseded a slower
- *     one), the handler is skipped entirely.
- *   - **Same-route skip**: by default, `route.name === nextRoute.name`
- *     short-circuits the handler — query-only navigations skip the work.
- *     Opt out with `skipSameRoute: false`.
- *
- * Cleanup is bound to the injection context's `DestroyRef`. Must be
- * called within an injection context (constructor, field initializer,
- * or `runInInjectionContext`).
- *
- * If the handler returns a Promise, the router blocks on it. If the
- * Promise resolves, navigation proceeds. If it rejects, the router emits
- * `TRANSITION_CANCELLED`.
- *
- * **Handler reactivity (Angular):** `inject*` functions run **once**
- * during component construction; `handler` is captured in closure at the
- * call site. The common Angular pattern is to pass a class method
- * (`this.onExit.bind(this)` or an arrow-property) — its identity is
- * stable across change detection. To vary behavior over time, read
- * signals **inside** the handler body — do not rely on swapping the
- * handler reference.
- *
- * @example Animation
- * ```ts
- * \@Component({ ... })
- * class FadeOutComponent {
- *   private el = inject(ElementRef<HTMLElement>);
- *
- *   constructor() {
- *     injectRouteExit(async ({ signal }) => {
- *       const el = this.el.nativeElement;
- *       el.classList.add("fade-out");
- *       const cleanup = () => el.classList.remove("fade-out");
- *       signal.addEventListener("abort", cleanup, { once: true });
- *       try {
- *         el.getBoundingClientRect();
- *         await Promise.allSettled(el.getAnimations().map((a) => a.finished));
- *       } finally {
- *         cleanup();
- *       }
- *     });
- *   }
- * }
- * ```
- *
- * @example Auto-save form draft
- * ```ts
- * injectRouteExit(async ({ signal }) => {
- *   if (this.formState.dirty) {
- *     await this.api.saveDraft(this.formState, { signal });
- *   }
- * });
- * ```
- */
-export function injectRouteExit(
-  handler: RouteExitHandler,
-  options?: UseRouteExitOptions,
-): void {
-  assertInInjectionContext(injectRouteExit);
-
-  const router = injectRouter();
-  const destroyRef = inject(DestroyRef);
-  const skipSameRoute = options?.skipSameRoute ?? true;
-
-  const off = router.subscribeLeave(({ route, nextRoute, signal }) => {
-    if (skipSameRoute && route.name === nextRoute.name) {
-      return;
-    }
-
-    if (signal.aborted) {
-      return;
-    }
-
-    return handler({ route, nextRoute, signal });
-  });
-
-  destroyRef.onDestroy(off);
-}

package/src/functions/injectRouteNode.ts

@@ -1,19 +0,0 @@
-import { assertInInjectionContext } from "@angular/core";
-import { getNavigator } from "@real-router/core";
-import { createRouteNodeSource } from "@real-router/sources";
-
-import { sourceToSignal } from "../sourceToSignal";
-import { injectRouter } from "./injectRouter";
-
-import type { RouteSignals } from "../types";
-
-export function injectRouteNode(nodeName: string): RouteSignals {
-  assertInInjectionContext(injectRouteNode);
-
-  const router = injectRouter();
-  const navigator = getNavigator(router);
-  const source = createRouteNodeSource(router, nodeName);
-  const routeState = sourceToSignal(source);
-
-  return { routeState, navigator };
-}

package/src/functions/injectRouteUtils.ts

@@ -1,15 +0,0 @@
-import { assertInInjectionContext } from "@angular/core";
-import { getPluginApi } from "@real-router/core/api";
-import { getRouteUtils } from "@real-router/route-utils";
-
-import { injectRouter } from "./injectRouter";
-
-import type { RouteUtils } from "@real-router/route-utils";
-
-export function injectRouteUtils(): RouteUtils {
-  assertInInjectionContext(injectRouteUtils);
-
-  const router = injectRouter();
-
-  return getRouteUtils(getPluginApi(router).getTree());
-}

package/src/functions/injectRouter.ts

@@ -1,12 +0,0 @@
-import { assertInInjectionContext } from "@angular/core";
-
-import { injectOrThrow } from "./injectOrThrow";
-import { ROUTER } from "../providers";
-
-import type { Router } from "@real-router/core";
-
-export function injectRouter(): Router {
-  assertInInjectionContext(injectRouter);
-
-  return injectOrThrow(ROUTER, "injectRouter");
-}

package/src/functions/injectRouterTransition.ts

@@ -1,17 +0,0 @@
-import { assertInInjectionContext } from "@angular/core";
-import { getTransitionSource } from "@real-router/sources";
-
-import { sourceToSignal } from "../sourceToSignal";
-import { injectRouter } from "./injectRouter";
-
-import type { Signal } from "@angular/core";
-import type { RouterTransitionSnapshot } from "@real-router/sources";
-
-export function injectRouterTransition(): Signal<RouterTransitionSnapshot> {
-  assertInInjectionContext(injectRouterTransition);
-
-  const router = injectRouter();
-  const source = getTransitionSource(router);
-
-  return sourceToSignal(source);
-}

package/src/index.ts

@@ -1,63 +0,0 @@
-export { provideRealRouter, ROUTER, NAVIGATOR, ROUTE } from "./providers";
-
-export type { RealRouterOptions } from "./providers";
-
-export { provideRealRouterFactory } from "./providersFactory";
-
-export type {
-  RealRouterFactoryOptions,
-  RequestDepsFactory,
-  RequestPluginsFactory,
-} from "./providersFactory";
-
-export { sourceToSignal } from "./sourceToSignal";
-
-// Note: SSR-feature exports (`ClientOnly`, `ServerOnly`, `injectDeferred`)
-// have moved to the `/ssr` subpath — import them from
-// `@real-router/angular/ssr` to opt into the SSR-feature surface.
-export {
-  injectRouter,
-  injectNavigator,
-  injectRoute,
-  injectRouteNode,
-  injectRouteUtils,
-  injectRouterTransition,
-  injectIsActiveRoute,
-  injectRouteExit,
-  injectRouteEnter,
-} from "./functions";
-
-export type {
-  RouteExitContext,
-  RouteExitHandler,
-  UseRouteExitOptions,
-  RouteEnterContext,
-  RouteEnterHandler,
-  UseRouteEnterOptions,
-} from "./functions";
-
-export { RouteView } from "./components/RouteView";
-
-export { RouterErrorBoundary } from "./components/RouterErrorBoundary";
-
-export { NavigationAnnouncer } from "./components/NavigationAnnouncer";
-
-export { RouteMatch } from "./directives/RouteMatch";
-
-export { RouteSelf } from "./directives/RouteSelf";
-
-export { RouteNotFound } from "./directives/RouteNotFound";
-
-export { RealLink } from "./directives/RealLink";
-
-export { RealLinkActive } from "./directives/RealLinkActive";
-
-export type { RouteSignals, ErrorContext } from "./types";
-
-export type {
-  RouteSnapshot,
-  RouterTransitionSnapshot,
-  RouterErrorSnapshot,
-} from "@real-router/sources";
-
-export type { Navigator } from "@real-router/core";

package/src/internal/buildActiveRouteOptions.ts

@@ -1,20 +0,0 @@
-import type { ActiveRouteSourceOptions } from "@real-router/sources";
-
-/**
- * Build the `options` literal for `createActiveRouteSource` while honoring
- * `exactOptionalPropertyTypes` — the type forbids passing `{ hash: undefined }`
- * literally (#532), so callers must conditionally include the `hash` key only
- * when a value was provided.
- *
- * Used by `RealLink`, `RealLinkActive`, and `injectIsActiveRoute` — extracted
- * from three identical ternaries (review-2026-05-16 §8a LOW).
- */
-export function buildActiveRouteOptions(
-  strict: boolean,
-  ignoreQueryParams: boolean,
-  hash: string | undefined,
-): ActiveRouteSourceOptions {
-  return hash === undefined
-    ? { strict, ignoreQueryParams }
-    : { strict, ignoreQueryParams, hash };
-}