refactor(Thumbnail): queue for expensive file operations

BREAKING CHANGE: removed throttle and isShownOnLoad props as they are no longer required due to ability to cancel position in global queue

Co-authored-by: Liam Ross <[email protected]>

Author: lbittner-pdftron

src/components/FileOrganizer/FileOrganizer.stories.tsx

@@ -20,11 +20,10 @@ export default {
 interface TemplateProps {
   onRenderDragLayer?: boolean;
   numFiles?: number;
-  lazy?: boolean;
   editable?: boolean;
 }
 
-const Template: FC<TemplateProps> = ({ onRenderDragLayer, numFiles = 2, lazy, editable }) => {
+const Template: FC<TemplateProps> = ({ onRenderDragLayer, numFiles = 2, editable }) => {
   // This is the index organizing function.
   const [files, setFiles] = useState<FakeFile[]>([]);
   const handleOnMove = useCallback<NonNullable<FileOrganizerProps<FakeFile>['onMove']>>((fromIndex, toIndex) => {
@@ -47,13 +46,13 @@ const Template: FC<TemplateProps> = ({ onRenderDragLayer, numFiles = 2, lazy, ed
       if (prev.length < numFiles) {
         const newFiles = [];
         for (let index = prev.length; index < numFiles; index++) {
-          newFiles.push(createFile(index, { lazy }));
+          newFiles.push(createFile(index));
         }
         return [...prev, ...newFiles];
       }
       return prev;
     });
-  }, [numFiles, lazy]);
+  }, [numFiles]);
 
   return (
     <FileOrganizer
@@ -100,11 +99,10 @@ export const WithCustomDragLayer = () => {
   const numFiles = number('number of files', 2, { min: 0, max: 16, step: 1, range: true });
   return <Template numFiles={numFiles} onRenderDragLayer />;
 };
-export const StressTestWithLazyThumbnails = () => <Template lazy numFiles={1000} />;
 
 export const UseManagedFilesHook = () => {
   const { fileOrganizerProps, getThumbnailSelectionProps, draggingIds } = useManagedFiles({
-    initialFiles: Array.from({ length: 100 }, (_, index) => createFile(index)),
+    initialFiles: Array.from({ length: 1000 }, (_, index) => createFile(index)),
     preventMultiDrag: boolean('preventMultiDrag', false, 'useManagedFiles options'),
     preventMultiSelect: boolean('preventMultiSelect', false, 'useManagedFiles options'),
     preventDeselectOnDragOther: boolean('preventDeselectOnDragOther', false, 'useManagedFiles options'),

src/components/FileOrganizer/FileOrganizer.tsx

@@ -113,8 +113,6 @@ export interface OnRenderThumbnailProps<F> {
     otherDragging: boolean;
     /** Callback for setting whether the thumbnail is in editing mode. */
     onEditingChange: (isEditing: boolean) => void;
-    /** Is this thumbnail shown on initial load. Use to turn off throttling. */
-    isShownOnLoad: boolean;
   };
   /** ID of the file. */
   id: string;
@@ -172,24 +170,6 @@ export function FileOrganizer<F extends ObjectWithId>({
     [onDragChange],
   );
 
-  // Whenever files changes, detect which items are in view and prevent
-  // throttling. Set as array of IDs to notify onRenderThumbnail.
-  const [initialShownIds, setInitialShownIds] = useState<string[]>([]);
-  useEffect(() => {
-    if (files) {
-      requestAnimationFrame(() => {
-        if (!fileOrganizerRef.current) return;
-        const itemsInView = fileOrganizerRef.current.querySelectorAll('div[draggable="true"]');
-        const ids: string[] = [];
-        itemsInView.forEach((draggableItem) => {
-          const dataFileId = draggableItem.getAttribute('data-file-id');
-          if (dataFileId) ids.push(dataFileId);
-        });
-        setInitialShownIds(ids);
-      });
-    }
-  }, [files]);
-
   const handleItemKeyDown = useCallback(
     (event: KeyboardEvent<HTMLDivElement>, index: number, _file: F, draggableRef: RefObject<HTMLDivElement>) => {
       let indexDiff = 0;
@@ -292,7 +272,6 @@ export function FileOrganizer<F extends ObjectWithId>({
                 dragging: isDragging || isInDragGroup,
                 otherDragging,
                 onEditingChange: (editing) => setEditingId(editing ? file.id : undefined),
-                isShownOnLoad: !initialShownIds || initialShownIds.includes(file.id),
               },
               id: file.id,
               index,
@@ -312,7 +291,6 @@ export function FileOrganizer<F extends ObjectWithId>({
       handleOnDragChange,
       handleItemKeyDown,
       onRenderThumbnail,
-      initialShownIds,
     ],
   );
 

src/components/Thumbnail/Thumbnail.stories.tsx

@@ -26,20 +26,18 @@ const defaultProps = (options?: CreateFileOptions, index = 0, withToolButtons?:
 
 export const Basic = () => <Thumbnail {...defaultProps()} />;
 
-export const Throttled = () => <Thumbnail {...defaultProps({ lazy: true })} />;
-
-export const Pending = () => <Thumbnail {...defaultProps({ pending: true })} />;
+export const Expensive = () => <Thumbnail {...defaultProps({ lazy: true })} />;
 
 export const Rejected = () => <Thumbnail {...defaultProps({ error: true })} />;
 
 export const WithToolButtons = () => <Thumbnail {...defaultProps(undefined, undefined, true)} />;
 
 export const WithLabel = () => <Thumbnail label={text('label', 'some_label')} {...defaultProps()} />;
 
-export const WithSelectedIcon = () => (
+export const SelectedIcon = () => (
   <Thumbnail
     {...defaultProps()}
-    selectedIcon={<div style={{ color: 'red', fontSize: 20 }}>{text('selectedIcon', 'Selected Icon')}</div>}
+    selectedIcon={<div style={{ color: 'red', fontSize: 20 }}>{text('selectedIcon', 'CUSTOM!')}</div>}
   />
 );
 

src/components/Thumbnail/Thumbnail.test.tsx

@@ -4,7 +4,7 @@ import { spy } from 'sinon';
 import { createFile } from '../../storybook-helpers/data/files';
 import { Thumbnail } from '../Thumbnail';
 
-const testFile = createFile(0, { pending: true });
+const testFile = createFile(0);
 
 describe('Thumbnail component', () => {
   it('renders its contents', () => {

src/components/Thumbnail/Thumbnail.tsx

@@ -47,15 +47,6 @@ export interface ThumbnailProps<F> extends ClickableDivProps {
    * A node to render on the top-left of the thumbnail.
    */
   selectedIcon?: ReactNode;
-  /**
-   * Default 500ms. Set to 0 to prevent all throttling. Set the delay for
-   * fetching any lazy async items from file.
-   */
-  throttle?: number;
-  /**
-   * If true, will prevent throttling.
-   */
-  isShownOnLoad?: boolean;
   /**
    * Class for the thumbnail image.
    */
@@ -84,8 +75,6 @@ export function Thumbnail<F extends FileLike>({
   selectedIcon,
   onRename,
   onEditingChange,
-  throttle,
-  isShownOnLoad,
   imageClassName,
   className,
   disabled,
@@ -99,8 +88,7 @@ export function Thumbnail<F extends FileLike>({
 
   const { focused, handleOnFocus, handleOnBlur } = useFocus(onFocus, onBlur);
 
-  const toThrottle = isShownOnLoad ? 0 : throttle;
-  const [thumbnail, thumbnailErr] = useFileSubscribe(file, (f) => f.thumbnail, 'onthumbnailchange', toThrottle);
+  const [thumbnail, thumbnailErr] = useFileSubscribe(file, (f) => f.thumbnail, 'onthumbnailchange');
   const [name] = useFileSubscribe(file, (f) => f.name, 'onnamechange');
 
   const handleOnSave = (newName: string) => {

src/data/file.ts

@@ -49,6 +49,16 @@ export interface FileDetails {
    * license will take priority over the global license.
    */
   license?: string;
+  /**
+   * A reference to the document that was used to create this File class. Used as an optimization
+   * where applicable. If passed, 'pageIndex' must also be passed
+   */
+  fullDocumentObj?: CoreControls.Document;
+  /**
+   * Used in conjunction with 'fullDocumentObj'. Represents the pageIndex of 'fullDocumentObj' that this
+   * file belongs too
+   */
+  pageIndex?: number;
 }
 
 export interface FileLike {
@@ -60,6 +70,8 @@ export interface FileLike {
   fileObj: MemoizedPromise<Blob>;
   documentObj: MemoizedPromise<CoreControls.Document>;
   subscribe: (...args: any) => () => void;
+  fullDocumentObj?: CoreControls.Document;
+  pageIndex?: number;
 }
 
 export type FileEventType =
@@ -96,19 +108,40 @@ export class File implements FileLike {
   private _freezeThumbnail: boolean;
   private _subscribers: FileEventListenersObj;
   private _license?: string;
+  private _fullDocumentObj?: CoreControls.Document;
+  private _pageIndex?: number;
 
   /**
    * Initialize the `File`.
    * @param fileDetails The file details object or file-like class to initialize
    * this `File` with.
    */
   constructor(fileDetails: FileDetails) {
-    const { name, id, originalName, extension, fileObj, documentObj, thumbnail, license } = fileDetails;
+    const {
+      name,
+      id,
+      originalName,
+      extension,
+      fileObj,
+      documentObj,
+      thumbnail,
+      license,
+      fullDocumentObj,
+      pageIndex,
+    } = fileDetails;
 
     if (!fileObj && !documentObj) {
       throw new Error('One of `fileObj` or `documentObj` is required to initialize File.');
     }
 
+    if (fullDocumentObj) {
+      if (typeof pageIndex !== 'number') {
+        throw new Error('"pageIndex" must be passed if using "fullDocumentObj"');
+      }
+      this._fullDocumentObj = fullDocumentObj;
+      this._pageIndex = pageIndex;
+    }
+
     this._id = id || getStringId('file');
     this._name = name;
     this._originalName = originalName || name;
@@ -164,6 +197,16 @@ export class File implements FileLike {
     return this._documentObj;
   }
 
+  /** Gets the full document object if provided during initialization. */
+  get fullDocumentObj() {
+    return this._fullDocumentObj;
+  }
+
+  /** Gets the page index if provided during initialization. */
+  get pageIndex() {
+    return this._pageIndex;
+  }
+
   /** The name of the file. */
   get name() {
     return this._name;
@@ -299,7 +342,10 @@ export class File implements FileLike {
 
   /** Generate a thumbnail from document object. */
   private _generateThumbnail = () => {
-    return getThumbnail(this.documentObj.get(), this.extension);
+    return getThumbnail(this.fullDocumentObj || this.documentObj.get(), {
+      extension: this.extension,
+      pageIndex: this.pageIndex,
+    });
   };
 
   /** Generate a file object from document object. */

src/hooks/useFile.ts

@@ -32,13 +32,12 @@ interface FileHook<F> {
  * This hook converts a file class with async values into a React-friendly hook
  * with async values set to undefined until they are fetched.
  * @param file The file to convert to react observable values.
- * @param throttle The timeout if unfetched memo promise.
  */
-export function useFile<F extends FileLike>(file: F, throttle?: number): FileHook<F> {
-  const [name, nameErr] = useFileSubscribe(file, (f) => f.name, 'onnamechange', throttle);
-  const [thumbnail, thumbnailErr] = useFileSubscribe(file, (f) => f.thumbnail, 'onthumbnailchange', throttle);
-  const [fileObj, fileObjErr] = useFileSubscribe(file, (f) => f.fileObj, 'onfileobjchange', throttle);
-  const [documentObj, documentObjErr] = useFileSubscribe(file, (f) => f.documentObj, 'ondocumentobjchange', throttle);
+export function useFile<F extends FileLike>(file: F): FileHook<F> {
+  const [name, nameErr] = useFileSubscribe(file, (f) => f.name, 'onnamechange');
+  const [thumbnail, thumbnailErr] = useFileSubscribe(file, (f) => f.thumbnail, 'onthumbnailchange');
+  const [fileObj, fileObjErr] = useFileSubscribe(file, (f) => f.fileObj, 'onfileobjchange');
+  const [documentObj, documentObjErr] = useFileSubscribe(file, (f) => f.documentObj, 'ondocumentobjchange');
 
   const fileValue = useMemo<FileHook<F>>(
     () => ({

src/hooks/useFileSubscribe.ts

@@ -1,6 +1,6 @@
 import { useEffect, useMemo, useRef, useState } from 'react';
 import { FileEventType, FileLike, MemoizedPromise } from '../data';
-import { DEFAULT_THROTTLE_TIMEOUT } from '../utils';
+import GlobalQueue from '../work/GlobalQueue';
 
 /**
  * Will subscribe to a value from a file and return the value, as well as any
@@ -14,7 +14,6 @@ export function useFileSubscribe<F extends FileLike, T>(
   file: F,
   getCurrentValue: (file: F) => T | MemoizedPromise<T>,
   eventType?: FileEventType,
-  throttle?: number,
 ) {
   const getValue = useRef(getCurrentValue);
 
@@ -27,18 +26,17 @@ export function useFileSubscribe<F extends FileLike, T>(
 
   useEffect(() => {
     let cancelled = false;
-    let timeout: number;
+    let cancel: () => void;
 
-    const setMemoValue = async (newValue: MemoizedPromise<T>) => {
+    const setMemoValue = (val: T) => {
       try {
-        const val = await newValue.get();
         if (!cancelled) setValue(val);
       } catch (error) {
         if (!cancelled) setError(error);
       }
     };
 
-    const subscribe = (delay?: boolean) => {
+    const subscribe = () => {
       setError(undefined);
 
       const val = getValue.current(file);
@@ -49,27 +47,34 @@ export function useFileSubscribe<F extends FileLike, T>(
       }
 
       setValue(undefined);
-      if (!delay || val.done || throttle === 0) {
-        setMemoValue(val);
+
+      if (val.done) {
+        val.get().then(setMemoValue);
       } else {
-        timeout = window.setTimeout(() => {
-          setMemoValue(val);
-        }, throttle ?? DEFAULT_THROTTLE_TIMEOUT);
+        const r = GlobalQueue.process<T>(() => val.get());
+        cancel = r[1];
+        r[0]
+          .then((result: T) => {
+            setMemoValue(result);
+          })
+          .catch((e) => {
+            setError(e);
+          });
       }
     };
 
-    subscribe(true);
+    subscribe();
 
     let unsubscribe: (() => void) | undefined;
 
     if (eventType) unsubscribe = file.subscribe(eventType, subscribe);
 
     return () => {
+      cancel?.();
       unsubscribe?.();
       cancelled = true;
-      clearTimeout(timeout);
     };
-  }, [eventType, file, throttle]);
+  }, [eventType, file]);
 
   return useMemo(() => [value, error, setValue], [error, value]);
 }

src/storybook-helpers/data/files.ts

@@ -5,8 +5,7 @@ import testPdfThumbnailRotated from '../images/pdf-preview-2.png';
 import testPdfThumbnail from '../images/pdf-preview.png';
 
 export interface CreateFileOptions {
-  pending?: boolean;
-  lazy?: boolean;
+  lazy?: boolean; // Expensive operation
   error?: boolean;
 }
 
@@ -22,6 +21,8 @@ export class FakeFile implements FileLike {
   thumbnail: MemoizedPromise<string>;
   fileObj: MemoizedPromise<Blob>;
   documentObj: MemoizedPromise<CoreControls.Document>;
+  fullDocumentObj: CoreControls.Document | undefined;
+  pageIndex: number | undefined;
 
   constructor(index: number, options: CreateFileOptions = {}) {
     this.id = `file_${index + 1}`;
@@ -35,9 +36,8 @@ export class FakeFile implements FileLike {
 
   private _getParameter<T>(parameter: T, options: CreateFileOptions) {
     const internals = (() => {
-      if (options.pending) return async () => new Promise(() => {});
-      if (options.lazy) return async () => Promise.resolve(parameter);
-      if (options.error) return () => Promise.reject('Some error.');
+      if (options.lazy) return () => new Promise((res) => setTimeout(() => res(parameter), 500));
+      if (options.error) return () => new Promise((_res, rej) => setTimeout(() => rej('Some error.'), 500));
       return parameter;
     })();
     return new MemoizedPromise(internals as FuturableOrLazy<T>);

src/utils/debugUtils.ts

@@ -0,0 +1,8 @@
+export function logExecTime(tag: string): () => number {
+  const now = performance.now();
+  return () => {
+    const now2 = performance.now();
+    console.log(`${tag} took ${now2 - now}ms`);
+    return now2 - now;
+  };
+}