@uniflowed/router 0.0.0-alpha.17 → 0.0.0-alpha.20

package/client.js

@@ -1,12 +1,31 @@
 // @flow
 //
-// Hydrating the document in the browser.
+// Starting the application in the browser.
+//
+// Two entry points, and which one `virtual:uf/client` calls is decided by
+// `app.rendering.modes`. `hydrate` is the one every uf build has used: a server
+// or a prerender wrote the markup, and React attaches to it. `render` is for
+// `["csr"]`, where the build wrote one shell with an empty root and nothing has
+// been rendered anywhere yet; see its own comment for why that is not `hydrate`
+// with a flag.
 //
 // `virtual:uf/client` calls `hydrate` with the app root and the route table.
 // The current route's chunks are loaded and its embedded loader data read
 // *before* `hydrateRoot`, so the first client render is synchronous and
 // matches the server's markup exactly.
 //
+// # What "its loader data" means once the loader can defer
+//
+// It is a payload rather than a value: `internal/payload.js` writes the model
+// into `<script id="__uf_data">` with a `"$P<n>"` reference wherever the loader
+// left a promise, and each of those arrives later in a `<script data-uf-row>`
+// of its own. So two things happen before `hydrateRoot` rather than one — the
+// model is decoded, and `internal/payload-rows.js` starts watching for the
+// rows it referred to. Both have to be first: the decoded model is what the
+// first render is handed, and a row that landed while nothing was watching
+// would be a boundary that never resolves. A document with nothing deferred
+// has no references, so the reader is handed no ids and installs nothing.
+//
 // # A hydration that fails says what differed
 //
 // React reports a mismatch with one sentence and a list of the six things that
@@ -49,6 +68,17 @@
 // `app.react.strictMode: false` in `uf.config.js` turns it off. See
 // ubugeeei-prod/uf#516.
 //
+// # And an application can decline to be navigated
+//
+// `app.rendering.navigation: "document"` is the whole application saying what
+// the paragraph below says about one route: the document the server wrote is
+// what a link produces, and the browser fetches the next one. It is *not* the
+// same as declining to hydrate — the page still hydrates, so a `"use client"`
+// component is still interactive — and what it removes is the takeover. The
+// flag reaches the runtime through `installNavigation` before the first render;
+// see `internal/runtime.js` for what `RouterProvider` and `Link` then do, and
+// `docs/app/guide/rendering` for when a project wants it.
+//
 // # A route can decline to be hydrated
 //
 // uf's server-component analysis decides which routes have a `"use client"`
@@ -61,17 +91,23 @@
 
 import * as React from "react";
 import { StrictMode, startTransition } from "react";
-import { hydrateRoot } from "react-dom/client";
+import { createRoot, hydrateRoot } from "react-dom/client";
 
 import {
   type AppProps,
+  type Navigation,
   type RouteTable,
+  RedirectError,
   hasClientPage,
+  installNavigation,
   installRoutes,
   matchRoute,
+  resolveFailure,
   resolveMatch,
 } from "./internal/runtime.js";
 import { DATA_ID, ROOT_ID } from "./internal/document.js";
