fabba66c0f
This PR implements a camera options API.
- [x] Initial PR
- [x] Updated unit tests
- [x] Feedback / review
- [x] New unit tests
- [x] Update use-case examples
- [x] Ship?
## Public API
A user can provide camera options to the `Tldraw` component via the
`cameraOptions` prop. The prop is also available on the `TldrawEditor`
component and the constructor parameters of the `Editor` class.
```tsx
export default function CameraOptionsExample() {
return (
<div className="tldraw__editor">
<Tldraw cameraOptions={CAMERA_OPTIONS} />
</div>
)
}
```
At runtime, a user can:
- get the current camera options with `Editor.getCameraOptions`
- update the camera options with `Editor.setCameraOptions`
Setting the camera options automatically applies them to the current
camera.
```ts
editor.setCameraOptions({...editor.getCameraOptions(), isLocked: true })
```
A user can get the "camera fit zoom" via `editor.getCameraFitZoom()`.
# Interface
The camera options themselves can look a few different ways depending on
the `type` provided.
```tsx
export type TLCameraOptions = {
/** Whether the camera is locked. */
isLocked: boolean
/** The speed of a scroll wheel / trackpad pan. Default is 1. */
panSpeed: number
/** The speed of a scroll wheel / trackpad zoom. Default is 1. */
zoomSpeed: number
/** The steps that a user can zoom between with zoom in / zoom out. The first and last value will determine the min and max zoom. */
zoomSteps: number[]
/** Controls whether the wheel pans or zooms.
*
* - `zoom`: The wheel will zoom in and out.
* - `pan`: The wheel will pan the camera.
* - `none`: The wheel will do nothing.
*/
wheelBehavior: 'zoom' | 'pan' | 'none'
/** The camera constraints. */
constraints?: {
/** The bounds (in page space) of the constrained space */
bounds: BoxModel
/** The padding inside of the viewport (in screen space) */
padding: VecLike
/** The origin for placement. Used to position the bounds within the viewport when an axis is fixed or contained and zoom is below the axis fit. */
origin: VecLike
/** The camera's initial zoom, used also when the camera is reset.
*
* - `default`: Sets the initial zoom to 100%.
* - `fit-x`: The x axis will completely fill the viewport bounds.
* - `fit-y`: The y axis will completely fill the viewport bounds.
* - `fit-min`: The smaller axis will completely fill the viewport bounds.
* - `fit-max`: The larger axis will completely fill the viewport bounds.
* - `fit-x-100`: The x axis will completely fill the viewport bounds, or 100% zoom, whichever is smaller.
* - `fit-y-100`: The y axis will completely fill the viewport bounds, or 100% zoom, whichever is smaller.
* - `fit-min-100`: The smaller axis will completely fill the viewport bounds, or 100% zoom, whichever is smaller.
* - `fit-max-100`: The larger axis will completely fill the viewport bounds, or 100% zoom, whichever is smaller.
*/
initialZoom:
| 'fit-min'
| 'fit-max'
| 'fit-x'
| 'fit-y'
| 'fit-min-100'
| 'fit-max-100'
| 'fit-x-100'
| 'fit-y-100'
| 'default'
/** The camera's base for its zoom steps.
*
* - `default`: Sets the initial zoom to 100%.
* - `fit-x`: The x axis will completely fill the viewport bounds.
* - `fit-y`: The y axis will completely fill the viewport bounds.
* - `fit-min`: The smaller axis will completely fill the viewport bounds.
* - `fit-max`: The larger axis will completely fill the viewport bounds.
* - `fit-x-100`: The x axis will completely fill the viewport bounds, or 100% zoom, whichever is smaller.
* - `fit-y-100`: The y axis will completely fill the viewport bounds, or 100% zoom, whichever is smaller.
* - `fit-min-100`: The smaller axis will completely fill the viewport bounds, or 100% zoom, whichever is smaller.
* - `fit-max-100`: The larger axis will completely fill the viewport bounds, or 100% zoom, whichever is smaller.
*/
baseZoom:
| 'fit-min'
| 'fit-max'
| 'fit-x'
| 'fit-y'
| 'fit-min-100'
| 'fit-max-100'
| 'fit-x-100'
| 'fit-y-100'
| 'default'
/** The behavior for the constraints for both axes or each axis individually.
*
* - `free`: The bounds are ignored when moving the camera.
* - 'fixed': The bounds will be positioned within the viewport based on the origin
* - `contain`: The 'fixed' behavior will be used when the zoom is below the zoom level at which the bounds would fill the viewport; and when above this zoom, the bounds will use the 'inside' behavior.
* - `inside`: The bounds will stay completely within the viewport.
* - `outside`: The bounds will stay touching the viewport.
*/
behavior:
| 'free'
| 'fixed'
| 'inside'
| 'outside'
| 'contain'
| {
x: 'free' | 'fixed' | 'inside' | 'outside' | 'contain'
y: 'free' | 'fixed' | 'inside' | 'outside' | 'contain'
}
}
}
```
### Change Type
- [x] `sdk` — Changes the tldraw SDK
- [x] `feature` — New feature
### Test Plan
These features combine in different ways, so we'll want to write some
more tests to find surprises.
1. Add a step-by-step description of how to test your PR here.
2.
- [ ] Unit Tests
### Release Notes
- SDK: Adds camera options.
---------
Co-authored-by: Mitja Bezenšek <mitja.bezensek@gmail.com>
|
||
|---|---|---|
| .. | ||
| public | ||
| scripts | ||
| src | ||
| styles | ||
| .eslintignore | ||
| .gitignore | ||
| CHANGELOG.md | ||
| README.md | ||
| decs.d.ts | ||
| index.html | ||
| jestResolver.js | ||
| package.json | ||
| sentry-release-name.ts | ||
| sentry.client.config.ts | ||
| sentry.properties | ||
| setupTests.js | ||
| tsconfig.json | ||
| version.ts | ||
| vite.config.ts | ||
README.md
Project overview
This project is a Next.js application which contains the tldraw free as well as the tldraw pro applications. We are currently using the Next.js 13 option of having both pages (tldraw free) and app (tldraw pro) directory inside the same app. We did this since the free offering is the continuation of a Next.js version 12 app and it allowed us to combine it with the new App router option from Next.js 13 for tldraw pro without having to do a full migration to App router.
We also split the supabase into two projects:
tldraw-v2for tldraw free where we mainly store the snapshots datatldraw-profor tldraw pro which holds all the relational data that the pro version requires
On top of that we also use R2 for storing the documents data.
How to run the project
Tldraw pro
The development of tldraw pro happens against a local supabase instance. To set that up, you'll first need to install & start docker.
Once docker is started & you've run yarn to install tldraw's dependencies, the rest should be
handled automatically. Running yarn dev-app will:
- Start a local instance of supabase
- Run any database migrations
- Update your .env.local file with credentials for your local supabase instance
- Start tldraw
The supabase local development docs are a
good reference. When working on tldraw, the supabase command is available by running yarn supabase in the apps/app directory e.g. yarn supabase status.
When you're finished, we don't stop supabase because it takes a while each time we start and stop
it. Run yarn supabase stop to stop it manually.
If you write any new database migrations, you can apply those with yarn supabase migration up.
Some helpers
- You can see your db schema at the
Studio URLprinted out in the step 2. - If you ever need to reset your local supabase instance you can run
supabase db resetin the root ofapps/appproject. - The production version of Supabase sends out emails for certain events (email confirmation link, password reset link, etc). In local development you can find these emails at the
Inbucket URLprinted out in the step 2.
Tldraw free
The development of tldraw free happens against the production supabase instance. We only store snapshots data to one of the three tables, depending on the environment. The tables are:
snapshots- for productionsnapshots_staging- for stagingsnapshots_dev- for development
For local development you need to add the following env variables to .env.local:
SUPABASE_URL- use the production supabase urlSUPABASE_KEY- use the production supabase anon key
Once you have the environment variables set up you can run yarn dev-app from the root folder of our repo to start developing.
Running database tests
You need to have a psql client installed. You can then run yarn test-supabase to run db tests.
Sending emails
We are using Resend for sending emails. It allows us to write emails as React components. Emails live in a separate app apps/tl-emails.
Right now we are only using Resend via Supabase, but in the future we will probably also include Resend in our application and send emails directly.
The development workflow is as follows:
1. Creating / updating an email template
To start the development server for email run yarn dev-email from the root folder of our repo. You can then open http://localhost:3333 to see the result. This allows for quick local development of email templates.
Any images you want to use in the email should be uploaded to supabase to the email bucket.
Supabase provides some custom params (like the magic link url) that we can insert into our email, check their website for more info.
2. Generating the html version of the email
Once you are happy with the email template you can run yarn build-email from the root folder of our repo. This will generate the html version of the email and place it in apps/tl-emails/out folder.
3. Updating the template in Supabase
Once you have the html version of the email you can copy it into the Supabase template editor. You can find the templates here.