feat: add "dirty" and "pristine" field states

fulopkovacs · web-flow · commit 23823449e4f9 · 2024-03-17T22:48:16.000+01:00
diff --git a/docs/assets/field-states.png b/docs/assets/field-states.png
diff --git a/docs/guides/basic-concepts.md b/docs/guides/basic-concepts.md
@@ -66,6 +66,19 @@ Example:
 const { value, error, touched, isValidating } = field.state
 ```
 
+There are three field states can be very useful to see how the user interacts with a field. A field is _"touched"_ when the user clicks/tabs into it, _"pristine"_ until the user changes value in it, and _"dirty"_ after the value has been changed. You can check these states via the `isTouched`, `isPristine` and `isDirty` flags, as seen below.
+
+```tsx
+const { isTouched, isPristine, isDirty } = field.state.meta
+```
+
+![Field states](https://raw.githubusercontent.com/TanStack/form/f7afd70b502e17f4d7e83d1577823e3732ce2d43/docs/assets/field-states.png)
+
+> **Important note for users coming from `React Hook Form`**: the `isDirty` flag in `TanStack/form` is different from the flag with the same name in RHF.
+> In RHF, `isDirty = true`, when the form's values are different from the original values. If the user changes the values in a form, and then changes them again to end up with values that match the form's default values, `isDirty` will be `true` in RHF, but `false` in `TanStack/form`.
+> The default values are exposed both on the form's and the field's level in `TanStack/form` (`form.options.defaultValues`, `field.options.defaultValue`), so you can write your own `isDefaultValue()` helper if you need to emulate RHF's behavior.`
+
+
 ## Field API
 
 The Field API is an object passed to the render prop function when creating a field. It provides methods for working with the field's state.
diff --git a/docs/reference/fieldApi.md b/docs/reference/fieldApi.md
@@ -131,6 +131,14 @@ An object type representing the options for a field in a form.
 
 An object type representing the metadata of a field in a form.
 
+- ```tsx
+  isPristine: boolean
+  ```
+  - A flag that is `true` if the field's value have not been modified by the user. Opposite of `isDirty`.
+- ```tsx
+  isDirty: boolean
+  ```
+  - A flag that is `true` if the field's value have been modified by the user. Opposite of `isPristine`.
 - ```tsx
   isTouched: boolean
   ```
