Merge branch 'main' into vue-use-app-form

Author: crutchcorn

README.md

@@ -1,30 +1,34 @@
-<img src="https://static.scarf.sh/a.png?x-pxid=be2d8a11-9712-4c1d-9963-580b2d4fb133" />
+<img src="https://static.scarf.sh/a.png?x-pxid=be2d8a11-9712-4c1d-9963-580b2d4fb133" alt="" />
 
 ![TanStack Form Header](https://github.com/TanStack/form/raw/main/media/repo-header.png)
 
-Powerful and type-safe form state management for the web. TS/JS, React Form, Solid Form, Angular Form, Lit Form and Vue Form.
+Powerful and type-safe form state management for the web. TS/JS, React Form, Solid Form, Angular Form, Lit Form and Vue
+Form.
 
-<a href="https://twitter.com/intent/tweet?button_hashtag=TanStack" target="\_parent">
-  <img alt="#TanStack" src="https://img.shields.io/twitter/url?color=%2308a0e9&label=%23TanStack&style=social&url=https%3A%2F%2Ftwitter.com%2Fintent%2Ftweet%3Fbutton_hashtag%3DTanStack">
-</a><a href="https://discord.com/invite/WrRKjPJ" target="\_parent">
-  <img alt="" src="https://img.shields.io/badge/Discord-TanStack-%235865F2" />
-</a><a href="https://www.npmjs.com/package/@tanstack/form-core" target="\_parent">
-  <img alt="" src="https://img.shields.io/npm/dm/@tanstack/form-core.svg" />
-</a><a href="https://bundlephobia.com/package/@tanstack/form-core@latest" target="\_parent">
-  <img alt="" src="https://badgen.net/bundlephobia/minzip/@tanstack/form-core" />
+<a href="https://twitter.com/intent/tweet?button_hashtag=TanStack" target="_parent">
+  <img alt="Tweet about TanStack with hashtag #TanStack" src="https://img.shields.io/twitter/url?color=%2308a0e9&label=%23TanStack&style=social&url=https%3A%2F%2Ftwitter.com%2Fintent%2Ftweet%3Fbutton_hashtag%3DTanStack">
+</a><a href="https://discord.com/invite/WrRKjPJ" target="_parent">
+  <img alt="Join the TanStack Discord Community" src="https://img.shields.io/badge/Discord-TanStack-%235865F2" />
+</a><a href="https://www.npmjs.com/package/@tanstack/form-core" target="_parent">
+  <img alt="NPM downloads for @tanstack/form-core" src="https://img.shields.io/npm/dm/@tanstack/form-core.svg" />
+</a><a href="https://bundlephobia.com/package/@tanstack/form-core@latest" target="_parent">
+  <img alt="Minified + gzipped bundle size of @tanstack/form-core" src="https://badgen.net/bundlephobia/minzip/@tanstack/form-core" />
 </a><a href="#badge">
-    <img alt="semantic-release" src="https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg">
-  </a><a href="https://github.com/TanStack/form/discussions">
-  <img alt="Join the discussion on Github" src="https://img.shields.io/badge/Github%20Discussions%20%26%20Support-Chat%20now!-blue" />
-</a><a href="https://bestofjs.org/projects/tanstack-form"><img alt="Best of JS" src="https://img.shields.io/endpoint?url=https://bestofjs-serverless.now.sh/api/project-badge?fullName=TanStack%2Fform%26since=daily" /></a><a href="https://github.com/TanStack/form/" target="\_parent">
-  <img alt="" src="https://img.shields.io/github/stars/TanStack/form.svg?style=social&label=Star" />
-</a><a href="https://twitter.com/tannerlinsley" target="\_parent">
-  <img alt="" src="https://img.shields.io/twitter/follow/tannerlinsley.svg?style=social&label=Follow" />
-</a> <a href="https://gitpod.io/from-referrer/">
-  <img src="https://img.shields.io/badge/Gitpod-Ready--to--Code-blue?logo=gitpod" alt="Gitpod Ready-to-Code"/>
+  <img alt="Semantic Release Enabled" src="https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg">
+</a><a href="https://github.com/TanStack/form/discussions">
+  <img alt="Join GitHub Discussions for TanStack Form" src="https://img.shields.io/badge/Github%20Discussions%20%26%20Support-Chat%20now!-blue" />
+</a><a href="https://bestofjs.org/projects/tanstack-form">
+  <img alt="TanStack Form featured on Best of JS" src="https://img.shields.io/endpoint?url=https://bestofjs-serverless.now.sh/api/project-badge?fullName=TanStack%2Fform%26since=daily" />
+</a><a href="https://github.com/TanStack/form/" target="_parent">
+  <img alt="Star TanStack Form on GitHub" src="https://img.shields.io/github/stars/TanStack/form.svg?style=social&label=Star" />
+</a><a href="https://twitter.com/tannerlinsley" target="_parent">
+  <img alt="Follow Tanner Linsley on Twitter" src="https://img.shields.io/twitter/follow/tannerlinsley.svg?style=social&label=Follow" />
+</a><a href="https://gitpod.io/from-referrer/">
+  <img alt="Open TanStack Form in Gitpod" src="https://img.shields.io/badge/Gitpod-Ready--to--Code-blue?logo=gitpod" />
 </a>
 
-Enjoy this library? Try the entire [TanStack](https://tanstack.com)! [TanStack Query](https://github.com/TanStack/query), [TanStack Table](https://github.com/TanStack/table), [TanStack Router](https://github.com/tanstack/router), [TanStack Virtual](https://github.com/tanstack/virtual), [React Charts](https://github.com/TanStack/react-charts), [React Ranger](https://github.com/TanStack/ranger)
+Enjoy this library? Try the
+entire [TanStack](https://tanstack.com)! [TanStack Query](https://github.com/TanStack/query), [TanStack Table](https://github.com/TanStack/table), [TanStack Router](https://github.com/tanstack/router), [TanStack Virtual](https://github.com/tanstack/virtual), [React Charts](https://github.com/TanStack/react-charts), [React Ranger](https://github.com/TanStack/ranger)
 
 ## Visit [tanstack.com/form](https://tanstack.com/form) for docs, guides, API and more!
 

codecov.yml

@@ -1,3 +1,5 @@
+codecov:
+  max_report_age: off
 coverage:
   status:
     project:

docs/assets/field-states-extended.png

@@ -191,6 +191,10 @@
             {
               "label": "Arrays",
               "to": "framework/angular/guides/arrays"
+            },
+            {
+              "label": "Form Composition",
+              "to": "framework/angular/guides/form-composition"
             }
           ]
         },
@@ -487,6 +491,10 @@
             {
               "label": "Balastrong's Tutorial",
               "to": "framework/react/community/balastrong-tutorial"
+            },
+            {
+              "label": "Community Tutorials",
+              "to": "framework/react/community/tutorials"
             }
           ]
         }
