@uniflowed/router 0.0.0-alpha.4 → 0.0.0-alpha.40

package/internal/devtools.js

@@ -0,0 +1,131 @@
+// @flow
+//
+// Internal to `@uniflowed/router`: whether React DevTools can actually attach
+// to the page this browser just hydrated.
+//
+// `@uniflowed/vite` installs the hook DevTools attaches through, as a classic
+// script above every module — see `packages/vite/internal/devtools.js`, which
+// has the argument. That is uf saying what it intends. This is the half that
+// checks it happened, and the two are not the same claim: the preamble is
+// injected by a `transformIndexHtml` hook, into a document a project's own Vite
+// plugins also write to, and the thing that has to be true is an *ordering* —
+// the hook exists before `react-dom` is evaluated — which no amount of reading
+// the injector can establish about a particular page.
+//
+// It runs once, after hydration, in development only, and says nothing at all
+// when there is nothing wrong. See ubugeeei-prod/uf#503.
+//
+// # Why it reports rather than throws
+//
+// Nothing here is a reason to stop a page. DevTools not attaching costs a
+// developer a panel, and a framework that refused to render over it would have
+// turned a missing convenience into an outage. So the two findings go to the
+// terminal on the same channel as every other browser-side diagnostic — see
+// `./diagnostics.js` — and the page carries on.
+//
+// # The two findings, and why they are the two
+//
+// A third condition — React's *development* build, which is what gives the
+// panel props, hooks and source positions — is not checked here because a
+// browser cannot tell the difference from the outside, and because uf owns it
+// end to end: `mode` is `development` and `uf transform` is called with
+// `development: true`, both asserted in `packages/vite/devtools.test.js`
+// against the plugin rather than against a page. What is left is what only a
+// running page knows.
+//
+//   1. **There is no hook.** Something ran before `react-dom` and there was
+//      nothing for it to register with, or the preamble did not reach this
+//      document. Either way no renderer was announced and the panel will say
+//      the page is not using React.
+//   2. **There is more than one renderer.** Two copies of `react-dom` each
+//      injected, and DevTools shows the tree of whichever it heard from — which
+//      is the shape of the "multiple renderers concurrently rendering the same
+//      context provider" report, and a component tree that is missing half the
+//      page for a reason nothing on screen explains.
+
+import { reportDiagnostic } from "./diagnostics.js";
+
+/**
+ * The global React registers itself with.
+ *
+ * The same string as `DEVTOOLS_HOOK` in `@uniflowed/vite`'s
+ * `internal/devtools.js`, written out again rather than imported for the reason
+ * that file's neighbour `internal/diagnostics.js` gives about the endpoint
+ * paths: `@uniflowed/vite` is loaded by Vite before any Flow transform exists
+ * and this module is Flow, so the import cannot go either way.
+ * `packages/vite/devtools.test.js` asserts the two spellings agree, which is
+ * what makes a duplicated constant honest.
+ */
+export const DEVTOOLS_HOOK: string = "__REACT_DEVTOOLS_GLOBAL_HOOK__";
+
+/** The part of a page this module reads. */
+type HookWindow = {
+  [key: string]: mixed,
+  ...
+};
+
+/**
+ * What is wrong with this page's DevTools hook, as a diagnostic, or `null`.
+ *
+ * Separated from the reporting so that a test can ask the question without a
+ * channel to answer on, and because the wording is the part worth pinning: a
+ * reader who sees this in a terminal has to be able to act on it without
+ * reading this file.
+ */
+export function devtoolsProblem(win: HookWindow): {|
+  readonly message: string,
+  readonly detail: $ReadOnlyArray<string>,
+|} | null {
+  const hook = win[DEVTOOLS_HOOK];
+  if (hook == null || typeof hook !== "object") {
+    return {
+      message: `React DevTools cannot attach: nothing installed \`${DEVTOOLS_HOOK}\` before react-dom ran`,
+      detail: [
+        "React registers itself with that global while `react-dom` is evaluated, once and never again.",
+        "`uf dev` injects the hook as a classic script at the top of the head; a plugin that replaces",
+        "`transformIndexHtml`'s output, or a document that does not go through it, takes it away.",
+      ],
+    };
+  }
+
+  // `renderers` is a Map React puts its renderer in, keyed by the id `inject`
+  // handed back. Anything else there is a hook uf did not install and DevTools
+  // did not either, and guessing at its shape would report a problem that is
+  // really this module not recognising one.
+  const renderers = (hook: $FlowFixMe).renderers;
+  const count = renderers instanceof Map ? renderers.size : null;
+  if (count != null && count > 1) {
+    return {
+      message: `React DevTools has ${count} renderers on this page and will show one of them`,
+      detail: [
+        "Two copies of `react-dom` are loaded, so half the component tree is in a tree the panel cannot see.",
+        '`resolve.dedupe: ["react", "react-dom"]` is what usually prevents it; a linked package with its',
+        "own `react-dom` in `node_modules` is what usually causes it.",
+      ],
+    };
+  }
+  return null;
+}
+
+/**
+ * Report the problem, if there is one, to the terminal running `uf dev`.
+ *
+ * Throws nothing and returns nothing, and the guard is around the whole body
+ * rather than around the reading: this is called from the line after a
+ * successful hydration, so every failure available to it — a hook object whose
+ * property getter throws, a host with no `fetch` to report through — is a
+ * development convenience failing, and a development convenience that can take
+ * a working page down is worse than no convenience at all.
+ */
+export function reportDevtools(win: HookWindow): void {
+  try {
+    const problem = devtoolsProblem(win);
+    if (problem == null) {
+      return;
+    }
+    reportDiagnostic({ severity: "warn", message: problem.message, detail: problem.detail });
+  } catch {
+    // Deliberately silent. There is no second channel to complain on, and the
+    // thing being reported was never worth interrupting anybody for.
+  }
+}

