@uniflowed/web 0.0.0-alpha.18

package/cookie.js

@@ -0,0 +1,144 @@
+// @flow
+//
+// `@uniflowed/web/cookie`: reading a cookie from a component.
+//
+// A cookie is one value with two readers. On a server it is on the request,
+// and `@uniflowed/server` has it; in a browser it is on `document`, and a
+// component can read it directly. `useCookie` is the same call in both places,
+// which is the only reason it is worth having.
+//
+// This module deliberately does *not* import `@uniflowed/server`: that package
+// imports `node:async_hooks`, and importing it here would drag a Node builtin
+// into every browser bundle that renders a page. The server value arrives
+// through the render instead — the router puts it there — and the browser reads
+// `document.cookie`. Two sources, one call, and no server module in the client
+// graph.
+//
+// # What belongs in this module
+//
+// The browser half of a cookie, and the name under which a server render hands
+// its half over. A cookie is a small enough subject to be one file and a
+// distinct enough one to be its own: it is the only value in this package that
+// is *written* as well as read, and the only one whose two readers are
+// different APIs rather than the same API in two environments.
+//
+// Not here: anything that reads a request. Headers, the URL, and the session
+// are `@uniflowed/server`'s, and the paragraph above is the reason this module
+// must not grow an import of it.
+
+import * as React from "@uniflowed/react";
+
+/** How a cookie is written, in the browser. */
+export type CookieOptions = {
+  /** Seconds until it expires. Absent means a session cookie. */
+  readonly maxAge?: number,
+  readonly path?: string,
+  readonly sameSite?: "lax" | "strict" | "none",
+  readonly secure?: boolean,
+};
+
+/** Where a server-rendered page's cookies are handed to the client half. */
+const SERVER_COOKIES: string = "__ufServerCookies";
+
+/**
+ * Parse a `Cookie`-shaped header into a plain object.
+ *
+ * `Object.create(null)`, because `__proto__` is a cookie name an attacker can
+ * set and on an ordinary object it would not be a key at all. The same
+ * reasoning as `@uniflowed/server`'s parser, and deliberately a second copy:
+ * sharing it would mean importing that package here.
+ */
+export function parse(header: string | null): { [string]: string } {
+  const out: { [string]: string } = Object.create(null);
+  if (header == null || header === "") {
+    return out;
+  }
+  for (const pair of header.split(";")) {
+    const at = pair.indexOf("=");
+    if (at < 0) {
+      continue;
+    }
+    const name = pair.slice(0, at).trim();
+    if (name === "" || Object.hasOwn(out, name)) {
+      continue;
+    }
+    let value = pair.slice(at + 1).trim();
+    if (value.length >= 2 && value.startsWith('"') && value.endsWith('"')) {
+      value = value.slice(1, -1);
+    }
+    try {
+      out[name] = decodeURIComponent(value);
+    } catch {
+      // A malformed cookie is not a reason to fail a render; the value is
+      // simply not what the sender meant.
+      out[name] = value;
+    }
+  }
+  return out;
+}
+
+/** Serialise one cookie for `document.cookie`. */
+export function serialize(name: string, value: string, options?: CookieOptions): string {
+  let out = `${encodeURIComponent(name)}=${encodeURIComponent(value)}`;
+  out += `; Path=${options?.path ?? "/"}`;
+  if (options?.maxAge != null) {
+    out += `; Max-Age=${Math.trunc(options.maxAge)}`;
+  }
+  out += `; SameSite=${options?.sameSite ?? "lax"}`;
+  if (options?.secure === true) {
+    out += "; Secure";
+  }
+  return out;
+}
+
+/** Whatever cookies are readable here, server or browser. */
+function readAll(): { [string]: string } {
+  const host = (globalThis: $FlowFixMe);
+  if (host.document != null) {
+    return parse(host.document.cookie);
+  }
+  // Server-rendered: the router leaves the request's cookies where both halves
+  // can see them, so the first render matches what the browser will read.
+  return parse(host[SERVER_COOKIES] ?? null);
+}
+
+/**
+ * Read a cookie, and write it in the browser.
+ *
+ * The value is `null` when the cookie is not set, rather than `undefined`, so a
+ * component can tell "no cookie" from "a cookie whose value is empty" without
+ * two comparisons.
+ *
+ * Writing is browser-only and says so: setting a cookie during a server render
+ * has no defined moment to take effect — the headers may already be on the wire
+ * — so a route handler or a server action is where that belongs.
+ */
+export function useCookie(
+  name: string,
+): [string | null, (next: string, options?: CookieOptions) => void] {
+  const [value, setValue] = React.useState<string | null>(() => {
+    const all = readAll();
+    return Object.hasOwn(all, name) ? all[name] : null;
+  });
+
+  const write = React.useCallback(
+    (next: string, options?: CookieOptions) => {
+      const host = (globalThis: $FlowFixMe);
+      if (host.document == null) {
+        throw new Error(
+          `useCookie: ${name} cannot be written during a server render. ` +
+            "The response's headers may already have gone; set it from a route " +
+            "handler or a server action instead.",
+        );
+      }
+      host.document.cookie = serialize(name, next, options);
+      setValue(next);
+    },
+    [name],
+  );
+
+  return [value, write];
+}
+
+/** Where the server leaves the request's cookies for the first render. */
+export const SERVER_COOKIE_GLOBAL: string = SERVER_COOKIES;

