@real-router/preact 0.15.1 → 0.15.3

package/src/components/RouteView/helpers.tsx

@@ -1,176 +0,0 @@
-import { UNKNOWN_ROUTE } from "@real-router/core";
-import { startsWithSegment } from "@real-router/route-utils";
-import { Fragment, isValidElement, toChildArray } from "preact";
-import { Suspense } from "preact/compat";
-
-import { Match, NotFound, Self } from "./components";
-
-import type { MatchProps, NotFoundProps, SelfProps } from "./types";
-import type { VNode, ComponentChildren } from "preact";
-
-interface FallbackSlots {
-  selfChildren: ComponentChildren;
-  selfFallback: ComponentChildren | undefined;
-  selfFound: boolean;
-  notFoundChildren: ComponentChildren;
-}
-
-function isSegmentMatch(
-  routeName: string,
-  fullSegmentName: string,
-  exact: boolean,
-): boolean {
-  if (fullSegmentName === "") {
-    return false;
-  }
-
-  if (exact) {
-    return routeName === fullSegmentName;
-  }
-
-  return startsWithSegment(routeName, fullSegmentName);
-}
-
-export function collectElements(
-  children: ComponentChildren,
-  result: VNode[],
-): void {
-  for (const child of toChildArray(children)) {
-    if (!isValidElement(child)) {
-      continue;
-    }
-
-    if (
-      child.type === Match ||
-      child.type === Self ||
-      child.type === NotFound
-    ) {
-      result.push(child);
-    } else {
-      collectElements(
-        (child.props as { readonly children: ComponentChildren }).children,
-        result,
-      );
-    }
-  }
-}
-
-function renderSlot(
-  slotChildren: ComponentChildren,
-  key: string,
-  fallback?: ComponentChildren,
-): VNode {
-  const content =
-    fallback === undefined ? (
-      slotChildren
-    ) : (
-      <Suspense fallback={fallback}>{slotChildren}</Suspense>
-    );
-
-  return <Fragment key={key}>{content}</Fragment>;
-}
-
-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;
-  }
-
-  if (!slots.selfFound) {
-    slots.selfChildren = (child.props as SelfProps).children;
-    slots.selfFallback = (child.props as SelfProps).fallback;
-    slots.selfFound = true;
-  }
-}
-
-function processMatch(
-  child: VNode,
-  routeName: string,
-  nodeName: string,
-  alreadyActive: boolean,
-): VNode | null {
-  const {
-    segment,
-    exact = false,
-    fallback,
-    children,
-  } = child.props as MatchProps;
-  const fullSegmentName = nodeName ? `${nodeName}.${segment}` : segment;
-  const isActive =
-    !alreadyActive && isSegmentMatch(routeName, fullSegmentName, exact);
-
-  if (!isActive) {
-    return null;
-  }
-
-  return renderSlot(children, fullSegmentName, fallback);
-}
-
-function appendFallback(
-  rendered: VNode[],
-  routeName: string,
-  nodeName: string,
-  slots: FallbackSlots,
-): void {
-  if (slots.selfFound && routeName === nodeName) {
-    rendered.push(
-      renderSlot(slots.selfChildren, "__route-view-self__", slots.selfFallback),
-    );
-
-    return;
-  }
-
-  if (routeName === UNKNOWN_ROUTE && slots.notFoundChildren !== null) {
-    rendered.push(
-      <Fragment key="__route-view-not-found__">
-        {slots.notFoundChildren}
-      </Fragment>,
-    );
-  }
-}
-
-export function buildRenderList(
-  elements: VNode[],
-  routeName: string,
-  nodeName: string,
-): { rendered: VNode[]; activeMatchFound: boolean } {
-  const slots: FallbackSlots = {
-    selfChildren: null,
-    selfFallback: undefined,
-    selfFound: false,
-    notFoundChildren: null,
-  };
-  let activeMatchFound = false;
-  const rendered: VNode[] = [];
-
-  for (const child of elements) {
-    if (isFallbackKind(child)) {
-      assignFallbackSlot(child, slots);
-
-      continue;
-    }
-
-    const matchRendered = processMatch(
-      child,
-      routeName,
-      nodeName,
-      activeMatchFound,
-    );
-
-    if (matchRendered !== null) {
-      activeMatchFound = true;
-      rendered.push(matchRendered);
-    }
-  }
-
-  if (!activeMatchFound) {
-    appendFallback(rendered, routeName, nodeName, slots);
-  }
-
-  return { rendered, activeMatchFound };
-}

