@excalidraw/math 0.18.0-51ad895 → 0.18.0-51ca8ab

package/dist/types/excalidraw/types.d.ts

@@ -1,22 +1,24 @@
-import type { IMAGE_MIME_TYPES, UserIdleState, throttleRAF, MIME_TYPES, EditorInterface } from "@excalidraw/common";
+import type { IMAGE_MIME_TYPES, UserIdleState, throttleRAF, MIME_TYPES, EditorInterface, StrokeWidthKey } from "@excalidraw/common";
 import type { LinearElementEditor } from "@excalidraw/element";
 import type { MaybeTransformHandleType } from "@excalidraw/element";
-import type { PointerType, ExcalidrawLinearElement, NonDeletedExcalidrawElement, NonDeleted, TextAlign, ExcalidrawElement, GroupId, ExcalidrawBindableElement, Arrowhead, ChartType, FontFamilyValues, FileId, Theme, StrokeRoundness, ExcalidrawEmbeddableElement, ExcalidrawMagicFrameElement, ExcalidrawFrameLikeElement, ExcalidrawElementType, ExcalidrawIframeLikeElement, OrderedExcalidrawElement, ExcalidrawNonSelectionElement, BindMode } from "@excalidraw/element/types";
+import type { PointerType, ExcalidrawLinearElement, NonDeletedExcalidrawElement, NonDeleted, TextAlign, ExcalidrawElement, GroupId, ExcalidrawBindableElement, Arrowhead, FontFamilyValues, FileId, Theme, StrokeRoundness, ExcalidrawEmbeddableElement, ExcalidrawMagicFrameElement, ExcalidrawFrameLikeElement, ExcalidrawElementType, ExcalidrawIframeLikeElement, OrderedExcalidrawElement, ExcalidrawNonSelectionElement, BindMode, ExcalidrawTextElement, StrokeVariability } from "@excalidraw/element/types";
 import type { Merge, MaybePromise, ValueOf, MakeBrand } from "@excalidraw/common/utility-types";
 import type { CaptureUpdateActionType, DurableIncrement, EphemeralIncrement } from "@excalidraw/element";
+import type { GlobalPoint } from "@excalidraw/math";
 import type { Action } from "./actions/types";
 import type { Spreadsheet } from "./charts";
 import type { ClipboardData } from "./clipboard";
 import type App from "./components/App";
 import type Library from "./data/library";
-import type { FileSystemHandle } from "./data/filesystem";
 import type { ContextMenuItems } from "./components/ContextMenu";
 import type { SnapLine } from "./snapping";
 import type { ImportedDataState } from "./data/types";
+import type { SetViewportOptions } from "./viewport";
 import type { Language } from "./i18n";
 import type { isOverScrollBars } from "./scene/scrollbars";
 import type React from "react";
 import type { JSX } from "react";
+export type { App };
 export type SocketId = string & {
     _brand: "SocketId";
 };
