form.state

export type FormActionType = "change" | "blur" | "validated" | "submit" | "submitted" | "failed" | "reset";

export type FormStatus = "editing" | "submitting" | "submitted";

/** One thing that happened to the form. */
export interface FormAction {
  readonly type: FormActionType;
  /** the field, for change and blur */
  readonly name?: string;
  /** the new value, for change */
  readonly value?: string;
  /** field name to message: for validated (a validate-* capability's fields), and for failed (the server's) */
  readonly errors?: Readonly<Record<string, string>>;
}

/** Everything a form needs to render, as plain data. */
export interface FormState {
  /** each field's current value, in the form's order */
  readonly values: Readonly<Record<string, string>>;
  /** the values reset goes back to */
  readonly initial: Readonly<Record<string, string>>;
  /** fields the person has left, or every field once they have tried to submit; in the form's order */
  readonly touched: readonly string[];
  /** the latest validation: field name to message */
  readonly errors: Readonly<Record<string, string>>;
  /** how many times the person has tried to submit */
  readonly submitCount: number;
  /** submitting while a valid submit is in flight, submitted once it succeeded */
  readonly status: FormStatus;
}

export function initialFormState(values: Readonly<Record<string, string>>): FormState

import { initialFormState } from "#fune/form.state@^1";

import type { FormState } from "./form_state_types.ts";

/**
 * A fresh form: the values as given, nothing touched, no errors, never
 * submitted. The values' order is the form's order, which visibleErrors
 * keeps so an error summary lists problems top to bottom.
 */
export function initialFormState(values: Readonly<Record<string, string>>): FormState {
  const copy: Record<string, string> = {};
  for (const [name, value] of Object.entries(values)) {
    if (name === "") throw new Error("a field name must not be empty");
    if (typeof value !== "string") throw new Error(`the value of field "${name}" must be a string`);
    copy[name] = value;
  }
  return { values: copy, initial: { ...copy }, touched: [], errors: {}, submitCount: 0, status: "editing" };
}

export function formReducer(state: FormState, action: FormAction): FormState

import { formReducer } from "#fune/form.state@^1";

import type { FormAction, FormState } from "./form_state_types.ts";

/**
 * The next state of a form after one action. Pure: the state passed in is
 * never changed, so it works as React's useReducer reducer, in a test, on a
 * server or in any other framework's store.
 */
export function formReducer(state: FormState, action: FormAction): FormState {
  switch (action.type) {
    case "change": {
      const name = fieldName(state, action, "change");
      if (typeof action.value !== "string") throw new Error("a change action needs a value");
      // Editing after a successful submit means the form no longer matches
      // what was sent; during a submit the request is already in flight.
      const status = state.status === "submitted" ? "editing" : state.status;
      return { ...copy(state), values: { ...state.values, [name]: action.value }, status };
    }
    case "blur": {
      const name = fieldName(state, action, "blur");
      return { ...copy(state), touched: inFormOrder(state, [...state.touched, name]) };
    }
    case "validated": {
      if (action.errors === undefined || action.errors === null) throw new Error("a validated action needs errors");
      return { ...copy(state), errors: { ...action.errors } };
    }
    case "submit": {
      // A second click while the first submit is in flight changes nothing.
      if (state.status === "submitting") return copy(state);
      const valid = Object.keys(state.errors).length === 0;
      return {
        ...copy(state),
        touched: Object.keys(state.values),
        submitCount: state.submitCount + 1,
        status: valid ? "submitting" : "editing",
      };
    }
    case "submitted": {
      if (state.status !== "submitting") throw new Error("no submit is in progress");
      return { ...copy(state), status: "submitted" };
    }
    case "failed": {
      if (state.status !== "submitting") throw new Error("no submit is in progress");
      return { ...copy(state), errors: { ...(action.errors ?? {}) }, status: "editing" };
    }
    case "reset":
      return {
        values: { ...state.initial },
        initial: { ...state.initial },
        touched: [],
        errors: {},
        submitCount: 0,
        status: "editing",
      };
    default:
      throw new Error(`unknown form action type "${String((action as { type: unknown }).type)}"`);
  }
}

function copy(state: FormState): FormState {
  return {
    values: { ...state.values },
    initial: { ...state.initial },
    touched: [...state.touched],
    errors: { ...state.errors },
    submitCount: state.submitCount,
    status: state.status,
  };
}

function fieldName(state: FormState, action: FormAction, type: string): string {
  const name = action.name;
  if (typeof name !== "string" || name === "") throw new Error(`a ${type} action needs a name`);
  if (!Object.prototype.hasOwnProperty.call(state.values, name)) throw new Error(`unknown field "${name}"`);
  return name;
}

