@tinvar/react 0.0.0-stage → 0.4.0

package/src/form-data.js

@@ -0,0 +1,219 @@
+// A form's fields as data, and data as a request body.
+//
+// tinvar-spec.md, "Forms and mutations": "<Form action={moveUnit}> with
+// uncontrolled `name` inputs, nested names (`report[tags][]`)", and "Files:
+// payloads with files become multipart automatically". The names are PHP's:
+// a browser posting the same form without script sends them as they are, and
+// PHP builds the same nesting from them -- so the object built here is the
+// one the action would have received either way.
+//
+// No React and nothing from the router: <Form>, useForm and useHttp all use
+// it, and so do their tests, in a plain DOM.
+
+/** The hidden field <Form> renders for a post made without script; transport, not data. */
+export const TOKEN_FIELD = '_token';
+
+/**
+ * The path a field name stands for: `report[tags][]` is report, tags, and a
+ * push. An empty segment is a push, as PHP reads it.
+ *
+ * @param {string} name
+ * @returns {string[]}
+ */
+export function pathOf(name) {
+  const open = name.indexOf('[');
+  if (open <= 0 || !name.endsWith(']')) return [name];
+
+  const path = [name.slice(0, open)];
+  const rest = name.slice(open);
+  const segment = /\[([^\]]*)\]/g;
+  let match;
+  let consumed = 0;
+  while ((match = segment.exec(rest)) !== null) {
+    if (match.index !== consumed) return [name];
+    path.push(match[1] ?? '');
+    consumed = segment.lastIndex;
+  }
+
+  // Anything after the last bracket is not PHP's nesting; the name is a name.
+  return consumed === rest.length ? path : [name];
+}
+
+/**
+ * Sets a value at a field name's path, building the nesting on the way.
+ *
+ * @param {Record<string, unknown>} target
+ * @param {string} name
+ * @param {unknown} value
+ */
+export function setPath(target, name, value) {
+  const path = pathOf(name);
+  /** @type {any} */
+  let level = target;
+
+  for (let i = 0; i < path.length; i++) {
+    const key = path[i];
+    const last = i === path.length - 1;
+
+    // A key a prototype answers to is not a field: `__proto__[x]` would
+    // otherwise write onto Object.prototype for every object on the page.
+    if (key === '__proto__' || key === 'constructor' || key === 'prototype') return;
+
+    if (key === '') {
+      if (!Array.isArray(level)) return;
+      if (last) {
+        level.push(value);
+        return;
+      }
+      const next = path[i + 1] === '' ? [] : {};
+      level.push(next);
+      level = next;
+      continue;
+    }
+
+    if (last) {
+      level[key] = value;
+      return;
+    }
+
+    const wantsList = path[i + 1] === '';
+    const existing = Object.hasOwn(level, key) ? level[key] : undefined;
+    if (existing === null || typeof existing !== 'object' || Array.isArray(existing) !== wantsList) {
+      level[key] = wantsList ? [] : {};
+    }
+    level = level[key];
+  }
+}
+
+/**
+ * The value at a field name's path, or undefined. A trailing `[]` names the
+ * whole list.
+ *
+ * @param {unknown} source
+ * @param {string} name
+ */
+export function getPath(source, name) {
+  const path = pathOf(name);
+  if (path.at(-1) === '' && path.length > 1) path.pop();
+
+  /** @type {any} */
+  let level = source;
+  for (const key of path) {
+    if (level === null || typeof level !== 'object' || !Object.hasOwn(level, key)) return undefined;
+    level = level[key];
+  }
+  return level;
+}
+
+/**
+ * A form's fields, as the object its action receives.
+ *
+ * Read through FormData, so it is exactly what the browser would post: only
+ * checked boxes, every selected option, the button that submitted it, files
+ * as File objects. An empty file input -- nothing chosen -- is left out
+ * rather than sent as a nameless, empty file. The CSRF field is left out:
+ * the token travels in the header.
+ *
+ * @param {HTMLFormElement} form
+ * @param {HTMLElement | null} [submitter]
+ * @returns {Record<string, unknown>}
+ */
+export function formToObject(form, submitter = null) {
+  /** @type {FormData} */
+  let entries;
+  try {
+    entries = submitter ? new FormData(form, submitter) : new FormData(form);
+  } catch {
+    // A submitter that is not this form's own button.
+    entries = new FormData(form);
+  }
+
+  /** @type {Record<string, unknown>} */
+  const data = {};
+  for (const [name, value] of entries) {
+    if (name === TOKEN_FIELD) continue;
+    if (isFile(value) && value.name === '' && value.size === 0) continue;
+    setPath(data, name, value);
+  }
+  return data;
+}
+
+/** @param {unknown} value */
+export function isFile(value) {
+  return (
+    (typeof File !== 'undefined' && value instanceof File) ||
+    (typeof Blob !== 'undefined' && value instanceof Blob)
+  );
+}
+
+/**
+ * Whether data holds a file anywhere, so has to go as multipart.
+ *
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+export function hasFiles(value) {
+  if (isFile(value)) return true;
+  if (typeof FileList !== 'undefined' && value instanceof FileList) return value.length > 0;
+  if (Array.isArray(value)) return value.some(hasFiles);
+  if (value !== null && typeof value === 'object') return Object.values(value).some(hasFiles);
+  return false;
+}
+
+/**
+ * The data without its files. Precognition leaves them out by default
+ * ("files excluded by default"): validating an email should not upload the
+ * attachment beside it on every keystroke.
+ *
+ * @param {unknown} value
+ * @returns {unknown}
+ */
+export function withoutFiles(value) {
+  if (isFile(value) || (typeof FileList !== 'undefined' && value instanceof FileList)) return undefined;
+  if (Array.isArray(value)) return value.map(withoutFiles).filter((v) => v !== undefined);
+  if (value !== null && typeof value === 'object') {
+    /** @type {Record<string, unknown>} */
+    const out = {};
+    for (const [key, item] of Object.entries(value)) {
+      const kept = withoutFiles(item);
+      if (kept !== undefined) out[key] = kept;
+    }
+    return out;
+  }
+  return value;
+}
+
+/**
+ * Data as multipart, under the names PHP reads back into the same nesting:
+ * `report[tags][]` for a list, `report[title]` for a field. Booleans go as
+ * 1 and 0, and null as an empty string, as an HTML form would send them.
+ *
+ * @param {Record<string, unknown>} data
+ * @returns {FormData}
+ */
+export function toFormData(data) {
+  const out = new FormData();
+
+  /** @param {string} name @param {unknown} value */
+  const append = (name, value) => {
+    if (value === undefined) return;
+    if (isFile(value)) {
+      out.append(name, /** @type {Blob} */ (value));
+    } else if (typeof FileList !== 'undefined' && value instanceof FileList) {
+      for (const file of value) out.append(`${name}[]`, file);
+    } else if (Array.isArray(value)) {
+      for (const item of value) append(`${name}[]`, item);
+    } else if (value instanceof Date) {
+      out.append(name, value.toISOString());
+    } else if (value !== null && typeof value === 'object') {
+      for (const [key, item] of Object.entries(value)) append(`${name}[${key}]`, item);
+    } else if (typeof value === 'boolean') {
+      out.append(name, value ? '1' : '0');
+    } else {
+      out.append(name, value === null ? '' : String(value));
+    }
+  };
+
+  for (const [key, value] of Object.entries(data)) append(key, value);
+  return out;
+}

