@tinvar/react 0.0.0-stage → 0.4.1

package/src/inbox.js

@@ -0,0 +1,293 @@
+// A signed-in user's in-app inbox, by the #[Inbox] names codegen writes
+// (ADR 0155).
+//
+// `inbox.customer.page()` POSTs to /_inbox/customer for the newest entries
+// and the unread count; `markRead(ids)` and `markAllRead()` to
+// /_inbox/customer/read; `preferences()` and `choose(...)` to
+// /_inbox/customer/preferences. Each carries the session's CSRF token,
+// read from the cookie as the request is sent, to a path on this origin
+// and nowhere else. Whose inbox is never sent: the server reads the
+// signed-in user, in the tenant the inbox's own declarations resolve.
+//
+// `listen(onUpdate)` hears the feed change as it happens -- an entry
+// arriving, another tab marking some read -- on the inbox's personal
+// channel, `inbox.{name}`, through the channel runtime: its token is bound
+// to the session, the user and their auth epoch, and let in again on
+// every trade. Without a hub nothing is heard, and a page polls nothing:
+// the next page() is the truth.
+//
+// What the server answers is checked before anything draws it (review of
+// 2026-11-03): a page, a count, the kinds of notification and every update
+// the channel brings are held to their shapes, and an answer that is not
+// one is an InboxError, an update that is not one unheard. An entry's link
+// is kept only where it is a path on this site (sitePath()), so neither the
+// bell nor an app's onOpen is handed somewhere else to go.
+//
+// No React: the hook is in use-inbox.js, the component in inbox-view.js.
+
+import { CSRF_HEADER, csrfToken } from './csrf.js';
+import { listen as listenChannel } from './channel.js';
+
+export const INBOX_PATH = '/_inbox/';
+
+/** An inbox name, as #[Inbox] declares them. */
+const NAME_SHAPE = /^[a-z][a-z0-9_]{0,31}$/;
+
+/**
+ * $url where it is a path on this site, else null: one `/`, not `//` or
+ * `/\\` -- which a browser reads as another host -- and no control
+ * character, which a browser strips first (`/\t/host` is `//host`).
+ *
+ * @param {unknown} url
+ * @returns {string | null}
+ */
+export function sitePath(url) {
+  if (typeof url !== 'string' || !url.startsWith('/') || url.length > 2048) return null;
+  if (url[1] === '/' || url.includes('\\') || /[\u0000-\u001f\u007f]/.test(url)) return null;
+  return url;
+}
+
+/** @param {unknown} v */
+const isMap = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+/** @param {unknown} v */
+const isCount = (v) => typeof v === 'number' && Number.isInteger(v) && v >= 0;
+/** @param {unknown} v */
+const isStrings = (v) => Array.isArray(v) && v.every((s) => typeof s === 'string');
+
+/**
+ * An entry as the server writes one, its link kept only on this site; null
+ * for anything else.
+ *
+ * @param {unknown} value
+ */
+export function readEntry(value) {
+  if (!isMap(value)) return null;
+  const e = /** @type {Record<string, unknown>} */ (value);
+  if (
+    typeof e.id !== 'string' ||
+    e.id === '' ||
+    typeof e.type !== 'string' ||
+    typeof e.title !== 'string' ||
+    typeof e.body !== 'string' ||
+    (e.url !== null && typeof e.url !== 'string') ||
+    typeof e.createdAt !== 'string' ||
+    (e.readAt !== null && typeof e.readAt !== 'string')
+  ) {
+    return null;
+  }
+  return {
+    id: e.id,
+    type: e.type,
+    title: e.title,
+    body: e.body,
+    url: sitePath(e.url),
+    createdAt: e.createdAt,
+    readAt: e.readAt,
+  };
+}
+
+/** @param {unknown} value */
+function readPage(value) {
+  if (!isMap(value)) return null;
+  const p = /** @type {Record<string, unknown>} */ (value);
+  if (!Array.isArray(p.entries) || !isCount(p.unread) || (p.next !== null && typeof p.next !== 'string')) {
+    return null;
+  }
+  const entries = p.entries.map(readEntry);
+  if (entries.some((e) => e === null)) return null;
+  return {
+    entries: /** @type {NonNullable<ReturnType<typeof readEntry>>[]} */ (entries),
+    unread: p.unread,
+    next: p.next,
+  };
+}
+
+/** @param {unknown} value */
+function readCount(value) {
+  if (!isMap(value)) return null;
+  const c = /** @type {Record<string, unknown>} */ (value);
+  return isCount(c.unread) ? { unread: c.unread } : null;
+}
+
+/** @param {unknown} value */
+function readPreferences(value) {
+  if (!isMap(value)) return null;
+  const p = /** @type {Record<string, unknown>} */ (value);
+  if (!Array.isArray(p.types)) return null;
+  const types = p.types.map((/** @type {unknown} */ t) => {
+    if (!isMap(t)) return null;
+    const k = /** @type {Record<string, unknown>} */ (t);
+    return typeof k.type === 'string' &&
+      typeof k.label === 'string' &&
+      typeof k.description === 'string' &&
+      isStrings(k.channels) &&
+      isStrings(k.enabled)
+      ? { type: k.type, label: k.label, description: k.description, channels: k.channels, enabled: k.enabled }
+      : null;
+  });
+  return types.some((t) => t === null) ? null : { types };
+}
+
+/**
+ * An update as the inbox's channel says one; null for anything else.
+ *
+ * @param {unknown} value
+ */
+export function readUpdate(value) {
+  if (!isMap(value)) return null;
+  const u = /** @type {Record<string, unknown>} */ (value);
+  const read = u.read ?? [];
+  if (!isCount(u.unread) || !isStrings(read) || (u.allRead !== undefined && typeof u.allRead !== 'boolean')) {
+    return null;
+  }
+  const entry = u.entry === null || u.entry === undefined ? null : readEntry(u.entry);
+  if (entry === null && u.entry !== null && u.entry !== undefined) return null;
+  return { unread: u.unread, entry, read, allRead: u.allRead === true };
+}
+
+/** A call the server refused, or that never got an answer (status 0). */
+export class InboxError extends Error {
+  /**
+   * @param {string} name
+   * @param {number} status
+   * @param {unknown} [body]
+   */
+  constructor(name, status, body) {
+    const error =
+      body !== null &&
+      typeof body === 'object' &&
+      'error' in body &&
+      body.error !== null &&
+      typeof body.error === 'object'
+        ? /** @type {{ message?: unknown }} */ (body.error)
+        : {};
+    super(
+      typeof error.message === 'string'
+        ? error.message
+        : `[tinvar] The inbox '${name}' did not answer (${status}).`,
+    );
+    this.name = 'InboxError';
+    this.inbox = name;
+    this.status = status;
+    this.body = body;
+  }
+}
+
+/**
+ * The client for one inbox.
+ *
+ * @param {string} name
+ * @param {{ fetch?: typeof fetch, document?: { cookie?: string } | null, listen?: typeof listenChannel }} [options]
+ */
+export function inboxClient(name, options = {}) {
+  if (!NAME_SHAPE.test(name)) {
+    throw new Error(
+      `[tinvar] '${name}' is not an inbox name: a lowercase identifier, as #[Inbox] declares it.`,
+    );
+  }
+  const channel = `inbox.${name}`;
+  const listenImpl = options.listen ?? listenChannel;
+
+  /**
+   * @param {string} path
+   * @param {unknown} body
+   */
+  /**
+   * @template T
+   * @param {string} path
+   * @param {unknown} body
+   * @param {(value: unknown) => T | null} read
+   * @param {string} what
+   * @returns {Promise<T>}
+   */
+  const call = async (path, body, read, what) => {
+    const fetchImpl = options.fetch ?? globalThis.fetch?.bind(globalThis);
+    if (!fetchImpl) throw new InboxError(name, 0);
+    const token = csrfToken(options.document ?? globalThis.document);
+    let response;
+    try {
+      response = await fetchImpl(INBOX_PATH + name + path, {
+        method: 'POST',
+        headers: {
+          'content-type': 'application/json',
+          accept: 'application/json',
+          ...(token === null ? {} : { [CSRF_HEADER]: token }),
+        },
+        body: JSON.stringify(body),
+        credentials: 'same-origin',
+        mode: 'same-origin',
+        redirect: 'error',
+        cache: 'no-store',
+      });
+    } catch {
+      throw new InboxError(name, 0);
+    }
+    let parsed = null;
+    try {
+      parsed = await response.json();
+    } catch {
+      parsed = null;
+    }
+    if (!response.ok) throw new InboxError(name, response.status, parsed);
+    const held = read(parsed);
+    if (held === null) {
+      throw new InboxError(name, response.status, {
+        error: { message: `[tinvar] The inbox '${name}' answered with something that is not ${what}.` },
+      });
+    }
+    return held;
+  };
+
+  return {
+    name,
+    channel,
+    /** @param {{ before?: string | null, limit?: number }} [page] */
+    page: (page = {}) =>
+      call(
+        '',
+        {
+          ...(page.before ? { before: page.before } : {}),
+          ...(page.limit === undefined ? {} : { limit: page.limit }),
+        },
+        readPage,
+        'a page of entries',
+      ),
+    /** @param {string[]} ids */
+    markRead: (ids) => call('/read', { ids }, readCount, 'an unread count'),
+    markAllRead: () => call('/read', { all: true }, readCount, 'an unread count'),
+    preferences: () => call('/preferences', {}, readPreferences, 'the kinds of notification'),
+    /** @param {{ type: string, channel: string, enabled: boolean }[]} choices */
+    choose: (choices) =>
+      call('/preferences', { choose: choices }, readPreferences, 'the kinds of notification'),
+    /**
+     * @param {(update: unknown) => void} onUpdate
+     * @param {{ onError?: (error: unknown) => void, onGap?: () => void }} [listenOptions]
+     */
+    listen: (onUpdate, listenOptions = {}) =>
+      listenImpl(
+        channel,
+        {},
+        (/** @type {unknown} */ raw) => {
+          const update = readUpdate(raw);
+          if (update !== null) onUpdate(update);
+        },
+        {
+          ...(options.fetch ? { fetch: options.fetch } : {}),
+          ...listenOptions,
+        },
+      ),
+  };
+}
+
+/**
+ * The typed `inbox` codegen exports: a client for each #[Inbox], by name.
+ *
+ * @param {string[]} names
+ * @param {{ fetch?: typeof fetch, document?: { cookie?: string } | null }} [options]
+ */
+export function inboxes(names, options = {}) {
+  /** @type {Record<string, ReturnType<typeof inboxClient>>} */
+  const clients = {};
+  for (const name of names) clients[name] = inboxClient(name, options);
+  return clients;
+}

