@tinvar/react 0.0.0-stage → 0.4.1

package/src/use-channel.d.ts

@@ -0,0 +1,21 @@
+import type { ChannelError, Channels, ChannelShape } from './channel.js';
+
+export interface UseChannelOptions {
+  /** A refusal -- 401, 403, 404 -- or a request that never got an answer. */
+  onError?: (error: ChannelError) => void;
+  /** The stream was down for a while: messages may have been missed. */
+  onGap?: () => void;
+}
+
+/**
+ * Listens to one channel while the component is mounted, subscribing again
+ * when the channel or its parameters change; null parameters listen to
+ * nothing yet. The latest `onMessage` is the one called.
+ */
+export declare function useChannel<M extends { [N in keyof M]: ChannelShape }, N extends keyof M & string>(
+  channel: Channels<M>,
+  name: N,
+  params: M[N]['params'] | null | undefined,
+  onMessage: (message: M[N]['message']) => void,
+  options?: UseChannelOptions,
+): void;

package/src/use-channel.js

@@ -0,0 +1,51 @@
+'use client';
+
+// useChannel: a component listening to one of the application's #[Channel]s
+// while it is mounted (ADR 0069).
+//
+//   useChannel(channel, 'orders', { order: id }, (message) => setNotice(message));
+//
+// Subscribed when it mounts and whenever the channel or its parameters
+// change, and unsubscribed when it unmounts. The latest `onMessage` is the
+// one called, so an inline function does not subscribe again on every
+// render. What it hears goes through the live module, which the app's entry
+// starts (createLive): without it, nothing is traded and nothing is heard.
+
+import { useEffect, useRef } from 'react';
+
+/**
+ * @template {{ listen: (name: any, params: any, onMessage: any, options?: any) => () => void }} C
+ * @param {C} channel the `channel` codegen exports
+ * @param {string} name
+ * @param {Record<string, string | number | boolean> | null | undefined} params null to listen to nothing yet
+ * @param {(message: any) => void} onMessage
+ * @param {{ onError?: (error: import('./channel.js').ChannelError) => void, onGap?: () => void }} [options]
+ */
+export function useChannel(channel, name, params, onMessage, options) {
+  const latest = useRef({ onMessage, options });
+  latest.current = { onMessage, options };
+
+  // By value: a parameters object written inline is a new object on every
+  // render, and the same subscription.
+  const key =
+    params == null
+      ? null
+      : JSON.stringify(Object.entries(params).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)));
+
+  useEffect(() => {
+    if (key === null) return undefined;
+    /** @type {Record<string, string | number | boolean>} */
+    const current = Object.fromEntries(JSON.parse(key));
+
+    return channel.listen(
+      name,
+      current,
+      (/** @type {unknown} */ message) => latest.current.onMessage(message),
+      {
+        onError: (/** @type {import('./channel.js').ChannelError} */ error) =>
+          latest.current.options?.onError?.(error),
+        onGap: () => latest.current.options?.onGap?.(),
+      },
+    );
+  }, [channel, name, key]);
+}

package/src/use-form.d.ts

