@valentinkolb/ssr 0.8.0 → 0.10.0

package/README.md

@@ -42,12 +42,16 @@ What is intentionally not included:
 - no build tool wrapper around Bun
 
 Use the libraries you already prefer. This package only handles SSR and islands hydration.
+The optional `@valentinkolb/ssr/nav` subpath provides progressive anchor
+enhancement for islands, but it still does not add route matching, loaders, or
+SPA routing.
 
 ## Features
 
 - Small SSR core with Bun-native build/plugin flow
 - Adapters for Bun, Hono, and Elysia
 - Type-safe Hono page helper via `createSSRHandler`
+- Optional progressive navigation helpers via `@valentinkolb/ssr/nav`
 - Monorepo support via `rootDir`
 - Public path mounting via `basePath` for microfrontends
 - Stable file-path-based island IDs (collision-safe across workspace packages)
@@ -145,7 +149,7 @@ import Counter from "../components/Counter.island";
 
 export default ssr(async (c) => {
   c.get("page").title = "Home";
-  return <Counter initial={5} />;
+  return () => <Counter initial={5} />;
 });
 ```
 
@@ -174,6 +178,87 @@ NODE_ENV=development bun --watch --preload=./scripts/preload.ts src/server.ts
 - Hono: `@valentinkolb/ssr/hono`
 - Elysia: `@valentinkolb/ssr/elysia`
 
+## Optional Navigation Helpers
+
+`@valentinkolb/ssr/nav` is an opt-in browser helper for islands that want to
+update URL history after they have already updated client state.
+
+```tsx
+import { createSignal } from "solid-js";
+import { Link, type LinkNavigateEvent } from "@valentinkolb/ssr/nav";
+
+export default function Tabs() {
+  const [tab, setTab] = createSignal("alpha");
+
+  const openTab = (nav: LinkNavigateEvent) => {
+    const next = nav.url.searchParams.get("tab") ?? "alpha";
+    setTab(next);
+    nav.replaceWith(`/demo?tab=${next}`, { scroll: "preserve" });
+  };
+
+  return (
+    <Link href="/demo?tab=beta" scroll="preserve" onNavigate={openTab}>
+      Open beta
+    </Link>
+  );
+}
+```
+
+`Link` renders a real `<a href>` during SSR. Enhanced clicks only run in the
+browser for same-origin, left-click navigation without modifier keys. Without
+`onNavigate`, `Link` calls `navigate()` directly and only updates browser
+history. With `onNavigate`, the island owns data loading and state updates, then
+calls `nav.push()`, `nav.replaceWith()`, or `nav.fallback()`.
+
+Available exports:
+
+- `Link`
+- `navigate()`, `navigateTo()`, `documentNavigate()`, `refreshCurrentPath()`
+- `captureScroll()`, `restoreScroll()`, `startViewTransition()`
+- `LinkNavigateEvent`, `LinkProps`, `EnhancedNavigateOptions`, `NavigationScrollMode`, `ScrollSnapshot`
+
+Use `data-scroll-preserve="stable-key"` on scroll containers that should keep
+their scroll position across enhanced navigation.
+
+## Rendering API
+
+`html()` and Hono `ssr()` handlers expect a synchronous render function:
+
+```tsx
+export default ssr(async (c) => {
+  const data = await loadData();
+  c.get("page").title = data.title;
+
+  return () => <Page data={data} />;
+});
+
+app.get("/", () => html(() => <Page />));
+```
+
+Do async work in the handler before returning the render function. Do not make the render function itself `async`; Solid SSR expects synchronous JSX evaluation.
+
+### v0.9.0 migration
+
+This is a breaking change in v0.9.0. In v0.8.x and earlier, examples often returned already-created JSX:
+
+```tsx
+// v0.8.x and earlier
+export default ssr(async () => <Page />);
+
+app.get("/", () => html(<Page />));
+```
+
+In v0.9.0, wrap JSX creation in a render function:
+
+```tsx
+// v0.9.0+
+export default ssr(async () => () => <Page />);
+
+app.get("/", () => html(() => <Page />));
+```
+
+This ensures Solid primitives such as `createUniqueId()` run inside `renderToString()`, where the SSR context exists.
+
 ## `createConfig` options
 
 ```ts
