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

Author: clydin

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

@@ -27,8 +27,7 @@ Use this pattern when a validation rule for one field depends on the state of an
 ## Key Concepts
 
 - **`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.
+- **`submit()`:** An async helper function that manages the form's submission state and should be called from the submit event handler.
 
 ## Example Files
 
@@ -40,7 +39,7 @@ This file defines the component's logic, including a schema that uses `applyWhen
 
 ```typescript
 import { Component, signal, Output, EventEmitter, ChangeDetectionStrategy } from '@angular/core';
-import { form, schema, applyWhen, required } from '@angular/forms/signals';
+import { form, schema, applyWhen, required, submit } from '@angular/forms/signals';
 import { JsonPipe } from '@angular/common';
 
 export interface ContactForm {
@@ -73,10 +72,10 @@ export class ContactFormComponent {
 
   contactForm = form(this.contactModel, contactSchema);
 
-  handleSubmit() {
-    if (this.contactForm().valid()) {
+  async handleSubmit() {
+    await submit(this.contactForm, async () => {
       this.submitted.emit(this.contactForm().value());
-    }
+    });
   }
 }
 ```
@@ -86,7 +85,7 @@ export class ContactFormComponent {
 This file provides the template for the form, which includes a checkbox that controls the validation of another field.
 
 ```html
-<form (ngSubmit)="handleSubmit()">
+<form (submit)="handleSubmit(); $event.preventDefault()">
   <div>
     <label>
       <input type="checkbox" [control]="contactForm.subscribe" />
@@ -112,8 +111,8 @@ This file provides the template for the form, which includes a checkbox that con
 
 ## Usage Notes
 
-- The submit button is disabled based on the form's `valid` signal (`[disabled]="!contactForm().valid()"`).
-- The `handleSubmit` method checks `this.contactForm().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
 

packages/forms/signals/examples/05-dynamic-field-state-hidden.md

@@ -24,7 +24,7 @@ Use this pattern when you need to show or hide a form control based on another c
 ## Key Concepts
 
 - **`hidden()`:** A function used within a schema to define the logic that determines whether a field should be hidden. It takes a `FieldPath` and a predicate function.
-- **Predicate Function:** The function passed to `hidden` that returns `true` when the field should be hidden.
+- **`submit()`:** An async helper function that manages the form's submission state and should be called from the submit event handler.
 - **`@if` block:** Used in the template to conditionally render the form control based on the field's `hidden` signal.
 
 ## Example Files
@@ -37,7 +37,7 @@ This file defines the component's logic, including a schema that uses the `hidde
 
 ```typescript
 import { Component, signal, Output, EventEmitter, ChangeDetectionStrategy } from '@angular/core';
-import { form, schema, hidden, required } from '@angular/forms/signals';
+import { form, schema, hidden, required, submit } from '@angular/forms/signals';
 import { JsonPipe } from '@angular/common';
 
 export interface ContactForm {
@@ -70,10 +70,10 @@ export class ContactFormComponent {
 
   contactForm = form(this.contactModel, contactSchema);
 
-  handleSubmit() {
-    if (this.contactForm().valid()) {
+  async handleSubmit() {
+    await submit(this.contactForm, async () => {
       this.submitted.emit(this.contactForm().value());
-    }
+    });
   }
 }
 ```
@@ -83,7 +83,7 @@ export class ContactFormComponent {
 This file provides the template for the form, using an `@if` block to conditionally render a field based on its `hidden` signal.
 
 ```html
-<form (ngSubmit)="handleSubmit()">
+<form (submit)="handleSubmit(); $event.preventDefault()">
   <div>
     <label>Reason for Contact:</label>
     <select [control]="contactForm.reason">

packages/forms/signals/examples/06-conditionally-disabling-fields.md

@@ -24,7 +24,7 @@ Use this pattern whenever you need to enable or disable a form control based on
 ## Key Concepts
 
 - **`disabled()`:** A function used within a schema to define the logic that determines whether a field should be disabled. It takes a `FieldPath` and a predicate function.
-- **Predicate Function:** The function passed to `disabled` that returns `true` when the field should be disabled.
+- **`submit()`:** An async helper function that manages the form's submission state and should be called from the submit event handler.
 - **`disabled` signal:** A signal on the `FieldState` that reflects the field's disabled status, which can be used for attribute binding in the template.
 
 ## Example Files
@@ -37,7 +37,7 @@ This file defines the component's logic, including a schema that uses the `disab
 
 ```typescript
 import { Component, signal, Output, EventEmitter, ChangeDetectionStrategy } from '@angular/core';
-import { form, schema, disabled, required } from '@angular/forms/signals';
+import { form, schema, disabled, required, submit } from '@angular/forms/signals';
 import { JsonPipe } from '@angular/common';
 
 export interface PromoForm {
@@ -70,10 +70,10 @@ export class PromoFormComponent {
 
   promoForm = form(this.promoModel, promoSchema);
 
-  handleSubmit() {
-    if (this.promoForm().valid()) {
+  async handleSubmit() {
+    await submit(this.promoForm, async () => {
       this.submitted.emit(this.promoForm().value());
-    }
+    });
   }
 }
 ```
@@ -83,7 +83,7 @@ export class PromoFormComponent {
 This file provides the template for the form, binding an input's `disabled` attribute to its corresponding field's `disabled` signal.
 
 ```html
-<form (ngSubmit)="handleSubmit()">
+<form (submit)="handleSubmit(); $event.preventDefault()">
   <div>
     <label>
       <input type="checkbox" [control]="promoForm.hasPromoCode" />

packages/forms/signals/examples/07-dynamic-arrays.md

@@ -26,8 +26,7 @@ Use this pattern when you have a form where the user can add or remove multiple
 ## Key Concepts
 
 - **`applyEach()`:** A function used within a schema to apply a sub-schema to each element of an array field.
-- **`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.
+- **`submit()`:** An async helper function that manages the form's submission state and should be called from the submit event handler.
 
 ## Example Files
 
@@ -39,7 +38,7 @@ This file defines the component's logic, including methods to dynamically add an
 
 ```typescript
 import { Component, signal, Output, EventEmitter, ChangeDetectionStrategy } from '@angular/core';
-import { form, schema, applyEach, validate } from '@angular/forms/signals';
+import { form, schema, applyEach, validate, submit } from '@angular/forms/signals';
 import { JsonPipe } from '@angular/common';
 
 export interface Question {
@@ -53,11 +52,11 @@ export interface SurveyForm {
 }
 
 const questionSchema = schema<Question>((question) => {
-  validate(question.text, ({value}) => (value === '' ? { required: true } : null));
+  validate(question.text, ({value}) => (value() === '' ? { required: true } : null));
 });
 
 const surveySchema = schema<SurveyForm>((survey) => {
-  validate(survey.title, ({value}) => (value === '' ? { required: true } : null));
+  validate(survey.title, ({value}) => (value() === '' ? { required: true } : null));
   applyEach(survey.questions, questionSchema);
 });
 
@@ -81,21 +80,21 @@ export class SurveyFormComponent {
   addQuestion() {
     this.surveyModel.update(survey => {
       survey.questions.push({ text: '', required: false });
-      return survey;
+      return { ...survey };
     });
   }
 
   removeQuestion(index: number) {
     this.surveyModel.update(survey => {
       survey.questions.splice(index, 1);
-      return survey;
+      return { ...survey };
     });
   }
 
-  handleSubmit() {
-    if (this.surveyForm().valid()) {
+  async handleSubmit() {
+    await submit(this.surveyForm, async () => {
       this.submitted.emit(this.surveyForm().value());
-    }
+    });
   }
 }
 ```
@@ -105,7 +104,7 @@ export class SurveyFormComponent {
 This file provides the template for the form, using an `@for` block to render the fields for each question in the array.
 
 ```html
-<form (ngSubmit)="handleSubmit()">
+<form (submit)="handleSubmit(); $event.preventDefault()">
   <div>
     <label>
       Survey Title:

packages/forms/signals/examples/08-custom-form-control.md

@@ -27,7 +27,7 @@ Use this pattern when you have a form input that is more complex than a standard
 
 - **`FormValueControl<T>`:** An interface that custom form control components can implement to integrate with signal forms.
 - **`model()`:** A function from `@angular/core` that creates a two-way bound signal input, used here to implement the `value` property of the `FormValueControl` interface.
-- **`(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
 
@@ -70,7 +70,7 @@ This file defines the parent form component that consumes the custom numeric ste
 
 ```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';
 import { NumericStepperComponent } from './numeric-stepper.component';
 
@@ -96,8 +96,10 @@ export class ProductFormComponent {
 
   productForm = form(this.productModel);
 
-  handleSubmit() {
-    this.submitted.emit(this.productForm().value());
+  async handleSubmit() {
+    await submit(this.productForm, async () => {
+      this.submitted.emit(this.productForm().value());
+    });
   }
 }
 ```
@@ -107,7 +109,7 @@ export class ProductFormComponent {
 This file provides the template for the parent form, showing how the `[control]` directive is used on the custom component.
 
 ```html
-<form (ngSubmit)="handleSubmit()">
+<form (submit)="handleSubmit(); $event.preventDefault()">
   <div>
     <label>
       Product Name:

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

@@ -29,6 +29,7 @@ Use this pattern for validation that requires a network request. The `validateHt
 
 - **`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.
+- **`submit()`:** An async helper function that manages the form's submission state and should be called from the submit event handler.
 
 ## Example Files
 
@@ -40,7 +41,7 @@ This file defines the component's logic, including a schema that uses `validateH
 
 ```typescript
 import { Component, signal, Output, EventEmitter, ChangeDetectionStrategy } from '@angular/core';
-import { form, schema, required, validateHttp } from '@angular/forms/signals';
+import { form, schema, required, validateHttp, submit } from '@angular/forms/signals';
 import { JsonPipe } from '@angular/common';
 
 export interface RegistrationForm {
@@ -71,10 +72,10 @@ export class RegistrationFormComponent {
 
   registrationForm = form(this.registrationModel, registrationSchema);
 
-  handleSubmit() {
-    if (this.registrationForm().valid()) {
+  async handleSubmit() {
+    await submit(this.registrationForm, async () => {
       this.submitted.emit(this.registrationForm().value());
-    }
+    });
   }
 }
 ```
@@ -84,7 +85,7 @@ export class RegistrationFormComponent {
 This file provides the template for the form, showing how to display feedback while the asynchronous validation is pending.
 
 ```html
-<form (ngSubmit)="handleSubmit()">
+<form (submit)="handleSubmit(); $event.preventDefault()">
   <div>
     <label>
       Username:

packages/forms/signals/examples/10-debounced-async-validation.md

@@ -31,7 +31,7 @@ Use this pattern for any asynchronous validation that is tied to user input, suc
 - **`validateAsync()`:** The function used to add an asynchronous validator.
 - **RxJS `Subject` and `switchMap`:** Used to create an observable stream of user input. `switchMap` is crucial for canceling previous pending requests when new input arrives.
 - **RxJS `debounceTime`:** An operator that waits for a specified period of silence in the observable stream before emitting the latest value.
-- **`pending` signal:** A signal on the `FieldState` that is `true` while async validation is running.
+- **`submit()`:** An async helper function that manages the form's submission state and should be called from the submit event handler.
 
 ## Example Files
 
@@ -43,7 +43,7 @@ This file defines the component's logic, using an RxJS `Subject` to debounce use
 
 ```typescript
 import { Component, inject, OnDestroy, signal, Output, EventEmitter, ChangeDetectionStrategy } from '@angular/core';
-import { form, schema, validate, validateAsync } from '@angular/forms/signals';
+import { form, schema, validate, validateAsync, submit } from '@angular/forms/signals';
 import { JsonPipe } from '@angular/common';
 import { UsernameService } from './username.service';
 import { Subject } from 'rxjs';
@@ -78,20 +78,20 @@ export class RegistrationFormComponent implements OnDestroy {
 
   private createSchema() {
     return schema<RegistrationForm>((form) => {
-      validate(form.username, ({value}) => (value === '' ? { required: true } : null));
+      validate(form.username, ({value}) => (value() === '' ? { required: true } : null));
       validateAsync(form.username, async ({value}) => {
-        if (value === '') return null;
-        this.username$.next(value);
+        if (value() === '') return null;
+        this.username$.next(value());
         const isTaken = await firstValueFrom(this.validationResult$);
         return isTaken ? { unique: true } : null;
       });
     });
   }
 
-  handleSubmit() {
-    if (this.registrationForm().valid()) {
+  async handleSubmit() {
+    await submit(this.registrationForm, async () => {
       this.submitted.emit(this.registrationForm().value());
-    }
+    });
   }
 
   ngOnDestroy() {
@@ -106,7 +106,7 @@ export class RegistrationFormComponent implements OnDestroy {
 This file provides the template for the form, showing how to disable the submit button while validation is in progress.
 
 ```html
-<form (ngSubmit)="handleSubmit()">
+<form (submit)="handleSubmit(); $event.preventDefault()">
   <div>
     <label>
       Username:

packages/forms/signals/examples/11-reusable-custom-validators.md

@@ -27,7 +27,7 @@ Use this pattern when you have validation logic that is shared across multiple f
 
 - **Validator Function:** A standalone function that takes configuration (like a minimum length) and returns a validation function that can be used with `validate`.
 - **Factory Pattern:** Using a higher-order function to create and configure your validator, making it highly reusable.
-- **`(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
 
@@ -42,8 +42,8 @@ import { FieldValidator } from '@angular/forms/signals';
 
 export function minLength(minLength: number): FieldValidator<string> {
   return ({value}) => {
-    if (value.length < minLength) {
-      return { minLength: { requiredLength: minLength, actualLength: value.length } };
+    if (value().length < minLength) {
+      return { minLength: { requiredLength: minLength, actualLength: value().length } };
     }
     return null;
   };
@@ -56,7 +56,7 @@ This file defines the component's logic, importing and using the reusable valida
 
 ```typescript
 import { Component, signal, Output, EventEmitter, ChangeDetectionStrategy } from '@angular/core';
-import { form, schema, validate } from '@angular/forms/signals';
+import { form, schema, validate, submit } from '@angular/forms/signals';
 import { JsonPipe } from '@angular/common';
 import { minLength } from './custom-validators';
 
@@ -87,10 +87,10 @@ export class RegistrationFormComponent {
 
   registrationForm = form(this.registrationModel, registrationSchema);
 
-  handleSubmit() {
-    if (this.registrationForm().valid()) {
+  async handleSubmit() {
+    await submit(this.registrationForm, async () => {
       this.submitted.emit(this.registrationForm().value());
-    }
+    });
   }
 }
 ```
@@ -100,7 +100,7 @@ export class RegistrationFormComponent {
 This file provides the template for the form, displaying detailed error messages from the custom validator.
 
 ```html
-<form (ngSubmit)="handleSubmit()">
+<form (submit)="handleSubmit(); $event.preventDefault()">
   <div>
     <label>
       Username: