feature: preserve validation error between updates config flag

.changeset/lucky-coats-explain.md

@@ -0,0 +1,6 @@
+---
+"@formeus/core": minor
+"docs": minor
+---
+
+preserveValidationErrorOnUpdate configuration flag added

apps/docs/pages/docs/reference/createForm.mdx

@@ -62,13 +62,6 @@ Returning a promise from this function makes returned `isSubmitting` value `true
 
 ### `config`
 
-```js
-type FormConfig = {
-  autoValidate?: boolean
-  validateConcurrentlyOnSubmit?: boolean
-}
-```
-
 Configuration options for the current form.
 
 Overrides global config if set.

apps/docs/pages/docs/reference/setFormConfig.mdx

@@ -22,6 +22,7 @@ const form = createForm({
 type FormConfig = {
   autoValidate?: boolean,
   validateConcurrentlyOnSubmit?: boolean,
+  preserveValidationErrorOnUpdate?: boolean,
 }
 ```
 
@@ -42,3 +43,9 @@ When set to `true`, calling the `submit` method will trigger concurrent validati
 
 Default is `false`, and calling the `submit` method triggers sequential validation of your form fields, stopping
 if any validation fails.
+
+### `preserveValidationErrorOnUpdate`
+
+When set to `true`, field validation errors will be preserved after updates.
+
+Default is `false`, and updating the field value will clear its validation error.

packages/form-core/src/form.ts

@@ -146,7 +146,9 @@ export function createForm<
       newValidations = {
         ...newValidations,
         [key]: {
-          error: undefined,
+          error: config.preserveValidationErrorOnUpdate
+            ? validations[key].error
+            : undefined,
           checked: false,
           validating: false,
         } as ValidationState,

packages/form-core/src/formConfig.ts

@@ -4,6 +4,7 @@ import { FormConfig } from "./types"
 let staticConfig: FormConfig = {
   autoValidate: false,
   validateConcurrentlyOnSubmit: false,
+  preserveValidationErrorOnUpdate: false,
 }
 
 export function setFormConfig(config: FormConfig) {

packages/form-core/src/tests/form.test.ts

@@ -79,6 +79,73 @@ describe("form", () => {
     })
   })
 
+  it("field validation error is cleared after update", async () => {
+    const form = createForm({
+      initial: {
+        email: "",
+      },
+      validators: {
+        ...createClientValidator("failing", "email"),
+      },
+    })
+
+    const snapshot1 = form.getSnapshot()
+    snapshot1.runValidation("email")
+
+    const snapshot2 = form.getSnapshot()
+
+    expect(snapshot2.validations.email).toStrictEqual({
+      checked: true,
+      error: new Error("email invalid"),
+      validating: false,
+    })
+
+    snapshot2.update("email", "newInvalidMail")
+
+    const snapshot3 = form.getSnapshot()
+
+    expect(snapshot3.validations.email).toStrictEqual({
+      checked: false,
+      error: undefined,
+      validating: false,
+    })
+  })
+
+  it("field validation error is not cleared after update if flag is set", async () => {
+    const form = createForm({
+      initial: {
+        email: "",
+      },
+      validators: {
+        ...createClientValidator("failing", "email"),
+      },
+      config: {
+        preserveValidationErrorOnUpdate: true,
+      },
+    })
+
+    const snapshot1 = form.getSnapshot()
+    snapshot1.runValidation("email")
+
+    const snapshot2 = form.getSnapshot()
+
+    expect(snapshot2.validations.email).toStrictEqual({
+      checked: true,
+      error: new Error("email invalid"),
+      validating: false,
+    })
+
+    snapshot2.update("email", "newInvalidMail")
+
+    const snapshot3 = form.getSnapshot()
+
+    expect(snapshot3.validations.email).toStrictEqual({
+      checked: false,
+      error: new Error("email invalid"),
+      validating: false,
+    })
+  })
+
   it("has correct state after running server validations", async () => {
     const initial = {
       email: "",

packages/form-core/src/types.ts

@@ -160,4 +160,14 @@ export type FormConfig = {
    * Default is `false`.
    */
   validateConcurrentlyOnSubmit?: boolean
+  /**
+   * `true` - If form field had a validation error, updating that field will preserve the validation error.
+   *
+   * `false` - Form field validation error is cleared when that field is updated.
+   *
+   * This doesn't affect validation logic and result in any way, it controls the preserving of error state between updates.
+   *
+   * Default is `false`.
+   */
+  preserveValidationErrorOnUpdate?: boolean
 }