@tinvar/react 0.0.0-stage → 0.4.0

package/src/channel.js

@@ -0,0 +1,132 @@
+// Subscribing to the application's #[Channel]s, by the names codegen writes
+// (ADR 0069).
+//
+// `channel.listen('orders', { order }, (message) => ...)` asks the server
+// for a subscription -- POST /_channel/orders, with the session's CSRF
+// token, its parameters in the body -- and the server lets it in as it lets
+// in any entry point: the tenant, the panel and its stack, the models
+// resolved in the tenant, every #[Authorize]. What it answers with is a
+// token, never a topic: the client names a channel and its parameters, the
+// server works out the topic from what it resolved, and the token is handed
+// to the live module (subscribeChannel), which trades it beside the page's
+// at /_live/subscribe and delivers each message published to it.
+//
+// A refusal -- 401, 403, 404 -- subscribes to nothing and is handed to
+// `onError`; nothing is retried, since asking again is asking the same
+// checks. A 204 is a server with no hub, where nothing is heard: no error.
+//
+// A token that ran out unrenewed -- a tab hidden past its five minutes --
+// is asked for again the same way, the checks run afresh, and `onGap`
+// called once the new one is listened to: messages published meanwhile
+// were not heard. A refusal then goes to `onError`, as the first would.
+// No React: a hook is in use-channel.js.
+
+import { csrfHeaders } from './csrf.js';
+import { subscribeChannel } from './live.js';
+
+export const CHANNEL_PATH = '/_channel/';
+
+/** A channel name, as the server declares them: dot-separated identifiers. */
+const NAME_SHAPE = /^[A-Za-z_][A-Za-z0-9_]*(?:\.[A-Za-z_][A-Za-z0-9_]*)*$/;
+
+/** A subscription the server refused, or that could not be asked for. */
+export class ChannelError extends Error {
+  /**
+   * @param {string} name
+   * @param {number} status 0 when the request never got an answer
+   */
+  constructor(name, status) {
+    super(`[tinvar] The channel '${name}' refused a subscription (${status}).`);
+    this.name = 'ChannelError';
+    this.channel = name;
+    this.status = status;
+  }
+}
+
+/**
+ * Subscribes to one channel until the returned function is called.
+ *
+ * @param {string} name
+ * @param {Record<string, string | number | boolean>} params
+ * @param {(message: unknown) => void} onMessage
+ * @param {{ fetch?: typeof fetch, document?: Document, onError?: (error: ChannelError) => void, onGap?: () => void }} [options]
+ * @returns {() => void}
+ */
+export function listen(name, params, onMessage, options = {}) {
+  const fetchImpl = options.fetch ?? globalThis.fetch?.bind(globalThis);
+  const fail = (/** @type {number} */ status) => options.onError?.(new ChannelError(name, status));
+
+  if (!NAME_SHAPE.test(name) || !fetchImpl) {
+    fail(0);
+    return () => {};
+  }
+
+  let closed = false;
+  let off = () => {};
+  const controller = new AbortController();
+
+  /** Asks for the subscription: its token, or null after telling `onError` why not. */
+  const ask = async () => {
+    let response;
+    try {
+      response = await fetchImpl(CHANNEL_PATH + name, {
+        method: 'POST',
+        headers: {
+          'content-type': 'application/json',
+          accept: 'application/json',
+          ...csrfHeaders(options.document ?? globalThis.document),
+        },
+        body: JSON.stringify({ params }),
+        credentials: 'same-origin',
+        mode: 'same-origin',
+        redirect: 'error',
+        cache: 'no-store',
+        signal: controller.signal,
+      });
+    } catch {
+      if (!closed) fail(0);
+      return null;
+    }
+    if (closed) return null;
+    if (!response.ok) {
+      fail(response.status);
+      return null;
+    }
+    // Nothing to hear: the application runs with no hub, as under php -S.
+    if (response.status === 204) return null;
+
+    let body;
+    try {
+      body = await response.json();
+    } catch {
+      if (!closed) fail(response.status);
+      return null;
+    }
+    if (closed) return null;
+
+    const token = typeof body?.token === 'string' ? body.token : null;
+    if (token === null) fail(response.status);
+    return token;
+  };
+
+  void ask().then((token) => {
+    if (token !== null && !closed) off = subscribeChannel(token, onMessage, options.onGap, ask);
+  });
+
+  return () => {
+    if (closed) return;
+    closed = true;
+    controller.abort();
+    off();
+  };
+}
+
+/**
+ * The typed `channel` codegen exports: `listen()` by name, each name's
+ * parameters and message typed by the ChannelMap it is built for.
+ *
+ * @returns {{ listen: typeof listen }}
+ */
+export function channels() {
+  return { listen };
+}

