@nanoporetech-digital/components 2.12.0 → 2.13.0

package/dist/collection/components/field-validator/field-validator.js

@@ -5,7 +5,6 @@ import { Component, Prop, h, Host, Element, State, Watch, Event, Method, } from
 import { createStore } from '@stencil/store';
 /**
  * A toolbox for `nano-...` form fields and form validation.
- *
  * - Easy to add validation accross field dependencies - e.g. "When Field1 contains '123' Field2 must contain '456'"
  * - Easy access to whole form and individual field validity states
  * - Easy access to form data payload
@@ -15,8 +14,15 @@ import { createStore } from '@stencil/store';
 export class FieldValidator {
   constructor() {
     this.submitted = false;
-    this.fields = [];
-    // annoyingly, whenever we attempt to checkValidty it fires `invalid` events.
+    this.allFields = [];
+    this.nanoFieldSelector = `
+    nano-input,
+    nano-select,
+    nano-file-upload,
+    nano-date-input,
+    nano-checkbox
+  `;
+    // annoyingly, whenever we attempt to `checkValidty()` it fires `invalid` events.
     // this is used to prevent infinite loops / multiple calls
     this.internalValidate = false;
     // Public API
@@ -25,12 +31,27 @@ export class FieldValidator {
     /** Tries to scroll to the first invalid field on submit */
     this.scrollToInvalid = true;
     this._dirty = false;
+    /** By default, `nano-field-validator` will also track all native form field elements.
+     * You can add extra web-component form fields to listen to
+     * (as long as they match the standard form field spec) by using the `fieldSelector` prop.
+     */
+    this.extraFieldSelector = 'input, select, textarea';
     // Event handlers
