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

package/internal/compose.js

@@ -0,0 +1,478 @@
+// @flow
+//
+// Internal to `@uniflowed/router`: one walk from a resolved route to the tree
+// that renders it.
+//
+// The layouts, the `$loading.js` fallbacks, the error boundaries, the
+// templates and the parallel-route slots all have to be threaded into one stack
+// at the depth each was declared at, and there must be exactly one place that
+// does it. There used to be exactly one — `RouteView` — and it read the route
+// from the router's context, which is a place a server composing a tree for
+// React Server Components does not have. So the walk is a function of the
+// resolved route and the page element, `RouteView` calls it, and so can the
+// Flight renderer (ubugeeei-prod/uf#519): two callers of one composition rather
+// than two compositions that agree until one of them moves.
+//
+// Nothing here reads a context or calls a hook. The components it places — a
+// route's own modules, the error boundary, the dev-only boundary marks — are
+// referenced, not rendered, so what they need is decided where they render.
+
+import * as React from "react";
+import { Suspense } from "react";
+
+import { ROOT_ERROR_ID, ROUTE_ERROR_ID, suspenseId } from "./boundary-data.js";
+import type { RouteBoundary } from "./boundary-data.js";
+import { BoundaryEdge } from "./boundaries.js";
+import { RouteErrorBoundary } from "./error-view.js";
+import { Head } from "./head.js";
+import type { RouteParams, SearchParams } from "./routing.js";
+import type {
+  LayoutModule,
+  LayoutRenderProps,
+  LoadingModule,
+  PageModule,
+  PageRenderProps,
+  ResolvedRoute,
+  ResolvedSlot,
+  ResolvedTemplate,
+  TemplateModule,
+} from "./resolve.js";
+import { renderable } from "./resolve.js";
+
+/** What a caller hands [`composeRoute`] beside the resolved route. */
+export type ComposeOptions = {|
+  /**
+   * The innermost element: the page, and whatever the caller renders beside it.
+   *
+   * The caller's rather than this module's, because it is the one element that
+   * depends on where the route is being rendered — the browser reads the
+   * loader's answer out of its router, and a server has it in hand.
+   */
+  readonly page: React.Node,
+  /**
+   * The boundary marks `uf dev` draws, keyed by boundary id, or `null` for none.
+   *
+   * Read only behind [`BOUNDARY_MARKS`], so a build folds every use away.
+   */
+  readonly marks: ?Map<string, RouteBoundary>,
+|};
+
+/** The route a slot renders inside, as much of it as a slot reads. */
+type SlotRoute = { +pathname: string, +searchParams: SearchParams, ... };
+
+/**
+ * Whether this bundle marks the boundaries it renders.
+ *
+ * The same gate, spelled the same way, as `BOUNDARY_MARKS` in `./runtime.js`,
+ * which has the argument: `import.meta.hot` is defined while Vite serves and
+ * replaced with `undefined` in a build, so every branch it guards here is
+ * statically dead in a production bundle and `./boundaries.js` is dropped
+ * rather than shipped unused.
+ */
+const BOUNDARY_MARKS: boolean = import.meta.hot != null;
+
+/**
+ * The matched page inside its layouts, innermost last, with the document
+ * metadata as hoistable head elements.
+ *
+ * A function of a resolved route and the page element, and of nothing a render
+ * holds: no context is read here, so the same walk builds the tree the browser
+ * renders for a single-page application and the tree a server hands to React's
+ * Flight renderer. `RouteView` in `./runtime.js` is the browser's caller, and it
+ * decides the page element because that is the half that reads the router.
+ *
+ * # One walk down the layouts, not three
+ *
+ * The layouts, the error boundary and the `<Suspense>` boundaries all have to
+ * be threaded into the same stack at the depth each was declared at, so this
+ * is one descending loop over that depth rather than a pass per kind. `depth`
+ * counts the layouts still *outside* the element built so far, which is what
+ * `above` means on both a route's `errorBoundary` and each of its `loading`
+ * entries — one number, one meaning, one place it is compared.
+ *
+ * # Where the error boundaries go
+ *
+ * Two, and they are not the same thing twice. The inner one is the project's
+ * `$error.js`, placed at the depth the file sits at, so the layouts above
+ * it stay mounted and interactive while the subtree below is replaced — that
+ * placement *is* the feature. The outer one has no module and so renders the
+ * framework's page; it is what stands between a throw in a root layout, or in
+ * the error component itself, and an unmounted document. A single boundary
+ * cannot be both: put it outside and a page's throw takes the navigation down
+ * with it; put it inside and nothing catches the layout above.
+ *
+ * # Where the loading boundaries go
+ *
+ * Inside the layout of the segment that declared the file and outside
+ * everything under it, which is what makes the shell arrive first: a renderer
+ * streaming this tree can send every layout down to the boundary, and the
+ * fallback, before whatever the page is waiting for has resolved. A segment
+ * with no `$loading.js` contributes no boundary at all — it is not wrapped
+ * in a `<Suspense fallback={null}>` on the way past — so a project that
+ * declares none renders the tree it rendered before this existed, and a page
+ * that suspends without a boundary above it still fails the way React says it
+ * should rather than silently rendering nothing.
+ *
+ * The error boundary goes *outside* the fallback at the same depth. A throw
+ * while the page is resolving has to reach a boundary that is still mounted,
+ * and the `<Suspense>` is part of what the throw came out of.
+ *
+ * # Where the templates go
+ *
+ * Inside their own segment's layout and outside everything else at that depth
+ * — the error boundary, the fallback and the page — which is what makes a
+ * template's remount mean "this segment and what is under it" and a layout's
+ * persistence mean "this segment's frame". The two files are the same wrapper
+ * with opposite answers to one question, so they are one line apart here, and
+ * the whole of the difference is the `key` — see [`insideTemplates`], which is
+ * that line's other half.
+ *
+ * # Where the boundary marks go
+ *
+ * Inside each boundary and around nothing else, under `uf dev` only. A
+ * `<Suspense>` and a class boundary each render no element of their own, so the
+ * run of nodes one owns is indistinguishable on the page from the layout's own
+ * nodes beside it — the marks are what distinguish it, and this loop is the
+ * only place that knows which boundary is which. `./boundaries.js` has the
+ * mechanism and the argument; every reference to it here is inside a
+ * [`BOUNDARY_MARKS`] branch, so a build has none of it. See
+ * ubugeeei-prod/uf#520.
+ */
+export function composeRoute(resolved: ResolvedRoute, options: ComposeOptions): React.Node {
+  const { module, above } = resolved.errorBoundary;
+  const { marks } = options;
+  // The innermost element, so a page that suspends — on its loader or on
+  // anything else — suspends below every boundary the loop below adds, which is
+  // what makes the layouts and the fallback the shell rather than something
+  // waiting behind the page.
+  let element: React.Node = options.page;
+
+  for (let depth = resolved.layouts.length; depth >= 0; depth -= 1) {
+    // Backwards over a root-first list, so the deepest segment's fallback ends
+    // up closest to the page. Two segments land on the same depth whenever the
+    // inner one declares no layout of its own, and then this order is the only
+    // thing that keeps them nested the way the directories are.
+    for (let index = resolved.loading.length - 1; index >= 0; index -= 1) {
+      const boundary = resolved.loading[index];
+      if (boundary.above !== depth) {
+        continue;
+      }
+      const Fallback = loadingComponent(boundary.module);
+      element = (
+        <Suspense fallback={<Fallback />}>
+          {BOUNDARY_MARKS ? insideBoundary(marks?.get(suspenseId(index)), element) : element}
+        </Suspense>
+      );
+    }
+    // Placed on `above` alone, and not on there being a module: a `null` one is
+    // the framework's own error page, and where it renders is exactly the
+    // question ubugeeei-prod/uf#351 asks. A project that declares no
+    // `$error.js` has the record the build synthesises for the router root,
+    // whose `above` is the root's layouts — so the framework's page appears
+    // inside the masthead rather than in place of the document. A table with no
+    // record at all answers 0, which puts this boundary outside every layout,
+    // where the outer one below already stood.
+    //
+    // Not around a route that already resolved to its error page: that page is
+    // the boundary's own component, and wrapping it in the same boundary would
+    // answer a throw inside it with itself.
+    if (depth === above && resolved.error == null) {
+      element = (
+        <RouteErrorBoundary module={module} resetKey={resolved.pathname}>
+          {BOUNDARY_MARKS ? insideBoundary(marks?.get(ROUTE_ERROR_ID), element) : element}
+        </RouteErrorBoundary>
+      );
+    }
+    element = insideTemplates(element, resolved, depth);
+    if (depth > 0) {
+      const Layout = layoutComponent(resolved.layouts[depth - 1]);
+      // The slots declared on this layout's own segment, beside `children`.
+      // Spread rather than passed as one `slots` object, because a slot is a
+      // prop a layout declares by name — `component Dashboard(children, team)`
+      // — and a bag would make every layout destructure a map to find out
+      // whether the router had anything for it.
+      // The spread first and `params` after it, so that a slot named after a
+      // prop the layout already has loses rather than wins. `@params` and
+      // `@children` are refused by the scan, and this is the second line of
+      // that defence for a table written by hand: losing a slot is a hole in
+      // the page, and overwriting `params` is every route in the segment
+      // rendering against the wrong parameters.
+      element = (
+        <Layout {...slotsAt(resolved.slots, depth, resolved)} params={resolved.params}>
+          {element}
+        </Layout>
+      );
+    }
+  }
+  if (needsRootStreamFrame(resolved)) {
+    element = <RootStreamFrame>{element}</RootStreamFrame>;
+  }
+  return (
+    <>
+      <Head metadata={resolved.metadata} />
+      <RouteErrorBoundary module={null} resetKey={resolved.pathname}>
+        {BOUNDARY_MARKS ? insideBoundary(marks?.get(ROOT_ERROR_ID), element) : element}
+      </RouteErrorBoundary>
+    </>
+  );
+}
+
+/**
+ * `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.
+ *
+ * Here rather than beside the marks in `./boundaries.js`, because this is a
+ * factory and that is a client module: a server composing a tree for React
+ * Server Components calls this, and the edges it places stay references to
+ * the module that renders them.
+ */
+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" />
+    </>
+  );
+}
+
+/**
+ * Whether the outermost route fallback needs one host element above it.
+ *
+ * React can flush a shell whose suspended boundary is inside any host element,
+ * but not one whose boundary is a direct child of the render root. A route with
+ * no layout and a root `$loading.js` is exactly that second tree: every
+ * framework component above it renders no element, so the fallback waits for
+ * the page it was meant to stand in for. A root layout is already the element
+ * that can carry it, and deeper fallbacks sit inside a layout by construction.
+ */
+function needsRootStreamFrame(resolved: ResolvedRoute): boolean {
+  return resolved.layouts.length === 0 && resolved.loading.some((boundary) => boundary.above === 0);
+}
+
+component RootStreamFrame(children: React.Node) {
+  return (
+    <div data-uf-stream-root="" style={{ display: "contents" }}>
+      {children}
+    </div>
+  );
+}
+
+/**
+ * The component a page module renders: its default export, or the named
+ * `Page` that `uf create` scaffolds. An MDX page always has a default export.
+ */
+export function pageComponent(module: PageModule): React.ComponentType<PageRenderProps> {
+  const component = module.default ?? module.Page;
+  if (component == null) {
+    throw new Error(
+      "@uniflowed/router: a page module must export a component as `default` or `Page`",
+    );
+  }
+  return renderable(component);
+}
+
+/**
+ * The component a loading module renders: `default`, or the named `Loading`.
+ *
+ * No props, unlike a page or a layout. A fallback is what the router shows
+ * when it does not have the route's answer yet, so there is nothing it could
+ * be handed that would be true — not `data`, which is the thing being waited
+ * for, and not `children`, because it renders instead of them.
+ */
+export function loadingComponent(module: LoadingModule): React.ComponentType<{||}> {
+  const component = module.default ?? module.Loading;
+  if (component == null) {
+    throw new Error(
+      "@uniflowed/router: a loading module must export a component as `default` or `Loading`",
+    );
+  }
+  return renderable(component);
+}
+
+/**
+ * `element`, wrapped in every template declared at `depth`.
+ *
+ * Outside the boundaries at that depth and inside the layout below it, and
+ * backwards over a root-first list for the reason the fallbacks are: two
+ * segments share a depth whenever the inner one declares no layout, and this
+ * order is what keeps them nested the way the directories are.
+ *
+ * A function beside `RouteView` rather than a third loop inside it, and that
+ * is not only for reading: a third nested loop assigning to `element` is what
+ * the React Compiler's aliasing inference gave up on, and a component it
+ * cannot compile is a component it does not memoise.
+ */
+export function insideTemplates(
+  element: React.Node,
+  resolved: {
+    readonly pathname: string,
+    readonly params: RouteParams,
+    readonly templates: $ReadOnlyArray<ResolvedTemplate>,
+    ...
+  },
+  depth: number,
+): React.Node {
+  let out = element;
+  for (let index = resolved.templates.length - 1; index >= 0; index -= 1) {
+    const entry = resolved.templates[index];
+    if (entry.above !== depth) {
+      continue;
+    }
+    const Template = templateComponent(entry.module);
+    // Keyed on the pathname, which is the whole difference between this file
+    // and `$layout.js`: React throws the subtree away and builds it again
+    // whenever the key changes, and a navigation that changes only the query
+    // string leaves it alone.
+    out = (
+      <Template key={resolved.pathname} params={resolved.params}>
+        {out}
+      </Template>
+    );
+  }
+  return out;
+}
+
+/**
+ * The slots declared at `depth`, as the props the layout there receives.
+ *
+ * One object per layout rather than one lookup per slot, so the common case —
+ * a project with no slots at all — allocates nothing and spreads nothing.
+ *
+ * A slot the URL addressed and that has no `$default.js` is `null` rather
+ * than absent: a layout that declares `team` receives `team` on every route,
+ * so `{team ?? <Empty />}` is a thing a project can write and rely on.
+ */
+export function slotsAt(
+  slots: $ReadOnlyArray<ResolvedSlot>,
+  depth: number,
+  route: SlotRoute,
+): { readonly [string]: React.Node } {
+  if (slots.length === 0) {
+    return EMPTY_SLOTS;
+  }
+  const props: { [string]: React.Node } = {};
+  for (const slot of slots) {
+    if (slot.above === depth) {
+      // `null` rather than an element that renders nothing, and the difference
+      // is the whole of what the prop is for: `{team ?? <Empty />}` has to be
+      // able to tell "this slot has nothing in it" from "this slot rendered
+      // something empty", and an element is never `null`.
+      props[slot.name] =
+        slot.page == null ? null : (
+          <SlotView slot={slot} pathname={route.pathname} searchParams={route.searchParams} />
+        );
+    }
+  }
+  return props;
+}
+
+/** One object for every layout on a project that declares no slot. */
+const EMPTY_SLOTS: { readonly [string]: React.Node } = Object.freeze({});
+
+/**
+ * One slot's tree: its page, inside the layouts declared under the slot, with
+ * the slots those layouts declare in turn.
+ *
+ * The same composition [`RouteView`] does and deliberately not the same
+ * function. A route's tree carries the things a slot does not have — the error
+ * boundary, the `<Suspense>` fallbacks, the templates, the head — and folding
+ * a second, simpler case into that loop would be four `if`s asking which of the
+ * two this is. What the two share is the *order*, page innermost and layouts
+ * backwards over a root-first list, and that is short enough to be right twice.
+ *
+ * A slot with no page is never rendered through this component at all —
+ * [`slotsAt`] hands the layout `null` instead, so the layout can tell an empty
+ * slot from one that rendered something empty. The guard below is what makes
+ * that a fact about one place rather than a convention two places share.
+ */
+component SlotView(slot: ResolvedSlot, pathname: string, searchParams: SearchParams) {
+  // The pathname and the search string are the route's, and they are handed
+  // down rather than read from the router: a slot matches the path and the
+  // query belongs to the URL rather than to either match, and a component that
+  // reads no context is one a server can render for React Server Components.
+  const page = slot.page;
+  if (page == null) {
+    return null;
+  }
+  // Except in an interception, whose URL is not the one the route on screen was
+  // resolved for. The page it renders reads the intercepted URL's query, and
+  // its templates and error boundary are keyed on the intercepted pathname — so
+  // a second photo opened in the modal remounts what the first one mounted, the
+  // way a navigation between two pages does.
+  const at = slot.intercepted?.pathname ?? pathname;
+  const query = slot.intercepted?.searchParams ?? searchParams;
+  const Page = pageComponent(page);
+  let element: React.Node = <Page params={slot.params} searchParams={query} data={undefined} />;
+  const templateContext = {
+    pathname: at,
+    params: slot.params,
+    templates: slot.templates,
+  };
+  for (let depth = slot.layouts.length; depth >= 0; depth -= 1) {
+    for (let index = slot.loading.length - 1; index >= 0; index -= 1) {
+      const boundary = slot.loading[index];
+      if (boundary.above !== depth) {
+        continue;
+      }
+      const Fallback = loadingComponent(boundary.module);
+      element = <Suspense fallback={<Fallback />}>{element}</Suspense>;
+    }
+    const errorBoundary = slot.errorBoundary;
+    if (errorBoundary != null && errorBoundary.above === depth) {
+      element = (
+        <RouteErrorBoundary module={errorBoundary.module} resetKey={`${at}:${slot.name}`}>
+          {element}
+        </RouteErrorBoundary>
+      );
+    }
+    element = insideTemplates(element, templateContext, depth);
+    if (depth > 0) {
+      const Layout = layoutComponent(slot.layouts[depth - 1]);
+      element = (
+        <Layout {...slotsAt(slot.slots, depth, { pathname, searchParams })} params={slot.params}>
+          {element}
+        </Layout>
+      );
+    }
+  }
+  return element;
+}
+
+/**
+ * The component a template module renders: `default`, or the named `Template`.
+ *
+ * The same props a layout receives, because it is a layout in every way but
+ * one: it wraps `children`, it may read the route's parameters, and the only
+ * difference is that `RouteView` gives the element a `key` so React builds it
+ * again on every navigation.
+ */
+function templateComponent(module: TemplateModule): React.ComponentType<LayoutRenderProps> {
+  const component = module.default ?? module.Template;
+  if (component == null) {
+    throw new Error(
+      "@uniflowed/router: a template module must export a component as `default` or `Template`",
+    );
+  }
+  return renderable(component);
+}
+
+/** The component a layout module renders: `default`, or the named `Layout`. */
+function layoutComponent(module: LayoutModule): React.ComponentType<LayoutRenderProps> {
+  const component = module.default ?? module.Layout;
+  if (component == null) {
+    throw new Error(
+      "@uniflowed/router: a layout module must export a component as `default` or `Layout`",
+    );
+  }
+  return renderable(component);
+}