package/src/client-modules.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Starts watching the RSC client's module loads on `scope` (the global
+ * object by default). False where no RSC client is installed.
+ */
+export declare function watchClientModules(scope?: Record<string, unknown>): boolean;
+
+/** Settles once every client module load started so far has; null when none is pending. */
+export declare function clientModulesSettled(scope?: Record<string, unknown>): Promise<void> | null;

package/src/client-modules.js

@@ -0,0 +1,88 @@
+// The client components a payload names, and whether their chunks are here.
+//
+// Decoding a page's payload resolves its root as soon as the root's row has
+// arrived. A client component the page renders is a module reference in
+// that payload: the decoder starts loading its chunk when it reads the
+// reference, and React suspends on it where the page renders it. So a
+// commit made the moment the root resolved could wait inside React for a
+// chunk still on the wire -- and the router runs that commit in a view
+// transition, which holds the old page frozen on screen until React is done
+// (ADR 0045).
+//
+// The decoder asks for every client module through one function, the RSC
+// plugin's `__vite_rsc_require__`, looked up on the global object each time:
+// the first call for a module starts its load and hands back the load's
+// promise, later ones the same promise. Wrapped here, every load a payload
+// starts is seen while it is pending, and prepare() waits for those before
+// it hands the router a commit (page-root.js). A load that fails is waited
+// for too, and then left to the page's error boundary, as before.
+//
+// Only what the decoder has asked for by the time the root resolves: a
+// chunk named further down the stream, under a Suspense boundary still
+// streaming, is that boundary's to wait for, not the commit's.
+
+/** The global the RSC plugin's client require is installed on. */
+const REQUIRE = '__vite_rsc_require__';
+
+/** Set on the wrapper, so it is never wrapped twice. */
+const WATCHED = Symbol.for('tinvar.clientModules.watched');
+
+/** @type {WeakMap<object, Set<PromiseLike<unknown>>>} what each global object's decoder is still loading */
+const pendingBy = new WeakMap();
+
+/**
+ * Starts watching the client module loads on $scope -- the global object,
+ * unless a test gives another. Nothing to watch where no RSC client is
+ * installed; asked again, it watches once.
+ *
+ * @param {Record<string, unknown>} [scope]
+ * @returns {boolean} whether there is a require to watch
+ */
+export function watchClientModules(scope = /** @type {Record<string, unknown>} */ (globalThis)) {
+  const original = scope[REQUIRE];
+  if (typeof original !== 'function') return false;
+  if (/** @type {any} */ (original)[WATCHED] === true) return true;
+
+  /** @type {Set<PromiseLike<unknown>>} */
+  const pending = pendingBy.get(scope) ?? new Set();
+  pendingBy.set(scope, pending);
+
+  /** @param {string} id */
+  const watched = function (id) {
+    const loaded = original.call(this, id);
+    // A promise the decoder has not seen settle: the flight client marks
+    // a settled one `fulfilled` on the promise itself.
+    if (
+      loaded !== null &&
+      typeof loaded === 'object' &&
+      typeof (/** @type {any} */ (loaded).then) === 'function' &&
+      /** @type {any} */ (loaded).status !== 'fulfilled' &&
+      !pending.has(loaded)
+    ) {
+      pending.add(loaded);
+      const done = () => pending.delete(loaded);
+      /** @type {PromiseLike<unknown>} */ (loaded).then(done, done);
+    }
+    return loaded;
+  };
+  // What the plugin hung on its require -- a chunk-name lookup, in
+  // webpack's shape -- stays reachable through the wrapper.
+  Object.assign(watched, original);
+  Object.defineProperty(watched, WATCHED, { value: true });
+  scope[REQUIRE] = watched;
+  return true;
+}
+
+/**
+ * Settles once every client module load started so far has settled, either
+ * way; null when none is pending.
+ *
+ * @param {Record<string, unknown>} [scope]
+ * @returns {Promise<void> | null}
+ */
+export function clientModulesSettled(scope = /** @type {Record<string, unknown>} */ (globalThis)) {
+  const pending = pendingBy.get(scope);
+  if (pending === undefined || pending.size === 0) return null;
+
+  return Promise.allSettled([...pending]).then(() => undefined);
+}

