@mkmonkeycat/dom-utils 0.1.0

package/src/dom/element.ts

@@ -0,0 +1,252 @@
+/**
+ * Parses class names from various input formats into a flat array of class names.
+ * @param classNames - Class names as strings, arrays of strings, or undefined.
+ * @returns An array of individual class names.
+ */
+export const parseClass = (...classNames: (string | string[] | undefined)[]): string[] => {
+  return classNames.flatMap((className) => {
+    if (typeof className === 'string') {
+      return className.trim().split(/\s+/).filter(Boolean);
+    }
+    return className || [];
+  });
+};
+
+/**
+ * Creates an HTML element with specified attributes and children.
+ * @param tag - The tag name of the HTML element to create.
+ * @param attributes - An object containing attributes, styles, event handlers, and dataset entries to set on the element.
+ * @param children - Child nodes or strings to append to the created element.
+ * @returns The created HTML element.
+ */
+export const createElement = <K extends keyof HTMLElementTagNameMap>(
+  tag: K,
+  attributes?: ElementAttributes<HTMLElementTagNameMap[K]>,
+  ...children: (Node | string)[]
+): HTMLElementTagNameMap[K] => {
+  const element = document.createElement(tag);
+
+  if (!attributes) {
+    addChildren(element, children);
+    return element;
+  }
+
+  Object.entries(attributes).forEach(([key, value]) => {
+    if (value == null) return;
+
+    if (key === 'className' || key === 'class') {
+      const classes = Array.isArray(value) ? parseClass(...value) : parseClass(value as string);
+      element.className = classes.join(' ');
+      return;
+    }
+
+    if (key === 'style') {
+      if (typeof value === 'string') {
+        element.style.cssText = value;
+      } else if (typeof value === 'object') {
+        Object.assign(element.style, value);
+      }
+      return;
+    }
+
+    if (key === 'dataset' && typeof value === 'object') {
+      Object.assign(element.dataset, value as Record<string, string>);
+      return;
+    }
+
+    if (key.startsWith('on')) {
+      const eventName = key.slice(2).toLowerCase();
+      if (typeof value === 'function') {
+        element.addEventListener(eventName, value as EventListener);
+      } else if (Array.isArray(value)) {
+        value.forEach((handler) => {
+          if (typeof handler === 'function') {
+            element.addEventListener(eventName, handler);
+          }
+        });
+      }
+      return;
+    }
+
+    if (key in element) {
+      (element as Record<string, unknown>)[key] = value;
+    } else {
+      element.setAttribute(key, String(value));
+    }
+  });
+
+  addChildren(element, children);
+  return element;
+};
+
+/**
+ * Creates a DocumentFragment for batch DOM operations.
+ * @param children - Child nodes or strings to add to the fragment.
+ * @returns A DocumentFragment containing the children.
+ */
+export const createFragment = (...children: (Node | string)[]): DocumentFragment => {
+  const frag = document.createDocumentFragment();
+  children.forEach((child) => {
+    if (typeof child === 'string') {
+      frag.appendChild(document.createTextNode(child));
+    } else {
+      frag.appendChild(child);
+    }
+  });
+  return frag;
+};
+
+const addChildren = (element: HTMLElement, children: (Node | string)[]) => {
+  children.forEach((child) => {
+    if (typeof child === 'string') {
+      element.appendChild(document.createTextNode(child));
+    } else {
+      element.appendChild(child);
+    }
+  });
+};
+
+export type CSSProperties = Partial<CSSStyleDeclaration> | string;
+
+export type EventHandlers = {
+  [K in keyof HTMLElementEventMap as `on${Capitalize<K>}`]?: (
+    event: HTMLElementEventMap[K],
+  ) => void;
+};
+
+export type ElementAttributes<T extends HTMLElement = HTMLElement> = {
+  className?: string | string[];
+  class?: string | string[];
+  style?: CSSProperties;
+  dataset?: Record<string, string>;
+} & EventHandlers &
+  Partial<Omit<T, 'style' | 'children' | 'className' | 'classList' | 'dataset'>> & {
+    [key: string]: unknown;
+  };
+
+/**
+ * Gets the width and height of an element (including padding and border).
+ * @param element - The element to measure.
+ * @returns An object with width and height properties.
+ */
+export const getSize = (element: HTMLElement): { width: number; height: number } => {
+  return {
+    width: element.offsetWidth,
+    height: element.offsetHeight,
+  };
+};
+
+/**
+ * Gets the offset position of an element relative to the document.
+ * @param element - The element to measure.
+ * @returns An object with top and left properties.
+ */
+export const getOffset = (element: HTMLElement): { top: number; left: number } => {
+  return {
+    top: element.offsetTop,
+    left: element.offsetLeft,
+  };
+};
+
+/**
+ * Gets a computed style value for an element.
+ * @param element - The element to query.
+ * @param property - The CSS property name.
+ * @returns The computed style value.
+ */
+export const getComputedStyle = (element: HTMLElement, property: string): string => {
+  return window.getComputedStyle(element).getPropertyValue(property).trim();
+};
+
+/**
+ * Scrolls the element to a specific position (or to view if no position specified).
+ * @param element - The element to scroll.
+ * @param options - Scroll behavior options.
+ */
+export const scrollTo = (
+  element: HTMLElement,
+  options?: ScrollToOptions | { top?: number; left?: number },
+): void => {
+  if (!element) return;
+  if (element === document.documentElement || element === document.body) {
+    window.scrollTo(options as ScrollToOptions);
+  } else {
+    element.scrollTo?.(options as ScrollToOptions);
+  }
+};
+
+/**
+ * Scrolls the element into the viewport.
+ * @param element - The element to scroll into view.
+ * @param options - Scroll behavior options.
+ */
+export const scrollIntoView = (
+  element: HTMLElement,
+  options?: ScrollIntoViewOptions | boolean,
+): void => {
+  element.scrollIntoView?.(options);
+};
+
+/**
+ * Gets the inner size of an element (client width/height: includes padding, excludes border and scrollbar).
+ * @param element - The element to measure.
+ * @returns An object with width and height properties.
+ */
+export const getInnerSize = (element: HTMLElement): { width: number; height: number } => {
+  return {
+    width: element.clientWidth,
+    height: element.clientHeight,
+  };
+};
+
+/**
+ * Gets the outer size of an element (offset size). Optionally includes margins.
+ * @param element - The element to measure.
+ * @param includeMargin - Whether to include margins in the calculation.
+ * @returns An object with width and height properties.
+ */
+export const getOuterSize = (
+  element: HTMLElement,
+  includeMargin = false,
+): { width: number; height: number } => {
+  let width = element.offsetWidth;
+  let height = element.offsetHeight;
+
+  if (includeMargin) {
+    const styles = window.getComputedStyle(element);
+    const ml = parseFloat(styles.marginLeft || '0');
+    const mr = parseFloat(styles.marginRight || '0');
+    const mt = parseFloat(styles.marginTop || '0');
+    const mb = parseFloat(styles.marginBottom || '0');
+    width += ml + mr;
+    height += mt + mb;
+  }
+
+  return { width, height };
+};
+
+/**
+ * Gets the bounding client rect of an element.
+ * @param element - The element to measure.
+ * @returns The DOMRect representing the element's bounding box.
+ */
+export const getRect = (element: HTMLElement): DOMRect => {
+  return element.getBoundingClientRect();
+};
+
+/**
+ * Creates an SVG element from an SVG string.
+ * @param svgString - The SVG markup as a string.
+ * @returns The parsed SVGElement.
+ * @throws Error if the SVG string is invalid or contains multiple root elements.
+ */
+export const createSVGFromString = (svgString: string): SVGElement => {
+  const parser = new DOMParser();
+  const doc = parser.parseFromString(svgString, 'image/svg+xml');
+
+  if (doc.documentElement.nodeName === 'parsererror') {
+    throw new Error('Invalid SVG string: Failed to parse SVG');
+  }
+
+  return doc.documentElement as unknown as SVGElement;
+};

