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

Author: clydin

packages/forms/signals/examples/01-basic-signal-form.md

@@ -25,8 +25,7 @@ Use this pattern as the starting point for any new form in an Angular applicatio
 
 - **`form()`:** A function that creates a `Field` representing the form, taking a `WritableSignal` as the data model.
 - **`[control]` directive:** Binds a `Field` from your component to a native HTML input element, creating a two-way data binding.
-- **`@Output()`:** A decorator used to emit custom events from a child component to a parent component.
-- **`(ngSubmit)`:** An event binding on a `<form>` element that triggers a method when the form is submitted.
+- **`submit()`:** An async helper function that manages the form's submission state and should be called from the submit event handler.
 
 ## Example Files
 
@@ -38,7 +37,7 @@ This file defines the component's logic, including the signal-based data model a
 
 ```typescript
 import { Component, signal, Output, EventEmitter, ChangeDetectionStrategy } from '@angular/core';
-import { form } from '@angular/forms/signals';
+import { form, submit } from '@angular/forms/signals';
 import { JsonPipe } from '@angular/common';
 
 export interface UserProfile {
@@ -65,20 +64,22 @@ export class UserProfileComponent {
 
   profileForm = form(this.profileModel);
 
-  handleSubmit() {
+  async handleSubmit() {
     // For this basic example, we assume the form is always valid for submission.
     // See the validation example for how to handle invalid forms.
-    this.submitted.emit(this.profileForm().value());
+    await submit(this.profileForm, async () => {
+      this.submitted.emit(this.profileForm().value());
+    });
   }
 }
 ```
 
 ### user-profile.component.html
 
-The template is wrapped in a `<form>` tag with an `(ngSubmit)` event and a submit button.
+The template is wrapped in a `<form>` tag with a `(submit)` event and a submit button.
 
 ```html
-<form (ngSubmit)="handleSubmit()">
+<form (submit)="handleSubmit(); $event.preventDefault()">
   <div>
     <label>
       First Name:
@@ -109,8 +110,8 @@ The template is wrapped in a `<form>` tag with an `(ngSubmit)` event and a submi
 
 - The `[control]` directive automatically handles the two-way data binding between the input element and the corresponding `Field` in the `profileForm`.
 - The `profileForm()` signal gives you access to the `FieldState`, which includes the form's `value` as a signal.
-- The `(ngSubmit)` event on the `<form>` element is bound to the `handleSubmit` method in the component.
-- When `handleSubmit` is called, it emits the current form value through the `submitted` output property.
+- The native `(submit)` event on the `<form>` element is bound to the `handleSubmit` method. It's important to call `$event.preventDefault()` to prevent a full page reload.
+- The `handleSubmit` method uses the `submit()` helper to manage the submission process.
 
 ## How to Use This Example
 

packages/forms/signals/examples/02-built-in-validators.md

@@ -31,11 +31,8 @@ Use this pattern as the primary method for applying common validation logic in y
 
 - **`required()`:** A built-in validator that ensures a field has a value.
 - **`minLength(number)`:** A built-in validator that ensures a string's length is at least the specified minimum.
-- **`maxLength(number)`:** A built-in validator that ensures a string's length does not exceed the specified maximum.
-- **`min(number)`:** A built-in validator that ensures a numeric value is at least the specified minimum.
-- **`max(number)`:** A built-in validator that ensures a numeric value does not exceed the specified maximum.
 - **`email()`:** A built-in validator that checks if a string is in a valid email format.
-- **`pattern(RegExp)`:** A built-in validator that checks if a string matches a given regular expression.
+- **`submit()`:** An async helper function that manages the form's submission state and should be called from the submit event handler.
 
 ## Example Files
 
@@ -47,7 +44,7 @@ This file defines the component's logic, including the data model and a validati
 
 ```typescript
 import { Component, signal, Output, EventEmitter, ChangeDetectionStrategy } from '@angular/core';
