feat(forms): add experimental signal-based forms (angular#63408)

This commit introduces an experimental version of a new signal-based forms API for Angular. This new API aims to explore how signals can be leveraged to create a more declarative, intuitive, and reactive way of handling forms.

The primary goals of this new signal-based approach are:

*   **Signal-centric Design:** Place signals at the core of the forms experience, enabling a truly reactive programming model for form state and logic.
*   **Declarative Logic:** Allow developers to define form behavior, such as validation and conditional fields, declaratively using TypeScript. This moves logic out of the template and into a typed, testable schema.
*   **Developer-Owned Data Model:** The library does not maintain a copy of data in a form model, but instead read and write it via a developer-provided `WritableSignal`, eliminating the need for applications to synchronize their data with the form system.
*   **Interoperability:** A key design goal is seamless interoperability with existing reactive forms, allowing for incremental adoption.
*   **Bridging Template and Reactive Forms:** This exploration hopes to close the gap between template and reactive forms, offering a unified and more powerful approach that combines the best aspects of both.

This initial version of the experimental API includes the core building blocks, such as the `form()` function, `Field` and `FieldState` objects, and a `[control]` directive for binding to UI elements. It also introduces a schema-based system for defining validation, conditional logic, and other form behaviors.

Note: This is an early, experimental API. It is not yet complete and is subject to change based on feedback and further exploration.

Co-authored-by: Kirill Cherkashin <[email protected]>
Co-authored-by: Alex Rickabaugh <[email protected]>
Co-authored-by: Leon Senft <[email protected]>
Co-authored-by: Dylan Hunn <[email protected]>
Co-authored-by: Michael Small <[email protected]>

PR Close angular#63408

Author: mmalerba

goldens/public-api/forms/signals/index.api.md

@@ -81,6 +81,7 @@
     "@rollup/plugin-commonjs": "^28.0.0",
     "@rollup/plugin-node-resolve": "^16.0.0",
     "@schematics/angular": "21.0.0-next.1",
+    "@standard-schema/spec": "^1.0.0",
     "@types/angular": "^1.6.47",
     "@types/babel__core": "7.20.5",
     "@types/babel__generator": "7.27.0",
@@ -209,7 +210,8 @@
     "tslint-no-toplevel-property-access": "0.0.2",
     "typed-graphqlify": "^3.1.1",
     "undici": "^7.0.0",
-    "vrsource-tslint-rules": "6.0.0"
+    "vrsource-tslint-rules": "6.0.0",
+    "zod": "^4.0.10"
   },
   "resolutions": {
     "https-proxy-agent": "7.0.6",

package.json

@@ -0,0 +1,28 @@
+load("//tools:defaults.bzl", "api_golden_test", "ng_project")
+
+package(default_visibility = ["//visibility:public"])
+
+ng_project(
+    name = "signals",
+    srcs = glob(
+        [
+            "*.ts",
+            "src/**/*.ts",
+        ],
+    ),
+    deps = [
+        "//:node_modules/@standard-schema/spec",
+        "//packages/core",
+        "//packages/forms",
+    ],
+)
+
+api_golden_test(
+    name = "forms_signals_api",
+    data = [
+        "//goldens:public-api",
+        "//packages/forms/signals",
+    ],
+    entry_point = "index.d.ts",
+    golden = "goldens/public-api/forms/signals/index.api.md",
+)

packages/forms/signals/BUILD.bazel

@@ -0,0 +1,37 @@
+# 🚧 Experimental Signal-Based Forms API 🏗️
+
+This directory contains an experimental new Angular Forms API built on top of
+[signals](https://angular.dev/guide/signals). We're using this experimental API to explore potential
+designs for such a system, to play with new ideas, identify challenges, and to demonstrate
+interoperability with the existing version of `@angular/forms`.
+
+## Not yet supported
+
+- Debouncing validation
+- Dynamic objects
+- Tuples
+- Interop with Reactive/Template forms
+- Strongly-typed binding to UI controls
+
+## FAQs
+
+### Why are you working on this?
+
+We've been exploring ways that we can integrate signals into Angular's forms package. We've looked
+at several options, including integrating signals into template and reactive forms, and designing a
+new flavor of forms with signals at the core. Our hope is that we can leverage this work to close
+the gap between template and reactive forms, which often inspires debate in the Angular ecosystem.
+
+### What does this mean for the future of template and/or reactive forms?
+
+Nothing is changing yet with template and reactive forms. This API is early and still highly experimental.
+
+Even if we achieve our goals, we will roll out any changes to forms incrementally. Like with NgModules
+and `standalone`, we don't intend to deprecate template or reactive forms without a clear sign from
+our community that the ecosystem is fully on board.
+
+### Will I need to rewrite my application code to use the new forms system?
+
+No - a non-negotiable design goal of a new signal-based forms system is interoperability with
+existing forms code and applications. It should be possible to incrementally start using the new
+system in existing applications, and as always we will explore the possibility of automated migrations.

packages/forms/signals/README.md

@@ -0,0 +1,14 @@
+/**
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.dev/license
+ */
+
+// This file is not used to build this module. It is only used during editing
+// by the TypeScript language service and during build for verification. `ngc`
+// replaces this file with production index.ts when it rewrites private symbol
+// names.
+
+export * from './public_api';

packages/forms/signals/index.ts

@@ -0,0 +1,23 @@
+/**
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.dev/license
+ */
+
+/**
+ * @module
+ * @description
+ * Entry point for all public APIs of this package.
+ */
+export * from './src/api/async';
+export * from './src/api/control';
+export * from './src/api/logic';
+export * from './src/api/property';
+export * from './src/api/structure';
+export * from './src/api/types';
+export * from './src/api/validators';
+export * from './src/controls/control';
+export * from './src/controls/interop_ng_control';
+export * from './src/api/validation_errors';

packages/forms/signals/public_api.ts

@@ -0,0 +1,194 @@
+/**
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.dev/license
+ */
+
+import {httpResource, HttpResourceOptions, HttpResourceRequest} from '@angular/common/http';
+import {computed, ResourceRef, Signal} from '@angular/core';
+import {FieldNode} from '../field/node';
+import {addDefaultField} from '../field/validation';
+import {FieldPathNode} from '../schema/path_node';
+import {assertPathIsCurrent} from '../schema/schema';
+import {property} from './logic';
+import {FieldContext, FieldPath, PathKind, TreeValidationResult} from './types';
+
+/**
+ * A function that takes the result of an async operation and the current field context, and maps it
+ * to a list of validation errors.
+ *
+ * @param result The result of the async operation.
+ * @param ctx The context for the field the validator is attached to.
+ * @return A validation error, or list of validation errors to report based on the result of the async operation.
+ *   The returned errors can optionally specify a field that the error should be targeted to.
+ *   A targeted error will show up as an error on its target field rather than the field being validated.
+ *   If a field is not given, the error is assumed to apply to the field being validated.
+ * @template TValue The type of value stored in the field being validated.
+ * @template TResult The type of result returned by the async operation
+ * @template TPathKind The kind of path being validated (a root path, child path, or item of an array)
+ */
+export type MapToErrorsFn<TValue, TResult, TPathKind extends PathKind = PathKind.Root> = (
+  result: TResult,
+  ctx: FieldContext<TValue, TPathKind>,
+) => TreeValidationResult;
+
+/**
+ * Options that indicate how to create a resource for async validation for a field,
+ * and map its result to validation errors.
+ *
+ * @template TValue The type of value stored in the field being validated.
+ * @template TParams The type of parameters to the resource.
+ * @template TResult The type of result returned by the resource
+ * @template TPathKind The kind of path being validated (a root path, child path, or item of an array)
+ */
+export interface AsyncValidatorOptions<
+  TValue,
+  TParams,
+  TResult,
+  TPathKind extends PathKind = PathKind.Root,
+> {
+  /**
+   * A function that receives the field context and returns the params for the resource.
+   *
+   * @param ctx The field context for the field being validated.
+   * @returns The params for the resource.
+   */
+  readonly params: (ctx: FieldContext<TValue, TPathKind>) => TParams;
+
+  /**
+   * A function that receives the resource params and returns a resource of the given params.
+   * The given params should be used as is to create the resource.
+   * The forms system will report the params as `undefined` when this validation doesn't need to be run.
+   *
+   * @param params The params to use for constructing the resource
+   * @returns A reference to the constructed resource.
+   */
+  readonly factory: (params: Signal<TParams | undefined>) => ResourceRef<TResult | undefined>;
+
+  /**
+   * A function that takes the resource result, and the current field context and maps it to a list
+   * of validation errors.
+   *
+   * @param result The resource result.
+   * @param ctx The context for the field the validator is attached to.
+   * @return A validation error, or list of validation errors to report based on the resource result.
+   *   The returned errors can optionally specify a field that the error should be targeted to.
+   *   A targeted error will show up as an error on its target field rather than the field being validated.
+   *   If a field is not given, the error is assumed to apply to the field being validated.
+   */
+  readonly errors: MapToErrorsFn<TValue, TResult, TPathKind>;
+}
+
+/**
+ * Options that indicate how to create an httpResource for async validation for a field,
+ * and map its result to validation errors.
+ *
+ * @template TValue The type of value stored in the field being validated.
+ * @template TResult The type of result returned by the httpResource
+ * @template TPathKind The kind of path being validated (a root path, child path, or item of an array)
+ */
+export interface HttpValidatorOptions<TValue, TResult, TPathKind extends PathKind = PathKind.Root> {
+  /**
+   * A function that receives the field context and returns the url or request for the httpResource.
+   * If given a URL, the underlying httpResource will perform an HTTP GET on it.
+   *
+   * @param ctx The field context for the field being validated.
+   * @returns The URL or request for creating the httpResource.
+   */
+  readonly request:
+    | ((ctx: FieldContext<TValue, TPathKind>) => string | undefined)
+    | ((ctx: FieldContext<TValue, TPathKind>) => HttpResourceRequest | undefined);
+
+  /**
+   * A function that takes the httpResource result, and the current field context and maps it to a
+   * list of validation errors.
+   *
+   * @param result The httpResource result.
+   * @param ctx The context for the field the validator is attached to.
+   * @return A validation error, or list of validation errors to report based on the httpResource result.
+   *   The returned errors can optionally specify a field that the error should be targeted to.
+   *   A targeted error will show up as an error on its target field rather than the field being validated.
+   *   If a field is not given, the error is assumed to apply to the field being validated.
+   */
+  readonly errors: MapToErrorsFn<TValue, TResult, TPathKind>;
+
+  /**
+   * The options to use when creating the httpResource.
+   */
+  readonly options?: HttpResourceOptions<TResult, unknown>;
+}
+
+/**
+ * Adds async validation to the field corresponding to the given path based on a resource.
+ * Async validation for a field only runs once all synchronous validation is passing.
+ *
+ * @param path A path indicating the field to bind the async validation logic to.
+ * @param opts The async validation options.
+ * @template TValue The type of value stored in the field being validated.
+ * @template TParams The type of parameters to the resource.
+ * @template TResult The type of result returned by the resource
+ * @template TPathKind The kind of path being validated (a root path, child path, or item of an array)
+ */
+export function validateAsync<TValue, TParams, TResult, TPathKind extends PathKind = PathKind.Root>(
+  path: FieldPath<TValue, TPathKind>,
+  opts: AsyncValidatorOptions<TValue, TParams, TResult, TPathKind>,
+): void {
+  assertPathIsCurrent(path);
+  const pathNode = FieldPathNode.unwrapFieldPath(path);
+
+  const RESOURCE = property(path, (ctx) => {
+    const params = computed(() => {
+      const node = ctx.stateOf(path) as FieldNode;
+      const validationState = node.validationState;
+      if (validationState.shouldSkipValidation() || !validationState.syncValid()) {
+        return undefined;
+      }
+      return opts.params(ctx);
+    });
+    return opts.factory(params);
+  });
+
+  pathNode.logic.addAsyncErrorRule((ctx) => {
+    const res = ctx.state.property(RESOURCE)!;
+    switch (res.status()) {
+      case 'idle':
+        return undefined;
+      case 'loading':
+      case 'reloading':
+        return 'pending';
+      case 'resolved':
+      case 'local':
+        if (!res.hasValue()) {
+          return undefined;
+        }
+        const errors = opts.errors(res.value()!, ctx as FieldContext<TValue, TPathKind>);
+        return addDefaultField(errors, ctx.field);
+      case 'error':
+        // TODO: Design error handling for async validation. For now, just throw the error.
+        throw res.error();
+    }
+  });
+}
+
+/**
+ * Adds async validation to the field corresponding to the given path based on an httpResource.
+ * Async validation for a field only runs once all synchronous validation is passing.
+ *
+ * @param path A path indicating the field to bind the async validation logic to.
+ * @param opts The http validation options.
+ * @template TValue The type of value stored in the field being validated.
+ * @template TResult The type of result returned by the httpResource
+ * @template TPathKind The kind of path being validated (a root path, child path, or item of an array)
+ */
+export function validateHttp<TValue, TResult = unknown, TPathKind extends PathKind = PathKind.Root>(
+  path: FieldPath<TValue, TPathKind>,
+  opts: HttpValidatorOptions<TValue, TResult, TPathKind>,
+) {
+  validateAsync(path, {
+    params: opts.request,
+    factory: (request: Signal<any>) => httpResource(request, opts.options),
+    errors: opts.errors,
+  });
+}