feat: add useHover sensor

packages/web-api-hooks/src/index.ts

@@ -7,6 +7,7 @@ export { default as useDocumentVisibility } from './useDocumentVisibility';
 export { default as useEventListener } from './useEventListener';
 export { default as useFocus } from './useFocus';
 export { default as useGeolocation } from './useGeolocation';
+export { default as useHover } from './useHover';
 export { default as useInterval } from './useInterval';
 export { default as useLocalStorage } from './useLocalStorage';
 export { default as useMedia } from './useMedia';

packages/web-api-hooks/src/useHover.ts

@@ -0,0 +1,47 @@
+import { useState } from 'react';
+
+/**
+ * Tracks hover state of an element.
+ *
+ * @param disallowTouch Determines whether touch gestures should be ignored.
+ * @returns Whether the element is hovered, and props to be spread over the element under observation.
+ *
+ * @example
+ * function Component() {
+ *   const [isHovered, bindHover] = useHover();
+ *   // ...
+ *   return <ElementToObserve {...bindHover} />;
+ * }
+ */
+export default function useHover(
+  disallowTouch = false,
+): [
+  boolean,
+  Readonly<{
+    onMouseEnter: () => void;
+    onMouseLeave: () => void;
+    onTouchStart: () => void;
+    onTouchEnd: () => void;
+  }>,
+] {
+  const [isHovered, setHovered] = useState(false);
+
+  return [
+    isHovered,
+    {
+      onMouseEnter() {
+        setHovered(true);
+      },
+      onMouseLeave() {
+        setHovered(false);
+      },
+
+      onTouchStart() {
+        setHovered(!disallowTouch);
+      },
+      onTouchEnd() {
+        setHovered(false);
+      },
+    },
+  ];
+}