@tinvar/react 0.0.0-stage → 0.4.0

package/src/form.js

@@ -0,0 +1,615 @@
+'use client';
+
+// <Form>: a real <form> that posts to an action, and does it better with
+// script than without.
+//
+// tinvar-spec.md, "Forms and mutations":
+//
+//   "<Form action={moveUnit}> with uncontrolled `name` inputs, nested names
+//   (`report[tags][]`), `transform`, and slot props: `errors`, `processing`,
+//   `progress`, `wasSuccessful`, `recentlySuccessful`, `isDirty`, `reset`,
+//   `submit`, `cancel`, `setError`, `clearErrors`. Keep Inertia's split:
+//   top-level props control the submission, `options` controls the visit
+//   after it."
+//
+// It renders <form method="post" action="/_action/{name}"> with the CSRF
+// token in a hidden field, so before JavaScript loads -- or without it -- a
+// submit is an ordinary post, which the endpoint answers with a page: back
+// to the form with its errors flashed (FlashStore), or on to wherever the
+// action redirected. Once hydrated, a submit is a fetch instead, and the
+// answer lands in place: errors on their fields, the page re-rendered, the
+// redirect followed as a client visit.
+//
+// <FormSession> carries what forms need from the server, per request: the
+// token for the hidden field, and what a post made without script flashed
+// for this page. The app renders it once, around the page, from its render
+// entry; the props are plain data, so it can be given them by a server
+// component.
+
+import {
+  createContext,
+  createElement,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from 'react';
+import { actionName, actionUrl } from './action.js';
+import { formToObject, getPath, TOKEN_FIELD } from './form-data.js';
+import { useRouter } from './link.js';
+import { useOptimisticStore } from './optimistic.js';
+import { usePrecognition } from './precognition.js';
+import { assignLocation } from './router-hooks.js';
+import { submitAction } from './submit.js';
+import { normalizeErrors } from './transport.js';
+
+/** How long `recentlySuccessful` stays true after a success, in ms -- Inertia's figure. */
+export const RECENTLY_SUCCESSFUL_MS = 2000;
+
+const SessionContext = createContext(/** @type {Session | null} */ (null));
+
+/** @internal What useFormContext() reads: a <Form>'s slot props, or a useForm() form. */
+export const FormContext = createContext(/** @type {Record<string, unknown> | null} */ (null));
+const EMPTY = Object.freeze({});
+
+/**
+ * What a post made without script left for this page.
+ *
+ * @typedef {{
+ *   flash?: Record<string, unknown>,
+ *   form?: { action: string, errors?: Record<string, string[]>, old?: Record<string, unknown>, expired?: boolean },
+ * }} Flashed
+ *
+ * @typedef {{
+ *   csrfToken: string | null,
+ *   flashed: Flashed,
+ *   flash: Record<string, unknown>,
+ *   setFlash: (flash: Record<string, unknown>) => void,
+ *   hardNavigate: (url: string) => void,
+ * }} Session
+ */
+
+/**
+ * The server's per-request state for every form below it.
+ *
+ * @param {{
+ *   csrfToken?: string | null,
+ *   flash?: Flashed | null,
+ *   hardNavigate?: (url: string) => void,
+ *   children?: unknown,
+ * }} props
+ */
+export function FormSession({ csrfToken = null, flash = null, hardNavigate = assignLocation, children }) {
+  const flashed = useMemo(() => normalizeFlashed(flash), [flash]);
+  const router = useOptionalRouter();
+
+  // An action's flash shows until the next page, whose own flash -- from
+  // the server, in this component's props -- replaces it. Kept with the
+  // props it was set under, so a new page that brings a flash drops it
+  // without an effect; and with the page it was set on, for one that
+  // brings none.
+  const [live, setLive] = useState(
+    /** @type {{ under: Flashed, flash: Record<string, unknown>, page: string } | null} */ (null),
+  );
+  const current = live !== null && live.under === flashed ? live.flash : (flashed.flash ?? EMPTY);
+  const setFlash = useCallback(
+    (/** @type {Record<string, unknown>} */ next) =>
+      setLive({ under: flashed, flash: next, page: pageOf(globalThis.location?.href) }),
+    [flashed],
+  );
+
+  // A page with nothing flashed renders this with `flash={null}`, as the
+  // page before it did: the props are the same, so nothing in them says
+  // the page is another. The router does, when it has moved to one. The
+  // same page again -- a reload after an action that revalidated it, a
+  // jump to an anchor -- keeps what the action said.
+  useEffect(() => {
+    if (typeof router?.on !== 'function') return undefined;
+    return router.on('navigate', (/** @type {CustomEvent} */ event) => {
+      const page = pageOf(event.detail?.url);
+      setLive((now) => (now !== null && now.page !== page ? null : now));
+    });
+  }, [router]);
+
+  const value = useMemo(
+    () => ({ csrfToken, flashed, flash: current, setFlash, hardNavigate }),
+    [csrfToken, flashed, current, setFlash, hardNavigate],
+  );
+
+  return createElement(SessionContext.Provider, { value }, children);
+}
+
+/** The flash the page should show: a post's, carried across its redirect, or an action's since. */
+export function useFlash() {
+  return useContext(SessionContext)?.flash ?? EMPTY;
+}
+
+/**
+ * The slot props of the <Form> around a component -- errors, processing,
+ * reset and the rest -- for an input nested deep inside it; or the useForm()
+ * form a <FormProvider> above it shares. Null outside either.
+ */
+export function useFormContext() {
+  return useContext(FormContext);
+}
+
+/** The router, or null: none is above a form rendered on the server, or in a test. */
+export function useOptionalRouter() {
+  try {
+    return useRouter();
+  } catch {
+    return null;
+  }
+}
+
+/** @internal The FormSession above, for the hooks that submit. */
+export function useFormSession() {
+  return useContext(SessionContext);
+}
+
+/**
+ * @param {Record<string, any> & { action: import('./action.js').ActionTarget }} props
+ */
+export function Form(props) {
+  const {
+    action,
+    transform,
+    options,
+    headers,
+    onBefore,
+    onStart,
+    onProgress,
+    onSuccess,
+    onError,
+    onHttpException,
+    onNetworkError,
+    onCancel,
+    onFinish,
+    onFlash,
+    onExpired,
+    resetOnSuccess = false,
+    resetOnError = false,
+    setDefaultsOnSuccess = false,
+    disableWhileProcessing = false,
+    validationTimeout,
+    validateFiles = false,
+    validateAgainst: _validateAgainst,
+    children,
+    onSubmit: appOnSubmit,
+    ...attributes
+  } = props;
+
+  const name = actionName(action);
+  const session = useContext(SessionContext);
+  const router = useOptionalRouter();
+  const optimistic = useOptimisticStore();
+
+  // Errors a post without script was sent back with: shown on the fields
+  // as the page renders, on the server as in the browser.
+  const flashed = session?.flashed.form?.action === name ? session.flashed.form : null;
+
+  const formRef = useRef(/** @type {HTMLFormElement | null} */ (null));
+  const [errors, setErrors] = useState(() => firstMessages(flashed?.errors));
+  const [processing, setProcessing] = useState(false);
+  const [progress, setProgress] = useState(/** @type {import('./transport.js').Progress | null} */ (null));
+  const [wasSuccessful, setWasSuccessful] = useState(false);
+  const [recentlySuccessful, setRecentlySuccessful] = useState(false);
+  const [isDirty, setDirty] = useState(false);
+  // The page outlived its session: by a 419 to this form's last submit, or
+  // -- for a post made without script -- by the flash it was sent back with.
+  const [expired, setExpired] = useState(() => flashed?.expired === true);
+
+  /** The fields as they stood when the form mounted, or were last made the defaults. */
+  const defaults = useRef(/** @type {string | null} */ (null));
+  /**
+   * What each field held when setDefaultsOnSuccess last made it the default,
+   * for reset() to put back. Not the elements' own defaults: React sets
+   * those again from the `defaultValue` it renders, so a reset after a save
+   * went back past it, to what the markup first said.
+   */
+  const held = useRef(/** @type {WeakMap<Element, unknown> | null} */ (null));
+  const inFlight = useRef(/** @type {AbortController | null} */ (null));
+  const recently = useRef(/** @type {ReturnType<typeof setTimeout> | undefined} */ (undefined));
+
+  // The latest props, for a submission that started under older ones.
+  const latest = useRef(props);
+  latest.current = props;
+
+  const snapshot = useCallback(() => (formRef.current ? serialize(formToObject(formRef.current)) : null), []);
+  const updateDirty = useCallback(() => {
+    const now = snapshot();
+    setDirty(now !== null && defaults.current !== null && now !== defaults.current);
+  }, [snapshot]);
+
+  useEffect(() => {
+    defaults.current = snapshot();
+    return () => {
+      clearTimeout(recently.current);
+      inFlight.current?.abort();
+    };
+  }, [snapshot]);
+
+  // The browser's own events, not React's onChange: React reports a change
+  // only to a value it is tracking, and these inputs are the form's, not
+  // React's -- an input whose value a password manager or a script set
+  // never reaches onChange at all.
+  //
+  // Read once the event is over, not in it. A state update made in a native
+  // listener renders at the next microtask -- between this listener and
+  // React's own, further up -- and that render put a controlled input's old
+  // value back before React saw the new one: typing into one did nothing.
+  useEffect(() => {
+    const form = formRef.current;
+    if (!form) return;
+    /** @type {ReturnType<typeof setTimeout> | undefined} */
+    let pending;
+    const later = () => {
+      clearTimeout(pending);
+      pending = setTimeout(updateDirty, 0);
+    };
+    form.addEventListener('input', later);
+    form.addEventListener('change', later);
+    return () => {
+      clearTimeout(pending);
+      form.removeEventListener('input', later);
+      form.removeEventListener('change', later);
+    };
+  }, [updateDirty]);
+
+  const reset = useCallback(
+    (/** @type {string[]} */ ...fields) => {
+      const form = formRef.current;
+      if (!form) return;
+      if (fields.length === 0) form.reset();
+      for (const element of form.elements) {
+        if (fields.length > 0 && !fields.includes(fieldOf(element))) continue;
+        if (held.current?.has(element)) restoreElement(element, held.current.get(element));
+        else if (fields.length > 0) resetElement(element);
+      }
+      updateDirty();
+    },
+    [updateDirty],
+  );
+
+  const setError = useCallback(
+    (/** @type {string | Record<string, string>} */ field, /** @type {string | undefined} */ message) => {
+      setErrors((now) =>
+        typeof field === 'string' ? { ...now, [field]: message ?? '' } : { ...now, ...field },
+      );
+    },
+    [],
+  );
+
+  const clearErrors = useCallback((/** @type {string[]} */ ...fields) => {
+    setErrors((now) => {
+      if (fields.length === 0) return EMPTY;
+      const next = { ...now };
+      for (const field of fields) delete next[field];
+      return next;
+    });
+  }, []);
+
+  const cancel = useCallback(() => {
+    inFlight.current?.abort();
+  }, []);
+
+  // validate('email'): the action's own form request, asked about the field
+  // as it stands in the form, without the action running -- or an
+  // endpoint's, given `validateAgainst={endpoint.precognitive(...)}`
+  // (ADR 0125).
+  const precognition = usePrecognition({
+    action: () => latest.current.validateAgainst ?? latest.current.action,
+    data: () => {
+      const data = formRef.current ? formToObject(formRef.current) : {};
+      return typeof latest.current.transform === 'function' ? latest.current.transform(data) : data;
+    },
+    errors,
+    setErrors,
+    timeout: validationTimeout,
+    files: validateFiles,
+  });
+  const { cancelValidation } = precognition;
+
+  const send = useCallback(
+    async (/** @type {HTMLElement | null} */ submitter) => {
+      const form = formRef.current;
+      if (!form) return;
+      const p = latest.current;
+
+      let data = formToObject(form, submitter);
+      if (typeof p.transform === 'function') data = p.transform(data);
+      if (typeof p.onBefore === 'function' && p.onBefore(data) === false) return;
+
+      // The submission validates everything; an answer about one field
+      // arriving after it would only be older news.
+      cancelValidation();
+
+      // A second submit replaces the first, as a second click on a link
+      // does: the answer that matters is the one to what was sent last.
+      inFlight.current?.abort();
+      const controller = new AbortController();
+      inFlight.current = controller;
+      const current = () => inFlight.current === controller;
+
+      setProcessing(true);
+      setProgress(null);
+      setWasSuccessful(false);
+      setRecentlySuccessful(false);
+      setExpired(false);
+      clearTimeout(recently.current);
+
+      const outcome = await submitAction({
+        action: p.action,
+        data,
+        router,
+        options: p.options ?? {},
+        headers: p.headers ?? {},
+        signal: controller.signal,
+        hardNavigate: session?.hardNavigate,
+        optimistic,
+        callbacks: {
+          onStart: p.onStart,
+          onProgress: (progress) => {
+            if (current()) setProgress(progress);
+            p.onProgress?.(progress);
+          },
+          onSuccess: p.onSuccess,
+          onError: p.onError,
+          onHttpException: p.onHttpException,
+          onNetworkError: p.onNetworkError,
+          onCancel: p.onCancel,
+          onFinish: p.onFinish,
+          onExpired: p.onExpired,
+          onFlash: (flash) => {
+            session?.setFlash(flash);
+            p.onFlash?.(flash);
+          },
+        },
+      });
+
+      // Superseded: the later submission owns the form's state now.
+      if (!current()) return;
+      inFlight.current = null;
+      setProcessing(false);
+      setProgress(null);
+
+      if (outcome.type === 'expired') setExpired(true);
+
+      if (outcome.type === 'success') {
+        setErrors(EMPTY);
+        setWasSuccessful(true);
+        setRecentlySuccessful(true);
+        recently.current = setTimeout(() => setRecentlySuccessful(false), RECENTLY_SUCCESSFUL_MS);
+        resetFields(p.resetOnSuccess);
+        if (p.setDefaultsOnSuccess) {
+          if (formRef.current) held.current = valuesOf(formRef.current);
+          defaults.current = snapshot();
+        }
+        updateDirty();
+      } else if (outcome.type === 'validation') {
+        setErrors(firstMessages(outcome.errors));
+        resetFields(p.resetOnError);
+      }
+
+      /** @param {boolean | string[] | undefined} which */
+      function resetFields(which) {
+        if (which === true) reset();
+        else if (Array.isArray(which) && which.length > 0) reset(...which);
+      }
+    },
+    [router, session, optimistic, snapshot, updateDirty, reset, cancelValidation],
+  );
+
+  const submit = useCallback(() => {
+    const form = formRef.current;
+    if (!form) return;
+    // Through the form, so its own constraint validation and onSubmit run
+    // as for a click on its button.
+    if (typeof form.requestSubmit === 'function') form.requestSubmit();
+    else void send(null);
+  }, [send]);
+
+  const old = useCallback(
+    (/** @type {string} */ field, /** @type {unknown} */ fallback = undefined) => {
+      const value = getPath(flashed?.old, field);
+      return value === undefined ? fallback : value;
+    },
+    [flashed],
+  );
+
+  const hasErrors = Object.keys(errors).length > 0;
+  const { validate, validating, valid, invalid } = precognition;
+  const slot = useMemo(
+    () => ({
+      errors,
+      hasErrors,
+      processing,
+      progress,
+      wasSuccessful,
+      recentlySuccessful,
+      isDirty,
+      reset,
+      submit,
+      cancel,
+      setError,
+      clearErrors,
+      old,
+      validate,
+      validating,
+      expired,
+      valid,
+      invalid,
+    }),
+    [
+      errors,
+      hasErrors,
+      processing,
+      progress,
+      wasSuccessful,
+      recentlySuccessful,
+      isDirty,
+      reset,
+      submit,
+      cancel,
+      setError,
+      clearErrors,
+      old,
+      validate,
+      validating,
+      expired,
+      valid,
+      invalid,
+    ],
+  );
+
+  /** @param {any} event */
+  const onSubmit = (event) => {
+    appOnSubmit?.(event);
+    // The app's handler may stop it -- its own checks found a problem.
+    if (event.defaultPrevented) return;
+    event.preventDefault();
+    void send(event.nativeEvent?.submitter ?? null);
+  };
+
+  const token = session?.csrfToken ?? null;
+  const content = typeof children === 'function' ? children(slot) : children;
+
+  return createElement(
+    FormContext.Provider,
+    { value: slot },
+    createElement(
+      'form',
+      {
+        ...attributes,
+        ref: formRef,
+        method: 'post',
+        action: actionUrl(name),
+        onSubmit,
+        inert: disableWhileProcessing && processing ? true : undefined,
+      },
+      // Only with a token to put in it: "Stored output never contains a
+      // CSRF token", and a form rendered without one reads the cookie when
+      // it is submitted by script.
+      token === null ? null : createElement('input', { type: 'hidden', name: TOKEN_FIELD, value: token }),
+      content,
+    ),
+  );
+}
+
+/**
+ * The first message for each field, which is what a field shows.
+ *
+ * @param {unknown} errors
+ * @returns {Record<string, string>}
+ */
+export function firstMessages(errors) {
+  /** @type {Record<string, string>} */
+  const out = {};
+  for (const [field, messages] of Object.entries(normalizeErrors(errors))) {
+    if (messages[0] !== undefined) out[field] = messages[0];
+  }
+  return Object.keys(out).length === 0 ? EMPTY : out;
+}
+
+/**
+ * The flash as the server sent it, made safe to read: a PHP empty array
+ * crosses as a list, and anything not shaped as expected is nothing.
+ *
+ * @param {unknown} flash
+ * @returns {Flashed}
+ */
+function normalizeFlashed(flash) {
+  if (flash === null || typeof flash !== 'object' || Array.isArray(flash)) return EMPTY;
+  const raw = /** @type {Record<string, any>} */ (flash);
+  /** @type {Flashed} */
+  const out = {};
+  if (raw.flash && typeof raw.flash === 'object' && !Array.isArray(raw.flash)) out.flash = raw.flash;
+  if (raw.form && typeof raw.form === 'object' && typeof raw.form.action === 'string') {
+    out.form = {
+      action: raw.form.action,
+      errors: normalizeErrors(raw.form.errors),
+      old:
+        raw.form.old && typeof raw.form.old === 'object' && !Array.isArray(raw.form.old) ? raw.form.old : {},
+      expired: raw.form.expired === true,
+    };
+  }
+  return out;
+}
+
+/**
+ * A page's URL without its fragment, which names a place on the page, not
+ * another page.
+ *
+ * @param {unknown} href
+ */
+function pageOf(href) {
+  if (typeof href !== 'string') return '';
+  const at = href.indexOf('#');
+  return at === -1 ? href : href.slice(0, at);
+}
+
+/** The fields' values as a string to compare: files by name and size, since their bytes are not read. */
+function serialize(/** @type {unknown} */ data) {
+  return JSON.stringify(data, (_key, value) =>
+    typeof File !== 'undefined' && value instanceof File ? `file:${value.name}:${value.size}` : value,
+  );
+}
+
+/** A form element's field name without a trailing `[]`, which is how reset() names it. */
+function fieldOf(/** @type {Element} */ element) {
+  const name = /** @type {HTMLInputElement} */ (element).name ?? '';
+  return name.endsWith('[]') ? name.slice(0, -2) : name;
+}
+
+/**
+ * What each field of a form holds, by element: a box's checked state, a
+ * select's selected options, any other field's value. Files are left out;
+ * a reset empties them, as the browser's does.
+ *
+ * @param {HTMLFormElement} form
+ * @returns {WeakMap<Element, unknown>}
+ */
+function valuesOf(form) {
+  const values = new WeakMap();
+  for (const element of form.elements) {
+    if (element instanceof HTMLInputElement) {
+      if (element.type === 'checkbox' || element.type === 'radio') values.set(element, element.checked);
+      else if (element.type !== 'file') values.set(element, element.value);
+    } else if (element instanceof HTMLTextAreaElement) {
+      values.set(element, element.value);
+    } else if (element instanceof HTMLSelectElement) {
+      values.set(
+        element,
+        [...element.options].map((option) => option.selected),
+      );
+    }
+  }
+  return values;
+}
+
+/** Puts back what valuesOf() found a field holding. */
+function restoreElement(/** @type {Element} */ element, /** @type {unknown} */ value) {
+  if (element instanceof HTMLInputElement) {
+    if (element.type === 'checkbox' || element.type === 'radio') element.checked = value === true;
+    else element.value = String(value);
+  } else if (element instanceof HTMLTextAreaElement) {
+    element.value = String(value);
+  } else if (element instanceof HTMLSelectElement && Array.isArray(value)) {
+    [...element.options].forEach((option, i) => (option.selected = value[i] === true));
+  }
+}
+
+/** Puts one field back to its default, as form.reset() would. */
+function resetElement(/** @type {Element} */ element) {
+  if (element instanceof HTMLInputElement) {
+    if (element.type === 'checkbox' || element.type === 'radio') element.checked = element.defaultChecked;
+    else if (element.type !== 'file') element.value = element.defaultValue;
+    else element.value = '';
+  } else if (element instanceof HTMLTextAreaElement) {
+    element.value = element.defaultValue;
+  } else if (element instanceof HTMLSelectElement) {
+    for (const option of element.options) option.selected = option.defaultSelected;
+  }
+}

package/src/forms.d.ts

@@ -0,0 +1,4 @@
+export * from './form';
+export * from './use-form';
+export * from './use-http';
+export * from './optimistic';

package/src/forms.js

@@ -0,0 +1,10 @@
+// @tinvar/react/form -- forms and mutations, from one entry.
+//
+// Each module it gathers is a client module of its own ('use client'), so a
+// server component importing <Form> or <FormSession> from here gets a client
+// reference, as it would importing the module itself.
+
+export { Form, FormSession, useFlash, useFormContext, RECENTLY_SUCCESSFUL_MS } from './form.js';
+export { useForm, FormProvider } from './use-form.js';
+export { useHttp, query, QUERY_PREFIX } from './use-http.js';
+export { OptimisticState, useOptimisticState } from './optimistic.js';

package/src/fragment-client.d.ts

@@ -0,0 +1,70 @@
+/** Fetching one deferred subtree. */
+
+export declare const FRAGMENT_PREFIX: '/_fragment/';
+export declare const TOKEN_HEADER: 'x-fragment-token';
+export declare const FRAGMENT_CONTENT_TYPE: 'text/x-component';
+export declare const MIN_INTERVAL_MS: number;
+export declare const MAX_FAILURES: number;
+
+export declare class FragmentError extends Error {
+  constructor(message: string, status: number, digest?: string | null);
+  status: number;
+  /** What the server logged a 5xx under, when its answer said. */
+  digest: string | null;
+}
+
+/**
+ * Whether a failed load was the server's render throwing -- a 5xx, or an
+ * error row the renderer wrote -- with the digest it was reported under.
+ * Null for any other failure.
+ */
+export declare function serverFailure(error: unknown): { digest: string | null } | null;
+
+/**
+ * Holds one boundary's token across refetches. The token rotates on every
+ * successful response, which is what lets a refresh boundary outlive the hour
+ * the first one was issued for.
+ */
+export declare class FragmentHandle {
+  constructor(token: string, fetchImpl?: typeof fetch);
+  readonly token: string;
+  /** Whether this handle has given up: a 404, or too many failures. */
+  readonly terminal: boolean;
+  /**
+   * The live token the last successful load came with: the topics of the
+   * tags its render read. Null when it read none.
+   */
+  readonly liveToken: string | null;
+  /** Takes a fresh token for the same boundary, keeping the pacing. */
+  adopt(token: string): void;
+  /** `headers`: the once-shared holds to claim, X-Have-Shared alone (ADR 0074). */
+  load(options?: {
+    signal?: AbortSignal;
+    headers?: Record<string, string>;
+  }): Promise<ReadableStream<Uint8Array>>;
+  /**
+   * Fetches and decodes. A body that fails to decode counts as a failed
+   * load, against the same backoff and limit as a failed request.
+   */
+  load<T>(options: {
+    signal?: AbortSignal;
+    decode: (stream: ReadableStream<Uint8Array>) => T | Promise<T>;
+    headers?: Record<string, string>;
+  }): Promise<T>;
+  /**
+   * Fetches a <Deferred group>'s boundaries in one request, resolving with
+   * each one's subtree in order. The handles' backoff, limits and rotation
+   * hold for all of them at once.
+   */
+  static loadGroup(
+    handles: FragmentHandle[],
+    options: {
+      signal?: AbortSignal;
+      decode: (stream: ReadableStream<Uint8Array>) => unknown;
+      headers?: Record<string, string>;
+    },
+  ): Promise<unknown[]>;
+}
+
+/** A token's signed claims without its issue and expiry times; equal for re-issues of the same boundary. */
+export declare function tokenIdentity(token: string | null): string | null;