@uniflowed/router 0.0.0-alpha.34 → 0.0.0-alpha.37

package/client.js

@@ -14,6 +14,13 @@
 // *before* `hydrateRoot`, so the first client render is synchronous and
 // matches the server's markup exactly.
 //
+// An application whose routes render as React Server Components, the default,
+// starts from neither: `hydrateFlight` in `./rsc-client.js` hydrates the Flight
+// payload its document carries. That is a separate entry so that this one,
+// which every other web application imports, never names React's Flight
+// client. The client is an optional peer that needs React 19.3, and a project
+// on React 19.2 does not install it (ubugeeei-prod/uf#992).
+//
 // # What "its loader data" means once the loader can defer
 //
 // It is a payload rather than a value: `internal/payload.js` writes the model
@@ -101,6 +108,7 @@ import {
   hasClientPage,
   installNavigation,
   installRoutes,
+  installRouting,
   matchRoute,
   resolveFailure,
   resolveMatch,
@@ -108,6 +116,8 @@ import {
 import { DATA_ID, ROOT_ID } from "./internal/document.js";
 import { decodePayload } from "./internal/payload.js";
 import { createPayloadReader, domObserver } from "./internal/payload-rows.js";
+import { prepareDocumentForHydration } from "./internal/prepare-document.js";
+import { type TrailingSlash, addressOf, applicationPathOf } from "./internal/base-path.js";
 
 /**
  * Hydrate the current document.
@@ -123,6 +133,8 @@ export async function hydrate(options: {|
   readonly errors: RouteTable["errors"],
   readonly strictMode?: boolean,
   readonly navigation?: Navigation,
+  readonly basePath?: string,
+  readonly trailingSlash?: TrailingSlash,
 |}): Promise<void> {
   const table: RouteTable = {
     routes: options.routes,
@@ -135,15 +147,18 @@ export async function hydrate(options: {|
   // `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");
+  installRouting({ basePath: options.basePath, trailingSlash: options.trailingSlash });
+  // The route table has no base path in it, and the address bar does.
+  const applicationPath = applicationPathOf(window.location.pathname) ?? window.location.pathname;
 
   // 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.
-  const matched = matchRoute(table.routes, window.location.pathname);
+  const matched = matchRoute(table.routes, applicationPath);
   if (matched != null && !hasClientPage(matched.route)) {
     return;
   }
 
-  const url = window.location.pathname + window.location.search;
+  const url = applicationPath + 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
@@ -217,42 +232,6 @@ export async function hydrate(options: {|
   }
 }
 
-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.
  *
@@ -289,6 +268,8 @@ export async function render(options: {|
   readonly errors: RouteTable["errors"],
   readonly strictMode?: boolean,
   readonly navigation?: Navigation,
+  readonly basePath?: string,
+  readonly trailingSlash?: TrailingSlash,
 |}): Promise<void> {
   const table: RouteTable = {
     routes: options.routes,
@@ -297,14 +278,17 @@ export async function render(options: {|
   };
   installRoutes(table);
   installNavigation(options.navigation ?? "client");
+  installRouting({ basePath: options.basePath, trailingSlash: options.trailingSlash });
 
-  const url = window.location.pathname + window.location.search;
+  const url =
+    (applicationPathOf(window.location.pathname) ?? 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);
+      window.location.replace(addressOf(error.to));
       return;
     }
     // The error boundary, chosen the same way the server chooses it. A throw

package/index.js

@@ -73,6 +73,7 @@ export {
   RouteView,
   RouterProvider,
   UnauthorizedError,
+  basePath,
   buildRoute,
   forbidden,
   hasClientPage,

package/internal/base-path.js

@@ -0,0 +1,175 @@
+// @flow
+//
+// Internal to `@uniflowed/router`: `app.router.basePath` and
+// `app.router.trailingSlash`, as the router reads them.
+//
+// The route table has no base in it — `/guide` is `/guide` whether the site is
+// served at `/` or at `/docs` — and the browser's address bar has one. This
+// module is the one place those two spellings meet: a `Link` and a navigation
+// turn an application path into the address, and hydration, `popstate` and a
+// refresh turn the address back into an application path before the table is
+// asked. Every other part of the router speaks application paths.
+//
+// The policy decides the spelling of a path a link writes, so that a page is
+// linked by the address its server answers without a redirect. The server's
+// half — the `308` for the other spelling, and the `404` outside the base — is
+// `@uniflowed/server`'s `internal/routing.js`.
+//
+// # Installed, like navigation
+//
+// Module state beside `installNavigation`, set once by the entry that started
+// the application: `virtual:uf/client` in the browser and `virtual:uf/server`
+// in the graph that renders documents. `@uniflowed/vite` writes both calls from
+// `uf.config.js`, so a dev server and a build link the same way. A test that
+// installs nothing gets the root and `"ignore"`, which is what every
+// application had before the setting existed.
+
+/** Which spelling of a path is the page; see `app.router.trailingSlash`. */
+export type TrailingSlash = "never" | "always" | "ignore";
+
+/** What an entry installs. */
+export type RoutingSettings = {|
+  readonly basePath?: string,
+  readonly trailingSlash?: TrailingSlash,
+|};
+
+let installedBase: string = "";
+let installedSlash: TrailingSlash = "ignore";
+
+/**
+ * Say where this application is served and how its paths are spelled. Called
+ * once, by the entry that starts it.
+ */
+export function installRouting(settings: RoutingSettings): void {
+  installedBase = normalizeBase(settings.basePath ?? "");
+  installedSlash = settings.trailingSlash ?? "ignore";
+}
+
+/**
+ * The path this application is served under: `""` at the root, `"/docs"`
+ * otherwise.
+ *
+ * For code that builds an absolute address the router did not build for it —
+ * a middleware's `Response.redirect(new URL(`${basePath()}/sign-in`, request.url))`
+ * — because a route handler and a middleware are handed the application path,
+ * and an address built from `/sign-in` alone leaves the base behind.
+ */
+export function basePath(): string {
+  return installedBase;
+}
+
+/** How this application spells a path. */
+export function trailingSlash(): TrailingSlash {
+  return installedSlash;
+}
+
+/**
+ * The address for an application path: the base in front, the policy's
+ * spelling, the query and the fragment kept.
+ *
+ * Only a path that starts with a single `/` is an application path. Anything
+ * else — `https://…`, `//cdn…`, `mailto:`, `?page=2`, `#top`, `../up` — is
+ * returned as it was written, because the browser resolves it against the
+ * address that is already there.
+ */
+export function addressOf(to: string): string {
+  if (!to.startsWith("/") || to.startsWith("//")) {
+    return to;
+  }
+  const { path, rest } = splitPath(to);
+  return `${installedBase}${spellPath(path, installedSlash, installedBase !== "")}${rest}`;
+}
+
+/**
+ * The application path for an address's pathname, or `null` when the address
+ * is outside the base.
+ *
+ * `/docs/guide` is `/guide` under `/docs`, and `/docs` and `/docs/` are both
+ * `/`. `/docsx` is not under `/docs`: a base is whole segments.
+ */
+export function applicationPathOf(pathname: string): string | null {
+  if (installedBase === "") {
+    return pathname;
+  }
+  if (pathname === installedBase) {
+    return "/";
+  }
+  if (pathname.startsWith(`${installedBase}/`)) {
+    return pathname.slice(installedBase.length);
+  }
+  return null;
+}
+
+/**
+ * A browser pathname in this application's spelling: the base kept, the
+ * application path under it spelled by the policy. A pathname outside the
+ * base is returned as it was.
+ *
+ * For an address the router read back rather than wrote — the document path a
+ * payload URL names has lost its trailing slash, and the history entry a
+ * navigation writes should be the address the server answers without a
+ * redirect.
+ */
+export function canonicalAddress(pathname: string): string {
+  const application = applicationPathOf(pathname);
+  if (application == null) {
+    return pathname;
+  }
+  const spelled = spellPath(application, installedSlash, installedBase !== "");
+  return `${installedBase}${spelled}`;
+}
+
+/**
+ * `path` in `policy`'s spelling.
+ *
+ * The root of an application at the root is `/` whatever the policy says. The
+ * root of an application under a base is the base itself — `/docs` — unless
+ * the policy is `"always"`, which spells it `/docs/`. A path whose last segment
+ * looks like a file keeps what it was written with, because `/robots.txt/` is
+ * not a page.
+ */
+export function spellPath(path: string, policy: TrailingSlash, underBase: boolean): string {
+  let end = path.length;
+  while (end > 0 && path.charCodeAt(end - 1) === 47) {
+    end -= 1;
+  }
+  const trimmed = path.slice(0, end);
+  if (trimmed === "") {
+    return policy === "always" || !underBase ? "/" : "";
+  }
+  if (policy === "ignore" || looksLikeAFile(trimmed)) {
+    return path;
+  }
+  return policy === "always" ? `${trimmed}/` : trimmed;
+}
+
+/** Whether a path's last segment has an extension. */
+function looksLikeAFile(path: string): boolean {
+  const last = path.slice(path.lastIndexOf("/") + 1);
+  return last.includes(".");
+}
+
+function splitPath(to: string): {| readonly path: string, readonly rest: string |} {
+  let end = to.length;
+  for (let index = 0; index < to.length; index += 1) {
+    const code = to.charCodeAt(index);
+    // `?` and `#`.
+    if (code === 63 || code === 35) {
+      end = index;
+      break;
+    }
+  }
+  return { path: to.slice(0, end), rest: to.slice(end) };
+}
+
+/**
+ * A base as `uf_config` accepts one, with a trailing slash forgiven: `""`,
+ * `"/"` and absent are the root.
+ */
+function normalizeBase(base: string): string {
+  let end = base.length;
+  while (end > 0 && base.charCodeAt(end - 1) === 47) {
+    end -= 1;
+  }
+  return base.slice(0, end);
+}

package/internal/boundaries.js

@@ -83,8 +83,10 @@
 // package is `sideEffects: false`, so with the references folded away the
 // module is dropped rather than merely unused.
 
+"use client";
+
 import * as React from "react";
-import { useEffect, useState } from "react";
+import { useEffect, useSyncExternalStore } from "react";
 
 import { SYNTHESISED_SOURCE } from "./boundary-data.js";
 import { reportDiagnostic } from "./diagnostics.js";
@@ -114,13 +116,32 @@ export const BOUNDARY_GLOBAL: string = "__ufBoundaries";
 /**
  * Whether an edge that mounts now should be in the DOM immediately.
  *
- * Latched by the first edge to mount and never cleared. Read through
- * `useState`'s initialiser rather than during the render body, which is the
- * difference between "this component's first state" and "a module variable a
+ * Latched by the first edge to mount and never cleared, and read through
+ * `useSyncExternalStore` rather than during the render body, which is the
+ * difference between "a value React asked for" and "a module variable a
  * memoising compiler is entitled to hold on to".
  */
 let marksAreLive = false;
 
+/** The edges waiting to hear that marks have gone live. */
+const liveListeners: Set<() => void> = new Set();
+
+function subscribeToLiveMarks(listener: () => void): () => void {
+  liveListeners.add(listener);
+  return () => {
+    liveListeners.delete(listener);
+  };
+}
+
+function marksAreLiveNow(): boolean {
+  return marksAreLive;
+}
+
+/** What a server rendered, and so what every hydrating edge renders: nothing. */
+function noMarksOnTheServer(): boolean {
+  return false;
+}
+
 /**
  * One end of one boundary.
  *
@@ -128,12 +149,25 @@ let marksAreLive = false;
  * This used to be a `<template>`, but React 19.3 reports template insertion
  * during document-root hydration as a browser error. A `span hidden` carries
  * the same marker data without entering layout or the accessibility tree.
+ *
+ * # Why the server snapshot, and not a first state
+ *
+ * An edge used to take `marksAreLive` as its first state, which is right only
+ * if every edge on a page hydrates in the same pass. Under React Server
+ * Components they do not: a client reference loads when the payload names it,
+ * so the part of the tree above it hydrates, commits and runs this effect
+ * first, and an edge that hydrates afterwards read `true` and rendered a mark
+ * the server never wrote — a hydration mismatch on every page with a boundary
+ * below a client component, under `uf dev` only. `useSyncExternalStore` hands a
+ * hydrating edge the server's answer whenever it hydrates, and an edge mounted
+ * by a navigation or by HMR the live one, in its own commit, as before.
  */
-component BoundaryEdge(boundary: RouteBoundary, edge: "open" | "close") {
-  const [live, setLive] = useState<boolean>(() => marksAreLive);
+export component BoundaryEdge(boundary: RouteBoundary, edge: "open" | "close") {
+  const live = useSyncExternalStore(subscribeToLiveMarks, marksAreLiveNow, noMarksOnTheServer);
   useEffect(() => {
+    if (marksAreLive) return;
     marksAreLive = true;
-    setLive(true);
+    for (const listener of [...liveListeners]) listener();
   }, []);
   if (!live) {
     return null;
@@ -154,25 +188,14 @@ component BoundaryEdge(boundary: RouteBoundary, edge: "open" | "close") {
 /**
  * `children`, between the two marks of `boundary`.
  *
- * `children` unchanged when there is no boundary to mark, so a caller never has
- * to ask twice. The marks are the first and last children of a fragment rather
- * than a wrapper's, so the nodes between them are siblings of them, and every
- * position in the fragment is fixed — an edge going from `null` to a hidden
- * mark after mount is an insertion beside `children` and not around it,
- * which is why it costs no remount.
+ * Kept importable from here, where the marks are, and written in
+ * `./compose.js`, where they are placed. This module is a client module — an
+ * edge has state and an effect — and a server composing a tree for React Server
+ * Components calls the factory rather than rendering it, so the factory has to
+ * live in a module that graph evaluates while the edges it places stay
+ * references to this one. See ubugeeei-prod/uf#519.
  */
-export function insideBoundary(boundary: ?RouteBoundary, children: React.Node): React.Node {
-  if (boundary == null) {
-    return children;
-  }
-  return (
-    <>
-      <BoundaryEdge boundary={boundary} edge="open" />
-      {children}
-      <BoundaryEdge boundary={boundary} edge="close" />
-    </>
-  );
-}
+export { insideBoundary } from "./compose.js";
 
 /**
  * How far a walk between two marks will go before giving up.