0c4174c0b8
This PR updates our user-facing APIs for the Tldraw and TldrawEditor components, as well as the Editor (App). It mainly incorporates surface changes from #1450 without any changes to validators or migrators, incorporating feedback / discussion with @SomeHats and @ds300. Here we: - remove the TldrawEditorConfig - bring back a loose version of shape definitions - make a separation between "core" shapes and "default" shapes - do not allow custom shapes, migrators or validators to overwrite core shapes - but _do_ allow new shapes ## `<Tldraw>` component In this PR, the `Tldraw` component wraps both the `TldrawEditor` component and our `TldrawUi` component. It accepts a union of props for both components. Previously, this component also added local syncing via a `useLocalSyncClient` hook call, however that has been pushed down to the `TldrawEditor` component. ## `<TldrawEditor>` component The `TldrawEditor` component now more neatly wraps up the different ways that the editor can be configured. ## The store prop (`TldrawEditorProps.store`) There are three main ways for the `TldrawEditor` component to be run: 1. with an externally defined store 2. with an externally defined syncing store (local or remote) 3. with an internally defined store 4. with an internally defined locally syncing store The `store` prop allows for these configurations. If the `store` prop is defined, it may be defined either as a `TLStore` or as a `SyncedStore`. If the store is a `TLStore`, then the Editor will assume that the store is ready to go; if it is defined as a SyncedStore, then the component will display the loading / error screens as needed, or the final editor once the store's status is "synced". When the store is left undefined, then the `TldrawEditor` will create its own internal store using the optional `instanceId`, `initialData`, or `shapes` props to define the store / store schema. If the `persistenceKey` prop is left undefined, then the store will not be synced. If the `persistenceKey` is defined, then the store will be synced locally. In the future, we may also here accept the API key / roomId / etc for creating a remotely synced store. The `SyncedStore` type has been expanded to also include types used for remote syncing, e.g. with `ConnectionStatus`. ## Tools By default, the App has two "baked-in" tools: the select tool and the zoom tool. These cannot (for now) be replaced or removed. The default tools are used by default, but may be replaced by other tools if provided. ## Shapes By default, the App has a set of "core" shapes: - group - embed - bookmark - image - video - text That cannot by overwritten because they're created by the app at different moments, such as when double clicking on the canvas or via a copy and paste event. In follow up PRs, we'll split these out so that users can replace parts of the code where these shapes are created. ### Change Type - [x] `major` — Breaking Change ### Test Plan - [x] Unit Tests |
||
|---|---|---|
| .github | ||
| .husky | ||
| .yarn | ||
| apps | ||
| assets | ||
| config | ||
| e2e/screenshots | ||
| packages | ||
| scripts | ||
| .eslintignore | ||
| .eslintplugin.js | ||
| .eslintrc.js | ||
| .gitignore | ||
| .ignore | ||
| .prettierignore | ||
| .prettierrc | ||
| .yarnrc.yml | ||
| CODE_OF_CONDUCT.md | ||
| CONTRIBUTING.md | ||
| LICENSE | ||
| README.md | ||
| lazy.config.ts | ||
| lerna.json | ||
| package.json | ||
| public-yarn.lock | ||
README.md
tldraw
Welcome to the public monorepo for tldraw.
What is tldraw?
tldraw is a collaborative digital whiteboard available at tldraw.com. Its editor, user interface, and other underlying libraries are open source and available in this repository. They are also distributed on npm. You can use tldraw to create a drop-in whiteboard for your product or as the foundation on which to build your own inifinite canvas applications.
Learn more at tldraw.dev.
Note This repo contains source code for the current version of tldraw. You can find the source for the original version here.
Installation & Usage
To learn more about using tldraw in your React application, follow our guide here or see this StackBlitz.
import { Tldraw } from '@tldraw/tldraw'
import '@tldraw/tldraw/editor.css'
import '@tldraw/tldraw/ui.css'
function TldrawExample() {
return <Tldraw />
}
Local development
To run the local development server, first clone this repo.
Install dependencies:
yarn
Start the local development server:
yarn dev
Open the example project at localhost:5420.
Examples
Our development server contains several examples that demonstrates different ways that you can customize tldraw or use its APIs. Each example is found in the apps/examples/src folder.
- eg:
localhost:5420for the basic example. - eg:
localhost:5420/apifor the API example.
To learn more about using tldraw, visit our docs.
About this repository
Top-level layout
This repository's contents is divided across four primary sections:
/appscontains the source for our applications/packagescontains the source for our public packages/scriptscontains scripts used for building and publishing/assetscontains icons and translations relied on by the app
Applications
examples: our local development / examples projectdocs: our docs site at tldraw.devvscode: our Visual Studio Code extension
Packages
editor: the tldraw editorui: the editor's user interfacetldraw: the main tldraw package containing both the editor and the UIprimitives: low-level primitives for working with vectors and geometrytlschema: shape definitions and migrationstlsync-client: a library for (locally) syncronizing editor instancestlstore: an in-memory reactive databasetlvalidate: a validation library used for run-time validationtlassets: a library for working with tldraw's fonts and translationsfile-format: a library for working with tldraw's.tldrfile formatutils: low-level data utilities shared by other libraries
Community
Have questions, comments or feedback? Join our discord or start a discussion.
Distributions
You can find tldraw on npm here.
License
The source code for various apps and packages in this repository (as well as our 2.0+ distributions and releases) are currently licensed under Apache-2.0. These licenses are subject to change in our upcoming 2.0 release. If you are planning to use tldraw in a commercial product, please reach out at hello@tldraw.com.
Contribution
Please see our contributing guide. Found a bug? Please submit an issue.
Note: we are currently unable to accept contributions on the @tldraw/tldraw or @tldraw/editor packages while we work out our final licensing.
Contact
Find us on Twitter at @tldraw or email hello@tldraw.com. You can also join our discord for quick help and support.