From 7e8b1b0566929ca6d8b5efdfafc8564e597adbb4 Mon Sep 17 00:00:00 2001
From: Corbin Crutchley <git@crutchcorn.dev>
Date: Mon, 18 Mar 2024 13:07:57 -0600
Subject: [PATCH] docs: add linked fields docs for React

---
 docs/config.json                             |  4 ++
 docs/framework/react/guides/linked-fields.md | 74 ++++++++++++++++++++
 docs/reference/fieldApi.md                   | 12 ++++
 3 files changed, 90 insertions(+)
 create mode 100644 docs/framework/react/guides/linked-fields.md

diff --git a/docs/config.json b/docs/config.json
index 483cad023..8abd35a1d 100644
--- a/docs/config.json
+++ b/docs/config.json
@@ -85,6 +85,10 @@
               "label": "Arrays",
               "to": "framework/react/guides/arrays"
             },
+            {
+              "label": "Linked Fields",
+              "to": "framework/react/guides/linked-fields"
+            },
             {
               "label": "UI Libraries",
               "to": "framework/react/guides/ui-libraries"
diff --git a/docs/framework/react/guides/linked-fields.md b/docs/framework/react/guides/linked-fields.md
new file mode 100644
index 000000000..029444f6d
--- /dev/null
+++ b/docs/framework/react/guides/linked-fields.md
@@ -0,0 +1,74 @@
+# Link Two Form Fields Together
+
+You may find yourself needing to link two fields together; when one is validated as another field's value has changed.
+One such usage is when you have both a `password` and `confirm_password` field,
+where you want to `confirm_password` to error out when `password`'s value does not match;
+regardless of which field triggered the value change.
+
+Imagine the following userflow:
+
+- User updates confirm password field.
+- User updates the non-confirm password field.
+
+In this example, the form will still have errors present,
+as the "confirm password" field validation has not been re-ran to mark as accepted.
+
+To solve this, we need to make sure that the "confirm password" validation is re-run when the password field is updated.
+To do this, you can add a `onChangeListenTo` property to the `confirm_password` field.
+
+```tsx
+ function App() {
+  const form = useForm({
+    defaultValues: {
+      password: '',
+      confirm_password: '',
+    },
+    // ...
+  })
+
+  return (
+    <div>
+      <form.Field name="password">
+        {(field) => (
+          <label>
+            <div>Password</div>
+            <input
+              value={field.state.value}
+              onChange={(e) => field.handleChange(e.target.value)}
+            />
+          </label>
+        )}
+      </form.Field>
+      <form.Field
+        name="confirm_password"
+        validators={{
+          onChangeListenTo: ['password'],
+          onChange: ({ value, fieldApi }) => {
+            if (value !== fieldApi.form.getFieldValue('password')) {
+              return 'Passwords do not match'
+            }
+            return undefined
+          },
+        }}
+      >
+        {(field) => (
+          <div>
+            <label>
+              <div>Confirm Password</div>
+              <input
+                value={field.state.value}
+                onChange={(e) => field.handleChange(e.target.value)}
+              />
+            </label>
+            {field.state.meta.errors.map((err) => (
+              <div key={err}>{err}</div>
+            ))}
+          </div>
+        )}
+      </form.Field>
+    </div>
+  )
+}
+```
+
+This similarly works with `onBlurListenTo` property, which will re-run the validation when the field is blurred.
diff --git a/docs/reference/fieldApi.md b/docs/reference/fieldApi.md
index f8ead0871..827368318 100644
--- a/docs/reference/fieldApi.md
+++ b/docs/reference/fieldApi.md
@@ -89,6 +89,12 @@ An object type representing the options for a field in a form.
   - An optional number to represent how long the `onChangeAsync` should wait before running
   - If set to a number larger than 0, will debounce the async validation event by this length of time in milliseconds
 
+- ```tsx
+  onChangeListenTo?: DeepKeys<TParentData>[]
+  ```
+
+  - An optional list of field names that should trigger **this** field's `onChange` and `onChangeAsync` events when **its** value changes
+
 - ```tsx
   onBlur?: ValidateFn<TData, TParentData>
   ```
@@ -108,6 +114,12 @@ An object type representing the options for a field in a form.
   - An optional number to represent how long the `onBlurAsyncDebounceMs` should wait before running
   - If set to a number larger than 0, will debounce the async validation event by this length of time in milliseconds
 
+- ```tsx
+  onBlurListenTo?: DeepKeys<TParentData>[]
+  ```
+
+  - An optional list of field names that should trigger **this** field's `onBlur` and `onBlurAsync` events when **its** field blurs
+
 - ```tsx
   onSubmit?: ValidateFn<TData, TParentData>
   ```