fixup! docs(forms): add initial signal forms examples

Author: clydin

packages/forms/signals/examples/03-cross-field-validation.md

@@ -1,13 +1,13 @@
 ---
 title: Signal Form with Cross-Field Validation
-summary: Implements a cross-field validator using `validateTree` to ensure two fields in a signal form are consistent with each other.
+summary: Implements a cross-field validator by applying a validator to one field that reactively depends on the value of another field.
 keywords:
   - signal forms
   - form
   - control
   - validation
   - cross-field validation
-  - validateTree
+  - valueOf
   - schema
   - minLength
   - submit
@@ -23,25 +23,25 @@ The purpose of this pattern is to implement validation logic that depends on the
 
 ## When to Use
 
-Use this pattern when the validity of one form field depends on the value of another. This is common in registration forms, password change forms, and any form where two fields must be consistent with each other. `validateTree` is the signal-based equivalent of a cross-field validator on a `FormGroup` in `ReactiveFormsModule`.
+Use this pattern when the validity of one form field depends on the value of another. This is common in registration forms, password change forms, and any form where two fields must be consistent with each other. The recommended approach is to apply a validator to the field where the error should be reported (e.g., `confirmPassword`) and use the `valueOf` function in the validation context to reactively get the value of the other field it depends on (e.g., `password`).
 
 ## Key Concepts
 
-- **`validateTree()`:** A function used within a schema to add a validator to a form group or the entire form.
+- **`validate()`:** A function used within a schema to add a validator to a specific field.
+- **`valueOf()`:** A function available in the validation context that allows you to reactively access the value of any other field in the form.
 - **`valid` signal:** A signal on the `FieldState` that is `true` only when the field and all its descendants are valid.
-- **`(ngSubmit)`:** An event binding on a `<form>` element that triggers a method when the form is submitted.
 
 ## Example Files
 
 This example consists of a standalone component that defines and manages a password change form.
 
 ### password-form.component.ts
 
-This file defines the component's logic, including a schema with a `validateTree` function for cross-field validation.
+This file defines the component's logic. The schema applies a validator to `confirmPassword` that compares its value to the value of the `password` field.
 
 ```typescript
 import { Component, signal, Output, EventEmitter, ChangeDetectionStrategy } from '@angular/core';
-import { form, schema, validate, validateTree } from '@angular/forms/signals';
+import { form, schema, validate } from '@angular/forms/signals';
 import { JsonPipe } from '@angular/common';
 
 export interface PasswordForm {
@@ -56,9 +56,9 @@ const passwordSchema = schema<PasswordForm>((passwordForm) => {
     return null;
   });
 
-  validateTree(passwordForm, ({value, fieldOf}) => {
-    if (value.password !== value.confirmPassword) {
-      return [{ field: fieldOf(passwordForm.confirmPassword), error: { mismatch: true } }];
+  validate(passwordForm.confirmPassword, ({value, valueOf}) => {
+    if (value !== valueOf(passwordForm.password)) {
+      return { mismatch: true };
     }
     return null;
   });

packages/forms/signals/examples/04-conditional-validation.md

@@ -1,13 +1,13 @@
 ---
 title: Signal Form with Conditional Validation
-summary: Applies a validator to a signal form field only when a specific condition is met by using the `validateWhen` function.
+summary: Applies a validator to a signal form field only when a specific condition is met by using the `applyWhen` function.
 keywords:
   - signal forms
   - form
   - control
   - validation
   - conditional validation
-  - validateWhen
+  - applyWhen
   - schema
   - submit
 required_packages:
@@ -26,7 +26,7 @@ Use this pattern when a validation rule for one field depends on the state of an
 
 ## Key Concepts
 
-- **`validateWhen()`:** A function used within a schema to apply a validator conditionally.
+- **`applyWhen()`:** A function used within a schema to apply a validator conditionally.
 - **`valid` signal:** A signal on the `FieldState` that is `true` only when the field and all its descendants are valid.
 - **`(ngSubmit)`:** An event binding on a `<form>` element that triggers a method when the form is submitted.
 
@@ -36,11 +36,11 @@ This example consists of a standalone component that defines and manages a conta
 
 ### contact-form.component.ts
 
-This file defines the component's logic, including a schema that uses `validateWhen` to apply a validator conditionally.
+This file defines the component's logic, including a schema that uses `applyWhen` to apply a validator conditionally.
 
 ```typescript
 import { Component, signal, Output, EventEmitter, ChangeDetectionStrategy } from '@angular/core';
