phane-tech-dom-utils 1.0.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 phane-tech
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,322 @@
+# 📦 Kotipalli Phaneendra Kumar - Array Utilities
+
+A lightweight, safe, and predictable **DOM utility module** that simplifies common DOM operations with **strict validation**, **consistent return values**, and **clean JSDoc documentation**.
+
+Designed specifically for **browser environments**, this module helps you work confidently with elements, attributes, classes, styles, events, and dynamic DOM creation without unexpected runtime errors.
+
+---
+
+## ✨ Highlights
+
+- 🧱 Safe DOM selectors with validation  
+- 🏷️ Attribute helpers (get / set / remove)  
+- 🧩 Class utilities (add / remove / toggle / check)  
+- 🎨 Style helpers (single & multiple styles)  
+- 🧩 Dynamic element creation & DOM insertion  
+- 🎧 Event listener helpers  
+- ⭐ Tab title & favicon utilities  
+- 📚 Fully documented using JSDoc  
+- ⚡ Predictable return values (`undefined` for invalid input)  
+
+---
+
+## 📦 Installation
+
+```bash
+npm install phane-js-dom-helpers
+```
+---
+
+## 🚀 Import
+
+```js
+import {
+  getElementById,
+  getElementsByClassName,
+  getElementsByTagName,
+  setTabTitle,
+  getTabTitle,
+  setFavicon,
+  getFavicon,
+  setTextContent,
+  setHTMLContent,
+  setAttribute,
+  getAttribute,
+  removeAttribute,
+  hasClass,
+  addClass,
+  removeClass,
+  toggleClass,
+  setStyle,
+  setStyles,
+  createDynamicElement,
+  appendDynamicTag,
+  removeElement,
+  addEventListenerHelper,
+  removeEventListenerHelper,
+  onElementLoad,
+  setDataId
+} from "phane-js-dom-helpers";
+```
+
+---
+
+## 📚 API Reference
+
+### 🔍 getElementById(id)
+
+Safely returns a DOM element by its ID.
+
+```js
+getElementById("header"); // HTMLElement | null
+getElementById("unknown"); // null
+getElementById(""); // undefined
+```
+
+---
+
+### 🔍 getElementsByClassName(className)
+
+Returns a live HTMLCollection of elements.
+
+```js
+getElementsByClassName("card"); // HTMLCollection
+```
+
+---
+
+### 🔍 getElementsByTagName(tagName)
+
+Returns a live HTMLCollection of elements.
+
+```js
+getElementsByTagName("div"); // HTMLCollection
+```
+
+---
+
+### 🏷️ setTabTitle(title)
+
+Sets the browser tab title.
+
+```js
+setTabTitle("Home"); // "Home"
+```
+
+---
+
+### ⭐ getTabTitle()
+
+Returns the current tab title.
+
+```js
+getTabTitle(); // "Home"
+```
+
+---
+
+### ⭐ setFavicon(url)
+
+Sets or updates the browser favicon.
+
+```js
+setFavicon("/favicon.ico");
+```
+
+---
+
+### ⭐ getFavicon()
+
+Returns the current favicon URL if available.
+
+```js
+getFavicon(); // string | undefined
+```
+
+---
+
+### ✏️ setTextContent(element, text)
+
+Safely sets innerText on an element.
+
+```js
+setTextContent(el, "Hello World");
+```
+
+---
+
+### ✏️ setHTMLContent(element, html)
+
+Safely sets innerHTML on an element.
+```js
+setHTMLContent(el, "<b>Hello</b>");
+```
+
+---
+
+### 🧱 setAttribute(element, name, value)
+
+Adds or updates an attribute.
+
+```js
+setAttribute(el, "data-id", "123");
+```
+
+---
+
+### 🧱 getAttribute(element, name)
+
+Gets an attribute value.
+
+```js
+getAttribute(el, "data-id"); // "123"
+```
+
+---
+
+### 🧱 removeAttribute(element, name)
+
+Removes an attribute.
+
+```js
+removeAttribute(el, "disabled");
+```
+
+---
+
+### 🧩 hasClass(element, className)
+
+Checks if a class exists on an element.
+
+```js
+hasClass(el, "active"); // true | false
+```
+
+---
+
+### 🧩 addClass / removeClass / toggleClass
+
+Manages element classes safely.
+
+```js
+addClass(el, "active");
+removeClass(el, "active");
+toggleClass(el, "active");
+```
+
+---
+
+### 🎨 setStyle(element, property, value)
+
+Sets a single CSS style.
+
+```js
+setStyle(el, "color", "red");
+```
+
+---
+
+### 🎨 setStyles(element, styles)
+
+Applies multiple CSS styles at once.
+
+```js
+setStyles(el, {
+  color: "red",
+  backgroundColor: "yellow"
+});
+```
+---
+
+### 🧩 createDynamicElement(tag, content?, props?)
+
+Creates a DOM element dynamically.
+
+```js
+createDynamicElement("div", "Hello", {
+  id: "box",
+  className: "card"
+});
+```
+
+---
+
+### ➕ appendDynamicTag(child, parent?)
+
+Appends an element to the DOM.
+
+```js
+appendDynamicTag(div);
+appendDynamicTag(div, container);
+```
+---
+
+### ❌ removeElement(child, parent?)
+
+Removes an element from the DOM.
+
+```js
+removeElement(div);
+```
+
+---
+
+### 🎧 addEventListenerHelper(el, type, handler)
+
+Adds an event listener safely.
+
+```js
+addEventListenerHelper(btn, "click", handleClick);
+```
+
+---
+
+### 🎧 removeEventListenerHelper(el, type, handler)
+
+Removes an event listener safely.
+
+```js
+removeEventListenerHelper(btn, "click", handleClick);
+```
+
+---
+
+### ⏳ onElementLoad(element?, handler)
+
+Executes a handler when DOM or element is ready.
+
+```js
+onElementLoad(null, () => console.log("DOM Ready"));
+```
+
+
+---
+
+### 🆔 setDataId(element, value)
+
+Sets data-id attribute.
+
+```js
+setDataId(el, "123");
+```
+---
+
+## 🧪 Design Principles
+
+- ❌ Invalid input → undefined
+- ✅ Safe DOM access
+- 🔁 No unexpected mutations
+- 📖 Predictable, documented behavior
+
+
+## 📄 License
+
+MIT
+
+---
+## 🔗 Links
+
+- **GitHub Repository:** https://github.com/phane-tech/phane-tech-dom-utilities
+- **Demo / Documentation:** https://phane-tech.github.io/phane-tech-dom-utilities/module-DomHelpers.html
+- **Unit Test Cases Reports:** https://phane-tech.github.io/phane-tech-dom-utilities/unit-test-report.html
+

