|
|
@@ -4,388 +4,10 @@
|
|
4
|
4
|
|
|
5
|
5
|
# @tldraw/tldraw
|
|
6
|
6
|
|
|
7
|
|
-This package contains the [tldraw](https://tldraw.com) editor as a React component named `<TLDraw>`. You can use this package to embed the editor in any React application.
|
|
|
7
|
+This package contains the [TLDraw](https://tldraw.com) editor as a React component named `<TLDraw>`. You can use this package to embed the editor in any React application.
|
|
8
|
8
|
|
|
9
|
|
-🎨 Want to build your own tldraw-ish app instead? Try [@tldraw/core](https://github.com/tldraw/core).
|
|
|
9
|
+🎨 Want to build your own TLDraw-ish app instead? Try [@tldraw/core](https://github.com/tldraw/core).
|
|
10
|
10
|
|
|
11
|
11
|
💕 Love this library? Consider [becoming a sponsor](https://github.com/sponsors/steveruizok?frequency=recurring&sponsor=steveruizok).
|
|
12
|
12
|
|
|
13
|
|
-## Installation
|
|
14
|
|
-
|
|
15
|
|
-Use your package manager of choice to install `@tldraw/tldraw` and its peer dependencies.
|
|
16
|
|
-
|
|
17
|
|
-```bash
|
|
18
|
|
-yarn add @tldraw/tldraw
|
|
19
|
|
-# or
|
|
20
|
|
-npm i @tldraw/tldraw
|
|
21
|
|
-```
|
|
22
|
|
-
|
|
23
|
|
-## Usage
|
|
24
|
|
-
|
|
25
|
|
-Import the `TLDraw` React component and use it in your app.
|
|
26
|
|
-
|
|
27
|
|
-```tsx
|
|
28
|
|
-import { TLDraw } from '@tldraw/tldraw'
|
|
29
|
|
-
|
|
30
|
|
-function App() {
|
|
31
|
|
- return <TLDraw />
|
|
32
|
|
-}
|
|
33
|
|
-```
|
|
34
|
|
-
|
|
35
|
|
-### Persisting the State
|
|
36
|
|
-
|
|
37
|
|
-You can use the `id` to persist the state in a user's browser storage.
|
|
38
|
|
-
|
|
39
|
|
-```tsx
|
|
40
|
|
-import { TLDraw } from '@tldraw/tldraw'
|
|
41
|
|
-
|
|
42
|
|
-function App() {
|
|
43
|
|
- return <TLDraw id="myState" />
|
|
44
|
|
-}
|
|
45
|
|
-```
|
|
46
|
|
-
|
|
47
|
|
-### Controlling the Component through Props
|
|
48
|
|
-
|
|
49
|
|
-You can control the `TLDraw` component through its props.
|
|
50
|
|
-
|
|
51
|
|
-```tsx
|
|
52
|
|
-import { TLDraw, TLDrawDocument } from '@tldraw/tldraw'
|
|
53
|
|
-
|
|
54
|
|
-function App() {
|
|
55
|
|
- const myDocument: TLDrawDocument = {}
|
|
56
|
|
-
|
|
57
|
|
- return <TLDraw document={document} />
|
|
58
|
|
-}
|
|
59
|
|
-```
|
|
60
|
|
-
|
|
61
|
|
-### Controlling the Component through the TLDrawState API
|
|
62
|
|
-
|
|
63
|
|
-You can also control the `TLDraw` component imperatively through the `TLDrawState` API.
|
|
64
|
|
-
|
|
65
|
|
-```tsx
|
|
66
|
|
-import { TLDraw, TLDrawState } from '@tldraw/tldraw'
|
|
67
|
|
-
|
|
68
|
|
-function App() {
|
|
69
|
|
- const handleMount = React.useCallback((state: TLDrawState) => {
|
|
70
|
|
- state.selectAll()
|
|
71
|
|
- }, [])
|
|
72
|
|
-
|
|
73
|
|
- return <TLDraw onMount={handleMount} />
|
|
74
|
|
-}
|
|
75
|
|
-```
|
|
76
|
|
-
|
|
77
|
|
-Internally, the `TLDraw` component's user interface uses this API to make changes to the component's state. See the `TLDrawState` section for more on this API.
|
|
78
|
|
-
|
|
79
|
|
-### Responding to Changes
|
|
80
|
|
-
|
|
81
|
|
-You can respond to changes and user actions using the `onChange` callback.
|
|
82
|
|
-
|
|
83
|
|
-```tsx
|
|
84
|
|
-import { TLDraw, TLDrawState } from '@tldraw/tldraw'
|
|
85
|
|
-
|
|
86
|
|
-function App() {
|
|
87
|
|
- const handleChange = React.useCallback((state: TLDrawState, reason: string) => {}, [])
|
|
88
|
|
-
|
|
89
|
|
- return <TLDraw onMount={handleMount} />
|
|
90
|
|
-}
|
|
91
|
|
-```
|
|
92
|
|
-
|
|
93
|
|
-Internally, the `TLDraw` component's user interface uses this API to make changes to the component's state. See the `TLDrawState` section for more on this API.
|
|
94
|
|
-
|
|
95
|
|
-## Documentation
|
|
96
|
|
-
|
|
97
|
|
-### `TLDraw`
|
|
98
|
|
-
|
|
99
|
|
-The `TLDraw` React component is the [tldraw](https://tldraw.com) editor exported as a standalone component. You can control the editor through props, or through the `TLDrawState`'s imperative API. **All props are optional.**
|
|
100
|
|
-
|
|
101
|
|
-| Prop | Type | Description |
|
|
102
|
|
-| ----------------- | ---------------- | --------------------------------------------------------------------------------------------------------- |
|
|
103
|
|
-| `id` | `string` | An id under which to persist the component's state. |
|
|
104
|
|
-| `document` | `TLDrawDocument` | An initial [`TLDrawDocument`](#tldrawdocument) object. |
|
|
105
|
|
-| `currentPageId` | `string` | A current page id, referencing the `TLDrawDocument` object provided via the `document` prop. |
|
|
106
|
|
-| `autofocus` | `boolean` | Whether the editor should immediately receive focus. Defaults to true. |
|
|
107
|
|
-| `showMenu` | `boolean` | Whether to show the menu. |
|
|
108
|
|
-| `showPages` | `boolean` | Whether to show the pages menu. |
|
|
109
|
|
-| `showStyles` | `boolean` | Whether to show the styles menu. |
|
|
110
|
|
-| `showTools` | `boolean` | Whether to show the tools. |
|
|
111
|
|
-| `showUI` | `boolean` | Whether to show any UI other than the canvas. |
|
|
112
|
|
-| `onMount` | `Function` | Called when the editor first mounts, receiving the current `TLDrawState`. |
|
|
113
|
|
-| `onPatch` | `Function` | Called when the state is updated via a patch. |
|
|
114
|
|
-| `onCommand` | `Function` | Called when the state is updated via a command. |
|
|
115
|
|
-| `onPersist` | `Function` | Called when the state is persisted after an action. |
|
|
116
|
|
-| `onChange` | `Function` | Called when the `TLDrawState` updates for any reason. |
|
|
117
|
|
-| `onUserChange` | `Function` | Called when the user's "presence" information changes. |
|
|
118
|
|
-| `onUndo` | `Function` | Called when the `TLDrawState` updates after an undo. |
|
|
119
|
|
-| `onRedo` | `Function` | Called when the `TLDrawState` updates after a redo. |
|
|
120
|
|
-| `onSignIn` | `Function` | Called when the user selects Sign In from the menu. |
|
|
121
|
|
-| `onSignOut` | `Function` | Called when the user selects Sign Out from the menu. |
|
|
122
|
|
-| `onNewProject` | `Function` | Called when the user when the user creates a new project through the menu or through a keyboard shortcut. |
|
|
123
|
|
-| `onSaveProject` | `Function` | Called when the user saves a project through the menu or through a keyboard shortcut. |
|
|
124
|
|
-| `onSaveProjectAs` | `Function` | Called when the user saves a project as a new project through the menu or through a keyboard shortcut. |
|
|
125
|
|
-| `onOpenProject` | `Function` | Called when the user opens new project through the menu or through a keyboard shortcut. |
|
|
126
|
|
-
|
|
127
|
|
-> **Note**: For help with the file-related callbacks, see `useFileSystem`.
|
|
128
|
|
-
|
|
129
|
|
-### `useFileSystem`
|
|
130
|
|
-
|
|
131
|
|
-You can use the `useFileSystem` hook to get prepared callbacks for `onNewProject`, `onOpenProject`, `onSaveProject`, and `onSaveProjectAs`. These callbacks allow a user to save files via the [FileSystem](https://developer.mozilla.org/en-US/docs/Web/API/FileSystem) API.
|
|
132
|
|
-
|
|
133
|
|
-```ts
|
|
134
|
|
-import { TLDraw, useFileSystem } from '@tldraw/tldraw'
|
|
135
|
|
-
|
|
136
|
|
-function App() {
|
|
137
|
|
- const fileSystemEvents = useFileSystem()
|
|
138
|
|
-
|
|
139
|
|
- return <TLDraw {...fileSystemEvents} />
|
|
140
|
|
-}
|
|
141
|
|
-```
|
|
142
|
|
-
|
|
143
|
|
-### `TLDrawDocument`
|
|
144
|
|
-
|
|
145
|
|
-You can initialize or control the `<TLDraw>` component via its `document` property. A `TLDrawDocument` is an object with three properties:
|
|
146
|
|
-
|
|
147
|
|
-- `id` - A unique ID for this document
|
|
148
|
|
-- `pages` - A table of `TLDrawPage` objects
|
|
149
|
|
-- `pageStates` - A table of `TLPageState` objects
|
|
150
|
|
-- `version` - The document's version, used internally for migrations.
|
|
151
|
|
-
|
|
152
|
|
-```ts
|
|
153
|
|
-import { TLDrawDocument, TLDrawState } from '@tldraw/tldraw'
|
|
154
|
|
-
|
|
155
|
|
-const myDocument: TLDrawDocument = {
|
|
156
|
|
- id: 'doc',
|
|
157
|
|
- version: TLDrawState.version,
|
|
158
|
|
- pages: {
|
|
159
|
|
- page1: {
|
|
160
|
|
- id: 'page1',
|
|
161
|
|
- shapes: {},
|
|
162
|
|
- bindings: {},
|
|
163
|
|
- },
|
|
164
|
|
- },
|
|
165
|
|
- pageStates: {
|
|
166
|
|
- page1: {
|
|
167
|
|
- id: 'page1',
|
|
168
|
|
- selectedIds: [],
|
|
169
|
|
- currentParentId: 'page1',
|
|
170
|
|
- camera: {
|
|
171
|
|
- point: [0, 0],
|
|
172
|
|
- zoom: 1,
|
|
173
|
|
- },
|
|
174
|
|
- },
|
|
175
|
|
- },
|
|
176
|
|
-}
|
|
177
|
|
-
|
|
178
|
|
-function App() {
|
|
179
|
|
- return <TLDraw document={myDocument} />
|
|
180
|
|
-}
|
|
181
|
|
-```
|
|
182
|
|
-
|
|
183
|
|
-**Tip:** TLDraw is built on [@tldraw/core](https://github.com/tldraw/core). The pages and pageStates in TLDraw are objects containing `TLPage` and `TLPageState` objects from the core library. For more about these types, check out the [@tldraw/core](https://github.com/tldraw/core) documentation.
|
|
184
|
|
-
|
|
185
|
|
-**Important:** In the `pages` object, each `TLPage` object must be keyed under its `id` property. Likewise, each `TLPageState` object must be keyed under its `id`. In addition, each `TLPageState` object must have an `id` that matches its corresponding page.
|
|
186
|
|
-
|
|
187
|
|
-### Shapes
|
|
188
|
|
-
|
|
189
|
|
-Your `TLPage` objects may include shapes: objects that fit one of the `TLDrawShape` interfaces listed below. All `TLDrawShapes` extends a common interface:
|
|
190
|
|
-
|
|
191
|
|
-| Property | Type | Description |
|
|
192
|
|
-| --------------------- | ---------------- | --------------------------------------------------------------- |
|
|
193
|
|
-| `id` | `string` | A unique ID for the shape. |
|
|
194
|
|
-| `name` | `string` | The shape's name. |
|
|
195
|
|
-| `type` | `string` | The shape's type. |
|
|
196
|
|
-| `parentId` | `string` | The ID of the shape's parent (a shape or its page). |
|
|
197
|
|
-| `childIndex` | `number` | The shape's order within its parent's children, indexed from 1. |
|
|
198
|
|
-| `point` | `number[]` | The `[x, y]` position of the shape. |
|
|
199
|
|
-| `rotation` | `number[]` | (optional) The shape's rotation in radians. |
|
|
200
|
|
-| `children` | `string[]` | (optional) The shape's child shape ids. |
|
|
201
|
|
-| `handles` | `TLDrawHandle{}` | (optional) A table of `TLHandle` objects. |
|
|
202
|
|
-| `isLocked` | `boolean` | (optional) True if the shape is locked. |
|
|
203
|
|
-| `isHidden` | `boolean` | (optional) True if the shape is hidden. |
|
|
204
|
|
-| `isEditing` | `boolean` | (optional) True if the shape is currently editing. |
|
|
205
|
|
-| `isGenerated` | `boolean` | (optional) True if the shape is generated. |
|
|
206
|
|
-| `isAspectRatioLocked` | `boolean` | (optional) True if the shape's aspect ratio is locked. |
|
|
207
|
|
-
|
|
208
|
|
-> **Important:** In order for re-ordering to work, a shape's `childIndex` values _must_ start from 1, not 0. The page or parent shape's "bottom-most" child should have a `childIndex` of 1.
|
|
209
|
|
-
|
|
210
|
|
-The `ShapeStyle` object is a common style API for all shapes.
|
|
211
|
|
-
|
|
212
|
|
-| Property | Type | Description |
|
|
213
|
|
-| ---------- | ------------ | --------------------------------------- |
|
|
214
|
|
-| `size` | `SizeStyle` | The size of the shape's stroke. |
|
|
215
|
|
-| `dash` | `DashStyle` | The style of the shape's stroke. |
|
|
216
|
|
-| `color` | `ColorStyle` | The shape's color. |
|
|
217
|
|
-| `isFilled` | `boolean` | (optional) True if the shape is filled. |
|
|
218
|
|
-
|
|
219
|
|
-#### `DrawShape`
|
|
220
|
|
-
|
|
221
|
|
-A hand-drawn line.
|
|
222
|
|
-
|
|
223
|
|
-| Property | Type | Description |
|
|
224
|
|
-| -------- | ------------ | ----------------------------------------- |
|
|
225
|
|
-| `points` | `number[][]` | An array of points as `[x, y, pressure]`. |
|
|
226
|
|
-
|
|
227
|
|
-##### `RectangleShape`
|
|
228
|
|
-
|
|
229
|
|
-A rectangular shape.
|
|
230
|
|
-
|
|
231
|
|
-| Property | Type | Description |
|
|
232
|
|
-| -------- | ---------- | --------------------------------------- |
|
|
233
|
|
-| `size` | `number[]` | The `[width, height]` of the rectangle. |
|
|
234
|
|
-
|
|
235
|
|
-#### `EllipseShape`
|
|
236
|
|
-
|
|
237
|
|
-An elliptical shape.
|
|
238
|
|
-
|
|
239
|
|
-| Property | Type | Description |
|
|
240
|
|
-| -------- | ---------- | ----------------------------------- |
|
|
241
|
|
-| `radius` | `number[]` | The `[x, y]` radius of the ellipse. |
|
|
242
|
|
-
|
|
243
|
|
-#### `ArrowShape`
|
|
244
|
|
-
|
|
245
|
|
-An arrow that can connect shapes.
|
|
246
|
|
-
|
|
247
|
|
-| Property | Type | Description |
|
|
248
|
|
-| ------------- | -------- | ----------------------------------------------------------------------- |
|
|
249
|
|
-| `handles` | `object` | An object with three `TLHandle` properties: `start`, `end`, and `bend`. |
|
|
250
|
|
-| `decorations` | `object` | An object with two properties `start`, `end`, and `bend`. |
|
|
251
|
|
-
|
|
252
|
|
-#### `TextShape`
|
|
253
|
|
-
|
|
254
|
|
-A line of text.
|
|
255
|
|
-
|
|
256
|
|
-| Property | Type | Description |
|
|
257
|
|
-| -------- | -------- | ------------------------- |
|
|
258
|
|
-| `text` | `string` | The shape's text content. |
|
|
259
|
|
-
|
|
260
|
|
-#### `StickyShape`
|
|
261
|
|
-
|
|
262
|
|
-A sticky note.
|
|
263
|
|
-
|
|
264
|
|
-| Property | Type | Description |
|
|
265
|
|
-| -------- | -------- | ------------------------- |
|
|
266
|
|
-| `text` | `string` | The shape's text content. |
|
|
267
|
|
-
|
|
268
|
|
-### Bindings
|
|
269
|
|
-
|
|
270
|
|
-A binding is a connection **from** one shape and **to** another shape. At the moment, only arrows may be bound "from". Most shapes may be bound "to", except other `ArrowShape` and `DrawShape`s.
|
|
271
|
|
-
|
|
272
|
|
-| Property | Type | Description |
|
|
273
|
|
-| ---------- | ---------------- | -------------------------------------------------------- |
|
|
274
|
|
-| `id` | `string` | The binding's own unique ID. |
|
|
275
|
|
-| `fromId` | `string` | The id of the `ArrowShape` that the binding is bound to. |
|
|
276
|
|
-| `toId` | `string` | The id of the other shape that the binding is bound to. |
|
|
277
|
|
-| `handleId` | `start` or `end` | The connected arrow handle. |
|
|
278
|
|
-| `distance` | `number` | The distance from the bound point. |
|
|
279
|
|
-| `point` | `number[]` | A normalized point representing the bound point. |
|
|
280
|
|
-
|
|
281
|
|
-### `TLDrawState` API
|
|
282
|
|
-
|
|
283
|
|
-You can change the `TLDraw` component's state through an imperative API called `TLDrawState`. To access this API, use the `onMount` callback, or any of the component's callback props, like `onPersist`.
|
|
284
|
|
-
|
|
285
|
|
-```tsx
|
|
286
|
|
-import { TLDraw, TLDrawState } from '@tldraw/tldraw'
|
|
287
|
|
-
|
|
288
|
|
-function App() {
|
|
289
|
|
- const handleMount = React.useCallback((state: TLDrawState) => {
|
|
290
|
|
- state.selectAll()
|
|
291
|
|
- }, [])
|
|
292
|
|
-
|
|
293
|
|
- return <TLDraw onMount={handleMount} />
|
|
294
|
|
-}
|
|
295
|
|
-```
|
|
296
|
|
-
|
|
297
|
|
-To view the full documentation of the `TLDrawState` API, generate the project's documentation by running `yarn docs` from the root folder, then open the file at:
|
|
298
|
|
-
|
|
299
|
|
-```
|
|
300
|
|
-/packages/tldraw/docs/classes/TLDrawState.html
|
|
301
|
|
-```
|
|
302
|
|
-
|
|
303
|
|
-Here are some useful methods:
|
|
304
|
|
-
|
|
305
|
|
-- `loadDocument`
|
|
306
|
|
-- `select`
|
|
307
|
|
-- `selectAll`
|
|
308
|
|
-- `selectNone`
|
|
309
|
|
-- `delete`
|
|
310
|
|
-- `deleteAll`
|
|
311
|
|
-- `deletePage`
|
|
312
|
|
-- `changePage`
|
|
313
|
|
-- `cut`
|
|
314
|
|
-- `copy`
|
|
315
|
|
-- `paste`
|
|
316
|
|
-- `copyJson`
|
|
317
|
|
-- `copySvg`
|
|
318
|
|
-- `undo`
|
|
319
|
|
-- `redo`
|
|
320
|
|
-- `zoomIn`
|
|
321
|
|
-- `zoomOut`
|
|
322
|
|
-- `zoomToContent`
|
|
323
|
|
-- `zoomToSelection`
|
|
324
|
|
-- `zoomToFit`
|
|
325
|
|
-- `zoomTo`
|
|
326
|
|
-- `resetZoom`
|
|
327
|
|
-- `setCamera`
|
|
328
|
|
-- `resetCamera`
|
|
329
|
|
-- `align`
|
|
330
|
|
-- `distribute`
|
|
331
|
|
-- `stretch`
|
|
332
|
|
-- `nudge`
|
|
333
|
|
-- `duplicate`
|
|
334
|
|
-- `flipHorizontal`
|
|
335
|
|
-- `flipVertical`
|
|
336
|
|
-- `rotate`
|
|
337
|
|
-- `style`
|
|
338
|
|
-- `group`
|
|
339
|
|
-- `ungroup`
|
|
340
|
|
-- `createShapes`
|
|
341
|
|
-- `updateShapes`
|
|
342
|
|
-- `updateDocument`
|
|
343
|
|
-- `updateUsers`
|
|
344
|
|
-- `removeUser`
|
|
345
|
|
-- `setSetting`
|
|
346
|
|
-- `selectTool`
|
|
347
|
|
-- `cancel`
|
|
348
|
|
-
|
|
349
|
|
-Check the generated docs, source or the TypeScript types for more on these and other methods.
|
|
350
|
|
-
|
|
351
|
|
-## Local Development
|
|
352
|
|
-
|
|
353
|
|
-From the root folder:
|
|
354
|
|
-
|
|
355
|
|
-- Run `yarn` to install dependencies.
|
|
356
|
|
-
|
|
357
|
|
-- Run `yarn start` to start the development server for the package and for the example.
|
|
358
|
|
-
|
|
359
|
|
-- Open `localhost:5420` to view the example project.
|
|
360
|
|
-
|
|
361
|
|
-**Note:** The multiplayer examples and endpoints currently require an API key from [Liveblocks](https://liveblocks.io/), however the storage services that are used in TLDraw are currently in alpha and (as of November 2021) not accessible to the general public. You won't be able to authenticate and run these parts of the project.
|
|
362
|
|
-
|
|
363
|
|
-Other scripts:
|
|
364
|
|
-
|
|
365
|
|
-- Run `yarn test` to execute unit tests via [Jest](https://jestjs.io).
|
|
366
|
|
-
|
|
367
|
|
-- Run `yarn docs` to build the docs via [ts-doc](https://typedoc.org/).
|
|
368
|
|
-
|
|
369
|
|
-## Example
|
|
370
|
|
-
|
|
371
|
|
-See the `example` folder for examples of how to use the `<TLDraw/>` component.
|
|
372
|
|
-
|
|
373
|
|
-## Community
|
|
374
|
|
-
|
|
375
|
|
-### Support
|
|
376
|
|
-
|
|
377
|
|
-Need help? Please [open an issue](https://github.com/tldraw/tldraw/issues/new) for support.
|
|
378
|
|
-
|
|
379
|
|
-### Discussion
|
|
380
|
|
-
|
|
381
|
|
-Want to connect with other devs? Visit the [Discord channel](https://discord.gg/s4FXZ6fppJ).
|
|
382
|
|
-
|
|
383
|
|
-### License
|
|
384
|
|
-
|
|
385
|
|
-This project is licensed under MIT.
|
|
386
|
|
-
|
|
387
|
|
-If you're using the library in a commercial product, please consider [becoming a sponsor](https://github.com/sponsors/steveruizok?frequency=recurring&sponsor=steveruizok).
|
|
388
|
|
-
|
|
389
|
|
-## Author
|
|
390
|
|
-
|
|
391
|
|
-- [@steveruizok](https://twitter.com/steveruizok)
|
|
|
13
|
+For documentation, see the [TLDraw](https://github.com/tldraw) repository.
|
Steve Ruiz
2 years ago