feat(useParentElement): new function (#2855)

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

packages/core/index.ts

@@ -78,6 +78,7 @@ export * from './useOffsetPagination'
 export * from './useOnline'
 export * from './usePageLeave'
 export * from './useParallax'
+export * from './useParentElement'
 export * from './usePerformanceObserver'
 export * from './usePermission'
 export * from './usePointer'

packages/core/useParentElement/Demo.vue

@@ -0,0 +1,9 @@
+<script lang="ts" setup>
+import { useParentElement } from '@vueuse/core'
+
+const parentElement = useParentElement()
+</script>
+
+<template>
+  <p>Parent element tag: {{ parentElement ? parentElement.tagName : 'Finding...' }}</p>
+</template>

packages/core/useParentElement/index.md

@@ -0,0 +1,36 @@
+---
+category: Elements
+---
+
+# useParentElement
+
+Get parent element of the given element
+
+## Usage
+
+When no argument is passed, it will return the parent element of the current component.
+
+```js
+import { useParentElement } from '@vueuse/core'
+
+const parentEl = useParentElement()
+
+onMounted(() => {
+  console.log(parentEl.value)
+})
+```
+
+It can also accept a `ref` as the first argument.
+
+```ts
+import { useParentElement } from '@vueuse/core'
+
+// Don't forget to bind the ref to the element
+const tooltip = ref<HTMLElement | undefined>()
+
+const tooltipWrapper = useParentElement(tooltip)
+
+onMounted(() => {
+  console.log(tooltipWrapper.value)
+})
+```

packages/core/useParentElement/index.test.ts

@@ -0,0 +1,47 @@
+import { defineComponent, h, isVue2, nextTick, ref } from 'vue-demi'
+import { mount } from '../../.test'
+import { useParentElement } from '.'
+
+describe.skipIf(isVue2)('useParentElement', () => {
+  it('should be defined', () => {
+    expect(useParentElement).toBeDefined()
+  })
+
+  it('should work without ref', async () => {
+    let parentElement: any
+
+    const Child = defineComponent({
+      setup() {
+        parentElement = useParentElement()
+        return () => h('div', {})
+      },
+    })
+
+    mount({
+      setup() {
+        return () => h('parent', h(Child))
+      },
+    })
+
+    await nextTick()
+
+    expect(parentElement.value!.tagName).to.equal('PARENT')
+  })
+
+  it('should accept ref', async () => {
+    const liEl = ref()
+    const parentElement = useParentElement(liEl)
+
+    mount(defineComponent({
+      setup() {
+        return () => h('ul', {}, [
+          h('li', { ref: liEl }),
+        ])
+      },
+    }))
+
+    await nextTick()
+
+    expect(parentElement.value!.tagName).to.equal('UL')
+  })
+})

packages/core/useParentElement/index.ts

@@ -0,0 +1,23 @@
+import type { MaybeComputedRef } from '@vueuse/shared'
+import { resolveUnref, tryOnMounted } from '@vueuse/shared'
+import type { Ref } from 'vue-demi'
+import { shallowRef, watch } from 'vue-demi'
+import { unrefElement } from '../unrefElement'
+import { useCurrentElement } from '../useCurrentElement'
+
+export function useParentElement(
+  element: MaybeComputedRef<HTMLElement | SVGElement | null | undefined> = useCurrentElement<HTMLElement | SVGAElement>(),
+): Readonly<Ref<HTMLElement | SVGElement | null | undefined>> {
+  const parentElement = shallowRef<HTMLElement | SVGElement | null | undefined>()
+
+  const update = () => {
+    const el = unrefElement(element)
+    if (el)
+      parentElement.value = el.parentElement
+  }
+
+  tryOnMounted(update)
+  watch(() => resolveUnref(element), update)
+
+  return parentElement
+}