components/field/field.ts

Functions

Imports

It imports no other module of this repo. Imported by components/people-roles/people-roles.react.tsx, components/people-roles/people-roles.ts, components/switch-reason/switch-reason.ts.

Source

1// The field's behaviour: check a field when it is left and every field on submit, with the
2// platform's constraint validation (required, type, pattern, min, max...), write the
3// message into the field's .cap-field-error, set aria-invalid, and on a failed submit move
4// focus to the first field in error. No framework; the React wrapper and switch-reason use
5// the same functions.
6
7export type Control = HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement;
8
9// The ValidityState flags, in the order a message is chosen. A control can override each
10// with a data attribute: data-error-value-missing, data-error-type-mismatch, and so on.
11const FLAGS = ["valueMissing", "typeMismatch", "patternMismatch", "tooShort", "tooLong", "rangeUnderflow", "rangeOverflow", "stepMismatch", "badInput"] as const;
12
13let serial = 0;
14
15export function isControl(el: unknown): el is Control {
16  return el instanceof HTMLInputElement || el instanceof HTMLSelectElement || el instanceof HTMLTextAreaElement;
17}
18
19// What to say about a control, or "" when it is valid. The control's own words first,
20// then the browser's.
21export function messageFor(control: Control): string {
22  const v = control.validity;
23  if (v.valid) return "";
24  if (v.customError) return control.validationMessage;
25  for (const flag of FLAGS) {
26    if (!v[flag]) continue;
27    const own = control.dataset[`error${flag.charAt(0).toUpperCase()}${flag.slice(1)}`];
28    if (own) return own;
29  }
30  return control.dataset.error || control.validationMessage;
31}
32
33// The controls that share one message: a radio group, or the control alone.
34export function groupOf(control: Control): Control[] {
35  if (control instanceof HTMLInputElement && control.type === "radio" && control.name && control.form) {
36    return [...control.form.querySelectorAll<HTMLInputElement>(`input[type="radio"][name="${CSS.escape(control.name)}"]`)];
37  }
38  return [control];
39}
40
41// The control a check is about: the select behind an enhanced select's button.
42function controlOf(el: unknown): Control | null {
43  if (isControl(el)) return el;
44  if (el instanceof HTMLElement && el.classList.contains("cap-select-trigger")) return el.closest(".cap-select-wrap")?.querySelector<HTMLSelectElement>("select.cap-select") ?? null;
45  return null;
46}
47
48export function errorFor(control: Control): HTMLElement | null {
49  return control.closest(".cap-field")?.querySelector<HTMLElement>(".cap-field-error") ?? null;
50}
51
52function describe(control: Control, id: string): void {
53  const ids = (control.getAttribute("aria-describedby") ?? "").split(/\s+/).filter(Boolean);
54  if (!ids.includes(id)) control.setAttribute("aria-describedby", [id, ...ids].join(" "));
55}
56
57// Shows a message beside a control. `announce` gives it role="alert": only for an error
58// that appears after a submit; one found on leaving a field is read through
59// aria-describedby when the field is next focused.
60export function showError(control: Control, text: string, announce = false): void {
61  const el = errorFor(control);
62  for (const c of groupOf(control)) c.setAttribute("aria-invalid", "true");
63  control.closest(".cap-field")?.setAttribute("data-invalid", "true");
64  if (!el) return;
65  if (!el.id) el.id = `cap-field-error-${++serial}`;
66  for (const c of groupOf(control)) describe(c, el.id);
67  if (announce) el.setAttribute("role", "alert");
68  else if (el.hidden || el.textContent !== text) el.removeAttribute("role");
69  el.textContent = text;
70  el.hidden = false;
71}
72
73export function clearError(control: Control): void {
74  for (const c of groupOf(control)) c.removeAttribute("aria-invalid");
75  control.closest(".cap-field")?.removeAttribute("data-invalid");
76  const el = errorFor(control);
77  if (!el) return;
78  el.removeAttribute("role");
79  el.textContent = "";
80  el.hidden = true;
81}
82
83// Checks one control and shows or clears its message. True when it is valid.
84export function validate(control: Control, announce = false): boolean {
85  const text = messageFor(control);
86  if (text) showError(control, text, announce);
87  else clearError(control);
88  return !text;
89}
90
91// Checks every field of a form. On failure, announces the messages that were not already
92// showing and moves focus to the first field in error. True when the form is valid.
93export function validateForm(form: HTMLFormElement): boolean {
94  const seen = new Set<string>();
95  let first: Control | null = null;
96  for (const el of form.elements) {
97    if (!isControl(el) || !el.willValidate) continue;
98    if (el instanceof HTMLInputElement && el.type === "radio" && el.name) {
99      if (seen.has(el.name)) continue;
100      seen.add(el.name);
101    }
102    const was = el.getAttribute("aria-invalid") === "true";
103    const ok = validate(el, !was);
104    if (!ok && !first) first = el;
105  }
106  if (first) first.focus();
107  return first === null;
108}
109
110// A click on an input group's text or icon addon puts the cursor in its field, as a click
111// on the field itself would (a button in the addon keeps its own click).
112function groupClick(e: MouseEvent): void {
113  const target = e.target as HTMLElement | null;
114  const addon = target?.closest<HTMLElement>(".cap-input-addon");
115  if (!addon || target?.closest("button, a, input, select, textarea")) return;
116  addon.parentElement?.querySelector<HTMLElement>("input, textarea")?.focus();
117}
118
119// Attaches to every form[data-cap="field"] under root that is not attached yet. The form
120// gets novalidate, so the browser's own bubbles give way to the messages beside the
121// fields. Returns a function that detaches them all.
122export function enhance(root: ParentNode = document): () => void {
123  const undo: Array<() => void> = [];
124  for (const group of root.querySelectorAll<HTMLElement>(".cap-input-group:not([data-cap-ready])")) {
125    group.dataset.capReady = "";
126    group.addEventListener("click", groupClick);
127    undo.push(() => {
128      group.removeEventListener("click", groupClick);
129      delete group.dataset.capReady;
130    });
131  }
132  for (const form of root.querySelectorAll<HTMLFormElement>("form[data-cap='field']:not([data-cap-ready])")) {
133    form.dataset.capReady = "";
134    const hadNoValidate = form.noValidate;
135    form.noValidate = true;
136
137    // A field is checked on leaving only once it has been changed, so tabbing through an
138    // empty form does not fill it with errors. A field showing an error is checked again
139    // as it is typed in, so the message goes as soon as it is fixed.
140    const onInput = (e: Event) => {
141      const c = e.target;
142      if (!isControl(c)) return;
143      c.dataset.capDirty = "";
144      if (c.getAttribute("aria-invalid") === "true") validate(c);
145    };
146    const onLeave = (e: FocusEvent) => {
147      const c = controlOf(e.target);
148      if (c && c.dataset.capDirty !== undefined && c.willValidate) validate(c);
149    };
150    // Capture, and stopped there, so an app's own submit handler runs only for a valid form.
151    const onSubmit = (e: SubmitEvent) => {
152      if (!validateForm(form)) {
153        e.preventDefault();
154        e.stopImmediatePropagation();
155      }
156    };
157    form.addEventListener("input", onInput);
158    form.addEventListener("change", onInput);
159    form.addEventListener("focusout", onLeave);
160    form.addEventListener("submit", onSubmit, { capture: true });
161    undo.push(() => {
162      form.removeEventListener("input", onInput);
163      form.removeEventListener("change", onInput);
164      form.removeEventListener("focusout", onLeave);
165      form.removeEventListener("submit", onSubmit, { capture: true });
166      form.noValidate = hadNoValidate;
167      delete form.dataset.capReady;
168    });
169  }
170  return () => undo.forEach((f) => f());
171}