Merge pull request #174 from umbraco/feature/formControlMixin-adapt-native-validation

ability to map validaty state from native input to a custom form control

Author: madsrasmussen

packages/uui-base/lib/mixins/FormControlMixin.ts

@@ -5,15 +5,18 @@ import { UUIFormControlEvent } from '../events';
 
 type Constructor<T = {}> = new (...args: any[]) => T;
 
+type NativeFormControlElement = HTMLInputElement; // Eventually use a specific interface or list multiple options like appending these types: ... | HTMLTextAreaElement | HTMLSelectElement
+
 // TODO: make it possible to define FormDataEntryValue type.
 export declare abstract class FormControlMixinInterface extends LitElement {
   formAssociated: boolean;
   get value(): FormDataEntryValue;
   set value(newValue: FormDataEntryValue);
   name: string;
   formResetCallback(): void;
-  checkValidity: () => boolean;
+  checkValidity(): boolean;
   get validationMessage(): string;
+  public setCustomValidity(error: string): void;
   protected _value: FormDataEntryValue;
   protected _internals: any;
   protected abstract getFormElement(): HTMLElement | undefined;
@@ -22,6 +25,7 @@ export declare abstract class FormControlMixinInterface extends LitElement {
     getMessageMethod: () => String,
     checkMethod: () => boolean
   ) => void;
+  protected addFormControlElement(element: NativeFormControlElement): void;
   pristine: boolean;
   required: boolean;
   requiredMessage: string;
@@ -46,9 +50,10 @@ type FlagTypes =
   | 'badInput'
   | 'valid';
 
+// Acceptable as an internal interface/type, BUT if exposed externally this should be turned into a public class in a separate file.
 interface Validator {
   flagKey: FlagTypes;
-  getMessage: () => String;
+  getMessageMethod: () => String;
   checkMethod: () => boolean;
 }
 
@@ -147,6 +152,7 @@ export const FormControlMixin = <T extends Constructor<LitElement>>(
     private _internals: any;
     private _form: HTMLFormElement | null = null;
     private _validators: Validator[] = [];
+    private _formCtrlElements: NativeFormControlElement[] = [];
 
     constructor(...args: any[]) {
       super(...args);
@@ -208,32 +214,89 @@ export const FormControlMixin = <T extends Constructor<LitElement>>(
      * );
      * @method hasValue
      * @param {FlagTypes} flagKey the type of validation.
-     * @param {method} getMessage method to retrieve relevant message. Is executed every time the validator is re-executed.
+     * @param {method} getMessageMethod method to retrieve relevant message. Is executed every time the validator is re-executed.
      * @param {method} checkMethod method to determine if this validator should invalidate this form control. Return true if this should prevent submission.
      */
     protected addValidator(
       flagKey: FlagTypes,
       getMessageMethod: () => String,
       checkMethod: () => boolean
-    ) {
-      this._validators.push({
+    ): Validator {
+      const obj = {
         flagKey: flagKey,
-        getMessage: getMessageMethod,
+        getMessageMethod: getMessageMethod,
         checkMethod: checkMethod,
-      });
+      };
+      this._validators.push(obj);
+      return obj;
+    }
+
+    protected removeValidator(validator: Validator) {
+      const index = this._validators.indexOf(validator);
+      if (index !== -1) {
+        this._validators.splice(index, 1);
+      }
+    }
+
+    /**
+     * @method addFormControlElement
+     * @description Important notice if adding a native form control then ensure that its value and thereby validity is updated when value is changed from the outside.
+     * @param element {NativeFormControlElement} - element to validate and include as part of this form association.
+     */
+    protected addFormControlElement(element: NativeFormControlElement) {
+      this._formCtrlElements.push(element);
+    }
+
+    private _customValidityObject?: Validator;
+
+    /**
+     * @method setCustomValidity
+     * @description Set custom validity state, set to empty string to remove the custom message.
+     * @param message {string} - The message to be shown
+     * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/HTMLObjectElement/setCustomValidity|HTMLObjectElement:setCustomValidity}
+     */
+    protected setCustomValidity(message: string | null) {
+      if (this._customValidityObject) {
+        this.removeValidator(this._customValidityObject);
+      }
+
+      if (message != null && message !== '') {
+        this._customValidityObject = this.addValidator(
+          'customError',
+          (): string => message,
+          () => true
+        );
+      }
+
+      this._runValidators();
     }
 
     private _runValidators() {
+      this._validityState = {};
+
+      // Loop through inner native form controls to adapt their validityState.
+      this._formCtrlElements.forEach(formCtrlEl => {
+        for (const key in formCtrlEl.validity) {
+          if (key !== 'valid' && (formCtrlEl.validity as any)[key]) {
+            (this as any)._validityState[key] = true;
+            this._internals.setValidity(
+              (this as any)._validityState,
+              formCtrlEl.validationMessage,
+              formCtrlEl
+            );
+          }
+        }
+      });
+
+      // Loop through custom validators, currently its intentional to have them overwritten native validity. but might need to be reconsidered (This current way enables to overwrite with custom messages)
       this._validators.forEach(validator => {
         if (validator.checkMethod()) {
           this._validityState[validator.flagKey] = true;
           this._internals.setValidity(
             this._validityState,
-            validator.getMessage(),
+            validator.getMessageMethod(),
             this.getFormElement()
           );
-        } else {
-          this._validityState[validator.flagKey] = false;
         }
       });
 
@@ -275,6 +338,12 @@ export const FormControlMixin = <T extends Constructor<LitElement>>(
     }
 
     public checkValidity() {
+      for (const key in this._formCtrlElements) {
+        if (this._formCtrlElements[key].checkValidity() === false) {
+          return false;
+        }
+      }
+
       return this._internals?.checkValidity();
     }
 

packages/uui-form/lib/uui-form.story.ts

@@ -81,7 +81,7 @@ export const Overview: Story = () => {
           <uui-label slot="label" required>Email</uui-label>
           <uui-input
             name="email"
-            type="text"
+            type="email"
             label="Email"
             required></uui-input>
         </uui-form-layout-item>

packages/uui-input/lib/uui-input.element.ts

@@ -1,6 +1,6 @@
 import { FormControlMixin } from '@umbraco-ui/uui-base/lib/mixins';
 import { defineElement } from '@umbraco-ui/uui-base/lib/registration';
-import { css, html, LitElement } from 'lit';
+import { css, html, LitElement, PropertyValueMap } from 'lit';
 import { property, query } from 'lit/decorators.js';
 
 import { UUIInputEvent } from './UUIInputEvent';
@@ -246,6 +246,13 @@ export class UUIInputElement extends FormControlMixin(LitElement) {
     );
   }
 
+  protected firstUpdated(
+    _changedProperties: PropertyValueMap<any> | Map<PropertyKey, unknown>
+  ): void {
+    super.firstUpdated(_changedProperties);
+    this.addFormControlElement(this._input);
+  }
+
   /**
    * This method enables <label for="..."> to focus the input
    */
@@ -287,6 +294,7 @@ export class UUIInputElement extends FormControlMixin(LitElement) {
         placeholder=${this.placeholder}
         aria-label=${this.label}
         .disabled=${this.disabled}
+        ?required=${this.required}
         ?readonly=${this.readonly}
         @input=${this._onInput}
         @change=${this._onChange} />

packages/uui-input/lib/uui-input.test.ts

@@ -186,7 +186,7 @@ describe('UuiInput in Form', () => {
       });
     });
 
-    describe('custom error', () => {
+    describe('custom error though attributes', () => {
       beforeEach(async () => {
         element.setAttribute('error', 'true');
         await elementUpdated(element);
@@ -212,5 +212,79 @@ describe('UuiInput in Form', () => {
         expect(formElement.checkValidity()).to.be.true;
       });
     });
+
+    describe('custom error through setCustomValidity', () => {
+      it('sets element to invalid when it sets custom validity', async () => {
+        const validationMessage = 'custom error';
+        element.setCustomValidity(validationMessage);
+        expect(element.checkValidity()).to.be.false;
+        expect(element.validationMessage).to.equal(validationMessage);
+      });
+
+      it('sets the form to invalid when value is empty', async () => {
+        element.setCustomValidity('custom error');
+        expect(formElement.checkValidity()).to.be.false;
+      });
+
+      it('sets element to valid when it sets custom validity to an empty string', async () => {
+        const validationMessage = '';
+        element.setCustomValidity(validationMessage);
+        expect(element.checkValidity()).to.be.true;
+        expect(element.validationMessage).to.equal(validationMessage);
+      });
+
+      it('sets the form to valid when it doesnt have custom validity', async () => {
+        element.setCustomValidity('');
+        expect(formElement.checkValidity()).to.be.true;
+      });
+    });
+  });
+
+  describe('native validation', () => {
+    describe('email', () => {
+      beforeEach(async () => {
+        element.setAttribute('type', 'email');
+        await elementUpdated(element);
+      });
+
+      it('sets element to valid when value is empty', async () => {
+        expect(element.checkValidity()).to.be.true;
+      });
+
+      it('email element is invalid when it has a none compliant value', async () => {
+        element.value = 'new value';
+        await elementUpdated(element);
+        expect(element.checkValidity()).to.be.false;
+      });
+
+      it('email element is valid when it has a email value', async () => {
+        element.value = '[email protected]';
+        await elementUpdated(element);
+        expect(element.checkValidity()).to.be.true;
+      });
+    });
+
+    describe('url', () => {
+      beforeEach(async () => {
+        element.setAttribute('type', 'url');
+        await elementUpdated(element);
+      });
+
+      it('sets element to valid when value is empty', async () => {
+        expect(element.checkValidity()).to.be.true;
+      });
+
+      it('url element is invalid when it has a none compliant value', async () => {
+        element.value = 'new value';
+        await elementUpdated(element);
+        expect(element.checkValidity()).to.be.false;
+      });
+
+      it('url element is valid when it has a email value', async () => {
+        element.value = 'http://umbraco.com';
+        await elementUpdated(element);
+        expect(element.checkValidity()).to.be.true;
+      });
+    });
   });
 });