From 2ee44c1b05f527999bf3be28d79cda10364f390c Mon Sep 17 00:00:00 2001
From: Simon Ihmig <simon.ihmig@gmail.com>
Date: Fri, 27 Jan 2023 11:04:07 +0100
Subject: [PATCH 1/8] Validate fields on blur/change

---
 ember-headless-form/package.json              |   1 +
 .../src/components/-private/types.ts          |   8 +-
 .../src/components/headless-form.hbs          |  11 +-
 .../src/components/headless-form.ts           |  86 +++++-
 pnpm-lock.yaml                                |  22 +-
 test-app/app/templates/index.hbs              |   7 +-
 .../headless-form-validation-test.gts         | 252 ++++++++++++++----
 7 files changed, 317 insertions(+), 70 deletions(-)

diff --git a/ember-headless-form/package.json b/ember-headless-form/package.json
index 5a7456f9..adf28dad 100644
--- a/ember-headless-form/package.json
+++ b/ember-headless-form/package.json
@@ -57,6 +57,7 @@
     "@types/ember__debug": "^4.0.0",
     "@types/ember__engine": "^4.0.0",
     "@types/ember__error": "^4.0.0",
+    "@types/ember__modifier": "^4.0.3",
     "@types/ember__object": "^4.0.0",
     "@types/ember__polyfills": "^4.0.0",
     "@types/ember__routing": "^4.0.0",
diff --git a/ember-headless-form/src/components/-private/types.ts b/ember-headless-form/src/components/-private/types.ts
index 32ac2266..5de01b16 100644
--- a/ember-headless-form/src/components/-private/types.ts
+++ b/ember-headless-form/src/components/-private/types.ts
@@ -55,7 +55,7 @@ export type FieldValidateCallback<
  * Internal structure to track used fields
  * @private
  */
