feat: add isValidated flag to field state (#232)

logaretm · web-flow · commit 0b30be969737 · 2025-11-23T23:17:35.000+01:00
* feat: introduce isValidated flag

* chore: changeset

* feat: added submit done event

* fix: only set it in invalid events if html validation is enabled
diff --git a/.changeset/busy-pigs-fly.md b/.changeset/busy-pigs-fly.md
@@ -0,0 +1,5 @@
+---
+'@formwerk/core': patch
+---
+
+feat: introduce isValidated field-level flag
diff --git a/packages/core/src/useForm/useForm.ts b/packages/core/src/useForm/useForm.ts
@@ -239,6 +239,7 @@ export interface FormContext<TInput extends FormObject = FormObject, TOutput ext
     FormTransactionManager<TInput> {
   requestValidation(): Promise<FormValidationResult<TOutput>>;
   onSubmitAttempt(cb: () => void): void;
+  onSubmitDone(cb: () => void): void;
   onValidationDone(cb: () => void): void;
   isHtmlValidationDisabled(): boolean;
   onValidationDispatch(
diff --git a/packages/core/src/useForm/useFormActions.ts b/packages/core/src/useForm/useFormActions.ts
@@ -103,6 +103,7 @@ export function useFormActions<TForm extends FormObject = FormObject, TOutput ex
   const isSubmitAttempted = shallowRef(false);
   const wasSubmitted = shallowRef(false);
   const [dispatchSubmit, onSubmitAttempt] = createEventDispatcher<void>('submit');
+  const [dispatchSubmitDone, onSubmitDone] = createEventDispatcher<void>('submit:done');
   const {
     validate: _validate,
     onValidationDispatch,
@@ -129,6 +130,7 @@ export function useFormActions<TForm extends FormObject = FormObject, TOutput ex
 
       // Prevent submission if the form has errors
       if (!isValid) {
+        dispatchSubmitDone();
         isSubmitting.value = false;
         scrollToFirstInvalidField(form.id, scrollToInvalidFieldOnSubmit);
         return;
@@ -143,6 +145,7 @@ export function useFormActions<TForm extends FormObject = FormObject, TOutput ex
         unsetPath(output, path, true);
       }
 
+      dispatchSubmitDone();
       const result = await onSuccess(asConsumableData(output), { event: e, form: e?.target as HTMLFormElement });
       isSubmitting.value = false;
       wasSubmitted.value = true;
@@ -332,6 +335,7 @@ export function useFormActions<TForm extends FormObject = FormObject, TOutput ex
     onSubmitAttempt,
     onValidationDispatch,
     onValidationDone,
+    onSubmitDone,
     isSubmitting,
     submitAttemptsCount,
     wasSubmitted,
diff --git a/packages/core/src/useFormField/useFieldState.ts b/packages/core/src/useFormField/useFieldState.ts
@@ -6,6 +6,7 @@ import {
   nextTick,
   provide,
   readonly,
+  ref,
   Ref,
   shallowRef,
   toValue,
@@ -42,6 +43,7 @@ export type FieldState<TValue> = {
   isDirty: Ref<boolean>;
   isBlurred: Ref<boolean>;
   isValid: Ref<boolean>;
+  isValidated: Ref<boolean>;
   isDisabled: Ref<boolean>;
   errors: Ref<string[]>;
   errorMessage: Ref<string>;
@@ -55,6 +57,7 @@ export type FieldState<TValue> = {
   setTouched: (touched: boolean) => void;
   setBlurred: (blurred: boolean) => void;
   setErrors: (messages: Arrayable<string>) => void;
+  setIsValidated: (isValidated: boolean) => void;
   form?: FormContext | null;
 };
 
@@ -72,6 +75,7 @@ export function useFieldState<TValue = unknown>(opts?: Partial<FieldStateInit<TV
   const { fieldValue, pathlessValue, setValue } = useFieldValue(getPath, form, initialValue);
   const { isTouched, pathlessTouched, setTouched } = useFieldTouched(getPath, form);
   const { isBlurred, pathlessBlurred, setBlurred } = useFieldBlurred(getPath, form);
+  const { isValidated, setIsValidated } = useFieldIsValidated();
 
   const { errors, setErrors, isValid, errorMessage, pathlessValidity, submitErrors, submitErrorMessage } =
     useFieldValidity(getPath, isDisabled, form);
@@ -132,6 +136,7 @@ export function useFieldState<TValue = unknown>(opts?: Partial<FieldStateInit<TV
     isBlurred: readonly(isBlurred) as Ref<boolean>,
     isDirty,
     isValid,
+    isValidated,
     errors,
     errorMessage,
     isDisabled,
@@ -143,6 +148,7 @@ export function useFieldState<TValue = unknown>(opts?: Partial<FieldStateInit<TV
     setTouched,
     setBlurred,
     setErrors,
+    setIsValidated,
     submitErrors,
     submitErrorMessage,
   };
@@ -164,6 +170,10 @@ export function useFieldState<TValue = unknown>(opts?: Partial<FieldStateInit<TV
     setTouched(true);
   });
 
+  form.onSubmitDone(() => {
+    setIsValidated(true);
+  });
+
   tryOnScopeDispose(() => {
     const path = getPath();
     if (!path) {
@@ -491,3 +501,21 @@ export function resolveFieldState<TValue = unknown, TInitialValue = TValue>(
     useFieldState<TValue | undefined>(getStateInit<TValue, TInitialValue>(props, resolveValue))
   );
 }
+
+/**
+ * Tracks whether the field has been validated.
+ * This is useful for determining whether to show validation errors or not.
+ */
+export function useFieldIsValidated() {
+  // Right now, there is no need to track it in a form.
+  const isValidated = ref(false);
+
+  function setIsValidated(value: boolean) {
+    isValidated.value = value;
+  }
+
+  return {
+    isValidated,
+    setIsValidated,
+  };
+}
diff --git a/packages/core/src/useFormField/useFormField.spec.ts b/packages/core/src/useFormField/useFormField.spec.ts
@@ -294,3 +294,118 @@ test('validate warns and skips validation on a disabled field', async () => {
   // Clean up the mocks
   consoleWarnSpy.mockRestore();
 });
+
+describe('isValidated state', () => {
+  test('field starts with isValidated as false', async () => {
+    const { isValidated } = await renderSetup(() => {
+      return useFormField({ label: 'Field', initialValue: 'bar' }).state;
+    });
+
+    expect(isValidated.value).toBe(false);
+  });
+
+  test('isValidated remains false after programmatic validation without schema', async () => {
+    const { isValidated, validate } = await renderSetup(() => {
+      return useFormField({ label: 'Field', initialValue: 'bar' }).state;
+    });
+
+    expect(isValidated.value).toBe(false);
+    await validate();
+    expect(isValidated.value).toBe(false); // Should remain false - programmatic validation
+  });
+
+  test('isValidated remains false after programmatic validation with schema', async () => {
+    const { isValidated, validate } = await renderSetup(() => {
+      return useFormField({
+        label: 'Field',
+        initialValue: 'bar',
+        schema: defineStandardSchema(async () => {
+          return { value: 'bar' };
+        }),
+      }).state;
+    });
+
+    expect(isValidated.value).toBe(false);
+    await validate();
+    expect(isValidated.value).toBe(false); // Should remain false - programmatic validation
+  });
+
+  test('isValidated remains false after programmatic validation with errors', async () => {
+    const { isValidated, validate } = await renderSetup(() => {
+      return useFormField({
+        label: 'Field',
+        initialValue: '',
+        schema: defineStandardSchema(async () => {
+          return { issues: [{ message: 'Required', path: ['field'] }] };
+        }),
+      }).state;
+    });
+
+    expect(isValidated.value).toBe(false);
+    await validate(true);
+    expect(isValidated.value).toBe(false); // Should remain false - programmatic validation
+  });
+
+  test('isValidated can be set manually', async () => {
+    const { isValidated, setIsValidated } = await renderSetup(() => {
+      return useFormField({ label: 'Field', initialValue: 'bar' }).state;
+    });
+
+    expect(isValidated.value).toBe(false);
+    setIsValidated(true);
+    expect(isValidated.value).toBe(true);
+    setIsValidated(false);
+    expect(isValidated.value).toBe(false);
+  });
+
+  test('isValidated becomes true after form submit attempt', async () => {
+    const { form, field } = await renderSetup(
+      () => {
+        const form = useForm({
+          initialValues: { field: 'valid' },
+          schema: defineStandardSchema<{ field: string }>(async () => {
+            return { value: { field: 'valid' } };
+          }),
+        });
+        return { form };
+      },
+      () => {
+        const field = useFormField({
+          path: 'field',
+          schema: defineStandardSchema(async () => {
+            return { value: 'valid' };
+          }),
+        });
+        return { field };
+      },
+    );
+
+    expect(field.state.isValidated.value).toBe(false);
+
+    // Submit attempt is a user interaction
+    const handleSubmit = form.handleSubmit(async () => {});
+    await handleSubmit();
+
+    expect(field.state.isValidated.value).toBe(true);
+  });
+
+  test('isValidated is independent for pathless fields', async () => {
+    const { field1, field2 } = await renderSetup(() => {
+      const field1 = useFormField({ label: 'Field1', initialValue: 'bar' });
+      const field2 = useFormField({ label: 'Field2', initialValue: 'baz' });
+      return { field1, field2 };
+    });
+
+    expect(field1.state.isValidated.value).toBe(false);
+    expect(field2.state.isValidated.value).toBe(false);
+
+    // Manually set isValidated (simulating user interaction)
+    field1.state.setIsValidated(true);
+    expect(field1.state.isValidated.value).toBe(true);
+    expect(field2.state.isValidated.value).toBe(false);
+
+    field2.state.setIsValidated(true);
+    expect(field1.state.isValidated.value).toBe(true);
+    expect(field2.state.isValidated.value).toBe(true);
+  });
+});
diff --git a/packages/core/src/useFormField/useFormField.ts b/packages/core/src/useFormField/useFormField.ts
@@ -115,6 +115,11 @@ export type ExposedField<TValue> = {
    */
   isValid: Ref<boolean>;
 
+  /**
+   * Whether the field is validated, used to determine whether to show validation errors or not.
+   */
+  isValidated: Ref<boolean>;
+
   /**
    * Whether the field is disabled.
    */
@@ -135,6 +140,11 @@ export type ExposedField<TValue> = {
    */
   setBlurred: (blurred: boolean) => void;
 
+  /**
+   * Sets the validated state for the field.
+   */
+  setIsValidated: (isValidated: boolean) => void;
+
   /**
    * Sets the value for the field.
    */
@@ -176,6 +186,7 @@ export function exposeField<TReturns extends object, TValue>(
     isTouched: field.state.isTouched,
     isBlurred: field.state.isBlurred,
     isValid: field.state.isValid,
+    isValidated: field.state.isValidated,
     isDisabled: field.state.isDisabled,
     labelProps: field.labelProps,
     descriptionProps: field.descriptionProps,
@@ -191,6 +202,7 @@ export function exposeField<TReturns extends object, TValue>(
       : field.state.setErrors,
     setTouched: field.state.setTouched,
     setBlurred: field.state.setBlurred,
+    setIsValidated: field.state.setIsValidated,
     setValue: field.state.setValue,
     validate: (mutate = true) => field.state.validate(mutate),
     ...obj,
diff --git a/packages/core/src/validation/useInputValidity.spec.ts b/packages/core/src/validation/useInputValidity.spec.ts
diff --git a/packages/core/src/validation/useInputValidity.ts b/packages/core/src/validation/useInputValidity.ts
diff --git a/packages/core/src/validation/useValidationProvider.ts b/packages/core/src/validation/useValidationProvider.ts

-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +'@formwerk/core': patch
 +---
++
 +feat: introduce isValidated field-level flag