@excalidraw/common 0.18.0-4ce38fb → 0.18.0-4ce8305

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

@@ -1,12 +1,28 @@
 import type { UserIdleState, EditorInterface } from "@excalidraw/common";
-import type { ExcalidrawElement, NonDeletedElementsMap, NonDeletedExcalidrawElement, NonDeletedSceneElementsMap } from "@excalidraw/element/types";
+import type { ExcalidrawElement, ExcalidrawFrameLikeElement, NonDeletedElementsMap, NonDeletedExcalidrawElement, NonDeletedSceneElementsMap } from "@excalidraw/element/types";
 import type { MakeBrand } from "@excalidraw/common/utility-types";
+import type { RenderEnvironment } from "@excalidraw/element/renderEnvironment";
 import type { AppClassProperties, AppState, EmbedsValidationStatus, ElementRenderOverrides, ElementsPendingErasure, InteractiveCanvasAppState, StaticCanvasAppState, SocketId, PendingExcalidrawElements } from "../types";
 import type { RoughCanvas } from "roughjs/bin/canvas";
 import type { Drawable } from "roughjs/bin/core";
 export type RenderableElementsMap = NonDeletedElementsMap & MakeBrand<"RenderableElementsMap">;
 export type StaticCanvasRenderConfig = {
     canvasBackgroundColor: AppState["viewBackgroundColor"];
+    /**
+     * Backing-store scale the target canvas was bootstrapped with -- the owner
+     * window's devicePixelRatio when rendering into the editor, exportScale when
+     * exporting. Element caches are built and blitted at this ratio, so it must
+     * be the same value passed as `StaticSceneRenderConfig["scale"]`.
+     */
+    scale: number;
+    /**
+     * Host environment that creates the canvases and images this render
+     * rasterizes (per-editor owner window in the app; the export's
+     * `config.environment` when exporting). Defaults to the browser's.
+     */
+    renderEnvironment?: RenderEnvironment;
+    /** export only: clips everything drawn to this frame (square corners) */
+    clipToFrame?: ExcalidrawFrameLikeElement | null;
     imageCache: AppClassProperties["imageCache"];
     renderGrid: boolean;
     /** whether to render link icons on elements with links (never rendered
@@ -22,6 +38,12 @@ export type StaticCanvasRenderConfig = {
     elementRenderOverrides?: ElementRenderOverrides;
 };
 export type SVGRenderConfig = {
+    /**
+     * Host environment used for the text measurements this render needs (the
+     * SVG itself is built through `exportToSvg`'s owner document). Defaults to
+     * the browser's.
+     */
+    renderEnvironment?: RenderEnvironment;
     offsetX: number;
     offsetY: number;
     isExporting: boolean;

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

@@ -3,7 +3,7 @@ import type { LinearElementEditor } from "@excalidraw/element";
 import type { ListMarkerAdvance, MaybeTransformHandleType } from "@excalidraw/element";
 import type { PointerType, ExcalidrawLinearElement, NonDeletedExcalidrawElement, NonDeleted, TextAlign, ExcalidrawElement, GroupId, ExcalidrawBindableElement, ExcalidrawArrowElement, 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, OnDuplicateData } from "@excalidraw/element";
+import type { CaptureUpdateActionType, DurableIncrement, EphemeralIncrement, RenderEnvironment, OnDuplicateData } from "@excalidraw/element";
 import type { GlobalPoint } from "@excalidraw/math";
 import type { Action } from "./actions/types";
 import type { Spreadsheet } from "./charts";
@@ -692,6 +692,30 @@ export interface ExcalidrawProps {
      * @default document
      */
     ownerDocument?: Document;
+    /**
+     * Host environment used by the renderer and export pipeline to create
+     * canvases and images. Supply a custom implementation to redirect canvas
+     * creation and image decoding to e.g. a host canvas pool, an
+     * `OffscreenCanvas`, or a non-DOM image decoder. When omitted, canvas and
+     * image creation fall back to `ownerDocument` / `ownerWindow`.
+     *
+     * The value must be referentially stable -- every render cache (element
+     * canvases, text metrics, char widths, link icons) is keyed by this
+     * object's identity, so a new identity is a full cache miss. Passing an
+     * inline object literal mints a fresh identity on every React render,
+     * which silently re-rasterizes every element on every frame; hoist it to a
+     * module constant or memoize it (e.g. `useMemo`) instead.
+     *
+     * Only `createCanvas` and `createImage` are required. `createPath` (used to
+     * fill freedraw strokes) falls back to the global `Path2D`, which every
+     * browser has -- a non-browser host without one must supply it. Pass
+     * `document` (the owner document) for SVG exports to be built in it rather
+     * than in the global `document`, and `textMetrics` to measure the editor's
+     * text with your own provider.
+     *
+     * @default { createCanvas: () => ownerDocument.createElement("canvas"), createImage: () => new ownerWindow.Image(), createPath: (d) => new ownerWindow.Path2D(d), document: ownerDocument }
+     */
+    renderEnvironment?: RenderEnvironment;
     onChange?: (elements: readonly OrderedExcalidrawElement[], appState: AppState, files: BinaryFiles) => void;
     onThemeChange?: (theme: Theme | "system") => void;
     /**
@@ -960,6 +984,7 @@ export type AppClassProperties = {
     state: AppState;
     readonly ownerDocument: Document;
     readonly ownerWindow: Window & typeof globalThis;
+    renderEnvironment: RenderEnvironment;
     api: App["api"];
     sessionExportThemeOverride: App["sessionExportThemeOverride"];
     interactiveCanvas: HTMLCanvasElement | null;
@@ -1000,6 +1025,9 @@ export type AppClassProperties = {
     duplicate: App["duplicate"];
     toolDrag: App["toolDrag"];
     activeResizeHandle: App["activeResizeHandle"];
+    selectionTool: App["selectionTool"];
+    wrap: App["wrap"];
+    modifiers: App["modifiers"];
     isToolLocked: App["isToolLocked"];
     getEffectiveGridSize: App["getEffectiveGridSize"];
     setPlugins: App["setPlugins"];
@@ -1052,6 +1080,7 @@ export type PointerDownState = Readonly<{
         element: NonDeleted<ExcalidrawElement> | null;
         allHitElements: NonDeleted<ExcalidrawElement>[];
         wasAddedToSelection: boolean;
+        cycleTarget: NonDeleted<ExcalidrawElement> | null;
         hasBeenDuplicated: boolean;
         advancedListMarkers: readonly ListMarkerAdvance[];
         editedTextId: ExcalidrawTextElement["id"] | null;
@@ -1069,6 +1098,10 @@ export type PointerDownState = Readonly<{
             x: number;
             y: number;
         };
+        lastOffset: {
+            x: number;
+            y: number;
+        };
         blockDragging: boolean;
     };
     eventListeners: {
@@ -1104,6 +1137,21 @@ export interface ExcalidrawImperativeAPI {
     history: {
         clear: InstanceType<typeof App>["resetHistory"];
     };
+    /**
+     * Selects elements (or their ids — one or many), adds them to or removes
+     * them from the selection, or clears it — as the editor does: an element is
+     * selected with its group (unless `deep`), a frame and its children aren't
+     * selected at the same time, and locked elements are skipped (unless
+     * `includeLocked`). Text editing and cropping end, and the link popup of a
+     * lone selected element shows. Missing and deleted elements are skipped.
+     *
+     * By default the change is recorded for undo along with the next undoable
+     * change — pass `captureUpdate` as for `updateScene()` otherwise. Like
+     * `updateScene()`, it applies on the next render: read it back through
+     * `onChange()` or `getAppState()` after that. Works in view mode too, where
+     * the selection shows without transform handles.
+     */
+    selection: Pick<InstanceType<typeof App>["selection"], "select" | "add" | "remove" | "clear">;
     getSceneElements: InstanceType<typeof App>["getSceneElements"];
     getAppState: () => InstanceType<typeof App>["state"];
     getFiles: () => InstanceType<typeof App>["files"];

package/dist/types/utils/src/index.d.ts

@@ -1,3 +1,5 @@
-export * from "./export";
+export { exportScene, exportToClipboard, MIME_TYPES, } from "@excalidraw/excalidraw/scene/export";
+export type { ExportSceneData, ExportSceneConfig, ExportSceneOptions, } from "@excalidraw/excalidraw/scene/export";
 export { elementsOverlappingBBox } from "@excalidraw/element";
 export { getCommonBounds } from "@excalidraw/element";
+export type { RenderEnvironment } from "@excalidraw/element";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@excalidraw/common",
-  "version": "0.18.0-4ce38fb",
+  "version": "0.18.0-4ce8305",
   "type": "module",
   "types": "./dist/types/common/src/index.d.ts",
   "main": "./dist/prod/index.js",

package/dist/types/utils/src/export.d.ts

@@ -1,36 +0,0 @@
-import { MIME_TYPES } from "@excalidraw/common";
-import type { ExcalidrawFrameLikeElement, NonDeleted, NonDeletedExcalidrawElement } from "@excalidraw/element/types";
-import type { AppState, BinaryFiles } from "@excalidraw/excalidraw/types";
-export { MIME_TYPES };
-type ExportOpts = {
-    /** restored before exporting */
-    elements: readonly NonDeletedExcalidrawElement[];
-    appState?: Partial<Omit<AppState, "offsetTop" | "offsetLeft">>;
-    files: BinaryFiles | null;
-    maxWidthOrHeight?: number;
-    exportingFrame?: NonDeleted<ExcalidrawFrameLikeElement> | null;
-    getDimensions?: (width: number, height: number) => {
-        width: number;
-        height: number;
-        scale?: number;
-    };
-};
-export declare const exportToCanvas: ({ elements, appState, files, maxWidthOrHeight, getDimensions, exportPadding, exportingFrame, }: ExportOpts & {
-    exportPadding?: number;
-}) => Promise<HTMLCanvasElement>;
-export declare const exportToBlob: (opts: ExportOpts & {
-    mimeType?: string;
-    quality?: number;
-    exportPadding?: number;
-}) => Promise<Blob>;
-export declare const exportToSvg: ({ elements, appState, files, exportPadding, renderEmbeddables, exportingFrame, skipInliningFonts, reuseImages, }: Omit<ExportOpts, "getDimensions"> & {
-    exportPadding?: number;
-    renderEmbeddables?: boolean;
-    skipInliningFonts?: true;
-    reuseImages?: boolean;
-}) => Promise<SVGSVGElement>;
-export declare const exportToClipboard: (opts: ExportOpts & {
-    mimeType?: string;
-    quality?: number;
-    type: "png" | "svg" | "json";
-}) => Promise<void>;