-import { form, schema } from '@angular/forms/signals';
+import { form, schema, submit } from '@angular/forms/signals';
 import { required, minLength, maxLength, min, max, email, pattern } from '@angular/forms/signals';
 import { JsonPipe } from '@angular/common';
 
@@ -92,10 +89,10 @@ export class UserSettingsComponent {
 
   settingsForm = form(this.settingsModel, settingsSchema);
 
-  handleSubmit() {
-    if (this.settingsForm().valid()) {
+  async handleSubmit() {
+    await submit(this.settingsForm, async () => {
       this.submitted.emit(this.settingsForm().value());
-    }
+    });
   }
 }
 ```
@@ -105,16 +102,18 @@ export class UserSettingsComponent {
 This file provides the template for the form, displaying specific error messages for each potential validation failure.
 
 ```html
-<form (ngSubmit)="handleSubmit()">
+<form (submit)="handleSubmit(); $event.preventDefault()">
   <div>
     <label>Username:</label>
     <input type="text" [control]="settingsForm.username" />
     @if (settingsForm.username().errors().length > 0) {
       <div class="errors">
         @for (error of settingsForm.username().errors()) {
-          @if (error.required) { <p>Username is required.</p> }
-          @if (error.minLength) { <p>Username must be at least 3 characters.</p> }
-          @if (error.maxLength) { <p>Username cannot exceed 20 characters.</p> }
+          @switch (error.kind) {
+            @case ('required') { <p>Username is required.</p> }
+            @case ('minLength') { <p>Username must be at least 3 characters.</p> }
+            @case ('maxLength') { <p>Username cannot exceed 20 characters.</p> }
+          }
         }
       </div>
     }
@@ -126,9 +125,11 @@ This file provides the template for the form, displaying specific error messages
     @if (settingsForm.age().errors().length > 0) {
       <div class="errors">
         @for (error of settingsForm.age().errors()) {
-          @if (error.required) { <p>Age is required.</p> }
-          @if (error.min) { <p>You must be at least 18 years old.</p> }
-          @if (error.max) { <p>Age cannot be more than 100.</p> }
+          @switch (error.kind) {
+            @case ('required') { <p>Age is required.</p> }
+            @case ('min') { <p>You must be at least 18 years old.</p> }
+            @case ('max') { <p>Age cannot be more than 100.</p> }
+          }
         }
       </div>
     }
@@ -140,8 +141,10 @@ This file provides the template for the form, displaying specific error messages
     @if (settingsForm.email().errors().length > 0) {
       <div class="errors">
         @for (error of settingsForm.email().errors()) {
-          @if (error.required) { <p>Email is required.</p> }
-          @if (error.email) { <p>Please enter a valid email address.</p> }
+          @switch (error.kind) {
+            @case ('required') { <p>Email is required.</p> }
+            @case ('email') { <p>Please enter a valid email address.</p> }
+          }
         }
       </div>
     }
@@ -153,7 +156,9 @@ This file provides the template for the form, displaying specific error messages
     @if (settingsForm.website().errors().length > 0) {
       <div class="errors">
         @for (error of settingsForm.website().errors()) {
-          @if (error.pattern) { <p>Please enter a valid URL.</p> }
+          @switch (error.kind) {
+            @case ('pattern') { <p>Please enter a valid URL.</p> }
+          }
         }
       </div>
     }
@@ -166,7 +171,8 @@ This file provides the template for the form, displaying specific error messages
 ## Usage Notes
 
 - All built-in validators are imported directly from `@angular/forms`.
-- Each validator is a function that takes the `FieldPath` as its first argument, and optional configuration (like the minimum length) as the second.
+- The native `(submit)` event on the `<form>` element is bound to the `handleSubmit` method. It's important to call `$event.preventDefault()` to prevent a full page reload.
+- The `handleSubmit` method uses the `submit()` helper to manage the submission process.
 
 ## How to Use This Example
 

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

@@ -1,6 +1,6 @@
 ---
 title: Signal Form with Cross-Field Validation
-summary: Implements a cross-field validator by applying a validator to one field that reactively depends on the value of another field.
+summary: Implements a cross-field validator by applying a validator to one field that reactively depends on the value of another field using `valueOf`.
 keywords:
   - signal forms
   - form
@@ -29,7 +29,7 @@ Use this pattern when the validity of one form field depends on the value of ano
 
 - **`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.
+- **`submit()`:** An async helper function that manages the form's submission state and should be called from the submit event handler.
 
 ## Example Files
 
@@ -41,7 +41,7 @@ This file defines the component's logic. The schema applies a validator to `conf
 
 ```typescript
 import { Component, signal, Output, EventEmitter, ChangeDetectionStrategy } from '@angular/core';
-import { form, schema, validate } from '@angular/forms/signals';
+import { form, schema, validate, requiredError, minLengthError, customError, submit } from '@angular/forms/signals';
 import { JsonPipe } from '@angular/common';
 
 export interface PasswordForm {
@@ -51,14 +51,14 @@ export interface PasswordForm {
 
 const passwordSchema = schema<PasswordForm>((passwordForm) => {
   validate(passwordForm.password, ({value}) => {
-    if (value === '') return { required: true };
-    if (value.length < 8) return { minLength: { requiredLength: 8, actualLength: value.length } };
+    if (value() === '') return requiredError();
+    if (value().length < 8) return minLengthError(8);
     return null;
   });
 
   validate(passwordForm.confirmPassword, ({value, valueOf}) => {
-    if (value !== valueOf(passwordForm.password)) {
-      return { mismatch: true };
+    if (value() !== valueOf(passwordForm.password)) {
+      return customError({ kind: 'mismatch' });
     }
     return null;
   });
@@ -81,10 +81,10 @@ export class PasswordFormComponent {
 
   passwordForm = form(this.passwordModel, passwordSchema);
 
-  handleSubmit() {
-    if (this.passwordForm().valid()) {
+  async handleSubmit() {
+    await submit(this.passwordForm, async () => {
       this.submitted.emit(this.passwordForm().value());
-    }
+    });
   }
 }
 ```
@@ -94,7 +94,7 @@ export class PasswordFormComponent {
 This file provides the template for the form, showing how to display errors for both field-level and cross-field validation rules.
 
 ```html
-<form (ngSubmit)="handleSubmit()">
+<form (submit)="handleSubmit(); $event.preventDefault()">
   <div>
     <label>
       Password:
@@ -103,8 +103,10 @@ This file provides the template for the form, showing how to display errors for
     @if (passwordForm.password().errors().length > 0) {
       <div class="errors">
         @for (error of passwordForm.password().errors()) {
-          @if (error.required) { <p>Password is required.</p> }
-          @if (error.minLength) { <p>Password must be at least 8 characters long.</p> }
+          @switch (error.kind) {
+            @case ('required') { <p>Password is required.</p> }
+            @case ('minLength') { <p>Password must be at least 8 characters long.</p> }
+          }
         }
       </div>
     }
@@ -117,7 +119,9 @@ This file provides the template for the form, showing how to display errors for
     @if (passwordForm.confirmPassword().errors().length > 0) {
       <div class="errors">
         @for (error of passwordForm.confirmPassword().errors()) {
-          @if (error.mismatch) { <p>Passwords do not match.</p> }
+          @switch (error.kind) {
+            @case ('mismatch') { <p>Passwords do not match.</p> }
+          }
         }
       </div>
     }
@@ -129,8 +133,8 @@ This file provides the template for the form, showing how to display errors for
 
 ## Usage Notes
 
-- The submit button is disabled based on the form's `valid` signal (`[disabled]="!passwordForm().valid()"`).
-- The `handleSubmit` method checks `this.passwordForm().valid()` as a safeguard before emitting the data.
+- The native `(submit)` event on the `<form>` element is bound to the `handleSubmit` method. It's important to call `$event.preventDefault()` to prevent a full page reload.
+- The `handleSubmit` method uses the `submit()` helper to manage the submission process.
 
 ## How to Use This Example