Skip to content

Commit ddb7585

Browse files
ad1992dwelle
ad1992
and
dwelle
authored
docs: Docs for v0.17.0 🚀 (#7248)
* feat: add docs for getCommonBounds * docs: add docs for frames api support * docs: update docs for regenerateIds opts in convertToExcalidrawElements * add docs for ref removal * add docs for lock support and insertOnCanvasDirectly in setActiveTool * fix broken links * update docs for next js support * update docs for Preact * add faq * docs: add `onChange`, `onPointerDown`, `onPointerUp` docs * docs: update `useDevice` docs * update docs for disabling image tool * add docs for withinBounds helpers * fix lint * upgrade excal * add docusaurus2-dotenv for expose env vars * fix env variable and upgrade excal * Update dev-docs/docs/@excalidraw/excalidraw/api/excalidraw-element-skeleton.mdx Co-authored-by: David Luzar <5153846+dwelle@users.noreply.github.com> * update docs Co-authored-by: David Luzar <5153846+dwelle@users.noreply.github.com> * update docs for process.env --------- Co-authored-by: dwelle <5153846+dwelle@users.noreply.github.com>
1 parent 111a48f commit ddb7585

File tree

13 files changed

+391
-132
lines changed

13 files changed

+391
-132
lines changed

‎dev-docs/docs/@excalidraw/excalidraw/api/children-components/sidebar.mdx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -80,7 +80,7 @@ A given tab trigger button that switches to a given sidebar tab. It must be rend
8080
| `className` | `string` | No | |
8181
| `style` | `React.CSSProperties` | No | |
8282

83-
You can use the [`ref.toggleSidebar({ name: "custom" })`](/docs/@excalidraw/excalidraw/api/props/ref#toggleSidebar) api to control the sidebar, but we export a trigger button to make UI use cases easier.
83+
You can use the [`ref.toggleSidebar({ name: "custom" })`](/docs/@excalidraw/excalidraw/api/props/excalidraw-api#toggleSidebar) api to control the sidebar, but we export a trigger button to make UI use cases easier.
8484

8585
## Example
8686

‎dev-docs/docs/@excalidraw/excalidraw/api/excalidraw-element-skeleton.mdx

Lines changed: 55 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -10,27 +10,31 @@ The [`ExcalidrawElementSkeleton`](https://github.com/excalidraw/excalidraw/blob/
1010

1111
**_Signature_**
1212

13-
<pre>
14-
convertToExcalidrawElements(elements:{" "}
15-
<a href="https://github.com/excalidraw/excalidraw/blob/master/src/data/transform.ts#L133">
16-
ExcalidrawElementSkeleton
17-
</a>
18-
)
19-
</pre>
13+
```ts
14+
convertToExcalidrawElements(
15+
elements: ExcalidrawElementSkeleton,
16+
opts?: { regenerateIds: boolean }
17+
): ExcalidrawElement[]
18+
```
19+
20+
| Name | Type | Default | Description |
21+
| --- | --- | --- | --- |
22+
| `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. |
23+
| `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`. |
2024

2125
**_How to use_**
2226

2327
```js
2428
import { convertToExcalidrawElements } from "@excalidraw/excalidraw";
2529
```
2630

27-
This function converts the Excalidraw Element Skeleton to excalidraw elements which could be then rendered on the canvas. Hence calling this function is necessary before passing it to APIs like [`initialData`](https://docs.excalidraw.com/docs/@excalidraw/excalidraw/api/props/initialdata), [`updateScene`](https://docs.excalidraw.com/docs/@excalidraw/excalidraw/api/props/ref#updatescene) if you are using the Skeleton API
31+
This function converts the Excalidraw Element Skeleton to excalidraw elements which could be then rendered on the canvas. Hence calling this function is necessary before passing it to APIs like [`initialData`](https://docs.excalidraw.com/docs/@excalidraw/excalidraw/api/props/initialdata), [`updateScene`](https://docs.excalidraw.com/docs/@excalidraw/excalidraw/api/props/excalidraw-api#updatescene) if you are using the Skeleton API
2832

2933
## Supported Features
3034

3135
### Rectangle, Ellipse, and Diamond
3236

33-
To create these shapes you need to pass its `type` and `x` and `y` coordinates for position. The rest of the attributes are optional_.
37+
To create these shapes you need to pass its `type` and `x` and `y` coordinates for position. The rest of the attributes are optional\_.
3438

3539
For the Skeleton API to work, `convertToExcalidrawElements` needs to be called before passing it to Excalidraw Component via initialData, updateScene or any such API.
3640

@@ -427,3 +431,45 @@ convertToExcalidrawElements([
427431
```
428432

429433
![image](https://github.com/excalidraw/excalidraw/assets/11256141/a8b047c8-2eed-4aea-82a2-e1e6bbddb8d4)
434+
435+
### Frames
436+
437+
To create a frame, you need to pass `type`, `children` (list of Excalidraw element ids). The rest of the attributes are optional.
438+
439+
```ts
440+
{
441+
type: "frame";
442+
children: readonly ExcalidrawElement["id"][];
443+
name?: string;
444+
} & Partial<ExcalidrawFrameElement>);
445+
```
446+
447+
```ts
448+
convertToExcalidrawElements([
449+
{
450+
"type": "rectangle",
451+
"x": 10,
452+
"y": 10,
453+
"strokeWidth": 2,
454+
"id": "1"
455+
},
456+
{
457+
"type": "diamond",
458+
"x": 120,
459+
"y": 20,
460+
"backgroundColor": "#fff3bf",
461+
"strokeWidth": 2,
462+
"label": {
463+
"text": "HELLO EXCALIDRAW",
464+
"strokeColor": "#099268",
465+
"fontSize": 30
466+
},
467+
"id": "2"
468+
},
469+
{
470+
"type": "frame",
471+
"children": ["1", "2"],
472+
"name": "My frame"
473+
}]
474+
}
475+
```

‎dev-docs/docs/@excalidraw/excalidraw/api/props/ref.mdx renamed to ‎dev-docs/docs/@excalidraw/excalidraw/api/props/excalidraw-api.mdx

Lines changed: 89 additions & 70 deletions
Original file line numberDiff line numberDiff line change
@@ -1,27 +1,26 @@
1-
# ref
1+
# excalidrawAPI
22

33
<pre>
4-
<a href="https://reactjs.org/docs/refs-and-the-dom.html#creating-refs">
5-
createRef
6-
</a>{" "}
7-
&#124;{" "}
8-
<a href="https://reactjs.org/docs/hooks-reference.html#useref">useRef</a>{" "}
9-
&#124;{" "}
10-
<a href="https://reactjs.org/docs/refs-and-the-dom.html#callback-refs">
11-
callbackRef
12-
</a>{" "}
13-
&#124; <br />
14-
&#123; current: &#123; readyPromise: <a href="https://github.com/excalidraw/excalidraw/blob/master/src/utils.ts#L460">
15-
resolvablePromise
16-
</a> } }
4+
(api:{" "}
5+
<a href="https://github.com/excalidraw/excalidraw/blob/master/src/types.ts#L616">
6+
ExcalidrawAPI
7+
</a>
8+
) => void;
179
</pre>
1810

19-
You can pass a `ref` when you want to access some excalidraw APIs. We expose the below APIs:
11+
Once the callback is triggered, you will need to store the api in state to access it later.
12+
13+
```jsx showLineNumbers
14+
export default function App() {
15+
const [excalidrawAPI, setExcalidrawAPI] = useState(null);
16+
return <Excalidraw excalidrawAPI={{(api)=> setExcalidrawAPI(api)}} />;
17+
}
18+
```
19+
20+
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:
2021

2122
| API | Signature | Usage |
2223
| --- | --- | --- |
23-
| ready | `boolean` | This is set to true once Excalidraw is rendered |
24-
| [readyPromise](#readypromise) | `function` | This promise will be resolved with the api once excalidraw has rendered. This will be helpful when you want do some action on the host app once this promise resolves. For this to work you will have to pass ref as shown [here](#readypromise) |
2524
| [updateScene](#updatescene) | `function` | updates the scene with the sceneData |
2625
| [updateLibrary](#updatelibrary) | `function` | updates the scene with the sceneData |
2726
| [addFiles](#addfiles) | `function` | add files data to the appState |
@@ -39,54 +38,15 @@ You can pass a `ref` when you want to access some excalidraw APIs. We expose the
3938
| [setCursor](#setcursor) | `function` | This API can be used to set customise the mouse cursor on the canvas |
4039
| [resetCursor](#resetcursor) | `function` | This API can be used to reset to default mouse cursor on the canvas |
4140
| [toggleMenu](#togglemenu) | `function` | Toggles specific menus on/off |
41+
| [onChange](#onChange) | `function` | Subscribes to change events |
42+
| [onPointerDown](#onPointerDown) | `function` | Subscribes to `pointerdown` events |
43+
| [onPointerUp](#onPointerUp) | `function` | Subscribes to `pointerup` events |
4244

43-
## readyPromise
45+
:::info The `Ref` support has been removed in v0.17.0 so if you are using refs, please update the integration to use the `excalidrawAPI`.
4446

45-
<pre>
46-
const excalidrawRef = &#123; current:&#123; readyPromise:
47-
<a href="https://github.com/excalidraw/excalidraw/blob/master/src/utils.ts#L460">
48-
&nbsp;resolvablePromise
49-
</a>
50-
&nbsp;&#125; &#125;
51-
</pre>
52-
53-
Since plain object is passed as a `ref`, the `readyPromise` is resolved as soon as the component is mounted. Most of the time you will not need this unless you have a specific use case where you can't pass the `ref` in the react way and want to do some action on the host when this promise resolves.
54-
55-
```jsx showLineNumbers
56-
const resolvablePromise = () => {
57-
let resolve;
58-
let reject;
59-
const promise = new Promise((_resolve, _reject) => {
60-
resolve = _resolve;
61-
reject = _reject;
62-
});
63-
promise.resolve = resolve;
64-
promise.reject = reject;
65-
return promise;
66-
};
67-
68-
const App = () => {
69-
const excalidrawRef = useMemo(
70-
() => ({
71-
current: {
72-
readyPromise: resolvablePromise(),
73-
},
74-
}),
75-
[],
76-
);
47+
Additionally `ready` and `readyPromise` from the API have been discontinued. These APIs were found to be superfluous, and as part of the effort to streamline the APIs and maintain simplicity, they were removed in version v0.17.0.
7748

78-
useEffect(() => {
79-
excalidrawRef.current.readyPromise.then((api) => {
80-
console.log("loaded", api);
81-
});
82-
}, [excalidrawRef]);
83-
return (
84-
<div style={{ height: "500px" }}>
85-
<Excalidraw ref={excalidrawRef} />
86-
</div>
87-
);
88-
};
89-
```
49+
:::
9050

9151
## updateScene
9252

@@ -387,14 +347,25 @@ This API can be used to get the files present in the scene. It may contain files
387347

388348
This API has the below signature. It sets the `tool` passed in param as the active tool.
389349

390-
<pre>
391-
(tool: <br /> &#123; type:{" "}
392-
<a href="https://github.com/excalidraw/excalidraw/blob/master/src/shapes.tsx#L15">
393-
SHAPES
394-
</a>
395-
[number]["value"]&#124; "eraser" &#125; &#124;
396-
<br /> &#123; type: "custom"; customType: string &#125;) => void
397-
</pre>
350+
```ts
351+
(
352+
tool: (
353+
| (
354+
| { type: Exclude<ToolType, "image"> }
355+
| {
356+
type: Extract<ToolType, "image">;
357+
insertOnCanvasDirectly?: boolean;
358+
}
359+
)
360+
| { type: "custom"; customType: string }
361+
) & { locked?: boolean },
362+
) => {};
363+
```
364+
365+
| Name | Type | Default | Description |
366+
| --- | --- | --- | --- |
367+
| `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` |
368+
| `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 |
398369

399370
## setCursor
400371

@@ -421,3 +392,51 @@ This API is especially useful when you render a custom [`<Sidebar/>`](/docs/@exc
421392
```
422393

423394
This API can be used to reset to default mouse cursor.
395+
396+
## onChange
397+
398+
```tsx
399+
(
400+
callback: (
401+
elements: readonly ExcalidrawElement[],
402+
appState: AppState,
403+
files: BinaryFiles,
404+
) => void
405+
) => () => void
406+
```
407+
408+
Subscribes to change events, similar to [`props.onChange`](/docs/@excalidraw/excalidraw/api/props#onchange).
409+
410+
Returns an unsubscribe function.
411+
412+
## onPointerDown
413+
414+
```tsx
415+
(
416+
callback: (
417+
activeTool: AppState["activeTool"],
418+
pointerDownState: PointerDownState,
419+
event: React.PointerEvent<HTMLElement>,
420+
) => void,
421+
) => () => void
422+
```
423+
424+
Subscribes to canvas `pointerdown` events.
425+
426+
Returns an unsubscribe function.
427+
428+
## onPointerUp
429+
430+
```tsx
431+
(
432+
callback: (
433+
activeTool: AppState["activeTool"],
434+
pointerDownState: PointerDownState,
435+
event: PointerEvent,
436+
) => void,
437+
) => () => void
438+
```
439+
440+
Subscribes to canvas `pointerup` events.
441+
442+
Returns an unsubscribe function.

‎dev-docs/docs/@excalidraw/excalidraw/api/props/props.mdx

Lines changed: 30 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,11 @@
11
# Props
22

3-
All `props` are *optional*.
3+
All `props` are _optional_.
44

55
| Name | Type | Default | Description |
66
| --- | --- | --- | --- |
7-
| [`initialData`](/docs/@excalidraw/excalidraw/api/props/initialdata) | `object` &#124; `null` &#124; <code>Promise<object &#124; null></code> | `null` | The initial data with which app loads. |
8-
| [`ref`](/docs/@excalidraw/excalidraw/api/props/ref) | `object` | _ | `Ref` to be passed to Excalidraw |
7+
| [`initialData`](/docs/@excalidraw/excalidraw/api/props/initialdata) | `object` &#124; `null` &#124; <code>Promise<object &#124; null></code> | `null` | The initial data with which app loads. |
8+
| [`excalidrawAPI`](/docs/@excalidraw/excalidraw/api/props/excalidraw-api) | `function` | _ | Callback triggered with the excalidraw api once rendered |
99
| [`isCollaborating`](#iscollaborating) | `boolean` | _ | This indicates if the app is in `collaboration` mode |
1010
| [`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`. |
1111
| [`onPointerUpdate`](#onpointerupdate) | `function` | _ | Callback triggered when mouse pointer is updated. |
@@ -37,7 +37,7 @@ Beyond attributes that Excalidraw elements already support, you can store `custo
3737

3838
You can use this to add any extra information you need to keep track of.
3939

40-
You can add `customData` to elements when passing them as [`initialData`](/docs/@excalidraw/excalidraw/api/props/initialdata), or using [`updateScene`](/docs/@excalidraw/excalidraw/api/props/ref#updatescene) / [`updateLibrary`](/docs/@excalidraw/excalidraw/api/props/ref#updatelibrary) afterwards.
40+
You can add `customData` to elements when passing them as [`initialData`](/docs/@excalidraw/excalidraw/api/props/initialdata), or using [`updateScene`](/docs/@excalidraw/excalidraw/api/props/excalidraw-api#updatescene) / [`updateLibrary`](/docs/@excalidraw/excalidraw/api/props/excalidraw-api#updatelibrary) afterwards.
4141

4242
```js showLineNumbers
4343
{
@@ -93,8 +93,16 @@ This callback is triggered when mouse pointer is updated.
9393

9494
This prop if passed will be triggered on pointer down events and has the below signature.
9595

96+
9697
<pre>
97-
(activeTool: <a href="https://github.com/excalidraw/excalidraw/blob/master/src/types.ts#L115"> AppState["activeTool"]</a>, pointerDownState: <a href="https://github.com/excalidraw/excalidraw/blob/master/src/types.ts#L424">PointerDownState</a>) => void
98+
(activeTool:{" "}
99+
<a href="https://github.com/excalidraw/excalidraw/blob/master/src/types.ts#L115">
100+
{" "}
101+
AppState["activeTool"]
102+
</a>
103+
, pointerDownState: <a href="https://github.com/excalidraw/excalidraw/blob/master/src/types.ts#L424">
104+
PointerDownState
105+
</a>) => void
98106
</pre>
99107

100108
### onScrollChange
@@ -110,7 +118,11 @@ This prop if passed will be triggered when canvas is scrolled and has the below
110118
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.
111119

112120
<pre>
113-
(data: <a href="https://github.com/excalidraw/excalidraw/blob/master/src/clipboard.ts#L18">ClipboardData</a>, event: ClipboardEvent &#124; null) => boolean
121+
(data:{" "}
122+
<a href="https://github.com/excalidraw/excalidraw/blob/master/src/clipboard.ts#L18">
123+
ClipboardData
124+
</a>
125+
, event: ClipboardEvent &#124; null) => boolean
114126
</pre>
115127

116128
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.
@@ -136,8 +148,11 @@ It is invoked with empty items when user clears the library. You can use this ca
136148
This prop if passed will be triggered when clicked on `link`. To handle the redirect yourself (such as when using your own router for internal links), you must call `event.preventDefault()`.
137149

138150
<pre>
139-
(element: <a href="https://github.com/excalidraw/excalidraw/blob/master/src/element/types.ts#L114">ExcalidrawElement</a>,
140-
event: CustomEvent&lt;&#123; nativeEvent: MouseEvent }&gt;) => void
151+
(element:{" "}
152+
<a href="https://github.com/excalidraw/excalidraw/blob/master/src/element/types.ts#L114">
153+
ExcalidrawElement
154+
</a>
155+
, event: CustomEvent&lt;&#123; nativeEvent: MouseEvent }&gt;) => void
141156
</pre>
142157

143158
Example:
@@ -180,30 +195,30 @@ import { defaultLang, languages } from "@excalidraw/excalidraw";
180195

181196
### viewModeEnabled
182197

183-
This prop indicates whether the app is in `view mode`. When supplied, the value takes precedence over *intialData.appState.viewModeEnabled*, the `view mode` will be fully controlled by the host app, and users won't be able to toggle it from within the app.
198+
This prop indicates whether the app is in `view mode`. When supplied, the value takes precedence over _intialData.appState.viewModeEnabled_, the `view mode` will be fully controlled by the host app, and users won't be able to toggle it from within the app.
184199

185200
### zenModeEnabled
186201

187-
This prop indicates whether the app is in `zen mode`. When supplied, the value takes precedence over *intialData.appState.zenModeEnabled*, the `zen mode` will be fully controlled by the host app, and users won't be able to toggle it from within the app.
202+
This prop indicates whether the app is in `zen mode`. When supplied, the value takes precedence over _intialData.appState.zenModeEnabled_, the `zen mode` will be fully controlled by the host app, and users won't be able to toggle it from within the app.
188203

189204
### gridModeEnabled
190205

191-
This prop indicates whether the shows the grid. When supplied, the value takes precedence over *intialData.appState.gridModeEnabled*, the grid will be fully controlled by the host app, and users won't be able to toggle it from within the app.
206+
This prop indicates whether the shows the grid. When supplied, the value takes precedence over _intialData.appState.gridModeEnabled_, the grid will be fully controlled by the host app, and users won't be able to toggle it from within the app.
192207

193208
### libraryReturnUrl
194209

195210
If supplied, this URL will be used when user tries to install a library from [libraries.excalidraw.com](https://libraries.excalidraw.com).
196-
Defaults to *window.location.origin + window.location.pathname*. To install the libraries in the same tab from which it was opened, you need to set `window.name` (to any alphanumeric string) — if it's not set it will open in a new tab.
211+
Defaults to _window.location.origin + window.location.pathname_. To install the libraries in the same tab from which it was opened, you need to set `window.name` (to any alphanumeric string) — if it's not set it will open in a new tab.
197212

198213
### theme
199214

200-
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 unless *UIOptions.canvasActions.toggleTheme* is set to `true`, in which case the `theme` prop will control Excalidraw's default theme with ability to allow theme switching (you must take care of updating the `theme` prop when you detect a change to `appState.theme` from the [onChange](#onchange) callback).
215+
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 unless _UIOptions.canvasActions.toggleTheme_ is set to `true`, in which case the `theme` prop will control Excalidraw's default theme with ability to allow theme switching (you must take care of updating the `theme` prop when you detect a change to `appState.theme` from the [onChange](#onchange) callback).
201216

202217
You can use [`THEME`](/docs/@excalidraw/excalidraw/api/utils#theme) to specify the theme.
203218

204219
### name
205220

206-
This prop sets the `name` of the drawing which will be used when exporting the drawing. When supplied, the value takes precedence over *intialData.appState.name*, the `name` will be fully controlled by host app and the users won't be able to edit from within Excalidraw.
221+
This prop sets the `name` of the drawing which will be used when exporting the drawing. When supplied, the value takes precedence over _intialData.appState.name_, the `name` will be fully controlled by host app and the users won't be able to edit from within Excalidraw.
207222

208223

209224
### detectScroll
@@ -236,4 +251,4 @@ validateEmbeddable?: boolean | string[] | RegExp | RegExp[] | ((link: string) =>
236251

237252
This is an optional property. By default we support a handful of well-known sites. You may allow additional sites or disallow the default ones by supplying a custom validator. If you pass `true`, all URLs will be allowed. You can also supply a list of hostnames, RegExp (or list of RegExp objects), or a function. If the function returns `undefined`, the built-in validator will be used.
238253

239-
Supplying a list of hostnames (with or without `www.`) is the preferred way to allow a specific list of domains.
254+
Supplying a list of hostnames (with or without `www.`) is the preferred way to allow a specific list of domains.

0 commit comments

Comments
 (0)