package/src/client.d.ts

@@ -0,0 +1,36 @@
+export * from './router';
+export { parseDuration, cacheWindow, DEFAULT_CACHE_FOR } from './prefetch-cache';
+export * from './page-root';
+export { useLayoutProps, useSetLayoutProps } from './layout-props';
+export type { LayoutPropsStore } from './layout-props';
+export { FragmentProvider, loadDeferred, useDeferred, LOAD_EVENT } from './deferred-boundary';
+export type { DeferredState } from './deferred-boundary';
+export { beginRevalidation, refreshDeferred } from './deferred-revalidation';
+export { createLive, subscribeLive, readLiveToken, LIVE_BLOCK_ID } from './live';
+export type { Live, LiveOptions } from './live';
+export * from './fragment-client';
+export * from './rescue';
+export { installTrigger, TRIGGERS } from './deferred-triggers';
+export { csrfToken, csrfHeaders, CSRF_COOKIE, CSRF_HEADER } from './csrf';
+export * from './payload';
+export * from './action';
+export {
+  Form,
+  FormSession,
+  useFlash,
+  useFormContext,
+  RECENTLY_SUCCESSFUL_MS,
+  type FormProps,
+  type FormSlotProps,
+  type SubmitCallbacks,
+  type VisitOptions as FormVisitOptions,
+  type HttpFailure,
+  type Progress,
+  type Flashed,
+  type ActionResult,
+  type PrecognitionSettings,
+} from './form';
+export * from './use-form';
+export * from './use-http';
+export * from './optimistic';
+export * from './when-mounted';

package/src/client.js

@@ -0,0 +1,42 @@
+// @tinvar/react/client -- browser-only code.
+//
+// Separate from the package root because the root re-exports the server
+// helpers, which import node:async_hooks. A browser bundle importing the
+// root would pull that in; a client entry that imports only this cannot.
+
+export {
+  createRouter,
+  readPageMetadata,
+  bindingOf,
+  invalidatedTags,
+  flushInvalidated,
+  clearHistory,
+  INVALIDATED_TAGS_HEADER,
+  HISTORY_KEY_HEADER,
+  VisitCancelled,
+  VisitHttpError,
+  VisitNetworkError,
+  PAGE_METADATA_ID,
+  PAGE_HEADER,
+  PARTIAL_HEADER,
+  PREFETCH_PURPOSE,
+  BACKGROUND_HEADER,
+  RSC_CONTENT_TYPE,
+  ROUTE_TOKEN_HEADER,
+  LIVE_TOKEN_HEADER,
+  SCROLL_REGION_ATTRIBUTE,
+} from './router.js';
+export { createLive, subscribeLive, readLiveToken, LIVE_BLOCK_ID } from './live.js';
+export { parseDuration, cacheWindow, DEFAULT_CACHE_FOR } from './prefetch-cache.js';
+export { createPageRoot } from './page-root.js';
+export { useLayoutProps, useSetLayoutProps } from './layout-props.js';
+export { FragmentProvider, loadDeferred, useDeferred, LOAD_EVENT } from './deferred-boundary.js';
+export { beginRevalidation, refreshDeferred } from './deferred-revalidation.js';
+export { FragmentHandle, FragmentError, serverFailure } from './fragment-client.js';
+export { isRescued, RESCUED_KEY } from './rescue.js';
+export { installTrigger, TRIGGERS } from './deferred-triggers.js';
+export { csrfToken, csrfHeaders, CSRF_COOKIE, CSRF_HEADER } from './csrf.js';
+export { inlinePayloadStream, payloadRowBytes } from './payload.js';
+export { action, actionName, actionUrl, isActionReference, ActionError, ACTION_PREFIX } from './action.js';
+export * from './forms.js';
+export { WhenMounted } from './when-mounted.js';

