@real-router/preact 0.11.1 → 0.13.0

package/src/components/Link.tsx

@@ -1,5 +1,4 @@
 import { memo } from "preact/compat";
-import { useCallback, useMemo } from "preact/hooks";
 
 import { EMPTY_PARAMS, EMPTY_OPTIONS } from "../constants";
 import {
@@ -13,8 +12,26 @@ import { useIsActiveRoute } from "../hooks/useIsActiveRoute";
 import { useRouter } from "../hooks/useRouter";
 
 import type { LinkProps } from "../types";
-import type { FunctionComponent, JSX } from "preact";
+import type { FunctionComponent, TargetedMouseEvent } from "preact";
 
+/**
+ * Custom comparator for `Link`'s `memo()` wrapper.
+ *
+ * **Maintenance contract:** every field in `LinkProps` MUST appear in either
+ * the `===` chain (primitives + identity-checked references like `onClick` /
+ * `children` / `style`) or in the `shallowEqual` arms (object-valued
+ * `routeParams` / `routeOptions`). When adding a new prop to `LinkProps`,
+ * extend this function in the same PR — `tests/functional/Link.test.tsx`
+ * contains a regression-guard that fails the build if `LinkProps` gains a
+ * field that is not compared here.
+ *
+ * **Intentional omissions:** `props` (the rest-spread of HTMLAnchorElement
+ * attributes — `aria-label`, `data-*`, `target`-other-than-`_blank`-handling,
+ * etc.) is NOT compared. A change to `aria-label` will NOT trigger a Link
+ * re-render. This is by design: dynamic `aria-label` is rare; consumers who
+ * truly need a reactive aria-label should call `<Link key={ariaLabel}>` to
+ * force a remount.
+ */
 function areLinkPropsEqual(
   prev: Readonly<LinkProps>,
   next: Readonly<LinkProps>,
@@ -57,10 +74,7 @@ export const Link: FunctionComponent<LinkProps> = memo(
     // change caught by shallowEqual), so they're safe to use directly in hook
     // deps without useStableValue.
 
-    // Hash-aware active (#532): when `hash` prop is set, isActive requires
-    // both route AND hash to match. Tab-style UI (multiple links sharing
-    // routeName but differing in hash) needs this to avoid marking all tabs
-    // active by route-name alone.
+    // Hash-aware active (#532) — see useIsActiveRoute for the contract.
     const isActive = useIsActiveRoute(
       routeName,
       routeParams,
@@ -69,46 +83,45 @@ export const Link: FunctionComponent<LinkProps> = memo(
       hash,
     );
 
-    const href = useMemo(
-      () =>
-        buildHref(
-          router,
-          routeName,
-          routeParams,
-          hash === undefined ? undefined : { hash },
-        ),
-      [router, routeName, routeParams, hash],
+    // `buildHref` is a cheap synchronous call (route-tree lookup + string
+    // concat). Wrapping it in `useMemo` allocates a deps array on every
+    // render that does not bail out — and on bail-out the function body
+    // doesn't execute, so the cache never pays off. Same logic for
+    // `buildActiveClassName` and `handleClick` below.
+    const href = buildHref(
+      router,
+      routeName,
+      routeParams,
+      hash === undefined ? undefined : { hash },
     );
 
-    const handleClick = useCallback(
-      (evt: JSX.TargetedMouseEvent<HTMLAnchorElement>) => {
-        if (onClick) {
-          onClick(evt);
-
-          if (evt.defaultPrevented) {
-            return;
-          }
-        }
+    const handleClick = (evt: TargetedMouseEvent<HTMLAnchorElement>): void => {
+      if (onClick) {
+        onClick(evt);
 
-        if (!shouldNavigate(evt) || target === "_blank") {
+        if (evt.defaultPrevented) {
           return;
         }
+      }
 
-        evt.preventDefault();
-        navigateWithHash(
-          router,
-          routeName,
-          routeParams,
-          hash,
-          routeOptions,
-        ).catch(() => {});
-      },
-      [onClick, target, router, routeName, routeParams, routeOptions, hash],
-    );
+      if (!shouldNavigate(evt) || target === "_blank") {
+        return;
+      }
+
+      evt.preventDefault();
+      navigateWithHash(
+        router,
+        routeName,
+        routeParams,
+        hash,
+        routeOptions,
+      ).catch(() => {});
+    };
 
-    const finalClassName = useMemo(
-      () => buildActiveClassName(isActive, activeClassName, className),
-      [isActive, activeClassName, className],
+    const finalClassName = buildActiveClassName(
+      isActive,
+      activeClassName,
+      className,
     );
 
     return (

package/src/components/RouteView/RouteView.tsx

@@ -24,17 +24,21 @@ function RouteViewRoot({
     return collected;
   }, [children]);
 
-  if (!route) {
-    return null;
-  }
+  const routeName = route?.name;
 
-  const { rendered } = buildRenderList(elements, route.name, nodeName);
+  // buildRenderList is O(N) over Match/Self/NotFound children. Memo on
+  // (elements, routeName, nodeName) skips the re-walk on parent re-renders
+  // that don't change the active route; navigations always invalidate via
+  // routeName.
+  const rendered = useMemo(() => {
+    if (routeName === undefined) {
+      return [];
+    }
 
-  if (rendered.length > 0) {
-    return <>{rendered}</>;
-  }
+    return buildRenderList(elements, routeName, nodeName).rendered;
+  }, [elements, routeName, nodeName]);
 
-  return null;
+  return rendered.length > 0 ? <>{rendered}</> : null;
 }
 
 RouteViewRoot.displayName = "RouteView";

package/src/components/RouteView/helpers.tsx

@@ -70,24 +70,22 @@ function renderSlot(
   return <Fragment key={key}>{content}</Fragment>;
 }
 
-function recordFallback(child: VNode, slots: FallbackSlots): boolean {
+function isFallbackKind(child: VNode): boolean {
+  return child.type === NotFound || child.type === Self;
+}
+
+function assignFallbackSlot(child: VNode, slots: FallbackSlots): void {
   if (child.type === NotFound) {
     slots.notFoundChildren = (child.props as NotFoundProps).children;
 
-    return true;
+    return;
   }
 
-  if (child.type === Self) {
-    if (!slots.selfFound) {
-      slots.selfChildren = (child.props as SelfProps).children;
-      slots.selfFallback = (child.props as SelfProps).fallback;
-      slots.selfFound = true;
-    }
-
-    return true;
+  if (!slots.selfFound) {
+    slots.selfChildren = (child.props as SelfProps).children;
+    slots.selfFallback = (child.props as SelfProps).fallback;
+    slots.selfFound = true;
   }
-
-  return false;
 }
 
 function processMatch(
@@ -96,7 +94,12 @@ function processMatch(
   nodeName: string,
   alreadyActive: boolean,
 ): VNode | null {
-  const { segment, exact = false, fallback } = child.props as MatchProps;
+  const {
+    segment,
+    exact = false,
+    fallback,
+    children,
+  } = child.props as MatchProps;
   const fullSegmentName = nodeName ? `${nodeName}.${segment}` : segment;
   const isActive =
     !alreadyActive && isSegmentMatch(routeName, fullSegmentName, exact);
@@ -105,11 +108,7 @@ function processMatch(
     return null;
   }
 
-  return renderSlot(
-    (child.props as MatchProps).children,
-    fullSegmentName,
-    fallback,
-  );
+  return renderSlot(children, fullSegmentName, fallback);
 }
 
 function appendFallback(
@@ -150,7 +149,9 @@ export function buildRenderList(
   const rendered: VNode[] = [];
 
   for (const child of elements) {
-    if (recordFallback(child, slots)) {
+    if (isFallbackKind(child)) {
+      assignFallbackSlot(child, slots);
+
       continue;
     }
 

package/src/components/RouterErrorBoundary.tsx

@@ -1,6 +1,6 @@
 import { createDismissableError } from "@real-router/sources";
 import { Fragment } from "preact";
-import { useEffect, useRef } from "preact/hooks";
+import { useEffect, useLayoutEffect, useRef } from "preact/hooks";
 
 import { useRouter } from "../hooks/useRouter";
 import { useSyncExternalStore } from "../useSyncExternalStore";
@@ -21,12 +21,32 @@ export interface RouterErrorBoundaryProps {
   ) => void;
 }
 
+/**
+ * Declarative navigation-error boundary.
+ *
+ * **Not** a Preact `componentDidCatch`-style ErrorBoundary — this component
+ * does NOT catch render-time exceptions from `children`. It is a compositional
+ * component that subscribes to `createDismissableError` from
+ * `@real-router/sources` and renders `fallback(error, resetError)` ALONGSIDE
+ * `children` (wrapped in a `<Fragment>`) when the router emits a navigation
+ * error (guard rejection, ROUTE_NOT_FOUND, etc.). The boundary auto-resets on
+ * the next successful navigation; `resetError()` lets the consumer dismiss
+ * the fallback imperatively.
+ *
+ * For real exception boundaries, wrap children in a Preact ErrorBoundary
+ * (e.g. `preact-iso/ErrorBoundary` or a custom `componentDidCatch` class) —
+ * the two can coexist.
+ */
 export function RouterErrorBoundary({
   children,
   fallback,
   onError,
 }: RouterErrorBoundaryProps): VNode {
   const router = useRouter();
+
+  // `createDismissableError` is the cached factory from `@real-router/sources`
+  // — keyed per-router, identity stable across renders. `useMemo` would wrap
+  // a call that already memoizes downstream.
   const store = createDismissableError(router);
   const snapshot = useSyncExternalStore(
     store.subscribe,
@@ -36,9 +56,14 @@ export function RouterErrorBoundary({
 
   const onErrorRef = useRef(onError);
 
-  // eslint-disable-next-line @eslint-react/refs -- "latest ref" pattern: sync callback to ref to avoid effect re-runs
-  onErrorRef.current = onError;
+  useLayoutEffect(() => {
+    onErrorRef.current = onError;
+  });
 
+  // snapshot.version is the @real-router/sources dismissable-error invariant:
+  // it is the only field that monotonically advances on each new error episode
+  // (snapshot.error/toRoute/fromRoute are correlated reads within the same
+  // version frame), so depending on it covers all error fields by construction.
   useEffect(() => {
     if (snapshot.error) {
       onErrorRef.current?.(

package/src/components/ServerOnly.tsx

@@ -0,0 +1,26 @@
+import { useEffect, useState } from "preact/hooks";
+
+import type { ComponentChildren } from "preact";
+
+export interface ServerOnlyProps {
+  readonly children: ComponentChildren;
+  readonly fallback?: ComponentChildren;
+}
+
+export function ServerOnly({
+  children,
+  fallback = null,
+}: ServerOnlyProps): ComponentChildren {
+  const [mounted, setMounted] = useState(false);
+
+  useEffect(() => {
+    // SSR/hydration boundary: server emits the children branch, client matches
+    // it on first paint, then this effect flips state to swap in the fallback
+    // (or hide entirely). The intentional re-render keeps markup consistent
+    // across renders.
+    // eslint-disable-next-line @eslint-react/set-state-in-effect -- intentional post-hydration swap
+    setMounted(true);
+  }, []);
+
+  return mounted ? fallback : children;
+}

package/src/components/Streamed.tsx

@@ -0,0 +1,24 @@
+import { Suspense } from "preact/compat";
+
+import type { ComponentChildren } from "preact";
+
+export interface StreamedProps {
+  /** Shown while any descendant `<Await>` / `use(promise)`-equivalent suspends. */
+  readonly fallback: ComponentChildren;
+  readonly children: ComponentChildren;
+}
+
+/**
+ * Cross-adapter alias for `<Suspense fallback={…}>` from `preact/compat`.
+ * Pairs with `<Await>` for symmetry with the React/Solid/Svelte/Vue/Angular
+ * SSR streaming naming.
+ *
+ * Preact's `Suspense` is part of `preact/compat` (experimental). For
+ * production streaming the preact-render-to-string toolchain is required.
+ */
+export function Streamed({
+  fallback,
+  children,
+}: StreamedProps): ComponentChildren {
+  return <Suspense fallback={fallback}>{children}</Suspense>;
+}

package/src/context.ts

@@ -1,10 +1,27 @@
 import { createContext } from "preact";
+import { useContext } from "preact/hooks";
 
 import type { RouteContext as RouteContextType } from "./types";
 import type { Router, Navigator } from "@real-router/core";
+import type { Context } from "preact";
 
 export const RouteContext = createContext<RouteContextType | null>(null);
 
 export const RouterContext = createContext<Router | null>(null);
 
 export const NavigatorContext = createContext<Navigator | null>(null);
+
+export function createUseContextOrThrow<T>(
+  context: Context<T | null>,
+  hookName: string,
+): () => T {
+  return () => {
+    const value = useContext(context);
+
+    if (!value) {
+      throw new Error(`${hookName} must be used within a RouterProvider`);
+    }
+
+    return value;
+  };
+}

package/src/hooks/useDeferred.tsx

@@ -0,0 +1,26 @@
+import { useRoute } from "./useRoute";
+
+interface DeferredContext {
+  ssrDataDeferred?: Record<string, Promise<unknown>>;
+}
+
+const NEVER_PROMISE = new Promise<never>(() => {
+  // Intentionally never resolves — surfaces a forever-pending Suspense boundary
+  // when a key is requested that the loader never declared.
+});
+
+/**
+ * Read a deferred promise published by `defer({ deferred: { <key>: Promise } })`
+ * inside an SSR data loader. Mirror of `@real-router/react/ssr` `useDeferred`
+ * — same `state.context.ssrDataDeferred` contract, same NEVER-on-missing
+ * fallback. Pair with `<Await>` (this package) which adds Preact-side
+ * promise-status tracking since Preact 10 has no `use(promise)` analogue.
+ */
+export function useDeferred<T = unknown>(key: string): Promise<T> {
+  const { route } = useRoute();
+  const context = route.context as DeferredContext;
+  const deferred = context.ssrDataDeferred;
+  const promise = deferred?.[key];
+
+  return (promise ?? NEVER_PROMISE) as Promise<T>;
+}

package/src/hooks/useIsActiveRoute.tsx

@@ -1,9 +1,11 @@
 import { createActiveRouteSource } from "@real-router/sources";
+import { useMemo } from "preact/hooks";
 
 import { useSyncExternalStore } from "../useSyncExternalStore";
 import { useRouter } from "./useRouter";
 
 import type { Params } from "@real-router/core";
+import type { ActiveRouteSourceOptions } from "@real-router/sources";
 
 export function useIsActiveRoute(
   routeName: string,
@@ -15,19 +17,25 @@ export function useIsActiveRoute(
   const router = useRouter();
 
   // createActiveRouteSource is per-router + canonical-args cached in
-  // @real-router/sources, so passing params by reference is safe. The
-  // `hash` argument (#532) participates in the cache key — a tab Link
-  // pointing to `/settings#account` shares its source only with consumers
-  // using the same routeName + params + hash.
-  // exactOptionalPropertyTypes forbids `{ hash: undefined }` literally, so
-  // we conditionally include the key only when the caller passed a value.
-  const store = createActiveRouteSource(
-    router,
-    routeName,
-    params,
-    hash === undefined
-      ? { strict, ignoreQueryParams }
-      : { strict, ignoreQueryParams, hash },
+  // @real-router/sources. Caching the opts object + memoising the source
+  // lookup avoids (a) re-allocating the literal on every render and (b)
+  // re-running canonicalJson(params) on the cache lookup path. The `hash`
+  // argument (#532) participates in the cache key — a tab Link pointing to
+  // `/settings#account` shares its source only with consumers using the
+  // same routeName + params + hash. exactOptionalPropertyTypes forbids
+  // `{ hash: undefined }` literally, so we conditionally include the key
+  // only when the caller passed a value.
+  const opts = useMemo<ActiveRouteSourceOptions>(
+    () =>
+      hash === undefined
+        ? { strict, ignoreQueryParams }
+        : { strict, ignoreQueryParams, hash },
+    [strict, ignoreQueryParams, hash],
+  );
+
+  const store = useMemo(
+    () => createActiveRouteSource(router, routeName, params, opts),
+    [router, routeName, params, opts],
   );
 
   return useSyncExternalStore(

package/src/hooks/useNavigator.tsx

@@ -1,15 +1,8 @@
-import { useContext } from "preact/hooks";
-
-import { NavigatorContext } from "../context";
+import { createUseContextOrThrow, NavigatorContext } from "../context";
 
 import type { Navigator } from "@real-router/core";
 
-export const useNavigator = (): Navigator => {
-  const navigator = useContext(NavigatorContext);
-
-  if (!navigator) {
-    throw new Error("useNavigator must be used within a RouterProvider");
-  }
-
-  return navigator;
-};
+export const useNavigator: () => Navigator = createUseContextOrThrow(
+  NavigatorContext,
+  "useNavigator",
+);

package/src/hooks/useRoute.tsx

@@ -1,19 +1,18 @@
-import { useContext } from "preact/hooks";
-
-import { RouteContext } from "../context";
+import { createUseContextOrThrow, RouteContext } from "../context";
 
 import type { RouteContext as RouteContextType } from "../types";
 import type { Params, State } from "@real-router/core";
 
+const useRouteContextOrThrow = createUseContextOrThrow(
+  RouteContext,
+  "useRoute",
+);
+
 export const useRoute = <P extends Params = Params>(): Omit<
   RouteContextType<P>,
   "route"
 > & { route: State<P> } => {
-  const routeContext = useContext(RouteContext);
-
-  if (!routeContext) {
-    throw new Error("useRoute must be used within a RouterProvider");
-  }
+  const routeContext = useRouteContextOrThrow();
 
   if (!routeContext.route) {
     throw new Error(

package/src/hooks/useRouteNode.tsx

@@ -1,19 +1,20 @@
-import { getNavigator } from "@real-router/core";
 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();
 
-  const store = useMemo(
-    () => createRouteNodeSource(router, nodeName),
-    [router, nodeName],
-  );
+  // `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,
@@ -21,8 +22,11 @@ export function useRouteNode(nodeName: string): RouteContext {
     store.getSnapshot,
   );
 
-  const navigator = useMemo(() => getNavigator(router), [router]);
-
+  // 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/useRouter.tsx

@@ -1,15 +1,8 @@
-import { useContext } from "preact/hooks";
-
-import { RouterContext } from "../context";
+import { createUseContextOrThrow, RouterContext } from "../context";
 
 import type { Router } from "@real-router/core";
 
-export const useRouter = (): Router => {
-  const router = useContext(RouterContext);
-
-  if (!router) {
-    throw new Error("useRouter must be used within a RouterProvider");
-  }
-
-  return router;
-};
+export const useRouter: () => Router = createUseContextOrThrow(
+  RouterContext,
+  "useRouter",
+);

package/src/ssr.ts

@@ -0,0 +1,39 @@
+// 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

@@ -4,7 +4,7 @@ import type {
   Navigator,
   State,
 } from "@real-router/core";
-import type { JSX } from "preact";
+import type { HTMLAttributes } from "preact";
 
 export interface RouteState<P extends Params = Params> {
   route: State<P> | undefined;
@@ -16,7 +16,7 @@ export type RouteContext<P extends Params = Params> = {
 } & RouteState<P>;
 
 export interface LinkProps<P extends Params = Params> extends Omit<
-  JSX.HTMLAttributes<HTMLAnchorElement>,
+  HTMLAttributes<HTMLAnchorElement>,
   "className"
 > {
   routeName: string;

package/src/useSyncExternalStore.ts

@@ -14,6 +14,26 @@ import { useEffect, useState } from "preact/hooks";
  *
  * 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,