# YpsilonEventHandler > **โš ๏ธ NOTICE: This repository is now archived for historical reference.** > > **YEH has been integrated directly into [@yaijs/core](https://github.com/yaijs/yai)** as of v1.1.0. This standalone repository remains available as a reference, but all active development, documentation, and support now happens in the main YaiJS repository. > > **Documentation:** [https://yaijs.github.io/yai/docs/yeh/](https://yaijs.github.io/yai/docs/yeh/) --- > A lightweight, flexible event delegation utility for modern web applications. Simplifies event management by centralizing listeners and providing advanced routing options. YpsilonEventHandler uses browser-native APIs (stable since 2000) for reliable, no-dependency event handling. Works on `file://` with zero build tools. [![NPM version](https://img.shields.io/npm/v/ypsilon-event-handler.svg)](https://npmjs.org/package/ypsilon-event-handler) [![License](https://img.shields.io/npm/l/ypsilon-event-handler.svg)](https://github.com/eypsilon/YpsilonEventHandler/blob/main/LICENSE) [![Documentation](https://img.shields.io/badge/docs-QuantumType-blueviolet)](https://github.com/eypsilon/YpsilonEventHandler/blob/main/ypsilon-event-handler.d.ts) --- ## โœจ Features - **Event Delegation Made Easy**: One listener handles dynamic elements with scope-based routing. - **Automatic Target Resolution**: Handles nested elements (e.g., SVGs in buttons). - **Throttle & Debounce Support**: Built-in performance controls. - **Dynamic Listener Management**: Add/remove events at runtime. - **Flexible Handler Resolution**: Class methods, external maps, or globals. - **Multi-Handler System**: Closest-match resolution for nested components. - **Performance Tracking**: Optional metrics for optimization. - **No Dependencies**: ~5kB gzipped, enterprise-ready (~800 LOC). For advanced patterns (e.g., reactive state, super delegation), see [README.USAGE.md](README.USAGE.md). For internals, see [README.TECHNICAL.md](README.TECHNICAL.md). --- ## ๐Ÿš€ Quick Start **No setup, no build step, no server, just include the file.** **Get started in 30 seconds** โ€“ [try it live on JSFiddle](https://jsfiddle.net/L6zk29v5/) ```html YEH Demo
``` **30-second setup:** Create `app.html`, copy & paste the above code, then double-click to run. > **๐Ÿ’ก Universal Delegation Pattern** > > One listener on parent + `custom-selector` = handles unlimited elements within the parent --- ## ๐Ÿ“ฆ Installation ### CDN (Instant Setup) ```html ``` ### npm (Build Tools) ```bash npm install ypsilon-event-handler ``` ### Direct Download [Download latest version](ypsilon-event-handler.js) - works with file:// protocol --- ### โš™๏ธ Configuration Options Pass a third argument to the constructor to enable advanced features: | Option | Type | Default | Description | | ---------------------- | --------- | ------- | ---------------------------------------------------------------------------| | `enableStats` | `boolean` | `false` | Track performance metrics like event count and distance cache hits. | | `methods` | `object` | `null` | External method map for organizing handlers by event type. | | `enableGlobalFallback` | `boolean` | `false` | Fallback to global `window` functions when no method is found. | | `methodsFirst` | `boolean` | `false` | Check `methods` object before class methods during handler resolution. | | `passiveEvents` | `array` | auto | Override default passive events (scroll, touch, wheel, pointer). | | `abortController` | `boolean` | `false` | Enable `AbortController` support for programmatic listener removal. | | `enableDistanceCache` | `boolean` | `true` | Cache DOM distance calculations for performance (multi-handler scenarios). | **Example:** `new YpsilonEventHandler(events, aliases, { enableStats: true });` --- ## ๐Ÿ”— Fluent Chaining API Chain operations for complex event orchestration: ```js App.on('data-ready', 'handleData') .on('user-login', 'handleLogin') .emit('init-complete', { loaded: true }); ``` --- ### ๐Ÿงน Cleanup `handler.destroy();` or `handler.abort();` (if enabled). --- ### ๐Ÿ“Š Performance Metrics With `enableStats: true`: `console.log(handler.getStats());` --- ## ๐ŸŒ Browser Support **Chrome** | **Firefox** | **Safari** | **Edge** - all modern versions *Works with legacy browsers via Webpack + Babel.* --- ## ๐Ÿ“Š Comparison vs Popular Libraries | Feature | YpsilonEventHandler | EventEmitter3 | Redux Toolkit | jQuery | |-----------------------------|---------------------|---------------|---------------|----------------| | **Bundle Size** | 5kB gzipped | 7kB gzipped | 12kB+ gzipped | 30kB+ gzipped | | **Dependencies** | โœ… Zero | โœ… Zero | โŒ Many | โœ… Zero | | **Event Delegation** | โœ… Advanced | โŒ None | โŒ None | โœ… Basic | | **Multi-Handler System** | โœ… Unique | โŒ None | โŒ None | โŒ None | | **Throttle/Debounce** | โœ… Built-in | โŒ None | โŒ None | โŒ None | | **Native Browser API** | โœ… Yes | โŒ No | โŒ No | โŒ No | | **Dynamic Element Support** | โœ… Zero-config | โŒ None | โŒ None | โœ… Re-bind | | **TypeScript Support** | โœ… Full | โœ… Partial | โœ… Full | โš ๏ธ Community | | **Memory Leak Prevention** | โœ… Automatic | โš ๏ธ Manual | โœ… Automatic | โš ๏ธ Manual | | **Performance** | โœ… Native | โš ๏ธ Synthetic | โš ๏ธ Virtual | โš ๏ธ Abstraction | | **Custom Event Dispatch** | โœ… Built-in | โœ… Yes | โœ… Yes | โœ… Yes | | **Learning Curve** | โœ… Low | โœ… Low | โŒ Steep | โœ… Familiar | ### Why YpsilonEventHandler Stands Out - **Smallest footprint** with advanced features like multi-handler delegation. - **Native performance** using browser APIs, avoiding synthetic event overhead. - **Zero dependencies** and automatic memory management for scalability. - **Built-in utilities** (throttle, debounce, stats) eliminate external needs. ## ๐Ÿš€ **See It In Action** **[Interactive Examples Hub](https://eypsilon.github.io/YpsilonEventHandler-Examples/example/public/)** ~ Beautiful landing page with all examples organized by category **[Feature Demonstrations](https://eypsilon.github.io/YpsilonEventHandler-Examples/example/public/features/)** ~ Interactive examples of specific capabilities --- #### ๐Ÿ“‚ File Structure ```bash / โ”œโ”€โ”€ ypsilon-event-handler.js # Main library โ”œโ”€โ”€ README.md # Quick start and core guide โ”œโ”€โ”€ README.USAGE.md # Advanced patterns and techniques โ””โ”€โ”€ README.TECHNICAL.md # Implementation details and architecture ``` --- #### License MIT License โ€“ free to use in personal or commercial projects. ##### ๐Ÿ‘ฅ **Authors & Contributors** - **Claude Van DOM** - Implementation and optimization - **Engin Ypsilon** - Original concept and architecture - **The Y-Team** - Sunny DeepSeek & Herr Von Grokk