-import { form, schema, validateWhen } from '@angular/forms/signals';
+import { form, schema, applyWhen, required } from '@angular/forms/signals';
 import { JsonPipe } from '@angular/common';
 
 export interface ContactForm {
@@ -49,10 +49,10 @@ export interface ContactForm {
 }
 
 const contactSchema = schema<ContactForm>((contactForm) => {
-  validateWhen(
-    contactForm.email,
-    ({valueOf}) => valueOf(contactForm.subscribe),
-    ({value}) => (value === '' ? { required: true } : null)
+  applyWhen(
+    contactForm,
+    ({value}) => value().subscribe,
+    schema((form) => required(form.email))
   );
 });
 

packages/forms/signals/examples/09-async-validation.md

@@ -1,17 +1,18 @@
 ---
 title: Signal Form with Asynchronous Validation
-summary: Implements an asynchronous validator on a signal form field using `validateAsync` to check for a unique username against a mock backend service.
+summary: Implements an asynchronous validator on a signal form field using `validateHttp` to check for a unique username against a mock backend endpoint.
 keywords:
   - signal forms
   - form
   - control
   - validation
   - asynchronous validation
   - async
-  - validateAsync
+  - validateHttp
   - schema
 required_packages:
   - '@angular/forms'
+  - '@angular/common'
 related_concepts:
   - 'signals'
 ---
@@ -22,68 +23,37 @@ The purpose of this pattern is to perform validation that requires an asynchrono
 
 ## When to Use
 
-Use this pattern for validation that requires a network request, a debounce, or any other asynchronous operation. It allows the UI to remain responsive while the validation is in progress and provides feedback to the user once the validation is complete. This is the modern, signal-based equivalent of `AsyncValidator` in `ReactiveFormsModule`.
+Use this pattern for validation that requires a network request. The `validateHttp` function provides a convenient, built-in way to integrate backend validation. It allows the UI to remain responsive while the validation is in progress and provides feedback to the user once the validation is complete. This is the modern, signal-based equivalent of `AsyncValidator` in `ReactiveFormsModule`.
 
 ## Key Concepts
 
-- **`validateAsync()`:** A function used within a schema to add an asynchronous validator to a field.
-- **Asynchronous Validator Function:** A function that returns a `Promise` which resolves to an error object or `null`.
+- **`validateHttp()`:** A function used within a schema to add an asynchronous validator to a field based on an HTTP request.
 - **`pending` signal:** A signal on the `FieldState` that is `true` while an asynchronous validator is running.
 
 ## Example Files
 
-This example consists of a standalone component and a service that work together to perform asynchronous validation.
-
-### username.service.ts
-
-This file defines a mock service that simulates an asynchronous check for username uniqueness.
-
-```typescript
-import { Injectable } from '@angular/core';
-import { of } from 'rxjs';
-import { delay } from 'rxjs/operators';
-
-@Injectable({ providedIn: 'root' })
-export class UsernameService {
-  private existingUsernames = ['admin', 'user', 'test'];
-
-  isUsernameTaken(username: string): Promise<boolean> {
-    return of(this.existingUsernames.includes(username.toLowerCase()))
-      .pipe(delay(500))
-      .toPromise();
-  }
-}
-```
+This example consists of a standalone component that performs asynchronous validation against a mock API endpoint.
 
 ### registration-form.component.ts
 
-This file defines the component's logic, including a schema that uses `validateAsync` to call the username service.
+This file defines the component's logic, including a schema that uses `validateHttp` to call the username validation endpoint.
 
 ```typescript
-import { Component, inject, signal, Output, EventEmitter, ChangeDetectionStrategy } from '@angular/core';
-import { form, schema, validate, validateAsync } from '@angular/forms/signals';
+import { Component, signal, Output, EventEmitter, ChangeDetectionStrategy } from '@angular/core';
+import { form, schema, required, validateHttp } from '@angular/forms/signals';
 import { JsonPipe } from '@angular/common';
-import { UsernameService } from './username.service';
 
 export interface RegistrationForm {
   username: string;
 }
 
-const createRegistrationSchema = (usernameService: UsernameService) => {
-  return schema<RegistrationForm>((registrationForm) => {
-    validate(registrationForm.username, ({value}) => {
-      if (value === '') {
-        return { required: true };
-      }
-      return null;
-    });
-    validateAsync(registrationForm.username, async ({value}) => {
-      if (value === '') return null;
-      const isTaken = await usernameService.isUsernameTaken(value);
-      return isTaken ? { unique: true } : null;
-    });
+const registrationSchema = schema<RegistrationForm>((form) => {
+  required(form.username);
+  validateHttp(form.username, {
+    request: ({value}) => `/api/username-check?username=${value}`,
+    errors: (result: {isTaken: boolean}) => (result.isTaken ? {unique: true} : null),
   });
-};
+});
 
 @Component({
   selector: 'app-registration-form',
@@ -95,13 +65,11 @@ const createRegistrationSchema = (usernameService: UsernameService) => {
 export class RegistrationFormComponent {
   @Output() submitted = new EventEmitter<RegistrationForm>();
 
-  private usernameService = inject(UsernameService);
-
   registrationModel = signal<RegistrationForm>({
     username: '',
   });
 
-  registrationForm = form(this.registrationModel, createRegistrationSchema(this.usernameService));
+  registrationForm = form(this.registrationModel, registrationSchema);
 
   handleSubmit() {
     if (this.registrationForm().valid()) {
@@ -144,15 +112,47 @@ This file provides the template for the form, showing how to display feedback wh
 
 ## Usage Notes
 
-- The **`validateAsync`** function takes a `FieldPath` and an async validator function.
-- The async validator function should return a `Promise` that resolves with the validation result.
+- The **`validateHttp`** function takes a `FieldPath` and an options object.
+- The `request` function returns the URL for the validation request.
+- The `errors` function maps the HTTP response to a validation error.
 - The **`pending`** signal on the field state (`registrationForm.username().pending()`) can be used to show a loading indicator to the user.
 
 ## How to Use This Example
 
-The parent component listens for the `(submitted)` event to receive the strongly-typed form data.
+To run this example, you need to provide an `HttpClient` and a mock backend that can respond to the validation requests.
 
 ```typescript
+// in app.config.ts
+import { ApplicationConfig } from '@angular/core';
+import { provideHttpClient, withInterceptors } from '@angular/common/http';
+import { HttpTestingController, provideHttpClientTesting } from '@angular/common/http/testing';
+
+// A simple interceptor to mock the backend
+const mockApiInterceptor = (req, next) => {
+  const controller = TestBed.inject(HttpTestingController);
+  const existingUsernames = ['admin', 'user', 'test'];
+
+  if (req.url.startsWith('/api/username-check')) {
+    const username = req.params.get('username');
+    const isTaken = existingUsernames.includes(username?.toLowerCase() ?? '');
+    
+    // Use a timeout to simulate network latency
+    setTimeout(() => {
+      const mockReq = controller.expectOne(req.urlWithParams);
+      mockReq.flush({ isTaken });
+    }, 500);
+  }
+  
+  return next(req);
+};
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    provideHttpClient(withInterceptors([mockApiInterceptor])),
+    provideHttpClientTesting(),
+  ],
+};
+
 // in app.component.ts
 import { Component } from '@angular/core';
 import { JsonPipe } from '@angular/common';