@tinvar/react 0.0.0-stage → 0.4.1

package/src/page-root.js

@@ -0,0 +1,455 @@
+// The page an app's browser entry shows, and the router mount that changes it.
+//
+// The router never imports React (router.js), so turning a payload into the
+// page on screen is the app's: decode the stream with its own client bundle,
+// set it as the root's state, and tell the router once React has COMMITTED
+// it, since the router scrolls and pushes history straight after. Every app
+// needs the same root for that, and the hand-written one an entry carried
+// had a defect no app should have to rediscover: a visit aborted while its
+// transition was pending -- cancelled, or superseded by the next click --
+// still committed when its data arrived. Its page showed under the old URL
+// and the old page's route token, and the scroll recorded for the old entry
+// was the aborted page's.
+//
+// A partial reload's payload is not a page but the segments it recomputed
+// (ADR 0015). They are merged into what the root shows, and handed to each
+// <Segment> slot through context, over the page they arrived for.
+//
+// Mounting is two steps (ADR 0045): prepare() decodes the payload, and the
+// commit it returns puts the page on screen. The router runs a view
+// transition around the commit alone, so the browser holds the old page
+// only while React swaps it, not while the payload is read -- nor while a
+// client component's chunk the payload names is still loading, which
+// prepare() waits for (client-modules.js); and a page
+// that is not to keep its state -- preserveState: false, a visit's default
+// -- is committed fresh: the components of the page segment, or of the
+// segments a partial reload carries, mount again rather than being
+// reconciled with the page they replace.
+//
+// An instant visit (ADR 0092) shows, as soon as it is asked for, the page's
+// layouts as they are on screen with a layout's loading boundary below
+// them: instant() turns it on, ahead of the request, and the page the visit
+// fetches turns it off by replacing it. Nothing of the next page is drawn
+// before its payload arrives; what shows meanwhile is what the browser
+// already holds.
+//
+// This module is browser-only, like the router; it imports React for the
+// root component and nothing from the server.
+
+import { createElement, startTransition, useLayoutEffect, useMemo, useState } from 'react';
+import { clientModulesSettled, watchClientModules } from './client-modules.js';
+import { createLayoutPropsStore } from './layout-props.js';
+import { SegmentContext } from './segment.js';
+
+/** The segment the page itself renders as; see compose-route.js. */
+const PAGE_SEGMENT = 'page';
+
+/**
+ * A page as the root holds it: the tree, and what partial reloads have put
+ * in its segments since it arrived whole.
+ *
+ * @typedef {{
+ *   root: unknown,
+ *   segments?: Readonly<Record<string, unknown>>,
+ *   generation?: number,
+ *   keys?: Readonly<Record<string, number>>,
+ *   committed?: () => void,
+ *   waiting?: readonly (() => void)[],
+ *   from?: Update,
+ *   instant?: { under: string, token: object },
+ *   dropBefore?: number,
+ * }} Shown
+ *
+ * `waiting` is every update this one was applied over that has not reached
+ * the screen yet, by the callback that tells its mount it has; `committed`
+ * calls them all.
+ *
+ * `generation` counts the whole pages shown. A merged list (<MergeSlot>)
+ * adds a partial reload's items to those it holds, but a whole page starts
+ * it again -- even the same page, where React keeps the component and its
+ * state -- so it compares this, not its props, to tell one from the other.
+ *
+ * `keys` counts, by segment, the times each was committed fresh: a
+ * <Segment> renders its content under its count, so a new one mounts it
+ * again.
+ *
+ * `instant` is the instant visit showing: the layout whose loading boundary
+ * stands in for what is below it, and the token of the visit that asked.
+ *
+ * `dropBefore` is, on a whole page, the last change to the layout props
+ * that page did not set: what the page before it set, dropped once it is
+ * on screen (layout-props.js).
+ *
+ * An update a mount asks for: a whole page, or segments to merge into the
+ * page shown when it is applied; `fresh` when what it replaces is not to
+ * keep its state.
+ *
+ * @typedef {{
+ *   root?: unknown,
+ *   partial?: Readonly<Record<string, unknown>>,
+ *   fresh?: boolean,
+ *   committed: () => void,
+ *   mark?: number,
+ * }} Update
+ *
+ * @typedef {{
+ *   decode: (stream: ReadableStream<Uint8Array>) => unknown,
+ * }} PageRootOptions
+ *
+ * A payload decoded and ready to go on screen.
+ *
+ * @typedef {{ commit: () => Promise<void> }} Prepared
+ */
+
+const NONE = Object.freeze({});
+
+/**
+ * @param {Shown} current
+ * @param {Update} update
+ * @param {Shown | null} onScreen the page last committed
+ * @returns {Shown}
+ */
+function apply(current, update, onScreen) {
+  // React renders transitions still pending together and commits them once:
+  // an action's re-render of the page and a poll's of one segment, say.
+  // Only the last state's callback ran, and the mount of the one before it
+  // waited for a commit that had already happened -- for good. So an update
+  // applied over one not yet on screen carries that one's callback too.
+  const waiting = [...(current === onScreen ? [] : (current.waiting ?? [])), update.committed];
+  const committed = () => {
+    for (const callback of waiting) callback();
+  };
+
+  // A whole page renews the page segment; layouts stay, as RSC's nested
+  // layouts do -- and as Inertia's persistent layouts keep their state
+  // whatever preserveState says. A partial reload renews what it carries.
+  const renewed = update.partial === undefined ? [PAGE_SEGMENT] : Object.keys(update.partial);
+  const keys = update.fresh ? renew(current.keys ?? NONE, renewed) : current.keys;
+
+  if (update.partial === undefined) {
+    return {
+      root: update.root,
+      generation: (current.generation ?? 0) + 1,
+      keys,
+      committed,
+      waiting,
+      from: update,
+      ...(update.mark === undefined ? {} : { dropBefore: update.mark }),
+    };
+  }
+
+  // A partial reload -- an action's re-render, say -- lands in the page
+  // under the loading boundary, which stays until the visit settles.
+  return {
+    root: current.root,
+    segments: { ...(current.segments ?? NONE), ...update.partial },
+    generation: current.generation ?? 0,
+    keys,
+    committed,
+    waiting,
+    from: update,
+    ...(current.instant === undefined ? {} : { instant: current.instant }),
+  };
+}
+
+/**
+ * @param {Readonly<Record<string, number>>} keys
+ * @param {readonly string[]} segments
+ * @returns {Readonly<Record<string, number>>}
+ */
+function renew(keys, segments) {
+  const next = { ...keys };
+  for (const id of segments) next[id] = (next[id] ?? 0) + 1;
+  return next;
+}
+
+/**
+ * The segments a partial payload carries, or null when it is not one --
+ * an app whose renderer rendered the page whole anyway, say -- and is
+ * then shown as a page.
+ *
+ * @param {unknown} decoded
+ * @returns {Readonly<Record<string, unknown>> | null}
+ */
+function segmentsOf(decoded) {
+  const segments = /** @type {{ segments?: unknown } | null} */ (decoded)?.segments;
+  return segments !== null && typeof segments === 'object' && !Array.isArray(segments)
+    ? /** @type {Record<string, unknown>} */ (segments)
+    : null;
+}
+
+/**
+ * Creates the root component an app hydrates its document with, and the
+ * `mount` to give createRouter().
+ *
+ * @param {PageRootOptions} options
+ */
+export function createPageRoot({ decode }) {
+  // Before any payload is decoded through it, so every load a visit's
+  // payload starts is seen.
+  watchClientModules();
+
+  /** The last page that reached the screen. */
+  let committed = /** @type {Shown | null} */ (null);
+
+  /**
+   * An update the router asked for before the root could take it -- a back
+   * press can arrive before hydration has run a single effect. Held, and
+   * applied once the root can, rather than dropped, which left its mount
+   * waiting forever.
+   */
+  let early = /** @type {Update | null} */ (null);
+
+  /** Changes what the root shows; the root's own setter once it has rendered. */
+  let set = /** @type {((change: (current: Shown) => Shown) => void) | null} */ (null);
+
+  /** What each segment last committed; see <Segment>. One map for the root's life. */
+  const recorded = new Map();
+
+  /** The layouts on screen with a loading boundary; see <Segment>. */
+  const boundaries = new Map();
+
+  /** What pages have handed their layouts with setLayoutProps(); see layout-props.js. */
+  const layoutProps = createLayoutPropsStore();
+
+  /** The whole pages shown, as of the last commit: a new one drops the last page's layout props. */
+  let shownGeneration = 0;
+
+  /**
+   * Changes what the root shows at once, outside a transition: an instant
+   * visit's loading boundary is drawn from what the browser holds, so
+   * nothing in it waits, and it must not wait behind a page's transition.
+   */
+  let setNow = /** @type {((change: (current: Shown) => Shown) => void) | null} */ (null);
+
+  /**
+   * @param {{ initial: unknown }} props
+   */
+  function PageRoot({ initial }) {
+    const [page, setPage] = useState(/** @returns {Shown} */ () => ({ root: initial }));
+
+    useLayoutEffect(() => {
+      set = (change) => startTransition(() => setPage(change));
+      setNow = setPage;
+
+      if (early !== null) {
+        const held = early;
+        early = null;
+        set((current) => apply(current, held, committed));
+      }
+
+      return () => {
+        set = null;
+        setNow = null;
+      };
+    }, []);
+
+    useLayoutEffect(() => {
+      committed = page;
+      const generation = page.generation ?? 0;
+      if (generation !== shownGeneration) {
+        shownGeneration = generation;
+        if (page.dropBefore !== undefined) layoutProps.dropBefore(page.dropBefore);
+      }
+      page.committed?.();
+    }, [page]);
+
+    const generation = page.generation ?? 0;
+    const keys = page.keys ?? NONE;
+    const instant = page.instant ?? null;
+    const store = useMemo(
+      () => ({
+        overrides: page.segments ?? NONE,
+        recorded,
+        generation,
+        keys,
+        instant,
+        boundaries,
+        layoutProps,
+      }),
+      [page.segments, generation, keys, instant],
+    );
+
+    return createElement(SegmentContext.Provider, { value: store }, page.root);
+  }
+
+  /** @param {Update} update */
+  function show(update) {
+    if (set === null) early = update;
+    else set((current) => apply(current, update, committed));
+  }
+
+  /**
+   * Takes back an update whose visit was aborted before it reached the
+   * screen.
+   *
+   * The transition that set it cannot be cancelled, and React commits it
+   * whenever what it suspended on arrives. So the state is put back to the
+   * page last committed, in a transition of its own: two transitions on one
+   * state are rendered together, and only the later is committed -- which
+   * now shows the page already on screen. Put back only if the aborted
+   * update is still the latest; a newer one stands.
+   *
+   * @param {Update} update
+   */
+  function withdraw(update) {
+    if (early === update) {
+      early = null;
+      return;
+    }
+
+    const back = committed;
+    if (set === null || back === null) return;
+
+    // A fresh object, so the effect that records what reached the screen
+    // runs for it; the tree in it is the one already there.
+    set((current) =>
+      current.from === update
+        ? { root: back.root, segments: back.segments, generation: back.generation, keys: back.keys }
+        : current,
+    );
+  }
+
+  /**
+   * Shows an instant visit's loading boundary: the boundary the layout
+   * keyed `under` gave -- or, given true, the one the layout directly above
+   * the page gave -- in place of what that layout holds, until the visit's
+   * page replaces it or the returned function takes it back. Null, and
+   * nothing shown, when no layout on screen by that key has a boundary: the
+   * visit is then an ordinary one, and the page on screen stays until the
+   * next is ready.
+   *
+   * Taking it back after the page has replaced it, or after a later instant
+   * visit has shown its own, does nothing.
+   *
+   * @param {true | string} under
+   * @returns {(() => void) | null}
+   */
+  function instant(under) {
+    const key = under === true ? layoutAbove(PAGE_SEGMENT) : under;
+    const change = setNow;
+    if (typeof key !== 'string' || !boundaries.has(key) || change === null) return null;
+
+    const token = {};
+    change((current) => ({ ...current, instant: { under: key, token } }));
+
+    return () => {
+      setNow?.((current) => {
+        if (current.instant?.token !== token) return current;
+        const next = { ...current };
+        delete next.instant;
+        return next;
+      });
+    };
+  }
+
+  /**
+   * The layout whose loading boundary stands in for segment `id`, if one on
+   * screen has one.
+   *
+   * @param {string} id
+   * @returns {string | undefined}
+   */
+  function layoutAbove(id) {
+    for (const [layout, child] of boundaries) {
+      if (child === id) return layout;
+    }
+    return undefined;
+  }
+
+  /**
+   * The router's first step: decodes the payload, and hands back the
+   * commit that puts it on screen -- or null when the visit was aborted
+   * meanwhile, and the page is never to show.
+   *
+   * @param {ReadableStream<Uint8Array>} stream
+   * @param {import('./router.js').Page} page
+   * @returns {Promise<Prepared | null>}
+   */
+  async function prepare(stream, page) {
+    watchClientModules();
+    const decoded = await decode(stream);
+
+    // Superseded while decoding: the next page is coming, this one never shows.
+    if (page.signal.aborted) return null;
+
+    // The chunks of the client components the payload has named so far,
+    // still loading: waited for here, outside the view transition, so the
+    // commit never holds the old page frozen while one arrives.
+    const loading = clientModulesSettled();
+    if (loading !== null) {
+      await Promise.race([loading, abortedOf(page.signal)]);
+      if (page.signal.aborted) return null;
+    }
+
+    const partial = page.partial ? segmentsOf(decoded) : null;
+    const fresh = page.preserveState === false;
+
+    /** @type {Promise<void> | null} */
+    let committing = null;
+
+    return {
+      /**
+       * Shows the page. Resolves once React has committed it, or once the
+       * visit is aborted -- and then the page never commits. Asked twice,
+       * it shows the page once.
+       */
+      commit() {
+        committing ??= new Promise((resolve) => {
+          /** @type {Update} */
+          // A whole page drops what the page before it set for its layouts
+          // -- everything set up to now, before any of it has rendered.
+          const update =
+            partial === null
+              ? { root: decoded, fresh, committed: () => resolve(undefined), mark: layoutProps.mark() }
+              : { partial, fresh, committed: () => resolve(undefined) };
+
+          if (page.signal.aborted) {
+            resolve(undefined);
+            return;
+          }
+          page.signal.addEventListener(
+            'abort',
+            () => {
+              withdraw(update);
+              resolve(undefined);
+            },
+            { once: true },
+          );
+
+          show(update);
+        });
+        return committing;
+      },
+    };
+  }
+
+  /**
+   * The router's mount in one step: prepare(), then its commit. Resolves
+   * once React has committed the page, or once the visit is aborted -- and
+   * then the page never commits.
+   *
+   * @param {ReadableStream<Uint8Array>} stream
+   * @param {import('./router.js').Page} page
+   * @returns {Promise<void>}
+   */
+  async function mount(stream, page) {
+    const prepared = await prepare(stream, page);
+    await prepared?.commit();
+  }
+
+  return { PageRoot, mount, prepare, instant };
+}
+
+/**
+ * Settles when $signal aborts.
+ *
+ * @param {AbortSignal} signal
+ * @returns {Promise<void>}
+ */
+function abortedOf(signal) {
+  return new Promise((resolve) => {
+    if (signal.aborted) resolve();
+    else signal.addEventListener('abort', () => resolve(), { once: true });
+  });
+}

