@valentinkolb/ssr 0.9.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)
@@ -174,6 +178,48 @@ 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:
@@ -288,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.9.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/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,
+  });
+}