package/src/compose-route.d.ts

@@ -0,0 +1,33 @@
+import type { ReactNode } from 'react';
+
+/** The segment the page itself renders as. */
+export declare const PAGE_SEGMENT: 'page';
+
+export interface LayoutSegment {
+  /** The layout's key, as in `LayoutProps<'shop'>`. */
+  key: string;
+  render: (children: ReactNode) => ReactNode;
+  /**
+   * What an instant visit under this layout shows where its child goes
+   * while the next page is fetched (ADR 0092): a skeleton, drawn from
+   * nothing the next page's loader returns.
+   */
+  loading?: () => ReactNode;
+}
+
+/** What a partial reload sends: each recomputed segment, rendered alone. */
+export interface PartialRoute {
+  segments: Record<string, ReactNode>;
+}
+
+/**
+ * The whole document, every segment in its <Segment> slot; or, given the
+ * frame's `segments`, only those, as `{ segments }`.
+ */
+export declare function composeRoute(route: {
+  /** Outermost first, as their loaders run. */
+  layouts: readonly LayoutSegment[];
+  page: () => ReactNode;
+  document?: (children: ReactNode) => ReactNode;
+  segments?: readonly string[] | null | undefined;
+}): ReactNode | PartialRoute;

package/src/compose-route.js

@@ -0,0 +1,107 @@
+// What a route renders: the whole document, or only what a partial reload
+// recomputed.
+//
+// ADR 0015. The renderer is handed a frame whose `segments`, when present,
+// name the layouts and page a partial reload recomputed -- and whose loader
+// data holds theirs alone. Those are rendered on their own, each as it
+// would sit in the page, and sent as `{ segments }` for the page root to put
+// in place. Without `segments` the route renders whole, every segment
+// wrapped in the <Segment> slot that receives them later.
+//
+// Both shapes are built here, from one description of the route, so an
+// application's entry cannot render the slots one way and the partial
+// payload another.
+//
+// A layout may give a loading boundary (ADR 0092): what an instant visit
+// shows in its child's slot while the next page under it is fetched. It is
+// rendered here, with the page, and rides on that slot as a prop -- the
+// browser holds it from then on, drawn by the server for this request like
+// everything else on the page.
+//
+// No Node and no DOM: this runs in the RSC environment, where <Segment> is
+// a client reference.
+
+import { createElement } from 'react';
+import { Segment } from './segment.js';
+
+/** The segment the page itself renders as. */
+export const PAGE_SEGMENT = 'page';
+
+/**
+ * @typedef {{
+ *   key: string,
+ *   render: (children: unknown) => unknown,
+ *   loading?: () => unknown,
+ * }} LayoutSegment
+ *
+ * @param {{
+ *   layouts: readonly LayoutSegment[],
+ *   page: () => unknown,
+ *   document?: (children: unknown) => unknown,
+ *   segments?: readonly string[] | null,
+ * }} route layouts outermost first, as their loaders run; `segments` from
+ *   the frame
+ * @returns {unknown} the document, or `{ segments }` for a partial reload
+ */
+export function composeRoute({ layouts, page, document, segments }) {
+  const keys = [...layouts.map((layout) => layout.key), PAGE_SEGMENT];
+  if (new Set(keys).size !== keys.length) {
+    throw new Error(
+      `[tinvar] A route's segments must have distinct keys, and none may be '${PAGE_SEGMENT}'.`,
+    );
+  }
+
+  if (segments === undefined || segments === null) {
+    let tree = createElement(Segment, slot(PAGE_SEGMENT, layouts.at(-1), page()));
+    for (let i = layouts.length - 1; i >= 0; i--) {
+      const layout = /** @type {LayoutSegment} */ (layouts[i]);
+      tree = createElement(Segment, slot(layout.key, layouts[i - 1], layout.render(tree)));
+    }
+    return document ? document(tree) : tree;
+  }
+
+  /** @type {Record<string, unknown>} */
+  const out = {};
+  for (const key of segments) {
+    const at = keys.indexOf(key);
+    // Not one of this route's: nothing to render for it.
+    if (at === -1) continue;
+
+    if (key === PAGE_SEGMENT) {
+      out[key] = page();
+      continue;
+    }
+
+    // Its child was not recomputed, so it is an empty slot, which keeps
+    // what the page already shows there.
+    const layout = /** @type {LayoutSegment} */ (layouts[at]);
+    out[key] = layout.render(createElement(Segment, slot(/** @type {string} */ (keys[at + 1]), layout)));
+  }
+
+  return { segments: out };
+}
+
+/**
+ * The props of the slot segment `id` sits in, inside `parent`: its children,
+ * and its parent's loading boundary after them, when the parent gave one.
+ *
+ * After, because Flight renders a client component's props in their order,
+ * and what a server component asks for goes to PHP by the tick it is asked
+ * in. With the boundary first, the shop's catalog sent its 24 availability
+ * calls and the header's shared read in two frames, not one; with the page
+ * first, its queries are asked for before anything of the boundary is drawn.
+ *
+ * @param {string} id
+ * @param {LayoutSegment | undefined} parent
+ * @param {unknown} [children] none for the empty slot of a layout re-rendered alone
+ * @returns {{ id: string, children?: unknown, parent?: string, loading?: unknown }}
+ */
+function slot(id, parent, children) {
+  const own = children === undefined ? { id } : { id, children };
+  if (parent?.loading === undefined) return own;
+
+  const loading = parent.loading();
+  // Nothing to show is no boundary: undefined would read as none, and the
+  // slot would then show its children during an instant visit.
+  return loading === undefined ? own : { ...own, parent: parent.key, loading };
+}

