[WIP] Form Groups

docs/config.json

@@ -128,6 +128,10 @@
               "label": "Arrays",
               "to": "framework/react/guides/arrays"
             },
+            {
+              "label": "Form Groups",
+              "to": "framework/react/guides/form-groups"
+            },
             {
               "label": "Linked Fields",
               "to": "framework/react/guides/linked-fields"
@@ -644,6 +648,10 @@
               "label": "Simple",
               "to": "framework/react/examples/simple"
             },
+            {
+              "label": "Multi-Step Wizard",
+              "to": "framework/react/examples/multi-step-wizard"
+            },
             {
               "label": "Arrays",
               "to": "framework/react/examples/array"
@@ -697,6 +705,10 @@
               "label": "Simple",
               "to": "framework/vue/examples/simple"
             },
+            {
+              "label": "Multi-Step Wizard",
+              "to": "framework/vue/examples/multi-step-wizard"
+            },
             {
               "label": "Arrays",
               "to": "framework/vue/examples/array"
@@ -714,6 +726,10 @@
               "label": "Simple",
               "to": "framework/angular/examples/simple"
             },
+            {
+              "label": "Multi-Step Wizard",
+              "to": "framework/angular/examples/multi-step-wizard"
+            },
             {
               "label": "Arrays",
               "to": "framework/angular/examples/array"
@@ -735,6 +751,10 @@
               "label": "Simple",
               "to": "framework/solid/examples/simple"
             },
+            {
+              "label": "Multi-Step Wizard",
+              "to": "framework/solid/examples/multi-step-wizard"
+            },
             {
               "label": "Arrays",
               "to": "framework/solid/examples/array"
@@ -756,6 +776,10 @@
               "label": "Simple",
               "to": "framework/lit/examples/simple"
             },
+            {
+              "label": "Multi-Step Wizard",
+              "to": "framework/lit/examples/multi-step-wizard"
+            },
             {
               "label": "Array",
               "to": "framework/lit/examples/array"
@@ -770,13 +794,30 @@
             }
           ]
         },
