@real-router/solid 0.6.0 → 0.8.0

package/README.md

@@ -68,6 +68,8 @@ All hooks that subscribe to route state return `Accessor<T>` — call the access
 | `useRouterTransition()`   | `Accessor<RouterTransitionSnapshot>` | On transition start/end              |
 | `useRouteStore()`         | `RouteState` (store)                 | Granular — per-property              |
 | `useRouteNodeStore(name)` | `RouteState` (store)                 | Granular — per-property, node-scoped |
+| `useRouteExit(handler, options?)`  | `void` — wraps `subscribeLeave` with abort + same-route guards            | Never (handler captured at hook call) |
+| `useRouteEnter(handler, options?)` | `void` — fires once on nav-driven mount via `useRoute()` + `transition.from` | Never (handler captured at hook call) |
 
 ### Store-Based Hooks (Granular Reactivity)
 
@@ -137,8 +139,39 @@ function GlobalProgress() {
     </Show>
   );
 }
+
+// useRouteExit — exit animations, draft autosave, AbortSignal-aware cleanup
+function FadeOut() {
+  let ref: HTMLDivElement | undefined;
+  useRouteExit(async ({ signal }) => {
+    if (!ref) return;
+    ref.classList.add("fade-out");
+    const cleanup = () => ref!.classList.remove("fade-out");
+    signal.addEventListener("abort", cleanup, { once: true });
+    ref.getBoundingClientRect(); // style flush
+    await Promise.allSettled(ref.getAnimations().map((a) => a.finished));
+    cleanup();
+  });
+  return <div ref={ref}>...</div>;
+}
+
+// useRouteEnter — page-enter analytics, focus management, entry animations
+function PageEnterAnalytics() {
+  useRouteEnter(({ route, previousRoute }) => {
+    analytics.track("page_enter", {
+      route: route.name,
+      from: previousRoute.name,
+    });
+  });
+  return null;
+}
 ```
 
+> **Solid handler-reactivity:** components run once, so `handler` is captured at
+> hook-call time. To vary behavior over time, read signals **inside** the
+> handler body. See [CLAUDE.md](./CLAUDE.md) → "useRouteExit / useRouteEnter
+> Handler Is Captured At Init".
+
 ## Components
 
 ### `<Link>`
@@ -332,18 +365,30 @@ Opt-in preservation of scroll position across navigations:
 
 Restores scroll on back/forward, scrolls to top (or `#hash`) on push. Three modes: `"restore"` (default), `"top"`, `"manual"`. Custom containers via `scrollContainer: () => HTMLElement | null`. Options are read once on mount — changing the prop at runtime does not reconfigure the utility (Solid `onMount` is non-reactive). See [Scroll Restoration guide](https://github.com/greydragon888/real-router/wiki/Scroll-Restoration) for details.
 
