elementdrawing 1.0.0

package/src/js/events.js

@@ -0,0 +1,585 @@
+/**
+ * Event System Utilities
+ * ElementDrawing Framework - Event binding, creation, normalization,
+ * keyboard/mouse/touch/scroll/resize handling, and custom event emitter.
+ */
+
+'use strict';
+
+// ─── Event Binding ────────────────────────────────────────────────────────────
+
+/**
+ * Bind an event handler to an element.
+ * @param {HTMLElement|Window|Document} el
+ * @param {string} event - Event type
+ * @param {Function} handler
+ * @param {Object|boolean} [options=false]
+ * @returns {Function} Unbind function
+ */
+function on(el, event, handler, options) {
+  el.addEventListener(event, handler, options || false);
+  return function unbind() {
+    el.removeEventListener(event, handler, options || false);
+  };
+}
+
+/**
+ * Remove an event handler from an element.
+ * @param {HTMLElement|Window|Document} el
+ * @param {string} event
+ * @param {Function} handler
+ * @param {Object|boolean} [options=false]
+ */
+function off(el, event, handler, options) {
+  el.removeEventListener(event, handler, options || false);
+}
+
+/**
+ * Bind an event handler that fires only once.
+ * @param {HTMLElement|Window|Document} el
+ * @param {string} event
+ * @param {Function} handler
+ * @param {Object|boolean} [options=false]
+ * @returns {Function} Unbind function
+ */
+function once(el, event, handler, options) {
+  function onceHandler() {
+    off(el, event, onceHandler, options);
+    return handler.apply(this, arguments);
+  }
+  on(el, event, onceHandler, options);
+  return function unbind() {
+    off(el, event, onceHandler, options);
+  };
+}
+
+/**
+ * Delegate an event to matching child elements.
+ * @param {HTMLElement} parent - Parent element to listen on
+ * @param {string} event - Event type
+ * @param {string} selector - CSS selector for child elements
+ * @param {Function} handler - Event handler
+ * @returns {Function} Unbind function
+ */
+function delegate(parent, event, selector, handler) {
+  function delegateHandler(e) {
+    const target = e.target.closest(selector);
+    if (target && parent.contains(target)) {
+      handler.call(target, e, target);
+    }
+  }
+  on(parent, event, delegateHandler);
+  return function unbind() {
+    off(parent, event, delegateHandler);
+  };
+}
+
+// ─── Event Creation ───────────────────────────────────────────────────────────
+
+/**
+ * Create a custom event.
+ * @param {string} type - Event type
+ * @param {Object} [detail] - Custom data
+ * @param {Object} [options] - Event options
+ * @returns {CustomEvent}
+ */
+function createEvent(type, detail, options) {
+  options = options || {};
+  return new CustomEvent(type, {
+    bubbles: options.bubbles !== undefined ? options.bubbles : true,
+    cancelable: options.cancelable !== undefined ? options.cancelable : true,
+    detail: detail,
+  });
+}
+
+/**
+ * Dispatch an event on an element.
+ * @param {HTMLElement} el
+ * @param {Event|string} event
+ * @param {Object} [detail]
+ * @returns {boolean} False if preventDefault was called
+ */
+function dispatchEvent(el, event, detail) {
+  if (typeof event === 'string') {
+    event = createEvent(event, detail);
+  }
+  return el.dispatchEvent(event);
+}
+
+/**
+ * Fire a native-like event on an element.
+ * @param {HTMLElement} el
+ * @param {string} type - e.g. 'click', 'focus', 'blur'
+ * @param {Object} [options]
+ * @returns {boolean}
+ */
+function fireEvent(el, type, options) {
+  const event = new Event(type, {
+    bubbles: (options && options.bubbles) !== undefined ? options.bubbles : true,
+    cancelable: (options && options.cancelable) !== undefined ? options.cancelable : true,
+  });
+  Object.assign(event, options || {});
+  return el.dispatchEvent(event);
+}
+
+// ─── Event Normalization ──────────────────────────────────────────────────────
+
+/**
+ * Get the event target.
+ * @param {Event} e
+ * @returns {HTMLElement}
+ */
+function getTarget(e) {
+  return e.target || e.srcElement;
+}
+
+/**
+ * Get the related target (for mouseenter/mouseleave, focus/blur).
+ * @param {Event} e
+ * @returns {HTMLElement|null}
+ */
+function getRelatedTarget(e) {
+  return e.relatedTarget || null;
+}
+
+/**
+ * Get the offset coordinates of a mouse event relative to the target.
+ * @param {MouseEvent} e
+ * @returns {{ offsetX: number, offsetY: number }}
+ */
+function getOffset(e) {
+  return { offsetX: e.offsetX, offsetY: e.offsetY };
+}
+
+/**
+ * Prevent default behavior.
+ * @param {Event} e
+ */
+function preventDefault(e) {
+  if (e.preventDefault) e.preventDefault();
+  e.returnValue = false;
+}
+
+/**
+ * Stop event propagation.
+ * @param {Event} e
+ */
+function stopPropagation(e) {
+  if (e.stopPropagation) e.stopPropagation();
+  e.cancelBubble = true;
+}
+
+/**
+ * Stop immediate propagation.
+ * @param {Event} e
+ */
+function stopImmediatePropagation(e) {
+  if (e.stopImmediatePropagation) e.stopImmediatePropagation();
+}
+
+// ─── Keyboard Events ──────────────────────────────────────────────────────────
+
+/**
+ * Check if the key is Enter.
+ * @param {KeyboardEvent} e
+ * @returns {boolean}
+ */
+function isEnter(e) {
+  return e.key === 'Enter' || e.keyCode === 13;
+}
+
+/**
+ * Check if the key is Escape.
+ * @param {KeyboardEvent} e
+ * @returns {boolean}
+ */
+function isEscape(e) {
+  return e.key === 'Escape' || e.keyCode === 27;
+}
+
+/**
+ * Check if the key is Tab.
+ * @param {KeyboardEvent} e
+ * @returns {boolean}
+ */
+function isTab(e) {
+  return e.key === 'Tab' || e.keyCode === 9;
+}
+
+/**
+ * Check if the key is an arrow key.
+ * @param {KeyboardEvent} e
+ * @returns {boolean}
+ */
+function isArrow(e) {
+  return e.key.startsWith('Arrow') || (e.keyCode >= 37 && e.keyCode <= 40);
+}
+
+/**
+ * Get the key code from a keyboard event.
+ * @param {KeyboardEvent} e
+ * @returns {number}
+ */
+function getKeyCode(e) {
+  return e.keyCode || e.which || 0;
+}
+
+/**
+ * Check if a modifier key is pressed.
+ * @param {KeyboardEvent} e
+ * @param {string} modifier - 'ctrl' | 'shift' | 'alt' | 'meta'
+ * @returns {boolean}
+ */
+function isModifier(e, modifier) {
+  switch (modifier) {
+    case 'ctrl': return e.ctrlKey;
+    case 'shift': return e.shiftKey;
+    case 'alt': return e.altKey;
+    case 'meta': return e.metaKey;
+    default: return false;
+  }
+}
+
+// ─── Mouse Events ─────────────────────────────────────────────────────────────
+
+/**
+ * Check if the mouse button is a left click.
+ * @param {MouseEvent} e
+ * @returns {boolean}
+ */
+function isLeftClick(e) {
+  return e.button === 0;
+}
+
+/**
+ * Check if the mouse button is a right click.
+ * @param {MouseEvent} e
+ * @returns {boolean}
+ */
+function isRightClick(e) {
+  return e.button === 2;
+}
+
+/**
+ * Get the mouse button number.
+ * @param {MouseEvent} e
+ * @returns {number}
+ */
+function getButton(e) {
+  return e.button;
+}
+
+/**
+ * Get the mouse coordinates (page and client).
+ * @param {MouseEvent} e
+ * @returns {{ pageX: number, pageY: number, clientX: number, clientY: number }}
+ */
+function getCoordinates(e) {
+  return {
+    pageX: e.pageX,
+    pageY: e.pageY,
+    clientX: e.clientX,
+    clientY: e.clientY,
+  };
+}
+
+// ─── Touch Events ─────────────────────────────────────────────────────────────
+
+/**
+ * Get a specific touch from a touch event.
+ * @param {TouchEvent} e
+ * @param {number} [index=0]
+ * @returns {Touch|null}
+ */
+function getTouch(e, index) {
+  index = index || 0;
+  return e.touches && e.touches[index] ? e.touches[index] : null;
+}
+
+/**
+ * Get the distance between two touch points.
+ * @param {TouchEvent} e
+ * @returns {number}
+ */
+function getTouchDistance(e) {
+  if (!e.touches || e.touches.length < 2) return 0;
+  const dx = e.touches[0].clientX - e.touches[1].clientX;
+  const dy = e.touches[0].clientY - e.touches[1].clientY;
+  return Math.sqrt(dx * dx + dy * dy);
+}
+
+/**
+ * Check if a touch event is a pinch gesture.
+ * @param {TouchEvent} e
+ * @returns {boolean}
+ */
+function isPinch(e) {
+  return e.touches && e.touches.length >= 2;
+}
+
+/**
+ * Check if a touch event is a swipe.
+ * @param {Object} startTouch - Starting touch coordinates
+ * @param {Object} endTouch - Ending touch coordinates
+ * @param {number} [threshold=50] - Minimum distance for a swipe
+ * @returns {{ isSwipe: boolean, direction: string, distance: number }}
+ */
+function isSwipe(startTouch, endTouch, threshold) {
+  threshold = threshold || 50;
+  const dx = endTouch.clientX - startTouch.clientX;
+  const dy = endTouch.clientY - startTouch.clientY;
+  const absDx = Math.abs(dx);
+  const absDy = Math.abs(dy);
+  const distance = Math.sqrt(dx * dx + dy * dy);
+
+  if (distance < threshold) {
+    return { isSwipe: false, direction: '', distance };
+  }
+
+  let direction;
+  if (absDx > absDy) {
+    direction = dx > 0 ? 'right' : 'left';
+  } else {
+    direction = dy > 0 ? 'down' : 'up';
+  }
+
+  return { isSwipe: true, direction, distance };
+}
+
+// ─── Scroll Events ────────────────────────────────────────────────────────────
+
+/**
+ * Bind a scroll handler with optional throttling.
+ * @param {HTMLElement|Window} el
+ * @param {Function} handler
+ * @param {number} [throttleMs=100]
+ * @returns {Function} Unbind function
+ */
+function onScroll(el, handler, throttleMs) {
+  throttleMs = throttleMs || 100;
+  let lastCall = 0;
+  let ticking = false;
+
+  function scrollHandler(e) {
+    const now = Date.now();
+    if (now - lastCall < throttleMs) {
+      if (!ticking) {
+        ticking = true;
+        requestAnimationFrame(() => {
+          handler(e);
+          ticking = false;
+        });
+      }
+      return;
+    }
+    lastCall = now;
+    handler(e);
+  }
+
+  return on(el, 'scroll', scrollHandler, { passive: true });
+}
+
+/**
+ * Bind a handler that fires when scrolling ends.
+ * @param {HTMLElement|Window} el
+ * @param {Function} handler
+ * @param {number} [delay=150]
+ * @returns {Function} Unbind function
+ */
+function onScrollEnd(el, handler, delay) {
+  delay = delay || 150;
+  let timeoutId;
+
+  function scrollHandler() {
+    clearTimeout(timeoutId);
+    timeoutId = setTimeout(() => handler(), delay);
+  }
+
+  const unbind = on(el, 'scroll', scrollHandler, { passive: true });
+  return function unbindScrollEnd() {
+    clearTimeout(timeoutId);
+    unbind();
+  };
+}
+
+/**
+ * Get scroll direction from previous and current scroll positions.
+ * @param {number} prevScrollTop
+ * @param {number} currentScrollTop
+ * @returns {'up'|'down'|'none'}
+ */
+function getScrollDirection(prevScrollTop, currentScrollTop) {
+  const diff = currentScrollTop - prevScrollTop;
+  if (diff > 0) return 'down';
+  if (diff < 0) return 'up';
+  return 'none';
+}
+
+// ─── Resize Events ────────────────────────────────────────────────────────────
+
+/**
+ * Bind a resize handler with debouncing.
+ * @param {Function} handler
+ * @param {number} [debounceMs=150]
+ * @returns {Function} Unbind function
+ */
+function onResize(handler, debounceMs) {
+  debounceMs = debounceMs || 150;
+  let timeoutId;
+
+  function resizeHandler() {
+    clearTimeout(timeoutId);
+    timeoutId = setTimeout(() => {
+      handler({
+        width: window.innerWidth,
+        height: window.innerHeight,
+      });
+    }, debounceMs);
+  }
+
+  return on(window, 'resize', resizeHandler);
+}
+
+/**
+ * Create a debounced resize observer for a specific element.
+ * @param {HTMLElement} el
+ * @param {Function} handler
+ * @returns {{ disconnect: Function }} Observer handle
+ */
+function debounceResize(el, handler) {
+  if (typeof ResizeObserver === 'undefined') {
+    return { disconnect: function () {} };
+  }
+
+  let timeoutId;
+  const observer = new ResizeObserver((entries) => {
+    clearTimeout(timeoutId);
+    timeoutId = setTimeout(() => handler(entries), 100);
+  });
+
+  observer.observe(el);
+  return {
+    disconnect: function () {
+      clearTimeout(timeoutId);
+      observer.disconnect();
+    },
+  };
+}
+
+// ─── Custom Event Emitter ─────────────────────────────────────────────────────
+
+/**
+ * Create a custom event emitter.
+ * @returns {Object} Emitter with on, off, emit, once methods
+ */
+function emitter() {
+  const listeners = {};
+
+  return {
+    /**
+     * Subscribe to an event.
+     * @param {string} event
+     * @param {Function} handler
+     * @returns {Function} Unsubscribe function
+     */
+    on: function (event, handler) {
+      if (!listeners[event]) listeners[event] = [];
+      listeners[event].push(handler);
+      return function () {
+        const idx = listeners[event].indexOf(handler);
+        if (idx !== -1) listeners[event].splice(idx, 1);
+      };
+    },
+
+    /**
+     * Unsubscribe from an event.
+     * @param {string} event
+     * @param {Function} [handler] - If omitted, removes all handlers for the event
+     */
+    off: function (event, handler) {
+      if (!listeners[event]) return;
+      if (!handler) {
+        delete listeners[event];
+        return;
+      }
+      const idx = listeners[event].indexOf(handler);
+      if (idx !== -1) listeners[event].splice(idx, 1);
+    },
+
+    /**
+     * Emit an event.
+     * @param {string} event
+     * @param {...*} args
+     * @returns {boolean} True if any handler was called
+     */
+    emit: function (event) {
+      const args = Array.prototype.slice.call(arguments, 1);
+      if (!listeners[event]) return false;
+
+      listeners[event].slice().forEach((handler) => {
+        try {
+          handler.apply(null, args);
+        } catch (error) {
+          console.error('[emitter] Handler error for "' + event + '":', error);
+        }
+      });
+      return true;
+    },
+
+    /**
+     * Subscribe to an event once.
+     * @param {string} event
+     * @param {Function} handler
+     * @returns {Function} Unsubscribe function
+     */
+    once: function (event, handler) {
+      function onceHandler() {
+        emitter.off(event, onceHandler);
+        return handler.apply(null, arguments);
+      }
+      return emitter.on(event, onceHandler);
+    },
+
+    /**
+     * Get all listener counts.
+     * @returns {Object}
+     */
+    listenerCounts: function () {
+      const counts = {};
+      Object.keys(listeners).forEach((event) => {
+        counts[event] = listeners[event].length;
+      });
+      return counts;
+    },
+
+    /**
+     * Remove all listeners.
+     */
+    removeAllListeners: function () {
+      Object.keys(listeners).forEach((key) => delete listeners[key]);
+    },
+  };
+}
+
+// ─── Exports ──────────────────────────────────────────────────────────────────
+
+module.exports = {
+  // Event binding
+  on, off, once, delegate,
+  // Event creation
+  createEvent, dispatchEvent, fireEvent,
+  // Event normalization
+  getTarget, getRelatedTarget, getOffset, preventDefault, stopPropagation, stopImmediatePropagation,
+  // Keyboard events
+  isEnter, isEscape, isTab, isArrow, getKeyCode, isModifier,
+  // Mouse events
+  isLeftClick, isRightClick, getButton, getCoordinates,
+  // Touch events
+  getTouch, getTouchDistance, isPinch, isSwipe,
+  // Scroll events
+  onScroll, onScrollEnd, getScrollDirection,
+  // Resize events
+  onResize, debounceResize,
+  // Custom events
+  emitter,
+};