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

package/README.md

@@ -54,7 +54,7 @@ npm install ngx-vest-forms
 > only(field); // only(undefined) safely runs all tests
 > ```
 >
-> Why: Conditional `only()` corrupts Vest's execution tracking and breaks `omitWhen` + `validationConfig`.
+> Why: Conditional `only()` breaks Vest's change detection mechanism and causes timing issues with `omitWhen` + `validationConfig` in ngx-vest-forms.
 > 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.
@@ -118,7 +118,7 @@ That's all you need. The directive automatically creates controls, wires validat
 - **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
+- **Error display helpers** — `ngx-control-wrapper` component (recommended) or `FormErrorDisplayDirective` as hostDirective for custom wrappers
 - **Cross-field dependencies** — `validationConfig` for field-to-field triggers, `ROOT_FORM` for form-level rules
 - **Utilities** — Field paths, field clearing, validation config builder
 
@@ -134,7 +134,7 @@ providers: [
   { provide: NGX_ERROR_DISPLAY_MODE_TOKEN, useValue: 'on-blur-or-submit' }
 ]
 
-// Or per-field via control wrapper
+// Recommended: Use ngx-control-wrapper component
 <ngx-control-wrapper [errorDisplayMode]="'on-blur'">
   <input name="email" [ngModel]="formValue().email" />
 </ngx-control-wrapper>
@@ -235,8 +235,12 @@ Manually trigger validation when form structure changes between **input fields a
 
 **NOT needed when**: Switching between different input fields (value changes trigger validation automatically).
 
+**IMPORTANT**: `triggerFormValidation()` only re-runs validation logic—it does NOT mark fields as touched or show errors.
+
+> **Note on form submission**: With the default `on-blur-or-submit` error display mode, errors are shown automatically when you submit via `(ngSubmit)`. The form automatically calls `markAllAsTouched()` internally. You only need to call `markAllAsTouched()` manually for special cases like multiple forms with one submit button.
+
 ```typescript
-// Example: Switching from input to paragraph
+// Structure change: Re-run validation
 @if (type() === 'typeA') {
   <input name="fieldA" [ngModel]="formValue().fieldA" />
 } @else {
@@ -245,7 +249,23 @@ Manually trigger validation when form structure changes between **input fields a
 
 onTypeChange(newType: string) {
   this.formValue.update(v => ({ ...v, type: newType }));
-  this.vestForm.triggerFormValidation();  // Only needed for structure changes
+  this.vestForm.triggerFormValidation();  // Re-runs validation, doesn't show errors
+}
+
+// Standard form submission - NO manual call needed!
+// Errors shown automatically via (ngSubmit) with default on-blur-or-submit mode
+<form ngxVestForm (ngSubmit)="save()">
+  <!-- ... -->
+  <button type="submit">Submit</button>
+</form>
+
+// Multiple forms with one button - NEED manual markAllAsTouched()
+submitBoth() {
+  this.form1().markAllAsTouched();
+  this.form2().markAllAsTouched();
+  if (this.form1().valid && this.form2().valid) {
+    // Submit logic
+  }
 }
 ```