@@ -564,6 +572,10 @@
             {
               "label": "Arrays",
               "to": "framework/angular/examples/array"
+            },
+            {
+              "label": "Form Composition",
+              "to": "framework/angular/examples/large-form"
             }
           ]
         },

docs/assets/field-states.png

@@ -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.
@@ -228,7 +258,7 @@ onCountryChange: FieldListenerFn<any, any, any, any, string> = ({
   }
 ```
 
-More information can be found at [Listeners](./listeners.md)
+More information can be found at [Listeners](../listeners.md)
 
 ## Array Fields
 

docs/config.json

@@ -0,0 +1,178 @@
+---
+id: form-composition
+title: Form Composition
+---
+
+A common criticism of TanStack Form is its verbosity out-of-the-box. While this _can_ be useful for educational purposes - helping enforce understanding our APIs - it's not ideal in production use cases.
+
+As a result, while basic usage of `[tanstackField]` enables the most powerful and flexible usage of TanStack Form, we provide APIs that wrap it and make your application code less verbose.
+
+## Pre-bound Field Components
+
+If you've ever used TanStack Form in Angular to bind more than one input, you'll have quickly realized how much goes into each input:
+
+```angular-ts
+import { Component } from '@angular/core'
+import { TanStackField, injectForm, injectStore } from '@tanstack/angular-form'
+
+@Component({
+  selector: 'app-root',
+  standalone: true,
+  imports: [TanStackField],
+  template: `
+    <div>
+      <ng-container
+        [tanstackField]="form"
+        name="firstName"
+        #firstName="field"
+      >
+        <label [for]="firstName.api.name">First Name:</label>
+        <input
+          [id]="firstName.api.name"
+          [name]="firstName.api.name"
+          [value]="firstName.api.state.value"
+          (blur)="firstName.api.handleBlur()"
+          (input)="firstName.api.handleChange($any($event).target.value)"
+        />
+        @if (firstName.api.state.meta.isTouched) {
+          @for (error of firstName.api.state.meta.errors; track $index) {
+            <div style="color: red">
+              {{ error }}
+            </div>
+          }
+        }
+        @if (firstName.api.state.meta.isValidating) {
+          <p>Validating...</p>
+        }
+      </ng-container>
+    </div>
+    <div>
+      <ng-container
+        [tanstackField]="form"
+        name="lastName"
+        #lastName="field"
+      >
+        <label [for]="lastName.api.name">Last Name:</label>
+        <input
+          [id]="lastName.api.name"
+          [name]="lastName.api.name"
+          [value]="lastName.api.state.value"
+          (blur)="lastName.api.handleBlur()"
+          (input)="lastName.api.handleChange($any($event).target.value)"
+        />
+        @if (lastName.api.state.meta.isTouched) {
+          @for (error of lastName.api.state.meta.errors; track $index) {
+            <div style="color: red">
+              {{ error }}
+            </div>
+          }
+        }
+        @if (lastName.api.state.meta.isValidating) {
+          <p>Validating...</p>
+        }
+      </ng-container>
+    </div>
+  `,
+})
+export class AppComponent {
+  form = injectForm({
+    defaultValues: {
+      firstName: '',
+      lastName: '',
+    },
+    onSubmit({ value }) {
+      // Do something with form data
+      console.log(value)
+    },
+  })
+}
+```
+
+This is functionally correct, but introduces a _lot_ of repeated templating behavior over and over. Instead, let's move the error handling, label to input binding, and other repeated logic into a component:
+
+```angular-ts
+import {injectField} from '@tanstack/angular-form'
+
+@Component({
+  selector: 'app-text-field',
+  standalone: true,
+  template: `
+    <label [for]="field.api.name">{{ label() }}</label>
+    <input
+      [id]="field.api.name"
+      [name]="field.api.name"
+      [value]="field.api.state.value"
+      (blur)="field.api.handleBlur()"
+      (input)="field.api.handleChange($any($event).target.value)"
+    />
+    @if (field.api.state.meta.isTouched) {
+      @for (error of field.api.state.meta.errors; track $index) {
+        <div style="color: red">
+          {{ error }}
+        </div>
+      }
+    }
+    @if (field.api.state.meta.isValidating) {
+      <p>Validating...</p>
+    }
+  `,
+})
+export class AppTextField {
+  label = input.required<string>()
+  // This API requires another part to it from the parent component
+  field = injectField<string>()
+}
+```
+
+> `injectField` accepts a single generic to define the `field.state.value` type.
+>
+> As a result, a numerical text field would be represented as `injectField<number>`, for example.
+
+Now, we can use the `TanStackAppField` directive (`tanstack-app-field`) to `provide` the expected field associated with this input:
+
+```angular-ts
+import { Component } from '@angular/core'
+import {
+  TanStackAppField,
+  TanStackField,
+  injectForm,
+} from '@tanstack/angular-form'
+
+@Component({
+  selector: 'app-root',
+  standalone: true,
+  imports: [TanStackField, TanStackAppField, AppTextField],
+  template: `
+    <div>
+      <app-text-field
+        label="First name:"
+        tanstack-app-field
+        [tanstackField]="form"
+        name="firstName"
+      />
+    </div>
+    <div>
+      <app-text-field
+        label="Last name:"
+        tanstack-app-field
+        [tanstackField]="form"
+        name="lastName"
+      />
+    </div>
+  `,
+})
+export class AppComponent {
+  form = injectForm({
+    defaultValues: {
+      firstName: '',
+      lastName: '',
+    },
+    onSubmit({ value }) {
+      // Do something with form data
+      console.log(value)
+    },
+  })
+}
+```
+
+> Here, the `tanstack-app-field` directive is taking the properties from `[tanstackField]` and `provide`ing them down to the `app-text-field` so that they can be more easily consumed as a component.