package/src/components/RouteView/index.ts

@@ -1,8 +0,0 @@
-export { RouteView } from "./RouteView";
-
-export type {
-  RouteViewProps,
-  RouteViewMatchProps,
-  RouteViewSelfProps,
-  RouteViewNotFoundProps,
-} from "./RouteView";

package/src/components/RouteView/types.ts

@@ -1,24 +0,0 @@
-import type { ComponentChildren } from "preact";
-
-export interface RouteViewProps {
-  readonly nodeName: string;
-  readonly children: ComponentChildren;
-}
-
-export interface MatchProps {
-  readonly segment: string;
-  readonly exact?: boolean;
-  readonly fallback?: ComponentChildren;
-  readonly children: ComponentChildren;
-}
-
-export interface SelfProps {
-  /** Fallback content while children are suspended. */
-  readonly fallback?: ComponentChildren;
-  /** Content to render when the active route name equals the parent RouteView's nodeName. */
-  readonly children: ComponentChildren;
-}
-
-export interface NotFoundProps {
-  readonly children: ComponentChildren;
-}

package/src/components/RouterErrorBoundary.tsx

@@ -1,84 +0,0 @@
-import { createDismissableError } from "@real-router/sources";
-import { Fragment } from "preact";
-import { useEffect, useLayoutEffect, useRef } from "preact/hooks";
-
-import { useRouter } from "../hooks/useRouter";
-import { useSyncExternalStore } from "../useSyncExternalStore";
-
-import type { RouterError, State } from "@real-router/core";
-import type { ComponentChildren, VNode } from "preact";
-
-export interface RouterErrorBoundaryProps {
-  readonly children: ComponentChildren;
-  readonly fallback: (
-    error: RouterError,
-    resetError: () => void,
-  ) => ComponentChildren;
-  readonly onError?: (
-    error: RouterError,
-    toRoute: State | null,
-    fromRoute: State | null,
-  ) => 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,
-    store.getSnapshot,
-    store.getSnapshot,
-  );
-
-  const onErrorRef = useRef(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?.(
-        snapshot.error,
-        snapshot.toRoute,
-        snapshot.fromRoute,
-      );
-    }
-    // eslint-disable-next-line @eslint-react/exhaustive-deps -- onError tracked via ref, snapshot fields accessed inside callback
-  }, [snapshot.version]);
-
-  return (
-    <Fragment>
-      {children}
-      {snapshot.error ? fallback(snapshot.error, snapshot.resetError) : null}
-    </Fragment>
-  );
-}

package/src/components/ServerOnly.tsx

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

@@ -1,24 +0,0 @@
-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/constants.ts

@@ -1,9 +0,0 @@
-/**
- * Stable empty object for default params
- */
-export const EMPTY_PARAMS = Object.freeze({});
-
-/**
- * Stable empty options object
- */
-export const EMPTY_OPTIONS = Object.freeze({});

package/src/context.ts

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

@@ -1,26 +0,0 @@
-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,46 +0,0 @@
-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,
-  params?: Params,
-  strict = false,
-  ignoreQueryParams = true,
-  hash?: string,
-): boolean {
-  const router = useRouter();
-
-  // createActiveRouteSource is per-router + canonical-args cached in
-  // @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(
-    store.subscribe,
-    store.getSnapshot,
-    store.getSnapshot,
-  );
-}

package/src/hooks/useNavigator.tsx

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

package/src/hooks/useRoute.tsx

@@ -1,26 +0,0 @@
-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 = useRouteContextOrThrow();
-
-  if (!routeContext.route) {
-    throw new Error(
-      "useRoute called with no active route. Did you forget to await router.start() before rendering, or is the router stopped/disposed?",
-    );
-  }
-
-  return routeContext as Omit<RouteContextType<P>, "route"> & {
-    route: State<P>;
-  };
-};

package/src/hooks/useRouteEnter.tsx

