npm - @real-router/angular - Versions diffs - 0.4.0 → 0.6.0 - Mend

@real-router/angular 0.4.0 → 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (17) hide show

package/README.md +60 -1
package/dist/README.md +60 -1
package/dist/fesm2022/real-router-angular.mjs +383 -7
package/dist/fesm2022/real-router-angular.mjs.map +1 -1
package/dist/types/real-router-angular.d.ts +168 -4
package/dist/types/real-router-angular.d.ts.map +1 -1
package/package.json +3 -3
package/src/dom-utils/direction-tracker.ts +70 -0
package/src/dom-utils/index.ts +8 -0
package/src/dom-utils/route-announcer.ts +1 -1
package/src/dom-utils/view-transitions.ts +142 -0
package/src/functions/index.ts +16 -0
package/src/functions/injectRoute.ts +24 -3
package/src/functions/injectRouteEnter.ts +122 -0
package/src/functions/injectRouteExit.ts +118 -0
package/src/index.ts +11 -0
package/src/providers.ts +35 -1

package/src/dom-utils/direction-tracker.ts ADDED Viewed

@@ -0,0 +1,70 @@
+import type { Router } from "@real-router/core";
+export interface DirectionTracker {
+  destroy: () => void;
+}
+const NOOP_INSTANCE: DirectionTracker = Object.freeze({
+  destroy: () => {
+    /* no-op */
+  },
+});
+/**
+ * Track navigation direction (forward / back) and write it to
+ * `<html data-nav-direction>` on every leave. CSS / JS readers consume
+ * the attribute via `html[data-nav-direction="back"]` selectors or
+ * `document.documentElement.dataset.navDirection`.
+ *
+ * Mechanism-agnostic — works identically whether downstream UI uses CSS
+ * `@keyframes`, View Transitions pseudo-elements, or library state
+ * (motion's `motion.div initial={{ x: ... }}`).
+ *
+ * Implementation:
+ *   - On install, set `data-nav-direction="forward"` baseline.
+ *   - Attach a `popstate` listener that flips an internal flag to
+ *     `true`. Browser back/forward navigation triggers popstate; user
+ *     clicks on `<Link>` / programmatic `router.navigate(...)` do not.
+ *   - On every `subscribeLeave`, write
+ *     `popstateFlag ? "back" : "forward"` and reset the flag.
+ *
+ * Returns `{ destroy }` to clean up the listener and clear the dataset
+ * attribute.
+ */
+export function createDirectionTracker(router: Router): DirectionTracker {
+  if (typeof document === "undefined") {
+    return NOOP_INSTANCE;
+  }
+  let popstateFlag = false;
+  document.documentElement.dataset.navDirection = "forward";
+  const onPopstate = (): void => {
+    popstateFlag = true;
+  };
+  // IMPORTANT — listener-ordering: `popstate` fires on `window`, which
+  // has no DOM descendants, so capture phase is moot. Listeners are
+  // dispatched in registration order. To beat the browser-plugin's own
+  // popstate handler, this tracker must be installed **before**
+  // `router.usePlugin(browserPluginFactory())` in user code. Otherwise
+  // the plugin's handler runs first and synchronously fires
+  // `subscribeLeave` while `popstateFlag` is still `false`.
+  globalThis.addEventListener("popstate", onPopstate);
+  const offLeave = router.subscribeLeave(() => {
+    document.documentElement.dataset.navDirection = popstateFlag
+      ? "back"
+      : "forward";
+    popstateFlag = false;
+  });
+  return {
+    destroy: () => {
+      offLeave();
+      globalThis.removeEventListener("popstate", onPopstate);
+      delete document.documentElement.dataset.navDirection;
+    },
+  };
+}

package/src/dom-utils/index.ts CHANGED Viewed

@@ -1,7 +1,11 @@
+export { createDirectionTracker } from "./direction-tracker";
 export { createRouteAnnouncer } from "./route-announcer";
 export { createScrollRestoration } from "./scroll-restore";
