feat(Form fields): improve accesibility of errors (#1246)

WEB-1958

- Added an icon to error messages (this makes the error message more
accesible over inverse and for color-blind users)
- Added an aria-live region to announce all the fields with error when
the form is submitted and there is more than one field with error
- Make sure all mandatory form fields are validated
- Form fields are validated onBlur. Previously, we only validated fields
with a special format, like email.
- Fixed an error making VoiceOver read fields label twice

src/__stories__/custom-field-story.tsx

@@ -214,6 +214,7 @@ const AutocompleteSelectField = ({name, options}: AutocompleteSelectFieldProps)
 
     const fieldProps = useFieldProps({
         name,
+        label: 'Autocomplete',
         defaultValue: undefined,
         value: filterValue,
         processValue: (value: string) => value.trim(),
@@ -249,7 +250,6 @@ const AutocompleteSelectField = ({name, options}: AutocompleteSelectFieldProps)
                 <TextField
                     {...fieldProps}
                     fullWidth
-                    label="Autocomplete"
                     ref={combineRefs(ref, inputRef)}
                     onFocus={onPress}
                     onPress={() => {

src/__tests__/form-test.tsx

@@ -78,6 +78,29 @@ test('custom validator', async () => {
     );
 });
 
+test('when there are multiple errors on submit, the fields with error are anounced by screen reader', async () => {
+    const handleSubmitSpy = jest.fn();
+
+    render(
+        <ThemeContextProvider theme={makeTheme()}>
+            <Form onSubmit={handleSubmitSpy}>
+                <TextField label="Username" name="username" />
+                <TextField label="Password" name="password" validate={() => 'wrong password'} />
+                <ButtonPrimary submit>Submit</ButtonPrimary>
+            </Form>
+        </ThemeContextProvider>
+    );
+
+    await userEvent.type(screen.getByLabelText('Password'), 'letmein');
+    await userEvent.click(screen.getByText('Submit'));
+
+    expect(screen.getByText('Este campo es obligatorio')).toBeInTheDocument();
+    expect(screen.getByText('wrong password')).toBeInTheDocument();
+    const liveRegion = screen.getByRole('alert');
+    expect(liveRegion).toBeInTheDocument();
+    expect(liveRegion).toHaveTextContent('Revisa los siguientes errores: Username, Password');
+});
+
 test('fields are disabled during submit', async () => {
     let resolveSubmitPromise: (value?: unknown) => void = () => {};
     const submitPromise = new Promise((r) => {

src/box.tsx

@@ -16,6 +16,7 @@ type Props = {
     paddingBottom?: ByBreakpoint<PadSize>;
     paddingLeft?: ByBreakpoint<PadSize>;
     paddingRight?: ByBreakpoint<PadSize>;
+    as?: React.ComponentType<any> | string;
     children?: React.ReactNode;
     className?: string;
     role?: string;
@@ -31,6 +32,7 @@ const Box = React.forwardRef<HTMLDivElement, Props>(
         {
             className,
             children,
+            as: Component = 'div',
             width,
             padding = 0,
             paddingX = padding,
@@ -64,7 +66,7 @@ const Box = React.forwardRef<HTMLDivElement, Props>(
         }
 
         return (
-            <div
+            <Component
                 {...getPrefixedDataAttributes(dataAttributes)}
                 role={role}
                 aria-label={ariaLabel}
@@ -78,7 +80,7 @@ const Box = React.forwardRef<HTMLDivElement, Props>(
                 id={id}
             >
                 {children}
-            </div>
+            </Component>
         );
     }
 );

src/credit-card-expiration-field.tsx

@@ -97,6 +97,7 @@ const CreditCardExpirationField = ({
     error,
     helperText,
     name,
+    label,
     optional,
     validate: validateProp,
     onChange,
@@ -112,9 +113,6 @@ const CreditCardExpirationField = ({
     const {setFormError, jumpToNext} = useForm();
 
     const validate = (value: ExpirationDateValue, rawValue: string): string | undefined => {
-        if (!rawValue) {
-            return optional ? '' : texts.formFieldErrorIsMandatory || t(tokens.formFieldErrorIsMandatory);
-        }
         const {month, year} = value;
         if (!month || !year) {
             return texts.formCreditCardExpirationError || t(tokens.formCreditCardExpirationError);
@@ -142,6 +140,7 @@ const CreditCardExpirationField = ({
 
     const fieldProps = useFieldProps({
         name,
+        label,
         value,
         defaultValue,
         processValue,

src/credit-card-number-field.tsx

@@ -157,6 +157,7 @@ const CreditCardNumberField = ({
     error,
     helperText,
     name,
+    label,
     optional,
     validate: validateProp,
     onChange,
@@ -174,9 +175,6 @@ const CreditCardNumberField = ({
 
     const validate = (value: string | undefined, rawValue: string) => {
         const error = texts.formCreditCardNumberError || t(tokens.formCreditCardNumberError);
-        if (!value) {
-            return optional ? '' : texts.formFieldErrorIsMandatory || t(tokens.formFieldErrorIsMandatory);
-        }
         if (isAmericanExpress(value) && !acceptedCards.americanExpress) {
             return error;
         }
@@ -189,7 +187,7 @@ const CreditCardNumberField = ({
         if (!isValidCreditCardNumber(value)) {
             return error;
         }
-        if (getCreditCardNumberLength(value) !== value.length) {
+        if (getCreditCardNumberLength(value) !== value?.length) {
             return error;
         }
         return validateProp?.(value, rawValue);
@@ -199,6 +197,7 @@ const CreditCardNumberField = ({
 
     const fieldProps = useFieldProps({
         name,
+        label,
         value,
         defaultValue,
         processValue,

src/cvv-field.tsx

@@ -42,7 +42,6 @@ const TooltipContent = ({acceptedCards}: {acceptedCards: CardOptions}) => {
                             <Text2>
                                 {texts.formCreditCardCvvTooltipAmex || t(tokens.formCreditCardCvvTooltipAmex)}
                             </Text2>
-                            )
                         </Inline>
                     )}
                 </Stack>
@@ -61,6 +60,7 @@ const CvvField = ({
     error,
     helperText,
     name,
+    label,
     optional,
     validate: validateProp,
     onChange,
@@ -79,9 +79,6 @@ const CvvField = ({
     const [isCvvHelpOpen, setIsCvvHelpOpen] = React.useState(false);
 
     const validate = (value: string, rawValue: string) => {
-        if (!value) {
-            return optional ? '' : texts.formFieldErrorIsMandatory || t(tokens.formFieldErrorIsMandatory);
-        }
         if (value.length !== maxLength) {
             return texts.formCreditCardCvvError || t(tokens.formCreditCardCvvError);
         }
@@ -92,6 +89,7 @@ const CvvField = ({
 
     const fieldProps = useFieldProps({
         name,
+        label,
         value,
         defaultValue,
         processValue,

src/date-field.tsx

@@ -29,6 +29,7 @@ const DateField = ({
     error,
     helperText,
     name,
+    label,
     optional,
     validate: validateProp,
     onChange,
@@ -77,6 +78,7 @@ const DateField = ({
 
     const fieldProps = useFieldProps({
         name,
+        label,
         value,
         defaultValue,
         processValue,

src/date-time-field.tsx

@@ -29,6 +29,7 @@ const FormDateField = ({
     error,
     helperText,
     name,
+    label,
     optional,
     validate: validateProp,
     onChange,
@@ -83,6 +84,7 @@ const FormDateField = ({
 
     const fieldProps = useFieldProps({
         name,
+        label,
         value,
         defaultValue,
         processValue,

src/decimal-field.tsx

@@ -6,7 +6,6 @@ import {TextFieldBaseAutosuggest} from './text-field-base';
 import {createChangeEvent} from './utils/dom';
 import {useRifm} from 'rifm';
 import {combineRefs} from './utils/common';
-import * as tokens from './text-tokens';
 
 import type {Locale} from './utils/locale';
 import type {CommonFormFieldProps} from './text-field-base';
@@ -115,8 +114,9 @@ const DecimalField = ({
     error,
     helperText,
     name,
+    label,
     optional,
-    validate: validateProp,
+    validate,
     onChange,
     onChangeValue,
     onBlur,
@@ -126,19 +126,11 @@ const DecimalField = ({
     dataAttributes,
     ...rest
 }: DecimalFieldProps): JSX.Element => {
-    const {texts, t} = useTheme();
-
-    const validate = (value: string | undefined, rawValue: string) => {
-        if (!value) {
-            return optional ? '' : texts.formFieldErrorIsMandatory || t(tokens.formFieldErrorIsMandatory);
-        }
-        return validateProp?.(value, rawValue);
-    };
-
     const processValue = (value: string) => value.trim();
 
     const fieldProps = useFieldProps({
         name,
+        label,
         value,
         defaultValue,
         processValue,

src/email-field.tsx

@@ -20,6 +20,7 @@ const EmailField = ({
     error,
     helperText,
     name,
+    label,
     optional,
     validate: validateProp,
     onChange,
@@ -34,10 +35,7 @@ const EmailField = ({
     const {texts, t} = useTheme();
 
     const validate = (value: string | undefined, rawValue: string) => {
-        if (!value) {
-            return optional ? '' : texts.formFieldErrorIsMandatory || t(tokens.formFieldErrorIsMandatory);
-        }
-        if (!RE_EMAIL.test(value)) {
+        if (!RE_EMAIL.test(value ?? '')) {
             return texts.formEmailError || t(tokens.formEmailError);
         }
         return validateProp?.(value, rawValue);
@@ -47,6 +45,7 @@ const EmailField = ({
 
     const fieldProps = useFieldProps({
         name,
+        label,
         value,
         defaultValue,
         processValue,

src/form-context.tsx

@@ -1,5 +1,7 @@
 'use client';
 import * as React from 'react';
+import {useTheme} from './hooks';
+import * as tokens from './text-tokens';
 
 export type FormStatus = 'filling' | 'sending';
 export type FormErrors = {[name: string]: string | undefined};
@@ -9,6 +11,7 @@ export type FieldRegistration = {
     input?: HTMLInputElement | HTMLSelectElement | null;
     validator?: FieldValidator;
     focusableElement?: HTMLDivElement | HTMLSelectElement | null;
+    label?: string;
 };
 
 type Context = {
@@ -47,18 +50,21 @@ export const useForm = (): Context => React.useContext(FormContext);
 
 export const useControlProps = <T,>({
     name,
+    label,
     value,
     defaultValue,
     onChange,
     disabled,
 }: {
     name: string;
+    label?: string;
     value: undefined | T;
     defaultValue: undefined | T;
     onChange: undefined | ((value: T) => void);
     disabled?: boolean;
 }): {
     name: string;
+    label?: string;
     value?: T;
     defaultValue?: T;
     onChange: (value: T) => void;
@@ -77,11 +83,13 @@ export const useControlProps = <T,>({
 
     return {
         name,
+        label,
         value,
         defaultValue: defaultValue ?? (value === undefined ? rawValues[name] ?? false : undefined),
         focusableRef: (focusableElement: HTMLDivElement | null) =>
             register(name, {
                 focusableElement,
+                label,
             }),
         onChange: (value: T) => {
             setRawValue({name, value});
@@ -95,6 +103,7 @@ export const useControlProps = <T,>({
 
 export const useFieldProps = ({
     name,
+    label,
     value,
     defaultValue,
     processValue,
@@ -108,6 +117,7 @@ export const useFieldProps = ({
     onChangeValue,
 }: {
     name: string;
+    label: string;
     value?: string;
     defaultValue?: string;
     processValue: (value: string) => unknown;
@@ -123,6 +133,7 @@ export const useFieldProps = ({
     value?: string;
     defaultValue?: string;
     name: string;
+    label: string;
     helperText?: string;
     required: boolean;
     error: boolean;
@@ -131,6 +142,7 @@ export const useFieldProps = ({
     inputRef: (field: HTMLInputElement | null) => void;
     onChange: (event: React.ChangeEvent<HTMLInputElement>) => void;
 } => {
+    const {texts, t} = useTheme();
     const {setRawValue, setValue, rawValues, values, formErrors, formStatus, setFormError, register} =
         useForm();
     const rawValue = value ?? defaultValue ?? rawValues[name] ?? '';
@@ -151,15 +163,22 @@ export const useFieldProps = ({
         value,
         defaultValue: defaultValue ?? (value === undefined ? rawValues[name] ?? '' : undefined),
         name,
+        label,
         helperText: formErrors[name] || helperText,
         required: !optional,
         error: error || !!formErrors[name],
         disabled: disabled || formStatus === 'sending',
         onBlur: (e: React.FocusEvent) => {
-            setFormError({name, error: validate?.(values[name], rawValues[name])});
+            let error: string | undefined;
+            if (!rawValues[name] && !optional) {
+                error = texts.formFieldErrorIsMandatory || t(tokens.formFieldErrorIsMandatory);
+            } else if (validate) {
+                error = validate(values[name], rawValues[name]);
+            }
+            setFormError({name, error});
             onBlur?.(e);
         },
-        inputRef: (input: HTMLInputElement | null) => register(name, {input, validator: validate}),
+        inputRef: (input: HTMLInputElement | null) => register(name, {input, validator: validate, label}),
         onChange: (event: React.ChangeEvent<HTMLInputElement>) => {
             const rawValue = event.currentTarget.value;
             const value = processValue(rawValue);