feat(onClickOutside): add controls (#4537)

sibbng · antfu · web-flow · commit ab116abfdba4 · 2025-02-12T02:43:00.000Z
Co-authored-by: Anthony Fu &lt;anthonyfu117@hotmail.com&gt;
Co-authored-by: Anthony Fu &lt;github@antfu.me&gt;
diff --git a/packages/core/onClickOutside/component.ts b/packages/core/onClickOutside/component.ts
@@ -4,7 +4,7 @@ import { onClickOutside } from '@vueuse/core'
 import { defineComponent, h, ref } from 'vue'
 
 export interface OnClickOutsideProps extends RenderableComponent {
-  options?: OnClickOutsideOptions
+  options?: Omit<OnClickOutsideOptions, 'controls'>
 }
 
 export const OnClickOutside = /* #__PURE__ */ defineComponent<OnClickOutsideProps>({
diff --git a/packages/core/onClickOutside/directive.ts b/packages/core/onClickOutside/directive.ts
@@ -4,7 +4,7 @@ import { onClickOutside } from '.'
 
 export const vOnClickOutside: ObjectDirective<
   HTMLElement,
-  OnClickOutsideHandler | [(evt: any) => void, OnClickOutsideOptions]
+  OnClickOutsideHandler | [(evt: any) => void, Omit<OnClickOutsideOptions, 'controls'>]
 > = {
   mounted(el, binding) {
     const capture = !binding.modifiers.bubble
diff --git a/packages/core/onClickOutside/index.md b/packages/core/onClickOutside/index.md
@@ -26,6 +26,24 @@ onClickOutside(target, event => console.log(event))
 </template>
 ```
 
+If you need more control over triggering the handler, you can use the `controls` option.
+
+```ts
+const { cancel, trigger } = onClickOutside(
+  modalRef,
+  (event) => {
+    modal.value = false
+  },
+  { controls: true },
+)
+
+useEventListener('pointermove', (e) => {
+  cancel()
+  // or
+  trigger(e)
+})
+```
+
 ## Component Usage
 
 ```vue
diff --git a/packages/core/onClickOutside/index.ts b/packages/core/onClickOutside/index.ts
@@ -8,7 +8,7 @@ import { defaultWindow } from '../_configurable'
 import { unrefElement } from '../unrefElement'
 import { useEventListener } from '../useEventListener'
 
-export interface OnClickOutsideOptions extends ConfigurableWindow {
+export interface OnClickOutsideOptions<Controls extends boolean = false> extends ConfigurableWindow {
   /**
    * List of elements that should not trigger the event.
    */
@@ -23,9 +23,25 @@ export interface OnClickOutsideOptions extends ConfigurableWindow {
    * @default false
    */
   detectIframe?: boolean
+  /**
+   * Use controls to cancel/trigger listener.
+   * @default false
+   */
+  controls?: Controls
 }
 
-export type OnClickOutsideHandler<T extends { detectIframe: OnClickOutsideOptions['detectIframe'] } = { detectIframe: false }> = (evt: T['detectIframe'] extends true ? PointerEvent | FocusEvent : PointerEvent) => void
+export type OnClickOutsideHandler<
+  T extends {
+    detectIframe: OnClickOutsideOptions['detectIframe']
+    controls: boolean
+  } = { detectIframe: false, controls: false },
+> = (
+  event: T['controls'] extends true ? Event | (T['detectIframe'] extends true
+    ? PointerEvent | FocusEvent
+    : PointerEvent) : T['detectIframe'] extends true
+    ? PointerEvent | FocusEvent
+    : PointerEvent,
+) => void
 
 let _iOSWorkaround = false
 
@@ -37,15 +53,31 @@ let _iOSWorkaround = false
  * @param handler
  * @param options
  */
-export function onClickOutside<T extends OnClickOutsideOptions>(
+export function onClickOutside(
+  target: MaybeElementRef,
+  handler: OnClickOutsideHandler<{ detectIframe: OnClickOutsideOptions['detectIframe'], controls: true }>,
+  options: OnClickOutsideOptions<true>,
+): { stop: Fn, cancel: Fn, trigger: (event: Event) => void }
+
+export function onClickOutside(
+  target: MaybeElementRef,
+  handler: OnClickOutsideHandler<{ detectIframe: OnClickOutsideOptions['detectIframe'], controls: false }>,
+  options?: OnClickOutsideOptions<false>,
+): Fn
+
+// Implementation
+export function onClickOutside(
   target: MaybeElementRef,
-  handler: OnClickOutsideHandler<{ detectIframe: T['detectIframe'] }>,
-  options: T = {} as T,
+  handler: OnClickOutsideHandler,
+  options: OnClickOutsideOptions<boolean> = {},
 ) {
-  const { window = defaultWindow, ignore = [], capture = true, detectIframe = false } = options
+  const { window = defaultWindow, ignore = [], capture = true, detectIframe = false, controls = false } = options
 
-  if (!window)
-    return noop
+  if (!window) {
+    return controls
+      ? { stop: noop, cancel: noop, trigger: noop }
+      : noop
+  }
 
   // Fixes: https://github.com/vueuse/vueuse/issues/1520
   // How it works: https://stackoverflow.com/a/39712411
@@ -59,7 +91,7 @@ export function onClickOutside<T extends OnClickOutsideOptions>(
 
   let shouldListen = true
 
-  const shouldIgnore = (event: PointerEvent) => {
+  const shouldIgnore = (event: Event) => {
     return toValue(ignore).some((target) => {
       if (typeof target === 'string') {
         return Array.from(window.document.querySelectorAll(target))
@@ -81,7 +113,7 @@ export function onClickOutside<T extends OnClickOutsideOptions>(
     return vm && vm.$.subTree.shapeFlag === 16
   }
 
-  function checkMultipleRoots(target: MaybeElementRef, event: PointerEvent): boolean {
+  function checkMultipleRoots(target: MaybeElementRef, event: Event): boolean {
     const vm = toValue(target) as ComponentPublicInstance
     const children = vm.$.subTree && vm.$.subTree.children
 
@@ -92,7 +124,7 @@ export function onClickOutside<T extends OnClickOutsideOptions>(
     return children.some((child: VNode) => child.el === event.target || event.composedPath().includes(child.el))
   }
 
-  const listener = (event: PointerEvent) => {
+  const listener = (event: Event) => {
     const el = unrefElement(target)
 
     if (event.target == null)
@@ -104,15 +136,15 @@ export function onClickOutside<T extends OnClickOutsideOptions>(
     if (!el || el === event.target || event.composedPath().includes(el))
       return
 
-    if (event.detail === 0)
+    if ('detail' in event && event.detail === 0)
       shouldListen = !shouldIgnore(event)
 
     if (!shouldListen) {
       shouldListen = true
       return
     }
 
-    handler(event)
+    handler(event as any)
   }
 
   let isProcessingClick = false
@@ -146,5 +178,19 @@ export function onClickOutside<T extends OnClickOutsideOptions>(
 
   const stop = () => cleanup.forEach(fn => fn())
 
+  if (controls) {
+    return {
+      stop,
+      cancel: () => {
+        shouldListen = false
+      },
+      trigger: (event: Event) => {
+        shouldListen = true
+        listener(event)
+        shouldListen = false
+      },
+    }
+  }
+
   return stop
 }

Original file line number	Diff line number	Diff line change
`@@ -4,7 +4,7 @@ import { onClickOutside } from '@vueuse/core'`
`4`	`4`	`import { defineComponent, h, ref } from 'vue'`
`5`	`5`
`6`	`6`	`export interface OnClickOutsideProps extends RenderableComponent {`
`7`		`- options?: OnClickOutsideOptions`
	`7`	`+ options?: Omit<OnClickOutsideOptions, 'controls'>`
`8`	`8`	`}`
`9`	`9`
`10`	`10`	`export const OnClickOutside = /* #__PURE__ */ defineComponent<OnClickOutsideProps>({`