@uniflowed/router 0.0.0-alpha.9 → 0.2.0

package/internal/flight.js

@@ -0,0 +1,192 @@
+// @flow
+//
+// Internal to `@uniflowed/router`: the names a Flight payload is spoken in.
+//
+// A route rendered by React Server Components travels as React's own Flight
+// payload (ubugeeei-prod/uf#519). `react-server-dom-parcel` writes it on the
+// server and reads it in the browser, and uf invents no format of its own —
+// the one uf used to have for loader data, `./payload.js`'s numbered rows, was
+// Flight-shaped precisely so that it could be replaced by this. What uf still
+// decides is two things around the payload: what its root value *is*, and the
+// URL a browser asks for one at. Every graph has to agree about both, so both
+// are here.
+//
+// Pure data and string functions, and type imports only: the module graph
+// that renders server components, the one that renders HTML and the browser's
+// all import this file, and none of them may be handed anything the others
+// could not evaluate.
+
+import type { Node } from "react";
+
+import type { RouteError, RouteParams, SearchParams } from "./routing.js";
+import type { Metadata, ResolvedRoute } from "./resolve.js";
+
+/**
+ * What a route resolved to, as the browser holds it.
+ *
+ * Everything a hook reads, and nothing that is a module. A resolved route
+ * carries the page, the layouts and the boundaries it loaded; none of those
+ * crosses, because what they rendered is already in the payload beside this
+ * value, and a component the browser does need crosses inside that tree as a
+ * client reference. So `useRoute()` and `useLoaderData()` read this, and
+ * `RouteView` renders the tree.
+ *
+ * `data` and `deferred` cross as Flight values. That is a narrower contract
+ * than the JSON the loader's answer used to be embedded as: Flight carries a
+ * `Date`, a `Map`, a `Set` and a promise, and it refuses a class instance by
+ * name rather than turning it into `{}` the way `JSON.stringify` did. A thrown
+ * error in `error` crosses the way React sends any error value — with its
+ * message in development and replaced by React's own sentence in a build.
+ */
+export type RouteState = {|
+  readonly pathname: string,
+  readonly search: string,
+  readonly path: string,
+  readonly params: RouteParams,
+  readonly searchParams: SearchParams,
+  /** What the loader returned, once it has. `undefined` while `deferred` is set. */
+  readonly data: mixed,
+  /** The loader still running, as a promise the browser can `use`. */
+  readonly deferred: ?Promise<mixed>,
+  readonly metadata: Metadata,
+  readonly viewTransition: ?string,
+  readonly status: 200 | 401 | 403 | 404 | 500,
+  readonly error: ?RouteError,
+  readonly interception?: ?FlightInterception,
+|};
+
+/** Row 0 of a route's payload: the route, and the tree it rendered. */
+export type FlightRoot = {|
+  readonly route: RouteState,
+  readonly tree: Node,
+  /**
+   * The build that rendered it, when the build has an id.
+   *
+   * In the payload rather than only in a response header, because the payload
+   * of a prerendered route is a file and a host that serves files runs nothing
+   * that could set one. A page on another build loads the document instead of
+   * rendering this; see `./deployment.js`.
+   */
+  readonly deployment?: string | null,
+|};
+
+/** The intercepted URL a Flight payload rendered, and the page it rendered over. */
+export type FlightInterception = {|
+  readonly pathname: string,
+  readonly search: string,
+  readonly from: string,
+|};
+
+/** What the browser may send with a payload request. */
+export type FlightFetchOptions = {|
+  readonly interceptedFrom?: string,
+|};
+
+/**
+ * What fetching a route's payload turned into.
+ *
+ * Declared here rather than beside the fetch in `./flight-browser.js`, because
+ * the router's navigation names this type and must not import React's Flight
+ * client: `./runtime.js` is in every application's bundle, and that client is
+ * only in the bundles of applications that render Server Components
+ * (ubugeeei-prod/uf#992).
+ */
+export type FetchedFlight =
+  | {|
+      readonly kind: "flight",
+      /** The route the server answered for: a redirect's target, when there was one. */
+      readonly url: string,
+      readonly root: Promise<FlightRoot>,
+    |}
+  | {|
+      /**
+       * The answer was not a payload: a redirect off this origin, or a host
+       * that had no payload for the URL. The browser should load `url` as a
+       * document.
+       */
+      readonly kind: "document",
+      readonly url: string,
+    |};
+
+/** The part of a resolved route that crosses to the browser. */
+export function routeState(resolved: ResolvedRoute): RouteState {
+  const interception = resolved.interception;
+  return {
+    pathname: resolved.pathname,
+    search: resolved.search,
+    path: resolved.path,
+    params: resolved.params,
+    searchParams: resolved.searchParams,
+    data: resolved.data,
+    deferred: resolved.deferred,
+    metadata: resolved.metadata,
+    viewTransition: resolved.viewTransition,
+    status: resolved.status,
+    error: resolved.error,
+    interception:
+      interception == null
+        ? null
+        : {
+            pathname: interception.pathname,
+            search: interception.search,
+            from: interception.base.pathname + interception.base.search,
+          },
+  };
+}
+
+/**
+ * The last path segment of the URL a route's payload is fetched from.
+ *
+ * A path rather than a header, for the two reasons a header would have been
+ * wrong. A static host answers files, and a file has one name per URL: `uf
+ * build` writes `dist/guide/__uf.flight` beside `dist/guide/index.html`, and a
+ * host that has never heard of uf serves both. And a shared cache that ignores
+ * `Vary` would hand a browser a payload where it asked for a document, which is
+ * the class of bug `docs/security.md` records for RSC caches — a different URL
+ * cannot be confused with the document's by anything that caches by URL.
+ *
+ * A segment rather than an extension, so that `/` and `/index` stay two URLs
+ * with two payloads, and so that a middleware guarding `/dashboard` guards the
+ * payload of `/dashboard` by the path rule it already has.
+ */
+export const FLIGHT_SEGMENT: string = "__uf.flight";
+
+/** The content type a payload is answered with. */
+export const FLIGHT_CONTENT_TYPE: string = "text/x-component";
+
+/** The request header that carries the page an intercepted payload is rendered over. */
+export const INTERCEPTED_FROM_HEADER: string = "uf-intercepted-from";
+
+/**
+ * The URL of `url`'s payload: its pathname with [`FLIGHT_SEGMENT`] appended,
+ * and its query string unchanged.
+ *
+ * `url` is a path and query, as the router holds one; a hash never reaches a
+ * server and is dropped.
+ */
+export function flightUrl(url: string): string {
+  const hash = url.indexOf("#");
+  const withoutHash = hash === -1 ? url : url.slice(0, hash);
+  const question = withoutHash.indexOf("?");
+  const pathname = question === -1 ? withoutHash : withoutHash.slice(0, question);
+  const search = question === -1 ? "" : withoutHash.slice(question);
+  const trimmed = pathname.replace(/\/+$/, "");
+  return `${trimmed}/${FLIGHT_SEGMENT}${search}`;
+}
+
+/**
+ * The document path a payload URL's pathname names, or `null` when the
+ * pathname is not a payload URL.
+ *
+ * `/__uf.flight` is the root's; `/guide/__uf.flight` is `/guide`'s. Anything
+ * else is `null`, and that includes a pathname that merely contains the segment
+ * somewhere in the middle — `/__uf.flight/x` is a URL some route may own.
+ */
+export function documentPathOf(pathname: string): string | null {
+  const suffix = `/${FLIGHT_SEGMENT}`;
+  if (!pathname.endsWith(suffix)) {
+    return null;
+  }
+  const document = pathname.slice(0, pathname.length - suffix.length);
+  return document === "" ? "/" : document;
+}