diff --git a/docs/reference/formApi.md b/docs/reference/formApi.md
@@ -233,6 +233,16 @@ An object representing the current state of the form.
   ```
   - A boolean indicating if any of the form fields have been touched.
 
+- ```tsx
+  isPristine: boolean
+  ```
+  - A boolean indicating if none of the form's fields' values have been modified by the user. `True` if the user have not modified any of the fields. Opposite of `isDirty`.
+
+- ```tsx
+  isDirty: boolean
+  ```
+  - A boolean indicating if any of the form's fields' values have been modified by the user. `True` if the user have modified at least one of the fields. Opposite of `isPristine`.
+
 - ```tsx
   isSubmitted: boolean
   ```
diff --git a/packages/form-core/src/FieldApi.ts b/packages/form-core/src/FieldApi.ts
@@ -232,6 +232,8 @@ export interface FieldApiOptions<
 
 export type FieldMeta = {
   isTouched: boolean
+  isPristine: boolean
+  isDirty: boolean
   touchedErrors: ValidationError[]
   errors: ValidationError[]
   errorMap: ValidationErrorMap
@@ -300,6 +302,8 @@ export class FieldApi<
         meta: this._getMeta() ?? {
           isValidating: false,
           isTouched: false,
+          isDirty: false,
+          isPristine: true,
           touchedErrors: [],
           errors: [],
           errorMap: {},
@@ -318,6 +322,8 @@ export class FieldApi<
             ? state.meta.errors
             : []
 
+          state.meta.isPristine = !state.meta.isDirty
+
           this.prevState = state
           this.state = state
         },
@@ -448,6 +454,8 @@ export class FieldApi<
     ({
       isValidating: false,
       isTouched: false,
+      isDirty: false,
+      isPristine: true,
       touchedErrors: [],
       errors: [],
       errorMap: {},
diff --git a/packages/form-core/src/FormApi.ts b/packages/form-core/src/FormApi.ts
@@ -129,6 +129,8 @@ export type FormState<TFormData> = {
   isSubmitting: boolean
   // General
   isTouched: boolean
+  isDirty: boolean
+  isPristine: boolean
   isSubmitted: boolean
   isValidating: boolean
   isValid: boolean
@@ -152,6 +154,8 @@ function getDefaultFormState<TFormData>(
     isSubmitted: defaultState.isSubmitted ?? false,
     isSubmitting: defaultState.isSubmitting ?? false,
     isTouched: defaultState.isTouched ?? false,
+    isPristine: defaultState.isPristine ?? true,
+    isDirty: defaultState.isDirty ?? false,
     isValid: defaultState.isValid ?? false,
     isValidating: defaultState.isValidating ?? false,
     submissionAttempts: defaultState.submissionAttempts ?? 0,
@@ -208,6 +212,9 @@ export class FormApi<
 
           const isTouched = fieldMetaValues.some((field) => field?.isTouched)
 
+          const isDirty = fieldMetaValues.some((field) => field?.isDirty)
+          const isPristine = !isDirty
+
           const isValidating = isFieldsValidating || state.isFormValidating
           state.errors = Object.values(state.errorMap).filter(
             (val: unknown) => val !== undefined,
@@ -226,6 +233,8 @@ export class FormApi<
             isValid,
             canSubmit,
             isTouched,
+            isPristine,
+            isDirty,
           }
 
           this.state = state
@@ -625,6 +634,7 @@ export class FormApi<
         this.setFieldMeta(field, (prev) => ({
           ...prev,
           isTouched: true,
+          isDirty: true,
         }))
       }
 
diff --git a/packages/form-core/src/tests/FieldApi.spec.ts b/packages/form-core/src/tests/FieldApi.spec.ts
@@ -46,6 +46,8 @@ describe('field api', () => {
     expect(field.getMeta()).toEqual({
       isTouched: false,
       isValidating: false,
+      isPristine: true,
+      isDirty: false,
       touchedErrors: [],
       errors: [],
       errorMap: {},
@@ -57,12 +59,14 @@ describe('field api', () => {
     const field = new FieldApi({
       form,
       name: 'name',
-      defaultMeta: { isTouched: true },
+      defaultMeta: { isTouched: true, isDirty: true, isPristine: false },
     })
 
     expect(field.getMeta()).toEqual({
       isTouched: true,
       isValidating: false,
+      isDirty: true,
+      isPristine: false,
       touchedErrors: [],
       errors: [],
       errorMap: {},
diff --git a/packages/form-core/src/tests/FormApi.spec.ts b/packages/form-core/src/tests/FormApi.spec.ts
@@ -21,6 +21,8 @@ describe('form api', () => {
       errorMap: {},
       isSubmitting: false,
       isTouched: false,
+      isPristine: true,
+      isDirty: false,
       isValid: true,
       isValidating: false,
       submissionAttempts: 0,
@@ -55,6 +57,8 @@ describe('form api', () => {
       isSubmitted: false,
       isSubmitting: false,
       isTouched: false,
+      isPristine: true,
+      isDirty: false,
       isValid: true,
       isValidating: false,
       submissionAttempts: 0,
@@ -87,6 +91,8 @@ describe('form api', () => {
       isSubmitted: false,
       isSubmitting: false,
       isTouched: false,
+      isPristine: true,
+      isDirty: false,
       isValid: true,
       isValidating: false,
       submissionAttempts: 30,
@@ -130,6 +136,8 @@ describe('form api', () => {
       isSubmitted: false,
       isSubmitting: false,
       isTouched: false,
+      isPristine: true,
+      isDirty: false,
       isValid: true,
       isValidating: false,
       submissionAttempts: 300,
@@ -170,6 +178,8 @@ describe('form api', () => {
       isSubmitted: false,
       isSubmitting: false,
       isTouched: false,
+      isPristine: true,
+      isDirty: false,
       isValid: true,
       isValidating: false,
       submissionAttempts: 0,
@@ -204,6 +214,40 @@ describe('form api', () => {
     expect(form.getFieldValue('name')).toEqual('other')
   })
 
+  it("should be dirty after a field's value has been set", () => {
+    const form = new FormApi({
+      defaultValues: {
+        name: 'test',
+      },
+    })
+    form.mount()
+
+    form.setFieldValue('name', 'other', { touch: true })
+
+    expect(form.state.isDirty).toBe(true)
+    expect(form.state.isPristine).toBe(false)
+  })
+
+  it('should be clean again after being reset from a dirty state', () => {
+    const form = new FormApi({
+      defaultValues: {
+        name: 'test',
+      },
+    })
+    form.mount()
+
+    form.setFieldMeta('name', (meta) => ({
+      ...meta,
+      isDirty: true,
+      isPristine: false,
+    }))
+
+    form.reset()
+
+    expect(form.state.isDirty).toBe(false)
+    expect(form.state.isPristine).toBe(true)
+  })
+
   it("should push an array field's value", () => {
     const form = new FormApi({
       defaultValues: {
