Add Input.error prop

This sets a custom validation error for the input component which is
communicated to the browser via `HTMLInputElement.setCustomValidity`.

This, along with any native validation constraints such as `required`, will
prevent form submission until they are resolved.

Author: robertknight

src/components/input/Input.tsx

@@ -1,7 +1,9 @@
 import classnames from 'classnames';
 import type { JSX } from 'preact';
 
-import type { PresentationalProps } from '../../types';
+import { useSyncedRef } from '../../hooks/use-synced-ref';
+import { useValidationError } from '../../hooks/use-validation-error';
+import type { FormControlProps, PresentationalProps } from '../../types';
 import { downcastRef } from '../../util/typing';
 import { inputGroupStyles } from './InputGroup';
 
@@ -26,9 +28,8 @@ export function inputStyles({ classes, feedback }: InputStylesOptions) {
   );
 }
 
-type ComponentProps = {
+type ComponentProps = FormControlProps & {
   type?: 'text' | 'email' | 'search' | 'number' | 'password' | 'url';
-  feedback?: 'error' | 'warning';
 };
 
 export type InputProps = PresentationalProps &
@@ -42,6 +43,7 @@ export default function Input({
   elementRef,
   type = 'text',
   classes,
+  error,
   feedback,
 
   ...htmlAttributes
@@ -52,11 +54,21 @@ export default function Input({
     );
   }
 
+  const inputRef = downcastRef<HTMLElement | undefined, HTMLInputElement>(
+    elementRef,
+  );
+  const ref = useSyncedRef<HTMLInputElement>(inputRef);
+
+  if (error) {
+    feedback = 'error';
+  }
+  useValidationError(ref, error);
+
   return (
     <input
       data-component="Input"
       {...htmlAttributes}
-      ref={downcastRef(elementRef)}
+      ref={ref}
       type={type}
       className={inputStyles({ classes, feedback })}
       aria-invalid={feedback === 'error'}

src/components/input/test/Input-test.js

@@ -23,6 +23,26 @@ describe('Input', () => {
     console.warn.restore();
   });
 
+  [
+    {
+      error: undefined,
+      validationMessage: '',
+      invalid: false,
+    },
+    {
+      error: 'Not a valid URL',
+      validationMessage: 'Not a valid URL',
+      invalid: true,
+    },
+  ].forEach(({ error, validationMessage, invalid }) => {
+    it('should set custom validation error if `error` prop is provided', () => {
+      const wrapper = mount(<Input aria-label="Test" error={error} />);
+      const input = wrapper.find('input');
+      assert.equal(input.getDOMNode().validationMessage, validationMessage);
+      assert.equal(input.prop('aria-invalid'), invalid);
+    });
+  });
+
   [
     { feedback: undefined, expectedInvalid: false },
     { feedback: 'error', expectedInvalid: true },

src/hooks/use-validation-error.ts

@@ -0,0 +1,25 @@
+import type { RefObject } from 'preact';
+import { useLayoutEffect } from 'preact/hooks';
+
+export type InputLike = {
+  setCustomValidity(message: string): void;
+};
+
+/**
+ * Sync custom validation error messages to the browser's native validation
+ * state.
+ *
+ * @param ref - An `HTMLInputElement` or other element that supports the
+ *   Constraint Validation API
+ * @param error - The current error or undefined if the field input is valid
+ */
+export function useValidationError(
+  ref: RefObject<InputLike | undefined>,
+  error?: string,
+) {
+  // Sync errors to native form validation API. This will prevent submission
+  // of the form until the error is resolved.
+  useLayoutEffect(() => {
+    ref.current?.setCustomValidity(error ?? '');
+  }, [error, ref]);
+}

src/pattern-library/components/patterns/input/InputPage.tsx

@@ -29,7 +29,7 @@ export default function InputPage() {
         </Library.Pattern>
 
         <Library.Pattern title="Working with Inputs">
-          <Library.Example title="Accessibility">
+          <Library.Example title="Labels">
             <p>
               Hypothesis does not currently have a design pattern for labeling
               text inputs. However, for accessibility, it is critical that an{' '}
@@ -61,6 +61,26 @@ export default function InputPage() {
               </div>
             </Library.Demo>
           </Library.Example>
+          <Library.Example title="Validation errors">
+            <p>
+              Validation errors can be triggered as a result of standard HTML
+              attributes such as <code>required</code> or a custom error set
+              using the <code>error</code> prop. Errors set using{' '}
+              <code>error</code> are synced to the browser via{' '}
+              <code>HTMLInputElement.setCustomValidity</code>. This allows the
+              browser to alert the user when they try to submit the containing
+              form.
+            </p>
+            <p>
+              If the input has custom validation checks, they should be
+              performed in the element&apos;s <code>onChange</code> handler.
+            </p>
+            <p>
+              If the form is using custom UI to present validation errors,
+              inputs must link to the element displaying their validation error
+              using <code>aria-describedby</code>.
+            </p>
+          </Library.Example>
         </Library.Pattern>
 
         <Library.Pattern title="Component API">
@@ -69,6 +89,23 @@ export default function InputPage() {
             presentational component props
           </Library.Link>
           .
+          <Library.Example title="error">
+            <Library.Info>
+              <Library.InfoItem label="description">
+                Set <code>error</code> to indicate a validation error. This
+                implicitly sets{' '}
+                <code>
+                  feedback={'"'}error{'"'}
+                </code>
+                . In addition to visually and semantically indicating the error
+                state, this will set a custom validation error on the input
+                using <code>HTMLInputElement.setCustomValidity</code>.
+              </Library.InfoItem>
+              <Library.InfoItem label="type">
+                <code>string</code>
+              </Library.InfoItem>
+            </Library.Info>
+          </Library.Example>
           <Library.Example title="feedback">
             <Library.Info>
               <Library.InfoItem label="description">

src/types.ts

@@ -11,6 +11,30 @@ export type PresentationalProps = {
   elementRef?: Ref<HTMLElement | undefined>;
 };
 
+/**
+ * Common props for form controls.
+ */
+export type FormControlProps = {
+  /**
+   * The current validation error.
+   *
+   * If set, this will override `feedback` and set it to `error`. The validation
+   * error will be synced to the browser's native validation state via
+   * {@link HTMLInputElement.setCustomValidity}. This will prevent submission
+   * of the containing form.
+   */
+  error?: string;
+
+  /**
+   * Set the visual and semantic state (`aria-invalid`) of the control to
+   * indicate an error.
+   *
+   * Unlike {@link FormControlProps.error} this does not set a native validation
+   * error and as such, it won't prevent a containing form from being submitted.
+   */
+  feedback?: 'error' | 'warning';
+};
+
 /**
  * Props common to components that are opinionated compositions of other
  * components.