feat: add listeners react documentation

docs/config.json

@@ -101,6 +101,10 @@
               "label": "Linked Fields",
               "to": "framework/react/guides/linked-fields"
             },
+            {
+              "label": "Listeners",
+              "to": "framework/react/guides/listeners"
+            },
             {
               "label": "UI Libraries",
               "to": "framework/react/guides/ui-libraries"

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

@@ -195,6 +195,23 @@ const firstName = form.useStore((state) => state.values.firstName)
 
 Note: The usage of the `form.useField` hook to achieve reactivity is discouraged since it is designed to be used thoughtfully within the `form.Field` component. You might want to use `form.useStore` instead.
 
+## Listeners
+
+`@tanstack/react-form` allows you to react to specific triggers and "listen" to them to dispatch side effects.
+
+Example:
+
+```tsx
+<form.Field
+  name="country"
+  listener={
+    onChange: ({ value }) => {
+      form.reset({county: ''})
+    },
+  }
+/>
+```
+
 ## Array Fields
 
 Array fields allow you to manage a list of values within a form, such as a list of hobbies. You can create an array field using the `form.Field` component with the `mode="array"` prop.

docs/framework/react/guides/listeners.md

@@ -0,0 +1,64 @@
+---
+id: listeners
+title: Side effects for event triggers
+---
+
+For situations where you want to "affect" or "react" to triggers, there's the listener API. For example, if you, as the developer, want to reset a form field as a result of another field changing, you would use the listener API.
+
+Imagine the following user flow:
+
+- User selects a country from a drop-down.
+- User then selects a county from another drop-down.
+- User changes the selected country to a different one.
+
+In this example, when the user changes the country, the selected county needs to be reset as it's no longer valid. With the listener API, we can subscribe to the onChange event and dispatch a reset to the field "county" when the listener is fired.
+
+Other events that can be "listened" to are:
+
+- onChange
+- onBlur
+- onMount
+- onSubmit
+
+```tsx
+function App() {
+  const form = useForm({
+    defaultValues: {
+      country: '',
+      county: '',
+    },
+    // ...
+  })
+
+  return (
+    <div>
+      <form.Field name="country">
+        {(field) => (
+          <label>
+            <div>Country</div>
+            <input
+              value={field.state.value}
+              onChange={(e) => field.handleChange(e.target.value)}
+              listener={onChange: ({ value }) => {
+                form.reset({county: ''})
+              }}
+            />
+          </label>
+        )}
+      </form.Field>
+
+      <form.Field name="county">
+        {(field) => (
+          <label>
+            <div>County</div>
+            <input
+              value={field.state.value}
+              onChange={(e) => field.handleChange(e.target.value)}
+            />
+          </label>
+        )}
+      </form.Field>
+    </div>
+  )
+}
+```