@uniflowed/router 0.0.0-alpha.35 → 0.0.0-alpha.39

package/internal/navigation-cache.js

@@ -0,0 +1,144 @@
+// @flow
+//
+// Internal to `@uniflowed/router`: the routes a navigation already has.
+//
+// A navigation used to ask the server every time. A `Link` prefetched a route's
+// payload on hover and handed it to exactly one click, and every other way back
+// to a page the reader had just seen, a second visit or the back button, waited
+// on the network again (ubugeeei-prod/uf#960). This module is what a navigation
+// reads first instead: the route it fetched or prefetched, kept for
+// `app.rendering.staleTime` seconds and asked for again after that.
+//
+// # Off until a project says a number
+//
+// uf's caches are opt-in, and this one is too. `staleTime` is `0` until a
+// project writes one, and at `0` nothing is kept, so a navigation shows what the
+// server answered for it just now, which is the guarantee every project had
+// before the setting existed.
+//
+// # What is kept
+//
+// One promise per route, never a copy of what it resolved to:
+//
+// - an application React Server Components render keeps the payload fetch: the
+//   route's state and its tree, with the `$loading.js` fallbacks the tree
+//   carries, so going back to a page that was still streaming shows the loading
+//   shell the first visit did;
+// - an application rendered from its modules keeps the resolved route: the
+//   loader's data, and the page, layouts and loading boundaries it loaded.
+//
+// A promise rather than its value, so a click on a link whose prefetch is still
+// in flight waits on that request instead of making a second one. The router
+// forgets an entry whose fetch failed or turned out not to be a route.
+//
+// # Keyed by the application path
+//
+// The path and query the route table is asked about, without
+// `app.router.basePath`: `/docs/guide?tab=api` under `/docs` is kept as
+// `/guide?tab=api`. A fragment is never part of a key, because a server never
+// sees one.
+//
+// # Cleared, not revalidated in place
+//
+// `router.refresh()` and every server action clear the whole cache. An action
+// is a write, and which pages it changed is the server's to know, so the next
+// navigation to any of them asks again rather than showing what the write made
+// untrue.
+
+import { applicationPathOf } from "./base-path.js";
+import type { FetchedFlight } from "./flight.js";
+import type { ResolvedRoute } from "./resolve.js";
+
+/** How many routes each cache keeps at once. Past it, the oldest is dropped. */
+export const NAVIGATION_CACHE_LIMIT = 32;
+
+let staleTimeMs: number = 0;
+
+/**
+ * Say how long, in seconds, a route a navigation fetched is shown again without
+ * asking. `0`, the default, keeps nothing. Called once, by the entry that
+ * started the application.
+ */
+export function installStaleTime(seconds: number): void {
+  staleTimeMs = Number.isFinite(seconds) && seconds > 0 ? seconds * 1000 : 0;
+  if (staleTimeMs === 0) {
+    clearNavigationCache();
+  }
+}
+
+/** Whether navigations keep what they fetch. */
+export function keepsNavigations(): boolean {
+  return staleTimeMs > 0;
+}
+
+/** The key a URL's route is kept under: its application path, then its query. */
+export function navigationKey(pathname: string, search: string): string {
+  return `${applicationPathOf(pathname) ?? pathname}${search}`;
+}
+
+/** One kind of kept route. */
+export type NavigationCache<T> = {|
+  /** The route kept under `key`, while it is fresh. A stale one is dropped. */
+  readonly read: (key: string) => T | null,
+  /** Keep `value` under `key` from now. Nothing is kept while the stale time is `0`. */
+  readonly store: (key: string, value: T) => void,
+  /** Drop what `key` keeps, if it is still `value`. */
+  readonly forget: (key: string, value: T) => void,
+  readonly clear: () => void,
+  /** How many routes are kept, fresh or not. */
+  readonly size: () => number,
+|};
+
+function createNavigationCache<T>(): NavigationCache<T> {
+  const entries: Map<string, {| readonly value: T, readonly at: number |}> = new Map();
+  return {
+    read(key) {
+      const entry = entries.get(key);
+      if (entry == null) {
+        return null;
+      }
+      if (Date.now() - entry.at >= staleTimeMs) {
+        entries.delete(key);
+        return null;
+      }
+      return entry.value;
+    },
+    store(key, value) {
+      if (staleTimeMs === 0) {
+        return;
+      }
+      // Deleted first, so a route kept again moves to the young end.
+      entries.delete(key);
+      if (entries.size >= NAVIGATION_CACHE_LIMIT) {
+        const oldest = entries.keys().next();
+        if (oldest.done !== true) {
+          entries.delete(oldest.value);
+        }
+      }
+      entries.set(key, { value, at: Date.now() });
+    },
+    forget(key, value) {
+      if (entries.get(key)?.value === value) {
+        entries.delete(key);
+      }
+    },
+    clear() {
+      entries.clear();
+    },
+    size() {
+      return entries.size;
+    },
+  };
+}
+
+/** Payload fetches, for an application React Server Components render. */
+export const flightNavigations: NavigationCache<Promise<FetchedFlight>> = createNavigationCache();
+
+/** Resolved routes, for an application rendered from its modules. */
+export const routeNavigations: NavigationCache<Promise<ResolvedRoute>> = createNavigationCache();
+
+/** Forget every kept route. `router.refresh()` and each server action call this. */
+export function clearNavigationCache(): void {
+  flightNavigations.clear();
+  routeNavigations.clear();
+}

