diff --git a/src/packages/excalidraw/CHANGELOG.md b/src/packages/excalidraw/CHANGELOG.md index 2047cd41..d8128d2f 100644 --- a/src/packages/excalidraw/CHANGELOG.md +++ b/src/packages/excalidraw/CHANGELOG.md @@ -33,9 +33,7 @@ Please add the latest change on the top under the correct section. - Add `maxWidthOrHeight?: number` attribute. - `scale` returned from `getDimensions()` is now optional (default to `1`). -- Image support. - - NOTE: the unreleased API is highly unstable and may change significantly before the next stable release. As such it's largely undocumented at this point. You are encouraged to read through the [PR](https://github.com/excalidraw/excalidraw/pull/4011) description if you want to know more about the internals. +- Image support added for host [PR](https://github.com/excalidraw/excalidraw/pull/4011) General notes: @@ -55,7 +53,7 @@ Please add the latest change on the top under the correct section. Other notes: - `.excalidraw` files may now contain top-level `files` key in format of `Record` when exporting any (image) elements. - - Changes were made to various export utilityies exported from the package so that they take `files`. For now, TypeScript should help you figure the changes out. + - Changes were made to various export utilities exported from the package so that they take `files`, you can refer to the docs for the same. - Export [`isLinearElement`](https://github.com/excalidraw/excalidraw/blob/master/src/packages/excalidraw/README.md#isLinearElement) and [`getNonDeletedElements`](https://github.com/excalidraw/excalidraw/blob/master/src/packages/excalidraw/README.md#getNonDeletedElements) [#4072](https://github.com/excalidraw/excalidraw/pull/4072). diff --git a/src/packages/excalidraw/README_NEXT.md b/src/packages/excalidraw/README_NEXT.md index bb68306d..91d3c808 100644 --- a/src/packages/excalidraw/README_NEXT.md +++ b/src/packages/excalidraw/README_NEXT.md @@ -399,7 +399,7 @@ For a complete list of variables, check [theme.scss](https://github.com/excalidr | [`theme`](#theme) | [THEME.LIGHT](#THEME-1) | [THEME.LIGHT](#THEME-1) | [THEME.LIGHT](#THEME-1) | The theme of the Excalidraw component | | [`name`](#name) | string | | Name of the drawing | | [`UIOptions`](#UIOptions) | 
{ canvasActions:  CanvasActions }
| [DEFAULT UI OPTIONS](https://github.com/excalidraw/excalidraw/blob/master/src/constants.ts#L129) | To customise UI options. Currently we support customising [`canvas actions`](#canvasActions) | -| [`onPaste`](#onPaste) | 
(data: ClipboardData, event: ClipboardEvent | null) => boolean
| | Callback to be triggered if passed when the something is pasted in to the scene | +| [`onPaste`](#onPaste) | 
(data: ClipboardData, event: ClipboardEvent | null) => boolean
| | Callback to be triggered if passed when the something is pasted in to the scene | | [`detectScroll`](#detectScroll) | boolean | true | Indicates whether to update the offsets when nearest ancestor is scrolled. | | [`handleKeyboardGlobally`](#handleKeyboardGlobally) | boolean | false | Indicates whether to bind the keyboard events to document. | | [`onLibraryChange`](#onLibraryChange) | 
(items: LibraryItems) => void | Promise<any>
| | The callback if supplied is triggered when the library is updated and receives the library items. | @@ -416,12 +416,14 @@ Excalidraw takes `100%` of `width` and `height` of the containing block so make Every time component updates, this callback if passed will get triggered and has the below signature. ```js -(excalidrawElements, appState) => void; +(excalidrawElements, appState, files) => void; ``` 1.`excalidrawElements`: Array of [excalidrawElements](https://github.com/excalidraw/excalidraw/blob/master/src/element/types.ts#L78) in the scene. -2.`appState`: [AppState](https://github.com/excalidraw/excalidraw/blob/master/src/types.ts#L42) of the scene +2.`appState`: [AppState](https://github.com/excalidraw/excalidraw/blob/master/src/types.ts#L42) of the scene. + +3. `files`: The [`BinaryFiles`]([BinaryFiles](https://github.com/excalidraw/excalidraw/blob/master/src/types.ts#L64) which are added to the scene. Here you can try saving the data to your backend or local storage for example. @@ -435,6 +437,7 @@ This helps to load Excalidraw with `initialData`. It must be an object or a [pro | `appState` | [AppState](https://github.com/excalidraw/excalidraw/blob/master/src/types.ts#L42) | The App state with which Excalidraw should be mounted. | | `scrollToContent` | boolean | This attribute implies whether to scroll to the nearest element to center once Excalidraw is mounted. By default, it will not scroll the nearest element to the center. Make sure you pass `initialData.appState.scrollX` and `initialData.appState.scrollY` when `scrollToContent` is false so that scroll positions are retained | | `libraryItems` | [LibraryItems](https://github.com/excalidraw/excalidraw/blob/master/src/types.ts#L151) | This library items with which Excalidraw should be mounted. | +| `files` | [BinaryFiles](https://github.com/excalidraw/excalidraw/blob/master/src/types.ts#L64) | The files added to the scene. | ```json { @@ -487,6 +490,7 @@ You can pass a `ref` when you want to access some excalidraw APIs. We expose the | [importLibrary](#importlibrary) | `(url: string, token?: string) => void` | Imports library from given URL | | setToastMessage | `(message: string) => void` | This API can be used to show the toast with custom message. | | [id](#id) | string | Unique ID for the excalidraw component. | +| [getFiles](#getFiles) | 
() => files
| This API can be used to get the files present in the scene. It may contain files that aren't referenced by any element, so if you're persisting the files to a storage, you should compare them against stored elements. | #### `readyPromise` @@ -516,7 +520,7 @@ You can use this function to update the scene with the sceneData. It accepts the 
(files: BinaryFileData) => void
-Adds supplied files data to the `appState.files` cache, on top of existing files present in the cache. +Adds supplied files data to the `appState.files` cache on top of existing files present in the cache. #### `onCollabButtonClick` @@ -640,7 +644,7 @@ The below attributes can be set in `UIOptions.canvasActions.export` to customize This callback is triggered if passed when something is pasted into the scene. You can use this callback in case you want to do something additional when the paste event occurs. 
-(data: ClipboardData, event: ClipboardEvent | null) => boolean
+(data: ClipboardData, event: ClipboardEvent | null) => boolean
This callback must return a `boolean` value or a [promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/Promise) which resolves to a boolean value. @@ -809,7 +813,8 @@ This function makes sure elements and state is set to appropriate values and set elements, appState getDimensions, -}: ExportOpts + files +}: ExportOpts | Name | Type | Default | Description | @@ -818,6 +823,7 @@ This function makes sure elements and state is set to appropriate values and set | appState | [AppState](https://github.com/excalidraw/excalidraw/blob/master/src/packages/utils.ts#L12) | [defaultAppState](https://github.com/excalidraw/excalidraw/blob/master/src/appState.ts#L11) | The app state of the scene | | getDimensions | `(width: number, height: number) => { width: number, height: number, scale?: number }` | undefined | A function which returns the `width`, `height`, and optionally `scale` (defaults `1`), with which canvas is to be exported. | | maxWidthOrHeight | `number` | undefined | The maximum width or height of the exported image. If provided, `getDimensions` is ignored. | +| files | [BinaryFiles](The [`BinaryFiles`](<[BinaryFiles](https://github.com/excalidraw/excalidraw/blob/master/src/types.ts#L64)>) | undefined | The files added to the scene. | **How to use** @@ -863,6 +869,7 @@ exportToSvg({ appState: AppState, exportPadding?: number, metadata?: string, + files?: BinaryFiles }) @@ -871,6 +878,7 @@ exportToSvg({ | elements | [Excalidraw Element []](https://github.com/excalidraw/excalidraw/blob/master/src/element/types.ts#L78) | | The elements to exported as svg | | appState | [AppState](https://github.com/excalidraw/excalidraw/blob/master/src/types.ts#L42) | [defaultAppState](https://github.com/excalidraw/excalidraw/blob/master/src/appState.ts#L11) | The app state of the scene | | exportPadding | number | 10 | The padding to be added on canvas | +| files | [BinaryFiles](The [`BinaryFiles`](<[BinaryFiles](https://github.com/excalidraw/excalidraw/blob/master/src/types.ts#L64)>) | undefined | The files added to the scene. | This function returns a promise which resolves to svg of the exported drawing. diff --git a/src/packages/excalidraw/example/App.js b/src/packages/excalidraw/example/App.js index 50080294..d12066ae 100644 --- a/src/packages/excalidraw/example/App.js +++ b/src/packages/excalidraw/example/App.js @@ -5,12 +5,25 @@ import Sidebar from "./sidebar/Sidebar"; import "./App.scss"; import initialData from "./initialData"; +import { MIME_TYPES } from "../../../constants"; // This is so that we use the bundled excalidraw.developement.js file instead // of the actual source code const { exportToCanvas, exportToSvg, exportToBlob } = window.Excalidraw; const Excalidraw = window.Excalidraw.default; +const resolvablePromise = () => { + let resolve; + let reject; + const promise = new Promise((_resolve, _reject) => { + resolve = _resolve; + reject = _reject; + }); + promise.resolve = resolve; + promise.reject = reject; + return promise; +}; + const renderTopRightUI = () => { return (