Merge pull request #407 from antonioru/feat/use-long-press

feat(hook): introduces useLongPress hook

Author: antonioru

.eslintrc.js

@@ -34,7 +34,8 @@ module.exports = {
     'import/no-named-as-default-member': 'off',
     '@typescript-eslint/explicit-function-return-type': 'off',
     '@typescript-eslint/strict-boolean-expressions': 'off',
-    '@typescript-eslint/no-non-null-assertion': 'off'
+    '@typescript-eslint/no-non-null-assertion': 'off',
+    '@typescript-eslint/no-invalid-void-type': 'off'
   },
   overrides: [
     {

.github/workflows/branch-tests.yml

@@ -13,17 +13,13 @@ jobs:
     if: "!contains(github.event.head_commit.message, 'skip ci')"
     runs-on: ubuntu-latest
 
-    strategy:
-      matrix:
-        node-version: [ 18.14 ]
-
     steps:
-      - uses: actions/checkout@v2
-      - name: Testing branch on Node version ${{ matrix.node-version }}
-        uses: actions/setup-node@v1
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
         with:
-          node-version: ${{ matrix.node-version }}
-      - run: npm install --force
+          node-version: 18.14
+
+      - run: npm install
       - run: npm run lint
       - run: npm run build
       - run: npm test

.github/workflows/ci.yml

@@ -14,31 +14,31 @@ jobs:
     if: "!contains(github.event.head_commit.message, 'skip ci')"
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v2
-      - uses: actions/setup-node@v1
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
         with:
           node-version: 18.14
           registry-url: https://registry.npmjs.org/
 
-      - name: NPM CI
+      - name: NPM Install
         run: npm install
 
-      - name: Repository build
+      - name: Build
         run: npm run build
 
       - name: Tests (with coverage)
         run: npm test -- --coverage
 
       - name: Coveralls GitHub Action
-        uses: coverallsapp/github-action@v1.1.1
+        uses: coverallsapp/github-action@v2
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}
 
       - name: Build website (Github pages)
         run: npm run build-doc --if-present
 
       - name: Publish website on GitHub Pages
-        uses: crazy-max/ghaction-github-pages@v2.1.2
+        uses: crazy-max/ghaction-github-pages@v3
         with:
           build_dir: dist-ghpages
         env:

CHANGELOG.md

@@ -1020,3 +1020,13 @@ Errored release
 ### Fixes
 
 - wrong dependency in package.json
+
+## [4.2.0] - 2023-03-18
+
+### Adds
+
+- `useLongPress` hook
+
+### Fixes
+
+- Deprecated github actions version

docs/useLongPress.md

@@ -0,0 +1,87 @@
+# useLongPress
+
+A hook that facilitates the implementation of a long press functionality on a given target, supporting both mouse and touch events.
+
+### Why? 💡
+
+- Provides an easy way to add long-press functionality to a specific target element
+- Automatically adds mouse event listeners to the specified target element
+- Automatically removes the listeners when the component unmounts
+- Enables abstractions on mouse-related and touch-related events
+
+### Basic Usage:
+
+```jsx harmony
+import { useRef, useState } from 'react';
+import { Tag, Space, Typography, Alert } from 'antd';
+import useLongPress from 'beautiful-react-hooks/useLongPress';
+
+const MyComponent = () => {
+  const [coordinates, setCoordinates] = useState([0, 0]);
+  const ref = useRef();
+  const [longPressCount, setLongPressCount] = useState(0)
+  const { isLongPressing, onLongPressStart, onLongPressEnd } = useLongPress(ref);
+
+  onLongPressStart(() => {
+    setLongPressCount(() => {
+      return longPressCount + 1
+    });
+  });
+
+  onLongPressEnd(() => {
+    setLongPressCount(() => {
+      return longPressCount + 1
+    });
+  })
+
+  return (
+    <DisplayDemo title="useLongPress">
+      <div ref={ref}>
+        <Space direction="vertical">
+          <Alert message="Long press this box to get information on the long press event" type="info" showIcon />
+          <Tag color={isLongPressing ? 'green' : 'red'}>isLongPressing: {isLongPressing ? 'yes' : 'no'}</Tag>
+          {!!longPressCount && (
+            <Typography.Paragraph>
+              Long press events count:
+              <Tag color="green">{longPressCount}</Tag>
+            </Typography.Paragraph>
+          )}
+        </Space>
+      </div>
+    </DisplayDemo>
+  );
+};
+
+<MyComponent />
+```
+
+### Press duration:
+
+You can specify the duration of the long press by passing a number as the second argument to the hook.
+
+```jsx harmony
+import { useRef, useState } from 'react';
+import { Tag, Space, Typography, Alert } from 'antd';
+import useLongPress from 'beautiful-react-hooks/useLongPress';
+
+const MyComponent = () => {
+  const [coordinates, setCoordinates] = useState([0, 0]);
+  const ref = useRef();
+  const { isLongPressing } = useLongPress(ref, 1000);
+
+  return (
+    <DisplayDemo title="useLongPress">
+      <div ref={ref}>
+        <Space direction="vertical">
+          <Alert message="Long press this box to get information on the long press event" type="info" showIcon />
+          <Tag color={isLongPressing ? 'green' : 'red'}>isLongPressing: {isLongPressing ? 'yes' : 'no'}</Tag>
+        </Space>
+      </div>
+    </DisplayDemo>
+  );
+};
+
+<MyComponent />
+```
+
+<!-- Types -->

docs/useMouseEvents.md

@@ -39,15 +39,15 @@ const MyComponent = () => {
   });
 
   return (
-          <DisplayDemo title="useMouseEvent">
-            <div ref={ref}>
-              <Space direction="vertical">
-                <Alert message="Move mouse over this box to get its current coordinates" type="info" showIcon />
-                <Tag color="green">ClientX: {coordinates[0]}</Tag>
-                <Tag color="green">ClientY: {coordinates[1]}</Tag>
-              </Space>
-            </div>
-          </DisplayDemo>
+    <DisplayDemo title="useMouseEvent">
+      <div ref={ref}>
+        <Space direction="vertical">
+          <Alert message="Move mouse over this box to get its current coordinates" type="info" showIcon />
+          <Tag color="green">ClientX: {coordinates[0]}</Tag>
+          <Tag color="green">ClientY: {coordinates[1]}</Tag>
+        </Space>
+      </div>
+    </DisplayDemo>
   );
 };
 