package/src/index.combined.d.ts

@@ -0,0 +1,31 @@
+// The root as a program that typechecks server and client code together
+// sees it: both entries' exports, for whichever kind of file imports them.
+// See index.js for why there are three.
+//
+// TypeScript applies one set of conditions to a whole program, so a project
+// whose one tsconfig covers its server components and its client components
+// -- the shop's -- cannot have the root resolve as each file's environment
+// will. It gets this: what a server component imports from the root, and
+// what a client component does, each typed as it is. The bundler still
+// holds the line between them: a client file importing a server-only name
+// from the root fails the client build, which resolves the root to
+// index.js, where the name does not exist.
+
+export * from './client';
+export * from './server';
+export { Deferred, type DeferredProps } from './deferred';
+
+/**
+ * `query` is two functions: a server component's, which calls a PHP query
+ * over the render's socket (`@tinvar/react/server`), and the client's, which
+ * names one for useHttp (`@tinvar/react/form`). The root is each one under
+ * its own condition, but a program checking both kinds of file together
+ * cannot tell which a file means -- typed as either, the other's callers
+ * would check against the wrong function. So it is neither here: import it
+ * from the subpath that says which.
+ */
+export interface AmbiguousQuery {
+  readonly 'import query() from @tinvar/react/server or @tinvar/react/form': never;
+}
+
+export declare const query: AmbiguousQuery;