package/internal/form-action.js

@@ -0,0 +1,243 @@
+// @flow
+//
+// Internal to `@uniflowed/router`: a server action as a form the browser can
+// submit before any JavaScript has run.
+//
+// React 19's contract for `<form action={serverFunction}>` is progressive
+// enhancement. While rendering to HTML, React asks the function for
+// `$$FORM_ACTION(prefix)` and writes what it answers into the markup — a
+// `method`, an `encType`, a hidden field named `name`, and one hidden field per
+// entry of `data` — so the form is a real form that posts to the page it is on.
+// A function without the property gets `action="javascript:throw …"` instead,
+// which is what every uf form got before ubugeeei-prod/uf#1358.
+//
+// Two functions carry the property: the reference the browser holds
+// (`createServerReference` in `../action.js`) and the real function the server
+// renders with (`registerServerAction`, which `@uniflowed/vite` calls on every
+// callable export of a `"use server"` module in the server graph). Both answer
+// with the same fields, from the code below, so the markup the server writes and
+// what a hydrated page would have written agree.
+//
+// # The fields
+//
+// React hands `$$FORM_ACTION` a prefix unique to the form in its render, and
+// the prefix is in every field name so that two forms — or a `<form>` and a
+// `<button formAction>` inside it — never read each other's fields:
+//
+// | Field | Value |
+// | --- | --- |
+// | `$uf_ref_<prefix>` | empty. The field that says *which* action this submit is for; on a `<button formAction>` it is the button's own name, so only the button that was pressed sends it |
+// | `$uf_id_<prefix>` | the action's id, the same 64 hexadecimal characters the JSON call carries in `uf-action` |
+// | `$uf_bound_<prefix>` | the bound arguments, as the JSON envelope `encodeActionArguments` writes, when there are any |
+//
+// `useActionState` adds React's own `$ACTION_KEY`, which names the hook that
+// submitted, so the answer can put the action's result back into the same hook.
+//
+// Every field is a string and every bound argument goes through the same
+// grammar as a JSON call: nothing new is allowed to cross by arriving as a form.
+// `./action-endpoint.js` is the other half, and its header says what a native
+// post is refused for.
+
+import { encodeActionArguments } from "./action-wire.js";
+
+/** The name of the field that says which action a submit is for. */
+export const FORM_REF_FIELD = "$uf_ref_";
+/** The action id, beside it. */
+export const FORM_ID_FIELD = "$uf_id_";
+/** The bound arguments, beside it. */
+export const FORM_BOUND_FIELD = "$uf_bound_";
+/** React's own: which `useActionState` submitted. */
+export const FORM_STATE_KEY_FIELD = "$ACTION_KEY";
+
+/**
+ * The only content type a native action post may have.
+ *
+ * `application/x-www-form-urlencoded` rather than `multipart/form-data`,
+ * because a server action refuses a file anyway and multipart parsing is a
+ * surface uf does not open for one (`docs/security.md`). `$$FORM_ACTION` says
+ * it explicitly, so React writes it on the form and on a submit button.
+ */
+export const FORM_ACTION_CONTENT_TYPE = "application/x-www-form-urlencoded";
+
+/** What `$$FORM_ACTION` answers, in the shape React reads. */
+export type FormActionFields = {|
+  readonly name: string,
+  readonly method: "POST",
+  readonly encType: string,
+  readonly data: FormData,
+|};
+
+/**
+ * What a `useActionState` postback leaves for the page it renders.
+ *
+ * React's `ReactFormState`: the action's result, the hook's key, the action's
+ * id, and how many bound arguments it had *besides* the state
+ * `useActionState` bound itself.
+ */
+export type FormState = [mixed, string, string, number];
+
+/**
+ * Make `fn` a server action a form can post to without JavaScript.
+ *
+ * Defines three non-enumerable properties on `fn` and returns it:
+ *
+ * - `$$FORM_ACTION(prefix)`, the fields above;
+ * - `$$IS_SIGNATURE_EQUAL(id, bound)`, which React asks while rendering a
+ *   postback's answer to decide whether a `useActionState` is the one that
+ *   submitted — the same action, bound the same number of times;
+ * - `bind`, which keeps both of those on the function it returns, with the
+ *   bound arguments recorded so they travel in the form.
+ *
+ * `call` is what the bound function runs: `fn` itself on the server, the
+ * network call in the browser.
+ */
+export function withFormAction<T extends (...args: $ReadOnlyArray<empty>) => mixed>(
+  fn: T,
+  id: string,
+  bound: $ReadOnlyArray<mixed>,
+): T {
+  const define = (name: string, value: mixed) => {
+    Object.defineProperty(fn, name, { value, configurable: true, writable: true });
+  };
+  define("$$FORM_ACTION", (prefix: string): FormActionFields => formFields(id, bound, prefix));
+  define(
+    "$$IS_SIGNATURE_EQUAL",
+    (referenceId: string, boundCount: number): boolean =>
+      referenceId === id && boundCount === bound.length,
+  );
+  // `Function.prototype.bind` itself, reached through a cast: Flow types
+  // `bind` per call site and has no type for the method taken off the
+  // prototype and applied to an arbitrary function.
+  const nativeBind: $FlowFixMe = Function.prototype.bind;
+  define("bind", function bindAction(thisArg: mixed, ...more: Array<mixed>) {
+    const next: T = nativeBind.call(fn, thisArg, ...more);
+    return withFormAction(next, id, [...bound, ...more]);
+  });
+  return fn;
+}
+
+/**
+ * The fields a form bound to this action is written with.
+ *
+ * Throws `ActionValueError` when a bound argument cannot cross, which React
+ * catches and reports as "Failed to serialize an action for progressive
+ * enhancement" before writing the form it would have written without this —
+ * so an unencodable state costs the pre-hydration submit and nothing else.
+ */
+export function formFields(
+  id: string,
+  bound: $ReadOnlyArray<mixed>,
+  prefix: string,
+): FormActionFields {
+  const data = new FormData();
+  data.append(`${FORM_ID_FIELD}${prefix}`, id);
+  if (bound.length > 0) {
+    data.append(`${FORM_BOUND_FIELD}${prefix}`, encodeActionArguments(bound));
+  }
+  return {
+    name: `${FORM_REF_FIELD}${prefix}`,
+    method: "POST",
+    encType: FORM_ACTION_CONTENT_TYPE,
+    data,
+  };
+}
+
+/** What a native post names, read off its fields. */
+export type FormPost = {|
+  /** The action id, as sent; checked by the caller. */
+  readonly id: string | null,
+  /** The bound-argument envelope, as sent, or `null` when there is none. */
+  readonly bound: string | null,
+  /** `$ACTION_KEY`, or `null` when no `useActionState` submitted. */
+  readonly stateKey: string | null,
+  /** Every other field, in order: what the action is handed as its form. */
+  readonly entries: Array<[string, string]>,
+|};
+
+/**
+ * Read a native post's fields, or `null` when it names no action at all.
+ *
+ * `null` is the caller's signal to decline, exactly as a JSON request with no
+ * `uf-action` header is: an ordinary form posted to a route handler must reach
+ * that handler. The last `$uf_ref_` field wins, because the browser writes a
+ * pressed button's name after the fields of the form around it, and a button's
+ * `formAction` is meant to override the form's `action`.
+ *
+ * Every field whose name uf or React owns is kept out of `entries`, including
+ * another prefix's, so the action receives the form the person filled in and
+ * nothing that says how it was wired.
+ */
+export function readFormPost(fields: URLSearchParams): FormPost | null {
+  let prefix: string | null = null;
+  for (const [name] of fields) {
+    if (name.startsWith(FORM_REF_FIELD)) {
+      prefix = name.slice(FORM_REF_FIELD.length);
+    }
+  }
+  if (prefix == null) {
+    return null;
+  }
+  const entries: Array<[string, string]> = [];
+  for (const [name, value] of fields) {
+    if (!isWiring(name)) {
+      entries.push([name, value]);
+    }
+  }
+  return {
+    id: fields.get(`${FORM_ID_FIELD}${prefix}`),
+    bound: fields.get(`${FORM_BOUND_FIELD}${prefix}`),
+    stateKey: fields.get(FORM_STATE_KEY_FIELD),
+    entries,
+  };
+}
+
+/** Whether a field is uf's or React's rather than the form's own. */
+function isWiring(name: string): boolean {
+  return name.startsWith("$uf_") || name.startsWith("$ACTION_");
+}
+
+/** The element a postback's form state is written into the document as. */
+export const FORM_STATE_ELEMENT_ID = "uf:form-state";
+
+/**
+ * The `<script>` that carries a postback's form state to `hydrateRoot`.
+ *
+ * `application/json`, so it is data and never executed — no nonce, and nothing
+ * a Content Security Policy has to admit. The result was already held to the
+ * wire grammar before it got here, so it is plain JSON; `<` is escaped so
+ * that no string in it can close the element.
+ */
+export function formStateScript(state: FormState): string {
+  const json = JSON.stringify(state).replace(/</g, "\\u003c");
+  return `<script type="application/json" id="${FORM_STATE_ELEMENT_ID}">${json}</script>`;
+}
+
+/**
+ * The form state a document carries, or `undefined`.
+ *
+ * Read by both hydrating entries before `hydrateRoot`. Anything malformed is
+ * `undefined` rather than an exception: the page still hydrates, and the
+ * `useActionState` that submitted starts from its initial state, which is what
+ * it would have done with JavaScript from the start.
+ */
+export function readFormState(document: Document): FormState | void {
+  const element = document.getElementById(FORM_STATE_ELEMENT_ID);
+  if (element == null) {
+    return undefined;
+  }
+  try {
+    const parsed: mixed = JSON.parse(element.textContent);
+    if (
+      Array.isArray(parsed) &&
+      parsed.length === 4 &&
+      typeof parsed[1] === "string" &&
+      typeof parsed[2] === "string" &&
+      typeof parsed[3] === "number"
+    ) {
+      return [parsed[0], parsed[1], parsed[2], parsed[3]];
+    }
+  } catch {
+    // Fall through: see above.
+  }
+  return undefined;
+}

