ngx-vest-forms 2.0.0-beta.1 → 2.0.0-beta.3

package/README.md

@@ -1,113 +1,43 @@
 <!-- prettier-ignore -->
 <div align="center">
 
-<img src="./course.jpeg" alt="ngx-vest-forms" align="center" height="96" />
-
 # ngx-vest-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 minimal boilerplate.
+
 [![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)
+[![Angular](<https://img.shields.io/badge/Angular-19+%20(min)%20%E2%80%94%2020%20recommended-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)
 
 ⭐ If you like this project, star it on GitHub — it helps a lot!
 
-[Overview](#overview) • [Getting Started](#getting-started) • [Complete Example](#complete-example) • [Core Concepts](#core-concepts) • [Validation](#validation) • [Intermediate Topics](#intermediate-topics) • [Advanced Topics](#advanced-topics) • [Features](#features) • [Documentation](#documentation) • [Resources](#resources) • [Developer Resources](#developer-resources) • [Acknowledgments](#acknowledgments)
+[Quick Start](#installation--quick-start) • [Docs](#documentation) • [Key Features](#key-features) • [Migration](#migration) • [FAQ](#faq) • [Resources](#resources)
 
 </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!
-
-> [!TIP]
-> **What's New**: Major improvements in the latest release! See **[Release Notes](./docs/PR-60-CHANGES.md)** for complete details.
->
-> - ✅ **Critical Fix**: Validation timing with `omitWhen` + `validationConfig`
-> - ✅ **New Types**: `NgxDeepPartial`, `NgxDeepRequired`, `NgxVestSuite` (cleaner API)
-> - ✅ **Array Utilities**: Convert arrays to/from objects for template-driven forms
-> - ✅ **Field Path Helpers**: Parse and stringify field paths for Standard Schema
-
-> [!WARNING]
-> **Breaking Change**: You must now call `only()` **unconditionally** in validation suites.
->
-> **Migration**: Remove `if (field)` wrapper around `only()` calls:
+> **New Maintainer**:
 >
-> ```typescript
-> // ❌ OLD (will break)
-> if (field) {
->   only(field);
-> }
->
-> // ✅ NEW (required)
-> only(field); // Safe: only(undefined) runs all tests
-> ```
->
-> **Why**: Conditional `only()` calls corrupt Vest's execution tracking, breaking `omitWhen` + `validationConfig`.
->
-> **See**: [Performance Optimization with `only()`](#performance-optimization-with-only) section and [Migration Guide](./docs/PR-60-CHANGES.md#migration-guide) for complete details.
-
-> [!NOTE]
-> **Selector Prefix Update**: We now recommend using the `ngx-` prefix for all selectors. The legacy `sc-` prefix is **deprecated** and will be removed in v3.0.0.
->
-> - ✅ **Recommended**: `<ngx-control-wrapper>`, `ngxVestForm`, `ngxValidateRootForm`
-> - ⚠️ **Deprecated**: `<sc-control-wrapper>`, `scVestForm`, `validateRootForm`
->
-> Both prefixes work in v2.0+, allowing gradual migration. See [Dual Selector Support](./docs/dev/DUAL-SELECTOR-SUPPORT.md) for complete migration guide.
-
-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.
+> 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!
 
-## Overview
+## Why ngx-vest-forms?
 
-**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 state with Angular signals
+- Type-safe template-driven forms with runtime shape validation (dev only)
+- Powerful Vest.js validations (sync/async, conditional, composable)
+- Minimal boilerplate: controls and validation wiring are automatic
 
-- **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
+See the full guides under [Documentation](#documentation).
 
-### 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;
-```
-
-## Getting Started
+## Installation & Quick Start
 
 ### Prerequisites
 
-- **Angular**: >=18.0.0 (Signals support required)
+- **Angular**: >=19.0.0 minimum, 20.x recommended (all used APIs stable)
 - **Vest.js**: >=5.4.6 (Validation engine)
 - **TypeScript**: >=5.8.0 (Modern Angular features)
-- **Node.js**: >=18.19.0 (Required for Angular 18+)
-
-### Browser Support
-
-ngx-vest-forms supports all modern browsers that Angular 18+ targets:
-
-- **Chrome**: 98+ (includes `structuredClone()` support)
-- **Firefox**: 94+ (includes `structuredClone()` support)
-- **Safari**: 15.4+ (includes `structuredClone()` support)
-- **Edge**: 98+ (includes `structuredClone()` support)
-
-> **Note**: The library uses native `structuredClone()` for object cloning, which is fully supported in all Angular 18+ target environments. No polyfill is required.
+- **Node.js**: >=20 (Maintenance release)
 
 ### Installation
 
@@ -115,1330 +45,303 @@ ngx-vest-forms supports all modern browsers that Angular 18+ targets:
 npm install ngx-vest-forms
 ```
 
-### 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, NgxDeepPartial } from 'ngx-vest-forms';
-
-type MyFormModel = NgxDeepPartial<{
-  generalInfo: {
-    firstName: string;
-    lastName: string;
-  };
-}>;
-```
-
-#### Step 2: Set up your component
-
-Use `[ngModel]` (not `[(ngModel)]`) for unidirectional data flow:
-
-```typescript
-import { vestForms, NgxDeepPartial } from 'ngx-vest-forms';
-
-// A form model is always deep partial because angular will create it over time organically
-type MyFormModel = NgxDeepPartial<{
-  generalInfo: {
-    firstName: string;
-    lastName: string;
-  };
-}>;
-
-@Component({
-  imports: [vestForms],
-  template: `
-    <form
-      ngxVestForm
-      (formValueChange)="formValue.set($event)"
-      (ngSubmit)="save()"
-    >
-      <div ngModelGroup="generalInfo">
-        <label>First name</label>
-        <input
-          type="text"
-          name="firstName"
-          [ngModel]="formValue().generalInfo?.firstName"
-        />
-
-        <label>Last name</label>
-        <input
-          type="text"
-          name="lastName"
-          [ngModel]="formValue().generalInfo?.lastName"
-        />
-      </div>
-    </form>
-  `,
-})
-export class MyComponent {
-  // This signal will hold the state of our form
-  protected readonly formValue = signal<MyFormModel>({});
-}
-```
-
-#### 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`.
+> **v.2.0.0 NOTE:**
+>
+> You must call `only()` **unconditionally** in Vest suites.
+>
+> ```ts
+> // ✅ Correct
+> only(field); // only(undefined) safely runs all tests
+> ```
+>
+> Why: Conditional `only()` corrupts Vest's execution tracking and breaks `omitWhen` + `validationConfig`.
+> See the [Migration Guide](./docs/migration/MIGRATION-v1.x-to-v2.0.0.md#1-unconditional-only-pattern-required-critical).
+>
+> Selector prefix: use `ngx-` (recommended). The legacy `sc-` works in v2.x but is deprecated and will be removed in v3.
 
-### Minimal Example
+### Quick Start
 
-Here's the absolute minimum to get started with ngx-vest-forms:
+Start simple (with validations):
 
-```typescript
+```ts
 import { Component, signal } from '@angular/core';
-import { vestForms, NgxDeepPartial } from 'ngx-vest-forms';
-
-type SimpleForm = NgxDeepPartial<{
-  email: string;
-  name: string;
-}>;
-
-@Component({
-  selector: 'app-simple-form',
-  imports: [vestForms],
-  template: `
-    <form
-      ngxVestForm
-      (formValueChange)="formValue.set($event)"
-      (ngSubmit)="save()"
-    >
-      <label for="email">Email</label>
-      <input id="email" name="email" [ngModel]="formValue().email" />
-
-      <label for="name">Name</label>
-      <input id="name" name="name" [ngModel]="formValue().name" />
-
-      <button type="submit">Submit</button>
-    </form>
-  `,
-})
-export class SimpleFormComponent {
-  protected readonly formValue = signal<SimpleForm>({});
-
-  protected save(): void {
-    console.log('Form submitted:', this.formValue());
-  }
-}
-```
-
-That's all you need! The `ngxVestForm` directive automatically:
-
-- Creates FormControls for each input
-- Manages form state with signals
-- Provides type-safe unidirectional data flow
-
-## Complete Example
-
-A complete working form with ngx-vest-forms requires just 4 steps:
-
-1. **Define your form model** using `NgxDeepPartial<T>`
-2. **Create a validation suite** with Vest.js using `staticSuite()`
-3. **Set up your component** with a signal for form state
-4. **Build your template** with `ngxVestForm` directive and `[ngModel]` bindings
-
-The result: A fully functional form with type safety, automatic form control creation, validation on blur/submit, and error display - all with minimal boilerplate.
-
-> **📖 Complete Guide**: See **[Complete Example](./docs/COMPLETE-EXAMPLE.md)** for a full working example with detailed explanations of each step, key concepts, and common patterns.
-
-## Core Concepts
-
-### Understanding Form State
-
-Angular automatically creates FormGroups and FormControls based on your template structure. The `ngxVestForm` directive provides these outputs:
-
-| Output            | Description                                     |
-| ----------------- | ----------------------------------------------- |
-| `formValueChange` | Emits when form value changes (debounced)       |
-| `dirtyChange`     | Emits when dirty state changes                  |
-| `validChange`     | Emits when validation state changes             |
-| `errorsChange`    | Emits complete list of errors for form/controls |
-
-### Public Methods
-
-| Method                    | Description                                                                                                           |
-| ------------------------- | --------------------------------------------------------------------------------------------------------------------- |
-| `triggerFormValidation()` | Manually triggers form validation update when form structure changes without value changes (e.g., conditional fields) |
-
-### Form Models and Type Safety
-
-All form models in ngx-vest-forms use `NgxDeepPartial<T>` (or the legacy alias `DeepPartial<T>`) because Angular's template-driven forms build up values incrementally:
-
-```typescript
-import { NgxDeepPartial } from 'ngx-vest-forms';
-
-type MyFormModel = NgxDeepPartial<{
-  generalInfo: {
-    firstName: string;
-    lastName: string;
-  };
-}>;
-```
-
-> **Note**: The `Ngx` prefix prevents naming conflicts with other libraries. Both `NgxDeepPartial` and `DeepPartial` work identically; the Ngx-prefixed version is recommended for new code.
-
-This is why you must use the `?` operator in templates:
-
-```html
-<input [ngModel]="formValue().generalInfo?.firstName" name="firstName" />
-```
-
-### Validation Suite Type Safety
-
-Use `NgxVestSuite<T>` for type-safe validation suites:
-
-```typescript
-import { NgxVestSuite, NgxDeepPartial } from 'ngx-vest-forms';
+import { NgxVestForms, NgxDeepPartial, NgxVestSuite } from 'ngx-vest-forms';
 import { staticSuite, only, test, enforce } from 'vest';
 
-type FormModel = NgxDeepPartial<{
-  email: string;
-  password: string;
-  profile: {
-    age: number;
-  };
-}>;
-
-// Create validation suite
-export const validationSuite: NgxVestSuite<FormModel> = staticSuite(
-  (model: FormModel, field?: string) => {
-    only(field); // CRITICAL: Always call only() unconditionally
-
-    test('email', 'Email is required', () => {
-      enforce(model.email).isNotBlank();
-    });
-
-    test('profile.age', 'Must be 18+', () => {
-      enforce(model.profile?.age).greaterThanOrEquals(18);
-    });
-  }
-);
-
-// Component - use directly
-@Component({...})
-class MyFormComponent {
-  protected readonly suite = validationSuite;
-  protected readonly formValue = signal<FormModel>({});
-}
-```
-
-**Key Benefits:**
-
-- **Type Safety**: Full TypeScript support for model and field parameters
-- **Template Compatibility**: Works seamlessly in Angular templates
-- **Simplified API**: Single type for all validation suite needs
-- **No Type Assertions**: No `as any` or `$any()` casts needed
-
-### Form State Type and Utilities
-
-The `formState` computed signal returns an `NgxFormState<T>` object with the current form state:
-
-```typescript
-import { NgxFormState, createEmptyFormState } from 'ngx-vest-forms';
+type MyFormModel = NgxDeepPartial<{ email: string; name: string }>;
 
-// The form state contains:
-interface NgxFormState<TModel> {
-  valid: boolean; // Whether the form is valid
-  errors: Record<string, string[]>; // Map of field errors by path
-  value: TModel | null; // Current form value (includes disabled fields)
-}
+// Minimal validation suite (always call only(field) unconditionally)
+const suite: NgxVestSuite<MyFormModel> = staticSuite((model, field?) => {
+  only(field);
+  test('email', 'Email is required', () => {
+    enforce(model.email).isNotBlank();
+  });
+});
 
-// Useful for parent components displaying child form state
 @Component({
+  imports: [NgxVestForms],
   template: `
-    <app-child-form #childForm />
-    <div>Form Valid: {{ formState().valid }}</div>
-    <div>Errors: {{ formState().errors | json }}</div>
-  `,
-  changeDetection: ChangeDetectionStrategy.OnPush,
-})
-export class ParentComponent {
-  // Modern Angular 20+: Use viewChild() instead of @ViewChild
-  private readonly childForm = viewChild<ChildFormComponent>('childForm');
-
-  // Provide safe fallback when child form isn't initialized yet
-  protected readonly formState = computed(
-    () => this.childForm()?.vestForm?.formState() ?? createEmptyFormState()
-  );
-}
-```
-
-The `createEmptyFormState()` utility creates a safe default state:
-
-- `valid: true`
-- `errors: {}`
-- `value: null`
-
-This prevents null reference errors in templates when child forms or form references might be undefined.
-
-### Shape Validation: Catching Typos Early
-
-Template-driven forms are type-safe, but not in the `name` attributes or `ngModelGroup` attributes.
-Making a typo in those can result in a time-consuming endeavor. For this we have introduced shapes.
-A shape is an object where the `scVestForm` can validate to. It is a deep required of the form model:
-
-```typescript
-import { DeepPartial, DeepRequired, vestForms } from 'ngx-vest-forms';
-
-type MyFormModel = DeepPartial<{
-  generalInfo: {
-    firstName: string;
-    lastName: string;
-  };
-}>;
-
-export const myFormModelShape: DeepRequired<MyFormModel> = {
-  generalInfo: {
-    firstName: '',
-    lastName: '',
-  },
-};
+    <form ngxVestForm [suite]="suite" (formValueChange)="formValue.set($event)">
+      <ngx-control-wrapper>
+        <label for="email">Email</label>
+        <input id="email" name="email" [ngModel]="formValue().email" />
+        <!-- Errors display automatically below input -->
+      </ngx-control-wrapper>
+
+      <ngx-control-wrapper>
+        <label for="name">Name</label>
+        <input id="name" name="name" [ngModel]="formValue().name" />
+      </ngx-control-wrapper>
 
-@Component({
-  imports: [vestForms],
-  template: `
-    <form
-      ngxVestForm
-      [formShape]="shape"
-      (formValueChange)="formValue.set($event)"
-      (ngSubmit)="save()"
-    >
-      <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>
+      <button type="submit">Submit</button>
     </form>
   `,
 })
 export class MyComponent {
   protected readonly formValue = signal<MyFormModel>({});
-  protected readonly shape = myFormModelShape;
+  protected readonly suite = suite;
 }
 ```
 
-By passing the shape to the `formShape` input the `ngxVestForm` will validate the actual form value
-against the form shape every time the form changes, but only when Angular is in devMode.
-
-Making a typo in the name attribute or an ngModelGroup attribute would result in runtime errors.
-The console would look like this:
-
-```chatinput
-Error: Shape mismatch:
-
-[ngModel] Mismatch 'firstame'
-[ngModelGroup] Mismatch: 'addresses.billingddress'
-[ngModel] Mismatch 'addresses.billingddress.steet'
-[ngModel] Mismatch 'addresses.billingddress.number'
-[ngModel] Mismatch 'addresses.billingddress.city'
-[ngModel] Mismatch 'addresses.billingddress.zipcode'
-[ngModel] Mismatch 'addresses.billingddress.country'
-
-
-    at validateShape (shape-validation.ts:28:19)
-    at Object.next (form.directive.ts:178:17)
-    at ConsumerObserver.next (Subscriber.js:91:33)
-    at SafeSubscriber._next (Subscriber.js:60:26)
-    at SafeSubscriber.next (Subscriber.js:31:18)
-    at subscribe.innerSubscriber (switchMap.js:14:144)
-    at OperatorSubscriber._next (OperatorSubscriber.js:13:21)
-    at OperatorSubscriber.next (Subscriber.js:31:18)
-    at map.js:7:24
-```
-
-## Validation
+Notes.
 
-ngx-vest-forms uses [Vest.js](https://vestjs.dev) for validation - a lightweight, flexible validation framework that works across any JavaScript environment.
+- Use `[ngModel]` (not `[(ngModel)]`) for unidirectional data flow
+- The `?` operator is required because template-driven forms build values incrementally (`NgxDeepPartial`)
+- The `name` attribute MUST exactly match the property path used in `[ngModel]` — see [Field Paths](./docs/FIELD-PATHS.md)
 
-### Creating Your First Validation Suite
+That's all you need. The directive automatically creates controls, wires validation, and manages state.
 
-Vest suites use `staticSuite()` with `only()` for performance optimization:
-
-```typescript
-import { enforce, only, staticSuite, test } from 'vest';
-
-export const myFormSuite = staticSuite((model: MyFormModel, field?) => {
-  only(field); // Call unconditionally at top
-
-  test('firstName', 'First name is required', () => {
-    enforce(model.firstName).isNotBlank();
-  });
-});
-```
+## Key Features
 
-**Test parameters**: `test(fieldName, errorMessage, validationFunction)`
+- **Unidirectional state with signals** — Models are `NgxDeepPartial<T>` so values build up incrementally
+- **Type-safe with runtime shape validation** — Automatic control creation and validation wiring (dev mode checks)
+- **Vest.js validations** — Sync/async, conditional, composable patterns with `only(field)` optimization
+- **Error display modes** — Control when errors show: `on-blur`, `on-submit`, or `on-blur-or-submit` (default)
+- **Form state tracking** — Access touched, dirty, valid/invalid states for individual fields or entire form
+- **Error display helpers** — `ngx-control-wrapper`, tokens, and `FormErrorDisplayDirective` for consistent UX
+- **Cross-field dependencies** — `validationConfig` for field-to-field triggers, `ROOT_FORM` for form-level rules
+- **Utilities** — Field paths, field clearing, validation config builder
 
-- Use dot notation for nested fields: `'addresses.billingAddress.street'`
+### Error Display Modes
 
-### Connecting Validation to Your Form
-
-The biggest pain point ngx-vest-forms solves: **Connecting Vest suites to Angular with zero boilerplate**:
+Control when validation errors are shown to users with three built-in modes:
 
 ```typescript
-// Component
-class MyComponent {
-  protected readonly formValue = signal<MyFormModel>({});
-  protected readonly suite = myFormModelSuite;
-}
-```
-
-```html
-<!-- Template -->
-<form
-  ngxVestForm
-  [suite]="suite"
-  (formValueChange)="formValue.set($event)"
-  (ngSubmit)="save()"
->
-  ...
-</form>
-```
-
-That's it! Validations are completely wired. Behind the scenes:
-
-1. Control gets created, Angular recognizes the `ngModel` directives
-2. These directives implement `AsyncValidator` and connect to the Vest suite
-3. User types into control
-4. The validate function gets called
-5. Vest returns the errors
-6. ngx-vest-forms puts those errors on the Angular form control
-
-This means `valid`, `invalid`, `errors`, `statusChanges` all work just like a regular Angular form.
-
-### Displaying Validation Errors
+// Global configuration via DI token
+import { NGX_ERROR_DISPLAY_MODE_TOKEN } from 'ngx-vest-forms';
 
-Use the `ngx-control-wrapper` component to show validation errors consistently:
+providers: [
+  { provide: NGX_ERROR_DISPLAY_MODE_TOKEN, useValue: 'on-blur-or-submit' }
+]
 
-```html
-<div ngModelGroup="generalInfo" ngx-control-wrapper>
-  <ngx-control-wrapper>
-    <label>First name</label>
-    <input
-      type="text"
-      name="firstName"
-      [ngModel]="formValue().generalInfo?.firstName"
-    />
-  </ngx-control-wrapper>
-
-  <ngx-control-wrapper>
-    <label>Last name</label>
-    <input
-      type="text"
-      name="lastName"
-      [ngModel]="formValue().generalInfo?.lastName"
-    />
-  </ngx-control-wrapper>
-</div>
+// Or per-field via control wrapper
+<ngx-control-wrapper [errorDisplayMode]="'on-blur'">
+  <input name="email" [ngModel]="formValue().email" />
+</ngx-control-wrapper>
 ```
 
-Errors show automatically:
+**Available modes:**
 
-- ✅ On blur
-- ✅ On submit
+- **`on-blur-or-submit`** (default) — Show errors after field is touched OR form is submitted
+- **`on-blur`** — Show errors only after field loses focus (touched)
+- **`on-submit`** — Show errors only after form submission
 
-You can use `ngx-control-wrapper` on:
+**Tip**: Use `on-blur-or-submit` for best UX — users get immediate feedback on touched fields while preventing overwhelming errors on pristine forms.
 
-- Elements that hold `ngModelGroup`
-- Elements that have an `ngModel` (or form control) inside of them
+📖 **[Complete Guide: Custom Control Wrappers](./docs/CUSTOM-CONTROL-WRAPPERS.md)**
 
-### Performance Optimization with `only()`
+### Form State
 
-**Critical**: Always call `only()` unconditionally at the top of your validation suite:
-
-```typescript
-export const suite = staticSuite((model, field?) => {
-  only(field); // ✅ CORRECT - Unconditional call
-  // ...tests
-});
-
-// ❌ WRONG - Conditional call
-export const badSuite = staticSuite((model, field?) => {
-  if (field) only(field); // Breaks Vest's execution tracking!
-});
-```
-
-**Why**: `only(undefined)` is safe (runs all tests), while `only('fieldName')` optimizes by running only that field's tests. Conditional calls corrupt Vest's internal state and break `omitWhen` + `validationConfig` timing.
-
-- ✅ **Fixed**: Proper validation with `omitWhen` and nested fields with `validationConfig`
-
-> [!IMPORTANT]
-> **Critical Pattern**: You MUST call `only()` unconditionally. Never wrap it in `if (field)`. This ensures validation uses current form values and prevents timing issues with `omitWhen` and `validationConfig`. Conditional `only()` calls corrupt Vest's internal execution tracking.
-
-### Error Display Control
-
-The `ngx-control-wrapper` component uses the `FormErrorDisplayDirective` under the hood to manage when and how errors are displayed.
-
-#### Error Display Modes
-
-ngx-vest-forms supports three error display modes:
-
-- **`on-blur-or-submit`** (default) - Show errors after field blur OR form submission
-- **`on-blur`** - Show errors only after field blur
-- **`on-submit`** - Show errors only after form submission
-
-#### Configuring Error Display
-
-**Global Configuration** - Set the default mode for your entire application:
-
-```typescript
-import { ApplicationConfig } from '@angular/core';
-import { NGX_ERROR_DISPLAY_MODE_TOKEN } from 'ngx-vest-forms';
-
-export const appConfig: ApplicationConfig = {
-  providers: [{ provide: NGX_ERROR_DISPLAY_MODE_TOKEN, useValue: 'on-submit' }],
-};
-
-// Or in a component
-@Component({
-  providers: [{ provide: NGX_ERROR_DISPLAY_MODE_TOKEN, useValue: 'on-submit' }],
-})
-export class MyComponent {}
-```
-
-**Per-Instance Configuration** - Override the mode for specific form fields:
+Access complete form and field state through the `FormErrorDisplayDirective` or `FormControlStateDirective`:
 
 ```typescript
 @Component({
   template: `
-    <ngx-control-wrapper [errorDisplayMode]="'on-blur'">
+    <ngx-control-wrapper #wrapper="ngxErrorDisplay">
       <input name="email" [ngModel]="formValue().email" />
-    </ngx-control-wrapper>
-  `,
-})
-export class MyFormComponent {}
-```
-
-> **Note**: The `ngx-control-wrapper` component accepts `errorDisplayMode` as an input to override the global setting for specific fields.
-
-### Validation Options
-
-You can configure additional `validationOptions` at various levels like `form`, `ngModelGroup` or `ngModel`.
-
-For example, to debounce validation (useful for API calls):
-
-```html
-<form ngxVestForm ... [validationOptions]="{ debounceTime: 0 }">
-  ...
-  <ngx-control-wrapper>
-    <label>UserId</label>
-    <input
-      type="text"
-      name="userId"
-      [ngModel]="formValue().userId"
-      [validationOptions]="{ debounceTime: 300 }"
-    />
-  </ngx-control-wrapper>
-  ...
-</form>
-```
-
-#### Configurable Validation Config Debounce
-
-The `validationConfig` feature (for triggering dependent field validations) uses a debounce to prevent excessive validation calls. You can configure this debounce globally or per-component using the `NGX_VALIDATION_CONFIG_DEBOUNCE_TOKEN`:
-
-**Global Configuration** (recommended for consistent behavior):
-
-```typescript
-import { ApplicationConfig } from '@angular/core';
-import { NGX_VALIDATION_CONFIG_DEBOUNCE_TOKEN } from 'ngx-vest-forms';
-
-export const appConfig: ApplicationConfig = {
-  providers: [
-    // Set global debounce for validationConfig dependencies
-    { provide: NGX_VALIDATION_CONFIG_DEBOUNCE_TOKEN, useValue: 150 },
-  ],
-};
-```
-
-**Per-Route Configuration**:
-
-```typescript
-{
-  path: 'checkout',
-  component: CheckoutComponent,
-  providers: [
-    { provide: NGX_VALIDATION_CONFIG_DEBOUNCE_TOKEN, useValue: 50 }
-  ]
-}
-```
-
-**Per-Component Configuration**:
-
-```typescript
-@Component({
-  providers: [
-    // Disable debounce for testing
-    { provide: NGX_VALIDATION_CONFIG_DEBOUNCE_TOKEN, useValue: 0 },
-  ],
-})
-export class MyFormComponent {}
-```
-
-**Default**: 100ms (maintains backward compatibility)
-
-> **Note**: This token controls the debounce for `validationConfig` dependency triggering only. For individual field validation debouncing, use `[validationOptions]="{ debounceTime: 300 }"` on the control as shown above.
-
-## Intermediate Topics
-
-### Conditional Fields
-
-Use computed signals to show/hide fields dynamically. Angular automatically manages FormControl creation/removal:
-
-```typescript
-class MyComponent {
-  protected readonly showLastName = computed(
-    () => !!this.formValue().firstName
-  );
-}
-```
-
-```html
-@if(showLastName()) {
-  <input name="lastName" [ngModel]="formValue().lastName" />
-}
-
-  <label>Last name</label>
-  <input
-    type="text"
-    name="lastName"
-    [ngModel]="formValue().generalInformation?.lastName"
-  />
-</div>
-}
-```
-
-### Reactive Disabling
-
-To achieve reactive disabling, we just have to take advantage of computed signals as well:
-
-```typescript
-class MyComponent {
-  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"
-/>
-```
-
-### Conditional Validations
-
-Vest makes it extremely easy to create conditional validations.
-Assume we have a form model that has `age` and `emergencyContact`.
-The `emergencyContact` is required, but only when the person is not of legal age.
-
-We can use the `omitWhen` so that when the person is below 18, the assertion
-will not be done.
-
-```typescript
-import { enforce, omitWhen, only, staticSuite, test } from 'vest';
-
-...
-omitWhen((model.age || 0) >= 18, () => {
-  test('emergencyContact', 'Emergency contact is required', () => {
-    enforce(model.emergencyContact).isNotBlank();
-  });
-});
-```
-
-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
-
-````typescript
-test('passwords.password', 'Password is not filled in', () => {
-  enforce(model.passwords?.password).isNotBlank();
-});
-
-omitWhen(!model.passwords?.password, () => {
-  test('passwords.confirmPassword', 'Confirm password required', () => {
-    enforce(model.passwords?.confirmPassword).isNotBlank();
-  });
-
-  test('passwords', 'Passwords must match', () => {
-    enforce(model.passwords?.confirmPassword).equals(model.passwords?.password);
-  });
-});
-
-This pattern is testable, reusable across frameworks, and readable.
 
-Forget about manually adding, removing validators on reactive forms and not being able to
-re-use them. This code is easy to test, easy to re-use on frontend, backend, angular, react, etc...
-**Oh, it's also pretty readable**
-
-### Dependent Field Validation with Conditional Rendering
-
-When fields that depend on each other are conditionally rendered (using `@if`), you need a **reactive validationConfig** to avoid "control not found" warnings.
-
-> **💡 Related Pattern**: If you're also switching between form inputs and non-form content (like informational text), you'll need [`triggerFormValidation()`](#handling-form-structure-changes) in addition to computed `validationConfig`. See the [comparison matrix](#handling-dynamic-forms-two-common-patterns) for when to use each.
-
-#### The Problem
-
-```typescript
-// ❌ This causes warnings when conditional fields don't exist
-class MyComponent {
-  protected readonly validationConfig = {
-    quantity: ['justification'], // justification only shows when quantity > 5!
-  };
-}
-````
-
-#### The Solution
-
-Use a **computed signal** for `validationConfig`:
-
-```typescript
-import { Component, signal, computed } from '@angular/core';
-
-@Component({
-  template: `
-    <form ngxVestForm [validationConfig]="validationConfig()" ...>
-      <input name="quantity" [ngModel]="formValue().quantity" />
-
-      @if ((formValue().quantity || 0) > 5) {
-        <textarea
-          name="justification"
-          [ngModel]="formValue().justification"
-        ></textarea>
+      @if (wrapper.isTouched()) {
+        <span>Field was touched</span>
       }
-    </form>
-  `,
+      @if (wrapper.isPending()) {
+        <span>Validating...</span>
+      }
+    </ngx-control-wrapper>
+  `
 })
-export class MyComponent {
-  protected readonly formValue = signal<MyFormModel>({});
-
-  // ✅ Computed config only references controls that exist
-  protected readonly validationConfig = computed(() => {
-    const config: Record<string, string[]> = {};
-
-    // Only add dependency when field is in DOM
-    if ((this.formValue().quantity || 0) > 5) {
-      config['quantity'] = ['justification'];
-      config['justification'] = ['quantity']; // Bidirectional validation
-    }
-
-    return config;
-  });
-}
 ```
 
-**Key Points:**
+**Available state signals:**
 
-- ✅ **Reactive**: Config updates when field visibility changes
-- ✅ **No Warnings**: Only references controls that exist in DOM
-- ✅ **Bidirectional**: Works for two-way validation dependencies
-- ✅ **Type-Safe**: Full TypeScript support
+- `isTouched()` / `isDirty()` — User interaction state
+- `isValid()` / `isInvalid()` — Validation state
+- `isPending()` — Async validation in progress
+- `errorMessages()` / `warningMessages()` — Current validation messages
+- `shouldShowErrors()` — Computed based on display mode and state
 
-**Template Binding:**
+**Tip**: For async validations, use `createDebouncedPendingState()` to prevent "Validating..." messages from flashing when validation completes quickly (< 200ms).
 
-```html
-<!-- Notice the function call: validationConfig() -->
-<form ngxVestForm [validationConfig]="validationConfig()" ...>...</form>
-```
+📖 **[Complete Guide: Custom Control Wrappers](./docs/CUSTOM-CONTROL-WRAPPERS.md)**
 
-### ValidationConfig Fluent Builder API
+## Advanced Features
 
-For complex validation configurations, ngx-vest-forms provides a type-safe fluent builder API that makes validation dependencies clearer and easier to maintain.
+### Validation Config
 
-#### Why Use the Builder?
+Automatically re-validate dependent fields when another field changes. Essential when using Vest.js's `omitWhen`/`skipWhen` for conditional validations.
 
-**Without Builder (Manual):**
+**When to use**: Password confirmation, conditional required fields, or any field that depends on another field's value.
 
 ```typescript
-// ❌ Verbose, error-prone, no type safety
 protected readonly validationConfig = {
-  'password': ['confirmPassword'],
-  'confirmPassword': ['password'], // Easy to forget reverse
-  'startDate': ['endDate'],
-  'endDate': ['startDate'],
-  'country': ['state', 'zipCode'],
+  'password': ['confirmPassword'],  // When password changes, re-validate confirmPassword
+  'age': ['emergencyContact']       // When age changes, re-validate emergencyContact
 };
 ```
 
-**With Builder:**
-
-```typescript
-import { createValidationConfig } from 'ngx-vest-forms';
-
-// ✅ Clean, type-safe, self-documenting
-protected readonly validationConfig = createValidationConfig<MyFormModel>()
-  .bidirectional('password', 'confirmPassword')
-  .bidirectional('startDate', 'endDate')
-  .whenChanged('country', ['state', 'zipCode'])
-  .build();
-```
-
-#### Builder Methods
-
-**`whenChanged(trigger, revalidate)`** - One-way dependency
-
-```typescript
-// When country changes, revalidate state and zipCode
-.whenChanged('country', ['state', 'zipCode'])
-```
+**Important**: `validationConfig` only triggers re-validation—validation logic is always defined in your Vest suite.
 
-**`bidirectional(field1, field2)`** - Two-way dependency
+📖 **[Complete Guide: ValidationConfig vs Root-Form](./docs/VALIDATION-CONFIG-VS-ROOT-FORM.md)**
 
-```typescript
-// When either password or confirmPassword changes, revalidate the other
-.bidirectional('password', 'confirmPassword')
-```
+### Root-Form Validation
 
-**`group(fields)`** - All fields revalidate each other
-
-```typescript
-// When any contact field changes, revalidate all others
-.group(['firstName', 'lastName', 'email'])
-```
-
-**`merge(config)`** - Combine configurations
-
-```typescript
-// Conditionally merge additional config
-.merge(isInternational() ? { country: ['customsForm'] } : {})
-```
+Form-level validation rules that don't belong to any specific field (e.g., "at least one contact method required").
 
-#### Real-World Example
+**When to use**: Business rules that evaluate multiple fields but errors should appear at form level, not on individual fields.
 
 ```typescript
-import { Component, signal, computed } from '@angular/core';
-import { createValidationConfig, type DeepPartial } from 'ngx-vest-forms';
-
-type OrderFormModel = DeepPartial<{
-  // Customer info
-  firstName: string;
-  lastName: string;
-  email: string;
-
-  // Password
-  password: string;
-  confirmPassword: string;
-
-  // Dates
-  startDate: Date;
-  endDate: Date;
-
-  // Location
-  country: string;
-  state: string;
-  zipCode: string;
-}>;
-
-@Component({
-  // ...
-})
-export class OrderFormComponent {
-  protected readonly validationConfig = createValidationConfig<OrderFormModel>()
-    // Customer info group
-    .group(['firstName', 'lastName', 'email'])
-
-    // Password confirmation
-    .bidirectional('password', 'confirmPassword')
-
-    // Date range
-    .bidirectional('startDate', 'endDate')
-
-    // Location dependencies
-    .whenChanged('country', ['state', 'zipCode'])
-
-    .build();
-}
-```
-
-#### Benefits
-
-- ✅ **Type Safety**: IDE autocomplete for all field paths
-- ✅ **Readability**: Intent is clear from method names
-- ✅ **Maintainability**: Less boilerplate, easier to understand
-- ✅ **Error Prevention**: Compile-time validation of field names
-- ✅ **Backward Compatible**: Works alongside manual configurations
-
-#### Combining with Computed Signals
-
-For dynamic configurations, combine the builder with computed signals:
+import { ROOT_FORM } from 'ngx-vest-forms';
 
-```typescript
-protected readonly validationConfig = computed(() =>
-  createValidationConfig<FormModel>()
-    .bidirectional('password', 'confirmPassword')
-    // Conditionally add dependencies
-    .merge(
-      this.isInternational()
-        ? { country: ['customsForm', 'taxId'] }
-        : {}
-    )
-    .build()
-);
+// In your Vest suite
+test(ROOT_FORM, 'At least one contact method is required', () => {
+  enforce(model.email || model.phone).isTruthy();
+});
 ```
 
-> **📚 Learn More**: See the [ValidationConfig Builder Guide](./docs/VALIDATION-CONFIG-BUILDER.md) for comprehensive examples and patterns.
-
-## Advanced Topics
-
-### Handling Dynamic Forms: Two Common Patterns
-
-Dynamic forms present two distinct challenges that require different solutions:
-
-| Challenge                                           | Solution                                                                              | When to Use                                                |
-| --------------------------------------------------- | ------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
-| **Conditional fields with validation dependencies** | [Computed `validationConfig`](#dependent-field-validation-with-conditional-rendering) | Fields depend on each other AND are conditionally rendered |
-| **Structure changes without value changes**         | [`triggerFormValidation()`](#handling-form-structure-changes)                         | Switching between form inputs and non-form content         |
-
-> **💡 Pro Tip**: These solutions are complementary and often used together in complex forms with both conditional validation dependencies and dynamic structure changes.
-
-### Handling Form Structure Changes
-
-When form structure changes dynamically (e.g., switching between form inputs and non-form elements like `<p>` tags), use `triggerFormValidation()` to manually update validation state:
-
-```typescript
-@Component({
-  template: `
-    <form ngxVestForm [suite]="suite" #vestForm="ngxVestForm">
-      <select
-        name="type"
-        [ngModel]="formValue().type"
-        (ngModelChange)="onTypeChange($event)"
-      >
-        <option value="typeA">Type A</option>
-        <option value="typeC">Type C (no input)</option>
-      </select>
-
-      @if (formValue().type === 'typeA') {
-        <input name="fieldA" [ngModel]="formValue().fieldA" />
-      } @else {
-        <p>No additional input required.</p>
-      }
-    </form>
-  `,
-})
-class MyComponent {
-  protected readonly vestFormRef = viewChild.required('vestForm', {
-    read: FormDirective,
-  });
-
-  protected onTypeChange(type: string) {
-    this.formValue.update((v) => {
-      const updated = clearFieldsWhen(v, { fieldA: type !== 'typeA' });
-      return { ...updated, type };
-    });
-    this.vestFormRef().triggerFormValidation();
-  }
-}
+```html
+<!-- In template -->
+<form ngxVestForm ngxValidateRootForm [suite]="suite">
+  <!-- Show form-level errors -->
+  <div *ngIf="vestForm.errors?.rootForm">{{ vestForm.errors.rootForm }}</div>
+</form>
 ```
 
-> **📖 Detailed Guide**: See **[Field Clearing Utilities](./docs/FIELD-CLEARING-UTILITIES.md)** and **[Structure Change Detection Guide](./docs/STRUCTURE_CHANGE_DETECTION.md)** for comprehensive examples.
-
-**When to use `triggerFormValidation()`**: After form structure changes (showing/hiding fields), clearing form sections, or switching between form inputs and non-form content.
+📖 **[Complete Guide: ValidationConfig vs Root-Form](./docs/VALIDATION-CONFIG-VS-ROOT-FORM.md)**
 
-> **🔗 See Also**: [Computed `validationConfig`](#dependent-field-validation-with-conditional-rendering) for validation dependencies, and [Field Clearing Utilities](./docs/FIELD-CLEARING-UTILITIES.md) for state management.
+### Dynamic Form Structure
 
-#### Field Clearing Pattern
+Manually trigger validation when form structure changes between **input fields and non-input content** (like `<p>` tags) without value changes.
 
-**When field clearing is required**: When switching between form inputs and non-form elements (e.g., `<input>` ↔ `<p>` tags).
+**When to use**: When switching from form controls to informational text/paragraphs where no control values change.
 
-**Why**: Angular removes FormControls when switching to non-form content, but component signals retain old values, creating state inconsistency.
+**NOT needed when**: Switching between different input fields (value changes trigger validation automatically).
 
 ```typescript
-// Use clearFieldsWhen to synchronize state
-import { clearFieldsWhen } from 'ngx-vest-forms';
-
-this.formValue.update((v) =>
-  clearFieldsWhen(v, {
-    fieldA: procedureType !== 'typeA', // Clear when NOT showing input
-  })
-);
-```
-
-**When NOT required**: Pure form-to-form conditionals (switching input types with same `name`) – Angular maintains FormControl throughout.
-
-##### When Field Clearing is NOT Required
-
-Pure form-to-form conditionals (switching input types with same `name`) usually don't need field clearing because Angular maintains the FormControl throughout:
-
-```typescript
-// These switches DON'T require field clearing:
-@if (inputType === 'text') {
-  <input name="field" [ngModel]="formValue().field" type="text" />
+// Example: Switching from input to paragraph
+@if (type() === 'typeA') {
+  <input name="fieldA" [ngModel]="formValue().fieldA" />
 } @else {
-  <input name="field" [ngModel]="formValue().field" type="number" />
+  <p>No input required</p>  // ← No form control, needs triggerFormValidation()
 }
-```
-
-> **📖 Complete Guide**: See **[Field Clearing Utilities](./docs/FIELD-CLEARING-UTILITIES.md)** for detailed patterns and use cases.
-
-### Field State Utilities
-
-When building dynamic forms, you often need to conditionally show/hide form inputs or switch between form inputs and non-form content (like informational text). ngx-vest-forms provides specialized utilities to keep your component state synchronized with Angular's form state during these transitions.
-
-**Key Utilities:**
-
-- **`clearFieldsWhen(state, conditions)`** - Conditionally clear fields based on boolean conditions (most common)
-- **`clearFields(state, fieldArray)`** - Unconditionally clear specific fields (for reset operations)
-- **`keepFieldsWhen(state, conditions)`** - Keep only fields that meet conditions (whitelist approach)
-
-**When to Use:**
-
-These utilities are primarily needed when your template conditionally renders form inputs in some branches and non-form content (like `<p>` tags) in others. They ensure your component state stays consistent with the actual form structure.
-
-**Example:**
-
-```typescript
-import { clearFieldsWhen } from 'ngx-vest-forms';
-
-// Clear shipping address when switching from input to "No shipping needed" message
-const updatedState = clearFieldsWhen(formValue(), {
-  'addresses.shippingAddress': !useShippingAddress,
-  emergencyContact: age >= 18, // Clear when adult (no emergency contact input shown)
-});
-```
-
-**Important Note:**
-
-Pure form-to-form conditionals (switching between different input types with the same `name`) typically don't require these utilities as Angular maintains the FormControl throughout the transition.
-
-> **📖 Detailed Guide**: See **[Field Clearing Utilities](./docs/FIELD-CLEARING-UTILITIES.md)** for comprehensive examples, use cases, and when field clearing is required vs. not required.
-
-### Composable Validations
 
-Break down complex validation logic into reusable functions that can be shared across forms, frameworks, and even frontend/backend:
-
-```typescript
-// Reusable validation function
-export function addressValidations(
-  model: AddressModel | undefined,
-  field: string
-): void {
-  test(`${field}.street`, 'Street is required', () => {
-    enforce(model?.street).isNotBlank();
-  });
-  test(`${field}.city`, 'City is required', () => {
-    enforce(model?.city).isNotBlank();
-  });
-  // ... more validations
+onTypeChange(newType: string) {
+  this.formValue.update(v => ({ ...v, type: newType }));
+  this.vestForm.triggerFormValidation();  // Only needed for structure changes
 }
-
-// Use in your suite
-export const orderSuite: NgxVestSuite<OrderFormModel> = staticSuite(
-  (model, field?) => {
-    only(field);
-    addressValidations(model.billingAddress, 'billingAddress');
-    addressValidations(model.shippingAddress, 'shippingAddress');
-  }
-);
 ```
 
-**Benefits:**
-
-- ✅ **Reusability** - Share validation logic across different forms
-- ✅ **Maintainability** - Update validation logic in one place
-- ✅ **Testability** - Test validation functions independently
-- ✅ **Cross-framework** - Use same logic on frontend/backend, Angular/React
+📖 **[Complete Guide: Structure Change Detection](./docs/STRUCTURE_CHANGE_DETECTION.md)**
 
-> **📖 Detailed Guide**: See **[Composable Validations](./docs/COMPOSABLE-VALIDATIONS.md)** for advanced patterns, conditional composition, organizing validation files, nested compositions, and testing strategies.
+### Shape Validation (Development Mode)
 
-### Custom Control Wrappers
-
-Create your own error display components using the `FormErrorDisplayDirective`, which provides all the validation state you need:
+In development mode, ngx-vest-forms validates that your form's structure matches your TypeScript model, catching common mistakes early:
 
 ```typescript
-@Component({
-  selector: 'app-custom-wrapper',
-  hostDirectives: [FormErrorDisplayDirective],
-  template: `
-    <div class="field-wrapper">
-      <ng-content />
-      @if (errorDisplay.shouldShowErrors()) {
-        <div class="error">
-          @for (error of errorDisplay.errors(); track error) {
-            <span>{{ error }}</span>
-          }
-        </div>
-      }
-      @if (errorDisplay.isPending()) {
-        <div class="validating">Validating...</div>
-      }
-    </div>
-  `,
-})
-export class CustomWrapperComponent {
-  protected readonly errorDisplay = inject(FormErrorDisplayDirective, {
-    self: true,
-  });
-}
-```
-
-**When to create custom wrappers:**
-
-- Match your design system (Material, PrimeNG, etc.)
-- Custom error formatting (tooltips, popovers, inline)
-- Add UI elements (icons, help text, character counters)
-- Specific accessibility patterns
-
-> **📖 Detailed Guide**: See **[Custom Control Wrappers](./docs/CUSTOM-CONTROL-WRAPPERS.md)** for Material Design examples, available signals reference, and best practices.
-
-### Cross-Field Validation: Three Complementary Features
-
-ngx-vest-forms provides three features for handling validation in complex, dynamic forms:
-
-> **💡 Key Insight**: `validationConfig` is **essential** when using Vest.js's `omitWhen`/`skipWhen` for conditional validations. It ensures Angular re-validates dependent fields when conditions change.
-
-| Feature                       | Purpose                                         | Errors Appear At                     | Use For                                           |
-| ----------------------------- | ----------------------------------------------- | ------------------------------------ | ------------------------------------------------- |
-| **`validationConfig`**        | **Re-validation trigger** when fields change    | **Field level** (`errors.fieldName`) | Fields that need re-validation when others change |
-| **`validateRootForm`**        | Creates **form-level** validations              | **Form level** (`errors.rootForm`)   | Form-wide business rules                          |
-| **`triggerFormValidation()`** | Manual validation trigger for structure changes | N/A (triggers existing validations)  | Structure changes without value changes           |
-
-**Key Insight**: These solve different problems and often work together!
-
-> **📖 Complete Guide**: See **[Validation Features Guide](./docs/VALIDATION-CONFIG-VS-ROOT-FORM.md)** for detailed comparison, decision trees, use cases, and examples of using all three features together.
-
-**Quick Examples:**
+// Your model
+type MyFormModel = NgxDeepPartial<{
+  email: string;
+  address: { street: string; city: string };
+}>;
 
-```typescript
-// validationConfig: Re-validation trigger (NOT validation logic!)
-// This says: "When password changes, also re-validate confirmPassword"
-validationConfig = {
-  password: ['confirmPassword'], // When password changes, revalidate confirmPassword
+// Define shape for runtime validation
+const shape: NgxDeepRequired<MyFormModel> = {
+  email: '',
+  address: { street: '', city: '' },
 };
-// The actual validation logic is in your Vest suite:
-test('confirmPassword', 'Must match', () => {
-  enforce(model.confirmPassword).equals(model.password);
-});
-
-// validateRootForm: Form-level business rules
-test(ROOT_FORM, 'Brecht is not 30 anymore', () => {
-  enforce(
-    model.firstName === 'Brecht' &&
-      model.lastName === 'Billiet' &&
-      model.age === 30
-  ).isFalsy();
-});
-
-// triggerFormValidation(): After structure changes
-protected readonly vestFormRef = viewChild.required('vestForm', { read: FormDirective });
-
-onTypeChange(type: string) {
-  this.formValue.update(v => ({ ...v, type }));
-  this.vestFormRef().triggerFormValidation(); // ✅ Force validation update
-}
-```
-
-### Validations on the Root Form
-
-For form-level validations that span multiple fields, use the `ROOT_FORM` constant with `validateRootForm`:
-
-> **⚠️ Breaking Change (v3)**: Default validation mode changed from `'live'` to `'submit'`. See [Migration Guide](./docs/MIGRATION-V3.md) for details.
-
-```typescript
-import { ROOT_FORM } from 'ngx-vest-forms';
-
-// In your suite
-test(ROOT_FORM, 'Passwords must match', () => {
-  enforce(model.confirmPassword).equals(model.password);
-});
 ```
 
 ```html
-<form
-  ngxVestForm
-  ngxValidateRootForm
-  [ngxValidateRootFormMode]="'submit'"
-  [suite]="suite"
-  (errorsChange)="errors.set($event)"
->
-  <!-- Display root-level errors -->
-  {{ errors()?.['rootForm'] }}
-</form>
-```
-
-#### Validation Modes
-
-Root form validation supports two modes:
+<form ngxVestForm [suite]="suite" [formShape]="shape">
+  <!-- ✅ Correct: matches shape -->
+  <input name="email" [ngModel]="formValue().email" />
+  <input name="address.street" [ngModel]="formValue().address?.street" />
 
-- **`'submit'` (default)**: Validates only after the form is submitted. This is the recommended mode for most use cases as it prevents premature validation errors.
-- **`'live'`**: Validates on every value change, providing immediate feedback.
+  <!-- ❌ Error in dev mode: typo detected -->
+  <input name="emial" [ngModel]="formValue().email" />
 
-```html
-<!-- Submit mode - validates after submit (default) -->
-<form ngxVestForm ngxValidateRootForm [ngxValidateRootFormMode]="'submit'">
-  <!-- form controls -->
-</form>
-
-<!-- Live mode - validates immediately -->
-<form ngxVestForm ngxValidateRootForm [ngxValidateRootFormMode]="'live'">
-  <!-- form controls -->
+  <!-- ❌ Error in dev mode: path doesn't exist in shape -->
+  <input name="address.zipcode" [ngModel]="formValue().address?.zipcode" />
 </form>
 ```
 
-### Validation of Dependent Controls
-
-When field validations depend on other fields (e.g., `confirmPassword` depends on `password`), use `validationConfig` to trigger re-validation:
-
-> **📖 When to use `validationConfig` vs `validateRootForm`**: See **[ValidationConfig vs ROOT_FORM Validation](./docs/VALIDATION-CONFIG-VS-ROOT-FORM.md)** for a complete comparison and decision tree.
-
-```typescript
-// In your suite - Vest handles the logic
-omitWhen(!model.password, () => {
-  test('confirmPassword', 'Passwords must match', () => {
-    enforce(model.confirmPassword).equals(model.password);
-  });
-});
-```
-
-```typescript
-// In your component - validationConfig handles Angular orchestration
-protected validationConfig = {
-  password: ['confirmPassword'] // When password changes, revalidate confirmPassword
-};
-```
-
-```html
-<form ngxVestForm [suite]="suite" [validationConfig]="validationConfig">
-  <input name="password" [ngModel]="formValue().password" />
-  <input name="confirmPassword" [ngModel]="formValue().confirmPassword" />
-</form>
-```
+**Benefits:**
 
-**Why `validationConfig` is needed**: Vest.js handles validation logic, but cannot tell Angular to revalidate other form controls. The `validationConfig` bridges this gap by telling Angular's form system which fields should be revalidated when others change.
-There is also a complex example of form arrays with complex validations in the examples.
+- Catch typos in `name` attributes immediately during development
+- Ensure template structure matches TypeScript model
+- Zero runtime cost in production (checks disabled automatically)
+- Works with nested objects and arrays
 
-### Child Form Components
+**Important**: Shape validation only runs in development mode (`isDevMode()` returns `true`). Production builds have zero overhead.
 
-Large forms are difficult to maintain in a single file. ngx-vest-forms supports splitting forms into reusable child components, which is essential for code organization and component reusability (like address forms used in multiple places).
+📖 **[Complete Guide: Field Paths](./docs/FIELD-PATHS.md)**
 
-**Critical Requirement:**
+## Documentation
 
-Child components that contain form fields **MUST** use `vestFormsViewProviders` to access the parent form:
+### Getting Started
 
-```typescript
-import { Component, input } from '@angular/core';
-import { vestForms, vestFormsViewProviders } from 'ngx-vest-forms';
+- **[Complete Example](./docs/COMPLETE-EXAMPLE.md)** - Step-by-step walkthrough from basic form to advanced patterns
+- **[Composable Validations](./docs/COMPOSABLE-VALIDATIONS.md)** - Break validation logic into reusable, testable functions
 
-@Component({
-  selector: 'app-address',
-  viewProviders: [vestFormsViewProviders], // ⚠️ REQUIRED for child form components
-  template: `
-    <ngx-control-wrapper>
-      <label>Street</label>
-      <input [ngModel]="address().street" name="street" />
-    </ngx-control-wrapper>
-    <!-- More address fields... -->
-  `,
-})
-export class AddressComponent {
-  readonly address = input<AddressModel>();
-}
-```
+### Advanced Patterns
 
-**Key Benefits:**
+- **[ValidationConfig vs Root-Form](./docs/VALIDATION-CONFIG-VS-ROOT-FORM.md)** - Cross-field dependencies and form-level rules
+- **[Field Path Types](./docs/FIELD-PATHS.md)** - Type-safe dot-notation paths for nested properties
+- **[Structure Change Detection](./docs/STRUCTURE_CHANGE_DETECTION.md)** - Handle dynamic form structure updates
+- **[Field Clearing Utilities](./docs/FIELD-CLEARING-UTILITIES.md)** - Type-safe utilities for clearing nested form values
 
-- **Component Reusability** - Share address, phone number, or other form sections across multiple forms
-- **Code Organization** - Keep large forms manageable by splitting them into logical sections
-- **Type Safety** - Each child component can have its own strongly-typed model
-- **Dynamic Field Names** - Use inputs to customize field name prefixes (e.g., `billingAddress.street` vs `shippingAddress.street`)
+### UI & Integration
 
-> **📖 Detailed Guide**: See **[Child Components](./docs/CHILD-COMPONENTS.md)** for complete examples including dynamic field names, nested child components, and troubleshooting common issues.
+- **[Child Components](./docs/CHILD-COMPONENTS.md)** - Split large forms into smaller, maintainable components
+- **[Custom Control Wrappers](./docs/CUSTOM-CONTROL-WRAPPERS.md)** - Build consistent error display patterns
+- **[API Tokens](./docs/API-TOKENS.md)** - Configure error display modes and other global settings
 
-## Features
+### Reference
 
-Now that you've seen how ngx-vest-forms works, here's a complete overview of its capabilities:
+- **[Utilities README](./projects/ngx-vest-forms/src/lib/utils/README.md)** - Canonical reference for all utility functions
 
-### Core Features
+### Examples
 
-- **Unidirectional Data Flow** - Predictable state management with Angular signals
-- **Type Safety** - Full TypeScript support with `NgxDeepPartial<T>` and `NgxDeepRequired<T>`
-- **Enhanced Field Path Types** - Template literal autocomplete for field names ([Documentation](./docs/FIELD-PATHS.md))
-- **Zero Boilerplate** - Automatic FormControl and FormGroup creation
-- **Shape Validation** - Runtime validation against your TypeScript models (dev mode)
+- **[Examples Project](./projects/examples)** - Working code examples with business hours forms, purchase forms, and validation config demos
+  - Run locally: `npm install && npm start`
+  - Includes smart components, UI components, and complete validation patterns
 
-### Advanced Validation
+## Migration
 
-- **Async Validations** - Built-in support with AbortController and pending state
-- **Conditional Logic** - Use `omitWhen()` for conditional validation rules
-- **Composable Suites** - Reusable validation functions across projects
-- **Custom Debouncing** - Configure validation timing per field or form
-- **Warnings Support** - Non-blocking feedback with Vest's `warn()` feature
-- **Performance Optimization** - Field-level validation with `only()` pattern
+- v1.x → v2.0.0: **[Migration Guide](./docs/migration/MIGRATION-v1.x-to-v2.0.0.md)**
+- Selector prefixes: **[Dual Selector Support](./docs/DUAL-SELECTOR-SUPPORT.md)**
 
-### Dynamic Forms
+Browser support follows Angular 19+ targets (no `structuredClone` polyfill required).
 
-- **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
-- **Structure Change Detection** - Manual trigger for validation updates when form structure changes
+## FAQ
 
-### Developer Experience
+### Do I need validations to use ngx-vest-forms?
 
-- **Runtime Shape Checking** - Catch typos in `name` attributes early
-- **Flexible Error Display** - Built-in `ngx-control-wrapper` or create custom wrappers with `FormErrorDisplayDirective`
-- **Error Display Modes** - Control when errors show: on-blur, on-submit, or both
-- **Validation Config** - Declare field dependencies for complex scenarios
-- **Field State Utilities** - Helper functions for managing dynamic form state
-- **Modern Angular** - Built for Angular 18+ with standalone components and signals
+No—but you’ll almost always want them. Common cases to start without a suite:
 
-## Documentation
+- Prototyping UI while deferring rules
+- Gradual migration: adopt unidirectional state and type-safe models first
+- Server-driven validation: display backend errors while you add a client suite later
 
-### Detailed Guides
-
-For comprehensive documentation beyond this README, check out our detailed guides:
-
-- **[Accessibility Guide](./docs/ACCESSIBILITY.md)** - WCAG 2.2 AA compliance and best practices
-  - Polite vs assertive ARIA live regions
-  - Field-level and form-level error strategies
-  - Implementation details and testing guidance
-- **[Field Path Types](./docs/FIELD-PATHS.md)** - Type-safe field references with IDE autocomplete
-  - Template literal types for field paths
-  - `ValidationConfigMap<T>` for type-safe configs
-  - `FormFieldName<T>` for Vest suites
-  - Migration guide and best practices
-  - Performance considerations
-- **[Utility Types & Functions Reference](./projects/ngx-vest-forms/src/lib/utils/README.md)** - Complete guide to all public utility types and functions
-  - Type utilities: `NgxDeepPartial`, `NgxDeepRequired`, `NgxFormCompatibleDeepRequired`
-  - Form utilities: `setValueAtPath()`, `createEmptyFormState()`
-  - Array/Object conversion: `arrayToObject()`, `deepArrayToObject()`, `objectToArray()`
-  - Field path utilities: `stringifyFieldPath()`
-  - Field clearing: `clearFieldsWhen()`, `clearFields()`, `keepFieldsWhen()`
-  - Validation config builder: `createValidationConfig()`
-- **[Structure Change Detection Guide](./docs/STRUCTURE_CHANGE_DETECTION.md)** - Advanced handling of conditional form scenarios
-  - Alternative approaches and their trade-offs
-  - Performance considerations and best practices
-  - Detailed API reference with examples
-  - When and why to use `triggerFormValidation()`
-
-### Coming Soon
-
-- **Advanced Form Arrays Guide** - Dynamic lists, nested arrays, and complex scenarios
-- **Custom Validation Guide** - Building reusable validation suites and complex rules
-- **Performance Optimization Guide** - Tips and techniques for large-scale forms
+You can add a Vest suite at any time by binding `[suite]` on the form.
 
 ## Resources
 
@@ -1447,12 +350,9 @@ For comprehensive documentation beyond this README, check out our detailed guide
 - **[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
@@ -1460,8 +360,6 @@ 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
@@ -1473,12 +371,6 @@ This library was originally created by [Brecht Billiet](https://twitter.com/brec
 - **[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
@@ -1489,33 +381,6 @@ This project includes detailed instruction files designed to help developers mas
 - **[`.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.