@real-router/solid 0.14.2 → 0.14.4

package/src/components/RouterErrorBoundary.tsx

@@ -1,45 +0,0 @@
-import { createDismissableError } from "@real-router/sources";
-import { createEffect, Show } from "solid-js";
-
-import { createSignalFromSource } from "../createSignalFromSource";
-import { useRouter } from "../hooks/useRouter";
-
-import type { RouterError, State } from "@real-router/core";
-import type { JSX } from "solid-js";
-
-export interface RouterErrorBoundaryProps {
-  readonly children: JSX.Element;
-  readonly fallback: (
-    error: RouterError,
-    resetError: () => void,
-  ) => JSX.Element;
-  readonly onError?: (
-    error: RouterError,
-    toRoute: State | null,
-    fromRoute: State | null,
-  ) => void;
-}
-
-export function RouterErrorBoundary(
-  props: RouterErrorBoundaryProps,
-): JSX.Element {
-  const router = useRouter();
-  const snapshot = createSignalFromSource(createDismissableError(router));
-
-  createEffect(() => {
-    const snap = snapshot();
-
-    if (snap.error) {
-      props.onError?.(snap.error, snap.toRoute, snap.fromRoute);
-    }
-  });
-
-  return (
-    <>
-      {props.children}
-      <Show when={snapshot().error}>
-        {(error) => props.fallback(error(), snapshot().resetError)}
-      </Show>
-    </>
-  );
-}

package/src/components/ServerOnly.tsx

@@ -1,20 +0,0 @@
-import { Show } from "solid-js";
-
-import { createMountedSignal } from "../utils/createMountedSignal";
-
-import type { JSX } from "solid-js";
-
-export interface ServerOnlyProps {
-  readonly children: JSX.Element;
-  readonly fallback?: JSX.Element;
-}
-
-export function ServerOnly(props: ServerOnlyProps): JSX.Element {
-  const mounted = createMountedSignal();
-
-  return (
-    <Show when={mounted()} fallback={props.children}>
-      {props.fallback}
-    </Show>
-  );
-}

package/src/components/Streamed.tsx

@@ -1,23 +0,0 @@
-import { Suspense } from "solid-js";
-
-import type { JSX } from "solid-js";
-
-export interface StreamedProps {
-  /** Shown while any descendant `<Await>` / `createResource` suspends. */
-  readonly fallback: JSX.Element;
-  readonly children: JSX.Element;
-}
-
-/**
- * Cross-adapter alias for Solid's `<Suspense fallback={…}>`. Symmetric naming
- * with the React/Preact/Svelte/Vue/Angular `<Streamed>` components — pick
- * `<Streamed>` for cross-framework consistency, or use Solid's native
- * `<Suspense>` directly when team conventions prefer that.
- *
- * Solid's `<Suspense>` is a built-in primitive; out-of-order resolution +
- * splice scripts during `renderToStream` are part of the runtime. See
- * Solid's SSR docs for the wire-format details.
- */
-export function Streamed(props: StreamedProps): JSX.Element {
-  return <Suspense fallback={props.fallback}>{props.children}</Suspense>;
-}

package/src/constants.ts

@@ -1,27 +0,0 @@
-/**
- * Stable empty object for default params.
- *
- * `Object.freeze` makes mutation throw under ESM strict mode — this guards
- * against accidental writes that would corrupt the shared default across
- * every Link without explicit params.
- *
- * §8.1 audit note (LOW #19): consumers cast `EMPTY_PARAMS as P` at usage
- * sites (e.g. `Link.tsx`, `directives/link.tsx`). The cast is required for
- * type compatibility with the generic `P extends Params` and DOES technically
- * widen the `Readonly<{}>` type, but the underlying object stays frozen at
- * runtime — any attempt to mutate fails at the JS engine level regardless
- * of TS-level visibility. The frozen sentinel is also used by Link's
- * fast-path identity check (`props.routeParams === undefined` after the
- * §8.1 audit fix); changing this object's identity would silently break
- * that path.
- */
-export const EMPTY_PARAMS = Object.freeze({});
-
-/**
- * Stable empty options object.
- *
- * Same freeze/cast guarantees as `EMPTY_PARAMS` — the sentinel is shared
- * across all default `routeOptions` consumers (`Link`, `use:link`) to
- * avoid per-render `{}` allocations.
- */
-export const EMPTY_OPTIONS = Object.freeze({});

package/src/context.ts