package/src/index.d.ts

@@ -0,0 +1,5 @@
+// The root as the browser and the SSR environment resolve it, and as a
+// program typechecking client code alone sees it, under `browser`. The RSC
+// environment's, under `react-server`, is index.server.d.ts; a program
+// checking both kinds of code together sees index.combined.d.ts.
+export * from './client';

package/src/index.js

@@ -0,0 +1,29 @@
+// @tinvar/react -- the package root, resolved by environment.
+//
+// The root used to re-export the render-context helpers, which import
+// node:async_hooks, beside the fragment client and the triggers, which want
+// a DOM; so it could load in neither environment, and it never exported
+// <Deferred>. It is now two entries, chosen by the conditions package.json
+// lists:
+//
+//   react-server  index.server.js: what a server component calls -- query(),
+//                 nonce(), the render context -- and <Deferred>.
+//   browser       this file: what @tinvar/react/client exports, for the
+//   default       browser and for the SSR environment, which renders client
+//                 components on Node.
+//
+// The types follow the same conditions, with one case more. TypeScript
+// applies one set of conditions to a whole program and adds neither of
+// these itself, so a program of server code alone says `react-server` in
+// its customConditions and sees index.server.d.ts; one of client code alone
+// says `browser` and sees index.d.ts; and one that checks both together --
+// an app's single tsconfig -- says neither and sees index.combined.d.ts:
+// both entries' names, each typed as it is. The bundler, which does resolve
+// per environment, is what refuses a server-only name in a client file.
+// `query` is the one name both entries export, as two functions, so the
+// combined types give neither: there it comes from `/server` or `/form`.
+//
+// The subpath entries stay, and remain the precise way in: a client
+// component such as <Link> comes from its own subpath in either environment.
+
+export * from './client.js';

