Add hook to check form validity on submission

By default forms handle validation automatically when submitted, displaying an
error message and focusing the first control with an error. This hook is useful
if the caller wants to customize how validation error messages are presented on
submission.

Author: robertknight

src/hooks/test/use-validate-on-submit-test.js

@@ -0,0 +1,134 @@
+import { mount } from 'enzyme';
+import { useState, useId } from 'preact/hooks';
+
+import { Input } from '../../components/input';
+import { useValidateOnSubmit } from '../use-validate-on-submit';
+
+// Example of a simple form that uses this hook to implement custom display of
+// validation messages.
+function CustomForm({ onSelectURL }) {
+  const [url, setURL] = useState();
+  const [error, setError] = useState();
+  const errorId = useId();
+
+  const onSubmit = useValidateOnSubmit(() => {
+    onSelectURL(url);
+  });
+
+  const onChangeURL = event => {
+    const url = event.target.value;
+    setURL(undefined);
+
+    try {
+      new URL(url);
+      setError(undefined);
+      setURL(url);
+    } catch {
+      setError('Not a valid URL');
+    }
+  };
+
+  return (
+    <form onSubmit={onSubmit} noValidate>
+      <Input
+        onChange={onChangeURL}
+        required
+        aria-label="URL"
+        aria-describedby={errorId}
+        error={error}
+      />
+      <div id={errorId}>{error}</div>
+      <button type="submit">Submit</button>
+    </form>
+  );
+}
+
+describe('useValidateOnSubmit', () => {
+  function changeURL(form, url) {
+    const input = form.find('input');
+    input.getDOMNode().value = url;
+    input.simulate('change');
+  }
+
+  function submitForm(form) {
+    form.find('form').simulate('submit');
+  }
+
+  it('should invoke callback if form has no errors', () => {
+    const onSelectURL = sinon.stub();
+    const form = mount(<CustomForm onSelectURL={onSelectURL} />);
+    changeURL(form, 'https://example.com');
+    submitForm(form);
+    assert.calledWith(onSelectURL, 'https://example.com');
+  });
+
+  it('should invoke change event for empty, required inputs', () => {
+    const onSelectURL = sinon.stub();
+    const form = mount(<CustomForm onSelectURL={onSelectURL} />);
+    const input = form.find('input');
+    const onChange = sinon.stub();
+    input.getDOMNode().addEventListener('change', onChange);
+
+    submitForm(form);
+
+    assert.notCalled(onSelectURL);
+    assert.calledOnce(onChange);
+  });
+
+  it('should not invoke callback if form has errors', () => {
+    const onSelectURL = sinon.stub();
+    const form = mount(<CustomForm onSelectURL={onSelectURL} />);
+    changeURL(form, 'not valid');
+    submitForm(form);
+    assert.notCalled(onSelectURL);
+  });
+
+  it('should focus first input with an error', () => {
+    const onSelectURL = sinon.stub();
+    const form = mount(<CustomForm onSelectURL={onSelectURL} />);
+    changeURL(form, 'not valid');
+
+    const input = form.find('input').getDOMNode();
+    const focusStub = sinon.stub(input, 'focus');
+    submitForm(form);
+
+    assert.calledOnce(focusStub);
+  });
+
+  // Create a fake `Event` for which we can control the `target` property.
+  // We do this in order to call the event handler directly, rather than
+  // using `target.dispatchEvent`. This makes catching the exception easier.
+  function createFakeEvent({ type, target }) {
+    return { type, target, preventDefault: sinon.stub() };
+  }
+
+  it('should throw if handler received non-"submit" event', () => {
+    function InvalidUsage() {
+      const onSubmit = useValidateOnSubmit(() => {});
+
+      // eslint-disable-next-line
+      return <form onClick={onSubmit} />;
+    }
+    const wrapper = mount(<InvalidUsage />);
+    assert.throws(() => {
+      const formEl = wrapper.find('form').getDOMNode();
+      const event = createFakeEvent({ type: 'click', target: formEl });
+      wrapper.find('form').prop('onClick')(event);
+    }, 'Event type is not "submit"');
+  });
+
+  it('should throw if handler is not a form', () => {
+    function InvalidUsage() {
+      const onSubmit = useValidateOnSubmit(() => {});
+
+      // eslint-disable-next-line
+      return <button onSubmit={onSubmit} type="button" />;
+    }
+    const wrapper = mount(<InvalidUsage />);
+    assert.throws(() => {
+      const buttonEl = wrapper.find('button').getDOMNode();
+      const event = createFakeEvent({ type: 'submit', target: buttonEl });
+      wrapper.find('button').prop('onSubmit')(event);
+    }, 'Event target is not a form');
+  });
+});

