Form

"use client";

import { useEffect, useId, useRef, useState, useTransition } from "react";
import type { ComponentProps, MouseEvent, ReactNode, SubmitEvent } from "react";
import "./form.css";

/** Every named value in the form. A name that appears more than once, such as a checkbox group, is an array. */
export type FormValues = Record<string, string | string[]>;
/** Error text by field name. */
export type FormErrors = Record<string, string>;
/** What a submit handler may return: field errors from the server, or a message to announce. */
export type FormResult = void | undefined | { errors?: FormErrors; message?: string };

export type FormState = {
  /** Error text by field name, from native constraints, validate and the last result. */
  errors: FormErrors;
  /** True while an async action or onSubmit is running. */
  pending: boolean;
  /** True once a submit has been tried. */
  submitted: boolean;
};

export type FormProps = Omit<ComponentProps<"form">, "action" | "onSubmit" | "children" | "noValidate"> & {
  /** A URL submits natively once the form is valid. A function runs in a transition, with pending state, instead. */
  action?: string | ((data: FormData) => FormResult | Promise<FormResult>);
  /** Runs only when the form is valid. Return or resolve { errors } to show server errors. */
  onSubmit?: (event: SubmitEvent<HTMLFormElement>, data: FormData) => FormResult | Promise<FormResult>;
  /** Extra checks after the native constraints. Return error text by field name. */
  validate?: (values: FormValues, data: FormData) => FormErrors | void;
  /** Heading of the error summary. */
  summaryTitle?: (count: number) => string;
  /** Announced, and shown under the form, after a successful submit. */
  successMessage?: string;
  /** Clears the fields after a successful submit. */
  resetOnSuccess?: boolean;
  /** Plain nodes, or a function that receives the errors and pending state to pass on to fields and buttons. */
  children?: ReactNode | ((state: FormState) => ReactNode);
};

type Entry = { key: string; label: string; message: string };
type Control = HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement;

const FOCUSABLE =
  'input:not([type="hidden"]):not(:disabled), select:not(:disabled), textarea:not(:disabled), button:not(:disabled), [tabindex]:not([tabindex="-1"])';

function isControl(el: Element): el is Control {
  return el instanceof HTMLInputElement || el instanceof HTMLSelectElement || el instanceof HTMLTextAreaElement;
}

function toValues(data: FormData): FormValues {
  const values: FormValues = {};
  for (const [key, entry] of data) {
    const text = typeof entry === "string" ? entry : entry.name;
    const had = values[key];
    values[key] = had === undefined ? text : Array.isArray(had) ? [...had, text] : [had, text];
  }
  return values;
}

/** Readable text of a label, without the text of controls or hidden decoration nested inside it. */
function textOf(el: Element | null | undefined) {
  if (!el) return "";
  const copy = el.cloneNode(true) as Element;
  for (const inner of copy.querySelectorAll('button, input, select, textarea, [aria-hidden="true"]')) inner.remove();
  return copy.textContent?.replace(/\s+/g, " ").trim() || "";
}

/** The name a person would recognise: the group legend for radios, else the control's own label. */
function labelOf(el: Control, key: string): string {
  const root = el.ownerDocument;
  if (el instanceof HTMLInputElement && (el.type === "radio" || el.type === "checkbox")) {
    const legend = textOf(el.closest("fieldset")?.querySelector(":scope > legend"));
    if (legend && el.form?.querySelectorAll(`[name="${CSS.escape(el.name)}"]`).length !== 1) return legend;
  }
  const labelledBy = el.getAttribute("aria-labelledby");
  if (labelledBy) {
    const text = labelledBy.split(/\s+/).map((id) => textOf(root.getElementById(id))).join(" ").trim();
    if (text) return text;
  }
  const aria = el.getAttribute("aria-label");
  if (aria && el.getAttribute("aria-hidden") !== "true") return aria;
  const own = textOf(el.labels?.[0]);
  if (own) return own;
  // A hidden input carries the value of a composite part; its label sits beside it in the part root.
  const near = textOf(el.parentElement?.querySelector("label, legend"));
  return near || key;
}