@@ -206,7 +291,7 @@ export const { config, html } = createConfig({
 // docs-app.ts
 const docsApp = new Hono()
   .route("/_ssr", routes(config))
-  .get("/", () => html(<DocsHome />));
+  .get("/", () => html(() => <DocsHome />));
 
 // host-app.ts
 export default new Hono().route("/docs", docsApp);
@@ -234,7 +319,7 @@ await Bun.build({
 
 - initializes `c.get("page")` as typed page options
 - accepts middlewares/validators before final handler
-- lets handlers return either JSX or `Response`
+- lets handlers return either a synchronous render function or `Response`
 
 ## Dev mode tools
 
@@ -249,7 +334,7 @@ It can:
 ## Limitations
 
 - islands must use default export
-- props must be serializable (via `seroval`)
+- props must be serializable via `seroval`; do not pass functions, callbacks, event handlers, Solid signals/stores, DOM nodes, or class instances as island/client props
 - nested island/client imports are not supported
 
 ## Local monorepo example

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@valentinkolb/ssr",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "description": "Minimal SSR framework for SolidJS and Bun",
   "type": "module",
   "main": "src/index.ts",
@@ -9,7 +9,8 @@
     ".": "./src/index.ts",
     "./bun": "./src/adapter/bun.ts",
     "./elysia": "./src/adapter/elysia.ts",
-    "./hono": "./src/adapter/hono.ts"
+    "./hono": "./src/adapter/hono.ts",
+    "./nav": "./src/nav.ts"
   },
   "scripts": {
     "test": "bun test"
@@ -34,12 +35,12 @@
   "dependencies": {
     "@babel/core": "^7.24.0",
     "@babel/preset-typescript": "^7.24.0",
+    "@types/babel__core": "^7.20.5",
     "babel-preset-solid": "^1.8.0",
     "seroval": "^1.0.0"
   },
   "devDependencies": {
     "@elysiajs/static": "^1.2.0",
-    "@types/babel__core": "^7.20.5",
     "@types/bun": "latest",
     "elysia": "^1.2.0",
     "hono": "^4.6.14",

package/src/adapter/bun.ts

@@ -23,7 +23,7 @@ type Routes = Record<string, RouteHandler>;
  * serve({
  *   routes: {
  *     ...routes(config),
- *     "/": () => html(<Home />),
+ *     "/": () => html(() => <Home />),
  *   },
  * });
  * ```

package/src/adapter/elysia.ts

@@ -20,7 +20,7 @@ import {
  * import { routes } from "@valentinkolb/ssr/adapter/elysia";
  * new Elysia()
  *   .use(routes(config))
- *   .get("/", () => html(<Home />))
+ *   .get("/", () => html(() => <Home />))
  *   .listen(3000);
  * ```
  */

package/src/adapter/hono.ts

@@ -5,8 +5,7 @@
 import { Hono } from "hono";
 import { createFactory } from "hono/factory";
 import type { Context, Env, Handler, MiddlewareHandler, TypedResponse } from "hono";
-import type { JSX } from "solid-js";
-import type { SsrConfig, HtmlFn } from "../index";
+import type { SsrConfig, HtmlFn, RenderFn } from "../index";
 import { getSsrDir, getCacheHeaders, createReloadResponse, safePath } from "./utils";
 
 // ============================================================================
@@ -20,8 +19,8 @@ type PageEnv<T extends object> = {
   };
 };
 
-/** SSR handler return type - JSX element or Response (for redirects etc.) */
-type SsrHandlerResult = JSX.Element | Response | TypedResponse;
+/** SSR handler return type - render function or Response (for redirects etc.) */
+type SsrHandlerResult = RenderFn | Response | TypedResponse;
 
 /** SSR handler function signature */
 type SsrHandler<E extends Env, T extends object> = (
@@ -41,7 +40,7 @@ type SsrHandlers = [MiddlewareHandler, ...MiddlewareHandler[], Handler];
  * Features:
  * - Full compatibility with Hono middlewares/validators
  * - Type-safe page options via `c.get("page")`
- * - Return JSX directly or Response for redirects
+ * - Return a render function or Response for redirects
  * - No manual `html()` call needed
  *
  * @example
@@ -88,7 +87,7 @@ type SsrHandlers = [MiddlewareHandler, ...MiddlewareHandler[], Handler];
  *     c.get("page").title = room.name;
  *     c.get("page").description = `Welcome to ${room.name}`;
  *
- *     return <RoomView room={room} />;
+ *     return () => <RoomView room={room} />;
  *   }
  * );
  * ```
@@ -125,7 +124,7 @@ export const createSSRHandler = <T extends object>(html: HtmlFn<T>) => {
       await next();
     });
 
-    // Wrapped handler: JSX → html(), Response → passthrough
+    // Wrapped handler: render function → html(), Response → passthrough
     const wrappedHandler: Handler = async (c) => {
       const result = await finalHandler(c as Context<E & PageEnv<T>>);
 
@@ -134,8 +133,15 @@ export const createSSRHandler = <T extends object>(html: HtmlFn<T>) => {
         return result;
       }
 
-      // Otherwise treat as JSX element and render with html()
-      return html(result as JSX.Element, c.get("page") as T);
+      if (typeof result !== "function") {
+        throw new Error("[ssr] ssr() handlers must return a render function: return () => <Page />");
+      }
+
+      if (result.constructor.name === "AsyncFunction") {
+        throw new Error("[ssr] ssr() render functions must be synchronous: return () => <Page />");
+      }
+
+      return html(result as RenderFn, c.get("page") as T);
     };
 
     // Return tuple for spread: .get('/path', ...ssr(handler))
@@ -155,7 +161,7 @@ export const createSSRHandler = <T extends object>(html: HtmlFn<T>) => {
  * import { routes } from "@valentinkolb/ssr/adapter/hono";
  * const app = new Hono()
  *   .route("/_ssr", routes(config))
- *   .get("/", () => html(<Home />));
+ *   .get("/", () => html(() => <Home />));
  * ```
  */
 export const routes = (config: SsrConfig) => {

package/src/index.ts

@@ -68,7 +68,9 @@ export type SsrConfig = {
   ssrPath: string;
 };
 
-export type HtmlFn<T extends object> = (element: JSX.Element, options?: T) => Promise<Response>;
+export type RenderFn = () => JSX.Element;
+
+export type HtmlFn<T extends object> = (render: RenderFn, options?: T) => Promise<Response>;
 
 type PluginFn = () => BunPlugin;
 
@@ -151,8 +153,12 @@ export const createConfig = <T extends object = object>(options: SsrOptions<T> =
   const devConfigScript = `<script>globalThis.__SSR_CONFIG=${JSON.stringify({ ssrPath })}</script>`;
 
   // HTML renderer
-  const html: HtmlFn<T> = async (element, opts = {} as T) => {
-    const body = renderToString(() => element);
+  const html: HtmlFn<T> = async (render, opts = {} as T) => {
+    if (render.constructor.name === "AsyncFunction") {
+      throw new Error("[ssr] html() expects a synchronous render function: html(() => <Page />)");
+    }
+
+    const body = renderToString(render);
 
     // Framework-injected assets
     let scripts = `${islandDisplayStyle}\n${hydrationScript}`;

package/src/nav.ts

@@ -0,0 +1,229 @@
+/**
+ * Opt-in browser navigation helpers for SSR islands.
+ *
+ * This is not a router. Links remain real anchors and apps decide whether an
+ * enhanced click can update client state before committing browser history.
+ */
+import type { JSX } from "solid-js";
+import { createDynamic } from "solid-js/web";
+
+type AnchorProps = JSX.AnchorHTMLAttributes<HTMLAnchorElement>;
+
+export type NavigationScrollMode = "top" | "preserve" | "manual";
+
+export type ScrollSnapshot = {
+  window: { x: number; y: number };
+  regions: Array<{
+    key: string;
+    x: number;
+    y: number;
+  }>;
+};
+
+export type EnhancedNavigateOptions = {
+  replace?: boolean;
+  scroll?: NavigationScrollMode;
+  scrollSnapshot?: ScrollSnapshot;
+  viewTransition?: boolean;
+};
+
+export type LinkNavigateEvent = {
+  event: MouseEvent;
+  href: string;
+  url: URL;
+  replace: boolean;
+  scroll: NavigationScrollMode;
+  push: (href?: string, options?: EnhancedNavigateOptions) => void;
+  replaceWith: (href?: string, options?: Omit<EnhancedNavigateOptions, "replace">) => void;
+  fallback: (href?: string) => void;
+  scrollSnapshot: ScrollSnapshot;
+  captureScroll: (selector?: string) => ScrollSnapshot;
+  restoreScroll: typeof restoreScroll;
+};
+
+export type LinkProps = Omit<AnchorProps, "href" | "onClick"> & {
+  href: string;
+  replace?: boolean;
+  scroll?: NavigationScrollMode;
+  onClick?: JSX.EventHandlerUnion<HTMLAnchorElement, MouseEvent>;
+  onNavigate?: (event: LinkNavigateEvent) => void | Promise<void>;
+};
+
+const SCROLL_PRESERVE_SELECTOR = "[data-scroll-preserve]";
+
+type ViewTransitionDocument = Document & {
+  startViewTransition?: (callback: () => void | Promise<void>) => unknown;
+};
+
+/**
+ * Returns the current URL path + query, without the hash.
+ */
+export const currentPathWithQuery = (): string => {
+  const url = new URL(window.location.href);
+  return `${url.pathname}${url.search}`;
+};
+
+/**
+ * Navigates to the current path + query with a full document navigation.
+ */
+export const refreshCurrentPath = (): void => {
+  window.location.assign(currentPathWithQuery());
+};
+
+/**
+ * Navigates with a full document navigation.
+ */
+export const navigateTo = (href: string): void => {
+  window.location.assign(href);
+};
+
+export const startViewTransition = (callback: () => void | Promise<void>): void => {
+  const doc = document as ViewTransitionDocument;
+  if (!doc.startViewTransition) {
+    void callback();
+    return;
+  }
+  doc.startViewTransition(callback);
+};
+
+const restoreRegionScroll = (snapshot: ScrollSnapshot): void => {
+  for (const region of snapshot.regions) {
+    const selector = `[data-scroll-preserve="${CSS.escape(region.key)}"]`;
+    const el = document.querySelector<HTMLElement>(selector);
+    if (!el) continue;
+    el.scrollLeft = region.x;
+    el.scrollTop = region.y;
+  }
+};
+
+/**
+ * Captures window scroll and keyed `[data-scroll-preserve]` regions.
+ */
+export const captureScroll = (selector = SCROLL_PRESERVE_SELECTOR): ScrollSnapshot => ({
+  window: { x: window.scrollX, y: window.scrollY },
+  regions: Array.from(document.querySelectorAll<HTMLElement>(selector))
+    .map((el) => ({
+      key: el.dataset.scrollPreserve ?? "",
+      x: el.scrollLeft,
+      y: el.scrollTop,
+    }))
+    .filter((region) => region.key.length > 0),
+});
+
+/**
+ * Restores a captured scroll snapshot.
+ */
+export const restoreScroll = (snapshot: ScrollSnapshot, options: { window?: boolean } = {}): void => {
+  restoreRegionScroll(snapshot);
+  if (options.window === false) return;
+  window.scrollTo(snapshot.window.x, snapshot.window.y);
+};
+
+/**
+ * Updates browser history without a document reload.
+ *
+ * Use this after the current island has already updated its UI or when it is
+ * intentionally preserving the current DOM. It does not match routes, load
+ * data, or re-render server pages.
+ */
+export const navigate = (href: string, options: EnhancedNavigateOptions = {}): void => {
+  const scroll = options.scroll ?? "top";
+  const snapshot = scroll === "manual" ? null : (options.scrollSnapshot ?? captureScroll());
+  const url = new URL(href, window.location.href);
+  const target = `${url.pathname}${url.search}${url.hash}`;
+
+  const commit = () => {
+    if (options.replace) window.history.replaceState(null, "", target);
+    else window.history.pushState(null, "", target);
+
+    if (!snapshot) return;
+    restoreRegionScroll(snapshot);
+    if (scroll === "preserve") {
+      window.scrollTo(snapshot.window.x, snapshot.window.y);
+      return;
+    }
+    window.scrollTo(0, 0);
+  };
+
+  if (options.viewTransition === false) {
+    commit();
+    return;
+  }
+  startViewTransition(commit);
+};
+
+export const documentNavigate = (href: string, options: { replace?: boolean } = {}): void => {
+  if (options.replace) window.location.replace(href);
+  else window.location.assign(href);
+};
+
+const shouldEnhanceClick = (event: MouseEvent, anchor: HTMLAnchorElement): boolean => {
+  if (event.defaultPrevented || event.button !== 0) return false;
+  if (event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) return false;
+  if (anchor.target && anchor.target !== "_self") return false;
+  if (anchor.hasAttribute("download")) return false;
+
+  const url = new URL(anchor.href, window.location.href);
+  return url.origin === window.location.origin;
+};
+
+const callUserClick = (handler: LinkProps["onClick"], event: MouseEvent, anchor: HTMLAnchorElement): void => {
+  if (!handler) return;
+  if (typeof handler === "function") {
+    handler(event as MouseEvent & { currentTarget: HTMLAnchorElement; target: Element });
+    return;
+  }
+  (handler as unknown as EventListenerObject).handleEvent(event);
+};
+
+/**
+ * SSR-safe anchor with opt-in progressive navigation.
+ */
+export function Link(props: LinkProps) {
+  const anchorProps = () => {
+    const { href: _href, replace: _replace, scroll: _scroll, onNavigate: _onNavigate, onClick: _onClick, ...rest } = props;
+    return rest;
+  };
+
+  const handleClick: JSX.EventHandler<HTMLAnchorElement, MouseEvent> = (event) => {
+    callUserClick(props.onClick, event, event.currentTarget);
+    if (!shouldEnhanceClick(event, event.currentTarget)) return;
+
+    const href = props.href;
+    const url = new URL(href, window.location.href);
+    const scroll = props.scroll ?? "top";
+    const replace = Boolean(props.replace);
+    const scrollSnapshot = captureScroll();
+
+    event.preventDefault();
+
+    if (!props.onNavigate) {
+      navigate(href, { replace, scroll, scrollSnapshot });
+      return;
+    }
+
+    startViewTransition(() =>
+      props.onNavigate!({
+        event,
+        href,
+        url,
+        replace,
+        scroll,
+        push: (nextHref = href, options = {}) =>
+          navigate(nextHref, { replace: false, scroll, scrollSnapshot, viewTransition: false, ...options }),
+        replaceWith: (nextHref = href, options = {}) =>
+          navigate(nextHref, { replace: true, scroll, scrollSnapshot, viewTransition: false, ...options }),
+        fallback: (nextHref = href) => documentNavigate(nextHref, { replace }),
+        scrollSnapshot,
+        captureScroll,
+        restoreScroll,
+      }),
+    );
+  };
+
+  return createDynamic(() => "a", {
+    ...anchorProps(),
+    href: props.href,
+    onClick: handleClick,
+  });
+}