Sync

docs/framework/react/guides/basic-concepts.md

@@ -92,17 +92,40 @@ const {
 } = field.state
 ```
 
-There are three field states that can be 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.
+There are three states in the metadata that can be useful to see how the user interacts with a field:
+
+- _"isTouched"_, after the user clicks/tabs into the field
+- _"isPristine"_, until the user changes the field value
+- _"isDirty"_, after the fields value has been changed
 
 ```tsx
 const { isTouched, isPristine, isDirty } = field.state.meta
 ```
 
 ![Field states](https://raw.githubusercontent.com/TanStack/form/main/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 `false` in RHF, but `true` 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.`
+## Understanding 'isDirty' in Different Libraries
+
+Non-Persistent `dirty` state
+
+- **Libraries**: React Hook Form (RHF), Formik, Final Form.
+- **Behavior**: A field is 'dirty' if its value differs from the default. Reverting to the default value makes it 'clean' again.
+
+Persistent `dirty` state
+
+- **Libraries**: Angular Form, Vue FormKit.
+- **Behavior**: A field remains 'dirty' once changed, even if reverted to the default value.
+
+We have chosen the persistent 'dirty' state model. To also support a non-persistent 'dirty' state, we introduce the isDefault flag. This flag acts as an inverse of the non-persistent 'dirty' state.
+
+```tsx
+const { isTouched, isPristine, isDirty, isDefaultValue } = field.state.meta
+
+// The following line will re-create the non-Persistent `dirty` functionality.
+const nonPersistentIsDirty = !isDefaultValue
+```
+
+![Field states extended](https://raw.githubusercontent.com/TanStack/form/main/docs/assets/field-states-extended.png)
 
 ## Field API
 

docs/reference/classes/fieldapi.md

@@ -7,7 +7,7 @@ title: FieldApi
 
 # Class: FieldApi\<TParentData, TName, TData, TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync, TOnSubmit, TOnSubmitAsync, TFormOnMount, TFormOnChange, TFormOnChangeAsync, TFormOnBlur, TFormOnBlurAsync, TFormOnSubmit, TFormOnSubmitAsync, TFormOnServer, TParentSubmitMeta\>
 
-Defined in: [packages/form-core/src/FieldApi.ts:859](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L859)
+Defined in: [packages/form-core/src/FieldApi.ts:863](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L863)
 
 A class representing the API for managing a form field.
 
@@ -65,7 +65,7 @@ the `new FieldApi` constructor.
 new FieldApi<TParentData, TName, TData, TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync, TOnSubmit, TOnSubmitAsync, TFormOnMount, TFormOnChange, TFormOnChangeAsync, TFormOnBlur, TFormOnBlurAsync, TFormOnSubmit, TFormOnSubmitAsync, TFormOnServer, TParentSubmitMeta>(opts): FieldApi<TParentData, TName, TData, TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync, TOnSubmit, TOnSubmitAsync, TFormOnMount, TFormOnChange, TFormOnChangeAsync, TFormOnBlur, TFormOnBlurAsync, TFormOnSubmit, TFormOnSubmitAsync, TFormOnServer, TParentSubmitMeta>
 ```
 
-Defined in: [packages/form-core/src/FieldApi.ts:991](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L991)
+Defined in: [packages/form-core/src/FieldApi.ts:995](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L995)
 
 Initializes a new `FieldApi` instance.
 
@@ -87,7 +87,7 @@ Initializes a new `FieldApi` instance.
 form: FormApi<TParentData, TFormOnMount, TFormOnChange, TFormOnChangeAsync, TFormOnBlur, TFormOnBlurAsync, TFormOnSubmit, TFormOnSubmitAsync, TFormOnServer, TParentSubmitMeta>;
 ```
 
-Defined in: [packages/form-core/src/FieldApi.ts:903](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L903)
+Defined in: [packages/form-core/src/FieldApi.ts:907](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L907)
 
 A reference to the form API instance.
 
@@ -99,7 +99,7 @@ A reference to the form API instance.
 name: DeepKeys<TParentData>;
 ```
 
-Defined in: [packages/form-core/src/FieldApi.ts:927](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L927)
+Defined in: [packages/form-core/src/FieldApi.ts:931](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L931)
 
 The field name.
 
@@ -111,7 +111,7 @@ The field name.
 options: FieldApiOptions<TParentData, TName, TData, TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync, TOnSubmit, TOnSubmitAsync, TFormOnMount, TFormOnChange, TFormOnChangeAsync, TFormOnBlur, TFormOnBlurAsync, TFormOnSubmit, TFormOnSubmitAsync, TFormOnServer, TParentSubmitMeta>;
 ```
 
-Defined in: [packages/form-core/src/FieldApi.ts:931](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L931)
+Defined in: [packages/form-core/src/FieldApi.ts:935](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L935)
 
 The field options.
 
@@ -123,7 +123,7 @@ The field options.
 store: Derived<FieldState<TParentData, TName, TData, TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync, TOnSubmit, TOnSubmitAsync, TFormOnMount, TFormOnChange, TFormOnChangeAsync, TFormOnBlur, TFormOnBlurAsync, TFormOnSubmit, TFormOnSubmitAsync>>;
 ```
 
-Defined in: [packages/form-core/src/FieldApi.ts:955](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L955)
+Defined in: [packages/form-core/src/FieldApi.ts:959](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L959)
 
 The field state store.
 
@@ -135,7 +135,7 @@ The field state store.
 timeoutIds: object;
 ```
 
-Defined in: [packages/form-core/src/FieldApi.ts:982](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L982)
+Defined in: [packages/form-core/src/FieldApi.ts:986](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L986)
 
 #### formListeners
 
@@ -165,7 +165,7 @@ validations: Record<ValidationCause, null | Timeout>;
 get state(): FieldState<TParentData, TName, TData, TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync, TOnSubmit, TOnSubmitAsync, TFormOnMount, TFormOnChange, TFormOnChangeAsync, TFormOnBlur, TFormOnBlurAsync, TFormOnSubmit, TFormOnSubmitAsync>
 ```
 
-Defined in: [packages/form-core/src/FieldApi.ts:979](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L979)
+Defined in: [packages/form-core/src/FieldApi.ts:983](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L983)
 
 The current field state.
 
@@ -181,7 +181,7 @@ The current field state.
 getInfo(): FieldInfo<TParentData>
 ```
 
-Defined in: [packages/form-core/src/FieldApi.ts:1245](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1245)
+Defined in: [packages/form-core/src/FieldApi.ts:1249](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1249)
 
 Gets the field information object.
 
@@ -197,7 +197,7 @@ Gets the field information object.
 getMeta(): FieldMeta<TParentData, TName, TData, TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync, TOnSubmit, TOnSubmitAsync, TFormOnMount, TFormOnChange, TFormOnChangeAsync, TFormOnBlur, TFormOnBlurAsync, TFormOnSubmit, TFormOnSubmitAsync>
 ```
 
-Defined in: [packages/form-core/src/FieldApi.ts:1213](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1213)
+Defined in: [packages/form-core/src/FieldApi.ts:1217](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1217)
 
 #### Returns
 
@@ -211,7 +211,7 @@ Defined in: [packages/form-core/src/FieldApi.ts:1213](https://github.com/TanStac
 getValue(): TData
 ```
 
-Defined in: [packages/form-core/src/FieldApi.ts:1198](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1198)
+Defined in: [packages/form-core/src/FieldApi.ts:1202](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1202)
 
 Gets the current field value.
 
@@ -231,7 +231,7 @@ Use `field.state.value` instead.
 handleBlur(): void
 ```
 
-Defined in: [packages/form-core/src/FieldApi.ts:1657](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1657)
+Defined in: [packages/form-core/src/FieldApi.ts:1661](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1661)
 
 Handles the blur event.
 
@@ -247,7 +247,7 @@ Handles the blur event.
 handleChange(updater): void
 ```
 
-Defined in: [packages/form-core/src/FieldApi.ts:1650](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1650)
+Defined in: [packages/form-core/src/FieldApi.ts:1654](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1654)
 
 Handles the change event.
 
@@ -272,7 +272,7 @@ insertValue(
    opts?): void
 ```
 
-Defined in: [packages/form-core/src/FieldApi.ts:1262](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1262)
+Defined in: [packages/form-core/src/FieldApi.ts:1266](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1266)
 
 Inserts a value at the specified index, shifting the subsequent values to the right.
 
@@ -302,7 +302,7 @@ Inserts a value at the specified index, shifting the subsequent values to the ri
 mount(): () => void
 ```
 
-Defined in: [packages/form-core/src/FieldApi.ts:1088](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1088)
+Defined in: [packages/form-core/src/FieldApi.ts:1092](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1092)
 
 Mounts the field instance to the form.
 
@@ -325,7 +325,7 @@ moveValue(
    opts?): void
 ```
 
-Defined in: [packages/form-core/src/FieldApi.ts:1306](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1306)
+Defined in: [packages/form-core/src/FieldApi.ts:1310](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1310)
 
 Moves the value at the first specified index to the second specified index.
 
@@ -357,7 +357,7 @@ parseValueWithSchema(schema):
   | StandardSchemaV1Issue[]
 ```
 
-Defined in: [packages/form-core/src/FieldApi.ts:1699](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1699)
+Defined in: [packages/form-core/src/FieldApi.ts:1703](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1703)
 
 Parses the field's value with the given schema and returns
 issues (if any). This method does NOT set any internal errors.
@@ -385,7 +385,7 @@ parseValueWithSchemaAsync(schema): Promise<
 | StandardSchemaV1Issue[]>
 ```
 
-Defined in: [packages/form-core/src/FieldApi.ts:1711](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1711)
+Defined in: [packages/form-core/src/FieldApi.ts:1715](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1715)
 
 Parses the field's value with the given schema and returns
 issues (if any). This method does NOT set any internal errors.
@@ -412,7 +412,7 @@ The standard schema to parse this field's value with.
 pushValue(value, opts?): void
 ```
 
-Defined in: [packages/form-core/src/FieldApi.ts:1250](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1250)
+Defined in: [packages/form-core/src/FieldApi.ts:1254](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1254)
 
 Pushes a new value to the field.
 
@@ -438,7 +438,7 @@ Pushes a new value to the field.
 removeValue(index, opts?): void
 ```
 
-Defined in: [packages/form-core/src/FieldApi.ts:1288](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1288)
+Defined in: [packages/form-core/src/FieldApi.ts:1292](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1292)
 
 Removes a value at the specified index.
 
@@ -467,7 +467,7 @@ replaceValue(
    opts?): void
 ```
 
-Defined in: [packages/form-core/src/FieldApi.ts:1275](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1275)
+Defined in: [packages/form-core/src/FieldApi.ts:1279](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1279)
 
 Replaces a value at the specified index.
 
@@ -497,7 +497,7 @@ Replaces a value at the specified index.
 setErrorMap(errorMap): void
 ```
 
-Defined in: [packages/form-core/src/FieldApi.ts:1674](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1674)
+Defined in: [packages/form-core/src/FieldApi.ts:1678](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1678)
 
 Updates the field's errorMap
 
@@ -519,7 +519,7 @@ Updates the field's errorMap
 setMeta(updater): void
 ```
 
-Defined in: [packages/form-core/src/FieldApi.ts:1218](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1218)
+Defined in: [packages/form-core/src/FieldApi.ts:1222](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1222)
 
 Sets the field metadata.
 
@@ -541,7 +541,7 @@ Sets the field metadata.
 setValue(updater, options?): void
 ```
 
-Defined in: [packages/form-core/src/FieldApi.ts:1205](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1205)
+Defined in: [packages/form-core/src/FieldApi.ts:1209](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1209)
 
 Sets the field value and run the `change` validator.
 
@@ -570,7 +570,7 @@ swapValues(
    opts?): void
 ```
 
-Defined in: [packages/form-core/src/FieldApi.ts:1297](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1297)
+Defined in: [packages/form-core/src/FieldApi.ts:1301](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1301)
 
 Swaps the values at the specified indices.
 
@@ -600,7 +600,7 @@ Swaps the values at the specified indices.
 update(opts): void
 ```
 
-Defined in: [packages/form-core/src/FieldApi.ts:1141](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1141)
+Defined in: [packages/form-core/src/FieldApi.ts:1145](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1145)
 
 Updates the field instance with new options.
 
@@ -622,7 +622,7 @@ Updates the field instance with new options.
 validate(cause, opts?): unknown[] | Promise<unknown[]>
 ```
 
-Defined in: [packages/form-core/src/FieldApi.ts:1617](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1617)
+Defined in: [packages/form-core/src/FieldApi.ts:1621](https://github.com/TanStack/form/blob/main/packages/form-core/src/FieldApi.ts#L1621)
 
 Validates the field value.