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>
|
||
|---|---|---|
| .. | ||
| app | ||
| components | ||
| content | ||
| public | ||
| scripts | ||
| styles | ||
| types | ||
| utils | ||
| .gitignore | ||
| .prettierignore | ||
| CHANGELOG.md | ||
| LICENSE.md | ||
| README.md | ||
| content.d.ts | ||
| next-env.d.ts | ||
| next.config.js | ||
| package.json | ||
| tsconfig.content.json | ||
| tsconfig.json | ||
| watcher.ts | ||
README.md
tldraw-docs
Welcome to the source for the tldraw docs site.
This site is a Next.js app that uses MDX for content. It contains human-written docs in the content folder as well as generated docs in the api folder.
We have several scripts that build these files into a SQLite database that is used to generate the site's pages.
To pull the most recent docs from the tldraw repo, create an .env file with a GitHub personal access token and the SHA of the commit or branch that you'd like to pull from.
ACCESS_TOKEN=your_github_access_token
SOURCE_SHA=main
The files are also provided in this repo.
Building the content
You can build the markdown and API content using the following scripts:
yarn refresh-everythingto reset the database, generate the markdown from the API docs, and populate the database with articles from both the regular content and the generated API contentyarn refresh-contentto generate just the regular content
Content
The docs has two types of content: regular content that is written by the team and auto-generated content that is created using tsdoc and API extractor.
The content folder contains all content in the form of MDX files. All articles belong to a "section" and a "category". The sections.json defines each section and any categories belonging to that section.
A section looks like this:
{
"id": "community",
"title": "Community",
"description": "Guides for contributing to tldraw's open source project.",
"categories": []
}
The content is organized into folders for each section. The gen folder contains auto-generated content.
Regular Content
The content folder contains all "regular" content in the form of MDX files.All articles belong to a "section" and a "category". The content is organized into folders for each "section".
An article's frontmatter looks like this:
---
title: User Interface
description: How to customize the tldraw user interface using overrides.
status: published
author: steveruizok
date: 3/22/2023
order: 8
keywords:
- ui
- interface
- tools
- shapes
- custom
- button
- toolbar
- styles
---
Title
The title is displayed in the article's header, in the page title, in the search bar, and in search results. It is used to find an article through the site's search feature.
Description
The description is hidden in the article's frontmatter, but is used to populate the article's meta description tag. It is also used to find an article through the site's search feature.
Hero
The hero is used for the article's social media image. It is not displayed in the article. It should refer to a page in the public/images folder.
Category
An article may declare its category in its frontmatter. Any article that does not declare a category will be placed into the "ucg" category for "uncategorized" articles.
Order
The order property defines the article's order in its category. Uncategorized articles are placed at the end of the list of categories sorted by its order. For a section without categories, the order keyword effectively defines the order that the article will appear in the section list.
Author
The author must refer to an author named in the content/authors.json file.
An author looks like this:
"steveruizok": {
"name": "Steve Ruiz",
"email": "steve@tldraw.com",
"twitter": "steveruizok",
"image": "steve_ruiz.jpg"
}
The image should refer to an image in public/avatars.
Date
The date is formatted as DD/MM/YYYY.
Status
An article's status may be either draft or published. A draft article is hidden in production.
Keywords
The keywords are used to find an article through the site's search feature.
Auto-generated content
The auto-generated docs content is created using tsdoc and API extractor. The source is the API documentation created by yarn build or yarn build-api. The output is placed in the gen folder.
Developing the docs
When developing the docs, any change to the content folder will cause the page to refresh. This is a little shitty but it mostly works.
Contribution
Please see our contributing guide. Found a bug? Please submit an issue.
License
The tldraw source code and its distributions are provided under the tldraw license. This license does not permit commercial use.
If you wish to use this project in commercial product, you need to purchase a commercial license. matPlease contact us at sales@tldraw.com for more inforion about obtaining a commercial license.
Trademarks
Copyright (c) 2023-present tldraw Inc. The tldraw name and logo are trademarks of tldraw. Please see our trademark guidelines for info on acceptable usage.
Contact
Find us on Twitter at @tldraw or email sales@tldraw.com. You can also join our discord for quick help and support.