@@ -0,0 +1,86 @@
+import type { ReactNode } from 'react';
+import type { ActionTarget } from './action';
+import type { PrecognitionTarget } from './endpoint';
+import type { PrecognitionSettings, Progress, SubmitCallbacks, VisitOptions } from './form';
+
+/** What a useForm() submission came to. */
+export type Submitted =
+  | { type: 'success'; result: import('./form').ActionResult }
+  | { type: 'validation'; errors: Record<string, string[]> }
+  | { type: 'http'; failure: import('./form').HttpFailure }
+  | { type: 'network'; error: unknown }
+  | { type: 'expired' }
+  | { type: 'cancelled' };
+
+/** How one submission runs: top-level fields control it; `options`, the visit after it. */
+export interface Submission extends SubmitCallbacks {
+  options?: VisitOptions;
+  headers?: Record<string, string>;
+  resetOnSuccess?: boolean | string[];
+  resetOnError?: boolean | string[];
+  setDefaultsOnSuccess?: boolean;
+}
+
+export interface UseForm<D extends Record<string, unknown>> {
+  data: D;
+  setData: {
+    <K extends keyof D>(field: K, value: D[K]): void;
+    (data: Partial<D>): void;
+    (update: (data: D) => D): void;
+  };
+  /** The first message for each field. */
+  errors: Partial<Record<keyof D | (string & {}), string>>;
+  hasErrors: boolean;
+  processing: boolean;
+  progress: Progress | null;
+  wasSuccessful: boolean;
+  /** True for two seconds after a success. */
+  recentlySuccessful: boolean;
+  /** Whether the data differs from the defaults. */
+  isDirty: boolean;
+  /** Puts the named fields -- or every field -- back to their defaults. */
+  reset: (...fields: (keyof D)[]) => void;
+  /** Makes the current data -- or the fields given -- what isDirty and reset() compare with. */
+  defaults: {
+    (): void;
+    <K extends keyof D>(field: K, value: D[K]): void;
+    (fields: Partial<D>): void;
+  };
+  setError: {
+    (field: keyof D | (string & {}), message: string): void;
+    (errors: Partial<Record<keyof D | (string & {}), string>>): void;
+  };
+  clearErrors: (...fields: (keyof D | (string & {}))[]) => void;
+  /** Reshapes the data before each submission. */
+  transform: (fn: (data: D) => Record<string, unknown>) => void;
+  /** Fields never kept on the history entry -- a password. Returns the form. */
+  dontRemember: (...fields: (keyof D)[]) => UseForm<D>;
+  /** Posts the data to an action and applies the answer to the page. */
+  submit: (action: ActionTarget, submission?: Submission) => Promise<Submitted | undefined>;
+  cancel: () => void;
+  /** The page outlived its session; see FormSlotProps.expired. */
+  expired: boolean;
+  /** Names the action -- or the endpoint, by `endpoint.precognitive()` -- validate() asks. Returns the form. */
+  withPrecognition: (
+    action: ActionTarget | PrecognitionTarget,
+    settings?: PrecognitionSettings,
+  ) => UseForm<D>;
+  /** Precognition: asks the action's (or endpoint's) form request about these fields, after the validation timeout. */
+  validate: (field: (keyof D & string) | (string & {}) | string[]) => void;
+  validating: boolean;
+  valid: (field: keyof D | (string & {})) => boolean;
+  invalid: (field: keyof D | (string & {})) => boolean;
+}
+
+/**
+ * A form whose fields React holds. Given a key, its data and errors are kept
+ * on the history entry, so back and forward bring them back.
+ */
+export declare function useForm<D extends Record<string, unknown>>(data: D): UseForm<D>;
+export declare function useForm<D extends Record<string, unknown>>(key: string, data: D): UseForm<D>;
+
+/** Makes a useForm() form what useFormContext() returns below it. */
+export declare function FormProvider<D extends Record<string, unknown>>(props: {
+  form: UseForm<D>;
+  children?: ReactNode;
+}): ReactNode;

package/src/use-form.js

