refactor: Form associated mixin and validation slots container

rkaraivanov · rkaraivanov · commit b484277dd1ee · 2025-07-16T14:12:11.000+03:00
Introduced a `_touched` state for form associated components and dropped
the previous `_dirty` flag.

Changed the behavior of how **invalid** visual state is represented for
components. With the current batch of changes, the visual styles are
applied if the internal validity of the component is **false** and one of
the following is applicable:

* the user has interacted with the component through the UI - either
  by focusing, click, selection, typing or other form of keyboard interaction.
* `reportValidity` was invoked on the form associated component.
* The parent form of the form associated component is being submitted.
diff --git a/src/components/common/mixins/forms/associated.ts b/src/components/common/mixins/forms/associated.ts
@@ -1,16 +1,31 @@
 import type { LitElement } from 'lit';
-import { property } from 'lit/decorators.js';
+import { property, state } from 'lit/decorators.js';
 import { addSafeEventListener, isFunction, isString } from '../../util.js';
 import type { Validator } from '../../validators.js';
 import type { Constructor } from '../constructor.js';
 import type { FormValue } from './form-value.js';
-import type {
-  FormAssociatedCheckboxElementInterface,
-  FormAssociatedElementInterface,
-  FormRestoreMode,
-  FormValueType,
+import {
+  type FormAssociatedCheckboxElementInterface,
+  type FormAssociatedElementInterface,
+  type FormRestoreMode,
+  type FormValueType,
+  InternalInvalidEvent,
+  InternalResetEvent,
 } from './types.js';
 
+const eventOptions = {
+  bubbles: false,
+  composed: false,
+};
+
+function emitFormInvalidEvent(host: LitElement): void {
+  host.dispatchEvent(new CustomEvent(InternalInvalidEvent, eventOptions));
+}
+
+function emitFormResetEvent(host: LitElement): void {
+  host.dispatchEvent(new CustomEvent(InternalResetEvent, eventOptions));
+}
+
 function BaseFormAssociated<T extends Constructor<LitElement>>(base: T) {
   class BaseFormAssociatedElement extends base {
     public static readonly formAssociated = true;
@@ -20,9 +35,25 @@ function BaseFormAssociated<T extends Constructor<LitElement>>(base: T) {
 
     protected _disabled = false;
     protected _invalid = false;
-    protected _dirty = false;
     protected _pristine = true;
 
+    @state()
+    private _isFormSubmit = false;
+
+    @state()
+    private _touched = false;
+
+    @state()
+    private _isInternalValidation = false;
+
+    private get _shouldApplyStyles(): boolean {
+      return (
+        this._invalid &&
+        (this._touched || this._isFormSubmit) &&
+        !this._isInternalValidation
+      );
+    }
+
     protected get __validators(): Validator[] {
       return [];
     }
@@ -55,13 +86,12 @@ function BaseFormAssociated<T extends Constructor<LitElement>>(base: T) {
      * @default false
      */
     @property({ type: Boolean, reflect: true })
-    public set invalid(value: boolean) {
-      this._invalid = value;
-      this.toggleAttribute('invalid', Boolean(this._invalid));
+    public set invalid(_: boolean) {
+      this._setInvalidStyles();
     }
 
     public get invalid(): boolean {
-      return this._invalid;
+      return this._shouldApplyStyles;
     }
 
     /** Returns the HTMLFormElement associated with this element. */
@@ -97,39 +127,68 @@ function BaseFormAssociated<T extends Constructor<LitElement>>(base: T) {
       addSafeEventListener(this, 'invalid', this._handleInvalid);
     }
 
+    /** @internal */
     public override connectedCallback(): void {
       super.connectedCallback();
-      this._dirty = false;
+      this._pristine = true;
+      this._touched = false;
       this._updateValidity();
+      this._setInvalidStyles();
     }
 
-    private _handleInvalid(event: Event) {
+    private _setInvalidStyles(): void {
+      this.toggleAttribute('invalid', this._shouldApplyStyles);
+      this.requestUpdate();
+    }
+
+    private _handleInvalid(event: Event): void {
       event.preventDefault();
-      this.invalid = true;
+      this._invalid = true;
+
+      if (this._isInternalValidation) {
+        this._isInternalValidation = false;
+      } else {
+        this._isFormSubmit = true;
+        emitFormInvalidEvent(this);
+      }
+
+      this._setInvalidStyles();
+      this._isFormSubmit = false;
     }
 
-    private _setInvalidState(): void {
-      if (this._dirty || !this._pristine) {
-        this.invalid = !this.checkValidity();
+    protected _handleBlur(): void {
+      if (!this._touched) {
+        this._touched = true;
+      }
+      this._validate();
+    }
+
+    protected _setTouchedState(): void {
+      if (!this._touched) {
+        this._touched = true;
       }
     }
 
     private __runValidators() {
       const validity: ValidityStateFlags = {};
       let message = '';
+      let isInvalid = false;
 
       for (const validator of this.__validators) {
         const isValid = validator.isValid(this);
 
         validity[validator.key] = !isValid;
 
         if (!isValid) {
+          isInvalid = true;
           message = isFunction(validator.message)
             ? validator.message(this)
             : validator.message;
         }
       }
 
+      this._invalid = isInvalid;
+
       return { validity, message };
     }
 
@@ -145,13 +204,12 @@ function BaseFormAssociated<T extends Constructor<LitElement>>(base: T) {
 
     protected _validate(message?: string): void {
       this._updateValidity(message);
-      this._setInvalidState();
     }
 
     /**
      * Executes the component validators and updates the internal validity state.
      */
-    protected _updateValidity(error?: string) {
+    protected _updateValidity(error?: string): void {
       let { validity, message } = this.__runValidators();
       const hasCustomError = this.validity.customError;
 
@@ -178,11 +236,15 @@ function BaseFormAssociated<T extends Constructor<LitElement>>(base: T) {
       }
 
       this.__internals.setValidity(validity, message);
+      this._isInternalValidation = true;
+      this._invalid = !this.__internals.checkValidity();
     }
 
     protected _setFormValue(value: FormValueType, state?: FormValueType): void {
       this._pristine = false;
       this.__internals.setFormValue(value, state);
+      this._updateValidity();
+      this._setInvalidStyles();
     }
 
     protected formAssociatedCallback(_form: HTMLFormElement): void {}
@@ -195,8 +257,10 @@ function BaseFormAssociated<T extends Constructor<LitElement>>(base: T) {
     protected formResetCallback(): void {
       this._restoreDefaultValue();
       this._pristine = true;
-      this._dirty = false;
-      this.invalid = false;
+      this._touched = false;
+      this._invalid = false;
+      this._setInvalidStyles();
+      emitFormResetEvent(this);
     }
 
     /* c8 ignore next 4 */
@@ -206,24 +270,25 @@ function BaseFormAssociated<T extends Constructor<LitElement>>(base: T) {
     ): void {}
 
     /** Checks for validity of the control and shows the browser message if it invalid. */
-    public reportValidity() {
+    public reportValidity(): boolean {
       const state = this.__internals.reportValidity();
-      this.invalid = !state;
+      this._invalid = !state;
       return state;
     }
 
     /** Checks for validity of the control and emits the invalid event if it invalid. */
-    public checkValidity() {
+    public checkValidity(): boolean {
+      this._isInternalValidation = true;
       const state = this.__internals.checkValidity();
-      this.invalid = !state;
+      this._invalid = !state;
       return state;
     }
 
     /**
      * Sets a custom validation message for the control.
      * As long as `message` is not empty, the control is considered invalid.
      */
-    public setCustomValidity(message: string) {
+    public setCustomValidity(message: string): void {
       this._updateValidity(message);
     }
   }
@@ -250,7 +315,7 @@ export function FormAssociatedMixin<T extends Constructor<LitElement>>(
       }
     }
 
-    public get defaultValue() {
+    public get defaultValue(): unknown {
       return this._formValue.defaultValue;
     }
 
diff --git a/src/components/common/mixins/forms/types.ts b/src/components/common/mixins/forms/types.ts
@@ -13,7 +13,6 @@ declare class BaseFormAssociatedElement {
 
   // Properties
   protected _formValue: unknown;
-  protected _dirty: boolean;
   protected _pristine: boolean;
   protected _disabled: boolean;
   protected _invalid: boolean;
@@ -60,6 +59,12 @@ declare class BaseFormAssociatedElement {
 
   // Methods
 
+  // TODO: Explain
+  protected _handleBlur(): void;
+
+  // TODO: Explain
+  protected _setTouchedState(): void;
+
   /**
    * Sets the default value of the component.
    * Called in `attributeChangedCallback`(i.e. when the `value` attribute of the control is set).
@@ -71,13 +76,15 @@ declare class BaseFormAssociatedElement {
    */
   protected _restoreDefaultValue(): void;
 
+  // TODO: Change docs based on the new behavior
   /**
    * Executes the {@link BaseFormAssociatedElement._updateValidity | `_updateValidity()`} hook and then applies
    * the {@link BaseFormAssociatedElement.invalid | `invalid`} attribute on the control and the associated styles
    * if the element has completed the first update cycle or it has been interacted with by the user.
    */
   protected _validate(message?: string): void;
 
+  // TODO: Drop
   /**
    * Executes the component's validators and updates the internal validity state.
    */
@@ -160,3 +167,6 @@ export declare class FormRequiredInterface {
   public set required(value: boolean);
   public get required(): boolean;
 }
+
+export const InternalInvalidEvent = 'igc-form-internal-invalid';
+export const InternalResetEvent = 'igc-form-internal-reset';
diff --git a/src/components/validation-container/validation-container.ts b/src/components/validation-container/validation-container.ts
@@ -3,8 +3,13 @@ import { property, state } from 'lit/decorators.js';
 import { cache } from 'lit/directives/cache.js';
 import { ifDefined } from 'lit/directives/if-defined.js';
 import { addThemingController } from '../../theming/theming-controller.js';
+import { createAbortHandle } from '../common/abort-handler.js';
 import { registerComponent } from '../common/definitions/register.js';
-import type { IgcFormControl } from '../common/mixins/forms/types.js';
+import {
+  type IgcFormControl,
+  InternalInvalidEvent,
+  InternalResetEvent,
+} from '../common/mixins/forms/types.js';
 import { partMap } from '../common/part-map.js';
 import { isEmpty, toKebabCase } from '../common/util.js';
 import IgcIconComponent from '../icon/icon.js';
@@ -107,6 +112,8 @@ export default class IgcValidationContainerComponent extends LitElement {
     `;
   }
 
+  private readonly _abortHandle = createAbortHandle();
+
   private _target!: IgcFormControl;
 
   @state()
@@ -121,9 +128,12 @@ export default class IgcValidationContainerComponent extends LitElement {
       return;
     }
 
-    this._target?.removeEventListener('invalid', this);
+    this._abortHandle.abort();
+    const { signal } = this._abortHandle;
+
     this._target = value;
-    this._target.addEventListener('invalid', this);
+    this._target.addEventListener(InternalInvalidEvent, this, { signal });
+    this._target.addEventListener(InternalResetEvent, this, { signal });
   }
 
   public get target(): IgcFormControl {
@@ -144,10 +154,11 @@ export default class IgcValidationContainerComponent extends LitElement {
   /** @internal */
   public handleEvent(event: Event): void {
     switch (event.type) {
-      case 'invalid':
-        if (!this.invalid) {
-          this.invalid = true;
-        }
+      case InternalInvalidEvent:
+        this.invalid = true;
+        break;
+      case InternalResetEvent:
+        this.invalid = false;
         break;
       case 'slotchange': {
         const newHasSlottedContent = hasProjectedValidation(this);