@@ -73,13 +73,13 @@ const MyComponent = () => {
   });
 
   return (
-          <DisplayDemo title="useMouseEvent">
-            <Space direction="vertical">
-              <Alert message="Move mouse around to get its current global coordinates" type="info" showIcon />
-              <Tag color="green">ClientX: {coordinates[0]}</Tag>
-              <Tag color="green">ClientY: {coordinates[1]}</Tag>
-            </Space>
-          </DisplayDemo>
+    <DisplayDemo title="useMouseEvent">
+      <Space direction="vertical">
+        <Alert message="Move mouse around to get its current global coordinates" type="info" showIcon />
+        <Tag color="green">ClientX: {coordinates[0]}</Tag>
+        <Tag color="green">ClientY: {coordinates[1]}</Tag>
+      </Space>
+    </DisplayDemo>
   );
 };
 
@@ -105,14 +105,15 @@ const MyComponent = (props) => {
   const { mouseDownHandler } = props;
 
   return (
-          <div onMouseDown={mouseDownHandler} />
+    <div onMouseDown={mouseDownHandler} />
   );
 };
 ```
 
 <!-- Types -->
+
 ### Types
-    
+
 ```typescript static
 import { type RefObject } from 'react';
 /**
@@ -141,4 +142,5 @@ declare const useMouseEvents: <TElement extends HTMLElement>(targetRef?: RefObje
 export default useMouseEvents;
 
 ```
-<!-- Types:end -->
+
+<!-- Types:end -->

src/useEvent.ts

@@ -7,10 +7,10 @@ import safeHasOwnProperty from './shared/safeHasOwnProperty'
  * when fired from that HTML Element.
  */
 const useEvent = <TEvent extends Event, TElement extends HTMLElement = HTMLElement>
