Event Handling

/**
 * Attach event handlers to elements
 * @param events - Space-separated event types or event map object
 * @param selector - Optional selector for event delegation
 * @param data - Optional data to pass to handler
 * @param handler - Event handler function
 * @returns jQuery object for chaining
 */
on(events: string, handler: function): jQuery;
on(events: string, selector: string, handler: function): jQuery;
on(events: string, data: any, handler: function): jQuery;
on(events: string, selector: string, data: any, handler: function): jQuery;
on(events: object): jQuery;

/**
 * Attach one-time event handlers that are automatically removed after first trigger
 * @param events - Space-separated event types or event map object
 * @param selector - Optional selector for event delegation
 * @param data - Optional data to pass to handler
 * @param handler - Event handler function
 * @returns jQuery object for chaining
 */
one(events: string, handler: function): jQuery;
one(events: string, selector: string, handler: function): jQuery;
one(events: string, data: any, handler: function): jQuery;
one(events: string, selector: string, data: any, handler: function): jQuery;
one(events: object): jQuery;

// Basic event binding
$('#button').on('click', function() {
  alert('Button clicked!');
});

// Multiple events
$('.item').on('mouseenter mouseleave', function(e) {
  $(this).toggleClass('hover', e.type === 'mouseenter');
});

// Event delegation
$('#container').on('click', '.item', function() {
  // Handle click on .item elements inside #container
  // Works for current and future .item elements
});

// Passing data
$('.button').on('click', { message: 'Hello' }, function(e) {
  alert(e.data.message); // 'Hello'
});

// Event map
$('#element').on({
  'click': function() { console.log('clicked'); },
  'mouseenter': function() { console.log('entered'); },
  'mouseleave': function() { console.log('left'); }
});

// One-time handlers
$('#dialog').one('click', '.close', function() {
  $('#dialog').remove();
});

/**
 * Remove event handlers from elements
 * @param events - Optional space-separated event types
 * @param selector - Optional selector that was used for delegation
 * @param handler - Optional specific handler function to remove
 * @returns jQuery object for chaining
 */
off(): jQuery;
off(events: string): jQuery;
off(events: string, handler: function): jQuery;
off(events: string, selector: string): jQuery;
off(events: string, selector: string, handler: function): jQuery;
off(events: object): jQuery;

// Remove all event handlers
$('#element').off();

// Remove specific event type
$('#element').off('click');

// Remove specific handler
function myHandler() { /* ... */ }
$('#element').on('click', myHandler);
$('#element').off('click', myHandler);

// Remove delegated events
$('#container').off('click', '.item');

// Remove using event map
$('#element').off({
  'click': myClickHandler,
  'mouseenter': myEnterHandler
});

/**
 * Trigger event handlers and default browser behavior
 * @param eventType - Event type to trigger
 * @param extraParameters - Optional additional parameters to pass to handlers
 * @returns jQuery object for chaining
 */
trigger(eventType: string, extraParameters?: any[]): jQuery;
trigger(event: Event, extraParameters?: any[]): jQuery;

/**
 * Trigger event handlers only (no bubbling or default behavior)
 * @param eventType - Event type to trigger
 * @param extraParameters - Optional additional parameters to pass to handlers
 * @returns Result from last triggered handler
 */
triggerHandler(eventType: string, extraParameters?: any[]): any;

// Trigger click event
$('#button').trigger('click');

// Trigger with additional data
$('#input').trigger('change', ['custom', 'data']);

// Trigger custom events
$('#element').trigger('custom:event', { customData: true });

// triggerHandler - no bubbling/defaults
const result = $('#input').triggerHandler('focus');

// Event namespacing syntax: 'eventType.namespace'
// Multiple namespaces: 'eventType.namespace1.namespace2'

// Add namespaced events
$('#element').on('click.myPlugin', handler1);
$('#element').on('click.myPlugin.special', handler2);
$('#element').on('mouseenter.myPlugin', handler3);

// Remove by namespace
$('#element').off('.myPlugin'); // Remove all myPlugin events
$('#element').off('click.myPlugin'); // Remove only click.myPlugin
$('#element').off('.special'); // Remove all .special events

// Trigger by namespace
$('#element').trigger('click.myPlugin');

// Define custom event handler
$('#element').on('user:login', function(e, userData) {
  console.log('User logged in:', userData);
});

// Trigger custom event
$('#element').trigger('user:login', [{ name: 'John', id: 123 }]);

// Custom events with delegation
$('#app').on('widget:update', '.widget', function(e, data) {
  // Handle widget update events
});

// Trigger on specific widgets
$('.widget').trigger('widget:update', [updateData]);

interface JQueryEvent extends Event {
  // Event information
  type: string;
  target: Element;
  currentTarget: Element;
  relatedTarget?: Element;
  pageX: number;
  pageY: number;
  which: number;
  data?: any;
  namespace?: string;
  result?: any;
  timeStamp: number;
  