@@ -1,35 +0,0 @@
-import { createContext, useContext } from "solid-js";
-
-import type { RouteState } from "./types";
-import type { Router, Navigator } from "@real-router/core";
-import type { Accessor } from "solid-js";
-
-export interface RouterContextValue {
-  router: Router;
-  navigator: Navigator;
-  routeSelector: (routeName: string) => boolean;
-}
-
-export const RouterContext = createContext<RouterContextValue | null>(null);
-
-export const RouteContext = createContext<Accessor<RouteState> | null>(null);
-
-/**
- * Read the required RouterContext or throw a labelled error. Internal helper
- * — consolidates 4 copies of the same `useContext + null-check + throw`
- * block across the public hooks/components/directives. The `consumerName`
- * parameter keeps each callsite's error message specific (so the consumer
- * sees "useRouter must be used within a RouterProvider", not a generic
- * "context missing" message).
- */
-export function useRequiredRouterContext(
-  consumerName: string,
-): RouterContextValue {
-  const ctx = useContext(RouterContext);
-
-  if (!ctx) {
-    throw new Error(`${consumerName} must be used within a RouterProvider`);
-  }
-
-  return ctx;
-}

package/src/createSignalFromSource.ts

@@ -1,71 +0,0 @@
-import { createSignal, onCleanup } from "solid-js";
-
-import type { RouterSource } from "@real-router/sources";
-import type { Accessor } from "solid-js";
-
-export function createSignalFromSource<T>(
-  source: RouterSource<T>,
-): Accessor<T> {
-  // Mini-sprint E.5 (audit-5 §4.2 #7) — defensive init-phase snapshot
-  // reads. A throwing `getSnapshot()` during construction would
-  // propagate up through `createSignal<T>(...)` (or the post-subscribe
-  // re-sync below) into the reactive owner, tearing down the entire
-  // RouterProvider subtree (and any siblings sharing the owner). Catch
-  // + log + fall back to `undefined` (initial) or skip-update (post-
-  // subscribe re-sync) so the accessor still constructs; the next
-  // emit refreshes the value.
-  //
-  // Post-init emit-time throws are NOT wrapped — they bubble to Solid's
-  // `<ErrorBoundary>` (or surface as unhandled errors in dev) so
-  // genuine source bugs aren't silently masked.
-  let initial: T;
-
-  try {
-    initial = source.getSnapshot();
-  } catch (error) {
-    console.error(
-      "[real-router] createSignalFromSource: initial getSnapshot threw — accessor defaulting to undefined.",
-      error,
-    );
-    initial = undefined as T;
-  }
-
-  const [value, setValue] = createSignal<T>(initial);
-
-  // `sync` is a stable reference (defined once at outer scope) so the
-  // subscribe callback below does not re-allocate it per emit. Solid's
-  // `setValue(fn)` treats fn as an updater `(prev) => next`; our updater
-  // ignores `prev` and reads the latest snapshot fresh, which gives a
-  // function-form micro-allocation cost (one extra fn call per emit) BUT
-  // a much smaller TS surface than the `setValue(value)` direct form —
-  // that overload is typed `Exclude<T, Function>`, requiring per-call
-  // `as Exclude<T, (...args: never[]) => unknown>` casts for generic T.
-  // The micro-opt is not worth the cast complexity.
-  // See §8.2 audit note.
-  const sync = (): T => source.getSnapshot();
-
-  const unsubscribe = source.subscribe(() => {
-    setValue(sync);
-  });
-
-  // Re-read after subscribe: lazy sources reconcile their snapshot in
-  // onFirstSubscribe (when reused after disconnect via cache). Listener
-  // is not notified for that internal update, so we must sync manually.
-  // No-op when snapshot is unchanged (signal equality check). Wrapped
-  // because this is still init-phase: a throw here ALSO tears down the
-  // owner, same as the initial read above.
-  try {
-    setValue(sync);
-  } catch (error) {
-    console.error(
-      "[real-router] createSignalFromSource: post-subscribe getSnapshot threw — accessor retains initial value.",
-      error,
-    );
-  }
-
-  onCleanup(() => {
-    unsubscribe();
-  });
-
-  return value;
-}

package/src/createStoreFromSource.ts

