@mkmonkeycat/dom-utils 0.1.0 → 1.0.0

package/src/dom/events.ts

@@ -1,245 +0,0 @@
-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

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

package/src/dom/observer.ts

@@ -1,197 +0,0 @@
-/**
- * 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();
-};

package/src/dom/style.ts

@@ -1,23 +0,0 @@
-/**
- * Injects a <style> tag with the provided CSS into the document.
- * @param css - The CSS text to inject.
- * @param options - Optional configuration such as `id`, `nonce`, and target container.
- * @returns An object containing the created style element and a `remove` function.
- */
-export const injectStyle = (
-  css: string,
-  options: { id?: string; nonce?: string; target?: HTMLElement } = {},
-): { style: HTMLStyleElement; remove: () => void } => {
-  const { id, nonce, target = document.head } = options;
-  const style = document.createElement('style');
-  if (id) style.id = id;
-  if (nonce) style.setAttribute('nonce', nonce);
-  style.textContent = css;
-  target.appendChild(style);
-
-  const remove = () => {
-    style.parentNode?.removeChild(style);
-  };
-
-  return { style, remove };
-};

package/src/dom/tag-internal.ts

@@ -1,19 +0,0 @@
-import { isMarkedAs, markFunc, type TaggedFunction } from '../utils/tag';
-
-/**
- * Marks a function as an mk utils internal event handler.
- * @param func - The function to mark.
- * @returns The marked function.
- */
-export const markAsEventFunc = <F extends CallableFunction>(
-  func: F,
-): TaggedFunction<F, '__mkEvent'> => markFunc(func, '__mkEvent');
-
-/**
- * Checks if a function is marked as an mk utils internal event handler.
- * @param func - The function to check.
- * @returns True if the function is marked as an event handler, false otherwise.
- */
-export const isEventFunc = <F extends CallableFunction>(
-  func: F,
-): func is TaggedFunction<F, '__mkEvent'> => isMarkedAs(func, '__mkEvent');

package/src/dom/win.ts

@@ -1,21 +0,0 @@
-export const globalWin: Win = typeof unsafeWindow !== 'undefined' ? unsafeWindow : window;
-export const globalDoc: Document = globalWin.document;
-
-export function getWin(): Win;
-export function getWin(
-  target: Node | Event | ShadowRoot | Document | Window | null | undefined,
-): Win | null;
-export function getWin(target?: Node | Event | ShadowRoot | Document | Window | null): Win | null {
-  if (!target) return globalWin;
-
-  if (target instanceof Window) return target as Win;
-  if (target instanceof UIEvent && target.view) return target.view as Win;
-  if (target instanceof Document) return target.defaultView;
-  if (target instanceof ShadowRoot) return target.host.ownerDocument?.defaultView ?? null;
-  if (target instanceof Node) return target.ownerDocument?.defaultView ?? null;
-
-  return null;
-}
-
-export type Win = Window & typeof globalThis;
-declare const unsafeWindow: Win | undefined;

package/src/index.ts

@@ -1,4 +0,0 @@
-export const VERSION = '0.0.1';
-
-export * from './dom';
-export * from './utils';

package/src/utils/index.ts

@@ -1,4 +0,0 @@
-export * from './string';
-export * from './tag';
-export * from './timing';
-export * from './types';

package/src/utils/string.ts

@@ -1,17 +0,0 @@
-/**
- * Converts a camelCase string to kebab-case.
- * @param str - The camelCase string to convert.
- * @returns The kebab-case string.
- */
-export const camelToKebab = (str: string): string => {
-  return str.replace(/([a-z0-9]|(?=[A-Z]))([A-Z])/g, '$1-$2').toLowerCase();
-};
-
-/**
- * Converts a PascalCase string to kebab-case.
- * @param str - The PascalCase string to convert.
- * @returns The kebab-case string.
- */
-export const pascalToKebab = (str: string): string => {
-  return str.replace(/([a-z0-9]|(?=[A-Z]))([A-Z])/g, '$1-$2').toLowerCase();
-};

package/src/utils/tag.ts

@@ -1,31 +0,0 @@
-/**
- * Type representing a function tagged with a specific string.
- */
-export type TaggedFunction<F extends CallableFunction, T extends string> = F & {
-  readonly [K in T]?: true;
-};
-
-/**
- * Marks a function with a specific tag.
- * @param func - The function to mark.
- * @param tag - The tag to assign.
- * @returns The marked function.
- */
-export const markFunc = <F extends CallableFunction, T extends string>(
-  func: F,
-  tag: T,
-): TaggedFunction<F, T> => {
-  Object.defineProperty(func, tag, { value: true });
-  return func as TaggedFunction<F, T>;
-};
-
-/**
- * Checks if a function is marked with a specific tag.
- * @param func - The function to check.
- * @param tag - The tag to look for.
- * @returns True if the function is marked with the tag, false otherwise.
- */
-export const isMarkedAs = <F extends CallableFunction, T extends string>(
-  func: F,
-  tag: T,
-): func is TaggedFunction<F, T> => !!(func as Record<string, unknown>)[tag];