@webalternatif/js-core 1.6.3 → 1.6.4

package/dist/esm/dom.js

@@ -4,82 +4,74 @@ function _unsupportedIterableToArray(r, a) { if (r) { if ("string" == typeof r)
 function _iterableToArray(r) { if ("undefined" != typeof Symbol && null != r[Symbol.iterator] || null != r["@@iterator"]) return Array.from(r); }
 function _arrayWithoutHoles(r) { if (Array.isArray(r)) return _arrayLikeToArray(r); }
 function _arrayLikeToArray(r, a) { (null == a || a > r.length) && (a = r.length); for (var e = 0, n = Array(a); e < a; e++) n[e] = r[e]; return n; }
-import { isArray, isArrayLike, isObject, isPlainObject, isString } from './is.js';
+import { isArray, isArrayLike, isDocument, isFunction, isPlainObject, isString, isWindow } from './is.js';
 import { camelCase } from './string.js';
 import { each, foreach, map } from './traversal.js';
 import { inArray } from './array.js';
 import { on, off, __resetCustomEventsForTests } from './onOff.js';
 var cssNumber = ['animationIterationCount', 'aspectRatio', 'borderImageSlice', 'columnCount', 'flexGrow', 'flexShrink', 'fontWeight', 'gridArea', 'gridColumn', 'gridColumnEnd', 'gridColumnStart', 'gridRow', 'gridRowEnd', 'gridRowStart', 'lineHeight', 'opacity', 'order', 'orphans', 'scale', 'widows', 'zIndex', 'zoom', 'fillOpacity', 'floodOpacity', 'stopOpacity', 'strokeMiterlimit', 'strokeOpacity'];
-
-/**
- * @param {any} o
- * @returns {boolean}
- */
-export var isWindow = function isWindow(o) {
-  return !!o && o === o.window;
-};
-
-/**
- * @param {any} o
- * @returns {boolean}
- */
-export var isDocument = function isDocument(o) {
-  return !!o && o.nodeType === 9;
-};
-
-/**
- * @param {any} o
- * @returns {boolean}
- */
-export var isDomElement = function isDomElement(o) {
-  return isObject(o) && o instanceof HTMLElement;
-};
-
-/**
- * @param {Element} el
- * @param {string} cssRule
- * @returns {string}
- */
-export var getStyle = function getStyle(el, cssRule) {
-  if (!isDomElement(el)) {
-    return '';
-  }
-  if (window.getComputedStyle) {
-    var computedStyle = window.getComputedStyle(el, null);
-    return computedStyle.getPropertyValue(cssRule) || computedStyle[camelCase(cssRule)] || '';
-  }
-  return el.style[camelCase(cssRule)] || '';
-};
 var dom = {
   /**
-   * @param {Element} el
-   * @param {string} [selector]
-   * @returns {NodeList|Element[]}
+   * Returns the direct children of an element.
+   * If a selector is provided, only children matching the selector are returned.
+   *
+   * @example
+   * // <ul id="list"><li class="a"></li><li class="b"></li></ul>
+   * const list = document.getElementById('list')
+   *
+   * dom.children(list) // [[<li class="a">], [<li class="b">]]
+   * dom.children(list, '.a') // [<li class="a">]
+   *
+   * @param {Element} el - Parent element
+   * @param {string} [selector] - Optional CSS selector to filter direct children
+   * @returns {Element[]} Direct children, optionally filtered
    */
   children: function children(el, selector) {
-    return selector ? this.find(el, ":scope > ".concat(selector)) : el.children;
+    return selector ? this.find(el, ":scope > ".concat(selector)) : Array.from(el.children);
   },
   /**
-   * @param {Element} el
-   * @param {string} [selector]
-   * @returns {Element|null}
+   * Returns the first direct child of an element matching `selector`.
+   *
+   * @example
+   * // <ul id="list"><li class="a"></li><li class="b"></li></ul>
+   * const list = document.getElementById('list')
+   *
+   * dom.child(list) // <li class="a">
+   * dom.child(list, '.b') // <li class="b">
+   * dom.child(list, '.c') // null
+   *
+   * @param {Element} el - Parent element
+   * @param {string} [selector] - Optional CSS selector to filter direct children
+   * @returns {Element|null} - The first matching direct child, or null if none found
    */
   child: function child(el, selector) {
     return this.first(this.children(el, selector));
   },
   /**
-   * @param {Element|Document|string} refEl
-   * @param {string|Element|NodeList|Array<Element>} [selector]
-   * @returns {Element}
-   */
-  findOne: function findOne(refEl, selector) {
-    var _this$find$;
-    return (_this$find$ = this.find(refEl, selector)[0]) !== null && _this$find$ !== void 0 ? _this$find$ : null;
-  },
-  /**
-   * @param {Element|Document|string} refEl
-   * @param {string|Element|NodeList|Array<Element>} [selector]
-   * @returns {Element[]}
+   * Finds elements based on a selector or a collection
+   *
+   * If only one argument is provided, the search is performed from `document`.
+   *
+   * The `selector` can be:
+   * - a CSS selector string
+   * - a single Element
+   * - a NodeList or array-like collection of Elements
+   *
+   * @example
+   * dom.find('.item') // All elements matching .item in document
+   *
+   * const container = document.getElementById('box')
+   * dom.find(container, '.item') // All .item inside #box
+   *
+   * const el = document.querySelector('.item')
+   * dom.find(container, el) // [el] if inside container, otherwise []
+   *
+   * const list = document.querySelectorAll('.item')
+   * dom.find(container, list) // Only those inside container
+   *
+   * @param {Element|Document|DocumentFragment|string} refEl - Reference element or selector (if used alone)
+   * @param {string|Element|NodeList|Array<Element>} [selector] - What to find
+   * @returns {Element[]} - An array of matched elements
    */
   find: function find(refEl, selector) {
     if (undefined === selector) {
@@ -104,29 +96,80 @@ var dom = {
     }
   },
   /**
-   * @param {Element|string} el
-   * @param {string} data
-   * @param {string} [value]
-   * @returns {Element|null}
+   * Finds the first element matching a selector or collection.
+   *
+   * Behaves like `dom.find` but returns only the first matched element.
+   * Returns `null` if no element matches.
+   *
+   * @param {Element|Document|DocumentFragment|string} refEl - Reference element or selector (if used alone)
+   * @param {string|Element|NodeList|Array<Element>} [selector] - What to find
+   * @returns {Element|null} - The first matched Element, or null if none found
    */
-  findOneByData: function findOneByData(el, data, value) {
-    var _this$findByData$;
-    return (_this$findByData$ = this.findByData(el, data, value)[0]) !== null && _this$findByData$ !== void 0 ? _this$findByData$ : null;
+  findOne: function findOne(refEl, selector) {
+    var _this$find$;
+    return (_this$find$ = this.find(refEl, selector)[0]) !== null && _this$find$ !== void 0 ? _this$find$ : null;
   },
   /**
-   * @param {Element|string} el
-   * @param {string} data
-   * @param {string} [value]
-   * @returns {Element[]}
+   * Finds elements by a data-* attribute.
+   *
+   * If `value` is provided, only elements with an exact matching value are returned.
+   * If `value` is omitted, all elements having the data attribute are returned.
+   *
+   * @example
+   * // <div data-user-id="42"></div>
+   *
+   * dom.findByData(document, 'user-id') // all elements with [data-user-id]
+   * dom.findByData(document, 'user-id', '42') // elements with [data-user-id="42"]
+   *
+   * @param {Element|Document|string} el - Reference element or selector (if used alone)
+   * @param {string} data - The data-* key without the "data-" prefix
+   * @param {string} [value] - Optional value to match exactly
+   * @returns {Element[]} - Matching elements
    */
   findByData: function findByData(el, data, value) {
-    var escapeValue = CSS.escape(value);
+    if (undefined === value) return this.find(el, "[data-".concat(data, "]"));
+    var escapeValue = CSS.escape(value + '');
     return this.find(el, "[data-".concat(data, "=\"").concat(escapeValue, "\"]"));
   },
   /**
-   * @param {Element|NodeList|Array<Element>} el
-   * @param {string} className
-   * @returns {Element|NodeList|Array<Element>}
+   * Finds the first element matching a data-* attribute.
+   *
+   * If `value` is provided, returns the first element whose data attribute
+   * exactly matches the given value. If omitted, returns the first element
+   * that has the data attribute.
+   *
+   * @example
+   * // <div data-user-id="42"></div>
+   *
+   * dom.findOneByData(document, 'user-id') // first element with [data-user-id]
+   * dom.findOneByData(document, 'user-id', '42') // element with [data-user-id="42"]
+   * dom.findOneByData(document, 'user-id', '99') // null
+   *
+   * @param {Element|Document|string} el - Reference element or selector (if used alone)
+   * @param {string} data - The data-* key without the "data-" prefix
+   * @param {string} [value] - Optional value to match exactly
+   * @returns {Element|null} The first matching element, or null if none found
+   */
+  findOneByData: function findOneByData(el, data, value) {
+    var _this$findByData$;
+    return (_this$findByData$ = this.findByData(el, data, value)[0]) !== null && _this$findByData$ !== void 0 ? _this$findByData$ : null;
+  },
+  /**
+   * Adds one or more CSS classes to one or multiple elements.
+   *
+   * Multiple classes can be provided as a space-separated string.
+   * Accepts a single Element, a NodeList, or an array of Elements.
+   *
+   * @example
+   * const el = document.querySelector('#box')
+   * dom.addClass(el, 'active')
+   *
+   * const items = document.querySelectorAll('.item')
+   * dom.addClass(items, 'selected active')
+   *
+   * @param {Element|NodeList|Element[]} el - Element(s) to update
+   * @param {string} className - One or more class names separated by spaces
+   * @returns {Element|NodeList|Element[]} The original input
    */
   addClass: function addClass(el, className) {
     if (!className) return el;
@@ -143,12 +186,24 @@ var dom = {
     return el;
   },
   /**
-   * @param {Element|NodeList|Array<Element>} el
-   * @param {string} className
-   * @returns {Element|NodeList|Array<Element>}
+   * Removes one or more CSS classes from one or multiple elements.
+   *
+   * Multiple classes can be provided as a space-separated string.
+   * Accepts a single Element, a NodeList, or an array of Elements.
+   *
+   * @example
+   * const el = document.querySelector('#box')
+   * dom.removeClass(el, 'active')
+   *
+   * const items = document.querySelectorAll('.item')
+   * dom.removeClass(items, 'selected highlighted')
+   *
+   * @param {Element|NodeList|Array<Element>} el - Element(s) to update
+   * @param {string} className - One or more class names separated by spaces
+   * @returns {Element|NodeList|Array<Element>} The original input
    */
   removeClass: function removeClass(el, className) {
-    if (!className) return;
+    if (!className) return el;
     var classNames = className.split(' ').map(function (c) {
       return c.trim();
     }).filter(Boolean);
@@ -162,10 +217,24 @@ var dom = {
     return el;
   },
   /**
-   * @param {Element} el
-   * @param {string} classNames
-   * @param {boolean} [force]
-   * @returns {Element}
+   * Toggles one or more CSS classes on an element.
+   *
+   * Multiple classes can be provided as a space-separated string.
+   * If `force` is provided, it explicitly adds (`true`) or removes (`false`)
+   * the class instead of toggling it.
+   *
+   * @example
+   * const el = document.querySelector('#box')
+   *
+   * dom.toggleClass(el, 'active')        // toggles "active"
+   * dom.toggleClass(el, 'a b')           // toggles both classes
+   * dom.toggleClass(el, 'active', true)  // ensures "active" is present
+   * dom.toggleClass(el, 'active', false) // ensures "active" is removed
+   *
+   * @param {Element} el - Element to update
+   * @param {string} classNames - One or more class names separated by spaces
+   * @param {boolean} [force] - Optional force flag passed to classList.toggle
+   * @returns {Element} The element
    */
   toggleClass: function toggleClass(el, classNames, force) {
     foreach(classNames.split(' ').map(function (c) {
@@ -176,9 +245,22 @@ var dom = {
     return el;
   },
   /**
-   * @param {Element} el
-   * @param {string} classNames
-   * @returns {boolean}
+   * Checks whether an element has all the given CSS classes.
+   *
+   * Multiple classes can be provided as a space-separated string.
+   * Returns `true` only if the element contains every class.
+   *
+   * @example
+   * // <div class="box active large"></div>
+   *
+   * dom.hasClass(el, 'active') // true
+   * dom.hasClass(el, 'active large') // true
+   * dom.hasClass(el, 'active missing') // false
+   * dom.hasClass(el, '') // false
+   *
+   * @param {Element} el - Element to test
+   * @param {string} classNames - One or more class names separated by spaces
+   * @returns {boolean} - `true` if the element has all the classes
    */
   hasClass: function hasClass(el, classNames) {
     if (!classNames) return false;
@@ -186,18 +268,25 @@ var dom = {
     foreach(classNames.split(' ').map(function (c) {
       return c.trim();
     }).filter(Boolean), function (c) {
-      if (el.classList.contains(c)) {
-        return true;
-      }
+      if (inArray(c, Array.from(el.classList))) return;
       foundClasses = false;
       return false;
     });
     return foundClasses;
   },
   /**
-   * @param {Node} node
-   * @param {...(Node|string)} children
-   * @returns {Node}
+   * Appends one or more children to a node.
+   *
+   * Children can be DOM nodes or HTML strings.
+   *
+   * @example
+   * const box = document.createElement('div')
+   * dom.append(box, document.createElement('span'))
+   * dom.append(box, '<b>Hello</b>', '<i>world</i>')
+   *
+   * @param {Node} node - The parent node
+   * @param {...(Node|string)} children - Nodes or HTML strings to append
+   * @returns {Node} The parent node
    */
   append: function append(node) {
     var _this = this;
@@ -213,9 +302,21 @@ var dom = {
     return node;
   },
   /**
-   * @param {Node} node
-   * @param {...(Node|string)} children
-   * @returns {Node}
+   * Prepends one or more children to a node.
+   *
+   * Children can be DOM nodes or HTML strings.
+   * HTML strings are converted to nodes using `dom.create`.
+   * When multiple children are provided, their original order is preserved.
+   *
+   * @example
+   * const box = document.createElement('div')
+   *
+   * dom.prepend(box, document.createElement('span'))
+   * dom.prepend(box, '<b>Hello</b>', '<i>world</i>')
+   *
+   * @param {Node} node - The parent node
+   * @param {...(Node|string)} children - Nodes or HTML strings to prepend
+   * @returns {Node} - The parent node
    */
   prepend: function prepend(node) {
     var _this2 = this;
@@ -231,7 +332,7 @@ var dom = {
     return node;
   },
   /**
-   * @param {Element|NodeList|Array<Element>|string} els
+   * @param {Element|NodeList|Element[]|string} els
    * @returns {void}
    */
   remove: function remove() {
@@ -252,9 +353,24 @@ var dom = {
     });
   },
   /**
-   * @param {Element} el
-   * @param {string|Element} [selector]
-   * @returns {Element|null}
+   * Returns the closest ancestor of an element matching a selector or a specific element.
+   *
+   * If a DOM element is provided as `selector`, the function walks up the DOM
+   * tree and returns it if found among the ancestors (or the element itself).
+   * If a CSS selector string is provided, it delegates to `Element.closest()`.
+   * If `selector` is omitted, the element itself is returned.
+   *
+   * @example
+   * const item = document.querySelector('.item')
+   * const container = document.querySelector('.container')
+   *
+   * dom.closest(item, '.container') // container
+   * dom.closest(item, container) // container
+   * dom.closest(item) // item
+   *
+   * @param {Element} el - The starting element
+   * @param {string|Element} [selector] - CSS selector or specific ancestor element
+   * @returns {Element|null} - The matching ancestor, or null if none found
    */
   closest: function closest(el, selector) {
     if (selector instanceof Element) {
@@ -274,9 +390,22 @@ var dom = {
     return el.closest(selector);
   },
   /**
-   * @param {Element} el
-   * @param {string} [selector]
-   * @returns {Element|null}
+   * Returns the next sibling element of a node.
+   *
+   * If a selector is provided, the next sibling is returned only if it matches
+   * the selector. This function does not search beyond the immediate sibling.
+   *
+   * @example
+   * // <div class="a"></div><div class="b"></div><div class="c"></div>
+   * const a = document.querySelector('.a')
+   *
+   * dom.next(a) // <div class="b">
+   * dom.next(a, '.b') // <div class="b">
+   * dom.next(a, '.c') // null
+   *
+   * @param {Element} el - Reference element
+   * @param {string|null} [selector] - CSS selector to filter the sibling
+   * @returns {Element|null} - The next sibling element, or null if not found/matching
    */
   next: function next(el) {
     var selector = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : null;
@@ -288,9 +417,22 @@ var dom = {
     return null;
   },
   /**
-   * @param {Element} el
-   * @param {string|null} [selector]
-   * @returns {Element|null}
+   * Returns the previous sibling element of a node.
+   *
+   * If a selector is provided, the previous sibling is returned only if it matches
+   * the selector. This function does not search beyond the immediate sibling.
+   *
+   * @example
+   * // <div class="a"></div><div class="b"></div><div class="c"></div>
+   * const c = document.querySelector('.c')
+   *
+   * dom.prev(c) // <div class="b">
+   * dom.prev(c, '.b') // <div class="b">
+   * dom.prev(c, '.a') // null
+   *
+   * @param {Element} el - Reference element
+   * @param {string|null} [selector] - CSS selector to filter the sibling
+   * @returns {Element|null} - The previous sibling element, or null if not found/matching
    */
   prev: function prev(el) {
     var selector = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : null;
@@ -302,9 +444,21 @@ var dom = {
     return null;
   },
   /**
-   * @param {Element} el
-   * @param {string} [selector]
-   * @returns {Element[]}
+   * Returns all following sibling elements of a node.
+   *
+   * If a selector is provided, only siblings matching the selector are included.
+   * Traversal continues through all next siblings in document order.
+   *
+   * @example
+   * // <div class="a"></div><div class="b"></div><div class="c"></div>
+   * const a = document.querySelector('.a')
+   *
+   * dom.nextAll(a) // [<div class="b">, <div class="c">]
+   * dom.nextAll(a, '.c') // [<div class="c">]
+   *
+   * @param {Element} el - Reference element
+   * @param {string} [selector] - CSS selector to filter siblings
+   * @returns {Element[]} - Array of matching following siblings
    */
   nextAll: function nextAll(el, selector) {
     var siblings = [];
@@ -318,9 +472,21 @@ var dom = {
     return siblings;
   },
   /**
-   * @param {Element} el
-   * @param {string} [selector]
-   * @returns {Element[]}
+   * Returns all preceding sibling elements of a node.
+   *
+   * If a selector is provided, only siblings matching the selector are included.
+   * Traversal continues through all previous siblings in reverse document order.
+   *
+   * @example
+   * // <div class="a"></div><div class="b"></div><div class="c"></div>
+   * const c = document.querySelector('.c')
+   *
+   * dom.prevAll(c) // [<div class="b">, <div class="a">]
+   * dom.prevAll(c, '.a') // [<div class="a">]
+   *
+   * @param {Element} el - Reference element
+   * @param {string} [selector] - CSS selector to filter siblings
+   * @returns {Element[]} - Array of matching preceding siblings
    */
   prevAll: function prevAll(el, selector) {
     var siblings = [];
@@ -334,9 +500,42 @@ var dom = {
     return siblings;
   },
   /**
-   * @param {Element} el
-   * @param {Element|string} selector
-   * @returns {Element[]}
+   * Returns the index of a node among its preceding siblings.
+   *
+   * If a selector is provided, only matching siblings are considered.
+   *
+   * @example
+   * // <div class="a"></div><div class="b"></div><div class="c"></div>
+   * const c = document.querySelector('.c')
+   *
+   * dom.index(a) // 0
+   * dom.index(c) // 2
+   * dom.prevAll(c, '.a') // 1
+   *
+   * @param {Element} el - Reference element
+   * @param {string} [selector] - CSS selector to filter siblings
+   * @returns {number} - The index of `el`
+   */
+  index: function index(el, selector) {
+    return this.prevAll(el, selector).length;
+  },
+  /**
+   * Returns all following sibling elements until a matching element is reached.
+   *
+   * Traversal stops before the first sibling that matches the given selector
+   * or equals the provided element. That matching element is not included.
+   *
+   * @example
+   * // <div class="a"></div><div class="b"></div><div class="c"></div><div class="d"></div>
+   * const a = document.querySelector('.a')
+   * const d = document.querySelector('.d')
+   *
+   * dom.nextUntil(a, '.d') // [<div class="b">, <div class="c">]
+   * dom.nextUntil(a, d)    // [<div class="b">, <div class="c">]
+   *
+   * @param {Element} el - Reference element
+   * @param {Element|string} selector - CSS selector or element to stop at
+   * @returns {Element[]} - Array of siblings until the stop condition
    */
   nextUntil: function nextUntil(el, selector) {
     var selectorIsElement = false;
@@ -354,9 +553,23 @@ var dom = {
     return list;
   },
   /**
-   * @param {Element} el
-   * @param {Element|string} selector
-   * @returns {Element[]}
+   * Returns all preceding sibling elements until a matching element is reached.
+   *
+   * Traversal stops before the first sibling that matches the given selector
+   * or equals the provided element. That matching element is not included.
+   *
+   * @example
+   * // <div class="a"></div><div class="b"></div><div class="c"></div><div class="d"></div>
+   *
+   * const d = document.querySelector('.d')
+   * const a = document.querySelector('.a')
+   *
+   * dom.prevUntil(d, '.a') // [<div class="c">, <div class="b">]
+   * dom.prevUntil(d, a)    // [<div class="c">, <div class="b">]
+   *
+   * @param {Element} el - Reference element
+   * @param {Element|string} selector - CSS selector or element to stop at
+   * @returns {Element[]} - Array of siblings until the stop condition
    */
   prevUntil: function prevUntil(el, selector) {
     var selectorIsElement = false;
@@ -374,9 +587,22 @@ var dom = {
     return list;
   },
   /**
-   * @param {Element} el
-   * @param {Element} wrappingElement
-   * @returns {Element}
+   * Wraps an element inside another element.
+   *
+   * If the wrapping element is not already in the DOM, it is inserted
+   * just before the target element. The target element is then appended
+   * inside the wrapper.
+   *
+   * @example
+   * const el = document.querySelector('.item')
+   * const wrapper = document.createElement('div')
+   *
+   * dom.wrap(el, wrapper)
+   * // <div><div class="item"></div></div>
+   *
+   * @param {Element} el - The element to wrap
+   * @param {Element} wrappingElement - The wrapper element
+   * @returns {Element} - The original wrapped element
    */
   wrap: function wrap(el, wrappingElement) {
     if (!wrappingElement.isConnected) {
@@ -386,10 +612,21 @@ var dom = {
     return el;
   },
   /**
-   * @param {Element} el
-   * @param {string} name
-   * @param {*} [value]
-   * @returns {Element|*}
+   * Gets, sets, or removes an attribute on an element.
+   *
+   * - If `value` is omitted, returns the attribute value (or null if not present).
+   * - If `value` is `null`, the attribute is removed.
+   * - Otherwise, the attribute is set to the provided value.
+   *
+   * @example
+   * dom.attr(el, 'id') // "my-id"
+   * dom.attr(el, 'title', 'Hello') // sets title="Hello"
+   * dom.attr(el, 'disabled', null) // removes the attribute
+   *
+   * @param {Element} el - Target element
+   * @param {string} name - Attribute name
+   * @param {string|null} [value] - Value to set, or null to remove
+   * @returns {Element|string|null} - The attribute value when reading, otherwise the element
    */
   attr: function attr(el, name, value) {
     if (undefined === value) return el.getAttribute(name);
@@ -401,10 +638,24 @@ var dom = {
     return el;
   },
   /**
-   * @param {Element} el
-   * @param {string} name
-   * @param {*} [value]
-   * @returns {*|Element}
+   * Gets or sets a property directly on a DOM element.
+   *
+   * Unlike `dom.attr`, this interacts with the live DOM property,
+   * not the HTML attribute.
+   *
+   * - If `value` is omitted, returns the property value.
+   * - Otherwise, sets the property.
+   *
+   * @example
+   * dom.prop(input, 'checked') // true/false
+   * dom.prop(input, 'checked', true) // checks the checkbox
+   *
+   * dom.prop(img, 'src') // full resolved URL
+   *
+   * @param {Element} el - Target element
+   * @param {string} name - Property name
+   * @param {any} [value] - Value to set
+   * @returns {*|Element} - The property value when reading, otherwise the element
    */
   prop: function prop(el, name, value) {
     if (undefined === value) {
@@ -414,9 +665,18 @@ var dom = {
     return el;
   },
   /**
-   * @param {Element} el
-   * @param {string} [html]
-   * @returns {Element|string}
+   * Gets or sets the HTML content of an element.
+   *
+   * - If `html` is omitted, returns the element's current `innerHTML`.
+   * - Otherwise, replaces the element's content with the provided HTML string.
+   *
+   * @example
+   * dom.html(el) // "<span>Hello</span>"
+   * dom.html(el, '<b>Hi</b>') // sets inner HTML
+   *
+   * @param {Element} el - Target element
+   * @param {string} [html] - HTML string to set
+   * @returns {Element|string} The HTML string when reading, otherwise the element
    */
   html: function html(el, _html) {
     if (undefined === _html) return el.innerHTML;
@@ -424,9 +684,18 @@ var dom = {
     return el;
   },
   /**
-   * @param {Element} el
-   * @param {string} [text]
-   * @returns {Element|string}
+   * Gets or sets the text content of an element.
+   *
+   * - If `text` is omitted, returns the element's visible text (`innerText`).
+   * - Otherwise, replaces the element's text content.
+   *
+   * @example
+   * dom.text(el) // "Hello world"
+   * dom.text(el, 'New text') // sets visible text content
+   *
+   * @param {Element} el - Target element
+   * @param {string} [text] - Text to set
+   * @returns {Element|string} - The text when reading, otherwise the element
    */
   text: function text(el, _text) {
     if (undefined === _text) return el.innerText;
@@ -434,20 +703,43 @@ var dom = {
     return el;
   },
   /**
-   * @param {Element} el
-   * @returns {Element}
+   * Hides an element by setting `display: none`, while preserving its original display value.
+   *
+   * The original computed `display` value is stored internally so it can be
+   * restored later (typically by the corresponding `show()` method).
+   *
+   * @example
+   * dom.hide(el) // element becomes hidden
+   *
+   * @param {Element} el - Element to hide
+   * @returns {Element} The element
    */
   hide: function hide(el) {
     if (undefined === this.data(el, '__display__')) {
-      var display = getComputedStyle(el).display;
+      var display = '';
+      if (isFunction(window.getComputedStyle)) {
+        display = window.getComputedStyle(el).display;
+      } else {
+        display = el.style.display;
+      }
       this.data(el, '__display__', display);
     }
     el.style.display = 'none';
     return el;
   },
   /**
-   * @param {Element} el
-   * @returns {Element}
+   * Shows an element by restoring its original `display` value.
+   *
+   * If the element was previously hidden using `hide`, its original
+   * computed display value is restored. Otherwise, the inline `display`
+   * style is simply removed.
+   *
+   * @example
+   * dom.hide(el)
+   * dom.show(el) // element becomes visible again with its original display
+   *
+   * @param {Element} el - Element to show
+   * @returns {Element} - The element
    */
   show: function show(el) {
     var dataDisplay = this.data(el, '__display__');
@@ -460,17 +752,47 @@ var dom = {
     return el;
   },
   /**
-   * @param {Element} el
-   * @returns {Element}
+   * Toggles the visibility of an element using `dom.hide` and `dom.show`.
+   *
+   * The visibility state is determined from the computed display value,
+   * not only the inline style.
+   *
+   * @example
+   * dom.toggle(el) // hides if visible, shows if hidden
+   *
+   * @param {Element} el - Element to toggle
+   * @returns {Element} - The element
    */
   toggle: function toggle(el) {
-    return 'none' === el.style.display ? this.show(el) : this.hide(el);
+    return 'none' === this.css(el, 'display') ? this.show(el) : this.hide(el);
   },
   /**
-   * @param {Element} el
-   * @param {Object<string, string>|string} name
-   * @param {string} [value]
-   * @returns {Element|DOMStringMap}
+   * Gets, sets, or removes data-* attributes on an element.
+   *
+   * - If called with no arguments, returns the element's `dataset`.
+   * - If `name` is an object, sets multiple data entries.
+   * - If `value` is omitted, returns the value of the data key.
+   * - If `value` is `null`, removes the data attribute.
+   * - Otherwise, sets the data value.
+   *
+   * Keys can be provided in camelCase (`userId`) or kebab-case with `data-` prefix (`data-user-id`).
+   *
+   * @example
+   * dom.data(el) // DOMStringMap of all data attributes
+   *
+   * dom.data(el, 'userId') // value of data-user-id
+   * dom.data(el, 'userId', '42') // sets data-user-id="42"
+   *
+   * dom.data(el, 'data-role', 'admin') // also works
+   *
+   * dom.data(el, { userId: '42', role: 'admin' }) // sets multiple values
+   *
+   * dom.data(el, 'userId', null) // removes data-user-id
+   *
+   * @param {Element} el - Target element
+   * @param {Object<string, string>|string} [name] - Data key or object of key/value pairs
+   * @param {string|null} [value] - Value to set, or null to remove
+   * @returns {Element|DOMStringMap|string|undefined} - Dataset, value, or element
    */
   data: function data(el, name, value) {
     var _this4 = this;
@@ -487,34 +809,69 @@ var dom = {
     var key = camelCase(isAttr ? (name + '').replace(/^data-/, '') : name + '');
     if (undefined === value) return el.dataset[key];
     if (null === value) {
-      this.removeData(el, key);
+      delete el.dataset[key];
       return el;
     }
     el.dataset[key] = value;
     return el;
   },
   /**
-   * @param {Element} el
-   * @param {string} name
-   * @returns {Element|*}
+   * Removes a data-* attribute from an element.
+   *
+   * The key can be provided in camelCase, kebab-case, or with the `data-` prefix.
+   *
+   * @example
+   * dom.removeData(el, 'userId')     // removes data-user-id
+   * dom.removeData(el, 'user-id')    // removes data-user-id
+   * dom.removeData(el, 'data-role')  // removes data-role
+   *
+   * @param {Element} el - Target element
+   * @param {string} name - Data key to remove
+   * @returns {Element} - The element
    */
   removeData: function removeData(el, name) {
-    var key = camelCase((name + '').replace(/^data-/, ''));
-    delete el.dataset[key];
-    return el;
+    return this.data(el, name, null);
   },
   /**
-   * @param {HTMLElement} el
-   * @param {Object<string, string>|string} style
-   * @param {string} [value]
-   * @returns {Element}
+   * Gets or sets CSS styles on an element.
+   *
+   * - If `style` is a string and `value` is omitted, returns the computed style value.
+   * - If `style` is a string and `value` is provided, sets the style.
+   * - If `style` is an object, sets multiple styles at once.
+   *
+   * handles :
+   * - camelCase and kebab-case properties
+   * - CSS custom properties (`--var`)
+   * - Adding `px` to numeric values where appropriate
+   *
+   * @example
+   * dom.css(el, 'color') // "rgb(255, 0, 0)"
+   * dom.css(el, 'background-color', 'blue')
+   * dom.css(el, 'width', 200) // sets "200px"
+   *
+   * dom.css(el, {
+   *   width: 100,
+   *   height: 50,
+   *   backgroundColor: 'red'
+   * })
+   *
+   * dom.css(el, '--my-var', '10px') // CSS custom property
+   *
+   * @param {HTMLElement} el - Target element
+   * @param {Object<string, string|number>|string} style - CSS property or object of properties
+   * @param {string|number} [value] - Value to set
+   * @returns {Element|string} - The style value when reading, otherwise the element
    */
   css: function css(el, style, value) {
     var _this5 = this;
     if (isString(style)) {
       var prop = style.startsWith('--') ? style : camelCase(style);
       if (undefined === value) {
-        return getStyle(el, prop);
+        if (window.getComputedStyle) {
+          var computedStyle = window.getComputedStyle(el, null);
+          return computedStyle.getPropertyValue(style) || computedStyle[camelCase(style)] || '';
+        }
+        return el.style[camelCase(style)] || '';
       }
       if (prop.startsWith('--')) {
         el.style.setProperty(prop, String(value));
@@ -530,10 +887,22 @@ var dom = {
     return el;
   },
   /**
-   * @param {Element} el
-   * @param {string} selectorClosest
-   * @param {string} selectorFind
-   * @returns {Array<Element>}
+   * Finds elements matching a selector inside the closest ancestor
+   * that matches another selector.
+   *
+   * First finds the closest ancestor of `el` matching `selectorClosest`,
+   * then searches inside it for elements matching `selectorFind`.
+   *
+   * @example
+   * // <div class="card"><button class="btn"></button><span class="label"></span></div>
+   *
+   * dom.closestFind(button, '.card', '.label')
+   * // => finds .label inside the closest .card ancestor
+   *
+   * @param {Element} el - Starting element
+   * @param {string} selectorClosest - Selector used to find the closest ancestor
+   * @param {string} selectorFind - Selector used to find elements inside that ancestor
+   * @returns {Element[]} - Array of matched elements, or empty array if none found
    */
   closestFind: function closestFind(el, selectorClosest, selectorFind) {
     var closest = this.closest(el, selectorClosest);
@@ -543,10 +912,22 @@ var dom = {
     return [];
   },
   /**
-   * @param {Element} el
-   * @param {string} selectorClosest
-   * @param {string} selectorFindOne
-   * @returns {Element|null}
+   * Finds the first element matching a selector inside the closest ancestor
+   * that matches another selector.
+   *
+   * First finds the closest ancestor of `el` matching `selectorClosest`,
+   * then searches inside it for the first element matching `selectorFindOne`.
+   *
+   * @example
+   * // <div class="card"><button class="btn"></button><span class="label"></span></div>
+   *
+   * dom.closestFindOne(button, '.card', '.label')
+   * // => finds the first .label inside the closest .card ancestor
+   *
+   * @param {Element} el - Starting element
+   * @param {string} selectorClosest - Selector used to find the closest ancestor
+   * @param {string} selectorFindOne - Selector used to find a single element inside that ancestor
+   * @returns {Element|null} - The matched element, or null if none found
    */
   closestFindOne: function closestFindOne(el, selectorClosest, selectorFindOne) {
     var closest = this.closest(el, selectorClosest);
@@ -556,8 +937,18 @@ var dom = {
     return null;
   },
   /**
-   * @param {NodeList|Element|Array<Element>} nodeList
-   * @returns {Element|null}
+   * Returns the first element from a collection or the element itself.
+   *
+   * Accepts a single Element, a NodeList, or an array of Elements.
+   * Returns `null` if the collection is empty.
+   *
+   * @example
+   * dom.first(document.querySelectorAll('.item')) // first .item
+   * dom.first([el1, el2]) // el1
+   * dom.first(el) // el
+   *
+   * @param {NodeList|Element|Element[]} nodeList - Collection or single element
+   * @returns {Element|null} - The first element, or null if none found
    */
   first: function first(nodeList) {
     var _Array$from$;
@@ -565,8 +956,17 @@ var dom = {
     return (_Array$from$ = Array.from(nodeList)[0]) !== null && _Array$from$ !== void 0 ? _Array$from$ : null;
   },
   /**
-   * @param {NodeList|Array<Element>} nodeList
-   * @returns {Element|null}
+   * Returns the last element from a collection or the element itself.
+   *
+   * Accepts a NodeList or an array of Elements.
+   * Returns `null` if the collection is empty.
+   *
+   * @example
+   * dom.last(document.querySelectorAll('.item')) // last .item
+   * dom.last([el1, el2]) // el2
+   *
+   * @param {NodeList|Element|Element[]} nodeList - Collection or single element
+   * @returns {Element|null} - The last element, or null if none found
    */
   last: function last(nodeList) {
     var _arr;
@@ -575,8 +975,20 @@ var dom = {
     return (_arr = arr[arr.length - 1]) !== null && _arr !== void 0 ? _arr : null;
   },
   /**
-   * @param {string} html
-   * @returns {Element|DocumentFragment|null}
+   * Creates DOM node(s) from a tag name or an HTML string.
+   *
+   * - If a simple tag name is provided (e.g. `"div"`), a new element is created.
+   * - If an HTML string is provided, it is parsed using a `<template>` element.
+   * - If the HTML contains a single root element, that element is returned.
+   * - If multiple root nodes are present, a `DocumentFragment` is returned.
+   *
+   * @example
+   * dom.create('div') // <div></div>
+   * dom.create('<span>Hello</span>') // <span>Hello</span>
+   * dom.create('<li>One</li><li>Two</li>') // DocumentFragment containing both <li>
+   *
+   * @param {string} html - Tag name or HTML string
+   * @returns {Element|DocumentFragment|null} - Created node(s), or null if input is invalid
    */
   create: function create(html) {
     if (!isString(html)) return null;
@@ -595,9 +1007,22 @@ var dom = {
     return frag.cloneNode(true);
   },
   /**
-   * @param {NodeList|Array<Element>} nodeList
-   * @param {number} [index=0]
-   * @returns {Element|null}
+   * Returns the element at a given index from a collection.
+   *
+   * Supports negative indexes to count from the end of the list.
+   * Returns `null` if the index is out of bounds.
+   *
+   * @example
+   * const items = document.querySelectorAll('.item')
+   *
+   * dom.eq(items, 0)  // first element
+   * dom.eq(items, 2)  // third element
+   * dom.eq(items, -1) // last element
+   * dom.eq(items, -2) // second to last
+   *
+   * @param {NodeList|Element[]} nodeList - Collection of elements
+   * @param {number} [index=0] - Index of the element (can be negative)
+   * @returns {Element|null} - The element at the given index, or null if not found
    */
   eq: function eq(nodeList) {
     var index = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : 0;
@@ -609,9 +1034,18 @@ var dom = {
     return nodeList[index];
   },
   /**
-   * @param {Element} el
-   * @param {Element|string} newEl
-   * @returns {Element|null}
+   * Inserts a new element or HTML string immediately after a reference element.
+   *
+   * If `newEl` is a string, it is converted to a node using `dom.create`.
+   * Returns the inserted node, or `null` if the reference element has no parent.
+   *
+   * @example
+   * dom.after(el, '<span>New</span>')
+   * dom.after(el, document.createElement('div'))
+   *
+   * @param {Element} el - Reference element
+   * @param {Element|string} newEl - Element or HTML string to insert
+   * @returns {Element|DocumentFragment|null} - The inserted node, or null if insertion failed
    */
   after: function after(el, newEl) {
     if (!el.parentElement) return null;
@@ -621,9 +1055,18 @@ var dom = {
     return el.parentElement.insertBefore(newEl, el.nextElementSibling);
   },
   /**
-   * @param {Element} el
-   * @param {Element|string} newEl
-   * @returns {Element|null}
+   * Inserts a new element or HTML string immediately before a reference element.
+   *
+   * If `newEl` is a string, it is converted to a node using `dom.create`.
+   * Returns the inserted node, or `null` if the reference element has no parent.
+   *
+   * @example
+   * dom.before(el, '<span>New</span>')
+   * dom.before(el, document.createElement('div'))
+   *
+   * @param {Element} el - Reference element
+   * @param {Element|string} newEl - Element or HTML string to insert
+   * @returns {Element|DocumentFragment|null} - The inserted node, or null if insertion failed
    */
   before: function before(el, newEl) {
     if (!el.parentElement) return null;
@@ -633,8 +1076,13 @@ var dom = {
     return el.parentElement.insertBefore(newEl, el);
   },
   /**
-   * @param {Element} el
-   * @returns {Element}
+   * Removes all child nodes from an element.
+   *
+   * @example
+   * dom.empty(el) // el now has no children
+   *
+   * @param {Element} el - Element to clear
+   * @returns {Element} - The element
    */
   empty: function empty(el) {
     while (el.firstChild) {
@@ -643,23 +1091,45 @@ var dom = {
     return el;
   },
   /**
-   * @param {Element|NodeList|Array<Element>} el
-   * @param {string|Element} selector
-   * @return {Array<Element>}
+   * Filters a collection of elements by excluding those matching a selector
+   * or a specific element.
+   *
+   * Accepts a single Element, a NodeList, or an array of Elements.
+   * If `selector` is a string, elements matching it are excluded.
+   * If `selector` is an Element, that exact element is excluded.
+   *
+   * @example
+   * const items = document.querySelectorAll('.item')
+   *
+   * dom.not(items, '.active') // all .item elements except those with .active
+   * dom.not(items, someElement) // all elements except that specific one
+   *
+   * dom.not(el, '.hidden') // returns [] if el matches, otherwise [el]
+   *
+   * @param {Element|NodeList|Element[]} el - Element(s) to filter
+   * @param {string|Element} selector - CSS selector or element to exclude
+   * @returns {Element[]} - Filtered array of elements
    */
   not: function not(el, selector) {
     var elements = el instanceof Element ? [el] : Array.from(el);
     var selectorIsString = isString(selector);
     return elements.filter(function (e) {
-      // if (!(e instanceof Element)) return false
-
       return selectorIsString ? !e.matches(selector) : e !== selector;
     });
   },
   /**
-   * @param {Element} elem1
-   * @param {Element} elem2
-   * @returns {boolean}
+   * Checks whether two elements visually collide (overlap) in the viewport.
+   *
+   * Returns `true` if their rectangles intersect.
+   *
+   * @example
+   * if (dom.collide(box1, box2)) {
+   *   console.log('Elements overlap')
+   * }
+   *
+   * @param {Element} elem1 - First element
+   * @param {Element} elem2 - Second element
+   * @returns {boolean} - `true` if the elements overlap, otherwise false
    */
   collide: function collide(elem1, elem2) {
     var rect1 = elem1.getBoundingClientRect();
@@ -667,25 +1137,49 @@ var dom = {
     return rect1.x < rect2.x + rect2.width && rect1.x + rect1.width > rect2.x && rect1.y < rect2.y + rect2.height && rect1.y + rect1.height > rect2.y;
   },
   /**
-   * @param {Element} el
-   * @param {string|Element} selector
+   * Checks whether an element matches a selector or is equal to another element.
+   *
+   * If `selector` is a string, uses `Element.matches()`.
+   * If `selector` is an Element, checks strict equality.
+   *
+   * @example
+   * dom.matches(el, '.active') // true if el has class "active"
+   * dom.matches(el, otherEl)   // true if el === otherEl
+   *
+   * @param {Element} el - Element to test
+   * @param {string|Element} selector - CSS selector or element to compare
+   * @returns {boolean} - `true` if the element matches, otherwise false
    */
   matches: function matches(el, selector) {
     if (!el) return false;
     return selector instanceof Element ? selector === el : el.matches(selector);
   },
   /**
-   * @param {Element} el
-   * @param {Element} child
-   * @param {Element} oldChild
+   * Replaces a child node of an element with another node.
+   *
+   * @example
+   * dom.replaceChild(parent, newEl, oldEl)
+   *
+   * @param {Element} el - Parent element
+   * @param {Element} child - New child node
+   * @param {Element} oldChild - Existing child node to replace
+   * @returns {Element} - The replaced node
    */
   replaceChild: function replaceChild(el, child, oldChild) {
     return el.replaceChild(child, oldChild);
   },
   /**
-   * @param {Element} el
-   * @param {NodeList|Array<Element>|string[]} children
-   * @returns {Element}
+   * Replaces all children of an element with new nodes or HTML strings.
+   *
+   * Strings are converted to DOM nodes using `dom.create`.
+   *
+   * @example
+   * dom.replaceChildren(el, '<span>A</span>', '<span>B</span>')
+   * dom.replaceChildren(el, document.createElement('div'))
+   *
+   * @param {Element} el - Target element
+   * @param {...(Element|string)} children - New children to insert
+   * @returns {Element} - The element
    */
   replaceChildren: function replaceChildren(el) {
     var _this6 = this;
@@ -703,8 +1197,19 @@ var dom = {
     return el;
   },
   /**
-   * @param {Element|Document|Window} el
-   * @returns {{top: number, left: number}}
+   * Returns the page offset of an element, document, or window.
+   *
+   * - For `window`, returns the current scroll position.
+   * - For `document`, returns the scroll position of the root element.
+   * - For an element, returns its position relative to the top-left of the page.
+   *
+   * @example
+   * dom.offset(window)   // { top: scrollY, left: scrollX }
+   * dom.offset(document) // { top: scrollTop, left: scrollLeft }
+   * dom.offset(el)       // position of el relative to the page
+   *
+   * @param {Element|Document|Window} el - Target element, document, or window
+   * @returns {{top: number, left: number}} - The offset relative to the page
    */
   offset: function offset(el) {
     if (isWindow(el)) {
@@ -726,8 +1231,24 @@ var dom = {
     };
   },
   /**
-   * @param {Node} el
-   * @returns {boolean}
+   * Checks whether a node is inside an editable context.
+   *
+   * Returns true if the element itself, or one of its ancestors,
+   * is an editable form control or has `contenteditable="true"`.
+   * Text nodes are automatically resolved to their parent element.
+   *
+   * @example
+   * dom.isEditable(inputEl) // true
+   * dom.isEditable(textareaEl) // true
+   * dom.isEditable(selectEl) // true
+   *
+   * dom.isEditable(divWithContentEditable) // true
+   * dom.isEditable(spanInsideContentEditable) // true
+   *
+   * dom.isEditable(document.body) // false
+   *
+   * @param {Node} el - Node to test
+   * @returns {boolean} True if the node is in an editable context
    */
   isEditable: function isEditable(el) {
     var _el;
@@ -736,8 +1257,16 @@ var dom = {
     return inArray(el.tagName, ['INPUT', 'TEXTAREA', 'SELECT']) || el.isContentEditable || !!this.closest(el, '[contenteditable="true"]');
   },
   /**
-   * @param {Node} node
-   * @returns {boolean}
+   * Checks whether a node is currently attached to the main document.
+   *
+   * @example
+   * dom.isInDOM(el) // true if element is in the document
+   *
+   * const frag = document.createDocumentFragment()
+   * dom.isInDOM(frag) // false
+   *
+   * @param {Node} node - Node to test
+   * @returns {boolean} - `true` if the node is attached to the document
    */
   isInDOM: function isInDOM(node) {
     if (!(node instanceof Node)) return false;
@@ -746,7 +1275,82 @@ var dom = {
     });
     return root === document;
   },
+  /**
+   * Attaches one or more event listeners to an element, document, or window.
+   *
+   * Supports:
+   * - Multiple events (space-separated)
+   * - Event namespaces (e.g. "click.menu")
+   * - Event delegation via CSS selector
+   * - Custom events
+   *
+   * Custom Events :
+   *
+   * The following custom events are available:
+   *
+   * `longtap`
+   *   Fired when the user presses and holds on an element for a short duration
+   *   (useful for touch interfaces and long-press interactions).
+   *
+   * `dbltap`
+   *   Fired when the user performs a quick double tap on touch devices.
+   *
+   * These events are automatically enabled the first time they are used.
+   *
+   * @example
+   * // Simple binding
+   * dom.on(button, 'click', (ev) => {})
+   *
+   * // Multiple events
+   * dom.on(input, 'focus blur', handler)
+   *
+   * // Namespaced event
+   * dom.on(button, 'click.menu', handler)
+   *
+   * // Delegated event
+   * dom.on(list, 'click', '.item', (ev) => {})
+   *
+   * // With options
+   * dom.on(window, 'scroll', handler, { passive: true })
+   *
+   * @example
+   * dom.on(el, 'longtap', handler)
+   * dom.on(el, 'dbltap', handler)
+   *
+   * @param {Element|Document|Window} el - Element to bind the listener to
+   * @param {string} events - Space-separated list of events (optionally namespaced)
+   * @param {string|function} [selector] - CSS selector for delegation, or handler if no delegation
+   * @param {function|AddEventListenerOptions|boolean} [handler] - Event handler
+   * @param {AddEventListenerOptions|boolean} [options] - Native event listener options
+   * @returns {Element} - The element
+   */
   on: on,
+  /**
+   * Removes event listeners previously attached with `dom.on`.
+   *
+   * You can remove listeners by:
+   * - Event type
+   * - Namespace
+   * - Handler reference
+   * - Selector (for delegated events)
+   * - Options
+   *
+   * If no event is provided, all listeners on the element are removed.
+   *
+   * @example
+   * dom.off(button, 'click')
+   * dom.off(button, 'click.menu')
+   * dom.off(button, 'click', handler)
+   * dom.off(list, 'click', '.item', handler)
+   * dom.off(button) // removes all listeners
+   *
+   * @param {Element|Document|Window} el - Element to unbind listeners from
+   * @param {string} [events] - Space-separated events (optionally namespaced)
+   * @param {string|function} [selector] - Delegation selector or handler
+   * @param {function|AddEventListenerOptions|boolean} [handler] - Specific handler to remove
+   * @param {AddEventListenerOptions|boolean} [options] - Listener options to match
+   * @returns {Element} - The element
+   */
   off: off
 };
 
@@ -756,4 +1360,10 @@ if ('test' === process.env.NODE_ENV) {
     __resetCustomEventsForTests();
   };
 }
-export default dom;
+export default dom;
+
+/* istanbul ignore next */
+if ('undefined' !== typeof window) {
+  window.webf = window.webf || {};
+  window.webf.dom = dom;
+}