ngx-vest-forms 1.0.3 → 1.2.0

package/README.md

@@ -1,34 +1,95 @@
+<!-- prettier-ignore -->
+<div align="center">
+
+<img src="./course.jpeg" alt="ngx-vest-forms" align="center" height="96" />
+
 # ngx-vest-forms
 
-### Introduction
+[![npm version](https://img.shields.io/npm/v/ngx-vest-forms.svg?style=flat-square)](https://www.npmjs.com/package/ngx-vest-forms)
+[![Build Status](https://img.shields.io/github/actions/workflow/status/ngx-vest-forms/ngx-vest-forms/cd.yml?branch=master&style=flat-square&label=Build)](https://github.com/ngx-vest-forms/ngx-vest-forms/actions/workflows/cd.yml)
+[![Angular](https://img.shields.io/badge/Angular-18+-dd0031?style=flat-square&logo=angular)](https://angular.dev)
+[![TypeScript](https://img.shields.io/badge/TypeScript-blue?style=flat-square&logo=typescript&logoColor=white)](https://www.typescriptlang.org)
+[![License](https://img.shields.io/badge/License-MIT-yellow?style=flat-square)](LICENSE)
 
-This is a very lightweight adapter for Angular template-driven forms and [vestjs](https://vestjs.dev).
-This package gives us the ability to create unidirectional forms without any boilerplate.
-It is meant for complex forms with a high focus on complex validations and conditionals.
+⭐ If you like this project, star it on GitHub — it helps a lot!
 
-All the validations are asynchronous and use [vestjs](https://vestjs.dev) suites that can be re-used
-across different frameworks and technologies.
+[Overview](#overview) • [Getting Started](#getting-started) • [Features](#features) • [Basic Usage](#basic-usage) • [Examples](#examples) • [Resources](#resources) • [Developer Resources](#developer-resources) • [Acknowledgments](#acknowledgments)
 
-### Installation
+</div>
+
+> [!NOTE]
+> **New Maintainer**: I'm [the-ult](https://bsky.app/profile/the-ult.bsky.social), now maintaining this project as Brecht Billiet has moved on to other priorities. Huge thanks to Brecht for creating this amazing library and his foundational work on Angular forms!
+
+A lightweight, type-safe adapter between Angular template-driven forms and [Vest.js](https://vestjs.dev) validation. Build complex forms with unidirectional data flow, sophisticated async validations, and zero boilerplate.
+
+> [!TIP]
+> **For Developers**: This project includes comprehensive instruction files for GitHub Copilot and detailed development guides. See [Developer Resources](#developer-resources) to copy these files to your workspace for enhanced development experience.
+
+## Overview
+
+**ngx-vest-forms** transforms Angular template-driven forms into a powerful, type-safe solution for complex form scenarios. By combining Angular's simplicity with Vest.js's validation power, you get:
+
+- **Unidirectional Data Flow** - Predictable state management with Angular signals
+- **Type Safety** - Full TypeScript support with runtime shape validation
+- **Async Validations** - Built-in support for complex, conditional validations
+- **Zero Boilerplate** - Automatic form control creation and validation wiring
+- **Conditional Logic** - Show/hide fields and validation rules dynamically
+- **Reusable Validations** - Share validation suites across frameworks
 
-You can install the package by running:
+### Why Choose ngx-vest-forms?
 
-```shell
-npm i ngx-vest-forms
+Traditional Angular reactive forms require extensive boilerplate for complex scenarios. Template-driven forms are simpler but lack type safety and advanced validation features. **ngx-vest-forms bridges this gap**, giving you the best of both worlds.
+
+```typescript
+// Before: Complex reactive form setup
+const form = this.fb.group({
+  generalInfo: this.fb.group({
+    firstName: ['', [Validators.required]],
+    lastName: ['', [Validators.required]]
+  })
+});
+
+// After: Simple, type-safe template-driven approach
+protected readonly formValue = signal<MyFormModel>({});
+protected readonly suite = myValidationSuite;
 ```
 
-### Creating a simple form
+## Getting Started
+
+### Prerequisites
 
-Let's start by explaining how to create a simple form.
-I want a form with a form group called `general` info that has 2 properties:
-- `firstName`
-- `lastName`
+- **Angular**: >=18.0.0 (Signals support required)
+- **Vest.js**: >=5.4.6 (Validation engine)
+- **TypeScript**: >=5.8.0 (Modern Angular features)
+- **Node.js**: >=22.0.0 (Required for Angular 18+)
+
+### Installation
+
+```bash
+npm install ngx-vest-forms
+```
 
-We need to import the `vestForms` const in the imports section of the `@Component` decorator.
-Now we can apply the `scVestForm` directive to the `form` tag and listen to the `formValueChange` output to feed our signal.
-In the form we create a form group for `generalInfo`  with the `ngModelGroup` directive.
-And we crate 2 inputs with the `name` attribute and the `[ngModel]` input.
-**Do note that we are not using the banana in the box syntax but only tha square brackets, resulting in a unidirectional dataflow**
+### Quick Start
+
+Create your first ngx-vest-forms component in 3 simple steps:
+
+#### Step 1: Define your form model
+
+```typescript
+import { signal } from '@angular/core';
+import { vestForms, DeepPartial } from 'ngx-vest-forms';
+
+type MyFormModel = DeepPartial<{
+  generalInfo: {
+    firstName: string;
+    lastName: string;
+  };
+}>;
+```
+
+#### Step 2: Set up your component
+
+Use `[ngModel]` (not `[(ngModel)]`) for unidirectional data flow:
 
 ```typescript
 import { vestForms, DeepPartial } from 'ngx-vest-forms';
@@ -38,24 +99,34 @@ type MyFormModel = DeepPartial<{
   generalInfo: {
     firstName: string;
     lastName: string;
-  }
-}>
+  };
+}>;
 
 @Component({
   imports: [vestForms],
   template: `
-<form scVestForm 
+    <form
+      scVestForm
       (formValueChange)="formValue.set($event)"
-      (ngSubmit)="onSubmit()">
+      (ngSubmit)="onSubmit()"
+    >
       <div ngModelGroup="generalInfo">
         <label>First name</label>
-        <input type="text" name="firstName" [ngModel]="formValue().generalInformation?.firstName"/>
-      
+        <input
+          type="text"
+          name="firstName"
+          [ngModel]="formValue().generalInfo?.firstName"
+        />
+
         <label>Last name</label>
-        <input type="text" name="lastName" [ngModel]="formValue().generalInformation?.lastName"/>
+        <input
+          type="text"
+          name="lastName"
+          [ngModel]="formValue().generalInfo?.lastName"
+        />
       </div>
-</form>
-  `
+    </form>
+  `,
 })
 export class MyComponent {
   // This signal will hold the state of our form
@@ -63,22 +134,59 @@ export class MyComponent {
 }
 ```
 
-**Note: Template-driven forms are deep partial, so always use the `?` operator in your templates.**
+#### Step 3: That's it! 🎉
+
+Your form automatically creates FormGroups and FormControls with type-safe, unidirectional data flow.
+
+> [!IMPORTANT]
+> Notice we use `[ngModel]` (not `[(ngModel)]`) for unidirectional data flow, and the `?` operator since template-driven forms are `DeepPartial`.
 
-That's it! This will feed the `formValue` signal and angular will create a form group and 2 form controls for us automatically.
-The object that will be fed in the `formValue` signal will look like this:
+## Features
+
+### Core Features
+
+- **Unidirectional Data Flow** - Predictable state management with Angular signals
+- **Type Safety** - Full TypeScript support with `DeepPartial<T>` and `DeepRequired<T>`
+- **Zero Boilerplate** - Automatic FormControl and FormGroup creation
+- **Shape Validation** - Runtime validation against your TypeScript models (dev mode)
+
+### Advanced Validation
+
+- **Async Validations** - Built-in support with AbortController
+- **Conditional Logic** - Use `omitWhen()` for conditional validation rules
+- **Composable Suites** - Reusable validation functions across projects
+- **Custom Debouncing** - Configure validation timing per field or form
+
+### Dynamic Forms
+
+- **Conditional Fields** - Show/hide fields based on form state
+- **Form Arrays** - Dynamic lists with add/remove functionality
+- **Reactive Disabling** - Disable fields based on computed signals
+- **State Management** - Preserve field state across conditional rendering
+
+### Developer Experience
+
+- **Runtime Shape Checking** - Catch typos in `name` attributes early
+- **Built-in Error Display** - `sc-control-wrapper` component for consistent UX
+- **Validation Config** - Declare field dependencies for complex scenarios
+- **Modern Angular** - Built for Angular 18+ with standalone components
+
+## Basic Usage
+
+The form value will be automatically populated like this:
 
 ```typescript
 formValue = {
   generalInfo: {
     firstName: '',
-    lastName: ''
-  }
-}
+    lastName: '',
+  },
+};
 ```
 
 The ngForm will contain automatically created FormGroups and FormControls.
 This does not have anything to do with this package. It's just Angular:
+
 ```typescript
 form = {
   controls: {
@@ -92,14 +200,14 @@ form = {
 }
 ```
 
-The `scVestForm` directive offers some basic outputs for us though:
+The `scVestForm` directive offers these outputs:
 
-| Output               | Description                                                                                                                             | 
-|----------------------|-----------------------------------------------------------------------------------------------------------------------------------------|
-| formValueChange<T>   | Emits when the form value changes. But debounces<br/> the events since template-driven forms are created by the<br/>framework over time | 
-| dirtyChange<boolean> | Emits when the dirty state of the form changes                                                                                          | 
-| validChange<boolean> | Emits when the form becomes dirty or pristine                                                                                           | 
-| errorsChange         | Emits an entire list of the form and all its form groups and controls                                                                   | 
+| Output            | Description                                                                                     |
+| ----------------- | ----------------------------------------------------------------------------------------------- |
+| `formValueChange` | Emits when the form value changes (debounced since template-driven forms are created over time) |
+| `dirtyChange`     | Emits when the dirty state of the form changes                                                  |
+| `validChange`     | Emits when the form becomes valid or invalid                                                    |
+| `errorsChange`    | Emits the complete list of errors for the form and all its controls                             |
 
 ### Avoiding typo's
 
@@ -114,33 +222,42 @@ type MyFormModel = DeepPartial<{
   generalInfo: {
     firstName: string;
     lastName: string;
-  }
-}>
+  };
+}>;
 
 export const myFormModelShape: DeepRequired<MyFormModel> = {
   generalInfo: {
     firstName: '',
-    lastName: '' 
-  }
+    lastName: '',
+  },
 };
 
 @Component({
   imports: [vestForms],
   template: `
-<form scVestForm 
+    <form
+      scVestForm
       [formShape]="shape"
       (formValueChange)="formValue.set($event)"
-      (ngSubmit)="onSubmit()">
-      
+      (ngSubmit)="onSubmit()"
+    >
       <div ngModelGroup="generalInfo">
         <label>First name</label>
-        <input type="text" name="firstName" [ngModel]="formValue().generalInformation?.firstName"/>
-      
+        <input
+          type="text"
+          name="firstName"
+          [ngModel]="formValue().generalInformation?.firstName"
+        />
+
         <label>Last name</label>
-        <input type="text" name="lastName" [ngModel]="formValue().generalInformation?.lastName"/>
+        <input
+          type="text"
+          name="lastName"
+          [ngModel]="formValue().generalInformation?.lastName"
+        />
       </div>
-</form>
-  `
+    </form>
+  `,
 })
 export class MyComponent {
   protected readonly formValue = signal<MyFormModel>({});
@@ -179,7 +296,7 @@ Error: Shape mismatch:
 
 ### Conditional fields
 
-What if we want to remove a form control or form group? With reactive forms that would require a lot of work 
+What if we want to remove a form control or form group? With reactive forms that would require a lot of work
 but since Template driven forms do all the hard work for us, we can simply create a computed signal for that and
 bind that in the template. Having logic in the template is considered a bad practice, so we can do all
 the calculations in our class.
@@ -189,11 +306,19 @@ Let's hide `lastName` if `firstName` is not filled in:
 ```html
 <div ngModelGroup="generalInfo">
   <label>First name</label>
-  <input type="text" name="firstName" [ngModel]="formValue().generalInformation?.firstName"/>
-  
+  <input
+    type="text"
+    name="firstName"
+    [ngModel]="formValue().generalInformation?.firstName"
+  />
+
   @if(lastNameAvailable()){
-    <label>Last name</label>
-    <input type="text" name="lastName" [ngModel]="formValue().generalInformation?.lastName"/>
+  <label>Last name</label>
+  <input
+    type="text"
+    name="lastName"
+    [ngModel]="formValue().generalInformation?.lastName"
+  />
   }
 </div>
 ```
@@ -201,8 +326,8 @@ Let's hide `lastName` if `firstName` is not filled in:
 ```typescript
 class MyComponent {
   ...
-  protected readonly lastNameAvailable = 
-    computed(() => !!this.formValue().generalInformation?.firstName);
+  protected readonly lastNameAvailable =
+    computed(() => !!this.formValue().generalInfo?.firstName);
 }
 ```
 
@@ -211,13 +336,21 @@ This also works for a form group:
 
 ```html
 @if(showGeneralInfo()){
-  <div ngModelGroup="generalInfo">
-    <label>First name</label>
-    <input type="text" name="firstName" [ngModel]="formValue().generalInformation?.firstName"/>
-    
-    <label>Last name</label>
-    <input type="text" name="lastName" [ngModel]="formValue().generalInformation?.lastName"/>
-  </div>
+<div ngModelGroup="generalInfo">
+  <label>First name</label>
+  <input
+    type="text"
+    name="firstName"
+    [ngModel]="formValue().generalInformation?.firstName"
+  />
+
+  <label>Last name</label>
+  <input
+    type="text"
+    name="lastName"
+    [ngModel]="formValue().generalInformation?.lastName"
+  />
+</div>
 }
 ```
 
@@ -227,18 +360,150 @@ To achieve reactive disabling, we just have to take advantage of computed signal
 
 ```typescript
 class MyComponent {
-  protected readonly lastNameDisabled = 
-    computed(() => !this.formValue().generalInformation?.firstName);
+  protected readonly lastNameDisabled = computed(
+    () => !this.formValue().generalInfo?.firstName
+  );
 }
 ```
 
 We can bind the computed signal to the `disabled` directive of Angular.
+
 ```html
-<input type="text" name="lastName" 
-       [disabled]="lastNameDisabled()" 
-       [ngModel]="formValue().generalInformation?.lastName"/>
+<input
+  type="text"
+  name="lastName"
+  [disabled]="lastNameDisabled()"
+  [ngModel]="formValue().generalInformation?.lastName"
+/>
+```
+
+## Examples
+
+### Simple Form with Validation
+
+Here's a complete example showing form setup, validation, and error display:
+
+```typescript
+import { Component, signal } from '@angular/core';
+import { staticSuite, test, enforce } from 'vest';
+import { vestForms, DeepPartial, DeepRequired } from 'ngx-vest-forms';
+
+// 1. Define your form model
+type UserFormModel = DeepPartial<{
+  firstName: string;
+  lastName: string;
+  email: string;
+}>;
+
+// 2. Create a shape for runtime validation (recommended)
+const userFormShape: DeepRequired<UserFormModel> = {
+  firstName: '',
+  lastName: '',
+  email: '',
+};
+
+// 3. Create a Vest validation suite
+const userValidationSuite = staticSuite(
+  (model: UserFormModel, field?: string) => {
+    if (field) {
+      only(field); // Critical for performance - only validate the active field
+    }
+
+    test('firstName', 'First name is required', () => {
+      enforce(model.firstName).isNotBlank();
+    });
+
+    test('lastName', 'Last name is required', () => {
+      enforce(model.lastName).isNotBlank();
+    });
+
+    test('email', 'Valid email is required', () => {
+      enforce(model.email).isEmail();
+    });
+  }
+);
+
+@Component({
+  selector: 'app-user-form',
+  imports: [vestForms],
+  template: `
+    <form
+      scVestForm
+      [suite]="suite"
+      [formShape]="shape"
+      (formValueChange)="formValue.set($event)"
+      (ngSubmit)="onSubmit()"
+    >
+      <div sc-control-wrapper>
+        <label>First Name</label>
+        <input [ngModel]="formValue().firstName" name="firstName" />
+      </div>
+
+      <div sc-control-wrapper>
+        <label>Last Name</label>
+        <input [ngModel]="formValue().lastName" name="lastName" />
+      </div>
+
+      <div sc-control-wrapper>
+        <label>Email</label>
+        <input [ngModel]="formValue().email" name="email" type="email" />
+      </div>
+
+      <button type="submit">Submit</button>
+    </form>
+  `,
+})
+export class UserFormComponent {
+  protected readonly formValue = signal<UserFormModel>({});
+  protected readonly suite = userValidationSuite;
+  protected readonly shape = userFormShape;
+
+  protected onSubmit() {
+    console.log('Form submitted:', this.formValue());
+  }
+}
+```
+
+### Conditional Fields Example
+
+```typescript
+@Component({
+  template: `
+    <form scVestForm [suite]="suite" (formValueChange)="formValue.set($event)">
+      <!-- Age field -->
+      <div sc-control-wrapper>
+        <label>Age</label>
+        <input [ngModel]="formValue().age" name="age" type="number" />
+      </div>
+
+      <!-- Emergency contact - only required if under 18 -->
+      @if (emergencyContactRequired()) {
+        <div sc-control-wrapper>
+          <label>Emergency Contact</label>
+          <input
+            [ngModel]="formValue().emergencyContact"
+            name="emergencyContact"
+          />
+        </div>
+      }
+    </form>
+  `,
+})
+export class ConditionalFormComponent {
+  protected readonly formValue = signal<ConditionalFormModel>({});
+
+  // Computed signal for conditional logic
+  protected readonly emergencyContactRequired = computed(
+    () => (this.formValue().age || 0) < 18
+  );
+}
 ```
 
+### Live Examples
+
+- **[Purchase Form Demo](https://github.com/ngx-vest-forms/ngx-vest-forms/tree/master/projects/examples/src/app/components/smart/purchase-form)** - Complex form with nested objects, validation dependencies, and conditional logic
+- **[Business Hours Demo](https://github.com/ngx-vest-forms/ngx-vest-forms/tree/master/projects/examples/src/app/components/smart/business-hours-form)** - Dynamic form arrays with complex validation rules
+
 ### Validations
 
 The absolute gem in ngx-vest-forms is the flexibility in validations without writing any boilerplate.
@@ -247,13 +512,50 @@ You can use it on the backend/frontend/Angular/react etc...
 
 We use vest because it introduces the concept of vest suites. These are suites that kind of look like unit-tests
 but that are highly flexible:
-* [X] Write validations on forms
-* [X] Write validations on form groups
-* [X] Write validations on form controls
-* [X] Composable/reuse-able different validation suites
-* [X] Write conditional validations
+
+- [x] Write validations on forms
+- [x] Write validations on form groups
+- [x] Write validations on form controls
+- [x] Composable/reuse-able different validation suites
+- [x] Write conditional validations
+
+### Validation Performance with `only()`
+
+ngx-vest-forms automatically optimizes validation performance by running validations only for the field being interacted with. This is achieved through Vest's `only()` function:
+
+```typescript
+import { enforce, only, staticSuite, test } from 'vest';
+
+export const myFormModelSuite = staticSuite(
+  (model: MyFormModel, field?: string) => {
+    if (field) {
+      only(field); // Only validate the specific field during user interaction
+    }
+    // When field is undefined (e.g., on submit), all validations run
+
+    test('firstName', 'First name is required', () => {
+      enforce(model.firstName).isNotBlank();
+    });
+    test('lastName', 'Last name is required', () => {
+      enforce(model.lastName).isNotBlank();
+    });
+  }
+);
+```
+
+This pattern ensures:
+
+- ✅ During typing/blur: Only the current field validates (better performance)
+- ✅ On form submit: All fields validate (complete validation)
+- ✅ Untouched fields don't show errors prematurely (better UX)
+
+> [!IMPORTANT]
+> Always include the optional `field?: string` parameter in your suite and use the `only(field)` pattern. The library automatically passes the field name during individual field validation.
+
+### Basic Validation Suite
 
 This is how you write a simple Vest suite:
+
 ```typescript
 import { enforce, only, staticSuite, test } from 'vest';
 import { MyFormModel } from '../models/my-form.model'
@@ -291,21 +593,23 @@ class MyComponent {
 ```
 
 ```html
-
-<form scVestForm
-      [formShape]="shape"
-      [formValue]="formValue"
-      [suite]="suite"
-      (formValueChange)="formValue.set($event)"
-      (ngSubmit)="onSubmit()">
+<form
+  scVestForm
+  [formShape]="shape"
+  [formValue]="formValue"
+  [suite]="suite"
+  (formValueChange)="formValue.set($event)"
+  (ngSubmit)="onSubmit()"
+>
   ...
 </form>
 ```
 
-That's it. Validations are completely wired now. Because ngx-vest-forms will hook into the 
+That's it. Validations are completely wired now. Because ngx-vest-forms will hook into the
 `[ngModel]` and `ngModelGroup` attributes, and create ngValidators automatically.
 
-It goes like this: 
+It goes like this:
+
 - Control gets created, Angular recognizes the `ngModel` and `ngModelGroup` directives
 - These directives implement `AsyncValidator` and will connect to a vest suite
 - User types into control
@@ -314,7 +618,7 @@ It goes like this:
 - Vest returns the errors
 - @simpilfied/forms puts those errors on the angular form control
 
-This means that `valid`, `invalid`, `errors`,  `statusChanges` etc will keep on working
+This means that `valid`, `invalid`, `errors`, `statusChanges` etc will keep on working
 just like it would with a regular angular form.
 
 #### Showing validation errors
@@ -323,10 +627,12 @@ Now we want to show the validation errors in a consistent way.
 For that we have provided the `sc-control-wrapper` attribute component.
 
 You can use it on:
+
 - elements that hold `ngModelGroup`
 - elements that have an `ngModel` (or form control) inside of them.
 
 This will show errors automatically on:
+
 - form submit
 - blur
 
@@ -351,12 +657,13 @@ Let's update our form:
 ```
 
 This is the only thing we need to do to create a form that is completely wired with vest.
-* [x] Automatic creation of form controls and form groups
-* [x] Automatic connection to vest suites
-* [x] Automatic typo validation
-* [x] Automatic adding of css error classes and showing validation messages
-  * [x] On blur
-  * [x] On submit
+
+- [x] Automatic creation of form controls and form groups
+- [x] Automatic connection to vest suites
+- [x] Automatic typo validation
+- [x] Automatic adding of css error classes and showing validation messages
+  - [x] On blur
+  - [x] On submit
 
 ### Conditional validations
 
@@ -381,9 +688,9 @@ omitWhen((model.age || 0) >= 18, () => {
 You can put those validations on every field that you want. On form group fields and on form control fields.
 Check this interesting example below:
 
-* [x] Password is always required
-* [x] Confirm password is only required when there is a password
-* [x] The passwords should match, but only when they are both filled in
+- [x] Password is always required
+- [x] Confirm password is only required when there is a password
+- [x] The passwords should match, but only when they are both filled in
 
 ```typescript
 test('passwords.password', 'Password is not filled in', () => {
@@ -394,11 +701,16 @@ omitWhen(!model.passwords?.password, () => {
     enforce(model.passwords?.confirmPassword).isNotBlank();
   });
 });
-omitWhen(!model.passwords?.password || !model.passwords?.confirmPassword, () => {
-  test('passwords', 'Passwords do not match', () => {
-    enforce(model.passwords?.confirmPassword).equals(model.passwords?.password);
-  });
-});
+omitWhen(
+  !model.passwords?.password || !model.passwords?.confirmPassword,
+  () => {
+    test('passwords', 'Passwords do not match', () => {
+      enforce(model.passwords?.confirmPassword).equals(
+        model.passwords?.password
+      );
+    });
+  }
+);
 ```
 
 Forget about manually adding, removing validators on reactive forms and not being able to
@@ -414,7 +726,10 @@ This is quite straightforward with Vest.
 Let's take this simple function that validates an address:
 
 ```typescript
-export function addressValidations(model: AddressModel | undefined, field: string): void {
+export function addressValidations(
+  model: AddressModel | undefined,
+  field: string
+): void {
   test(`${field}.street`, 'Street is required', () => {
     enforce(model?.street).isNotBlank();
   });
@@ -444,8 +759,14 @@ export const mySuite = staticSuite(
     if (field) {
       only(field);
     }
-    addressValidations(model.addresses?.billingAddress, 'addresses.billingAddress');
-    addressValidations(model.addresses?.shippingAddress, 'addresses.shippingAddress');
+    addressValidations(
+      model.addresses?.billingAddress,
+      'addresses.billingAddress'
+    );
+    addressValidations(
+      model.addresses?.shippingAddress,
+      'addresses.shippingAddress'
+    );
   }
 );
 ```
@@ -460,36 +781,54 @@ Checkbox is checked. But if it is checked, all fields are required.
 And if both addresses are filled in, they should be different.
 
 This gives us validation on:
-* [x] The addresses form field (they can't be equal)
-* [x] The shipping Address field (only required when checkbox is checked)
-* [x] validation on all the address fields (street, number, etc) on both addresses
+
+- [x] The addresses form field (they can't be equal)
+- [x] The shipping Address field (only required when checkbox is checked)
+- [x] validation on all the address fields (street, number, etc) on both addresses
 
 ```typescript
-addressValidations(
-  model.addresses?.billingAddress,
-  'addresses.billingAddress'
-);
-omitWhen(
-  !model.addresses?.shippingAddressDifferentFromBillingAddress,
-  () => {
-    addressValidations(
-      model.addresses?.shippingAddress,
-      'addresses.shippingAddress'
+addressValidations(model.addresses?.billingAddress, 'addresses.billingAddress');
+omitWhen(!model.addresses?.shippingAddressDifferentFromBillingAddress, () => {
+  addressValidations(
+    model.addresses?.shippingAddress,
+    'addresses.shippingAddress'
+  );
+  test('addresses', 'The addresses appear to be the same', () => {
+    enforce(JSON.stringify(model.addresses?.billingAddress)).notEquals(
+      JSON.stringify(model.addresses?.shippingAddress)
     );
-    test('addresses', 'The addresses appear to be the same', () => {
-      enforce(JSON.stringify(model.addresses?.billingAddress)).notEquals(
-        JSON.stringify(model.addresses?.shippingAddress)
-      );
-    });
-  }
-);
+  });
+});
+```
+
+### Validation options
+
+The validation is triggered immediately when the input on the formModel changes.
+In some cases you want to debounce the input (e.g. if you make an api call in the validation suite).
+
+You can configure additional `validationOptions` at various levels like `form`, `ngModelGroup` or `ngModel`.
+
+```html
+<form scVestForm ... [validationOptions]="{ debounceTime: 0 }">
+  ...
+  <div sc-control-wrapper>
+    <label>UserId</label>
+    <input
+      type="text"
+      name="userId"
+      [ngModel]="formValue().userId"
+      [validationOptions]="{ debounceTime: 300 }"
+    />
+  </div>
+  ...
+</form>
 ```
 
 ### Validations on the root form
 
 When we want to validate multiple fields that are depending on each other,
 it is a best practice to wrap them in a parent form group.
-If `password`  and `confirmPassword` have to be equal the validation should not happen on
+If `password` and `confirmPassword` have to be equal the validation should not happen on
 `password` nor on `confirmPassword`, it should happen on `passwords`:
 
 ```typescript
@@ -497,8 +836,8 @@ const form = {
   // validation happens here
   passwords: {
     password: '',
-    confirmPassword: ''
-  }
+    confirmPassword: '',
+  },
 };
 ```
 
@@ -508,16 +847,19 @@ Use the `errorsChange` output to keep the errors as state in a signal that we ca
 wherever we want.
 
 ```html
-{{ errors()?.['rootForm'] }} <!-- render the errors on the rootForm -->
-{{ errors() }} <!-- render all the errors -->
-<form scVestForm 
-      [formValue]="formValue()"
-      [validateRootForm]="true"
-      [formShape]="shape"
-      [suite]="suite"
-      (errorsChange)="errors.set($event)"
-      ...>
-</form>
+{{ errors()?.['rootForm'] }}
+<!-- render the errors on the rootForm -->
+{{ errors() }}
+<!-- render all the errors -->
+<form
+  scVestForm
+  [formValue]="formValue()"
+  [validateRootForm]="true"
+  [formShape]="shape"
+  [suite]="suite"
+  (errorsChange)="errors.set($event)"
+  ...
+></form>
 ```
 
 ```typescript
@@ -525,7 +867,7 @@ export class MyformComponent {
   protected readonly formValue = signal<MyFormModel>({});
   protected readonly suite = myFormModelSuite;
   // Keep the errors in state
-  protected readonly errors = signal<Record<string, string>>({ });
+  protected readonly errors = signal<Record<string, string>>({});
 }
 ```
 
@@ -539,29 +881,187 @@ import { ROOT_FORM } from 'ngx-vest-forms';
 
 test(ROOT_FORM, 'Brecht is not 30 anymore', () => {
   enforce(
-    model.firstName === 'Brecht' && 
-    model.lastName === 'Billiet' && 
-    model.age === 30).isFalsy();
+    model.firstName === 'Brecht' &&
+      model.lastName === 'Billiet' &&
+      model.age === 30
+  ).isFalsy();
 });
 ```
 
-### Validation dependencies
+### Validation of dependant controls and or groups
 
-Sometimes we need to re-trigger validations of form controls or form groups because they are dependant on other form controls or form groups.
-For instance: A `confirmPassword` field is not required unless the `password` is filled in. Which means that when the `password` field gets a new value,
-we need to run the validations on `confirmPassword`.
+Sometimes, form validations are dependent on the values of other form controls or groups.
+This scenario is common when a field's validity relies on the input of another field.
+A typical example is the `confirmPassword` field, which should only be validated if the `password` field is filled in.
+When the `password` field value changes, it necessitates re-validating the `confirmPassword` field to ensure
+consistency.
 
+#### Understanding the Architecture: Why `validationConfig` Is Needed
 
-### Form arrays
+Before diving into the implementation, it's important to understand the architectural boundaries between Vest.js and Angular:
 
-Todo
+**What Vest.js Handles:**
 
-#### Form array validations
+- ✅ Validation logic and rules
+- ✅ Conditional validation with `omitWhen()`, `skipWhen()`
+- ✅ Field-level optimization with `only()`
+- ✅ Async validations with AbortController
+- ✅ Cross-field validation logic (e.g., "passwords must match")
 
-An example can be found [in this simplified courses article](https://blog.simplified.courses/template-driven-forms-with-form-arrays/)
+**What Vest.js Cannot Do:**
+
+- ❌ Trigger Angular to revalidate a different form control
+- ❌ Control Angular's form control lifecycle
+- ❌ Tell Angular "when field X changes, also validate field Y"
+
+**Angular's Limitation:**
+Angular template-driven forms do not natively know about cross-field dependencies. When a field changes, only its own validators run automatically.
+
+**How `validationConfig` Bridges This Gap:**
+
+The `validationConfig` tells Angular's form system: "when field X changes, also call `updateValueAndValidity()` on field Y". This ensures that:
+
+- Cross-field validations run at the right time
+- UI error states update correctly
+- Form validation state remains consistent
+
+**Example of the Problem:**
+
+```typescript
+// In your Vest suite
+test('confirmPassword', 'Passwords must match', () => {
+  enforce(model.confirmPassword).equals(model.password);
+});
+```
 
-We can look in `projects/examples/src/app/validations/phonenumber.validations.ts` to see an example on the validations part.
+Without `validationConfig`: If user changes `password`, the `confirmPassword` field won't be revalidated automatically, even though its validity depends on the password value.
 
+With `validationConfig`: Angular knows to revalidate `confirmPassword` whenever `password` changes.
+
+**Architectural Benefits of This Separation:**
+
+This separation of concerns provides several advantages:
+
+- **Clarity**: Vest.js focuses on validation logic, `validationConfig` handles Angular orchestration
+- **Reusability**: Vest suites work across frameworks, while `validationConfig` is Angular-specific
+- **Maintainability**: Changes to validation logic don't affect dependency management
+- **Performance**: Only necessary validations run, only necessary controls revalidate
+- **Testability**: Validation logic can be tested independently from Angular form behavior
+
+Here's how you can handle validation dependencies with ngx-vest-forms and vest.js:
+
+Use Vest to create a suite where you define the conditional validations.
+For example, the `confirmPassword` field should only be validated when the `password` field is not empty.
+Additionally, you need to ensure that both fields match.
+
+```typescript
+import { enforce, omitWhen, staticSuite, test } from 'vest';
+import { MyFormModel } from '../models/my-form.model';
+
+import { enforce, omitWhen, only, staticSuite, test } from 'vest';
+
+    test('password', 'Password is required', () => {
+      enforce(model.password).isNotBlank();
+    });
+
+    omitWhen(!model.password, () => {
+      test('confirmPassword', 'Confirm password is required', () => {
+        enforce(model.confirmPassword).isNotBlank();
+      });
+    });
+
+    omitWhen(!model.password || !model.confirmPassword, () => {
+      test('passwords', 'Passwords do not match', () => {
+        enforce(model.confirmPassword).equals(model.password);
+      });
+    });
+  }
+);
+```
+
+Creating a validation config.
+The `scVestForm` has an input called `validationConfig`, that we can use to let the system know when to retrigger validations.
+
+```typescript
+protected validationConfig = {
+    password: ['passwords.confirmPassword']
+}
+```
+
+Here we see that when password changes, it needs to update the field `passwords.confirmPassword`.
+This validationConfig is completely dynamic, and can also be used for form arrays.
+
+```html
+<form scVestForm ... [validationConfig]="validationConfig">
+  <div ngModelGroup="passwords">
+    <label>Password</label>
+    <input
+      type="password"
+      name="password"
+      [ngModel]="formValue().passwords?.password"
+    />
+
+    <label>Confirm Password</label>
+    <input
+      type="password"
+      name="confirmPassword"
+      [ngModel]="formValue().passwords?.confirmPassword"
+    />
+  </div>
+</form>
+```
+
+#### Advanced State Management Patterns
+
+The `validationConfig` works seamlessly with different state management approaches. By default, most examples show using a single signal for both input and output:
+
+```typescript
+// Standard pattern: single signal for both input and output
+protected readonly formValue = signal<MyFormModel>({});
+
+// Template
+<form scVestForm
+      [formValue]="formValue()"
+      (formValueChange)="formValue.set($event)"
+      [validationConfig]="validationConfig">
+```
+
+However, you can also use **separate signals** for input and output if your application architecture requires it:
+
+```typescript
+// Advanced pattern: separate input and output signals
+protected readonly inputFormValue = signal<MyFormModel>({});
+protected readonly outputFormValue = signal<MyFormModel>({});
+
+// Template
+<form scVestForm
+      [formValue]="inputFormValue()"
+      (formValueChange)="handleFormChange($event)"
+      [validationConfig]="validationConfig">
+  <input name="password" [ngModel]="outputFormValue().password" />
+  <input name="confirmPassword" [ngModel]="outputFormValue().confirmPassword" />
+</form>
+
+// Component
+handleFormChange(value: MyFormModel) {
+  // Update output signal independently
+  this.outputFormValue.set(value);
+  // Optionally sync input signal or perform other logic
+}
+```
+
+**Why this works**: The validation configuration operates at the **form control level**, listening directly to Angular's form control changes rather than component signals. This makes it independent of your chosen state management pattern.
+
+This pattern is useful when:
+
+- You need different processing logic for form inputs vs outputs
+- You're integrating with state management libraries
+- You want to maintain separate concerns between form display and form handling
+
+#### Form array validations
+
+An example can be found [in this simplified courses article](https://blog.simplified.courses/template-driven-forms-with-form-arrays/)
+There is also a complex example of form arrays with complex validations in the examples.
 
 ### Child form components
 
@@ -583,9 +1083,101 @@ export class AddressComponent {
 }
 ```
 
-You can check the examples in the github repo [here](https://github.com/simplifiedcourses/ngx-vest-forms/blob/master/projects/examples).
+## Resources
+
+### Documentation & Tutorials
+
+- **[Angular Official Documentation](https://angular.dev/guide/forms)** - Template-driven forms guide
+- **[Vest.js Documentation](https://vestjs.dev)** - Validation framework used by ngx-vest-forms
+- **[Live Examples Repository](https://github.com/ngx-vest-forms/ngx-vest-forms/tree/master/projects/examples)** - Complex form examples and patterns
+- **[Interactive Stackblitz Demo](https://stackblitz.com/~/github.com/simplifiedcourses/ngx-vest-forms-stackblitz)** - Try it in your browser
+
+### Running Examples Locally
+
+Clone this repo and run the examples:
+
+```bash
+npm install
+npm start
+```
+
+### Learning Resources
+
+[![Angular Forms Course](course.jpeg)](https://www.simplified.courses/complex-angular-template-driven-forms)
+
+**[Complex Angular Template-Driven Forms Course](https://www.simplified.courses/complex-angular-template-driven-forms)** - Master advanced form patterns and become a form expert.
+
+### Founding Articles by Brecht Billiet
+
+This library was originally created by [Brecht Billiet](https://twitter.com/brechtbilliet). Here are his foundational blog posts that inspired and guided the development:
+
+- **[Introducing ngx-vest-forms](https://blog.simplified.courses/introducing-ngx-vest-forms/)** - The original introduction and motivation
+- **[Making Angular Template-Driven Forms Type-Safe](https://blog.simplified.courses/making-angular-template-driven-forms-typesafe/)** - Deep dive into type safety
+- **[Asynchronous Form Validators in Angular with Vest](https://blog.simplified.courses/asynchronous-form-validators-in-angular-with-vest/)** - Advanced async validation patterns
+- **[Template-Driven Forms with Form Arrays](https://blog.simplified.courses/template-driven-forms-with-form-arrays/)** - Dynamic form arrays implementation
+
+### Community & Support
+
+- **[GitHub Issues](https://github.com/ngx-vest-forms/ngx-vest-forms/issues)** - Report bugs or request features
+- **[GitHub Discussions](https://github.com/ngx-vest-forms/ngx-vest-forms/discussions)** - Ask questions and share ideas
+- **[npm Package](https://www.npmjs.com/package/ngx-vest-forms)** - Official package page
+
+## Developer Resources
+
+### Comprehensive Instruction Files
+
+This project includes detailed instruction files designed to help developers master ngx-vest-forms and Vest.js patterns:
+
+- **[`.github/instructions/ngx-vest-forms.instructions.md`](.github/instructions/ngx-vest-forms.instructions.md)** - Complete guide for using ngx-vest-forms library
+- **[`.github/instructions/vest.instructions.md`](.github/instructions/vest.instructions.md)** - Comprehensive Vest.js validation patterns and best practices
+- **[`.github/copilot-instructions.md`](.github/copilot-instructions.md)** - Main GitHub Copilot instructions for this workspace
+
+### Using Instruction Files in Your Workspace
+
+For the best development experience with ngx-vest-forms, **copy these instruction files to your own project's `.github/` directory**:
+
+```bash
+# Create the directories in your project
+mkdir -p .github/instructions
+
+# Copy the instruction files
+curl -o .github/instructions/ngx-vest-forms.instructions.md \
+  https://raw.githubusercontent.com/ngx-vest-forms/ngx-vest-forms/main/.github/instructions/ngx-vest-forms.instructions.md
+
+curl -o .github/instructions/vest.instructions.md \
+  https://raw.githubusercontent.com/ngx-vest-forms/ngx-vest-forms/main/.github/instructions/vest.instructions.md
+
+# Optionally, adapt the main copilot instructions for your project
+curl -o .github/copilot-instructions.md \
+  https://raw.githubusercontent.com/ngx-vest-forms/ngx-vest-forms/main/.github/copilot-instructions.md
+```
+
+**Benefits of copying instruction files:**
+
+- **GitHub Copilot Integration** - Enhanced code generation aligned with best practices
+- **Comprehensive Documentation** - Complete patterns and examples at your fingertips
+- **Consistent Code Quality** - Maintain validation patterns and architectural standards
+- **Faster Development** - Quick reference for complex scenarios and optimizations
+
+## Acknowledgments
+
+🙏 **Special thanks to [Brecht Billiet](https://twitter.com/brechtbilliet)** for creating the original version of this library and his pioneering work on Angular forms. His vision and expertise laid the foundation for what ngx-vest-forms has become today.
+
+### Core Contributors & Inspirations
+
+**[Evyatar Alush](https://twitter.com/evyataral)** - Creator of [Vest.js](https://vestjs.dev/)
+
+- 🎯 **The validation engine** that powers ngx-vest-forms
+- 🎙️ **Featured on PodRocket**: [Vest with Evyatar Alush](https://dev.to/podrocket/vest-with-evyatar-alush) - Deep dive into the philosophy and architecture of Vest.js
+
+**[Ward Bell](https://twitter.com/wardbell)** - Template-Driven Forms Advocate
+
+- 📢 **Evangelized Template-Driven Forms**: [Prefer Template-Driven Forms](https://devconf.net/talk/prefer-template-driven-forms-ward-bell-ng-conf-2021) (ng-conf 2021)
+- 🎥 **Original Vest.js + Angular Integration**: [Form validation done right](https://www.youtube.com/watch?v=EMUAtQlh9Ko) - The foundational talk that inspired this approach
+- 💻 **Early Implementation**: [ngc-validate](https://github.com/wardbell/ngc-validate) - The initial version of template-driven forms with Vest.js
+
+These pioneers laid the groundwork that made ngx-vest-forms possible, combining the power of declarative validation with the elegance of Angular's template-driven approach.
 
-## Want to learn more?
-[![course.jpeg](course.jpeg)](https://www.simplified.courses/complex-angular-template-driven-forms)
+## License
 
-[This course](https://www.simplified.courses/complex-angular-template-driven-forms) teaches you to become a form expert in no time.
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.