@real-router/solid 0.11.0 → 0.12.0

package/dist/cjs/ssr.js

@@ -0,0 +1,263 @@
+'use strict';
+
+var web = require('solid-js/web');
+var solidJs = require('solid-js');
+
+/**
+ * Returns a boolean accessor that is `false` during initial render (SSR
+ * and the first client paint) and flips to `true` once the component
+ * has mounted in the browser.
+ *
+ * Solid guarantees that `onMount` does NOT fire during `renderToString` /
+ * `renderToStream`, so the accessor stays `false` server-side — this is
+ * the building block for SSR boundary components (`<ClientOnly>` /
+ * `<ServerOnly>`).
+ *
+ * Consolidates the identical `createSignal(false) + onMount(setMounted)`
+ * pattern across the two boundary components (§8a Q15).
+ */
+function createMountedSignal() {
+  const [mounted, setMounted] = solidJs.createSignal(false);
+  solidJs.onMount(() => {
+    setMounted(true);
+  });
+  return mounted;
+}
+
+function ClientOnly(props) {
+  const mounted = createMountedSignal();
+  return web.createComponent(solidJs.Show, {
+    get when() {
+      return mounted();
+    },
+    get fallback() {
+      return props.fallback;
+    },
+    get children() {
+      return props.children;
+    }
+  });
+}
+
+function ServerOnly(props) {
+  const mounted = createMountedSignal();
+  return web.createComponent(solidJs.Show, {
+    get when() {
+      return mounted();
+    },
+    get fallback() {
+      return props.children;
+    },
+    get children() {
+      return props.fallback;
+    }
+  });
+}
+
+solidJs.createContext(null);
+const RouteContext = solidJs.createContext(null);
+
+const useRoute = () => {
+  const routeSignal = solidJs.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;
+};
+
+const NEVER_PROMISE = new Promise(() => {
+  // 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.
+ */
+function useDeferred(key) {
+  const routeAccessor = useRoute();
+  return () => {
+    const context = routeAccessor().route.context;
+    const deferred = context.ssrDataDeferred;
+    return deferred?.[key] ?? NEVER_PROMISE;
+  };
+}
+
+/**
+ * Reads `useDeferred(name)` and hands the resolved value to the render-prop.
+ * Wraps the deferred promise in `createResource` so Solid's reactivity tracks
+ * resolution and `<Suspense>` gets the standard suspend signal.
+ *
+ * ```tsx
+ * <Streamed fallback={<Spinner />}>
+ *   <Await<Review[]> name="reviews">
+ *     {(reviews) => <ReviewList items={reviews} />}
+ *   </Await>
+ * </Streamed>
+ * ```
+ *
+ * Implementation: returns a Solid accessor (function child) that reads
+ * `resource()` — this both (a) triggers `<Suspense>` suspension while pending
+ * and (b) re-throws on `errored` for the nearest `<ErrorBoundary>` to catch.
+ * The render-prop is gated on `resource.state === "ready"` rather than on
+ * truthiness so falsy resolved values (`0`, `false`, `null`, `""`) still
+ * reach `props.children`.
+ */
+function Await(props) {
+  const promiseAccessor = useDeferred(props.name);
+  const [resource] = solidJs.createResource(promiseAccessor, promise => promise);
+
+  // The double cast `as unknown as JSX.Element` (audit-2026-05-17 §8a) is
+  // load-bearing: this returns a Solid accessor *function*, not an element
+  // node. `JSX.Element` in Solid is a union that includes function-as-child
+  // for reactive bindings, but the type machinery can't narrow the bare
+  // arrow's signature to that union — going through `unknown` is the
+  // standard escape hatch used elsewhere in solid-router-style adapters.
+  // Removing either cast yields a "Type '() => unknown' is not assignable
+  // to type 'JSX.Element'" error.
+  return () => {
+    const value = resource();
+    if (resource.state !== "ready") {
+      return;
+    }
+    return props.children(value);
+  };
+}
+
+/**
+ * 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.
+ */
+function Streamed(props) {
+  return web.createComponent(solidJs.Suspense, {
+    get fallback() {
+      return props.fallback;
+    },
+    get children() {
+      return props.children;
+    }
+  });
+}
+
+const HttpStatusContext = solidJs.createContext(null);
+function HttpStatusProvider(props) {
+  return web.createComponent(HttpStatusContext.Provider, {
+    get value() {
+      return props.sink;
+    },
+    get children() {
+      return props.children;
+    }
+  });
+}
+
+/**
+ * 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 "solid-js/web";
+ * import { createHttpStatusSink, HttpStatusProvider } from "@real-router/solid/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 (`renderToStream`):** 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), or use `renderToStringAsync` (single-shot, awaits all Suspense
+ * before returning HTML).
+ *
+ * **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).
+ */
+function HttpStatusCode(props) {
+  const sink = solidJs.useContext(HttpStatusContext);
+  if (sink) {
+    sink.code = props.code;
+  }
+  return null;
+}
+
+/**
+ * Render-scoped HTTP status sink. Created per request on the server, passed to
+ * `<HttpStatusProvider sink={...}>`, and read after `renderToString` /
+ * `renderToStream` 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.
+ * - **Hydration symmetry:** mount `<HttpStatusProvider>` on both server and
+ *   client (with a throwaway client sink). Solid emits `data-hk` markers
+ *   per component boundary; an extra provider on one side desyncs the
+ *   counter and breaks the hydration walker.
+ */
+
+function createHttpStatusSink() {
+  return {
+    code: undefined
+  };
+}
+
+exports.Await = Await;
+exports.ClientOnly = ClientOnly;
+exports.HttpStatusCode = HttpStatusCode;
+exports.HttpStatusProvider = HttpStatusProvider;
+exports.ServerOnly = ServerOnly;
+exports.Streamed = Streamed;
+exports.createHttpStatusSink = createHttpStatusSink;
+exports.useDeferred = useDeferred;

package/dist/esm/index.d.mts

@@ -319,7 +319,26 @@ declare const RouteContext: solid_js.Context<Accessor<RouteState<_real_router_co
 
 declare function createSignalFromSource<T>(source: RouterSource<T>): Accessor<T>;
 
+/**
+ * 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.
+ */
 declare function createStoreFromSource<T extends object>(source: RouterSource<T>): T;
 
 export { Link, RouteContext, RouteView, RouterContext, RouterErrorBoundary, RouterProvider, createSignalFromSource, createStoreFromSource, link, useNavigator, useRoute, useRouteEnter, useRouteExit, useRouteNode, useRouteNodeStore, useRouteStore, useRouteUtils, useRouter, useRouterTransition };
-export type { LinkDirectiveOptions, LinkProps, RouteEnterContext, RouteEnterHandler, RouteExitContext, RouteExitHandler, RouteState, MatchProps as RouteViewMatchProps, NotFoundProps as RouteViewNotFoundProps, RouteViewProps, SelfProps as RouteViewSelfProps, RouterErrorBoundaryProps, UseRouteEnterOptions, UseRouteExitOptions };
+export type { LinkDirectiveOptions, LinkProps, RouteEnterContext, RouteEnterHandler, RouteExitContext, RouteExitHandler, RouteState, MatchProps as RouteViewMatchProps, NotFoundProps as RouteViewNotFoundProps, RouteViewProps, SelfProps as RouteViewSelfProps, RouterContextValue, RouterErrorBoundaryProps, UseRouteEnterOptions, UseRouteExitOptions };

package/dist/esm/ssr.d.mts

@@ -0,0 +1,163 @@
+import { JSX, Accessor } from 'solid-js';
+
+interface ClientOnlyProps {
+    readonly children: JSX.Element;
+    readonly fallback?: JSX.Element;
+}
+declare function ClientOnly(props: ClientOnlyProps): JSX.Element;
+
+interface ServerOnlyProps {
+    readonly children: JSX.Element;
+    readonly fallback?: JSX.Element;
+}
+declare function ServerOnly(props: ServerOnlyProps): JSX.Element;
+
+interface AwaitProps<T> {
+    /** Deferred key declared in the loader's `defer({ deferred: { <name>: ... } })`. */
+    readonly name: string;
+    /** Render the resolved value. Surrounding `<Suspense>` shows fallback while
+     * pending; rejection bubbles through Solid's `<ErrorBoundary>`. */
+    readonly children: (value: T) => JSX.Element;
+}
+/**
+ * Reads `useDeferred(name)` and hands the resolved value to the render-prop.
+ * Wraps the deferred promise in `createResource` so Solid's reactivity tracks
+ * resolution and `<Suspense>` gets the standard suspend signal.
+ *
+ * ```tsx
+ * <Streamed fallback={<Spinner />}>
+ *   <Await<Review[]> name="reviews">
+ *     {(reviews) => <ReviewList items={reviews} />}
+ *   </Await>
+ * </Streamed>
+ * ```
+ *
+ * Implementation: returns a Solid accessor (function child) that reads
+ * `resource()` — this both (a) triggers `<Suspense>` suspension while pending
+ * and (b) re-throws on `errored` for the nearest `<ErrorBoundary>` to catch.
+ * The render-prop is gated on `resource.state === "ready"` rather than on
+ * truthiness so falsy resolved values (`0`, `false`, `null`, `""`) still
+ * reach `props.children`.
+ */
+declare function Await<T = unknown>(props: AwaitProps<T>): JSX.Element;
+
+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.
+ */
+declare function Streamed(props: StreamedProps): JSX.Element;
+
+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 "solid-js/web";
+ * import { createHttpStatusSink, HttpStatusProvider } from "@real-router/solid/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 (`renderToStream`):** 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), or use `renderToStringAsync` (single-shot, awaits all Suspense
+ * before returning HTML).
+ *
+ * **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).
+ */
+declare function HttpStatusCode(props: HttpStatusCodeProps): JSX.Element;
+
+/**
+ * Render-scoped HTTP status sink. Created per request on the server, passed to
+ * `<HttpStatusProvider sink={...}>`, and read after `renderToString` /
+ * `renderToStream` 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.
+ * - **Hydration symmetry:** mount `<HttpStatusProvider>` on both server and
+ *   client (with a throwaway client sink). Solid emits `data-hk` markers
+ *   per component boundary; an extra provider on one side desyncs the
+ *   counter and breaks the hydration walker.
+ */
+interface HttpStatusSink {
+    code: number | undefined;
+}
+declare function createHttpStatusSink(): HttpStatusSink;
+
+interface HttpStatusProviderProps {
+    readonly sink: HttpStatusSink;
+    readonly children: JSX.Element;
+}
+declare function HttpStatusProvider(props: HttpStatusProviderProps): JSX.Element;
+
+/**
+ * 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.
+ */
+declare function useDeferred<T = unknown>(key: string): Accessor<Promise<T>>;
+
+export { Await, ClientOnly, HttpStatusCode, HttpStatusProvider, ServerOnly, Streamed, createHttpStatusSink, useDeferred };
+export type { AwaitProps, ClientOnlyProps, HttpStatusCodeProps, HttpStatusProviderProps, HttpStatusSink, ServerOnlyProps, StreamedProps };