/** Where a summary link sends focus: the control itself, the checked radio, or the nearest focusable control in its part. */
function targetFor(form: HTMLFormElement, key: string): HTMLElement | null {
  const item = form.elements.namedItem(key);
  let el: Element | null = null;
  if (item instanceof RadioNodeList) {
    const all = Array.from(item);
    el = all.find((node) => node instanceof HTMLInputElement && node.checked) ?? all[0] ?? null;
  } else el = item;
  if (!(el instanceof HTMLElement)) return null;
  const hidden = el instanceof HTMLInputElement && el.type === "hidden";
  if (!hidden && !el.matches(":disabled")) return el;
  // A hidden value: go to the part's invalid control if it has one, else its first control.
  const root = el.parentElement;
  return (
    root?.querySelector<HTMLElement>(':is(input:not([type="hidden"]), select, textarea):invalid') ??
    root?.querySelector<HTMLElement>(FOCUSABLE) ??
    null
  );
}

/**
 * The name a control's error is filed under. A composite part may show a visible input without a
 * name and submit through a hidden one beside it; the error then belongs to the hidden one's name.
 */
function keyOf(el: Control): string {
  if (el.name) return el.name;
  let parent = el.parentElement;
  for (let depth = 0; depth < 3 && parent && parent !== el.form; depth++, parent = parent.parentElement) {
    const hidden = parent.querySelector<HTMLInputElement>(':scope > input[type="hidden"][name]');
    if (hidden) return hidden.name;
  }
  return el.id;
}

const same = (a: Entry[], b: Entry[]) =>
  a.length === b.length && a.every((e, i) => e.key === b[i].key && e.message === b[i].message && e.label === b[i].label);

