@acpaas-ui/ngx-forms 6.1.8 → 6.1.10

package/src/lib/upload/README.md

@@ -0,0 +1,283 @@
+# @acpaas-ui/ngx-forms
+
+The upload module provides a couple of upload components and an `Uploader` class.
+
+- `<aui-upload>` component
+- `<aui-upload-zone>` component
+- `<aui-upload-queue>` component
+- `<aui-validation-list>` component
+- `Uploader` class (non-angular service)
+
+## Usage
+
+```typescript
+import { UploadModule } from '@acpaas-ui/ngx-forms';
+```
+
+Add a map with error messages for the validation
+
+```typescript
+UploadModule.forChild({
+  INVALID_FILE_TYPE: 'Ongeldig bestandstype',
+  INVALID_FILE_SIZE: 'Ongeldige bestandsgrootte',
+  INVALID_MIME_TYPE: 'Ongeldig mime type',
+});
+```
+
+## Documentation
+
+Visit our [documentation site](https://antwerp-ui.digipolis.be/) for full how-to docs and guidelines
+
+### API
+
+#### `<aui-upload>`
+
+This component wraps the `upload-zone`, `upload-queue` and `validation-list`, it is recommended to use this component instead of the individual `upload-zone` and `upload-queue` but it's not required.
+
+| Name                                                    | Default value            | Description                                                                                                                                                                                               |
+| ------------------------------------------------------- | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `@Input() options: UploadOptions;`                      | `UPLOAD_OPTIONS_DEFAULT` | An instance of the UploadOptions interface that is part of the Uploader class. Its different options and there default values that are defined in `UPLOAD_OPTIONS_DEFAULT` are explained in detail below. |
+| `@Input() data-id: string;`                             | `''`                     | An id that can be used in combination with a label's for attribute.                                                                                                                                       |
+| `@Input() ariaLabelRemove: string;`                     | `'Verwijder'`            | The 'delete' text that is used for screenreaders.                                                                                                                                                         |
+| `@Input() disabled: boolean;`                           | `false`                  | Optional attribute to set the upload and the upload zone disabled.                                                                                                                                        |
+| `@Input() multiple: boolean;`                           | `true`                   | Optional attribute to restrict the number of uploaded files to be selected.                                                                                                                               |
+| `@Input() accept: boolean;`                             | `true`                   | Optional accept attribute to define the type of files that can be selected.                                                                                                                               |
+| `@Output() selectUploadedFiles: EventEmitter<Object[]>` | -                        | On a successful upload, this will emit the response of the backend. This should be an array of objects with the uploaded filename and url.                                                                |
+
+#### `<aui-upload-zone>`
+
+This component provides the upload functionality.
+
+| Name                                                   | Default value                      | Description                                                                                                                                                                                                           |
+| ------------------------------------------------------ | ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `@Input() uploader: Uploader;`                         | -                                  | An instance of the Uploader class. This class handles the validation and upload of a file. Its different options and there default values that are defined in `UPLOAD_OPTIONS_DEFAULT` are explained in detail below. |
+| `@Input() multiple: boolean;`                          | `true`                             | Enable the HTML `multiple` attribute so the user can select multiple files to upload.                                                                                                                                 |
+| `@Input() id: string;`                                 | `''`                               | An id that can be used in combination with a label's for attribute.                                                                                                                                                   |
+| `@Input() ariaId: string;`                             | `[random id when no id was given]` | An id that can be used when you don't want a visible label.                                                                                                                                                           |
+| `@Input() disabled: boolean;`                          | `false`                            | Optional attribute to set the upload zone disabled.                                                                                                                                                                   |
+| `@Input() multiple: boolean;`                          | `true`                             | Optional attribute to restrict the number of uploaded files to be selected.                                                                                                                                           |
+| `@Input() accept: boolean;`                            | `true`                             | Optional accept attribute to define the type of files that can be selected.                                                                                                                                           |
+| `@Output() uploadedFiles: EventEmitter<Object[]>;`     | -                                  | Emits an array of files that were uploaded.                                                                                                                                                                           |
+| `@Output() queuedFiles: EventEmitter<File[]>;`         | -                                  | Emits an array of file objects that have past the validation and are ready to be uploaded.                                                                                                                            |
+| `@Output() invalidFiles: EventEmitter<InvalidFile[]>;` | -                                  | Emits an array of invalid files and the reason why they are invalid.                                                                                                                                                  |
+
+#### `<aui-upload-queue>`
+
+This component provides a list of queued files.
+
+| Name                                              | Default value | Description                                                                                                                                                                                                           |
+| ------------------------------------------------- | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `@Input() files: File[];`                         | -             | An array of files.                                                                                                                                                                                                    |
+| `@Input() uploader: Uploader;`                    | -             | An instance of the Uploader class. This class handles the validation and upload of a file. Its different options and there default values that are defined in `UPLOAD_OPTIONS_DEFAULT` are explained in detail below. |
+| `@Input() ariaLabelRemove: string;`               | `'Verwijder'` | The 'delete' text that is used for screenreaders.                                                                                                                                                                     |
+| `@Output() uploadedFiles: EventEmitter<Object[]>` | -             | Emits an array of files that were uploaded.                                                                                                                                                                           |
+
+#### `<aui-validation-list>`
+
+This component displays possible error messages.
+
+| Name                                    | Default value | Description                                                    |
+| --------------------------------------- | ------------- | -------------------------------------------------------------- |
+| `@Input() invalidFiles: InvalidFile[];` | `[]`          | An array of invalid files and the reason why they are invalid. |
+| `@Input() ariaLabelRemove: string;`     | `'Verwijder'` | The 'delete' text that is used for screenreaders.              |
+
+#### `Uploader`
+
+This class handles the validation and upload of a file.
+
+##### `UploadOptions`
+
+| Name                          | Default value | Description                                                                                                  |
+| ----------------------------- | ------------- | ------------------------------------------------------------------------------------------------------------ |
+| `allowedMimeTypes: string[];` | `[]`          | The MIME types that are allowed to be uploaded.                                                              |
+| `allowedFileTypes: string[];` | `[]`          | The file extensions that are allowed to be uploaded.                                                         |
+| `autoUpload: boolean;`        | `false`       | Upload the file automatically without confirmation.                                                          |
+| `maxFileSize: number;`        | `0`           | The maximum file size that is allowed. The value is expressed in Bytes. The value 0 equals infinite.         |
+| `queueLimit: number;`         | `0`           | The maximum number of files that can be selected at the same time. The value 0 equals infinite.              |
+| `type: string;`               | `'drop'`      | By default an upload has an `upload-zone` but with the option `'button'`, you can set it as an uploadbutton. |
+| `url: string;`                | `''`          | The upload url.                                                                                              |
+
+#### Example
+
+```typescript
+import { UploadModule } from '@acpaas-ui/ngx-forms';
+
+@NgModule({
+    imports: [
+        UploadModule
+    ]
+});
+
+export class AppModule {};
+```
+
+**Basic upload**
+
+```typescript
+public dropzone1: UploadOptions = {
+    allowedMimeTypes: ['image/jpeg'],
+    maxFileSize: 10000000,
+    queueLimit: 2,
+    type: 'drop',
+    url: 'api/upload',
+};
+```
+
+```html
+<aui-upload [options]="dropzone1" (selectUploadedFiles)="onUpload($event)">
+  <div class="m-upload__message">Drag your files here or click to upload</div>
+  <div class="m-upload__description">Optional description message</div>
+</aui-upload>
+```
+
+**Upload button**
+
+```typescript
+public dropzone2: UploadOptions = {
+    type: 'button',
+    allowedFileTypes: ['.jpg', 'jpeg', 'png'],
+    autoUpload: true,
+    maxFileSize: 2000000,
+    url: 'api/upload',
+};
+```
+
+```html
+<div class="u-margin-bottom">
+  <aui-upload [options]="dropzone2" (selectUploadedFiles)="onUpload($event)">
+    <div class="m-upload__button">Select your files to upload</div>
+  </aui-upload>
+</div>
+```
+
+**Custom upload**
+
+```typescript
+import { Uploader } from '@acpaas-ui/ngx-forms';
+```
+
+```typescript
+public files = [];
+public invalidFiles: InvalidFile[] = [];
+public queuedFiles: File[] = [];
+public uploadedFiles: File[] = [];
+// Pass created options into new instance of Uploader
+public uploader = new Uploader({
+    allowedFileTypes: ['jpg', 'jpeg', 'png'],
+    type: 'drop',
+    url: 'api/upload',
+});
+public showError = false;
+public fileName = '';
+});
+```
+
+```typescript
+public onQueuedFiles(files: File[]) {
+    if (!files.length) {
+        return;
+    }
+    this.queuedFiles = this.queuedFiles.concat(files);
+}
+
+public onUploadedFiles(files) {
+    this.uploadedFiles = this.uploadedFiles.concat(files);
+}
+
+public onInvalidFiles(errorFiles: InvalidFile[]) {
+    this.invalidFiles = errorFiles;
+    if (errorFiles.length > 0) {
+        this.fileName = this.invalidFiles[0]['file'].name;
+        this.showError = true;
+        this.invalidFiles = [];
+    } else {
+        this.showError = false;
+    }
+}
+
+public reloadErrors() {
+    this.showError = false;
+    if (!this.queuedFiles.length) {
+        return;
+    }
+}
+
+/**
+ * Using the uploader url option
+ */
+
+public uploadFiles(): void {
+// Upload files returns an obervable
+this.uploader.uploadFiles(this.queuedFiles).subscribe(
+    (response) => {
+        // Response has a progress property to use with a progress bar
+        if (response.progress) {
+            console.log('response.progress = ', response.progress);
+        }
+        // Response had a data property with an array of uploaded files: UploadedFile[]
+        if (response.data) {
+            console.log('response.data = ', response.data);
+        }
+        this.uploadedFiles = response.data;
+    },
+    (err) => {
+        console.log('HTTP Error', err);
+    });
+}
+
+/**
+ * Using a custom upload service
+ */
+
+// public uploadFiles(): void {
+//     if (!this.queuedFiles.length) {
+//         return;
+//     }
+//     this.customService.postFile(this.queuedFiles).subscribe(res => {
+//         this.result = res;
+//     }, (error) => {
+//         console.log(error);
+//     });
+// }
+```
+
+```scss
+::ng-deep .a-upload-queue__wrapper {
+  .a-button {
+    display: none;
+  }
+}
+```
+
+```html
+<aui-upload-zone
+  [uploader]="uploader"
+  (queuedFiles)="onQueuedFiles($event)"
+  (uploadedFiles)="onUploadedFiles($event)"
+  (invalidFiles)="onInvalidFiles($event)"
+>
+  <div class="m-upload__message">Drag your files here or click to upload</div>
+  <div class="m-upload__description">Maximum filesize: 10 MB, File extension: jpg, jpeg, png</div>
+</aui-upload-zone>
+<aui-upload-queue [files]="queuedFiles"></aui-upload-queue>
+<div *ngIf="showError" class="u-margin-bottom">
+  <ul class="m-upload__files">
+    <li class="is-error">
+      <aui-icon name="ai-alert-triangle"></aui-icon>
+      <span class="m-upload__filename">{{ fileName }}</span>
+      <span class="m-upload__error">This file extension is not allowed.</span>
+      <button
+        type="button"
+        (click)="reloadErrors()"
+        class="m-upload__delete a-button a-button--text a-button--danger a-button--s has-icon"
+      >
+        <aui-icon name="ai-remove"></aui-icon>
+      </button>
+    </li>
+  </ul>
+</div>
+```
+
+## Contributing
+
+Visit our [Contribution Guidelines](../../../../../CONTRIBUTING.md) for more information on how to contribute.

package/src/lib/upload/classes/uploader.class.spec.ts

@@ -0,0 +1,100 @@
+import { UPLOAD_OPTIONS_DEFAULT } from '../upload.conf';
+import { UploadOptions } from '../types/upload.types';
+
+import { Uploader } from './uploader.class';
+
+describe('Uploader', () => {
+  const uploadResponse = [
+    {
+      url: 'http://localhost/myfile',
+      name: 'myFile',
+    },
+  ];
+
+  beforeEach(() => {});
+
+  it('should have default options', () => {
+    const uploader = new Uploader();
+    expect(uploader.options).toEqual(UPLOAD_OPTIONS_DEFAULT);
+  });
+
+  it('should merge custom options with default options', () => {
+    const options: UploadOptions = {
+      type: 'button',
+      maxFileSize: 20000,
+    };
+
+    const uploader = new Uploader(options);
+    const result = Object.assign({}, UPLOAD_OPTIONS_DEFAULT, options);
+    expect(uploader.options).toEqual(result);
+  });
+
+  it('should validate file type', () => {
+    let result;
+    let f;
+    const date = new Date();
+    const uploader = new Uploader({
+      allowedFileTypes: ['jpg'],
+    });
+
+    f = new File([''], 'filename.txt', { type: 'text/plain', lastModified: date.getTime() });
+    result = uploader.validateFiles([f]);
+    expect(result.validFiles.length).toEqual(0);
+    expect(result.invalidFiles.length).toEqual(1);
+
+    f = new File([''], 'filename.jpg', { type: 'image/jpeg', lastModified: date.getTime() });
+    result = uploader.validateFiles([f]);
+    expect(result.validFiles.length).toEqual(1);
+    expect(result.invalidFiles.length).toEqual(0);
+  });
+
+  it('should validate mime type', () => {
+    let result;
+    let f;
+    const date = new Date();
+    const uploader = new Uploader({
+      allowedMimeTypes: ['image/jpeg'],
+    });
+
+    f = new File([''], 'filename.txt', { type: 'text/plain', lastModified: date.getTime() });
+    result = uploader.validateFiles([f]);
+    expect(result.validFiles.length).toEqual(0);
+    expect(result.invalidFiles.length).toEqual(1);
+
+    f = new File([''], 'filename.jpg', { type: 'image/jpeg', lastModified: date.getTime() });
+    result = uploader.validateFiles([f]);
+    expect(result.validFiles.length).toEqual(1);
+    expect(result.invalidFiles.length).toEqual(0);
+  });
+
+  it('should validate max file size', () => {
+    let result;
+    let f;
+    const date = new Date();
+    const uploader = new Uploader({
+      maxFileSize: 2,
+    });
+
+    f = new File(['takesomespace'], 'filename.txt', { type: 'text/plain', lastModified: date.getTime() });
+    result = uploader.validateFiles([f]);
+    expect(result.validFiles.length).toEqual(0);
+    expect(result.invalidFiles.length).toEqual(1);
+
+    f = new File(['a'], 'filename.jpg', { type: 'image/jpeg', lastModified: date.getTime() });
+    result = uploader.validateFiles([f]);
+    expect(result.validFiles.length).toEqual(1);
+    expect(result.invalidFiles.length).toEqual(0);
+  });
+
+  it('should throw an error if no upload url is defined', () => {
+    const date = new Date();
+    const uploader = new Uploader({
+      maxFileSize: 2,
+    });
+
+    const f = new File(['takesomespace'], 'filename.txt', { type: 'text/plain', lastModified: date.getTime() });
+    expect(() => {
+      uploader.uploadFiles([f]);
+    }).toThrow(Error('Define the upload url.'));
+  });
+});

package/src/lib/upload/classes/uploader.class.ts

@@ -0,0 +1,144 @@
+import { Observable } from 'rxjs';
+
+import { UPLOAD_OPTIONS_DEFAULT } from '../upload.conf';
+import { InvalidFile, UploadOptions } from '../types/upload.types';
+
+export class Uploader {
+  public options: UploadOptions = UPLOAD_OPTIONS_DEFAULT;
+
+  constructor(options?: UploadOptions) {
+    this.setOptions(options);
+  }
+
+  public setOptions(options) {
+    this.options = Object.assign({}, this.options, options);
+  }
+
+  public uploadFiles(files: File[]): Observable<{ progress: number, data: object[] }> {
+    const formData: FormData = this.filesToFormData(files);
+
+    return new Observable(observer => {
+      const xhr = new XMLHttpRequest();
+
+      // Progress callback
+      xhr.upload.addEventListener('progress', (e) => {
+        if (e.lengthComputable) {
+          const percentComplete = e.loaded / e.total;
+
+          observer.next({
+            progress: percentComplete,
+            data: null,
+          });
+        }
+      });
+
+      // Complete callback
+      xhr.onload = () => {
+        observer.next({
+          progress: 1,
+          data: xhr.response,
+        });
+        // observer.complete();
+      };
+
+      // Do request
+      xhr.responseType = 'json';
+      xhr.open('post', this.options.url);
+      xhr.send(formData);
+    });
+  }
+
+  public validateFiles(files) {
+    const validFiles: File[] = [];
+    const invalidFiles: InvalidFile[] = [];
+
+    if (files.length > 0) {
+
+      for (const file of files) {
+        const errors = [];
+
+        if (!this.validateFileType(file)) {
+          errors.push('INVALID_FILE_TYPE');
+        }
+
+        if (!this.validateFileSize(file)) {
+          errors.push('INVALID_FILE_SIZE');
+        }
+
+        if (!this.validateMimeType(file)) {
+          errors.push('INVALID_MIME_TYPE');
+        }
+
+        if (errors.length === 0) {
+          validFiles.push(file);
+        } else {
+          invalidFiles.push({
+            reasons: errors,
+            file,
+          });
+        }
+      }
+    }
+
+    return {
+      validFiles,
+      invalidFiles,
+    };
+  }
+
+  protected filesToFormData(files: File[]): FormData {
+    const formData = new FormData();
+
+    if (!this.options.url || this.options.url === '') {
+      throw new Error('Define the upload url.');
+    }
+
+    for (const file of files) {
+      formData.append('file', file);
+    }
+
+    return formData;
+  }
+
+  protected getFileExtension(file: File): string {
+    return file.name.split('.')[file.name.split('.').length - 1];
+  }
+
+  protected validateFileType(file: File): boolean {
+    const allowedFileTypes = this.options.allowedFileTypes;
+    const ext = this.getFileExtension(file);
+
+    // Filter defined?
+    if (!Array.isArray(allowedFileTypes) || allowedFileTypes.length === 0) {
+      return true;
+    }
+
+    // Make allowedFileTypes case insensitive
+    const toUpper = (x) => x.toUpperCase();
+    const allowedFileTypesToUpper = allowedFileTypes.map(toUpper);
+
+    return allowedFileTypesToUpper.lastIndexOf(ext.toUpperCase()) !== -1;
+  }
+
+  protected validateFileSize(file: File): boolean {
+    const maxFileSize = this.options.maxFileSize;
+
+    // Filter defined?
+    if (!maxFileSize || maxFileSize === 0) {
+      return true;
+    }
+
+    return maxFileSize > file.size;
+  }
+
+  protected validateMimeType(file: File): boolean {
+    const allowedMimeTypes = this.options.allowedMimeTypes;
+
+    // Filter defined?
+    if (!Array.isArray(allowedMimeTypes) || allowedMimeTypes.length === 0) {
+      return true;
+    }
+
+    return allowedMimeTypes.lastIndexOf(file.type) !== -1;
+  }
+}

package/src/lib/upload/components/upload/upload.component.html

@@ -0,0 +1,28 @@
+<div class="m-upload aui-upload">
+  <aui-upload-zone
+    [id]="id"
+    [accept]="accept"
+    [capture]="capture"
+    [ariaId]="ariaId"
+    [disabled]="disabled"
+    [multiple]="multiple"
+    [uploader]="uploader"
+    (invalidFiles)="onInvalidFiles($event)"
+    (queuedFiles)="onQueuedFiles($event)"
+    (uploadedFiles)="onUploadedFiles($event)"
+    [label]="label"
+    [description]="description"
+  >
+    <div class="m-upload__button">
+      <ng-content select=".m-upload__button"></ng-content>
+    </div>
+  </aui-upload-zone>
+  <aui-validation-list [ariaLabelRemove]="ariaLabelRemove" [invalidFiles]="invalidFiles"></aui-validation-list>
+  <aui-upload-queue
+    (uploadedFiles)="onUploadedFiles($event)"
+    *ngIf="!options?.autoUpload"
+    [ariaLabelRemove]="ariaLabelRemove"
+    [files]="queuedFiles"
+    [uploader]="uploader"
+  ></aui-upload-queue>
+</div>

package/src/lib/upload/components/upload/upload.component.scss

@@ -0,0 +1,3 @@
+.m-upload__button {
+  position: relative;
+}

package/src/lib/upload/components/upload/upload.component.spec.ts

@@ -0,0 +1,117 @@
+import { Component, DebugElement, Input } from '@angular/core';
+import { waitForAsync, ComponentFixture, TestBed } from '@angular/core/testing';
+import { By } from '@angular/platform-browser';
+
+import { UploadComponent } from './upload.component';
+import { InvalidFile } from '../../types/upload.types';
+
+const mockUploadFiles = [
+  {
+    url: 'http://localhost/myfile.jpg',
+    name: 'myfile',
+  },
+];
+
+const mockFile1 = new File(['file1'], 'filename1.txt', {
+  type: 'text/plain',
+  lastModified: new Date().getTime(),
+});
+const mockFile2 = new File(['file2'], 'filename2.txt', {
+  type: 'text/plain',
+  lastModified: new Date().getTime(),
+});
+const mockFileList = [mockFile1, mockFile2];
+
+const mockInvalidFiles: InvalidFile[] = [
+  {
+    reasons: ['INVALID_FILE_TYPE'],
+    file: mockFile1,
+  },
+];
+
+@Component({
+  selector: 'aui-upload-zone',
+  template: '<div>aui-upload-zone</div>',
+})
+export class UploadZoneComponent {
+  @Input() uploader;
+  @Input() accept;
+  @Input() capture;
+  @Input() ariaId;
+  @Input() disabled = false;
+  @Input() multiple;
+  @Input() label;
+  @Input() description;
+}
+
+@Component({
+  selector: 'aui-upload-queue',
+  template: '<div>aui-upload-queue</div>',
+})
+export class UploadQueueComponent {
+  @Input() uploader;
+  @Input() files;
+  @Input() ariaLabelRemove;
+}
+
+@Component({
+  selector: 'aui-validation-list',
+  template: '<div>aui-validation-list</div>',
+})
+export class ValidationListComponent {
+  @Input() invalidFiles;
+  @Input() ariaLabelRemove;
+}
+
+describe('The Upload Component', () => {
+  let comp: UploadComponent;
+  let fixture: ComponentFixture<UploadComponent>;
+  let de: DebugElement;
+  let el: HTMLElement;
+
+  // waitForAsync beforeEach
+  beforeEach(waitForAsync(() => {
+    TestBed.configureTestingModule({
+      declarations: [
+        UploadComponent,
+        UploadZoneComponent,
+        UploadQueueComponent,
+        ValidationListComponent,
+      ],
+    }).compileComponents(); // compile template and css
+  }));
+
+  // synchronous beforeEach
+  beforeEach(() => {
+    fixture = TestBed.createComponent(UploadComponent);
+
+    comp = fixture.componentInstance; // BannerComponent test instance
+
+    // query for the title <h1> by CSS element selector
+    de = fixture.debugElement.query(By.css('.m-upload'));
+    el = de.nativeElement;
+  });
+
+  it('should exist', () => {
+    fixture.detectChanges();
+    expect(el).not.toBeUndefined();
+  });
+
+  it('should emit uploaded files', () => {
+    spyOn(comp.selectUploadedFiles, 'emit');
+    comp.onUploadedFiles(mockUploadFiles);
+    expect(comp.selectUploadedFiles.emit).toHaveBeenCalledWith(mockUploadFiles);
+  });
+
+  it('should concat queued files', () => {
+    comp.queuedFiles = [mockFile1];
+    comp.onQueuedFiles(mockFileList);
+    const result = [mockFile1].concat(mockFileList);
+    expect(comp.queuedFiles).toEqual(result);
+  });
+
+  it('should set invalid files', () => {
+    comp.onInvalidFiles(mockInvalidFiles);
+    expect(comp.invalidFiles).toEqual(mockInvalidFiles);
+  });
+});