@opentf/web 0.6.0 → 0.8.0

package/runtime/route-data.js

@@ -0,0 +1,64 @@
+// Route-loader data on the client (docs/DATA.md). A page with a sibling
+// `loader.{js,ts}` gets its data three ways, all converging on `router.data`:
+//
+//   • first paint over server HTML — the payload is inlined as
+//     `<script type="application/json" id="__otfw_data">` and read here;
+//   • SPA navigation — fetched from `<path>/__data.json` (the same URL a static
+//     host serves as a literal file written at SSG time, and the serve/dev
+//     servers answer dynamically);
+//   • dev/CSR first load — the same fetch, since there is no server markup.
+//
+// The endpoint returns the raw loader JSON (no envelope): 404 means "no data for
+// this route" (no loader, or the loader called `notFound()`) and maps to
+// `undefined` so the page renders its empty state.
+
+/** The reserved per-route data filename/URL suffix (`/todos` → `/todos/__data.json`). */
+export const DATA_FILE = "__data.json";
+
+// Match the router's path normalization (a trailing slash must hit the same URL).
+const normalize = (p) => (p || "/").replace(/(.)\/+$/, "$1");
+
+/** The data-endpoint URL for a page path: `"/"` → `/__data.json`,
+ *  `"/todos"` → `/todos/__data.json`, preserving the query string. */
+export function dataUrlFor(pathname, search = "") {
+  const path = normalize(pathname);
+  return (path === "/" ? `/${DATA_FILE}` : `${path}/${DATA_FILE}`) + (search || "");
+}
+
+/**
+ * Fetch a route's loader data. 200 → the parsed JSON; 404 → `undefined` (no
+ * loader / `notFound()`); anything else throws (the router reports it and
+ * commits the navigation with no data).
+ */
+export async function fetchRouteData(pathname, search = "") {
+  const res = await fetch(dataUrlFor(pathname, search));
+  if (res.status === 404) return undefined;
+  if (!res.ok) throw new Error(`route data request for ${pathname} failed (${res.status})`);
+  return res.json();
+}
+
+// The inline first-paint payload, read once and cached (mirrors the island-props
+// payload reader in hydrate.js). `undefined` data serializes to *no script at all*
+// (the toolchain skips injection), so a missing element simply reads as undefined.
+let _read = false;
+let _value;
+
+/** The loader data inlined by the server for the current document, or `undefined`. */
+export function readInlineRouteData() {
+  if (!_read) {
+    _read = true;
+    const el = typeof document !== "undefined" ? document.getElementById("__otfw_data") : null;
+    try {
+      _value = el ? JSON.parse(el.textContent || "null") : undefined;
+    } catch {
+      _value = undefined;
+    }
+  }
+  return _value;
+}
+
+/** Reset the cached inline payload (tests only — a fresh document between cases). */
+export function __resetInlineRouteData() {
+  _read = false;
+  _value = undefined;
+}

package/runtime/router.js

@@ -11,11 +11,14 @@
 // NOTE: passing route params to a page via its `props` argument
 // (`function Page(props) { props.params.id }`) and layout `props.children`
 // composition both require signal-free page props, which the compiler does not
-// emit yet — for now pages read params via the reactive `router.params`.
+// emit yet — for now pages read params via the reactive `router.params`, and a
+// route loader's data via the reactive `router.data` (docs/DATA.md).
 
 import { clearError, reportError } from "../core/errors.js";
 import { signal } from "../core/signals.js";
+import { beginHydration, cursor, endHydration } from "./hydrate.js";
 import { runCleanup, runMount } from "./mount.js";
+import { fetchRouteData, readInlineRouteData } from "./route-data.js";
 
 const isBrowser = typeof window !== "undefined";
 
@@ -33,9 +36,10 @@ const state = {
   searchParams: signal(new URLSearchParams(isBrowser ? window.location.search : "")),
   params: signal({}),
   locale: signal(null),
+  data: signal(undefined),
 };
 
-export const routes = { pages: {}, layouts: {}, notFound: null };
+export const routes = { pages: {}, layouts: {}, notFound: null, loaderRoutes: new Set() };
 let guard = null;
 let rootEl = null;
 
