feat: Add new AppField API for Angular

docs/config.json

@@ -191,6 +191,10 @@
             {
               "label": "Arrays",
               "to": "framework/angular/guides/arrays"
+            },
+            {
+              "label": "Form Composition",
+              "to": "framework/angular/guides/form-composition"
             }
           ]
         },
@@ -568,6 +572,10 @@
             {
               "label": "Arrays",
               "to": "framework/angular/examples/array"
+            },
+            {
+              "label": "Form Composition",
+              "to": "framework/angular/examples/large-form"
             }
           ]
         },

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

@@ -0,0 +1,178 @@
+---
+id: form-composition
+title: Form Composition
+---
+
+A common criticism of TanStack Form is its verbosity out-of-the-box. While this _can_ be useful for educational purposes - helping enforce understanding our APIs - it's not ideal in production use cases.
+
+As a result, while basic usage of `[tanstackField]` enables the most powerful and flexible usage of TanStack Form, we provide APIs that wrap it and make your application code less verbose.
+
+## Pre-bound Field Components
+
+If you've ever used TanStack Form in Angular to bind more than one input, you'll have quickly realized how much goes into each input:
+
+```angular-ts
+import { Component } from '@angular/core'
+import { TanStackField, injectForm, injectStore } from '@tanstack/angular-form'
+
+@Component({
+  selector: 'app-root',
+  standalone: true,
+  imports: [TanStackField],
+  template: `
+    <div>
+      <ng-container
+        [tanstackField]="form"
+        name="firstName"
+        #firstName="field"
+      >
+        <label [for]="firstName.api.name">First Name:</label>
+        <input
+          [id]="firstName.api.name"
+          [name]="firstName.api.name"
+          [value]="firstName.api.state.value"
+          (blur)="firstName.api.handleBlur()"
+          (input)="firstName.api.handleChange($any($event).target.value)"
+        />
+        @if (firstName.api.state.meta.isTouched) {
+          @for (error of firstName.api.state.meta.errors; track $index) {
+            <div style="color: red">
+              {{ error }}
+            </div>
+          }
+        }
+        @if (firstName.api.state.meta.isValidating) {
+          <p>Validating...</p>
+        }
+      </ng-container>
+    </div>
+    <div>
+      <ng-container
+        [tanstackField]="form"
+        name="lastName"
+        #lastName="field"
+      >
+        <label [for]="lastName.api.name">Last Name:</label>
+        <input
+          [id]="lastName.api.name"
+          [name]="lastName.api.name"
+          [value]="lastName.api.state.value"
+          (blur)="lastName.api.handleBlur()"
+          (input)="lastName.api.handleChange($any($event).target.value)"
+        />
+        @if (lastName.api.state.meta.isTouched) {
+          @for (error of lastName.api.state.meta.errors; track $index) {
+            <div style="color: red">
+              {{ error }}
+            </div>
+          }
+        }
+        @if (lastName.api.state.meta.isValidating) {
+          <p>Validating...</p>
+        }
+      </ng-container>
+    </div>
+  `,
+})
+export class AppComponent {
+  form = injectForm({
+    defaultValues: {
+      firstName: '',
+      lastName: '',
+    },
+    onSubmit({ value }) {
+      // Do something with form data
+      console.log(value)
+    },
+  })
+}
+```
+
+This is functionally correct, but introduces a _lot_ of repeated templating behavior over and over. Instead, let's move the error handling, label to input binding, and other repeated logic into a component:
+
+```angular-ts
+import {injectField} from '@tanstack/angular-form'
+
+@Component({
+  selector: 'app-text-field',
+  standalone: true,
+  template: `
+    <label [for]="field.api.name">{{ label() }}</label>
+    <input
+      [id]="field.api.name"
+      [name]="field.api.name"
+      [value]="field.api.state.value"
+      (blur)="field.api.handleBlur()"
+      (input)="field.api.handleChange($any($event).target.value)"
+    />
+    @if (field.api.state.meta.isTouched) {
+      @for (error of field.api.state.meta.errors; track $index) {
+        <div style="color: red">
+          {{ error }}
+        </div>
+      }
+    }
+    @if (field.api.state.meta.isValidating) {
+      <p>Validating...</p>
+    }
+  `,
+})
+export class AppTextField {
+  label = input.required<string>()
+  // This API requires another part to it from the parent component
+  field = injectField<string>()
+}
+```
+
+> `injectField` accepts a single generic to define the `field.state.value` type.
+>
+> As a result, a numerical text field would be represented as `injectField<number>`, for example.
+
+Now, we can use the `TanStackAppField` directive (`tanstack-app-field`) to `provide` the expected field associated with this input:
+
+```angular-ts
+import { Component } from '@angular/core'
+import {
+  TanStackAppField,
+  TanStackField,
+  injectForm,
+} from '@tanstack/angular-form'
+
+@Component({
+  selector: 'app-root',
+  standalone: true,
+  imports: [TanStackField, TanStackAppField, AppTextField],
+  template: `
+    <div>
+      <app-text-field
+        label="First name:"
+        tanstack-app-field
+        [tanstackField]="form"
+        name="firstName"
+      />
+    </div>
+    <div>
+      <app-text-field
+        label="Last name:"
+        tanstack-app-field
+        [tanstackField]="form"
+        name="lastName"
+      />
+    </div>
+  `,
+})
+export class AppComponent {
+  form = injectForm({
+    defaultValues: {
+      firstName: '',
+      lastName: '',
+    },
+    onSubmit({ value }) {
+      // Do something with form data
+      console.log(value)
+    },
+  })
+}
+```
+
+> Here, the `tanstack-app-field` directive is taking the properties from `[tanstackField]` and `provide`ing them down to the `app-text-field` so that they can be more easily consumed as a component.

examples/angular/array/package.json

@@ -10,23 +10,23 @@
     "test": "ng test"
   },
   "dependencies": {
-    "@angular/animations": "^19.2.14",
-    "@angular/common": "^19.2.14",
-    "@angular/compiler": "^19.2.14",
-    "@angular/core": "^19.2.14",
-    "@angular/forms": "^19.2.14",
-    "@angular/platform-browser": "^19.2.14",
-    "@angular/platform-browser-dynamic": "^19.2.14",
-    "@angular/router": "^19.2.14",
+    "@angular/animations": "^20.0.0",
+    "@angular/common": "^20.0.0",
+    "@angular/compiler": "^20.0.0",
+    "@angular/core": "^20.0.0",
+    "@angular/forms": "^20.0.0",
+    "@angular/platform-browser": "^20.0.0",
+    "@angular/platform-browser-dynamic": "^20.0.0",
+    "@angular/router": "^20.0.0",
     "@tanstack/angular-form": "^1.12.4",
     "rxjs": "^7.8.2",
     "tslib": "^2.8.1",
-    "zone.js": "^0.15.1"
+    "zone.js": "0.15.1"
   },
   "devDependencies": {
-    "@angular-devkit/build-angular": "^19.2.15",
-    "@angular/cli": "^19.2.15",
-    "@angular/compiler-cli": "^19.2.14",
+    "@angular-devkit/build-angular": "^20.0.0",
+    "@angular/cli": "^20.0.0",
+    "@angular/compiler-cli": "^20.0.0",
     "typescript": "5.8.2"
   }
 }

examples/angular/large-form/.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/large-form/.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/large-form/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.