@real-router/solid 0.6.0 → 0.8.0

package/src/hooks/useRouteExit.tsx

@@ -0,0 +1,123 @@
+import { onCleanup } from "solid-js";
+
+import { useRouter } from "./useRouter";
+
+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. `signal.addEventListener(
+ *     "abort", ...)` does not fire retroactively, so without this guard
+ *     downstream cleanup would never trigger.
+ *   - **Same-route skip**: by default, `route.name === nextRoute.name`
+ *     short-circuits the handler — query-only navigations (sort, filter,
+ *     pagination) skip the work. Opt out with `skipSameRoute: false`.
+ *
+ * Returns nothing — the subscription's lifecycle is bound to the
+ * component via `onCleanup`.
+ *
+ * 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 (Solid)**: Solid components run **once** at mount;
+ * `handler` is captured in closure at the call site. If you need
+ * different behavior across renders, derive it from a signal inside the
+ * handler body — do not rely on swapping the handler reference.
+ *
+ * @example Animation
+ * ```tsx
+ * let ref: HTMLDivElement | undefined;
+ *
+ * useRouteExit(async ({ signal }) => {
+ *   const el = ref;
+ *   if (!el) return;
+ *   el.classList.add("fade-out");
+ *   const cleanup = () => el.classList.remove("fade-out");
+ *   signal.addEventListener("abort", cleanup, { once: true });
+ *   try {
+ *     el.getBoundingClientRect();   // style flush
+ *     await Promise.allSettled(el.getAnimations().map((a) => a.finished));
+ *   } finally {
+ *     cleanup();
+ *   }
+ * });
+ * ```
+ *
+ * @example Auto-save form draft
+ * ```tsx
+ * useRouteExit(async ({ signal }) => {
+ *   if (formState.dirty) await api.saveDraft(formState, { signal });
+ * });
+ * ```
+ *
+ * @example Reading rich transition metadata via `nextRoute.transition`
+ * ```tsx
+ * useRouteExit(({ route, nextRoute }) => {
+ *   if (nextRoute.transition.segments.deactivated.includes("products")) {
+ *     productCache.clear();
+ *   }
+ *   if (nextRoute.transition.redirected) {
+ *     return;
+ *   }
+ * });
+ * ```
+ */
+export function useRouteExit(
+  handler: RouteExitHandler,
+  options?: UseRouteExitOptions,
+): void {
+  const router = useRouter();
+  const skipSameRoute = options?.skipSameRoute ?? true;
+
+  const off = router.subscribeLeave(({ route, nextRoute, signal }) => {
+    if (skipSameRoute && route.name === nextRoute.name) {
+      return;
+    }
+
+    // Reentrant abort: signal is already aborted when listener fires
+    // (e.g. a newer navigate superseded this one before subscribeLeave
+    // even ran). addEventListener("abort", ...) does not fire
+    // retroactively, so we skip the handler entirely.
+    if (signal.aborted) {
+      return;
+    }
+
+    return handler({ route, nextRoute, signal });
+  });
+
+  onCleanup(off);
+}

package/src/index.tsx

@@ -22,6 +22,10 @@ export { useRouteNodeStore } from "./hooks/useRouteNodeStore";
 
 export { useRouterTransition } from "./hooks/useRouterTransition";
 
+export { useRouteExit } from "./hooks/useRouteExit";
+
+export { useRouteEnter } from "./hooks/useRouteEnter";
+
 export { RouterProvider } from "./RouterProvider";
 
 export { RouterContext, RouteContext } from "./context";
@@ -39,9 +43,22 @@ export type { LinkDirectiveOptions } from "./directives/link";
 export type {
   RouteViewProps,
   RouteViewMatchProps,
+  RouteViewSelfProps,
   RouteViewNotFoundProps,
 } from "./components/RouteView";
 
+export type {
+  RouteExitContext,
+  RouteExitHandler,
+  UseRouteExitOptions,
+} from "./hooks/useRouteExit";
+
+export type {
+  RouteEnterContext,
+  RouteEnterHandler,
+  UseRouteEnterOptions,
+} from "./hooks/useRouteEnter";
+
 export type { Navigator } from "@real-router/core";
 
 export type { RouterTransitionSnapshot } from "@real-router/sources";