WEB-442-feat: implement LightGallery document preview across all document tabs (#2847)

* feat: implement LightGallery document preview across all document tabs feat(documents): add LightGallery preview with accessibility and error handling * fix: add accessibility and performance improvements for document preview fix(styles): replace undefined variable with -river Delete button title translated
2025-12-03 05:18:02 -06:00
parent 83f3a0b0fe
commit 9432ad3b96
32 changed files with 1031 additions and 323 deletions
@@ -1,5 +1,5 @@
 <div class="tab-container mat-typography">
-  <div class="layout-row align-start-center">
+  <div class="layout-row align-start-center header-row">
    <h3 class="flex-90">{{ 'labels.heading.Documents' | translate }}</h3>

    <div class="flex-10" *mifosxHasPermission="'CREATE_DOCUMENT'">
@@ -9,51 +9,59 @@
    </div>
  </div>

-  <table mat-table #documentsTable [dataSource]="dataSource" matSort>
-    <ng-container matColumnDef="name">
-      <th mat-header-cell *matHeaderCellDef mat-sort-header>{{ 'labels.inputs.name' | translate }}</th>
-      <td mat-cell *matCellDef="let document">{{ document.name }}</td>
-    </ng-container>
-
-    <ng-container matColumnDef="description">
-      <th mat-header-cell *matHeaderCellDef mat-sort-header>{{ 'labels.inputs.Description' | translate }}</th>
-      <td mat-cell *matCellDef="let document">{{ document.description }}</td>
-    </ng-container>
-
-    <ng-container matColumnDef="filename">
-      <th mat-header-cell *matHeaderCellDef mat-sort-header>{{ 'labels.inputs.File Name' | translate }}</th>
-      <td mat-cell *matCellDef="let document">{{ document.fileName }}</td>
-    </ng-container>
-
-    <ng-container matColumnDef="actions">
-      <th mat-header-cell *matHeaderCellDef mat-sort-header>{{ 'labels.inputs.Actions' | translate }}</th>
-      <td mat-cell *matCellDef="let document; let index">
-        <button
-          class="document-action-button"
-          mat-raised-button
-          color="primary"
-          (click)="downloadDocument(document.id)"
+  <div *ngIf="entityDocuments?.length; else empty">
+    <div class="document-grid">
+      <div class="document-card" *ngFor="let document of entityDocuments; trackBy: trackByDocumentId">
+        <div
+          class="thumb"
+          [class.clickable]="isPreviewable(document)"
+          role="button"
+          tabindex="0"
+          [attr.aria-label]="('labels.buttons.Preview' | translate) + ': ' + document.name"
+          (keydown.enter)="isPreviewable(document) && openPreview(document)"
+          (keydown.space)="isPreviewable(document) && openPreview(document)"
+          (click)="isPreviewable(document) && openPreview(document)"
        >
-          <fa-icon icon="cloud-download-alt"></fa-icon>
-        </button>
-        <button
-          class="document-action-button"
-          mat-raised-button
-          color="warn"
-          (click)="deleteDocument(document.id, document.name)"
-        >
-          <fa-icon icon="times"></fa-icon>
-        </button>
-      </td>
-    </ng-container>
+          <ng-container *ngIf="previewThumbnails[document.id]; else placeholder">
+            <img [src]="previewThumbnails[document.id]" [alt]="document.name" [title]="document.name" loading="lazy" />
+          </ng-container>
+          <ng-template #placeholder>
+            <div class="placeholder">
+              <fa-icon icon="file"></fa-icon>
+              <span>{{ document.fileName || document.name }}</span>
+            </div>
+          </ng-template>
+          <div class="preview-overlay" *ngIf="isPreviewable(document)">
+            <fa-icon icon="eye"></fa-icon>
+          </div>
+        </div>
+        <div class="card-body">
+          <div class="title">{{ document.name }}</div>
+          <div class="meta" *ngIf="document.fileName">{{ document.fileName }}</div>
+          <div class="description" *ngIf="document.description">{{ document.description }}</div>
+          <div class="actions">
+            <button
+              mat-icon-button
+              color="warn"
+              (click)="deleteDocument(document.id, document.name)"
+              title="Delete"
+              [attr.aria-label]="'labels.buttons.Delete' | translate"
+              *mifosxHasPermission="'DELETE_DOCUMENT'"
+            >
+              <fa-icon icon="times"></fa-icon>
+            </button>
+          </div>
+        </div>
+      </div>
+    </div>
+  </div>

-    <tr mat-header-row *matHeaderRowDef="displayedColumns"></tr>
-    <tr mat-row *matRowDef="let row; columns: displayedColumns"></tr>
-  </table>
-
-  <mat-paginator
-    *ngIf="entityDocuments && entityDocuments.length > 10"
-    [pageSizeOptions]="[10, 25, 50]"
-    showFirstLastButtons
-  ></mat-paginator>
+  <ng-template #empty>
+    <div class="empty-state">
+      <p>{{ 'labels.text.NoDocuments' | translate }}</p>
+      <p class="muted">{{ 'labels.text.UploadDocumentHint' | translate }}</p>
+    </div>
+  </ng-template>
 </div>
+
+<div #lightboxRoot class="document-lightbox-host"></div>
@@ -1,16 +1,159 @@
-table {
-  width: 100%;
-  margin-top: 3%;
+@use '../../../../assets/styles/colours' as *;

-  .document-action-button {
-    min-width: 26px;
-    padding: 0 6px;
-    margin: 4px;
-    line-height: 25px;
+.tab-container {
+  padding: 1rem;
+  margin: 1rem 0;
+}
+
+.header-row {
+  display: flex;
+  align-items: center;
+}
+
+.document-grid {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 1rem;
+  margin-top: 0.75rem;
+}
+
+.document-card {
+  width: 240px;
+  background: $white;
+  border: 1px solid $silver;
+  border-radius: 4px;
+  overflow: hidden;
+  box-shadow: 0 1px 4px rgba($dark-grey, 0.12);
+  display: flex;
+  flex-direction: column;
+  transition:
+    transform 0.2s ease,
+    box-shadow 0.2s ease;
+
+  &:hover {
+    transform: translateY(-1px);
+    box-shadow: 0 4px 12px rgba($dark-grey, 0.14);
  }
 }

-.tab-container {
-  padding: 1%;
-  margin: 1%;
+.thumb {
+  position: relative;
+  background: $clouds;
+  min-height: 9.5rem;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  cursor: default;
+
+  &.clickable {
+    cursor: pointer;
+  }
+
+  img {
+    width: 100%;
+    height: 100%;
+    object-fit: cover;
+  }
+}
+
+.preview-overlay {
+  position: absolute;
+  bottom: 0.5rem;
+  right: 0.5rem;
+  background: rgba($white, 0.9);
+  border-radius: 50%;
+  padding: 0.4rem;
+  color: $peter-river;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  opacity: 0;
+  transition: opacity 0.2s ease;
+
+  .thumb:hover &,
+  .thumb:focus & {
+    opacity: 1;
+  }
+}
+
+.placeholder {
+  color: $light-grey;
+  text-align: center;
+  padding: 0.875rem;
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+  align-items: center;
+  justify-content: center;
+
+  fa-icon {
+    font-size: 22px;
+  }
+
+  span {
+    font-size: 12px;
+    line-height: 1.2;
+  }
+}
+
+.preview-btn {
+  position: absolute;
+  right: 0.5rem;
+  bottom: 0.5rem;
+  background: rgba($black, 0.65);
+  color: $white;
+}
+
+.card-body {
+  padding: 0.75rem 0.875rem 0.875rem;
+  display: flex;
+  flex-direction: column;
+  gap: 0.375rem;
+}
+
+.title {
+  font-weight: 700;
+  color: $dark-grey;
+}
+
+.meta {
+  font-size: 12px;
+  color: $asbestos;
+}
+
+.description {
+  font-size: 13px;
+  color: $dark-grey;
+  min-height: 32px;
+}
+
+.actions {
+  display: flex;
+  justify-content: flex-end;
+  gap: 0.375rem;
+  margin-top: 0.25rem;
+}
+
+.empty-state {
+  margin-top: 0.75rem;
+  padding: 1.25rem;
+  text-align: center;
+  background: $light-grey;
+  border: 1px dashed $silver;
+  border-radius: 4px;
+  color: $dark-grey;
+  display: flex;
+  flex-direction: column;
+  gap: 0.5rem;
+  align-items: center;
+
+  .muted {
+    color: $concrete;
+    margin: 0.25rem 0 0;
+    font-size: 0.8125rem;
+  }
+}
+
+.document-lightbox-host {
+  display: none;
 }
@@ -1,25 +1,17 @@
-import { Component, Input, OnInit, ViewChild } from '@angular/core';
+import { Component, ElementRef, Input, OnDestroy, OnInit, ViewChild } from '@angular/core';
 import { MatDialog } from '@angular/material/dialog';
-import { MatPaginator } from '@angular/material/paginator';
-import { MatSort, MatSortHeader } from '@angular/material/sort';
-import {
-  MatTable,
-  MatTableDataSource,
-  MatColumnDef,
-  MatHeaderCellDef,
-  MatHeaderCell,
-  MatCellDef,
-  MatCell,
-  MatHeaderRowDef,
-  MatHeaderRow,
-  MatRowDef,
-  MatRow
-} from '@angular/material/table';
+import lightGallery from 'lightgallery';
+import lgFullscreen from 'lightgallery/plugins/fullscreen';
+import lgThumbnail from 'lightgallery/plugins/thumbnail';
+import lgZoom from 'lightgallery/plugins/zoom';
+import type { LightGallery } from 'lightgallery/lightgallery';
+import type { GalleryItem } from 'lightgallery/lg-utils';
 import { UploadDocumentDialogComponent } from 'app/clients/clients-view/custom-dialogs/upload-document-dialog/upload-document-dialog.component';
 import { ClientsService } from 'app/clients/clients.service';
 import { LoansService } from 'app/loans/loans.service';
 import { SavingsService } from 'app/savings/savings.service';
 import { DeleteDialogComponent } from 'app/shared/delete-dialog/delete-dialog.component';
+import { DocumentPreviewService } from 'app/shared/services/document-preview.service';
 import { Observable } from 'rxjs';
 import { FaIconComponent } from '@fortawesome/angular-fontawesome';
 import { STANDALONE_SHARED_IMPORTS } from 'app/standalone-shared.module';
@@ -28,80 +20,55 @@ import { STANDALONE_SHARED_IMPORTS } from 'app/standalone-shared.module';
  selector: 'mifosx-entity-documents-tab',
  templateUrl: './entity-documents-tab.component.html',
  styleUrls: ['./entity-documents-tab.component.scss'],
+  standalone: true,
  imports: [
    ...STANDALONE_SHARED_IMPORTS,
-    FaIconComponent,
-    MatTable,
-    MatSort,
-    MatColumnDef,
-    MatHeaderCellDef,
-    MatHeaderCell,
-    MatSortHeader,
-    MatCellDef,
-    MatCell,
-    MatHeaderRowDef,
-    MatHeaderRow,
-    MatRowDef,
-    MatRow,
-    MatPaginator
+    FaIconComponent
  ]
 })
-export class EntityDocumentsTabComponent implements OnInit {
-  @ViewChild('documentsTable', { static: true }) documentsTable: MatTable<Element>;
+export class EntityDocumentsTabComponent implements OnInit, OnDestroy {
+  @ViewChild('lightboxRoot', { static: true }) lightboxRoot: ElementRef<HTMLElement>;

  @Input() entityId: string;
  @Input() entityType: string;
  @Input() entityDocuments: any;

  @Input() callbackUpload: (documentData: FormData) => Observable<any>;
-  @Input() callbackDownload: (documentId: string) => void;
  @Input() callbackDelete: (documentId: string) => void;

-  /** Status of the loan account */
-  status: any;
-  /** Choice */
-  choice: boolean;
-
-  /** Columns to be displayed in loan documents table. */
-  displayedColumns: string[] = [
-    'name',
-    'description',
-    'filename',
-    'actions'
+  previewThumbnails: Record<string, string> = {};
+  private lightboxInstance: LightGallery | null = null;
+  private readonly lightboxPlugins = [
+    lgZoom,
+    lgThumbnail,
+    lgFullscreen
  ];
-  /** Data source for loan documents table. */
-  dataSource: MatTableDataSource<any>;

-  /** Paginator for codes table. */
-  @ViewChild(MatPaginator) paginator: MatPaginator;
-  /** Sorter for codes table. */
-  @ViewChild(MatSort) sort: MatSort;
-
-  /**
-   *
-   * @param {MatDialog} dialog Dialog for Inputs.
-   * @param {SavingsService} savingsService Savings Account services.
-   * @param {LoansService} loansService Loan Account services.
-   * @param {ClientsService} clientsService Client services.
-   */
  constructor(
    public dialog: MatDialog,
    private savingsService: SavingsService,
    private loansService: LoansService,
-    private clientsService: ClientsService
+    private clientsService: ClientsService,
+    private documentPreviewService: DocumentPreviewService
  ) {}

-  ngOnInit() {
-    this.dataSource = new MatTableDataSource(this.entityDocuments);
-    this.dataSource.paginator = this.paginator;
-    this.dataSource.sort = this.sort;
+  ngOnInit(): void {
+    this.prefetchThumbnails();
  }

-  downloadDocument(documentId: string) {
-    this.callbackDownload(documentId);
+  ngOnDestroy(): void {
+    this.destroyLightbox();
+    if (Array.isArray(this.entityDocuments)) {
+      this.entityDocuments.forEach((doc: any) => this.documentPreviewService.release(doc.id));
+    }
  }

-  uploadDocument() {
+  /** TrackBy function for documents ngFor */
+  trackByDocumentId(_: number, doc: any): any {
+    return doc?.id;
+  }
+
+  uploadDocument(): void {
    const uploadDocumentDialogRef = this.dialog.open(UploadDocumentDialogComponent, {
      data: { documentIdentifier: false, entityType: '' },
      width: '33rem'
@@ -113,34 +80,143 @@ export class EntityDocumentsTabComponent implements OnInit {
        formData.append('file', dialogResponse.file);
        formData.append('description', dialogResponse.description);
        this.callbackUpload(formData).subscribe((res: any) => {
-          this.entityDocuments.push({
+          const newDocument = {
            id: res.resourceId,
            parentEntityType: this.entityType,
            parentEntityId: this.entityId,
            name: dialogResponse.fileName,
            description: dialogResponse.description,
            fileName: dialogResponse.file.name
-          });
-          this.documentsTable.renderRows();
+          };
+          this.entityDocuments.push(newDocument);
+          this.setThumbnail(newDocument);
        });
      }
    });
  }

-  deleteDocument(documentId: string, name: number) {
+  deleteDocument(documentId: string, name: string): void {
    const deleteDocumentDialogRef = this.dialog.open(DeleteDialogComponent, {
      data: { deleteContext: `Document: ${name}` }
    });
    deleteDocumentDialogRef.afterClosed().subscribe((response: any) => {
      if (response.delete) {
        this.callbackDelete(documentId);
-        for (let i = 0; i < this.entityDocuments.length; i++) {
-          if (this.entityDocuments[i].id === documentId) {
-            this.entityDocuments.splice(i, 1);
-          }
+        const index = this.entityDocuments.findIndex((doc: any) => doc.id === documentId);
+        if (index !== -1) {
+          this.entityDocuments.splice(index, 1);
        }
-        this.documentsTable.renderRows();
+        this.documentPreviewService.release(documentId);
+        delete this.previewThumbnails[documentId];
      }
    });
  }
+
+  isPreviewable(document: any): boolean {
+    return this.documentPreviewService.isPreviewable(document);
+  }
+
+  async openPreview(document: any): Promise<void> {
+    if (!this.isPreviewable(document)) {
+      return;
+    }
+    try {
+      const previewables = this.entityDocuments.filter((doc: any) => this.isPreviewable(doc));
+      const galleryItems: GalleryItem[] = [];
+
+      for (const item of previewables) {
+        try {
+          const preview = await this.documentPreviewService.resolvePreviewUrl(item, (descriptor) =>
+            this.getDownloadObservable(descriptor.id)
+          );
+          if (preview.type === 'image') {
+            this.previewThumbnails[item.id] = preview.url;
+          }
+          galleryItems.push({
+            src: preview.url,
+            thumb: preview.type === 'image' ? preview.url : undefined,
+            subHtml: this.buildSubHtml(item),
+            iframe: preview.type === 'pdf'
+          });
+        } catch (error) {
+          console.error('Preview failed for document', item.id, error);
+        }
+      }
+
+      if (!galleryItems.length) {
+        return;
+      }
+
+      const startIndex = Math.max(
+        0,
+        previewables.findIndex((item: any) => item.id === document.id)
+      );
+      this.destroyLightbox();
+      this.lightboxInstance = lightGallery(this.lightboxRoot.nativeElement, {
+        dynamic: true,
+        dynamicEl: galleryItems,
+        plugins: this.lightboxPlugins,
+        download: false,
+        closable: true,
+        escKey: true,
+        zoomFromOrigin: true
+      });
+
+      this.lightboxInstance.openGallery(startIndex);
+    } catch (error) {
+      console.error('Unable to open preview', error);
+    }
+  }
+
+  private destroyLightbox(): void {
+    if (this.lightboxInstance) {
+      this.lightboxInstance.destroy();
+      this.lightboxInstance = null;
+    }
+  }
+
+  private getDownloadObservable(documentId: string): Observable<Blob> {
+    if (this.entityType === 'savings') {
+      return this.savingsService.downloadSavingsDocument(this.entityId, documentId);
+    }
+    if (this.entityType === 'loans') {
+      return this.loansService.downloadLoanDocument(this.entityId, documentId);
+    }
+    return this.clientsService.downloadClientDocument(this.entityId, documentId);
+  }
+
+  private buildSubHtml(document: any): string {
+    const description = document.description
+      ? `<p class="lg-caption-text">${this.escapeHtml(document.description)}</p>`
+      : '';
+    const filename = document.fileName ? `<p class="lg-meta">${this.escapeHtml(document.fileName)}</p>` : '';
+    return `<div class="lg-caption"><h4>${this.escapeHtml(document.name || 'Document')}</h4>${description}${filename}</div>`;
+  }
+
+  private escapeHtml(value: string): string {
+    return value
+      ? value.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;')
+      : '';
+  }
+
+  private setThumbnail(document: any): void {
+    if (!this.documentPreviewService.isPreviewable(document)) {
+      return;
+    }
+    this.documentPreviewService
+      .resolvePreviewUrl(document, () => this.getDownloadObservable(document.id))
+      .then((preview) => {
+        if (preview.type === 'image') {
+          this.previewThumbnails[document.id] = preview.url;
+        }
+      })
+      .catch((): void => undefined);
+  }
+
+  private prefetchThumbnails(): void {
+    if (!Array.isArray(this.entityDocuments)) {
+      return;
+    }
+    this.entityDocuments.forEach((doc: any) => this.setThumbnail(doc));
+  }
 }