+        {
+          "label": "preact",
+          "children": [
+            {
+              "label": "Simple",
+              "to": "framework/preact/examples/simple"
+            },
+            {
+              "label": "Multi-Step Wizard",
+              "to": "framework/preact/examples/multi-step-wizard"
+            }
+          ]
+        },
         {
           "label": "svelte",
           "children": [
             {
               "label": "Simple",
               "to": "framework/svelte/examples/simple"
             },
+            {
+              "label": "Multi-Step Wizard",
+              "to": "framework/svelte/examples/multi-step-wizard"
+            },
             {
               "label": "Arrays",
               "to": "framework/svelte/examples/array"

docs/framework/angular/guides/arrays.md

@@ -15,7 +15,12 @@ To use an array, you can use `field.api.state.value` on an array value:
   standalone: true,
   imports: [TanStackField],
   template: `
-    <ng-container [tanstackField]="form" name="people" mode="array" #people="field">
+    <ng-container
+      [tanstackField]="form"
+      name="people"
+      mode="array"
+      #people="field"
+    >
       <div>
         @for (_ of people.api.state.value; track $index) {
           <!-- ... -->
@@ -101,7 +106,12 @@ export class AppComponent {
   template: `
     <form (submit)="handleSubmit($event)">
       <div>
-        <ng-container [tanstackField]="form" name="people" mode="array" #people="field">
+        <ng-container
+          [tanstackField]="form"
+          name="people"
+          mode="array"
+          #people="field"
+        >
           <div>
             @for (_ of people.api.state.value; track $index) {
               <ng-container

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

@@ -237,10 +237,7 @@ Finally, in the parent component, create the form with `injectForm` and pass it
 ```angular-ts
 // app.component.ts
 import { Component } from '@angular/core'
-import {
-  TanStackWithForm,
-  injectForm,
-} from '@tanstack/angular-form'
+import { TanStackWithForm, injectForm } from '@tanstack/angular-form'
 import { ChildForm } from './child-form.component'
 import { peopleFormOpts } from './shared-form'
 

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

@@ -0,0 +1,177 @@
+---
+id: form-groups
+title: Form Groups
+---
+
+When building a multi-stage form that has many stages, like so:
+
+![Form stepper](https://raw.githubusercontent.com/TanStack/form/main/docs/assets/stepper.png)
+
+It's common for each step to have its own form. However, this complicates the form submission and validation process by requiring you to add complex logic.
+
+Luckily, TanStack Form provides a way to build out sub-forms that make this kind of development trivial to implement: `<form.FormGroup>`.
+
+## Usage
+
+To use a form group in TanStack Form, you'll use `useForm` or [`useAppForm`](./form-composition.md) to create a `form` variable, then reference its `FormGroup` component like you would a `Field`:
+
+```tsx
+const form = useForm({
+    defaultValues: {
+        step1: {
+            name: ""
+        },
+        step2: {
+            age: 0
+        }
+    }
+})
+
+return (
+    <form.FormGroup
+        name="step1"
+        children={group => (
+            // `group` here has all of the form-like methods you'd expect like `deleteField` or `insertFieldValue`
+            // ...
+        )}
+    />
+)
+```
+
+This becomes much more useful when paired with external state to conditionally render a `FormGroup`:
+
+```tsx
+const [step, setStep] = useState(0)
+const form = useForm({
+    defaultValues: {
+        step1: {
+            name: ""
+        },
+        step2: {
+            age: 0
+        }
+    }
+})
+
+return (
+    <>
+        {step === 0 ? <form.FormGroup
+            name="step1"
+            onGroupSubmit={() => {
+                // We can move the step forward when validation passes
+                setStep(step + 1)
+            }}
+            onGroupSubmitInvalid={() => {
+                // Or handle invalid submissions, just like a top-level form
+            }}
+            onSubmitMeta={{} as SomeType}
+            children={group => (
+                // Use `group.handleSubmit()` to submit the sub-form, but not the parent form
+                // ...
+            )}
+        /> : null }
+        {step === 1 ? <form.FormGroup
+            name="step2"
+            children={group => (
+                // Then, use `form.handleSubmit()` to submit the entire form
+                // ...
+            )}
+        /> : null }
+    </>
+)
+```
+
+## Form Group Validation
+
+Form groups have a distinct validation proceedure that we think makes sense for sub-forms:
+
+- Form groups can have their own validation:
+
+```tsx
+<form.FormGroup
+  name="step1"
+  validators={{ onChange: () => 'Error' }}
+  children={(group) => {
+    group.state.meta.errorMap // {onChange: "Error" | undefined}
+    group.state.meta.errors // ("Error")[]
+  }}
+/>
+```
+
+- Can set errors on sub-fields:
+
+```tsx
+<form.FormGroup
+  name="step1"
+  validators={{
+    onChange: ({ value, groupApi }) => ({
+      group: value.name === 'error' ? 'Group error' : undefined,
+      fields: {
+        // Must use the name of the field relative to the FormGroup as the error key,
+        // to stay consistent with how standard schema works with form groups
+        name: value.name === 'error' ? 'Field error' : undefined,
+      },
+    }),
+  }}
+/>
+```
+
+- And can even accept standard schemas:
+
+```tsx
+<form.FormGroup
+  name="step1"
+  validators={{
+    onChange: z.object({
+      name: z.string().min(2),
+    }),
+  }}
+/>
+```
+
+> The reason we don't use the full path names for fields is so that you can compose your schemas like so:
+>
+> ```
+> const step1Schema = z.object({
+>     name: z.string().min(2)
+> })
+>
+> const schema = z.object({
+>     step1: step1Schema,
+>     step2: step2Schema
+> })
+> ```
+>
+> And pass the `step1Schema` to a form group and `schema` to the parent form. That way, partially validated data will still flag errors if the group is bypassed.
+
+### Dynamic Group Validation
+
+If you want to use [dynamic validation (`onDynamic`)](./dynamic-validation.md) with a form group, do not rely on the `onDynamic` validator passed to `useForm`:
+
+```tsx
+useForm({
+  validationLogic: revalidateLogic(),
+  validators: {
+    // This validator will not run `onChange` when a sub-form is submitted;
+    // it will only run `onChange` when the form itself is submitted.
+    onDynamic: schema,
+  },
+})
+```
+
+Instead, pass your sub-schema for the group to the `onDynamic` validation of the `FormGroup` itself:
+
+```tsx
+<form.FormGroup validators={{ onDynamic: step1Schema }} />
+```
+
+It will treat `group.submissionAttempts` as the way to change what validator is ran before/after submit.
+
+## Form Group State
+
+Just like you're able to access `group.state.meta.errors`, you're also able to access the group's value using `group.state.value`. Likewise, here are some valuable properties you can access in the `group.state.meta`:
+
+- `group.state.meta.isFieldsValid`: `true` when the field-level validators have no errors
+- `group.state.meta.isGroupValid`: `true` when the group-level validators have no errors
+- `group.state.meta.isValid`: `true` when both the field-level and group-level validators have no errors
+- `group.state.meta.isSubmitting`: `true` when the group is in the process of being submitted

examples/angular/multi-step-wizard/.editorconfig

@@ -0,0 +1,16 @@
+# Editor configuration, see https://editorconfig.org
+root = true
+
+[*]
+charset = utf-8
+indent_style = space
+indent_size = 2
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.ts]
+quote_type = single
+
+[*.md]
+max_line_length = off
+trim_trailing_whitespace = false

examples/angular/multi-step-wizard/.gitignore

@@ -0,0 +1,42 @@
+# See http://help.github.com/ignore-files/ for more about ignoring files.
+
+# Compiled output
+/dist
+/tmp
+/out-tsc
+/bazel-out
+
+# Node
+/node_modules
+npm-debug.log
+yarn-error.log
+
+# IDEs and editors
+.idea/
+.project
+.classpath
+.c9/
+*.launch
+.settings/
+*.sublime-workspace
+
+# Visual Studio Code
+.vscode/*
+!.vscode/settings.json
+!.vscode/tasks.json
+!.vscode/launch.json
+!.vscode/extensions.json
+.history/*
+
+# Miscellaneous
+/.angular/cache
+.sass-cache/
+/connect.lock
+/coverage
+/libpeerconnection.log
+testem.log
+/typings
+
+# System files
+.DS_Store
+Thumbs.db