mirror of
https://github.com/excalidraw/excalidraw.git
synced 2025-05-03 10:00:07 -04:00
feat: Export THEME from the package (#4055)
* Use Theme type everywhere * Rename Appearance type to Theme for consistency * Reorder headers in readme The host don't need to pass hardcoded strings any more and instead can use the exported constant
This commit is contained in:
Aakansha Doshi
GitHub
parent
be2da9539e
commit
463857ad9a
15 changed files with 582 additions and 559 deletions
|
|
@ -11,6 +11,20 @@ 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
|
||||
|
||||
### Features
|
||||
|
||||
- Export `THEME` constant from the package so host can use this when passing the theme
|
||||
|
||||
#### BREAKING CHANGE
|
||||
|
||||
The `Appearance` type is now removed and renamed to `Theme` so `Theme` type needs to be used.
|
||||
|
||||
---
|
||||
|
||||
## 0.10.0 (2021-10-13)
|
||||
|
||||
## Excalidraw API
|
||||
|
|
|
|||
|
|
@ -371,7 +371,7 @@ To view the full example visit :point_down:
|
|||
| [`zenModeEnabled`](#zenModeEnabled) | boolean | | This implies if the zen mode is enabled |
|
||||
| [`gridModeEnabled`](#gridModeEnabled) | boolean | | This implies if the grid mode is enabled |
|
||||
| [`libraryReturnUrl`](#libraryReturnUrl) | string | | What URL should [libraries.excalidraw.com](https://libraries.excalidraw.com) be installed to |
|
||||
| [`theme`](#theme) | `light` or `dark` | | The theme of the Excalidraw component |
|
||||
| [`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 | null) => boolean</pre> | | Callback to be triggered if passed when the something is pasted in to the scene |
|
||||
|
|
@ -564,7 +564,7 @@ If supplied, this URL will be used when user tries to install a library from [li
|
|||
|
||||
#### `theme`
|
||||
|
||||
This prop controls Excalidraw's theme. When supplied, the value takes precedence over `intialData.appState.theme`, the theme will be fully controlled by the host app, and users won't be able to toggle it from within the app.
|
||||
This prop controls Excalidraw's theme. When supplied, the value takes precedence over `intialData.appState.theme`, the theme will be fully controlled by the host app, and users won't be able to toggle it from within the app. You can use [`THEME`](#THEME-1) to specify the theme.
|
||||
|
||||
#### `name`
|
||||
|
||||
|
|
@ -612,11 +612,7 @@ This callback must return a `boolean` value or a [promise](https://developer.moz
|
|||
|
||||
In case you want to prevent the excalidraw paste action you must return `false`, it will stop the native excalidraw clipboard management flow (nothing will be pasted into the scene).
|
||||
|
||||
### Does it support collaboration ?
|
||||
|
||||
No, Excalidraw package doesn't come with collaboration built in, since the implementation is specific to each host app. We expose APIs which you can use to communicate with Excalidraw which you can use to implement it. You can check our own implementation [here](https://github.com/excalidraw/excalidraw/blob/master/src/excalidraw-app/index.tsx).
|
||||
|
||||
### importLibrary
|
||||
#### `importLibrary`
|
||||
|
||||
Imports library from given URL. You should call this on `hashchange`, passing the `addLibrary` value if you detect it as shown below. Optionally pass a CSRF `token` to skip prompting during installation (retrievable via `token` key from the url coming from [https://libraries.excalidraw.com](https://libraries.excalidraw.com/)).
|
||||
|
||||
|
|
@ -638,17 +634,17 @@ useEffect(() => {
|
|||
|
||||
Try out the [Demo](#Demo) to see it in action.
|
||||
|
||||
### detectScroll
|
||||
#### `detectScroll`
|
||||
|
||||
Indicates whether Excalidraw should listen for `scroll` event on the nearest scrollable container in the DOM tree and recompute the coordinates (e.g. to correctly handle the cursor) when the component's position changes. You can disable this when you either know this doesn't affect your app or you want to take care of it yourself (calling the [`refresh()`](#ref) method).
|
||||
|
||||
### handleKeyboardGlobally
|
||||
#### `handleKeyboardGlobally`
|
||||
|
||||
Indicates whether to bind keyboard events to `document`. Disabled by default, meaning the keyboard events are bound to the Excalidraw component. This allows for multiple Excalidraw components to live on the same page, and ensures that Excalidraw keyboard handling doesn't collide with your app's (or the browser) when the component isn't focused.
|
||||
|
||||
Enable this if you want Excalidraw to handle keyboard even if the component isn't focused (e.g. a user is interacting with the navbar, sidebar, or similar).
|
||||
|
||||
### onLibraryChange
|
||||
#### `onLibraryChange`
|
||||
|
||||
Ths callback if supplied will get triggered when the library is updated and has the below signature.
|
||||
|
||||
|
|
@ -658,58 +654,17 @@ Ths callback if supplied will get triggered when the library is updated and has
|
|||
|
||||
It is invoked with empty items when user clears the library. You can use this callback when you want to do something additional when library is updated for example persisting it to local storage.
|
||||
|
||||
### id
|
||||
#### `id`
|
||||
|
||||
The unique id of the excalidraw component. This can be used to identify the excalidraw component, for example importing the library items to the excalidraw component from where it was initiated when you have multiple excalidraw components rendered on the same page as shown in [multiple excalidraw demo](https://codesandbox.io/s/multiple-excalidraw-k1xx5).
|
||||
|
||||
### autoFocus
|
||||
#### `autoFocus`
|
||||
|
||||
This prop implies whether to focus the Excalidraw component on page load. Defaults to false.
|
||||
|
||||
### Extra API's
|
||||
### Does it support collaboration ?
|
||||
|
||||
#### `getSceneVersion`
|
||||
|
||||
**How to use**
|
||||
|
||||
<pre>
|
||||
import { getSceneVersion } from "@excalidraw/excalidraw-next";
|
||||
getSceneVersion(elements: <a href="https://github.com/excalidraw/excalidraw/blob/master/src/element/types.ts#L78">ExcalidrawElement[]</a>)
|
||||
</pre>
|
||||
|
||||
This function returns the current scene version.
|
||||
|
||||
#### `isInvisiblySmallElement`
|
||||
|
||||
**_Signature_**
|
||||
|
||||
<pre>
|
||||
isInvisiblySmallElement(element: <a href="https://github.com/excalidraw/excalidraw/blob/master/src/element/types.ts#L78">ExcalidrawElement</a>): boolean
|
||||
</pre>
|
||||
|
||||
**How to use**
|
||||
|
||||
```js
|
||||
import { isInvisiblySmallElement } from "@excalidraw/excalidraw-next";
|
||||
```
|
||||
|
||||
Returns `true` if element is invisibly small (e.g. width & height are zero).
|
||||
|
||||
#### `getElementMap`
|
||||
|
||||
**_Signature_**
|
||||
|
||||
<pre>
|
||||
getElementsMap(elements: <a href="https://github.com/excalidraw/excalidraw/blob/master/src/element/types.ts#L78">ExcalidrawElement[]</a>): {[id: string]: <a href="https://github.com/excalidraw/excalidraw/blob/master/src/element/types.ts#L78">ExcalidrawElement</a>}
|
||||
</pre>
|
||||
|
||||
**How to use**
|
||||
|
||||
```js
|
||||
import { getElementsMap } from "@excalidraw/excalidraw-next";
|
||||
```
|
||||
|
||||
This function returns an object where each element is mapped to its id.
|
||||
No, Excalidraw package doesn't come with collaboration built in, since the implementation is specific to each host app. We expose APIs which you can use to communicate with Excalidraw which you can use to implement it. You can check our own implementation [here](https://github.com/excalidraw/excalidraw/blob/master/src/excalidraw-app/index.tsx).
|
||||
|
||||
### Restore utilities
|
||||
|
||||
|
|
@ -767,19 +722,6 @@ import { restore } from "@excalidraw/excalidraw-next";
|
|||
|
||||
This function makes sure elements and state is set to appropriate values and set to default value if not present. It is a combination of [restoreElements](#restoreElements) and [restoreAppState](#restoreAppState).
|
||||
|
||||
#### `serializeAsJSON`
|
||||
|
||||
**_Signature_**
|
||||
|
||||
<pre>
|
||||
serializeAsJSON({
|
||||
elements: <a href="https://github.com/excalidraw/excalidraw/blob/master/src/element/types.ts#L78">ExcalidrawElement[]</a>,
|
||||
appState: <a href="https://github.com/excalidraw/excalidraw/blob/master/src/types.ts#L42">AppState</a>,
|
||||
}): string
|
||||
</pre>
|
||||
|
||||
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#L16) source for details).
|
||||
|
||||
### Export utilities
|
||||
|
||||
#### `exportToCanvas`
|
||||
|
|
@ -864,7 +806,113 @@ This function returns a promise which resolves to svg of the exported drawing.
|
|||
| exportWithDarkMode | boolean | false | Indicates whether to export with dark mode |
|
||||
| exportEmbedScene | boolean | false | Indicates whether scene data should be embedded in svg. This will increase the svg size. |
|
||||
|
||||
### FONT_FAMILY
|
||||
### Extra API's
|
||||
|
||||
#### `serializeAsJSON`
|
||||
|
||||
**_Signature_**
|
||||
|
||||
<pre>
|
||||
serializeAsJSON({
|
||||
elements: <a href="https://github.com/excalidraw/excalidraw/blob/master/src/element/types.ts#L78">ExcalidrawElement[]</a>,
|
||||
appState: <a href="https://github.com/excalidraw/excalidraw/blob/master/src/types.ts#L42">AppState</a>,
|
||||
}): string
|
||||
</pre>
|
||||
|
||||
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#L16) source for details).
|
||||
|
||||
#### `getSceneVersion`
|
||||
|
||||
**How to use**
|
||||
|
||||
<pre>
|
||||
import { getSceneVersion } from "@excalidraw/excalidraw-next";
|
||||
getSceneVersion(elements: <a href="https://github.com/excalidraw/excalidraw/blob/master/src/element/types.ts#L78">ExcalidrawElement[]</a>)
|
||||
</pre>
|
||||
|
||||
This function returns the current scene version.
|
||||
|
||||
#### `isInvisiblySmallElement`
|
||||
|
||||
**_Signature_**
|
||||
|
||||
<pre>
|
||||
isInvisiblySmallElement(element: <a href="https://github.com/excalidraw/excalidraw/blob/master/src/element/types.ts#L78">ExcalidrawElement</a>): boolean
|
||||
</pre>
|
||||
|
||||
**How to use**
|
||||
|
||||
```js
|
||||
import { isInvisiblySmallElement } from "@excalidraw/excalidraw-next";
|
||||
```
|
||||
|
||||
Returns `true` if element is invisibly small (e.g. width & height are zero).
|
||||
|
||||
#### `getElementMap`
|
||||
|
||||
**_Signature_**
|
||||
|
||||
<pre>
|
||||
getElementsMap(elements: <a href="https://github.com/excalidraw/excalidraw/blob/master/src/element/types.ts#L78">ExcalidrawElement[]</a>): {[id: string]: <a href="https://github.com/excalidraw/excalidraw/blob/master/src/element/types.ts#L78">ExcalidrawElement</a>}
|
||||
</pre>
|
||||
|
||||
**How to use**
|
||||
|
||||
```js
|
||||
import { getElementsMap } from "@excalidraw/excalidraw-next";
|
||||
```
|
||||
|
||||
This function returns an object where each element is mapped to its id.
|
||||
|
||||
#### `loadLibraryFromBlob`
|
||||
|
||||
```js
|
||||
import { loadLibraryFromBlob } from "@excalidraw/excalidraw-next";
|
||||
```
|
||||
|
||||
**_Signature_**
|
||||
|
||||
<pre>
|
||||
loadLibraryFromBlob(blob: <a href="https://developer.mozilla.org/en-US/docs/Web/API/Blob">Blob</a>)
|
||||
</pre>
|
||||
|
||||
This function loads the library from the blob.
|
||||
|
||||
#### `loadFromBlob`
|
||||
|
||||
**How to use**
|
||||
|
||||
```js
|
||||
import { loadFromBlob } from "@excalidraw/excalidraw-next";
|
||||
```
|
||||
|
||||
**Signature**
|
||||
|
||||
<pre>
|
||||
loadFromBlob(blob: <a href="https://developer.mozilla.org/en-US/docs/Web/API/Blob">Blob</a>, localAppState: <a href="https://github.com/excalidraw/excalidraw/blob/master/src/types.ts#L42">AppState</a> | null)
|
||||
</pre>
|
||||
|
||||
This function loads the scene data from the blob. If you pass `localAppState`, `localAppState` value will be preferred over the `appState` derived from `blob`
|
||||
|
||||
#### `getFreeDrawSvgPath`
|
||||
|
||||
**How to use**
|
||||
|
||||
```js
|
||||
import { getFreeDrawSvgPath } from "@excalidraw/excalidraw-next";
|
||||
```
|
||||
|
||||
**Signature**
|
||||
|
||||
<pre>
|
||||
getFreeDrawSvgPath(element: <a href="https://github.com/excalidraw/excalidraw/blob/master/src/element/types.ts#L127">ExcalidrawFreeDrawElement</a>
|
||||
</pre>
|
||||
|
||||
This function returns the free draw svg path for the element.
|
||||
|
||||
### Exported constants
|
||||
|
||||
#### `FONT_FAMILY`
|
||||
|
||||
**How to use**
|
||||
|
||||
|
|
@ -882,51 +930,22 @@ import { FONT_FAMILY } from "@excalidraw/excalidraw-next";
|
|||
|
||||
Defaults to `FONT_FAMILY.Virgil` unless passed in `initialData.appState.currentItemFontFamily`.
|
||||
|
||||
### loadLibraryFromBlob
|
||||
|
||||
```js
|
||||
import { loadLibraryFromBlob } from "@excalidraw/excalidraw-next";
|
||||
```
|
||||
|
||||
**_Signature_**
|
||||
|
||||
<pre>
|
||||
loadLibraryFromBlob(blob: <a href="https://developer.mozilla.org/en-US/docs/Web/API/Blob">Blob</a>)
|
||||
</pre>
|
||||
|
||||
This function loads the library from the blob.
|
||||
|
||||
### loadFromBlob
|
||||
#### `THEME`
|
||||
|
||||
**How to use**
|
||||
|
||||
```js
|
||||
import { loadFromBlob } from "@excalidraw/excalidraw-next";
|
||||
import { THEME } from "@excalidraw/excalidraw-next";
|
||||
```
|
||||
|
||||
**Signature**
|
||||
`THEME` contains all the themes supported by `Excalidraw` as explained below
|
||||
|
||||
<pre>
|
||||
loadFromBlob(blob: <a href="https://developer.mozilla.org/en-US/docs/Web/API/Blob">Blob</a>, localAppState: <a href="https://github.com/excalidraw/excalidraw/blob/master/src/types.ts#L42">AppState</a> | null)
|
||||
</pre>
|
||||
| Theme | Description |
|
||||
| ----- | --------------- |
|
||||
| LIGHT | The light theme |
|
||||
| DARK | The Dark theme |
|
||||
|
||||
This function loads the scene data from the blob. If you pass `localAppState`, `localAppState` value will be preferred over the `appState` derived from `blob`
|
||||
|
||||
### getFreeDrawSvgPath
|
||||
|
||||
**How to use**
|
||||
|
||||
```js
|
||||
import { getFreeDrawSvgPath } from "@excalidraw/excalidraw-next";
|
||||
```
|
||||
|
||||
**Signature**
|
||||
|
||||
<pre>
|
||||
getFreeDrawSvgPath(element: <a href="https://github.com/excalidraw/excalidraw/blob/master/src/element/types.ts#L127">ExcalidrawFreeDrawElement</a>
|
||||
</pre>
|
||||
|
||||
This function returns the free draw svg path for the element.
|
||||
Defaults to `THEME.LIGHT` unless passed in `initialData.appState.theme`
|
||||
|
||||
## Need help?
|
||||
|
||||
|
|
|
|||
|
|
@ -183,4 +183,4 @@ export {
|
|||
loadFromBlob,
|
||||
getFreeDrawSvgPath,
|
||||
} from "../../packages/utils";
|
||||
export { FONT_FAMILY } from "../../constants";
|
||||
export { FONT_FAMILY, THEME } from "../../constants";
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue