@dwelle/excalidraw 0.4.0-c38ebd4 → 0.4.0-c4ea72b

package/types/scene/export.d.ts

@@ -1,12 +1,13 @@
 import { NonDeletedExcalidrawElement, Theme } from "../element/types";
 import { AppState, BinaryFiles } from "../types";
+import { serializeAsJSON } from "../data/json";
 export declare const SVG_EXPORT_TAG = "<!-- svg-source:excalidraw -->";
-export declare type ExportToCanvasData = {
+export type ExportToCanvasData = {
     elements: readonly NonDeletedExcalidrawElement[];
     appState?: Partial<Omit<AppState, "offsetTop" | "offsetLeft">>;
     files: BinaryFiles | null;
 };
-export declare type ExportToCanvasConfig = {
+export type ExportToCanvasConfig = {
     theme?: Theme;
     /**
      * Canvas background. Valid values are:
@@ -19,10 +20,28 @@ export declare type ExportToCanvasConfig = {
      */
     canvasBackgroundColor?: string | false;
     /**
-     * Canvas padding in pixels. Affected by scale. Ignored if `fit` is set to
-     * `cover`.
+     * Canvas padding in pixels. Affected by `scale`.
      *
-     * @default 10
+     * When `fit` is set to `none`, padding is added to the content bounding box
+     * (including if you set `width` or `height` or `maxWidthOrHeight` or
+     * `widthOrHeight`).
+     *
+     * When `fit` set to `contain`, padding is subtracted from the content
+     * bounding box (ensuring the size doesn't exceed the supplied values, with
+     * the exeception of using alongside `scale` as noted above), and the padding
+     * serves as a minimum distance between the content and the canvas edges, as
+     * it may exceed the supplied padding value from one side or the other in
+     * order to maintain the aspect ratio. It is recommended to set `position`
+     * to `center` when using `fit=contain`.
+     *
+     * When `fit` is set to `cover`, padding is disabled (set to 0).
+     *
+     * When `fit` is set to `none` and either `width` or `height` or
+     * `maxWidthOrHeight` is set, padding is simply adding to the bounding box
+     * and the content may overflow the canvas, thus right or bottom padding
+     * may be ignored.
+     *
+     * @default 0
      */
     padding?: number;
     /**
@@ -33,6 +52,16 @@ export declare type ExportToCanvasConfig = {
      * `scale`.
      */
     maxWidthOrHeight?: number;
+    /**
+     * Scale the canvas content to be excatly this many pixels wide/tall,
+     * maintaining the aspect ratio.
+     *
+     * Cannot be used in conjunction with `maxWidthOrHeight`.
+     *
+     * Final dimensions can get smaller/larger if used in conjunction with
+     * `scale`.
+     */
+    widthOrHeight?: number;
     /**
      * Width of the frame. Supply `x` or `y` if you want to ofsset the canvas
      * content.
@@ -84,12 +113,15 @@ export declare type ExportToCanvasConfig = {
      * Behavior aligns with the `object-fit` CSS property.
      *
      * - `none`    - no scaling.
-     * - `contain` - scale to fit the frame.
+     * - `contain` - scale to fit the frame. Includes `padding`.
      * - `cover`   - scale to fill the frame while maintaining aspect ratio. If
      *               content overflows, it will be cropped.
      *
-     * @default "contain" unless `x` or `y` are specified, in which case "none"
-     * is used (forced).
+     * If `maxWidthOrHeight` or `widthOrHeight` is set, `fit` is ignored.
+     *
+     * @default "contain" unless `width`, `height`, `maxWidthOrHeight`, or
+     * `widthOrHeight` is specified in which case `none` is the default (can be
+     * changed). If `x` or `y` are specified, `none` is forced.
      */
     fit?: "none" | "contain" | "cover";
     /**
@@ -100,9 +132,11 @@ export declare type ExportToCanvasConfig = {
      * - `center` - canvas is centered on the axis which is not specified
      *              (or both).
      *
+     * If `maxWidthOrHeight` or `widthOrHeight` is set, `position` is ignored.
+     *
      * @default "center"
      */
-    position?: "center" | "none";
+    position?: "center" | "topLeft";
     /**
      * A multiplier to increase/decrease the frame dimensions
      * (content resolution).
@@ -150,5 +184,9 @@ export declare const exportToSvg: (elements: readonly NonDeletedExcalidrawElemen
     viewBackgroundColor: string;
     exportWithDarkMode?: boolean;
     exportEmbedScene?: boolean;
-}, files: BinaryFiles | null) => Promise<SVGSVGElement>;
-export declare const getExportSize: (elements: readonly NonDeletedExcalidrawElement[], padding: number, scale: number) => [number, number];
+    renderFrame?: boolean;
+}, files: BinaryFiles | null, opts?: {
+    serializeAsJSON?: () => string;
+    renderEmbeddables?: boolean;
+}) => Promise<SVGSVGElement>;
+export declare const getCanvasSize: (elements: readonly NonDeletedExcalidrawElement[]) => [minX: number, minY: number, width: number, height: number];

package/types/scene/scroll.d.ts

@@ -11,7 +11,7 @@ export declare const centerScrollOn: ({ scenePoint, viewportDimensions, zoom, }:
     scrollX: number;
     scrollY: number;
 };
-export declare const calculateScrollCenter: (elements: readonly ExcalidrawElement[], appState: AppState, canvas: HTMLCanvasElement | null) => {
+export declare const calculateScrollCenter: (elements: readonly ExcalidrawElement[], appState: AppState) => {
     scrollX: number;
     scrollY: number;
 };

package/types/scene/scrollbars.d.ts

@@ -1,14 +1,10 @@
 import { ExcalidrawElement } from "../element/types";
-import { Zoom } from "../types";
+import { InteractiveCanvasAppState } from "../types";
 import { ScrollBars } from "./types";
 export declare const SCROLLBAR_MARGIN = 4;
 export declare const SCROLLBAR_WIDTH = 6;
 export declare const SCROLLBAR_COLOR = "rgba(0,0,0,0.3)";
-export declare const getScrollBars: (elements: readonly ExcalidrawElement[], viewportWidth: number, viewportHeight: number, { scrollX, scrollY, zoom, }: {
-    scrollX: number;
-    scrollY: number;
-    zoom: Zoom;
-}) => ScrollBars;
+export declare const getScrollBars: (elements: readonly ExcalidrawElement[], viewportWidth: number, viewportHeight: number, appState: InteractiveCanvasAppState) => ScrollBars;
 export declare const isOverScrollBars: (scrollBars: ScrollBars, x: number, y: number) => {
     isOverEither: boolean;
     isOverHorizontal: boolean;

package/types/scene/selection.d.ts

@@ -1,11 +1,31 @@
 import { ExcalidrawElement, NonDeletedExcalidrawElement } from "../element/types";
-import { AppState } from "../types";
-export declare const getElementsWithinSelection: (elements: readonly NonDeletedExcalidrawElement[], selection: NonDeletedExcalidrawElement) => NonDeletedExcalidrawElement[];
-export declare const isSomeElementSelected: (elements: readonly NonDeletedExcalidrawElement[], appState: AppState) => boolean;
+import { AppState, InteractiveCanvasAppState } from "../types";
+/**
+ * Frames and their containing elements are not to be selected at the same time.
+ * Given an array of selected elements, if there are frames and their containing elements
+ * we only keep the frames.
+ * @param selectedElements
+ */
+export declare const excludeElementsInFramesFromSelection: <T extends ExcalidrawElement>(selectedElements: readonly T[]) => T[];
+export declare const getElementsWithinSelection: (elements: readonly NonDeletedExcalidrawElement[], selection: NonDeletedExcalidrawElement, excludeElementsInFrames?: boolean) => NonDeletedExcalidrawElement[];
+export declare const isSomeElementSelected: {
+    (elements: readonly NonDeletedExcalidrawElement[], appState: Pick<AppState, "selectedElementIds">): boolean;
+    clearCache(): void;
+};
 /**
  * Returns common attribute (picked by `getAttribute` callback) of selected
  *  elements. If elements don't share the same value, returns `null`.
  */
-export declare const getCommonAttributeOfSelectedElements: <T>(elements: readonly NonDeletedExcalidrawElement[], appState: AppState, getAttribute: (element: ExcalidrawElement) => T) => T | null;
-export declare const getSelectedElements: (elements: readonly NonDeletedExcalidrawElement[], appState: AppState, includeBoundTextElement?: boolean) => NonDeletedExcalidrawElement[];
-export declare const getTargetElements: (elements: readonly NonDeletedExcalidrawElement[], appState: AppState) => NonDeletedExcalidrawElement[];
+export declare const getCommonAttributeOfSelectedElements: <T>(elements: readonly NonDeletedExcalidrawElement[], appState: Pick<AppState, "selectedElementIds">, getAttribute: (element: ExcalidrawElement) => T) => T | null;
+export declare const getSelectedElements: (elements: readonly NonDeletedExcalidrawElement[], appState: Pick<InteractiveCanvasAppState, "selectedElementIds">, opts?: {
+    includeBoundTextElement?: boolean;
+    includeElementsInFrames?: boolean;
+}) => ExcalidrawElement[];
+export declare const getTargetElements: (elements: readonly NonDeletedExcalidrawElement[], appState: Pick<AppState, "selectedElementIds" | "editingElement">) => ExcalidrawElement[];
+/**
+ * returns prevState's selectedElementids if no change from previous, so as to
+ * retain reference identity for memoization
+ */
+export declare const makeNextSelectedElementIds: (nextSelectedElementIds: AppState["selectedElementIds"], prevState: Pick<AppState, "selectedElementIds">) => Readonly<{
+    [id: string]: true;
+}>;

package/types/scene/types.d.ts

@@ -1,57 +1,79 @@
-import { ExcalidrawTextElement } from "../element/types";
-import { AppClassProperties, AppState } from "../types";
-export declare type RenderConfig = {
-    scrollX: AppState["scrollX"];
-    scrollY: AppState["scrollY"];
+import type { RoughCanvas } from "roughjs/bin/canvas";
+import { Drawable } from "roughjs/bin/core";
+import { ExcalidrawTextElement, NonDeletedExcalidrawElement } from "../element/types";
+import { AppClassProperties, InteractiveCanvasAppState, StaticCanvasAppState } from "../types";
+export type RenderConfig = {};
+export type StaticCanvasRenderConfig = {
+    imageCache: AppClassProperties["imageCache"];
+    renderGrid: boolean;
+    /** when exporting the behavior is slightly different (e.g. we can't use
+     CSS filters), and we disable render optimizations for best output */
+    isExporting: boolean;
     /** null indicates transparent bg */
-    canvasBackgroundColor: AppState["viewBackgroundColor"] | null;
-    zoom: AppState["zoom"];
-    shouldCacheIgnoreZoom: AppState["shouldCacheIgnoreZoom"];
-    theme: AppState["theme"];
-    /**
-     * canvas scale factor. Not related to zoom. In browsers, it's the
-     * devicePixelRatio. For export, it's the `appState.exportScale`
-     * (user setting) or whatever scale you want to use when exporting elsewhere.
-     *
-     * Bigger the scale, the more pixels (=quality).
-     */
-    canvasScale: number;
+    canvasBackgroundColor: string | null;
+};
+export type InteractiveCanvasRenderConfig = {
+    remoteSelectedElementIds: {
+        [elementId: string]: string[];
+    };
     remotePointerViewportCoords: {
         [id: string]: {
             x: number;
             y: number;
         };
     };
-    remotePointerButton?: {
-        [id: string]: string | undefined;
-    };
-    remoteSelectedElementIds: {
-        [elementId: string]: string[];
+    remotePointerUserStates: {
+        [id: string]: string;
     };
     remotePointerUsernames: {
         [id: string]: string;
     };
-    remotePointerUserStates: {
-        [id: string]: string;
+    remotePointerButton?: {
+        [id: string]: string | undefined;
     };
-    imageCache: AppClassProperties["imageCache"];
-    renderScrollbars?: boolean;
-    renderSelection?: boolean;
-    renderGrid?: boolean;
-    /** when exporting the behavior is slightly different (e.g. we can't use
-      CSS filters), and we disable render optimizations for best output */
-    isExporting: boolean;
     selectionColor?: string;
+    renderScrollbars?: boolean;
+};
+export type RenderInteractiveSceneCallback = {
+    atLeastOneVisibleElement: boolean;
+    elements: readonly NonDeletedExcalidrawElement[];
+    scrollBars?: ScrollBars;
 };
-export declare type SceneScroll = {
+export type StaticSceneRenderConfig = {
+    canvas: HTMLCanvasElement;
+    rc: RoughCanvas;
+    elements: readonly NonDeletedExcalidrawElement[];
+    visibleElements: readonly NonDeletedExcalidrawElement[];
+    /**
+     * canvas scale factor. Not related to zoom. In browsers, it's the
+     * devicePixelRatio. For export, it's the `appState.exportScale`
+     * (user setting) or whatever scale you want to use when exporting elsewhere.
+     *
+     * Bigger the scale, the more pixels (=quality).
+     */
+    scale: number;
+    appState: StaticCanvasAppState;
+    renderConfig: StaticCanvasRenderConfig;
+};
+export type InteractiveSceneRenderConfig = {
+    canvas: HTMLCanvasElement | null;
+    elements: readonly NonDeletedExcalidrawElement[];
+    visibleElements: readonly NonDeletedExcalidrawElement[];
+    selectedElements: readonly NonDeletedExcalidrawElement[];
+    scale: number;
+    appState: InteractiveCanvasAppState;
+    renderConfig: InteractiveCanvasRenderConfig;
+    callback: (data: RenderInteractiveSceneCallback) => void;
+};
+export type SceneScroll = {
     scrollX: number;
     scrollY: number;
 };
 export interface Scene {
     elements: ExcalidrawTextElement[];
 }
-export declare type ExportType = "png" | "clipboard" | "clipboard-svg" | "backend" | "svg";
-export declare type ScrollBars = {
+export type ExportType = "png" | "clipboard" | "clipboard-svg" | "backend" | "svg";
+export type ScrollBars = {
     horizontal: {
         x: number;
         y: number;
@@ -65,3 +87,16 @@ export declare type ScrollBars = {
         height: number;
     } | null;
 };
+export type ElementShape = Drawable | Drawable[] | null;
+export type ElementShapes = {
+    rectangle: Drawable;
+    ellipse: Drawable;
+    diamond: Drawable;
+    embeddable: Drawable;
+    freedraw: Drawable | null;
+    arrow: Drawable[];
+    line: Drawable[];
+    text: null;
+    image: null;
+    frame: null;
+};