package/internal/prepare-document.js

@@ -0,0 +1,49 @@
+// @flow
+//
+// Internal to `@uniflowed/router`: a server's document, made ready for React to
+// hydrate.
+//
+// Where a server wrote the head's metadata, an element React leaves behind, and
+// the placeholder action React writes into a form whose action is a function
+// (its server and its client spell that placeholder differently): none of these
+// comes from a route, and each would be reported as a mismatch. So each is put
+// right before `hydrateRoot` compares the markup with the tree. Both ways of
+// hydrating do it — `hydrate` in `../client.js`, for a route rendered from its
+// modules, and `hydrateFlight` in `../rsc-client.js`, for one React Server
+// Components rendered — so the code lives here rather than in either entry.
+
+export 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);
+    }
+  }
+}

package/internal/react-version.js

@@ -0,0 +1,77 @@
+// @flow
+//
+// Internal to `@uniflowed/router`: the React that React Server Components need.
+//
+// The router installs beside React 19.2.3, the React that Expo SDK 57 and React
+// Native 0.87 ship. Matching a URL, the native route table and a route rendered
+// from its modules need nothing newer (ubugeeei-prod/uf#992). React Server
+// Components do. They render through `react-server-dom-parcel`, React's own
+// Flight renderer and client, which is released with React and requires the
+// React it was released with: 19.3. So that package is an optional peer, and
+// every module that loads it asks here first.
+//
+// # Why a check at run time
+//
+// A peer range cannot say it. The router has one range for `react`, and that
+// range has to admit 19.2.3 for a native app, while an optional peer that is
+// absent is never compared with anything. The failure is also not where the
+// mistake is: React's Flight client imports against React 19.2 and fails later,
+// inside a render, in terms of React's internals. So each entry that loads
+// Flight refuses before it does anything, and names the React it found and the
+// one it needs.
+//
+// It is a call rather than a statement at module scope, because no shipped
+// module runs anything when it is imported
+// (`crates/uf_lib/tests/package_surface.rs`).
+
+import * as React from "react";
+
+/** The oldest React that React Server Components render on. */
+export const SERVER_COMPONENTS_REACT: string = "19.3.0";
+
+/**
+ * Why `entry` cannot run on React `installed`, or `null` when it can.
+ *
+ * The release numbers are compared and a prerelease tag is ignored, so a 19.3
+ * canary counts as 19.3: React names a canary after the release it leads to.
+ */
+export function serverComponentsRefusal(entry: string, installed: string): string | null {
+  const found = releaseOf(installed);
+  const needed = releaseOf(SERVER_COMPONENTS_REACT);
+  if (found != null && needed != null && !isBefore(found, needed)) {
+    return null;
+  }
+  return (
+    `@uniflowed/router: ${entry} needs React ${SERVER_COMPONENTS_REACT} or newer for React ` +
+    `Server Components, and the React it loaded is ${installed}. Install react, react-dom and ` +
+    "react-server-dom-parcel at ^19.3.0, or set `app.rsc: false` in uf.config.js to render " +
+    "routes from their modules, which the router supports from React 19.2.3."
+  );
+}
+
+/**
+ * Refuse, with [`serverComponentsRefusal`]'s sentence, unless the React this
+ * module loaded can render React Server Components.
+ */
+export function requireServerComponentsReact(entry: string): void {
+  const refusal = serverComponentsRefusal(entry, React.version);
+  if (refusal != null) {
+    throw new Error(refusal);
+  }
+}
+
+/** `[major, minor, patch]` of a version, or `null` when it does not start with one. */
+function releaseOf(version: string): [number, number, number] | null {
+  const match = /^(\d+)\.(\d+)\.(\d+)/.exec(version);
+  return match == null ? null : [Number(match[1]), Number(match[2]), Number(match[3])];
+}
+
+/** Whether release `a` comes before release `b`. */
+function isBefore(a: [number, number, number], b: [number, number, number]): boolean {
+  for (let index = 0; index < 3; index += 1) {
+    if (a[index] !== b[index]) {
+      return a[index] < b[index];
+    }
+  }
+  return false;
+}