@@ -1,147 +0,0 @@
-import { useEffect, useLayoutEffect, useRef } from "preact/hooks";
-
-import { useRoute } from "./useRoute";
-
-import type { State } from "@real-router/core";
-
-export interface RouteEnterContext {
-  /** The route that was just activated. */
-  route: State;
-  /** The route that was active immediately before this navigation. */
-  previousRoute: State;
-}
-
-export type RouteEnterHandler = (context: RouteEnterContext) => void;
-
-export 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 ad-hoc `useEffect` + `useRoute()` doesn't:
- *
- *   - **Skip-initial**: handler is skipped when there is no
- *     `previousRoute` (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.name === previousRoute.name`. Sort/filter/query-only
- *     navigations re-run the effect (because `route` reference changes
- *     in `useRoute`'s snapshot), but they are not "entries" in the
- *     animation / analytics sense — the component instance has stayed
- *     mounted throughout. Opt out with `skipSameRoute: false` when
- *     the handler legitimately needs to fire on every navigation
- *     (e.g. analytics tracking each query-param flip).
- *   - **Latest-handler ref**: the handler can change identity on every
- *     render without re-running the effect — the registered wrapper
- *     dispatches to whatever `handlerRef.current` points to.
- *   - **Mount-time `route` / `previousRoute` snapshot**: the handler
- *     receives the values that were live at the moment of mount, not
- *     the latest ones (which may have moved on if the user navigated
- *     again before the effect drained).
- *
- * Race-safety: `useRoute()` is wired through `useSyncExternalStore` from
- * `@real-router/sources` (Preact polyfill: useState + useEffect, same
- * post-commit semantics), so by the time the new component's effect
- * runs, the snapshot is the post-commit one. This is the reason we can
- * read mount-time context from `useRoute()` instead of subscribing to
- * `router.subscribe` directly (which fires before Preact schedules a
- * re-render — the well-known race in distributed components).
- *
- * Note: Preact does not expose a `StrictMode` equivalent, so the
- * `lastHandledRouteRef` guard exists primarily for defensive symmetry
- * with the React implementation. It is harmless in Preact.
- *
- * @example Direction-aware entry animation
- * ```tsx
- * useRouteEnter(({ route }) => {
- *   const direction = route.context.browser?.direction;
- *   ref.current?.classList.add(
- *     direction === "back" ? "slide-from-left" : "slide-from-right",
- *   );
- * });
- * ```
- *
- * @example Source-aware focus management
- * ```tsx
- * useRouteEnter(({ route }) => {
- *   if (route.context.browser?.source === "navigate") {
- *     headingRef.current?.focus();
- *   }
- * });
- * ```
- *
- * @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 }) => {
- *   // route.transition: TransitionMeta — populated by core for every state
- *   if (route.transition.redirected) {
- *     showToast(`Redirected from ${route.transition.from}`);
- *   }
- *   if (route.transition.segments.activated.includes("products")) {
- *     // products subtree just became active (could be products or
- *     // products.detail). Useful for subtree-scoped side effects.
- *   }
- * });
- * ```
- */
-export function useRouteEnter(
-  handler: RouteEnterHandler,
-  options?: UseRouteEnterOptions,
-): void {
-  const { route, previousRoute } = useRoute();
-  const handlerRef = useRef(handler);
-  const lastHandledRouteRef = useRef<State | null>(null);
-  const skipSameRoute = options?.skipSameRoute ?? true;
-
-  // Keep the latest handler reference accessible without re-running
-  // the effect. useLayoutEffect (synchronous, post-render, pre-paint)
-  // updates the ref before the effect can read it.
-  useLayoutEffect(() => {
-    handlerRef.current = handler;
-  });
-
-  useEffect(() => {
-    // Early-exit guards, top-down:
-    //
-    //   - **Skip-initial**: `state.transition.from` is undefined only
-    //     for the very first state committed by `router.start()`.
-    //   - **Skip-same-route**: query-only navigations have
-    //     `transition.from === route.name`. Opt-out via
-    //     `skipSameRoute: false`.
-    //   - **Defensive dedupe**: same `route` ref between effect
-    //     cleanup + re-run. Preact has no StrictMode, but we keep the
-    //     guard for parity with React; v8-ignored.
-    if (!route.transition.from) {
-      return;
-    }
-    if (skipSameRoute && route.transition.from === route.name) {
-      return;
-    }
-    /* v8 ignore start */
-    if (lastHandledRouteRef.current === route || !previousRoute) {
-      return;
-    }
-    /* v8 ignore stop */
-
-    lastHandledRouteRef.current = route;
-    handlerRef.current({ route, previousRoute });
-  }, [route, previousRoute, skipSameRoute]);
-}