feat: add use-long-press (#150)

* feat: add use-long-press

* fix: cannot get correct dom target when target is vue component instance

* docs: add useLongPress docs router path

* style: optimized code line

In alphabetical order

* style: optimized code line

In alphabetical order

* docs: update long-press zh-cn docs

* feat: supported point event on use-long-press

---------

Co-authored-by: YongGit <1013588891@qq.com>

Author: erikkkwu

packages/hooks/docs/.vitepress/router.ts

@@ -67,6 +67,7 @@ const Router = [
       { text: 'useScroll', link: '/useScroll/' },
       { text: 'useTitle', link: '/useTitle/' },
       { text: 'useWinResize', link: '/useWinResize/' },
+      { text: 'useLongPress', link: '/useLongPress/' },
     ],
   },
   {

packages/hooks/src/index.ts

@@ -25,6 +25,7 @@ import useInViewport from './useInViewport'
 import useKeyPress from './useKeyPress'
 import useLocalStorageState from './useLocalStorageState'
 import useLockFn from './useLockFn'
+import useLongPress from './useLongPress'
 import useMouse from './useMouse'
 import useMap from './useMap'
 import useMedia from './useMedia'
@@ -75,6 +76,7 @@ export {
   useKeyPress,
   useLocalStorageState,
   useLockFn,
+  useLongPress,
   useMap,
   useMedia,
   useMouse,
@@ -97,5 +99,5 @@ export {
   useVirtualList,
   useWhyDidYouUpdate,
   useWinResize,
-  useWebSocket,
+  useWebSocket
 }

packages/hooks/src/useLongPress/__tests__/index.spec.ts

@@ -0,0 +1,104 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import useLongPress from '../index'
+import renderHook from 'test-utils/renderHook'
+
+describe('useLongPressStatus tests', () => {
+  let targetMock: HTMLElement
+  const mouseDownEvent: PointerEvent = new PointerEvent('pointerdown')
+  const mouseUpEvent: PointerEvent = new PointerEvent('pointerup')
+  const mouseMoveEvent: PointerEvent = new PointerEvent('pointermove')
+  beforeEach(() => {
+    targetMock = document.createElement('div')
+    vi.useFakeTimers({
+      toFake: [ 'setTimeout', 'setInterval' ],
+    });
+  });
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+  it('should change isPressed status when user longPress in 500ms', async () => {
+    const [ result ] = renderHook(() => useLongPress(targetMock))
+
+    targetMock.dispatchEvent(mouseDownEvent);
+
+    expect(result.isPressing.value).toBeFalsy()
+
+    vi.advanceTimersByTime(500);
+
+    expect(result.isPressing.value).toBeTruthy()
+  });
+
+  it('should record pressed every 100ms', () => {
+    const [ result ] = renderHook(() => useLongPress(targetMock))
+    targetMock.dispatchEvent(mouseDownEvent);
+
+    expect(result.pressingTime.value).toBe(0);
+
+    vi.advanceTimersByTime(500);
+    expect(result.pressingTime.value).toBe(0);
+
+    vi.advanceTimersByTime(100);
+    expect(result.pressingTime.value).toBe(100);
+
+    vi.advanceTimersByTime(100);
+    expect(result.pressingTime.value).toBe(200);
+  });
+
+  it('should reset pressingTime and isPressing when user mouseUp', async () => {
+    const [ result ] = renderHook(() => useLongPress(targetMock))
+
+    targetMock.dispatchEvent(mouseDownEvent);
+    vi.advanceTimersByTime(600);
+
+    expect(result.pressingTime.value).toBe(100);
+    expect(result.isPressing.value).toBeTruthy()
+
+    targetMock.dispatchEvent(mouseUpEvent)
+
+    expect(result.pressingTime.value).toBe(0);
+    expect(result.isPressing.value).toBeFalsy()
+  });
+
+  it('should reset pressingTime and isPressing when user mouseMove', async () => {
+    const [ result ] = renderHook(() => useLongPress(targetMock))
+
+    targetMock.dispatchEvent(mouseDownEvent);
+    vi.advanceTimersByTime(600);
+
+    expect(result.pressingTime.value).toBe(100);
+    expect(result.isPressing.value).toBeTruthy()
+
+    targetMock.dispatchEvent(mouseMoveEvent);
+
+    expect(result.pressingTime.value).toBe(0);
+    expect(result.isPressing.value).toBeFalsy()
+  });
+  //
+  it('should not cancel event on mouseLeave when cancelOnMove toggle is false', async () => {
+    const [ { pressingTime, isPressing } ] = renderHook(() => useLongPress(targetMock, {
+      cancelOnMove: false,
+    }))
+
+    targetMock.dispatchEvent(mouseDownEvent);
+
+    vi.advanceTimersByTime(600);
+    expect(pressingTime.value).toBe(100);
+    expect(isPressing.value).toBeTruthy()
+
+    targetMock.dispatchEvent(mouseMoveEvent);
+
+    expect(pressingTime.value).toBe(100);
+    expect(isPressing.value).toBeTruthy()
+  });
+
+  it('should stop all event listener when component unmounted', async () => {
+    const elementRemoveEventListenerSpy = vi.spyOn(targetMock, 'removeEventListener');
+    const [ , app ] = renderHook(() => useLongPress(targetMock))
+
+    app.unmount()
+
+    expect(elementRemoveEventListenerSpy).toHaveBeenCalledWith(mouseDownEvent.type, expect.any(Function));
+    expect(elementRemoveEventListenerSpy).toHaveBeenCalledWith(mouseUpEvent.type, expect.any(Function));
+    expect(elementRemoveEventListenerSpy).toHaveBeenCalledWith(mouseMoveEvent.type, expect.any(Function));
+  });
+});

packages/hooks/src/useLongPress/demo/demo.vue

@@ -0,0 +1,19 @@
+<template>
+  <div>
+    <p>
+      {{ pressingTime }} ms
+    </p>
+    <div>
+      <vhp-button ref="pressButton"> {{ isPressing ? 'Pressing' : 'Click' }}</vhp-button>
+    </div>
+  </div>
+</template>
+
+<script lang="ts" setup>
+import { useLongPress } from 'vue-hooks-plus'
+import { ref } from 'vue'
+
+const pressButton = ref(null)
+const { pressingTime , isPressing } = useLongPress(pressButton)
+
+</script>

packages/hooks/src/useLongPress/index.en-US.md

@@ -0,0 +1,55 @@
+---
+map:
+  # Path mapped to docs
+  path: /useLongPress
+---
+
+# useLongPress
+
+Listen for a long press on an element.
+
+## Code demonstration
+
+<demo src="./demo/demo.vue"
+  language="vue"
+  title="Basic usage"
+  desc="listen for a long press on an element."> </demo>
+
+## API
+
+```typescript
+const { isPressing , pressingTime } = useLongPress(target: BasicTarget , options?: LongPressOptions)
+```
+
+## Result
+
+| Property     | Description                                                                                                                  | Type                     |
+|--------------|------------------------------------------------------------------------------------------------------------------------------|--------------------------|
+| isPressing   | Indicates the current pressing state. If pressing, the value is true; otherwise it's false.                                  | `Readonly<Ref<boolean>>` |
+| pressingTime | Represents the duration of pressing (possibly in milliseconds). This value will only be updated during the pressing period.  | `Readonly<Ref<number>>`  |
+
+## Params
+
+| Property | Description            | Type                                                        | Default |
+|----------|------------------------|-------------------------------------------------------------|---------|
+| target   | DOM element or ref     | `() => Element` \| `Element` \| `MutableRefObject<Element>` | -       |
+| options  | Additional config      | `UseLongPressOptions`                                       | -       |
+
+### DropOptions
+
+| Property      | Description                                                      | Type                  | Default |
+|---------------|------------------------------------------------------------------|-----------------------|---------|
+| delay         | Time in ms till `longpress` gets called                          | `number`              | 500     |
+| minUpdateTime | Minimum time interval in ms for updating the `longpress` event   | `number`              | 100     |
+| cancelOnMove  | Whether to cancel the longpress event when mouse move            | `boolean`             | true    |
+| modifiers     | `longpress` event modifiers                                      | `LongPressModifiers`  | -       |
+
+### LongPressModifiers
+
+| Property   | Description                             | Type         | Default |
+|------------|-----------------------------------------|--------------|---------|
+| stop       | stopPropagation event                   | `boolean`    | -       |
+| once       | eventListener once option               | `boolean`    | -       |
+| prevent    | preventDefault event                    | `boolean`    | -       |
+| capture    | eventListener capture option            | `boolean`    | -       |
+| self       | check event target element same as self | `boolean`    | -       |

packages/hooks/src/useLongPress/index.ts

@@ -0,0 +1,134 @@
+import { BasicTarget, getTargetElement } from '../utils/domTarget'
+import { DeepReadonly, readonly, Ref, ref } from 'vue'
+import useEffectWithTarget from '../utils/useEffectWithTarget'
+
+export interface UseLongPressOptions {
+  delay?: number;
+  minUpdateTime?: number;
+  cancelOnMove?: boolean;
+  modifiers?: LongPressModifiers;
+}
+
+export interface LongPressModifiers {
+  stop?: boolean;
+  once?: boolean;
+  prevent?: boolean;
+  capture?: boolean;
+  self?: boolean;
+}
+
+type MouseDownEvents = 'pointerdown' | 'touchstart' | 'mousedown';
+type MouseUpEvents = 'pointerup' | 'touchend' | 'mouseup';
+type MouseMoveEvents = 'pointermove' | 'touchmove' | 'mousemove';
+
+const getSupportedMouseEvents = (): {
+  mouseMove: MouseMoveEvents;
+  mouseUp: MouseUpEvents;
+  mouseDown: MouseDownEvents
+} => {
+  const hasPointEvent = 'PointerEvent' in window;
+  if (hasPointEvent) {
+    return {
+      mouseDown: 'pointerdown',
+      mouseUp: 'pointerup',
+      mouseMove: 'pointermove'
+    }
+  }
+
+  const isTouch = 'ontouchstart' in window || navigator.maxTouchPoints > 0;
+
+  if (isTouch) {
+    return {
+      mouseDown: 'touchstart',
+      mouseUp: 'touchend',
+      mouseMove: 'touchmove'
+    }
+  }
+
+  return {
+    mouseDown: 'mousedown',
+    mouseUp: 'mouseup',
+    mouseMove: 'mousemove'
+  }
+}
+
+const useLongPress: ( target: BasicTarget, options?: UseLongPressOptions ) => {
+  pressingTime: DeepReadonly<Ref<number>>;
+  isPressing: DeepReadonly<Ref<boolean>>
+} = ( target: BasicTarget, options: UseLongPressOptions = {} ) => {
+  const DEFAULT_DELAY_TIME = 500
+  const DEFAULT_UPDATE_TIME = 100
+
+  const isPressing = ref<boolean>(false)
+  const pressingTime = ref(0);
+
+  let pressingTimer: ReturnType<typeof setTimeout> | undefined;
+  let timeoutTimer: ReturnType<typeof setTimeout> | undefined;
+  const eventOptions = {
+    capture: options?.modifiers?.capture,
+    once: options?.modifiers?.once,
+  };
+
+  useEffectWithTarget(
+    () => {
+      const targetElement = getTargetElement(target)
+      if (!targetElement) {
+        return
+      }
+
+      const { mouseDown, mouseUp, mouseMove } = getSupportedMouseEvents()
+
+      function clear() {
+        if (timeoutTimer) {
+          clearTimeout(timeoutTimer);
+          timeoutTimer = undefined;
+        }
+
+        if (pressingTimer) {
+          clearInterval(pressingTimer);
+          pressingTimer = undefined;
+        }
+        pressingTime.value = 0;
+        isPressing.value = false;
+      }
+
+      function onDown( ev: Event ): void {
+        if (options.modifiers?.self && ev.target !== targetElement) return;
+
+        clear();
+
+        if (options.modifiers?.prevent) ev.preventDefault();
+
+        if (options.modifiers?.stop) ev.stopPropagation();
+
+        timeoutTimer = setTimeout(() => {
+          isPressing.value = true;
+          pressingTimer = setInterval(() => {
+            pressingTime.value += options.minUpdateTime || DEFAULT_UPDATE_TIME;
+          }, options.minUpdateTime || DEFAULT_UPDATE_TIME)
+        }, options.delay || DEFAULT_DELAY_TIME);
+      }
+
+
+      targetElement.addEventListener(mouseDown, onDown, eventOptions);
+      targetElement.addEventListener(mouseUp, clear, eventOptions);
+      if (options.cancelOnMove ?? true) {
+        targetElement.addEventListener(mouseMove, clear, eventOptions);
+      }
+
+      return () => {
+        targetElement.removeEventListener(mouseDown, onDown);
+        targetElement.removeEventListener(mouseUp, clear);
+        if (options.cancelOnMove ?? true) {
+          targetElement.removeEventListener(mouseMove, clear);
+        }
+      }
+    },
+    [],
+    target,
+  )
+
+  return { isPressing: readonly(isPressing), pressingTime: readonly(pressingTime) }
+}
+
+export default useLongPress