tldraw/assets/translations
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
..
ar.json Lokalise: Translations update (#2908) 2024-02-22 11:20:51 +00:00
ca.json Lokalise: Translations update (#2908) 2024-02-22 11:20:51 +00:00
cs.json Lokalise: Translations update (#2908) 2024-02-22 11:20:51 +00:00
da.json Lokalise: Translations update (#2908) 2024-02-22 11:20:51 +00:00
de.json Lokalise: Translations update (#2908) 2024-02-22 11:20:51 +00:00
en.json transfer-out: transfer out 2023-04-25 12:01:25 +01:00
es.json Lokalise: Translations update (#2908) 2024-02-22 11:20:51 +00:00
fa.json Lokalise: Translations update (#2908) 2024-02-22 11:20:51 +00:00
fi.json Lokalise: Translations update (#2908) 2024-02-22 11:20:51 +00:00
fr.json Lokalise: Translations update (#3649) 2024-04-30 10:23:23 +00:00
gl.json Lokalise: Translations update (#2908) 2024-02-22 11:20:51 +00:00
he.json Update community translations + remove unused translations (#1356) 2023-05-12 15:32:22 +00:00
hi-in.json Lokalise: Translations update (#2908) 2024-02-22 11:20:51 +00:00
hr.json Lokalise: Translations update (#2908) 2024-02-22 11:20:51 +00:00
hu.json Lokalise: Translations update (#3649) 2024-04-30 10:23:23 +00:00
id.json Lokalise: Translations update (#3649) 2024-04-30 10:23:23 +00:00
it.json Lokalise: Translations update (#2908) 2024-02-22 11:20:51 +00:00
ja.json Lokalise: Translations update (#2908) 2024-02-22 11:20:51 +00:00
ko-kr.json Lokalise: Translations update (#3649) 2024-04-30 10:23:23 +00:00
ku.json Update community translations + remove unused translations (#1356) 2023-05-12 15:32:22 +00:00
languages.json Lokalise: Translations update (#3649) 2024-04-30 10:23:23 +00:00
main.json Readonly / room creation omnibus (#3192) 2024-04-25 14:10:40 +00:00
my.json Update community translations + remove unused translations (#1356) 2023-05-12 15:32:22 +00:00
ne.json Lokalise: Translations update (#2908) 2024-02-22 11:20:51 +00:00
no.json Update community translations + remove unused translations (#1356) 2023-05-12 15:32:22 +00:00
pl.json Update community translations + remove unused translations (#1356) 2023-05-12 15:32:22 +00:00
pt-br.json improves translation into pt-br (#2231) 2023-11-27 13:45:25 +00:00
pt-pt.json Update community translations + remove unused translations (#1356) 2023-05-12 15:32:22 +00:00
ro.json Update romanian translations (#3269) 2024-03-26 18:34:31 +00:00
ru.json Lokalise: Translations update (#2908) 2024-02-22 11:20:51 +00:00
sl.json Camera options (#3282) 2024-05-04 17:39:04 +00:00
sv.json Update community translations + remove unused translations (#1356) 2023-05-12 15:32:22 +00:00
te.json Update community translations + remove unused translations (#1356) 2023-05-12 15:32:22 +00:00
th.json Lokalise: Translations update (#2908) 2024-02-22 11:20:51 +00:00
tr.json Lokalise: Translations update (#2908) 2024-02-22 11:20:51 +00:00
uk.json Lokalise: Translations update (#2908) 2024-02-22 11:20:51 +00:00
vi.json Lokalise: Translations update (#2908) 2024-02-22 11:20:51 +00:00
zh-cn.json Lokalise: Translations update (#2908) 2024-02-22 11:20:51 +00:00
zh-tw.json Lokalise: Translations update (#2908) 2024-02-22 11:20:51 +00:00