@excalidraw/excalidraw 0.17.1-a38e82f → 0.17.1-b7babe5

package/dist/excalidraw/data/library.d.ts

@@ -1,13 +1,53 @@
-import { LibraryItems, ExcalidrawImperativeAPI, LibraryItemsSource } from "../types";
+import { LibraryItems, ExcalidrawImperativeAPI, LibraryItemsSource, LibraryItems_anyVersion } from "../types";
 import type App from "../components/App";
 import { ExcalidrawElement } from "../element/types";
+import { MaybePromise } from "../utility-types";
+export type LibraryPersistedData = {
+    libraryItems: LibraryItems;
+};
+export type LibraryAdatapterSource = "load" | "save";
+export interface LibraryPersistenceAdapter {
+    /**
+     * Should load data that were previously saved into the database using the
+     * `save` method. Should throw if saving fails.
+     *
+     * Will be used internally in multiple places, such as during save to
+     * in order to reconcile changes with latest store data.
+     */
+    load(metadata: {
+        /**
+         * Indicates whether we're loading data for save purposes, or reading
+         * purposes, in which case host app can implement more aggressive caching.
+         */
+        source: LibraryAdatapterSource;
+    }): MaybePromise<{
+        libraryItems: LibraryItems_anyVersion;
+    } | null>;
+    /** Should persist to the database as is (do no change the data structure). */
+    save(libraryData: LibraryPersistedData): MaybePromise<void>;
+}
+export interface LibraryMigrationAdapter {
+    /**
+     * loads data from legacy data source. Returns `null` if no data is
+     * to be migrated.
+     */
+    load(): MaybePromise<{
+        libraryItems: LibraryItems_anyVersion;
+    } | null>;
+    /** clears entire storage afterwards */
+    clear(): MaybePromise<void>;
+}
 export declare const libraryItemsAtom: import("jotai").PrimitiveAtom<{
     status: "loading" | "loaded";
+    /** indicates whether library is initialized with library items (has gone
+     * through at least one update). Used in UI. Specific to this atom only. */
     isInitialized: boolean;
     libraryItems: LibraryItems;
 }> & {
     init: {
         status: "loading" | "loaded";
+        /** indicates whether library is initialized with library items (has gone
+         * through at least one update). Used in UI. Specific to this atom only. */
         isInitialized: boolean;
         libraryItems: LibraryItems;
     };
@@ -17,10 +57,9 @@ export declare const libraryItemsAtom: import("jotai").PrimitiveAtom<{
 export declare const mergeLibraryItems: (localItems: LibraryItems, otherItems: LibraryItems) => LibraryItems;
 declare class Library {
     /** latest libraryItems */
-    private lastLibraryItems;
-    /** indicates whether library is initialized with library items (has gone
-     * though at least one update) */
-    private isInitialized;
+    private currLibraryItems;
+    /** snapshot of library items since last onLibraryChange call */
+    private prevLibraryItems;
     private app;
     constructor(app: App);
     private updateQueue;
@@ -48,7 +87,20 @@ export declare const parseLibraryTokensFromUrl: () => {
     libraryUrl: string;
     idToken: string | null;
 } | null;
-export declare const useHandleLibrary: ({ excalidrawAPI, getInitialLibraryItems, }: {
+export declare const getLibraryItemsHash: (items: LibraryItems) => number;
+export declare const useHandleLibrary: (opts: {
     excalidrawAPI: ExcalidrawImperativeAPI | null;
-    getInitialLibraryItems?: (() => LibraryItemsSource) | undefined;
-}) => void;
+} & ({
+    /** @deprecated we recommend using `opts.adapter` instead */
+    getInitialLibraryItems?: () => MaybePromise<LibraryItemsSource>;
+} | {
+    adapter: LibraryPersistenceAdapter;
+    /**
+     * Adapter that takes care of loading data from legacy data store.
+     * Supply this if you want to migrate data on initial load from legacy
+     * data store.
+     *
+     * Can be a different LibraryPersistenceAdapter.
+     */
+    migrationAdapter?: LibraryMigrationAdapter;
+})) => void;

package/dist/excalidraw/data/library.js

@@ -8,8 +8,12 @@ import { t } from "../i18n";
 import { useEffect, useRef } from "react";
 import { URL_HASH_KEYS, URL_QUERY_KEYS, APP_NAME, EVENT, DEFAULT_SIDEBAR, LIBRARY_SIDEBAR_TAB, } from "../constants";
 import { libraryItemSvgsCache } from "../hooks/useLibraryItemSvg";
-import { cloneJSON } from "../utils";
-export const libraryItemsAtom = atom({ status: "loaded", isInitialized: true, libraryItems: [] });
+import { arrayToMap, cloneJSON, preventUnload, promiseTry, resolvablePromise, } from "../utils";
+import { Emitter } from "../emitter";
+import { Queue } from "../queue";
+import { hashElementsVersion, hashString } from "../element";
+const onLibraryUpdateEmitter = new Emitter();
+export const libraryItemsAtom = atom({ status: "loaded", isInitialized: false, libraryItems: [] });
 const cloneLibraryItems = (libraryItems) => cloneJSON(libraryItems);
 /**
  * checks if library item does not exist already in current library
@@ -39,12 +43,36 @@ export const mergeLibraryItems = (localItems, otherItems) => {
     }
     return [...newItems, ...localItems];
 };
+/**
+ * Returns { deletedItems, addedItems } maps of all added and deleted items
+ * since last onLibraryChange event.
+ *
+ * Host apps are recommended to diff with the latest state they have.
+ */
+const createLibraryUpdate = (prevLibraryItems, nextLibraryItems) => {
+    const nextItemsMap = arrayToMap(nextLibraryItems);
+    const update = {
+        deletedItems: new Map(),
+        addedItems: new Map(),
+    };
+    for (const item of prevLibraryItems) {
+        if (!nextItemsMap.has(item.id)) {
+            update.deletedItems.set(item.id, item);
+        }
+    }
+    const prevItemsMap = arrayToMap(prevLibraryItems);
+    for (const item of nextLibraryItems) {
+        if (!prevItemsMap.has(item.id)) {
+            update.addedItems.set(item.id, item);
+        }
+    }
+    return update;
+};
 class Library {
     /** latest libraryItems */
-    lastLibraryItems = [];
-    /** indicates whether library is initialized with library items (has gone
-     * though at least one update) */
-    isInitialized = false;
+    currLibraryItems = [];
+    /** snapshot of library items since last onLibraryChange call */
+    prevLibraryItems = cloneLibraryItems(this.currLibraryItems);
     app;
     constructor(app) {
         this.app = app;
@@ -55,21 +83,25 @@ class Library {
     };
     notifyListeners = () => {
         if (this.updateQueue.length > 0) {
-            jotaiStore.set(libraryItemsAtom, {
+            jotaiStore.set(libraryItemsAtom, (s) => ({
                 status: "loading",
-                libraryItems: this.lastLibraryItems,
-                isInitialized: this.isInitialized,
-            });
+                libraryItems: this.currLibraryItems,
+                isInitialized: s.isInitialized,
+            }));
         }
         else {
-            this.isInitialized = true;
             jotaiStore.set(libraryItemsAtom, {
                 status: "loaded",
-                libraryItems: this.lastLibraryItems,
-                isInitialized: this.isInitialized,
+                libraryItems: this.currLibraryItems,
+                isInitialized: true,
             });
             try {
-                this.app.props.onLibraryChange?.(cloneLibraryItems(this.lastLibraryItems));
+                const prevLibraryItems = this.prevLibraryItems;
+                this.prevLibraryItems = cloneLibraryItems(this.currLibraryItems);
+                const nextLibraryItems = cloneLibraryItems(this.currLibraryItems);
+                this.app.props.onLibraryChange?.(nextLibraryItems);
+                // for internal use in `useHandleLibrary` hook
+                onLibraryUpdateEmitter.trigger(createLibraryUpdate(prevLibraryItems, nextLibraryItems), nextLibraryItems);
             }
             catch (error) {
                 console.error(error);
@@ -78,9 +110,8 @@ class Library {
     };
     /** call on excalidraw instance unmount */
     destroy = () => {
-        this.isInitialized = false;
         this.updateQueue = [];
-        this.lastLibraryItems = [];
+        this.currLibraryItems = [];
         jotaiStore.set(libraryItemSvgsCache, new Map());
         // TODO uncomment after/if we make jotai store scoped to each excal instance
         // jotaiStore.set(libraryItemsAtom, {
@@ -99,7 +130,7 @@ class Library {
         return new Promise(async (resolve) => {
             try {
                 const libraryItems = await (this.getLastUpdateTask() ||
-                    this.lastLibraryItems);
+                    this.currLibraryItems);
                 if (this.updateQueue.length > 0) {
                     resolve(this.getLatestLibrary());
                 }
@@ -108,7 +139,7 @@ class Library {
                 }
             }
             catch (error) {
-                return resolve(this.lastLibraryItems);
+                return resolve(this.currLibraryItems);
             }
         });
     };
@@ -126,7 +157,7 @@ class Library {
                 try {
                     const source = await (typeof libraryItems === "function" &&
                         !(libraryItems instanceof Blob)
-                        ? libraryItems(this.lastLibraryItems)
+                        ? libraryItems(this.currLibraryItems)
                         : libraryItems);
                     let nextItems;
                     if (source instanceof Blob) {
@@ -146,7 +177,7 @@ class Library {
                             this.app.focusContainer();
                         }
                         if (merge) {
-                            resolve(mergeLibraryItems(this.lastLibraryItems, nextItems));
+                            resolve(mergeLibraryItems(this.currLibraryItems, nextItems));
                         }
                         else {
                             resolve(nextItems);
@@ -178,10 +209,10 @@ class Library {
             try {
                 await this.getLastUpdateTask();
                 if (typeof libraryItems === "function") {
-                    libraryItems = libraryItems(this.lastLibraryItems);
+                    libraryItems = libraryItems(this.currLibraryItems);
                 }
-                this.lastLibraryItems = cloneLibraryItems(await libraryItems);
-                resolve(this.lastLibraryItems);
+                this.currLibraryItems = cloneLibraryItems(await libraryItems);
+                resolve(this.currLibraryItems);
             }
             catch (error) {
                 reject(error);
@@ -190,7 +221,7 @@ class Library {
             .catch((error) => {
             if (error.name === "AbortError") {
                 console.warn("Library update aborted by user");
-                return this.lastLibraryItems;
+                return this.currLibraryItems;
             }
             throw error;
         })
@@ -291,12 +322,105 @@ export const parseLibraryTokensFromUrl = () => {
         : null;
     return libraryUrl ? { libraryUrl, idToken } : null;
 };
-export const useHandleLibrary = ({ excalidrawAPI, getInitialLibraryItems, }) => {
-    const getInitialLibraryRef = useRef(getInitialLibraryItems);
+class AdapterTransaction {
+    static queue = new Queue();
+    static async getLibraryItems(adapter, source, _queue = true) {
+        const task = () => new Promise(async (resolve, reject) => {
+            try {
+                const data = await adapter.load({ source });
+                resolve(restoreLibraryItems(data?.libraryItems || [], "published"));
+            }
+            catch (error) {
+                reject(error);
+            }
+        });
+        if (_queue) {
+            return AdapterTransaction.queue.push(task);
+        }
+        return task();
+    }
+    static run = async (adapter, fn) => {
+        const transaction = new AdapterTransaction(adapter);
+        return AdapterTransaction.queue.push(() => fn(transaction));
+    };
+    // ------------------
+    adapter;
+    constructor(adapter) {
+        this.adapter = adapter;
+    }
+    getLibraryItems(source) {
+        return AdapterTransaction.getLibraryItems(this.adapter, source, false);
+    }
+}
+let lastSavedLibraryItemsHash = 0;
+let librarySaveCounter = 0;
+export const getLibraryItemsHash = (items) => {
+    return hashString(items
+        .map((item) => {
+        return `${item.id}:${hashElementsVersion(item.elements)}`;
+    })
+        .sort()
+        .join());
+};
+const persistLibraryUpdate = async (adapter, update) => {
+    try {
+        librarySaveCounter++;
+        return await AdapterTransaction.run(adapter, async (transaction) => {
+            const nextLibraryItemsMap = arrayToMap(await transaction.getLibraryItems("save"));
+            for (const [id] of update.deletedItems) {
+                nextLibraryItemsMap.delete(id);
+            }
+            const addedItems = [];
+            // we want to merge current library items with the ones stored in the
+            // DB so that we don't lose any elements that for some reason aren't
+            // in the current editor library, which could happen when:
+            //
+            // 1. we haven't received an update deleting some elements
+            //    (in which case it's still better to keep them in the DB lest
+            //     it was due to a different reason)
+            // 2. we keep a single DB for all active editors, but the editors'
+            //    libraries aren't synced or there's a race conditions during
+            //    syncing
+            // 3. some other race condition, e.g. during init where emit updates
+            //    for partial updates (e.g. you install a 3rd party library and
+            //    init from DB only after — we emit events for both updates)
+            for (const [id, item] of update.addedItems) {
+                if (nextLibraryItemsMap.has(id)) {
+                    // replace item with latest version
+                    // TODO we could prefer the newer item instead
+                    nextLibraryItemsMap.set(id, item);
+                }
+                else {
+                    // we want to prepend the new items with the ones that are already
+                    // in DB to preserve the ordering we do in editor (newly added
+                    // items are added to the beginning)
+                    addedItems.push(item);
+                }
+            }
+            const nextLibraryItems = addedItems.concat(Array.from(nextLibraryItemsMap.values()));
+            const version = getLibraryItemsHash(nextLibraryItems);
+            if (version !== lastSavedLibraryItemsHash) {
+                await adapter.save({ libraryItems: nextLibraryItems });
+            }
+            lastSavedLibraryItemsHash = version;
+            return nextLibraryItems;
+        });
+    }
+    finally {
+        librarySaveCounter--;
+    }
+};
+export const useHandleLibrary = (opts) => {
+    const { excalidrawAPI } = opts;
+    const optsRef = useRef(opts);
+    optsRef.current = opts;
+    const isLibraryLoadedRef = useRef(false);
     useEffect(() => {
         if (!excalidrawAPI) {
             return;
         }
+        // reset on editor remount (excalidrawAPI changed)
+        isLibraryLoadedRef.current = false;
         const importLibraryFromURL = async ({ libraryUrl, idToken, }) => {
             const libraryPromise = new Promise(async (resolve, reject) => {
                 try {
@@ -357,20 +481,165 @@ export const useHandleLibrary = ({ excalidrawAPI, getInitialLibraryItems, }) =>
             }
         };
         // -------------------------------------------------------------------------
-        // ------ init load --------------------------------------------------------
-        if (getInitialLibraryRef.current) {
-            excalidrawAPI.updateLibrary({
-                libraryItems: getInitialLibraryRef.current(),
-            });
-        }
+        // ---------------------------------- init ---------------------------------
+        // -------------------------------------------------------------------------
         const libraryUrlTokens = parseLibraryTokensFromUrl();
         if (libraryUrlTokens) {
             importLibraryFromURL(libraryUrlTokens);
         }
+        // ------ (A) init load (legacy) -------------------------------------------
+        if ("getInitialLibraryItems" in optsRef.current &&
+            optsRef.current.getInitialLibraryItems) {
+            console.warn("useHandleLibrar `opts.getInitialLibraryItems` is deprecated. Use `opts.adapter` instead.");
+            Promise.resolve(optsRef.current.getInitialLibraryItems())
+                .then((libraryItems) => {
+                excalidrawAPI.updateLibrary({
+                    libraryItems,
+                    // merge with current library items because we may have already
+                    // populated it (e.g. by installing 3rd party library which can
+                    // happen before the DB data is loaded)
+                    merge: true,
+                });
+            })
+                .catch((error) => {
+                console.error(`UseHandeLibrary getInitialLibraryItems failed: ${error?.message}`);
+            });
+        }
+        // -------------------------------------------------------------------------
         // --------------------------------------------------------- init load -----
+        // -------------------------------------------------------------------------
+        // ------ (B) data source adapter ------------------------------------------
+        if ("adapter" in optsRef.current && optsRef.current.adapter) {
+            const adapter = optsRef.current.adapter;
+            const migrationAdapter = optsRef.current.migrationAdapter;
+            const initDataPromise = resolvablePromise();
+            // migrate from old data source if needed
+            // (note, if `migrate` function is defined, we always migrate even
+            //  if the data has already been migrated. In that case it'll be a no-op,
+            //  though with several unnecessary steps — we will still load latest
+            //  DB data during the `persistLibraryChange()` step)
+            // -----------------------------------------------------------------------
+            if (migrationAdapter) {
+                initDataPromise.resolve(promiseTry(migrationAdapter.load)
+                    .then(async (libraryData) => {
+                    let restoredData = null;
+                    try {
+                        // if no library data to migrate, assume no migration needed
+                        // and skip persisting to new data store, as well as well
+                        // clearing the old store via `migrationAdapter.clear()`
+                        if (!libraryData) {
+                            return AdapterTransaction.getLibraryItems(adapter, "load");
+                        }
+                        restoredData = restoreLibraryItems(libraryData.libraryItems || [], "published");
+                        // we don't queue this operation because it's running inside
+                        // a promise that's running inside Library update queue itself
+                        const nextItems = await persistLibraryUpdate(adapter, createLibraryUpdate([], restoredData));
+                        try {
+                            await migrationAdapter.clear();
+                        }
+                        catch (error) {
+                            console.error(`couldn't delete legacy library data: ${error.message}`);
+                        }
+                        // migration suceeded, load migrated data
+                        return nextItems;
+                    }
+                    catch (error) {
+                        console.error(`couldn't migrate legacy library data: ${error.message}`);
+                        // migration failed, load data from previous store, if any
+                        return restoredData;
+                    }
+                })
+                    // errors caught during `migrationAdapter.load()`
+                    .catch((error) => {
+                    console.error(`error during library migration: ${error.message}`);
+                    // as a default, load latest library from current data source
+                    return AdapterTransaction.getLibraryItems(adapter, "load");
+                }));
+            }
+            else {
+                initDataPromise.resolve(promiseTry(AdapterTransaction.getLibraryItems, adapter, "load"));
+            }
+            // load initial (or migrated) library
+            excalidrawAPI
+                .updateLibrary({
+                libraryItems: initDataPromise.then((libraryItems) => {
+                    const _libraryItems = libraryItems || [];
+                    lastSavedLibraryItemsHash = getLibraryItemsHash(_libraryItems);
+                    return _libraryItems;
+                }),
+                // merge with current library items because we may have already
+                // populated it (e.g. by installing 3rd party library which can
+                // happen before the DB data is loaded)
+                merge: true,
+            })
+                .finally(() => {
+                isLibraryLoadedRef.current = true;
+            });
+        }
+        // ---------------------------------------------- data source datapter -----
         window.addEventListener(EVENT.HASHCHANGE, onHashChange);
         return () => {
             window.removeEventListener(EVENT.HASHCHANGE, onHashChange);
         };
-    }, [excalidrawAPI]);
+    }, [
+        // important this useEffect only depends on excalidrawAPI so it only reruns
+        // on editor remounts (the excalidrawAPI changes)
+        excalidrawAPI,
+    ]);
+    // This effect is run without excalidrawAPI dependency so that host apps
+    // can run this hook outside of an active editor instance and the library
+    // update queue/loop survives editor remounts
+    //
+    // This effect is still only meant to be run if host apps supply an persitence
+    // adapter. If we don't have access to it, it the update listener doesn't
+    // do anything.
+    useEffect(() => {
+        // on update, merge with current library items and persist
+        // -----------------------------------------------------------------------
+        const unsubOnLibraryUpdate = onLibraryUpdateEmitter.on(async (update, nextLibraryItems) => {
+            const isLoaded = isLibraryLoadedRef.current;
+            // we want to operate with the latest adapter, but we don't want this
+            // effect to rerun on every adapter change in case host apps' adapter
+            // isn't stable
+            const adapter = ("adapter" in optsRef.current && optsRef.current.adapter) || null;
+            try {
+                if (adapter) {
+                    if (
+                    // if nextLibraryItems hash identical to previously saved hash,
+                    // exit early, even if actual upstream state ends up being
+                    // different (e.g. has more data than we have locally), as it'd
+                    // be low-impact scenario.
+                    lastSavedLibraryItemsHash !==
+                        getLibraryItemsHash(nextLibraryItems)) {
+                        await persistLibraryUpdate(adapter, update);
+                    }
+                }
+            }
+            catch (error) {
+                console.error(`couldn't persist library update: ${error.message}`, update);
+                // currently we only show error if an editor is loaded
+                if (isLoaded && optsRef.current.excalidrawAPI) {
+                    optsRef.current.excalidrawAPI.updateScene({
+                        appState: {
+                            errorMessage: t("errors.saveLibraryError"),
+                        },
+                    });
+                }
+            }
+        });
+        const onUnload = (event) => {
+            if (librarySaveCounter) {
+                preventUnload(event);
+            }
+        };
+        window.addEventListener(EVENT.BEFORE_UNLOAD, onUnload);
+        return () => {
+            window.removeEventListener(EVENT.BEFORE_UNLOAD, onUnload);
+            unsubOnLibraryUpdate();
+            lastSavedLibraryItemsHash = 0;
+            librarySaveCounter = 0;
+        };
+    }, [
+    // this effect must not have any deps so it doesn't rerun
+    ]);
 };

package/dist/excalidraw/element/index.d.ts

@@ -10,7 +10,15 @@ export { isTextElement, isExcalidrawElement } from "./typeChecks";
 export { redrawTextBoundingBox } from "./textElement";
 export { getPerfectElementSize, getLockedLinearCursorAlignSize, isInvisiblySmallElement, resizePerfectLineForNWHandler, getNormalizedDimensions, } from "./sizeHelpers";
 export { showSelectedShapeActions } from "./showSelectedShapeActions";
+/**
+ * @deprecated unsafe, use hashElementsVersion instead
+ */
 export declare const getSceneVersion: (elements: readonly ExcalidrawElement[]) => number;
+/**
+ * Hashes elements' versionNonce (using djb2 algo). Order of elements matters.
+ */
+export declare const hashElementsVersion: (elements: readonly ExcalidrawElement[]) => number;
+export declare const hashString: (s: string) => number;
 export declare const getVisibleElements: (elements: readonly ExcalidrawElement[]) => readonly NonDeletedExcalidrawElement[];
 export declare const getNonDeletedElements: <T extends ExcalidrawElement>(elements: readonly T[]) => readonly NonDeleted<T>[];
 export declare const isNonDeletedElement: <T extends ExcalidrawElement>(element: T) => element is NonDeleted<T>;

package/dist/excalidraw/element/index.js

@@ -11,7 +11,30 @@ export { isTextElement, isExcalidrawElement } from "./typeChecks";
 export { redrawTextBoundingBox } from "./textElement";
 export { getPerfectElementSize, getLockedLinearCursorAlignSize, isInvisiblySmallElement, resizePerfectLineForNWHandler, getNormalizedDimensions, } from "./sizeHelpers";
 export { showSelectedShapeActions } from "./showSelectedShapeActions";
+/**
+ * @deprecated unsafe, use hashElementsVersion instead
+ */
 export const getSceneVersion = (elements) => elements.reduce((acc, el) => acc + el.version, 0);
+/**
+ * Hashes elements' versionNonce (using djb2 algo). Order of elements matters.
+ */
+export const hashElementsVersion = (elements) => {
+    let hash = 5381;
+    for (let i = 0; i < elements.length; i++) {
+        hash = (hash << 5) + hash + elements[i].versionNonce;
+    }
+    return hash >>> 0; // Ensure unsigned 32-bit integer
+};
+// string hash function (using djb2). Not cryptographically secure, use only
+// for versioning and such.
+export const hashString = (s) => {
+    let hash = 5381;
+    for (let i = 0; i < s.length; i++) {
+        const char = s.charCodeAt(i);
+        hash = (hash << 5) + hash + char;
+    }
+    return hash >>> 0; // Ensure unsigned 32-bit integer
+};
 export const getVisibleElements = (elements) => elements.filter((el) => !el.isDeleted && !isInvisiblySmallElement(el));
 export const getNonDeletedElements = (elements) => elements.filter((element) => !element.isDeleted);
 export const isNonDeletedElement = (element) => !element.isDeleted;

package/dist/excalidraw/element/textElement.d.ts

@@ -1,7 +1,7 @@
 import { ElementsMap, ExcalidrawElement, ExcalidrawElementType, ExcalidrawTextContainer, ExcalidrawTextElement, ExcalidrawTextElementWithContainer, FontFamilyValues, FontString, NonDeletedExcalidrawElement } from "./types";
 import { MaybeTransformHandleType } from "./transformHandles";
 import { AppState } from "../types";
-import { ExtractSetType } from "../utility-types";
+import { ExtractSetType, MakeBrand } from "../utility-types";
 export declare const normalizeText: (text: string) => string;
 export declare const redrawTextBoundingBox: (textElement: ExcalidrawTextElement, container: ExcalidrawElement | null, elementsMap: ElementsMap) => void;
 export declare const bindTextToShapeAfterDuplication: (newElements: ExcalidrawElement[], oldElements: ExcalidrawElement[], oldIdToDuplicatedId: Map<ExcalidrawElement["id"], ExcalidrawElement["id"]>) => void;
@@ -70,6 +70,21 @@ export declare const computeContainerDimensionForBoundText: (dimension: number,
 export declare const getBoundTextMaxWidth: (container: ExcalidrawElement, boundTextElement: ExcalidrawTextElement | null) => number;
 export declare const getBoundTextMaxHeight: (container: ExcalidrawElement, boundTextElement: ExcalidrawTextElementWithContainer) => number;
 export declare const isMeasureTextSupported: () => boolean;
+/** OS/2 sTypoAscender, https://learn.microsoft.com/en-us/typography/opentype/spec/os2#stypoascender */
+type sTypoAscender = number & MakeBrand<"sTypoAscender">;
+/** OS/2 sTypoDescender, https://learn.microsoft.com/en-us/typography/opentype/spec/os2#stypodescender */
+type sTypoDescender = number & MakeBrand<"sTypoDescender">;
+/**
+ * Hardcoded metrics for default fonts, read by https://opentype.js.org/font-inspector.html.
+ * For custom fonts, read these metrics from OS/2 table and extend this object.
+ *
+ * WARN: opentype does NOT open WOFF2 correctly, make sure to convert WOFF2 to TTF first.
+ */
+export declare const FONT_METRICS: Record<number, {
+    unitsPerEm: number;
+    ascender: sTypoAscender;
+    descender: sTypoDescender;
+}>;
 export declare const getDefaultLineHeight: (fontFamily: FontFamilyValues) => number & {
     _brand: "unitlessLineHeight";
 };

package/dist/excalidraw/element/textElement.js

@@ -203,7 +203,7 @@ export const getLineHeightInPx = (fontSize, lineHeight) => {
  * Calculates vertical offset for a text with alphabetic baseline.
  */
 export const getVerticalOffset = (fontFamily, fontSize, lineHeightPx) => {
-    const { unitsPerEm, ascender, descender } = FONT_METRICS[fontFamily];
+    const { unitsPerEm, ascender, descender } = FONT_METRICS[fontFamily] || FONT_METRICS[FONT_FAMILY.Helvetica];
     const fontSizeEm = fontSize / unitsPerEm;
     const lineGap = lineHeightPx - fontSizeEm * ascender + fontSizeEm * descender;
     const verticalOffset = fontSizeEm * ascender + lineGap;
@@ -658,9 +658,11 @@ const DEFAULT_LINE_HEIGHT = {
 };
 /**
  * Hardcoded metrics for default fonts, read by https://opentype.js.org/font-inspector.html.
- * For custom fonts, read these metrics on load and extend this object.
+ * For custom fonts, read these metrics from OS/2 table and extend this object.
+ *
+ * WARN: opentype does NOT open WOFF2 correctly, make sure to convert WOFF2 to TTF first.
  */
-const FONT_METRICS = {
+export const FONT_METRICS = {
     [FONT_FAMILY.Virgil]: {
         unitsPerEm: 1000,
         ascender: 886,
@@ -676,6 +678,11 @@ const FONT_METRICS = {
         ascender: 1977,
         descender: -480,
     },
+    [FONT_FAMILY.Assistant]: {
+        unitsPerEm: 1000,
+        ascender: 1021,
+        descender: -287,
+    },
 };
 export const getDefaultLineHeight = (fontFamily) => {
     if (fontFamily in DEFAULT_LINE_HEIGHT) {

package/dist/excalidraw/index.d.ts

@@ -8,14 +8,14 @@ import MainMenu from "./components/main-menu/MainMenu";
 import WelcomeScreen from "./components/welcome-screen/WelcomeScreen";
 import LiveCollaborationTrigger from "./components/live-collaboration/LiveCollaborationTrigger";
 export declare const Excalidraw: React.MemoExoticComponent<(props: ExcalidrawProps) => JSX.Element>;
-export { getSceneVersion, isInvisiblySmallElement, getNonDeletedElements, } from "./element";
+export { getSceneVersion, hashElementsVersion, hashString, isInvisiblySmallElement, getNonDeletedElements, } from "./element";
 export { defaultLang, useI18n, languages } from "./i18n";
 export { restore, restoreAppState, restoreElements, restoreLibraryItems, } from "./data/restore";
 export { exportToCanvas, exportToBlob, exportToSvg, exportToClipboard, } from "../utils/export";
 export { serializeAsJSON, serializeLibraryAsJSON } from "./data/json";
 export { loadFromBlob, loadSceneOrLibraryFromBlob, loadLibraryFromBlob, } from "./data/blob";
 export { getFreeDrawSvgPath } from "./renderer/renderElement";
-export { mergeLibraryItems } from "./data/library";
+export { mergeLibraryItems, getLibraryItemsHash } from "./data/library";
 export { isLinearElement } from "./element/typeChecks";
 export { FONT_FAMILY, THEME, MIME_TYPES, ROUNDNESS } from "./constants";
 export { mutateElement, newElementWith, bumpVersion, } from "./element/mutateElement";