package/internal/diagnostics.js

@@ -0,0 +1,169 @@
+// @flow
+//
+// Internal to `@uniflowed/router`: the way a diagnostic the browser produced
+// reaches the terminal.
+//
+// Every other uf diagnostic — a type error, a lint finding, a failing test, a
+// page that rendered its error boundary — arrives in the terminal the
+// developer already has open. One produced *in the browser* had nowhere to go:
+// the page is the only process that knows about it, and `uf dev`'s diagnostics
+// come up the driver's event channel from the Node process. So the hydration
+// report added in ubugeeei-prod/uf#582 lived in a browser overlay and in the
+// console, which has to be noticed, in a window that may not be in front, by
+// somebody who does not know to look. See ubugeeei-prod/uf#583.
+//
+// This is the client half. The server half is `uf dev`, through
+// `@uniflowed/vite`'s `internal/diagnostics.js`, which turns what arrives into
+// the same rendering the terminal gives everything else: a severity, the page
+// it came from, and a code frame when there is a position to draw one around.
+//
+// # One channel, and why the poster is not shared
+//
+// `/__uf/diagnostic` and `/__uf/vitals` are one channel: two paths, one payload
+// shape, one `diagnostic` event out of the driver, one renderer. What is *not*
+// shared is the twenty lines that post to it. `@uniflowed/web/vitals` has its
+// own `vitalsBeacon`, and this is the router's.
+//
+// `@uniflowed/hmr` would have been the tidier home — it is already "the browser
+// half of `uf dev`" — and it cannot be one. `tools/ci/publishable.sh` refuses a
+// published package that depends on an unpublished one, because the tarball
+// would name a version the registry does not have; `@uniflowed/router` is on
+// npm and `@uniflowed/hmr` is a declaration package that is not. What the two
+// posters do share is the contract, and `packages/vite/dev-channel.test.js`
+// asserts that every spelling of these paths agrees — a duplicated constant
+// with a test on it is honest, and one without is how a browser ends up
+// posting to a path nothing serves.
+//
+// # It is development only, and it is best effort
+//
+// `uf dev` serves this path and nothing else does: a built application has no
+// `/__uf/` anything, so a call in production posts to a path that answers 404
+// and the rejected promise is swallowed here. That is a fallback rather than a
+// design — both callers are behind `import.meta.hot` in `../client.js`, the
+// hydration report and the DevTools check, so a production bundle has no path
+// to this module rather than merely no answer from it.
+//
+// Nothing here opens a connection until it is called, importing it does nothing
+// at all, and what it sends goes to the page's own origin as a path rather than
+// a URL, so it cannot be pointed at somebody else's server. Nothing leaves the
+// machine.
+
+/**
+ * The path `uf dev` serves the diagnostic channel on.
+ *
+ * Under `/__uf/`, beside the update stream `@uniflowed/hmr` opens and the
+ * vitals endpoint `@uniflowed/web/vitals` posts to, for the reason that prefix
+ * exists: a directory in `app/` whose name begins with `_` is not a route, so
+ * no application can put anything here and nothing here can shadow a path a
+ * project wrote.
+ */
+export const DIAGNOSTIC_ENDPOINT: string = "/__uf/diagnostic";
+
+/**
+ * How loudly a diagnostic reads in the terminal.
+ *
+ * `error` for something that is wrong, `warn` for something that is worth
+ * knowing, `info` for something that is only a measurement. Three rather than
+ * two because the vitals report on the same channel needs the third: a page
+ * whose numbers are all good has still reported, and printing that as a warning
+ * would teach the reader to ignore the warnings.
+ */
+export type DiagnosticSeverity = "error" | "warn" | "info";
+
+/**
+ * One diagnostic, as the channel carries it.
+ *
+ * `message` is the headline and the only required field: one line, the thing
+ * that is wrong. `detail` is everything under it — the values that differed,
+ * the path through the tree, the advice — and is a list of lines rather than a
+ * blob so the terminal can indent them without guessing where they break.
+ *
+ * `url` is the page the browser was on, which the reporter fills in when the
+ * caller does not: a diagnostic that does not say which page produced it is a
+ * diagnostic somebody has to reproduce before they can act on it.
+ *
+ * `file`, `line` and `column` are for the rare browser-side report that knows a
+ * source position. When the file and the line are both there `uf dev` draws its
+ * ordinary code frame; when they are not it prints the headline and the detail,
+ * which is what a hydration mismatch — a fact about a DOM node rather than
+ * about a line — can honestly offer.
+ */
+export type BrowserDiagnostic = {
+  readonly severity: DiagnosticSeverity,
+  readonly message: string,
+  readonly detail?: $ReadOnlyArray<string>,
+  readonly url?: string,
+  readonly file?: string,
+  readonly line?: number,
+  readonly column?: number,
+};
+
+/** The part of the browser this module needs. */
+type ReportingWindow = {
+  readonly location?: { readonly href?: string, ... },
+  readonly fetch?: (input: string, init: { ... }) => Promise<mixed>,
+  ...
+};
+
+/** For a promise whose outcome is deliberately not looked at. */
+function noop(): void {}
+
+/**
+ * Send one diagnostic to `uf dev`, if there is a `uf dev` to send it to.
+ *
+ * Returns nothing and throws nothing. A diagnostic is a thing a person reads,
+ * not a thing an application branches on, and a reporter that could fail would
+ * make every caller wrap it — from a code path that is, by construction,
+ * already handling something that went wrong.
+ *
+ * `fetch` rather than `sendBeacon`, which is the opposite of the choice
+ * `vitalsBeacon` makes and for the opposite reason: a vital is measured as the
+ * page is put away and needs a transport that outlives it, while a diagnostic
+ * is produced by a page that is still running and had better arrive in the
+ * order it happened. `keepalive` covers the case where the page goes away
+ * immediately afterwards anyway.
+ *
+ * @param diagnostic what to report
+ * @param endpoint where to post it; [`DIAGNOSTIC_ENDPOINT`] by default
+ */
+export function reportDiagnostic(diagnostic: BrowserDiagnostic, endpoint?: string): void {
+  const win = reportingWindow();
+  if (win == null) {
+    return;
+  }
+  const post = win.fetch;
+  if (post == null) {
+    return;
+  }
+
+  const body = JSON.stringify({
+    ...diagnostic,
+    url: diagnostic.url ?? win.location?.href ?? "",
+  });
+  // A rejected promise nobody is holding becomes an unhandled rejection, which
+  // arrives in whatever error reporter the application installed — from a line
+  // about development tooling. Losing the report is the right outcome when
+  // there is nothing listening; reporting the loss as an application error is
+  // not.
+  post(endpoint ?? DIAGNOSTIC_ENDPOINT, {
+    method: "POST",
+    body,
+    keepalive: true,
+    headers: { "content-type": "application/json" },
+  }).then(noop, noop);
+}
+
+/**
+ * The window to report from, or `null` where there is no browser.
+ *
+ * The same reading `@uniflowed/web/vitals` makes, and for the same reason: in a
+ * browser `globalThis` *is* the window, but not where a document has been
+ * installed onto another host's global, which is every uf test process. Asking
+ * for the document first is what makes both cases work.
+ */
+function reportingWindow(): ReportingWindow | null {
+  if (typeof globalThis.document === "undefined") {
+    return null;
+  }
+  return globalThis.window ?? globalThis;
+}

package/internal/error-view.js

@@ -0,0 +1,193 @@
+// @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);
+  // The error module's own export, looked up by route, for the same reason as
+  // the page component in `compose.js`: the same component on every render of
+  // that route, through a lookup the compiler cannot see into.
+  // uf-lint-disable-next-line react-compiler/static-components
+  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 })}
+      />
+    );
+  }
+}