diff --git a/.dockerignore b/.dockerignore index 7a0150947..1f38a978c 100644 --- a/.dockerignore +++ b/.dockerignore @@ -6,6 +6,6 @@ !.prettierrc !package.json !public/ -!src/ +!packages/ !tsconfig.json !yarn.lock diff --git a/.env.development b/.env.development index 44955884f..95e21ff87 100644 --- a/.env.development +++ b/.env.development @@ -7,9 +7,6 @@ VITE_APP_LIBRARY_BACKEND=https://us-central1-excalidraw-room-persistence.cloudfu # collaboration WebSocket server (https://github.com/excalidraw/excalidraw-room) VITE_APP_WS_SERVER_URL=http://localhost:3002 -# set this only if using the collaboration workflow we use on excalidraw.com -VITE_APP_PORTAL_URL= - VITE_APP_PLUS_LP=https://plus.excalidraw.com VITE_APP_PLUS_APP=https://app.excalidraw.com diff --git a/.env.production b/.env.production index 26b46a52a..0c715854a 100644 --- a/.env.production +++ b/.env.production @@ -4,16 +4,13 @@ VITE_APP_BACKEND_V2_POST_URL=https://json.excalidraw.com/api/v2/post/ VITE_APP_LIBRARY_URL=https://libraries.excalidraw.com VITE_APP_LIBRARY_BACKEND=https://us-central1-excalidraw-room-persistence.cloudfunctions.net/libraries -VITE_APP_PORTAL_URL=https://portal.excalidraw.com - VITE_APP_PLUS_LP=https://plus.excalidraw.com VITE_APP_PLUS_APP=https://app.excalidraw.com VITE_APP_AI_BACKEND=https://oss-ai.excalidraw.com -# Fill to set socket server URL used for collaboration. -# Meant for forks only: excalidraw.com uses custom VITE_APP_PORTAL_URL flow -VITE_APP_WS_SERVER_URL= +# socket server URL used for collaboration +VITE_APP_WS_SERVER_URL=https://oss-collab.excalidraw.com VITE_APP_FIREBASE_CONFIG='{"apiKey":"AIzaSyAd15pYlMci_xIp9ko6wkEsDzAAA0Dn0RU","authDomain":"excalidraw-room-persistence.firebaseapp.com","databaseURL":"https://excalidraw-room-persistence.firebaseio.com","projectId":"excalidraw-room-persistence","storageBucket":"excalidraw-room-persistence.appspot.com","messagingSenderId":"654800341332","appId":"1:654800341332:web:4a692de832b55bd57ce0c1"}' diff --git a/.eslintignore b/.eslintignore index b238ce5f7..ab3aa6c76 100644 --- a/.eslintignore +++ b/.eslintignore @@ -5,4 +5,4 @@ package-lock.json firebase/ dist/ public/workbox -src/packages/excalidraw/types +packages/excalidraw/types diff --git a/.github/workflows/autorelease-excalidraw.yml b/.github/workflows/autorelease-excalidraw.yml index 4eaeb11f1..5ff5690eb 100644 --- a/.github/workflows/autorelease-excalidraw.yml +++ b/.github/workflows/autorelease-excalidraw.yml @@ -23,5 +23,5 @@ jobs: NPM_TOKEN: ${{ secrets.NPM_TOKEN }} - name: Auto release run: | - yarn add @actions/core + yarn add @actions/core -W yarn autorelease diff --git a/.github/workflows/autorelease-preview.yml b/.github/workflows/autorelease-preview.yml index bcd501880..a40ed3c43 100644 --- a/.github/workflows/autorelease-preview.yml +++ b/.github/workflows/autorelease-preview.yml @@ -44,7 +44,7 @@ jobs: - name: Auto release preview id: "autorelease" run: | - yarn add @actions/core + yarn add @actions/core -W yarn autorelease preview ${{ github.event.issue.number }} - name: Post comment post release if: always() diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml index d42f8f632..82f826361 100644 --- a/.github/workflows/lint.yml +++ b/.github/workflows/lint.yml @@ -16,7 +16,7 @@ jobs: - name: Install and lint run: | - yarn --frozen-lockfile + yarn install yarn test:other yarn test:code yarn test:typecheck diff --git a/.github/workflows/locales-coverage.yml b/.github/workflows/locales-coverage.yml index 822af06e1..3cce93e04 100644 --- a/.github/workflows/locales-coverage.yml +++ b/.github/workflows/locales-coverage.yml @@ -22,11 +22,11 @@ jobs: - name: Create report file run: | yarn locales-coverage - FILE_CHANGED=$(git diff src/locales/percentages.json) + FILE_CHANGED=$(git diff packages/excalidraw/locales/percentages.json) if [ ! -z "${FILE_CHANGED}" ]; then git config --global user.name 'Excalidraw Bot' git config --global user.email 'bot@excalidraw.com' - git add src/locales/percentages.json + git add packages/excalidraw/locales/percentages.json git commit -am "Auto commit: Calculate translation coverage" git push fi diff --git a/.github/workflows/size-limit.yml b/.github/workflows/size-limit.yml index 8ced8ee03..5bd3c0d92 100644 --- a/.github/workflows/size-limit.yml +++ b/.github/workflows/size-limit.yml @@ -15,16 +15,14 @@ jobs: uses: actions/setup-node@v3 with: node-version: 18.x - - name: Install - run: yarn --frozen-lockfile - - name: Install in src/packages/excalidraw - run: yarn --frozen-lockfile - working-directory: src/packages/excalidraw + - name: Install in packages/excalidraw + run: yarn + working-directory: packages/excalidraw env: CI: true - uses: andresz1/size-limit-action@v1 with: github_token: ${{ secrets.GITHUB_TOKEN }} - build_script: build:umd + build_script: build:esm skip_step: install - directory: src/packages/excalidraw + directory: packages/excalidraw diff --git a/.github/workflows/test-coverage-pr.yml b/.github/workflows/test-coverage-pr.yml index 76c818298..7ff40ad5d 100644 --- a/.github/workflows/test-coverage-pr.yml +++ b/.github/workflows/test-coverage-pr.yml @@ -16,7 +16,7 @@ jobs: with: node-version: "18.x" - name: "Install Deps" - run: yarn --frozen-lockfile + run: yarn install - name: "Test Coverage" run: yarn test:coverage - name: "Report Coverage" diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index 5c4584e82..2c458a810 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -13,5 +13,5 @@ jobs: node-version: 18.x - name: Install and test run: | - yarn --frozen-lockfile + yarn install yarn test:app diff --git a/.gitignore b/.gitignore index 6e430f4ed..21d2730a2 100644 --- a/.gitignore +++ b/.gitignore @@ -21,10 +21,8 @@ npm-debug.log* package-lock.json yarn-debug.log* yarn-error.log* -src/packages/excalidraw/types -src/packages/excalidraw/example/public/bundle.js -src/packages/excalidraw/example/public/excalidraw-assets-dev -src/packages/excalidraw/example/public/excalidraw.development.js +packages/excalidraw/types coverage dev-dist html +examples/**/bundle.* \ No newline at end of file diff --git a/README.md b/README.md index 2a8a3f908..e8cd3b06f 100644 --- a/README.md +++ b/README.md @@ -85,7 +85,7 @@ We'll be adding these features as drop-in plugins for the npm package in the fut ## Quick start -Install the [Excalidraw npm package](https://www.npmjs.com/package/@excalidraw/excalidraw): +**Note:** following instructions are for installing the Excalidraw [npm package](https://www.npmjs.com/package/@excalidraw/excalidraw) when integrating Excalidraw into your own app. To run the repository locally for development, please refer to our [Development Guide](https://docs.excalidraw.com/docs/introduction/development). ``` npm install react react-dom @excalidraw/excalidraw @@ -97,7 +97,7 @@ or via yarn yarn add react react-dom @excalidraw/excalidraw ``` -Don't forget to check out our [Documentation](https://docs.excalidraw.com)! +Check out our [documentation](https://docs.excalidraw.com/docs/@excalidraw/excalidraw/installation) for more details! ## Contributing diff --git a/crowdin.yml b/crowdin.yml index a08b939c6..ccb8a17aa 100644 --- a/crowdin.yml +++ b/crowdin.yml @@ -1,3 +1,3 @@ files: - - source: /src/locales/en.json - translation: /src/locales/%locale%.json + - source: /packages/excalidraw/locales/en.json + translation: /packages/excalidraw/locales/%locale%.json diff --git a/dev-docs/docs/@excalidraw/excalidraw/api/children-components/main-menu.mdx b/dev-docs/docs/@excalidraw/excalidraw/api/children-components/main-menu.mdx index 77c746b84..e601a2471 100644 --- a/dev-docs/docs/@excalidraw/excalidraw/api/children-components/main-menu.mdx +++ b/dev-docs/docs/@excalidraw/excalidraw/api/children-components/main-menu.mdx @@ -133,7 +133,7 @@ function App() { } ``` -Here is a [complete list](https://github.com/excalidraw/excalidraw/blob/master/src/components/mainMenu/DefaultItems.tsx) of the default items. +Here is a [complete list](https://github.com/excalidraw/excalidraw/blob/master/packages/excalidraw/components/mainMenu/DefaultItems.tsx) of the default items. ### MainMenu.Group diff --git a/dev-docs/docs/@excalidraw/excalidraw/api/constants.mdx b/dev-docs/docs/@excalidraw/excalidraw/api/constants.mdx index a6c95ab2a..029f5b05c 100644 --- a/dev-docs/docs/@excalidraw/excalidraw/api/constants.mdx +++ b/dev-docs/docs/@excalidraw/excalidraw/api/constants.mdx @@ -37,7 +37,7 @@ Defaults to `THEME.LIGHT` unless passed in `initialData.appState.theme` ### MIME_TYPES -[`MIME_TYPES`](https://github.com/excalidraw/excalidraw/blob/master/src/constants.ts#L101) contains all the mime types supported by `Excalidraw`. +[`MIME_TYPES`](https://github.com/excalidraw/excalidraw/blob/master/packages/excalidraw/constants.ts#L101) contains all the mime types supported by `Excalidraw`. **How to use ** diff --git a/dev-docs/docs/@excalidraw/excalidraw/api/excalidraw-element-skeleton.mdx b/dev-docs/docs/@excalidraw/excalidraw/api/excalidraw-element-skeleton.mdx index 838896c42..b633236aa 100644 --- a/dev-docs/docs/@excalidraw/excalidraw/api/excalidraw-element-skeleton.mdx +++ b/dev-docs/docs/@excalidraw/excalidraw/api/excalidraw-element-skeleton.mdx @@ -2,9 +2,9 @@ We support a simplified API to make it easier to generate Excalidraw elements programmatically. This API is in beta and subject to change before stable. You can check the [PR](https://github.com/excalidraw/excalidraw/pull/6546) for more details. -For this purpose we introduced a new type [`ExcalidrawElementSkeleton`](https://github.com/excalidraw/excalidraw/blob/master/src/data/transform.ts#L133). This is the simplified version of [`ExcalidrawElement`](https://github.com/excalidraw/excalidraw/blob/master/src/element/types.ts#L134) type with the minimum possible attributes so that creating elements programmatically is much easier (especially for cases like binding arrows or creating text containers). +For this purpose we introduced a new type [`ExcalidrawElementSkeleton`](https://github.com/excalidraw/excalidraw/blob/master/packages/excalidraw/data/transform.ts#L133). This is the simplified version of [`ExcalidrawElement`](https://github.com/excalidraw/excalidraw/blob/master/packages/excalidraw/element/types.ts#L134) type with the minimum possible attributes so that creating elements programmatically is much easier (especially for cases like binding arrows or creating text containers). -The [`ExcalidrawElementSkeleton`](https://github.com/excalidraw/excalidraw/blob/master/src/data/transform.ts#L133) can be converted to fully qualified Excalidraw elements by using [`convertToExcalidrawElements`](/docs/@excalidraw/excalidraw/api/excalidraw-element-skeleton#converttoexcalidrawelements). +The [`ExcalidrawElementSkeleton`](https://github.com/excalidraw/excalidraw/blob/master/packages/excalidraw/data/transform.ts#L133) can be converted to fully qualified Excalidraw elements by using [`convertToExcalidrawElements`](/docs/@excalidraw/excalidraw/api/excalidraw-element-skeleton#converttoexcalidrawelements). ## convertToExcalidrawElements @@ -19,7 +19,7 @@ convertToExcalidrawElements( | Name | Type | Default | Description | | --- | --- | --- | --- | -| `elements` | [ExcalidrawElementSkeleton](https://github.com/excalidraw/excalidraw/blob/master/src/data/transform.ts#L137) | | The Excalidraw element Skeleton which needs to be converted to Excalidraw elements. | +| `elements` | [ExcalidrawElementSkeleton](https://github.com/excalidraw/excalidraw/blob/master/packages/excalidraw/data/transform.ts#L137) | | The Excalidraw element Skeleton which needs to be converted to Excalidraw elements. | | `opts` | `{ regenerateIds: boolean }` | ` {regenerateIds: true}` | By default `id` will be regenerated for all the elements irrespective of whether you pass the `id` so if you don't want the ids to regenerated, you can set this attribute to `false`. | **_How to use_** @@ -71,7 +71,7 @@ function App() { } ``` -You can pass additional [`properties`](https://github.com/excalidraw/excalidraw/blob/master/src/element/types.ts#L27) as well to decorate the shapes. +You can pass additional [`properties`](https://github.com/excalidraw/excalidraw/blob/master/packages/excalidraw/element/types.ts#L27) as well to decorate the shapes. :::info @@ -192,7 +192,7 @@ convertToExcalidrawElements([ ### Text Containers -In addition to `type`, `x` and `y` properties, [`label`](https://github.com/excalidraw/excalidraw/blob/master/src/data/transform.ts#L124C7-L130C59) property is required for text containers. The `text` property in `label` is required, rest of the attributes are optional. +In addition to `type`, `x` and `y` properties, [`label`](https://github.com/excalidraw/excalidraw/blob/master/packages/excalidraw/data/transform.ts#L124C7-L130C59) property is required for text containers. The `text` property in `label` is required, rest of the attributes are optional. If you don't provide the dimensions of container, we calculate it based of the label dimensions. @@ -326,7 +326,7 @@ convertToExcalidrawElements([ ### Arrow bindings -To bind arrow to a shape you need to specify its [`start`](https://github.com/excalidraw/excalidraw/blob/master/src/data/transform.ts#L86) and [`end`](https://github.com/excalidraw/excalidraw/blob/master/src/data/transform.ts#L54) properties. You need to pass either `type` or `id` property in `start` and `end` properties, rest of the attributes are optional +To bind arrow to a shape you need to specify its [`start`](https://github.com/excalidraw/excalidraw/blob/master/packages/excalidraw/data/transform.ts#L86) and [`end`](https://github.com/excalidraw/excalidraw/blob/master/packages/excalidraw/data/transform.ts#L54) properties. You need to pass either `type` or `id` property in `start` and `end` properties, rest of the attributes are optional ```js convertToExcalidrawElements([ diff --git a/dev-docs/docs/@excalidraw/excalidraw/api/props/excalidraw-api.mdx b/dev-docs/docs/@excalidraw/excalidraw/api/props/excalidraw-api.mdx index 22e9034fd..ffff19fb0 100644 --- a/dev-docs/docs/@excalidraw/excalidraw/api/props/excalidraw-api.mdx +++ b/dev-docs/docs/@excalidraw/excalidraw/api/props/excalidraw-api.mdx @@ -2,7 +2,7 @@
(api:{" "} - + ExcalidrawAPI ) => void; @@ -17,7 +17,7 @@ export default function App() { } ``` -You can use this prop when you want to access some [Excalidraw APIs](https://github.com/excalidraw/excalidraw/blob/master/src/types.ts#L616). We expose the below APIs :point_down: +You can use this prop when you want to access some [Excalidraw APIs](https://github.com/excalidraw/excalidraw/blob/master/packages/excalidraw/types.ts#L616). We expose the below APIs :point_down: | API | Signature | Usage | | --- | --- | --- | @@ -37,7 +37,7 @@ You can use this prop when you want to access some [Excalidraw APIs](https://git | [setActiveTool](#setactivetool) | `function` | This API can be used to set the active tool | | [setCursor](#setcursor) | `function` | This API can be used to set customise the mouse cursor on the canvas | | [resetCursor](#resetcursor) | `function` | This API can be used to reset to default mouse cursor on the canvas | -| [toggleMenu](#togglemenu) | `function` | Toggles specific menus on/off | +| [toggleSidebar](#toggleSidebar) | `function` | Toggles specific sidebar on/off | | [onChange](#onChange) | `function` | Subscribes to change events | | [onPointerDown](#onPointerDown) | `function` | Subscribes to `pointerdown` events | | [onPointerUp](#onPointerUp) | `function` | Subscribes to `pointerup` events | @@ -52,7 +52,7 @@ Additionally `ready` and `readyPromise` from the API have been discontinued. The(scene:{" "} - + sceneData ) => void @@ -62,9 +62,9 @@ You can use this function to update the scene with the sceneData. It accepts the | Name | Type | Description | | --- | --- | --- | -| `elements` | [`ImportedDataState["elements"]`](https://github.com/excalidraw/excalidraw/blob/master/src/data/types.ts#L38) | The `elements` to be updated in the scene | -| `appState` | [`ImportedDataState["appState"]`](https://github.com/excalidraw/excalidraw/blob/master/src/data/types.ts#L39) | The `appState` to be updated in the scene. | -| `collaborators` |Map
| The list of collaborators to be updated in the scene. | +| `elements` | [`ImportedDataState["elements"]`](https://github.com/excalidraw/excalidraw/blob/master/packages/excalidraw/data/types.ts#L38) | The `elements` to be updated in the scene | +| `appState` | [`ImportedDataState["appState"]`](https://github.com/excalidraw/excalidraw/blob/master/packages/excalidraw/data/types.ts#L39) | The `appState` to be updated in the scene. | +| `collaborators` |Collaborator> Map
| The list of collaborators to be updated in the scene. | | `commitToHistory` | `boolean` | Implies if the `history (undo/redo)` should be recorded. Defaults to `false`. | ```jsx live @@ -125,13 +125,13 @@ function App() {Collaborator> (opts: {
libraryItems:{" "} - + LibraryItemsSource ;
merge?: boolean;
prompt?: boolean;
openLibraryMenu?: boolean;
defaultStatus?: "unpublished" | "published";
}) => Promise< - + LibraryItems > @@ -141,7 +141,7 @@ You can use this function to update the library. It accepts the below attributes | Name | Type | Default | Description | | --- | --- | --- | --- | -| `libraryItems` | [LibraryItemsSource](https://github.com/excalidraw/excalidraw/blob/master/src/types.ts#L249) | \_ | The `libraryItems` to be replaced/merged with current library | +| `libraryItems` | [LibraryItemsSource](https://github.com/excalidraw/excalidraw/blob/master/packages/excalidraw/types.ts#L249) | \_ | The `libraryItems` to be replaced/merged with current library | | `merge` | boolean | `false` | Whether to merge with existing library items. | | `prompt` | boolean | `false` | Whether to prompt user for confirmation. | | `openLibraryMenu` | boolean | `false` | Keep the library menu open after library is updated. | @@ -189,7 +189,7 @@ function App() {setExcalidrawAPI(api)} - // initial data retrieved from https://github.com/excalidraw/excalidraw/blob/master/dev-docs/src/initialData.js + // initial data retrieved from https://github.com/excalidraw/excalidraw/blob/master/dev-docs/packages/excalidraw/initialData.js initialData={{ libraryItems: initialData.libraryItems, appState: { openSidebar: "library" }, @@ -204,7 +204,7 @@ function App() { (files:{" "} - + BinaryFileData ) => void @@ -224,7 +224,7 @@ Resets the scene. If `resetLoadingState` is passed as true then it will also for() =>{" "} - + ExcalidrawElement[]@@ -235,7 +235,7 @@ Returns all the elements including the deleted in the scene.() => NonDeleted< - + ExcalidrawElement []> @@ -247,7 +247,7 @@ Returns all the elements excluding the deleted in the scene() =>{" "} - + AppState@@ -288,7 +288,7 @@ Scroll the nearest element out of the elements supplied to the center of the vie | Attribute | type | default | Description | | --- | --- | --- | --- | -| target | [ExcalidrawElement](https://github.com/excalidraw/excalidraw/blob/master/src/element/types.ts#L115) | [ExcalidrawElement[]](https://github.com/excalidraw/excalidraw/blob/master/src/element/types.ts#L115) | All scene elements | The element(s) to scroll to. | +| target | [ExcalidrawElement](https://github.com/excalidraw/excalidraw/blob/master/packages/excalidraw/element/types.ts#L115) | [ExcalidrawElement[]](https://github.com/excalidraw/excalidraw/blob/master/packages/excalidraw/element/types.ts#L115) | All scene elements | The element(s) to scroll to. | | opts.fitToContent | boolean | false | Whether to fit the elements to viewport by automatically changing zoom as needed. Note that the zoom range is between 10%-100%. | | opts.fitToViewport | boolean | false | Similar to fitToContent but the zoom range is not limited. If elements are smaller than the viewport, zoom will go above 100%. | | opts.viewportZoomFactor | number | 0.7 | when fitToViewport=true, how much screen should the content cover, between 0.1 (10%) and 1 (100%) | @@ -336,7 +336,7 @@ The unique id of the excalidraw component. This can be used to identify the exca() =>{" "} - + files@@ -364,7 +364,7 @@ This API has the below signature. It sets the `tool` passed in param as the acti | Name | Type | Default | Description | | --- | --- | --- | --- | -| `type` | [ToolType](https://github.com/excalidraw/excalidraw/blob/master/src/types.ts#L91) | `selection` | The tool type which should be set as active tool. When setting `image` as active tool, the insertion onto canvas when using image tool is disabled by default, so you can enable it by setting `insertOnCanvasDirectly` to `true` | +| `type` | [ToolType](https://github.com/excalidraw/excalidraw/blob/master/packages/excalidraw/types.ts#L91) | `selection` | The tool type which should be set as active tool. When setting `image` as active tool, the insertion onto canvas when using image tool is disabled by default, so you can enable it by setting `insertOnCanvasDirectly` to `true` | | `locked` | `boolean` | `false` | Indicates whether the the active tool should be locked. It behaves the same way when using the `lock` tool in the editor interface | ## setCursor diff --git a/dev-docs/docs/@excalidraw/excalidraw/api/props/initialdata.mdx b/dev-docs/docs/@excalidraw/excalidraw/api/props/initialdata.mdx index 7d79128f0..0fec6ea02 100644 --- a/dev-docs/docs/@excalidraw/excalidraw/api/props/initialdata.mdx +++ b/dev-docs/docs/@excalidraw/excalidraw/api/props/initialdata.mdx @@ -1,18 +1,18 @@ # initialData-{ elements?: ExcalidrawElement[], appState?: AppState } +{ elements?: ExcalidrawElement[], appState?: AppState }This helps to load Excalidraw with `initialData`. It must be an object or a [promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/Promise) which resolves to an object containing the below optional fields. | Name | Type | Description | | --- | --- | --- | -| `elements` | [ExcalidrawElement[]](https://github.com/excalidraw/excalidraw/blob/master/src/element/types.ts#L114) | The `elements` with which `Excalidraw` should be mounted. | -| `appState` | [AppState](https://github.com/excalidraw/excalidraw/blob/master/src/types.ts#L95) | The `AppState` with which `Excalidraw` should be mounted. | +| `elements` | [ExcalidrawElement[]](https://github.com/excalidraw/excalidraw/blob/master/packages/excalidraw/element/types.ts#L114) | The `elements` with which `Excalidraw` should be mounted. | +| `appState` | [AppState](https://github.com/excalidraw/excalidraw/blob/master/packages/excalidraw/types.ts#L95) | The `AppState` with which `Excalidraw` should be mounted. | | `scrollToContent` | `boolean` | This attribute indicates 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#L247) | 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#L82) | The `files` added to the scene. | +| `libraryItems` | [LibraryItems](https://github.com/excalidraw/excalidraw/blob/master/packages/excalidraw/types.ts#L247) | Promise<[LibraryItems](https://github.com/excalidraw/excalidraw/blob/master/packages/excalidraw/types.ts#L200)> | This library items with which `Excalidraw` should be mounted. | +| `files` | [BinaryFiles](https://github.com/excalidraw/excalidraw/blob/master/packages/excalidraw/types.ts#L82) | The `files` added to the scene. | You might want to use this when you want to load excalidraw with some initial elements and app state. diff --git a/dev-docs/docs/@excalidraw/excalidraw/api/props/props.mdx b/dev-docs/docs/@excalidraw/excalidraw/api/props/props.mdx index 069b15901..766c723e4 100644 --- a/dev-docs/docs/@excalidraw/excalidraw/api/props/props.mdx +++ b/dev-docs/docs/@excalidraw/excalidraw/api/props/props.mdx @@ -23,7 +23,7 @@ All `props` are _optional_. | [`libraryReturnUrl`](#libraryreturnurl) | `string` | _ | What URL should [libraries.excalidraw.com](https://libraries.excalidraw.com) be installed to | | [`theme`](#theme) | `"light"` | `"dark"` | `"light"` | The theme of the Excalidraw component | | [`name`](#name) | `string` | | Name of the drawing | -| [`UIOptions`](/docs/@excalidraw/excalidraw/api/props/ui-options) | `object` | [DEFAULT UI OPTIONS](https://github.com/excalidraw/excalidraw/blob/master/src/constants.ts#L151) | To customise UI options. Currently we support customising [`canvas actions`](#canvasactions) | +| [`UIOptions`](/docs/@excalidraw/excalidraw/api/props/ui-options) | `object` | [DEFAULT UI OPTIONS](https://github.com/excalidraw/excalidraw/blob/master/packages/excalidraw/constants.ts#L151) | To customise UI options. Currently we support customising [`canvas actions`](/docs/@excalidraw/excalidraw/api/props/ui-options#canvasactions) | | [`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. | | [`autoFocus`](#autofocus) | `boolean` | `false` | indicates whether to focus the Excalidraw component on page load | @@ -33,7 +33,7 @@ All `props` are _optional_. ### Storing custom data on Excalidraw elements -Beyond attributes that Excalidraw elements already support, you can store `custom` data on each `element` in a `customData` object. The type of the attribute is [`Record`](https://github.com/excalidraw/excalidraw/blob/master/src/element/types.ts#L66) and is optional. +Beyond attributes that Excalidraw elements already support, you can store `custom` data on each `element` in a `customData` object. The type of the attribute is [`Record `](https://github.com/excalidraw/excalidraw/blob/master/packages/excalidraw/element/types.ts#L66) and is optional. You can use this to add any extra information you need to keep track of. @@ -59,11 +59,11 @@ Every time component updates, this callback if passed will get triggered and has (excalidrawElements, appState, files) => void; ``` -1. `excalidrawElements`: Array of [excalidrawElements](https://github.com/excalidraw/excalidraw/blob/master/src/element/types.ts#L114) in the scene. +1. `excalidrawElements`: Array of [excalidrawElements](https://github.com/excalidraw/excalidraw/blob/master/packages/excalidraw/element/types.ts#L114) in the scene. -2. `appState`: [AppState](https://github.com/excalidraw/excalidraw/blob/master/src/types.ts#L95) of the scene. +2. `appState`: [AppState](https://github.com/excalidraw/excalidraw/blob/master/packages/excalidraw/types.ts#L95) of the scene. -3. `files`: The [BinaryFiles](https://github.com/excalidraw/excalidraw/blob/master/src/types.ts#L64) which are added to the scene. +3. `files`: The [BinaryFiles](https://github.com/excalidraw/excalidraw/blob/master/packages/excalidraw/types.ts#L64) which are added to the scene. Here you can try saving the data to your backend or local storage for example. @@ -79,14 +79,14 @@ This callback is triggered when mouse pointer is updated. 2.`button`: The position of the button. This will be one of `["down", "up"]` -3.`pointersMap`: [`pointers`](https://github.com/excalidraw/excalidraw/blob/master/src/types.ts#L131) map of the scene +3.`pointersMap`: [`pointers`](https://github.com/excalidraw/excalidraw/blob/master/packages/excalidraw/types.ts#L131) map of the scene ```js (exportedElements, appState, canvas) => void ``` -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#L95) of the scene. +1. `exportedElements`: An array of [non deleted elements](https://github.com/excalidraw/excalidraw/blob/master/packages/excalidraw/element/types.ts#L87) which needs to be exported. +2. `appState`: [AppState](https://github.com/excalidraw/excalidraw/blob/master/packages/excalidraw/types.ts#L95) of the scene. 3. `canvas`: The `HTMLCanvasElement` of the scene. ### onPointerDown @@ -96,11 +96,11 @@ This prop if passed will be triggered on pointer down events and has the below s (activeTool:{" "} - + {" "} AppState["activeTool"] - , pointerDownState: + , pointerDownState: PointerDownState ) => void@@ -119,7 +119,7 @@ This callback is triggered if passed when something is pasted into the scene. Yo(data:{" "} - + ClipboardData , event: ClipboardEvent | null) => boolean @@ -135,7 +135,7 @@ This callback if supplied will get triggered when the library is updated and has(items:{" "} - + LibraryItems ) => void | Promise<any> @@ -149,7 +149,7 @@ This prop if passed will be triggered when clicked on `link`. To handle the redi(element:{" "} - + ExcalidrawElement , event: CustomEvent<{ nativeEvent: MouseEvent }>) => void @@ -182,7 +182,7 @@ const onLinkOpen: ExcalidrawProps["onLinkOpen"] = useCallback( ### langCode -Determines the `language` of the UI. It should be one of the [available language codes](https://github.com/excalidraw/excalidraw/blob/master/src/i18n.ts#L14). Defaults to `en` (English). We also export default language and supported languages which you can import as shown below. +Determines the `language` of the UI. It should be one of the [available language codes](https://github.com/excalidraw/excalidraw/blob/master/packages/excalidraw/i18n.ts#L14). Defaults to `en` (English). We also export default language and supported languages which you can import as shown below. ```js import { defaultLang, languages } from "@excalidraw/excalidraw"; @@ -191,7 +191,7 @@ import { defaultLang, languages } from "@excalidraw/excalidraw"; | name | type | | --- | --- | | `defaultLang` | `string` | -| `languages` | [`Language[]`](https://github.com/excalidraw/excalidraw/blob/master/src/i18n.ts#L15) | +| `languages` | [`Language[]`](https://github.com/excalidraw/excalidraw/blob/master/packages/excalidraw/i18n.ts#L15) | ### viewModeEnabled diff --git a/dev-docs/docs/@excalidraw/excalidraw/api/props/render-props.mdx b/dev-docs/docs/@excalidraw/excalidraw/api/props/render-props.mdx index f0f4adc44..0df7634cb 100644 --- a/dev-docs/docs/@excalidraw/excalidraw/api/props/render-props.mdx +++ b/dev-docs/docs/@excalidraw/excalidraw/api/props/render-props.mdx @@ -4,7 +4,7 @@(isMobile: boolean, appState: - + AppState ) => JSX | null@@ -66,7 +66,7 @@ function App() {(element: NonDeleted<ExcalidrawEmbeddableElement>, appState:{" "} - + AppState ) => JSX.Element | null diff --git a/dev-docs/docs/@excalidraw/excalidraw/api/props/ui-options.mdx b/dev-docs/docs/@excalidraw/excalidraw/api/props/ui-options.mdx index ac91f9e00..9d77e390a 100644 --- a/dev-docs/docs/@excalidraw/excalidraw/api/props/ui-options.mdx +++ b/dev-docs/docs/@excalidraw/excalidraw/api/props/ui-options.mdx @@ -4,7 +4,7 @@ This prop can be used to customise UI of Excalidraw. Currently we support custom{ -| Name | Type | Default | Description | | --- | --- | --- | --- | -| `elements` | [Excalidraw Element []](https://github.com/excalidraw/excalidraw/blob/master/src/element/types.ts#L114) | | The elements to be exported to canvas. | -| `appState` | [AppState](https://github.com/excalidraw/excalidraw/blob/master/src/packages/utils.ts#L23) | [Default App State](https://github.com/excalidraw/excalidraw/blob/master/src/appState.ts#L17) | The app state of the scene. | +| `elements` | [Excalidraw Element []](https://github.com/excalidraw/excalidraw/blob/master/packages/excalidraw/element/types.ts#L114) | | The elements to be exported to canvas. | +| `appState` | [AppState](https://github.com/excalidraw/excalidraw/blob/master/packages/excalidraw/packages/utils.ts#L23) | [Default App State](https://github.com/excalidraw/excalidraw/blob/master/packages/excalidraw/appState.ts#L17) | The app state of the scene. | | [`getDimensions`](#getdimensions) | `function` | _ | A function which returns the `width`, `height`, and optionally `scale` (defaults to `1`), with which canvas is to be exported. | | `maxWidthOrHeight` | `number` | _ | The maximum `width` or `height` of the exported image. If provided, `getDimensions` is ignored. | -| `files` | [BinaryFiles](https://github.com/excalidraw/excalidraw/blob/master/src/types.ts#L59) | _ | The files added to the scene. | +| `files` | [BinaryFiles](https://github.com/excalidraw/excalidraw/blob/master/packages/excalidraw/types.ts#L59) | _ | The files added to the scene. | | `exportPadding` | `number` | `10` | The `padding` to be added on canvas. | @@ -105,7 +105,7 @@ function App() {
canvasActions?: +
canvasActions?: CanvasActions ,
dockedSidebarBreakpoint?: number,
welcomeScreen?: boolean
@@ -55,7 +55,7 @@ If `UIOptions.canvasActions.export` is `false` the export button will not be ren ## dockedSidebarBreakpoint -This prop indicates at what point should we break to a docked, permanent sidebar. If not passed it defaults to [`MQ_RIGHT_SIDEBAR_MAX_WIDTH_PORTRAIT`](https://github.com/excalidraw/excalidraw/blob/master/src/constants.ts#L161). +This prop indicates at what point should we break to a docked, permanent sidebar. If not passed it defaults to [`MQ_RIGHT_SIDEBAR_MAX_WIDTH_PORTRAIT`](https://github.com/excalidraw/excalidraw/blob/master/packages/excalidraw/constants.ts#L161). If the _width_ of the _excalidraw_ container exceeds _dockedSidebarBreakpoint_, the sidebar will be `dockable` and the button to `dock` the sidebar will be shown If user choses to `dock` the sidebar, it will push the right part of the UI towards the left, making space for the sidebar as shown below. @@ -73,9 +73,9 @@ function App() { ## tools -This `prop ` controls the visibility of the tools in the editor. +This `prop` controls the visibility of the tools in the editor. Currently you can control the visibility of `image` tool via this prop. | Prop | Type | Default | Description | | --- | --- | --- | --- | -| image | boolean | true | Decides whether `image` tool should be visible. \ No newline at end of file +| image | boolean | true | Decides whether `image` tool should be visible. diff --git a/dev-docs/docs/@excalidraw/excalidraw/api/utils/export.mdx b/dev-docs/docs/@excalidraw/excalidraw/api/utils/export.mdx index f5469f01d..ef59054c4 100644 --- a/dev-docs/docs/@excalidraw/excalidraw/api/utils/export.mdx +++ b/dev-docs/docs/@excalidraw/excalidraw/api/utils/export.mdx @@ -20,16 +20,16 @@ exportToCanvas({
getDimensions,
files,
exportPadding?: number;
-}: ExportOpts +}: ExportOptsexportToBlob(
- opts: ExportOpts & {
+ opts: ExportOpts & {
mimeType?: string,
quality?: number,
exportPadding?: number;
@@ -134,16 +134,16 @@ Returns a promise which resolves with a [blob](https://developer.mozilla.org/en-exportToSvg({
elements: - + ExcalidrawElement[] ,
appState: - AppState + AppState ,
exportPadding: number,
metadata: string,
files: - + BinaryFiles ,
}); @@ -151,10 +151,10 @@ exportToSvg({
| Name | Type | Default | Description | | --- | --- | --- | --- | -| elements | [Excalidraw Element []](https://github.com/excalidraw/excalidraw/blob/master/src/element/types.ts#L114) | | The elements to exported as `svg `| -| appState | [AppState](https://github.com/excalidraw/excalidraw/blob/master/src/types.ts#L95) | [defaultAppState](https://github.com/excalidraw/excalidraw/blob/master/src/appState.ts#L11) | The `appState` of the scene | +| elements | [Excalidraw Element []](https://github.com/excalidraw/excalidraw/blob/master/packages/excalidraw/element/types.ts#L114) | | The elements to exported as `svg `| +| appState | [AppState](https://github.com/excalidraw/excalidraw/blob/master/packages/excalidraw/types.ts#L95) | [defaultAppState](https://github.com/excalidraw/excalidraw/blob/master/packages/excalidraw/appState.ts#L11) | The `appState` of the scene | | exportPadding | number | 10 | The `padding` to be added on canvas | -| files | [BinaryFiles](https://github.com/excalidraw/excalidraw/blob/master/src/types.ts#L64) | undefined | The `files` added to the scene. | +| files | [BinaryFiles](https://github.com/excalidraw/excalidraw/blob/master/packages/excalidraw/types.ts#L64) | undefined | The `files` added to the scene. | This function returns a promise which resolves to `svg` of the exported drawing. @@ -164,7 +164,7 @@ This function returns a promise which resolves to `svg` of the exported drawing.exportToClipboard(| Prop | Type | Description | | ---- | ---- | ---- | -| `elements` | ImportedDataState["elements"] | The `elements` to be restored | -| [`localElements`](#localelements) | ExcalidrawElement[] | null | undefined | When `localElements` are supplied, they are used to ensure that existing restored elements reuse `version` (and increment it), and regenerate `versionNonce`. | +| `elements` | ImportedDataState["elements"] | The `elements` to be restored | +| [`localElements`](#localelements) | ExcalidrawElement[] | null | undefined | When `localElements` are supplied, they are used to ensure that existing restored elements reuse `version` (and increment it), and regenerate `versionNonce`. | | [`opts`](#opts) | `Object` | The extra optional parameter to configure restored elements #### localElements @@ -70,15 +70,15 @@ Parameter `refreshDimensions` indicates whether we should also `recalculate` tex
- opts: ExportOpts & {
+ opts: ExportOpts & {
mimeType?: string,
quality?: number;
type: 'png' | 'svg' |'json'
diff --git a/dev-docs/docs/@excalidraw/excalidraw/api/utils/restore.mdx b/dev-docs/docs/@excalidraw/excalidraw/api/utils/restore.mdx index 665a1ef9f..3f2546483 100644 --- a/dev-docs/docs/@excalidraw/excalidraw/api/utils/restore.mdx +++ b/dev-docs/docs/@excalidraw/excalidraw/api/utils/restore.mdx @@ -8,7 +8,7 @@ id: "restore" **_Signature_**-restoreAppState(appState: ImportedDataState["appState"],**_How to use_** @@ -17,7 +17,7 @@ restoreAppState(appState: restoreElements( - elements: ImportedDataState["elements"],
localAppState: Partial<AppState> | null): AppState +restoreAppState(appState: ImportedDataState["appState"],
localAppState: Partial<AppState> | null): AppState
- localElements: ExcalidrawElement[] | null | undefined): ExcalidrawElement[],
+ elements: ImportedDataState["elements"],
+ localElements: ExcalidrawElement[] | null | undefined): ExcalidrawElement[],
opts: { refreshDimensions?: boolean, repairBindings?: boolean }
)restore( - data: ImportedDataState,-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`. +See [`restoreAppState()`](https://github.com/excalidraw/excalidraw/blob/master/packages/excalidraw/packages/excalidraw/README.md#restoreAppState) about `localAppState`, and [`restoreElements()`](https://github.com/excalidraw/excalidraw/blob/master/packages/excalidraw/packages/excalidraw/README.md#restoreElements) about `localElements`. **_How to use_** @@ -93,7 +93,7 @@ This function makes sure elements and state is set to appropriate values and set **_Signature_**
- localAppState: Partial<AppState> | null | undefined,
- localElements: ExcalidrawElement[] | null | undefined
): DataState
+ data: ImportedDataState,
+ localAppState: Partial<AppState> | null | undefined,
+ localElements: ExcalidrawElement[] | null | undefined
): DataState
opts: { refreshDimensions?: boolean, repairBindings?: boolean }
)-restoreLibraryItems(libraryItems: ImportedDataState["libraryItems"],diff --git a/dev-docs/docs/@excalidraw/excalidraw/api/utils/utils-intro.md b/dev-docs/docs/@excalidraw/excalidraw/api/utils/utils-intro.md index 9f3d3287c..69bd88a83 100644 --- a/dev-docs/docs/@excalidraw/excalidraw/api/utils/utils-intro.md +++ b/dev-docs/docs/@excalidraw/excalidraw/api/utils/utils-intro.md @@ -8,7 +8,7 @@ These are pure Javascript functions exported from the @excalidraw/excalidraw [`@ ### serializeAsJSON -Takes the scene elements and state and returns a JSON string. `Deleted` elements as well as most properties from `AppState` are removed from the resulting JSON. (see [`serializeAsJSON()`](https://github.com/excalidraw/excalidraw/blob/master/src/data/json.ts#L42) source for details). +Takes the scene elements and state and returns a JSON string. `Deleted` elements as well as most properties from `AppState` are removed from the resulting JSON. (see [`serializeAsJSON()`](https://github.com/excalidraw/excalidraw/blob/master/packages/excalidraw/data/json.ts#L42) source for details). If you want to overwrite the `source` field in the `JSON` string, you can set `window.EXCALIDRAW_EXPORT_SOURCE` to the desired value. @@ -16,8 +16,8 @@ If you want to overwrite the `source` field in the `JSON` string, you can set `w
+restoreLibraryItems(libraryItems: ImportedDataState["libraryItems"],
defaultStatus: "published" | "unpublished")serializeAsJSON({@@ -37,7 +37,7 @@ If you want to overwrite the source field in the JSON string, you can set `windo
- elements: ExcalidrawElement[],
- appState: AppState,
+ elements: ExcalidrawElement[],
+ appState: AppState,
}): stringserializeLibraryAsJSON( - libraryItems: LibraryItems[]) + libraryItems: LibraryItems[])**How to use** @@ -53,7 +53,7 @@ Returns `true` if element is invisibly small (e.g. width & height are zero). **_Signature_**-isInvisiblySmallElement(element: ExcalidrawElement): boolean +isInvisiblySmallElement(element: ExcalidrawElement): boolean**How to use** @@ -80,10 +80,10 @@ excalidrawAPI.updateScene(scene);loadFromBlob(### loadLibraryFromBlob @@ -130,10 +130,10 @@ if (contents.type === MIME_TYPES.excalidraw) {
blob: Blob,
- localAppState: AppState | null,
- localElements: ExcalidrawElement[] | null,
+ localAppState: AppState | null,
+ localElements: ExcalidrawElement[] | null,
fileHandle?: FileSystemHandle | null
-) => Promise<RestoredDataState> +) => Promise<RestoredDataState>loadSceneOrLibraryFromBlob(### getFreeDrawSvgPath @@ -149,7 +149,7 @@ import { getFreeDrawSvgPath } from "@excalidraw/excalidraw"; **Signature**
blob: Blob,
- localAppState: AppState | null,
- localElements: ExcalidrawElement[] | null,
+ localAppState: AppState | null,
+ localElements: ExcalidrawElement[] | null,
fileHandle?: FileSystemHandle | null
-) => Promise<{ type: string, data: RestoredDataState | ImportedLibraryState}> +) => Promise<{ type: string, data: RestoredDataState | ImportedLibraryState}>-getFreeDrawSvgPath(element: ExcalidrawFreeDrawElement) +getFreeDrawSvgPath(element: ExcalidrawFreeDrawElement)### isLinearElement @@ -165,7 +165,7 @@ import { isLinearElement } from "@excalidraw/excalidraw"; **Signature**-isLinearElement(elementType?: ExcalidrawElement): boolean +isLinearElement(elementType?: ExcalidrawElement): boolean### getNonDeletedElements @@ -181,7 +181,7 @@ import { getNonDeletedElements } from "@excalidraw/excalidraw"; **Signature**-getNonDeletedElements(elements: readonly ExcalidrawElement[]): as readonly NonDeletedExcalidrawElement[] +getNonDeletedElements(elements: readonly ExcalidrawElement[]): as readonly NonDeletedExcalidrawElement[]### mergeLibraryItems @@ -196,9 +196,9 @@ import { mergeLibraryItems } from "@excalidraw/excalidraw";mergeLibraryItems(### parseLibraryTokensFromUrl @@ -239,8 +239,8 @@ export const App = () => {
- localItems: LibraryItems,
- otherItems: LibraryItems
-): LibraryItems + localItems: LibraryItems,
+ otherItems: LibraryItems
+): LibraryItemsuseHandleLibrary(opts: {@@ -253,7 +253,7 @@ This function returns the current `scene` version. **_Signature_**
- excalidrawAPI: ExcalidrawAPI,
- getInitialLibraryItems?: () => LibraryItemsSource
+ excalidrawAPI: ExcalidrawAPI,
+ getInitialLibraryItems?: () => LibraryItemsSource
});-getSceneVersion(elements: ExcalidrawElement[]) +getSceneVersion(elements: ExcalidrawElement[])**How to use** @@ -274,7 +274,7 @@ import { sceneCoordsToViewportCoords } from "@excalidraw/excalidraw";sceneCoordsToViewportCoords({ sceneX: number, sceneY: number },### viewportCoordsToSceneCoords @@ -289,7 +289,7 @@ import { viewportCoordsToSceneCoords } from "@excalidraw/excalidraw";
- appState: AppState
): { x: number, y: number } + appState: AppState
): { x: number, y: number }viewportCoordsToSceneCoords({ clientX: number, clientY: number },### useDevice @@ -350,8 +350,8 @@ To help with localization, we export the following. | name | type | | --- | --- | | `defaultLang` | `string` | -| `languages` | [`Language[]`](https://github.com/excalidraw/excalidraw/blob/master/src/i18n.ts#L15) | -| `useI18n` | [`() => { langCode, t }`](https://github.com/excalidraw/excalidraw/blob/master/src/i18n.ts#L15) | +| `languages` | [`Language[]`](https://github.com/excalidraw/excalidraw/blob/master/packages/excalidraw/i18n.ts#L15) | +| `useI18n` | [`() => { langCode, t }`](https://github.com/excalidraw/excalidraw/blob/master/packages/excalidraw/i18n.ts#L15) | ```js import { defaultLang, languages, useI18n } from "@excalidraw/excalidraw"; diff --git a/dev-docs/docs/@excalidraw/excalidraw/customizing-styles.mdx b/dev-docs/docs/@excalidraw/excalidraw/customizing-styles.mdx index 9e0f9fcdf..ea9073c1c 100644 --- a/dev-docs/docs/@excalidraw/excalidraw/customizing-styles.mdx +++ b/dev-docs/docs/@excalidraw/excalidraw/customizing-styles.mdx @@ -21,7 +21,7 @@ Most notably, you can customize the primary colors, by overriding these variable - `--color-primary-light` - `--color-primary-contrast-offset` — a slightly darker (in light mode), or lighter (in dark mode) `--color-primary` color to fix contrast issues (see [Chubb illusion](https://en.wikipedia.org/wiki/Chubb_illusion)). It will fall back to `--color-primary` if not present. -For a complete list of variables, check [theme.scss](https://github.com/excalidraw/excalidraw/blob/master/src/css/theme.scss), though most of them will not make sense to override. +For a complete list of variables, check [theme.scss](https://github.com/excalidraw/excalidraw/blob/master/packages/excalidraw/css/theme.scss), though most of them will not make sense to override. ```css showLineNumbers .custom-styles .excalidraw { diff --git a/dev-docs/docs/@excalidraw/excalidraw/development.mdx b/dev-docs/docs/@excalidraw/excalidraw/development.mdx index 2e73d5731..3c405a7d9 100644 --- a/dev-docs/docs/@excalidraw/excalidraw/development.mdx +++ b/dev-docs/docs/@excalidraw/excalidraw/development.mdx @@ -13,7 +13,7 @@ To start the example app using the `@excalidraw/excalidraw` package, follow the 1. Install the dependencies ```bash - cd src/packages/excalidraw && yarn + cd packages/excalidraw && yarn ``` 2. Start the example app diff --git a/dev-docs/docs/@excalidraw/excalidraw/faq.mdx b/dev-docs/docs/@excalidraw/excalidraw/faq.mdx index 5c66a603f..e9c6a81d1 100644 --- a/dev-docs/docs/@excalidraw/excalidraw/faq.mdx +++ b/dev-docs/docs/@excalidraw/excalidraw/faq.mdx @@ -39,7 +39,7 @@ Since Vite removes env variables by default, you can update the vite config to e ``` define: { - "process.env.IS_PREACT": process.env.IS_PREACT, + "process.env.IS_PREACT": JSON.stringify("true"), }, ``` diff --git a/dev-docs/docs/@excalidraw/excalidraw/integration.mdx b/dev-docs/docs/@excalidraw/excalidraw/integration.mdx index aa8e002c5..d6bf3fd0d 100644 --- a/dev-docs/docs/@excalidraw/excalidraw/integration.mdx +++ b/dev-docs/docs/@excalidraw/excalidraw/integration.mdx @@ -32,15 +32,9 @@ function App() { ### Next.js -Since _Excalidraw_ doesn't support server side rendering, you should render the component once the host is `mounted`. +Since Excalidraw doesn't support `server side rendering` so it should be rendered only on `client`. The way to achieve this in next.js is using `next.js dynamic import`. -Here are two ways on how you can render **Excalidraw** on **Next.js**. - - - -1. Using **Next.js Dynamic** import [Recommended]. - -Since Excalidraw doesn't support server side rendering so you can also use `dynamic import` to render by setting `ssr` to `false`. +If you want to only import `Excalidraw` component you can do :point_down: ```jsx showLineNumbers import dynamic from "next/dynamic"; @@ -55,25 +49,88 @@ export default function App() { } ``` -Here is a working [demo](https://codesandbox.io/p/sandbox/excalidraw-with-next-dynamic-k8yjq2). +However the above component only works for named component exports. If you want to import some util / constant or something else apart from Excalidraw, then this approach will not work. Instead you can write a wrapper over Excalidraw and import the wrapper dynamically. +If you are using `pages router` then importing the wrapper dynamically would work, where as if you are using `app router` then you will have to also add `useClient` directive on top of the file in addition to dynamically importing the wrapper as shown :point_down: -2. Importing Excalidraw once **client** is rendered. +
- appState: AppState
): {x: number, y: number} + appState: AppState
): {x: number, y: number}+ + + +Here is a [source code](https://github.com/excalidraw/excalidraw/tree/master/examples/excalidraw/with-nextjs) for the example with app and pages router. You you can try it out [here](https://excalidraw-package-example-with-nextjs-gh6smrdnq-excalidraw.vercel.app/). -Here is a working [demo](https://codesandbox.io/p/sandbox/excalidraw-with-next-5xb3d) The `types` are available at `@excalidraw/excalidraw/types`, you can view [example for typescript](https://codesandbox.io/s/excalidraw-types-9h2dm) @@ -93,7 +150,7 @@ Since Vite removes env variables by default, you can update the vite config to e ``` define: { - "process.env.IS_PREACT": process.env.IS_PREACT, + "process.env.IS_PREACT": JSON.stringify("true"), }, ``` ::: @@ -148,7 +205,7 @@ import TabItem from "@theme/TabItem";-```jsx showLineNumbers -import { useState, useEffect } from "react"; -export default function App() { - const [Excalidraw, setExcalidraw] = useState(null); - useEffect(() => { - import("@excalidraw/excalidraw").then((comp) => - setExcalidraw(comp.Excalidraw), + ```jsx showLineNumbers + "use client"; + import { Excalidraw. convertToExcalidrawElements } from "@excalidraw/excalidraw"; + + import "@excalidraw/excalidraw/index.css"; + + const ExcalidrawWrapper: React.FC = () => { + console.info(convertToExcalidrawElements([{ + type: "rectangle", + id: "rect-1", + width: 186.47265625, + height: 141.9765625, + },])); + return ( + + ); - }, []); - return <>{Excalidraw && + +}>; -} -``` + }; + export default ExcalidrawWrapper; + ``` + + + + ```jsx showLineNumbers + import dynamic from "next/dynamic"; + + // Since client components get prerenderd on server as well hence importing + // the excalidraw stuff dynamically with ssr false + + const ExcalidrawWrapper = dynamic( + async () => (await import("../excalidrawWrapper")).default, + { + ssr: false, + }, + ); + + export default function Page() { + return ( + + ++ ); + } + ``` + + + ```jsx showLineNumbers + import dynamic from "next/dynamic"; + + // Since client components get prerenderd on server as well hence importing + // the excalidraw stuff dynamically with ssr false + + const ExcalidrawWrapper = dynamic( + async () => (await import("../excalidrawWrapper")).default, + { + ssr: false, + }, + ); + + export default function Page() { + return ( + ++ ); + } + ``` + + Excalidraw Embed Example
- +