@tinvar/react 0.0.0-stage → 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Carson Hopper
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

@@ -1,6 +1,170 @@
 {
   "name": "@tinvar/react",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.4.0",
+  "license": "MIT",
+  "files": [
+    "src"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./src/index.js",
+  "exports": {
+    ".": {
+      "react-server": {
+        "types": "./src/index.server.d.ts",
+        "default": "./src/index.server.js"
+      },
+      "browser": {
+        "types": "./src/index.d.ts",
+        "default": "./src/index.js"
+      },
+      "default": {
+        "types": "./src/index.combined.d.ts",
+        "default": "./src/index.js"
+      }
+    },
+    "./server": {
+      "types": "./src/server.d.ts",
+      "default": "./src/server.js"
+    },
+    "./deferred": {
+      "types": "./src/deferred.d.ts",
+      "default": "./src/deferred.jsx"
+    },
+    "./deferred-boundary": {
+      "types": "./src/deferred-boundary.d.ts",
+      "default": "./src/deferred-boundary.js"
+    },
+    "./client": {
+      "types": "./src/client.d.ts",
+      "default": "./src/client.js"
+    },
+    "./link": {
+      "types": "./src/link.d.ts",
+      "default": "./src/link.js"
+    },
+    "./route": {
+      "types": "./src/route.d.ts",
+      "default": "./src/route.js"
+    },
+    "./endpoint": {
+      "types": "./src/endpoint.d.ts",
+      "default": "./src/endpoint.js"
+    },
+    "./action": {
+      "types": "./src/action.d.ts",
+      "react-server": "./src/action-server.js",
+      "default": "./src/action.js"
+    },
+    "./form": {
+      "types": "./src/forms.d.ts",
+      "default": "./src/forms.js"
+    },
+    "./rescue": {
+      "types": "./src/rescue.d.ts",
+      "default": "./src/rescue.js"
+    },
+    "./head": {
+      "types": "./src/head.d.ts",
+      "default": "./src/head.js"
+    },
+    "./segment": {
+      "types": "./src/segment.d.ts",
+      "default": "./src/segment.js"
+    },
+    "./layout-props": {
+      "types": "./src/layout-props.d.ts",
+      "default": "./src/layout-props.js"
+    },
+    "./compose-route": {
+      "types": "./src/compose-route.d.ts",
+      "default": "./src/compose-route.js"
+    },
+    "./poll": {
+      "types": "./src/poll.d.ts",
+      "default": "./src/poll.js"
+    },
+    "./progress": {
+      "types": "./src/progress.d.ts",
+      "default": "./src/progress.js"
+    },
+    "./use-remember": {
+      "types": "./src/use-remember.d.ts",
+      "default": "./src/use-remember.js"
+    },
+    "./once": {
+      "types": "./src/once.d.ts",
+      "default": "./src/once.js"
+    },
+    "./once-slot": {
+      "types": "./src/once-slot.d.ts",
+      "default": "./src/once-slot.js"
+    },
+    "./merge": {
+      "types": "./src/merge.d.ts",
+      "default": "./src/merge.js"
+    },
+    "./merge-slot": {
+      "types": "./src/merge-slot.d.ts",
+      "default": "./src/merge-slot.js"
+    },
+    "./infinite-scroll": {
+      "types": "./src/infinite-scroll.d.ts",
+      "default": "./src/infinite-scroll.js"
+    },
+    "./live": {
+      "types": "./src/live.d.ts",
+      "default": "./src/live.js"
+    },
+    "./channel": {
+      "types": "./src/channel.d.ts",
+      "default": "./src/channel.js"
+    },
+    "./use-channel": {
+      "types": "./src/use-channel.d.ts",
+      "default": "./src/use-channel.js"
+    },
+    "./inbox": {
+      "types": "./src/inbox.d.ts",
+      "default": "./src/inbox.js"
+    },
+    "./use-inbox": {
+      "types": "./src/use-inbox.d.ts",
+      "default": "./src/use-inbox.js"
+    },
+    "./inbox-view": {
+      "types": "./src/inbox-view.d.ts",
+      "default": "./src/inbox-view.js"
+    },
+    "./upload": {
+      "types": "./src/upload.d.ts",
+      "default": "./src/upload.js"
+    },
+    "./transfer": {
+      "types": "./src/transfer.d.ts",
+      "default": "./src/transfer.js"
+    },
+    "./optional": {
+      "types": "./src/optional.d.ts",
+      "default": "./src/optional.js"
+    },
+    "./telemetry": {
+      "types": "./src/telemetry.d.ts",
+      "default": "./src/telemetry.js"
+    },
+    "./when-mounted": {
+      "types": "./src/when-mounted.d.ts",
+      "default": "./src/when-mounted.js"
+    },
+    "./testing": {
+      "types": "./src/testing.d.ts",
+      "default": "./src/testing.js"
+    }
+  },
+  "peerDependencies": {
+    "react": "^19.0.0"
+  },
+  "types": "./src/index.d.ts"
+}

package/src/action-server.js

@@ -0,0 +1,41 @@
+// Action references as a server component sees them: plain data.
+//
+// The spec passes a reference from a server component to a client one --
+// `<RackGrid onMove={moveUnit} />` -- and Flight serializes nothing it cannot
+// rebuild on the other side. A function is refused ("Functions cannot be
+// passed directly to Client Components"), and the renderer never decodes
+// server-function references, by design: "Actions go to PHP." So under the
+// `react-server` condition a reference is `{ action, url }`, which crosses as
+// it is. Everything on the client that takes an action reads that shape, and
+// action() there turns it back into something callable.
+//
+// A server component never calls one: the renderer does not post to PHP.
+
+export const ACTION_PREFIX = '/_action/';
+
+/**
+ * @param {string | { readonly action: string }} target
+ * @returns {string}
+ */
+export function actionName(target) {
+  const name = typeof target === 'string' ? target : target?.action;
+  if (typeof name !== 'string' || name === '') {
+    throw new TypeError('[tinvar] An action is its name, or a reference from @actions/*.');
+  }
+  return name;
+}
+
+/** @param {string | { readonly action: string }} target */
+export function actionUrl(target) {
+  return ACTION_PREFIX + encodeURIComponent(actionName(target));
+}
+
+/** A server component's reference to a PHP action: data to hand a client component. */
+export function action(/** @type {string | { readonly action: string }} */ target) {
+  const name = actionName(target);
+  return Object.freeze({ action: name, url: actionUrl(name) });
+}
+
+export function isActionReference() {
+  return false;
+}

package/src/action.d.ts

@@ -0,0 +1,68 @@
+/** Action references: what codegen's `@actions/*` modules export. */
+
+export declare const ACTION_PREFIX: '/_action/';
+
+/** What the action endpoint answers with; codegen emits the same shape as `ActionResult`. */
+export interface ActionResponse {
+  value: unknown;
+  flash: Record<string, unknown>;
+  revalidated: string[];
+  payloads: Record<string, string>;
+  /** Where the action redirected, when it did. */
+  redirect?: string;
+}
+
+/** An action, as anything that takes one accepts it: its name, or a reference. */
+export type ActionTarget = string | { readonly action: string };
+
+export interface CallOptions {
+  signal?: AbortSignal;
+  headers?: Record<string, string>;
+}
+
+/**
+ * A reference to one PHP action. Call it to post; give it to `<Form action>`,
+ * `useForm().submit()` or `useHttp()` to have the page follow the answer.
+ *
+ * Under the `react-server` condition it is the plain `{ action, url }`, which
+ * a server component can hand a client component.
+ */
+export interface ActionReference<Args extends object = Record<string, unknown>, Result = ActionResponse> {
+  (args: Args, options?: CallOptions): Promise<Result>;
+  readonly action: string;
+  readonly url: string;
+  /**
+   * The same action, patching the nearest `<OptimisticState>` while it runs,
+   * when submitted through `<Form>` or useForm. The patch returns the keys it
+   * changes, and is replayed as other requests settle, so it must be pure.
+   */
+  optimistic<S extends Record<string, unknown> = Record<string, any>>(
+    patch: (state: S) => Partial<S>,
+  ): ActionReference<Args, Result>;
+}
+
+/** A reference to the PHP action named, or to the one a plain `{ action }` names. */
+export declare function action<Args extends object = Record<string, unknown>, Result = ActionResponse>(
+  target: ActionTarget,
+): ActionReference<Args, Result>;
+
+/** The action's wire name, from its name or a reference. */
+export declare function actionName(target: ActionTarget): string;
+
+/** Where the action is posted: `/_action/{name}`. */
+export declare function actionUrl(target: ActionTarget): string;
+
+export declare function isActionReference(value: unknown): value is ActionReference;
+
+/** The optimistic patch a reference carries, or null. */
+export declare function optimisticPatch(
+  target: ActionTarget,
+): ((state: Record<string, any>) => Record<string, unknown>) | null;
+
+/** Why a direct call did not succeed: which channel, the status, and any field errors. */
+export declare class ActionError extends Error {
+  readonly kind: 'validation' | 'http' | 'expired' | 'network' | 'cancelled';
+  /** 0 when there was no answer. */
+  readonly status: number;
+  readonly errors: Record<string, string[]>;
+}

package/src/action.js

@@ -0,0 +1,167 @@
+// Action references: what codegen's `@actions/*` modules export.
+//
+// tinvar-spec.md, "Actions and revalidation": "codegen emits typed
+// TypeScript stubs that behave like Next.js server actions":
+//
+//   import { moveUnit } from '@actions/RackActions';
+//   <form action={moveUnit}>...</form>
+//   <RackGrid onMove={moveUnit} />
+//
+// So a reference is three things at once: a function that posts to its PHP
+// action, a name that <Form>, useForm and useHttp read to know where to post,
+// and -- with `.optimistic(patch)` -- a variant that patches client state
+// while it runs (optimistic.js, ADR 0016). Anything that takes an action
+// takes a reference or the action's name as a string; actionName() reads
+// either.
+//
+// Under the `react-server` condition, action-server.js stands in: a server
+// component can only hand a client component what Flight can serialize, and
+// a function is not that.
+
+import { send } from './transport.js';
+
+export const ACTION_PREFIX = '/_action/';
+
+/** Marks a reference, so a function that merely has an `action` property is not mistaken for one. */
+const REFERENCE = Symbol.for('tinvar.action');
+
+/**
+ * What an action is given as: its name, a reference, or the plain
+ * `{ action }` a server component hands across.
+ *
+ * @typedef {string | { readonly action: string }} ActionTarget
+ */
+
+/**
+ * The action's wire name.
+ *
+ * @param {ActionTarget} target
+ * @returns {string}
+ */
+export function actionName(target) {
+  const name = typeof target === 'string' ? target : target?.action;
+  if (typeof name !== 'string' || name === '') {
+    throw new TypeError('[tinvar] An action is its name, or a reference from @actions/*.');
+  }
+  return name;
+}
+
+/**
+ * Where an action is posted. Encoded, though generated names never need it:
+ * a name taken from anywhere else stays one path segment.
+ *
+ * @param {ActionTarget} target
+ */
+export function actionUrl(target) {
+  return ACTION_PREFIX + encodeURIComponent(actionName(target));
+}
+
+/** @param {unknown} value */
+export function isActionReference(value) {
+  return typeof value === 'function' && /** @type {any} */ (value)[REFERENCE] === true;
+}
+
+/**
+ * The optimistic patch a reference carries, or null.
+ *
+ * @param {ActionTarget} target
+ * @returns {((state: Record<string, any>) => Record<string, unknown>) | null}
+ */
+export function optimisticPatch(target) {
+  return isActionReference(target) ? /** @type {any} */ (target.optimisticPatch ?? null) : null;
+}
+
+/**
+ * A reference to a PHP action.
+ *
+ * @param {ActionTarget} target
+ */
+export function action(target) {
+  return reference(actionName(target), null);
+}
+
+/**
+ * @param {string} name
+ * @param {((state: Record<string, any>) => Record<string, unknown>) | null} patch
+ */
+function reference(name, patch) {
+  /**
+   * Called directly, it posts and resolves with what the endpoint answered.
+   * It does not move the page -- no redirect followed, no payload mounted --
+   * because nothing here knows the page: <Form>, useForm and useHttp do,
+   * and are how a page follows an action. A failure rejects with an
+   * ActionError naming which of the three channels it came by.
+   *
+   * @param {Record<string, unknown>} [args]
+   * @param {{ signal?: AbortSignal, headers?: Record<string, string> }} [options]
+   */
+  const call = async (args = {}, options = {}) => {
+    const outcome = await send({
+      url: ACTION_PREFIX + encodeURIComponent(name),
+      data: args,
+      headers: options.headers,
+      signal: options.signal,
+    });
+
+    if (outcome.type === 'success')
+      return outcome.body ?? { value: null, flash: {}, revalidated: [], payloads: {} };
+    if (outcome.type === 'redirect' || outcome.type === 'location') {
+      return { value: null, flash: {}, revalidated: [], payloads: {}, redirect: outcome.location };
+    }
+    throw new ActionError(name, outcome);
+  };
+
+  Object.defineProperties(call, {
+    action: { value: name, enumerable: true },
+    url: { value: ACTION_PREFIX + encodeURIComponent(name), enumerable: true },
+    optimisticPatch: { value: patch },
+    [REFERENCE]: { value: true },
+    optimistic: {
+      /**
+       * The same action, patching the nearest <OptimisticState> while it
+       * runs -- through <Form>, useForm or useHttp, which know where that
+       * is. The patch takes the current state and returns the keys it
+       * changes, and is replayed as other requests settle, so it must be
+       * pure.
+       *
+       * @param {(state: Record<string, any>) => Record<string, unknown>} next
+       */
+      value: (next) => {
+        if (typeof next !== 'function') {
+          throw new TypeError('[tinvar] optimistic() takes a function from the current state to a patch.');
+        }
+        return reference(name, next);
+      },
+    },
+  });
+
+  return Object.freeze(call);
+}
+
+/**
+ * Why a direct call did not succeed: field errors (422), another status, or
+ * no answer at all.
+ */
+export class ActionError extends Error {
+  /**
+   * @param {string} name
+   * @param {import('./transport.js').Outcome} outcome
+   */
+  constructor(name, outcome) {
+    super(
+      outcome.type === 'validation'
+        ? `The action ${name} was refused: the input is invalid.`
+        : outcome.type === 'network'
+          ? `The action ${name} could not be reached.`
+          : `The action ${name} failed${'status' in outcome ? ` with ${outcome.status}` : ''}.`,
+    );
+    this.name = 'ActionError';
+    /** 'validation', 'http', 'expired', 'network' or 'cancelled'. */
+    this.kind = outcome.type;
+    /** 0 when there was no answer. */
+    this.status = 'status' in outcome ? outcome.status : outcome.type === 'expired' ? 419 : 0;
+    /** @type {Record<string, string[]>} */
+    this.errors = outcome.type === 'validation' ? outcome.errors : {};
+    this.outcome = outcome;
+  }
+}

package/src/bootstrap.js

@@ -0,0 +1,153 @@
+// Trading a statically built page's placeholders for fragment tokens.
+//
+// tinvar-spec.md: "Fragments inside static pages get their tokens from a
+// small per-visitor bootstrap request, never from the build." A page built
+// by `tinvar build:static` is one file for every visitor, so its <Deferred>
+// boundaries carry no token -- a token minted at build time would have no
+// session to bind to, and would be everyone's. Each carries a placeholder
+// instead: `b1.` and base64url JSON of the page's route, the params it was
+// built for and the boundary's id. Nothing in it is signed or secret.
+//
+// When a boundary first loads, this asks POST /_bootstrap for the page's
+// tokens, minted for the visitor's own session from what the build recorded
+// -- never from the placeholder, which only says which page this is -- and
+// the boundary loads with its token like any other.
+
+import { csrfHeaders } from './csrf.js';
+
+export const BOOTSTRAP_PATH = '/_bootstrap';
+
+const PLACEHOLDER = /^b1\.([A-Za-z0-9_-]+)$/;
+
+/**
+ * Whether a boundary's token is a static page's placeholder.
+ *
+ * @param {string | null | undefined} token
+ */
+export function isPlaceholder(token) {
+  return typeof token === 'string' && PLACEHOLDER.test(token);
+}
+
+/**
+ * What a placeholder names, or null for anything that is not one.
+ *
+ * @param {string} token
+ * @returns {{ route: string, params: Record<string, string>, id: string } | null}
+ */
+export function placeholderTarget(token) {
+  const match = PLACEHOLDER.exec(token);
+  if (!match) return null;
+  try {
+    const json = atob(match[1].replace(/-/g, '+').replace(/_/g, '/'));
+    const { r, p, b } = JSON.parse(json);
+    if (
+      typeof r !== 'string' ||
+      typeof b !== 'string' ||
+      typeof p !== 'object' ||
+      p === null ||
+      Array.isArray(p)
+    ) {
+      return null;
+    }
+    return { route: r, params: p, id: b };
+  } catch {
+    return null;
+  }
+}
+
+export class BootstrapError extends Error {
+  /** @param {string} message @param {number} status */
+  constructor(message, status) {
+    super(message);
+    this.name = 'BootstrapError';
+    this.status = status;
+  }
+}
+
+/**
+ * The page's requests in flight, per fetch implementation, by page: the
+ * boundaries one trigger loads together ask once between them. Dropped once
+ * settled, so a boundary loading an hour later asks again rather than taking
+ * tokens that have since expired.
+ *
+ * @type {WeakMap<object, Map<string, Promise<Record<string, string>>>>}
+ */
+const inFlight = new WeakMap();
+
+/**
+ * The token for one placeholder, from /_bootstrap.
+ *
+ * @param {string} placeholder
+ * @param {typeof fetch} fetchImpl
+ * @returns {Promise<string>}
+ */
+export async function bootstrapToken(placeholder, fetchImpl) {
+  const target = placeholderTarget(placeholder);
+  if (!target) {
+    throw new BootstrapError('Not a static page placeholder.', 404);
+  }
+
+  const key = JSON.stringify([target.route, target.params]);
+  let pages = inFlight.get(fetchImpl);
+  if (!pages) inFlight.set(fetchImpl, (pages = new Map()));
+
+  let pending = pages.get(key);
+  if (!pending) {
+    pending = requestTokens(target.route, target.params, fetchImpl).finally(() => pages.delete(key));
+    pages.set(key, pending);
+  }
+
+  const token = (await pending)[target.id];
+  if (typeof token !== 'string' || token === '') {
+    // The server does not know this page as built -- a page left over from
+    // an earlier build -- so nothing will make this boundary load but a
+    // fresh copy of the page.
+    throw new BootstrapError('This page is out of date; reload it.', 404);
+  }
+  return token;
+}
+
+/**
+ * POST /_bootstrap for one page.
+ *
+ * A visitor arriving at a static page may have no session yet, and so no
+ * CSRF cookie: the first request answers 419 and sets both, and is made once
+ * more with the token it set. The server answers 409 to a request with no
+ * session to mint for, which the same retry covers.
+ *
+ * @param {string} route
+ * @param {Record<string, string>} params
+ * @param {typeof fetch} fetchImpl
+ * @returns {Promise<Record<string, string>>}
+ */
+async function requestTokens(route, params, fetchImpl) {
+  const send = () =>
+    fetchImpl(BOOTSTRAP_PATH, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json', accept: 'application/json', ...csrfHeaders() },
+      body: JSON.stringify({ route, params }),
+      credentials: 'same-origin',
+      // As a fragment's own request: a redirect off this origin could hand
+      // back tokens of someone else's choosing.
+      mode: 'same-origin',
+      redirect: 'error',
+      cache: 'no-store',
+    });
+
+  let response = await send();
+  if (response.status === 419 || response.status === 409) response = await send();
+
+  if (!response.ok) {
+    throw new BootstrapError(`Bootstrap failed with ${response.status}.`, response.status);
+  }
+
+  const body = await response.json().catch(() => null);
+  const tokens = body?.tokens;
+  // A page the server built nothing for is answered with none, which PHP
+  // writes as an empty list.
+  if (Array.isArray(tokens) && tokens.length === 0) return {};
+  if (typeof tokens !== 'object' || tokens === null || Array.isArray(tokens)) {
+    throw new BootstrapError('Bootstrap answered without tokens.', response.status);
+  }
+  return tokens;
+}

