tldraw/packages/tlschema
Steve Ruiz fabba66c0f
Camera options (#3282)
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>
2024-05-04 17:39:04 +00:00
..
src Camera options (#3282) 2024-05-04 17:39:04 +00:00
api-extractor.json transfer-out: transfer out 2023-04-25 12:01:25 +01:00
api-report.md Camera options (#3282) 2024-05-04 17:39:04 +00:00
CHANGELOG.md Update CHANGELOG.md [skip ci] 2024-04-23 11:47:53 +00:00
LICENSE.md Change licenses to tldraw (#2167) 2023-12-19 10:41:01 +00:00
package.json Update CHANGELOG.md [skip ci] 2024-04-23 11:47:53 +00:00
README.md Fix trademark links (#2380) 2023-12-26 09:22:04 +00:00
tsconfig.json Check tsconfig "references" arrays (#2891) 2024-02-21 13:07:53 +00:00

@tldraw/tlschema

This package houses type definitions, schema migrations, and other type metadata for the tldraw editor's default persisted data.

There are three main kinds of types:

  • Record types

    These are root record types added to the Store class. They are defined in the ./src/records directory.

  • Shape types

    These are subtypes of the root TLShape record type. They allow specifying a unique name and custom props for a particular kind of shape.

  • Asset types

    These are subtypes of the root TLAsset record type. They allow specifying a unique name and custom props for a particular kind of asset.

Adding migrations

If you make any kind of change to any persisted data shape in this package, you must add migrations that are able to convert old versions to new versions, and vice-versa.

If you are making a change that affects the structure of a record, shape, or asset, update the migrations in the same file as the record, shape, or asset is defined.

If you are making a change that affects the structure of the store (e.g. renaming or deleting a type, consolidating two shape types into one, etc), add your changes in the migrations in schema.ts.

After making your changes, add a new version number, using a meaninful name. For example, if you add a new property to the TLShape type called ownerId that points to a user, you might do this:

In TLShape.ts

 const Versions = {
   RemoveSomeProp: 1,
+  AddOwnerId: 2,
 } as const

and then in the TLShape type

   x: number
   y: number
+  ownerId: ID<TLUser> | null
   props: Props
   parentId: ID<TLShape> | ID<TLPage>

and then adding a migration:

 export const shapeTypeMigrations = defineMigrations({
   currentVersion: Versions.Initial,
   firstVersion: Versions.Initial,
   migrators: {
+    [Versions.AddOwnerId]: {
+      // add ownerId property
+      up: (shape) => ({...shape, ownerId: null}),
+      // remove ownerId property
+      down: ({ownerId, ...shape}) => shape,
+    }
   },

After you've added your migration, make sure to add a test for it in src/migrations.test.ts. It will complain if you do not!

Community

Have questions, comments or feedback? Join our discord or start a discussion.

Distributions

You can find tldraw on npm here.

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. Please contact us at hello@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 hello@tldraw.com. You can also join our discord for quick help and support.