util

/**
 * DOM utility helpers for element selection, manipulation, and safe event handling.
 */

/**
 * Safely gets an element by its ID.
 * @param {string} id - Element ID.
 * @returns {HTMLElement|null} The DOM element or null if not found.
 */
export function getEl(id) {
	if (!id || typeof id !== 'string') return null;
	return document.getElementById(id);
}

/**
 * Safely queries a single descendant element.
 * @param {string} selector - CSS selector.
 * @param {Element|Document} [parent=document] - Parent element to query from.
 * @returns {HTMLElement|Element|null} The matched element or null.
 */
export function queryEl(selector, parent = document) {
	if (!selector || !parent || typeof parent.querySelector !== 'function') return null;
	return parent.querySelector(selector);
}

/**
 * Safely queries all matching descendant elements as an Array.
 * @param {string} selector - CSS selector.
 * @param {Element|Document} [parent=document] - Parent element to query from.
 * @returns {Element[]} Array of matched elements.
 */
export function queryAll(selector, parent = document) {
	if (!selector || !parent || typeof parent.querySelectorAll !== 'function') return [];
	return [...parent.querySelectorAll(selector)];
}

/**
 * Toggles a class on an element if the element exists.
 * @param {Element|null} el - Target element.
 * @param {string} className - Class name to toggle.
 * @param {boolean} [force] - Optional force boolean.
 * @returns {boolean} Whether the class is present after toggling.
 */
export function toggleElementClass(el, className, force) {
	if (!el || !el.classList || !className) return false;
	if (typeof force === 'boolean') {
		return el.classList.toggle(className, force);
	}
	return el.classList.toggle(className);
}

/**
 * Sets the display style on an element.
 * @param {HTMLElement|Element|null} el - Target element.
 * @param {string} display - CSS display value.
 */
export function setElementDisplay(el, display) {
	if (el && el.style) {
		el.style.display = display;
	}
}

/**
 * Creates a DOM element from an HTML string.
 * @param {string} htmlString - Valid HTML string.
 * @returns {HTMLElement|Element|null} The parsed root element or null.
 */
export function createElementFromHTML(htmlString) {
	if (!htmlString || typeof htmlString !== 'string') return null;
	const template = document.createElement('template');
	template.innerHTML = htmlString.trim();
	return template.content.firstElementChild;
}

/**
 * Safely attaches an event listener to an element with existence verification.
 * @param {EventTarget|null} el - Target element or event target.
 * @param {string} event - Event name.
 * @param {Function} handler - Event handler function.
 * @param {object|boolean} [options] - Optional addEventListener options.
 */
export function addSafeEventListener(el, event, handler, options) {
	if (el && typeof el.addEventListener === 'function' && typeof handler === 'function') {
		el.addEventListener(event, handler, options);
	}
}