feat(elements): Consider ValidityState in FieldState (#3594)

.changeset/grumpy-dancers-thank.md

@@ -0,0 +1,14 @@
+---
+"@clerk/elements": minor
+---
+
+Improve `<FieldState>` and re-organize some data attributes related to validity states. These changes might be breaking changes for you.
+
+Overview of changes:
+
+- `<form>` no longer has `data-valid` and `data-invalid` attributes. If there are global errors (same heuristics as `<GlobalError>`) then a `data-global-error` attribute will be present.
+- Fixed a bug where `<Field>` could contain `data-valid` and `data-invalid` at the same time.
+- The field state (accessible through e.g. `<FieldState>`) now also incorporates the field's [ValidityState](https://developer.mozilla.org/en-US/docs/Web/API/ValidityState) into its output. If the `ValidityState` is invalid, the field state will be an `error`. You can access this information in three places:
+  1. `<FieldState>`
+  2. `data-state` attribute on `<Input>`
+  3. `<Field>{(state) => <p>Field's state is {state}</p>}</Field>`

packages/elements/examples/nextjs/app/sign-in/[[...sign-in]]/page.tsx

@@ -130,7 +130,7 @@ export default function SignInPage() {
                       <Clerk.Label className='sr-only'>Email</Clerk.Label>
                       <Clerk.Input
                         className={`w-full rounded border border-[rgb(37,37,37)] bg-[rgb(12,12,12)] px-4 py-2 placeholder-[rgb(100,100,100)] ${
-                          fieldState === 'invalid' && 'border-red-500'
+                          fieldState === 'error' && 'border-red-500'
                         }`}
                         placeholder='Enter your email address'
                       />
@@ -190,9 +190,10 @@ export default function SignInPage() {
                       <Clerk.Label className='sr-only'>Email</Clerk.Label>
                       <Clerk.Input
                         className={`w-full rounded border border-[rgb(37,37,37)] bg-[rgb(12,12,12)] px-4 py-2 placeholder-[rgb(100,100,100)] ${
-                          fieldState === 'invalid' && 'border-red-500'
+                          fieldState === 'error' && 'border-red-500'
                         }`}
                         placeholder='Enter your email address'
+                        type='email'
                       />
                       <Clerk.FieldError className='block w-full font-mono text-red-400' />
                     </>

packages/elements/src/react/common/form/index.tsx

@@ -18,6 +18,7 @@ import {
   FormMessage as RadixFormMessage,
   Label as RadixLabel,
   Submit as RadixSubmit,
+  ValidityState as RadixValidityState,
 } from '@radix-ui/react-form';
 import { Slot } from '@radix-ui/react-slot';
 import * as React from 'react';
@@ -43,7 +44,7 @@ import { isReactFragment } from '~/react/utils/is-react-fragment';
 
 import type { OTPInputProps } from './otp';
 import { OTP_LENGTH_DEFAULT, OTPInput } from './otp';
-import { type ClerkFieldId, FIELD_STATES, FIELD_VALIDITY, type FieldStates } from './types';
+import { type ClerkFieldId, FIELD_STATES, type FieldStates } from './types';
 
 /* -------------------------------------------------------------------------------------------------
  * Context
@@ -52,26 +53,13 @@ import { type ClerkFieldId, FIELD_STATES, FIELD_VALIDITY, type FieldStates } fro
 const FieldContext = React.createContext<Pick<FieldDetails, 'name'> | null>(null);
 const useFieldContext = () => React.useContext(FieldContext);
 
+const ValidityStateContext = React.createContext<ValidityState | undefined>(undefined);
+const useValidityStateContext = () => React.useContext(ValidityStateContext);
+
 /* -------------------------------------------------------------------------------------------------
- * Hooks
+ * Utils
  * -----------------------------------------------------------------------------------------------*/
 
-const useGlobalErrors = () => {
-  const errors = useFormSelector(globalErrorsSelector);
-
-  return {
-    errors,
-  };
-};
-
-const useFieldFeedback = ({ name }: Partial<Pick<FieldDetails, 'name'>>) => {
-  const feedback = useFormSelector(fieldFeedbackSelector(name));
-
-  return {
-    feedback,
-  };
-};
-
 const determineInputTypeFromName = (name: FormFieldProps['name']) => {
   if (name === 'password' || name === 'confirmPassword' || name === 'currentPassword' || name === 'newPassword') {
     return 'password' as const;
@@ -89,6 +77,36 @@ const determineInputTypeFromName = (name: FormFieldProps['name']) => {
   return 'text' as const;
 };
 
+/**
+ * Radix can return the ValidityState object, which contains the validity of the field. We need to merge this with our existing fieldState.
+ * When the ValidityState is valid: false, the fieldState should be overriden. Otherwise, it shouldn't change at all.
+ * @see https://www.radix-ui.com/primitives/docs/components/form#validitystate
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/ValidityState
+ */
+const enrichFieldState = (validity: ValidityState | undefined, fieldState: FieldStates) => {
+  return validity?.valid === false ? FIELD_STATES.error : fieldState;
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Hooks
+ * -----------------------------------------------------------------------------------------------*/
+
+const useGlobalErrors = () => {
+  const errors = useFormSelector(globalErrorsSelector);
+
+  return {
+    errors,
+  };
+};
+
+const useFieldFeedback = ({ name }: Partial<Pick<FieldDetails, 'name'>>) => {
+  const feedback = useFormSelector(fieldFeedbackSelector(name));
+
+  return {
+    feedback,
+  };
+};
+
 /**
  * Given a field name, determine the current state of the field
  */
@@ -133,7 +151,6 @@ const useFieldState = ({ name }: Partial<Pick<FieldDetails, 'name'>>) => {
  */
 const useForm = ({ flowActor }: { flowActor?: BaseActorRef<{ type: 'SUBMIT' }> }) => {
   const { errors } = useGlobalErrors();
-  const validity = errors.length > 0 ? FIELD_VALIDITY.invalid : FIELD_VALIDITY.valid;
 
   // Register the onSubmit handler for form submission
   // TODO: merge user-provided submit handler
@@ -149,7 +166,7 @@ const useForm = ({ flowActor }: { flowActor?: BaseActorRef<{ type: 'SUBMIT' }> }
 
   return {
     props: {
-      [`data-${validity}`]: true,
+      ...(errors.length > 0 ? { 'data-global-error': true } : {}),
       onSubmit,
     },
   };
@@ -161,12 +178,10 @@ const useField = ({ name }: Partial<Pick<FieldDetails, 'name'>>) => {
 
   const shouldBeHidden = false; // TODO: Implement clerk-js utils
   const hasError = feedback ? feedback.type === 'error' : false;
-  const validity = hasError ? FIELD_VALIDITY.invalid : FIELD_VALIDITY.valid;
 
   return {
     hasValue,
     props: {
-      [`data-${validity}`]: true,
       'data-hidden': shouldBeHidden ? true : undefined,
       serverInvalid: hasError,
     },
@@ -186,6 +201,7 @@ const useInput = ({
   const fieldContext = useFieldContext();
   const name = inputName || fieldContext?.name;
   const { state: fieldState } = useFieldState({ name });
+  const validity = useValidityStateContext();
 
   if (!name) {
     throw new Error('Clerk: <Input /> must be wrapped in a <Field> component or have a name prop.');
@@ -342,7 +358,7 @@ const useInput = ({
       onFocus,
       'data-hidden': shouldBeHidden ? true : undefined,
       'data-has-value': hasValue ? true : undefined,
-      'data-state': fieldState,
+      'data-state': enrichFieldState(validity, fieldState),
       ...props,
       ...rest,
     },
@@ -444,7 +460,17 @@ const FieldInner = React.forwardRef<FormFieldElement, FormFieldProps>((props, fo
       {...rest}
       ref={forwardedRef}
     >
-      {typeof children === 'function' ? children(fieldState) : children}
+      <RadixValidityState>
+        {validity => {
+          const enrichedFieldState = enrichFieldState(validity, fieldState);
+
+          return (
+            <ValidityStateContext.Provider value={validity}>
+              {typeof children === 'function' ? children(enrichedFieldState) : children}
+            </ValidityStateContext.Provider>
+          );
+        }}
+      </RadixValidityState>
     </RadixField>
   );
 });
@@ -493,11 +519,12 @@ function FieldState({ children }: FieldStateRenderFn) {
   const field = useFieldContext();
   const { feedback } = useFieldFeedback({ name: field?.name });
   const { state } = useFieldState({ name: field?.name });
+  const validity = useValidityStateContext();
 
   const message = feedback?.message instanceof ClerkElementsFieldError ? feedback.message.message : feedback?.message;
   const codes = feedback?.codes;
 
-  const fieldState = { state, message, codes };
+  const fieldState = { state: enrichFieldState(validity, state), message, codes };
 
   return children(fieldState);
 }