package/src/dom/events.ts

@@ -0,0 +1,245 @@
+import type { SingleOrArray } from '../utils/types';
+import { markAsEventFunc } from './tag-internal';
+
+/**
+ * Options for onClickOutside function.
+ */
+export interface OnClickOutsideOptions {
+  /** Event type to listen for. Default: 'mousedown' */
+  event?: 'mousedown' | 'mouseup' | 'click';
+  /** Whether to capture the event. Default: true */
+  capture?: boolean;
+  /** Elements to exclude from the outside check */
+  exclude?: (HTMLElement | null)[];
+}
+
+/**
+ * Attaches a listener that triggers when clicking outside the specified element.
+ * @param element - The element to watch.
+ * @param callback - The callback to invoke when clicking outside.
+ * @param options - Configuration options.
+ * @returns A function to remove the listener.
+ */
+export const onClickOutside = (
+  element: HTMLElement,
+  callback: (event: MouseEvent) => void,
+  options: OnClickOutsideOptions = {},
+): (() => void) => {
+  const { event = 'mousedown', capture = true, exclude = [] } = options;
+
+  const handleClick = markAsEventFunc((e: MouseEvent) => {
+    const target = e.target as Node;
+
+    // Check if click is on the element or its descendants
+    if (element.contains(target)) return;
+
+    // Check if click is on excluded elements
+    if (exclude.some((el) => el?.contains(target))) return;
+
+    callback(e);
+  });
+
+  document.addEventListener(event, handleClick, capture);
+
+  return () => document.removeEventListener(event, handleClick, capture);
+};
+
+/**
+ * Options for onKeyPress function.
+ */
+export interface OnKeyPressOptions {
+  /** Whether to prevent default behavior. Default: false */
+  preventDefault?: boolean;
+  /** Whether to stop propagation. Default: false */
+  stopPropagation?: boolean;
+  /** Event type. Default: 'keydown' */
+  event?: 'keydown' | 'keyup' | 'keypress';
+  /** Target element. Default: document */
+  target?: HTMLElement | Document;
+}
+
+/**
+ * Attaches a listener for specific key presses.
+ * @param key - The key or keys to listen for (e.g., 'Escape', 'Enter', ['a', 'b']).
+ * @param callback - The callback to invoke when the key is pressed.
+ * @param options - Configuration options.
+ * @returns A function to remove the listener.
+ */
+export const onKeyPress = (
+  key: string | string[],
+  callback: (event: KeyboardEvent) => void,
+  options: OnKeyPressOptions = {},
+): (() => void) => {
+  const {
+    preventDefault = false,
+    stopPropagation = false,
+    event = 'keydown',
+    target = document,
+  } = options;
+
+  const keys = Array.isArray(key) ? key : [key];
+
+  const handleKeyPress = markAsEventFunc((e: KeyboardEvent) => {
+    if (keys.includes(e.key)) {
+      if (preventDefault) e.preventDefault();
+      if (stopPropagation) e.stopPropagation();
+      callback(e);
+    }
+  });
+
+  target.addEventListener(event, handleKeyPress as EventListener);
+
+  return () => target.removeEventListener(event, handleKeyPress as EventListener);
+};
+
+/**
+ * Options for onEscape function.
+ */
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+export interface OnEscapeOptions extends Omit<OnKeyPressOptions, 'event'> {}
+
+/**
+ * Attaches a listener for the Escape key.
+ * @param callback - The callback to invoke when Escape is pressed.
+ * @param options - Configuration options.
+ * @returns A function to remove the listener.
+ */
+export const onEscape = (
+  callback: (event: KeyboardEvent) => void,
+  options: OnEscapeOptions = {},
+): (() => void) => {
+  return onKeyPress('Escape', callback, options);
+};
+
+/**
+ * Options for onEnter function.
+ */
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+export interface OnEnterOptions extends Omit<OnKeyPressOptions, 'event'> {}
+
+/**
+ * Attaches a listener for the Enter key.
+ * @param callback - The callback to invoke when Enter is pressed.
+ * @param options - Configuration options.
+ * @returns A function to remove the listener.
+ */
+export const onEnter = (
+  callback: (event: KeyboardEvent) => void,
+  options: OnEnterOptions = {},
+): (() => void) => {
+  return onKeyPress('Enter', callback, options);
+};
+
+/**
+ * Options for onLongPress function.
+ */
+export interface OnLongPressOptions {
+  /** Duration in milliseconds to trigger long press. Default: 500 */
+  duration?: number;
+  /** Threshold in pixels for movement tolerance. Default: 10 */
+  threshold?: number;
+}
+
+/**
+ * Attaches a listener for long press events.
+ * @param element - The element to watch.
+ * @param callback - The callback to invoke on long press.
+ * @param options - Configuration options.
+ * @returns A function to remove the listeners.
+ */
+export const onLongPress = (
+  element: HTMLElement,
+  callback: (event: MouseEvent | TouchEvent) => void,
+  options: OnLongPressOptions = {},
+): (() => void) => {
+  const { duration = 500, threshold = 10 } = options;
+
+  let timeoutId: ReturnType<typeof setTimeout> | null = null;
+  let startX = 0;
+  let startY = 0;
+
+  const getPoint = (e: MouseEvent | TouchEvent) => ('touches' in e ? e.touches[0] : e);
+
+  const handleStart = markAsEventFunc((e: MouseEvent | TouchEvent) => {
+    const point = getPoint(e);
+    startX = point.clientX;
+    startY = point.clientY;
+
+    timeoutId = setTimeout(() => {
+      callback(e);
+    }, duration);
+  });
+
+  const handleMove = markAsEventFunc((e: MouseEvent | TouchEvent) => {
+    if (!timeoutId) return;
+
+    const point = getPoint(e);
+    const deltaX = Math.abs(point.clientX - startX);
+    const deltaY = Math.abs(point.clientY - startY);
+
+    if (deltaX > threshold || deltaY > threshold) {
+      handleEnd();
+    }
+  });
+
+  const handleEnd = markAsEventFunc(() => {
+    if (timeoutId) {
+      clearTimeout(timeoutId);
+      timeoutId = null;
+    }
+  });
+
+  const removeListeners = addEventsListener(element, {
+    mousedown: handleStart as EventListener,
+    mousemove: handleMove as EventListener,
+    mouseup: handleEnd,
+    mouseleave: handleEnd,
+    touchstart: handleStart as EventListener,
+    touchmove: handleMove as EventListener,
+    touchend: handleEnd,
+    touchcancel: handleEnd,
+  });
+
+  return () => {
+    removeListeners();
+    if (timeoutId) clearTimeout(timeoutId);
+  };
+};
+
+/**
+ * Attaches multiple event listeners to an element.
+ * @param element - The element to attach listeners to.
+ * @param events - An object mapping event types to handlers.
+ */
+export const addEventsListener = <E extends HTMLElement>(
+  element: E,
+  events: Partial<{
+    [K in Parameters<E['addEventListener']>[0]]: SingleOrArray<
+      Parameters<E['addEventListener']>[1]
+    >;
+  }>,
+  options?: AddEventListenerOptions,
+): (() => void) => {
+  const handlers: [eventName: string, eventHandlers: EventListener][] = [];
+
+  Object.entries(events).forEach(([eventKey, handler]) => {
+    if (!handler) return;
+    const event = eventKey;
+
+    if (Array.isArray(handler)) {
+      handler.forEach((h: EventListener) => {
+        element.addEventListener(event, h, options);
+        handlers.push([event, h]);
+      });
+    } else {
+      element.addEventListener(event, handler as EventListener, options);
+      handlers.push([event, handler as EventListener]);
+    }
+  });
+
+  return () => {
+    handlers.forEach(([event, handler]) => {
+      element.removeEventListener(event, handler, options);
+    });
+  };
+};

