@tinvar/react 0.0.0-stage → 0.4.0

package/src/deferred-groups.js

@@ -0,0 +1,198 @@
+// The boundaries of one <Deferred group>, fetched together.
+//
+// Inertia's `Inertia::defer($fn, 'group')` loads every deferred prop in a
+// group in one request. Here a group is the boundaries on one page that
+// share a `group` name, and they load in one request too: when any of them
+// is triggered, every one of them that has something to load goes in a
+// single `GET /_fragment/<token>/<token>/...`, whose payload is the list of
+// their subtrees (ADR 0018). The server verifies each token, runs the page's
+// chain once, and renders them in one render, so their queries batch as a
+// page's do; here, each boundary is handed its own subtree.
+//
+// No React: the boundaries are React's, and talk to this through a small
+// member interface, so the batching rules can be read -- and tested --
+// without mounting anything.
+
+import { FragmentHandle } from './fragment-client.js';
+
+/**
+ * The most boundaries one request may carry. Mirrors
+ * FragmentEndpoint::MAX_GROUP: the endpoint answers a longer list with the
+ * same 404 as any refused token, which is final: a group sent past it whole
+ * never loaded, and every member gave up on its first try.
+ */
+export const MAX_GROUP = 16;
+
+/**
+ * What a boundary gives its group.
+ *
+ * @typedef {{
+ *   handle: FragmentHandle,
+ *   ready: (again: boolean, asked: boolean) => boolean,
+ *   start: (again: boolean, load?: Promise<unknown>) => void,
+ *   skip: (again: boolean) => void,
+ * }} Member
+ *
+ *   ready  whether it would load now: not already loading, not given up, and
+ *          not loaded unless it always refetches -- or `again`, for a
+ *          revalidation. `asked` says whether it was triggered itself, which
+ *          a boundary showing its rescue slot waits for.
+ *   start  runs its load: the one given, its share of the group's request,
+ *          or with none its own request, when it is the only one ready.
+ *   skip   it asked and was not ready.
+ */
+
+class Group {
+  /** @type {Set<Member>} */
+  members = new Set();
+  /** @type {Set<Member>} members that asked since the last flush */
+  asked = new Set();
+  again = false;
+  scheduled = false;
+  /** @type {Set<{ members: Set<Member>, controller: AbortController }>} */
+  flights = new Set();
+
+  /**
+   * @param {() => ((stream: ReadableStream<Uint8Array>) => unknown) | undefined} decode
+   * @param {() => Record<string, string>} claims
+   */
+  constructor(decode, claims) {
+    this.decode = decode;
+    this.claims = claims;
+  }
+
+  /** @param {Member} member @param {boolean} again */
+  request(member, again) {
+    this.asked.add(member);
+    this.again ||= again;
+    if (this.scheduled) return;
+    this.scheduled = true;
+
+    // A task, not a microtask: boundaries scrolled into view together are
+    // reported by one observer each, and those callbacks are not all in one
+    // microtask. Waiting a task gathers them into the one request.
+    setTimeout(() => this.flush(), 0);
+  }
+
+  flush() {
+    this.scheduled = false;
+    const { again, asked } = this;
+    this.again = false;
+    this.asked = new Set();
+
+    const batch = [];
+    for (const member of this.members) {
+      if (member.ready(again, asked.has(member))) batch.push(member);
+      else if (asked.has(member)) member.skip(again);
+    }
+
+    // Past the endpoint's cap, in requests of at most MAX_GROUP: each its own
+    // flight, which succeeds or fails on its own, as two groups' would.
+    for (let i = 0; i < batch.length; i += MAX_GROUP) {
+      this.send(batch.slice(i, i + MAX_GROUP), again);
+    }
+  }
+
+  /** @param {Member[]} batch @param {boolean} again */
+  send(batch, again) {
+    // One alone is an ordinary request: its payload's root is its subtree,
+    // as a lone boundary's is.
+    if (batch.length === 1) {
+      batch[0].start(again);
+      return;
+    }
+
+    const controller = new AbortController();
+    const flight = { members: new Set(batch), controller };
+    this.flights.add(flight);
+
+    const loading = FragmentHandle.loadGroup(
+      batch.map((member) => member.handle),
+      { signal: controller.signal, decode: this.decode() ?? ((stream) => stream), headers: this.claims() },
+    );
+    loading.then(
+      () => this.flights.delete(flight),
+      () => this.flights.delete(flight),
+    );
+
+    batch.forEach((member, i) =>
+      member.start(
+        again,
+        loading.then((nodes) => nodes[i]),
+      ),
+    );
+  }
+
+  /** @param {Member} member */
+  leave(member) {
+    this.members.delete(member);
+    this.asked.delete(member);
+
+    // Abandoned once nobody it was for is left -- the page moved on -- and
+    // let go of now: its abort settles later, after the group's last leave
+    // has looked to see whether anything is still in flight.
+    for (const flight of this.flights) {
+      flight.members.delete(member);
+      if (flight.members.size === 0) {
+        this.flights.delete(flight);
+        flight.controller.abort();
+      }
+    }
+  }
+}
+
+/** Every group under one <FragmentProvider>, by name. */
+export class FragmentGroups {
+  /** @type {Map<string, Group>} */
+  #groups = new Map();
+  #decode;
+  #claims;
+
+  /**
+   * @param {() => ((stream: ReadableStream<Uint8Array>) => unknown) | undefined} decode the provider's, when asked
+   * @param {() => Record<string, string>} [claims] the once-shared holds to claim, when asked (ADR 0074)
+   */
+  constructor(decode, claims = () => ({})) {
+    this.#decode = decode;
+    this.#claims = claims;
+  }
+
+  /**
+   * @param {string} name
+   * @param {Member} member
+   * @returns {() => void} leave
+   */
+  join(name, member) {
+    let group = this.#groups.get(name);
+    if (!group) {
+      group = new Group(this.#decode, this.#claims);
+      this.#groups.set(name, group);
+    }
+    group.members.add(member);
+
+    return () => {
+      group.leave(member);
+      // Unregistered once empty -- unless a newer group has taken the name.
+      if (group.members.size === 0 && group.flights.size === 0 && this.#groups.get(name) === group) {
+        this.#groups.delete(name);
+      }
+    };
+  }
+
+  /** How many groups have members: one that has none is forgotten. */
+  get size() {
+    return this.#groups.size;
+  }
+
+  /**
+   * Asks for the group to load: on the next task, every member that is
+   * ready loads, in one request.
+   *
+   * @param {string} name
+   * @param {Member} member the one asking
+   * @param {boolean} again a revalidation: loaded members load again too
+   */
+  request(name, member, again) {
+    this.#groups.get(name)?.request(member, again);
+  }
+}

package/src/deferred-revalidation.d.ts

@@ -0,0 +1,37 @@
+/** When an action's revalidation is replacing what deferred boundaries show. */
+
+export interface RevalidationState {
+  /** An action's revalidation of the mounted page is in flight. */
+  active: boolean;
+  /** Bumped each time one settles having revalidated the page. */
+  generation: number;
+  /** Bumped by refreshDeferred(): loaded boundaries fetch again, without reloading. */
+  quiet: number;
+}
+
+export declare const AT_REST: RevalidationState;
+
+/**
+ * Marks the boundaries on the page as reloading until the returned settle()
+ * is called: with `revalidated: true` (the default) once the revalidated page
+ * is mounted, so loaded boundaries fetch their fragments again; with `false`
+ * when the action ended without revalidating it.
+ */
+export declare function beginRevalidation(): (outcome?: { revalidated?: boolean }) => void;
+
+/**
+ * Asks every loaded boundary on the page to fetch its content again, reloading
+ * until the fresh content is on screen -- for an action whose response named
+ * the tags it invalidated but re-rendered no route.
+ */
+export declare function revalidateDeferred(): void;
+
+/**
+ * Asks every loaded boundary on the page to fetch its content again without
+ * marking it reloading -- for a poll, where nothing an action did changed the
+ * page and dimming it on a timer would be motion on a data refresh.
+ */
+export declare function refreshDeferred(): void;
+
+export declare function revalidationState(): RevalidationState;
+export declare function onRevalidation(listener: () => void): () => void;

package/src/deferred-revalidation.js

@@ -0,0 +1,108 @@
+// When an action's revalidation is replacing what deferred boundaries show.
+//
+// tinvar-spec.md, "Rescue and reloading": "A `reloading` flag lets a boundary
+// dim stale content while an action's revalidation streams in."
+//
+// The router owns actions and the payloads they bring back; the boundaries
+// own what they do about one. This is the seam between them, and it is
+// deliberately narrow: whoever runs an action against the mounted page -- the
+// router, a form helper -- calls beginRevalidation() when it starts, and the
+// returned settle() once the revalidated page is mounted, or the action has
+// ended without revalidating anything.
+//
+//   - From begin to settle, every boundary with content on screen is
+//     `reloading`: what it shows may be about to change.
+//   - On settle({ revalidated: true }), each of them fetches its fragment
+//     again -- a re-rendered page hands it a re-issued token for the same
+//     content, which it keeps, so nothing else would -- and stays
+//     `reloading` until the fresh content is on screen.
+//   - On settle({ revalidated: false }), they stop reloading and keep what
+//     they show.
+//
+// No React and no DOM, so the router -- which never imports React -- can
+// call it.
+
+let active = 0;
+let generation = 0;
+let quiet = 0;
+const listeners = new Set();
+
+/** @type {{ active: boolean, generation: number, quiet: number }} */
+let snapshot = Object.freeze({ active: false, generation: 0, quiet: 0 });
+
+/** What a server render reads: nothing is being revalidated there. */
+export const AT_REST = Object.freeze({ active: false, generation: 0, quiet: 0 });
+
+/**
+ * Marks the boundaries on the page as reloading, until the returned settle()
+ * is called. Each call needs its own settle; overlapping revalidations keep
+ * the boundaries reloading until the last one settles.
+ *
+ * @returns {(outcome?: { revalidated?: boolean }) => void}
+ */
+export function beginRevalidation() {
+  active++;
+  publish();
+
+  let settled = false;
+  return ({ revalidated = true } = {}) => {
+    // Once: a caller settling in both a then and a finally must not end
+    // someone else's revalidation.
+    if (settled) return;
+    settled = true;
+    active--;
+    if (revalidated) generation++;
+    publish();
+  };
+}
+
+/**
+ * Asks every loaded boundary on the page to fetch its content again, as an
+ * action's re-render of the page does: reloading until the fresh content is
+ * on screen.
+ *
+ * For an action that re-rendered no route but whose response named the
+ * query tags it invalidated. "When an action revalidates a tag, the client
+ * re-fetches any mounted fragment that read it" (tinvar-spec.md, "Deferred
+ * components") -- and which fragment read which tag is the server's to
+ * know, not the client's, so every loaded one fetches again.
+ */
+export function revalidateDeferred() {
+  beginRevalidation()({ revalidated: true });
+}
+
+/**
+ * Asks every loaded boundary on the page to fetch its content again, without
+ * marking it reloading. For a poll: content that may have moved on, where no
+ * action changed anything, and where dimming the page every few seconds
+ * would be motion on a data refresh (MER-10.5). A boundary still on its
+ * fallback is untouched -- it loads on its own trigger -- and a load is
+ * still subject to the boundary's backoff and failure limit.
+ */
+export function refreshDeferred() {
+  quiet++;
+  publish();
+}
+
+/**
+ * For useSyncExternalStore: the same object until something changes.
+ *
+ * @returns {{ active: boolean, generation: number, quiet: number }}
+ */
+export function revalidationState() {
+  return snapshot;
+}
+
+/**
+ * @param {() => void} listener
+ * @returns {() => void} unsubscribe
+ */
+export function onRevalidation(listener) {
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+}
+
+function publish() {
+  snapshot = Object.freeze({ active: active > 0, generation, quiet });
+  for (const listener of listeners) listener();
+}

package/src/deferred-triggers.d.ts

@@ -0,0 +1,26 @@
+/** When a deferred boundary decides to fetch. */
+
+export interface TriggerOptions {
+  /** A <Deferred> without one hands it on as undefined. */
+  buffer?: number | undefined;
+  always?: boolean | undefined;
+  /** The scroll container `visible` measures against; the document without one. */
+  root?: Element | null;
+}
+
+export type Trigger = (element: Element, load: () => void, options?: TriggerOptions) => () => void;
+
+export declare const onVisible: Trigger;
+export declare const onIdle: Trigger;
+export declare const onInteraction: Trigger;
+export declare const onManual: Trigger;
+
+export declare const TRIGGERS: Record<'visible' | 'idle' | 'interaction' | 'manual', Trigger>;
+
+/** An unknown name loads immediately rather than leaving a boundary empty. */
+export declare function installTrigger(
+  name: string,
+  element: Element,
+  load: () => void,
+  options?: TriggerOptions,
+): () => void;

package/src/deferred-triggers.js

@@ -0,0 +1,172 @@
+// When a deferred boundary decides to fetch.
+//
+// tinvar-spec.md, "Deferred components":
+//
+//   visible      The placeholder scrolls into view (IntersectionObserver)
+//   idle         The browser is idle after hydration
+//   interaction  The user hovers, focuses or clicks inside the placeholder
+//   manual       Client code calls .load() from a ref
+//
+// Each trigger is a function taking the placeholder element and a callback,
+// and returning a teardown. They are deliberately plain: no React, no shared
+// state, nothing that needs a bundler. That makes them testable in isolation,
+// which is why they live here instead of inside the component.
+//
+// Every trigger fires its callback AT MOST ONCE and tears itself down on the
+// way. A boundary that fetched twice because a user scrolled past it twice
+// would be a self-inflicted request storm, and `always` (refetch each time it
+// becomes visible) is a separate opt-in rather than the default.
+
+/** Pixels before the element enters the viewport, per the spec's `buffer`. */
+const DEFAULT_BUFFER = 0;
+
+/**
+ * `root` is the scroll container to measure against, for an element inside
+ * one -- <InfiniteScroll> in a chat panel, say. Without it, the document.
+ *
+ * @param {Element} element
+ * @param {() => void} load
+ * @param {{buffer?: number, always?: boolean, root?: Element | null}} [options]
+ * @returns {() => void} teardown
+ */
+export function onVisible(element, load, options = {}) {
+  // A number of pixels, or none. Anything else -- NaN, a string with a unit,
+  // Infinity -- made a rootMargin the observer's constructor throws on, and
+  // the boundary failed in its effect instead of loading.
+  const requested = Number(options.buffer ?? DEFAULT_BUFFER);
+  const buffer = Number.isFinite(requested) ? requested : DEFAULT_BUFFER;
+
+  // No IntersectionObserver means no way to know when this scrolls into view.
+  // Loading immediately is the right failure: the content is the point, and a
+  // boundary that silently never loads is worse than one that loads early.
+  if (typeof IntersectionObserver === 'undefined') {
+    load();
+    return () => {};
+  }
+
+  let fired = false;
+
+  const observer = new IntersectionObserver(
+    (entries) => {
+      // One delivery can carry several records for the element -- it
+      // entered, left and entered again between two runs of the observer's
+      // task -- and each intersecting one called load. disconnect() stops
+      // later deliveries, not the rest of this one. Once per delivery, and
+      // without `always` once at all.
+      if (fired || !entries.some((entry) => entry.isIntersecting)) return;
+
+      if (!options.always) {
+        fired = true;
+        observer.disconnect();
+      }
+      load();
+    },
+    {
+      // The DOCUMENT as root, not the implicit one. With the implicit root,
+      // the spec ignores rootMargin for a target outside the top-level
+      // document -- so in any page rendered inside a frame, `buffer` was
+      // silently a no-op. Measured in Chromium: a target 50px past the fold
+      // with a 200px margin reports not-intersecting under the implicit
+      // root and intersecting with root: document. The same in a top-level
+      // page, and correct in a frame.
+      root: options.root ?? (typeof document === 'undefined' ? null : document),
+      rootMargin: `${buffer}px`,
+    },
+  );
+
+  observer.observe(element);
+
+  return () => observer.disconnect();
+}
+
+/**
+ * The element is unused, but the signature is uniform so TRIGGERS can call
+ * every trigger the same way.
+ *
+ * @param {Element} _element
+ * @param {() => void} load
+ * @returns {() => void}
+ */
+export function onIdle(_element, load) {
+  // requestIdleCallback is still missing in Safari. A timeout is the honest
+  // fallback: "idle" means "not now, but soon", and a frame or two later is
+  // a closer reading than never.
+  if (typeof requestIdleCallback !== 'function') {
+    const timer = setTimeout(load, 1);
+    return () => clearTimeout(timer);
+  }
+
+  const handle = requestIdleCallback(() => load(), { timeout: 2000 });
+
+  // Guarded the same way the scheduling call is. A polyfill or test shim can
+  // provide one without the other, and a bare reference in the teardown
+  // throws ReferenceError at exactly the moment a boundary is being removed.
+  return () => {
+    if (typeof cancelIdleCallback === 'function') cancelIdleCallback(handle);
+  };
+}
+
+/**
+ * @param {Element} element
+ * @param {() => void} load
+ * @returns {() => void}
+ */
+export function onInteraction(element, load) {
+  // focusin, not focus: focus does not bubble, so a focusable child would
+  // never reach a listener on the placeholder.
+  const events = ['pointerenter', 'focusin', 'click'];
+
+  const fire = () => {
+    teardown();
+    load();
+  };
+
+  const teardown = () => {
+    for (const event of events) element.removeEventListener(event, fire);
+  };
+
+  for (const event of events) element.addEventListener(event, fire, { once: false });
+
+  return teardown;
+}
+
+/**
+ * `manual`: nothing watches, the handle's load() is the only trigger.
+ *
+ * @returns {() => void}
+ */
+export function onManual() {
+  return () => {};
+}
+
+export const TRIGGERS = {
+  visible: onVisible,
+  idle: onIdle,
+  interaction: onInteraction,
+  manual: onManual,
+};
+
+/**
+ * Installs the named trigger.
+ *
+ * An unknown trigger name is a developer error, and the safe reading is NOT
+ * "never load" -- that ships a page with a permanently empty boundary. It
+ * loads and says so.
+ *
+ * @param {string} name
+ * @param {Element} element
+ * @param {() => void} load
+ * @param {{buffer?: number, always?: boolean}} [options]
+ * @returns {() => void}
+ */
+export function installTrigger(name, element, load, options = {}) {
+  const trigger = TRIGGERS[name];
+
+  if (!trigger) {
+    console.error(`[tinvar] Unknown <Deferred load="${name}">; loading immediately.`);
+    load();
+    return () => {};
+  }
+
+  return trigger(element, load, options);
+}

package/src/deferred.d.ts

@@ -0,0 +1,24 @@
+import type { ReactNode } from 'react';
+
+export interface DeferredProps {
+  /** The server component to render later, by its name in the app's registry. */
+  component: string;
+  /** Signed, not encrypted: readable in page source, so never a secret. */
+  props?: Record<string, unknown>;
+  load?: 'visible' | 'idle' | 'interaction' | 'manual';
+  fallback?: ReactNode;
+  /** Shown beside the content while the boundary fetches it again; useDeferred().fetching in a client component. */
+  fetching?: ReactNode;
+  /** Shown once the server's render of the fragment throws; reported to PHP, and the page carries on. */
+  rescue?: ReactNode;
+  /** Pixels before the boundary is visible to load it: an IntersectionObserver rootMargin. */
+  buffer?: number;
+  /** Fetch again each time the boundary comes back into view, with the usual backoff and limits. */
+  always?: boolean;
+  /** Boundaries on a page sharing a group load together, in one request. */
+  group?: string;
+  id?: string;
+}
+
+/** A boundary whose subtree renders after the page has loaded, on a trigger. */
+export declare function Deferred(props: DeferredProps): Promise<ReactNode>;

package/src/deferred.jsx

@@ -0,0 +1,100 @@
+// <Deferred>: a server component that renders a placeholder, not its children.
+//
+// tinvar-spec.md, "Deferred components":
+//
+//   "During the page render, the renderer does not render the children. It
+//    emits a placeholder carrying a fragment token: component ID, props,
+//    route, panel, build, session hash and expiry under one MAC."
+//
+// "Does not render the children" is the whole value. Suspense streams work
+// that is already happening; Deferred skips the work entirely until someone
+// needs it. So this component must never touch `children` -- doing so would
+// run the very queries it exists to avoid, and the page would pay for a
+// subtree nobody has asked to see.
+//
+// That is why the boundary is declared by `component` and `props` rather than
+// by the children themselves: PHP renders the named component when the
+// fragment is requested, and the children are only ever a type-level hint of
+// what will appear there.
+
+import { mintFragmentToken } from './server.js';
+import { DeferredBoundary } from './deferred-boundary.js';
+
+/**
+ * `props` are SIGNED, not encrypted.
+ *
+ * The token looks opaque but is `v1.<base64url(json)>.<mac>`, so anything in
+ * props is readable from page source, a screenshot, or a page pasted into a
+ * bug report -- with no key and no session. The spec says props "must not
+ * contain secrets"; this is the reminder, because a developer looking at the
+ * rendered attribute has no reason to guess it is plaintext.
+ *
+ * `rescue` is shown instead of the fragment once the server's render of it
+ * throws: the failure is reported to PHP's exception handler and the page
+ * carries on (tinvar-spec.md, "Rescue and reloading"). An element, like
+ * `fallback`, rendered on either side; a client component in it reads the
+ * digest and a retry from useDeferred().
+ *
+ * `buffer`, `always` and `fetching` are Inertia's <WhenVisible>: load that
+ * many pixels before the boundary is visible; fetch again each time it
+ * comes back into view, paced by the same backoff and limits as any load;
+ * and show `fetching` beside the content while it does. `fetching` is an
+ * element rather than Inertia's render function, which could not cross from
+ * this server component to the client tree; a client component reads the
+ * same flag from useDeferred().
+ *
+ * `group` is Inertia's `Inertia::defer($fn, 'group')`: boundaries on a page
+ * sharing one load together, in one request the server renders as one --
+ * whichever is triggered first loads them all (ADR 0018).
+ *
+ * @param {{
+ *   component: string,
+ *   props?: Record<string, unknown>,
+ *   load?: 'visible' | 'idle' | 'interaction' | 'manual',
+ *   fallback?: unknown,
+ *   fetching?: unknown,
+ *   rescue?: unknown,
+ *   buffer?: number,
+ *   always?: boolean,
+ *   group?: string,
+ *   id?: string,
+ * }} options
+ */
+export async function Deferred({
+  component,
+  props = {},
+  load = 'visible',
+  fallback = null,
+  fetching,
+  rescue,
+  buffer,
+  always,
+  group,
+  id,
+}) {
+  if (typeof component !== 'string' || component === '') {
+    throw new Error('<Deferred> needs a `component` naming the server component to render later.');
+  }
+
+  const token = await mintFragmentToken(component, props);
+
+  // The boundary is a client component: React renders the fallback now and
+  // the fragment once the trigger fires, through Suspense. It carries the
+  // token and nothing else. The token is readable in page source by design
+  // -- it is not a capability, and the fragment endpoint re-runs the
+  // originating route's authorization on use -- but it is still per-session,
+  // so the markup it sits in is never cacheable across visitors.
+  return (
+    <DeferredBoundary
+      token={token}
+      load={load}
+      buffer={buffer}
+      always={always}
+      group={group}
+      id={id}
+      fallback={fallback}
+      fetching={fetching}
+      rescue={rescue}
+    />
+  );
+}