[Integration] useEventListener system composable

[johnleider]

Summary

Integration improvements for useEventListener with the v0 system.

Research Findings

v0 Implementation (Production-Ready)

Core Features:

• Multiple Overloads: Window, Document, HTMLElement, generic EventTarget
• Reactive Parameters: MaybeRefOrGetter<T> for target, events, listeners
• Event Options: Full AddEventListenerOptions support (capture, passive, once)
• Auto Cleanup: onScopeDispose(stop, true) for automatic unmount cleanup
• Multiple Events/Listeners: Array handling for batch registration
• Convenience Functions: useWindowEventListener(), useDocumentEventListener()

Vuetify 3 Comparison

Feature	v0	Vuetify 3 Directives
Reactivity	✅ Full reactive	❌ Static bindings
Auto cleanup	✅ Scope-based	❌ Manual in beforeUnmount
Multiple events	✅ Via array	❌ Separate calls
Type safety	✅ 5+ overloads	❌ Limited
SSR safe	✅ Built-in	⚠️ Manual IN_BROWSER checks

Vuetify 3 Current Pattern

// V3 directive pattern (error-prone)
mounted(el) {
  el.addEventListener('click', handler, true)
  el._myDirective = { handler }
}
beforeUnmount(el) {
  el.removeEventListener('click', el._myDirective.handler, true)
  delete el._myDirective
}

Issues:

• Easy to miss cleanup
• Handler function changes require dual updates
• Brittle when refactoring

v0 Pattern

// v0 composable pattern (automatic)
useEventListener(el, 'click', handler, { capture: true })
// Cleanup happens automatically via onScopeDispose

Integration Points

• Foundation for useClickOutside, useHotkey
• Consistent cleanup patterns
• SSR safety via useHydration
• Document directive → composable migration
• Provide examples for common V3 directive replacements

Status

✅ Production-ready - Foundation layer complete

[johnleider]

Closed — production-ready foundation layer. Docs tracked separately.