package/src/payload.d.ts

@@ -0,0 +1,15 @@
+/** A row as the renderer writes it: payload text, or bytes that are not UTF-8 as base64. */
+export type PayloadRow = string | { $b64: string };
+
+/** The bytes one row stands for. Throws on anything that is not a row. */
+export function payloadRowBytes(row: unknown): Uint8Array;
+
+/**
+ * The inline payload (`self.__rsc`) as the byte stream React's client
+ * decodes. Reads rows as their scripts run, until `self.__rsc_done` is true.
+ */
+export function inlinePayloadStream(globals?: {
+  __rsc?: unknown;
+  __rsc_done?: unknown;
+  document?: { readyState?: string };
+}): ReadableStream<Uint8Array>;

package/src/payload.js

@@ -0,0 +1,101 @@
+// The RSC payload the renderer writes into the document, read back as the
+// byte stream React's client decodes.
+//
+// Each row is a `self.__rsc.push(...)` script (tinvar-spec.md, "Rendered
+// output"). A row is a string, which is the payload's own UTF-8 text; or,
+// for a stretch of payload that is not valid UTF-8 -- a Uint8Array or
+// ArrayBuffer prop, which Flight serializes as its raw bytes -- an object
+// {"$b64": "..."} carrying those bytes. The same marker the json-lines
+// codec uses for binary. Encoding every row as text again, as browser
+// entries did, replaced each byte that was not UTF-8 and corrupted the prop.
+
+const encoder = new TextEncoder();
+
+/**
+ * The bytes one row stands for.
+ *
+ * @param {unknown} row
+ * @returns {Uint8Array}
+ */
+export function payloadRowBytes(row) {
+  if (typeof row === 'string') return encoder.encode(row);
+
+  if (row !== null && typeof row === 'object' && typeof row.$b64 === 'string') {
+    const binary = atob(row.$b64);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+    return bytes;
+  }
+
+  throw new TypeError('Not a payload row: expected a string or {"$b64": "..."}.');
+}
+
+/** The longest the stream waits between looks for the payload's end. */
+const MAX_POLL_MS = 100;
+
+/**
+ * The inline payload as a stream, for createFromReadableStream().
+ *
+ * Rows already in the document are read at once; later ones as their
+ * scripts push them, until `self.__rsc_done` is true. The renderer claims
+ * both globals before any content, so page content naming an element `__rsc`
+ * cannot stand in for them. Checked here too: anything but an array is not
+ * the payload, and only `true` means done.
+ *
+ * A push is read as it is made. The end is looked for between pushes, less
+ * often the longer nothing comes, and no more once the document has loaded
+ * without it -- a render cut off partway sends nothing further, and was
+ * otherwise looked for every few milliseconds for as long as the tab stayed.
+ *
+ * @param {{ __rsc?: unknown, __rsc_done?: unknown, document?: { readyState?: string } }} [globals] defaults to `globalThis`
+ * @returns {ReadableStream<Uint8Array>}
+ */
+export function inlinePayloadStream(globals = /** @type {never} */ (globalThis)) {
+  const rows = Array.isArray(globals.__rsc) ? globals.__rsc : [];
+
+  return new ReadableStream({
+    start(controller) {
+      let index = 0;
+      let delay = 0;
+      /** @type {ReturnType<typeof setTimeout> | null} */
+      let timer = null;
+      let over = false;
+
+      const drain = () => {
+        if (over) return;
+        if (timer !== null) clearTimeout(timer);
+        timer = null;
+        const from = index;
+        try {
+          while (index < rows.length) controller.enqueue(payloadRowBytes(rows[index++]));
+        } catch (error) {
+          over = true;
+          controller.error(error);
+          return;
+        }
+        if (globals.__rsc_done === true) {
+          over = true;
+          controller.close();
+          return;
+        }
+        if (globals.document?.readyState === 'complete') return;
+        delay = index > from ? 0 : Math.min(MAX_POLL_MS, Math.max(4, delay * 2));
+        timer = setTimeout(drain, delay);
+      };
+
+      // Read as the renderer's scripts push, not when the next look comes.
+      const push = rows.push;
+      Object.defineProperty(rows, 'push', {
+        configurable: true,
+        writable: true,
+        value: (/** @type {unknown[]} */ ...items) => {
+          const length = push.apply(rows, items);
+          drain();
+          return length;
+        },
+      });
+
+      drain();
+    },
+  });
+}