-export interface FieldData<
+export interface FieldRegistrationData<
   DATA extends FormData,
   KEY extends FormKey<DATA> = FormKey<DATA>
 > {
@@ -69,7 +69,7 @@ export interface FieldData<
 export type RegisterFieldCallback<
   DATA extends FormData,
   KEY extends FormKey<DATA> = FormKey<DATA>
-> = (name: KEY, field: FieldData<DATA, KEY>) => void;
+> = (name: KEY, field: FieldRegistrationData<DATA, KEY>) => void;
 
 export type UnregisterFieldCallback<
   DATA extends FormData,
@@ -79,6 +79,4 @@ export type UnregisterFieldCallback<
 /**
  * Mapper type to construct subset of objects, whose keys are only strings (and not number or symbol)
  */
-export type OnlyStringKeys<T extends object> = {
-  [P in Extract<keyof T, string>]: T[P];
-};
+export type OnlyStringKeys<T extends object> = Pick<T, keyof T & string>;
diff --git a/ember-headless-form/src/components/headless-form.hbs b/ember-headless-form/src/components/headless-form.hbs
index b7462ef5..2b9a8ddd 100644
--- a/ember-headless-form/src/components/headless-form.hbs
+++ b/ember-headless-form/src/components/headless-form.hbs
@@ -1,11 +1,18 @@
-<form ...attributes {{on 'submit' this.onSubmit}}>
+{{! ignoring prettier here is need to *not* wrap the modifier usage below into a new line, making @glint-expect-error fail to work 🙈 }}
+{{! prettier-ignore }}
+<form
+  ...attributes
+  {{on 'submit' this.onSubmit}}
+  {{! @glint-expect-error: modifier helper not supported, see https://github.com/typed-ember/glint/issues/410 }}
+  {{(if this.fieldValidationEvent (modifier this.on this.fieldValidationEvent this.handleFieldValidation))}}
+>
   {{yield
     (hash
       field=(component
         (ensure-safe-component this.FieldComponent)
         data=this.internalData
         set=this.set
-        errors=this.lastValidationResult
+        errors=this.visibleErrors
         registerField=this.registerField
         unregisterField=this.unregisterField
       )
diff --git a/ember-headless-form/src/components/headless-form.ts b/ember-headless-form/src/components/headless-form.ts
index 324e4bcb..c3bcbad7 100644
--- a/ember-headless-form/src/components/headless-form.ts
+++ b/ember-headless-form/src/components/headless-form.ts
@@ -1,6 +1,7 @@
 import Component from '@glimmer/component';
 import { tracked } from '@glimmer/tracking';
 import { assert } from '@ember/debug';
+import { on } from '@ember/modifier';
 import { action } from '@ember/object';
 
 import { TrackedObject } from 'tracked-built-ins';
@@ -10,11 +11,13 @@ import FieldComponent from './-private/field';
 import type { HeadlessFormFieldComponentSignature } from './-private/field';
 import type {
   ErrorRecord,
-  FieldData,
+  FieldRegistrationData,
+  FieldValidateCallback,
   FormData,
   FormKey,
   FormValidateCallback,
   UserData,
+  ValidationError,
 } from './-private/types';
 import type { ComponentLike, WithBoundArgs } from '@glint/template';
 
@@ -37,7 +40,7 @@ export interface HeadlessFormComponentSignature<DATA extends UserData> {
     default: [
       {
         field: WithBoundArgs<
-          typeof FieldComponent<FormData<DATA>>,
+          typeof FieldComponent<DATA>,
           'data' | 'set' | 'errors' | 'registerField' | 'unregisterField'
         >;
       }
@@ -45,19 +48,34 @@ export interface HeadlessFormComponentSignature<DATA extends UserData> {
   };
 }
 
+class FieldData<
+  DATA extends FormData,
+  KEY extends FormKey<DATA> = FormKey<DATA>
+> {
+  constructor(fieldRegistration: FieldRegistrationData<DATA, KEY>) {
+    this.validate = fieldRegistration.validate;
+  }
+
+  @tracked validationEnabled = false;
+
+  validate?: FieldValidateCallback<DATA, KEY>;
+}
+
 export default class HeadlessFormComponent<
   DATA extends UserData
 > extends Component<HeadlessFormComponentSignature<DATA>> {
   FieldComponent: ComponentLike<HeadlessFormFieldComponentSignature<DATA>> =
     FieldComponent;
 
-  internalData: FormData<DATA> = new TrackedObject(
-    this.args.data ?? {}
-  ) as FormData<DATA>;
+  // we cannot use (modifier "on") directly in the template due to https://github.com/emberjs/ember.js/issues/19869
+  on = on;
+
+  internalData: DATA = new TrackedObject(this.args.data ?? {}) as DATA;
 
   fields = new Map<FormKey<FormData<DATA>>, FieldData<FormData<DATA>>>();
 
   @tracked lastValidationResult?: ErrorRecord<FormData<DATA>>;
+  @tracked showAllValidations = false;
 
   get validateOn(): ValidateOn {
     return this.args.validateOn ?? 'submit';
@@ -67,6 +85,16 @@ export default class HeadlessFormComponent<
     return this.args.revalidateOn ?? 'change';
   }
 
+  get fieldValidationEvent(): 'focusout' | 'change' | undefined {
+    const { validateOn } = this;
+
+    return validateOn === 'submit'
+      ? undefined
+      : validateOn === 'blur'
+      ? 'focusout'
+      : validateOn;
+  }
+
   get hasValidationErrors(): boolean {
     // Only consider validation errors for which we actually have a field rendered
     return this.lastValidationResult
@@ -106,11 +134,38 @@ export default class HeadlessFormComponent<
     return Object.keys(errors).length > 0 ? errors : undefined;
   }
 
+  get visibleErrors(): ErrorRecord<FormData<DATA>> | undefined {
+    if (!this.lastValidationResult) {
+      return undefined;
+    }
+
+    const visibleErrors: ErrorRecord<FormData<DATA>> = {};
+
+    for (const [field, errors] of Object.entries(this.lastValidationResult) as [
+      FormKey<FormData<DATA>>,
+      ValidationError<FormData<DATA>[FormKey<FormData<DATA>>]>[]
+    ][]) {
+      if (this.showErrorsFor(field)) {
+        visibleErrors[field] = errors;
+      }
+    }
+
+    return visibleErrors;
+  }
+
+  showErrorsFor(field: FormKey<FormData<DATA>>): boolean {
+    return (
+      this.showAllValidations ||
+      (this.fields.get(field)?.validationEnabled ?? false)
+    );
+  }
+
   @action
   async onSubmit(e: Event): Promise<void> {
     e.preventDefault();
 
     this.lastValidationResult = await this.validate();
+    this.showAllValidations = true;
 
     if (!this.hasValidationErrors) {
       this.args.onSubmit?.(this.internalData);
@@ -126,7 +181,7 @@ export default class HeadlessFormComponent<
   @action
   registerField(
     name: FormKey<FormData<DATA>>,
-    field: FieldData<FormData<DATA>>
+    field: FieldRegistrationData<FormData<DATA>>
   ): void {
     assert(
       `You passed @name="${String(
@@ -134,7 +189,7 @@ export default class HeadlessFormComponent<
       )}" to the form field, but this is already in use. Names of form fields must be unique!`,
       !this.fields.has(name)
     );
-    this.fields.set(name, field);
+    this.fields.set(name, new FieldData(field));
   }
 
   @action
@@ -146,4 +201,21 @@ export default class HeadlessFormComponent<
   set<KEY extends FormKey<FormData<DATA>>>(key: KEY, value: DATA[KEY]): void {
     this.internalData[key] = value;
   }
+
+  @action
+  async handleFieldValidation(e: Event): Promise<void> {
+    const { target } = e;
+    const { name } = target as HTMLInputElement;
+
+    if (name) {
+      const field = this.fields.get(name as FormKey<FormData<DATA>>);
+
+      if (field) {
+        this.lastValidationResult = await this.validate();
+        field.validationEnabled = true;
+      }
+    } else {
+      // @todo how to handle custom controls that don't emit focusout/change events from native form controls?
+    }
+  }
 }
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index d86fe8c3..a7e44acb 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -39,6 +39,7 @@ importers:
       '@types/ember__debug': ^4.0.0
       '@types/ember__engine': ^4.0.0
       '@types/ember__error': ^4.0.0
+      '@types/ember__modifier': ^4.0.3
       '@types/ember__object': ^4.0.0
       '@types/ember__polyfills': ^4.0.0
       '@types/ember__routing': ^4.0.0
@@ -90,6 +91,7 @@ importers:
       '@types/ember__debug': 4.0.3_@babel+core@7.20.12
       '@types/ember__engine': 4.0.4_@babel+core@7.20.12
       '@types/ember__error': 4.0.2
+      '@types/ember__modifier': 4.0.3_@babel+core@7.20.12
       '@types/ember__object': 4.0.5_@babel+core@7.20.12
       '@types/ember__polyfills': 4.0.1
       '@types/ember__routing': 4.0.12_@babel+core@7.20.12
@@ -2975,10 +2977,7 @@ packages:
   /@types/ember__controller/4.0.4:
     resolution: {integrity: sha512-+f0knTIJJkRX5xijeSI/n4FvLfhMFFxIxODyFFFFB483EryYuts3QzpTwU5D66WQ5rAbZvpPRXRMPTTCNJoUhg==}
     dependencies:
-      '@types/ember__object': 4.0.5
-    transitivePeerDependencies:
-      - '@babel/core'
-      - supports-color
+      '@types/ember__object': 4.0.5_@babel+core@7.20.12
     dev: true
 
   /@types/ember__controller/4.0.4_@babel+core@7.20.12:
@@ -3051,16 +3050,23 @@ packages:
       - supports-color
     dev: true
 
-  /@types/ember__object/4.0.5:
-    resolution: {integrity: sha512-gXrywWBwoW7J9y9yJqoZ0m1qtiyMdrEi29cJdF1xI2qOnMqaZeuSCMYaPQMsyq52/YnVIG2EnGzo6eUD57J4Nw==}
+  /@types/ember__modifier/4.0.3_@babel+core@7.20.12:
+    resolution: {integrity: sha512-2Z4ty8OZNVO/UkypnVMoqdp57OxRd48dko3wYzYMbjhR7Wi2Gtd374dLlhoA6WXcWnEyrz7SUCot8zyBpBZwfg==}
     dependencies:
-      '@types/ember': 4.0.3
-      '@types/rsvp': 4.0.4
+      '@types/ember': 4.0.3_@babel+core@7.20.12
+      '@types/ember__owner': 4.0.3
     transitivePeerDependencies:
       - '@babel/core'
       - supports-color
     dev: true
 
+  /@types/ember__object/4.0.5:
+    resolution: {integrity: sha512-gXrywWBwoW7J9y9yJqoZ0m1qtiyMdrEi29cJdF1xI2qOnMqaZeuSCMYaPQMsyq52/YnVIG2EnGzo6eUD57J4Nw==}
+    dependencies:
+      '@types/ember': 4.0.3_@babel+core@7.20.12
+      '@types/rsvp': 4.0.4
+    dev: true
+
   /@types/ember__object/4.0.5_@babel+core@7.20.12:
     resolution: {integrity: sha512-gXrywWBwoW7J9y9yJqoZ0m1qtiyMdrEi29cJdF1xI2qOnMqaZeuSCMYaPQMsyq52/YnVIG2EnGzo6eUD57J4Nw==}
     dependencies:
diff --git a/test-app/app/templates/index.hbs b/test-app/app/templates/index.hbs
index bc0e5162..192f9032 100644
--- a/test-app/app/templates/index.hbs
+++ b/test-app/app/templates/index.hbs
@@ -1,4 +1,9 @@
-<HeadlessForm @data={{this.data}} @onSubmit={{this.doSomething}} as |form|>
+<HeadlessForm
+  @data={{this.data}}
+  @validateOn='blur'
+  @onSubmit={{this.doSomething}}
+  as |form|
+>
   <form.field @name='name' as |field|>
     <field.label>Name</field.label>
     <field.input />
diff --git a/test-app/tests/integration/components/headless-form-validation-test.gts b/test-app/tests/integration/components/headless-form-validation-test.gts
index 46fc3d71..381c0430 100644
--- a/test-app/tests/integration/components/headless-form-validation-test.gts
+++ b/test-app/tests/integration/components/headless-form-validation-test.gts
@@ -2,7 +2,7 @@
 /* eslint-disable simple-import-sort/imports,padding-line-between-statements,decorator-position/decorator-position -- Can't fix these manually, without --fix working in .gts */
 
 import { tracked } from '@glimmer/tracking';
-import { click, fillIn, render, rerender } from '@ember/test-helpers';
+import { blur, click, fillIn, render, rerender } from '@ember/test-helpers';
 import { module, test } from 'qunit';
 
 import HeadlessForm from 'ember-headless-form/components/headless-form';
@@ -10,53 +10,69 @@ import sinon from 'sinon';
 import { setupRenderingTest } from 'test-app/tests/helpers';
 
 import type { RenderingTestContext } from '@ember/test-helpers';
+import type {
+  FormValidateCallback,
+  FieldValidateCallback,
+  ErrorRecord,
+  ValidationError,
+} from 'ember-headless-form/components/-private/types';
 
 module('Integration Component HeadlessForm > Validation', function (hooks) {
   setupRenderingTest(hooks);
 
-  interface FormData {
+  interface TestFormData {
     firstName?: string;
     lastName?: string;
   }
 
-  const validateFormCallbackSync = ({ firstName }: FormData) => {
-    const firstNameErrors = [];
-    if (firstName == undefined) {
-      firstNameErrors.push({
-        type: 'required',
-        value: firstName,
-        message: 'firstName is required!',
-      });
-    } else {
-      if (firstName.charAt(0).toUpperCase() !== firstName.charAt(0)) {
-        firstNameErrors.push({
-          type: 'uppercase',
-          value: firstName,
-          message: 'firstName must be upper case!',
+  const validateFormCallbackSync: FormValidateCallback<TestFormData> = (
+    data
+  ) => {
+    const errorRecord: ErrorRecord<TestFormData> = {};
+
+    for (const [field, value] of Object.entries(data)) {
+      const errors: ValidationError<string>[] = [];
+      if (value == undefined) {
+        errors.push({
+          type: 'required',
+          value,
+          message: `${field} is required!`,
         });
+      } else {
+        if (value.charAt(0).toUpperCase() !== value.charAt(0)) {
+          errors.push({
+            type: 'uppercase',
+            value,
+            message: `${field} must be upper case!`,
+          });
+        }
+
+        if (value.toLowerCase() === 'foo') {
+          errors.push({
+            type: 'notFoo',
+            value,
+            message: `Foo is an invalid ${field}!`,
+          });
+        }
       }
 
-      if (firstName.toLowerCase() === 'foo') {
-        firstNameErrors.push({
-          type: 'notFoo',
-          value: firstName,
-          message: 'Foo is an invalid firstName!',
-        });
+      if (errors.length > 0) {
+        errorRecord[field as keyof TestFormData] = errors;
       }
     }
 
-    return firstNameErrors.length > 0
-      ? { firstName: firstNameErrors }
-      : undefined;
+    return errorRecord;
   };
 
-  const validateFormCallbackAsync = async (data: FormData) => {
+  const validateFormCallbackAsync: FormValidateCallback<TestFormData> = async (
+    data
+  ) => {
     return await validateFormCallbackSync(data);
   };
 
-  const validateFieldCallbackSync = (
-    value: string | undefined,
-    field: string
+  const validateFieldCallbackSync: FieldValidateCallback<TestFormData> = (
+    value,
+    field
   ) => {
     const errors = [];
     if (value == undefined) {
@@ -86,11 +102,10 @@ module('Integration Component HeadlessForm > Validation', function (hooks) {
     return errors.length > 0 ? errors : undefined;
   };
 
-  const validateFieldCallbackAsync = async (
-    value: string | undefined,
-    field: string
-  ) => {
-    return await validateFieldCallbackSync(value, field);
+  const validateFieldCallbackAsync: FieldValidateCallback<
+    TestFormData
+  > = async (value, field, data) => {
+    return await validateFieldCallbackSync(value, field, data);
   };
 
   module('form @validation callback', function () {
@@ -100,7 +115,7 @@ module('Integration Component HeadlessForm > Validation', function (hooks) {
     ].forEach(({ testType, validateCallback }) =>
       module(testType, function () {
         test('validation callback is called on submit', async function (assert) {
-          const data: FormData = { firstName: 'Tony', lastName: 'Ward' };
+          const data: TestFormData = { firstName: 'Tony', lastName: 'Ward' };
           const validateCallback = sinon.spy();
 
           await render(<template>
@@ -130,7 +145,7 @@ module('Integration Component HeadlessForm > Validation', function (hooks) {
         });
 
         test('onSubmit is not called when validation fails', async function (assert) {
-          const data: FormData = { firstName: 'Foo', lastName: 'Smith' };
+          const data: TestFormData = { firstName: 'Foo', lastName: 'Smith' };
           const submitHandler = sinon.spy();
 
           await render(<template>
@@ -154,7 +169,7 @@ module('Integration Component HeadlessForm > Validation', function (hooks) {
         });
 
         test('onInvalid is called when validation fails', async function (assert) {
-          const data: FormData = { firstName: 'Foo', lastName: 'Smith' };
+          const data: TestFormData = { firstName: 'Foo', lastName: 'Smith' };
           const invalidHandler = sinon.spy();
 
           await render(<template>
@@ -189,7 +204,7 @@ module('Integration Component HeadlessForm > Validation', function (hooks) {
         });
 
         test('onSubmit is called when validation passes', async function (assert) {
-          const data: FormData = {};
+          const data: TestFormData = {};
           const submitHandler = sinon.spy();
 
           await render(<template>
@@ -219,7 +234,7 @@ module('Integration Component HeadlessForm > Validation', function (hooks) {
         });
 
         test('validation errors are exposed as field.errors on submit', async function (assert) {
-          const data: FormData = { firstName: 'Foo', lastName: 'Smith' };
+          const data: TestFormData = { firstName: 'Foo', lastName: 'Smith' };
 
           await render(<template>
             <HeadlessForm
@@ -268,7 +283,7 @@ module('Integration Component HeadlessForm > Validation', function (hooks) {
         });
 
         test('field.errors is associated to input', async function (this: RenderingTestContext, assert) {
-          const data: FormData = { firstName: 'Foo' };
+          const data: TestFormData = { firstName: 'Foo' };
 
           await render(<template>
             <HeadlessForm
@@ -321,7 +336,7 @@ module('Integration Component HeadlessForm > Validation', function (hooks) {
         });
 
         test('field.errors renders all error messages in non-block mode', async function (assert) {
-          const data: FormData = { firstName: 'foo' };
+          const data: TestFormData = { firstName: 'foo' };
 
           await render(<template>
             <HeadlessForm
@@ -349,7 +364,7 @@ module('Integration Component HeadlessForm > Validation', function (hooks) {
         });
 
         test('field.errors yields errors in block mode', async function (assert) {
-          const data: FormData = { firstName: 'foo' };
+          const data: TestFormData = { firstName: 'foo' };
 
           await render(<template>
             <HeadlessForm
@@ -421,7 +436,7 @@ module('Integration Component HeadlessForm > Validation', function (hooks) {
         });
 
         test('validation errors for dynamically removed fields are not taken into account', async function (assert) {
-          const data: FormData = {};
+          const data: TestFormData = {};
           const submitHandler = sinon.spy();
           // This validation callback intentionally always returns an error, as it should be ignored
           const validateCallback = () => ({
@@ -527,7 +542,7 @@ module('Integration Component HeadlessForm > Validation', function (hooks) {
         });
 
         test('validation errors mark the control as invalid', async function (assert) {
-          const data: FormData = { firstName: 'Foo' };
+          const data: TestFormData = { firstName: 'Foo' };
 
           await render(<template>
             <HeadlessForm
@@ -558,7 +573,7 @@ module('Integration Component HeadlessForm > Validation', function (hooks) {
     ].forEach(({ testType, validateCallback }) =>
       module(testType, function () {
         test('validation callback is called on submit', async function (assert) {
-          const data: FormData = { firstName: 'Tony', lastName: 'Ward' };
+          const data: TestFormData = { firstName: 'Tony', lastName: 'Ward' };
           const validateCallback = sinon.spy();
 
           await render(<template>
@@ -588,7 +603,7 @@ module('Integration Component HeadlessForm > Validation', function (hooks) {
         });
 
         test('onSubmit is not called when validation fails', async function (assert) {
-          const data: FormData = { firstName: 'Foo', lastName: 'Smith' };
+          const data: TestFormData = { firstName: 'Foo', lastName: 'Smith' };
           const submitHandler = sinon.spy();
 
           await render(<template>
@@ -611,7 +626,7 @@ module('Integration Component HeadlessForm > Validation', function (hooks) {
         });
 
         test('validation errors are exposed as field.errors on submit', async function (assert) {
-          const data: FormData = { firstName: 'Foo', lastName: 'Smith' };
+          const data: TestFormData = { firstName: 'Foo', lastName: 'Smith' };
 
           await render(<template>
             <HeadlessForm @data={{data}} as |form|>
@@ -830,4 +845,147 @@ module('Integration Component HeadlessForm > Validation', function (hooks) {
       })
     );
   });
+
+  module('@validateOn="blur"', function () {
+    test('form validation callback is called on blur', async function (assert) {
+      const data: TestFormData = { firstName: 'Tony', lastName: 'Ward' };
+      const validateCallback = sinon.spy();
+
+      await render(<template>
+        <HeadlessForm
+          @data={{data}}
+          @validateOn="blur"
+          @validate={{validateCallback}}
+          as |form|
+        >
+          <form.field @name="firstName" as |field|>
+            <field.label>First Name</field.label>
+            <field.input data-test-first-name />
+          </form.field>
+          <form.field @name="lastName" as |field|>
+            <field.label>Last Name</field.label>
+            <field.input data-test-last-name />
+          </form.field>
+          <button type="submit" data-test-submit>Submit</button>
+        </HeadlessForm>
+      </template>);
+
+      await fillIn('[data-test-first-name]', 'Foo');
+
+      assert.false(
+        validateCallback.called,
+        '@validate is not called while typing'
+      );
+
+      await blur('[data-test-first-name]');
+
+      assert.true(
+        validateCallback.calledWith({ ...data, firstName: 'Foo' }),
+        '@validate is called with form data'
+      );
+    });
+
+    test('field validation callback is called on blur', async function (assert) {
+      const data: TestFormData = { firstName: 'Tony', lastName: 'Ward' };
+      const validateCallback = sinon.spy();
+
+      await render(<template>
+        <HeadlessForm @data={{data}} @validateOn="blur" as |form|>
+          <form.field
+            @name="firstName"
+            @validate={{validateCallback}}
+            as |field|
+          >
+            <field.label>First Name</field.label>
+            <field.input data-test-first-name />
+          </form.field>
+          <form.field @name="lastName" as |field|>
+            <field.label>Last Name</field.label>
+            <field.input data-test-last-name />
+          </form.field>
+          <button type="submit" data-test-submit>Submit</button>
+        </HeadlessForm>
+      </template>);
+
+      await fillIn('[data-test-first-name]', 'Foo');
+
+      assert.false(
+        validateCallback.called,
+        '@validate is not called while typing'
+      );
+
+      await blur('[data-test-first-name]');
+
+      assert.true(
+        validateCallback.calledWith('Foo', 'firstName', {
+          ...data,
+          firstName: 'Foo',
+        }),
+        '@validate is called with form data'
+      );
+    });
+
+    test('validation errors are exposed as field.errors on blur', async function (assert) {
+      const data: TestFormData = { firstName: 'Foo', lastName: 'Foo' };
+
+      await render(<template>
+        <HeadlessForm
+          @data={{data}}
+          @validateOn="blur"
+          @validate={{validateFormCallbackSync}}
+          as |form|
+        >
+          <form.field @name="firstName" as |field|>
+            <field.label>First Name</field.label>
+            <field.input data-test-first-name />
+            <field.errors data-test-first-name-errors />
+          </form.field>
+          <form.field @name="lastName" as |field|>
+            <field.label>Last Name</field.label>
+            <field.input data-test-last-name />
+            <field.errors data-test-last-name-errors />
+          </form.field>
+          <button type="submit" data-test-submit>Submit</button>
+        </HeadlessForm>
+      </template>);
+
+      assert
+        .dom('[data-test-first-name-errors]')
+        .doesNotExist(
+          'validation errors are not rendered before validation happens'
+        );
+      assert
+        .dom('[data-test-last-name-errors]')
+        .doesNotExist(
+          'validation errors are not rendered before validation happens'
+        );
+
+      await fillIn('[data-test-first-name]', 'Foo');
+
+      assert
+        .dom('[data-test-first-name-errors]')
+        .doesNotExist(
+          'validation errors are not rendered before validation happens'
+        );
+      assert
+        .dom('[data-test-last-name-errors]')
+        .doesNotExist(
+          'validation errors are not rendered before validation happens'
+        );
+
+      await blur('[data-test-first-name]');
+
+      assert
+        .dom('[data-test-first-name-errors]')
+        .exists(
+          { count: 1 },
+          'validation errors appear on blur when validation fails'
+        );
+      assert
+        .dom('[data-test-last-name-errors]')
+        .doesNotExist(
+          'validation errors are not rendered for untouched fields'
+        );
+    });
+  });
 });

From f7a640c6165ccbd20bd140fe4c11310af110e373 Mon Sep 17 00:00:00 2001
From: Simon Ihmig <simon.ihmig@gmail.com>
Date: Fri, 27 Jan 2023 18:50:46 +0100
Subject: [PATCH 2/8] Add tests for `@validateOn="change"`

---
 .../headless-form-validation-test.gts         | 374 ++++++++++++------
 1 file changed, 246 insertions(+), 128 deletions(-)

diff --git a/test-app/tests/integration/components/headless-form-validation-test.gts b/test-app/tests/integration/components/headless-form-validation-test.gts
index 381c0430..2b54a570 100644
--- a/test-app/tests/integration/components/headless-form-validation-test.gts
+++ b/test-app/tests/integration/components/headless-form-validation-test.gts
@@ -846,146 +846,264 @@ module('Integration Component HeadlessForm > Validation', function (hooks) {
     );
   });
 
-  module('@validateOn="blur"', function () {
-    test('form validation callback is called on blur', async function (assert) {
-      const data: TestFormData = { firstName: 'Tony', lastName: 'Ward' };
-      const validateCallback = sinon.spy();
-
-      await render(<template>
-        <HeadlessForm
-          @data={{data}}
-          @validateOn="blur"
-          @validate={{validateCallback}}
-          as |form|
-        >
-          <form.field @name="firstName" as |field|>
-            <field.label>First Name</field.label>
-            <field.input data-test-first-name />
-          </form.field>
-          <form.field @name="lastName" as |field|>
-            <field.label>Last Name</field.label>
-            <field.input data-test-last-name />
-          </form.field>
-          <button type="submit" data-test-submit>Submit</button>
-        </HeadlessForm>
-      </template>);
-
-      await fillIn('[data-test-first-name]', 'Foo');
-
-      assert.false(
-        validateCallback.called,
-        '@validate is not called while typing'
-      );
-
-      await blur('[data-test-first-name]');
-
-      assert.true(
-        validateCallback.calledWith({ ...data, firstName: 'Foo' }),
-        '@validate is called with form data'
-      );
-    });
-
-    test('field validation callback is called on blur', async function (assert) {
-      const data: TestFormData = { firstName: 'Tony', lastName: 'Ward' };
-      const validateCallback = sinon.spy();
-
-      await render(<template>
-        <HeadlessForm @data={{data}} @validateOn="blur" as |form|>
-          <form.field
-            @name="firstName"
+  module(`@validateOn`, function () {
+    module('blur', function () {
+      test('form validation callback is called on blur', async function (assert) {
+        const data: TestFormData = { firstName: 'Tony', lastName: 'Ward' };
+        const validateCallback = sinon.spy();
+
+        await render(<template>
+          <HeadlessForm
+            @data={{data}}
+            @validateOn="blur"
             @validate={{validateCallback}}
-            as |field|
+            as |form|
           >
-            <field.label>First Name</field.label>
-            <field.input data-test-first-name />
-          </form.field>
-          <form.field @name="lastName" as |field|>
-            <field.label>Last Name</field.label>
-            <field.input data-test-last-name />
-          </form.field>
-          <button type="submit" data-test-submit>Submit</button>
-        </HeadlessForm>
-      </template>);
-
-      await fillIn('[data-test-first-name]', 'Foo');
-
-      assert.false(
-        validateCallback.called,
-        '@validate is not called while typing'
-      );
-
-      await blur('[data-test-first-name]');
-
-      assert.true(
-        validateCallback.calledWith('Foo', 'firstName', {
-          ...data,
-          firstName: 'Foo',
-        }),
-        '@validate is called with form data'
-      );
-    });
-
-    test('validation errors are exposed as field.errors on blur', async function (assert) {
-      const data: TestFormData = { firstName: 'Foo', lastName: 'Foo' };
-
-      await render(<template>
-        <HeadlessForm
-          @data={{data}}
-          @validateOn="blur"
-          @validate={{validateFormCallbackSync}}
-          as |form|
-        >
-          <form.field @name="firstName" as |field|>
-            <field.label>First Name</field.label>
-            <field.input data-test-first-name />
-            <field.errors data-test-first-name-errors />
-          </form.field>
-          <form.field @name="lastName" as |field|>
-            <field.label>Last Name</field.label>
-            <field.input data-test-last-name />
-            <field.errors data-test-last-name-errors />
-          </form.field>
-          <button type="submit" data-test-submit>Submit</button>
-        </HeadlessForm>
-      </template>);
-
-      assert
-        .dom('[data-test-first-name-errors]')
-        .doesNotExist(
-          'validation errors are not rendered before validation happens'
+            <form.field @name="firstName" as |field|>
+              <field.label>First Name</field.label>
+              <field.input data-test-first-name />
+            </form.field>
+            <form.field @name="lastName" as |field|>
+              <field.label>Last Name</field.label>
+              <field.input data-test-last-name />
+            </form.field>
+            <button type="submit" data-test-submit>Submit</button>
+          </HeadlessForm>
+        </template>);
+
+        await fillIn('[data-test-first-name]', 'Foo');
+
+        assert.false(
+          validateCallback.called,
+          '@validate is not called while typing'
         );
-      assert
-        .dom('[data-test-last-name-errors]')
-        .doesNotExist(
-          'validation errors are not rendered before validation happens'
+
+        await blur('[data-test-first-name]');
+
+        assert.true(
+          validateCallback.calledWith({ ...data, firstName: 'Foo' }),
+          '@validate is called with form data'
         );
+      });
 
-      await fillIn('[data-test-first-name]', 'Foo');
+      test('field validation callback is called on blur', async function (assert) {
+        const data: TestFormData = { firstName: 'Tony', lastName: 'Ward' };
+        const validateCallback = sinon.spy();
 
-      assert
-        .dom('[data-test-first-name-errors]')
-        .doesNotExist(
-          'validation errors are not rendered before validation happens'
+        await render(<template>
+          <HeadlessForm @data={{data}} @validateOn="blur" as |form|>
+            <form.field
+              @name="firstName"
+              @validate={{validateCallback}}
+              as |field|
+            >
+              <field.label>First Name</field.label>
+              <field.input data-test-first-name />
+            </form.field>
+            <form.field @name="lastName" as |field|>
+              <field.label>Last Name</field.label>
+              <field.input data-test-last-name />
+            </form.field>
+            <button type="submit" data-test-submit>Submit</button>
+          </HeadlessForm>
+        </template>);
+
+        await fillIn('[data-test-first-name]', 'Foo');
+
+        assert.false(
+          validateCallback.called,
+          '@validate is not called while typing'
         );
-      assert
-        .dom('[data-test-last-name-errors]')
-        .doesNotExist(
-          'validation errors are not rendered before validation happens'
+
+        await blur('[data-test-first-name]');
+
+        assert.true(
+          validateCallback.calledWith('Foo', 'firstName', {
+            ...data,
+            firstName: 'Foo',
+          }),
+          '@validate is called with form data'
         );
+      });
+
+      test('validation errors are exposed as field.errors on blur', async function (assert) {
+        const data: TestFormData = { firstName: 'Foo', lastName: 'Foo' };
+
+        await render(<template>
+          <HeadlessForm
+            @data={{data}}
+            @validateOn="blur"
+            @validate={{validateFormCallbackSync}}
+            as |form|
+          >
+            <form.field @name="firstName" as |field|>
+              <field.label>First Name</field.label>
+              <field.input data-test-first-name />
+              <field.errors data-test-first-name-errors />
+            </form.field>
+            <form.field @name="lastName" as |field|>
+              <field.label>Last Name</field.label>
+              <field.input data-test-last-name />
+              <field.errors data-test-last-name-errors />
+            </form.field>
+            <button type="submit" data-test-submit>Submit</button>
+          </HeadlessForm>
+        </template>);
+
+        assert
+          .dom('[data-test-first-name-errors]')
+          .doesNotExist(
+            'validation errors are not rendered before validation happens'
+          );
+        assert
+          .dom('[data-test-last-name-errors]')
+          .doesNotExist(
+            'validation errors are not rendered before validation happens'
+          );
+
+        await fillIn('[data-test-first-name]', 'Foo');
+
+        assert
+          .dom('[data-test-first-name-errors]')
+          .doesNotExist(
+            'validation errors are not rendered before validation happens'
+          );
+        assert
+          .dom('[data-test-last-name-errors]')
+          .doesNotExist(
+            'validation errors are not rendered before validation happens'
+          );
+
+        await blur('[data-test-first-name]');
 
-      await blur('[data-test-first-name]');
+        assert
+          .dom('[data-test-first-name-errors]')
+          .exists(
+            { count: 1 },
+            'validation errors appear on blur when validation fails'
+          );
+        assert
+          .dom('[data-test-last-name-errors]')
+          .doesNotExist(
+            'validation errors are not rendered for untouched fields'
+          );
+      });
+    });
+
+    module('change', function () {
+      test('form validation callback is called on change', async function (assert) {
+        const data: TestFormData = { firstName: 'Tony', lastName: 'Ward' };
+        const validateCallback = sinon.spy();
 
-      assert
-        .dom('[data-test-first-name-errors]')
-        .exists(
-          { count: 1 },
-          'validation errors appear on blur when validation fails'
+        await render(<template>
+          <HeadlessForm
+            @data={{data}}
+            @validateOn="change"
+            @validate={{validateCallback}}
+            as |form|
+          >
+            <form.field @name="firstName" as |field|>
+              <field.label>First Name</field.label>
+              <field.input data-test-first-name />
+            </form.field>
+            <form.field @name="lastName" as |field|>
+              <field.label>Last Name</field.label>
+              <field.input data-test-last-name />
+            </form.field>
+            <button type="submit" data-test-submit>Submit</button>
+          </HeadlessForm>
+        </template>);
+
+        await fillIn('[data-test-first-name]', 'Foo');
+
+        assert.true(
+          validateCallback.calledWith({ ...data, firstName: 'Foo' }),
+          '@validate is called with form data'
         );
-      assert
-        .dom('[data-test-last-name-errors]')
-        .doesNotExist(
-          'validation errors are not rendered for untouched fields'
+      });
+
+      test('field validation callback is called on change', async function (assert) {
+        const data: TestFormData = { firstName: 'Tony', lastName: 'Ward' };
+        const validateCallback = sinon.spy();
+
+        await render(<template>
+          <HeadlessForm @data={{data}} @validateOn="change" as |form|>
+            <form.field
+              @name="firstName"
+              @validate={{validateCallback}}
+              as |field|
+            >
+              <field.label>First Name</field.label>
+              <field.input data-test-first-name />
+            </form.field>
+            <form.field @name="lastName" as |field|>
+              <field.label>Last Name</field.label>
+              <field.input data-test-last-name />
+            </form.field>
+            <button type="submit" data-test-submit>Submit</button>
+          </HeadlessForm>
+        </template>);
+
+        await fillIn('[data-test-first-name]', 'Foo');
+
+        assert.true(
+          validateCallback.calledWith('Foo', 'firstName', {
+            ...data,
+            firstName: 'Foo',
+          }),
+          '@validate is called with form data'
         );
+      });
+
+      test('validation errors are exposed as field.errors on change', async function (assert) {
+        const data: TestFormData = { firstName: 'Foo', lastName: 'Foo' };
+
+        await render(<template>
+          <HeadlessForm
+            @data={{data}}
+            @validateOn="change"
+            @validate={{validateFormCallbackSync}}
+            as |form|
+          >
+            <form.field @name="firstName" as |field|>
+              <field.label>First Name</field.label>
+              <field.input data-test-first-name />
+              <field.errors data-test-first-name-errors />
+            </form.field>
+            <form.field @name="lastName" as |field|>
+              <field.label>Last Name</field.label>
+              <field.input data-test-last-name />
+              <field.errors data-test-last-name-errors />
+            </form.field>
+            <button type="submit" data-test-submit>Submit</button>
+          </HeadlessForm>
+        </template>);
+
+        assert
+          .dom('[data-test-first-name-errors]')
+          .doesNotExist(
+            'validation errors are not rendered before validation happens'
+          );
+        assert
+          .dom('[data-test-last-name-errors]')
+          .doesNotExist(
+            'validation errors are not rendered before validation happens'
+          );
+
+        await fillIn('[data-test-first-name]', 'Foo');
+
+        assert
+          .dom('[data-test-first-name-errors]')
+          .exists(
+            { count: 1 },
+            'validation errors appear on blur when validation fails'
+          );
+        assert
+          .dom('[data-test-last-name-errors]')
+          .doesNotExist(
+            'validation errors are not rendered for untouched fields'
+          );
+      });
     });
   });
 });

From 89ed939a90731394170e67c02042330bdd03f513 Mon Sep 17 00:00:00 2001
From: Simon Ihmig <simon.ihmig@gmail.com>
Date: Mon, 30 Jan 2023 14:33:48 +0100
Subject: [PATCH 3/8] Add `@revalidationOn` support

---
 .../src/components/headless-form.hbs          |   2 +
 .../src/components/headless-form.ts           |  25 +
 .../headless-form-validation-test.gts         | 517 +++++++++++++++++-
 3 files changed, 542 insertions(+), 2 deletions(-)

diff --git a/ember-headless-form/src/components/headless-form.hbs b/ember-headless-form/src/components/headless-form.hbs
index 2b9a8ddd..90dec217 100644
--- a/ember-headless-form/src/components/headless-form.hbs
+++ b/ember-headless-form/src/components/headless-form.hbs
@@ -5,6 +5,8 @@
   {{on 'submit' this.onSubmit}}
   {{! @glint-expect-error: modifier helper not supported, see https://github.com/typed-ember/glint/issues/410 }}
   {{(if this.fieldValidationEvent (modifier this.on this.fieldValidationEvent this.handleFieldValidation))}}
+  {{! @glint-expect-error: modifier helper not supported, see https://github.com/typed-ember/glint/issues/410 }}
+  {{(if this.fieldRevalidationEvent (modifier this.on this.fieldRevalidationEvent this.handleFieldRevalidation))}}
 >
   {{yield
     (hash
diff --git a/ember-headless-form/src/components/headless-form.ts b/ember-headless-form/src/components/headless-form.ts
index c3bcbad7..2133e5b7 100644
--- a/ember-headless-form/src/components/headless-form.ts
+++ b/ember-headless-form/src/components/headless-form.ts
@@ -95,6 +95,16 @@ export default class HeadlessFormComponent<
       : validateOn;
   }
 
+  get fieldRevalidationEvent(): 'focusout' | 'change' | undefined {
+    const { revalidateOn } = this;
+
+    return revalidateOn === 'submit'
+      ? undefined
+      : revalidateOn === 'blur'
+      ? 'focusout'
+      : revalidateOn;
+  }
+
   get hasValidationErrors(): boolean {
     // Only consider validation errors for which we actually have a field rendered
     return this.lastValidationResult
@@ -218,4 +228,19 @@ export default class HeadlessFormComponent<
       // @todo how to handle custom controls that don't emit focusout/change events from native form controls?
     }
   }
+
+  @action
+  async handleFieldRevalidation(e: Event): Promise<void> {
+    const { target } = e;
+    const { name } = target as HTMLInputElement;
+
+    if (name) {
+      if (this.showErrorsFor(name as FormKey<FormData<DATA>>)) {
+        this.lastValidationResult = await this.validate();
+        // field.validationEnabled = true;
+      }
+    } else {
+      // @todo how to handle custom controls that don't emit focusout/change events from native form controls?
+    }
+  }
 }
diff --git a/test-app/tests/integration/components/headless-form-validation-test.gts b/test-app/tests/integration/components/headless-form-validation-test.gts
index 2b54a570..812b4eaa 100644
--- a/test-app/tests/integration/components/headless-form-validation-test.gts
+++ b/test-app/tests/integration/components/headless-form-validation-test.gts
@@ -884,6 +884,13 @@ module('Integration Component HeadlessForm > Validation', function (hooks) {
           validateCallback.calledWith({ ...data, firstName: 'Foo' }),
           '@validate is called with form data'
         );
+
+        await click('[data-test-submit]');
+
+        assert.true(
+          validateCallback.calledTwice,
+          '@validate is called again on submit'
+        );
       });
 
       test('field validation callback is called on blur', async function (assert) {
@@ -924,10 +931,17 @@ module('Integration Component HeadlessForm > Validation', function (hooks) {
           }),
           '@validate is called with form data'
         );
+
+        await click('[data-test-submit]');
+
+        assert.true(
+          validateCallback.calledTwice,
+          '@validate is called again on submit'
+        );
       });
 
       test('validation errors are exposed as field.errors on blur', async function (assert) {
-        const data: TestFormData = { firstName: 'Foo', lastName: 'Foo' };
+        const data: TestFormData = { firstName: 'Tony', lastName: 'Foo' };
 
         await render(<template>
           <HeadlessForm
@@ -1020,6 +1034,13 @@ module('Integration Component HeadlessForm > Validation', function (hooks) {
           validateCallback.calledWith({ ...data, firstName: 'Foo' }),
           '@validate is called with form data'
         );
+
+        await click('[data-test-submit]');
+
+        assert.true(
+          validateCallback.calledTwice,
+          '@validate is called again on submit'
+        );
       });
 
       test('field validation callback is called on change', async function (assert) {
@@ -1053,10 +1074,17 @@ module('Integration Component HeadlessForm > Validation', function (hooks) {
           }),
           '@validate is called with form data'
         );
+
+        await click('[data-test-submit]');
+
+        assert.true(
+          validateCallback.calledTwice,
+          '@validate is called again on submit'
+        );
       });
 
       test('validation errors are exposed as field.errors on change', async function (assert) {
-        const data: TestFormData = { firstName: 'Foo', lastName: 'Foo' };
+        const data: TestFormData = { firstName: 'Tony', lastName: 'Foo' };
 
         await render(<template>
           <HeadlessForm
@@ -1106,4 +1134,489 @@ module('Integration Component HeadlessForm > Validation', function (hooks) {
       });
     });
   });
+
+  module(`@revalidateOn`, function () {
+    module('blur', function () {
+      test('form validation callback is called on blur', async function (assert) {
+        const data: TestFormData = { firstName: 'Tony', lastName: 'Ward' };
+        const validateCallback = sinon.spy();
+
+        await render(<template>
+          <HeadlessForm
+            @data={{data}}
+            @revalidateOn="blur"
+            @validate={{validateCallback}}
+            as |form|
+          >
+            <form.field @name="firstName" as |field|>
+              <field.label>First Name</field.label>
+              <field.input data-test-first-name />
+            </form.field>
+            <form.field @name="lastName" as |field|>
+              <field.label>Last Name</field.label>
+              <field.input data-test-last-name />
+            </form.field>
+            <button type="submit" data-test-submit>Submit</button>
+          </HeadlessForm>
+        </template>);
+
+        await fillIn('[data-test-first-name]', 'Foo');
+
+        assert.false(
+          validateCallback.called,
+          '@validate is not called while typing'
+        );
+
+        await blur('[data-test-first-name]');
+
+        assert.false(
+          validateCallback.called,
+          '@validate is not called until submitting'
+        );
+
+        await click('[data-test-submit]');
+
+        assert.true(
+          validateCallback.calledOnce,
+          '@validate is called when submitting'
+        );
+        assert.true(
+          validateCallback.calledWith({ ...data, firstName: 'Foo' }),
+          '@validate is called with form data'
+        );
+
+        await fillIn('[data-test-first-name]', 'Tony');
+
+        assert.false(
+          validateCallback.calledTwice,
+          '@validate is not called while typing'
+        );
+
+        await blur('[data-test-first-name]');
+
+        assert.true(
+          validateCallback.calledTwice,
+          '@validate is called for revalidation on blur'
+        );
+        assert.true(
+          validateCallback
+            .getCall(1)
+            .calledWith({ ...data, firstName: 'Tony' }),
+          '@validate is called with form data'
+        );
+      });
+
+      test('field validation callback is called on blur', async function (assert) {
+        const data: TestFormData = { firstName: 'Tony', lastName: 'Ward' };
+        const validateCallback = sinon.spy();
+
+        await render(<template>
+          <HeadlessForm @data={{data}} @revalidateOn="blur" as |form|>
+            <form.field
+              @name="firstName"
+              @validate={{validateCallback}}
+              as |field|
+            >
+              <field.label>First Name</field.label>
+              <field.input data-test-first-name />
+            </form.field>
+            <form.field @name="lastName" as |field|>
+              <field.label>Last Name</field.label>
+              <field.input data-test-last-name />
+            </form.field>
+            <button type="submit" data-test-submit>Submit</button>
+          </HeadlessForm>
+        </template>);
+
+        await fillIn('[data-test-first-name]', 'Foo');
+
+        assert.false(
+          validateCallback.called,
+          '@validate is not called while typing'
+        );
+
+        await blur('[data-test-first-name]');
+
+        assert.false(
+          validateCallback.called,
+          '@validate is not called until submitting'
+        );
+
+        await click('[data-test-submit]');
+
+        assert.true(
+          validateCallback.calledOnce,
+          '@validate is called when submitting'
+        );
+        assert.true(
+          validateCallback.calledWith('Foo', 'firstName', {
+            ...data,
+            firstName: 'Foo',
+          }),
+          '@validate is called with form data'
+        );
+
+        await fillIn('[data-test-first-name]', 'Tony');
+
+        assert.false(
+          validateCallback.calledTwice,
+          '@validate is not called while typing'
+        );
+
+        await blur('[data-test-first-name]');
+
+        assert.true(
+          validateCallback.calledTwice,
+          '@validate is called for revalidation on blur'
+        );
+        assert.true(
+          validateCallback.getCall(1).calledWith('Tony', 'firstName', {
+            ...data,
+            firstName: 'Tony',
+          }),
+          '@validate is called with form data'
+        );
+      });
+
+      test('validation errors are exposed as field.errors on blur', async function (assert) {
+        const data: TestFormData = { firstName: 'Tony', lastName: 'Foo' };
+
+        await render(<template>
+          <HeadlessForm
+            @data={{data}}
+            @revalidateOn="blur"
+            @validate={{validateFormCallbackSync}}
+            as |form|
+          >
+            <form.field @name="firstName" as |field|>
+              <field.label>First Name</field.label>
+              <field.input data-test-first-name />
+              <field.errors data-test-first-name-errors />
+            </form.field>
+            <form.field @name="lastName" as |field|>
+              <field.label>Last Name</field.label>
+              <field.input data-test-last-name />
+              <field.errors data-test-last-name-errors />
+            </form.field>
+            <button type="submit" data-test-submit>Submit</button>
+          </HeadlessForm>
+        </template>);
+
+        assert
+          .dom('[data-test-first-name-errors]')
+          .doesNotExist(
+            'validation errors are not rendered before initial validation happens'
+          );
+        assert
+          .dom('[data-test-last-name-errors]')
+          .doesNotExist(
+            'validation errors are not rendered before initial validation happens'
+          );
+
+        await fillIn('[data-test-first-name]', 'Foo');
+
+        assert
+          .dom('[data-test-first-name-errors]')
+          .doesNotExist(
+            'validation errors are not rendered before initial validation happens'
+          );
+        assert
+          .dom('[data-test-last-name-errors]')
+          .doesNotExist(
+            'validation errors are not rendered before initial validation happens'
+          );
+
+        await blur('[data-test-first-name]');
+
+        assert
+          .dom('[data-test-first-name-errors]')
+          .doesNotExist(
+            'validation errors are not rendered before initial validation happens'
+          );
+        assert
+          .dom('[data-test-last-name-errors]')
+          .doesNotExist(
+            'validation errors are not rendered before initial validation happens'
+          );
+
+        await click('[data-test-submit]');
+
+        assert
+          .dom('[data-test-first-name-errors]')
+          .exists(
+            { count: 1 },
+            'validation errors appear on submit when validation fails'
+          );
+        assert
+          .dom('[data-test-last-name-errors]')
+          .exists(
+            { count: 1 },
+            'validation errors appear on submit when validation fails'
+          );
+
+        await fillIn('[data-test-first-name]', 'Tony');
+
+        assert
+          .dom('[data-test-first-name-errors]')
+          .exists(
+            { count: 1 },
+            'validation errors do not disappear until revalidation happens'
+          );
+        assert
+          .dom('[data-test-last-name-errors]')
+          .exists(
+            { count: 1 },
+            'validation errors do not disappear until revalidation happens'
+          );
+
+        await blur('[data-test-first-name]');
+
+        assert
+          .dom('[data-test-first-name-errors]')
+          .doesNotExist(
+            'validation errors disappear after successful revalidation'
+          );
+        assert
+          .dom('[data-test-last-name-errors]')
+          .exists(
+            { count: 1 },
+            'validation errors do not disappear until revalidation happens'
+          );
+      });
+    });
+
+    module('change', function () {
+      test('form validation callback is called on change', async function (assert) {
+        const data: TestFormData = { firstName: 'Tony', lastName: 'Ward' };
+        const validateCallback = sinon.spy();
+
+        await render(<template>
+          <HeadlessForm
+            @data={{data}}
+            @revalidateOn="change"
+            @validate={{validateCallback}}
+            as |form|
+          >
+            <form.field @name="firstName" as |field|>
+              <field.label>First Name</field.label>
+              <field.input data-test-first-name />
+            </form.field>
+            <form.field @name="lastName" as |field|>
+              <field.label>Last Name</field.label>
+              <field.input data-test-last-name />
+            </form.field>
+            <button type="submit" data-test-submit>Submit</button>
+          </HeadlessForm>
+        </template>);
+
+        await fillIn('[data-test-first-name]', 'Foo');
+
+        assert.false(
+          validateCallback.called,
+          '@validate is not called while typing'
+        );
+
+        await blur('[data-test-first-name]');
+
+        assert.false(
+          validateCallback.called,
+          '@validate is not called until submitting'
+        );
+
+        await click('[data-test-submit]');
+
+        assert.true(
+          validateCallback.calledOnce,
+          '@validate is called when submitting'
+        );
+        assert.true(
+          validateCallback.calledWith({ ...data, firstName: 'Foo' }),
+          '@validate is called with form data'
+        );
+
+        await fillIn('[data-test-first-name]', 'Tony');
+
+        assert.true(
+          validateCallback.calledTwice,
+          '@validate is called for revalidation on change'
+        );
+        assert.true(
+          validateCallback
+            .getCall(1)
+            .calledWith({ ...data, firstName: 'Tony' }),
+          '@validate is called with form data'
+        );
+
+        await blur('[data-test-first-name]');
+
+        assert.true(
+          validateCallback.calledTwice,
+          '@validate is not called again on blur'
+        );
+      });
+
+      test('field validation callback is called on change', async function (assert) {
+        const data: TestFormData = { firstName: 'Tony', lastName: 'Ward' };
+        const validateCallback = sinon.spy();
+
+        await render(<template>
+          <HeadlessForm @data={{data}} @revalidateOn="change" as |form|>
+            <form.field
+              @name="firstName"
+              @validate={{validateCallback}}
+              as |field|
+            >
+              <field.label>First Name</field.label>
+              <field.input data-test-first-name />
+            </form.field>
+            <form.field @name="lastName" as |field|>
+              <field.label>Last Name</field.label>
+              <field.input data-test-last-name />
+            </form.field>
+            <button type="submit" data-test-submit>Submit</button>
+          </HeadlessForm>
+        </template>);
+
+        await fillIn('[data-test-first-name]', 'Foo');
+
+        assert.false(
+          validateCallback.called,
+          '@validate is not called while typing'
+        );
+
+        await blur('[data-test-first-name]');
+
+        assert.false(
+          validateCallback.called,
+          '@validate is not called until submitting'
+        );
+
+        await click('[data-test-submit]');
+
+        assert.true(
+          validateCallback.calledOnce,
+          '@validate is called when submitting'
+        );
+        assert.true(
+          validateCallback.calledWith('Foo', 'firstName', {
+            ...data,
+            firstName: 'Foo',
+          }),
+          '@validate is called with form data'
+        );
+
+        await fillIn('[data-test-first-name]', 'Tony');
+
+        assert.true(
+          validateCallback.calledTwice,
+          '@validate is called for revalidation on change'
+        );
+        assert.true(
+          validateCallback.getCall(1).calledWith('Tony', 'firstName', {
+            ...data,
+            firstName: 'Tony',
+          }),
+          '@validate is called with form data'
+        );
+
+        await blur('[data-test-first-name]');
+
+        assert.true(
+          validateCallback.calledTwice,
+          '@validate is called for revalidation on blur'
+        );
+      });
+
+      test('validation errors are exposed as field.errors on change', async function (assert) {
+        const data: TestFormData = { firstName: 'Tony', lastName: 'Foo' };
+
+        await render(<template>
+          <HeadlessForm
+            @data={{data}}
+            @revalidateOn="change"
+            @validate={{validateFormCallbackSync}}
+            as |form|
+          >
+            <form.field @name="firstName" as |field|>
+              <field.label>First Name</field.label>
+              <field.input data-test-first-name />
+              <field.errors data-test-first-name-errors />
+            </form.field>
+            <form.field @name="lastName" as |field|>
+              <field.label>Last Name</field.label>
+              <field.input data-test-last-name />
+              <field.errors data-test-last-name-errors />
+            </form.field>
+            <button type="submit" data-test-submit>Submit</button>
+          </HeadlessForm>
+        </template>);
+
+        assert
+          .dom('[data-test-first-name-errors]')
+          .doesNotExist(
+            'validation errors are not rendered before initial validation happens'
+          );
+        assert
+          .dom('[data-test-last-name-errors]')
+          .doesNotExist(
+            'validation errors are not rendered before initial validation happens'
+          );
+
+        await fillIn('[data-test-first-name]', 'Foo');
+
+        assert
+          .dom('[data-test-first-name-errors]')
+          .doesNotExist(
+            'validation errors are not rendered before initial validation happens'
+          );
+        assert
+          .dom('[data-test-last-name-errors]')
+          .doesNotExist(
+            'validation errors are not rendered before initial validation happens'
+          );
+
+        await blur('[data-test-first-name]');
+
+        assert
+          .dom('[data-test-first-name-errors]')
+          .doesNotExist(
+            'validation errors are not rendered before initial validation happens'
+          );
+        assert
+          .dom('[data-test-last-name-errors]')
+          .doesNotExist(
+            'validation errors are not rendered before initial validation happens'
+          );
+
+        await click('[data-test-submit]');
+
+        assert
+          .dom('[data-test-first-name-errors]')
+          .exists(
+            { count: 1 },
+            'validation errors appear on submit when validation fails'
+          );
+        assert
+          .dom('[data-test-last-name-errors]')
+          .exists(
+            { count: 1 },
+            'validation errors appear on submit when validation fails'
+          );
+
+        await fillIn('[data-test-first-name]', 'Tony');
+
+        assert
+          .dom('[data-test-first-name-errors]')
+          .doesNotExist(
+            'validation errors disappear after successful revalidation'
+          );
+        assert
+          .dom('[data-test-last-name-errors]')
+          .exists(
+            { count: 1 },
+            'validation errors do not disappear until revalidation happens'
+          );
+      });
+    });
+  });
 });

From f25e8a2db2267a56a75e4a2950ded01bcc42af55 Mon Sep 17 00:00:00 2001
From: Simon Ihmig <simon.ihmig@gmail.com>
Date: Mon, 30 Jan 2023 14:53:09 +0100
Subject: [PATCH 4/8] Optimize revalidation events

---
 .../src/components/headless-form.ts              | 16 ++++++++++++----
 1 file changed, 12 insertions(+), 4 deletions(-)

diff --git a/ember-headless-form/src/components/headless-form.ts b/ember-headless-form/src/components/headless-form.ts
index 2133e5b7..6659183c 100644
--- a/ember-headless-form/src/components/headless-form.ts
+++ b/ember-headless-form/src/components/headless-form.ts
@@ -89,18 +89,26 @@ export default class HeadlessFormComponent<
     const { validateOn } = this;
 
     return validateOn === 'submit'
-      ? undefined
-      : validateOn === 'blur'
+      ? // no need for dynamic validation, as validation always happens on submit
+        undefined
+      : // our component API expects "blur", but the actual blur event does not bubble up, so we use focusout internally instead
+      validateOn === 'blur'
       ? 'focusout'
       : validateOn;
   }
 
   get fieldRevalidationEvent(): 'focusout' | 'change' | undefined {
-    const { revalidateOn } = this;
+    const { validateOn, revalidateOn } = this;
 
     return revalidateOn === 'submit'
+      ? // no need for dynamic validation, as validation always happens on submit
+        undefined
+      : // when validation happens more frequently than revalidation, then we can ignore revalidation, because the validation handler will already cover us
+      validateOn === 'change' ||
+        (validateOn === 'blur' && revalidateOn === 'blur')
       ? undefined
-      : revalidateOn === 'blur'
+      : // our component API expects "blur", but the actual blur event does not bubble up, so we use focusout internally instead
+      revalidateOn === 'blur'
       ? 'focusout'
       : revalidateOn;
   }

From 7aca25fb13915ecc891e996f0ebf6f4aec597dcd Mon Sep 17 00:00:00 2001
From: Simon Ihmig <simon.ihmig@gmail.com>
Date: Mon, 30 Jan 2023 15:00:34 +0100
Subject: [PATCH 5/8] Fix stupid qunit linting rule

---
 .../components/headless-form-validation-test.gts          | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/test-app/tests/integration/components/headless-form-validation-test.gts b/test-app/tests/integration/components/headless-form-validation-test.gts
index 812b4eaa..bb7f3f68 100644
--- a/test-app/tests/integration/components/headless-form-validation-test.gts
+++ b/test-app/tests/integration/components/headless-form-validation-test.gts
@@ -847,7 +847,7 @@ module('Integration Component HeadlessForm > Validation', function (hooks) {
   });
 
   module(`@validateOn`, function () {
-    module('blur', function () {
+    module('@validateOn=blur', function () {
       test('form validation callback is called on blur', async function (assert) {
         const data: TestFormData = { firstName: 'Tony', lastName: 'Ward' };
         const validateCallback = sinon.spy();
@@ -1004,7 +1004,7 @@ module('Integration Component HeadlessForm > Validation', function (hooks) {
       });
     });
 
-    module('change', function () {
+    module('@validateOn=change', function () {
       test('form validation callback is called on change', async function (assert) {
         const data: TestFormData = { firstName: 'Tony', lastName: 'Ward' };
         const validateCallback = sinon.spy();
@@ -1136,7 +1136,7 @@ module('Integration Component HeadlessForm > Validation', function (hooks) {
   });
 
   module(`@revalidateOn`, function () {
-    module('blur', function () {
+    module('@revalidateOn=blur', function () {
       test('form validation callback is called on blur', async function (assert) {
         const data: TestFormData = { firstName: 'Tony', lastName: 'Ward' };
         const validateCallback = sinon.spy();
@@ -1385,7 +1385,7 @@ module('Integration Component HeadlessForm > Validation', function (hooks) {
       });
     });
 
-    module('change', function () {
+    module('@revalidateOn=change', function () {
       test('form validation callback is called on change', async function (assert) {
         const data: TestFormData = { firstName: 'Tony', lastName: 'Ward' };
         const validateCallback = sinon.spy();

From cf739d797b88b35aa882aeea93891addca911269 Mon Sep 17 00:00:00 2001
From: Simon Ihmig <simon.ihmig@gmail.com>
Date: Tue, 31 Jan 2023 09:56:49 +0100
Subject: [PATCH 6/8] Improve test assertion messages

---
 .../headless-form-validation-test.gts         | 58 +++++++++----------
 1 file changed, 29 insertions(+), 29 deletions(-)

diff --git a/test-app/tests/integration/components/headless-form-validation-test.gts b/test-app/tests/integration/components/headless-form-validation-test.gts
index bb7f3f68..0a2601b5 100644
--- a/test-app/tests/integration/components/headless-form-validation-test.gts
+++ b/test-app/tests/integration/components/headless-form-validation-test.gts
@@ -882,7 +882,7 @@ module('Integration Component HeadlessForm > Validation', function (hooks) {
 
         assert.true(
           validateCallback.calledWith({ ...data, firstName: 'Foo' }),
-          '@validate is called with form data'
+          '@validate is called with form data on blur'
         );
 
         await click('[data-test-submit]');
@@ -929,7 +929,7 @@ module('Integration Component HeadlessForm > Validation', function (hooks) {
             ...data,
             firstName: 'Foo',
           }),
-          '@validate is called with form data'
+          '@validate is called with form data on blur'
         );
 
         await click('[data-test-submit]');
@@ -967,12 +967,12 @@ module('Integration Component HeadlessForm > Validation', function (hooks) {
         assert
           .dom('[data-test-first-name-errors]')
           .doesNotExist(
-            'validation errors are not rendered before validation happens'
+            'validation errors are not rendered before form is filled in'
           );
         assert
           .dom('[data-test-last-name-errors]')
           .doesNotExist(
-            'validation errors are not rendered before validation happens'
+            'validation errors are not rendered before form is filled in'
           );
 
         await fillIn('[data-test-first-name]', 'Foo');
@@ -980,12 +980,12 @@ module('Integration Component HeadlessForm > Validation', function (hooks) {
         assert
           .dom('[data-test-first-name-errors]')
           .doesNotExist(
-            'validation errors are not rendered before validation happens'
+            'validation errors are not rendered before validation happens on blur'
           );
         assert
           .dom('[data-test-last-name-errors]')
           .doesNotExist(
-            'validation errors are not rendered before validation happens'
+            'validation errors are not rendered before validation happens on blur'
           );
 
         await blur('[data-test-first-name]');
@@ -1032,7 +1032,7 @@ module('Integration Component HeadlessForm > Validation', function (hooks) {
 
         assert.true(
           validateCallback.calledWith({ ...data, firstName: 'Foo' }),
-          '@validate is called with form data'
+          '@validate is called with form data on change'
         );
 
         await click('[data-test-submit]');
@@ -1110,12 +1110,12 @@ module('Integration Component HeadlessForm > Validation', function (hooks) {
         assert
           .dom('[data-test-first-name-errors]')
           .doesNotExist(
-            'validation errors are not rendered before validation happens'
+            'validation errors are not rendered before validation happens on change'
           );
         assert
           .dom('[data-test-last-name-errors]')
           .doesNotExist(
-            'validation errors are not rendered before validation happens'
+            'validation errors are not rendered before validation happens on change'
           );
 
         await fillIn('[data-test-first-name]', 'Foo');
@@ -1182,7 +1182,7 @@ module('Integration Component HeadlessForm > Validation', function (hooks) {
         );
         assert.true(
           validateCallback.calledWith({ ...data, firstName: 'Foo' }),
-          '@validate is called with form data'
+          '@validate is called with form data on submit'
         );
 
         await fillIn('[data-test-first-name]', 'Tony');
@@ -1202,7 +1202,7 @@ module('Integration Component HeadlessForm > Validation', function (hooks) {
           validateCallback
             .getCall(1)
             .calledWith({ ...data, firstName: 'Tony' }),
-          '@validate is called with form data'
+          '@validate is called with form data on blur'
         );
       });
 
@@ -1305,12 +1305,12 @@ module('Integration Component HeadlessForm > Validation', function (hooks) {
         assert
           .dom('[data-test-first-name-errors]')
           .doesNotExist(
-            'validation errors are not rendered before initial validation happens'
+            'validation errors are not rendered before initial validation happens before form is filled in'
           );
         assert
           .dom('[data-test-last-name-errors]')
           .doesNotExist(
-            'validation errors are not rendered before initial validation happens'
+            'validation errors are not rendered before initial validation happens before form is filled in'
           );
 
         await fillIn('[data-test-first-name]', 'Foo');
@@ -1318,12 +1318,12 @@ module('Integration Component HeadlessForm > Validation', function (hooks) {
         assert
           .dom('[data-test-first-name-errors]')
           .doesNotExist(
-            'validation errors are not rendered before initial validation happens'
+            'validation errors are not rendered before initial validation happens on submit'
           );
         assert
           .dom('[data-test-last-name-errors]')
           .doesNotExist(
-            'validation errors are not rendered before initial validation happens'
+            'validation errors are not rendered before initial validation happens on submit'
           );
 
         await blur('[data-test-first-name]');
@@ -1331,12 +1331,12 @@ module('Integration Component HeadlessForm > Validation', function (hooks) {
         assert
           .dom('[data-test-first-name-errors]')
           .doesNotExist(
-            'validation errors are not rendered before initial validation happens'
+            'validation errors are not rendered before initial validation happens on submit'
           );
         assert
           .dom('[data-test-last-name-errors]')
           .doesNotExist(
-            'validation errors are not rendered before initial validation happens'
+            'validation errors are not rendered before initial validation happens on submit'
           );
 
         await click('[data-test-submit]');
@@ -1360,13 +1360,13 @@ module('Integration Component HeadlessForm > Validation', function (hooks) {
           .dom('[data-test-first-name-errors]')
           .exists(
             { count: 1 },
-            'validation errors do not disappear until revalidation happens'
+            'validation errors do not disappear until revalidation happens on blur'
           );
         assert
           .dom('[data-test-last-name-errors]')
           .exists(
             { count: 1 },
-            'validation errors do not disappear until revalidation happens'
+            'validation errors do not disappear until revalidation happens on blur'
           );
 
         await blur('[data-test-first-name]');
@@ -1374,13 +1374,13 @@ module('Integration Component HeadlessForm > Validation', function (hooks) {
         assert
           .dom('[data-test-first-name-errors]')
           .doesNotExist(
-            'validation errors disappear after successful revalidation'
+            'validation errors disappear after successful revalidation on blur'
           );
         assert
           .dom('[data-test-last-name-errors]')
           .exists(
             { count: 1 },
-            'validation errors do not disappear until revalidation happens'
+            'validation errors do not disappear until revalidation happens on blur'
           );
       });
     });
@@ -1554,12 +1554,12 @@ module('Integration Component HeadlessForm > Validation', function (hooks) {
         assert
           .dom('[data-test-first-name-errors]')
           .doesNotExist(
-            'validation errors are not rendered before initial validation happens'
+            'validation errors are not rendered before initial validation happens before form is filled in'
           );
         assert
           .dom('[data-test-last-name-errors]')
           .doesNotExist(
-            'validation errors are not rendered before initial validation happens'
+            'validation errors are not rendered before initial validation happens before form is filled in'
           );
 
         await fillIn('[data-test-first-name]', 'Foo');
@@ -1567,12 +1567,12 @@ module('Integration Component HeadlessForm > Validation', function (hooks) {
         assert
           .dom('[data-test-first-name-errors]')
           .doesNotExist(
-            'validation errors are not rendered before initial validation happens'
+            'validation errors are not rendered before initial validation happens on submit'
           );
         assert
           .dom('[data-test-last-name-errors]')
           .doesNotExist(
-            'validation errors are not rendered before initial validation happens'
+            'validation errors are not rendered before initial validation happens on submit'
           );
 
         await blur('[data-test-first-name]');
@@ -1580,12 +1580,12 @@ module('Integration Component HeadlessForm > Validation', function (hooks) {
         assert
           .dom('[data-test-first-name-errors]')
           .doesNotExist(
-            'validation errors are not rendered before initial validation happens'
+            'validation errors are not rendered before initial validation happens on submit'
           );
         assert
           .dom('[data-test-last-name-errors]')
           .doesNotExist(
-            'validation errors are not rendered before initial validation happens'
+            'validation errors are not rendered before initial validation happens on submit'
           );
 
         await click('[data-test-submit]');
@@ -1608,13 +1608,13 @@ module('Integration Component HeadlessForm > Validation', function (hooks) {
         assert
           .dom('[data-test-first-name-errors]')
           .doesNotExist(
-            'validation errors disappear after successful revalidation'
+            'validation errors disappear after successful revalidation on change'
           );
         assert
           .dom('[data-test-last-name-errors]')
           .exists(
             { count: 1 },
-            'validation errors do not disappear until revalidation happens'
+            'validation errors do not disappear until revalidation happens on change'
           );
       });
     });

From b69caffaec0b8db8f78d14c58e796657e8efc62e Mon Sep 17 00:00:00 2001
From: Simon Ihmig <simon.ihmig@gmail.com>
Date: Tue, 31 Jan 2023 10:25:08 +0100
Subject: [PATCH 7/8] Add more JSDoc

---
 .../src/components/headless-form.ts           | 52 ++++++++++++++++++-
 1 file changed, 51 insertions(+), 1 deletion(-)

diff --git a/ember-headless-form/src/components/headless-form.ts b/ember-headless-form/src/components/headless-form.ts
index 6659183c..ee463dd7 100644
--- a/ember-headless-form/src/components/headless-form.ts
+++ b/ember-headless-form/src/components/headless-form.ts
@@ -48,6 +48,9 @@ export interface HeadlessFormComponentSignature<DATA extends UserData> {
   };
 }
 
+/**
+ * This internal data structure maintains information about each field that is registered to the form by `registerField`.
+ */
 class FieldData<
   DATA extends FormData,
   KEY extends FormKey<DATA> = FormKey<DATA>
@@ -56,8 +59,14 @@ class FieldData<
     this.validate = fieldRegistration.validate;
   }
 
+  /**
+   * tracked state that enabled a dynamic validation of a field *before* the whole form is submitted, e.g. by `@validateOn="blur" and the blur event being triggered for that particular field.
+   */
   @tracked validationEnabled = false;
 
+  /**
+   * The *field* level validation callback passed to the field as in `<form.field @name="foo" @validate={{this.validateCallback}}>`
+   */
   validate?: FieldValidateCallback<DATA, KEY>;
 }
 
@@ -70,11 +79,21 @@ export default class HeadlessFormComponent<
   // we cannot use (modifier "on") directly in the template due to https://github.com/emberjs/ember.js/issues/19869
   on = on;
 
+  /**
+   * A copy of the passed `@data` stored internally, which is only passed back to the component consumer after a (successful) form submission.
+   */
   internalData: DATA = new TrackedObject(this.args.data ?? {}) as DATA;
 
   fields = new Map<FormKey<FormData<DATA>>, FieldData<FormData<DATA>>>();
 
+  /**
+   * The last result of calling `this.validate()`.
+   */
   @tracked lastValidationResult?: ErrorRecord<FormData<DATA>>;
+
+  /**
+   * When this is set to true by submitting the form, eventual validation errors are show for *all* field, regardless of their individual dynamic validation status in `FieldData#validationEnabled`
+   */
   @tracked showAllValidations = false;
 
   get validateOn(): ValidateOn {
@@ -85,6 +104,9 @@ export default class HeadlessFormComponent<
     return this.args.revalidateOn ?? 'change';
   }
 
+  /**
+   * Return the event type that will be listened on for dynamic validation (i.e. *before* submitting)
+   */
   get fieldValidationEvent(): 'focusout' | 'change' | undefined {
     const { validateOn } = this;
 
@@ -97,6 +119,9 @@ export default class HeadlessFormComponent<
       : validateOn;
   }
 
+  /**
+   * Return the event type that will be listened on for dynamic *re*validation, i.e. updating the validation status of a field that has been previously marked as invalid
+   */
   get fieldRevalidationEvent(): 'focusout' | 'change' | undefined {
     const { validateOn, revalidateOn } = this;
 
@@ -113,6 +138,9 @@ export default class HeadlessFormComponent<
       : revalidateOn;
   }
 
+  /**
+   * Return true if validation has happened (by submitting or by an `@validateOn` event being triggered) and at least one field is invalid
+   */
   get hasValidationErrors(): boolean {
     // Only consider validation errors for which we actually have a field rendered
     return this.lastValidationResult
@@ -122,6 +150,9 @@ export default class HeadlessFormComponent<
       : false;
   }
 
+  /**
+   * Call the passed validation callbacks, defined both on the whole form as well as on field level, and return the merged result for all fields.
+   */
   async validate(): Promise<ErrorRecord<FormData<DATA>> | undefined> {
     let errors: ErrorRecord<FormData<DATA>> | undefined = undefined;
 
@@ -152,6 +183,11 @@ export default class HeadlessFormComponent<
     return Object.keys(errors).length > 0 ? errors : undefined;
   }
 
+  /**
+   * Return a mapping of field to validation errors, for all fields that are invalid *and* for which validation errors should be visible.
+   * Validation errors will be visible for a certain field, if validation errors for *all* fields are visible, which is the case when trying to submit the form,
+   * or when that field has triggered the event given by `@validateOn` for showing validation errors before submitting, e.g. on blur.
+   */
   get visibleErrors(): ErrorRecord<FormData<DATA>> | undefined {
     if (!this.lastValidationResult) {
       return undefined;
@@ -171,6 +207,9 @@ export default class HeadlessFormComponent<
     return visibleErrors;
   }
 
+  /**
+   * Given a field name, return if eventual errors for the field should be visible. See `visibleErrors` for further details.
+   */
   showErrorsFor(field: FormKey<FormData<DATA>>): boolean {
     return (
       this.showAllValidations ||
@@ -220,6 +259,11 @@ export default class HeadlessFormComponent<
     this.internalData[key] = value;
   }
 
+  /**
+   * Handle the `@validateOn` event for a certain field, e.g. "blur".
+   * Associating the event with a field is done by looking at the event target's `name` attribute, which must match one of the `<form.field @name="...">` invocations by the user's template.
+   * Validation will be triggered, and the particular field will be marked to show eventual validation errors.
+   */
   @action
   async handleFieldValidation(e: Event): Promise<void> {
     const { target } = e;
@@ -237,6 +281,13 @@ export default class HeadlessFormComponent<
     }
   }
 
+  /**
+   * Handle the `@revalidateOn` event for a certain field, e.g. "blur".
+   * Associating the event with a field is done by looking at the event target's `name` attribute, which must match one of the `<form.field @name="...">` invocations by the user's template.
+   * When a field has been already marked to show validation errors by `@validateOn`, then for revalidation another validation will be triggered.
+   *
+   * The use case here is to allow this to happen more frequently than the initial validation, e.g. `@validateOn="blur" @revalidateOn="change"`.
+   */
   @action
   async handleFieldRevalidation(e: Event): Promise<void> {
     const { target } = e;
@@ -245,7 +296,6 @@ export default class HeadlessFormComponent<
     if (name) {
       if (this.showErrorsFor(name as FormKey<FormData<DATA>>)) {
         this.lastValidationResult = await this.validate();
-        // field.validationEnabled = true;
       }
     } else {
       // @todo how to handle custom controls that don't emit focusout/change events from native form controls?

From d1a632a5dcfb52cf45f9ef7029b910e200485cf9 Mon Sep 17 00:00:00 2001
From: Simon Ihmig <simon.ihmig@gmail.com>
Date: Thu, 2 Feb 2023 10:35:10 +0100
Subject: [PATCH 8/8] `waitFor` async validation

---
 ember-headless-form/package.json                    |  1 +
 ember-headless-form/src/components/headless-form.ts |  2 ++
 pnpm-lock.yaml                                      | 13 ++++++++++---
 .../components/headless-form-validation-test.gts    |  8 ++++++--
 4 files changed, 19 insertions(+), 5 deletions(-)

diff --git a/ember-headless-form/package.json b/ember-headless-form/package.json
index adf28dad..3e3a23ed 100644
--- a/ember-headless-form/package.json
+++ b/ember-headless-form/package.json
@@ -28,6 +28,7 @@
   "dependencies": {
     "@babel/runtime": "^7.20.7",
     "@embroider/addon-shim": "^1.0.0",
+    "@ember/test-waiters": "^3.0.2",
     "@embroider/util": "^1.9.0",
     "tracked-built-ins": "^3.1.0"
   },
diff --git a/ember-headless-form/src/components/headless-form.ts b/ember-headless-form/src/components/headless-form.ts
index ee463dd7..a42b08e9 100644
--- a/ember-headless-form/src/components/headless-form.ts
+++ b/ember-headless-form/src/components/headless-form.ts
@@ -3,6 +3,7 @@ import { tracked } from '@glimmer/tracking';
 import { assert } from '@ember/debug';
 import { on } from '@ember/modifier';
 import { action } from '@ember/object';
+import { waitFor } from '@ember/test-waiters';
 
 import { TrackedObject } from 'tracked-built-ins';
 
@@ -153,6 +154,7 @@ export default class HeadlessFormComponent<
   /**
    * Call the passed validation callbacks, defined both on the whole form as well as on field level, and return the merged result for all fields.
    */
+  @waitFor
   async validate(): Promise<ErrorRecord<FormData<DATA>> | undefined> {
     let errors: ErrorRecord<FormData<DATA>> | undefined = undefined;
 
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index a7e44acb..5d05c51b 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -21,6 +21,7 @@ importers:
       '@babel/plugin-syntax-decorators': ^7.17.0
       '@babel/preset-typescript': ^7.18.6
       '@babel/runtime': ^7.20.7
+      '@ember/test-waiters': ^3.0.2
       '@embroider/addon-dev': ^3.0.0
       '@embroider/addon-shim': ^1.0.0
       '@embroider/util': ^1.9.0
@@ -66,6 +67,7 @@ importers:
       typescript: ^4.7.4
     dependencies:
       '@babel/runtime': 7.20.7
+      '@ember/test-waiters': 3.0.2
       '@embroider/addon-shim': 1.8.4
       '@embroider/util': 1.9.0
       tracked-built-ins: 3.1.0
@@ -2044,7 +2046,6 @@ packages:
       semver: 7.3.8
     transitivePeerDependencies:
       - supports-color
-    dev: true
 
   /@embroider/addon-dev/3.0.0_rollup@2.79.1:
     resolution: {integrity: sha512-h3ISDdp8LASA6583WC3IU3ECZ5fHlW3V3EkgpEeeH7KhxTerHjDjNf+S6+ZvPH+ZHi3WOCYPvUA5OfNICyMbtA==}
@@ -2977,7 +2978,10 @@ packages:
   /@types/ember__controller/4.0.4:
     resolution: {integrity: sha512-+f0knTIJJkRX5xijeSI/n4FvLfhMFFxIxODyFFFFB483EryYuts3QzpTwU5D66WQ5rAbZvpPRXRMPTTCNJoUhg==}
     dependencies:
-      '@types/ember__object': 4.0.5_@babel+core@7.20.12
+      '@types/ember__object': 4.0.5
+    transitivePeerDependencies:
+      - '@babel/core'
+      - supports-color
     dev: true
 
   /@types/ember__controller/4.0.4_@babel+core@7.20.12:
@@ -3063,8 +3067,11 @@ packages:
   /@types/ember__object/4.0.5:
     resolution: {integrity: sha512-gXrywWBwoW7J9y9yJqoZ0m1qtiyMdrEi29cJdF1xI2qOnMqaZeuSCMYaPQMsyq52/YnVIG2EnGzo6eUD57J4Nw==}
     dependencies:
-      '@types/ember': 4.0.3_@babel+core@7.20.12
+      '@types/ember': 4.0.3
       '@types/rsvp': 4.0.4
+    transitivePeerDependencies:
+      - '@babel/core'
+      - supports-color
     dev: true
 
   /@types/ember__object/4.0.5_@babel+core@7.20.12:
diff --git a/test-app/tests/integration/components/headless-form-validation-test.gts b/test-app/tests/integration/components/headless-form-validation-test.gts
index 0a2601b5..7919b258 100644
--- a/test-app/tests/integration/components/headless-form-validation-test.gts
+++ b/test-app/tests/integration/components/headless-form-validation-test.gts
@@ -67,7 +67,9 @@ module('Integration Component HeadlessForm > Validation', function (hooks) {
   const validateFormCallbackAsync: FormValidateCallback<TestFormData> = async (
     data
   ) => {
-    return await validateFormCallbackSync(data);
+    // intentionally adding a delay here, to make the validation behave truly async and assert that we are correctly waiting for it in tests
+    await new Promise((resolve) => setTimeout(resolve, 10));
+    return validateFormCallbackSync(data);
   };
 
   const validateFieldCallbackSync: FieldValidateCallback<TestFormData> = (
@@ -105,7 +107,9 @@ module('Integration Component HeadlessForm > Validation', function (hooks) {
   const validateFieldCallbackAsync: FieldValidateCallback<
     TestFormData
   > = async (value, field, data) => {
-    return await validateFieldCallbackSync(value, field, data);
+    // intentionally adding a delay here, to make the validation behave truly async and assert that we are correctly waiting for it in tests
+    await new Promise((resolve) => setTimeout(resolve, 10));
+    return validateFieldCallbackSync(value, field, data);
   };
 
   module('form @validation callback', function () {