ngx-vest-forms 1.1.0 → 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
+
+### Why Choose 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;
+```
 
-You can install the package by running:
+## Getting Started
 
-```shell
-npm i ngx-vest-forms
+### Prerequisites
+
+- **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
 ```
 
-### Creating a simple form
+### Quick Start
 
-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`
+Create your first ngx-vest-forms component in 3 simple steps:
 
-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**
+#### 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`.
+
+## 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
 
-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:
+- **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,59 +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.  
+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`. 
+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 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
@@ -520,8 +836,8 @@ const form = {
   // validation happens here
   passwords: {
     password: '',
-    confirmPassword: ''
-  }
+    confirmPassword: '',
+  },
 };
 ```
 
@@ -531,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
@@ -548,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>>({});
 }
 ```
 
@@ -562,14 +881,13 @@ 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 of dependant controls and or groups
 
 Sometimes, form validations are dependent on the values of other form controls or groups.
@@ -578,8 +896,59 @@ A typical example is the `confirmPassword` field, which should only be validated
 When the `password` field value changes, it necessitates re-validating the `confirmPassword` field to ensure
 consistency.
 
-Here's how you can handle validation dependencies with ngx-vest-forms and vest.js:
+#### Understanding the Architecture: Why `validationConfig` Is Needed
+
+Before diving into the implementation, it's important to understand the architectural boundaries between Vest.js and Angular:
+
+**What Vest.js Handles:**
+
+- ✅ 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")
+
+**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);
+});
+```
+
+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.
@@ -589,27 +958,25 @@ Additionally, you need to ensure that both fields match.
 import { enforce, omitWhen, staticSuite, test } from 'vest';
 import { MyFormModel } from '../models/my-form.model';
 
-export const myFormModelSuite = staticSuite((model: MyFormModel, field?: string) => {
-    if (field) {
-        only(field);
-    }
+import { enforce, omitWhen, only, staticSuite, test } from 'vest';
 
     test('password', 'Password is required', () => {
-        enforce(model.password).isNotBlank();
+      enforce(model.password).isNotBlank();
     });
 
     omitWhen(!model.password, () => {
-        test('confirmPassword', 'Confirm password is required', () => {
-            enforce(model.confirmPassword).isNotBlank();
-        });
+      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);
-        });
+      test('passwords', 'Passwords do not match', () => {
+        enforce(model.confirmPassword).equals(model.password);
+      });
     });
-});
+  }
+);
 ```
 
 Creating a validation config.
@@ -620,31 +987,82 @@ 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">
-    <div ngModelGroup="passwords">
-        <label>Password</label>
-        <input type="password" name="password" [ngModel]="formValue().passwords?.password"/>
+```
+
+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>({});
 
-        <label>Confirm Password</label>
-        <input type="password" name="confirmPassword" [ngModel]="formValue().passwords?.confirmPassword"/>
-    </div>
+// 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
 
 Big forms result in big files. It makes sense to split them up.
@@ -665,23 +1083,101 @@ export class AddressComponent {
 }
 ```
 
-# Examples
-to check the examples, clone this repo and run:
-```shell
-npm i
+## 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
 ```
 
-There is an example of a complex form with a lot of conditionals and specifics,
-and there is an example of a form array with complex validations that is used to
-create a form to add business hours. A free tutorial will follow soon.
+### 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
 
-You can check the examples in the github repo [here](https://github.com/simplifiedcourses/ngx-vest-forms/blob/master/projects/examples).
-[Here](https://stackblitz.com/~/github.com/simplifiedcourses/ngx-vest-forms-stackblitz){:target="_blank"} is a stackblitz example for you.
-It's filled with form complexities and also contains form array logic.
+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.