export function Form({
  action,
  onSubmit,
  validate,
  summaryTitle = (count) => (count === 1 ? "Fix 1 field to continue" : `Fix ${count} fields to continue`),
  successMessage = "Sent.",
  resetOnSuccess = false,
  className,
  children,
  ref,
  onInput,
  onChange,
  onClick,
  onKeyUp,
  onReset,
  ...rest
}: FormProps) {
  const id = useId();
  const formRef = useRef<HTMLFormElement | null>(null);
  const summaryRef = useRef<HTMLDivElement>(null);
  const locked = useRef(false);
  const custom = useRef<Control[]>([]);
  /** Errors from a submit result, kept until the field's value changes. */
  const server = useRef<Record<string, { message: string; value: string }>>({});
  const timer = useRef<ReturnType<typeof setTimeout> | undefined>(undefined);

  const [entries, setEntries] = useState<Entry[]>([]);
  const [failure, setFailure] = useState("");
  const [message, setMessage] = useState("");
  const [submitted, setSubmitted] = useState(false);
  const [attempt, setAttempt] = useState(0);
  const [pending, startTransition] = useTransition();

  // After a failed submit the summary takes focus, so it is read out and the links are one Tab away.
  useEffect(() => {
    if (attempt > 0) summaryRef.current?.focus();
  }, [attempt]);

  useEffect(() => () => clearTimeout(timer.current), []);

  /** Runs native constraints and validate, marks custom errors on their controls, and returns the list in DOM order. */
  function check(form: HTMLFormElement): Entry[] {
    for (const el of custom.current) el.setCustomValidity("");
    custom.current = [];
    const data = new FormData(form);
    const values = toValues(data);
    const extra: FormErrors = { ...(validate?.(values, data) ?? {}) };
    for (const [key, saved] of Object.entries(server.current)) {
      const now = values[key];
      const text = Array.isArray(now) ? now.join("\n") : (now ?? "");
      if (text === saved.value) extra[key] ??= saved.message;
      else delete server.current[key];
    }

    for (const [key, text] of Object.entries(extra)) {
      if (!text) continue;
      const item = form.elements.namedItem(key);
      const el = item instanceof RadioNodeList ? item[0] : item;
      // A control whose own part already set a message keeps it; only messages set here are cleared later.
      if (el && isControl(el) && el.willValidate && !el.validity.customError) {
        el.setCustomValidity(text);
        custom.current.push(el);
      }
    }

    const list: Entry[] = [];
    const seen = new Set<string>();
    for (const el of Array.from(form.elements)) {
      if (!isControl(el)) continue;
      const key = keyOf(el);
      if (!key || seen.has(key)) continue;
      const text = extra[key] || (el.willValidate && !el.validity.valid ? el.validationMessage : "");
      if (!text) continue;
      seen.add(key);
      list.push({ key, label: labelOf(el, key), message: text });
    }
    // Errors for names no control carries still show, under their own name.
    for (const [key, text] of Object.entries(extra)) {
      if (text && !seen.has(key)) list.push({ key, label: key, message: text });
    }
    return list;
  }

  function show(list: Entry[]) {
    setEntries((prev) => (same(prev, list) ? prev : list));
  }

  function remember(form: HTMLFormElement, errors: FormErrors) {
    const values = toValues(new FormData(form));
    for (const [key, text] of Object.entries(errors)) {
      const now = values[key];
      server.current[key] = { message: text, value: Array.isArray(now) ? now.join("\n") : (now ?? "") };
    }
  }

  function handleSubmit(event: SubmitEvent<HTMLFormElement>) {
    const form = event.currentTarget;
    // The ref answers at once; pending state lags a fast double click by a render.
    if (locked.current) {
      event.preventDefault();
      return;
    }
    setMessage("");
    setFailure("");
    setSubmitted(true);
    const list = check(form);
    show(list);
    if (list.length > 0) {
      event.preventDefault();
      setAttempt((n) => n + 1);
      return;
    }
    if (typeof action !== "function" && !onSubmit) return; // A URL, or the page itself: let the browser submit.

    event.preventDefault();
    locked.current = true;
    const data = new FormData(form, event.nativeEvent.submitter);
    startTransition(async () => {
      try {
        const results = [onSubmit ? await onSubmit(event, data) : undefined];
        if (typeof action === "function") results.push(await action(data));
        const errors: FormErrors = Object.assign({}, ...results.map((r) => r?.errors ?? {}));
        if (Object.keys(errors).length > 0) {
          remember(form, errors);
          show(check(form));
          setAttempt((n) => n + 1);
          return;
        }
        if (resetOnSuccess) {
          form.reset();
          setSubmitted(false);
        }
        setMessage(results.map((r) => r?.message).find(Boolean) ?? successMessage);
      } catch (error) {
        // Caught here so a failed request reports in the form rather than reaching an error boundary.
        setFailure(error instanceof Error && error.message ? error.message : "Something went wrong. Try again.");
        setAttempt((n) => n + 1);
      } finally {
        locked.current = false;
      }
    });
  }

  /** Once a submit has failed, the summary follows every edit, a tick later so composite parts have settled. */
  function recheck() {
    if (!submitted || locked.current) return;
    clearTimeout(timer.current);
    timer.current = setTimeout(() => {
      if (formRef.current) show(check(formRef.current));
    }, 0);
  }

  function focusField(event: MouseEvent<HTMLAnchorElement>, key: string) {
    event.preventDefault();
    const form = formRef.current;
    const target = form && targetFor(form, key);
    if (!target) return;
    target.focus({ preventScroll: true });
    target.scrollIntoView({ block: "center", behavior: "smooth" });
  }

  const errors: FormErrors = Object.fromEntries(entries.map((e) => [e.key, e.message]));
  const titleId = `${id}-summary`;
  const showSummary = entries.length > 0 || failure !== "";

  return (
    <form
      {...rest}
      ref={(node) => {
        formRef.current = node;
        if (typeof ref === "function") return ref(node);
        if (ref) ref.current = node;
      }}
      noValidate
      action={typeof action === "string" ? action : undefined}
      className={["eq-form", className].filter(Boolean).join(" ")}
      aria-busy={pending || undefined}
      data-pending={pending || undefined}
      data-submitted={submitted || undefined}
      onSubmit={handleSubmit}
      onInput={(event) => {
        onInput?.(event);
        recheck();
      }}
      onChange={(event) => {
        onChange?.(event);
        recheck();
      }}
      onClick={(event) => {
        onClick?.(event);
        recheck();
      }}
      onKeyUp={(event) => {
        onKeyUp?.(event);
        recheck();
      }}
      onReset={(event) => {
        onReset?.(event);
        // A reset starts over: no summary, no result, no stored server errors.
        clearTimeout(timer.current);
        for (const el of custom.current) el.setCustomValidity("");
        custom.current = [];
        server.current = {};
        setEntries([]);
        setFailure("");
        setMessage("");
        setSubmitted(false);
      }}
    >
      {showSummary && (
        <div className="eq-form-summary" ref={summaryRef} tabIndex={-1} aria-labelledby={titleId}>
          <p className="eq-form-summary-title" id={titleId}>
            {failure && entries.length === 0 ? "The form was not sent" : summaryTitle(entries.length)}
          </p>
          {failure && <p className="eq-form-summary-text">{failure}</p>}
          {entries.length > 0 && (
            <ul className="eq-form-summary-list">
              {entries.map((entry) => (
                <li key={entry.key}>
                  <a className="eq-form-summary-link" href={`#${entry.key}`} onClick={(event) => focusField(event, entry.key)}>
                    <span className="eq-form-summary-field">{entry.label}:</span> {entry.message}
                  </a>
                </li>
              ))}
            </ul>
          )}
        </div>
      )}
      {typeof children === "function" ? children({ errors, pending, submitted }) : children}
      {/* Always mounted, so the message is announced when it arrives. */}
      <p className="eq-form-status" role="status">
        {message && (
          <>
            <svg viewBox="0 0 16 16" fill="none" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
              <path d="m4 8.5 2.5 2.5L12 5.5" />
            </svg>
            {message}
          </>
        )}
      </p>
    </form>
  );
}

