[ADD] useHover hook

Author: nDriaDev

apps/react-tools-demo/src/components/hooks/useHover/UseHover.tsx

@@ -0,0 +1,19 @@
+import { useRef } from "react"
+import { useHover } from "../../../../../../packages/react-tools/src";
+
+/**
+The component renders a paragraph element with some text to which is attacched a ref used for __useHover__ hook that returns if element is hovered or not. This value is rendered into another paragraph element.
+
+When mouse is hovered paragraph element, status changes to true.
+ */
+export const UseHover = () => {
+	const pRef = useRef<HTMLParagraphElement>(null);
+	const hover = useHover(pRef);
+
+	return (
+		<div>
+			<p>Is hover: {hover ? "hover" : "not hover"}</p>
+			<p ref={pRef}>Lorem ipsum dolor, sit amet consectetur adipisicing elit. Id delectus deserunt atque! Est id voluptatem sint accusamus non doloribus totam nobis nostrum provident facilis eos eum, placeat consequatur minus quidem.</p>
+		</div>
+	);
+}

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

@@ -42,10 +42,11 @@ export const COMPONENTS = [
 		],
 		//EVENTS
 		[
-			"usePerformAction",
-			"useEventListener",
 			"useEvents",
+			"useEventListener",
 			"useEventDispatcher",
+			"usePerformAction",
+			"useHover"
 		],
 		//API DOM
 		[

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

@@ -0,0 +1,43 @@
+# useHover
+Hook that determines whether the item is hovered or not and handles state hovers.
+
+## Usage
+
+```tsx
+export const UseHover = () => {
+	const pRef = useRef<HTMLParagraphElement>(null);
+	const hover = useHover(pRef);
+
+	return (
+		<div>
+			<p>Is hover: {hover ? "hover" : "not hover"}</p>
+			<p ref={pRef}>Lorem ipsum dolor, sit amet consectetur adipisicing elit. Id delectus deserunt atque! Est id voluptatem sint accusamus non doloribus totam nobis nostrum provident facilis eos eum, placeat consequatur minus quidem.</p>
+		</div>
+	);
+}
+```
+
+> The component renders a paragraph element with some text to which is attacched a ref used for __useHover__ hook that returns if element is hovered or not. This value is rendered into another paragraph element.
+> 
+> When mouse is hovered paragraph element, status changes to true.
+
+
+## API
+
+```tsx
+useHover(target: RefObject<HTMLElement> | HTMLElement, opts?: { onEnter?: (evt: Event) => void, onChange?: (isHover: boolean) => void, onLeave?: (evt: Event) => void, returnValue?: boolean }): boolean | void 
+```
+
+> ### Params
+>
+> - __target__: _RefObject<HTMLElement> | HTMLElement_  
+DOM element or ref
+> - __opts?__: _{ onEnter?: (evt: Event) => void, onChange?: (isHover: boolean) => void, onLeave?: (evt: Event) => void, returnValue?: boolean }_  
+__onEnter__ function to be executed on starting hover, __onLeave__ function to be executed on hover finished, __onChange__ function to be executed when hover state changes, __return value__ boolean to return hover state value or not.
+>
+
+> ### Returns
+>
+> __result__: if __returnValue__ option is true or not specified, hook return state hover value, otherwise returns nothing.
+> - _boolean|void_  
+>

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

@@ -4,7 +4,7 @@ _useId_ hook polyfilled for React versions below 18: __not use for key prop__.
 ## API
 
 ```tsx
-useId() 
+useId(): string 
 ```
 
 > ### Params

packages/react-tools/README.md

@@ -43,7 +43,7 @@
 	- [x] useEventListener
 	- [x] useEventDispatcher
 	- [x] usePerformAction
-	- [ ] useHover
+	- [x] useHover
 	- [ ] useResponsive
 	- [ ] useClickOutside
 	- [ ] useSize (=useMeasuree?)

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

@@ -41,4 +41,6 @@ export { useClipboard } from './useClipboard';
 export { useMediaQuery } from './useMediaQuery';
 export { useColorScheme } from './useColorScheme';
 export { useTitle } from './useTitle'
-export { useLazyRef } from './useLazyRef';
+export { useLazyRef } from './useLazyRef';
+export { useId } from './useId';
+export { useHover } from './useHover';

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

@@ -0,0 +1,55 @@
+import { RefObject, useCallback, useMemo, useRef } from "react";
+import { useSyncExternalStore } from ".";
+
+/**
+ * **`useHover`**: Hook that determines whether the item is hovered or not and handles state hovers.
+ * @param {RefObject<HTMLElement> | HTMLElement} target - DOM element or ref
+ * @param {{ onEnter?: (evt: Event) => void, onChange?: (isHover: boolean) => void, onLeave?: (evt: Event) => void, returnValue?: boolean }} [opts] - __onEnter__ function to be executed on starting hover, __onLeave__ function to be executed on hover finished, __onChange__ function to be executed when hover state changes, __return value__ boolean to return hover state value or not.
+ * @returns {boolean|void} result - if __returnValue__ option is true or not specified, hook return state hover value, otherwise returns nothing.
+ */
+function useHover(target: RefObject<HTMLElement> | HTMLElement, opts?: { onEnter?: (evt: Event) => void, onChange?: (isHover: boolean) => void, onLeave?: (evt: Event) => void, returnValue?: true }): boolean;
+function useHover(target: RefObject<HTMLElement> | HTMLElement, opts?: { onEnter?: (evt: Event) => void, onChange?: (isHover: boolean) => void, onLeave?: (evt: Event) => void, returnValue?: false }): void;
+function useHover(target: RefObject<HTMLElement> | HTMLElement, opts?: { onEnter?: (evt: Event) => void, onChange?: (isHover: boolean) => void, onLeave?: (evt: Event) => void, returnValue?: boolean }): boolean | void {
+	const isHoverCached = useRef({ current: false, previous: false });
+	const onEnt = useMemo(()=> opts?.onEnter, [opts?.onEnter])
+	const onLeav = useMemo(()=> opts?.onLeave, [opts?.onLeave])
+	const onCng = useMemo(()=> opts?.onChange, [opts?.onChange])
+	const isHover = useSyncExternalStore(
+		useCallback(notif => {
+			const element = (target as RefObject<HTMLElement>).current
+					? (target as RefObject<HTMLElement>).current
+				: target as HTMLElement;
+			const pointerEnter = (evt: Event) => {
+				isHoverCached.current.current = true;
+				onEnt && onEnt(evt);
+				onCng && onCng(true);
+				notif();
+			}
+			const pointerLeave = (evt: Event) => {
+				isHoverCached.current.current = false;
+				onLeav && onLeav(evt);
+				onCng && onCng(false);
+				notif();
+			}
+			element?.addEventListener("pointerenter", pointerEnter);
+			element?.addEventListener("pointerleave", pointerLeave);
+
+			return () => {
+				element?.removeEventListener("pointerenter", pointerEnter);
+				element?.removeEventListener("pointerleave", pointerLeave);
+			}
+		}, [onCng, onEnt, onLeav, target]),
+		useCallback(() => {
+			if (isHoverCached.current.current !== isHoverCached.current.previous) {
+				isHoverCached.current.previous = isHoverCached.current.current;
+			}
+			return isHoverCached.current.previous;
+		}, [])
+	)
+
+	if (!opts || opts.returnValue === true) {
+		return isHover;
+	}
+}
+
+export {useHover}

packages/react-tools/src/index.ts

@@ -50,7 +50,9 @@ export {
 	useMediaQuery,
 	useColorScheme,
 	useTitle,
-	useLazyRef
+	useLazyRef,
+	useId,
+	useHover
 } from './hooks'
 
 export {