feat(useElementHover): new function (vitest-dev#830)

* initial useElementHover implementation

* chore: update

Co-authored-by: Anthony Fu <anthonyfu117@hotmail.com>

packages/core/index.ts

@@ -24,6 +24,7 @@ export * from './useDisplayMedia'
 export * from './useDocumentVisibility'
 export * from './useDraggable'
 export * from './useElementBounding'
+export * from './useElementHover'
 export * from './useElementSize'
 export * from './useElementVisibility'
 export * from './useEventBus'

packages/core/useElementHover/demo.vue

@@ -0,0 +1,13 @@
+<script setup lang="ts">
+import { ref } from 'vue-demi'
+import { useElementHover } from '.'
+
+const el = ref()
+const isHovered = useElementHover(el)
+</script>
+
+<template>
+  <button ref="el">
+    <span>{{ isHovered ? 'Thank you!' : 'Hover me' }}</span>
+  </button>
+</template>

packages/core/useElementHover/index.md

@@ -0,0 +1,24 @@
+---
+category: Sensors
+---
+
+# useElementHover
+
+Reactive element's hover state.
+
+## Usage
+
+```vue
+<template>
+  <button ref="myHoverableElement">
+    {{ isHovered }}
+  </button>
+</template>
+
+<script setup>
+import { useElementHover } from '@vueuse/core'
+
+const myHoverableElement = ref()
+const isHovered = useElementHover(myHoverableElement)
+</script>
+```

packages/core/useElementHover/index.ts

@@ -0,0 +1,12 @@
+import { Ref, ref } from 'vue-demi'
+import { MaybeRef } from '@vueuse/shared'
+import { useEventListener } from '../useEventListener'
+
+export function useElementHover(el: MaybeRef<EventTarget>): Ref<boolean> {
+  const isHovered = ref(false)
+
+  useEventListener(el, 'mouseenter', () => isHovered.value = true)
+  useEventListener(el, 'mouseleave', () => isHovered.value = false)
+
+  return isHovered
+}

packages/functions.md

@@ -74,6 +74,7 @@
   - [`useDocumentVisibility`](https://vueuse.org/core/useDocumentVisibility/) — reactively track [`document.visibilityState`](https://developer.mozilla.org/en-US/docs/Web/API/Document/visibilityState)
   - [`useDraggable`](https://vueuse.org/core/useDraggable/) — make elements draggable
   - [`useElementBounding`](https://vueuse.org/core/useElementBounding/) — reactive [bounding box](https://developer.mozilla.org/en-US/docs/Web/API/Element/getBoundingClientRect) of an HTML element
+  - [`useElementHover`](https://vueuse.org/core/useElementHover/) — reactive element's hover state
   - [`useElementSize`](https://vueuse.org/core/useElementSize/) — reactive size of an HTML element
   - [`useElementVisibility`](https://vueuse.org/core/useElementVisibility/) — tracks the visibility of an element within the viewport
   - [`useGeolocation`](https://vueuse.org/core/useGeolocation/) — reactive [Geolocation API](https://developer.mozilla.org/en-US/docs/Web/API/Geolocation_API)