docs: corrected field state definitions

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

@@ -40,21 +40,51 @@ Each field has its own state, which includes its current value, validation statu
 
 Example:
 
-```tsx
+```ts
 const {
   value,
   meta: { errors, 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.
+There are four states in the metadata that can be useful to see how the user interacts with a field:
 
-```tsx
-const { isTouched, isPristine, isDirty } = field.state.meta
+- _"isTouched"_, after the user changes the field or blurs the field
+- _"isDirty"_, after the field's value has been changed, even if it's been reverted to the default. Opposite of _"isPristine"_
+- _"isPristine"_, until the user changes the field value. Opposite of _"isDirty"_
+- _"isBlurred"_, after the field has been blurred
+
+```ts
+const { isTouched, isDirty, isPristine, isBlurred } = field.state.meta
 ```
 
 ![Field states](https://raw.githubusercontent.com/TanStack/form/main/docs/assets/field-states.png)
 
+## 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 an additional flag:
+
+- _"isDefaultValue"_, whether the field's current value is the default value
+
+```ts
+const { isDefaultValue, isTouched } = 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
 
 The Field API is an object accessed in the `tanstackField.api` property when creating a field. It provides methods for working with the field's state.

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

@@ -86,17 +86,47 @@ For Example:
 
 Each field has its own state, which includes its current value, validation status, error messages, and other metadata. You can access a field's state using its `field.state` property.
 
-```tsx
+```ts
 const {
   value,
   meta: { errors, 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.
+There are four states in the metadata that can be useful to see how the user interacts with a field:
 
-```tsx
-const { isTouched, isPristine, isDirty } = field.state.meta
+- _"isTouched"_, after the user changes the field or blurs the field
+- _"isDirty"_, after the field's value has been changed, even if it's been reverted to the default. Opposite of `isPristine`
+- _"isPristine"_, until the user changes the field value. Opposite of `isDirty`
+- _"isBlurred"_, after the field has been blurred
+
+```ts
+const { isTouched, isDirty, isPristine, isBlurred } = field.state.meta
 ```
 
 ![Field states](https://raw.githubusercontent.com/TanStack/form/main/docs/assets/field-states.png)
+
+## 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 an additional flag:
+
+- _"isDefaultValue"_, whether the field's current value is the default value
+
+```ts
+const { isDefaultValue, isTouched } = 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)

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

@@ -85,21 +85,22 @@ Each field has its own state, which includes its current value, validation statu
 
 Example:
 
-```tsx
+```ts
 const {
   value,
   meta: { errors, isValidating },
 } = field.state
 ```
 
-There are three states in the metadata that can be useful to see how the user interacts with a field:
+There are four 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
+- _"isTouched"_, after the user changes the field or blurs the field
+- _"isDirty"_, after the field's value has been changed, even if it's been reverted to the default. Opposite of `isPristine`
+- _"isPristine"_, until the user changes the field value. Opposite of `isDirty`
+- _"isBlurred"_, after the field has been blurred
 
-```tsx
-const { isTouched, isPristine, isDirty } = field.state.meta
+```ts
+const { isTouched, isDirty, isPristine, isBlurred } = field.state.meta
 ```
 
 ![Field states](https://raw.githubusercontent.com/TanStack/form/main/docs/assets/field-states.png)
@@ -116,10 +117,12 @@ 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.
+We have chosen the persistent 'dirty' state model. To also support a non-persistent 'dirty' state, we introduce an additional flag:
 
-```tsx
-const { isTouched, isPristine, isDirty, isDefaultValue } = field.state.meta
+- _"isDefaultValue"_, whether the field's current value is the default value
+
+```ts
+const { isDefaultValue, isTouched } = field.state.meta
 
 // The following line will re-create the non-Persistent `dirty` functionality.
 const nonPersistentIsDirty = !isDefaultValue

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

@@ -77,21 +77,51 @@ Each field has its own state, which includes its current value, validation statu
 
 Example:
 
-```tsx
+```ts
 const {
   value,
   meta: { errors, 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.
+There are four states in the metadata that can be useful to see how the user interacts with a field:
 
-```tsx
-const { isTouched, isPristine, isDirty } = field().state.meta
+- _"isTouched"_, after the user changes the field or blurs the field
+- _"isDirty"_, after the field's value has been changed, even if it's been reverted to the default. Opposite of `isPristine`
+- _"isPristine"_, until the user changes the field value. Opposite of `isDirty`
+- _"isBlurred"_, after the field has been blurred
+
+```ts
+const { isTouched, isDirty, isPristine, isBlurred } = field().state.meta
 ```
 
 ![Field states](https://raw.githubusercontent.com/TanStack/form/main/docs/assets/field-states.png)
 
+## 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 an additional flag:
+
+- _"isDefaultValue"_, whether the field's current value is the default value
+
+```ts
+const { isDefaultValue, isTouched } = 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
 
 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.

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

@@ -83,14 +83,44 @@ const {
 } = 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.
+There are four states in the metadata that can be useful to see how the user interacts with a field:
+
+- _"isTouched"_, after the user changes the field or blurs the field
+- _"isDirty"_, after the field's value has been changed, even if it's been reverted to the default. Opposite of `isPristine`
+- _"isPristine"_, until the user changes the field value. Opposite of `isDirty`
+- _"isBlurred"_, after the field has been blurred
 
 ```ts
-const { isTouched, isPristine, isDirty } = field.state.meta
+const { isTouched, isDirty, isPristine, isBlurred } = field.state.meta
 ```
 
 ![Field states](https://raw.githubusercontent.com/TanStack/form/main/docs/assets/field-states.png)
 
+## 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 an additional flag:
+
+- _"isDefaultValue"_, whether the field's current value is the default value
+
+```ts
+const { isDefaultValue, isTouched } = 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
 
 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.

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

@@ -76,25 +76,55 @@ Example:
 
 ## Field State
 
-Each field has its own state, which includes its current value, validation status, error messages, and other metadata. You can access a field's state using the `field.state` property.
+Each field has its own state, which includes its current value, validation status, error messages, and other metadata. You can access a field's state using the `field().state` property.
 
 Example:
 
-```js
+```ts
 const {
   value,
   meta: { errors, 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.
+There are four states in the metadata that can be useful to see how the user interacts with a field:
 
-```js
-const { isTouched, isPristine, isDirty } = field.state.meta
+- _"isTouched"_, after the user changes the field or blurs the field
+- _"isDirty"_, after the field's value has been changed, even if it's been reverted to the default. Opposite of `isPristine`
+- _"isPristine"_, until the user changes the field value. Opposite of `isDirty`
+- _"isBlurred"_, after the field has been blurred
+
+```ts
+const { isTouched, isDirty, isPristine, isBlurred } = field.state.meta
 ```
 
 ![Field states](https://raw.githubusercontent.com/TanStack/form/main/docs/assets/field-states.png)
 
+## 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 an additional flag:
+
+- _"isDefaultValue"_, whether the field's current value is the default value
+
+```ts
+const { isDefaultValue, isTouched } = 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
 
 The Field API is an object provided by a scoped slot using the `v-slot` directive. This slot receives an argument named `field` that provides methods and properties for working with the field's state.