package/head.js

@@ -0,0 +1,132 @@
+// @flow
+//
+// `@uniflowed/web/head`: the document head, from a component.
+//
+// A page's title and its meta tags are decided by whatever is rendering, which
+// is usually not the thing that owns `<head>`. `useHead` lets a component say
+// what it needs and puts it there.
+//
+// # What this does and does not do
+//
+// In a browser it applies. On a server it does not, and that is deliberate
+// rather than unfinished: the head is written before the body is streamed, so a
+// component that renders *after* the head has gone cannot change it. uf's
+// answer for server-rendered metadata is the route's own `metadata` export,
+// which the router resolves before it renders anything — `useHead` is for what
+// a page decides while it is running.
+//
+// Saying so matters because the alternative is a silent one. A `useHead` that
+// pretended to work on a server would produce a page whose title is right in a
+// browser and wrong in a crawler, which is the case nobody checks.
+//
+// # What belongs in this module
+//
+// Head tags a component decides while it is running: the title, `<meta>`,
+// canonical and alternate `<link>`s. The test is that the value is not known
+// until something has rendered.
+//
+// Not here: a preload. It is a `<link>` and it still belongs to `media.js`,
+// because what is difficult about a preload is the request it starts — `as`,
+// `crossOrigin`, the second download when they disagree — and not the element
+// it is spelled as. Route metadata is not here either: the router resolves a
+// route's `metadata` export before it renders anything, which is what makes it
+// work in a crawler, and that is exactly the case this module cannot serve.
+
+import * as React from "@uniflowed/react";
+
+/** One `<meta>`, by whichever attribute names it. */
+export type Meta = {
+  readonly name?: string,
+  readonly property?: string,
+  readonly content: string,
+};
+
+/** One `<link>`. */
+export type Link = {
+  readonly rel: string,
+  readonly href: string,
+  readonly type?: string,
+  readonly sizes?: string,
+};
+
+/** What a component wants in the head. */
+export type Head = {
+  readonly title?: string,
+  readonly meta?: $ReadOnlyArray<Meta>,
+  readonly links?: $ReadOnlyArray<Link>,
+};
+
+/** Marks the elements this module owns, so it can remove its own and no others. */
+const OWNED = "data-uf-head";
+
+/** The attribute that names one `<meta>`, and the value that identifies it. */
+function metaKey(meta: Meta): string {
+  return meta.name != null ? `name=${meta.name}` : `property=${meta.property ?? ""}`;
+}
+
+/**
+ * Put `head` in the document, and take it out again when the component goes.
+ *
+ * Every element it adds is marked, and only marked elements are removed — a
+ * component that unmounts must not take the document's own `<meta charset>`
+ * with it.
+ *
+ * The title is restored rather than removed, because a document with no title
+ * shows its URL in the tab, which looks like a bug.
+ */
+export function useHead(head: Head): void {
+  // The whole head as a string: an object literal is a new object every render,
+  // and depending on it would re-apply on every one.
+  const key = JSON.stringify(head);
+
+  React.useEffect(() => {
+    const document = (globalThis: $FlowFixMe).document;
+    if (document == null) {
+      return undefined;
+    }
+
+    const previousTitle = document.title;
+    if (head.title != null) {
+      document.title = head.title;
+    }
+
+    const added: Array<mixed> = [];
+    for (const meta of head.meta ?? []) {
+      const element = document.createElement("meta");
+      if (meta.name != null) {
+        element.setAttribute("name", meta.name);
+      }
+      if (meta.property != null) {
+        element.setAttribute("property", meta.property);
+      }
+      element.setAttribute("content", meta.content);
+      element.setAttribute(OWNED, metaKey(meta));
+      document.head.appendChild(element);
+      added.push(element);
+    }
+    for (const link of head.links ?? []) {
+      const element = document.createElement("link");
+      element.setAttribute("rel", link.rel);
+      element.setAttribute("href", link.href);
+      if (link.type != null) {
+        element.setAttribute("type", link.type);
+      }
+      if (link.sizes != null) {
+        element.setAttribute("sizes", link.sizes);
+      }
+      element.setAttribute(OWNED, `${link.rel}:${link.href}`);
+      document.head.appendChild(element);
+      added.push(element);
+    }
+
+    return () => {
+      if (head.title != null) {
+        document.title = previousTitle;
+      }
+      for (const element of added) {
+        (element: $FlowFixMe).remove();
+      }
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [key]);
+}

package/index.js

@@ -0,0 +1,96 @@
+// @flow
+//
+// `@uniflowed/web`: the primitives a page is built from.
+//
+// The small number of things every web page needs and nearly every project
+// reimplements: an image that does not shift the layout, a date that survives
+// hydration, a live region a screen reader actually announces, a cookie that
+// reads the same on both sides.
+//
+// Each is here because the naive version is wrong in a way that only shows up
+// later — a font preload without `crossOrigin` that silently downloads twice, a
+// `toLocaleString` that makes the server and the browser disagree, a live
+// region rendered at the same moment as its text and therefore never read. The
+// per-component documentation says which mistake it exists to prevent.
+//
+// # How the package is laid out
+//
+// Six modules beside this one, each named after the mistake it prevents
+// rather than after its place in a build:
+//
+// - `media.js` — the elements that load bytes, and the layout shifts and
+//   double downloads they cause. Also the icon sprite and the Open Graph card,
+//   which are the two things a build knows and a runtime cannot: which icons
+//   an application imported, and what a card the crawler will fetch says.
+// - `time.js` — an instant, rendered the same way on a server and in a
+//   browser.
+// - `regions.js` — the elements that exist for a screen reader: landmarks,
+//   live regions, and the link that reaches them.
+// - `cookie.js` — one value with two readers, and no `node:async_hooks` in a
+//   browser bundle.
+// - `head.js` — what a component decides to put in `<head>` while it runs.
+// - `vitals.js` — the five measurements the browser already takes of the
+//   page, and the only place in the package that could send anything anywhere.
+//
+// `vitals.js` is the odd one out and belongs here anyway. The other five are
+// about not causing a bad number; it is about reading the number, and it is
+// the same subject seen from the other end — an `Image` without dimensions and
+// a `Font` without `crossOrigin` are exactly what an LCP measures. Splitting
+// measurement into its own package would have put the diagnosis one install
+// away from the cure.
+//
+// They sit here, not under an `internal/`, and each has its own subpath. The
+// directory is the table of contents: a reader who opens the package sees five
+// subjects and can guess which file holds the thing they came for. Nothing in
+// them needs hiding — they contain the same components this file re-exports —
+// and calling them internal while exporting every one of their names would
+// have been a claim the package does not keep. `internal/` is for a module
+// consumers must *not* reach, and this package has none.
+//
+// This file stays a barrel because five modules genuinely need one. That is
+// aggregation, not indirection: `import { Image, Time } from "@uniflowed/web"`
+// is one import for a page that wants both, and the subpaths are there for a
+// bundle that wants exactly one.
+//
+// Routing is not here, and not re-exported either. `Link`, `useRoute` and
+// `useRouter` are `@uniflowed/router`'s, and passing them through this package
+// would give each of them two import paths, two places to document, and two
+// places to be wrong. It would also put this package's `Page` — a `<main>`
+// landmark — into the same import as the router's `PageProps`, which is a
+// route module's props and an entirely different idea.
+//
+// One name, one home. Import routing from the router.
+
+export type {
+  FontAsset,
+  FontFace,
+  IconAsset,
+  ImageAsset,
+  Loading,
+  OgAsset,
+  Source,
+  SpriteAsset,
+} from "./media.js";
+export { Font, Icon, IconSprite, Image, OgImage, Picture } from "./media.js";
+
+export type { TimeFormat, TimeValue } from "./time.js";
+export { Time, asInstant, relative } from "./time.js";
+
+export { Announcer, Layout, Page, SkipLink } from "./regions.js";
+
+export type { Head, Link as HeadLink, Meta } from "./head.js";
+export { useHead } from "./head.js";
+
+export type { CookieOptions } from "./cookie.js";
+export { useCookie } from "./cookie.js";
+
+export type {
+  CollectOptions,
+  NavigationType,
+  Rating,
+  Vital,
+  VitalName,
+  VitalsReport,
+  VitalsReporter,
+} from "./vitals.js";
+export { VITALS_ENDPOINT, collectVitals, useVitals, vitalsBeacon } from "./vitals.js";