Feature: useClickOutside

README.md

@@ -12,6 +12,7 @@ npm i --save @prefecthq/vue-compositions
 
 - [useBoolean](https://github.com/prefecthq/vue-compositions/tree/main/src/useBoolean)
 - [useChildrenAreWrapped](https://github.com/prefecthq/vue-compositions/tree/main/src/useChildrenAreWrapped)
+- [useClickOutside](https://github.com/prefecthq/vue-compositions/tree/main/src/useClickOutside)
 - [useComputedStyle](https://github.com/prefecthq/vue-compositions/tree/main/src/useComputedStyle)
 - [useDebouncedRef](https://github.com/prefecthq/vue-compositions/tree/main/src/useDebouncedRef)
 - [useElementRect](https://github.com/prefecthq/vue-compositions/tree/main/src/useElementRect)

src/index.ts

@@ -1,5 +1,6 @@
 export * from './useBoolean'
 export * from './useChildrenAreWrapped'
+export * from './useClickOutside'
 export * from './useComputedStyle'
 export * from './useDebouncedRef'
 export * from './useElementRect'

src/useClickOutside/README.md

@@ -0,0 +1,35 @@
+# useClickOutside
+The `useClickOutside` composition is designed to detect and react to clicks outside a specified element. It takes an element and a callback function as arguments. The composition returns `on` and `off` functions, allowing for manual control over the event listener if needed, although automatic cleanup is handled as part of the component's lifecycle.
+
+## Example
+```vue
+<template>
+  <div ref="el" />
+</template>
+
+<script lang="ts" setup>
+import { ref } from 'vue'
+import { useClickOutside } from '@prefecthq/vue-compositions'
+
+function handleClickOutside(): void {
+  // Do something, like close a modal
+}
+
+const el = ref()
+const { on, off } = useClickOutside(el, handleClickOutside)
+// Don't need to do anything with on/off unless your handler needs to be paused for some reason 
+</script>
+```
+
+## Arguments
+| Name     | Type                              |
+|----------|-----------------------------------|
+| element | `MaybeRefOrGetter<Element> |
+| callback | `() => void` |
+
+## Returns
+
+| Name   | Type        | Description                                       |
+|--------|-------------|---------------------------------------------------|
+| on    | `() => void`  | Manually turn on the event listener (note: this isn't needed unless `off` has been called) |
+| off | `() => void`  | Manually turn off the event listener (note: this isn't needed for cleanup - the event listener will be removed automatically as part of the component lifecycle)                |

src/useClickOutside/index.ts

@@ -0,0 +1 @@
+export * from './useClickOutside'

src/useClickOutside/useClickOutside.ts

@@ -0,0 +1,74 @@
+import { onScopeDispose } from 'vue'
+import { useGlobalEventListener } from '..'
+import { MaybeRefOrGetter } from '@/types/maybe'
+import { toValue } from '@/utilities/vue'
+
+type ClickOutsideEntry = {
+  element: MaybeRefOrGetter<Element>,
+  callback: () => void,
+}
+
+const callbacks = new Map<symbol, ClickOutsideEntry>()
+
+function handleClick(event: MouseEvent): void {
+  for (const { element, callback } of callbacks.values()) {
+    const elementValue = toValue(element)
+
+    if (!elementValue.contains(event.target as Node)) {
+      callback()
+    }
+  }
+}
+
+const { add, remove } = useGlobalEventListener('click', handleClick, { capture: true })
+
+function tryTeardownEventListener(): void {
+  if (callbacks.size > 0) {
+    return
+  }
+
+  remove()
+}
+
+function tryAddEventListener(): void {
+  if (callbacks.size > 0) {
+    return
+  }
+
+  add()
+}
+
+export type UseClickOutsideCallbackFunction = () => void
+
+export type UseClickOutside = {
+  off: () => void,
+  on: () => void,
+}
+
+export function useClickOutside(element: MaybeRefOrGetter<Element>, callback: UseClickOutsideCallbackFunction): UseClickOutside {
+  const id = Symbol('useClickOutside')
+
+  callbacks.set(id, { element, callback })
+
+  tryAddEventListener()
+
+  function off(): void {
+    callbacks.delete(id)
+    tryTeardownEventListener()
+  }
+
+  function on(): void {
+    callbacks.set(id, { element, callback })
+    tryAddEventListener()
+  }
+
+  onScopeDispose(() => {
+    off()
+    tryTeardownEventListener()
+  })
+
+  return {
+    off,
+    on,
+  }
+}