houser-js-utils/dist/DOMUtils.d.ts

A comprehensive collection of TypeScript utility functions for common development tasks including array manipulation, string processing, date handling, random number generation, validation, and much more.

/**
 * @module DOMUtils
 * @description A collection of utility functions for DOM manipulation, element queries, and browser interactions.
 * @example
 * ```typescript
 * import { DOMUtils } from 'houser-js-utils';
 *
 * // Query elements safely
 * const element = DOMUtils.querySelector('.my-class');
 *
 * // Check element visibility
 * const isVisible = DOMUtils.isElementVisible(element);
 *
 * // Scroll to element
 * DOMUtils.scrollToElement(element);
 * ```
 */
export declare const DOMUtils: {
    /**
     * Adds a class to an element if it doesn't already have it.
     * @param element - The DOM element to modify
     * @param className - The class name to add
     * @throws {TypeError} If element is not a valid DOM element
     */
    addClass(element: Element | null, className: string): void;
    /**
     * Gets the computed style of an element.
     * @param element - The DOM element to check
     * @param property - The CSS property to get (e.g., 'width', 'color')
     * @returns The computed value of the property or empty string if element is null
     */
    getComputedStyle(element: Element | null, property: string): string;
    /**
     * Gets the dimensions of an element including margins.
     * @param element - The DOM element to measure
     * @returns Object containing width and height, or {width: 0, height: 0} if element is null
     */
    getElementDimensions(element: Element | null): {
        width: number;
        height: number;
    };
    /**
     * Gets the offset position of an element relative to the document.
     * @param element - The DOM element to measure
     * @returns Object containing top and left offsets, or {top: 0, left: 0} if element is null
     */
    getElementOffset(element: Element | null): {
        top: number;
        left: number;
    };
    /**
     * Gets the scroll position of an element.
     * @param element - The DOM element to check
     * @returns Object containing scrollTop and scrollLeft values, or {scrollTop: 0, scrollLeft: 0} if element is null
     */
    getScrollPosition(element: Element | null): {
        scrollTop: number;
        scrollLeft: number;
    };
    /**
     * Checks if an element has a specific class.
     * @param element - The DOM element to check
     * @param className - The class name to check for
     * @returns True if the element has the class, false otherwise
     */
    hasClass(element: Element | null, className: string): boolean;
    /**
     * Checks if an element is currently fully visible in the viewport.
     * @param element - The DOM element to check
     * @returns True if the element is fully visible in the viewport, false otherwise
     */
    isElementInViewport(element: Element | null): boolean;
    /**
     * Checks if an element is partially visible in the viewport.
     * @param element - The DOM element to check
     * @returns True if any part of the element is visible in the viewport, false otherwise
     */
    isElementPartiallyVisible(element: Element | null): boolean;
    /**
     * Removes a class from an element if it has it.
     * @param element - The DOM element to modify
     * @param className - The class name to remove
     */
    removeClass(element: Element | null, className: string): void;
    /**
     * Scrolls an element into view with smooth behavior.
     * @param element - The DOM element to scroll into view
     * @param options - ScrollIntoViewOptions for customizing scroll behavior
     */
    scrollIntoView(element: Element | null, options?: ScrollIntoViewOptions): void;
    /**
     * Sets the scroll position of an element.
     * @param element - The DOM element to modify
     * @param position - Object containing scrollTop and scrollLeft values
     */
    setScrollPosition(element: Element | null, position: {
        scrollTop: number;
        scrollLeft: number;
    }): void;
    /**
     * Sets a CSS property on an element.
     * @param element - The DOM element to modify
     * @param property - The CSS property to set (e.g., 'width', 'color')
     * @param value - The value to set
     */
    setStyle(element: Element | null, property: string, value: string): void;
    /**
     * Toggles a class on an element.
     * @param element - The DOM element to modify
     * @param className - The class name to toggle
     * @param force - Optional boolean to force add or remove the class
     */
    toggleClass(element: Element | null, className: string, force?: boolean): void;
    /**
     * Waits for an element to be present in the DOM.
     * @param selector - CSS selector for the element
     * @param timeout - Maximum time to wait in milliseconds (default: 5000)
     * @returns Promise that resolves with the element or null if not found within timeout
     */
    waitForElement(selector: string, timeout?: number): Promise<Element | null>;
};