@@ -128,6 +130,7 @@ export type StaticCanvasAppState = Readonly<_CommonCanvasAppState & {
     croppingElementId: AppState["croppingElementId"];
 }>;
 export type InteractiveCanvasAppState = Readonly<_CommonCanvasAppState & {
+    activeTool: AppState["activeTool"];
     activeEmbeddable: AppState["activeEmbeddable"];
     selectionElement: AppState["selectionElement"];
     selectedGroupIds: AppState["selectedGroupIds"];
@@ -135,6 +138,7 @@ export type InteractiveCanvasAppState = Readonly<_CommonCanvasAppState & {
     multiElement: AppState["multiElement"];
     newElement: AppState["newElement"];
     isBindingEnabled: AppState["isBindingEnabled"];
+    isMidpointSnappingEnabled: AppState["isMidpointSnappingEnabled"];
     suggestedBinding: AppState["suggestedBinding"];
     isRotating: AppState["isRotating"];
     elementsToHighlight: AppState["elementsToHighlight"];
@@ -150,6 +154,7 @@ export type InteractiveCanvasAppState = Readonly<_CommonCanvasAppState & {
     frameRendering: AppState["frameRendering"];
     shouldCacheIgnoreZoom: AppState["shouldCacheIgnoreZoom"];
     exportScale: AppState["exportScale"];
+    currentItemArrowType: AppState["currentItemArrowType"];
 }>;
 export type ObservedAppState = ObservedStandaloneAppState & ObservedElementsAppState;
 export type ObservedStandaloneAppState = {
@@ -168,6 +173,42 @@ export type ObservedElementsAppState = {
     lockedMultiSelections: AppState["lockedMultiSelections"];
     activeLockedId: AppState["activeLockedId"];
 };
+export type BoxSelectionMode = "contain" | "overlap";
+/**
+ * A box, in scene coordinates, that pan & zoom are constrained to.
+ *
+ * This is a private type. For public API, only use specific properties,
+ * needed.
+ */
+export type ScrollConstraints = {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    /** when set, panning is constrained so the viewport stays within the box */
+    lockScroll: boolean;
+    /** when set, the viewport cannot zoom out below `zoom` */
+    lockZoom: boolean;
+    /**
+     * The zoom resolved after the `setViewport` navigation settled.
+     */
+    zoom: number;
+    /**
+     * Pixel amount the viewport may overscroll past its resting clamp before
+     * snapping back (rubberband). Screen pixels, zoom-independent. Resolved
+     * from `lock.overscroll` at the time the lock was installed (`true` →
+     * default give, `false` → 0).
+     */
+    overscroll: number;
+    /**
+     * Extra scrollable margin around the box (CSS-style), letting the viewport
+     * scroll past each box edge to reveal that much empty space. Values are
+     * viewport pixels and zoom-independent (a fixed on-screen distance).
+     * Resolved from the `offsets` passed to `setViewport` (see
+     * {@link ViewportOffsets}) at the time the lock was installed.
+     */
+    offsets?: Offsets;
+};
 export interface AppState {
     contextMenu: {
         items: ContextMenuItems;
@@ -201,9 +242,25 @@ export interface AppState {
      * - set on pointer down, updated during pointer move
      */
     selectionElement: NonDeletedExcalidrawElement | null;
+    /**
+     * tracking current arrow binding editor state (takes into account
+     * `bindingPreference` and keyboard modifiers (ctrl/alt)
+     */
     isBindingEnabled: boolean;
-    startBoundElement: NonDeleted<ExcalidrawBindableElement> | null;
-    suggestedBinding: NonDeleted<ExcalidrawBindableElement> | null;
+    /** user box selection preference; defaults to "contain" when unset */
+    boxSelectionMode: BoxSelectionMode;
+    /** user arrow binding preference */
+    bindingPreference: "enabled" | "disabled";
+    /** user preference whether arrow snap to midpoints while binding */
+    isMidpointSnappingEnabled: boolean;
+    /**
+     * The bindable element the UI highlights for the user when an arrow is
+     * dragged or otherwise its endpoint being close to said element.
+     */
+    suggestedBinding: {
+        element: NonDeleted<ExcalidrawBindableElement>;
+        midPoint?: GlobalPoint;
+    } | null;
     frameToHighlight: NonDeleted<ExcalidrawFrameLikeElement> | null;
     frameRendering: {
         enabled: boolean;
@@ -216,7 +273,7 @@ export interface AppState {
     /**
      * set when a new text is created or when an existing text is being edited
      */
-    editingTextElement: NonDeletedExcalidrawElement | null;
+    editingTextElement: ExcalidrawTextElement | null;
     activeTool: {
         /**
          * indicates a previous tool we should revert back to if we deselect the
@@ -239,9 +296,10 @@ export interface AppState {
     currentItemStrokeColor: string;
     currentItemBackgroundColor: string;
     currentItemFillStyle: ExcalidrawElement["fillStyle"];
-    currentItemStrokeWidth: number;
+    currentItemStrokeWidthKey: StrokeWidthKey;
     currentItemStrokeStyle: ExcalidrawElement["strokeStyle"];
     currentItemRoughness: number;
+    currentItemStrokeVariability: StrokeVariability;
     currentItemOpacity: number;
     currentItemFontFamily: FontFamilyValues;
     currentItemFontSize: number;
@@ -254,6 +312,7 @@ export interface AppState {
     viewBackgroundColor: string;
     scrollX: number;
     scrollY: number;
+    scrollConstraints: ScrollConstraints | null;
     cursorButton: "up" | "down";
     scrolledOutside: boolean;
     name: string | null;
@@ -278,6 +337,10 @@ export interface AppState {
     } | {
         name: "elementLinkSelector";
         sourceElementId: ExcalidrawElement["id"];
+    } | {
+        name: "charts";
+        data: Spreadsheet;
+        rawText: string;
     };
     /**
      * Reflects user preference for whether the default sidebar should be docked.
@@ -300,7 +363,7 @@ export interface AppState {
     selectedElementsAreBeingDragged: boolean;
     shouldCacheIgnoreZoom: boolean;
     toast: {
-        message: string;
+        message: React.ReactNode;
         closable?: boolean;
         duration?: number;
     } | null;
@@ -322,21 +385,13 @@ export interface AppState {
     height: number;
     offsetTop: number;
     offsetLeft: number;
-    fileHandle: FileSystemHandle | null;
+    fileHandle: FileSystemFileHandle | null;
     collaborators: Map<SocketId, Collaborator>;
     stats: {
         open: boolean;
         /** bitmap. Use `STATS_PANELS` bit values */
         panels: number;
     };
-    currentChartType: ChartType;
-    pasteDialog: {
-        shown: false;
-        data: null;
-    } | {
-        shown: true;
-        data: Spreadsheet;
-    };
     showHyperlinkPopup: false | "info" | "editor";
     selectedLinearElement: LinearElementEditor | null;
     snapLines: readonly SnapLine[];
@@ -375,7 +430,7 @@ export type SearchMatch = {
         showOnCanvas: boolean;
     }[];
 };
-export type UIAppState = Omit<AppState, "startBoundElement" | "cursorButton" | "scrollX" | "scrollY">;
+export type UIAppState = Omit<AppState, "cursorButton" | "scrollX" | "scrollY">;
 export type NormalizedZoomValue = number & {
     _brand: "normalizedZoom";
 };
@@ -419,15 +474,45 @@ export type LibraryItemsSource = ((currentLibraryItems: LibraryItems) => MaybePr
 export type ExcalidrawInitialDataState = Merge<ImportedDataState, {
     libraryItems?: MaybePromise<Required<ImportedDataState>["libraryItems"]>;
 }>;
+export type ExcalidrawInitialState = {
+    viewport?: Omit<SetViewportOptions, "animation">;
+};
 export type OnUserFollowedPayload = {
     userToFollow: UserToFollow;
     action: "FOLLOW" | "UNFOLLOW";
 };
+export type OnExportProgress = {
+    type: "progress";
+    message?: React.ReactNode;
+    /** 0-1 range */
+    progress?: number;
+};
 export interface ExcalidrawProps {
     onChange?: (elements: readonly OrderedExcalidrawElement[], appState: AppState, files: BinaryFiles) => void;
+    onThemeChange?: (theme: Theme | "system") => void;
+    /**
+     * note: only subscribes if the props.onIncrement is defined on initial render
+     */
     onIncrement?: (event: DurableIncrement | EphemeralIncrement) => void;
     initialData?: (() => MaybePromise<ExcalidrawInitialDataState | null>) | MaybePromise<ExcalidrawInitialDataState | null>;
-    excalidrawAPI?: (api: ExcalidrawImperativeAPI) => void;
+    initialState?: ExcalidrawInitialState;
+    /**
+     * Invoked as soon as the Excalidraw API is available
+     * NOTE editor is not yet mounted, and state is not yet initialized
+     */
+    onExcalidrawAPI?: (api: ExcalidrawImperativeAPI | null) => void;
+    /**
+     * Invoked once the editor root is mounted.
+     */
+    onMount?: (payload: ExcalidrawMountPayload) => void;
+    /**
+     * Invoked when the editor root is unmounted.
+     */
+    onUnmount?: () => void;
+    /**
+     * Invoked once the initial scene is loaded.
+     */
+    onInitialize?: (api: ExcalidrawImperativeAPI) => void;
     isCollaborating?: boolean;
     onPointerUpdate?: (payload: {
         pointer: {
@@ -465,6 +550,10 @@ export interface ExcalidrawProps {
     name?: string;
     renderCustomStats?: (elements: readonly NonDeletedExcalidrawElement[], appState: UIAppState) => JSX.Element;
     UIOptions?: Partial<UIOptions>;
+    /**
+     * dimensions and size constraints for inserted images
+     */
+    imageOptions?: ImageOptions;
     detectScroll?: boolean;
     handleKeyboardGlobally?: boolean;
     onLibraryChange?: (libraryItems: LibraryItems) => void | Promise<any>;
@@ -484,6 +573,29 @@ export interface ExcalidrawProps {
     aiEnabled?: boolean;
     showDeprecatedFonts?: boolean;
     renderScrollbars?: boolean;
+    /**
+     * Called before exporting to a file.
+     *
+     * Allows the host app to intercept and delay saving until async operations
+     * (e.g., images are loaded) complete.
+     *
+     * If Promise/AsyncGenerator is returned, a progress toast will be shown
+     * until the operation completes. Generator can yield progress updates.
+     */
+    onExport?: (
+    /** type of export. Currently we only call for JSON exports or
+     * JSON-embedded PNG (which is also identified as `json` type here)*/
+    type: "json", data: {
+        elements: readonly ExcalidrawElement[];
+        appState: AppState;
+        files: BinaryFiles;
+    }, options: {
+        /** signal that gets aborted if user cancels the export (e.g. closes
+         * the native file picker dialog). In that case, you can either
+         * return immediately, or throw AbortError.
+         */
+        signal: AbortSignal;
+    }) => MaybePromise<void> | AsyncGenerator<OnExportProgress, void>;
 }
 export type SceneData = {
     elements?: ImportedDataState["elements"];
@@ -496,12 +608,21 @@ export type ExportOpts = {
     onExportToBackend?: (exportedElements: readonly NonDeletedExcalidrawElement[], appState: UIAppState, files: BinaryFiles) => void;
     renderCustomUI?: (exportedElements: readonly NonDeletedExcalidrawElement[], appState: UIAppState, files: BinaryFiles, canvas: HTMLCanvasElement) => JSX.Element;
 };
+export type ImageOptions = Partial<{
+    maxWidthOrHeight: number;
+    maxFileSizeBytes: number;
+}>;
 export type CanvasActions = Partial<{
     changeViewBackgroundColor: boolean;
     clearCanvas: boolean;
     export: false | ExportOpts;
     loadScene: boolean;
     saveToActiveFile: boolean;
+    /**
+     * defaults to true if `props.theme` is omitted or `props.onThemeChange`
+     * is supplied (at which point the theme is considered as host-app controlled),
+     * else default to false
+     * */
     toggleTheme: boolean | null;
     saveAsImage: boolean;
 }>;
@@ -515,8 +636,7 @@ export type UIOptions = Partial<{
      * Optionally control the editor form factor and desktop UI mode from the host app.
      * If not provided, we will take care of it internally.
      */
-    formFactor?: EditorInterface["formFactor"];
-    desktopUIMode?: EditorInterface["desktopUIMode"];
+    getFormFactor?: (editorWidth: number, editorHeight: number) => EditorInterface["formFactor"];
     /** @deprecated does nothing. Will be removed in 0.15 */
     welcomeScreen?: boolean;
 }>;
@@ -526,6 +646,7 @@ export type AppProps = Merge<ExcalidrawProps, {
             export: ExportOpts;
         };
     }>;
+    imageOptions: Required<ImageOptions>;
     detectScroll: boolean;
     handleKeyboardGlobally: boolean;
     isCollaborating: boolean;
@@ -537,6 +658,8 @@ export type AppProps = Merge<ExcalidrawProps, {
 export type AppClassProperties = {
     props: AppProps;
     state: AppState;
+    api: App["api"];
+    sessionExportThemeOverride: App["sessionExportThemeOverride"];
     interactiveCanvas: HTMLCanvasElement | null;
     /** static canvas */
     canvas: HTMLCanvasElement;
@@ -556,7 +679,7 @@ export type AppClassProperties = {
     onInsertElements: App["onInsertElements"];
     onExportImage: App["onExportImage"];
     lastViewportPosition: App["lastViewportPosition"];
-    scrollToContent: App["scrollToContent"];
+    setViewport: App["setViewport"];
     addFiles: App["addFiles"];
     addElementsFromPasteOrLibrary: App["addElementsFromPasteOrLibrary"];
     togglePenMode: App["togglePenMode"];
@@ -571,13 +694,17 @@ export type AppClassProperties = {
     getEffectiveGridSize: App["getEffectiveGridSize"];
     setPlugins: App["setPlugins"];
     plugins: App["plugins"];
-    getEditorUIOffsets: App["getEditorUIOffsets"];
+    getViewportOffsets: App["getViewportOffsets"];
     visibleElements: App["visibleElements"];
     excalidrawContainerValue: App["excalidrawContainerValue"];
     onPointerUpEmitter: App["onPointerUpEmitter"];
     updateEditorAtom: App["updateEditorAtom"];
     onPointerDownEmitter: App["onPointerDownEmitter"];
+    onEvent: App["onEvent"];
+    onStateChange: App["onStateChange"];
+    lastPointerMoveCoords: App["lastPointerMoveCoords"];
     bindModeHandler: App["bindModeHandler"];
+    setAppState: App["setAppState"];
 };
 export type PointerDownState = Readonly<{
     origin: Readonly<{
@@ -638,7 +765,18 @@ export type PointerDownState = Readonly<{
     };
 }>;
 export type UnsubscribeCallback = () => void;
+export type ExcalidrawMountPayload = {
+    excalidrawAPI: ExcalidrawImperativeAPI;
+    container: HTMLDivElement | null;
+};
+export type ExcalidrawImperativeAPIEventMap = {
+    "editor:mount": [payload: ExcalidrawMountPayload];
+    "editor:initialize": [api: ExcalidrawImperativeAPI];
+    "editor:unmount": [];
+};
 export interface ExcalidrawImperativeAPI {
+    /** Whether the editor has been unmounted and the API is no longer usable. */
+    isDestroyed: boolean;
     updateScene: InstanceType<typeof App>["updateScene"];
     applyDeltas: InstanceType<typeof App>["applyDeltas"];
     mutateElement: InstanceType<typeof App>["mutateElement"];
@@ -653,7 +791,8 @@ export interface ExcalidrawImperativeAPI {
     getAppState: () => InstanceType<typeof App>["state"];
     getFiles: () => InstanceType<typeof App>["files"];
     getName: InstanceType<typeof App>["getName"];
-    scrollToContent: InstanceType<typeof App>["scrollToContent"];
+    setViewport: InstanceType<typeof App>["setViewport"];
+    getViewportOffsets: InstanceType<typeof App>["getViewportOffsets"];
     registerAction: (action: Action) => void;
     refresh: InstanceType<typeof App>["refresh"];
     setToast: InstanceType<typeof App>["setToast"];
@@ -676,6 +815,8 @@ export interface ExcalidrawImperativeAPI {
     onPointerUp: (callback: (activeTool: AppState["activeTool"], pointerDownState: PointerDownState, event: PointerEvent) => void) => UnsubscribeCallback;
     onScrollChange: (callback: (scrollX: number, scrollY: number, zoom: Zoom) => void) => UnsubscribeCallback;
     onUserFollow: (callback: (payload: OnUserFollowedPayload) => void) => UnsubscribeCallback;
+    onStateChange: InstanceType<typeof App>["onStateChange"];
+    onEvent: InstanceType<typeof App>["onEvent"];
 }
 export type FrameNameBounds = {
     x: number;
@@ -716,4 +857,102 @@ export type Offsets = Partial<{
     bottom: number;
     left: number;
 }>;
-export {};
+/**
+ * Value of the `data-viewport-ui` attribute, marking a DOM node as a UI
+ * surface that occludes the canvas. Such nodes are measured by
+ * `getViewportOffsets` to compute the default per-side viewport offsets:
+ *
+ * - `top` / `bottom` — offsets that side by the node's bottom/top edge
+ * - `side` — a panel hugging the left or right edge. Which side is not
+ *   declared but resolved geometrically: if the node's horizontal center
+ *   lies in the left half of the viewport it counts against the left
+ *   offset (by its right edge), otherwise against the right offset (by
+ *   `viewportWidth - left edge`). Measuring the rendered position instead
+ *   of declaring a side means RTL layouts and host-configurable docking
+ *   (e.g. sidebar side) are handled for free — but it assumes the surface
+ *   actually hugs one edge; don't mark a centered/near-full-width node as
+ *   `side` (its midpoint would classify it to one side and the offset
+ *   would swallow most of the viewport).
+ *
+ * The attribute should only be present while the surface is actually
+ * rendered — omit it (don't just hide the node) when the surface shouldn't
+ * push the viewport around.
+ */
+export type ViewportUIDock = "top" | "bottom" | "side";
+/**
+ * Options for `getViewportOffsets` (and the `ui` key of
+ * {@link ViewportOffsets}), controlling how offsets are derived from the
+ * currently rendered editor UI.
+ *
+ * NOTE unlike the physical sides of {@link Offsets}, the horizontal values
+ * here are logical, i.e. flipped in RTL layouts (`left` refers to the
+ * reading-direction start side).
+ */
+export type ViewportOffsetsOptions = {
+    /** padding added to each measured side (default 24) */
+    padding?: number;
+    paddingTop?: number;
+    paddingRight?: number;
+    paddingBottom?: number;
+    paddingLeft?: number;
+    /** final value for the given side, replacing the measured UI size
+     * (padding is not added on top) */
+    top?: number;
+    bottom?: number;
+    left?: number;
+    right?: number;
+    /**
+     * Reserve space for the given conditionally-rendered surfaces even while
+     * they're hidden, so the resulting offsets don't shift when they
+     * (dis)appear. Uses the surface's last-measured footprint, falling back
+     * to an approximate default if it hasn't been rendered yet. Ignored on
+     * phones (where these surfaces never occlude the canvas).
+     */
+    reserve?: {
+        /** styles panel (rendered when a tool or selection is active) */
+        stylesPanel?: boolean;
+        /** sidebar (e.g. library) */
+        sidebar?: boolean;
+    };
+};
+/**
+ * Viewport offsets accepted by the `setViewport`-family APIs (`setViewport`,
+ * `props.initialState.viewport`), insetting the usable viewport area per
+ * side so the target isn't fitted/centered underneath overlaid UI.
+ *
+ * Two (combinable) ways to specify:
+ *
+ * - **Static sides** (`top`/`right`/`bottom`/`left`) — absolute pixel
+ *   values, used as-is: physical (not flipped in RTL), zoom-independent,
+ *   no padding added. Sides not specified default to `0` (unless `ui` is
+ *   set, see below).
+ *
+ * - **`ui`** — derive the offsets from the editor UI (toolbar, styles
+ *   panel, sidebar...) as rendered at the time the viewport is set,
+ *   equivalent to calling `getViewportOffsets()`. Pass `true` for the
+ *   defaults, or options ({@link ViewportOffsetsOptions}) to customize
+ *   padding or reserve space for currently-hidden surfaces.
+ *
+ * When both are given, a static side always wins for that side — it
+ * replaces whatever `ui` would yield (including `ui`'s own side overrides,
+ * which — unlike the physical static sides — are RTL-relative). The
+ * remaining sides fall back to the `ui`-derived values.
+ *
+ * @example
+ * { top: 40 }                              // top 40px, other sides 0
+ * { ui: true }                             // measured UI + default padding
+ * { ui: { reserve: { stylesPanel: true } } } // + keep space for hidden panel
+ * { top: 40, ui: true }                    // top exactly 40px, rest from UI
+ */
+export type ViewportOffsets = Offsets & {
+    ui?: true | ViewportOffsetsOptions;
+};
+/**
+ * Value of the `data-viewport-ui-name` attribute, identifying a
+ * conditionally-rendered surface (marked with `data-viewport-ui`) so that
+ * `getViewportOffsets` can reserve space for it while it's hidden (see the
+ * `reserve` option). Whenever a named surface is rendered, its measured
+ * footprint is remembered; reserving uses that remembered footprint, or an
+ * approximate default if the surface hasn't been rendered yet.
+ */
+export type ViewportUIName = "sidebar" | "stylesPanel";