@excalidraw/excalidraw 0.18.0-7ea3229 → 0.18.0-816c81c

package/CHANGELOG.md

@@ -11,6 +11,87 @@ The change should be grouped under one of the below section and must contain PR
 Please add the latest change on the top under the correct section.
 -->
 
+## Unreleased
+
+## Excalidraw API
+
+### Breaking changes
+
+- Renamed the `excalidrawAPI` prop to `onExcalidrawAPI`.
+  - `onExcalidrawAPI` is now called on mount (instead of during constructor), and later on unmount (with `null` value). The API may be removed altogether in the future (you can use `onMount` & `onUmount` to manage the `ExcalidrawAPI` object (e.g. to cache it to a global state), already).
+
+### Features
+
+- Added `ExcalidrawAPI.isDestroyed` flag. Set to `true` once the editor unmounts. Calling any `get*` method, `onStateChange`, or `onEvent` on a destroyed API instance will throw in development and `console.error` in production. The `ExcalidrawAPI` will be reset to `null` on umount, but to be extra safe, you should check `ExcalidrawAPI.isDestroyed` before calling these methods to guard against subtle race conditions in your code.
+
+- Added `onMount`, `onInitialize`, and `onUnmount` props. `onMount` receives `{ excalidrawAPI, container }` once the editor root is mounted. `onInitialize` fires once the initial scene has loaded. `onUnmount` fires just before unmounting.
+
+- Same events are also accessible imperatively through `api.onEvent(...)`.
+
+  ```tsx
+  <Excalidraw
+    onExcalidrawAPI={(api) => {
+      api.onEvent("editor:mount", ({ excalidrawAPI, container }) => {
+        console.log(container);
+      });
+
+      api.onEvent("editor:initialize").then((readyApi) => {
+        readyApi.scrollToContent();
+      });
+    }}
+  />
+  ```
+
+  Note that in future releases, most, if not all, `excalidrawAPI.on*` subscriptions will be removed in favor of `excalidrawAPI.onEvent(name)`.
+
+- Also added `"editor:unmount"` lifecycle event, only accessible via `api.onEvent("editor:unmount")`.
+
+- Exported `<ExcalidrawAPIProvider/>`, `useExcalidrawAPI()`, `useAppStateValue(prop | props | selectorFunction)`, and `useOnExcalidrawStateChange(prop | props | selectorFunction, callback)` from the package. The imperative API also now exposes `onStateChange(prop | props | selectorFunction, callback?)`, and `onEvent(name, callback)`.
+
+  ```tsx
+  <ExcalidrawAPIProvider>
+    <Excalidraw />
+    <Logger />
+  </ExcalidrawAPIProvider>;
+
+  function Logger() {
+    // initially null before the ExcalidrawAPIProvider initializes ater
+    // <Excalidraw/> renders
+    // When <Excalidraw/> unmounts, is reset back to null
+    const api = useExcalidrawAPI();
+
+    useAppStateValue("viewModeEnabled", (viewModeEnabled) => {
+      console.log("view mode changed:", viewModeEnabled);
+    });
+
+    React.useEffect(() => {
+      if (api) {
+        console.log("editor instance id:", api.id);
+      }
+    }, [api]);
+
+    return null;
+  }
+  ```
+
+- Added `onExport` so host apps can delay JSON export until async work completes. The handler receives the export data plus an `AbortSignal`, and may return a `Promise` or an async generator that yields progress updates for the built-in toast UI.
+
+  ```tsx
+  <Excalidraw
+    onExport={async function* (_type, { files }, { signal }) {
+      yield { type: "progress", message: "Waiting for images..." };
+
+      await waitForImagesToLoad(files, signal);
+
+      if (signal.aborted) {
+        return;
+      }
+
+      yield { type: "progress", message: "Export ready", progress: 1 };
+    }}
+  />
+  ```
+
 ## Excalidraw Library
 
 ## 0.18.0 (2025-03-11)

package/README.md

@@ -1,10 +1,10 @@
 # Excalidraw
 
-**Excalidraw** is exported as a component to be directly embedded in your project.
+**Excalidraw** is exported as a React component that you can embed directly in your app.
 
 ## Installation
 
