@excalidraw/excalidraw 0.18.0-ac0d305 → 0.18.0-b1c6bfc

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-QF5FRM6O.js → chunk-4JOINNOK.js}

@@ -3,6 +3,10 @@ var labels = {
   paste: "Paste",
   pasteAsPlaintext: "Paste as plaintext",
   pasteCharts: "Paste charts",
+  chartType_bar: "Bar chart",
+  chartType_line: "Line chart",
+  chartType_radar: "Radar chart",
+  chartType_plaintext: "Plain text",
   selectAll: "Select all",
   multiSelect: "Add element to selection",
   moveCanvas: "Move canvas",
@@ -49,7 +53,14 @@ var labels = {
   arrowhead_crowfoot_many: "Crow's foot (many)",
   arrowhead_crowfoot_one: "Crow's foot (one)",
   arrowhead_crowfoot_one_or_many: "Crow's foot (one or many)",
+  arrowhead_cardinality_one: "Cardinality (one)",
+  arrowhead_cardinality_many: "Cardinality (many)",
+  arrowhead_cardinality_one_or_many: "Cardinality (one or many)",
+  arrowhead_cardinality_exactly_one: "Cardinality (exactly one)",
+  arrowhead_cardinality_zero_or_one: "Cardinality (zero or one)",
+  arrowhead_cardinality_zero_or_many: "Cardinality (zero or many)",
   more_options: "More options",
+  cardinality: "Cardinality",
   arrowtypes: "Arrow type",
   arrowtype_sharp: "Sharp arrow",
   arrowtype_round: "Curved arrow",
@@ -171,7 +182,14 @@ var labels = {
   linkToElement: "Link to object",
   wrapSelectionInFrame: "Wrap selection in frame",
   tab: "Tab",
-  shapeSwitch: "Switch shape"
+  shapeSwitch: "Switch shape",
+  preferences: "Preferences",
+  preferences_toolLock: "Tool lock",
+  boxSelectionMode: "Select on",
+  boxSelectionContain: "Wrap",
+  boxSelectionOverlap: "Overlap",
+  arrowBinding: "Arrow binding",
+  midpointSnapping: "Snap to midpoints"
 };
 var elementLink = {
   title: "Link to object",
@@ -181,7 +199,13 @@ var elementLink = {
 var library = {
   noItems: "No items added yet...",
   hint_emptyLibrary: "Select an item on canvas to add it here, or install a library from the public repository, below.",
-  hint_emptyPrivateLibrary: "Select an item on canvas to add it here."
+  hint_emptyPrivateLibrary: "Select an item on canvas to add it here.",
+  search: {
+    inputPlaceholder: "Search library",
+    heading: "Library matches",
+    noResults: "No matching items found...",
+    clearSearch: "Clear search"
+  }
 };
 var search = {
   title: "Find on canvas",
@@ -224,10 +248,11 @@ var buttons = {
   objectsSnapMode: "Snap to objects",
   exitZenMode: "Exit zen mode",
   cancel: "Cancel",
+  saveLibNames: "Save name(s) and exit",
   clear: "Clear",
   remove: "Remove",
   embed: "Toggle embedding",
-  publishLibrary: "Publish",
+  publishLibrary: "Rename or publish",
   submit: "Submit",
   confirm: "Confirm",
   embeddableInteractionButton: "Click to interact"
@@ -253,7 +278,8 @@ var alerts = {
   resetLibrary: "This will clear your library. Are you sure?",
   removeItemsFromsLibrary: "Delete {{count}} item(s) from library?",
   invalidEncryptionKey: "Encryption key must be of 22 characters. Live collaboration is disabled.",
-  collabOfflineWarning: "No internet connection available.\nYour changes will not be saved!"
+  collabOfflineWarning: "No internet connection available.\nYour changes will not be saved!",
+  localStorageQuotaExceeded: "Browser storage quota exceeded. Changes will not be saved."
 };
 var errors = {
   unsupportedFileType: "Unsupported file type.",
@@ -329,33 +355,34 @@ var headings = {
   shapes: "Shapes"
 };
 var hints = {
-  dismissSearch: "Escape to dismiss search",
-  canvasPanning: "To move canvas, hold mouse wheel or spacebar while dragging, or use the hand tool",
+  dismissSearch: "{{shortcut}} to dismiss search",
+  canvasPanning: "To move canvas, hold {{shortcut_1}} or {{shortcut_2}} while dragging, or use the hand tool",
   linearElement: "Click to start multiple points, drag for single line",
-  arrowTool: "Click to start multiple points, drag for single line. Press {{arrowShortcut}} again to change arrow type.",
+  arrowTool: "Click to start multiple points, drag for single line. Press {{shortcut}} again to change arrow type.",
+  arrowBindModifiers: "Hold {{shortcut_1}} to disable binding, or {{shortcut_2}} to bind at a fixed point",
   freeDraw: "Click and drag, release when you're finished",
   text: "Tip: you can also add text by double-clicking anywhere with the selection tool",
   embeddable: "Click-drag to create a website embed",
-  text_selected: "Double-click or press ENTER to edit text",
-  text_editing: "Press Escape or CtrlOrCmd+ENTER to finish editing",
-  linearElementMulti: "Click on last point or press Escape or Enter to finish",
-  lockAngle: "You can constrain angle by holding SHIFT",
-  resize: "You can constrain proportions by holding SHIFT while resizing,\nhold ALT to resize from the center",
-  resizeImage: "You can resize freely by holding SHIFT,\nhold ALT to resize from the center",
-  rotate: "You can constrain angles by holding SHIFT while rotating",
-  lineEditor_info: "Hold CtrlOrCmd and Double-click or press CtrlOrCmd + Enter to edit points",
-  lineEditor_line_info: "Double-click or press Enter to edit points",
-  lineEditor_pointSelected: "Press Delete to remove point(s),\nCtrlOrCmd+D to duplicate, or drag to move",
-  lineEditor_nothingSelected: "Select a point to edit (hold SHIFT to select multiple),\nor hold Alt and click to add new points",
+  text_selected: "Double-click or press {{shortcut}} to edit text",
+  text_editing: "Press {{shortcut_1}} or {{shortcut_2}} to finish editing",
+  linearElementMulti: "Click on last point or press {{shortcut_1}} or {{shortcut_2}} to finish",
+  lockAngle: "You can constrain angle by holding {{shortcut}}",
+  resize: "You can constrain proportions by holding {{shortcut_1}} while resizing,\nhold {{shortcut_2}} to resize from the center",
+  resizeImage: "You can resize freely by holding {{shortcut_1}},\nhold {{shortcut_2}} to resize from the center",
+  rotate: "You can constrain angles by holding {{shortcut}} while rotating",
+  lineEditor_info: "Hold {{shortcut_1}} and Double-click or press {{shortcut_2}} to edit points",
+  lineEditor_line_info: "Double-click or press {{shortcut}} to edit points",
+  lineEditor_pointSelected: "Press {{shortcut_1}} to remove point(s),\n{{shortcut_2}} to duplicate, or drag to move",
+  lineEditor_nothingSelected: "Select a point to edit (hold {{shortcut_1}} to select multiple),\nor hold {{shortcut_2}} and click to add new points",
   publishLibrary: "Publish your own library",
-  bindTextToElement: "Press enter to add text",
-  createFlowchart: "Hold CtrlOrCmd and Arrow key to create a flowchart",
-  deepBoxSelect: "Hold CtrlOrCmd to deep select, and to prevent dragging",
-  eraserRevert: "Hold Alt to revert the elements marked for deletion",
+  bindTextToElement: "{{shortcut}} to add text",
+  createFlowchart: "{{shortcut}} to create a flowchart",
+  deepBoxSelect: "Hold {{shortcut}} to deep select, and to prevent dragging",
+  eraserRevert: "Hold {{shortcut}} to revert the elements marked for deletion",
   firefox_clipboard_write: 'This feature can likely be enabled by setting the "dom.events.asyncClipboard.clipboardItem" flag to "true". To change the browser flags in Firefox, visit the "about:config" page.',
-  disableSnapping: "Hold CtrlOrCmd to disable snapping",
-  enterCropEditor: "Double click the image or press ENTER to crop the image",
-  leaveCropEditor: "Click outside the image or press ENTER or ESCAPE to finish cropping"
+  disableSnapping: "Hold {{shortcut}} to disable snapping",
+  enterCropEditor: "Double click the image or press {{shortcut}} to crop the image",
+  leaveCropEditor: "Click outside the image or press {{shortcut_1}} or {{shortcut_2}} to finish cropping"
 };
 var canvasError = {
   cannotShowPreview: "Cannot show preview",
@@ -386,6 +413,10 @@ var roomDialog = {
 var errorDialog = {
   title: "Error"
 };
+var progressDialog = {
+  title: "Saving",
+  defaultMessage: "Preparing to save..."
+};
 var exportDialog = {
   disk_title: "Save to disk",
   disk_details: "Export the scene data to a file from which you can import later.",
@@ -548,7 +579,9 @@ var colors = {
 };
 var welcomeScreen = {
   app: {
-    center_heading: "All your data is saved locally in your browser.",
+    center_heading: "Your drawings are saved in your browser's storage.",
+    center_heading_line2: "Browser storage can be cleared unexpectedly.",
+    center_heading_line3: "Save your work to a file regularly to avoid losing it.",
     center_heading_plus: "Did you want to go to the Excalidraw+ instead?",
     menuHint: "Export, preferences, languages, ..."
   },
@@ -601,9 +634,58 @@ var overwriteConfirm = {
 var mermaid = {
   title: "Mermaid to Excalidraw",
   button: "Insert",
-  description: "Currently only <flowchartLink>Flowchart</flowchartLink>,<sequenceLink> Sequence, </sequenceLink> and <classLink>Class </classLink>Diagrams are supported. The other types will be rendered as image in Excalidraw.",
+  description: "Currently only <flowchartLink>Flowchart</flowchartLink>, <sequenceLink>Sequence</sequenceLink>, <classLink>Class</classLink>, and <erdLink>Entity Relationship</erdLink> Diagrams are supported. The other types will be rendered as image in Excalidraw.",
   syntax: "Mermaid Syntax",
-  preview: "Preview"
+  preview: "Preview",
+  label: "Mermaid",
+  inputPlaceholder: "Write Mermaid diagram defintion here...",
+  autoFixAvailable: "Auto-fix is available"
+};
+var ttd = {
+  error: "Error!"
+};
+var chat = {
+  inputPlaceholder: "Start typing your diagram idea here... ({{shortcut}} for new line)",
+  inputPlaceholderWithMessages: "Continue refining your diagram...",
+  generating: "Generating...",
+  rateLimitRemaining: "{{count}} requests left today",
+  role: {
+    user: "You",
+    assistant: "AI Assistant",
+    system: "System"
+  },
+  aiBeta: "AI Beta",
+  label: "Chat",
+  menu: "Menu",
+  newChat: "New Chat",
+  deleteChat: "Delete chat",
+  deleteMessage: "Delete message",
+  viewAsMermaid: "View as Mermaid",
+  placeholder: {
+    title: "Let's design your diagram",
+    description: "Describe the diagram you want to create, and we'll generate it for you.",
+    hint: "At the moment we know Flowchart, Sequence, Class, State, and Entity Relationship diagrams."
+  },
+  preview: "Preview",
+  insert: "Insert",
+  retry: "Retry",
+  errors: {
+    promptTooShort: "Prompt is too short (min {{min}} characters)",
+    promptTooLong: "Prompt is too long (max {{max}} characters)",
+    generationFailed: "Generation failed",
+    invalidDiagram: "Generated an invalid diagram :(. You may edit manually, retry with auto-fix, or try a different prompt.",
+    fixInMermaid: "Edit Mermaid manually \u2192",
+    aiRepair: "Regenerate (auto-fix) \u2192",
+    requestAborted: "Request aborted",
+    requestFailed: "Request failed",
+    mermaidParseError: "Mermaid syntax error"
+  },
+  rateLimit: {
+    messageLimit: "You've hit your AI limit on the free plan. Try out Excalidraw+ for more or come back tomorrow.",
+    generalRateLimit: "Hold your horses, you're too fast for us! Please wait a moment before trying again.",
+    messageLimitInputPlaceholder: "You've reached your message limit"
+  },
+  upsellBtnLabel: "Upgrade to Plus"
 };
 var quickSearch = {
   placeholder: "Quick search"
@@ -641,6 +723,18 @@ var commandPalette = {
   itemNotAvailable: "Command is not available...",
   shortcutHint: "For Command palette, use {{shortcut}}"
 };
+var keys = {
+  ctrl: "Ctrl",
+  option: "Option",
+  cmd: "Cmd",
+  alt: "Alt",
+  escape: "Esc",
+  enter: "Enter",
+  shift: "Shift",
+  spacebar: "Space",
+  delete: "Delete",
+  mmb: "Scroll wheel"
+};
 var en_default = {
   labels,
   elementLink,
@@ -658,6 +752,7 @@ var en_default = {
   shareDialog,
   roomDialog,
   errorDialog,
+  progressDialog,
   exportDialog,
   helpDialog,
   clearCanvasDialog,
@@ -673,10 +768,13 @@ var en_default = {
   colorPicker,
   overwriteConfirm,
   mermaid,
+  ttd,
+  chat,
   quickSearch,
   fontList,
   userList,
-  commandPalette
+  commandPalette,
+  keys
 };
 
 export {
@@ -696,6 +794,7 @@ export {
   shareDialog,
   roomDialog,
   errorDialog,
+  progressDialog,
   exportDialog,
   helpDialog,
   clearCanvasDialog,
@@ -711,10 +810,13 @@ export {
   colorPicker,
   overwriteConfirm,
   mermaid,
+  ttd,
+  chat,
   quickSearch,
   fontList,
   userList,
   commandPalette,
+  keys,
   en_default
 };
-//# sourceMappingURL=chunk-QF5FRM6O.js.map
+//# sourceMappingURL=chunk-4JOINNOK.js.map