package/src/csrf.d.ts

@@ -0,0 +1,11 @@
+/** The cookie PHP issues the session's CSRF token in. */
+export declare const CSRF_COOKIE: '__Host-XSRF-TOKEN';
+
+/** The header a state-changing request carries it back in. */
+export declare const CSRF_HEADER: 'X-XSRF-TOKEN';
+
+/** The current CSRF token, read from the cookie at call time, or null. */
+export declare function csrfToken(doc?: { cookie?: string } | null): string | null;
+
+/** `{ 'X-XSRF-TOKEN': token }`, or `{}` when the page has no token. */
+export declare function csrfHeaders(doc?: { cookie?: string } | null): Record<string, string>;

package/src/csrf.js

@@ -0,0 +1,49 @@
+// The CSRF token, for every request that changes something.
+//
+// tinvar-spec.md, "HTTP": "Requests from JavaScript use the CSRF cookie and
+// header." PHP issues the token as a cookie script can read --
+// `__Host-XSRF-TOKEN`, bound to the session -- and a POST carries it back in
+// `X-XSRF-TOKEN`. Without the header every action, query and bootstrap POST
+// is refused with 419.
+//
+// Read from the cookie at send time, never kept: the server issues a new
+// token when the session rotates, and one remembered from page load would be
+// the old session's.
+
+export const CSRF_COOKIE = '__Host-XSRF-TOKEN';
+export const CSRF_HEADER = 'X-XSRF-TOKEN';
+
+/**
+ * The current CSRF token, or null when the page has none.
+ *
+ * @param {{ cookie?: string } | null | undefined} [doc]
+ * @returns {string | null}
+ */
+export function csrfToken(doc = globalThis.document) {
+  const cookies = typeof doc?.cookie === 'string' ? doc.cookie : '';
+
+  for (const pair of cookies.split(';')) {
+    const at = pair.indexOf('=');
+    // The exact name: a cookie whose name merely ends in it -- or one a
+    // sibling path set under a similar name -- is not this one.
+    if (at === -1 || pair.slice(0, at).trim() !== CSRF_COOKIE) continue;
+
+    const value = pair.slice(at + 1).trim();
+    return value === '' ? null : value;
+  }
+
+  return null;
+}
+
+/**
+ * The headers a state-changing request adds: the token, or nothing when
+ * there is none -- the server refuses that request, which is the right
+ * outcome, rather than this sending an empty header it would refuse anyway.
+ *
+ * @param {{ cookie?: string } | null | undefined} [doc]
+ * @returns {Record<string, string>}
+ */
+export function csrfHeaders(doc = globalThis.document) {
+  const token = csrfToken(doc);
+  return token === null ? {} : { [CSRF_HEADER]: token };
+}