package/src/form.d.ts

@@ -0,0 +1,177 @@
+import type { FormHTMLAttributes, ReactNode } from 'react';
+import type { ActionTarget } from './action';
+import type { PrecognitionTarget } from './endpoint';
+
+/** Upload progress, while a multipart submission is sent. */
+export interface Progress {
+  loaded: number;
+  total: number | undefined;
+  percentage: number | undefined;
+}
+
+/** What an action answered, as onSuccess sees it. */
+export interface ActionResult {
+  value: unknown;
+  flash: Record<string, unknown>;
+  revalidated: string[];
+  payloads: Record<string, string>;
+  /** Where the action redirected, when it did; the visit has happened. */
+  redirect?: string;
+}
+
+/** A status other than 422, as onHttpException sees it. */
+export interface HttpFailure {
+  status: number;
+  /** The server's machine-readable code, such as `too_many_attempts`. */
+  code: string | null;
+  /** The server's digest for the failure, to quote to support. */
+  reference: string | null;
+  /** Seconds, from Retry-After. */
+  retryAfter: number | null;
+  body: unknown;
+}
+
+/** The visit after a submission: the redirect it follows, or the page it re-renders. */
+export interface VisitOptions {
+  replace?: boolean;
+  preserveScroll?: boolean;
+  preserveState?: boolean;
+  [option: string]: unknown;
+}
+
+/** What a submission does at each step; top-level on `<Form>`, an argument to useForm().submit(). */
+export interface SubmitCallbacks<Data = Record<string, unknown>> {
+  /** Return false to stop the submission. */
+  onBefore?: (data: Data) => boolean | void;
+  onStart?: () => void;
+  onProgress?: (progress: Progress) => void;
+  onSuccess?: (result: ActionResult) => void | Promise<void>;
+  /** 422: the field errors, which the form also shows. */
+  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;
+  onFlash?: (flash: Record<string, unknown>) => void;
+  /** Refused twice for its CSRF token: the page outlived its session, and is being loaded again. */
+  onExpired?: () => void;
+}
+
+/** What `<Form>` hands its children, and useFormContext() returns. */
+export interface FormSlotProps {
+  /** The first message for each field. */
+  errors: Record<string, string>;
+  hasErrors: boolean;
+  processing: boolean;
+  progress: Progress | null;
+  wasSuccessful: boolean;
+  /** True for two seconds after a success. */
+  recentlySuccessful: boolean;
+  isDirty: boolean;
+  /** Puts the named fields -- or every field -- back to their defaults. */
+  reset: (...fields: string[]) => void;
+  submit: () => void;
+  cancel: () => void;
+  setError: {
+    (field: string, message: string): void;
+    (errors: Record<string, string>): void;
+  };
+  clearErrors: (...fields: string[]) => void;
+  /**
+   * What a post made without script sent for a field, to put back as its
+   * default value after the server sent the form back. Never a password.
+   */
+  old: <T = string>(field: string, fallback?: T) => T | undefined;
+  /**
+   * The page outlived its session: a 419 survived the retry with the
+   * refreshed token, or a post made without script was sent back for it.
+   * Not an error screen -- what was typed stays, and the next submit works.
+   */
+  expired: boolean;
+  /** Precognition: asks the action's form request about these fields, after the validation timeout. */
+  validate: (field: string | string[]) => void;
+  /** A Precognition request is out. */
+  validating: boolean;
+  /** Precognition said the field is fine, and nothing has said otherwise since. */
+  valid: (field: string) => boolean;
+  /** The field has an error. */
+  invalid: (field: string) => boolean;
+}
+
+/** Precognition's settings, on `<Form>` and `useForm().withPrecognition()`. */
+export interface PrecognitionSettings {
+  /** How long validate() gathers fields before asking, in ms. 1500 by default. */
+  validationTimeout?: number;
+  /** Send files with a validation request too. Off by default. */
+  validateFiles?: boolean;
+}
+
+export interface FormProps
+  extends
+    SubmitCallbacks,
+    PrecognitionSettings,
+    Omit<FormHTMLAttributes<HTMLFormElement>, 'action' | 'method' | 'children' | 'onError' | 'onProgress'> {
+  /** A reference from `@actions/*`, or the action's name. */
+  action: ActionTarget;
+  /**
+   * What validate() asks in place of the action: an endpoint, by
+   * `endpoint.precognitive()` (ADR 0125). The form still submits to its action.
+   */
+  validateAgainst?: PrecognitionTarget;
+  /** Reshapes the fields before they are sent. */
+  transform?: (data: Record<string, unknown>) => Record<string, unknown>;
+  /** The visit after the submission. */
+  options?: VisitOptions;
+  headers?: Record<string, string>;
+  resetOnSuccess?: boolean | string[];
+  resetOnError?: boolean | string[];
+  /** After a success, what the fields hold becomes what isDirty compares with. */
+  setDefaultsOnSuccess?: boolean;
+  /** Makes the form inert while it is processing. */
+  disableWhileProcessing?: boolean;
+  children?: ReactNode | ((slot: FormSlotProps) => ReactNode);
+}
+
+/**
+ * A real `<form method="post" action="/_action/…">`: an ordinary post before
+ * JavaScript loads, a fetch with the answer applied in place after.
+ */
+export declare function Form(props: FormProps): ReactNode;
+
+/** What a post made without script left for the page: see FlashStore. */
+export interface Flashed {
+  flash?: Record<string, unknown>;
+  form?: {
+    action: string;
+    errors?: Record<string, string[]>;
+    old?: Record<string, unknown>;
+    expired?: boolean;
+  };
+}
+
+/**
+ * The server's per-request state for the forms below it: the CSRF token for
+ * the hidden field, and what a post made without script flashed. Render it
+ * once, around the page, from the app's render entry.
+ */
+export declare function FormSession(props: {
+  csrfToken?: string | null;
+  flash?: Flashed | null;
+  /** A full page load; tests replace it. */
+  hardNavigate?: (url: string) => void;
+  children?: ReactNode;
+}): ReactNode;
+
+/** The flash the page should show: a post's, carried across its redirect, or an action's since. */
+export declare function useFlash(): Record<string, unknown>;
+
+/**
+ * The nearest `<Form>`'s slot props, or the useForm() form a `<FormProvider>`
+ * shares; null outside either. Name the shape you expect.
+ */
+export declare function useFormContext<T = FormSlotProps>(): T | null;
+
+/** How long `recentlySuccessful` stays true, in ms. */
+export declare const RECENTLY_SUCCESSFUL_MS: number;