elementdrawing 1.0.0

package/src/js/dom.js

@@ -0,0 +1,665 @@
+/**
+ * DOM Manipulation Utilities
+ * ElementDrawing Framework - Comprehensive DOM querying, creation,
+ * manipulation, CSS, attributes, dimensions, visibility, and animation helpers.
+ */
+
+'use strict';
+
+// ─── Query Selectors ──────────────────────────────────────────────────────────
+
+/**
+ * Select a single element by ID.
+ * @param {string} id
+ * @param {Document|HTMLElement} [context=document]
+ * @returns {HTMLElement|null}
+ */
+function byId(id, context) {
+  return (context || document).getElementById(id);
+}
+
+/**
+ * Select elements by class name.
+ * @param {string} className
+ * @param {Document|HTMLElement} [context=document]
+ * @returns {HTMLCollection}
+ */
+function byClass(className, context) {
+  return (context || document).getElementsByClassName(className);
+}
+
+/**
+ * Select elements by tag name.
+ * @param {string} tagName
+ * @param {Document|HTMLElement} [context=document]
+ * @returns {HTMLCollection}
+ */
+function byTag(tagName, context) {
+  return (context || document).getElementsByTagName(tagName);
+}
+
+/**
+ * Select the first element matching a CSS selector.
+ * @param {string} selector
+ * @param {Document|HTMLElement} [context=document]
+ * @returns {HTMLElement|null}
+ */
+function query(selector, context) {
+  return (context || document).querySelector(selector);
+}
+
+/**
+ * Select all elements matching a CSS selector.
+ * @param {string} selector
+ * @param {Document|HTMLElement} [context=document]
+ * @returns {NodeList}
+ */
+function queryAll(selector, context) {
+  return (context || document).querySelectorAll(selector);
+}
+
+// ─── DOM Creation ─────────────────────────────────────────────────────────────
+
+/**
+ * Create an HTML element with optional attributes and children.
+ * @param {string} tagName
+ * @param {Object} [attrs]
+ * @param {...(string|HTMLElement)} children
+ * @returns {HTMLElement}
+ */
+function createElement(tagName, attrs) {
+  const el = document.createElement(tagName);
+
+  if (attrs) {
+    Object.keys(attrs).forEach((key) => {
+      const value = attrs[key];
+      if (key === 'className' || key === 'class') {
+        el.className = value;
+      } else if (key === 'style' && typeof value === 'object') {
+        Object.assign(el.style, value);
+      } else if (key === 'style' && typeof value === 'string') {
+        el.style.cssText = value;
+      } else if (key.startsWith('data-')) {
+        el.setAttribute(key, value);
+      } else if (key.startsWith('on') && typeof value === 'function') {
+        const eventType = key.slice(2).toLowerCase();
+        el.addEventListener(eventType, value);
+      } else if (typeof value === 'boolean') {
+        if (value) el.setAttribute(key, '');
+        else el.removeAttribute(key);
+      } else {
+        el.setAttribute(key, value);
+      }
+    });
+  }
+
+  const childArgs = Array.prototype.slice.call(arguments, 2);
+  childArgs.forEach((child) => {
+    if (typeof child === 'string' || typeof child === 'number') {
+      el.appendChild(document.createTextNode(String(child)));
+    } else if (child instanceof HTMLElement || child instanceof DocumentFragment) {
+      el.appendChild(child);
+    }
+  });
+
+  return el;
+}
+
+/**
+ * Create a document fragment.
+ * @returns {DocumentFragment}
+ */
+function createFragment() {
+  return document.createDocumentFragment();
+}
+
+/**
+ * Create a text node.
+ * @param {string} text
+ * @returns {Text}
+ */
+function createTextNode(text) {
+  return document.createTextNode(text);
+}
+
+// ─── DOM Manipulation ─────────────────────────────────────────────────────────
+
+/**
+ * Append a child to a parent element.
+ * @param {HTMLElement} parent
+ * @param {HTMLElement|DocumentFragment|string} child
+ * @returns {HTMLElement}
+ */
+function append(parent, child) {
+  if (typeof child === 'string') {
+    parent.insertAdjacentHTML('beforeend', child);
+  } else {
+    parent.appendChild(child);
+  }
+  return parent;
+}
+
+/**
+ * Prepend a child to a parent element.
+ * @param {HTMLElement} parent
+ * @param {HTMLElement|DocumentFragment|string} child
+ * @returns {HTMLElement}
+ */
+function prepend(parent, child) {
+  if (typeof child === 'string') {
+    parent.insertAdjacentHTML('afterbegin', child);
+  } else {
+    parent.insertBefore(child, parent.firstChild);
+  }
+  return parent;
+}
+
+/**
+ * Insert a node before a reference node.
+ * @param {HTMLElement} newNode
+ * @param {HTMLElement} referenceNode
+ * @returns {HTMLElement}
+ */
+function insertBefore(newNode, referenceNode) {
+  if (referenceNode.parentNode) {
+    referenceNode.parentNode.insertBefore(newNode, referenceNode);
+  }
+  return newNode;
+}
+
+/**
+ * Remove an element from the DOM.
+ * @param {HTMLElement} el
+ * @returns {HTMLElement}
+ */
+function remove(el) {
+  if (el && el.parentNode) {
+    el.parentNode.removeChild(el);
+  }
+  return el;
+}
+
+/**
+ * Replace an old element with a new one.
+ * @param {HTMLElement} oldEl
+ * @param {HTMLElement} newEl
+ * @returns {HTMLElement}
+ */
+function replace(oldEl, newEl) {
+  if (oldEl.parentNode) {
+    oldEl.parentNode.replaceChild(newEl, oldEl);
+  }
+  return newEl;
+}
+
+/**
+ * Clone an element.
+ * @param {HTMLElement} el
+ * @param {boolean} [deep=true]
+ * @returns {HTMLElement}
+ */
+function clone(el, deep) {
+  return el.cloneNode(deep !== false);
+}
+
+/**
+ * Remove all children from an element.
+ * @param {HTMLElement} el
+ * @returns {HTMLElement}
+ */
+function empty(el) {
+  while (el.firstChild) {
+    el.removeChild(el.firstChild);
+  }
+  return el;
+}
+
+/**
+ * Wrap an element with a wrapper element.
+ * @param {HTMLElement} el
+ * @param {HTMLElement} wrapper
+ * @returns {HTMLElement}
+ */
+function wrap(el, wrapper) {
+  if (el.parentNode) {
+    el.parentNode.insertBefore(wrapper, el);
+  }
+  wrapper.appendChild(el);
+  return wrapper;
+}
+
+/**
+ * Unwrap an element (remove its parent, keeping the element).
+ * @param {HTMLElement} el
+ * @returns {HTMLElement}
+ */
+function unwrap(el) {
+  const parent = el.parentNode;
+  if (!parent) return el;
+
+  while (el.firstChild) {
+    parent.insertBefore(el.firstChild, el);
+  }
+  parent.removeChild(el);
+  return parent;
+}
+
+// ─── CSS Manipulation ─────────────────────────────────────────────────────────
+
+/**
+ * Add one or more CSS classes to an element.
+ * @param {HTMLElement} el
+ * @param {...string} classes
+ * @returns {HTMLElement}
+ */
+function addClass(el) {
+  const classes = Array.prototype.slice.call(arguments, 1);
+  el.classList.add.apply(el.classList, classes);
+  return el;
+}
+
+/**
+ * Remove one or more CSS classes from an element.
+ * @param {HTMLElement} el
+ * @param {...string} classes
+ * @returns {HTMLElement}
+ */
+function removeClass(el) {
+  const classes = Array.prototype.slice.call(arguments, 1);
+  el.classList.remove.apply(el.classList, classes);
+  return el;
+}
+
+/**
+ * Toggle a CSS class on an element.
+ * @param {HTMLElement} el
+ * @param {string} className
+ * @param {boolean} [force]
+ * @returns {HTMLElement}
+ */
+function toggleClass(el, className, force) {
+  el.classList.toggle(className, force);
+  return el;
+}
+
+/**
+ * Check if an element has a CSS class.
+ * @param {HTMLElement} el
+ * @param {string} className
+ * @returns {boolean}
+ */
+function hasClass(el, className) {
+  return el.classList.contains(className);
+}
+
+/**
+ * Set an inline style property on an element.
+ * @param {HTMLElement} el
+ * @param {string|Object} prop - CSS property name or style object
+ * @param {string} [value] - CSS value (if prop is a string)
+ * @returns {HTMLElement}
+ */
+function setStyle(el, prop, value) {
+  if (typeof prop === 'object') {
+    Object.keys(prop).forEach((key) => {
+      el.style[key] = prop[key];
+    });
+  } else {
+    el.style[prop] = value;
+  }
+  return el;
+}
+
+/**
+ * Get a computed style value for an element.
+ * @param {HTMLElement} el
+ * @param {string} prop
+ * @returns {string}
+ */
+function getStyle(el, prop) {
+  return window.getComputedStyle(el).getPropertyValue(prop);
+}
+
+/**
+ * Get all computed styles for an element.
+ * @param {HTMLElement} el
+ * @returns {CSSStyleDeclaration}
+ */
+function getComputedStyle(el) {
+  return window.getComputedStyle(el);
+}
+
+// ─── Attribute Manipulation ───────────────────────────────────────────────────
+
+/**
+ * Set an attribute on an element.
+ * @param {HTMLElement} el
+ * @param {string} name
+ * @param {string} value
+ * @returns {HTMLElement}
+ */
+function setAttribute(el, name, value) {
+  el.setAttribute(name, value);
+  return el;
+}
+
+/**
+ * Get an attribute value from an element.
+ * @param {HTMLElement} el
+ * @param {string} name
+ * @returns {string|null}
+ */
+function getAttribute(el, name) {
+  return el.getAttribute(name);
+}
+
+/**
+ * Remove an attribute from an element.
+ * @param {HTMLElement} el
+ * @param {string} name
+ * @returns {HTMLElement}
+ */
+function removeAttribute(el, name) {
+  el.removeAttribute(name);
+  return el;
+}
+
+/**
+ * Set a data attribute on an element.
+ * @param {HTMLElement} el
+ * @param {string} key
+ * @param {*} value
+ * @returns {HTMLElement}
+ */
+function setData(el, key, value) {
+  el.dataset[key] = value;
+  return el;
+}
+
+/**
+ * Get a data attribute from an element.
+ * @param {HTMLElement} el
+ * @param {string} key
+ * @returns {string|undefined}
+ */
+function getData(el, key) {
+  return el.dataset[key];
+}
+
+// ─── Dimension Utilities ──────────────────────────────────────────────────────
+
+/**
+ * Get the width of an element (content + padding + border).
+ * @param {HTMLElement} el
+ * @returns {number}
+ */
+function getWidth(el) {
+  return el.offsetWidth;
+}
+
+/**
+ * Get the height of an element (content + padding + border).
+ * @param {HTMLElement} el
+ * @returns {number}
+ */
+function getHeight(el) {
+  return el.offsetHeight;
+}
+
+/**
+ * Get the offset position of an element relative to the document.
+ * @param {HTMLElement} el
+ * @returns {{ top: number, left: number }}
+ */
+function getOffset(el) {
+  const rect = el.getBoundingClientRect();
+  return {
+    top: rect.top + window.pageYOffset,
+    left: rect.left + window.pageXOffset,
+  };
+}
+
+/**
+ * Get the position of an element relative to its offset parent.
+ * @param {HTMLElement} el
+ * @returns {{ top: number, left: number }}
+ */
+function getPosition(el) {
+  return {
+    top: el.offsetTop,
+    left: el.offsetLeft,
+  };
+}
+
+/**
+ * Get scroll information for an element.
+ * @param {HTMLElement} [el=window]
+ * @returns {{ top: number, left: number, width: number, height: number }}
+ */
+function getScroll(el) {
+  if (!el || el === window) {
+    return {
+      top: window.pageYOffset || document.documentElement.scrollTop,
+      left: window.pageXOffset || document.documentElement.scrollLeft,
+      width: document.documentElement.scrollWidth,
+      height: document.documentElement.scrollHeight,
+    };
+  }
+  return {
+    top: el.scrollTop,
+    left: el.scrollLeft,
+    width: el.scrollWidth,
+    height: el.scrollHeight,
+  };
+}
+
+/**
+ * Get viewport dimensions.
+ * @returns {{ width: number, height: number }}
+ */
+function getViewport() {
+  return {
+    width: window.innerWidth || document.documentElement.clientWidth,
+    height: window.innerHeight || document.documentElement.clientHeight,
+  };
+}
+
+/**
+ * Get the bounding client rect of an element.
+ * @param {HTMLElement} el
+ * @returns {DOMRect}
+ */
+function getRect(el) {
+  return el.getBoundingClientRect();
+}
+
+// ─── Visibility ───────────────────────────────────────────────────────────────
+
+/**
+ * Show a hidden element.
+ * @param {HTMLElement} el
+ * @param {string} [display='']
+ * @returns {HTMLElement}
+ */
+function show(el, display) {
+  el.style.display = display || '';
+  return el;
+}
+
+/**
+ * Hide an element.
+ * @param {HTMLElement} el
+ * @returns {HTMLElement}
+ */
+function hide(el) {
+  el.style.display = 'none';
+  return el;
+}
+
+/**
+ * Toggle element visibility.
+ * @param {HTMLElement} el
+ * @returns {HTMLElement}
+ */
+function toggle(el) {
+  if (el.style.display === 'none') {
+    show(el);
+  } else {
+    hide(el);
+  }
+  return el;
+}
+
+/**
+ * Check if an element is visible (not display:none or visibility:hidden).
+ * @param {HTMLElement} el
+ * @returns {boolean}
+ */
+function isVisible(el) {
+  if (el.offsetWidth === 0 && el.offsetHeight === 0) return false;
+  const style = window.getComputedStyle(el);
+  return style.display !== 'none' && style.visibility !== 'hidden' && style.opacity !== '0';
+}
+
+/**
+ * Check if an element is within the viewport.
+ * @param {HTMLElement} el
+ * @param {number} [threshold=0]
+ * @returns {boolean}
+ */
+function isInViewport(el, threshold) {
+  threshold = threshold || 0;
+  const rect = el.getBoundingClientRect();
+  const vp = getViewport();
+
+  return (
+    rect.top >= -threshold &&
+    rect.left >= -threshold &&
+    rect.bottom <= vp.height + threshold &&
+    rect.right <= vp.width + threshold
+  );
+}
+
+// ─── Animation Helpers ────────────────────────────────────────────────────────
+
+/**
+ * Animate an element using the Web Animations API or CSS transitions.
+ * @param {HTMLElement} el
+ * @param {Object} keyframes
+ * @param {Object} [options]
+ * @returns {Promise}
+ */
+function animate(el, keyframes, options) {
+  if (el.animate && typeof el.animate === 'function') {
+    return el.animate(keyframes, options).finished;
+  }
+
+  // Fallback: apply final state immediately
+  return new Promise((resolve) => {
+    Object.keys(keyframes).forEach((prop) => {
+      const value = Array.isArray(keyframes[prop])
+        ? keyframes[prop][keyframes[prop].length - 1]
+        : keyframes[prop];
+      el.style[prop] = value;
+    });
+    requestAnimationFrame(() => resolve(el));
+  });
+}
+
+/**
+ * Fade in an element.
+ * @param {HTMLElement} el
+ * @param {number} [duration=300]
+ * @returns {Promise}
+ */
+function fadeIn(el, duration) {
+  duration = duration || 300;
+  el.style.opacity = '0';
+  el.style.display = '';
+  return animate(el, { opacity: [0, 1] }, { duration, fill: 'forwards' });
+}
+
+/**
+ * Fade out an element.
+ * @param {HTMLElement} el
+ * @param {number} [duration=300]
+ * @returns {Promise}
+ */
+function fadeOut(el, duration) {
+  duration = duration || 300;
+  return animate(el, { opacity: [1, 0] }, { duration, fill: 'forwards' }).then(() => {
+    el.style.display = 'none';
+    return el;
+  });
+}
+
+/**
+ * Slide up (collapse) an element.
+ * @param {HTMLElement} el
+ * @param {number} [duration=300]
+ * @returns {Promise}
+ */
+function slideUp(el, duration) {
+  duration = duration || 300;
+  const height = el.offsetHeight;
+  return animate(el, {
+    height: [height + 'px', '0px'],
+    overflow: ['hidden', 'hidden'],
+  }, { duration, fill: 'forwards' }).then(() => {
+    el.style.display = 'none';
+    return el;
+  });
+}
+
+/**
+ * Slide down (expand) an element.
+ * @param {HTMLElement} el
+ * @param {number} [duration=300]
+ * @returns {Promise}
+ */
+function slideDown(el, duration) {
+  duration = duration || 300;
+  el.style.display = '';
+  el.style.overflow = 'hidden';
+  const height = el.scrollHeight;
+  el.style.height = '0px';
+  return animate(el, { height: ['0px', height + 'px'] }, { duration, fill: 'forwards' }).then(() => {
+    el.style.height = '';
+    el.style.overflow = '';
+    return el;
+  });
+}
+
+/**
+ * Toggle slide up/down.
+ * @param {HTMLElement} el
+ * @param {number} [duration=300]
+ * @returns {Promise}
+ */
+function slideToggle(el, duration) {
+  if (el.style.display === 'none' || el.offsetHeight === 0) {
+    return slideDown(el, duration);
+  }
+  return slideUp(el, duration);
+}
+
+// ─── Exports ──────────────────────────────────────────────────────────────────
+
+module.exports = {
+  // Query selectors
+  byId, byClass, byTag, query, queryAll,
+  // DOM creation
+  createElement, createFragment, createTextNode,
+  // DOM manipulation
+  append, prepend, insertBefore, remove, replace, clone, empty, wrap, unwrap,
+  // CSS manipulation
+  addClass, removeClass, toggleClass, hasClass, setStyle, getStyle, getComputedStyle,
+  // Attribute manipulation
+  setAttribute, getAttribute, removeAttribute, setData, getData,
+  // Dimension utilities
+  getWidth, getHeight, getOffset, getPosition, getScroll, getViewport, getRect,
+  // Visibility
+  show, hide, toggle, isVisible, isInViewport,
+  // Animation helpers
+  animate, fadeIn, fadeOut, slideUp, slideDown, slideToggle,
+};