Event Handling

/**
 * Register event listener with automatic cleanup
 * @param target - Event target (window, document, element, or ref)
 * @param event - Event name
 * @param listener - Event listener function
 * @param options - Event listener options
 * @returns Stop function
 */
function useEventListener<E extends keyof WindowEventMap>(
  event: E,
  listener: (this: Window, ev: WindowEventMap[E]) => any,
  options?: ConfigurableWindow & AddEventListenerOptions
): Fn;

function useEventListener<E extends keyof DocumentEventMap>(
  target: Document,
  event: E,
  listener: (this: Document, ev: DocumentEventMap[E]) => any,
  options?: AddEventListenerOptions
): Fn;

function useEventListener<E extends keyof HTMLElementEventMap>(
  target: MaybeElementRef,
  event: E,
  listener: (this: HTMLElement, ev: HTMLElementEventMap[E]) => any,
  options?: AddEventListenerOptions
): Fn;

function useEventListener(
  target: MaybeElementRef,
  event: string,
  listener: EventListener,
  options?: AddEventListenerOptions
): Fn;

import { ref } from "vue";
import { useEventListener } from "@vueuse/core";

// Window events
useEventListener('resize', () => {
  console.log('Window resized');
});

// Document events
useEventListener(document, 'visibilitychange', () => {
  console.log('Visibility changed:', document.visibilityState);
});

// Element events
const button = ref<HTMLButtonElement>();
useEventListener(button, 'click', (e) => {
  console.log('Button clicked:', e);
});

// Custom events
useEventListener('my-custom-event', (e) => {
  console.log('Custom event:', e.detail);
});

// With options
useEventListener('scroll', handleScroll, {
  passive: true,
  capture: true
});

/**
 * Event bus for component communication
 * @param key - Optional bus key for multiple buses
 * @returns Event bus utilities
 */
function useEventBus<T = unknown, P = T>(key?: any): UseEventBusReturn<T, P>;

interface UseEventBusReturn<T, P> {
  on: (listener: (event: T) => void) => Fn;
  once: (listener: (event: T) => void) => Fn;
  off: (listener: (event: T) => void) => void;
  emit: (event?: P) => void;
  reset: () => void;
}

/**
 * Listen for clicks outside of an element
 * @param target - Target element or ref
 * @param handler - Click outside handler
 * @param options - Configuration options
 * @returns Stop function
 */
function onClickOutside(
  target: MaybeElementRef,
  handler: OnClickOutsideHandler,
  options?: OnClickOutsideOptions
): Fn;

interface OnClickOutsideOptions extends ConfigurableWindow {
  ignore?: (MaybeElementRef | string)[];
  capture?: boolean;
  detectIframe?: boolean;
}

type OnClickOutsideHandler = (evt: PointerEvent) => void;

import { ref } from "vue";
import { onClickOutside } from "@vueuse/core";

const modal = ref<HTMLElement>();
const isOpen = ref(false);

onClickOutside(modal, () => {
  isOpen.value = false;
});

// With ignore list
const trigger = ref<HTMLElement>();
onClickOutside(modal, () => {
  isOpen.value = false;
}, {
  ignore: [trigger]
});

/**
 * Listen for key strokes with modifier support
 * @param key - Key or keys to listen for
 * @param handler - Key stroke handler
 * @param options - Configuration options
 * @returns Stop function
 */
function onKeyStroke(
  key: KeyFilter,
  handler: (event: KeyboardEvent) => void,
  options?: OnKeyStrokeOptions
): Fn;

interface OnKeyStrokeOptions {
  eventName?: 'keydown' | 'keypress' | 'keyup';
  target?: MaybeElementRef;
  passive?: boolean;
  dedupe?: boolean;
}

type KeyFilter = string | string[] | ((event: KeyboardEvent) => boolean);

/**
 * Fire when users start typing on non-input elements
 * @param callback - Callback when typing starts
 * @param options - Configuration options
 * @returns Stop function
 */
function onStartTyping(
  callback: (event: KeyboardEvent) => void,
  options?: OnStartTypingOptions
): Fn;

interface OnStartTypingOptions {
  document?: Document;
}

/**
 * Reactive key combination detection
 * @param options - Configuration options
 * @returns Reactive key states
 */
function useMagicKeys(options?: UseMagicKeysOptions): MagicKeysReturn;

interface MagicKeysReturn {
  current: Set<string>;
  [key: string]: Ref<boolean> | Set<string>;
  
  // Special combinations
  ctrl_a: Ref<boolean>;
  shift_ctrl_a: Ref<boolean>;
  // ... many more combinations
}

interface UseMagicKeysOptions {
  reactive?: boolean;
  target?: MaybeElementRef;
  aliasMap?: Record<string, string>;
  passive?: boolean;
  onEventFired?: (e: KeyboardEvent) => void;
}

/**
 * Track individual key modifier states
 * @param modifier - Modifier key to track
 * @param options - Configuration options
 * @returns Reactive modifier state
 */
function useKeyModifier(
  modifier: UseKeyModifierModifier,
  options?: UseKeyModifierOptions
): Ref<boolean>;

type UseKeyModifierModifier = 'Alt' | 'AltGraph' | 'CapsLock' | 'Control' | 'Fn' | 'Meta' | 'NumLock' | 'ScrollLock' | 'Shift' | 'Symbol' | 'SymbolLock';

interface UseKeyModifierOptions {
  events?: UseKeyModifierEvents[];
  initial?: boolean;
}

type UseKeyModifierEvents = 'mousedown' | 'mouseup' | 'keydown' | 'keyup' | 'pointerdown' | 'pointerup' | 'contextmenu';

/**
 * Detect long press gestures
 * @param target - Target element or ref
 * @param handler - Long press handler
 * @param options - Configuration options
 * @returns Stop function
 */
function onLongPress(
  target: MaybeElementRef,
  handler: (evt: PointerEvent) => void,
  options?: OnLongPressOptions
): () => void;

interface OnLongPressOptions {
  delay?: number;
  modifiers?: OnLongPressModifiers;
  distanceThreshold?: number | false;
}

interface OnLongPressModifiers {
  stop?: boolean;
  once?: boolean;
  prevent?: boolean;
  capture?: boolean;
  self?: boolean;
}