feat(solid-form): add withFieldGroup API

.changeset/sixty-hands-peel.md

@@ -0,0 +1,5 @@
+---
+'@tanstack/solid-form': minor
+---
+
+add withFieldGroup API Solid Form Composition

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

@@ -159,7 +159,7 @@ Sometimes forms get very large; it's just how it goes sometimes. While TanStack
 To solve this, we support breaking forms into smaller pieces using the `withForm` higher-order component.
 
 ```tsx
-const { useAppForm, withForm } = createFormHook({
+const { useAppForm, withForm, withFieldGroup } = createFormHook({
   fieldComponents: {
     TextField,
   },
@@ -213,8 +213,243 @@ function App() {
 ### `withForm` FAQ
 
 > Why a higher-order component instead of a hook?
+>
+> While hooks are the future of Solid, higher-order components are still a powerful tool for composition. In particular, the API of `withForm` enables us to have strong type-safety without requiring users to pass generics.
+
+## 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 FieldGroupPasswordFields = 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(props) {
+    // access reactive values using the group store
+    const password = useStore(
+      props.group.store,
+      (state) => state.values.password,
+    )
+    // or the form itself
+    const isSubmitting = useStore(
+      props.group.form.store,
+      (state) => state.isSubmitting,
+    )
+
+    return (
+      <div>
+        <h2>{props.title}</h2>
+        {/* Groups also have access to Field, Subscribe, Field, AppField and AppForm */}
+        <props.group.AppField name="password">
+          {(field) => <field.TextField label="Password" />}
+        </props.group.AppField>
+        <props.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 !== props.group.getFieldValue('password')) {
+                return 'Passwords do not match'
+              }
+              return undefined
+            },
+          }}
+        >
+          {(field) => (
+            <div>
+              <field.TextField label="Confirm Password" />
+              <field.ErrorInfo />
+            </div>
+          )}
+        </props.group.AppField>
+      </div>
+    )
+  },
+})
+```
 
-While hooks are the future of Solid, higher-order components are still a powerful tool for composition. In particular, the API of `withForm` enables us to have strong type-safety without requiring users to pass generics.
+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>
+      <FieldGroupPasswordFields
+        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) => (
+            <FieldGroupPasswordFields
+              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>
+      <FieldGroupPasswordFields
+        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:
+<FieldGroupPasswordFields
+  form={form}
+  fields={passwordFields}
+  title="Passwords"
+/>
+```
 
 ## Tree-shaking form and field components
 
@@ -316,7 +551,7 @@ function SubscribeButton(props: { label: string }) {
   )
 }
 
-const { useAppForm, withForm } = createFormHook({
+const { useAppForm, withForm, withFieldGroup } = createFormHook({
   fieldComponents: {
     TextField,
   },
@@ -345,7 +580,7 @@ const ChildForm = withForm({
   render: (props) => {
     return (
       <div>
-        <p>{title}</p>
+        <p>{props.title}</p>
         <props.form.AppField
           name="firstName"
           children={(field) => <field.TextField label="First Name" />}
@@ -360,9 +595,9 @@ const ChildForm = withForm({
 
 // /src/features/people/page.ts
 const Parent = () => {
-  const form = useAppForm({
+  const form = useAppForm(() => ({
     ...formOpts,
-  })
+  }))
 
   return <ChildForm form={form} title={'Testing'} />
 }

examples/solid/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/solid/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,7 @@ 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/solid/large-form/src/hooks/form.tsx

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