src/hooks/use-validate-on-submit.ts

@@ -0,0 +1,71 @@
+/**
+ * Return a form "submit" event handler that validates the form using
+ * {@link HTMLFormElement.checkValidity}.
+ *
+ * If the check passes, `onValid` is invoked. Otherwise the first control in
+ * {@link HTMLFormElement.elements} with an error is focused. This will allow
+ * the user to correct the error, and also cause screen readers to announce
+ * the current validation state and errors.
+ *
+ * This hook is useful for forms which want to display a custom presentation
+ * of validation errors. Forms using the browser's built-in validation error
+ * display do not need to use this.
+ *
+ * To show custom validation errors, the consumer should:
+ *
+ * - Ensure that all input controls validate their input on "change" events.
+ * - Ensure that validation errors are displayed for each control.  The input
+ *   fields must link their validation errors using `aria-describedby` and
+ *   indicate their state using `aria-invalid`.
+ * - Set the `noValidate` property on the `<form>` to disable the native
+ *   validation UI message
+ * - Call this hook to create a "submit" event handler and pass it to
+ *   the form's `submit` prop.
+ *
+ * See also https://react-spectrum.adobe.com/react-aria/forms.html.
+ */
+export function useValidateOnSubmit(
+  onValid: () => void,
+): (e: SubmitEvent) => void {
+  const onSubmit = (event: SubmitEvent) => {
+    if (event.type !== 'submit') {
+      throw new Error('Event type is not "submit"');
+    }
+    const formEl = event.target;
+    if (!(formEl instanceof HTMLFormElement)) {
+      throw new Error('Event target is not a form');
+    }
+
+    event.preventDefault();
+
+    if (formEl.checkValidity()) {
+      onValid();
+    } else {
+      // Focus first field wth an error if invalid. This matches the behavior
+      // of native form validation, allowing the user to correct the error
+      // and also announcing the problem to screen reader users.
+      let foundFirst = false;
+      for (const el of Array.from(formEl.elements) as Array<
+        HTMLElement | HTMLInputElement
+      >) {
+        if (!('validity' in el) || el.validity.valid) {
+          continue;
+        }
+
+        if (!foundFirst) {
+          el.focus();
+          foundFirst = true;
+        }
+
+        // If the user has focused an empty, required input field and
+        // triggered a submission by pressing Enter, that will not trigger
+        // a "change" event. Trigger this event to allow the input's "change"
+        // handler to update its custom error.
+        if (el.validity.valueMissing) {
+          el.dispatchEvent(new Event('change'));
+        }
+      }
+    }
+  };
+  return onSubmit;
+}

src/index.ts

@@ -7,6 +7,7 @@ export { useOrderedRows } from './hooks/use-ordered-rows';
 export { useStableCallback } from './hooks/use-stable-callback';
 export { useSyncedRef } from './hooks/use-synced-ref';
 export { useToastMessages } from './hooks/use-toast-messages';
+export { useValidateOnSubmit } from './hooks/use-validate-on-submit';
 export type {
   ToastMessagesState,
   ToastMessageData,