+import { decodePayload } from "./internal/payload.js";
+import { createPayloadReader, domObserver } from "./internal/payload-rows.js";
 
 /**
  * Hydrate the current document.
@@ -86,6 +122,7 @@ export async function hydrate(options: {|
   readonly notFound: RouteTable["notFound"],
   readonly errors: RouteTable["errors"],
   readonly strictMode?: boolean,
+  readonly navigation?: Navigation,
 |}): Promise<void> {
   const table: RouteTable = {
     routes: options.routes,
@@ -93,6 +130,11 @@ export async function hydrate(options: {|
     errors: options.errors,
   };
   installRoutes(table);
+  // Beside the table, and before anything renders. `"client"` when the entry
+  // says nothing, which is what `virtual:uf/client` generated before
+  // `app.rendering.navigation` existed and what a hand-written entry still
+  // means: the default is the behaviour, not the absence of one.
+  installNavigation(options.navigation ?? "client");
 
   // Before the loader data is read and before `resolveMatch` is called: both
   // would go looking for a page module that is not in this bundle.
@@ -102,12 +144,28 @@ export async function hydrate(options: {|
   }
 
   const url = window.location.pathname + window.location.search;
+  // Row 0 of the payload, and the reader that will fill in the rows it refers
+  // to. Both before `hydrateRoot`, and in this order: `decodePayload` is what
+  // tells the reader which rows the page is waiting for, and `watch` is what
+  // makes it notice the ones the server has not written yet. A document with
+  // nothing deferred has no references, so the reader is handed no ids, and
+  // `watch` returns without installing anything — see `internal/payload.js`.
   const embedded = document.getElementById(DATA_ID);
-  const data = embedded != null ? JSON.parse(embedded.textContent ?? "null") : undefined;
+  const reader = createPayloadReader(document, domObserver(document));
+  const data =
+    embedded != null
+      ? decodePayload(
+          JSON.parse(embedded.textContent ?? "null"),
+          reader.resolve,
+          "the route's loader data",
+        )
+      : undefined;
+  reader.watch();
   const resolved = await resolveMatch(table, url, { data, skipLoader: embedded != null });
 
   const { App } = options;
   const container = document.getElementById(ROOT_ID) ?? document;
+  prepareDocumentForHydration(document);
 
   // The server's markup, and the reporter that will read it, in development
   // only. Both have to be in place *before* `hydrateRoot`: React repairs a
@@ -117,13 +175,16 @@ export async function hydrate(options: {|
   // `import.meta.hot` is the gate because it is the one signal that is right in
   // all three places this module is evaluated. Vite defines it while serving
   // and replaces it with `undefined` in a build, so the branch is statically
-  // dead there; Node leaves it undefined, so `tests/library/rsc-split.test.js`
+  // dead there; Node leaves it undefined, so `packages/vite/rsc-split.test.js`
   // imports this file without a bundler and gets the production path. The
   // import is dynamic so that the overlay is not merely shaken out of a
   // production bundle but never reachable from one.
   let recovery = null;
+  let restoreDevHead = null;
   if (import.meta.hot != null) {
-    const { captureServerMarkup, hydrationErrorHandler } = await import("./internal/hydration.js");
+    const { captureServerMarkup, hydrationErrorHandler, prepareDevHeadForHydration } =
+      await import("./internal/hydration.js");
+    restoreDevHead = prepareDevHeadForHydration(document);
     recovery = hydrationErrorHandler(container, captureServerMarkup(container), document);
   }
 
@@ -138,6 +199,9 @@ export async function hydrate(options: {|
       options.strictMode === true ? <StrictMode>{tree}</StrictMode> : tree,
       recovery == null ? undefined : { onRecoverableError: recovery },
     );
+    if (restoreDevHead != null) {
+      setTimeout(restoreDevHead, 250);
+    }
   });
 
   // And, in development only, whether the panel a developer is about to open
@@ -152,3 +216,121 @@ export async function hydrate(options: {|
     reportDevtools(window);
   }
 }
+
+function prepareDocumentForHydration(document: Document): void {
+  const head = document.head;
+  const envelope = head.querySelector('meta[name="uf:render"]');
+  if (envelope != null && head.firstChild !== envelope) {
+    head.insertBefore(envelope, head.firstChild);
+  }
+  moveLayoutMetaAfterRouteHead(head, head.querySelector("meta[charset]"));
+  moveLayoutMetaAfterRouteHead(head, head.querySelector('meta[name="viewport"]'));
+  document.getElementById("_R_")?.remove();
+  normalizeReactFormActions(document);
+}
+
+function moveLayoutMetaAfterRouteHead(head: HTMLHeadElement, meta: Element | null): void {
+  if (meta == null) {
+    return;
+  }
+  const colorScheme = head.querySelector('meta[name="color-scheme"]');
+  if (colorScheme != null && colorScheme !== meta) {
+    head.insertBefore(meta, colorScheme);
+    return;
+  }
+  head.appendChild(meta);
+}
+
+const SERVER_FORM_PLACEHOLDER = "javascript:throw new Error('React form unexpectedly submitted.')";
+const CLIENT_FORM_PLACEHOLDER =
+  "javascript:throw new Error('A React form was unexpectedly submitted. If you called form.submit() manually, consider using form.requestSubmit() instead. If you\\'re trying to use event.stopPropagation() in a submit event handler, consider also calling event.preventDefault().')";
+
+function normalizeReactFormActions(document: Document): void {
+  for (const form of document.querySelectorAll("form")) {
+    if (form.getAttribute("action") === SERVER_FORM_PLACEHOLDER) {
+      form.setAttribute("action", CLIENT_FORM_PLACEHOLDER);
+    }
+  }
+}
+
+/**
+ * Render the current route into an empty shell.
+ *
+ * The single-page entry point: `app.rendering.modes: ["csr"]` writes one
+ * document with an empty root and no markup in it, and this is what fills it.
+ *
+ * # Why it is not `hydrate` with a flag
+ *
+ * Because hydration is React comparing what it renders against what a server
+ * sent, and here no server sent anything. `hydrateRoot` against an empty
+ * container is a mismatch on the first node of every page — React would report
+ * it, throw the shell away and render from scratch, which is this function
+ * with a warning in front of it. `createRoot` says what is actually happening:
+ * the browser is the only renderer this application has.
+ *
+ * Three more things follow from there, and each of them is a line below rather
+ * than an omission:
+ *
+ *   * **The loader runs here.** `resolveMatch` fetches the route's modules and
+ *     runs its loader in the browser, because there was no server render to run
+ *     it in and no `<script id="__uf_data">` for it to have left an answer in.
+ *   * **A URL that matches nothing is the not-found boundary**, resolved the
+ *     way a server resolves it. The host served this shell for a URL it had no
+ *     file for, so "nothing matched" is a perfectly ordinary arrival here
+ *     rather than the exception it is during hydration.
+ *   * **A redirect is the browser's.** `redirect()` from a loader throws before
+ *     anything is rendered; on a server that becomes a 307 and here it becomes
+ *     `location.replace`, which is the same instruction to the same browser.
+ */
+export async function render(options: {|
+  readonly App: React.ComponentType<AppProps>,
+  readonly routes: RouteTable["routes"],
+  readonly notFound: RouteTable["notFound"],
+  readonly errors: RouteTable["errors"],
+  readonly strictMode?: boolean,
+  readonly navigation?: Navigation,
+|}): Promise<void> {
+  const table: RouteTable = {
+    routes: options.routes,
+    notFound: options.notFound,
+    errors: options.errors,
+  };
+  installRoutes(table);
+  installNavigation(options.navigation ?? "client");
+
+  const url = window.location.pathname + window.location.search;
+  let resolved;
+  try {
+    resolved = await resolveMatch(table, url);
+  } catch (error) {
+    if (error instanceof RedirectError) {
+      window.location.replace(error.to);
+      return;
+    }
+    // The error boundary, chosen the same way the server chooses it. A throw
+    // from a loader is a page that cannot render, and rendering the boundary is
+    // what this application has instead of a 500.
+    resolved = await resolveFailure(table, url, error);
+  }
+
+  const { App } = options;
+  // An element, and never `document` — which is the other difference from
+  // `hydrate` above. `hydrateRoot` takes a document, because an app whose root
+  // layout renders `<html>` owns the whole of one and the server wrote it;
+  // `createRoot` does not, because creating a root *is* replacing the
+  // container's children and the container here would be the document. The
+  // shell always writes this element, so its absence means the document being
+  // rendered into is not one this build produced.
+  const container = document.getElementById(ROOT_ID);
+  if (container == null) {
+    throw new Error(
+      `@uniflowed/router: no #${ROOT_ID} in this document, so there is nothing to render into. ` +
+        "A single-page build writes the shell that carries it; this document came from " +
+        "somewhere else.",
+    );
+  }
+  const tree = <App url={url} initial={resolved} />;
+  createRoot(container).render(
+    options.strictMode === true ? <StrictMode>{tree}</StrictMode> : tree,
+  );
+}

