Merge branch 'main' into derived-state-refactor

# Conflicts: # docs/reference/classes/fieldapi.md # docs/reference/classes/formapi.md # docs/reference/type-aliases/fieldmeta.md # docs/reference/type-aliases/fieldstate.md # docs/reference/type-aliases/formstate.md # examples/react/next-server-actions/package.json # examples/react/remix/package.json # examples/react/tanstack-start/package.json # packages/angular-form/package.json # packages/form-core/package.json # packages/form-core/src/FieldApi.ts # packages/form-core/src/FormApi.ts # packages/react-form/package.json # packages/solid-form/package.json # packages/vue-form/package.json # pnpm-lock.yaml
TanStack · Dec 26, 2024 · bad44a9 · bad44a9
2 parents 4ce1db7 + d178f33
commit bad44a9
Show file tree

Hide file tree

Showing 138 changed files with 3,424 additions and 2,216 deletions.
diff --git a/.nvmrc b/.nvmrc
@@ -1 +1 @@
-20.15.1
+22.12.0
diff --git a/codecov.yml b/codecov.yml
@@ -2,5 +2,5 @@ coverage:
   status:
     project:
       default:
-        target: 90%
+        target: auto
         threshold: 1%
diff --git a/docs/config.json b/docs/config.json
@@ -408,6 +408,21 @@
         }
       ]
     },
+    {
+      "label": "Community Resources",
+      "children": [],
+      "frameworks": [
+        {
+          "label": "react",
+          "children": [
+            {
+              "label": "Balastrong's Tutorial",
+              "to": "framework/react/community/balastrong-tutorial"
+            }
+          ]
+        }
+      ]
+    },
     {
       "label": "Examples",
       "children": [],
@@ -427,6 +442,10 @@
               "label": "TanStack Query Integration",
               "to": "framework/react/examples/query-integration"
             },