// Touched fields, once each, in the order of the form's values.
function inFormOrder(state: FormState, names: readonly string[]): string[] {
  const set = new Set(names);
  return Object.keys(state.values).filter((name) => set.has(name));
}

export function visibleErrors(state: FormState): Readonly<Record<string, string>>

import { visibleErrors } from "#fune/form.state@^1";

import type { FormState } from "./form_state_types.ts";

/**
 * The error messages to show now. GOV.UK validates when the person submits,
 * not as they type or leave a field, so nothing shows before the first submit
 * attempt; after it, every error shows (a submit touches every field), and
 * keeps showing until a validated action clears it. Fields come in the form's
 * order, then any error for a name that is not a field (a form-wide message
 * from the server) in the order given. An empty message is no error.
 */
export function visibleErrors(state: FormState): Readonly<Record<string, string>> {
  const shown: Record<string, string> = {};
  if (state.submitCount === 0) return shown;
  const touched = new Set(state.touched);
  for (const name of Object.keys(state.values)) {
    const message = state.errors[name];
    if (touched.has(name) && typeof message === "string" && message !== "") shown[name] = message;
  }
  for (const [name, message] of Object.entries(state.errors)) {
    if (!(name in shown) && !Object.prototype.hasOwnProperty.call(state.values, name) && message !== "") shown[name] = message;
  }
  return shown;
}

Install

fune build

With that line in your source, in a TypeScript project (language typescript in fune.project), fune build resolves it and nothing else, pins them in fune.lock, downloads only the TypeScript package of each, and builds the code above into your project’s .fune/build, one readable file per capability with a header linking back here. Or pin a range in fune.project and build in one step:

fune add form.state

That builds the whole group. To build only what you call, and whatever it uses inside the group:

fune add form.state --only initialFormState

The manifest, vectors and README with only the TypeScript implementation. Install it without the registry with fune add ./form.state-1.0.1-typescript.fune, or fetch it from a terminal with fune pull form.state@1.0.1:typescript.

It is TypeScript only, so there is no package for Python or Rust. The full package is one file too: form.state-1.0.1.fune, 40,615 bytes, sha256 e87c728a244fcbb1336f68a8bc50ca6be08eb2194ab9d3a2a40882aa71372d5d.

// fune: before form.state.initialFormState
// fune: before form.state.formReducer
// fune: before form.state.visibleErrors

// fune: after form.state.initialFormState
// fune: after form.state.formReducer
// fune: after form.state.visibleErrors

// fune: step form.state.<fn> after <n|label>

More from the author

It holds no validation of its own. A `validate-*` capability (`auth.validate-registration`, `auth.validate-login`...) checks the values and its `fields` (field name to message) is dispatched as a `validated` action, so the browser and the API use the very same check.

## With React

"use client";
import { useReducer, type FormEvent } from "react";
import { formReducer, initialFormState, visibleErrors } from "#fune/form.state@^1";
import { validateRegistration } from "#fune/auth.validate-registration@^1";
import { passwordPolicy } from "#fune/auth.password-policy@^1";
import { TextField } from "#fune/react.form.text-field@^1";
import { PasswordField } from "#fune/react.form.password-field@^1";
import { ErrorSummary, errorSummaryItems } from "#fune/react.form.error-summary@^1";
import { Button } from "#fune/react.form.button@^1";

const policy = passwordPolicy("nist-800-63b-4-single-factor");
const ORDER = ["email", "password", "name"];

export function SignUp() {
  const [state, dispatch] = useReducer(formReducer, initialFormState({ email: "", password: "", name: "" }));
  const visible = visibleErrors(state);
  const field = (name: string) => ({
    id: name,
    value: state.values[name],
    error: visible[name],
    onChange: (value: string) => dispatch({ type: "change", name, value }),
    onBlur: () => dispatch({ type: "blur", name }),
  });

  async function onSubmit(event: FormEvent) {
    event.preventDefault();
    if (state.status === "submitting") return;   // a double click: one request is enough
    const { email, password, name } = state.values;
    const check = validateRegistration(email, password, name, policy);
    dispatch({ type: "validated", errors: check.fields });
    dispatch({ type: "submit" });                // counts the attempt; submitting only if no errors
    // dispatch is queued: state is still the old value here, so decide from check.valid
    if (!check.valid) return;
    const response = await fetch("/api/register", { method: "POST", body: JSON.stringify(state.values) });
    if (response.ok) dispatch({ type: "submitted" });
    else dispatch({ type: "failed", errors: (await response.json()).fields ?? {} });
  }

  return (
    <form onSubmit={onSubmit} noValidate>
      <ErrorSummary items={errorSummaryItems(visible, ORDER, {})} />
      <TextField label="Email address" type="email" autoComplete="email" spellCheck={false} {...field("email")} />
      <PasswordField label="Password" autoComplete="new-password" policy={policy} {...field("password")} />
      <TextField label="Full name" autoComplete="name" {...field("name")} />
      <Button loading={state.status === "submitting"}>Create account</Button>
    </form>
  );
}