  // Event control methods
  preventDefault(): void;
  stopPropagation(): void;
  stopImmediatePropagation(): void;
  
  // Event state checking
  isDefaultPrevented(): boolean;
  isPropagationStopped(): boolean;
  isImmediatePropagationStopped(): boolean;
}

$('#element').on('click', function(e) {
  // Prevent default browser behavior
  e.preventDefault();
  
  // Stop event from bubbling up
  e.stopPropagation();
  
  // Access event properties
  console.log('Event type:', e.type);
  console.log('Target element:', e.target);
  console.log('Mouse position:', e.pageX, e.pageY);
  console.log('Key/button pressed:', e.which);
  
  // Check event state
  if (e.isDefaultPrevented()) {
    console.log('Default was prevented');
  }
});

// Mouse events
click(handler?: function): jQuery;
dblclick(handler?: function): jQuery;
mousedown(handler?: function): jQuery;
mouseup(handler?: function): jQuery;
mousemove(handler?: function): jQuery;
mouseover(handler?: function): jQuery;
mouseout(handler?: function): jQuery;
mouseenter(handler?: function): jQuery;
mouseleave(handler?: function): jQuery;

// Keyboard events
keydown(handler?: function): jQuery;
keyup(handler?: function): jQuery;
keypress(handler?: function): jQuery;

// Form events
submit(handler?: function): jQuery;
change(handler?: function): jQuery;
focus(handler?: function): jQuery;
blur(handler?: function): jQuery;
focusin(handler?: function): jQuery;
focusout(handler?: function): jQuery;
select(handler?: function): jQuery;

// Window/Document events
resize(handler?: function): jQuery;
scroll(handler?: function): jQuery;
contextmenu(handler?: function): jQuery;

/**
 * Bind handlers for mouseenter and mouseleave events
 * @param handlerIn - Function to execute on mouseenter
 * @param handlerOut - Optional function to execute on mouseleave (defaults to handlerIn)
 * @returns jQuery object for chaining
 */
hover(handlerIn: function, handlerOut?: function): jQuery;

// Using shortcuts to bind events
$('#button').click(function() {
  console.log('Button clicked');
});

$('#input').focus(function() {
  $(this).addClass('focused');
}).blur(function() {
  $(this).removeClass('focused');
});

// Using shortcuts to trigger events
$('#button').click(); // Trigger click event
$('#form').submit(); // Trigger submit event

// Hover method
$('.item').hover(
  function() {
    $(this).addClass('hovered');
  },
  function() {
    $(this).removeClass('hovered');
  }
);

// Hover with single handler (for both enter and leave)
$('.button').hover(function() {
  $(this).toggleClass('highlight');
});

// Additional event shortcuts
$('#element').contextmenu(function(e) {
  e.preventDefault(); // Prevent browser context menu
  showCustomMenu();
});

$('#input').focusin(function() {
  $(this).parent().addClass('focus-container');
}).focusout(function() {
  $(this).parent().removeClass('focus-container');
});

/**
 * Create jQuery event object from native event
 * @param src - Source event or event type string
 * @param props - Optional properties to set on event object
 * @returns jQuery event object
 */
$.Event(src: string | Event, props?: object): JQueryEvent;

/**
 * Remove native event listener from element
 * @param element - Target element
 * @param type - Event type
 * @param handler - Event handler function
 */
$.removeEvent(element: Element, type: string, handler: function): void;

// Global event configuration
$.event.global: object; // Registry of global events
$.event.special: object; // Special event handlers by type

// Event system methods
$.event.add(element: Element, types: string, handler: function, data?: any, selector?: string): void;
$.event.remove(element: Element, types: string, handler?: function, selector?: string, mappedTypes?: boolean): void;
$.event.dispatch(nativeEvent: Event): any;
$.event.handlers(event: JQueryEvent, handlers: Array): Array;
$.event.fix(originalEvent: Event): JQueryEvent;
$.event.addProp(name: string, hook?: function): void;

// Create custom event objects
const customEvent = $.Event('custom:event', {
  customProperty: 'value'
});
$('#element').trigger(customEvent);

// Special event handling
$.event.special['custom:event'] = {
  setup: function() {
    // Setup code when first handler is bound
  },
  teardown: function() {
    // Cleanup code when last handler is removed
  },
  add: function(handleObj) {
    // Code to run when handler is added
  },
  remove: function(handleObj) {
    // Code to run when handler is removed
  }
};

// Efficient delegation for dynamic content
$('#container').on('click', '.button', function() {
  // Handles clicks on any .button inside #container
  // Works for buttons added after this code runs
});

// Multiple delegated events
$('#app').on({
  'click .save': function() { /* save handler */ },
  'click .cancel': function() { /* cancel handler */ },
  'change input': function() { /* input change handler */ }
});

// Delegation with data
$('#list').on('click', '.item', { action: 'select' }, function(e) {
  console.log('Action:', e.data.action);
});