package/src/deferred-boundary.d.ts

@@ -0,0 +1,61 @@
+import type { ReactNode } from 'react';
+
+export declare const LOAD_EVENT: 'tinvar:load';
+
+export interface FragmentProviderProps {
+  /** Turns a fragment's RSC stream into elements, with the app's own client bundle. */
+  decode: (stream: ReadableStream<Uint8Array>) => Promise<ReactNode>;
+  fetch?: typeof fetch;
+  onError?: (error: unknown, element: Element) => void;
+  /** The full page load a 401 calls for; `location.assign` by default. */
+  hardNavigate?: (url: string) => void;
+  children?: ReactNode;
+}
+
+export declare function FragmentProvider(props: FragmentProviderProps): ReactNode;
+
+/** Loads a `load="manual"` boundary, or any boundary early. */
+export declare function loadDeferred(target: string | Element): void;
+
+export interface DeferredBoundaryProps {
+  token: string;
+  load?: 'visible' | 'idle' | 'interaction' | 'manual';
+  buffer?: number;
+  always?: boolean;
+  /** Boundaries on a page sharing a group load together, in one request. */
+  group?: string;
+  id?: string;
+  fallback?: ReactNode;
+  /** Shown beside the content while the boundary fetches it again. */
+  fetching?: ReactNode;
+  /** Shown once the server's render of the fragment throws; see useDeferred(). */
+  rescue?: ReactNode;
+}
+
+export declare function DeferredBoundary(props: DeferredBoundaryProps): ReactNode;
+
+export interface DeferredState {
+  /**
+   * A load is in flight, from the trigger until what it brought is on
+   * screen. The boundary's element carries `data-fetching` meanwhile.
+   */
+  fetching: boolean;
+  /**
+   * The content on screen is about to be replaced: an action is revalidating
+   * the page, or the boundary is fetching what it brought back. The
+   * boundary's element carries `data-reloading` meanwhile. See
+   * beginRevalidation().
+   */
+  reloading: boolean;
+  /** Set once the server's render threw and the `rescue` slot is up, with the digest it was logged under. */
+  rescued: { digest: string | null } | null;
+  /** Loads the boundary again. */
+  retry: () => void;
+}
+
+/**
+ * The state of the <Deferred> boundary a client component is rendered in:
+ * its fallback, its content or its `rescue` slot. A hook, because a render
+ * prop cannot cross from a server component to the client tree.
+ */
+export declare function useDeferred(): DeferredState;