package/src/channel.d.ts

@@ -0,0 +1,46 @@
+/** Subscribing to the application's #[Channel]s (ADR 0069). */
+
+export declare const CHANNEL_PATH: '/_channel/';
+
+/** What one channel takes and carries, as codegen describes it. */
+export interface ChannelShape {
+  params: object;
+  message: unknown;
+}
+
+/** A subscription the server refused, or that could not be asked for. */
+export declare class ChannelError extends Error {
+  readonly channel: string;
+  /** 0 when the request never got an answer. */
+  readonly status: number;
+}
+
+export interface ListenOptions {
+  fetch?: typeof fetch;
+  document?: Document;
+  /** A refusal -- 401, 403, 404 -- or a request that never got an answer. Nothing is retried. */
+  onError?: (error: ChannelError) => void;
+  /** The stream was down for a while: messages may have been missed, and the hub keeps none to replay. */
+  onGap?: () => void;
+}
+
+/** Subscribes to one channel until the returned function is called. */
+export declare function listen(
+  name: string,
+  params: Record<string, string | number | boolean>,
+  onMessage: (message: unknown) => void,
+  options?: ListenOptions,
+): () => void;
+
+export interface Channels<M extends { [N in keyof M]: ChannelShape }> {
+  /** Subscribes to a channel by name until the returned function is called. */
+  listen<N extends keyof M & string>(
+    name: N,
+    params: M[N]['params'],
+    onMessage: (message: M[N]['message']) => void,
+    options?: ListenOptions,
+  ): () => void;
+}
+
+/** Builds the typed `channel` codegen exports. */
+export declare function channels<M extends { [N in keyof M]: ChannelShape }>(): Channels<M>;