@@ -0,0 +1,432 @@
+'use client';
+
+// useForm: a form whose fields React holds.
+//
+// tinvar-spec.md, "Forms and mutations": "`useForm(key?, data)` for
+// controlled forms, with history-remembered state and
+// `dontRemember('password')`. `useFormContext()` for nested inputs."
+//
+// The same submission as <Form> -- submit.js, so the same three error
+// channels and the same answer applied to the page -- with the data in
+// React state instead of the DOM. Given a key, the data and errors are kept
+// for the history entry through the router's remembered state -- the store
+// useRemember() keeps, bound to the session and wiped when it ends -- so
+// back to a half-filled form finds it as it was left; fields named in
+// dontRemember() never are. Without a router nothing is remembered.
+
+import { createElement, useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import {
+  FormContext,
+  firstMessages,
+  RECENTLY_SUCCESSFUL_MS,
+  useFormSession,
+  useOptionalRouter,
+} from './form.js';
+import { useOptimisticStore } from './optimistic.js';
+import { usePrecognition } from './precognition.js';
+import { submitAction } from './submit.js';
+import { carries, useHydrated } from './use-remember.js';
+
+const EMPTY = Object.freeze({});
+
+/**
+ * @template {Record<string, unknown>} D
+ * @param {string | D} keyOrData
+ * @param {D} [maybeData]
+ */
+export function useForm(keyOrData, maybeData) {
+  const key = typeof keyOrData === 'string' ? keyOrData : null;
+  const initial = /** @type {D} */ (typeof keyOrData === 'string' ? (maybeData ?? {}) : keyOrData);
+
+  const router = useOptionalRouter();
+  const optimistic = useOptimisticStore();
+  const session = useFormSession();
+
+  const rememberKey = key === null ? null : `form:${key}`;
+
+  // The page the form mounted on, for what it remembers: while a visit is
+  // mounting a page, that page, so a form on it never reads -- or writes --
+  // the entry being left. The router binds what it keeps to that page's
+  // session, and reads it back under no other.
+  const scope = useRef(/** @type {import('./router.js').RememberScope | null} */ (null));
+  if (scope.current === null && rememberKey !== null && typeof router?.rememberScope === 'function') {
+    scope.current = router.rememberScope();
+  }
+
+  const restored = useRef(
+    /** @type {{ data?: Partial<D>, errors?: Record<string, string> } | undefined} */ (undefined),
+  );
+  if (restored.current === undefined) {
+    restored.current =
+      rememberKey === null || scope.current === null ? {} : keptFor(router, rememberKey, scope.current);
+  }
+
+  // The defaults isDirty and reset() compare with: what the form was given,
+  // not what was restored into it.
+  const defaults = useRef(/** @type {D} */ (initial));
+  const [data, setDataState] = useState(
+    /** @returns {D} */ () => ({ ...initial, ...(restored.current?.data ?? {}) }),
+  );
+  const [errors, setErrors] = useState(
+    /** @returns {Record<string, string>} */ () => restored.current?.errors ?? EMPTY,
+  );
+  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 [expired, setExpired] = useState(false);
+  const [, setDefaultsVersion] = useState(0);
+
+  const unremembered = useRef(/** @type {Set<string>} */ (new Set()));
+  const transformer = useRef(/** @type {((data: D) => Record<string, unknown>) | null} */ (null));
+  const inFlight = useRef(/** @type {AbortController | null} */ (null));
+  const recently = useRef(/** @type {ReturnType<typeof setTimeout> | undefined} */ (undefined));
+  const latest = useRef(data);
+  latest.current = data;
+  const latestErrors = useRef(errors);
+  latestErrors.current = errors;
+  const latestInitial = useRef(initial);
+  latestInitial.current = initial;
+
+  // What the server rendered until hydration is done: the data the form was
+  // given, and no errors. What was remembered shows straight after; see
+  // useHydrated().
+  const hydrated = useHydrated();
+  const shownData = hydrated ? data : initial;
+  const shownErrors = hydrated ? errors : EMPTY;
+
+  /** What is kept of the data: everything but the fields named in dontRemember(). */
+  const rememberable = useCallback((/** @type {D} */ from) => {
+    /** @type {Record<string, unknown>} */
+    const kept = {};
+    for (const [field, value] of Object.entries(from)) {
+      if (!unremembered.current.has(field)) kept[field] = value;
+    }
+    return kept;
+  }, []);
+
+  useEffect(
+    () => () => {
+      clearTimeout(recently.current);
+      inFlight.current?.abort();
+    },
+    [],
+  );
+
+  // Kept for the entry as it changes. A field named in dontRemember() is
+  // left out entirely: a password is never written to storage.
+  useEffect(() => {
+    if (rememberKey === null || scope.current === null) return;
+    router?.remember(rememberKey, { data: rememberable(data), errors }, scope.current);
+  }, [router, rememberKey, data, errors, rememberable]);
+
+  // A form kept across a navigation -- the same page component for another
+  // product, or a form in a layout both pages share -- belongs to the new
+  // page from then on, as a useRemember() value does. It took its page once,
+  // as it mounted, and kept writing to that page's entry from every page
+  // after: what was typed on the second product went onto the first's entry,
+  // and back to either found the other's. So: back or forward to an entry
+  // that remembered the form brings that back; a visit carries what the form
+  // holds onto the new entry -- within one session, and never from an
+  // encrypted page to one that is not (carries()). Otherwise nothing it holds
+  // goes with it: it starts again from the data it was given.
+  useEffect(() => {
+    if (rememberKey === null || typeof router?.rememberScope !== 'function') return undefined;
+    return router.on('navigate', (/** @type {CustomEvent} */ event) => {
+      const next = router.rememberScope();
+      const previous = scope.current;
+      if (next === previous) return;
+      scope.current = next;
+
+      const kept = event.detail?.type === 'history' ? keptFor(router, rememberKey, next) : {};
+      const found = kept.data !== undefined || kept.errors !== undefined;
+
+      if (previous === null || !carries(previous, next) || found) {
+        setDataState({ ...latestInitial.current, ...(kept.data ?? {}) });
+        setErrors(kept.errors ?? EMPTY);
+        return;
+      }
+
+      router.remember(
+        rememberKey,
+        { data: rememberable(latest.current), errors: latestErrors.current },
+        next,
+      );
+    });
+  }, [router, rememberKey, rememberable]);
+
+  const setData = useCallback(
+    /**
+     * @param {keyof D | Partial<D> | ((data: D) => D)} field
+     * @param {unknown} [value]
+     */
+    (field, value) => {
+      setDataState((now) => {
+        if (typeof field === 'function') return field(now);
+        if (typeof field === 'object' && field !== null) return { ...now, ...field };
+        return { ...now, [field]: value };
+      });
+    },
+    [],
+  );
+
+  const reset = useCallback((/** @type {(keyof D)[]} */ ...fields) => {
+    setDataState((now) => {
+      if (fields.length === 0) return { ...defaults.current };
+      const next = { ...now };
+      for (const field of fields) next[field] = defaults.current[field];
+      return next;
+    });
+  }, []);
+
+  const setDefaults = useCallback(
+    /**
+     * @param {keyof D | Partial<D>} [field]
+     * @param {unknown} [value]
+     */
+    (field, value) => {
+      if (field === undefined) defaults.current = { ...latest.current };
+      else if (typeof field === 'object') defaults.current = { ...defaults.current, ...field };
+      else defaults.current = { ...defaults.current, [field]: value };
+      setDefaultsVersion((v) => v + 1);
+    },
+    [],
+  );
+
+  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 Object.keys(next).length === 0 ? EMPTY : next;
+    });
+  }, []);
+
+  const cancel = useCallback(() => inFlight.current?.abort(), []);
+
+  // Precognition needs an action to ask, which a form React holds learns
+  // from withPrecognition(); <Form> knows its own.
+  const precognitive = useRef(
+    /** @type {{ action: import('./action.js').ActionTarget | import('./precognition.js').PrecognitionTarget | null, timeout?: number, files?: boolean }} */ ({
+      action: null,
+    }),
+  );
+  const precognition = usePrecognition({
+    action: () => precognitive.current.action,
+    data: () => {
+      const payload = /** @type {Record<string, unknown>} */ ({ ...latest.current });
+      return transformer.current ? transformer.current(/** @type {D} */ (payload)) : payload;
+    },
+    errors: shownErrors,
+    setErrors,
+    timeout: () => precognitive.current.timeout,
+    files: () => precognitive.current.files,
+  });
+  const { cancelValidation } = precognition;
+
+  const submit = useCallback(
+    /**
+     * Posts the data to an action, and applies the answer to the page.
+     * Top-level fields control the submission; `options`, the visit after it.
+     *
+     * @param {import('./action.js').ActionTarget} action
+     * @param {import('./submit.js').Callbacks & {
+     *   onBefore?: (data: Record<string, unknown>) => boolean | void,
+     *   options?: Record<string, unknown>,
+     *   headers?: Record<string, string>,
+     *   resetOnSuccess?: boolean | string[],
+     *   resetOnError?: boolean | string[],
+     *   setDefaultsOnSuccess?: boolean,
+     * }} [submission]
+     */
+    async (action, submission = {}) => {
+      let payload = /** @type {Record<string, unknown>} */ ({ ...latest.current });
+      if (transformer.current) payload = transformer.current(/** @type {D} */ (payload));
+      if (typeof submission.onBefore === 'function' && submission.onBefore(payload) === false) return;
+
+      cancelValidation();
+      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,
+        data: payload,
+        router,
+        options: submission.options ?? {},
+        headers: submission.headers ?? {},
+        signal: controller.signal,
+        hardNavigate: session?.hardNavigate,
+        optimistic,
+        callbacks: {
+          ...submission,
+          onProgress: (next) => {
+            if (current()) setProgress(next);
+            submission.onProgress?.(next);
+          },
+          onFlash: (flash) => {
+            session?.setFlash(flash);
+            submission.onFlash?.(flash);
+          },
+        },
+      });
+
+      if (!current()) return outcome;
+      inFlight.current = null;
+      setProcessing(false);
+      setProgress(null);
+
+      // The page outlived its session; the form says so, and keeps what
+      // was typed for the next try.
+      if (outcome.type === 'expired') setExpired(true);
+
+      if (outcome.type === 'success') {
+        setErrors(EMPTY);
+        setWasSuccessful(true);
+        setRecentlySuccessful(true);
+        recently.current = setTimeout(() => setRecentlySuccessful(false), RECENTLY_SUCCESSFUL_MS);
+        if (submission.setDefaultsOnSuccess) setDefaults();
+        resetFields(submission.resetOnSuccess);
+      } else if (outcome.type === 'validation') {
+        setErrors(firstMessages(outcome.errors));
+        resetFields(submission.resetOnError);
+      }
+      return outcome;
+
+      /** @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, reset, setDefaults, cancelValidation],
+  );
+
+  const transform = useCallback((/** @type {(data: D) => Record<string, unknown>} */ fn) => {
+    transformer.current = fn;
+  }, []);
+
+  // Returns the form, so it reads as Inertia's does when chained:
+  // useForm('sign-in', data).dontRemember('password').
+  const self = useRef(/** @type {any} */ (null));
+  const dontRemember = useCallback((/** @type {string[]} */ ...fields) => {
+    for (const field of fields) unremembered.current.add(field);
+    return self.current;
+  }, []);
+
+  /**
+   * Names what validate() asks -- an action, or an endpoint as
+   * `endpoint.precognitive()` names one (ADR 0125); returns the form, to
+   * chain from useForm().
+   */
+  const withPrecognition = useCallback(
+    (
+      /** @type {import('./action.js').ActionTarget | import('./precognition.js').PrecognitionTarget} */ action,
+      /** @type {{ validationTimeout?: number, validateFiles?: boolean }} */ settings = {},
+    ) => {
+      precognitive.current = { action, timeout: settings.validationTimeout, files: settings.validateFiles };
+      return self.current;
+    },
+    [],
+  );
+
+  const isDirty = JSON.stringify(shownData) !== JSON.stringify(defaults.current);
+  const hasErrors = Object.keys(shownErrors).length > 0;
+  const { validate, validating, valid, invalid } = precognition;
+
+  const form = useMemo(
+    () => ({
+      data: shownData,
+      setData,
+      errors: shownErrors,
+      hasErrors,
+      processing,
+      progress,
+      wasSuccessful,
+      recentlySuccessful,
+      isDirty,
+      reset,
+      defaults: setDefaults,
+      setError,
+      clearErrors,
+      transform,
+      dontRemember,
+      submit,
+      cancel,
+      expired,
+      withPrecognition,
+      validate,
+      validating,
+      valid,
+      invalid,
+    }),
+    [
+      shownData,
+      setData,
+      shownErrors,
+      hasErrors,
+      processing,
+      progress,
+      wasSuccessful,
+      recentlySuccessful,
+      isDirty,
+      reset,
+      setDefaults,
+      setError,
+      clearErrors,
+      transform,
+      dontRemember,
+      submit,
+      cancel,
+      expired,
+      withPrecognition,
+      validate,
+      validating,
+      valid,
+      invalid,
+    ],
+  );
+  self.current = form;
+  return form;
+}
+
+/**
+ * What was remembered for a form on a page, in the shape useForm() keeps --
+ * nothing, for anything else.
+ *
+ * @param {any} router
+ * @param {string} key
+ * @param {import('./router.js').RememberScope} scope
+ * @returns {{ data?: Record<string, any>, errors?: Record<string, string> }}
+ */
+function keptFor(router, key, scope) {
+  const found = router?.remembered(key, scope);
+  return found !== null && typeof found === 'object' ? found : {};
+}
+
+/**
+ * Makes a useForm() form what useFormContext() returns below it, for inputs
+ * nested deep inside a form React holds -- as <Form> is for its own.
+ *
+ * @param {{ form: object, children?: unknown }} props
+ */
+export function FormProvider({ form, children }) {
+  return createElement(FormContext.Provider, { value: /** @type {any} */ (form) }, children);
+}