package/src/index.server.d.ts

@@ -0,0 +1,4 @@
+// The root as the RSC environment resolves it, under `react-server`, and as
+// a program typechecking server code alone sees it.
+export * from './server';
+export { Deferred, type DeferredProps } from './deferred';

package/src/index.server.js

@@ -0,0 +1,8 @@
+// @tinvar/react under the `react-server` condition: the RSC environment's
+// root. See index.js for the other environments and why there are two.
+//
+// <Deferred> renders a client boundary, which the RSC environment turns into
+// a client reference, so nothing of the browser's is loaded here.
+
+export * from './server.js';
+export { Deferred } from './deferred.jsx';

package/src/infinite-scroll.d.ts

@@ -0,0 +1,108 @@
+import type { Context, ReactNode } from 'react';
+
+/**
+ * What a Scroll page says about itself, without its items. A cursor page's
+ * `cursor` is the one it was read at (null for the first), its `previous`
+ * and `next` are cursors, and its `page` is 0 until placed (ADR 0120).
+ */
+export interface ScrollMeta {
+  id: string;
+  page: number;
+  cursor?: string | null;
+  previous: number | string | null;
+  next: number | string | null;
+  total: number | null;
+  perPage: number;
+  pageName: string;
+  reset: boolean;
+}
+
+/** The nearest <InfiniteScroll>'s state, and its two loads. */
+export interface InfiniteScrollState {
+  /** The list's dot path. */
+  id: string;
+  reverse: boolean;
+  /** Which edge is loading, if one is. */
+  loading: 'next' | 'previous' | null;
+  /** Whether pages load only when asked: `manual`, or `manualAfter` reached. */
+  manual: boolean;
+  hasNext: boolean;
+  hasPrevious: boolean;
+  /**
+   * The first and last page shown: page numbers, or for a list read by
+   * cursor, places counted from the page that arrived whole (0).
+   */
+  first: number;
+  last: number;
+  total: number | null;
+  perPage: number;
+  /** Resolve with whether a page was merged in. */
+  loadNext(): Promise<boolean>;
+  loadPrevious(): Promise<boolean>;
+  /** How many times the list has started again: a reset, a whole page, a cursor page that could not be placed. */
+  epoch: number;
+  /** Where a cursor page read at this cursor goes, once placed. */
+  place(cursor: string | null): number | undefined;
+}
+
+export declare const InfiniteScrollContext: Context<InfiniteScrollState | null>;
+
+/** The nearest <InfiniteScroll>'s state, for a client component: a "Load more", a count. */
+export declare function useInfiniteScroll(): InfiniteScrollState;
+
+/** The client half of <InfiniteScroll>; rendered by it, not by hand. */
+export declare function InfiniteScrollRoot(props: {
+  field: ScrollMeta;
+  buffer?: number;
+  manual?: boolean;
+  manualAfter?: number;
+  reverse?: boolean;
+  preserveUrl?: boolean;
+  previous?: ReactNode;
+  next?: ReactNode;
+  children?: ReactNode;
+}): ReactNode;
+
+export declare function extendRange<E extends { page: number }>(
+  range: { first: E; last: E },
+  edge: E,
+): { first: E; last: E };
+export declare function scrollContainerOf(element: Element | null): Element | null;
+export declare function itemsOf(
+  root: Element,
+  id: string,
+): { page: number; element: Element; key: string | null; index: number; cursor: string | null }[];
+
+/**
+ * Where a cursor page read at `cursor` goes among those shown: where it is,
+ * after the last (read at its `next`), before the first (at its
+ * `previous`); undefined for one none of them leads to.
+ */
+export declare function placeOf(
+  range: {
+    first: { page: number; previous: number | string | null };
+    last: { page: number; next: number | string | null };
+    places: ReadonlyMap<string, number>;
+  },
+  cursor: string | null,
+): number | undefined;
+
+/** How many pages either side of the reader's are loaded again when they come back to it. */
+export declare const RESTORE_PAGES: number;
+
+/** Where the reader is in a list, or null when no item is in view. */
+export declare function anchorOf(
+  root: Element,
+  id: string,
+  container: Element | null,
+  range: { first: { page: number }; last: { page: number } },
+  base?: ((visible: { page: number; cursor: string | null }) => number) | null,
+): import('./router.js').ScrollAnchor | null;
+
+/** Scrolls the list so the anchor's item is where it was; whether the item is there. */
+export declare function scrollToAnchor(
+  root: Element,
+  id: string,
+  container: Element | null,
+  anchor: import('./router.js').ScrollAnchor,
+): boolean;