@excalidraw/excalidraw 0.7.0 → 0.11.0

package/types/types.d.ts

@@ -1,15 +1,20 @@
 /// <reference types="react" />
-import { PointerType, ExcalidrawLinearElement, NonDeletedExcalidrawElement, NonDeleted, TextAlign, ExcalidrawElement, FontFamily, GroupId, ExcalidrawBindableElement, Arrowhead, ChartType } from "./element/types";
+import { PointerType, ExcalidrawLinearElement, NonDeletedExcalidrawElement, NonDeleted, TextAlign, ExcalidrawElement, GroupId, ExcalidrawBindableElement, Arrowhead, ChartType, FontFamilyValues, FileId, ExcalidrawImageElement, Theme } from "./element/types";
 import { SHAPES } from "./shapes";
 import { Point as RoughPoint } from "roughjs/bin/geometry";
 import { LinearElementEditor } from "./element/linearElementEditor";
 import { SuggestedBinding } from "./element/binding";
 import { ImportedDataState } from "./data/types";
-import { ExcalidrawImperativeAPI } from "./components/App";
-import type { ResolvablePromise } from "./utils";
+import type App from "./components/App";
+import type { ResolvablePromise, throttleRAF } from "./utils";
 import { Spreadsheet } from "./charts";
 import { Language } from "./i18n";
 import { ClipboardData } from "./clipboard";