export type FormSectionProps = Omit<ComponentProps<"fieldset">, "title"> & {
  /** The section's legend. */
  title: ReactNode;
  /** A line under the title, read as the group's description. */
  description?: ReactNode;
};

export function FormSection({ title, description, className, children, "aria-describedby": describedBy, ...rest }: FormSectionProps) {
  const id = useId();
  const descriptionId = description ? `${id}-description` : undefined;
  return (
    <fieldset
      {...rest}
      className={["eq-form-section", className].filter(Boolean).join(" ")}
      aria-describedby={[describedBy, descriptionId].filter(Boolean).join(" ") || undefined}
    >
      <legend className="eq-form-section-title">{title}</legend>
      {description && (
        <p className="eq-form-section-description" id={descriptionId}>
          {description}
        </p>
      )}
      <div className="eq-form-section-body">{children}</div>
    </fieldset>
  );
}

export type FormActionsProps = ComponentProps<"div"> & {
  /** Where the buttons sit. "between" pushes the first button to the start. */
  align?: "start" | "end" | "between";
  /** Keeps the row at the bottom of the scrolling area while the form scrolls under it. */
  sticky?: boolean;
};

export function FormActions({ align = "end", sticky = false, className, ...rest }: FormActionsProps) {
  return (
    <div
      {...rest}
      className={["eq-form-actions", className].filter(Boolean).join(" ")}
      data-align={align}
      data-sticky={sticky || undefined}
    />
  );
}