+export { createViewTransitions } from "./view-transitions";
 export {
   shouldNavigate,
   buildHref,
@@ -16,3 +20,7 @@ export type {
   ScrollRestorationOptions,
   ScrollRestorationMode,
 } from "./scroll-restore";
+export type { DirectionTracker } from "./direction-tracker";
+export type { ViewTransitions } from "./view-transitions";

package/src/dom-utils/route-announcer.ts CHANGED Viewed

@@ -136,7 +136,7 @@ function resolveText(
     return getCustomText(route);
   }
-  const h1Text = h1?.textContent.trim() ?? "";
+  const h1Text = (h1?.textContent ?? "").trim();
   const routeName = route.name.startsWith(INTERNAL_ROUTE_PREFIX)
     ? ""
     : route.name;

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

@@ -0,0 +1,142 @@
+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 CHANGED Viewed

@@ -11,3 +11,19 @@ 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/injectRoute.ts CHANGED Viewed

@@ -2,8 +2,29 @@ import { injectOrThrow } from "./injectOrThrow";
 import { ROUTE } from "../providers";
 import type { RouteSignals } from "../types";
-import type { Params } from "@real-router/core";
+import type { Signal } from "@angular/core";
+import type { Params, State } from "@real-router/core";
+import type { RouteSnapshot } from "@real-router/sources";
-export function injectRoute<P extends Params = Params>(): RouteSignals<P> {
-  return injectOrThrow(ROUTE, "injectRoute") as RouteSignals<P>;
+export function injectRoute<P extends Params = Params>(): Omit<
+  RouteSignals<P>,
+  "routeState"
+> & {
+  readonly routeState: Signal<
+    Omit<RouteSnapshot<P>, "route"> & { route: State<P> }
+  >;
+} {
+  const signals = injectOrThrow(ROUTE, "injectRoute") as RouteSignals<P>;
+  if (!signals.routeState().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 Omit<RouteSignals<P>, "routeState"> & {
+    readonly routeState: Signal<
+      Omit<RouteSnapshot<P>, "route"> & { route: State<P> }
+    >;
+  };
 }

package/src/functions/injectRouteEnter.ts ADDED Viewed

@@ -0,0 +1,122 @@
+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;
+  let lastHandledRoute: State | null = null;
+  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`.
+    //   - **Defensive dedupe + missing `previousRoute`**: same `route`
+    //     ref between effect re-runs is unexpected on Angular (the
+    //     signal only fires on real reference changes); `!previousRoute`
+    //     is unreachable once `transition.from` is set (core populates
+    //     them together). Both kept for parity with React; v8-ignored.
+    if (!route.transition.from) {
+      return;
+    }
+    if (skipSameRoute && route.transition.from === route.name) {
+      return;
+    }
+    /* v8 ignore start */
+    if (lastHandledRoute === route || !previousRoute) {
+      return;
+    }
+    /* v8 ignore stop */
+    lastHandledRoute = route;
+    handler({ route, previousRoute });
+  });
+}

package/src/functions/injectRouteExit.ts ADDED Viewed

@@ -0,0 +1,118 @@
+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/index.ts CHANGED Viewed

@@ -10,6 +10,17 @@ export {
   injectRouteUtils,
   injectRouterTransition,
   injectIsActiveRoute,
+  injectRouteExit,
+  injectRouteEnter,
+} from "./functions";
+export type {
+  RouteExitContext,
+  RouteExitHandler,
+  UseRouteExitOptions,
+  RouteEnterContext,
+  RouteEnterHandler,
+  UseRouteEnterOptions,
 } from "./functions";
 export { RouteView } from "./components/RouteView";

package/src/providers.ts CHANGED Viewed

@@ -1,4 +1,5 @@
 import {
+  ApplicationRef,
   DestroyRef,
   InjectionToken,
   inject,
@@ -9,7 +10,7 @@ import {
 import { getNavigator, type Router, type Navigator } from "@real-router/core";
 import { createRouteSource } from "@real-router/sources";
-import { createScrollRestoration } from "./dom-utils";
+import { createScrollRestoration, createViewTransitions } from "./dom-utils";
 import { sourceToSignal } from "./sourceToSignal";
 import type { ScrollRestorationOptions } from "./dom-utils";
@@ -23,6 +24,7 @@ export const ROUTE = new InjectionToken<RouteSignals>("ROUTE");
 export interface RealRouterOptions {
   scrollRestoration?: ScrollRestorationOptions;
+  viewTransitions?: boolean;
 }
 export function provideRealRouter(
@@ -57,5 +59,37 @@ export function provideRealRouter(
     );
   }
+  if (options?.viewTransitions === true) {
+    providers.push(
+      provideEnvironmentInitializer(() => {
+        const appRef = inject(ApplicationRef);
+        // Force synchronous change detection on every transition success
+        // BEFORE the VT utility resolves its deferred. The utility uses
+        // `setTimeout(0)` to release the new-snapshot capture, which is
+        // load-bearing because Chromium blocks rAF callbacks while VT sits
+        // in the `update-callback-called` phase. Angular's zoneless CD is
+        // rAF-driven by default — without this synchronous tick the new
+        // DOM is not committed when the browser captures the new snapshot,
+        // so old and new snapshots end up identical and animations finish
+        // in ~0 ms with no visible work (the inner-route `products.list ↔
+        // products.detail` morph in the example example was the canary).
+        // Subscribers fire in registration order; this one runs BEFORE
+        // `createViewTransitions` registers its own subscriber,
+        // guaranteeing CD completes first.
+        const offTick = router.subscribe(() => {
+          appRef.tick();
+        });
+        const vt = createViewTransitions(router);
+        inject(DestroyRef).onDestroy(() => {
+          offTick();
+          vt.destroy();
+        });
+      }),
+    );
+  }
   return makeEnvironmentProviders(providers);
 }