Add long press event (#3275)

This PR adds a "long press" event that fires when pointing for more than
500ms. This event is used in the same way that dragging is used (e.g. to
transition to from pointing_selection to translating) but only on
desktop. On mobile, long presses are used to open the context menu.

![Kapture 2024-03-26 at 18 57
15](https://github.com/tldraw/tldraw/assets/23072548/34a7ee2b-bde6-443b-93e0-082453a1cb61)

## Background

This idea came out of @TodePond's #3208 PR. We use a "dead zone" to
avoid accidentally moving / rotating things when clicking on them, which
is especially common on mobile if a dead zone feature isn't implemented.
However, this makes it difficult to make "fine adjustments" because you
need to drag out of the dead zone (to start translating) and then drag
back to where you want to go.

![Kapture 2024-03-26 at 19 00
38](https://github.com/tldraw/tldraw/assets/23072548/9a15852d-03d0-4b88-b594-27dbd3b68780)

With this change, you can long press on desktop to get to that
translating state. It's a micro UX optimization but especially nice if
apps want to display different UI for "dragging" shapes before the user
leaves the dead zone.

![Kapture 2024-03-26 at 19 02
59](https://github.com/tldraw/tldraw/assets/23072548/f0ff337e-2cbd-4b73-9ef5-9b7deaf0ae91)

### Change Type

<!-- ❗ Please select a 'Scope' label ❗️ -->

- [x] `sdk` — Changes the tldraw SDK
- [ ] `dotcom` — Changes the tldraw.com web app
- [ ] `docs` — Changes to the documentation, examples, or templates.
- [ ] `vs code` — Changes to the vscode plugin
- [ ] `internal` — Does not affect user-facing stuff

<!-- ❗ Please select a 'Type' label ❗️ -->

- [ ] `bugfix` — Bug fix
- [x] `feature` — New feature
- [ ] `improvement` — Improving existing features
- [ ] `chore` — Updating dependencies, other boring stuff
- [ ] `galaxy brain` — Architectural changes
- [ ] `tests` — Changes to any test code
- [ ] `tools` — Changes to infrastructure, CI, internal scripts,
debugging tools, etc.
- [ ] `dunno` — I don't know


### Test Plan

1. Long press shapes, selections, resize handles, rotate handles, crop
handles.
2. You should enter the corresponding states, just as you would have
with a drag.

- [ ] Unit Tests TODO

### Release Notes

- Add support for long pressing on desktop.

packages/editor/api-report.md

@@ -1824,6 +1824,8 @@ export abstract class StateNode implements Partial<TLEventHandlers> {
     // (undocumented)
     onKeyUp?: TLEventHandlers['onKeyUp'];
     // (undocumented)
+    onLongPress?: TLEventHandlers['onLongPress'];
+    // (undocumented)
     onMiddleClick?: TLEventHandlers['onMiddleClick'];
     // (undocumented)
     onPointerDown?: TLEventHandlers['onPointerDown'];
@@ -2144,6 +2146,8 @@ export interface TLEventHandlers {
     // (undocumented)
     onKeyUp: TLKeyboardEvent;
     // (undocumented)
+    onLongPress: TLPointerEvent;
+    // (undocumented)
     onMiddleClick: TLPointerEvent;
     // (undocumented)
     onPointerDown: TLPointerEvent;
@@ -2418,7 +2422,7 @@ export type TLPointerEventInfo = TLBaseEventInfo & {
 } & TLPointerEventTarget;
 
 // @public (undocumented)
-export type TLPointerEventName = 'middle_click' | 'pointer_down' | 'pointer_move' | 'pointer_up' | 'right_click';
+export type TLPointerEventName = 'long_press' | 'middle_click' | 'pointer_down' | 'pointer_move' | 'pointer_up' | 'right_click';
 
 // @public (undocumented)
 export type TLPointerEventTarget = {

packages/editor/api/api.json

@@ -34940,6 +34940,41 @@
               "isProtected": false,
               "isAbstract": false
             },
+            {
+              "kind": "Property",
+              "canonicalReference": "@tldraw/editor!StateNode#onLongPress:member",
+              "docComment": "",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "onLongPress?: "
+                },
+                {
+                  "kind": "Reference",
+                  "text": "TLEventHandlers",
+                  "canonicalReference": "@tldraw/editor!TLEventHandlers:interface"
+                },
+                {
+                  "kind": "Content",
+                  "text": "['onLongPress']"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": false,
+              "isOptional": true,
+              "releaseTag": "Public",
+              "name": "onLongPress",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 3
+              },
+              "isStatic": false,
+              "isProtected": false,
+              "isAbstract": false
+            },
             {
               "kind": "Property",
               "canonicalReference": "@tldraw/editor!StateNode#onMiddleClick:member",
@@ -38355,6 +38390,34 @@
                 "endIndex": 2
               }
             },
+            {
+              "kind": "PropertySignature",
+              "canonicalReference": "@tldraw/editor!TLEventHandlers#onLongPress:member",
+              "docComment": "",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "onLongPress: "
+                },
+                {
+                  "kind": "Reference",
+                  "text": "TLPointerEvent",
+                  "canonicalReference": "@tldraw/editor!TLPointerEvent:type"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": false,
+              "isOptional": false,
+              "releaseTag": "Public",
+              "name": "onLongPress",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              }
+            },
             {
               "kind": "PropertySignature",
               "canonicalReference": "@tldraw/editor!TLEventHandlers#onMiddleClick:member",
@@ -41004,7 +41067,7 @@
             },
             {
               "kind": "Content",
-              "text": "'middle_click' | 'pointer_down' | 'pointer_move' | 'pointer_up' | 'right_click'"
+              "text": "'long_press' | 'middle_click' | 'pointer_down' | 'pointer_move' | 'pointer_up' | 'right_click'"
             },
             {
               "kind": "Content",

packages/editor/src/lib/constants.ts

@@ -104,3 +104,6 @@ export const COARSE_HANDLE_RADIUS = 20
 
 /** @internal */
 export const HANDLE_RADIUS = 12
+
+/** @internal */
+export const LONG_PRESS_DURATION = 500

packages/editor/src/lib/editor/Editor.ts

@@ -79,6 +79,7 @@ import {
 	FOLLOW_CHASE_ZOOM_UNSNAP,
 	HIT_TEST_MARGIN,
 	INTERNAL_POINTER_IDS,
+	LONG_PRESS_DURATION,
 	MAX_PAGES,
 	MAX_SHAPES_PER_PAGE,
 	MAX_ZOOM,
@@ -8348,6 +8349,9 @@ export class Editor extends EventEmitter<TLEventMap> {
 	/** @internal */
 	private _selectedShapeIdsAtPointerDown: TLShapeId[] = []
 
+	/** @internal */
+	private _longPressTimeout = -1 as any
+
 	/** @internal */
 	capturedPointerId: number | null = null
 
@@ -8384,8 +8388,8 @@ export class Editor extends EventEmitter<TLEventMap> {
 			}
 			if (elapsed > 0) {
 				this.root.handleEvent({ type: 'misc', name: 'tick', elapsed })
-				this.scribbles.tick(elapsed)
 			}
+			this.scribbles.tick(elapsed)
 		})
 	}
 
@@ -8450,6 +8454,7 @@ export class Editor extends EventEmitter<TLEventMap> {
 		switch (type) {
 			case 'pinch': {
 				if (!this.getInstanceState().canMoveCamera) return
+				clearTimeout(this._longPressTimeout)
 				this._updateInputsFromEvent(info)
 
 				switch (info.name) {
@@ -8574,6 +8579,7 @@ export class Editor extends EventEmitter<TLEventMap> {
 							(this.getInstanceState().isCoarsePointer ? COARSE_DRAG_DISTANCE : DRAG_DISTANCE) /
 								this.getZoomLevel()
 					) {
+						clearTimeout(this._longPressTimeout)
 						inputs.isDragging = true
 					}
 				}
@@ -8591,6 +8597,10 @@ export class Editor extends EventEmitter<TLEventMap> {
 					case 'pointer_down': {
 						this.clearOpenMenus()
 
+						this._longPressTimeout = setTimeout(() => {
+							this.dispatch({ ...info, name: 'long_press' })
+						}, LONG_PRESS_DURATION)
+
 						this._selectedShapeIdsAtPointerDown = this.getSelectedShapeIds()
 
 						// Firefox bug fix...
@@ -8659,6 +8669,7 @@ export class Editor extends EventEmitter<TLEventMap> {
 								(this.getInstanceState().isCoarsePointer ? COARSE_DRAG_DISTANCE : DRAG_DISTANCE) /
 									this.getZoomLevel()
 						) {
+							clearTimeout(this._longPressTimeout)
 							inputs.isDragging = true
 						}
 						break
@@ -8801,6 +8812,8 @@ export class Editor extends EventEmitter<TLEventMap> {
 						break
 					}
 					case 'pointer_up': {
+						clearTimeout(this._longPressTimeout)
+
 						const otherEvent = this._clickManager.transformPointerUpEvent(info)
 						if (info.name !== otherEvent.name) {
 							this.root.handleEvent(info)

packages/editor/src/lib/editor/tools/StateNode.ts

@@ -198,6 +198,7 @@ export abstract class StateNode implements Partial<TLEventHandlers> {
 	onWheel?: TLEventHandlers['onWheel']
 	onPointerDown?: TLEventHandlers['onPointerDown']
 	onPointerMove?: TLEventHandlers['onPointerMove']
+	onLongPress?: TLEventHandlers['onLongPress']
 	onPointerUp?: TLEventHandlers['onPointerUp']
 	onDoubleClick?: TLEventHandlers['onDoubleClick']
 	onTripleClick?: TLEventHandlers['onTripleClick']

packages/editor/src/lib/editor/types/event-types.ts

@@ -16,6 +16,7 @@ export type TLPointerEventTarget =
 export type TLPointerEventName =
 	| 'pointer_down'
 	| 'pointer_move'
+	| 'long_press'
 	| 'pointer_up'
 	| 'right_click'
 	| 'middle_click'
@@ -152,6 +153,7 @@ export type TLExitEventHandler = (info: any, to: string) => void
 export interface TLEventHandlers {
 	onPointerDown: TLPointerEvent
 	onPointerMove: TLPointerEvent
+	onLongPress: TLPointerEvent
 	onRightClick: TLPointerEvent
 	onDoubleClick: TLClickEvent
 	onTripleClick: TLClickEvent
@@ -176,6 +178,7 @@ export const EVENT_NAME_MAP: Record<
 	wheel: 'onWheel',
 	pointer_down: 'onPointerDown',
 	pointer_move: 'onPointerMove',
+	long_press: 'onLongPress',
 	pointer_up: 'onPointerUp',
 	right_click: 'onRightClick',
 	middle_click: 'onMiddleClick',

packages/tldraw/src/lib/tools/SelectTool/childStates/PointingCropHandle.ts

@@ -37,16 +37,23 @@ export class PointingCropHandle extends StateNode {
 	}
 
 	override onPointerMove: TLEventHandlers['onPointerMove'] = () => {
-		const isDragging = this.editor.inputs.isDragging
-
-		if (isDragging) {
-			this.parent.transition('cropping', {
-				...this.info,
-				onInteractionEnd: this.info.onInteractionEnd,
-			})
+		if (this.editor.inputs.isDragging) {
+			this.startCropping()
 		}
 	}
 
+	override onLongPress: TLEventHandlers['onLongPress'] = () => {
+		this.startCropping()
+	}
+
+	private startCropping() {
+		if (this.editor.getInstanceState().isReadonly) return
+		this.parent.transition('cropping', {
+			...this.info,
+			onInteractionEnd: this.info.onInteractionEnd,
+		})
+	}
+
 	override onPointerUp: TLEventHandlers['onPointerUp'] = () => {
 		if (this.info.onInteractionEnd) {
 			this.editor.setCurrentTool(this.info.onInteractionEnd, this.info)

packages/tldraw/src/lib/tools/SelectTool/childStates/PointingHandle.ts

@@ -37,10 +37,19 @@ export class PointingHandle extends StateNode {
 
 	override onPointerMove: TLEventHandlers['onPointerMove'] = () => {
 		if (this.editor.inputs.isDragging) {
-			this.parent.transition('dragging_handle', this.info)
+			this.startDraggingHandle()
 		}
 	}
 
+	override onLongPress: TLEventHandlers['onLongPress'] = () => {
+		this.startDraggingHandle()
+	}
+
+	private startDraggingHandle() {
+		if (this.editor.getInstanceState().isReadonly) return
+		this.parent.transition('dragging_handle', this.info)
+	}
+
 	override onCancel: TLEventHandlers['onCancel'] = () => {
 		this.cancel()
 	}

packages/tldraw/src/lib/tools/SelectTool/childStates/PointingResizeHandle.ts

@@ -48,13 +48,20 @@ export class PointingResizeHandle extends StateNode {
 	}
 
 	override onPointerMove: TLEventHandlers['onPointerMove'] = () => {
-		const isDragging = this.editor.inputs.isDragging
-
-		if (isDragging) {
-			this.parent.transition('resizing', this.info)
+		if (this.editor.inputs.isDragging) {
+			this.startResizing()
 		}
 	}
 
+	override onLongPress: TLEventHandlers['onLongPress'] = () => {
+		this.startResizing()
+	}
+
+	private startResizing() {
+		if (this.editor.getInstanceState().isReadonly) return
+		this.parent.transition('resizing', this.info)
+	}
+
 	override onPointerUp: TLEventHandlers['onPointerUp'] = () => {
 		this.complete()
 	}

packages/tldraw/src/lib/tools/SelectTool/childStates/PointingRotateHandle.ts

@@ -33,14 +33,21 @@ export class PointingRotateHandle extends StateNode {
 		)
 	}
 
-	override onPointerMove = () => {
-		const { isDragging } = this.editor.inputs
-
-		if (isDragging) {
-			this.parent.transition('rotating', this.info)
+	override onPointerMove: TLEventHandlers['onPointerMove'] = () => {
+		if (this.editor.inputs.isDragging) {
+			this.startRotating()
 		}
 	}
 
+	override onLongPress: TLEventHandlers['onLongPress'] = () => {
+		this.startRotating()
+	}
+
+	private startRotating() {
+		if (this.editor.getInstanceState().isReadonly) return
+		this.parent.transition('rotating', this.info)
+	}
+
 	override onPointerUp = () => {
 		this.complete()
 	}

packages/tldraw/src/lib/tools/SelectTool/childStates/PointingSelection.ts

@@ -25,11 +25,19 @@ export class PointingSelection extends StateNode {
 
 	override onPointerMove: TLEventHandlers['onPointerMove'] = (info) => {
 		if (this.editor.inputs.isDragging) {
-			if (this.editor.getInstanceState().isReadonly) return
-			this.parent.transition('translating', info)
+			this.startTranslating(info)
 		}
 	}
 
+	override onLongPress: TLEventHandlers['onLongPress'] = (info) => {
+		this.startTranslating(info)
+	}
+
+	private startTranslating(info: TLPointerEventInfo) {
+		if (this.editor.getInstanceState().isReadonly) return
+		this.parent.transition('translating', info)
+	}
+
 	override onDoubleClick?: TLClickEvent | undefined = (info) => {
 		const hoveredShape = this.editor.getHoveredShape()
 		const hitShape =

packages/tldraw/src/lib/tools/SelectTool/childStates/PointingShape.ts

@@ -195,11 +195,19 @@ export class PointingShape extends StateNode {
 
 	override onPointerMove: TLEventHandlers['onPointerMove'] = (info) => {
 		if (this.editor.inputs.isDragging) {
-			if (this.editor.getInstanceState().isReadonly) return
-			this.parent.transition('translating', info)
+			this.startTranslating(info)
 		}
 	}
 
+	override onLongPress: TLEventHandlers['onLongPress'] = (info) => {
+		this.startTranslating(info)
+	}
+
+	private startTranslating(info: TLPointerEventInfo) {
+		if (this.editor.getInstanceState().isReadonly) return
+		this.parent.transition('translating', info)
+	}
+
 	override onCancel: TLEventHandlers['onCancel'] = () => {
 		this.cancel()
 	}

packages/tldraw/src/lib/tools/SelectTool/childStates/ScribbleBrushing.ts

@@ -42,9 +42,7 @@ export class ScribbleBrushing extends StateNode {
 
 		this.updateScribbleSelection(true)
 
-		requestAnimationFrame(() => {
-			this.editor.updateInstanceState({ brush: null })
-		})
+		this.editor.updateInstanceState({ brush: null })
 	}
 
 	override onExit = () => {