package/src/poll.d.ts

@@ -0,0 +1,55 @@
+import type { Router, VisitOptions } from './router';
+
+/** How much slower a `throttle` poll runs while its tab is in the background. */
+export declare const THROTTLE_FACTOR: number;
+
+/**
+ * What a tick does about the poll before it, still in flight: `rest` waits
+ * for it and runs the interval from when it settled (the default); `cancel`
+ * cancels it; `overlap` lets both run, and an older answer arriving after a
+ * newer one is dropped.
+ */
+export type PollMode = 'overlap' | 'cancel' | 'rest';
+
+/** While the tab is hidden: ten times less often (the default), not at all, or as usual. */
+export type PollBackground = 'throttle' | 'pause' | 'continue';
+
+export interface PollSettings {
+  mode?: PollMode;
+  background?: PollBackground;
+  /** Start on mount. True unless given. */
+  autoStart?: boolean;
+  /** After each poll, have loaded <Deferred> boundaries fetch again, quietly. */
+  deferred?: boolean;
+}
+
+export interface Poller {
+  start(): void;
+  stop(): void;
+  readonly running: boolean;
+}
+
+/** The poll's timing without React: each tick is `router.reload({ ...options(), background: true })`. */
+export declare function createPoller(settings: {
+  router: Pick<Router, 'reload'>;
+  interval: number;
+  options?: () => VisitOptions;
+  mode?: PollMode;
+  background?: PollBackground;
+  document?: Document;
+  now?: () => number;
+  /** Called after each poll that landed. */
+  onPolled?: () => void;
+}): Poller;
+
+/**
+ * Refreshes the page on screen every `interval` ms through background
+ * reloads -- partial ones, given `only` or `except` -- while the component
+ * is mounted. Never navigates; a version mismatch fires `location` instead
+ * of reloading.
+ */
+export declare function usePoll(
+  interval: number,
+  options?: Omit<VisitOptions, 'background' | 'signal'>,
+  settings?: PollSettings,
+): { start: () => void; stop: () => void };