package/internal/head.js

@@ -0,0 +1,219 @@
+// @flow
+//
+// Internal to `@uniflowed/router`: a route's metadata, as the elements React
+// hoists into `<head>`.
+//
+// Markup and nothing else — no hooks, no context — so the same component renders
+// a route's head in the tree a server composes for React Server Components and
+// in the tree the browser composes for a single-page application. `useSeo` in
+// `./runtime.js` is the component-level way in, and it renders this too.
+
+import * as React from "react";
+
+import type { JsonLd, Metadata, Robots } from "./resolve.js";
+
+/**
+ * One URL from a route's metadata, made absolute if it can be.
+ *
+ * Open Graph, Twitter and `rel="canonical"` all want an absolute URL, and a
+ * route module cannot know the host it is served from — so `metadataBase` is
+ * how a site says it once, and this is where it is applied.
+ *
+ * Three things it deliberately does not do. It does not resolve against the
+ * *page's* URL: `Head` renders inside the route and does not know it, and a
+ * `metadataBase` is a site-wide fact rather than a per-page one. It does not
+ * invent a base: with none declared the value is emitted exactly as written,
+ * which is what every page that predates this field already gets. And it does
+ * not throw — a `metadataBase` that is not a URL is a mistake in one field,
+ * and turning it into a blank page would be a worse answer than an unresolved
+ * `og:image`.
+ */
+function absoluteUrl(value: string, base: void | string): string {
+  if (base == null) return value;
+  try {
+    return new URL(value, base).href;
+  } catch {
+    return value;
+  }
+}
+
+/**
+ * The `robots` directives, as one `content` string, or `null` for none.
+ *
+ * `null` rather than an empty string, so a page that declared nothing gets no
+ * tag at all: "index, follow" is what a document with no `robots` meta already
+ * means, and writing it out tells a crawler what it had already assumed.
+ *
+ * Each declared field contributes its directive and no field implies another.
+ * `index: true` therefore emits `index` rather than nothing — the value is
+ * there to overrule a section that said otherwise, and a directive that
+ * disappeared because it agreed with the default would be a page saying
+ * something and no evidence of it in the markup.
+ */
+function robotsContent(robots: void | Robots): ?string {
+  if (robots == null) {
+    return null;
+  }
+  const directives: Array<string> = [];
+  if (robots.index != null) {
+    directives.push(robots.index ? "index" : "noindex");
+  }
+  if (robots.follow != null) {
+    directives.push(robots.follow ? "follow" : "nofollow");
+  }
+  if (robots.maxSnippet != null) {
+    directives.push(`max-snippet:${robots.maxSnippet}`);
+  }
+  if (robots.maxImagePreview != null) {
+    directives.push(`max-image-preview:${robots.maxImagePreview}`);
+  }
+  return directives.length === 0 ? null : directives.join(", ");
+}
+
+/**
+ * One JSON-LD object as the text of a `<script>`.
+ *
+ * `<` is escaped so a string inside the data holding `</script>` cannot end
+ * the element early — the same escape `server.js` applies to the embedded
+ * loader data, and for the same reason: the text is the application's and the
+ * element it lands in is terminated by a character sequence rather than by a
+ * length. `dataScript` also escapes U+2028 and U+2029; those are about a
+ * string being parsed as JavaScript source, and this one never is.
+ */
+function jsonLdText(entry: JsonLd): string {
+  return JSON.stringify(entry).replace(/</g, "\\u003c");
+}
+
+/**
+ * One JSON-LD object, as the element that carries it.
+ *
+ * A function rather than an element written inline, because the suppression
+ * needs a line of its own; `docs/app/$layout.js` has the same shape for the
+ * same reason. `security/no-dangerously-set-inner-html` is about markup that
+ * came from somewhere and has to be sanitized before a browser parses it as
+ * HTML, and its escape hatch is a `@uniflowed/markdown` sanitizer — the right
+ * answer for markup and no answer at all for JSON. This string is
+ * `JSON.stringify`'s output with `<` escaped, so nothing in it can close the
+ * element, and it is never parsed as HTML. There is also no other spelling:
+ * React escapes a text child, so `{"@type":"Article"}` would reach the page as
+ * `&quot;@type&quot;`, which is not JSON-LD any more.
+ */
+function jsonLdScript(entry: JsonLd): React.Node {
+  const text = jsonLdText(entry);
+  const html = { __html: text };
+  // uf-lint-disable-next-line security/no-dangerously-set-inner-html
+  return <script key={text} type="application/ld+json" dangerouslySetInnerHTML={html} />;
+}
+
+export component Head(metadata: Metadata) {
+  const { title, description, metadataBase, canonical, robots } = metadata;
+  const { alternates, pagination, jsonLd, openGraph, twitter } = metadata;
+  const href = canonical != null ? absoluteUrl(canonical, metadataBase) : null;
+  const crawler = robotsContent(robots);
+  // Read out of `alternates` once rather than through it at every use: the map
+  // is read inside a callback, and a refinement of `alternates.languages` does
+  // not survive being carried into one.
+  const languages = alternates?.languages;
+  // A page that said what it is called has said what its card is called. Every
+  // site that had to write both wrote the same string twice, and the second
+  // one is the one that goes stale — the docs site shipped thirty pages whose
+  // share cards carried an image and no title at all.
+  //
+  // `??`, not `||`: an empty string is a decision, and a page that deliberately
+  // has no card title should get none rather than the document's.
+  const cardTitle = openGraph?.title ?? title;
+  const cardDescription = openGraph?.description ?? description;
+  // `og:type` is one of the four properties Open Graph requires. A default is
+  // the difference between a document with a card and a document without one,
+  // and `website` is right for everything that is not an article or a video.
+  const cardType = openGraph?.type ?? "website";
+  // Only when the card was asked for. A page with no `twitter.card` gets no
+  // Twitter tags at all, which is what a site that never wanted one meant.
+  const twitterTitle = twitter != null ? (twitter.title ?? cardTitle) : null;
+  const twitterDescription = twitter != null ? (twitter.description ?? cardDescription) : null;
+  const twitterImageAlt = twitter != null ? (twitter.imageAlt ?? openGraph?.imageAlt) : null;
+  return (
+    <>
+      {title != null ? <title>{title}</title> : null}
+      {description != null ? <meta name="description" content={description} /> : null}
+      {crawler != null ? <meta name="robots" content={crawler} /> : null}
+      {href != null ? <link rel="canonical" href={href} /> : null}
+      {/* The set is reciprocal and includes this page, so a `hreflang` list is
+          usually the same list on every page of it — which is why it belongs
+          on the layout they share rather than on each of them.
+
+          `hrefLang` is React's spelling and it reaches the markup unchanged,
+          which is worth knowing before grepping a document for `hreflang` and
+          concluding it is missing. HTML attribute names are case-insensitive,
+          so the parser every crawler runs reads it as the same attribute; the
+          lowercase spelling is the one React warns about. */}
+      {languages != null
+        ? Object.keys(languages).map((language) => (
+            <link
+              key={language}
+              rel="alternate"
+              hrefLang={language}
+              href={absoluteUrl(languages[language], metadataBase)}
+            />
+          ))
+        : null}
+      {pagination?.prev != null ? (
+        <link rel="prev" href={absoluteUrl(pagination.prev, metadataBase)} />
+      ) : null}
+      {pagination?.next != null ? (
+        <link rel="next" href={absoluteUrl(pagination.next, metadataBase)} />
+      ) : null}
+      {/* `og:url` *is* the canonical URL of the page, in Open Graph's own
+          words, so one declaration answers both rather than asking a project
+          to write the same URL twice and keep them in step. */}
+      {href != null ? <meta property="og:url" content={href} /> : null}
+      {cardTitle != null ? <meta property="og:title" content={cardTitle} /> : null}
+      {cardDescription != null ? (
+        <meta property="og:description" content={cardDescription} />
+      ) : null}
+      {/* Only alongside something else. A document with `og:type` and nothing
+          more is not a card; it is one meta tag saying the page is a page. */}
+      {cardTitle != null || cardDescription != null || openGraph?.images != null ? (
+        <meta property="og:type" content={cardType} />
+      ) : null}
+      {openGraph?.siteName != null ? (
+        <meta property="og:site_name" content={openGraph.siteName} />
+      ) : null}
+      {openGraph?.images != null
+        ? openGraph.images.map((image) => (
+            <meta key={image} property="og:image" content={absoluteUrl(image, metadataBase)} />
+          ))
+        : null}
+      {openGraph?.imageAlt != null && openGraph?.images != null ? (
+        <meta property="og:image:alt" content={openGraph.imageAlt} />
+      ) : null}
+      {/* `name`, not `property`: Open Graph is RDFa and Twitter's cards are
+          not, and a `property="twitter:card"` is ignored by the crawler that
+          reads it. */}
+      {twitter?.card != null ? <meta name="twitter:card" content={twitter.card} /> : null}
+      {twitter?.site != null ? <meta name="twitter:site" content={twitter.site} /> : null}
+      {twitter?.creator != null ? <meta name="twitter:creator" content={twitter.creator} /> : null}
+      {/* X reads the `og:` tags when these are absent, so these are not
+          required — and every validator asks for them anyway, which is a good
+          enough reason when the value is one the page has already given. They
+          fall back through the card's title to the document's. */}
+      {twitterTitle != null ? <meta name="twitter:title" content={twitterTitle} /> : null}
+      {twitterDescription != null ? (
+        <meta name="twitter:description" content={twitterDescription} />
+      ) : null}
+      {twitter?.images != null
+        ? twitter.images.map((image) => (
+            <meta key={image} name="twitter:image" content={absoluteUrl(image, metadataBase)} />
+          ))
+        : null}
+      {twitterImageAlt != null && twitter?.images != null ? (
+        <meta name="twitter:image:alt" content={twitterImageAlt} />
+      ) : null}
+      {/* Last, and not hoisted into `<head>` with the rest: React hoists a
+          `<title>`, a `<meta>` and a `<link>`, and not a script whose body it
+          would have to carry. JSON-LD is read from anywhere in the document,
+          so these render where the route does. */}
+      {jsonLd != null ? jsonLd.map(jsonLdScript) : null}
+    </>
+  );
+}