+## View Transitions
+
+Opt-in animated route transitions via the browser's [View Transitions API](https://developer.mozilla.org/en-US/docs/Web/API/View_Transitions_API):
+
+```tsx
+<RouterProvider router={router} viewTransitions>
+  {/* Your app */}
+</RouterProvider>
+```
+
+No-op on unsupported browsers (Firefox as of 2026-04, SSR). Prop is read once on mount (Solid `onMount` is non-reactive) — if you need toggle, unmount/remount the provider. Customization is pure CSS via `::view-transition-*` pseudo-elements and `view-transition-name` for hero morphs. See [View Transitions guide](https://github.com/greydragon888/real-router/wiki/View-Transitions) for patterns.
+
 ## Documentation
 
 Full documentation: [Wiki](https://github.com/greydragon888/real-router/wiki)
 
-- [RouterProvider](https://github.com/greydragon888/real-router/wiki/RouterProvider) · [RouteView](https://github.com/greydragon888/real-router/wiki/RouteView) · [RouterErrorBoundary](https://github.com/greydragon888/real-router/wiki/RouterErrorBoundary) · [Link](https://github.com/greydragon888/real-router/wiki/Link) · [Scroll Restoration](https://github.com/greydragon888/real-router/wiki/Scroll-Restoration)
-- [useRouter](https://github.com/greydragon888/real-router/wiki/useRouter) · [useRoute](https://github.com/greydragon888/real-router/wiki/useRoute) · [useRouteNode](https://github.com/greydragon888/real-router/wiki/useRouteNode) · [useNavigator](https://github.com/greydragon888/real-router/wiki/useNavigator) · [useRouteUtils](https://github.com/greydragon888/real-router/wiki/useRouteUtils) · [useRouterTransition](https://github.com/greydragon888/real-router/wiki/useRouterTransition)
+- [RouterProvider](https://github.com/greydragon888/real-router/wiki/RouterProvider) · [RouteView](https://github.com/greydragon888/real-router/wiki/RouteView) · [RouterErrorBoundary](https://github.com/greydragon888/real-router/wiki/RouterErrorBoundary) · [Link](https://github.com/greydragon888/real-router/wiki/Link) · [Scroll Restoration](https://github.com/greydragon888/real-router/wiki/Scroll-Restoration) · [View Transitions](https://github.com/greydragon888/real-router/wiki/View-Transitions)
+- [useRouter](https://github.com/greydragon888/real-router/wiki/useRouter) · [useRoute](https://github.com/greydragon888/real-router/wiki/useRoute) · [useRouteNode](https://github.com/greydragon888/real-router/wiki/useRouteNode) · [useNavigator](https://github.com/greydragon888/real-router/wiki/useNavigator) · [useRouteUtils](https://github.com/greydragon888/real-router/wiki/useRouteUtils) · [useRouterTransition](https://github.com/greydragon888/real-router/wiki/useRouterTransition) · [useRouteExit](https://github.com/greydragon888/real-router/wiki/useRouteExit) · [useRouteEnter](https://github.com/greydragon888/real-router/wiki/useRouteEnter)
 
 ## Examples
 
-14 runnable examples — each is a standalone Vite app. Run: `cd examples/solid/basic && pnpm dev`
+14 runnable examples — each is a standalone Vite app. Run: `cd examples/web/solid/basic && pnpm dev`
 
-[basic](../../examples/solid/basic) · [nested-routes](../../examples/solid/nested-routes) · [auth-guards](../../examples/solid/auth-guards) · [data-loading](../../examples/solid/data-loading) · [lazy-loading](../../examples/solid/lazy-loading) · [async-guards](../../examples/solid/async-guards) · [hash-routing](../../examples/solid/hash-routing) · [persistent-params](../../examples/solid/persistent-params) · [error-handling](../../examples/solid/error-handling) · [dynamic-routes](../../examples/solid/dynamic-routes) · [store-based-state](../../examples/solid/store-based-state) · [use-link-directive](../../examples/solid/use-link-directive) · [signal-primitives](../../examples/solid/signal-primitives) · [combined](../../examples/solid/combined)
+[basic](../../examples/web/solid/basic) · [nested-routes](../../examples/web/solid/nested-routes) · [auth-guards](../../examples/web/solid/auth-guards) · [data-loading](../../examples/web/solid/data-loading) · [lazy-loading](../../examples/web/solid/lazy-loading) · [async-guards](../../examples/web/solid/async-guards) · [hash-routing](../../examples/web/solid/hash-routing) · [persistent-params](../../examples/web/solid/persistent-params) · [error-handling](../../examples/web/solid/error-handling) · [dynamic-routes](../../examples/web/solid/dynamic-routes) · [store-based-state](../../examples/web/solid/store-based-state) · [use-link-directive](../../examples/web/solid/use-link-directive) · [signal-primitives](../../examples/web/solid/signal-primitives) · [combined](../../examples/web/solid/combined)
 
 ## Related Packages
 

package/dist/cjs/index.d.ts

@@ -17,6 +17,12 @@ interface MatchProps {
     readonly fallback?: JSX.Element;
     readonly children: JSX.Element;
 }
+interface SelfProps {
+    /** Fallback content while children are suspended. */
+    readonly fallback?: JSX.Element;
+    /** Content to render when the active route name equals the parent RouteView's nodeName. */
+    readonly children: JSX.Element;
+}
 interface NotFoundProps {
     readonly children: JSX.Element;
 }
@@ -25,6 +31,10 @@ declare function Match(props: MatchProps): JSX.Element;
 declare namespace Match {
     var displayName: string;
 }
+declare function Self(props: SelfProps): JSX.Element;
+declare namespace Self {
+    var displayName: string;
+}
 declare function NotFound(props: NotFoundProps): JSX.Element;
 declare namespace NotFound {
     var displayName: string;
@@ -36,6 +46,7 @@ declare namespace RouteViewRoot {
 }
 declare const RouteView: typeof RouteViewRoot & {
     Match: typeof Match;
+    Self: typeof Self;
     NotFound: typeof NotFound;
 };
 
@@ -89,6 +100,170 @@ declare function useRouteNodeStore(nodeName: string): RouteState;
 
 declare function useRouterTransition(): Accessor<RouterTransitionSnapshot>;
 
+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;
+}
+interface UseRouteExitOptions {
+    /**
+     * Skip the handler when `route.name === nextRoute.name`
+     * (sort/filter/query-only navigations on the same route). Default:
+     * `true`.
+     */
+    skipSameRoute?: boolean;
+}
+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;
+ *   }
+ * });
+ * ```
+ */
+declare function useRouteExit(handler: RouteExitHandler, options?: UseRouteExitOptions): void;
+
+interface RouteEnterContext {
+    /** The route that was just activated. */
+    route: State;
+    /** The route that was active immediately before this navigation. */
+    previousRoute: State;
+}
+type RouteEnterHandler = (context: RouteEnterContext) => void;
+interface UseRouteEnterOptions {
+    /**
+     * Skip the handler when `route.name === previousRoute.name`
+     * (sort/filter/query-only navigations on the same route). Default:
+     * `true`. Symmetric with `useRouteExit`'s same-name option.
+     */
+    skipSameRoute?: boolean;
+}
+/**
+ * Fire `handler` once when the component mounts as a result of a
+ * navigation. Mirror of `useRouteExit` for the entry side.
+ *
+ * What this hook covers that an ad-hoc `createEffect` + `useRoute()`
+ * doesn't:
+ *
+ *   - **Skip-initial**: handler is skipped when there is no
+ *     `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-trigger the effect (because the `route` reference
+ *     changes), but they are not "entries" in the animation / analytics
+ *     sense — the component instance has stayed mounted throughout.
+ *     Opt out with `skipSameRoute: false`.
+ *   - **Mount-time `route` / `previousRoute` snapshot**: the handler
+ *     receives the values that were live at the moment of effect
+ *     activation, not the latest ones (which may have moved on if the
+ *     user navigated again before the effect drained).
+ *
+ * **Handler reactivity (Solid)**: Solid components run **once** at mount;
+ * `handler` is captured in closure when the hook is called. 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 Direction-aware entry animation
+ * ```tsx
+ * useRouteEnter(({ route }) => {
+ *   const direction = route.context.browser?.direction;
+ *   ref?.classList.add(
+ *     direction === "back" ? "slide-from-left" : "slide-from-right",
+ *   );
+ * });
+ * ```
+ *
+ * @example Analytics page-enter event (skip-initial built-in)
+ * ```tsx
+ * useRouteEnter(({ route, previousRoute }) => {
+ *   analytics.track("page_enter", {
+ *     route: route.name,
+ *     from: previousRoute.name,
+ *   });
+ * });
+ * ```
+ *
+ * @example Reading rich transition metadata via `route.transition`
+ * ```tsx
+ * useRouteEnter(({ route }) => {
+ *   if (route.transition.redirected) {
+ *     showToast(`Redirected from ${route.transition.from}`);
+ *   }
+ *   if (route.transition.segments.activated.includes("products")) {
+ *     // products subtree just became active
+ *   }
+ * });
+ * ```
+ */
+declare function useRouteEnter(handler: RouteEnterHandler, options?: UseRouteEnterOptions): void;
+
 type ScrollRestorationMode = "restore" | "top" | "manual";
 interface ScrollRestorationOptions {
     mode?: ScrollRestorationMode | undefined;
@@ -100,6 +275,7 @@ interface RouteProviderProps {
     router: Router;
     announceNavigation?: boolean;
     scrollRestoration?: ScrollRestorationOptions;
+    viewTransitions?: boolean;
 }
 declare function RouterProvider(props: ParentProps<RouteProviderProps>): JSX.Element;
 
@@ -115,5 +291,5 @@ declare function createSignalFromSource<T>(source: RouterSource<T>): Accessor<T>
 
 declare function createStoreFromSource<T extends object>(source: RouterSource<T>): T;
 
-export { Link, RouteContext, RouteView, RouterContext, RouterErrorBoundary, RouterProvider, createSignalFromSource, createStoreFromSource, link, useNavigator, useRoute, useRouteNode, useRouteNodeStore, useRouteStore, useRouteUtils, useRouter, useRouterTransition };
-export type { LinkDirectiveOptions, LinkProps, RouteState, MatchProps as RouteViewMatchProps, NotFoundProps as RouteViewNotFoundProps, RouteViewProps, RouterErrorBoundaryProps };
+export { Link, RouteContext, RouteView, RouterContext, RouterErrorBoundary, RouterProvider, createSignalFromSource, createStoreFromSource, link, useNavigator, useRoute, useRouteEnter, useRouteExit, useRouteNode, useRouteNodeStore, useRouteStore, useRouteUtils, useRouter, useRouterTransition };
+export type { LinkDirectiveOptions, LinkProps, RouteEnterContext, RouteEnterHandler, RouteExitContext, RouteExitHandler, RouteState, MatchProps as RouteViewMatchProps, NotFoundProps as RouteViewNotFoundProps, RouteViewProps, SelfProps as RouteViewSelfProps, RouterErrorBoundaryProps, UseRouteEnterOptions, UseRouteExitOptions };