package/handler.js

@@ -2,13 +2,13 @@
 //
 // Route handlers: a path that answers a request instead of rendering a page.
 //
-// `app/api/users/_uf.route.js` exporting `GET` and `POST` serves
+// `app/api/users/$route.js` exporting `GET` and `POST` serves
 // `/api/users`. A handler takes a `Request` and returns a `Response` — the
 // platform's own types, not a framework's wrapper — because that is what runs
 // unchanged on Node.js, Bun, Deno and a Cloudflare Worker, and uf's whole
 // position is that the host is a capability rather than a target.
 //
-//   // app/api/users/[id]/_uf.route.js
+//   // app/api/users/[id]/$route.js
 //   // @flow
 //   export async function GET(request: Request, context: HandlerContext) {
 //     const user = await find(context.params.id);

package/index.js

@@ -2,19 +2,26 @@
 //
 // `@uniflowed/router`: the file-system router.
 //
-// Pages live in `app/` as `_uf.page.js` (or `.mdx`), layouts as
-// `_uf.layout.js`, and `app.js` exports `routerView("./app")`. The route table
+// Pages live in `app/` as `$page.js` (or `.mdx`), layouts as
+// `$layout.js`, and `app.js` exports `routerView("./app")`. The route table
 // is generated from the directory at build time; this module is the runtime
 // that matches, loads, navigates and renders it.
 //
