feat: rewrite library state management & related refactor (#5067)

* support libraryItems promise for `updateScene()` and use `importLibrary`

* fix typing for `getLibraryItemsFromStorage()`

* remove `libraryItemsFromStorage` hack

if there was a point to it then I'm missing it, but this part will be rewritten anyway

* rewrite state handling

(temporarily removed loading states)

* add async support

* refactor and deduplicate library importing logic

* hide hints when library open

* fix snaps

* support promise in `initialData.libraryItems`

* add default to params instead

src/data/blob.ts

@@ -1,20 +1,16 @@
 import { nanoid } from "nanoid";
 import { cleanAppStateForExport } from "../appState";
-import {
-  ALLOWED_IMAGE_MIME_TYPES,
-  EXPORT_DATA_TYPES,
-  MIME_TYPES,
-} from "../constants";
+import { ALLOWED_IMAGE_MIME_TYPES, MIME_TYPES } from "../constants";
 import { clearElementsForExport } from "../element";
 import { ExcalidrawElement, FileId } from "../element/types";
 import { CanvasError } from "../errors";
 import { t } from "../i18n";
 import { calculateScrollCenter } from "../scene";
-import { AppState, DataURL } from "../types";
+import { AppState, DataURL, LibraryItem } from "../types";
 import { bytesToHexString } from "../utils";
 import { FileSystemHandle } from "./filesystem";
-import { isValidExcalidrawData } from "./json";
-import { restore } from "./restore";
+import { isValidExcalidrawData, isValidLibrary } from "./json";
+import { restore, restoreLibraryItems } from "./restore";
 import { ImportedLibraryData } from "./types";
 
 const parseFileContents = async (blob: Blob | File) => {
@@ -163,13 +159,17 @@ export const loadFromBlob = async (
   }
 };
 
-export const loadLibraryFromBlob = async (blob: Blob) => {
+export const loadLibraryFromBlob = async (
+  blob: Blob,
+  defaultStatus: LibraryItem["status"] = "unpublished",
+) => {
   const contents = await parseFileContents(blob);
-  const data: ImportedLibraryData = JSON.parse(contents);
-  if (data.type !== EXPORT_DATA_TYPES.excalidrawLibrary) {
-    throw new Error(t("alerts.couldNotLoadInvalidFile"));
+  const data: ImportedLibraryData | undefined = JSON.parse(contents);
+  if (!isValidLibrary(data)) {
+    throw new Error("Invalid library");
   }
-  return data;
+  const libraryItems = data.libraryItems || data.library;
+  return restoreLibraryItems(libraryItems, defaultStatus);
 };
 
 export const canvasToBlob = async (

src/data/json.ts

@@ -15,6 +15,7 @@ import {
   ExportedDataState,
   ImportedDataState,
   ExportedLibraryData,
+  ImportedLibraryData,
 } from "./types";
 import Library from "./library";
 
@@ -114,7 +115,7 @@ export const isValidExcalidrawData = (data?: {
   );
 };
 
-export const isValidLibrary = (json: any) => {
+export const isValidLibrary = (json: any): json is ImportedLibraryData => {
   return (
     typeof json === "object" &&
     json &&

src/data/library.ts

@@ -2,9 +2,51 @@ import { loadLibraryFromBlob } from "./blob";
 import { LibraryItems, LibraryItem } from "../types";
 import { restoreLibraryItems } from "./restore";
 import type App from "../components/App";
+import { ImportedDataState } from "./types";
+import { atom } from "jotai";
+import { jotaiStore } from "../jotai";
+import { isPromiseLike } from "../utils";
+import { t } from "../i18n";
+
+export const libraryItemsAtom = atom<
+  | { status: "loading"; libraryItems: null; promise: Promise<LibraryItems> }
+  | { status: "loaded"; libraryItems: LibraryItems }
+>({ status: "loaded", libraryItems: [] });
+
+const cloneLibraryItems = (libraryItems: LibraryItems): LibraryItems =>
+  JSON.parse(JSON.stringify(libraryItems));
+
+/**
+ * checks if library item does not exist already in current library
+ */
+const isUniqueItem = (
+  existingLibraryItems: LibraryItems,
+  targetLibraryItem: LibraryItem,
+) => {
+  return !existingLibraryItems.find((libraryItem) => {
+    if (libraryItem.elements.length !== targetLibraryItem.elements.length) {
+      return false;
+    }
+
+    // detect z-index difference by checking the excalidraw elements
+    // are in order
+    return libraryItem.elements.every((libItemExcalidrawItem, idx) => {
+      return (
+        libItemExcalidrawItem.id === targetLibraryItem.elements[idx].id &&
+        libItemExcalidrawItem.versionNonce ===
+          targetLibraryItem.elements[idx].versionNonce
+      );
+    });
+  });
+};
 
 class Library {
-  private libraryCache: LibraryItems | null = null;
+  /** cache for currently active promise when initializing/updating libaries
+   asynchronously */
+  private libraryItemsPromise: Promise<LibraryItems> | null = null;
+  /** last resolved libraryItems */
+  private lastLibraryItems: LibraryItems = [];
+
   private app: App;
 
   constructor(app: App) {
@@ -12,93 +54,92 @@ class Library {
   }
 
   resetLibrary = async () => {
-    await this.app.props.onLibraryChange?.([]);
-    this.libraryCache = [];
+    this.saveLibrary([]);
   };
 
   /** imports library (currently merges, removing duplicates) */
   async importLibrary(
-    blob: Blob,
+    library:
+      | Blob
+      | Required<ImportedDataState>["libraryItems"]
+      | Promise<Required<ImportedDataState>["libraryItems"]>,
     defaultStatus: LibraryItem["status"] = "unpublished",
   ) {
-    const libraryFile = await loadLibraryFromBlob(blob);
-    if (!libraryFile || !(libraryFile.libraryItems || libraryFile.library)) {
-      return;
-    }
+    return this.saveLibrary(
+      new Promise<LibraryItems>(async (resolve, reject) => {
+        try {
+          let libraryItems: LibraryItems;
+          if (library instanceof Blob) {
+            libraryItems = await loadLibraryFromBlob(library, defaultStatus);
+          } else {
+            libraryItems = restoreLibraryItems(await library, defaultStatus);
+          }
 
-    /**
-     * checks if library item does not exist already in current library
-     */
-    const isUniqueitem = (
-      existingLibraryItems: LibraryItems,
-      targetLibraryItem: LibraryItem,
-    ) => {
-      return !existingLibraryItems.find((libraryItem) => {
-        if (libraryItem.elements.length !== targetLibraryItem.elements.length) {
-          return false;
+          const existingLibraryItems = this.lastLibraryItems;
+
+          const filteredItems = [];
+          for (const item of libraryItems) {
+            if (isUniqueItem(existingLibraryItems, item)) {
+              filteredItems.push(item);
+            }
+          }
+
+          resolve([...filteredItems, ...existingLibraryItems]);
+        } catch (error) {
+          reject(new Error(t("errors.importLibraryError")));
         }
-
-        // detect z-index difference by checking the excalidraw elements
-        // are in order
-        return libraryItem.elements.every((libItemExcalidrawItem, idx) => {
-          return (
-            libItemExcalidrawItem.id === targetLibraryItem.elements[idx].id &&
-            libItemExcalidrawItem.versionNonce ===
-              targetLibraryItem.elements[idx].versionNonce
-          );
-        });
-      });
-    };
-
-    const existingLibraryItems = await this.loadLibrary();
-
-    const library = libraryFile.libraryItems || libraryFile.library || [];
-    const restoredLibItems = restoreLibraryItems(library, defaultStatus);
-    const filteredItems = [];
-    for (const item of restoredLibItems) {
-      if (isUniqueitem(existingLibraryItems, item)) {
-        filteredItems.push(item);
-      }
-    }
-
-    await this.saveLibrary([...filteredItems, ...existingLibraryItems]);
+      }),
+    );
   }
 
   loadLibrary = (): Promise<LibraryItems> => {
     return new Promise(async (resolve) => {
-      if (this.libraryCache) {
-        return resolve(JSON.parse(JSON.stringify(this.libraryCache)));
-      }
-
       try {
-        const libraryItems = this.app.libraryItemsFromStorage;
-        if (!libraryItems) {
-          return resolve([]);
-        }
-
-        const items = restoreLibraryItems(libraryItems, "unpublished");
-
-        // clone to ensure we don't mutate the cached library elements in the app
-        this.libraryCache = JSON.parse(JSON.stringify(items));
-
-        resolve(items);
-      } catch (error: any) {
-        console.error(error);
-        resolve([]);
+        resolve(
+          cloneLibraryItems(
+            await (this.libraryItemsPromise || this.lastLibraryItems),
+          ),
+        );
+      } catch (error) {
+        return resolve(this.lastLibraryItems);
       }
     });
   };
 
-  saveLibrary = async (items: LibraryItems) => {
-    const prevLibraryItems = this.libraryCache;
+  saveLibrary = async (items: LibraryItems | Promise<LibraryItems>) => {
+    const prevLibraryItems = this.lastLibraryItems;
     try {
-      const serializedItems = JSON.stringify(items);
-      // cache optimistically so that the app has access to the latest
-      // immediately
-      this.libraryCache = JSON.parse(serializedItems);
-      await this.app.props.onLibraryChange?.(items);
+      let nextLibraryItems;
+      if (isPromiseLike(items)) {
+        const promise = items.then((items) => cloneLibraryItems(items));
+        this.libraryItemsPromise = promise;
+        jotaiStore.set(libraryItemsAtom, {
+          status: "loading",
+          promise,
+          libraryItems: null,
+        });
+        nextLibraryItems = await promise;
+      } else {
+        nextLibraryItems = cloneLibraryItems(items);
+      }
+
+      this.lastLibraryItems = nextLibraryItems;
+      this.libraryItemsPromise = null;
+
+      jotaiStore.set(libraryItemsAtom, {
+        status: "loaded",
+        libraryItems: nextLibraryItems,
+      });
+      await this.app.props.onLibraryChange?.(
+        cloneLibraryItems(nextLibraryItems),
+      );
     } catch (error: any) {
-      this.libraryCache = prevLibraryItems;
+      this.lastLibraryItems = prevLibraryItems;
+      this.libraryItemsPromise = null;
+      jotaiStore.set(libraryItemsAtom, {
+        status: "loaded",
+        libraryItems: prevLibraryItems,
+      });
       throw error;
     }
   };

src/data/restore.ts

@@ -280,7 +280,7 @@ export const restoreAppState = (
 };
 
 export const restore = (
-  data: ImportedDataState | null,
+  data: Pick<ImportedDataState, "appState" | "elements" | "files"> | null,
   /**
    * Local AppState (`this.state` or initial state from localStorage) so that we
    * don't overwrite local state with default values (when values not
@@ -306,7 +306,7 @@ const restoreLibraryItem = (libraryItem: LibraryItem) => {
 };
 
 export const restoreLibraryItems = (
-  libraryItems: NonOptional<ImportedDataState["libraryItems"]>,
+  libraryItems: ImportedDataState["libraryItems"] = [],
   defaultStatus: LibraryItem["status"],
 ) => {
   const restoredItems: LibraryItem[] = [];