package/internal/error-view.js

@@ -0,0 +1,189 @@
+// @flow
+//
+// Internal to `@uniflowed/router`: what renders in place of a subtree that threw.
+//
+// The framework's error page, the component that picks between it and a
+// project's `$error.js`, the page a route that resolved to its error boundary
+// renders, and the class boundary that catches a throw while the browser
+// renders. Every one of them is the browser's: a boundary is a class, and a
+// retry is a navigation, so none of this can run in a graph resolved under
+// React's `react-server` condition — which is why it is out of `./runtime.js`'s
+// top half and in a module of its own. See ubugeeei-prod/uf#519.
+
+"use client";
+
+import * as React from "react";
+
+import type { RouteError } from "./routing.js";
+import type { ErrorModule } from "./resolve.js";
+import { errorTitle, renderable, routeErrorFor } from "./resolve.js";
+import { useRouterState } from "./runtime.js";
+
+/**
+ * The framework's error page, for a project that declares no `$error.js`.
+ *
+ * It says which of the three happened and offers the reset, and it does *not*
+ * print the thrown error: on the server that message is written for whoever
+ * deployed the application — a query, a path, a token in a stack — and this
+ * markup is sent to whoever asked for the page. `uf dev` reports the throw in
+ * the terminal and `uf build` fails the route, which are the places the person
+ * who can act on it is looking.
+ */
+component DefaultRouteError(error: RouteError, reset: () => void) {
+  const title = errorTitle(error);
+  const detail = match (error) {
+    {kind: "unauthorized"} => "This page needs you to be signed in.",
+    {kind: "forbidden"} => "You do not have access to this page.",
+    {kind: "thrown"} => "This page could not be rendered.",
+  };
+  return (
+    <main>
+      <title>{title}</title>
+      <h1>{title}</h1>
+      <p>{detail}</p>
+      <button type="button" onClick={reset}>
+        Try again
+      </button>
+    </main>
+  );
+}
+
+/** The component an error module renders: `default`, or the named `Error`. */
+function errorComponent(module: ErrorModule): React.ComponentType<ErrorRenderProps> {
+  const component = module.default ?? module.Error;
+  if (component == null) {
+    throw new Error(
+      "@uniflowed/router: an error module must export a component as `default` or `Error`",
+    );
+  }
+  return renderable(component);
+}
+
+/** The props an error boundary's component receives. */
+type ErrorRenderProps = {|
+  readonly error: RouteError,
+  readonly reset: () => void,
+|};
+
+/**
+ * The error UI, from whichever module is in scope.
+ *
+ * One component for both ways in — the class boundary below, which catches a
+ * throw while the browser renders, and `ResolvedErrorPage`, which is what the
+ * server renders because React's boundaries do not run in `renderToString`.
+ * Two paths to the same screen is exactly the pair that drifts.
+ */
+component RouteErrorView(module: ?ErrorModule, error: RouteError, reset: () => void) {
+  if (module == null) {
+    return <DefaultRouteError error={error} reset={reset} />;
+  }
+  const Boundary = errorComponent(module);
+  return <Boundary error={error} reset={reset} />;
+}
+
+/**
+ * The page of a route that resolved to an error.
+ *
+ * A resolved error route carries the error and the module on the route itself,
+ * so this is a static component rather than a closure the resolver builds:
+ * `RouteView` composes it in its layouts exactly like a page, which is what
+ * makes "inside the layouts above the boundary" one code path and not two.
+ *
+ * `reset()` here is `router.refresh()` — this route resolved to an error
+ * because a loader or an import threw, so re-running the resolution is what
+ * trying again means. On the server `refresh` does nothing, which is correct:
+ * a static render has nothing to re-run.
+ */
+export component ResolvedErrorPage() {
+  const { route, view, router } = useRouterState();
+  const reset = () => {
+    router.refresh().catch(() => {});
+  };
+
+  // Unreachable otherwise: this is only ever the page of an error route that was
+  // resolved from its modules. A route React Server Components rendered has
+  // [`ErrorRoutePage`] instead, with the boundary's module handed over as a prop.
+  if (route.error == null || view.kind !== "modules") {
+    return null;
+  }
+  return (
+    <RouteErrorView module={view.resolved.errorBoundary.module} error={route.error} reset={reset} />
+  );
+}
+
+/**
+ * The page of a route that resolved to an error, rendered by React Server
+ * Components.
+ *
+ * [`ResolvedErrorPage`] reads the error and the boundary's module out of the
+ * router, which holds a whole resolved route in a single-page application. The
+ * route a Flight payload hands the browser carries neither — the module is the
+ * server's, and what crosses is the part a hook reads — so the Flight renderer
+ * passes both as props: the boundary's module as `{ default: <client
+ * reference> }`, which is what a `"use client"` `$error.js` becomes on the way,
+ * and the error, which React serialises the way it serialises any error value.
+ * The retry is the same `router.refresh()`, because trying again still means
+ * resolving the route again. See ubugeeei-prod/uf#519.
+ */
+export component ErrorRoutePage(module: ?ErrorModule, error: RouteError) {
+  const { router } = useRouterState();
+  const reset = () => {
+    router.refresh().catch(() => {});
+  };
+  return <RouteErrorView module={module} error={error} reset={reset} />;
+}
+
+type RouteErrorBoundaryProps = {|
+  readonly module: ?ErrorModule,
+  readonly resetKey: string,
+  readonly children: React.Node,
+|};
+
+type RouteErrorBoundaryState = {| readonly error: ?RouteError |};
+
+/**
+ * The boundary that catches a throw while the browser renders the subtree.
+ *
+ * A class, because `getDerivedStateFromError` is React's contract for this and
+ * there is no hook that does it — this is the one place in the router where
+ * following React's public contract means not using a function component.
+ *
+ * Recovering on navigation is `componentDidUpdate` watching `resetKey`, not
+ * `key={pathname}` on the boundary. Keying it remounts the subtree on *every*
+ * navigation, error or not, and everything below the boundary goes with it —
+ * which is the layouts, whose whole purpose is to survive navigation with
+ * their scroll position and their open sections intact.
+ */
+export class RouteErrorBoundary extends React.Component<
+  RouteErrorBoundaryProps,
+  RouteErrorBoundaryState,
+> {
+  constructor(props: RouteErrorBoundaryProps) {
+    super(props);
+    this.state = { error: null };
+  }
+
+  static getDerivedStateFromError(error: mixed): RouteErrorBoundaryState {
+    return { error: routeErrorFor(error) };
+  }
+
+  componentDidUpdate(previous: RouteErrorBoundaryProps) {
+    if (this.state.error != null && previous.resetKey !== this.props.resetKey) {
+      this.setState({ error: null });
+    }
+  }
+
+  render(): React.Node {
+    const { error } = this.state;
+    if (error == null) {
+      return this.props.children;
+    }
+    return (
+      <RouteErrorView
+        module={this.props.module}
+        error={error}
+        reset={() => this.setState({ error: null })}
+      />
+    );
+  }
+}