-// `_uf.not-found.js` and `_uf.error.js` are the two boundaries: the page for a
+// `$not-found.js` and `$error.js` are the two boundaries: the page for a
 // path that matched nothing, and what renders in place of a subtree that threw.
 // Both are segment files, resolved by the nearest one above the path — and the
 // router root always has one of each, so a project that declares neither still
 // answers a 404 inside its own layouts rather than beside them.
 //
-// `_uf.template.js` is a layout that remounts on every navigation, for the
+// `$template.js` is a layout that remounts on every navigation, for the
 // cases where a layout's persistence is the wrong default.
+//
+// A directory named `@team` is a parallel-route slot: it contributes no URL
+// segment, and the layout of the segment that holds it receives the slot as a
+// `team` prop beside `children`. The slot's pages are matched against the same
+// URL the page is, so one URL renders two subtrees at once, and
+// `$default.js` is what a slot renders when the URL matched none of its
+// routes. See ubugeeei-prod/uf#267.
 
 import * as React from "react";
 
@@ -43,7 +50,10 @@ export type {
   RouteRecord,
   RouteTable,
   Router,
+  ResolvedSlot,
   SearchParams,
+  SlotRecord,
+  SlotRouteRecord,
   TemplateModule,
   TwitterCard,
 } from "./internal/runtime.js";
@@ -87,13 +97,26 @@ export type PageProps<
   readonly data: TData,
 |};
 
-/** Props an `_uf.error.js` component receives. */
+/** Props an `$error.js` component receives. */
 export type ErrorProps = {|
   readonly error: RouteError,
   readonly reset: () => void,
 |};
 
-/** Props a layout receives. */
+/**
+ * Props a layout receives.
+ *
+ * A layout on a segment that declares parallel-route slots receives one more
+ * prop per slot, named after the directory without its `@`, and this exact
+ * type does not describe those — the names are the project's. Declare them: a
+ * layout beside `@team` and `@analytics` is
+ *
+ *     component Dashboard(children: React.Node, team: React.Node, analytics: React.Node)
+ *
+ * and the router passes `null` for a slot the URL addressed by neither a route
+ * of its own nor a `$default.js`, so `{team ?? <Empty />}` is a thing that
+ * can be written and relied on.
+ */
 export type LayoutProps<
   TParams extends { readonly [string]: string | $ReadOnlyArray<string> } = {},
 > = {|

package/internal/action-wire.js

@@ -61,9 +61,12 @@
 //
 // * **A reference format.** React's Flight payload can carry a reference to a
 //   client module, a promise, or an element, and a decoder that reconstructs
-//   those is a decoder that constructs attacker-chosen objects. uf has no such
-//   payload (ubugeeei-prod/uf#252) and this grammar is not the place to grow
-//   one quietly.
+//   those is a decoder that constructs attacker-chosen objects. uf's payload
+//   (`./payload.js`) now carries one of the three — a reference to a *row of
+//   itself*, which names nothing to construct — and it is a document the
+//   server writes rather than a body somebody sends. This grammar is the one
+//   an untrusted sender is decoded under, so it still has none, and it is
+//   still not the place to grow one quietly (ubugeeei-prod/uf#252).
 // * **Class instances, `Map`, `Set`, `Date`, `RegExp`, typed arrays.** Each
 //   would need a tag in the payload saying which constructor to call, and a
 //   tag naming a constructor is the oracle every deserialisation CVE is made