Merge branch 'main' of github.com:TanStack/form into feat-deep-keys-of-type

Author: LeCarbonator

docs/assets/field-states-extended.png

@@ -487,6 +487,10 @@
             {
               "label": "Balastrong's Tutorial",
               "to": "framework/react/community/balastrong-tutorial"
+            },
+            {
+              "label": "Community Tutorials",
+              "to": "framework/react/community/tutorials"
             }
           ]
         }

docs/assets/field-states.png

@@ -120,7 +120,7 @@ So you can control when the validation is done by implementing the desired callb
         (blur)="age.api.handleBlur()"
         (input)="age.api.handleChange($any($event).target.valueAsNumber)"
       />
-      @if (age.api.state.meta.errors) {
+      @if (!age.api.state.meta.isValid) {
         <em role="alert">{{ age.api.state.meta.errors.join(', ') }}</em>
       }
     </ng-container>

docs/config.json

@@ -0,0 +1,14 @@
+---
+id: community-tutorials
+title: Community Tutorials
+---
+
+This page is a collection of community-created tutorials, articles, and videos that can help you learn more about TanStack Form from other developers. If you created a resource that you would like to add to this list, please open a PR! We keep them in chronological order by publish date to ensure the most up to date content is at the top.
+
+> Please note that the content listed here is entirely community maintained. While it may not be fully aligned with official recommendations and best practices, it can still offer valuable insights and alternative perspectives.
+
+## TanStack Form Tutorial - Best Form Library for React?
+
+[Watch Video](https://youtu.be/5oFQd-uAAHo) (March 7th, 2025)
+
+A tutorial from [Atharva Deosthale](https://links.atharva.codes) using TanStack Form in a Next.js project. The video is made for people who are just getting started with knowing TanStack Form and will cover client-side form validation and server-side form validation by taking advantage of the Form SDK. This tutorial expects you to have basic knowledge of working of React and client-server architectures.

docs/framework/angular/guides/validation.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/framework/react/community/tutorials.md

@@ -19,9 +19,9 @@ Here is an example:
     <>
       <Text>Age:</Text>
       <TextInput value={field.state.value} onChangeText={field.handleChange} />
-      {field.state.meta.errors ? (
+      {!field.state.meta.isValid && (
         <Text>{field.state.meta.errors.join(', ')}</Text>
-      ) : null}
+      )}
     </>
   )}
 </form.Field>

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

@@ -33,9 +33,9 @@ Here is an example:
         type="number"
         onChange={(e) => field.handleChange(e.target.valueAsNumber)}
       />
-      {field.state.meta.errors ? (
+      {!field.state.meta.isValid && (
         <em role="alert">{field.state.meta.errors.join(', ')}</em>
-      ) : null}
+      )}
     </>
   )}
 </form.Field>
@@ -64,9 +64,9 @@ In the example above, the validation is done at each keystroke (`onChange`). If,
         // We always need to implement onChange, so that TanStack Form receives the changes
         onChange={(e) => field.handleChange(e.target.valueAsNumber)}
       />
-      {field.state.meta.errors ? (
+      {!field.state.meta.isValid && (
         <em role="alert">{field.state.meta.errors.join(', ')}</em>
-      ) : null}
+      )}
     </>
   )}
 </form.Field>
@@ -96,9 +96,9 @@ So you can control when the validation is done by implementing the desired callb
         // We always need to implement onChange, so that TanStack Form receives the changes
         onChange={(e) => field.handleChange(e.target.valueAsNumber)}
       />
-      {field.state.meta.errors ? (
+      {!field.state.meta.isValid && (
         <em role="alert">{field.state.meta.errors.join(', ')}</em>
-      ) : null}
+      )}
     </>
   )}
 </form.Field>
@@ -122,9 +122,9 @@ Once you have your validation in place, you can map the errors from an array to
     return (
       <>
         {/* ... */}
-        {field.state.meta.errors.length ? (
+        {!field.state.meta.isValid && (
           <em>{field.state.meta.errors.join(',')}</em>
-        ) : null}
+        )}
       </>
     )
   }}
