Line data Source code
1 : import { useDebounceFn, useEventListener } from '@vueuse/core'
2 : import { ref } from 'vue'
3 : import type { MaybeRefOrGetter } from 'vue'
4 :
5 : import { isMiddleButtonEvent } from '@/base/pointerUtils'
6 :
7 : interface TransformSettlingOptions {
8 : /**
9 : * Delay in ms before transform is considered "settled" after last interaction
10 : * @default 256
11 : */
12 : settleDelay?: number
13 : /**
14 : * Whether to use passive event listeners (better performance but can't preventDefault)
15 : * @default true
16 : */
17 : passive?: boolean
18 : }
19 :
20 : /**
21 : * Tracks when canvas transforms (zoom or pan) are actively changing vs settled.
22 : *
23 : * This composable helps optimize rendering quality during transform interactions.
24 : * When the user is actively zooming or panning, we can reduce rendering quality
25 : * for better performance. Once the transform "settles" (stops changing), we can
26 : * trigger high-quality re-rasterization.
27 : *
28 : * The settling concept prevents constant quality switching during interactions
29 : * by waiting for a period of inactivity before considering the transform complete.
30 : *
31 : * Uses VueUse's useEventListener for automatic cleanup and useDebounceFn for
32 : * efficient settle detection.
33 : *
34 : * @example
35 : * ```ts
36 : * const { isTransforming } = useTransformSettling(canvasRef, {
37 : * settleDelay: 200
38 : * })
39 : *
40 : * // Use in CSS classes or rendering logic
41 : * const cssClass = computed(() => ({
42 : * 'low-quality': isTransforming.value,
43 : * 'high-quality': !isTransforming.value
44 : * }))
45 : * ```
46 : */
47 874 : export function useTransformSettling(
48 : target: MaybeRefOrGetter<HTMLElement | null | undefined>,
49 : options: TransformSettlingOptions = {}
50 : ) {
51 874 : const { settleDelay = 256, passive = true } = options
52 :
53 874 : const isTransforming = ref(false)
54 :
55 874 : const markTransformSettled = useDebounceFn(() => {
56 4 : isTransforming.value = false
57 : }, settleDelay)
58 :
59 255 : function markInteracting() {
60 255 : isTransforming.value = true
61 255 : void markTransformSettled()
62 : }
63 :
64 874 : const eventOptions = { capture: true, passive }
65 :
66 874 : useEventListener(target, 'wheel', markInteracting, eventOptions)
67 874 : usePointerDrag(target, markInteracting, eventOptions)
68 :
69 874 : return {
70 : isTransforming
71 : }
72 : }
73 :
74 : /**
75 : * Calls `onDrag` on each pointermove while a pointer is held down.
76 : */
77 874 : function usePointerDrag(
78 : target: MaybeRefOrGetter<HTMLElement | null | undefined>,
79 : onDrag: () => void,
80 : eventOptions: AddEventListenerOptions
81 : ) {
82 : /** Number of active pointers (supports multi-touch correctly). */
83 874 : const pointerCount = ref(0)
84 :
85 874 : useEventListener(
86 : target,
87 : 'pointerdown',
88 : (e: PointerEvent) => {
89 : // Only primary (0) and middle (1) buttons trigger canvas pan.
90 229 : if (e.button === 0 || isMiddleButtonEvent(e)) pointerCount.value++
91 : },
92 : eventOptions
93 : )
94 :
95 874 : useEventListener(
96 : target,
97 : 'pointermove',
98 : () => {
99 655 : if (pointerCount.value > 0) onDrag()
100 : },
101 : eventOptions
102 : )
103 :
104 : // Listen on window so the release is caught even if the pointer
105 : // leaves the canvas before the button is released.
106 874 : useEventListener(
107 : window,
108 : 'pointerup',
109 : () => {
110 2330 : if (pointerCount.value > 0) pointerCount.value--
111 : },
112 : eventOptions
113 : )
114 :
115 874 : useEventListener(
116 : window,
117 : 'pointercancel',
118 : () => {
119 3 : if (pointerCount.value > 0) pointerCount.value--
120 : },
121 : eventOptions
122 : )
123 : }
|