`dispatch` does not change `state` straight away: React applies the actions before the next render, in order, so `validated` then `submit` sees the new errors, but the code after them still sees the old state. That is why the fetch is decided by `check.valid`. To re-check as the person types, dispatch `validated` after each `change` too: nothing shows until they have tried to submit, and after that each message goes as soon as the field is fixed, which is what GOV.UK recommends.

## Why a reducer and not a hook

A hook can only run inside a React component, and nothing that runs there can be checked by a vector. A reducer is a pure function: every transition above is pinned by a test case in `vectors.json`, it runs the same in a unit test, in a server action rebuilding a form after a failed post, in a Web Worker, or in another framework's store (Redux, Zustand, Vue, Svelte, plain `let state = formReducer(state, action)`). `useReducer` is all the glue React needs.

## The state

| Field | Meaning | |---|---| | `values` | each field's current value, in the form's order | | `initial` | the values `reset` goes back to | | `touched` | the fields the person has left (`blur`), or every field once they have tried to submit; in the form's order | | `errors` | the latest validation, field name to message | | `submitCount` | how many times they have tried to submit | | `status` | `editing`, `submitting` (a valid submit is in flight) or `submitted` (it succeeded) |

The order of `values` is the order of the form, and `touched` and `visibleErrors` keep it, so an error summary lists problems top to bottom whatever order the validator found them in. (JavaScript orders object keys that look like whole numbers, `"0"`, `"12"`, before all others, so do not name fields that way.)

## The actions

| Action | Effect | |---|---| | `{ type: "change", name, value }` | sets one value. Leaves the errors as they were until the next `validated`. Returns a `submitted` form to `editing`, since it no longer matches what was sent. | | `{ type: "blur", name }` | marks the field touched | | `{ type: "validated", errors }` | replaces the errors with the validator's `fields`; `{}` clears them | | `{ type: "submit" }` | counts the attempt and touches every field; `submitting` only when there are no errors. Ignored while a submit is already in flight (a double click). | | `{ type: "submitted" }` | the submit succeeded | | `{ type: "failed", errors? }` | the submit failed; the server's errors (such as "An account with this email already exists") replace the errors, or none if it just failed (then say so in your own message) | | `{ type: "reset" }` | back to the initial values, untouched, no errors, never submitted |

Loud errors, so a typo is caught the first time it runs: an unknown `type` (`unknown form action type "submitt"`), a `change` or `blur` without a `name` (`a change action needs a name`), a name the form does not have (`unknown field "emial"`), a `change` without a `value`, a `validated` without `errors`, and `submitted` or `failed` when no submit is in progress. The input state is never changed; every action answers a new one.

## Which errors are visible

GOV.UK validates when the person submits, not as they type or when they leave a field, because messages that appear mid-answer interrupt and confuse. So `visibleErrors` shows nothing before the first submit attempt. After it, it shows the error of every touched field (a submit touches them all), in the form's order, then any message for a name that is not a field (a form-wide error from the server) in the order given. An empty message counts as no error. `touched` is kept anyway, for a form that chooses to show an error when the person leaves a field: filter `state.errors` by `state.touched` yourself.

## Other kinds of field

Every value is a string, as the browser submits it. A single checkbox is its value when ticked (`"yes"`) and `""` when not. A checkbox group (`react.form.checkbox-group`) is its ticked values joined with commas: `values={state.values.contact ? state.values.contact.split(",") : []}` and `onChange={(ticked) => dispatch({ type: "change", name: "contact", value: ticked.join(",") })}`. The option values are your own codes, so keep commas out of them. Radios and selects are their one value; a date is three fields (`dob-day`, `dob-month`, `dob-year`) or one ISO string, whichever your validator reads.

A note on the vectors: the harness compares maps without regard to key order, so the form's order in `visibleErrors` is stated here and implemented, but pinned by the vectors only for `touched`, which is a list.

Sources: GOV.UK Design System, "Validation" pattern https://design-system.service.gov.uk/patterns/validation/ and "Error summary" https://design-system.service.gov.uk/components/error-summary/; React, `useReducer` https://react.dev/reference/react/useReducer.

## Notices

Portions derived from GOV.UK Frontend (https://github.com/alphagov/govuk-frontend), Copyright (c) 2017 Crown Copyright (Government Digital Service), under the MIT License; the full notice is in NOTICE.

1.0.1 adds its attribution notices (NOTICE). The code and the tests are unchanged.

Files