@@ -273,9 +273,9 @@ export default function App() {
                 type="number"
                 onChange={(e) => field.handleChange(e.target.valueAsNumber)}
               />
-              {field.state.meta.errors ? (
+              {!field.state.meta.isValid && (
                 <em role="alert">{field.state.meta.errors.join(', ')}</em>
-              ) : null}
+              )}
             </>
           )}
         </form.Field>
@@ -357,9 +357,9 @@ To do this, we have dedicated `onChangeAsync`, `onBlurAsync`, and other methods
         type="number"
         onChange={(e) => field.handleChange(e.target.valueAsNumber)}
       />
-      {field.state.meta.errors ? (
+      {!field.state.meta.isValid && (
         <em role="alert">{field.state.meta.errors.join(', ')}</em>
-      ) : null}
+      )}
     </>
   )}
 </form.Field>
@@ -389,9 +389,9 @@ Synchronous and Asynchronous validations can coexist. For example, it is possibl
         onBlur={field.handleBlur}
         onChange={(e) => field.handleChange(e.target.valueAsNumber)}
       />
-      {field.state.meta.errors ? (
+      {!field.state.meta.isValid && (
         <em role="alert">{field.state.meta.errors.join(', ')}</em>
-      ) : null}
+      )}
     </>
   )}
 </form.Field>

docs/framework/react/guides/react-native.md

@@ -120,9 +120,9 @@ const PeoplePage = () => {
             type="number"
             onChange={(e) => field.handleChange(e.target.valueAsNumber)}
           />
-          {field.state.meta.errors.length ? (
+          {!field.state.meta.isValid && (
             <em>{field.state.meta.errors.join(',')}</em>
-          ) : null}
+          )}
         </>
       )}
     />

docs/framework/react/guides/validation.md

@@ -33,7 +33,7 @@ Here is an example:
         type="number"
         onInput={(e) => field().handleChange(e.target.valueAsNumber)}
       />
