@real-router/preact 0.15.2 → 0.15.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@real-router/preact",
-  "version": "0.15.2",
+  "version": "0.15.3",
   "type": "commonjs",
   "description": "Preact integration for Real-Router",
   "main": "./dist/cjs/index.js",
@@ -34,8 +34,7 @@
     }
   },
   "files": [
-    "dist",
-    "src"
+    "dist"
   ],
   "homepage": "https://github.com/greydragon888/real-router",
   "repository": {
@@ -64,9 +63,9 @@
   "license": "MIT",
   "sideEffects": false,
   "dependencies": {
+    "@real-router/core": "^0.57.0",
     "@real-router/route-utils": "^0.2.3",
-    "@real-router/core": "^0.56.0",
-    "@real-router/sources": "^0.8.5"
+    "@real-router/sources": "^0.8.6"
   },
   "devDependencies": {
     "@testing-library/dom": "10.4.1",
@@ -75,7 +74,7 @@
     "@testing-library/user-event": "14.6.1",
     "preact": "10.29.2",
     "preact-render-to-string": "6.7.0",
-    "@real-router/browser-plugin": "^0.17.6"
+    "@real-router/browser-plugin": "^0.17.7"
   },
   "peerDependencies": {
     "preact": ">=10.28.0 || ^11.0.0-0"

package/src/RouterProvider.tsx

@@ -1,152 +0,0 @@
-import { getNavigator } from "@real-router/core";
-import { createRouteSource } from "@real-router/sources";
-import { useEffect, useMemo } from "preact/hooks";
-
-import { NavigatorContext, RouteContext, RouterContext } from "./context";
-import {
-  createRouteAnnouncer,
-  createScrollRestoration,
-  createScrollSpy,
-  createViewTransitions,
-} from "./dom-utils";
-import { useSyncExternalStore } from "./useSyncExternalStore";
-
-import type { ScrollRestorationOptions, ScrollSpyOptions } from "./dom-utils";
-import type { Router } from "@real-router/core";
-import type { FunctionComponent, ComponentChildren } from "preact";
-
-export interface RouteProviderProps {
-  router: Router;
-  children: ComponentChildren;
-  announceNavigation?: boolean;
-  scrollRestoration?: ScrollRestorationOptions;
-  scrollSpy?: ScrollSpyOptions;
-  viewTransitions?: boolean;
-}
-
-export const RouterProvider: FunctionComponent<RouteProviderProps> = ({
-  router,
-  children,
-  announceNavigation,
-  scrollRestoration,
-  scrollSpy,
-  viewTransitions,
-}) => {
-  useEffect(() => {
-    if (!announceNavigation) {
-      return;
-    }
-
-    const announcer = createRouteAnnouncer(router);
-
-    return () => {
-      announcer.destroy();
-    };
-  }, [announceNavigation, router]);
-
-  // Primitive deps so inline `{ mode: "restore" }` doesn't thrash on every
-  // render. scrollContainer is a getter invoked lazily on every event inside
-  // the utility — swapping its reference doesn't change the resolved element,
-  // so we intentionally omit it from deps to keep inline getters stable.
-  const srMode = scrollRestoration?.mode;
-  const srAnchor = scrollRestoration?.anchorScrolling;
-  const srBehavior = scrollRestoration?.behavior;
-  const srStorageKey = scrollRestoration?.storageKey;
-  const srEnabled = scrollRestoration !== undefined;
-
-  useEffect(() => {
-    if (!srEnabled) {
-      return;
-    }
-
-    const sr = createScrollRestoration(router, {
-      mode: srMode,
-      anchorScrolling: srAnchor,
-      behavior: srBehavior,
-      storageKey: srStorageKey,
-      // srEnabled check above guarantees scrollRestoration is defined.
-      scrollContainer: scrollRestoration.scrollContainer,
-    });
-
-    return () => {
-      sr.destroy();
-    };
-    // scrollRestoration (for scrollContainer) omitted — see comment above.
-    // eslint-disable-next-line @eslint-react/exhaustive-deps
-  }, [router, srEnabled, srMode, srAnchor, srBehavior, srStorageKey]);
-
-  const spySelector = scrollSpy?.selector;
-  const spyRootMargin = scrollSpy?.rootMargin;
-  const spyEnabled =
-    scrollSpy !== undefined && spySelector !== undefined && spySelector !== "";
-
-  useEffect(() => {
-    if (!spyEnabled) {
-      return;
-    }
-
-    const spy = createScrollSpy(router, {
-      selector: spySelector,
-      rootMargin: spyRootMargin,
-      scrollContainer: scrollSpy.scrollContainer,
-    });
-
-    return () => {
-      spy.destroy();
-    };
-    // scrollSpy (for scrollContainer) omitted — same rationale as
-    // scrollRestoration above: getter is invoked lazily inside the utility.
-    // eslint-disable-next-line @eslint-react/exhaustive-deps
-  }, [router, spyEnabled, spySelector, spyRootMargin]);
-
-  useEffect(() => {
-    if (!viewTransitions) {
-      return;
-    }
-
-    const vt = createViewTransitions(router);
-
-    return () => {
-      vt.destroy();
-    };
-  }, [router, viewTransitions]);
-
-  // `getNavigator` is cached per-router in `@real-router/core` (WeakMap) —
-  // same router always returns the same Navigator ref. No `useMemo` needed.
-  const navigator = getNavigator(router);
-
-  // `createRouteSource` is NOT cached (per packages/sources/CLAUDE.md table).
-  // It must be stable across renders so `useSyncExternalStore`'s deps don't
-  // change identity and trigger an unsubscribe/resubscribe loop on every
-  // render. `useMemo([router])` gives one source per router-instance lifetime.
-  const store = useMemo(() => createRouteSource(router), [router]);
-
-  // useSyncExternalStore manages the router subscription lifecycle:
-  // subscribe connects to router on first listener, unsubscribes on last.
-  const { route, previousRoute } = useSyncExternalStore(
-    store.subscribe,
-    store.getSnapshot,
-    store.getSnapshot, // SSR: router returns same state on server and client
-  );
-
-  // Stable-ref against parent re-renders: when parent re-renders RouterProvider
-  // without a route change (e.g. consumer re-renders the root), navigator /
-  // route / previousRoute references stay identical (useSyncExternalStore +
-  // Object.is bail-out). Without `useMemo` the object literal is fresh every
-  // render, propagating spurious re-renders to every `useRoute()` consumer.
-  // The memo bails out whenever the three deps are referentially equal.
-  const routeContextValue = useMemo(
-    () => ({ navigator, route, previousRoute }),
-    [navigator, route, previousRoute],
-  );
-
-  return (
-    <RouterContext.Provider value={router}>
-      <NavigatorContext.Provider value={navigator}>
-        <RouteContext.Provider value={routeContextValue}>
-          {children}
-        </RouteContext.Provider>
-      </NavigatorContext.Provider>
-    </RouterContext.Provider>
-  );
-};

package/src/components/Await.tsx

@@ -1,99 +0,0 @@
-import { useDeferred } from "../hooks/useDeferred";
-
-import type { ComponentChildren } from "preact";
-
-interface TrackedPromise<T> extends Promise<T> {
-  status?: "pending" | "fulfilled" | "rejected";
-  value?: T;
-  reason?: unknown;
-}
-
-/**
- * Preact's `Suspense` (from `preact/compat`) catches a thrown thenable and
- * re-runs the boundary's render once it settles. For deterministic re-renders
- * we tag the promise with `.status` / `.value` / `.reason` on first access so
- * the second render-pass can return the value synchronously instead of
- * throwing again.
- *
- * The same tag layout is used by React 19's internal `use(promise)` cache,
- * so promises that already carry the tag (e.g. emitted by a Suspense-aware
- * data lib) are reused as-is.
- */
-function track<T>(promise: Promise<T>): TrackedPromise<T> {
-  const tracked = promise as TrackedPromise<T>;
-
-  if (tracked.status !== undefined) {
-    return tracked;
-  }
-
-  tracked.status = "pending";
-  promise.then(
-    (value) => {
-      /* v8 ignore next 4 -- @preserve: the `.status === "pending"` guard
-         protects against external mutation between `track()` and the .then
-         microtask; covered branch is the always-true case in our control. */
-      if (tracked.status === "pending") {
-        tracked.status = "fulfilled";
-        tracked.value = value;
-      }
-    },
-    /* v8 ignore start -- @preserve: rejection .then handler — tested
-       end-to-end via the React adapter's e2e ssr-streaming Scenario 10
-       (id=4 reviews promise rejects on the wire); covering it in unit tests
-       requires Preact's Suspense to surface the rejection through render,
-       which doesn't compose cleanly with vitest's unhandled-rejection
-       detector. Behaviour is symmetric to the success handler above. */
-    (error: unknown) => {
-      if (tracked.status === "pending") {
-        tracked.status = "rejected";
-        tracked.reason = error;
-      }
-    },
-    /* v8 ignore stop */
-  );
-
-  return tracked;
-}
-
-export interface AwaitProps<T> {
-  /** Deferred key declared in the loader's `defer({ deferred: { <name>: ... } })`. */
-  readonly name: string;
-  /** Render the resolved value. Suspends while pending; throws inside the
-   * nearest Error Boundary on rejection. */
-  readonly children: (value: T) => ComponentChildren;
-}
-
-/**
- * Reads `useDeferred(name)` and hands the resolved value to the render-prop
- * via Preact's `<Suspense>`-throwing convention. Wrap in `<Streamed>` (or
- * `<Suspense>` from `preact/compat`).
- *
- * ```tsx
- * <Streamed fallback={<Spinner />}>
- *   <Await<Review[]> name="reviews">
- *     {(reviews) => <ReviewList items={reviews} />}
- *   </Await>
- * </Streamed>
- * ```
- */
-export function Await<T = unknown>({
-  name,
-  children,
-}: AwaitProps<T>): ComponentChildren {
-  const promise = useDeferred<T>(name);
-  const tracked = track(promise);
-
-  if (tracked.status === "fulfilled") {
-    return children(tracked.value as T);
-  }
-
-  if (tracked.status === "rejected") {
-    throw tracked.reason;
-  }
-
-  // Suspense catches the thrown thenable and waits for resolution. ESLint
-  // complains because Promises aren't Errors, but Preact's Suspense (like
-  // React's pre-`use()` Suspense convention) explicitly expects a thenable.
-  // eslint-disable-next-line @typescript-eslint/only-throw-error -- Suspense thenable convention
-  throw promise;
-}

package/src/components/ClientOnly.tsx

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

package/src/components/HttpStatusCode.tsx

@@ -1,82 +0,0 @@
-import { useContext } from "preact/hooks";
-
-import { HttpStatusContext } from "./HttpStatusProvider";
-
-import type { ComponentChildren } from "preact";
-
-export interface HttpStatusCodeProps {
-  /** HTTP status to apply to the response. Common values: 404, 410, 451, 503. */
-  readonly code: number;
-}
-
-/**
- * Render-time HTTP status declaration. Mount inside a route component (typical
- * use case: a glob `*` route's NotFound page) when the status is decided by
- * the rendered tree rather than a loader.
- *
- * Writes `code` to the nearest `<HttpStatusProvider>`'s sink during render and
- * returns `null`. With no provider mounted (the standard client-side case)
- * the component is a silent no-op — same component tree hydrates without
- * touching the DOM or warning about mismatches.
- *
- * Loader-driven errors (`LoaderNotFound` → 404, `LoaderRedirect` → 30x) keep
- * working as before; this component covers render-time decisions only.
- *
- * Last write wins when several `<HttpStatusCode />` instances mount in the
- * same render pass — sink reflects the last component that ran.
- *
- * ```tsx
- * // entry-server.tsx
- * import { renderToString } from "preact-render-to-string";
- * import { createHttpStatusSink, HttpStatusProvider } from "@real-router/preact/ssr";
- *
- * const sink = createHttpStatusSink();
- * const html = renderToString(
- *   <HttpStatusProvider sink={sink}>
- *     <RouterProvider router={router}>
- *       <App />
- *     </RouterProvider>
- *   </HttpStatusProvider>,
- * );
- * response.status(sink.code ?? 200).send(html);
- * ```
- *
- * **Streaming SSR (`renderToReadableStream`):** the response status MUST be
- * sent before the first body byte flushes. If `<HttpStatusCode />` is mounted
- * inside a late-resolving `<Suspense>` boundary, the sink write may happen
- * AFTER the headers are already on the wire — the override is then lost.
- * Mount the component in the shell (above every `<Suspense>` that could
- * delay it). For non-streaming SSR (`renderToString` / `renderToStringAsync`)
- * there is no such ordering concern.
- *
- * **Valid `code` range:** Node's `res.end()` throws `Invalid status code` on
- * `NaN`, `0`, negative values, or values `> 999` — this surfaces as a 5xx /
- * dropped connection, not silent corruption. Pass a real HTTP status integer
- * (commonly 4xx/5xx; 100-999 is what Node accepts).
- */
-export function HttpStatusCode({
-  code,
-}: HttpStatusCodeProps): ComponentChildren {
-  const sink = useContext(HttpStatusContext);
-
-  if (sink) {
-    // Dev-only validation: Node's `res.end()` throws `Invalid status code` on
-    // NaN / 0 / negative / non-integer / >999. Surface the bad value at the
-    // source so the consumer can fix the routing logic, instead of waiting
-    // for the server to crash mid-response. Production builds (Vite, esbuild,
-    // tsdown all replace `process.env.NODE_ENV !== "production"` with `false`)
-    // strip the check.
-    if (
-      process.env.NODE_ENV !== "production" &&
-      (!Number.isInteger(code) || code < 100 || code > 999)
-    ) {
-      console.error(
-        `[real-router] <HttpStatusCode code={${String(code)}} /> received an invalid HTTP status code. Node's res.end() rejects values that are not an integer in [100, 999] — pass a real HTTP status (commonly 4xx/5xx).`,
-      );
-    }
-
-    sink.code = code;
-  }
-
-  return null;
-}

package/src/components/HttpStatusProvider.tsx

@@ -1,22 +0,0 @@
-import { createContext } from "preact";
-
-import type { HttpStatusSink } from "../utils/createHttpStatusSink";
-import type { ComponentChildren } from "preact";
-
-export const HttpStatusContext = createContext<HttpStatusSink | null>(null);
-
-export interface HttpStatusProviderProps {
-  readonly sink: HttpStatusSink;
-  readonly children: ComponentChildren;
-}
-
-export function HttpStatusProvider({
-  sink,
-  children,
-}: HttpStatusProviderProps): ComponentChildren {
-  return (
-    <HttpStatusContext.Provider value={sink}>
-      {children}
-    </HttpStatusContext.Provider>
-  );
-}

package/src/components/Link.tsx

@@ -1,141 +0,0 @@
-import { memo } from "preact/compat";
-
-import { EMPTY_PARAMS, EMPTY_OPTIONS } from "../constants";
-import {
-  shouldNavigate,
-  buildHref,
-  buildActiveClassName,
-  navigateWithHash,
-  shallowEqual,
-} from "../dom-utils";
-import { useIsActiveRoute } from "../hooks/useIsActiveRoute";
-import { useRouter } from "../hooks/useRouter";
-
-import type { LinkProps } from "../types";
-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>,
-): boolean {
-  return (
-    prev.routeName === next.routeName &&
-    prev.className === next.className &&
-    prev.activeClassName === next.activeClassName &&
-    prev.activeStrict === next.activeStrict &&
-    prev.ignoreQueryParams === next.ignoreQueryParams &&
-    prev.onClick === next.onClick &&
-    prev.target === next.target &&
-    prev.style === next.style &&
-    prev.children === next.children &&
-    prev.hash === next.hash &&
-    shallowEqual(prev.routeParams, next.routeParams) &&
-    shallowEqual(prev.routeOptions, next.routeOptions)
-  );
-}
-
-export const Link: FunctionComponent<LinkProps> = memo(
-  ({
-    routeName,
-    routeParams = EMPTY_PARAMS,
-    routeOptions = EMPTY_OPTIONS,
-    className,
-    activeClassName = "active",
-    activeStrict = false,
-    ignoreQueryParams = true,
-    hash,
-    onClick,
-    target,
-    children,
-    ...props
-  }) => {
-    const router = useRouter();
-
-    // memo + areLinkPropsEqual guarantees that on bail-out the component does
-    // not render; on render, routeParams/routeOptions changed reference (true
-    // change caught by shallowEqual), so they're safe to use directly in hook
-    // deps without useStableValue.
-
-    // Hash-aware active (#532) — see useIsActiveRoute for the contract.
-    const isActive = useIsActiveRoute(
-      routeName,
-      routeParams,
-      activeStrict,
-      ignoreQueryParams,
-      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 = (evt: TargetedMouseEvent<HTMLAnchorElement>): void => {
-      if (onClick) {
-        onClick(evt);
-
-        if (evt.defaultPrevented) {
-          return;
-        }
-      }
-
-      if (!shouldNavigate(evt) || target === "_blank") {
-        return;
-      }
-
-      evt.preventDefault();
-      navigateWithHash(
-        router,
-        routeName,
-        routeParams,
-        hash,
-        routeOptions,
-      ).catch(() => {});
-    };
-
-    const finalClassName = buildActiveClassName(
-      isActive,
-      activeClassName,
-      className,
-    );
-
-    return (
-      <a
-        {...props}
-        href={href}
-        className={finalClassName}
-        onClick={handleClick}
-      >
-        {children}
-      </a>
-    );
-  },
-  areLinkPropsEqual,
-);
-
-Link.displayName = "Link";

package/src/components/RouteView/RouteView.tsx

@@ -1,57 +0,0 @@
-import { useMemo } from "preact/hooks";
-
-import { Match, NotFound, Self } from "./components";
-import { buildRenderList, collectElements } from "./helpers";
-import { useRouteNode } from "../../hooks/useRouteNode";
-
-import type { RouteViewProps } from "./types";
-import type { VNode } from "preact";
-
-function RouteViewRoot({
-  nodeName,
-  children,
-}: Readonly<RouteViewProps>): VNode | null {
-  const { route } = useRouteNode(nodeName);
-
-  // Cache the flattened Match/Self/NotFound list across renders with unchanged
-  // children. children only differs when the parent re-renders with a new
-  // node, so this memoises the steady-state traversal.
-  const elements = useMemo(() => {
-    const collected: VNode[] = [];
-
-    collectElements(children, collected);
-
-    return collected;
-  }, [children]);
-
-  const routeName = route?.name;
-
-  // 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 [];
-    }
-
-    return buildRenderList(elements, routeName, nodeName).rendered;
-  }, [elements, routeName, nodeName]);
-
-  return rendered.length > 0 ? <>{rendered}</> : null;
-}
-
-RouteViewRoot.displayName = "RouteView";
-
-export const RouteView = Object.assign(RouteViewRoot, {
-  Match,
-  Self,
-  NotFound,
-});
-
-export type {
-  RouteViewProps,
-  MatchProps as RouteViewMatchProps,
-  SelfProps as RouteViewSelfProps,
-  NotFoundProps as RouteViewNotFoundProps,
-} from "./types";

package/src/components/RouteView/components.tsx

@@ -1,19 +0,0 @@
-import type { MatchProps, NotFoundProps, SelfProps } from "./types";
-
-export function Match(_props: MatchProps): null {
-  return null;
-}
-
-Match.displayName = "RouteView.Match";
-
-export function Self(_props: SelfProps): null {
-  return null;
-}
-
-Self.displayName = "RouteView.Self";
-
-export function NotFound(_props: NotFoundProps): null {
-  return null;
-}
-
-NotFound.displayName = "RouteView.NotFound";