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

package/index.js

@@ -22,6 +22,12 @@
 // 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.
+//
+// A directory named `(.)photo` inside a slot is an intercepting route: a client
+// navigation that starts on a page the slot is on, and reaches the URL the
+// directory stands in for, renders it in the slot and leaves the page
+// underneath where it was. A document request for that URL — a reload, a
+// shared link, a prerender — renders the ordinary page.
 
 import * as React from "react";
 
@@ -31,6 +37,7 @@ export type {
   AppProps,
   ErrorBoundary,
   ErrorModule,
+  Interception,
   JsonLd,
   LayoutModule,
   LinkPrefetch,

package/internal/boundaries.js

@@ -86,7 +86,18 @@
 import * as React from "react";
 import { useEffect, useState } from "react";
 
+import { SYNTHESISED_SOURCE } from "./boundary-data.js";
 import { reportDiagnostic } from "./diagnostics.js";
+import type { RouteBoundary } from "./boundary-data.js";
+
+export type { BoundaryKind, RouteBoundary } from "./boundary-data.js";
+export {
+  ROOT_ERROR_ID,
+  ROUTE_ERROR_ID,
+  SYNTHESISED_SOURCE,
+  routeBoundaries,
+  suspenseId,
+} from "./boundary-data.js";
 
 /** The attribute a mark carries its boundary's id in. */
 export const BOUNDARY_ATTRIBUTE: string = "data-uf-boundary";
@@ -100,116 +111,6 @@ export const SOURCE_ATTRIBUTE: string = "data-uf-boundary-source";
 /** The name `uf dev` installs the on-demand report under. */
 export const BOUNDARY_GLOBAL: string = "__ufBoundaries";
 
-/**
- * What `file` says for the error boundary the build synthesises.
- *
- * `routesModuleSource` writes this string where a declared boundary has a path,
- * because the record has no module to name — the framework's own error page
- * renders in its place. Written out again rather than imported for the reason
- * `./devtools.js` gives about `DEVTOOLS_HOOK`: `@uniflowed/vite` is plain
- * JavaScript loaded by Vite before any Flow transform exists, so the import
- * cannot go either way. `boundaries.test.js` holds the two spellings together.
- */
-export const SYNTHESISED_SOURCE: string = "@uniflowed/router";
-
-/** Which kind of boundary a mark belongs to. */
-export type BoundaryKind = "suspense" | "error";
-
-/**
- * One boundary of a resolved route, as the marks and the report name it.
- *
- * `id` pairs the two marks and is stable for a boundary across renders, so a
- * navigation that keeps a boundary keeps its marks mounted. `above` is how many
- * of the route's layouts are outside it — the same number, spelled the same
- * way, that `ResolvedRoute["errorBoundary"].above` and every `loading` entry
- * carry, because there is no second vocabulary for where a thing sits in the
- * stack.
- *
- * `source` is the file it was declared in, and is `null` for every `<Suspense>`
- * boundary. That asymmetry is the route table's rather than this module's: an
- * error boundary is matched by path, so the table carries its `file`, while a
- * `$loading.js` is carried by depth alone. Adding a path to the loading
- * records would put one in every visitor's bundle to serve a report only
- * `uf dev` reads.
- */
-export type RouteBoundary = {|
-  readonly id: string,
-  readonly kind: BoundaryKind,
-  readonly above: number,
-  readonly source: ?string,
-|};
-
-/** The id of the `<Suspense>` boundary at `index` of a route's `loading`. */
-export function suspenseId(index: number): string {
-  return `suspense:${index}`;
-}
-
-/** The id of the boundary a route's own `$error.js` renders. */
-export const ROUTE_ERROR_ID: string = "error:route";
-
-/**
- * The id of the boundary that stands outside every layout.
- *
- * It has no module and renders the framework's page; it is what is between a
- * throw in a root layout, or in the error component itself, and an unmounted
- * document. Marked like any other, because "which subtree does the last resort
- * own" is exactly as unanswerable from the page as the rest.
- */
-export const ROOT_ERROR_ID: string = "error:root";
-
-/** The part of a resolved route this module reads. */
-type BoundedRoute = {
-  readonly errorBoundary: { readonly above: number, ... },
-  readonly loading: $ReadOnlyArray<{ readonly above: number, ... }>,
-  readonly error: mixed,
-  ...
-};
-
-/**
- * Every boundary a resolved route renders, in the order they nest.
- *
- * A `Map` rather than a list because it is read both ways: `RouteView` asks for
- * one by id as it builds the stack, and the report walks the values. One
- * function answering both is the point — an id `RouteView` marks and the report
- * cannot find is a boundary that silently disappears from the map, and
- * ubugeeei-prod/uf#636 made the same argument about an explanation that can
- * disagree with the thing it explains.
- *
- * The route's own error boundary is absent when the route *is* its error page,
- * which is exactly when `RouteView` does not render one: wrapping that page in
- * the boundary whose component it is would answer a throw inside it with
- * itself.
- *
- * @param resolved the route being rendered
- * @param errorSource the `file` of the nearest `$error.js`, when the table
- *   has one; `null` leaves the boundary named by its depth alone
- */
-export function routeBoundaries(
-  resolved: BoundedRoute,
-  errorSource: ?string,
-): Map<string, RouteBoundary> {
-  const found: Map<string, RouteBoundary> = new Map();
-  found.set(ROOT_ERROR_ID, {
-    id: ROOT_ERROR_ID,
-    kind: "error",
-    above: 0,
-    source: SYNTHESISED_SOURCE,
-  });
-  if (resolved.error == null) {
-    found.set(ROUTE_ERROR_ID, {
-      id: ROUTE_ERROR_ID,
-      kind: "error",
-      above: resolved.errorBoundary.above,
-      source: errorSource,
-    });
-  }
-  resolved.loading.forEach((boundary, index) => {
-    const id = suspenseId(index);
-    found.set(id, { id, kind: "suspense", above: boundary.above, source: null });
-  });
-  return found;
-}
-
 /**
  * Whether an edge that mounts now should be in the DOM immediately.
  *

package/internal/boundary-data.js

@@ -0,0 +1,88 @@
+// @flow
+//
+// React-free names for the boundaries a resolved route renders.
+
+/**
+ * What `file` says for the error boundary the build synthesises.
+ *
+ * `routesModuleSource` writes this string where a declared boundary has a path,
+ * because the record has no module to name: the framework's own error page
+ * renders in its place. This module is plain data so the routing surface and
+ * the dev-only DOM marker code can share one spelling without importing React.
+ */
+export const SYNTHESISED_SOURCE: string = "@uniflowed/router";
+
+/** Which kind of boundary a mark or payload row belongs to. */
+export type BoundaryKind = "suspense" | "error";
+
+/** The id of the `<Suspense>` boundary at `index` of a route's `loading`. */
+export function suspenseId(index: number): string {
+  return `suspense:${index}`;
+}
+
+/** The id of the boundary a route's own `$error.js` renders. */
+export const ROUTE_ERROR_ID: string = "error:route";
+
+/**
+ * The id of the boundary that stands outside every layout.
+ *
+ * It has no module and renders the framework's page; it is what is between a
+ * throw in a root layout, or in the error component itself, and an unmounted
+ * document.
+ */
+export const ROOT_ERROR_ID: string = "error:root";
+
+/**
+ * One boundary of a resolved route, in uf's vocabulary rather than React's.
+ *
+ * `id` is the stable name `RouteView` marks in the DOM today and the name a
+ * future element payload can put beside the chunk that completed it. `above`
+ * is how many layouts are outside the boundary.
+ */
+export type RouteBoundary = {|
+  readonly id: string,
+  readonly kind: BoundaryKind,
+  readonly above: number,
+  readonly source: ?string,
+|};
+
+/** The part of a resolved route the boundary map reads. */
+type BoundedRoute = {
+  readonly errorBoundary: { readonly above: number, ... },
+  readonly loading: $ReadOnlyArray<{ readonly above: number, ... }>,
+  readonly error: mixed,
+  ...
+};
+
+/**
+ * Every boundary a resolved route renders, in the order they nest.
+ *
+ * A `Map` rather than a list because callers read it both ways: `RouteView`
+ * asks for one by id as it builds the stack, while diagnostics and payload
+ * summaries walk the values.
+ */
+export function routeBoundaries(
+  resolved: BoundedRoute,
+  errorSource: ?string,
+): Map<string, RouteBoundary> {
+  const found: Map<string, RouteBoundary> = new Map();
+  found.set(ROOT_ERROR_ID, {
+    id: ROOT_ERROR_ID,
+    kind: "error",
+    above: 0,
+    source: SYNTHESISED_SOURCE,
+  });
+  if (resolved.error == null) {
+    found.set(ROUTE_ERROR_ID, {
+      id: ROUTE_ERROR_ID,
+      kind: "error",
+      above: resolved.errorBoundary.above,
+      source: errorSource,
+    });
+  }
+  resolved.loading.forEach((boundary, index) => {
+    const id = suspenseId(index);
+    found.set(id, { id, kind: "suspense", above: boundary.above, source: null });
+  });
+  return found;
+}

package/internal/inspector.js

@@ -27,7 +27,7 @@
 // lands this is the recorder it is fed to: `inspectStream` takes chunks and
 // knows nothing about who produced them.
 //
-// # It reads React's own markers, and no others
+// # It reads React's markers, plus uf's row marker
 //
 // Fizz writes a suspended boundary into the shell as an empty
 // `<template id="B:0">` followed by the fallback and closed by a `<!--/$-->`
@@ -46,6 +46,11 @@
 // content of these chunks is the application's own — with a step limit on every
 // loop for the same reason `./boundaries.js` has a `WALK_LIMIT`.
 //
+// The one uf-owned marker read here is `data-uf-row` on deferred payload row
+// scripts. The inspector does not parse the row JSON or attach semantics to
+// the value; it only keeps the terminal report from saying a row boundary built
+// an anonymous `script`.
+//
 // A marker that a chunk boundary happened to split is not attributed rather
 // than guessed at: the chunk is still counted, still timed, and says so. The
 // alternative is a report that is confidently wrong about which part of the
@@ -81,6 +86,8 @@
 // honest report is silence. That is also what keeps this from being a request
 // log: it fires for the pages the feature is about and for no others.
 
+import { PAYLOAD_ROW_ATTRIBUTE } from "./payload.js";
+
 /** How many chunks of one document are recorded before the rest are counted. */
 const CHUNK_LIMIT = 64;
 
@@ -412,6 +419,10 @@ function topLevelElements(markup: string, from: number): $ReadOnlyArray<string>
 export function describeTag(tag: string): string {
   const space = tag.search(/[\s/>]/);
   const name = tag.slice(1, space === -1 ? tag.length : space).toLowerCase();
+  const row = name === "script" ? attribute(tag, PAYLOAD_ROW_ATTRIBUTE) : null;
+  if (row != null && row !== "") {
+    return `deferred payload row ${row}`;
+  }
   const id = attribute(tag, "id");
   if (id != null && id !== "") {
     return `${name}#${id}`;

package/internal/resolved-summary.js

@@ -0,0 +1,199 @@
+// @flow
+//
+// Module-free summaries of resolved routes.
+
+import { routeBoundaries, suspenseId } from "./boundary-data.js";
+import type { RouteBoundary } from "./boundary-data.js";
+import type { RouteParams, SearchParams } from "./routing.js";
+
+type RouteStatus = 200 | 401 | 403 | 404 | 500;
+
+type RouteMetadata = { readonly [string]: mixed, ... };
+
+type RouteErrorLike = {
+  readonly kind: "thrown" | "unauthorized" | "forbidden",
+  ...
+};
+
+type BoundaryLike = {
+  readonly above: number,
+  ...
+};
+
+type ModuleBoundaryLike = {
+  readonly above: number,
+  readonly module?: mixed,
+  ...
+};
+
+type SlotLike = {
+  readonly name: string,
+  readonly above: number,
+  readonly page: mixed,
+  readonly params: RouteParams,
+  readonly layouts: $ReadOnlyArray<mixed>,
+  readonly loading: $ReadOnlyArray<BoundaryLike>,
+  readonly templates: $ReadOnlyArray<BoundaryLike>,
+  readonly errorBoundary: ?ModuleBoundaryLike,
+  readonly slots: $ReadOnlyArray<SlotLike>,
+  ...
+};
+
+type RouteLike = {
+  readonly pathname: string,
+  readonly search: string,
+  readonly path: string,
+  readonly params: RouteParams,
+  readonly searchParams: SearchParams,
+  readonly layouts: $ReadOnlyArray<mixed>,
+  readonly data: mixed,
+  readonly deferred: mixed,
+  readonly metadata: RouteMetadata,
+  readonly viewTransition: ?string,
+  readonly status: RouteStatus,
+  readonly error: ?RouteErrorLike,
+  readonly errorBoundary: ModuleBoundaryLike,
+  readonly loading: $ReadOnlyArray<BoundaryLike>,
+  readonly templates: $ReadOnlyArray<BoundaryLike>,
+  readonly slots: $ReadOnlyArray<SlotLike>,
+  ...
+};
+
+export type ResolvedBoundarySummary = {|
+  readonly id: string,
+  readonly above: number,
+|};
+
+export type ResolvedTemplateSummary = {|
+  readonly above: number,
+|};
+
+export type ResolvedRouteErrorSummary =
+  | {| readonly kind: "thrown" |}
+  | {| readonly kind: "unauthorized" |}
+  | {| readonly kind: "forbidden" |};
+
+export type ResolvedErrorBoundarySummary = {|
+  readonly above: number,
+  readonly custom: boolean,
+  readonly rendered: boolean,
+|};
+
+export type ResolvedSlotSummary = {|
+  readonly name: string,
+  readonly above: number,
+  readonly active: boolean,
+  readonly params: RouteParams,
+  readonly layoutCount: number,
+  readonly loading: $ReadOnlyArray<ResolvedBoundarySummary>,
+  readonly templates: $ReadOnlyArray<ResolvedTemplateSummary>,
+  readonly errorBoundary: ?ResolvedErrorBoundarySummary,
+  readonly slots: $ReadOnlyArray<ResolvedSlotSummary>,
+|};
+
+export type ResolvedRouteSummary = {|
+  readonly pathname: string,
+  readonly search: string,
+  readonly path: string,
+  readonly params: RouteParams,
+  readonly searchParams: SearchParams,
+  readonly layoutCount: number,
+  readonly data: mixed,
+  readonly deferred: boolean,
+  readonly metadata: RouteMetadata,
+  readonly viewTransition: ?string,
+  readonly status: RouteStatus,
+  readonly error: ?ResolvedRouteErrorSummary,
+  readonly errorBoundary: ResolvedErrorBoundarySummary,
+  readonly loading: $ReadOnlyArray<ResolvedBoundarySummary>,
+  readonly templates: $ReadOnlyArray<ResolvedTemplateSummary>,
+  readonly slots: $ReadOnlyArray<ResolvedSlotSummary>,
+  readonly boundaries: $ReadOnlyArray<RouteBoundary>,
+|};
+
+/**
+ * The part of a `ResolvedRoute` that can cross to a payload or diagnostic.
+ *
+ * A resolved route carries loaded modules so `RouteView` can render today.
+ * The element payload in ubugeeei-prod/uf#519 needs the other half: route
+ * identity, data, metadata, status, and boundary names, with page/layout/
+ * fallback modules left behind in the renderer graph.
+ */
+export function summarizeResolvedRoute(
+  route: RouteLike,
+  errorSource?: ?string,
+): ResolvedRouteSummary {
+  return {
+    pathname: route.pathname,
+    search: route.search,
+    path: route.path,
+    params: route.params,
+    searchParams: route.searchParams,
+    layoutCount: route.layouts.length,
+    data: route.data,
+    deferred: route.deferred != null,
+    metadata: route.metadata,
+    viewTransition: route.viewTransition,
+    status: route.status,
+    error: summarizeError(route.error),
+    errorBoundary: summarizeErrorBoundary(route.errorBoundary, route.error == null),
+    loading: summarizeLoading(route.loading),
+    templates: summarizeTemplates(route.templates),
+    slots: route.slots.map(summarizeSlot),
+    boundaries: [...routeBoundaries(route, errorSource).values()],
+  };
+}
+
+function summarizeSlot(slot: SlotLike): ResolvedSlotSummary {
+  return {
+    name: slot.name,
+    above: slot.above,
+    active: slot.page != null,
+    params: slot.params,
+    layoutCount: slot.layouts.length,
+    loading: summarizeLoading(slot.loading),
+    templates: summarizeTemplates(slot.templates),
+    errorBoundary:
+      slot.errorBoundary == null ? null : summarizeErrorBoundary(slot.errorBoundary, true),
+    slots: slot.slots.map(summarizeSlot),
+  };
+}
+
+function summarizeLoading(
+  boundaries: $ReadOnlyArray<BoundaryLike>,
+): $ReadOnlyArray<ResolvedBoundarySummary> {
+  return boundaries.map((boundary, index) => ({
+    id: suspenseId(index),
+    above: boundary.above,
+  }));
+}
+
+function summarizeTemplates(
+  templates: $ReadOnlyArray<BoundaryLike>,
+): $ReadOnlyArray<ResolvedTemplateSummary> {
+  return templates.map((template) => ({ above: template.above }));
+}
+
+function summarizeErrorBoundary(
+  boundary: ModuleBoundaryLike,
+  rendered: boolean,
+): ResolvedErrorBoundarySummary {
+  return {
+    above: boundary.above,
+    custom: boundary.module != null,
+    rendered,
+  };
+}
+
+function summarizeError(error: ?RouteErrorLike): ?ResolvedRouteErrorSummary {
+  if (error == null) {
+    return null;
+  }
+  if (error.kind === "unauthorized") {
+    return { kind: "unauthorized" };
+  }
+  if (error.kind === "forbidden") {
+    return { kind: "forbidden" };
+  }
+  return { kind: "thrown" };
+}

package/internal/routing.js

@@ -31,29 +31,77 @@ export type LoadingRecord<TLoading = mixed> = {|
   readonly module: RouteModule<TLoading>,
 |};
 
+/** One `$error.js` inside a slot, as the route table carries it. */
+export type SlotErrorBoundaryRecord<TError = mixed> = {|
+  readonly above: number,
+  readonly module: RouteModule<TError>,
+|};
+
 /** One parallel-route slot, as the route table carries it. */
-export type SlotRecord<TPage = mixed, TLayout = mixed> = {|
+export type SlotRecord<
+  TPage = mixed,
+  TLayout = mixed,
+  TTemplate = mixed,
+  TLoading = mixed,
+  TError = mixed,
+> = {|
   readonly name: string,
   readonly above: number,
   readonly defaultPage: ?RouteModule<TPage>,
   readonly defaultFile?: string,
   readonly defaultMdx?: boolean,
-  readonly routes: $ReadOnlyArray<SlotRouteRecord<TPage, TLayout>>,
+  readonly defaultErrorBoundary?: ?SlotErrorBoundaryRecord<TError>,
+  readonly routes: $ReadOnlyArray<SlotRouteRecord<TPage, TLayout, TTemplate, TLoading, TError>>,
+  /**
+   * The routes this slot renders when a client navigation *intercepts* the URL
+   * each one names — `app/feed/@modal/(.)photo/[id]/$page.js` is the one for
+   * `/feed/photo/:id` — keyed by that URL.
+   *
+   * A second list rather than a flag on `routes`, because the two are read by
+   * different callers at different times and neither may see the other's.
+   * `routes` is matched against every URL the segment renders, by the server and
+   * by the browser alike. These are matched only by a navigation that starts on
+   * a page this slot is already rendered on, and nothing on a server reads them
+   * — which is the whole of why a document request for an intercepted URL
+   * renders the ordinary page. `resolveInterception`, beside the rest of the
+   * rendering, is the one reader.
+   *
+   * Absent on a slot that intercepts nothing, which is every slot a table
+   * written before interception existed.
+   */
+  readonly intercepts?: $ReadOnlyArray<
+    SlotRouteRecord<TPage, TLayout, TTemplate, TLoading, TError>,
+  >,
 |};
 
 /** One page inside a slot. */
-export type SlotRouteRecord<TPage = mixed, TLayout = mixed> = {|
+export type SlotRouteRecord<
+  TPage = mixed,
+  TLayout = mixed,
+  TTemplate = mixed,
+  TLoading = mixed,
+  TError = mixed,
+> = {|
   readonly path: string,
   readonly params: $ReadOnlyArray<RouteParamSpec>,
   readonly mdx: boolean,
   readonly file: string,
   readonly page: RouteModule<TPage>,
   readonly layouts: $ReadOnlyArray<RouteModule<TLayout>>,
-  readonly slots: $ReadOnlyArray<SlotRecord<TPage, TLayout>>,
+  readonly loading?: $ReadOnlyArray<LoadingRecord<TLoading>>,
+  readonly templates?: $ReadOnlyArray<TemplateRecord<TTemplate>>,
+  readonly errorBoundary?: ?SlotErrorBoundaryRecord<TError>,
+  readonly slots: $ReadOnlyArray<SlotRecord<TPage, TLayout, TTemplate, TLoading, TError>>,
 |};
 
 /** One entry of the generated route table. */
-export type RouteRecord<TPage = mixed, TLayout = mixed, TTemplate = mixed, TLoading = mixed> = {|
+export type RouteRecord<
+  TPage = mixed,
+  TLayout = mixed,
+  TTemplate = mixed,
+  TLoading = mixed,
+  TError = mixed,
+> = {|
   readonly path: string,
   readonly params: $ReadOnlyArray<RouteParamSpec>,
   readonly mdx: boolean,
@@ -62,7 +110,7 @@ export type RouteRecord<TPage = mixed, TLayout = mixed, TTemplate = mixed, TLoad
   readonly layouts: $ReadOnlyArray<RouteModule<TLayout>>,
   readonly loading?: $ReadOnlyArray<LoadingRecord<TLoading>>,
   readonly templates?: $ReadOnlyArray<TemplateRecord<TTemplate>>,
-  readonly slots?: $ReadOnlyArray<SlotRecord<TPage, TLayout>>,
+  readonly slots?: $ReadOnlyArray<SlotRecord<TPage, TLayout, TTemplate, TLoading, TError>>,
 |};
 
 /** One not-found boundary: the page for a path under `path` that matched nothing. */
@@ -90,12 +138,12 @@ export type RouteTable<
   TLoading = mixed,
   TError = mixed,
 > = {|
-  readonly routes: $ReadOnlyArray<RouteRecord<TPage, TLayout, TTemplate, TLoading>>,
+  readonly routes: $ReadOnlyArray<RouteRecord<TPage, TLayout, TTemplate, TLoading, TError>>,
   readonly notFound: $ReadOnlyArray<NotFoundBoundary<TPage, TLayout>>,
   readonly errors: $ReadOnlyArray<ErrorBoundary<TError, TLayout>>,
 |};
 
-type UnknownRouteRecord = RouteRecord<mixed, mixed, mixed, mixed>;
+type UnknownRouteRecord = RouteRecord<mixed, mixed, mixed, mixed, mixed>;
 
 /** A URL matched against a table. */
 export type RouteMatch<TRoute: { +path: string, ... } = UnknownRouteRecord> = {|