[WIP] Form Groups

.changeset/swift-suns-remain.md

@@ -0,0 +1,5 @@
+---
+'@tanstack/angular-form': minor
+---
+
+Add tanstack-with-form API for more modular form usage

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

examples/angular/multi-step-wizard/README.md

@@ -0,0 +1,27 @@
+# Simple
+
+This project was generated with [Angular CLI](https://github.com/angular/angular-cli) version 17.0.1.
+
+## Development server
+
+Run `ng serve` for a dev server. Navigate to `http://localhost:4200/`. The application will automatically reload if you change any of the source files.
+
+## Code scaffolding
+
+Run `ng generate component component-name` to generate a new component. You can also use `ng generate directive|pipe|service|class|guard|interface|enum|module`.
+
+## Build
+
+Run `ng build` to build the project. The build artifacts will be stored in the `dist/` directory.
+
+## Running unit tests
+
+Run `ng test` to execute the unit tests via [Karma](https://karma-runner.github.io).
+
+## Running end-to-end tests
+
+Run `ng e2e` to execute the end-to-end tests via a platform of your choice. To use this command, you need to first add a package that implements end-to-end testing capabilities.
+
+## Further help
+
+To get more help on the Angular CLI use `ng help` or go check out the [Angular CLI Overview and Command Reference](https://angular.io/cli) page.

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

@@ -0,0 +1,78 @@
+{
+  "$schema": "./node_modules/@angular/cli/lib/config/schema.json",
+  "version": 1,
+  "newProjectRoot": "projects",
+  "projects": {
+    "simple": {
+      "projectType": "application",
+      "schematics": {},
+      "root": "",
+      "sourceRoot": "src",
+      "prefix": "app",
+      "architect": {
+        "build": {
+          "builder": "@angular-devkit/build-angular:application",
+          "options": {
+            "outputPath": "dist/simple",
+            "index": "src/index.html",
+            "browser": "src/main.ts",
+            "polyfills": ["zone.js"],
+            "tsConfig": "tsconfig.app.json",
+            "assets": ["src/favicon.ico", "src/assets"],
+            "scripts": []
+          },
+          "configurations": {
+            "production": {
+              "budgets": [
+                {
+                  "type": "initial",
+                  "maximumWarning": "500kb",
+                  "maximumError": "1mb"
+                },
+                {
+                  "type": "anyComponentStyle",
+                  "maximumWarning": "2kb",
+                  "maximumError": "4kb"
+                }
+              ],
+              "outputHashing": "all"
+            },
+            "development": {
+              "optimization": false,
+              "extractLicenses": false,
+              "sourceMap": true
+            }
+          },
+          "defaultConfiguration": "production"
+        },
+        "serve": {
+          "builder": "@angular-devkit/build-angular:dev-server",
+          "configurations": {
+            "production": {
+              "buildTarget": "simple:build:production"
+            },
+            "development": {
+              "buildTarget": "simple:build:development"
+            }
+          },
+          "defaultConfiguration": "development"
+        },
+        "extract-i18n": {
+          "builder": "@angular-devkit/build-angular:extract-i18n",
+          "options": {
+            "buildTarget": "simple:build"
+          }
+        },
+        "test": {
+          "builder": "@angular-devkit/build-angular:karma",
+          "options": {
+            "polyfills": ["zone.js", "zone.js/testing"],
+            "tsConfig": "tsconfig.spec.json",
+            "assets": ["src/favicon.ico", "src/assets"],
+            "scripts": []
+          }
+        }
+      }
+    }
+  }
+}

examples/angular/multi-step-wizard/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@tanstack/form-example-angular-multi-step-wizard",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "ng": "ng",
+    "start": "ng cache clean && ng serve",
+    "build": "ng build",
+    "watch": "ng build --watch --configuration development",
+    "test": "ng test"
+  },
+  "dependencies": {
+    "@angular/animations": "^20.3.1",
+    "@angular/common": "^20.3.1",
+    "@angular/compiler": "^20.3.1",
+    "@angular/core": "^20.3.1",
+    "@angular/forms": "^20.3.1",
+    "@angular/platform-browser": "^20.3.1",
+    "@angular/platform-browser-dynamic": "^20.3.1",
+    "@angular/router": "^20.3.1",
+    "@tanstack/angular-form": "^1.31.0",
+    "rxjs": "^7.8.2",
+    "tslib": "^2.8.1",
+    "zod": "^3.25.76",
+    "zone.js": "0.15.1"
+  },
+  "devDependencies": {
+    "@angular-devkit/build-angular": "^20.3.2",
+    "@angular/cli": "^20.3.2",
+    "@angular/compiler-cli": "^20.3.1",
+    "typescript": "5.8.2"
+  }
+}

examples/angular/multi-step-wizard/src/app/app.component.ts

@@ -0,0 +1,61 @@
+import { Component, signal } from '@angular/core'
+import {
+  TanStackWithForm,
+  injectForm,
+  injectStore,
+  revalidateLogic,
+} from '@tanstack/angular-form'
+import { z } from 'zod'
+import { Step1Component } from './step1.component'
+import { Step2Component } from './step2.component'
+import { step1Schema, step2Schema, wizardFormOpts } from './shared-form'
+
+@Component({
+  selector: 'app-root',
+  standalone: true,
+  imports: [TanStackWithForm, Step1Component, Step2Component],
+  template: `
+    @if (step() === 0) {
+      <app-step1
+        tanstack-with-form
+        [form]="form"
+        [step]="step()"
+        [isSubmitting]="isSubmitting()"
+        (stepChange)="step.set($event)"
+      />
+    }
+    @if (step() === 1) {
+      <app-step2
+        tanstack-with-form
+        [form]="form"
+        [step]="step()"
+        [isSubmitting]="isSubmitting()"
+        (stepChange)="step.set($event)"
+      />
+    }
+  `,
+})
+export class AppComponent {
+  step = signal(0)
+
+  form = injectForm({
+    ...wizardFormOpts,
+    validationLogic: revalidateLogic(),
+    // onDynamic is only used when `form.handleSubmit` is called itself.
+    // When the FormGroup's `handleSubmit` is called, it will only validate the
+    // current step's schema. This means that this schema will not be called
+    // when the user submits the form group, but instead when they submit the
+    // entire form.
+    validators: {
+      onDynamic: z.object({
+        step1: step1Schema,
+        step2: step2Schema,
+      }),
+    },
+    onSubmit: ({ value }) => {
+      alert(`Form submitted: ${JSON.stringify(value)}`)
+    },
+  })
+
+  isSubmitting = injectStore(this.form, (state) => state.isSubmitting)
+}

examples/angular/multi-step-wizard/src/app/shared-form.ts

@@ -0,0 +1,21 @@
+import { formOptions } from '@tanstack/angular-form'
+import { z } from 'zod'
+
+export const step1Schema = z.object({
+  name: z.string().min(2, 'Name must be at least 2 characters'),
+})
+
+export const step2Schema = z.object({
+  name: z.string().min(3, 'Name must be at least 3 characters'),
+})
+
+export const wizardFormOpts = formOptions({
+  defaultValues: {
+    step1: {
+      name: '',
+    },
+    step2: {
+      name: '',
+    },
+  },
+})

examples/angular/multi-step-wizard/src/app/step1.component.ts

@@ -0,0 +1,69 @@
+import { Component, input, output } from '@angular/core'
+import {
+  TanStackAppField,
+  TanStackField,
+  TanStackFormGroup,
+  injectWithForm,
+} from '@tanstack/angular-form'
+import { TextFieldComponent } from './text-field.component'
+import { step1Schema, wizardFormOpts } from './shared-form'
+
+@Component({
+  selector: 'app-step1',
+  standalone: true,
+  imports: [
+    TanStackField,
+    TanStackAppField,
+    TanStackFormGroup,
+    TextFieldComponent,
+  ],
+  template: `
+    <ng-container
+      [tanstackFormGroup]="withForm.form"
+      name="step1"
+      [validators]="{ onDynamic: step1Schema }"
+      [onGroupSubmit]="onGroupSubmit"
+      [onGroupSubmitInvalid]="onGroupSubmitInvalid"
+      #group="formGroup"
+    >
+      <form
+        (submit)="
+          $event.preventDefault();
+          $event.stopPropagation();
+          group.api.handleSubmit()
+        "
+      >
+        <app-text-field
+          label="Step 1 Name"
+          tanstack-app-field
+          [tanstackField]="withForm.form"
+          name="step1.name"
+        />
+
+        <button type="submit" [disabled]="isSubmitting()">Submit</button>
+
+        <!-- formGroup contains errorMaps and errors, just like forms and fields -->
+        <pre>{{ stringify(group.api.state.meta.errorMap) }}</pre>
+      </form>
+    </ng-container>
+  `,
+})
+export class Step1Component {
+  withForm = injectWithForm({ ...wizardFormOpts })
+  step = input.required<number>()
+  isSubmitting = input.required<boolean>()
+  stepChange = output<number>()
+
+  step1Schema = step1Schema
+  stringify = (value: unknown) => JSON.stringify(value, null, 2)
+
+  onGroupSubmit = () => {
+    this.stepChange.emit(this.step() + 1)
+  }
+
+  onGroupSubmitInvalid = () => {
+    // Just like a form, you can also handle invalid submits at the group level,
+    // which is useful for multi-step wizards to prevent going to the next step
+    // if the current step is invalid
+  }
+}