@@ -1,65 +0,0 @@
-import { onCleanup } from "solid-js";
-import { createStore, reconcile } from "solid-js/store";
-
-import type { RouterSource } from "@real-router/sources";
-
-/**
- * Bridges a `RouterSource<T>` into a Solid store (`createStore` + `reconcile`).
- *
- * Unlike `createSignalFromSource` (whole-value replacement via `===`), this
- * bridge uses `reconcile` on every emit so **unchanged nested paths retain
- * their object identity**. Components that read only `state.route.name` will
- * not re-run when `state.route.params` changes — granular reactivity without
- * manual memoisation.
- *
- * **Ownership**: calls `onCleanup` — must be called inside a reactive owner
- * (component body or `createRoot`). Same contract as `createSignalFromSource`.
- *
- * **Lazy-source re-sync**: after `source.subscribe()`, a cached lazy source
- * may reconcile its snapshot in `onFirstSubscribe`. The listener is not
- * notified for that internal update, so we re-read immediately after
- * subscribing (`setState(reconcile(source.getSnapshot()))`) — mirrors the
- * same pattern in `createSignalFromSource`. `reconcile` is a no-op when the
- * snapshot is structurally unchanged, so there is no spurious reactivity cost.
- */
-export function createStoreFromSource<T extends object>(
-  source: RouterSource<T>,
-): T {
-  const initialSnapshot = source.getSnapshot();
-  const [state, setState] = createStore<T>({ ...initialSnapshot });
-
-  // Track the last reconciled snapshot reference to short-circuit redundant
-  // `reconcile` calls. Cached lazy sources (e.g. `createRouteNodeSource`)
-  // stabilize their snapshot — the same reference flows through multiple
-  // emits when nothing in the node's slice changed. `reconcile` itself
-  // handles identity (no-ops on structurally-equal input), but a reference
-  // check is cheaper than the structural walk and avoids the function call
-  // entirely on every navigation × N store consumers (§8b H10 audit fix).
-  let lastSnapshot: T = initialSnapshot;
-
-  const unsubscribe = source.subscribe(() => {
-    const nextSnapshot = source.getSnapshot();
-
-    if (nextSnapshot === lastSnapshot) {
-      return;
-    }
-
-    lastSnapshot = nextSnapshot;
-    setState(reconcile(nextSnapshot));
-  });
-
-  // Re-read after subscribe: lazy sources reconcile their snapshot in
-  // onFirstSubscribe (when reused after disconnect via cache). The listener
-  // is not notified for that internal update, so we must reconcile manually.
-  // Guarded by the same reference check so a no-op stays free.
-  const afterSubscribe = source.getSnapshot();
-
-  if (afterSubscribe !== lastSnapshot) {
-    lastSnapshot = afterSubscribe;
-    setState(reconcile(afterSubscribe));
-  }
-
-  onCleanup(unsubscribe);
-
-  return state;
-}

package/src/directives/link.tsx

@@ -1,111 +0,0 @@
-import { createActiveRouteSource } from "@real-router/sources";
-import { createEffect, onCleanup } from "solid-js";
-
-import { EMPTY_PARAMS, EMPTY_OPTIONS } from "../constants";
-import { createSignalFromSource } from "../createSignalFromSource";
-import { shouldNavigate, applyLinkA11y, buildHref } from "../dom-utils";
-import { useRouter } from "../hooks/useRouter";
-
-import type { Params } from "@real-router/core";
-
-export interface LinkDirectiveOptions<P extends Params = Params> {
-  routeName: string;
-  routeParams?: P;
-  routeOptions?: Record<string, unknown>;
-  activeClassName?: string;
-  activeStrict?: boolean;
-  ignoreQueryParams?: boolean;
-}
-
-export function link<P extends Params = Params>(
-  element: HTMLElement,
-  accessor: () => LinkDirectiveOptions<P>,
-): void {
-  const router = useRouter();
-  const options = accessor();
-
-  // audit-2026-05-17 §8a cleanup — single instanceof probe, single EMPTY_PARAMS
-  // default. Previously evaluated three times for the <a>-only branches and
-  // twice for routeParams. The directive accessor is read once at init
-  // (documented "use:link Options Are Captured Once"), so both lookups are
-  // stable and worth hoisting.
-  const anchor = element instanceof HTMLAnchorElement ? element : null;
-  const resolvedRouteParams = (options.routeParams ?? EMPTY_PARAMS) as P;
-  const resolvedRouteOptions = options.routeOptions ?? EMPTY_OPTIONS;
-
-  // Set href on <a> elements
-  if (anchor) {
-    const href = buildHref(router, options.routeName, resolvedRouteParams);
-
-    if (href === undefined) {
-      anchor.removeAttribute("href");
-    } else {
-      anchor.href = href;
-    }
-  }
-
-  applyLinkA11y(element);
-
-  // Active class tracking: only `isActive` is reactive (createEffect toggles
-  // the class on each emit). The `options` object itself is captured ONCE at
-  // init (see gotcha "use:link Options Are Captured Once") — changing
-  // `activeClassName` / `routeName` / `routeParams` later has no effect.
-  if (options.activeClassName) {
-    const activeClassName = options.activeClassName;
-    const activeSource = createActiveRouteSource(
-      router,
-      options.routeName,
-      resolvedRouteParams,
-      {
-        strict: options.activeStrict ?? false,
-        ignoreQueryParams: options.ignoreQueryParams ?? true,
-      },
-    );
-    const isActive = createSignalFromSource(activeSource);
-
-    createEffect(() => {
-      element.classList.toggle(activeClassName, isActive());
-    });
-  }
-
-  // Click handler
-  function handleClick(evt: MouseEvent) {
-    if (!shouldNavigate(evt)) {
-      return;
-    }
-
-    // Mini-sprint E.2 (audit-5 §4.2 #2) — respect upstream
-    // preventDefault. `<Link>` checks `local.onClick(evt); if
-    // (evt.defaultPrevented) return;` because it owns the React-style
-    // onClick prop. The directive has no equivalent prop, but the
-    // consumer may register their OWN click listener on the same
-    // element (DOM event order is "addEventListener queue, in
-    // registration order"). If their listener called preventDefault
-    // to opt-out of navigation, the directive must honour that.
-    if (evt.defaultPrevented) {
-      return;
-    }
-
-    // Symmetric with <Link> (#P0.6 audit): on an <a target="_blank"> the
-    // browser opens the URL in a new tab/window natively. Intercepting the
-    // click via preventDefault + router.navigate would suppress the new
-    // tab and silently keep the user on the current page.
-    if (anchor?.target === "_blank") {
-      return;
-    }
-
-    if (anchor) {
-      evt.preventDefault();
-    }
-
-    router
-      .navigate(options.routeName, resolvedRouteParams, resolvedRouteOptions)
-      .catch(() => {});
-  }
-
-  element.addEventListener("click", handleClick);
-
-  onCleanup(() => {
-    element.removeEventListener("click", handleClick);
-  });
-}