@@ -134,14 +138,19 @@ export const router = {
   get locale() {
     return state.locale.value;
   },
+  get data() {
+    return state.data.value;
+  },
   push: (path) => navigate(path),
   replace: (path) => navigate(path, true),
 };
 
-/** Derive the route ("/counter", "/") from a `.../app/<route>/page.jsx` path. */
+/** Derive the route ("/counter", "/") from a `.../app/<route>/page.jsx` path. The
+ *  lookahead pins `/app` to a complete path segment, so a route folder that merely
+ *  starts with "app" (`/appointments`) isn't clipped. */
 function routeFromPath(filePath) {
   const r = filePath
-    .replace(/^.*\/app/, "")
+    .replace(/^.*\/app(?=\/)/, "")
     .replace(/\/(page|layout|404)\.(jsx|tsx|mdx|md)$/, "");
   return r === "" ? "/" : r;
 }
@@ -161,6 +170,22 @@ export function registerRoutes(modules) {
   }
 }
 
+/**
+ * Register which route *patterns* (`"/todos"`, `"/items/[id]"`) have a server
+ * loader (docs/DATA.md) — the toolchain discovers `loader.{js,ts}` files and
+ * passes the list via `mountApp({ loaders })`. `navigate` only fetches
+ * `<path>/__data.json` for routes in this set; `matchRoute` returns the same
+ * pattern string, so membership is a plain Set lookup.
+ */
+export function registerLoaderRoutes(paths) {
+  routes.loaderRoutes = new Set(paths || []);
+}
+
+/** Set the reactive `router.data` directly (server render and tests). */
+export function setRouteData(data) {
+  state.data.value = data;
+}
+
 /** Layout entries that wrap `route`, outermost (root) first. */
 export function layoutChain(route) {
   const chain = [];
@@ -200,16 +225,68 @@ export async function buildRouteNode(match, query = {}) {
   return { node, nodes };
 }
 
+/**
+ * Adopt a matched route's server-rendered DOM (docs/HYDRATION.md §3.4, 2.1c) — the hydrate
+ * analogue of {@link buildRouteNode}. One cursor threads the whole layout chain: the
+ * outermost layout adopts at the container, and each layout hands that cursor to the next at
+ * its `{children}` slot (`props.children` is a thunk that claims the nested route's subtree
+ * and advances the cursor), down to the page. Returns `{ nodes }` (page → … → root) for
+ * lifecycle, or `null` if the page or any layout isn't adoptable (no `hydrateAt` export) — the
+ * caller then falls back to a clean CSR build. A thrown `HydrationMismatch` propagates up,
+ * disposing each layer's partial wiring on the way (each `hydrateAt` has its own guard).
+ */
+export async function hydrateRouteNode(match, query, rootEl) {
+  const props = { params: match.params, query };
+  const pageMod = await resolveModule(match.entry);
+  if (!pageMod || typeof pageMod.hydrateAt !== "function") return null;
+  const chain = layoutChain(match.route);
+  const layoutMods = [];
+  for (const entry of chain) {
+    const m = await resolveModule(entry);
+    if (!m || typeof m.hydrateAt !== "function") return null; // whole chain must be adoptable
+    layoutMods.push(m);
+  }
+
+  // Compose the adopt thunks innermost-first: the page, then each layout wrapping it. Each
+  // thunk pushes its claimed root node, so `nodes` ends up page → … → outermost (the inner
+  // thunk runs — and pushes — during the outer layout's walk, before the outer pushes).
+  const nodes = [];
+  let thunk = (c) => {
+    const n = pageMod.hydrateAt(c, props);
+    nodes.push(n);
+    return n;
+  };
+  for (let i = chain.length - 1; i >= 0; i--) {
+    const layout = layoutMods[i];
+    const inner = thunk;
+    thunk = (c) => {
+      const n = layout.hydrateAt(c, { ...props, children: inner });
+      nodes.push(n);
+      return n;
+    };
+  }
+  thunk(cursor(rootEl)); // outermost adopts at the container; the chain threads inward
+  return { nodes };
+}
+
+/** Resolve a route entry (lazy loader or module namespace) to its module. */
+async function resolveModule(entry) {
+  return typeof entry === "function" ? await entry() : entry;
+}
+
 /**
  * Set the reactive route state directly (no history/render). Used by server render
  * so a page reading `router.pathname`/`params`/`query` resolves to the route being
  * pre-rendered. The client uses `navigate` instead.
  */
-export function setRouteState({ pathname = "/", search = "", params = {}, locale } = {}) {
+export function setRouteState({ pathname = "/", search = "", params = {}, locale, data } = {}) {
   state.pathname.value = normalizePath(pathname);
   state.searchParams.value = new URLSearchParams(search);
   state.params.value = params;
   state.locale.value = locale !== undefined ? locale : resolveLocale(pathname).locale;
+  // Always assigned (even when the caller passed none) so a loader-less render
+  // never shows a previous route's stale data.
+  state.data.value = data;
 }
 
 /**
@@ -220,9 +297,16 @@ export function setRouteState({ pathname = "/", search = "", params = {}, locale
 export function matchRoute(pathname) {
   pathname = resolveLocale(pathname).path;
   for (const route in routes.pages) {
+    // `[param]` / `[...rest]` become named groups; literal parts are regex-escaped
+    // (a `v1.0` folder must not match `v1X0`).
     const pattern = route
-      .replace(/\[\.\.\.([^\]]+)\]/g, "(?<$1>.+)")
-      .replace(/\[([^\]]+)\]/g, "(?<$1>[^/]+)");
+      .split(/(\[\.\.\.[^\]]+\]|\[[^\]]+\])/)
+      .map((part) => {
+        if (part.startsWith("[...")) return `(?<${part.slice(4, -1)}>.+)`;
+        if (part.startsWith("[")) return `(?<${part.slice(1, -1)}>[^/]+)`;
+        return part.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+      })
+      .join("");
     const m = pathname.match(new RegExp(`^${pattern}/?$`));
     if (m) {
       const params = { ...(m.groups || {}) };
@@ -235,12 +319,20 @@ export function matchRoute(pathname) {
   return null;
 }
 
+// Monotonic navigation sequence: a navigation that awaited its loader-data fetch
+// commits only if no newer navigation started meanwhile (stale data must never
+// win over a later click).
+let navSeq = 0;
+
 /**
- * Navigate to `path`. Runs an optional route guard, swaps the rendered page
- * (tearing down the previous one's lifecycle), and updates window.history.
+ * Navigate to `path`. Runs an optional route guard, fetches the route's loader
+ * data when it has any (docs/DATA.md — fetch *then* commit, like the guard),
+ * swaps the rendered page (tearing down the previous one's lifecycle), and
+ * updates window.history.
  */
 export async function navigate(path, replace = false, isPop = false, hydrate = false) {
   if (!path || !rootEl) return;
+  const seq = ++navSeq;
   const url = new URL(path, window.location.origin);
 
   if (guard) {
@@ -273,10 +365,30 @@ export async function navigate(path, replace = false, isPop = false, hydrate = f
     matchRoute(url.pathname) ||
     (routes.notFound ? { entry: routes.notFound, params: {}, route: null } : null);
 
+  // Loader data (docs/DATA.md): resolved before any state write / history push /
+  // DOM swap, mirroring the guard's "settle before commit" flow. First paint over
+  // server HTML reads the inlined payload; every other navigation (SPA nav, dev/CSR
+  // first load, popstate) fetches the `<path>/__data.json` endpoint. A failed fetch
+  // is reported and the navigation commits with `data === undefined`.
+  let data;
+  if (match && match.route && routes.loaderRoutes.has(match.route)) {
+    if (hydrate) {
+      data = readInlineRouteData();
+    } else {
+      try {
+        data = await fetchRouteData(url.pathname, url.search);
+      } catch (e) {
+        reportError(e, { phase: "data", path: url.pathname });
+      }
+      if (seq !== navSeq) return; // a newer navigation superseded this one
+    }
+  }
+
   state.pathname.value = normalizePath(url.pathname);
   state.searchParams.value = url.searchParams;
   state.params.value = match ? match.params : {};
   state.locale.value = resolveLocale(url.pathname).locale;
+  state.data.value = data;
 
   if (!isPop) {
     if (replace) window.history.replaceState({}, "", path);
@@ -284,24 +396,34 @@ export async function navigate(path, replace = false, isPop = false, hydrate = f
   }
 
   // First paint over server-rendered DOM: *adopt* it (hydrate) instead of rebuilding,
-  // when the route module exposes a `hydrate` adopt factory (compiled with the hydrate
-  // target). Only leaf routes (no layout chain) hydrate so far — `{children}`-slot
-  // adoption is a later phase — so anything else falls through to a clean CSR build. A
+  // when the route module exposes a `hydrateAt` adopt factory (compiled with the hydrate
+  // target). `hydrateRouteNode` threads one cursor through the whole layout chain (2.1c);
+  // a route whose page or any layout isn't adoptable returns null → clean CSR build. A
   // hydration mismatch is reported (never silent) and also falls through to a rebuild.
+  //
+  // The hydration flag must be live *before* the route modules are imported: route chunks
+  // are code-split, so `customElements.define` — and the synchronous upgrade of every
+  // server-rendered `<web-*>` host — happens during those imports, before the factories
+  // run. Those upgrading components read `isHydrating()` to adopt their server DOM rather
+  // than build (docs/HYDRATION.md §3.4). `endHydration()` in `finally` makes every
+  // subsequent client navigation build fresh; the CSR fallback below then runs with the
+  // flag cleared, so a rebuilt host builds instead of trying to re-adopt.
   if (hydrate && match) {
+    beginHydration();
     try {
-      const mod = typeof match.entry === "function" ? await match.entry() : match.entry;
-      if (mod && typeof mod.hydrate === "function" && layoutChain(match.route).length === 0) {
-        const query = Object.fromEntries(url.searchParams);
-        const node = mod.hydrate(rootEl, { params: match.params, query });
-        currentNodes = [node];
-        runMount(node);
+      const query = Object.fromEntries(url.searchParams);
+      const adopted = await hydrateRouteNode(match, query, rootEl);
+      if (adopted) {
+        currentNodes = adopted.nodes;
+        for (const n of adopted.nodes) runMount(n); // onMount for page + every layout
         clearError({ phase: "route" });
         return;
       }
     } catch (e) {
       reportError(e, { phase: "hydrate", path: url.pathname });
       // fall through to a clean CSR build below
+    } finally {
+      endHydration();
     }
   }
 
@@ -352,12 +474,15 @@ export async function navigate(path, replace = false, isPop = false, hydrate = f
  * @param {Function} [opts.guard]  optional `(to, tools) => …` route guard.
  * @param {"spa"|"mpa"} [opts.nav]  navigation mode (default "spa"); "mpa" disables
  *   client-side link interception so every navigation is a full page load.
+ * @param {string[]} [opts.loaders]  route patterns that have a server loader
+ *   (docs/DATA.md) — navigation fetches `<path>/__data.json` for these.
  */
-export function mountApp({ pages, target, guard: g, i18n, nav } = {}) {
+export function mountApp({ pages, target, guard: g, i18n, nav, loaders } = {}) {
   rootEl = target || (isBrowser ? document.getElementById("app") : null);
   navMode = nav === "mpa" ? "mpa" : "spa";
   if (i18n) configureI18n(i18n);
   if (pages) registerRoutes(pages);
+  if (loaders) registerLoaderRoutes(loaders);
   guard = g || null;
   // In MPA mode the browser owns navigation (full loads push real history entries),
   // so there is no client-side history to react to — only wire popstate for SPA.

package/server/adapters/node.d.ts

@@ -0,0 +1,28 @@
+// Type definitions for the Node.js adapter (SPEC §11.4).
+import type { IncomingMessage, ServerResponse } from "node:http";
+
+import type { RequestHandler } from "../api.js";
+
+export interface NodeAdapterOptions {
+  /** Response for requests that match no API route (default: a 404). */
+  fallback?: (request: Request) => Response | Promise<Response>;
+}
+
+/** Build a WHATWG `Request` from a Node `IncomingMessage`. */
+export function toWebRequest(req: IncomingMessage, options?: { protocol?: string }): Promise<Request>;
+
+/** Write a WHATWG `Response` to a Node `ServerResponse`. */
+export function sendWebResponse(res: ServerResponse, webRes: Response): Promise<void>;
+
+/**
+ * Turn a Fetch handler into a Node `(req, res)` listener:
+ *
+ *   import { createServer } from "node:http";
+ *   import { apiHandler } from "./dist/server/api.js";
+ *   import { toNodeListener } from "@opentf/web/server/adapters/node";
+ *   createServer(toNodeListener(apiHandler)).listen(3000);
+ */
+export function toNodeListener(
+  handler: RequestHandler,
+  options?: NodeAdapterOptions,
+): (req: IncomingMessage, res: ServerResponse) => Promise<void>;

package/server/adapters/node.js

@@ -0,0 +1,74 @@
+// Node.js adapter for OTF Web API routes (SPEC §11.4). The API handler speaks the
+// standard Fetch `Request`/`Response`; Bun, Cloudflare Workers, and Deno provide
+// those natively, but `node:http` speaks its own `IncomingMessage`/`ServerResponse`.
+// This adapter translates between the two so `dist/server/api.js` runs on Node.
+//
+//   import { createServer } from "node:http";
+//   import { apiHandler } from "./dist/server/api.js";
+//   import { toNodeListener } from "@opentf/web/server/adapters/node";
+//   createServer(toNodeListener(apiHandler)).listen(3000);
+
+/** Build a WHATWG `Request` from a Node `IncomingMessage`. */
+export async function toWebRequest(req, { protocol = "http" } = {}) {
+  const host = req.headers.host ?? "localhost";
+  const url = `${protocol}://${host}${req.url}`;
+  const method = req.method ?? "GET";
+  const headers = new Headers();
+  for (const [k, v] of Object.entries(req.headers)) {
+    if (Array.isArray(v)) for (const one of v) headers.append(k, one);
+    else if (v != null) headers.set(k, v);
+  }
+  // GET/HEAD must not carry a body; everything else streams the request in.
+  const hasBody = method !== "GET" && method !== "HEAD";
+  const body = hasBody ? await readBody(req) : undefined;
+  return new Request(url, { method, headers, body });
+}
+
+function readBody(req) {
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    req.on("data", (c) => chunks.push(c));
+    req.on("end", () => resolve(Buffer.concat(chunks)));
+    req.on("error", reject);
+  });
+}
+
+/** Write a WHATWG `Response` to a Node `ServerResponse`. */
+export async function sendWebResponse(res, webRes) {
+  const headers = {};
+  webRes.headers.forEach((value, key) => {
+    if (key !== "set-cookie") headers[key] = value;
+  });
+  // `Headers` iteration collapses repeated Set-Cookie values into one string, which
+  // breaks multi-cookie responses (session + CSRF). Recover the individual cookies;
+  // Node accepts an array header value and writes one Set-Cookie line per entry.
+  const cookies = webRes.headers.getSetCookie?.() ?? [];
+  if (cookies.length > 0) headers["set-cookie"] = cookies;
+  res.writeHead(webRes.status, headers);
+  if (webRes.body) {
+    const buf = Buffer.from(await webRes.arrayBuffer());
+    res.end(buf);
+  } else {
+    res.end();
+  }
+}
+
+/**
+ * Turn a Fetch handler `(request) => Response | null` into a Node
+ * `(req, res)` listener. A `null` result (no API route matched) becomes the
+ * optional `fallback(request)` response, or a 404.
+ */
+export function toNodeListener(handler, { fallback } = {}) {
+  return async (req, res) => {
+    try {
+      const request = await toWebRequest(req);
+      let webRes = await handler(request);
+      if (!webRes) webRes = fallback ? await fallback(request) : new Response("Not Found", { status: 404 });
+      await sendWebResponse(res, webRes);
+    } catch (e) {
+      if (!res.headersSent) res.writeHead(500, { "content-type": "application/json" });
+      res.end(JSON.stringify({ error: "Internal Server Error" }));
+      console.error("✗ API (node adapter):", e?.stack ?? e);
+    }
+  };
+}

package/server/api.d.ts

@@ -0,0 +1,106 @@
+// Type definitions for file-based API routes (SPEC §11). Authoring handlers in
+// TypeScript: annotate the method exports with `ApiHandler` and the `_middleware`
+// default export with `Middleware`.
+//
+//   import type { ApiHandler, Middleware } from "@opentf/web/server";
+//   export const GET: ApiHandler = (request, { params }) => Response.json({ id: params.id });
+
+type MaybePromise<T> = T | Promise<T>;
+
+/**
+ * Route params resolved from `[param]` / `[...rest]` segments. A `[param]` segment
+ * resolves to a `string`; a `[...rest]` catch-all resolves to a `string[]`. Values
+ * arrive percent-decoded (`/users/John%20Doe` → `"John Doe"`).
+ */
+export type RouteParams = Record<string, string | string[]>;
+
+/** Per-request context, passed as the second argument to handlers and middleware. */
+export interface ApiContext {
+  /** Dynamic route params resolved from the matched path. */
+  params: RouteParams;
+  /** Parsed query-string parameters. */
+  query: Record<string, string>;
+  /** The parsed request URL. */
+  url: URL;
+  /**
+   * Mutable per-request bag. Middleware writes to it (e.g. an authenticated user
+   * or a validated body) and downstream middleware / the handler reads from it.
+   */
+  locals: Record<string, unknown>;
+}
+
+/**
+ * An HTTP method handler (`GET`, `POST`, …). Receives the standard Fetch `Request`
+ * plus the {@link ApiContext}. Should return (or throw) a `Response`; a plain value
+ * is a convenience that gets JSON-encoded.
+ */
+export type ApiHandler = (request: Request, context: ApiContext) => MaybePromise<Response>;
+
+/** Continue to the next middleware, or ultimately the route handler. */
+export type NextFn = () => Promise<Response>;
+
+/**
+ * Folder middleware — the default export of a `_middleware.{js,ts}` file. Applies
+ * to its folder and everything nested under it; multiple middleware compose
+ * outermost-first. Call `next()` to continue, or return a `Response` to
+ * short-circuit (e.g. an auth guard).
+ */
+export type Middleware = (request: Request, context: ApiContext, next: NextFn) => MaybePromise<Response>;
+
+/**
+ * The composed request handler produced by {@link createApiHandler}: resolves to a
+ * `Response`, or `null` when no API route matched (so the caller can fall through
+ * to SSR or a 404).
+ */
+export type RequestHandler = (request: Request) => Promise<Response | null>;
+
+/** A discovered route module: its method-named handler exports, keyed by method. */
+export type RouteModule = Partial<Record<string, ApiHandler>>;
+
+/** A discovered `_middleware` module: the middleware is the default export. */
+export interface MiddlewareModule {
+  default?: Middleware;
+  middleware?: Middleware;
+}
+
+export interface FetchHandlerOptions {
+  /** Response for requests that match no API route (default: a 404). */
+  fallback?: (request: Request) => MaybePromise<Response>;
+}
+
+export interface ApiHandlerOptions {
+  /**
+   * Absolute path of the app directory the module keys live under. When given, the
+   * route is derived by stripping this exact prefix (the CLI always passes it);
+   * without it a `/app` path-segment heuristic is used.
+   */
+  appDir?: string;
+}
+
+/** Derive the route path from an `app/**/route.{js,ts}` file path (folder = URL). */
+export function apiRouteFromPath(filePath: string, appDir?: string): string;
+
+/** Derive the folder route a `_middleware` file governs from its file path. */
+export function middlewareScopeFromPath(filePath: string, appDir?: string): string;
+
+/**
+ * Build the API request handler from discovered route + middleware modules (both
+ * keyed by absolute file path so routes are derived from the path).
+ */
+export function createApiHandler(
+  routeModules?: Record<string, RouteModule>,
+  middlewareModules?: Record<string, MiddlewareModule>,
+  options?: ApiHandlerOptions,
+): RequestHandler;
+
+/**
+ * Wrap a {@link RequestHandler} into a total Fetch handler that always returns a
+ * `Response` — a `null` (no route matched) becomes the `fallback` or a 404. Use it
+ * to mount the handler on Fetch-native runtimes (Bun, Cloudflare Workers, Deno):
+ *
+ *   export default { fetch: createFetchHandler(apiHandler) };
+ */
+export function createFetchHandler(
+  handler: RequestHandler,
+  options?: FetchHandlerOptions,
+): (request: Request) => Promise<Response>;