@energycap/components 0.39.21-ECAP-25650-file-upload-validation-support.20240806-0942 → 0.39.21-ECAP-25650-file-upload-validation-support.20240806-1534

package/fesm2020/energycap-components.mjs

@@ -4106,7 +4106,9 @@ const FileTypeExtensions = {
 };
 class FileUploadComponent extends FormControlBase {
     // static class to create the form group from a parent component
-    static getFormModel(validators, disabled = false, fileValidators) {
+    static getFormModel(validators, disabled = false, 
+    /** Any validators required to make sure the selected file is valid. It is recommended that you use `FileUploadComponent.getFileValidator` to help construct the validator(s). NOTE: This currently only works when multiSelect is false. */
+    fileValidators) {
         let formGroup = new FormGroup({
             file: new FormControl({ value: null, disabled: disabled }, { validators: validators, asyncValidators: fileValidators }),
             name: new FormControl({ value: null, disabled: disabled }, validators),
@@ -4118,10 +4120,18 @@ class FileUploadComponent extends FormControlBase {
         }
         return formGroup;
     }
+    /**
+     * Helper function that returns an async validator to be used with the file upload control.
+     * This is useful for when the file needs to be validated before it can be uploaded.
+     *
+     * @param callback The callback function that will be called to validate the file. Parameters for the callback are the file and the base64 string for the file.
+     * base64 is null if the fileOutput input on the FileUploadComponent is set to raw. Using fileOutput set to base64 is recommended for images.
+     */
     static getFileValidator(callback) {
         return async (control) => {
             if (control.value && control.parent) {
                 let file = control.value;
+                // For images, we need the base64 string to validate image dimensions
                 let base64 = control.parent.get('base64FileString')?.value;
                 return await callback(file, base64);
             }
@@ -4173,7 +4183,8 @@ class FileUploadComponent extends FormControlBase {
                 });
             }
         });
-        // Sync errors from the file control to the name control whenever the file control status changes
+        // Sync errors from the file control to the name control whenever the file control status changes.
+        // The name control is the only one displayed to the user so we need to show the errors there.
         this.formModel.get('file')?.statusChanges.pipe(takeUntil(this.componentDestroyed)).subscribe(() => {
             const errors = this.formModel.get('file')?.errors ?? null;
             this.formModel.get('name')?.setErrors(errors);
@@ -4218,26 +4229,47 @@ class FileUploadComponent extends FormControlBase {
      * @param file
      * @param base64FileString Optional: Will have a value provided if the fileOutput is set to base64
      */
-    async processFile(file, base64FileString) {
+    async processFile(file, base64FileString = null) {
+        // If we have async validators on the file control we need to do validation before we trigger the upload
+        const validateBeforeUpload = !!this.formModel.controls.file.asyncValidator;
+        if (validateBeforeUpload) {
+            await this.validateFile(file, base64FileString);
+        }
+        if (this.onFileSelected) {
+            // Only call the onFileSelected callback to upload the file if the form group is valid
+            if (this.formModel.valid) {
+                try {
+                    let result = await this.onFileSelected(file);
+                    // If we did validation, just patch the form result because the file is already in the form
+                    if (validateBeforeUpload) {
+                        this.formModel.patchValue({ uploadResult: result ?? null });
+                    }
+                    else {
+                        this.formModel.patchValue({ file, name: file.name, base64FileString, uploadResult: result ?? null });
+                    }
+                }
+                catch (e) {
+                    // Bummer, we're not going to do anything about it though.
+                    // We are not patching any of the result so any existing information remains
+                }
+            }
+            // If we don't have an onFileSelected callback we just patch the form model.
+            // In the case of pre-upload validation the form already has the file so we don't want to patch again.
+        }
+        else if (!validateBeforeUpload) {
+            this.formModel.patchValue({ file, name: file.name, base64FileString, uploadResult: null });
+        }
+    }
+    /** Patches the form with the selected file in order to trigger control validation */
+    async validateFile(file, base64FileString = null) {
         // Patch the file first to trigger any file validators
-        this.patchProcessedFile(file, base64FileString);
+        this.formModel.patchValue({ file, name: file.name, base64FileString, uploadResult: null });
         // If we have any async validators pending we need to wait for them to complete before we know if the form is valid
         if (this.formModel.pending) {
             await this.formModel.statusChanges.pipe(filter(status => status !== 'PENDING'), take(1), takeUntil(this.componentDestroyed)).toPromise();
         }
         // Mark the name control as touched so that any validation errors will show
         this.formModel.controls.name.markAsTouched();
-        // Only call the onFileSelected callback to upload the file if the form is valid
-        if (this.onFileSelected && this.formModel.valid) {
-            try {
-                let result = await this.onFileSelected(file);
-                this.formModel.patchValue({ uploadResult: result ?? null });
-            }
-            catch (e) {
-                // Bummer, we're not going to do anything about it though.
-                // We are not patching any of the result so any existing information remains
-            }
-        }
     }
     /**
      * Based on the fileOutput return whether this component is expected to deliver a base64 output
@@ -4246,21 +4278,6 @@ class FileUploadComponent extends FormControlBase {
     isBase64FileOutput() {
         return this.fileOutput === 'base64';
     }
-    /**
-     * When the file was selected and processed patch the file information that the hosting form will
-     * be looking for.
-     * @param file
-     * @param base64FileString
-     * @param onFileSelectedResult
-     */
-    patchProcessedFile(file, base64FileString) {
-        this.formModel?.patchValue({
-            file: file,
-            name: file?.name,
-            base64FileString: base64FileString ?? null,
-            uploadResult: null
-        });
-    }
     /** Maps the files to an array of File objects and sends them along
      * to the derived onMultipleFileSelected method in the hosting component
      */
@@ -10598,6 +10615,8 @@ class PageBaseComponent {
      * @param event
      */
     async onSave(event) {
+        // Show the saving overlay in case we have async validators in play
+        this.showStatus(PageStatus.Saving);
         this.formGroup.markAllAsTouched();
         // If the form has pending async validators, wait for it them to complete before proceeding
         if (this.formGroup.pending) {
@@ -10607,6 +10626,8 @@ class PageBaseComponent {
             await this.save();
         }
         else {
+            // Remove the saving overlay to display any errors
+            this.showStatus(PageStatus.Loaded);
             // Only show the banner with the generic message if the parent component hasn't already set one
             // by implementing onSave for additional validation
             if (this.errors === '') {