package/src/directives.d.ts

@@ -1,10 +0,0 @@
-import type { LinkDirectiveOptions } from "./directives/link";
-
-declare module "solid-js" {
-  // eslint-disable-next-line @typescript-eslint/no-namespace
-  namespace JSX {
-    interface Directives {
-      link: LinkDirectiveOptions | undefined;
-    }
-  }
-}

package/src/hooks/useDeferred.tsx

@@ -1,36 +0,0 @@
-import { useRoute } from "./useRoute";
-
-import type { Accessor } from "solid-js";
-
-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.
- *
- * Returns a Solid `Accessor<Promise<T>>` so the value tracks the active route
- * — re-reading on navigation picks up the new state's deferred map. Wrap with
- * `<Await name="key">{(value) => …}</Await>` (this package), which builds on
- * `createResource` + `<Suspense>` for native Solid streaming.
- *
- * Returns a forever-pending promise when the key is missing — surfaces
- * loader/consumer key drift as a visible Suspense fallback rather than a
- * silent runtime error.
- */
-export function useDeferred<T = unknown>(key: string): Accessor<Promise<T>> {
-  const routeAccessor = useRoute();
-
-  return () => {
-    const context = routeAccessor().route.context as DeferredContext;
-    const deferred = context.ssrDataDeferred;
-
-    return (deferred?.[key] ?? NEVER_PROMISE) as Promise<T>;
-  };
-}

package/src/hooks/useNavigator.tsx

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

package/src/hooks/useRoute.tsx

@@ -1,27 +0,0 @@
-import { useContext } from "solid-js";
-
-import { RouteContext } from "../context";
-
-import type { RouteState } from "../types";
-import type { Params, State } from "@real-router/core";
-import type { Accessor } from "solid-js";
-
-export const useRoute = <P extends Params = Params>(): Accessor<
-  Omit<RouteState<P>, "route"> & { route: State<P> }
-> => {
-  const routeSignal = useContext(RouteContext);
-
-  if (!routeSignal) {
-    throw new Error("useRoute must be used within a RouterProvider");
-  }
-
-  if (!routeSignal().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 routeSignal as Accessor<
-    Omit<RouteState<P>, "route"> & { route: State<P> }
-  >;
-};

package/src/hooks/useRouteEnter.tsx

@@ -1,121 +0,0 @@
-import { createEffect } from "solid-js";
-
-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 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
- *   }
- * });
- * ```
- */
-export function useRouteEnter(
-  handler: RouteEnterHandler,
-  options?: UseRouteEnterOptions,
-): void {
-  const routeState = useRoute();
-  const skipSameRoute = options?.skipSameRoute ?? true;
-  let lastHandledRoute: State | null = null;
-
-  createEffect(() => {
-    const { route, previousRoute } = routeState();
-
-    // 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 + missing `previousRoute`**: same `route`
-    //     ref between effect activations is unexpected on Solid (effects
-    //     run once per dependency change); `!previousRoute` is unreachable
-    //     once `transition.from` is set (the two are populated together by
-    //     core). Both kept for parity with React; v8-ignored.
-    if (!route.transition.from) {
-      return;
-    }
-    if (skipSameRoute && route.transition.from === route.name) {
-      return;
-    }
-    /* v8 ignore start */
-    if (lastHandledRoute === route || !previousRoute) {
-      return;
-    }
-    /* v8 ignore stop */
-
-    lastHandledRoute = route;
-    handler({ route, previousRoute });
-  });
-}