PrivateCoffee/tldraw
4
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 1
tldraw/README.md
Steve Ruiz be2c6d6d1f
[refactor] events (#230) 
* bumps rko, adds events

* rename tlstate to state, fix env for multiplayer test

* Fix multiplayer

* rename data tldrawstate to tldrawsnapshot

* Update multiplayer-editor.tsx

* Fix shhhmp

* Update 2.tldr

* Add API to the README
2021-11-08 14:21:37 +00:00

353 lines
14 KiB
Markdown
Raw Blame History

<div style="text-align: center; transform: scale(.5);">
<img src="card-repo.png"/>
</div>
# @tldraw/tldraw
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.
🎨 Want to build your own tldraw-ish app instead? Try [@tldraw/core](https://github.com/tldraw/core).
💕 Love this library? Consider [becoming a sponsor](https://github.com/sponsors/steveruizok?frequency=recurring&sponsor=steveruizok).
## Installation
Use your package manager of choice to install `@tldraw/core` and its peer dependencies.
```bash
yarn add @tldraw/tldraw
# or
npm i @tldraw/tldraw
```
## Usage
Import the `TLDraw` React component and use it in your app.
```tsx
import { TLDraw } from '@tldraw/tldraw'
function App() {
return <TLDraw />
}
```
### Persisting the State
You can use the `id` to persist the state in a user's browser storage.
```tsx
import { TLDraw } from '@tldraw/tldraw'
function App() {
return <TLDraw id="myState" />
}
```
### Controlling the Component through Props
You can control the `TLDraw` component through its props.
```tsx
import { TLDraw, TLDrawDocument } from '@tldraw/tldraw'
function App() {
const myDocument: TLDrawDocument = {}
return <TLDraw document={document} />
}
```
### Controlling the Component through the TLDrawState API
You can also control the `TLDraw` component imperatively through the `TLDrawState` API.
```tsx
import { TLDraw, TLDrawState } from '@tldraw/tldraw'
function App() {
const handleMount = React.useCallback((state: TLDrawState) => {
state.selectAll()
}, [])
return <TLDraw onMount={handleMount} />
}
```
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.
### Responding to Changes
You can respond to changes and user actions using the `onChange` callback.
```tsx
import { TLDraw, TLDrawState } from '@tldraw/tldraw'
function App() {
const handleChange = React.useCallback((state: TLDrawState, reason: string) => {}, [])
return <TLDraw onMount={handleMount} />
}
```
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.
## Documentation
### `TLDraw`
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.**
| Prop | Type | Description |
| --------------- | ---------------- | -------------------------------------------------------------------------------------------- |
| `id` | `string` | An id under which to persist the component's state. |
| `document` | `TLDrawDocument` | An initial [`TLDrawDocument`](#tldrawdocument) object. |
| `currentPageId` | `string` | A current page id, referencing the `TLDrawDocument` object provided via the `document` prop. |
| `onMount` | `Function` | Called when the editor first mounts, receiving the current `TLDrawState`. |
| `onPatch` | `Function` | Called when the state is updated via a patch. |
| `onCommand` | `Function` | Called when the state is updated via a command. |
| `onPersist` | `Function` | Called when the state is persisted after an action. |
| `onChange` | `Function` | Called when the `TLDrawState` updates for any reason. |
| `onUndo` | `Function` | Called when the `TLDrawState` updates after an undo. |
| `onRedo` | `Function` | Called when the `TLDrawState` updates after a redo. |
| `onUserChange` | `Function` | Called when the user's "presence" information changes. |
| `autofocus` | `boolean` | Whether the editor should immediately receive focus. Defaults to true. |
| `showMenu` | `boolean` | Whether to show the menu. |
| `showPages` | `boolean` | Whether to show the pages menu. |
| `showStyles` | `boolean` | Whether to show the styles menu. |
| `showTools` | `boolean` | Whether to show the tools. |
| `showUI` | `boolean` | Whether to show any UI other than the canvas. |
### `TLDrawDocument`
A `TLDrawDocument` is an object with three properties:
- `id` - A unique ID for this document
- `pages` - A table of `TLDrawPage` objects
- `pageStates` - A table of `TLPageState` objects
- `version` - The document's version, used internally for migrations.
```ts
import { TLDrawDocument, TLDrawState } from '@tldraw/tldraw'
const tldocument: TLDrawDocument = {
id: 'doc',
version: TLDrawState.version,
pages: {
page1: {
id: 'page1',
shapes: {},
bindings: {},
},
},
pageStates: {
page1: {
id: 'page1',
selectedIds: [],
currentParentId: 'page1',
camera: {
point: [0, 0],
zoom: 1,
},
},
},
}
```
**Tip:** TLDraw is built [@tldraw/core](https://github.com/tldraw/core). The pages and pagestates in TLDraw are just 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.
**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.
### Shapes
Your `TLPage` objects may include shapes: objects that fit one of the `TLDrawShape` interfaces listed below. All `TLDrawShapes` extends a common interface:
| Property | Type | Description |
| --------------------- | ---------------- | --------------------------------------------------------------- |
| `id` | `string` | A unique ID for the shape. |
| `name` | `string` | The shape's name. |
| `type` | `string` | The shape's type. |
| `parentId` | `string` | The ID of the shape's parent (a shape or its page). |
| `childIndex` | `number` | The shape's order within its parent's children, indexed from 1. |
| `point` | `number[]` | The `[x, y]` position of the shape. |
| `rotation` | `number[]` | (optional) The shape's rotation in radians. |
| `children` | `string[]` | (optional) The shape's child shape ids. |
| `handles` | `TLDrawHandle{}` | (optional) A table of `TLHandle` objects. |
| `isLocked` | `boolean` | (optional) True if the shape is locked. |
| `isHidden` | `boolean` | (optional) True if the shape is hidden. |
| `isEditing` | `boolean` | (optional) True if the shape is currently editing. |
| `isGenerated` | `boolean` | (optional) True if the shape is generated. |
| `isAspectRatioLocked` | `boolean` | (optional) True if the shape's aspect ratio is locked. |
> **Important:** In order for re-ordering to work correctly, 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.
The `ShapeStyle` object is a common style API for all shapes.
| Property | Type | Description |
| ---------- | ------------ | --------------------------------------- |
| `size` | `SizeStyle` | The size of the shape's stroke. |
| `dash` | `DashStyle` | The style of the shape's stroke. |
| `color` | `ColorStyle` | The shape's color. |
| `isFilled` | `boolean` | (optional) True if the shape is filled. |
#### `DrawShape`
A hand-drawn line.
| Property | Type | Description |
| -------- | ------------ | ----------------------------------------- |
| `points` | `number[][]` | An array of points as `[x, y, pressure]`. |
##### `RectangleShape`
A rectangular shape.
| Property | Type | Description |
| -------- | ---------- | --------------------------------------- |
| `size` | `number[]` | The `[width, height]` of the rectangle. |
#### `EllipseShape`
An elliptical shape.
| Property | Type | Description |
| -------- | ---------- | ----------------------------------- |
| `radius` | `number[]` | The `[x, y]` radius of the ellipse. |
#### `ArrowShape`
An arrow that can connect shapes.
| Property | Type | Description |
| ------------- | -------- | ----------------------------------------------------------------------- |
| `handles` | `object` | An object with three `TLHandle` properties: `start`, `end`, and `bend`. |
| `decorations` | `object` | An object with two properties `start`, `end`, and `bend`. |
#### `TextShape`
A line of text.
| Property | Type | Description |
| -------- | -------- | ------------------------- |
| `text` | `string` | The shape's text content. |
#### `StickyShape`
A sticky note.
| Property | Type | Description |
| -------- | -------- | ------------------------- |
| `text` | `string` | The shape's text content. |
### Bindings
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.
| Property | Type | Description |
| ---------- | ---------------- | -------------------------------------------------------- |
| `id` | `string` | The binding's own unique ID. |
| `fromId` | `string` | The id of the `ArrowShape` that the binding is bound to. |
| `toId` | `string` | The id of the other shape that the binding is bound to. |
| `handleId` | `start` or `end` | The connected arrow handle. |
| `distance` | `number` | The distance from the bound point. |
| `point` | `number[]` | A normalized point representing the bound point. |
### `TLDrawState` API
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`.
```tsx
import { TLDraw, TLDrawState } from '@tldraw/tldraw'
function App() {
const handleMount = React.useCallback((state: TLDrawState) => {
state.selectAll()
}, [])
return <TLDraw onMount={handleMount} />
}
```
The `TLDrawState` API is too large to document here. To view documentation for the API, build the documentation by running `yarn docs` from the root folder and open the file at `/packages/tldraw/docs/classes/TLDrawState.html` in your browser.
Here are some useful methods:
| Method | Description |
| ----------------- | ----------- |
| `loadDocument` | |
| `select` | |
| `selectAll` | |
| `selectNone` | |
| `delete` | |
| `deleteAll` | |
| `deletePage` | |
| `changePage` | |
| `cut` | |
| `copy` | |
| `paste` | |
| `copyJson` | |
| `copySvg` | |
| `undo` | |
| `redo` | |
| `zoomIn` | |
| `zoomOut` | |
| `zoomToContent` | |
| `zoomToSelection` | |
| `zoomToFit` | |
| `zoomTo` | |
| `resetZoom` | |
| `setCamera` | |
| `resetCamera` | |
| `align` | |
| `distribute` | |
| `stretch` | |
| `nudge` | |
| `duplicate` | |
| `flipHorizontal` | |
| `flipVertical` | |
| `rotate` | |
| `style` | |
| `group` | |
| `ungroup` | |
| `createShapes` | |
| `updateShapes` | |
| `updateDocument` | |
| `updateUsers` | |
| `removeUser` | |
| `setSetting` | |
| `selectTool` | |
| `cancel` | |
## Local Development
- Run `yarn` to install dependencies.
- Run `yarn start` to start the development server for the package and for the example.
- Open `localhost:5420` to view the example project.
- Run `yarn test` to execute unit tests via [Jest](https://jestjs.io).
- Run `yarn docs` to build the docs via [ts-doc](https://typedoc.org/).
## Example
See the `example` folder.
## Community
### Support
Need help? Please [open an issue](https://github.com/tldraw/tldraw/issues/new) for support.
### Discussion
Want to connect with other devs? Visit the [Discord channel](https://discord.gg/s4FXZ6fppJ).
### License
This project is licensed under MIT. If you're using the library in a commercial product, please consider [becoming a sponsor](https://github.com/sponsors/steveruizok?frequency=recurring&sponsor=steveruizok).
## Author
- [@steveruizok](https://twitter.com/steveruizok)
Reference in a new issue View git blame Copy permalink