+import { isOverScrollBars } from "./scene";
+import { MaybeTransformHandleType } from "./element/transformHandles";
+import Library from "./data/library";
+import type { FileSystemHandle } from "./data/filesystem";
+import type { ALLOWED_IMAGE_MIME_TYPES, MIME_TYPES } from "./constants";
 export declare type Point = Readonly<RoughPoint>;
 export declare type Collaborator = {
     pointer?: {
@@ -25,6 +30,17 @@ export declare type Collaborator = {
         stroke: string;
     };
 };
+export declare type DataURL = string & {
+    _brand: "DataURL";
+};
+export declare type BinaryFileData = {
+    mimeType: typeof ALLOWED_IMAGE_MIME_TYPES[number] | typeof MIME_TYPES.binary;
+    id: FileId;
+    dataURL: DataURL;
+    created: number;
+};
+export declare type BinaryFileMetadata = Omit<BinaryFileData, "dataURL">;
+export declare type BinaryFiles = Record<ExcalidrawElement["id"], BinaryFileData>;
 export declare type AppState = {
     isLoading: boolean;
     errorMessage: string | null;
@@ -39,10 +55,12 @@ export declare type AppState = {
     editingLinearElement: LinearElementEditor | null;
     elementType: typeof SHAPES[number]["value"];
     elementLocked: boolean;
+    penMode: boolean;
+    penDetected: boolean;
     exportBackground: boolean;
     exportEmbedScene: boolean;
     exportWithDarkMode: boolean;
-    shouldAddWatermark: boolean;
+    exportScale: number;
     currentItemStrokeColor: string;
     currentItemBackgroundColor: string;
     currentItemFillStyle: ExcalidrawElement["fillStyle"];
@@ -50,7 +68,7 @@ export declare type AppState = {
     currentItemStrokeStyle: ExcalidrawElement["strokeStyle"];
     currentItemRoughness: number;
     currentItemOpacity: number;
-    currentItemFontFamily: FontFamily;
+    currentItemFontFamily: FontFamilyValues;
     currentItemFontSize: number;
     currentItemTextAlign: TextAlign;
     currentItemStrokeSharpness: ExcalidrawElement["strokeSharpness"];
@@ -67,6 +85,7 @@ export declare type AppState = {
     isRotating: boolean;
     zoom: Zoom;
     openMenu: "canvas" | "shape" | null;
+    openPopup: "canvasColorPicker" | "backgroundColorPicker" | "strokeColorPicker" | null;
     lastPointerDownWith: PointerType;
     selectedElementIds: {
         [id: string]: boolean;
@@ -78,7 +97,7 @@ export declare type AppState = {
     showHelpDialog: boolean;
     toastMessage: string | null;
     zenModeEnabled: boolean;
-    theme: "light" | "dark";
+    theme: Theme;
     gridSize: number | null;
     viewModeEnabled: boolean;
     /** top-most selected groups (i.e. does not include nested groups) */
@@ -93,7 +112,7 @@ export declare type AppState = {
     offsetTop: number;
     offsetLeft: number;
     isLibraryOpen: boolean;
-    fileHandle: import("browser-fs-access").FileSystemHandle | null;
+    fileHandle: FileSystemHandle | null;
     collaborators: Map<string, Collaborator>;
     showStats: boolean;
     currentChartType: ChartType;
@@ -104,16 +123,15 @@ export declare type AppState = {
         shown: true;
         data: Spreadsheet;
     };
+    /** imageElement waiting to be placed on canvas */
+    pendingImageElement: NonDeleted<ExcalidrawImageElement> | null;
+    showHyperlinkPopup: false | "info" | "editor";
 };
 export declare type NormalizedZoomValue = number & {
     _brand: "normalizedZoom";
 };
 export declare type Zoom = Readonly<{
     value: NormalizedZoomValue;
-    translation: Readonly<{
-        x: number;
-        y: number;
-    }>;
 }>;
 export declare type PointerCoords = Readonly<{
     x: number;
@@ -132,14 +150,27 @@ export declare class GestureEvent extends UIEvent {
     readonly rotation: number;
     readonly scale: number;
 }
-export declare type LibraryItem = readonly NonDeleted<ExcalidrawElement>[];
+/** @deprecated legacy: do not use outside of migration paths */
+export declare type LibraryItem_v1 = readonly NonDeleted<ExcalidrawElement>[];
+/** @deprecated legacy: do not use outside of migration paths */
+export declare type LibraryItems_v1 = readonly LibraryItem_v1[];
+/** v2 library item */
+export declare type LibraryItem = {
+    id: string;
+    status: "published" | "unpublished";
+    elements: readonly NonDeleted<ExcalidrawElement>[];
+    /** timestamp in epoch (ms) */
+    created: number;
+    name?: string;
+    error?: string;
+};
 export declare type LibraryItems = readonly LibraryItem[];
 export declare type ExcalidrawAPIRefValue = ExcalidrawImperativeAPI | {
     readyPromise?: ResolvablePromise<ExcalidrawImperativeAPI>;
     ready?: false;
 };
 export interface ExcalidrawProps {
-    onChange?: (elements: readonly ExcalidrawElement[], appState: AppState) => void;
+    onChange?: (elements: readonly ExcalidrawElement[], appState: AppState, files: BinaryFiles) => void;
     initialData?: ImportedDataState | null | Promise<ImportedDataState | null>;
     excalidrawRef?: ForwardRef<ExcalidrawAPIRefValue>;
     onCollabButtonClick?: () => void;
@@ -152,50 +183,150 @@ export interface ExcalidrawProps {
         button: "down" | "up";
         pointersMap: Gesture["pointers"];
     }) => void;
-    onExportToBackend?: (exportedElements: readonly NonDeletedExcalidrawElement[], appState: AppState, canvas: HTMLCanvasElement | null) => void;
     onPaste?: (data: ClipboardData, event: ClipboardEvent | null) => Promise<boolean> | boolean;
-    renderFooter?: (isMobile: boolean) => JSX.Element;
+    renderTopRightUI?: (isMobile: boolean, appState: AppState) => JSX.Element | null;
+    renderFooter?: (isMobile: boolean, appState: AppState) => JSX.Element;
     langCode?: Language["code"];
     viewModeEnabled?: boolean;
     zenModeEnabled?: boolean;
     gridModeEnabled?: boolean;
     libraryReturnUrl?: string;
-    theme?: "dark" | "light";
+    theme?: Theme;
     name?: string;
     renderCustomStats?: (elements: readonly NonDeletedExcalidrawElement[], appState: AppState) => JSX.Element;
     UIOptions?: UIOptions;
     detectScroll?: boolean;
     handleKeyboardGlobally?: boolean;
     onLibraryChange?: (libraryItems: LibraryItems) => void | Promise<any>;
+    autoFocus?: boolean;
+    generateIdForFile?: (file: File) => string | Promise<string>;
+    onLinkOpen?: (element: NonDeletedExcalidrawElement, event: CustomEvent<{
+        nativeEvent: MouseEvent | React.PointerEvent<HTMLCanvasElement>;
+    }>) => void;
 }
 export declare type SceneData = {
     elements?: ImportedDataState["elements"];
     appState?: ImportedDataState["appState"];
     collaborators?: Map<string, Collaborator>;
     commitToHistory?: boolean;
+    libraryItems?: LibraryItems | LibraryItems_v1;
 };
 export declare enum UserIdleState {
     ACTIVE = "active",
     AWAY = "away",
     IDLE = "idle"
 }
+export declare type ExportOpts = {
+    saveFileToDisk?: boolean;
+    onExportToBackend?: (exportedElements: readonly NonDeletedExcalidrawElement[], appState: AppState, files: BinaryFiles, canvas: HTMLCanvasElement | null) => void;
+    renderCustomUI?: (exportedElements: readonly NonDeletedExcalidrawElement[], appState: AppState, files: BinaryFiles, canvas: HTMLCanvasElement | null) => JSX.Element;
+};
 declare type CanvasActions = {
     changeViewBackgroundColor?: boolean;
     clearCanvas?: boolean;
-    export?: boolean;
+    export?: false | ExportOpts;
     loadScene?: boolean;
-    saveAsScene?: boolean;
-    saveScene?: boolean;
+    saveToActiveFile?: boolean;
     theme?: boolean;
+    saveAsImage?: boolean;
 };
 export declare type UIOptions = {
     canvasActions?: CanvasActions;
 };
 export declare type AppProps = ExcalidrawProps & {
     UIOptions: {
-        canvasActions: Required<CanvasActions>;
+        canvasActions: Required<CanvasActions> & {
+            export: ExportOpts;
+        };
     };
     detectScroll: boolean;
     handleKeyboardGlobally: boolean;
+    isCollaborating: boolean;
+};
+/** A subset of App class properties that we need to use elsewhere
+ * in the app, eg Manager. Factored out into a separate type to keep DRY. */
+export declare type AppClassProperties = {
+    props: AppProps;
+    canvas: HTMLCanvasElement | null;
+    focusContainer(): void;
+    library: Library;
+    imageCache: Map<FileId, {
+        image: HTMLImageElement | Promise<HTMLImageElement>;
+        mimeType: typeof ALLOWED_IMAGE_MIME_TYPES[number];
+    }>;
+    files: BinaryFiles;
+};
+export declare type PointerDownState = Readonly<{
+    origin: Readonly<{
+        x: number;
+        y: number;
+    }>;
+    originInGrid: Readonly<{
+        x: number;
+        y: number;
+    }>;
+    scrollbars: ReturnType<typeof isOverScrollBars>;
+    lastCoords: {
+        x: number;
+        y: number;
+    };
+    originalElements: Map<string, NonDeleted<ExcalidrawElement>>;
+    resize: {
+        handleType: MaybeTransformHandleType;
+        isResizing: boolean;
+        offset: {
+            x: number;
+            y: number;
+        };
+        arrowDirection: "origin" | "end";
+        center: {
+            x: number;
+            y: number;
+        };
+    };
+    hit: {
+        element: NonDeleted<ExcalidrawElement> | null;
+        allHitElements: NonDeleted<ExcalidrawElement>[];
+        wasAddedToSelection: boolean;
+        hasBeenDuplicated: boolean;
+        hasHitCommonBoundingBoxOfSelectedElements: boolean;
+        hasHitElementInside: boolean;
+    };
+    withCmdOrCtrl: boolean;
+    drag: {
+        hasOccurred: boolean;
+        offset: {
+            x: number;
+            y: number;
+        } | null;
+    };
+    eventListeners: {
+        onMove: null | ReturnType<typeof throttleRAF>;
+        onUp: null | ((event: PointerEvent) => void);
+        onKeyDown: null | ((event: KeyboardEvent) => void);
+        onKeyUp: null | ((event: KeyboardEvent) => void);
+    };
+    boxSelection: {
+        hasOccurred: boolean;
+    };
+}>;
+export declare type ExcalidrawImperativeAPI = {
+    updateScene: InstanceType<typeof App>["updateScene"];
+    resetScene: InstanceType<typeof App>["resetScene"];
+    getSceneElementsIncludingDeleted: InstanceType<typeof App>["getSceneElementsIncludingDeleted"];
+    history: {
+        clear: InstanceType<typeof App>["resetHistory"];
+    };
+    scrollToContent: InstanceType<typeof App>["scrollToContent"];
+    getSceneElements: InstanceType<typeof App>["getSceneElements"];
+    getAppState: () => InstanceType<typeof App>["state"];
+    getFiles: () => InstanceType<typeof App>["files"];
+    refresh: InstanceType<typeof App>["refresh"];
+    importLibrary: InstanceType<typeof App>["importLibraryFromUrl"];
+    setToastMessage: InstanceType<typeof App>["setToastMessage"];
+    addFiles: (data: BinaryFileData[]) => void;
+    readyPromise: ResolvablePromise<ExcalidrawImperativeAPI>;
+    ready: true;
+    id: string;
 };
 export {};

package/types/utils.d.ts

@@ -1,6 +1,6 @@
-import { FontFamily, FontString } from "./element/types";
+import { EVENT } from "./constants";
+import { FontFamilyValues, FontString } from "./element/types";
 import { Zoom } from "./types";
-export declare const SVG_NS = "http://www.w3.org/2000/svg";
 export declare const setDateTimeForTests: (dateTime: string) => void;
 export declare const getDateTime: () => string;
 export declare const capitalizeString: (str: string) => string;
@@ -8,23 +8,24 @@ export declare const isToolIcon: (target: Element | EventTarget | null) => targe
 export declare const isInputLike: (target: Element | EventTarget | null) => target is HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement | HTMLBRElement | HTMLDivElement;
 export declare const isWritableElement: (target: Element | EventTarget | null) => target is HTMLInputElement | HTMLTextAreaElement | HTMLBRElement | HTMLDivElement;
 export declare const getFontFamilyString: ({ fontFamily, }: {
-    fontFamily: FontFamily;
+    fontFamily: FontFamilyValues;
 }) => string;
 /** returns fontSize+fontFamily string for assignment to DOM elements */
 export declare const getFontString: ({ fontSize, fontFamily, }: {
     fontSize: number;
-    fontFamily: FontFamily;
+    fontFamily: FontFamilyValues;
 }) => FontString;
-export declare const measureText: (text: string, font: FontString) => {
-    width: number;
-    height: number;
-    baseline: number;
-};
 export declare const debounce: <T extends any[]>(fn: (...args: T) => void, timeout: number) => {
     (...args: T): void;
     flush(): void;
     cancel(): void;
 };
+export declare const throttleRAF: <T extends any[]>(fn: (...args: T) => void) => {
+    (...args: T): void;
+    flush(): void;
+    cancel(): void;
+};
+export declare const chunk: <T extends unknown>(array: readonly T[], size: number) => T[][];
 export declare const selectNode: (node: Element) => void;
 export declare const removeSelection: () => void;
 export declare const distance: (x: number, y: number) => number;
@@ -87,8 +88,31 @@ export declare const resolvablePromise: <T>() => ResolvablePromise<T>;
  * @param func handler taking at most single parameter (event).
  */
 export declare const withBatchedUpdates: <TFunction extends ((event: any) => void) | (() => void)>(func: Parameters<TFunction>["length"] extends 0 | 1 ? TFunction : never) => TFunction;
+/**
+ * barches React state updates and throttles the calls to a single call per
+ * animation frame
+ */
+export declare const withBatchedUpdatesThrottled: <TFunction extends ((event: any) => void) | (() => void)>(func: Parameters<TFunction>["length"] extends 0 | 1 ? TFunction : never) => {
+    (...args: Parameters<TFunction>): void;
+    flush(): void;
+    cancel(): void;
+};
 export declare const nFormatter: (num: number, digits: number) => string;
 export declare const getVersion: () => string;
 export declare const supportsEmoji: () => boolean;
 export declare const getNearestScrollableContainer: (element: HTMLElement) => HTMLElement | Document;
 export declare const focusNearestParent: (element: HTMLInputElement) => void;
+export declare const preventUnload: (event: BeforeUnloadEvent) => void;
+export declare const bytesToHexString: (bytes: Uint8Array) => string;
+export declare const getUpdatedTimestamp: () => number;
+/**
+ * Transforms array of objects containing `id` attribute,
+ * or array of ids (strings), into a Map, keyd by `id`.
+ */
+export declare const arrayToMap: <T extends string | {
+    id: string;
+}>(items: readonly T[]) => Map<string, T>;
+export declare const isTestEnv: () => boolean;
+export declare const wrapEvent: <T extends Event>(name: EVENT, nativeEvent: T) => CustomEvent<{
+    nativeEvent: T;
+}>;

package/types/zindex.d.ts

@@ -1,6 +1,6 @@
 import { ExcalidrawElement } from "./element/types";
 import { AppState } from "./types";
-export declare const moveOneLeft: (elements: readonly ExcalidrawElement[], appState: AppState) => (import("./element/types").ExcalidrawLinearElement | import("./element/types").ExcalidrawSelectionElement | import("./element/types").ExcalidrawRectangleElement | import("./element/types").ExcalidrawDiamondElement | import("./element/types").ExcalidrawEllipseElement | import("./element/types").ExcalidrawTextElement)[];
-export declare const moveOneRight: (elements: readonly ExcalidrawElement[], appState: AppState) => (import("./element/types").ExcalidrawLinearElement | import("./element/types").ExcalidrawSelectionElement | import("./element/types").ExcalidrawRectangleElement | import("./element/types").ExcalidrawDiamondElement | import("./element/types").ExcalidrawEllipseElement | import("./element/types").ExcalidrawTextElement)[];
+export declare const moveOneLeft: (elements: readonly ExcalidrawElement[], appState: AppState) => (import("./element/types").ExcalidrawLinearElement | import("./element/types").ExcalidrawSelectionElement | import("./element/types").ExcalidrawRectangleElement | import("./element/types").ExcalidrawDiamondElement | import("./element/types").ExcalidrawEllipseElement | import("./element/types").ExcalidrawImageElement | import("./element/types").ExcalidrawTextElement | import("./element/types").ExcalidrawFreeDrawElement)[];
+export declare const moveOneRight: (elements: readonly ExcalidrawElement[], appState: AppState) => (import("./element/types").ExcalidrawLinearElement | import("./element/types").ExcalidrawSelectionElement | import("./element/types").ExcalidrawRectangleElement | import("./element/types").ExcalidrawDiamondElement | import("./element/types").ExcalidrawEllipseElement | import("./element/types").ExcalidrawImageElement | import("./element/types").ExcalidrawTextElement | import("./element/types").ExcalidrawFreeDrawElement)[];
 export declare const moveAllLeft: (elements: readonly ExcalidrawElement[], appState: AppState) => readonly ExcalidrawElement[];
 export declare const moveAllRight: (elements: readonly ExcalidrawElement[], appState: AppState) => readonly ExcalidrawElement[];