+            {
+              "label": "Standard Schema",
+              "to": "framework/react/examples/standard-schema"
+            },
             {
               "label": "Yup",
               "to": "framework/react/examples/yup"

diff --git a/docs/framework/angular/guides/basic-concepts.md b/docs/framework/angular/guides/basic-concepts.md
@@ -114,14 +114,21 @@ export class AppComponent {
 }
 ```
 
-## Validation Adapters
+## Validation with Standard Schema Libraries
 
-In addition to hand-rolled validation options, we also provide adapters like `@tanstack/zod-form-adapter`, `@tanstack/yup-form-adapter`, and `@tanstack/valibot-form-adapter` to enable usage with common schema validation tools like [Zod](https://zod.dev/), [Yup](https://github.com/jquense/yup), and [Valibot](https://valibot.dev/).
+In addition to hand-rolled validation options, we also support the [Standard Schema](https://github.com/standard-schema/standard-schema) specification.
+
+You can define a schema using any of the libraries implementing the specification and pass it to a form or field validator.
+
+Supported libraries include:
+
+- [Zod](https://zod.dev/)
+- [Valibot](https://valibot.dev/)
+- [ArkType](https://arktype.io/)
 
 Example:
 
 ```angular-ts
-import { zodValidator } from '@tanstack/zod-form-adapter'
 import { z } from 'zod'
 
 @Component({
@@ -132,7 +139,6 @@ import { z } from 'zod'
     <ng-container
       [tanstackField]="form"
       name="firstName"
-      [validatorAdapter]="zodValidator()"
       [validators]="{
         onChange: z.string().min(3, 'First name must be at least 3 characters'),
         onChangeAsyncDebounceMs: 500,
@@ -166,7 +172,6 @@ export class AppComponent {
   })
 
   z = z
-  zodValidator = zodValidator
 }
 ```
 

diff --git a/docs/framework/angular/guides/validation.md b/docs/framework/angular/guides/validation.md
@@ -382,24 +382,22 @@ This will debounce every async call with a 500ms delay. You can even override th
 
 > This will run `onChangeAsync` every 1500ms while `onBlurAsync` will run every 500ms.
 
-## Adapter-Based Validation (Zod, Yup, Valibot)
+## Validation through Schema Libraries
 
-While functions provide more flexibility and customization over your validation, they can be a bit verbose. To help solve this, there are libraries like [Valibot](https://valibot.dev/), [Yup](https://github.com/jquense/yup), and [Zod](https://zod.dev/) that provide schema-based validation to make shorthand and type-strict validation substantially easier.
+While functions provide more flexibility and customization over your validation, they can be a bit verbose. To help solve this, there are libraries that provide schema-based validation to make shorthand and type-strict validation substantially easier. You can also define a single schema for your entire form and pass it to the form level, errors will be automatically propagated to the fields.
 
-Luckily, we support all of these libraries through official adapters:
+### Standard Schema Libraries
 
-```bash
-$ npm install @tanstack/zod-form-adapter zod
-# or
-$ npm install @tanstack/yup-form-adapter yup
-# or
-$ npm install @tanstack/valibot-form-adapter valibot
-```
+TanStack Form natively supports all libraries following the [Standard Schema specification](https://github.com/standard-schema/standard-schema), most notably:
+- [Zod](https://zod.dev/)
+- [Valibot](https://valibot.dev/)
+- [ArkType](https://arktype.io/)
 
-Once done, we can add the adapter to the `validator` property on the form or field:
+*Note:* make sure to use the latest version of the schema libraries as older versions might not support Standard Schema yet.
+
+To use schemas from these libraries you can pass them to the `validators` props as you would do with a custom function:
 
 ```angular-ts
-import { zodValidator } from '@tanstack/zod-form-adapter'
 import { z } from 'zod'
 
 @Component({
@@ -420,19 +418,18 @@ import { z } from 'zod'
   `,
 })
 export class AppComponent {
-  form = injectForm({
-    // Either add the validator here or on `Field`
-    validatorAdapter: zodValidator(),
+  form = injectForm({ 
     // ...
-  })
+   })
 
   z = z
 
   // ...
 }
 ```
 
-These adapters also support async operations using the proper property names:
+Async validations on form and field level are supported as well:
+
 
 ```angular-ts
 @Component({
@@ -469,37 +466,50 @@ export class AppComponent {
 }
 ```
 
-### Form Level Adapter Validation
+### Other Schema Libraries
 
-You can also use the adapter at the form level:
+We also support [Yup](https://github.com/jquense/yup) through an official adapter:
 
-```typescript
-import { zodValidator } from '@tanstack/zod-form-adapter'
-import { z } from 'zod'
+```bash
+$ npm install @tanstack/yup-form-adapter yup
+```
 
-// ...
+Once done, we can add the adapter to the `validator` property on the form or field:
 
-const form = injectForm({
-  validatorAdapter: zodValidator(),
-  validators: {
-    onChange: z.object({
-      age: z.number().gte(13, 'You must be 13 to make an account'),
-    }),
-  },
-})
-```
+```angular-ts
+import { yupValidator } from '@tanstack/yup-form-adapter'
+import * as yup from 'yup'
 
-If you use the adapter at the form level, it will pass the validation to the fields of the same name.
+@Component({
+  selector: 'app-root',
+  standalone: true,
+  imports: [TanStackField],
+  template: `
+    <ng-container
+      [tanstackField]="form"
+      name="age"
+      [validators]="{
+        onChange: yup.number().moreThan(13, 'You must be 13 to make an account'),
+      }"
+      #age="field"
+    >
+      <!-- ... -->
+    </ng-container>
+  `,
+})
+export class AppComponent {
+  form = injectForm({
+    // Either add the validator here or on `Field`
+    validatorAdapter: yupValidator(),
+    // ...
+  })
 
-This means that:
+  yup = yup
 
-```html
-<ng-container [tanstackField]="form" name="age" #age="field">
-  <!-- ... -->
-</ng-container>
+  // ...
+}
 ```
 
-Will still display the error message from the form-level validation.
 
 ## Preventing invalid forms from being submitted
 

diff --git a/docs/framework/angular/reference/functions/injectform.md b/docs/framework/angular/reference/functions/injectform.md
@@ -17,7 +17,9 @@ function injectForm<TFormData, TFormValidator>(opts?): FormApi<TFormData, TFormV
 
 ## Parameters
 
-• **opts?**: `FormOptions`\<`TFormData`, `TFormValidator`\>
+### opts?
+
+`FormOptions`\<`TFormData`, `TFormValidator`\>
 
 ## Returns
 

diff --git a/docs/framework/angular/reference/functions/injectstore.md b/docs/framework/angular/reference/functions/injectstore.md
@@ -19,9 +19,13 @@ function injectStore<TFormData, TFormValidator, TSelected>(form, selector?): Sig
 
 ## Parameters
 
-• **form**: `FormApi`\<`TFormData`, `TFormValidator`\>
+### form
 
-• **selector?**
+`FormApi`\<`TFormData`, `TFormValidator`\>
+
+### selector?
+
+(`state`) => `TSelected`
 
 ## Returns
 

diff --git a/docs/framework/lit/reference/classes/tanstackformcontroller.md b/docs/framework/lit/reference/classes/tanstackformcontroller.md
@@ -25,9 +25,13 @@ new TanStackFormController<TParentData, TFormValidator>(host, config?): TanStack
 
 #### Parameters
 
-• **host**: `ReactiveControllerHost`
+##### host
 
-• **config?**: `FormOptions`\<`TParentData`, `TFormValidator`\>
+`ReactiveControllerHost`
+
+##### config?
+
+`FormOptions`\<`TParentData`, `TFormValidator`\>
 
 #### Returns
 
@@ -67,9 +71,13 @@ field<TName, TFieldValidator, TData>(fieldConfig, render): object
 
 #### Parameters
 
-• **fieldConfig**: `FieldOptions`\<`TParentData`, `TName`, `TFieldValidator`, `TFormValidator`, `TData`\>
+##### fieldConfig
+
+`FieldOptions`\<`TParentData`, `TName`, `TFieldValidator`, `TFormValidator`, `TData`\>
+
+##### render
 
-• **render**: `renderCallback`\<`TParentData`, `TName`, `TFieldValidator`, `TFormValidator`, `TData`\>
+`renderCallback`\<`TParentData`, `TName`, `TFieldValidator`, `TFormValidator`, `TData`\>
 
 #### Returns
 
@@ -81,19 +89,19 @@ field<TName, TFieldValidator, TData>(fieldConfig, render): object
 values: object;
 ```
 
-##### values.form
+###### values.form
 
 ```ts
 form: FormApi<TParentData, TFormValidator>;
 ```
 
-##### values.options
+###### values.options
 
 ```ts
 options: FieldOptions<TParentData, TName, TFieldValidator, TFormValidator, TData>;
 ```
 
-##### values.render
+###### values.render
 
 ```ts
 render: renderCallback<TParentData, TName, TFieldValidator, TFormValidator, TData>;

diff --git a/docs/framework/react/community/balastrong-tutorial.md b/docs/framework/react/community/balastrong-tutorial.md
@@ -0,0 +1,33 @@
+---
+id: balastrong-tutorial
+title: Balastrong's Tutorial
+---
+
+TanStack Form maintainer [Balastrong](https://bsky.app/profile/leonardomontini.dev) has created a series of video tutorials showcasing the most relevant features of the library. You'll find step by step guides that give you some extra insights into what you can build with TanStack Form, plus some nice tips and tricks.
+
+[Watch the full playlist](https://www.youtube.com/playlist?list=PLOQjd5dsGSxInTKUWTxyqSKwZCjDIUs0Y)
+
+
+## 1. [Setup and validation](https://youtu.be/Pf1qn35bgjs)
+
+The first steps into TanStack Form learning all the basics, from setting up the library to creating a simple form with text fields and validation (sync, debounced and async). [Watch video (8:16)](https://youtu.be/Pf1qn35bgjs)
+
+## 2. [Advanced validation](https://youtu.be/Pys2ExswZT0)
+
+An example of data being validated through a backend API while ensuring a smooth user experience by controlling loading state, error messages and linked fields. [Watch video (8:05)](https://youtu.be/Pys2ExswZT0)
+
+## 3. [Array fields](https://youtu.be/0IPPHdjvrzk)
+
+How to handle array fields with primitives (strings, numbers) and objects (nested fields), with validation and reordering. [Watch video (6:53)](https://youtu.be/0IPPHdjvrzk)
+
+## 4. [Reactivity](https://youtu.be/UXRZvNCnE-s)
+
+Learn why form values may not update in real time, why this behavior is intentional, and how to trigger UI updates efficiently. [Watch video (4:26)](https://youtu.be/UXRZvNCnE-s)
+
+## 5. [Form validation with schema libraries](https://youtu.be/HSboMHfPuZA)
+
+Use schema libraries like zod, yup or valibot to define your schema with validation rules. Pass it to TanStack Form through an adapter to validate all fields at once. [Watch video (6:29)](https://youtu.be/HSboMHfPuZA)
+
+## 6. [Side effects and listeners](https://youtu.be/A-w2IG7DAso)
+
+Similarly to field validators, you can attach events to field listeners and react to them, for example to reset a field when another one it depends on has changed. [Watch video (5:50)](https://youtu.be/A-w2IG7DAso)