@real-router/preact 0.15.2 → 0.15.3

package/src/hooks/useRouteExit.tsx

@@ -1,159 +0,0 @@
-import { useEffect, useLayoutEffect, useRef } from "preact/hooks";
-
-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`.
- *   - **Stable handler reference**: the handler can change identity on
- *     every render without causing resubscription — internal ref keeps
- *     the latest handler accessible to the long-lived subscription.
- *
- * Returns nothing — the subscription's lifecycle is bound to the
- * component's mount.
- *
- * 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` (existing core behavior, no change here).
- *
- * @example Animation
- * ```tsx
- * const ref = useRef<HTMLDivElement>(null);
- *
- * useRouteExit(async ({ signal }) => {
- *   const el = ref.current;
- *   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 Cancel inflight requests
- * ```tsx
- * useRouteExit(() => {
- *   inflightController.abort();
- * });
- * ```
- *
- * @example Library-coordinated exit (motion / framer-motion)
- * ```tsx
- * const exitResolverRef = useRef<(() => void) | null>(null);
- *
- * useRouteExit(({ signal }) => {
- *   return new Promise<void>((resolve) => {
- *     exitResolverRef.current = resolve;
- *     signal.addEventListener("abort", () => resolve(), { once: true });
- *   });
- * });
- *
- * const onExitComplete = () => exitResolverRef.current?.();
- * // pass onExitComplete to <AnimatePresence>
- * ```
- *
- * @example Reading rich transition metadata via `nextRoute.transition`
- * ```tsx
- * useRouteExit(({ route, nextRoute }) => {
- *   // nextRoute.transition: TransitionMeta — preview of the upcoming nav
- *   if (nextRoute.transition.segments.deactivated.includes("products")) {
- *     // leaving the products subtree entirely — flush product-related caches
- *     productCache.clear();
- *   }
- *   if (nextRoute.transition.redirected) {
- *     // skip animation when navigation arrived via redirect
- *     return;
- *   }
- * });
- * ```
- */
-export function useRouteExit(
-  handler: RouteExitHandler,
-  options?: UseRouteExitOptions,
-): void {
-  const router = useRouter();
-  const handlerRef = useRef(handler);
-  const skipSameRoute = options?.skipSameRoute ?? true;
-
-  // Keep the latest handler accessible to the subscription without
-  // resubscribing on every render — the subscription registers the
-  // wrapper once and dispatches to whatever ref points to.
-  // useLayoutEffect (synchronous, post-render, pre-paint) updates the
-  // ref before the browser can dispatch any router events that could
-  // observe a stale closure.
-  useLayoutEffect(() => {
-    handlerRef.current = handler;
-  });
-
-  useEffect(() => {
-    return 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 — any cleanup the
-      // handler would have wired via abort listener must not run because
-      // the corresponding `add` work never happened.
-      if (signal.aborted) {
-        return;
-      }
-
-      return handlerRef.current({ route, nextRoute, signal });
-    });
-  }, [router, skipSameRoute]);
-}

package/src/hooks/useRouteNode.tsx

@@ -1,34 +0,0 @@
-import { createRouteNodeSource } from "@real-router/sources";
-import { useMemo } from "preact/hooks";
-
-import { useSyncExternalStore } from "../useSyncExternalStore";
-import { useNavigator } from "./useNavigator";
-import { useRouter } from "./useRouter";
-
-import type { RouteContext } from "../types";
-
-export function useRouteNode(nodeName: string): RouteContext {
-  const router = useRouter();
-  const navigator = useNavigator();
-
-  // `createRouteNodeSource` is the cached factory from `@real-router/sources`
-  // keyed on (router, nodeName) — identical args return identical refs across
-  // renders. No `useMemo` needed.
-  const store = createRouteNodeSource(router, nodeName);
-
-  const { route, previousRoute } = useSyncExternalStore(
-    store.subscribe,
-    store.getSnapshot,
-    store.getSnapshot,
-  );
-
-  // Public stable-ref contract (locked by `useRouteNode.test.tsx` "should
-  // return stable reference when nothing changes"): consecutive renders with
-  // identical (navigator, route, previousRoute) return the same RouteContext
-  // ref. Drop this `useMemo` and downstream consumers re-render on every
-  // parent re-render.
-  return useMemo(
-    (): RouteContext => ({ navigator, route, previousRoute }),
-    [navigator, route, previousRoute],
-  );
-}

package/src/hooks/useRouteUtils.tsx

@@ -1,12 +0,0 @@
-import { getPluginApi } from "@real-router/core/api";
-import { getRouteUtils } from "@real-router/route-utils";
-
-import { useRouter } from "./useRouter";
-
-import type { RouteUtils } from "@real-router/route-utils";
-
-export const useRouteUtils = (): RouteUtils => {
-  const router = useRouter();
-
-  return getRouteUtils(getPluginApi(router).getTree());
-};

package/src/hooks/useRouter.tsx

@@ -1,8 +0,0 @@
-import { createUseContextOrThrow, RouterContext } from "../context";
-
-import type { Router } from "@real-router/core";
-
-export const useRouter: () => Router = createUseContextOrThrow(
-  RouterContext,
-  "useRouter",
-);

package/src/hooks/useRouterTransition.tsx

@@ -1,17 +0,0 @@
-import { getTransitionSource } from "@real-router/sources";
-
-import { useSyncExternalStore } from "../useSyncExternalStore";
-import { useRouter } from "./useRouter";
-
-import type { RouterTransitionSnapshot } from "@real-router/sources";
-
-export function useRouterTransition(): RouterTransitionSnapshot {
-  const router = useRouter();
-  const store = getTransitionSource(router);
-
-  return useSyncExternalStore(
-    store.subscribe,
-    store.getSnapshot,
-    store.getSnapshot,
-  );
-}

package/src/index.ts

@@ -1,56 +0,0 @@
-// Components
-export { RouteView } from "./components/RouteView";
-
-export { Link } from "./components/Link";
-
-export { RouterErrorBoundary } from "./components/RouterErrorBoundary";
-
-// Hooks
-export { useRouter } from "./hooks/useRouter";
-
-export { useNavigator } from "./hooks/useNavigator";
-
-export { useRouteUtils } from "./hooks/useRouteUtils";
-
-export { useRoute } from "./hooks/useRoute";
-
-export { useRouteNode } from "./hooks/useRouteNode";
-
-export { useRouterTransition } from "./hooks/useRouterTransition";
-
-export { useRouteExit } from "./hooks/useRouteExit";
-
-export { useRouteEnter } from "./hooks/useRouteEnter";
-
-// Context
-export { RouterProvider } from "./RouterProvider";
-
-export { RouterContext, NavigatorContext, RouteContext } from "./context";
-
-// Types
-export type { LinkProps } from "./types";
-
-export type { RouterErrorBoundaryProps } from "./components/RouterErrorBoundary";
-
-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";

package/src/ssr.ts

@@ -1,39 +0,0 @@
-// SSR-feature entry — Preact 10+
-//
-// Server-side and SSR-aware components/hooks. Mirror of `@real-router/react/ssr`
-// — same exports, same API surface. Pair with `@real-router/ssr-data-plugin`'s
-// `defer()` helper and `injectDeferredScripts` server-side wire-format.
-
-// Components
-export { ClientOnly } from "./components/ClientOnly";
-
-export { ServerOnly } from "./components/ServerOnly";
-
-export { Await } from "./components/Await";
-
-export { Streamed } from "./components/Streamed";
-
-export { HttpStatusCode } from "./components/HttpStatusCode";
-
-export { HttpStatusProvider } from "./components/HttpStatusProvider";
-
-// Hooks
-export { useDeferred } from "./hooks/useDeferred";
-
-// Utilities
-export { createHttpStatusSink } from "./utils/createHttpStatusSink";
-
-// Types
-export type { ClientOnlyProps } from "./components/ClientOnly";
-
-export type { ServerOnlyProps } from "./components/ServerOnly";
-
-export type { AwaitProps } from "./components/Await";
-
-export type { StreamedProps } from "./components/Streamed";
-
-export type { HttpStatusCodeProps } from "./components/HttpStatusCode";
-
-export type { HttpStatusProviderProps } from "./components/HttpStatusProvider";
-
-export type { HttpStatusSink } from "./utils/createHttpStatusSink";

package/src/types.ts

@@ -1,40 +0,0 @@
-import type {
-  NavigationOptions,
-  Params,
-  Navigator,
-  State,
-} from "@real-router/core";
-import type { HTMLAttributes } from "preact";
-
-export interface RouteState<P extends Params = Params> {
-  route: State<P> | undefined;
-  previousRoute?: State | undefined;
-}
-
-export type RouteContext<P extends Params = Params> = {
-  navigator: Navigator;
-} & RouteState<P>;
-
-export interface LinkProps<P extends Params = Params> extends Omit<
-  HTMLAttributes<HTMLAnchorElement>,
-  "className"
-> {
-  routeName: string;
-  routeParams?: P;
-  routeOptions?: NavigationOptions;
-  className?: string;
-  activeClassName?: string;
-  activeStrict?: boolean;
-  ignoreQueryParams?: boolean;
-  /**
-   * URL fragment (decoded form, no leading "#") (#532).
-   * - omitted/`undefined` → preserve current fragment on same-route navigation
-   * - `""` → clear fragment
-   * - non-empty → set fragment
-   *
-   * Requires a URL plugin (browser-plugin or navigation-plugin) for full
-   * round-trip; hash-plugin ignores the prop with a one-time dev warning.
-   */
-  hash?: string;
-  target?: string;
-}

package/src/useSyncExternalStore.ts

@@ -1,60 +0,0 @@
-import { useEffect, useState } from "preact/hooks";
-
-/**
- * Polyfill for React's useSyncExternalStore.
- *
- * Preact does not provide a native useSyncExternalStore.
- * This implementation uses useState + useEffect to subscribe
- * to external stores.
- *
- * Race condition handling: the value may change between
- * `useState(getSnapshot)` (render) and `useEffect` (commit).
- * We synchronize by calling `setValue(getSnapshot())` before
- * subscribing in the effect.
- *
- * The updater uses `Object.is` to bail out when the snapshot
- * is referentially stable, preventing redundant re-renders.
- *
- * SSR semantics: `_getServerSnapshot` is intentionally ignored.
- * Preact's `preact-render-to-string` runs `useState(getSnapshot)`
- * on the server and does not commit effects, so the initial
- * render already uses `getSnapshot()`. Real-Router's `createRouteSource`
- * (and friends) return the same value on server and client given the
- * same `router` instance, so passing `getSnapshot` itself as the third
- * argument at every call site is the symmetric SSR contract; a separate
- * `getServerSnapshot` would diverge during hydration. Consumers that
- * truly need a different server value should branch in `getSnapshot`.
- *
- * Stable-reference contract: `subscribe` and `getSnapshot` are deps of
- * the subscription effect. If a consumer passes inline closures, every
- * render triggers `unsubscribe → subscribe` plus a fresh `sync()` pass
- * — a silent O(N) reconnect that the Preact polyfill cannot bail out
- * of (React's native impl uses an internal sub-store keyed by identity;
- * we cannot replicate that without losing the latest-snapshot guarantee).
- * All Real-Router hooks pass router-keyed cached factories from
- * `@real-router/sources`, which produce stable refs per `(router, args…)`
- * — keep that pattern for every external use.
- */
-export function useSyncExternalStore<T>(
-  subscribe: (onStoreChange: () => void) => () => void,
-  getSnapshot: () => T,
-  _getServerSnapshot?: () => T,
-): T {
-  const [value, setValue] = useState(getSnapshot);
-
-  useEffect(() => {
-    const sync = (): void => {
-      setValue((prev) => {
-        const next = getSnapshot();
-
-        return Object.is(prev, next) ? prev : next;
-      });
-    };
-
-    sync();
-
-    return subscribe(sync);
-  }, [subscribe, getSnapshot]);
-
-  return value;
-}

package/src/utils/createHttpStatusSink.ts

@@ -1,27 +0,0 @@
-/**
- * Render-scoped HTTP status sink. Created per request on the server, passed to
- * `<HttpStatusProvider sink={...}>`, and read after `renderToString` (or the
- * Preact streaming helper) to apply the value to the HTTP response.
- *
- * Last write wins: if the rendered tree mounts more than one
- * `<HttpStatusCode />`, the value reflects the last component that ran during
- * the render pass.
- *
- * No-op on the client — `<HttpStatusCode />` reads the optional context and
- * skips the write when no provider is mounted, so the same component tree can
- * be hydrated without changing behaviour.
- *
- * Constraints:
- * - **Per-request only.** Don't share a sink across requests; the rendered
- *   tree mutates `code` in place. Module-level singletons leak status
- *   between concurrent requests.
- * - **Don't `Object.freeze` the sink.** The component writes to `.code`;
- *   freezing makes the assignment throw under ESM strict mode.
- */
-export interface HttpStatusSink {
-  code: number | undefined;
-}
-
-export function createHttpStatusSink(): HttpStatusSink {
-  return { code: undefined };
-}