package/src/dom/index.ts

@@ -0,0 +1,5 @@
+export * from './element';
+export * from './events';
+export * from './observer';
+export * from './style';
+export * from './win';

package/src/dom/observer.ts

@@ -0,0 +1,197 @@
+/**
+ * Options for waitForElement function.
+ */
+export interface WaitForElementOptions {
+  /** Maximum time to wait in milliseconds. Default: 5000 */
+  timeout?: number;
+  /** Root element to observe. Default: document.body */
+  root?: HTMLElement;
+  /** Check interval in milliseconds. Default: 100 */
+  interval?: number;
+}
+
+/**
+ * Waits for an element matching the selector to appear in the DOM.
+ * @param selector - CSS selector to match.
+ * @param options - Configuration options.
+ * @returns A promise that resolves with the element when found.
+ */
+export const waitForElement = <T extends HTMLElement = HTMLElement>(
+  selector: string,
+  options: WaitForElementOptions = {},
+): Promise<T> => {
+  const { timeout = 5000, root = document.body, interval = 100 } = options;
+
+  return new Promise((resolve, reject) => {
+    // Check if element already exists
+    const existingElement = root.querySelector<T>(selector);
+    if (existingElement) {
+      resolve(existingElement);
+      return;
+    }
+
+    // Use MutationObserver for efficient detection
+    const observer = new MutationObserver(() => {
+      const element = root.querySelector<T>(selector);
+      if (element) {
+        cleanup();
+        resolve(element);
+      }
+    });
+
+    observer.observe(root, {
+      childList: true,
+      subtree: true,
+    });
+
+    // Fallback interval check
+    const intervalId = setInterval(() => {
+      const element = root.querySelector<T>(selector);
+      if (element) {
+        cleanup();
+        resolve(element);
+      }
+    }, interval);
+
+    // Timeout handler
+    const timeoutId = setTimeout(() => {
+      cleanup();
+      reject(new Error(`Timeout: Element "${selector}" not found within ${timeout}ms`));
+    }, timeout);
+
+    const cleanup = () => {
+      observer.disconnect();
+      clearTimeout(timeoutId);
+      clearInterval(intervalId);
+    };
+  });
+};
+
+/**
+ * Options for watchElementRemoval function.
+ */
+export interface WatchElementRemovalOptions {
+  /** Callback to invoke when the element is removed */
+  onRemove?: () => void;
+  /** Root element to observe. Default: document.body */
+  root?: HTMLElement;
+}
+
+/**
+ * Watches for an element to be removed from the DOM.
+ * @param element - The element to watch.
+ * @param options - Configuration options.
+ * @returns A function to stop watching.
+ */
+export const watchElementRemoval = (
+  element: HTMLElement,
+  options: WatchElementRemovalOptions = {},
+): (() => void) => {
+  const { onRemove, root = document.body } = options;
+
+  const observer = new MutationObserver(() => {
+    if (!root.contains(element)) {
+      onRemove?.();
+      observer.disconnect();
+    }
+  });
+
+  observer.observe(root, {
+    childList: true,
+    subtree: true,
+  });
+
+  return () => observer.disconnect();
+};
+
+/**
+ * Returns a promise that resolves when the element is removed from the DOM.
+ * @param element - The element to watch.
+ * @param options - Configuration options.
+ * @returns A promise that resolves when the element is removed.
+ */
+export const waitForElementRemoval = (
+  element: HTMLElement,
+  options: { root?: HTMLElement; timeout?: number } = {},
+): Promise<void> => {
+  const { root = document.body, timeout } = options;
+
+  return new Promise((resolve, reject) => {
+    // Check if element is already removed
+    if (!root.contains(element)) {
+      resolve();
+      return;
+    }
+
+    let timeoutId: ReturnType<typeof setTimeout> | undefined;
+
+    const observer = new MutationObserver(() => {
+      if (!root.contains(element)) {
+        cleanup();
+        resolve();
+      }
+    });
+
+    observer.observe(root, {
+      childList: true,
+      subtree: true,
+    });
+
+    if (timeout) {
+      timeoutId = setTimeout(() => {
+        cleanup();
+        reject(new Error(`Timeout: Element not removed within ${timeout}ms`));
+      }, timeout);
+    }
+
+    const cleanup = () => {
+      observer.disconnect();
+      if (timeoutId) clearTimeout(timeoutId);
+    };
+  });
+};
+
+/**
+ * Options for watchElementChanges function.
+ */
+export interface WatchElementChangesOptions {
+  /** Watch for attribute changes. Default: true */
+  attributes?: boolean;
+  /** Watch for child node changes. Default: true */
+  childList?: boolean;
+  /** Watch for text content changes. Default: false */
+  characterData?: boolean;
+  /** Watch subtree. Default: false */
+  subtree?: boolean;
+  /** Callback for mutations */
+  onMutation?: (mutations: MutationRecord[]) => void;
+}
+
+/**
+ * Watches for changes to an element and its descendants.
+ * @param element - The element to watch.
+ * @param options - Configuration options.
+ * @returns A function to stop watching.
+ */
+export const watchElementChanges = (
+  element: HTMLElement,
+  options: WatchElementChangesOptions = {},
+): (() => void) => {
+  const {
+    attributes = true,
+    childList = true,
+    characterData = false,
+    subtree = false,
+    onMutation,
+  } = options;
+
+  const observer = new MutationObserver((mutations) => onMutation?.(mutations));
+  observer.observe(element, {
+    attributes,
+    childList,
+    characterData,
+    subtree,
+  });
+
+  return () => observer.disconnect();
+};