-      {field().state.meta.errors ? (
+      {!field().state.meta.isValid ? (
         <em role="alert">{field().state.meta.errors.join(', ')}</em>
       ) : null}
     </>
@@ -64,7 +64,7 @@ In the example above, the validation is done at each keystroke (`onChange`). If,
         // We always need to implement onInput, so that TanStack Form receives the changes
         onInput={(e) => field().handleChange(e.target.valueAsNumber)}
       />
-      {field().state.meta.errors ? (
+      {!field().state.meta.isValid ? (
         <em role="alert">{field().state.meta.errors.join(', ')}</em>
       ) : null}
     </>
@@ -96,7 +96,7 @@ So you can control when the validation is done by implementing the desired callb
         // We always need to implement onInput, so that TanStack Form receives the changes
         onInput={(e) => field().handleChange(e.target.valueAsNumber)}
       />
-      {field().state.meta.errors ? (
+      {!field().state.meta.isValid ? (
         <em role="alert">{field().state.meta.errors.join(', ')}</em>
       ) : null}
     </>
@@ -122,7 +122,7 @@ Once you have your validation in place, you can map the errors from an array to
     return (
       <>
         {/* ... */}
-        {field().state.meta.errors.length ? (
+        {!field().state.meta.isValid ? (
           <em>{field().state.meta.errors.join(',')}</em>
         ) : null}
       </>
@@ -364,7 +364,7 @@ To do this, we have dedicated `onChangeAsync`, `onBlurAsync`, and other methods
         type="number"
         onInput={(e) => field().handleChange(e.target.valueAsNumber)}
       />
-      {field().state.meta.errors ? (
+      {!field().state.meta.isValid ? (
         <em role="alert">{field().state.meta.errors.join(', ')}</em>
       ) : null}
     </>

docs/framework/react/quick-start.md

@@ -13,7 +13,7 @@ title: useStore
 function useStore<TState, TSelected>(store, selector?): Accessor<TSelected>
 ```
 
-Defined in: node\_modules/.pnpm/@tanstack+solid-store@0.7.0\_solid-js@1.9.5/node\_modules/@tanstack/solid-store/dist/esm/index.d.ts:8
+Defined in: node\_modules/.pnpm/@tanstack+solid-store@0.7.0\_solid-js@1.9.6/node\_modules/@tanstack/solid-store/dist/esm/index.d.ts:8
 
 ### Type Parameters
 
@@ -41,7 +41,7 @@ Defined in: node\_modules/.pnpm/@[email protected]\[email protected]/node
 function useStore<TState, TSelected>(store, selector?): Accessor<TSelected>
 ```
 
-Defined in: node\_modules/.pnpm/@tanstack+solid-store@0.7.0\_solid-js@1.9.5/node\_modules/@tanstack/solid-store/dist/esm/index.d.ts:9
+Defined in: node\_modules/.pnpm/@tanstack+solid-store@0.7.0\_solid-js@1.9.6/node\_modules/@tanstack/solid-store/dist/esm/index.d.ts:9
 
 ### Type Parameters
 

docs/framework/solid/guides/validation.md

@@ -35,7 +35,7 @@ Here is an example:
         @input="(e) => field.handleChange((e.target as HTMLInputElement).valueAsNumber)
                 "
       />
-      <em role="alert" v-if="field.state.meta.errors">{{
+      <em role="alert" v-if="!field.state.meta.isValid">{{
         field.state.meta.errors.join(', ')
       }}</em>
     </template>
@@ -69,7 +69,7 @@ In the example above, the validation is done at each keystroke (`onChange`). If,
         @input="(e) => field.handleChange((e.target as HTMLInputElement).valueAsNumber)
                 "
       />
-      <em role="alert" v-if="field.state.meta.errors">{{
+      <em role="alert" v-if="!field.state.meta.isValid">{{
         field.state.meta.errors.join(', ')
       }}</em>
     </template>
@@ -104,7 +104,7 @@ So you can control when the validation is done by implementing the desired callb
         @input="(e) => field.handleChange((e.target as HTMLInputElement).valueAsNumber)
                 "
       />
-      <em role="alert" v-if="field.state.meta.errors">{{
+      <em role="alert" v-if="!field.state.meta.isValid">{{
         field.state.meta.errors.join(', ')
       }}</em>
     </template>
@@ -131,7 +131,7 @@ Once you have your validation in place, you can map the errors from an array to
   >
     <template v-slot="{ field }">
       <!-- ... -->
-      <em role="alert" v-if="field.state.meta.errors">{{
+      <em role="alert" v-if="!field.state.meta.isValid">{{
         field.state.meta.errors.join(', ')
       }}</em>
     </template>
@@ -346,7 +346,7 @@ const onChangeAge = async ({ value }) => {
             field.handleChange((e.target as HTMLInputElement).valueAsNumber)
         "
       />
-      <em role="alert" v-if="field.state.meta.errors">{{
+      <em role="alert" v-if="!field.state.meta.isValid">{{
         field.state.meta.errors.join(', ')
       }}</em>
     </template>
@@ -391,7 +391,7 @@ const onBlurAgeAsync = async ({ value }) => {
             field.handleChange((e.target as HTMLInputElement).valueAsNumber)
         "
       />
-      <em role="alert" v-if="field.state.meta.errors">{{
+      <em role="alert" v-if="!field.state.meta.isValid">{{
         field.state.meta.errors.join(', ')
       }}</em>
     </template>

docs/framework/solid/reference/functions/usestore.md

@@ -34,7 +34,7 @@ import type { AnyFieldApi } from '@tanstack/react-form'
 function FieldInfo({ field }: { field: AnyFieldApi }) {
   return (
     <>
-      {field.state.meta.isTouched && field.state.meta.errors.length ? (
+      {field.state.meta.isTouched && !field.state.meta.isValid ? (
         <em>{field.state.meta.errors.join(', ')}</em>
       ) : null}
       {field.state.meta.isValidating ? 'Validating...' : null}