docs: tweak documentation for release and add examples (#4786)

* docs: tweak documentation for release

* Add image in initial data

* Add image

* remove watermark and make export work

* update readme

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.
+- Image support added for host [PR](https://github.com/excalidraw/excalidraw/pull/4011)
-
-  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.
 
   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<FileId, BinaryFileData>` 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).
 

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) | <pre>{ canvasActions: <a href="https://github.com/excalidraw/excalidraw/blob/master/src/types.ts#L208"> CanvasActions<a/> }</pre> | [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) | <pre>(data: <a href="https://github.com/excalidraw/excalidraw/blob/master/src/clipboard.ts#L17">ClipboardData</a>, event: ClipboardEvent &#124; null) => boolean</pre> |  | Callback to be triggered if passed when the something is pasted in to the scene |
+| [`onPaste`](#onPaste) | <pre>(data: <a href="https://github.com/excalidraw/excalidraw/blob/master/src/clipboard.ts#L21">ClipboardData</a>, event: ClipboardEvent &#124; null) => boolean</pre> |  | 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) | <pre>(items: <a href="https://github.com/excalidraw/excalidraw/blob/master/src/types.ts#L200">LibraryItems</a>) => void &#124; Promise&lt;any&gt; </pre> |  | 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) | <pre>() => <a href="https://github.com/excalidraw/excalidraw/blob/master/src/types.ts#L64">files</a> </pre> | 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
 
 <pre>(files: <a href="https://github.com/excalidraw/excalidraw/blob/master/src/types.ts">BinaryFileData</a>) => void </pre>
 
-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.
 
 <pre>
-(data: <a href="https://github.com/excalidraw/excalidraw/blob/master/src/clipboard.ts#L17">ClipboardData</a>, event: ClipboardEvent &#124; null) => boolean
+(data: <a href="https://github.com/excalidraw/excalidraw/blob/master/src/clipboard.ts#L21">ClipboardData</a>, event: ClipboardEvent &#124; null) => boolean
 </pre>
 
 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,
-}: <a href="https://github.com/excalidraw/excalidraw/blob/master/src/packages/utils.ts#L10">ExportOpts</a>
+  files
+}: <a href="https://github.com/excalidraw/excalidraw/blob/master/src/packages/utils.ts#L12">ExportOpts</a>
 </pre>
 
 | 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: <a href="https://github.com/excalidraw/excalidraw/blob/master/src/types.ts#L42">AppState</a>,
   exportPadding?: number,
   metadata?: string,
+  files?: <a href="https://github.com/excalidraw/excalidraw/blob/master/src/types.ts#L64">BinaryFiles</a>
 })
 </pre>
 
@@ -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.
 

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 (
     <button onClick={() => alert("This is dummy top right UI")}>
@@ -38,10 +51,35 @@ export default function App() {
   const [blobUrl, setBlobUrl] = useState(null);
   const [canvasUrl, setCanvasUrl] = useState(null);
   const [exportWithDarkMode, setExportWithDarkMode] = useState(false);
-  const [shouldAddWatermark, setShouldAddWatermark] = useState(false);
   const [theme, setTheme] = useState("light");
 
+  const initialStatePromiseRef = useRef({ promise: null });
+  if (!initialStatePromiseRef.current.promise) {
+    initialStatePromiseRef.current.promise = resolvablePromise();
+  }
   useEffect(() => {
+    const fetchData = async () => {
+      const res = await fetch("/rocket.jpeg");
+      const imageData = await res.blob();
+      const reader = new FileReader();
+      reader.readAsDataURL(imageData);
+
+      reader.onload = function () {
+        const imagesArray = [
+          {
+            id: "rocket",
+            dataURL: reader.result,
+            mimeType: MIME_TYPES.jpg,
+            created: 1644915140367,
+          },
+        ];
+
+        initialStatePromiseRef.current.promise.resolve(InitialData);
+        excalidrawRef.current.addFiles(imagesArray);
+      };
+    };
+    fetchData();
+
     const onHashChange = () => {
       const hash = new URLSearchParams(window.location.hash.slice(1));
       const libraryUrl = hash.get("addLibrary");
@@ -178,7 +216,7 @@ export default function App() {
         <div className="excalidraw-wrapper">
           <Excalidraw
             ref={excalidrawRef}
-            initialData={InitialData}
+            initialData={initialStatePromiseRef.current.promise}
             onChange={(elements, state) =>
               console.info("Elements :", elements, "State : ", state)
             }
@@ -207,14 +245,6 @@ export default function App() {
             />
             Export with dark mode
           </label>
-          <label className="export-wrapper__checkbox">
-            <input
-              type="checkbox"
-              checked={shouldAddWatermark}
-              onChange={() => setShouldAddWatermark(!shouldAddWatermark)}
-            />
-            Add Watermark
-          </label>
           <button
             onClick={async () => {
               const svg = await exportToSvg({
@@ -222,11 +252,11 @@ export default function App() {
                 appState: {
                   ...initialData.appState,
                   exportWithDarkMode,
-                  shouldAddWatermark,
                   width: 300,
                   height: 100,
                 },
                 embedScene: true,
+                files: excalidrawRef.current.getFiles(),
               });
               document.querySelector(".export-svg").innerHTML = svg.outerHTML;
             }}
@@ -243,8 +273,8 @@ export default function App() {
                 appState: {
                   ...initialData.appState,
                   exportWithDarkMode,
-                  shouldAddWatermark,
                 },
+                files: excalidrawRef.current.getFiles(),
               });
               setBlobUrl(window.URL.createObjectURL(blob));
             }}
@@ -256,14 +286,14 @@ export default function App() {
           </div>
 
           <button
-            onClick={() => {
+            onClick={async () => {
-              const canvas = exportToCanvas({
+              const canvas = await exportToCanvas({
                 elements: excalidrawRef.current.getSceneElements(),
                 appState: {
                   ...initialData.appState,
                   exportWithDarkMode,
-                  shouldAddWatermark,
                 },
+                files: excalidrawRef.current.getFiles(),
               });
               const ctx = canvas.getContext("2d");
               ctx.font = "30px Virgil";

src/packages/excalidraw/example/initialData.js

@@ -42,6 +42,33 @@ export default {
       versionNonce: 1128618623,
       isDeleted: false,
     },
+    {
+      fileId: "rocket",
+      type: "image",
+      x: 606.1042326312408,
+      y: 153.57729779411773,
+      width: 231.30325348751828,
+      height: 231.64340533088227,
+      angle: 0,
+      strokeColor: "transparent",
+      backgroundColor: "transparent",
+      fillStyle: "hachure",
+      strokeWidth: 1,
+      strokeStyle: "solid",
+      roughness: 1,
+      opacity: 100,
+      groupIds: [],
+      strokeSharpness: "round",
+      seed: 707269846,
+      version: 143,
+      versionNonce: 2028982666,
+      isDeleted: false,
+      boundElements: null,
+      updated: 1644914782403,
+      link: null,
+      status: "pending",
+      scale: [1, 1],
+    },
   ],
   appState: { viewBackgroundColor: "#AFEEEE", currentItemFontFamily: 1 },
   scrollToContent: true,