package/index.cjs

@@ -0,0 +1,2 @@
+const arrayUtils = require("./js/DomUtilities.js"); 
+module.exports = arrayUtils;

package/index.js

@@ -0,0 +1 @@
+export * from "./js/DomUtilities.js";

package/js/DomUtilities.js

@@ -0,0 +1,705 @@
+import { isObject, isString } from "phane-js-utils";
+/**
+ * DOM Helpers
+ * @module DomHelpers
+
+ */
+
+/**
+ * Get a DOM element by its ID.
+ *
+ * @function getElementById
+ * @memberof module:DomHelpers
+ *
+ * @param {*} elementId - The unique ID of the DOM element
+ * @returns { HTMLElement | null | undefined }
+ * Returns:a
+ * - HTMLElement if found
+ * - null if not found
+ * - undefined for invalid input
+ *
+ * @example
+ * getElementById("header") => HTMLElement
+ *
+ * getElementById("unknown") => null
+ *
+ * getElementById() => undefined
+ *
+ * getElementById(123) => undefined
+ */
+export function getElementById(elementId) {
+  if (!isString(elementId) || !elementId.trim()) return undefined;
+  const element = document.getElementById(elementId);
+  return element ?? null;
+}
+
+/**
+ * Get DOM elements by class name.
+ *
+ * @function getElementsByClassName
+ * @memberof module:DomHelpers
+ *
+ * @param {*} className - The class name to search for
+ * @returns { HTMLCollection | undefined }
+ * Returns:
+ * - HTMLCollection (may be empty)
+ * - undefined for invalid input
+ *
+ * @example
+ * getElementsByClassName("card") => HTMLCollection
+ *
+ * getElementsByClassName("unknown") => HTMLCollection (empty)
+ *
+ * getElementsByClassName("") => undefined
+ *
+ * getElementsByClassName(123) => undefined
+ */
+export function getElementsByClassName(className) {
+  if (!isString(className) || !className.trim()) return undefined;
+  return document.getElementsByClassName(className);
+}
+
+/**
+ * Get DOM elements by tag name.
+ *
+ * @function getElementsByTagName
+ * @memberof module:DomHelpers
+ *
+ * @param {*} tagName - The HTML tag name to search for
+ * @returns { HTMLCollection | undefined }
+ * Returns:
+ * - HTMLCollection (may be empty)
+ * - undefined for invalid input
+ *
+ * @example
+ * getElementsByTagName("div") => HTMLCollection
+ *
+ * getElementsByTagName("unknown") => HTMLCollection (empty)
+ *
+ * getElementsByTagName("") => undefined
+ *
+ * getElementsByTagName(null) => undefined
+ */
+export function getElementsByTagName(tagName) {
+  if (!isString(tagName) || !tagName.trim()) return undefined;
+  return document.getElementsByTagName(tagName);
+}
+
+
+/**
+ * Set the browser tab title.
+ *
+ * @function setTabTitle
+ * @memberof module:DomHelpers
+ *
+ * @param {*} title - The title to set for the browser tab
+ * @returns { string | undefined }
+ * Returns:
+ * - string (new title) on success
+ * - undefined for invalid input
+ *
+ * @example
+ * setTabTitle("Home") => "Home"
+ *
+ * setTabTitle("") => undefined
+ *
+ * setTabTitle(null) => undefined
+ */
+export function setTabTitle(title) {
+  if (!title) return undefined;
+  document.title = title;
+  return title;
+}
+
+/**
+ * Get the current browser tab title.
+ *
+ * @function getTabTitle
+ * @memberof module:DomHelpers
+ *
+ * @returns { string }
+ * Returns the current tab title
+ *
+ * @example
+ * getTabTitle() => "Home"
+ */
+export function getTabTitle() {
+  return document.title;
+}
+
+/**
+ * Set or update the browser tab favicon.
+ *
+ * @function setFavicon
+ * @memberof module:DomHelpers
+ *
+ * @param {*} faviconUrl - The favicon URL
+ * @returns { string | undefined }
+ * Returns:
+ * - string (favicon URL) on success
+ * - undefined for invalid input
+ *
+ * @example
+ * setFavicon("/favicon.ico") => "/favicon.ico"
+ *
+ * setFavicon("") => undefined
+ *
+ * setFavicon(null) => undefined
+ */
+export function setFavicon(faviconUrl) {
+  if (!isString(faviconUrl) || !faviconUrl.trim()) return undefined;
+  let favicon = document.querySelector("link[rel='icon']");
+  if (!favicon) {
+    favicon = createDynamicElement('link', null, { rel:'icon' });
+    appendDynamicTag(favicon);
+  }
+  favicon.href = faviconUrl;
+  return faviconUrl;
+}
+
+/**
+ * Get the current browser tab favicon URL.
+ *
+ * @function getFavicon
+ * @memberof module:DomHelpers
+ *
+ * @returns { string | undefined }
+ * Returns:
+ * - string (favicon URL) if exists
+ * - undefined if favicon is not set
+ *
+ * @example
+ * getFavicon() => "https://example.com/favicon.ico"
+ *
+ * getFavicon() => undefined
+ */
+export function getFavicon() {
+  const favicon = document.querySelector("link[rel='icon']");
+  return favicon?.href;
+}
+
+/**
+ * Set text content for a DOM element.
+ *
+ * @function setTextContent
+ * @memberof module:DomHelpers
+ *
+ * @param {*} element - The target DOM element
+ * @param {*} content - The text content to set
+ * @returns { string | undefined }
+ * Returns:
+ * - string (content) on success
+ * - undefined for invalid input
+ *
+ * @example
+ * setTextContent(el, "Hello") => "Hello"
+ *
+ * setTextContent(el, "") => ""
+ *
+ * setTextContent(null, "Hi") => undefined
+ */
+export function setTextContent(element, content) {
+  if (!(element instanceof HTMLElement)) return undefined;
+  element.innerText = content;
+  return content;
+}
+
+/**
+ * Set HTML content for a DOM element.
+ *
+ * @function setHTMLContent
+ * @memberof module:DomHelpers
+ *
+ * @param {*} element - The target DOM element
+ * @param {*} html - The HTML string to set
+ * @returns { string | undefined }
+ * Returns:
+ * - string (HTML content) on success
+ * - undefined for invalid input
+ *
+ * @example
+ * setHTMLContent(el, "<b>Hello</b>") => "<b>Hello</b>"
+ *
+ * setHTMLContent(el, "") => ""
+ *
+ * setHTMLContent(null, "<p>Hi</p>") => undefined
+ */
+export function setHTMLContent(element, html) {
+  if (!(element instanceof HTMLElement)) return undefined;
+  element.innerHTML = html;
+  return html;
+}
+
+/**
+ * Add or update an attribute on a DOM element.
+ *
+ * @function setAttribute
+ * @memberof module:DomHelpers
+ *
+ * @param {*} element - The target DOM element
+ * @param {*} attributeName - The attribute name
+ * @param {*} attributeValue - The attribute value
+ * @returns { string | undefined }
+ * Returns:
+ * - string (attribute value) on success
+ * - undefined for invalid input
+ *
+ * @example
+ * setAttribute(el, "id", "header") => "header"
+ *
+ * setAttribute(el, "data-id", "123") => "123"
+ *
+ * setAttribute(el, "disabled", "") => ""
+ *
+ * setAttribute(null, "id", "x") => undefined
+ */
+export function setAttribute(element, attributeName, attributeValue) {
+  if (!(element instanceof HTMLElement)) return undefined;
+  if (!isString(attributeName) || !attributeName.trim()) return undefined;
+  element.setAttribute(attributeName, attributeValue);
+  return attributeValue;
+}
+
+/**
+ * Get an attribute value from a DOM element.
+ *
+ * @function getAttribute
+ * @memberof module:DomHelpers
+ *
+ * @param {*} element - The target DOM element
+ * @param {*} attributeName - The attribute name
+ * @returns { string | null | undefined }
+ * Returns:
+ * - string if attribute exists
+ * - null if attribute does not exist
+ * - undefined for invalid input
+ *
+ * @example
+ * getAttribute(el, "id") => "header"
+ *
+ * getAttribute(el, "data-id") => "123"
+ *
+ * getAttribute(el, "unknown") => null
+ *
+ * getAttribute(null, "id") => undefined
+ */
+export function getAttribute(element, attributeName) {
+  if (!(element instanceof HTMLElement)) return undefined;
+  if (!isString(attributeName) || !attributeName.trim()) return undefined;
+  return element.getAttribute(attributeName);
+}
+
+/**
+ * Remove an attribute from a DOM element.
+ *
+ * @function removeAttribute
+ * @memberof module:DomHelpers
+ *
+ * @param {*} element - The target DOM element
+ * @param {*} attributeName - The attribute name
+ * @returns { boolean | undefined }
+ * Returns:
+ * - true if removal was attempted
+ * - undefined for invalid input
+ *
+ * @example
+ * removeAttribute(el, "disabled") => true
+ *
+ * removeAttribute(el, "data-id") => true
+ *
+ * removeAttribute(null, "id") => undefined
+ */
+export function removeAttribute(element, attributeName) {
+  if (!(element instanceof HTMLElement)) return undefined;
+  if (!isString(attributeName) || !attributeName.trim()) return undefined;
+  element.removeAttribute(attributeName);
+  return true;
+}
+
+/**
+ * Check if a DOM element has a specific class.
+ *
+ * @function hasClass
+ * @memberof module:DomHelpers
+ *
+ * @param {*} element - The target DOM element
+ * @param {*} className - The class name to check
+ * @returns { boolean | undefined }
+ * Returns:
+ * - true if the element has the class
+ * - false if the element does not have the class
+ * - undefined for invalid input
+ *
+ * @example
+ * hasClass(el, "active") => true
+ *
+ * hasClass(el, "hidden") => false
+ *
+ * hasClass(null, "active") => undefined
+ */
+export function hasClass(element, className) {
+  if (!(element instanceof HTMLElement)) return undefined;
+  if (!isString(className) || !className.trim()) return undefined;
+  return element.classList.contains(className);
+}
+
+/**
+ * Add a class to a DOM element if it does not already exist.
+ *
+ * @function addClass
+ * @memberof module:DomHelpers
+ *
+ * @param {*} element - The target DOM element
+ * @param {*} className - The class name to add
+ * @returns { string | undefined }
+ * Returns:
+ * - string (class name added or already present) on success
+ * - undefined for invalid input
+ *
+ * @example
+ * addClass(el, "active") => "active"
+ *
+ * addClass(el, "") => undefined
+ *
+ * addClass(null, "active") => undefined
+ */
+export function addClass(element, className) {
+  if (!(element instanceof HTMLElement)) return undefined;
+  if (!isString(className) || !className.trim()) return undefined;
+  if (!hasClass(element, className)) element.classList.add(className);
+  return className;
+}
+
+/**
+ * Remove a class from a DOM element if it exists.
+ *
+ * @function removeClass
+ * @memberof module:DomHelpers
+ *
+ * @param {*} element - The target DOM element
+ * @param {*} className - The class name to remove
+ * @returns { string | undefined }
+ * Returns:
+ * - string (class name removed or already absent) on success
+ * - undefined for invalid input
+ *
+ * @example
+ * removeClass(el, "active") => "active"
+ *
+ * removeClass(el, "") => undefined
+ *
+ * removeClass(null, "active") => undefined
+ */
+export function removeClass(element, className) {
+  if (!(element instanceof HTMLElement)) return undefined;
+  if (!isString(className) || !className.trim()) return undefined;
+  if (hasClass(element, className)) element.classList.remove(className);
+  return className;
+}
+
+/**
+ * Toggle a class on a DOM element.
+ *
+ * @function toggleClass
+ * @memberof module:DomHelpers
+ *
+ * @param {*} element - The target DOM element
+ * @param {*} className - The class name to toggle
+ * @returns { string | undefined }
+ * Returns:
+ * - string (class name toggled) on success
+ * - undefined for invalid input
+ *
+ * @example
+ * toggleClass(el, "active") => "active"
+ *
+ * toggleClass(el, "") => undefined
+ *
+ * toggleClass(null, "active") => undefined
+ */
+export function toggleClass(element, className) {
+  if (!(element instanceof HTMLElement)) return undefined;
+  if (!isString(className) || !className.trim()) return undefined;
+  element.classList.toggle(className);
+  return className;
+}
+
+/**
+ * Set a CSS style property on a DOM element.
+ *
+ * @function setStyle
+ * @memberof module:DomHelpers
+ *
+ * @param {*} element - The target DOM element
+ * @param {*} property - The CSS property name (camelCase)
+ * @param {*} value - The CSS value to apply
+ * @returns { string | undefined }
+ * Returns:
+ * - string (value applied) on success
+ * - undefined for invalid input
+ *
+ * @example
+ * setStyle(el, "color", "red") => "red"
+ *
+ * setStyle(el, "backgroundColor", "yellow") => "yellow"
+ *
+ * setStyle(null, "color", "red") => undefined
+ */
+export function setStyle(element, property, value) {
+  if (!(element instanceof HTMLElement)) return undefined;
+  if (!isString(property) || !property.trim()) return undefined;
+  element.style[property] = value;
+  return value;
+}
+
+/**
+ * Create a DOM element dynamically with optional content and properties.
+ *
+ * @function createDynamicElement
+ * @memberof module:DomHelpers
+ *
+ * @param {*} tagName - The HTML tag name for the element
+ * @param {*} content - Optional text content
+ * @param {*} propertyObj - Optional object of properties to assign
+ * @returns { HTMLElement | undefined }
+ * Returns:
+ * - HTMLElement on success
+ * - undefined for invalid input
+ *
+ * @example
+ * createDynamicElement("div", "Hello", { id: "myDiv", className: "card" });
+ *
+ * createDynamicElement("span") => <span></span>
+ *
+ * createDynamicElement(null) => undefined
+ */
+export function createDynamicElement(tagName, content, propertyObj) {
+  if (!isString(tagName) || !tagName.trim()) return undefined;
+  const ele = document.createElement(tagName);
+  if (isObject(propertyObj)) {
+     Object.entries(propertyObj).forEach(([key, value]) => {
+      ele[key] = value;
+    });
+  }
+  if (content) ele.innerText = content;
+  return ele;
+}
+
+/**
+ * Append a child element to a parent element or document body if parent is not provided.
+ *
+ * @function appendDynamicTag
+ * @memberof module:DomHelpers
+ *
+ * @param {*} child - The DOM element to append
+ * @param {*} parent - Optional parent DOM element (defaults to document.body)
+ * @returns { HTMLElement | undefined }
+ * Returns:
+ * - The appended child element on success
+ * - undefined for invalid input
+ *
+ * @example
+ * const div = createDynamicElement("div", "Hello");
+ * appendDynamicTag(div, document.getElementById("container"));
+ *
+ * appendDynamicTag(div) => appends to document.body
+ */
+export function appendDynamicTag(child, parent) {
+  if (!(child instanceof HTMLElement) || child === null) return undefined;
+  if (parent) {
+    if (!(parent instanceof HTMLElement)) return undefined;
+    return parent.appendChild(child);
+  } 
+  else return document.body.appendChild(child);
+}
+
+/**
+ * Remove a child element from a parent, or from the DOM if parent is not provided.
+ *
+ * @function removeElement
+ * @memberof module:DomHelpers
+ *
+ * @param {*} child - The DOM element to remove
+ * @param {*} parent - Optional parent DOM element
+ * @returns { HTMLElement | undefined }
+ * Returns:
+ * - The removed element on success
+ * - undefined for invalid input
+ *
+ * @example
+ * removeElement(child, document.getElementById("container"));
+ *
+ * removeElement(child) => removes directly from the DOM
+ */
+export function removeElement(child, parent) {
+  if (!(child instanceof HTMLElement)) return undefined;
+  if (parent) {
+    if (!(parent instanceof HTMLElement)) return undefined;
+    parent.removeChild(child);
+  } 
+  else child.remove();
+  return child;
+}
+
+/**
+ * Create a tag (script, link, etc.) and append it to the document head.
+ *
+ * @function headTags
+ * @memberof module:DomHelpers
+ *
+ * @param {*} tagName - The HTML tag name (e.g., "script", "link")
+ * @param {*} propertyObj - Optional object of properties to assign (like src, href, type, rel)
+ * @returns { HTMLElement | undefined }
+ * Returns:
+ * - The created and appended tag element
+ * - undefined for invalid input
+ *
+ * @example
+ * headTags("script", { src: "/app.js", type: "module" });
+ *
+ * headTags("link", { href: "/style.css", rel: "stylesheet" });
+ */
+export function headTags(tagName, propertyObj) {
+  if (!isString(tagName) || !tagName.trim()) return undefined;
+  const tag = createDynamicElement(tagName, null, propertyObj);
+ const res =  appendDynamicTag(tag, document.head);
+ return res;
+}
+
+/**
+ * Add an event listener to a DOM element.
+ *
+ * @function addEventListenerHelper
+ * @memberof module:DomHelpers
+ *
+ * @param {*} element - The target DOM element
+ * @param {*} type - The event type (e.g., "click", "input")
+ * @param {*} handler - The event handler function
+ * @returns { boolean | undefined }
+ * Returns:
+ * - true if the listener was added successfully
+ * - undefined for invalid input
+ *
+ * @example
+ * addEventListenerHelper(button, "click", () => alert("Clicked!"));
+ */
+export function addEventListenerHelper(element, type, handler) {
+  if (!(element instanceof HTMLElement)) return undefined;
+  if (!isString(type) || !type.trim()) return undefined;
+  if (typeof handler !== "function") return undefined;
+  element.addEventListener(type, handler);
+  return true;
+}
+
+/**
+ * Remove an event listener from a DOM element.
+ *
+ * @function removeEventListenerHelper
+ * @memberof module:DomHelpers
+ *
+ * @param {*} element - The target DOM element
+ * @param {*} type - The event type (e.g., "click", "input")
+ * @param {*} handler - The event handler function to remove
+ * @returns { boolean | undefined }
+ * Returns:
+ * - true if the listener was removed successfully
+ * - undefined for invalid input
+ *
+ * @example
+ * removeEventListenerHelper(button, "click", handleClick);
+ */
+export function removeEventListenerHelper(element, type, handler) {
+  if (!(element instanceof HTMLElement)) return undefined;
+  if (!isString(type) || !type.trim()) return undefined;
+  if (typeof handler !== "function") return undefined;
+  element.removeEventListener(type, handler);
+  return true;
+}
+
+/**
+ * Call a handler when the element is available or when the document is loaded.
+ *
+ * @function onElementLoad
+ * @memberof module:DomHelpers
+ *
+ * @param {*} element - The target DOM element. If null/undefined, uses document.
+ * @param {*} handler - The function to execute when ready
+ * @returns { boolean | undefined }
+ * Returns:
+ * - true if the listener was added successfully
+ * - undefined for invalid input
+ *
+ * @example
+ * onElementLoad(null, () => console.log("DOM fully loaded"));
+ *
+ * onElementLoad(button, () => console.log("Button is ready"));
+ */
+export function onElementLoad(element, handler) {
+  if (typeof handler !== "function") return undefined;
+  if (!element)  document.addEventListener("DOMContentLoaded", handler);
+  else if (element instanceof HTMLElement) {
+    if (document.body.contains(element)) handler();
+    else {
+      const observer = new MutationObserver((mutations, obs) => {
+        if (document.body.contains(element)) {
+          handler();
+          obs.disconnect();
+        }
+      });
+      observer.observe(document.body, { childList: true, subtree: true });
+    }
+  } 
+  else return undefined;
+  return true;
+}
+
+/**
+ * Set a data-id attribute on a DOM element.
+ *
+ * @function setDataId
+ * @memberof module:DomHelpers
+ *
+ * @param {*} element - The target DOM element
+ * @param {*} value - The value to set for data-id
+ * @returns { string | undefined }
+ * Returns:
+ * - The value set on data-id
+ * - undefined for invalid input
+ *
+ * @example
+ * setDataId(button, "123"); // returns "123"
+ *
+ * setDataId(null, "123"); // returns undefined
+ */
+export function setDataId(element, value) {
+  if (!(element instanceof HTMLElement)) return undefined;
+  element.dataset.id = value;
+  return value;
+}
+
+/**
+ * Apply multiple CSS styles to a DOM element.
+ *
+ * @function setStyles
+ * @memberof module:DomHelpers
+ *
+ * @param {*} element - The target DOM element
+ * @param {*} stylesObj - An object of CSS properties and values (camelCase)
+ * @returns { object | undefined }
+ * Returns:
+ * - The applied styles object on success
+ * - undefined for invalid input
+ *
+ * @example
+ * setStyles(div, { color: "red", backgroundColor: "yellow", fontSize: "16px" });
+ */
+export function setStyles(element, stylesObj) {
+  if (!(element instanceof HTMLElement)) return undefined;
+  if (!stylesObj || !isObject(stylesObj)) return undefined;
+  Object.entries(stylesObj).forEach(([property, value]) => {
+    if (isString(property) && property.trim()) {
+      element.style[property] = value;
+    }
+  });
+  return stylesObj;
+}

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "phane-tech-dom-utils",
+  "version": "1.0.3",
+  "description": "Pure JavaScript DOM utility functions",
+  "type": "module",
+  "main": "index.cjs",
+  "module": "index.js",
+  "files": [
+    "index.js",
+    "index.cjs",
+    "js"
+  ],
+  "keywords": [
+    "javascript",
+    "js",
+    "array",
+    "arrays",
+    "array-utils",
+    "array-helpers",
+    "array-methods",
+    "array-functions",
+    "utilities",
+    "utils",
+    "helpers",
+    "data-types",
+    "datatype",
+    "type-check",
+    "type-checking",
+    "validation",
+    "input-validation",
+    "array-validation",
+    "array-operations",
+    "flatten-array",
+    "sort-array",
+    "map-array",
+    "filter-array",
+    "find-array",
+    "reduce-array",
+    "merge-arrays",
+    "es-modules"
+  ],
+  "homepage": "https://phane-tech.github.io/phane-tech-array-utils/module-ArrayHelpers.html",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/phane-tech/phane-tech-dom-utilities"
+  },
+  "author": "Kotipalli Phaneendra Kumar",
+  "license": "MIT",
+  "scripts": {
+    "test": "jest",
+    "docs": "rimraf docs && npm run test && npx jsdoc -c jsdoc.json",
+    "release": "npm version patch && npm publish --access public"
+  },
+  "devDependencies": {
+    "@babel/core": "^7.28.5",
+    "@babel/preset-env": "^7.28.5",
+    "babel-jest": "^30.2.0",
+    "docdash": "^2.0.2",
+    "jest": "^30.2.0",
+    "jest-environment-jsdom": "^30.2.0",
+    "jest-html-reporter": "^4.3.0",
+    "jsdoc": "^4.0.5",
+    "jsdoc-to-markdown": "^9.1.3",
+    "rimraf": "^6.1.2"
+  },
+  "dependencies": {
+    "phane-js-utils": "^1.0.21"
+  }
+}