-Use `npm` or `yarn` to install the package.
+Install the package together with its React peer dependencies.
 
 ```bash
 npm install react react-dom @excalidraw/excalidraw
@@ -12,34 +12,131 @@ npm install react react-dom @excalidraw/excalidraw
 yarn add react react-dom @excalidraw/excalidraw
 ```
 
-> **Note**: If you don't want to wait for the next stable release and try out the unreleased changes, use `@excalidraw/excalidraw@next`.
+> **Note**: If you want to try unreleased changes, use `@excalidraw/excalidraw@next`.
 
-#### Self-hosting fonts
+## Quick start
 
-By default, Excalidraw will try to download all the used fonts from the [CDN](https://esm.run/@excalidraw/excalidraw/dist/prod).
+The minimum working setup has two easy-to-miss requirements:
 
-For self-hosting purposes, you'll have to copy the content of the folder `node_modules/@excalidraw/excalidraw/dist/prod/fonts` to the path where your assets should be served from (i.e. `public/` directory in your project). In that case, you should also set `window.EXCALIDRAW_ASSET_PATH` to the very same path, i.e. `/` in case it's in the root:
+1. Import the package CSS:
 
-```js
-<script>window.EXCALIDRAW_ASSET_PATH = "/";</script>
+```ts
+import "@excalidraw/excalidraw/index.css";
 ```
 
-### Dimensions of Excalidraw
+2. Render Excalidraw inside a container with a non-zero height.
 
-Excalidraw takes _100%_ of `width` and `height` of the containing block so make sure the container in which you render Excalidraw has non zero dimensions.
+```tsx
+import { Excalidraw } from "@excalidraw/excalidraw";
+import "@excalidraw/excalidraw/index.css";
+
+export default function App() {
+  return (
+    <div style={{ height: "100vh" }}>
+      <Excalidraw />
+    </div>
+  );
+}
+```
+
+Excalidraw fills `100%` of the width and height of its parent. If the parent has no height, the canvas will not be visible.
+
+## Next.js / SSR frameworks
+
+Excalidraw should be rendered on the client. In SSR frameworks such as Next.js, use a client component and load it dynamically with SSR disabled.
+
+```tsx
+// app/components/ExcalidrawClient.tsx
+"use client";
+
+import { Excalidraw } from "@excalidraw/excalidraw";
+import "@excalidraw/excalidraw/index.css";
+
+export default function ExcalidrawClient() {
+  return (
+    <div style={{ height: "100vh" }}>
+      <Excalidraw />
+    </div>
+  );
+}
+```
+
+```tsx
+// app/page.tsx
+import dynamic from "next/dynamic";
+
+const ExcalidrawClient = dynamic(
+  () => import("./components/ExcalidrawClient"),
+  { ssr: false },
+);
+
+export default function Page() {
+  return <ExcalidrawClient />;
+}
+```
+
+See the local examples for complete setups:
+
+- [examples/with-nextjs](https://github.com/excalidraw/excalidraw/tree/master/examples/with-nextjs)
+- [examples/with-script-in-browser](https://github.com/excalidraw/excalidraw/tree/master/examples/with-script-in-browser)
+
+## LLM / agent tips
+
+If an LLM or coding agent is setting up Excalidraw, these shortcuts usually save more time than re-prompting:
+
+- Start with a plain `<Excalidraw />` in a `100vh` container. Add refs, `initialData`, persistence, or custom UI only after the base embed works.
+- If the canvas is blank, check the CSS import and parent height first. Those are the two most common integration failures.
+- In Next.js or other SSR frameworks, assume client-only rendering first. Use `"use client"` and `dynamic(..., { ssr: false })` before debugging hydration or `window is not defined` errors.
+- If imports or entrypoints are unclear, inspect `node_modules/@excalidraw/excalidraw/package.json`. The installed package exports are the source of truth.
+- Do not set `window.EXCALIDRAW_ASSET_PATH` unless you are intentionally self-hosting fonts/assets.
+- When docs and generated code drift, copy the nearest working example from this repo, especially `examples/with-nextjs` or `examples/with-script-in-browser`.
+
+## Migrating to `@excalidraw/excalidraw@0.18.x`
+
+Version `0.18.x` removes the old `types/`-prefixed deep import paths. If you were importing types from `@excalidraw/excalidraw/types/...`, switch to the new type-only subpaths below.
+
+| Old path | New path |
+| --- | --- |
+| `@excalidraw/excalidraw/types/data/transform.js` | `@excalidraw/excalidraw/element/transform` |
+| `@excalidraw/excalidraw/types/data/types.js` | `@excalidraw/excalidraw/data/types` |
+| `@excalidraw/excalidraw/types/element/types.js` | `@excalidraw/excalidraw/element/types` |
+| `@excalidraw/excalidraw/types/utility-types.js` | `@excalidraw/excalidraw/common/utility-types` |
+| `@excalidraw/excalidraw/types/types.js` | `@excalidraw/excalidraw/types` |
+
+Drop the `.js` extension. The new package `exports` map resolves these paths without it.
+
+These deep subpaths are for `import type` only. Runtime imports should come from the package root, plus `@excalidraw/excalidraw/index.css` for styles.
+
+For example:
+
+```ts
+import { exportToSvg } from "@excalidraw/excalidraw";
+```
+
+## Self-hosting fonts
+
+By default, Excalidraw downloads the fonts it needs from the [CDN](https://esm.run/@excalidraw/excalidraw/dist/prod).
+
+For self-hosting, copy the contents of `node_modules/@excalidraw/excalidraw/dist/prod/fonts` into the path where your app serves static assets, for example `public/`. Then set `window.EXCALIDRAW_ASSET_PATH` to that same path:
+
+```html
+<script>
+  window.EXCALIDRAW_ASSET_PATH = "/";
+</script>
+```
 
 ## Demo
 
-Go to [CodeSandbox](https://codesandbox.io/p/sandbox/github/excalidraw/excalidraw/tree/master/examples/with-script-in-browser) example.
+Try the [CodeSandbox example](https://codesandbox.io/p/sandbox/github/excalidraw/excalidraw/tree/master/examples/with-script-in-browser).
 
 ## Integration
 
-Head over to the [docs](https://docs.excalidraw.com/docs/@excalidraw/excalidraw/integration).
+Read the [integration docs](https://docs.excalidraw.com/docs/@excalidraw/excalidraw/integration).
 
 ## API
 
-Head over to the [docs](https://docs.excalidraw.com/docs/@excalidraw/excalidraw/api).
+Read the [API docs](https://docs.excalidraw.com/docs/@excalidraw/excalidraw/api).
 
 ## Contributing
 
-Head over to the [docs](https://docs.excalidraw.com/docs/@excalidraw/excalidraw/contributing).
+Read the [contributing docs](https://docs.excalidraw.com/docs/@excalidraw/excalidraw/contributing).

package/dist/dev/{chunk-FXVS2QTZ.js → chunk-LWYHXCPK.js}

@@ -41,7 +41,6 @@ var getDefaultAppState = () => {
     showWelcomeScreen: false,
     theme: THEME.LIGHT,
     collaborators: /* @__PURE__ */ new Map(),
-    currentChartType: "bar",
     currentItemBackgroundColor: DEFAULT_ELEMENT_PROPS.backgroundColor,
     currentItemEndArrowhead: "arrow",
     currentItemFillStyle: DEFAULT_ELEMENT_PROPS.fillStyle,
@@ -85,6 +84,8 @@ var getDefaultAppState = () => {
     gridStep: DEFAULT_GRID_STEP,
     gridModeEnabled: false,
     isBindingEnabled: true,
+    bindingPreference: "enabled",
+    isMidpointSnappingEnabled: true,
     defaultSidebarDockedPreference: false,
     isLoading: false,
     isResizing: false,
@@ -97,7 +98,6 @@ var getDefaultAppState = () => {
     openPopup: null,
     openSidebar: null,
     openDialog: null,
-    pasteDialog: { shown: false, data: null },
     previousSelectedElementIds: {},
     resizingElement: null,
     scrolledOutside: false,
@@ -148,7 +148,6 @@ var APP_STATE_STORAGE_CONF = /* @__PURE__ */ ((config) => config)({
   showWelcomeScreen: { browser: true, export: false, server: false },
   theme: { browser: true, export: false, server: false },
   collaborators: { browser: false, export: false, server: false },
-  currentChartType: { browser: true, export: false, server: false },
   currentItemBackgroundColor: { browser: true, export: false, server: false },
   currentItemEndArrowhead: { browser: true, export: false, server: false },
   currentItemFillStyle: { browser: true, export: false, server: false },
@@ -191,7 +190,9 @@ var APP_STATE_STORAGE_CONF = /* @__PURE__ */ ((config) => config)({
   gridStep: { browser: true, export: true, server: true },
   gridModeEnabled: { browser: true, export: true, server: true },
   height: { browser: false, export: false, server: false },
-  isBindingEnabled: { browser: false, export: false, server: false },
+  isBindingEnabled: { browser: true, export: false, server: false },
+  bindingPreference: { browser: true, export: false, server: false },
+  isMidpointSnappingEnabled: { browser: true, export: false, server: false },
   defaultSidebarDockedPreference: {
     browser: true,
     export: false,
@@ -210,7 +211,6 @@ var APP_STATE_STORAGE_CONF = /* @__PURE__ */ ((config) => config)({
   openPopup: { browser: false, export: false, server: false },
   openSidebar: { browser: true, export: false, server: false },
   openDialog: { browser: false, export: false, server: false },
-  pasteDialog: { browser: false, export: false, server: false },
   previousSelectedElementIds: { browser: true, export: false, server: false },
   resizingElement: { browser: false, export: false, server: false },
   scrolledOutside: { browser: true, export: false, server: false },
@@ -535,7 +535,6 @@ var decode = (data) => {
 
 // data/json.ts
 import {
-  DEFAULT_FILENAME,
   EXPORT_DATA_TYPES,
   getExportSource,
   MIME_TYPES as MIME_TYPES2,
@@ -548,8 +547,7 @@ import {
   fileSave as _fileSave,
   supported as nativeFileSystemSupported
 } from "browser-fs-access";
-import { EVENT, MIME_TYPES, debounce } from "@excalidraw/common";
-var INPUT_CHANGE_INTERVAL_MS = 5e3;
+import { MIME_TYPES } from "@excalidraw/common";
 var fileOpen = async (opts) => {
   const mimeTypes = opts.extensions?.reduce((mimeTypes2, type) => {
     mimeTypes2.push(MIME_TYPES[type]);
@@ -565,39 +563,7 @@ var fileOpen = async (opts) => {
     description: opts.description,
     extensions,
     mimeTypes,
-    multiple: opts.multiple ?? false,
-    legacySetup: (resolve, reject, input) => {
-      const scheduleRejection = debounce(reject, INPUT_CHANGE_INTERVAL_MS);
-      const focusHandler = () => {
-        checkForFile();
-        document.addEventListener(EVENT.KEYUP, scheduleRejection);
-        document.addEventListener(EVENT.POINTER_UP, scheduleRejection);
-        scheduleRejection();
-      };
-      const checkForFile = () => {
-        if (input.files?.length) {
-          const ret = opts.multiple ? [...input.files] : input.files[0];
-          resolve(ret);
-        }
-      };
-      requestAnimationFrame(() => {
-        window.addEventListener(EVENT.FOCUS, focusHandler);
-      });
-      const interval = window.setInterval(() => {
-        checkForFile();
-      }, INPUT_CHANGE_INTERVAL_MS);
-      return (rejectPromise) => {
-        clearInterval(interval);
-        scheduleRejection.cancel();
-        window.removeEventListener(EVENT.FOCUS, focusHandler);
-        document.removeEventListener(EVENT.KEYUP, scheduleRejection);
-        document.removeEventListener(EVENT.POINTER_UP, scheduleRejection);
-        if (rejectPromise) {
-          console.warn("Opening the file was canceled (legacy-fs).");
-          rejectPromise(new AbortError());
-        }
-      };
-    }
+    multiple: opts.multiple ?? false
   });
   if (Array.isArray(files)) {
     return await Promise.all(
@@ -615,7 +581,8 @@ var fileSave = (blob, opts) => {
       extensions: [`.${opts.extension}`],
       mimeTypes: opts.mimeTypes
     },
-    opts.fileHandle
+    opts.fileHandle,
+    false
   );
 };
 
@@ -643,18 +610,24 @@ var serializeAsJSON = (elements, appState, files, type) => {
   };
   return JSON.stringify(data, null, 2);
 };
-var saveAsJSON = async (elements, appState, files, name = appState.name || DEFAULT_FILENAME) => {
-  const serialized = serializeAsJSON(elements, appState, files, "local");
-  const blob = new Blob([serialized], {
-    type: MIME_TYPES2.excalidraw
+var saveAsJSON = async ({
+  data,
+  filename,
+  fileHandle
+}) => {
+  const blob = Promise.resolve(data).then(({ elements, appState, files }) => {
+    const serialized = serializeAsJSON(elements, appState, files, "local");
+    return new Blob([serialized], {
+      type: MIME_TYPES2.excalidraw
+    });
   });
-  const fileHandle = await fileSave(blob, {
-    name,
+  const savedFileHandle = await fileSave(blob, {
+    name: filename,
     extension: "excalidraw",
     description: "Excalidraw file",
-    fileHandle: isImageFileHandle(appState.fileHandle) ? null : appState.fileHandle
+    fileHandle: isImageFileHandle(fileHandle) ? null : fileHandle
   });
-  return { fileHandle };
+  return { fileHandle: savedFileHandle };
 };
 var loadFromJSON = async (localAppState, localElements) => {
   const file = await fileOpen({
@@ -778,7 +751,7 @@ import { promiseTry as promiseTry2, LOCAL_FONT_PROTOCOL as LOCAL_FONT_PROTOCOL2
 import { isServerEnv, promiseTry } from "@excalidraw/common";
 
 // workers.ts
-import { debounce as debounce2 } from "@excalidraw/common";
+import { debounce } from "@excalidraw/common";
 var IdleWorker = class {
   constructor(workerUrl) {
     __publicField(this, "instance");
@@ -852,7 +825,7 @@ var WorkerPool = class _WorkerPool {
    */
   async createWorker() {
     const worker = new IdleWorker(this.workerUrl);
-    worker.debounceTerminate = debounce2((reject) => {
+    worker.debounceTerminate = debounce((reject) => {
       worker.instance.terminate();
       if (this.idleWorkers.has(worker)) {
         this.idleWorkers.delete(worker);
@@ -3545,8 +3518,7 @@ var _renderStaticScene = ({
 var renderStaticSceneThrottled = throttleRAF(
   (config) => {
     _renderStaticScene(config);
-  },
-  { trailing: true }
+  }
 );
 var renderStaticScene = (renderConfig, throttle) => {
   if (throttle) {
@@ -4508,6 +4480,7 @@ import {
 import {
   calculateFixedPointForNonElbowArrowBinding,
   getNonDeletedElements,
+  normalizeArrowhead,
   isPointInElement,
   isValidPolygon,
   projectFixedPointOntoDiagonal
@@ -4736,7 +4709,8 @@ var restoreElement = (element, targetElementsMap, existingElementsMap, opts) =>
       });
     case "line":
     case "draw":
-      const { startArrowhead = null, endArrowhead = null } = element;
+      const startArrowhead = normalizeArrowhead(element.startArrowhead);
+      const endArrowhead = normalizeArrowhead(element.endArrowhead);
       let x = element.x;
       let y = element.y;
       let points = (
@@ -4761,7 +4735,8 @@ var restoreElement = (element, targetElementsMap, existingElementsMap, opts) =>
         ...getSizeFromPoints(points)
       });
     case "arrow": {
-      const { startArrowhead: startArrowhead2 = null, endArrowhead: endArrowhead2 = "arrow" } = element;
+      const startArrowhead2 = normalizeArrowhead(element.startArrowhead);
+      const endArrowhead2 = element.endArrowhead === void 0 ? "arrow" : normalizeArrowhead(element.endArrowhead);
       const x2 = element.x;
       const y2 = element.y;
       const points2 = (
@@ -5102,7 +5077,7 @@ var parseFileContents = async (blob) => {
   let contents;
   if (blob.type === MIME_TYPES6.png) {
     try {
-      return await (await import("./data/image-X6URJSP5.js")).decodePngMetadata(blob);
+      return await (await import("./data/image-3J4DLBV6.js")).decodePngMetadata(blob);
     } catch (error) {
       if (error.message === "INVALID") {
         throw new ImageSceneDataError(
@@ -5536,4 +5511,4 @@ export {
   createFile,
   normalizeFile
 };
-//# sourceMappingURL=chunk-FXVS2QTZ.js.map
+//# sourceMappingURL=chunk-LWYHXCPK.js.map