-    /** Fired whenever store values change and potentially checks validity */
+    /**
+     * Fired whenever store values change and potentially checks validity
+     * @param key - the key of the store that's just changed
+     * @param newVal - the incoming, new value
+     */
     this.handleStoreChange = async (key, newVal) => {
-      const found = this.fields.find((field) => field.name === key);
-      if (found && found.value !== newVal)
+      const found = this.allFields.find((field) => field.name === key);
+      // field update has come programmatically (not from ui),
+      // so let's update the underlying ui field
+      if ((found &&
+        found.tagName === 'NANO-FILE-UPLOAD' &&
+        !this.fileStateEqual(key, found)) ||
+        (found.tagName !== 'NANO-FILE-UPLOAD' && found.value !== newVal)) {
         this.storeToFields([found]);
+      }
       if (this.validateOn === 'dirty' && this.dirty) {
         this.internalValidate = true;
         await this.validateAllFields();
@@ -39,17 +60,40 @@ export class FieldValidator {
       }
       this.nanoPayloadChange.emit(this._store.state);
     };
-    /** Handles field value changes and passes to store */
+    /**
+     * Handles nano field value changes and passes to store
+     * @param ev - the incoming change event
+     */
     this.handleFieldChange = (ev) => {
+      if (!this.nanoFields.includes(ev.target))
+        return;
       this._dirty = true;
       this.fieldsToStore([ev.target]);
     };
-    /** Handles default field validation events */
+    /**
+     * Handles non-nano field value changes and passes to store
+     * @param ev - the incoming change event
+     */
+    this.handlePlainFieldChange = (ev) => {
+      if (!this.plainFields.includes(ev.target))
+        return;
+      this.fieldsToStore([ev.target]);
+    };
+    /**
+     * Handles default field validation events
+     * @param ev - the invalid event
+     */
     this.handleFormInvalid = async (ev) => {
-      ev.preventDefault();
+      // if it's a non-nano field, we'll let default html5 validation do it's thing
+      if (!this.plainFields.includes(ev.target)) {
+        ev.preventDefault();
+      }
       this._valid = false;
+      // whenever `checkValidity` is called, this handler is in-turn called.
+      // this flag is used to stop infinite loops
       if (this.internalValidate)
         return;
+      // a submit must have happened to if 'submitThenDirty' turn on 'dirty' checking now
       if (this.validateOn === 'submitThenDirty')
         this.validateOn = 'dirty';
       this.submitted = true;
@@ -69,7 +113,10 @@ export class FieldValidator {
       this.scrollToFirstInvalid();
       this.nanoInvalid.emit();
     };
-    /** stops default form submission, checks if valid, then submits manually  */
+    /**
+     * stops default form submission, checks if valid, then submits manually
+     * @param e - a submit event from the nested form element
+     */
     this.handleSubmit = async (e) => {
       e.preventDefault();
       if (this.validateOn === 'submitThenDirty')
@@ -94,6 +141,7 @@ export class FieldValidator {
     return this._activeForm;
   }
   set activeForm(form) {
+    // manages event listners on whatever form is used (slotted on created here)
     if (!form)
       return;
     if (this._activeForm) {
@@ -104,7 +152,7 @@ export class FieldValidator {
   }
   /** Sync up validateOn with all fields */
   validateOnChange() {
-    this.fields.forEach((field) => {
+    this.nanoFields.forEach((field) => {
       if (field.tagName === 'NANO-CHECKBOX') {
         const cbg = field.closest('nano-checkbox-group');
         if (cbg)
@@ -132,7 +180,7 @@ export class FieldValidator {
   get payload() {
     return this._store.state;
   }
-  /** Returns true if validation errors will be displayed to the user */
+  /** Returns true if validation errors will be displayed to the user. @readonly */
   get showValidation() {
     return (this.validateOn === 'dirty' && this.dirty) || this.submitted;
   }
@@ -149,26 +197,58 @@ export class FieldValidator {
   ```
    */
   get validationState() {
+    // TODO - migrate nano-fields away from using proprietary methods in a bid to be closer to the spec
+    // this is big and ugly.
+    // why? Cos' it must unify checking validity state for both
+    // `nano-...` and plain form fields.
     const validationState = [];
-    this.fields.forEach(async (field) => {
+    this.allFields.forEach(async (field) => {
       const found = validationState.find((v) => v.name === field.name);
+      let pf;
+      let nf;
       if (found) {
-        found.validityMessage = field.validityMessage.length
-          ? field.validityMessage
-          : found.validityMessage;
+        if (field.validationMessage) {
+          pf = field;
+          found.validityMessage = pf.validationMessage.length
+            ? pf.validationMessage
+            : found.validityMessage;
+          this.internalValidate = true;
+          if (found.valid && !pf.checkValidity())
+            found.valid = false;
+          this.internalValidate = false;
+        }
+        else if (field.validityMessage) {
+          nf = field;
+          found.validityMessage = nf.validityMessage.length
+            ? nf.validityMessage
+            : nf.validityMessage;
+          if (found.valid && nf.invalid)
+            found.valid = false;
+        }
         if (!found.fields.find((f) => f === field))
           found.fields.push(field);
-        if (found.valid && field.invalid)
-          found.valid = false;
-        return;
+      }
+      let valid;
+      let validityMessage;
+      if (field.checkValidity) {
+        pf = field;
+        this.internalValidate = true;
+        valid = pf.checkValidity();
+        this.internalValidate = false;
+        validityMessage = pf.validationMessage;
+      }
+      else {
+        nf = field;
+        valid = !nf.invalid;
+        validityMessage = nf.validityMessage;
       }
       validationState.push({
         fields: [field],
         name: field.name,
-        valid: !field.invalid,
         value: this._store.state[field.name],
         dirty: false,
-        validityMessage: field.validityMessage,
+        valid,
+        validityMessage,
       });
     });
     return validationState;
@@ -180,6 +260,24 @@ export class FieldValidator {
   async setStore(state) {
     Object.entries(state).forEach(([key, val]) => (this.store.state[key] = val));
   }
+  /**
+   * Sets custom validity for all / some form fields.
+   * @param validity - a validity object of `{fieldName: errorString}` pairs. Set as an empty string to clear the error.
+   */
+  async setCustomValidity(validity) {
+    return await Promise.all(Object.entries(validity).map(async ([key, err]) => {
+      const field = this.allFields.find((f) => f.name === key);
+      if (!!field)
+        await this.setFieldError(field, err);
+    }));
+  }
+  /**
+   * Clear all custom validation.
+   * @param validity
+   */
+  async resetValidity() {
+    return await Promise.all(this.allFields.map(async (field) => await this.setFieldError(field, '')));
+  }
   // private methods
   attachSlotObserver() {
     if (!!this.mo)
@@ -199,62 +297,66 @@ export class FieldValidator {
   }
   /** Checks for new `nano-...` fields and adds them to our watch array and value store */
   setupFields() {
-    let fields = Array.from(this.host.querySelectorAll(`
-        nano-input,
-        nano-select,
-        nano-file-upload,
-        nano-date-input,
-        nano-checkbox
-      `));
-    fields = fields.filter((f) => !!f.name && !!f.name.length);
+    let nanoFields = Array.from(this.host.querySelectorAll(this.nanoFieldSelector));
+    let plainFields = Array.from(this.host.querySelectorAll(this.extraFieldSelector)).filter((e) => !e.closest(this.nanoFieldSelector));
+    nanoFields = nanoFields.filter((f) => !!f.name && !!f.name.length);
+    plainFields = plainFields.filter((f) => !!f.name && !!f.name.length);
     // do we have any currently un-watched fields?
-    if (!fields.filter((f) => !this.fields.includes(f)).length)
+    if (![...nanoFields, ...plainFields].filter((f) => !this.allFields.includes(f)).length)
       return;
     // setup the initial store state / refresh on new fields
-    this.fields = fields;
-    this.storeToFields(this.fields);
+    this.nanoFields = nanoFields;
+    this.plainFields = plainFields;
+    this.allFields = [...nanoFields, ...plainFields];
+    this.storeToFields(this.allFields);
     this.validateOnChange();
-    this.fieldsToStore(this.fields);
+    this.fieldsToStore(this.allFields);
     this.nanoPayloadChange.emit(this._store.state);
   }
   storeToFields(fields) {
     fields.forEach((field) => {
+      var _a;
       const fieldName = field.name;
       if (!fieldName.length ||
         typeof this._store.state[fieldName] === 'undefined')
         return;
-      switch (field.tagName) {
-        case 'NANO-CHECKBOX':
-          let cb = field;
-          if (cb.type === 'radio' ||
-            cb.type === 'segment' ||
-            cb.type === 'segment-pill') {
-            if (this._store.state[fieldName] === cb.value)
-              cb.checked = true;
-            else
-              cb.checked = false;
-          }
-          else if (Array.isArray(this._store.state[fieldName])) {
-            if (this._store.state[fieldName].includes(cb.value))
-              cb.checked = true;
-            else
-              cb.checked = false;
-          }
-          else {
-            if (this._store.state[fieldName] === cb.value)
-              cb.checked = true;
-            else
-              cb.checked = false;
-          }
-          break;
-        case 'NANO-FILE-UPLOAD':
-          field.files =
-            this._store.state[fieldName];
-          break;
-        default:
-          field.value = this._store.state[fieldName];
-          break;
+      if (field.tagName === 'NANO-CHECKBOX' ||
+        ['radio', 'checkbox'].includes(field.type)) {
+        let cb = field;
+        if (cb.type === 'radio' ||
+          cb.type === 'segment' ||
+          cb.type === 'segment-pill') {
+          // single radio type control
+          if (this._store.state[fieldName] === cb.value)
+            cb.checked = true;
+          else
+            cb.checked = false;
+        }
+        else if (Array.isArray(this._store.state[fieldName])) {
+          // multiple checkbox like controls
+          if (this._store.state[fieldName].includes(cb.value))
+            cb.checked = true;
+          else
+            cb.checked = false;
+        }
+        else {
+          // single checkbox like control
+          if (this._store.state[fieldName] === cb.value)
+            cb.checked = true;
+          else
+            cb.checked = false;
+        }
+        return;
       }
+      if (field.tagName === 'NANO-FILE-UPLOAD') {
+        const ff = field;
+        // this can only work if the field is empty rn... a one-time deal
+        if (!((_a = ff.files) === null || _a === void 0 ? void 0 : _a.length))
+          ff.files = this._store.state[fieldName];
+        return;
+      }
+      // default
+      field.value = this._store.state[fieldName];
     });
   }
   /** Loops through all `nano-...` fields and extracts their values into our store */
@@ -263,52 +365,70 @@ export class FieldValidator {
       const fieldName = field.name;
       if (!fieldName.length)
         return;
-      switch (field.tagName) {
-        case 'NANO-CHECKBOX':
-          let cb = field;
-          if (cb.type === 'radio' ||
-            cb.type === 'segment' ||
-            cb.type === 'segment-pill') {
-            // radio type control - only one can be checked
-            if (cb.checked)
-              this._store.state[fieldName] = cb.value;
-            else if (!cb.checked &&
-              (cb.value === this._store.state[fieldName] ||
-                !this._store.state[fieldName]))
-              this._store.state[fieldName] = '';
-          }
-          else if (this.fields.filter((f) => f.name === fieldName && f.tagName === 'NANO-CHECKBOX').length > 1) {
-            // multiple checkbox type control
-            const currentArr = Array.isArray(this._store.state[fieldName])
-              ? this._store.state[fieldName]
-              : [];
-            if (cb.checked) {
-              if (!this._store.state[fieldName].includes(cb.value)) {
-                this._store.state[fieldName] = [...currentArr, cb.value];
-              }
-            }
-            else {
-              this._store.state[fieldName] = currentArr.filter((v) => v !== cb.value);
+      if (field.tagName === 'NANO-CHECKBOX' ||
+        ['radio', 'checkbox'].includes(field.type)) {
+        let cb = field;
+        if (cb.type === 'radio' ||
+          cb.type === 'segment' ||
+          cb.type === 'segment-pill') {
+          // radio type control - only one can be checked
+          if (cb.checked)
+            this._store.state[fieldName] = cb.value;
+        }
+        else if (this.allFields.filter((f) => f.name === fieldName &&
+          (f.tagName === 'NANO-CHECKBOX' ||
+            f.type === 'checkbox')).length > 1) {
+          // multiple checkbox type control
+          const currentArr = Array.isArray(this._store.state[fieldName])
+            ? this._store.state[fieldName]
+            : [];
+          if (cb.checked) {
+            // checked
+            if (!this._store.state[fieldName].includes(cb.value)) {
+              this._store.state[fieldName] = [...currentArr, cb.value];
             }
           }
           else {
-            // single checkbox - on or off
-            if (cb.checked)
-              this._store.state[fieldName] = cb.value;
-            else
-              this._store.state[fieldName] = '';
+            // unchecked
+            this._store.state[fieldName] = currentArr.filter((v) => v !== cb.value);
           }
-          break;
-        case 'NANO-FILE-UPLOAD':
-          this._store.state[fieldName] = field.files;
-          break;
-        default:
-          this._store.state[fieldName] = field.value;
-          break;
+        }
+        else {
+          // single checkbox - on or off
+          if (cb.checked)
+            this._store.state[fieldName] = cb.value;
+          else
+            this._store.state[fieldName] = '';
+        }
+        return;
       }
+      if (field.tagName === 'NANO-FILE-UPLOAD') {
+        const ff = field;
+        if (!this.fileStateEqual(fieldName, ff))
+          this._store.state[fieldName] = ff.files;
+        return;
+      }
+      // default
+      this._store.state[fieldName] = field.value;
     });
   }
-  /** Checks for user defined validations */
+  /**
+   * Tries to ascertain whether the current model
+   * value is the same as the `nano-file-upload` value
+   * @param fieldName - the key to access from the data store
+   * @param field - the nano-file-upload field to assess against
+   * @returns true for equal, false for not equal
+   */
+  fileStateEqual(fieldName, field) {
+    return (JSON.stringify(this._store.state[fieldName]) ===
+      JSON.stringify(field.files) ||
+      this._store.state[fieldName] == field.files);
+  }
+  /**
+   * Checks for user defined validations
+   * @param key - current key of the data model to validate
+   * @param newVal - the newly set, incoming value to validate
+   */
   async validate(key, newVal) {
     if (!this.validation)
       return;
@@ -321,21 +441,33 @@ export class FieldValidator {
     // collection loop into a promise
     await Promise.all(Object.entries(res).map(async ([key, o]) => {
       // switch on/off validation messages
-      const field = this.fields.find((f) => f.name === key);
+      const field = this.allFields.find((f) => f.name === key);
       let validityTarget = field;
       if (field.tagName === 'NANO-CHECKBOX') {
+        // if we have a checkbox-group, set the validation message there
         const cbg = field.closest('nano-checkbox-group');
         validityTarget = cbg || field;
       }
-      // status is now valid - clear the error
-      if (validityTarget.validityMessage === o.msg && o.valid)
+      if ((validityTarget.validityMessage ||
+        validityTarget.validationMessage) === o.msg &&
+        o.valid) {
+        // status is now valid - clear the error
         await this.setFieldError(validityTarget, '');
-      // status is invalid. Set the error
+      }
       else if (!o.valid) {
+        // status is invalid. Set the error
         await this.setFieldError(validityTarget, o.msg);
       }
     }));
   }
+  /** Loops through all store entries and checks custom validation */
+  async validateAllFields() {
+    // This forces our loop to `await` and finish sequentially ... silly async stencil methods
+    await Object.entries(this._store.state).reduce(async (memo, [key, value]) => {
+      await memo;
+      await this.validate(key, value);
+    }, undefined);
+  }
   /**
    * Utility to smooth out setting error messages
    * (it's a different method on `nano-checkbox` 'cos they don't show errors themselves)
@@ -345,16 +477,10 @@ export class FieldValidator {
   async setFieldError(field, msg) {
     if (field['showError'])
       await field.showError(msg);
-    else
+    else if (field['setError'])
       await field.setError(msg);
-  }
-  /** Loops through all store entries and checks field validity */
-  async validateAllFields() {
-    // This forces our loop to `await` and finish sequentially ... silly async stencil methods
-    await Object.entries(this._store.state).reduce(async (memo, [key, value]) => {
-      await memo;
-      await this.validate(key, value);
-    }, undefined);
+    else
+      field.setCustomValidity(msg);
   }
   scrollToFirstInvalid() {
     if (!this.scrollToInvalid)
@@ -383,17 +509,21 @@ export class FieldValidator {
     requestAnimationFrame(() => {
       this.setupFields();
       this.attachSlotObserver();
-      this._store.on('set', (key, value) => this.handleStoreChange(key, value));
       this.host.addEventListener('nanoChange', this.handleFieldChange);
+      this.host.addEventListener('input', this.handlePlainFieldChange);
+      this.host.addEventListener('change', this.handlePlainFieldChange);
       this.host.addEventListener('submit', this.handleSubmit);
+      this._store.on('set', this.handleStoreChange);
     });
   }
   disconnectedCallback() {
     if (this.mo)
       this.mo.disconnect();
-    this._store.reset();
     this.host.removeEventListener('nanoChange', this.handleFieldChange);
+    this.host.removeEventListener('input', this.handlePlainFieldChange);
+    this.host.removeEventListener('change', this.handlePlainFieldChange);
     this.host.removeEventListener('submit', this.handleSubmit);
+    this._store.reset();
     if (this.activeForm)
       this.activeForm.removeEventListener('invalid', this.handleFormInvalid, true);
   }
@@ -530,7 +660,7 @@ export class FieldValidator {
       "optional": false,
       "docs": {
         "tags": [],
-        "text": "Returns true if validation errors will be displayed to the user"
+        "text": "Returns true if validation errors will be displayed to the user. @readonly"
       },
       "getter": true,
       "setter": false,
@@ -546,7 +676,15 @@ export class FieldValidator {
         "references": {
           "ValidationState": {
             "location": "import",
-            "path": "/builds/VuwsCczH/0/Digital/nano-components/packages/components/src/interface.d.ts"
+            "path": "/builds/f85YXDf1/0/Digital/nano-components/packages/components/src/interface.d.ts"
+          },
+          "PlainFormEles": {
+            "location": "import",
+            "path": "/builds/f85YXDf1/0/Digital/nano-components/packages/components/src/interface.d.ts"
+          },
+          "NanoFormEles": {
+            "location": "import",
+            "path": "/builds/f85YXDf1/0/Digital/nano-components/packages/components/src/interface.d.ts"
           }
         }
       },
@@ -559,6 +697,26 @@ export class FieldValidator {
       "getter": true,
       "setter": false
     },
+    "extraFieldSelector": {
+      "type": "string",
+      "mutable": false,
+      "complexType": {
+        "original": "string",
+        "resolved": "string",
+        "references": {}
+      },
+      "required": false,
+      "optional": false,
+      "docs": {
+        "tags": [],
+        "text": "By default, `nano-field-validator` will also track all native form field elements.\nYou can add extra web-component form fields to listen to\n(as long as they match the standard form field spec) by using the `fieldSelector` prop."
+      },
+      "getter": false,
+      "setter": false,
+      "attribute": "extra-field-selector",
+      "reflect": false,
+      "defaultValue": "'input, select, textarea'"
+    },
     "validation": {
       "type": "unknown",
       "mutable": false,
@@ -568,7 +726,7 @@ export class FieldValidator {
         "references": {
           "ValidatorValueStore": {
             "location": "import",
-            "path": "/builds/VuwsCczH/0/Digital/nano-components/packages/components/src/interface.d.ts"
+            "path": "/builds/f85YXDf1/0/Digital/nano-components/packages/components/src/interface.d.ts"
           }
         }
       },
@@ -595,8 +753,8 @@ export class FieldValidator {
     }
   }; }
   static get states() { return {
-    "userForm": {},
     "submitted": {},
+    "userForm": {},
     "_dirty": {},
     "_valid": {},
     "_store": {}
@@ -617,7 +775,7 @@ export class FieldValidator {
         "references": {
           "ValidatorValueStore": {
             "location": "import",
-            "path": "/builds/VuwsCczH/0/Digital/nano-components/packages/components/src/interface.d.ts"
+            "path": "/builds/f85YXDf1/0/Digital/nano-components/packages/components/src/interface.d.ts"
           }
         }
       }
@@ -669,7 +827,7 @@ export class FieldValidator {
           },
           "ValidatorValueStore": {
             "location": "import",
-            "path": "/builds/VuwsCczH/0/Digital/nano-components/packages/components/src/interface.d.ts"
+            "path": "/builds/f85YXDf1/0/Digital/nano-components/packages/components/src/interface.d.ts"
           }
         },
         "return": "Promise<void>"
@@ -681,6 +839,50 @@ export class FieldValidator {
             "text": "state - the state to load in the store"
           }]
       }
+    },
+    "setCustomValidity": {
+      "complexType": {
+        "signature": "(validity: { [key: string]: string; }) => Promise<void[]>",
+        "parameters": [{
+            "tags": [{
+                "name": "param",
+                "text": "validity - a validity object of `{fieldName: errorString}` pairs. Set as an empty string to clear the error."
+              }],
+            "text": "- a validity object of `{fieldName: errorString}` pairs. Set as an empty string to clear the error."
+          }],
+        "references": {
+          "Promise": {
+            "location": "global"
+          }
+        },
+        "return": "Promise<void[]>"
+      },
+      "docs": {
+        "text": "Sets custom validity for all / some form fields.",
+        "tags": [{
+            "name": "param",
+            "text": "validity - a validity object of `{fieldName: errorString}` pairs. Set as an empty string to clear the error."
+          }]
+      }
+    },
+    "resetValidity": {
+      "complexType": {
+        "signature": "() => Promise<void[]>",
+        "parameters": [],
+        "references": {
+          "Promise": {
+            "location": "global"
+          }
+        },
+        "return": "Promise<void[]>"
+      },
+      "docs": {
+        "text": "Clear all custom validation.",
+        "tags": [{
+            "name": "param",
+            "text": "validity"
+          }]
+      }
     }
   }; }
   static get elementRef() { return "host"; }
@@ -690,6 +892,9 @@ export class FieldValidator {
     }, {
       "propName": "validateOn",
       "methodName": "validateOnChange"
+    }, {
+      "propName": "extraFieldSelector",
+      "methodName": "attachSlotObserver"
     }]; }
 }
 //# sourceMappingURL=field-validator.js.map