-  (ref: RefObject<TElement>, eventName: string, options?: AddEventListenerOptions) => {
+  (target: RefObject<TElement>, eventName: string, options?: AddEventListenerOptions) => {
   const [handler, setHandler] = createHandlerSetter<TEvent>()
 
-  if (!!ref && !safeHasOwnProperty(ref, 'current')) {
+  if (!!target && !safeHasOwnProperty(target, 'current')) {
     throw new Error('Unable to assign any scroll event to the given ref')
   }
 
@@ -21,16 +21,16 @@ const useEvent = <TEvent extends Event, TElement extends HTMLElement = HTMLEleme
       }
     }
 
-    if (ref.current?.addEventListener && handler.current) {
-      ref.current.addEventListener(eventName, cb, options)
+    if (target.current?.addEventListener && handler.current) {
+      target.current.addEventListener(eventName, cb, options)
     }
 
     return () => {
-      if (ref.current?.addEventListener && handler.current) {
-        ref.current.removeEventListener(eventName, cb, options)
+      if (target.current?.addEventListener && handler.current) {
+        target.current.removeEventListener(eventName, cb, options)
       }
     }
-  }, [eventName, ref.current, options])
+  }, [eventName, target.current, options])
 
   return setHandler
 }

src/useLongPress.ts

@@ -0,0 +1,64 @@
+import { type RefObject, useCallback, useState } from 'react'
+import useMouseEvents from './useMouseEvents'
+import useConditionalTimeout from './useConditionalTimeout'
+import createHandlerSetter from './factory/createHandlerSetter'
+import useTouchEvents from './useTouchEvents'
+import { type CallbackSetter } from './shared/types'
+
+/**
+ * A hook that facilitates the implementation of the long press functionality on a given target, supporting both mouse and touch events.
+ */
+const useLongPress = <TElement extends HTMLElement>(target: RefObject<TElement>, duration = 500) => {
+  const { onMouseDown, onMouseUp, onMouseLeave } = useMouseEvents<TElement>(target, false)
+  const { onTouchStart, onTouchEnd } = useTouchEvents(target, false)
+  const [isLongPressing, setIsLongPressing] = useState(false)
+  const [timerOn, startTimer] = useState(false)
+  const [onLongPressStart, setOnLongPressStart] = createHandlerSetter<void>()
+  const [onLongPressEnd, setOnLongPressEnd] = createHandlerSetter<void>()
+
+  const longPressStart = useCallback((event: MouseEvent | TouchEvent) => {
+    event.preventDefault()
+    startTimer(true)
+  }, [])
+
+  const longPressStop = useCallback((event: MouseEvent | TouchEvent) => {
+    if (!isLongPressing) return
+    clearTimeout()
+    setIsLongPressing(false)
+    startTimer(false)
+    event.preventDefault()
+
+    if (onLongPressEnd?.current) {
+      onLongPressEnd.current()
+    }
+  }, [isLongPressing])
+
+  const [, clearTimeout] = useConditionalTimeout(() => {
+    setIsLongPressing(true)
+
+    if (onLongPressStart?.current) {
+      onLongPressStart.current()
+    }
+  }, duration, timerOn)
+
+  onMouseDown(longPressStart)
+  onMouseLeave(longPressStop)
+  onMouseUp(longPressStop)
+
+  onTouchStart(longPressStart)
+  onTouchEnd(longPressStop)
+
+  return Object.freeze<UseLongPressResult>({
+    isLongPressing,
+    onLongPressStart: setOnLongPressStart,
+    onLongPressEnd: setOnLongPressEnd
+  })
+}
+
+export interface UseLongPressResult {
+  isLongPressing: boolean
+  onLongPressStart: CallbackSetter<void>
+  onLongPressEnd: CallbackSetter<void>
+}
+
+export default useLongPress

test/useLongPress.spec.js

@@ -0,0 +1,18 @@
+import { cleanup, renderHook } from '@testing-library/react-hooks'
+import useLongPress from '../dist/useLongPress'
+import assertHook from './utils/assertHook'
+
+describe('useLongPress', () => {
+  beforeEach(() => cleanup())
+
+  assertHook(useLongPress)
+
+  it('should return a boolean value reporting whether the long-press event is happening as well as the handlers setters', () => {
+    const ref = { current: document.createElement('div') }
+    const { result } = renderHook(() => useLongPress(ref))
+
+    expect(result.current.isLongPressing).to.be.a('boolean')
+    expect(result.current.onLongPressStart).to.be.a('function')
+    expect(result.current.onLongPressEnd).to.be.a('function')
+  })
+})