package/src/use-http.d.ts

@@ -0,0 +1,56 @@
+import type { ActionTarget } from './action';
+import type { HttpFailure } from './form';
+
+export declare const QUERY_PREFIX: '/_query/';
+
+/** A reference to a PHP #[Query], for useHttp. */
+export interface QueryReference {
+  readonly query: string;
+  readonly url: string;
+}
+
+export declare function query(name: string): QueryReference;
+
+export interface HttpCallbacks<T = unknown> {
+  onSuccess?: (value: T) => void;
+  /** 422: the field errors, if the answer named fields. */
+  onError?: (errors: Record<string, string[]>) => void;
+  /** Any other status. */
+  onHttpException?: (failure: HttpFailure) => void;
+  /** No answer at all. */
+  onNetworkError?: (error: unknown) => void;
+  onCancel?: () => void;
+  onFinish?: () => void;
+  headers?: Record<string, string>;
+}
+
+export type Called<T = unknown> =
+  | { type: 'success'; value: T; redirect?: string }
+  | { type: 'validation'; errors: Record<string, string[]> }
+  | { type: 'http'; failure: HttpFailure }
+  | { type: 'network'; error: unknown }
+  | { type: 'cancelled' };
+
+export interface UseHttp<T = unknown> {
+  /** Calls it; a call still in flight is cancelled. */
+  call: (args?: Record<string, unknown>, callbacks?: HttpCallbacks<T>) => Promise<Called<T>>;
+  /** The last successful call's query result, or action value. */
+  result: T | undefined;
+  /** The first message for each field. */
+  errors: Record<string, string>;
+  hasErrors: boolean;
+  processing: boolean;
+  wasSuccessful: boolean;
+  cancel: () => void;
+  clearErrors: () => void;
+}
+
+/**
+ * Calls an action or a query without moving the page: search-as-you-type.
+ * Nothing is mounted and no redirect followed; an action's invalidated tags
+ * still flush prefetched pages, and its flash is still announced.
+ */
+export declare function useHttp<T = unknown>(
+  target: ActionTarget | QueryReference,
+  callbacks?: HttpCallbacks<T>,
+): UseHttp<T>;