feat(react-form): Add withFieldGroup (#1469)

* feat: add createFormGroup

* refactor: move createFormGroup to AppForm

While the previous separate implementation was compatible with AppForm, users
wouldn't have been able to use any field/form components
in the render itself. This commit allows them to do that,
at the expense of not being compatible with useForm.

* chore: add unit tests for createFormGroup types

* chore: add unit test for createFormGroup

* chore: export CreateFormGroupProps

* add DeepKeysOfType util type

This type will help with a lens API for forms
so that only names leading to the subset data
are allowed.

* feat: add initial FormLensApi draft

* chore: add FormLensApi tests batch

* fix(form-core): fix form.resetField() ignoring nested fields

* chore: complete form-core unit test for FormLensApi

* feat: add react adapter to form lens api

* fix: fix names for lens.Field and add test

* chore: export WithFormLensProps

* feat: add Subscribe and store to form lens

* feat: add mount method to FormLensApi

* fix: memoize innerProps to avoid focus loss in withFormLens

* refactor: use single useState instead of multiple useMemos

this is because useMemo is not intended for stable objects
see https://react.dev/reference/react/useMemo for more info

* feat: allow nesting withFormLenses

* remove createFormGroup for redundancy

* fix: widen typing of lens.Field/AppField to correct level

* docs: add withFormLens section

* fix: fix TName for lens component

* docs: fix typo in withFormLens

* feat: add lensErrors to FormLensApi store

* chore: adjust memo dependency in useFormLens

* chore: call userEvent.setup() in createFormHook tests

* refactor: move path concatenation to utils

* chore: move useLens to own file and rename

* feat: add FieldsMap and createFieldMap utils

* chore: migrate (most) lens references to field group

* chore: finalize migration from lens to field group

* ci: apply automated fixes and generate docs

* chore: remove accidental test file

* chore: add some unit tests for field mapping

* chore: add unit tests

* docs: update docs to use group

* docs: add caveat with field mapping

* docs: fix weird line break in alert text

* revert: remove FieldGroupApi#resetFieldMeta

the method appears to be a helper function for form.reset,
which is accessible from the field group API.
There does not seem to be a good reason to port this method
from FormApi.

* refactor: allow null or undefined for field group keys

users are able to do conditional rendering, but
TS generally doesn't pick up on it. Therefore,
while it is less type safe, it allows users to
use field groups in more locations than previously
possible.

* chore: add FieldGroupApi.test-d.ts

* docs(react-form): amend large form example with withFieldGroup

* chore(form-core): remove FieldGroupApi.reset

the reset is already accessible through group.form.reset.

* chore: fix broken unit test

---------

Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>

Author: LeCarbonator

docs/framework/react/guides/form-composition.md

@@ -248,6 +248,238 @@ const ChildForm = withForm({
 })
 ```
 
+## Reusing groups of fields in multiple forms
+
+Sometimes, a pair of fields are so closely related that it makes sense to group and reuse them — like the password example listed in the [linked fields guide](./linked-fields.md). Instead of repeating this logic across multiple forms, you can utilize the `withFieldGroup` higher-order component.
+
+> Unlike `withForm`, validators cannot be specified and could be any value.
+> Ensure that your fields can accept unknown error types.
+
+Rewriting the passwords example using `withFieldGroup` would look like this:
+
+```tsx
+const { useAppForm, withForm, withFieldGroup } = createFormHook({
+  fieldComponents: {
+    TextField,
+    ErrorInfo,
+  },
+  formComponents: {
+    SubscribeButton,
+  },
+  fieldContext,
+  formContext,
+})
+
+type PasswordFields = {
+  password: string
+  confirm_password: string
+}
+
+// These default values are not used at runtime, but the keys are needed for mapping purposes.
+// This allows you to spread `formOptions` without needing to redeclare it.
+const defaultValues: PasswordFields = {
+  password: '',
+  confirm_password: '',
+}
+
+const FieldGroupPasswordField = withFieldGroup({
+  defaultValues,
+  // You may also restrict the group to only use forms that implement this submit meta.
+  // If none is provided, any form with the right defaultValues may use it.
+  // onSubmitMeta: { action: '' }
+
+  // Optional, but adds props to the `render` function in addition to `form`
+  props: {
+    // These default values are also for type-checking and are not used at runtime
+    title: 'Password',
+  },
+  // Internally, you will have access to a `group` instead of a `form`
+  render: function Render({ group, title }) {
+    // access reactive values using the group store
+    const password = useStore(group.store, (state) => state.values.password)
+    // or the form itself
+    const isSubmitting = useStore(
+      group.form.store,
+      (state) => state.isSubmitting,
+    )
+
+    return (
+      <div>
+        <h2>{title}</h2>
+        {/* Groups also have access to Field, Subscribe, Field, AppField and AppForm */}
+        <group.AppField name="password">
+          {(field) => <field.TextField label="Password" />}
+        </group.AppField>
+        <group.AppField
+          name="confirm_password"
+          validators={{
+            onChangeListenTo: ['password'],
+            onChange: ({ value, fieldApi }) => {
+              // The form could be any values, so it is typed as 'unknown'
+              const values: unknown = fieldApi.form.state.values
+              // use the group methods instead
+              if (value !== group.getFieldValue('password')) {
+                return 'Passwords do not match'
+              }
+              return undefined
+            },
+          }}
+        >
+          {(field) => (
+            <div>
+              <field.TextField label="Confirm Password" />
+              <field.ErrorInfo />
+            </div>
+          )}
+        </group.AppField>
+      </div>
+    )
+  },
+})
+```
+
+We can now use these grouped fields in any form that implements the default values:
+
+```tsx
+// You are allowed to extend the group fields as long as the
+// existing properties remain unchanged
+type Account = PasswordFields & {
+  provider: string
+  username: string
+}
+
+// You may nest the group fields wherever you want
+type FormValues = {
+  name: string
+  age: number
+  account_data: PasswordFields
+  linked_accounts: Account[]
+}
+
+const defaultValues: FormValues = {
+  name: '',
+  age: 0,
+  account_data: {
+    password: '',
+    confirm_password: '',
+  },
+  linked_accounts: [
+    {
+      provider: 'TanStack',
+      username: '',
+      password: '',
+      confirm_password: '',
+    },
+  ],
+}
+
+function App() {
+  const form = useAppForm({
+    defaultValues,
+    // If the group didn't specify an `onSubmitMeta` property,
+    // the form may implement any meta it wants.
+    // Otherwise, the meta must be defined and match.
+    onSubmitMeta: { action: '' },
+  })
+
+  return (
+    <form.AppForm>
+      <PasswordFields
+        form={form}
+        // You must specify where the fields can be found
+        fields="account_data"
+        title="Passwords"
+      />
+      <form.Field name="linked_accounts" mode="array">
+        {(field) =>
+          field.state.value.map((account, i) => (
+            <PasswordFields
+              key={account.provider}
+              form={form}
+              // The fields may be in nested fields
+              fields={`linked_accounts[${i}]`}
+              title={account.provider}
+            />
+          ))
+        }
+      </form.Field>
+    </form.AppForm>
+  )
+}
+```
+
+### Mapping field group values to a different field
+
+You may want to keep the password fields on the top level of your form, or rename the properties for clarity. You can map field group values
+to their true location by changing the `field` property:
+
+> [!IMPORTANT]
+> Due to TypeScript limitations, field mapping is only allowed for objects. You can use records or arrays at the top level of a field group, but you will not be able to map the fields.
+
+```tsx
+// To have an easier form, you can keep the fields on the top level
+type FormValues = {
+  name: string
+  age: number
+  password: string
+  confirm_password: string
+}
+
+const defaultValues: FormValues = {
+  name: '',
+  age: 0,
+  password: '',
+  confirm_password: '',
+}
+
+function App() {
+  const form = useAppForm({
+    defaultValues,
+  })
+
+  return (
+    <form.AppForm>
+      <PasswordFields
+        form={form}
+        // You can map the fields to their equivalent deep key
+        fields={{
+          password: 'password',
+          confirm_password: 'confirm_password',
+          // or map them to differently named keys entirely
+          // 'password': 'name'
+        }}
+        title="Passwords"
+      />
+    </form.AppForm>
+  )
+}
+```
+
+If you expect your fields to always be at the top level of your form, you can create a quick map
+of your field groups using a helper function:
+
+```tsx
+const defaultValues: PasswordFields = {
+  password: '',
+  confirm_password: '',
+}
+
+const passwordFields = createFieldMap(defaultValues)
+/* This generates the following map:
+ {
+    'password': 'password',
+    'confirm_password': 'confirm_password'
+ }
+*/
+
+// Usage:
+<PasswordFields
+  form={form}
+  fields={passwordFields}
+  title="Passwords"
+/>
+```
+
 ## Tree-shaking form and field components
 
 While the above examples are great for getting started, they're not ideal for certain use-cases where you might have hundreds of form and field components.

examples/react/large-form/src/features/people/emergency-contact.tsx

@@ -0,0 +1,22 @@
+import { withFieldGroup } from '../../hooks/form'
+
+export const FieldGroupEmergencyContact = withFieldGroup({
+  defaultValues: {
+    phone: '',
+    fullName: '',
+  },
+  render: function Render({ group }) {
+    return (
+      <>
+        <group.AppField
+          name="fullName"
+          children={(field) => <field.TextField label="Full Name" />}
+        />
+        <group.AppField
+          name="phone"
+          children={(field) => <field.TextField label="Phone" />}
+        />
+      </>
+    )
+  },
+})

examples/react/large-form/src/features/people/page.tsx

@@ -1,5 +1,6 @@
 import { useAppForm } from '../../hooks/form.tsx'
 import { AddressFields } from './address-fields.tsx'
+import { FieldGroupEmergencyContact } from './emergency-contact.tsx'
 import { peopleFormOpts } from './shared-form.tsx'
 
 export const PeoplePage = () => {
@@ -57,14 +58,8 @@ export const PeoplePage = () => {
       />
       <AddressFields form={form} />
       <h2>Emergency Contact</h2>
-      <form.AppField
-        name="emergencyContact.fullName"
-        children={(field) => <field.TextField label="Full Name" />}
-      />
-      <form.AppField
-        name="emergencyContact.phone"
-        children={(field) => <field.TextField label="Phone" />}
-      />
+      <FieldGroupEmergencyContact form={form} fields="emergencyContact" />
+
       <form.AppForm>
         <form.SubscribeButton label="Submit" />
       </form.AppForm>

examples/react/large-form/src/hooks/form.tsx

@@ -13,7 +13,7 @@ function SubscribeButton({ label }: { label: string }) {
   )
 }
 
-export const { useAppForm, withForm } = createFormHook({
+export const { useAppForm, withForm, withFieldGroup } = createFormHook({
   fieldComponents: {
     TextField,
   },