c49b2e684a
* make default style small, adjust font sizes and stroke widths * Reduce size of handle click area * Make save command+shift+s (just persists) * Update stroke width for arrow * Update stroke width for draw * Update stroke width for ellipse * Update stroke width for rectangle * Tweak dash algorithm * Updates snapshot |
||
---|---|---|
.. | ||
scripts | ||
src | ||
LICENSE | ||
package.json | ||
README.md | ||
tsconfig.build.json | ||
tsconfig.json |
@tldraw/core
This package contains the core of the tldraw library. It includes:
Renderer
- a React componentTLShapeUtility
- an abstract class for custom shape utilities- the library's TypeScript
types
- several utility classes:
Installation
yarn add @tldraw/core --peer
Usage
Import the Renderer
React component and pass it the required props.
Documentation
Renderer
Prop | Type | Description |
---|---|---|
page |
TLPage |
The current page object. |
pageState |
TLPageState |
The current page's state. |
shapeUtils |
TLShapeUtils {} |
The shape utilities used to render the shapes. |
theme |
object |
(optional) an object with overrides for the Renderer's default colors. |
The theme object accepts valid CSS colors for the following properties:
Property | Description |
---|---|
foreground |
(optional) The primary (usually "text") color |
background |
(optional) The default page's background color |
brushFill |
(optional) The fill color of the brush selection box |
brushStroke |
(optional) The stroke color of the brush selection box |
selectFill |
(optional) The fill color of the selection bounds |
selectStroke |
(optional) The stroke color of the selection bounds and handles |
Tip: If providing an object for the
theme
prop, either define the object outside of the parent component or memoize it withReact.useMemo
.
The renderer also accepts many (optional) event callbacks.
Prop | Description |
---|---|
onPan |
The user panned with the mouse wheel |
onZoom |
The user zoomed with the mouse wheel |
onPinch |
The user moved their pointers during a pinch |
onPinchEnd |
The user stopped a two-pointer pinch |
onPinchStart |
The user began a two-pointer pinch |
onPointerMove |
The user moved their pointer |
onPointerUp |
The user ended a point |
onPointShape |
The user pointed a shape |
onDoubleClickShape |
The user double-pointed a shape |
onRightPointShape |
The user right-pointed a shape |
onMoveOverShape |
The user moved their pointer a shape |
onHoverShape |
The user moved their pointer onto a shape |
onUnhoverShape |
The user moved their pointer off of a shape |
onPointHandle |
The user pointed a shape handle |
onDoubleClickHandle |
The user double-pointed a shape handle |
onRightPointHandle - |
he user right-pointed a shape handle |
onMoveOverHandle |
The user moved their pointer over a shape handle |
onHoverHandle |
The user moved their pointer onto a shape handle |
onUnhoverHandle |
The user moved their pointer off of a shape handle |
onPointCanvas |
The user pointed the canvas |
onDoubleClickCanvas |
The user double-pointed the canvas |
onRightPointCanvas |
The user right-pointed the canvas |
onPointBounds |
The user pointed the selection bounds |
onDoubleClickBounds |
The user double-pointed the selection bounds |
onRightPointBounds |
The user right-pointed the selection bounds |
onPointBoundsHandle |
The user pointed a selection bounds edge or corner |
onDoubleClickBoundsHandle |
The user double-pointed a selection bounds edge or corner |
onBlurEditingShape |
The user blurred an editing (text) shape |
onError |
The renderer encountered an error |
Tip: If providing callbacks, either define the functions outside of the parent component or memoize them first with
React.useMemo
.
TLPage
An object describing the current page. It contains:
Property | Type | Description |
---|---|---|
id |
string |
A unique id for the page. |
shapes |
TLShape{} |
A table of shapes. |
bindings |
TLBinding{} |
A table of bindings. |
backgroundColor |
string |
(optional) The page's background fill color. Will also overwrite the theme. |
TLPageState
An object describing the current page. It contains:
Property | Type | Description |
---|---|---|
id |
string |
The corresponding page's id |
selectedIds |
string[] |
An array of selected shape ids |
camera |
object |
An object describing the camera state |
camera.point |
number[] |
The camera's [x, y] coordinates |
camera.zoom |
number |
The camera's zoom level |
currentParentId |
string |
(optional) The current parent id for selection |
brush |
TLBounds |
(optional) A Bounds for the current selection box |
pointedId |
string |
(optional) The currently pointed shape id |
hoveredId |
string |
(optional) The currently hovered shape id |
editingId |
string |
(optional) The currently editing shape id |
editingBindingId |
string |
(optional) The currently editing binding id |
TLShape
An object that describes a shape on the page. The shapes in your document should extend this interface with other properties. See Guide: Create a Custom Shape.
Property | Type | Description |
---|---|---|
id |
string |
The shape's id. |
type |
string |
The type of the shape, corresponding to the type of a TLShapeUtil . |
parentId |
string |
The id of the shape's parent (either the current page or another shape). |
childIndex |
number |
the order of the shape among its parent's children |
name |
string |
the name of the shape |
point |
number[] |
the shape's current [x, y] coordinates on the page |
rotation |
number |
(optiona) The shape's current rotation in radians |
children |
string[] |
(optional) An array containing the ids of this shape's children |
handles |
TLHandle{} |
(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 programatically |
isAspectRatioLocked |
boolean |
(optional) True if the shape's aspect ratio is locked |
TLHandle
An object that describes a relationship between two shapes on the page.
Property | Type | Description |
---|---|---|
id |
string |
An id for the handle. |
index |
number |
The handle's order within the shape's handles. |
point |
number[] |
The handle's [x, y] coordinates. |
TLBinding
An object that describes a relationship between two shapes on the page.
Property | Type | Description |
---|---|---|
id |
string |
A unique id for the binding. |
type |
string |
The binding's type. |
fromId |
string |
The id of the shape where the binding begins. |
toId |
string |
The id of the shape where the binding begins. |
TLShapeUtil
The TLShapeUtil
is an abstract class that you can extend to create utilities for your custom shapes. See Guide: Create a Custom Shape.
inputs
A class instance that stores the current pointer position and pressed keys.
Utils
A general purpose utility class.
Vec
A utility class for vector math and related methods.
Svg
A utility class for creating SVG path data through imperative commands.
Intersect
A utility class for finding intersections between various geometric shapes.
Guides
Create a Custom Shape
...
Example
import * as React from "react"
import { Renderer, TLShape, TLShapeUtil, Vec } from '@tldraw/core'
interface RectangleShape extends TLShape {
type: "rectangle",
size: number[]
}
class Rectangle extends TLShapeUtil<RectangleShape> {
// See the "Create a Custom Shape" guide
}
const myShapes = { rectangle: new Rectangle() }
function App() {
const [page, setPage] = React.useState({
id: "page1"
shapes: {
"rect1": {
id: 'rect1',
parentId: 'page1',
name: 'Rectangle',
childIndex: 0,
type: 'rectangle',
point: [0, 0],
rotation: 0,
size: [100, 100],
}
},
bindings: {}
})
const [pageState, setPageState] = React.useState({
id: "page1",
selectedIds: [],
camera: {
point: [0,0],
zoom: 1
}
})
const handlePan = React.useCallback((delta: number[]) => {
setPageState(pageState => {
...pageState,
camera: {
zoom,
point: Vec.sub(pageState.point, Vec.div(delta, pageState.zoom)),
},
})
}, [])
return (<Renderer
shapes={myShapes}
page={page}
pageState={pageState}
onPan={handlePan}
/>)
}
Development
Run yarn
to install dependencies.
Run yarn start
to begin the monorepo's development server (@tldraw/site
).
Run nx test core
to execute unit tests via Jest.
Contribution
To contribute, visit the Discord channel.