From ab1a30073c4309b1a9bfc5b2312414e8a44244d7 Mon Sep 17 00:00:00 2001 From: Aakansha Doshi Date: Thu, 12 May 2022 17:14:30 +0530 Subject: [PATCH] feat: expose utilitis to convert scene coords to viewport coords and vice versa (#5187) * feat: expose utilitis to convert scene coords to viewport coords and vice versa * add return value --- src/packages/excalidraw/CHANGELOG.md | 2 + src/packages/excalidraw/README_NEXT.md | 56 +++++++++++++++++++------- src/packages/excalidraw/example/App.js | 4 +- src/packages/excalidraw/index.tsx | 5 +++ 4 files changed, 51 insertions(+), 16 deletions(-) diff --git a/src/packages/excalidraw/CHANGELOG.md b/src/packages/excalidraw/CHANGELOG.md index 5624e15d..822467f5 100644 --- a/src/packages/excalidraw/CHANGELOG.md +++ b/src/packages/excalidraw/CHANGELOG.md @@ -17,6 +17,8 @@ Please add the latest change on the top under the correct section. #### Features +- Export [`sceneCoordsToViewportCoords`](https://github.com/excalidraw/excalidraw/blob/master/src/packages/excalidraw/README.md#onPointerDown) and [`viewportCoordsToSceneCoords`](https://github.com/excalidraw/excalidraw/blob/master/src/packages/excalidraw/README.md#onPointerDown) utilities [#5187](https://github.com/excalidraw/excalidraw/pull/5187). + - Added [`useHandleLibrary`](https://github.com/excalidraw/excalidraw/blob/master/src/packages/excalidraw/README.md#useHandleLibrary) hook to automatically handle importing of libraries when `#addLibrary` URL hash key is present, and potentially for initializing library as well [#5115](https://github.com/excalidraw/excalidraw/pull/5115). Also added [`parseLibraryTokensFromUrl`](https://github.com/excalidraw/excalidraw/blob/master/src/packages/excalidraw/README.md#parseLibraryTokensFromUrl) to help in manually importing library from URL if desired. diff --git a/src/packages/excalidraw/README_NEXT.md b/src/packages/excalidraw/README_NEXT.md index 6bec7e1c..d9e31dd3 100644 --- a/src/packages/excalidraw/README_NEXT.md +++ b/src/packages/excalidraw/README_NEXT.md @@ -383,7 +383,7 @@ For a complete list of variables, check [theme.scss](https://github.com/excalidr | Name | Type | Default | Description | | --- | --- | --- | --- | | [`onChange`](#onChange) | Function | | This callback is triggered whenever the component updates due to any change. This callback will receive the excalidraw elements and the current app state. | -| [`initialData`](#initialData) | 
{elements?: ExcalidrawElement[], appState?: AppState }
| null | The initial data with which app loads. | +| [`initialData`](#initialData) | 
{elements?: ExcalidrawElement[], appState?: AppState }
| null | The initial data with which app loads. | | [`ref`](#ref) | [`createRef`](https://reactjs.org/docs/refs-and-the-dom.html#creating-refs) | [`useRef`](https://reactjs.org/docs/hooks-reference.html#useref) | [`callbackRef`](https://reactjs.org/docs/refs-and-the-dom.html#callback-refs) | 
{ current: { readyPromise: resolvablePromise } }
| | Ref to be passed to Excalidraw | | [`onCollabButtonClick`](#onCollabButtonClick) | Function | | Callback to be triggered when the collab button is clicked | | [`isCollaborating`](#isCollaborating) | `boolean` | | This implies if the app is in collaboration mode | @@ -423,7 +423,7 @@ Every time component updates, this callback if passed will get triggered and has 1.`excalidrawElements`: Array of [excalidrawElements](https://github.com/excalidraw/excalidraw/blob/master/src/element/types.ts#L106) in the scene. -2.`appState`: [AppState](https://github.com/excalidraw/excalidraw/blob/master/src/types.ts#L66) of the scene. +2.`appState`: [AppState](https://github.com/excalidraw/excalidraw/blob/master/src/types.ts#L79) 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. @@ -436,7 +436,7 @@ This helps to load Excalidraw with `initialData`. It must be an object or a [pro | Name | Type | Description | | --- | --- | --- | | `elements` | [ExcalidrawElement[]](https://github.com/excalidraw/excalidraw/blob/master/src/element/types.ts#L106) | The elements with which Excalidraw should be mounted. | -| `appState` | [AppState](https://github.com/excalidraw/excalidraw/blob/master/src/types.ts#L66) | The App state with which Excalidraw should be mounted. | +| `appState` | [AppState](https://github.com/excalidraw/excalidraw/blob/master/src/types.ts#L79) | 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#L200) | Promise<[LibraryItems](https://github.com/excalidraw/excalidraw/blob/master/src/types.ts#L200)> | 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. | @@ -575,7 +575,7 @@ This callback is triggered when mouse pointer is updated. ``` 1. `exportedElements`: An array of [non deleted elements](https://github.com/excalidraw/excalidraw/blob/master/src/element/types.ts#L87) which needs to be exported. -2. `appState`: [AppState](https://github.com/excalidraw/excalidraw/blob/master/src/types.ts#L66) of the scene. +2. `appState`: [AppState](https://github.com/excalidraw/excalidraw/blob/master/src/types.ts#L79) of the scene. 3. `canvas`: The `HTMLCanvasElement` of the scene. #### `langCode` @@ -594,7 +594,7 @@ import { defaultLang, languages } from "@excalidraw/excalidraw-next"; #### `renderTopRightUI` 
-(isMobile: boolean, appState: AppState) => JSX
+(isMobile: boolean, appState: AppState) => JSX
A function returning JSX to render custom UI in the top right corner of the app. @@ -602,7 +602,7 @@ A function returning JSX to render custom UI in the top right corner of the app. #### `renderFooter` 
-(isMobile: boolean, appState: AppState) => JSX
+(isMobile: boolean, appState: AppState) => JSX
A function returning JSX to render custom UI footer. For example, you can use this to render a language picker that was previously being rendered by Excalidraw itself (for now, you'll need to implement your own language picker). @@ -803,7 +803,7 @@ No, Excalidraw package doesn't come with collaboration built in, since the imple **_Signature_** 
-restoreAppState(appState: ImportedDataState["appState"], localAppState: Partial<AppState> | null): AppState
+restoreAppState(appState: ImportedDataState["appState"], localAppState: Partial<AppState> | null): AppState
**_How to use_** @@ -812,7 +812,7 @@ restoreAppState(appState: -restoreElements(data: ImportedDataState, localAppState: Partial<AppState> | null | undefined, localElements: ExcalidrawElement[] | null | undefined): DataState +restoreElements(data: ImportedDataState, localAppState: Partial<AppState> | null | undefined, localElements: ExcalidrawElement[] | null | undefined): DataState See [`restoreAppState()`](https://github.com/excalidraw/excalidraw/blob/master/src/packages/excalidraw/README.md#restoreAppState) about `localAppState`, and [`restoreElements()`](https://github.com/excalidraw/excalidraw/blob/master/src/packages/excalidraw/README.md#restoreElements) about `localElements`. @@ -934,7 +934,7 @@ Returns a promise which resolves with a [blob](https://developer.mozilla.org/en- 
 exportToSvg({
   elements: ExcalidrawElement[],
-  appState: AppState,
+  appState: AppState,
   exportPadding?: number,
   metadata?: string,
   files?: BinaryFiles
@@ -944,7 +944,7 @@ exportToSvg({
 | Name | Type | Default | Description |
 | --- | --- | --- | --- |
 | elements | [Excalidraw Element []](https://github.com/excalidraw/excalidraw/blob/master/src/element/types.ts#L106) |  | The elements to exported as svg |
-| appState | [AppState](https://github.com/excalidraw/excalidraw/blob/master/src/types.ts#L66) | [defaultAppState](https://github.com/excalidraw/excalidraw/blob/master/src/appState.ts#L11) | The app state of the scene |
+| appState | [AppState](https://github.com/excalidraw/excalidraw/blob/master/src/types.ts#L79) | [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. |
 
@@ -996,7 +996,7 @@ Copies the scene data in the specified format (determined by `type`) to clipboar
 
 serializeAsJSON({
   elements: ExcalidrawElement[],
-  appState: AppState,
+  appState: AppState,
 }): string
 

 
@@ -1074,7 +1074,7 @@ excalidrawAPI.updateScene(scene);
 
 loadFromBlob(
   blob: Blob,
-  localAppState: AppState | null,
+  localAppState: AppState | null,
   localElements: ExcalidrawElement[] | null,
   fileHandle?: FileSystemHandle | null
 ) => Promise<RestoredDataState>
@@ -1102,7 +1102,7 @@ if (contents.type === MIME_TYPES.excalidraw) {
 
 loadSceneOrLibraryFromBlob(
   blob: Blob,
-  localAppState: AppState | null,
+  localAppState: AppState | null,
   localElements: ExcalidrawElement[] | null,
   fileHandle?: FileSystemHandle | null
 ) => Promise<{ type: string, data: RestoredDataState | ImportedLibraryState}>
@@ -1217,6 +1217,34 @@ A hook that automatically imports library from url if `#addLibrary` hash key exi
 
 In the future, we will be adding support for handling library persistence to browser storage (or elsewhere).
 
+#### `sceneCoordsToViewportCoords`
+
+```js
+import { sceneCoordsToViewportCoords } from "@excalidraw/excalidraw-next";
+```
+
+**_Signature_**
+
+
+sceneCoordsToViewportCoords({sceneX: number, sceneY: number}, appState: AppState): {x: number, y: number}
+

+
+This function returns equivalent viewport coords for the provided scene coords in params.
+
+#### `viewportCoordsToSceneCoords`
+
+```js
+import { viewportCoordsToSceneCoords } from "@excalidraw/excalidraw-next";
+```
+
+**_Signature_**
+
+
+viewportCoordsToSceneCoords({clientX: number, clientY: number}, appState: AppState): {x: number, y: number}
+

+
+This function returns equivalent scene coords for the provided viewport coords in params.
+
 ### Exported constants
 
 #### `FONT_FAMILY`
diff --git a/src/packages/excalidraw/example/App.js b/src/packages/excalidraw/example/App.js
index d7e726c9..0df9cb9b 100644
--- a/src/packages/excalidraw/example/App.js
+++ b/src/packages/excalidraw/example/App.js
@@ -7,8 +7,6 @@ import "./App.scss";
 import initialData from "./initialData";
 import { nanoid } from "nanoid";
 import {
-  sceneCoordsToViewportCoords,
-  viewportCoordsToSceneCoords,
   withBatchedUpdates,
   withBatchedUpdatesThrottled,
 } from "../../../utils";
@@ -28,6 +26,8 @@ const {
   Excalidraw,
   useHandleLibrary,
   MIME_TYPES,
+  sceneCoordsToViewportCoords,
+  viewportCoordsToSceneCoords,
 } = window.ExcalidrawLib;
 
 const COMMENT_SVG = (
diff --git a/src/packages/excalidraw/index.tsx b/src/packages/excalidraw/index.tsx
index 0e7e8129..936effdb 100644
--- a/src/packages/excalidraw/index.tsx
+++ b/src/packages/excalidraw/index.tsx
@@ -219,3 +219,8 @@ export {
   parseLibraryTokensFromUrl,
   useHandleLibrary,
 } from "../../data/library";
+
+export {
+  sceneCoordsToViewportCoords,
+  viewportCoordsToSceneCoords,
+} from "../../utils";