[IMPL] useLongPress hook

Author: nDriaDev

apps/react-tools-demo/src/App.css

@@ -592,4 +592,9 @@ button:not(:disabled) {
 .container-themed[data-color="light"] {
 	border-color: purple;
 	color: lightskyblue;
+}
+
+.btn-animated {
+	background-color: #1a1a1a;
+	animation: spin 1s linear forwards;
 }

apps/react-tools-demo/src/components/hooks/useLongPress/UseLongPress.tsx

@@ -0,0 +1,41 @@
+import { useState } from "react";
+import { useLongPress } from "../../../../../../packages/react-tools/src";
+
+/**
+The component has:
+- a __pressCounter__ state variable.
+- a __clickCounter__ state variable.
+- a RefCallback __cbRef__ attached to a button __Press me__. It is returned from _useLongPress_ hook that has a cb a function to update __pressCounter__ state and _normalPress_ option to update __clickCounter__ state.
+- it renders a div with __Press me__ button and two p elements that display __pressCounter__ and __clickCounter__.
+
+When the button is clicked for less than a second, _normalPress_ callback is executed, otherwise _long press_ callback is executed.
+ */
+export const UseLongPress = () => {
+	const [pressCounter, setPressCounter] = useState(0);
+	const [clickCounter, setClickCounter] = useState(0);
+	const [color, setColor] = useState(-1)
+
+
+	const cbRef = useLongPress<HTMLButtonElement>(() => {
+		setPressCounter((s) => s + 1);
+		setColor(1);
+	}, {
+		normalPress: () => setClickCounter((s) => s + 1),
+		onStart() {
+			setColor(0);
+		},
+		onFinish() {
+			setColor(-1);
+		},
+	});
+
+	return (
+		<div>
+			<button ref={cbRef} type="button" style={{ ...(color === -1 ? {} : { backgroundColor: color === -1 ? "inherit" : color === 0 ? "#8e830f" : "#0b5f07"})}}>
+				Press me
+			</button>
+			<p>pressCounter: {pressCounter}</p>
+			<p>clickCounter: {clickCounter}</p>
+		</div>
+	);
+}

apps/react-tools-demo/src/constants/components.ts

@@ -59,7 +59,8 @@ export const COMPONENTS = [
 			"useMeasure",
 			"useVisible",
 			"useScrollIntoView",
-			"useMouse"
+			"useMouse",
+			"useLongPress"
 		],
 		//API DOM
 		[

apps/react-tools-demo/src/markdown/useLongPress.md

@@ -0,0 +1,72 @@
+# useLongPress
+Hook to execute a callback on a long press event.
+
+## Usage
+
+```tsx
+export const UseLongPress = () => {
+	const [pressCounter, setPressCounter] = useState(0);
+	const [clickCounter, setClickCounter] = useState(0);
+	const [color, setColor] = useState(-1)
+
+
+	const cbRef = useLongPress<HTMLButtonElement>(() => {
+		setPressCounter((s) => s + 1);
+		setColor(1);
+	}, {
+		normalPress: () => setClickCounter((s) => s + 1),
+		onStart() {
+			setColor(0);
+		},
+		onFinish() {
+			setColor(-1);
+		},
+	});
+
+	return (
+		<div>
+			<button ref={cbRef} type="button" style={{ ...(color === -1 ? {} : { backgroundColor: color === -1 ? "inherit" : color === 0 ? "#8e830f" : "#0b5f07"})}}>
+				Press me
+			</button>
+			<p>pressCounter: {pressCounter}</p>
+			<p>clickCounter: {clickCounter}</p>
+		</div>
+	);
+}
+```
+
+> The component has:
+> - a __pressCounter__ state variable.
+> - a __clickCounter__ state variable.
+> - a RefCallback __cbRef__ attached to a button __Press me__. It is returned from _useLongPress_ hook that has a cb a function to update __pressCounter__ state and _normalPress_ option to update __clickCounter__ state.
+> - it renders a div with __Press me__ button and two p elements that display __pressCounter__ and __clickCounter__.
+> 
+> When the button is clicked for less than a second, _normalPress_ callback is executed, otherwise _long press_ callback is executed.
+
+
+## API
+
+```tsx
+useLongPress <T extends Element = Element, E extends Event = Event>(cb: useLongPressCallback<E>, { duration = 1000, normalPress, onStart, onFinish }: useLongPressOptions<E>): RefCallback<T> 
+```
+
+> ### Params
+>
+> - __cb__: _(evt:E)=>void_  
+callback to execute after a certain duration.
+> - __opts__: _Object_
+> - __opts.duration=1000?__: _number_  
+long press event duration in milliseconds.
+> - __opts.onStart?__: _(evt:E)=>void_  
+callback that will be executed on initial press event.
+> - __opts.onFinish?__: _(evt:E)=>void_  
+callback that will be executed when long press callback has done.
+> - __opts.normalPress?__: _(evt:E)=>void_  
+callback executed on normal press event.
+>
+
+> ### Returns
+>
+> __ref callback__: to be attached on target element.
+> - _RefCallback<T>_  
+>

apps/react-tools-demo/src/markdown/useMouse.md

@@ -56,7 +56,7 @@ if it is presents, position is relative to element.
 
 > ### Returns
 >
-> __ object- postion by axis and if relativeElement is present, relativeElement dimensions also.__
+> __ object__: postion by axis and if relativeElement is present, relativeElement dimensions also.
 > - __Union of__:  
 >     - __Object__:  
 >         - __x__ : _number|null_  

packages/react-tools/README.md

@@ -62,12 +62,11 @@
 	- [x] useVisibile
 	- [x] useScrollIntoView
 	- [x] useMouse
-	- [ ] useLongPress
+	- [x] useLongPress
 	- [ ] useKeysEvents
 	- [ ] useOrientation
 	- [ ] useImageOnLoad
 	- [ ] usePinchZoom
-
 	- [ ] useInfiniteScroll
 	- [ ] useDragAndDrop (check for mobile usage)
 

packages/react-tools/src/hooks/index.ts

@@ -58,4 +58,5 @@ export { useFullscreen } from './useFullscreen';
 export { useVisible } from './useVisible';
 export { useReducedMotion } from './useReducedMotion';
 export { useScrollIntoView } from './useScrollIntoView';
-export { useMouse } from './useMouse';
+export { useMouse } from './useMouse';
+export { useLongPress } from './useLongPress';

packages/react-tools/src/hooks/useLongPress.ts

@@ -0,0 +1,50 @@
+import { RefCallback, useCallback, useRef } from "react";
+import { useLongPressCallback, useLongPressOptions } from "../models/useLongPress.model";
+
+/**
+ * **`useLongPress`**: Hook to execute a callback on a long press event.
+ * @param {(evt:E)=>void} cb - callback to execute after a certain duration.
+ * @param {Object} opts
+ * @param {number} [opts.duration=1000] - long press event duration in milliseconds.
+ * @param {(evt:E)=>void} [opts.onStart] - callback that will be executed on initial press event.
+ * @param {(evt:E)=>void} [opts.onFinish] - callback that will be executed when long press callback has done.
+ * @param {(evt:E)=>void} [opts.normalPress] - callback executed on normal press event.
+ * @returns {RefCallback<T>} ref callback - to be attached on target element.
+ */
+export const useLongPress = <T extends Element = Element, E extends Event = Event>(cb: useLongPressCallback<E>, { duration = 1000, normalPress, onStart, onFinish }: useLongPressOptions<E>): RefCallback<T> => {
+	const evtRef = useRef<E>();
+	const idTimeout = useRef<number|undefined>();
+	const longPressActive = useRef(false);
+	const target = useRef<T>();
+
+	const pointerUp = useCallback(() => {
+		clearTimeout(idTimeout.current);
+		onFinish && onFinish(evtRef.current as E);
+		!longPressActive.current && normalPress && normalPress(evtRef.current!);
+	}, [normalPress, onFinish]);
+
+	const pointerDown = useCallback((evt: Event) => {
+		longPressActive.current = false;
+		evtRef.current = evt as E;
+
+		onStart && onStart(evt as E);
+
+		idTimeout.current = setTimeout(async () => {
+			longPressActive.current = true;
+			await cb(evt as E);
+		}, duration) as unknown as number;
+
+	}, [cb, duration, onStart]);
+
+	return useCallback((node: T) => {
+			if (node) {
+				node.addEventListener("pointerdown", pointerDown);
+				node.addEventListener("pointerup", pointerUp);
+				target.current = node;
+			} else {
+				target.current?.removeEventListener("pointerdown", pointerDown);
+				target.current?.removeEventListener("pointerup", pointerUp);
+				target.current = undefined;
+			}
+		}, [pointerDown, pointerUp]);
+}

packages/react-tools/src/index.ts

@@ -72,7 +72,8 @@ export {
 	useVisible,
 	useReducedMotion,
 	useScrollIntoView,
-	useMouse
+	useMouse,
+	useLongPress
 } from './hooks'
 
 export {

packages/react-tools/src/models/useLongPress.model.ts

@@ -0,0 +1,10 @@
+export interface useLongPressCallback<E extends Event = Event> {
+	(evt: E):void | Promise<void>
+}
+
+export interface useLongPressOptions<E extends Event = Event> {
+	duration?: number,
+	normalPress?: (evt: E) => void,
+	onStart?: (evt: E) => void,
+	onFinish?: (evt: E) => void
+}