@flexilla/utilities/dist/utilities.d.ts

Utilities package for flexilla library

export declare const $$: (selector: string, parentElement?: HTMLElement) => HTMLElement[];

export declare const $: (selector: string, parentElement?: HTMLElement) => HTMLElement | null;

/**
 * Find direct descendant Element
 * @param selector
 * @param parentElement
 * @returns
 */
export declare const $d: (selector: string, parentElement?: HTMLElement) => HTMLElement | undefined;

/**
 * Creates a toggle functionality for DOM elements based on provided options.
 *
 * @param {TogglerOptions} options - Configuration options for the toggler
 * @param {string | HTMLElement} options.trigger - The trigger element that controls the toggle action
 * @param {Array<{element: string | HTMLElement, attributes: {initial: Record<string, string>, to: Record<string, string>}}>} options.targets - Array of target elements and their toggle attributes
 * @param {Function} [options.onToggle] - Optional callback function called when toggle state changes
 *
 * @example
 * ```ts
 * actionToggler({
 *   trigger: '#toggleButton',
 *   targets: [{
 *     element: '#target',
 *     attributes: {
 *       initial: { 'aria-hidden': 'true' },
 *       to: { 'aria-hidden': 'false' }
 *     }
 *   }],
 *   onToggle: ({ isExpanded }) => console.log('Toggle state:', isExpanded)
 * });
 * ```
 */
export declare const actionToggler: (options: TogglerOptions) => void;

/**
 * @param {Object} params - The parameters object
 * @param {HTMLElement} params.element - The target HTML element
 * @param {Function} params.callback - The function to execute after the animation
 * @example
 * const div = document.getElementById('animated-div');
 * afterAnimation({
 *   element: div,
 *   callback: () => console.log('Animation completed')
 * });
 */
export declare const afterAnimation: ({ element, callback, }: {
    element: HTMLElement;
    callback: () => void;
}) => void;

/**
 * Executes a callback after a CSS transition has completed on an element.
 * If no transition is present or the transition is invalid, the callback executes immediately.
 * @param {Object} params - The parameters object
 * @param {HTMLElement} params.element - The target HTML element
 * @param {Function} params.callback - The function to execute after the transition
 * @example
 * const div = document.getElementById('animated-div');
 * afterTransition({
 *   element: div,
 *   callback: () => console.log('Transition completed')
 * });
 */
export declare const afterTransition: ({ element, callback, }: {
    element: HTMLElement;
    callback: () => void;
}) => void;

/**
 * Inserts a new HTML element before an existing element in the DOM.
 * @param {Object} params - The parameters object
 * @param {HTMLElement} params.newElement - The new element to insert
 * @param {HTMLElement} params.existingElement - The reference element before which to insert
 * @throws {Error} If either parameter is not a valid HTML element
 * @throws {Error} If the existing element has no parent element
 * @example
 * const newDiv = document.createElement('div');
 * const existingDiv = document.getElementById('existing');
 * appendBefore({ newElement: newDiv, existingElement: existingDiv });
 */
export declare const appendBefore: ({ newElement, existingElement, }: {
    newElement: HTMLElement;
    existingElement: HTMLElement;
}) => void;

declare type AttributeMap = {
    [key: string]: string;
};

/**
 * Dispatches a custom event with a typed detail object on a specified element.
 * @template T
 * @param {HTMLElement} element - The target HTML element
 * @param {string} eventName - The name of the custom event
 * @param {T} detail - The detail object to be included in the custom event
 * @example
 * const div = document.getElementById('my-div');
 * dispatchCustomEvent(div, 'my-event', { data: 'example' });
 */
export declare const dispatchCustomEvent: <T extends object>(element: HTMLElement, eventName: string, detail: T) => void;

/**
 * Initialize a scroll to top button
 * @param triggerElement {string | HTMLElement} the element that triggers the scroll to top
 * @param initFrom {number} the scroll position to show the button
 * @param target {string | HTMLElement} the target element to scroll to
 */
export declare const initScrollToTop: ({ triggerElement, initFrom, target }: {
    triggerElement: string | HTMLElement;
    initFrom?: number;
    target?: string | HTMLElement;
}) => {
    cleanup: () => void;
};

/**
 * Implements keyboard navigation for a container element and its focusable children.
 * This utility enables arrow key navigation, home/end support, and circular navigation
 * through focusable elements within a specified container.
 *
 * @param {KeyDirAccessibilityOptions} options - Configuration options for keyboard navigation
 * @param {HTMLElement | string} options.containerElement - The container element or its selector
 * @param {string | HTMLElement[]} [options.targetChildren='a:not([disabled]), button:not([disabled])'] - Focusable children elements or selector
 * @param {"up-down" | "left-right" | "all"} options.direction - Navigation direction mode
 *
 * @returns {{make: () => void, destroy: () => void}} An object containing methods to initialize and cleanup the keyboard navigation
 *
 * @example
 * // Basic usage with default settings
 * const nav = keyboardNavigation({
 *   containerElement: '.nav-container',
 *   direction: 'all'
 * });
 * nav.make();
 *
 * @example
 * // Custom configuration with specific child elements
 * const nav = keyboardNavigation({
 *   containerElement: document.getElementById('menu'),
 *   targetChildren: '.menu-item',
 *   direction: 'left-right'
 * });
 * nav.make();
 *
 * // Cleanup when no longer needed
 * nav.destroy();
 */
export declare const keyboardNavigation: ({ containerElement, targetChildren, direction }: KeyDirAccessibilityOptions) => {
    make: () => void;
    destroy: () => void;
};

/**
 * Configuration options for keyboard navigation functionality.
 *
 * @interface KeyDirAccessibilityOptions
 * @property {HTMLElement | string} [containerElement] - The container element or its selector that contains focusable children
 * @property {string | HTMLElement[]} [targetChildren] - Selector string for focusable children or array of HTMLElements
 * @property {"up-down" | "left-right" | "all"} direction - The allowed navigation directions:
 *   - "up-down": Only vertical arrow key navigation
 *   - "left-right": Only horizontal arrow key navigation
 *   - "all": Both vertical and horizontal navigation
 */
export declare type KeyDirAccessibilityOptions = {
    containerElement?: HTMLElement | string;
    targetChildren?: string | HTMLElement[];
    direction: "up-down" | "left-right" | "all";
};

/**
 * Creates a MutationObserver to watch for changes in child elements with specific attributes.
 *
 * @param {Object} params - The parameters object
 * @param {HTMLElement} params.container - The container element to observe
 * @param {string} params.attributeToWatch - The data attribute to watch for (e.g., 'data-tab-panel')
 * @param {() => void} params.onChildAdded - Callback function to execute when a matching child is added
 * ```
 */
export declare const observeChildrenChanges: ({ container, attributeToWatch, onChildAdded }: {
    container: HTMLElement;
    attributeToWatch: string;
    onChildAdded: () => void;
}) => () => void;

/**
 * Sets multiple attributes on an HTML element.
 * @param {HTMLElement} element - The target HTML element
 * @param {Record<string, string>} attributes - An object containing attribute key-value pairs
 * @example
 * const div = document.createElement('div');
 * setAttributes(div, { id: 'myDiv', class: 'my-class', 'data-test': 'value' });
 */
export declare const setAttributes: (element: HTMLElement, attributes: Record<string, string>) => void;

/**
 * Creates a toggleable navbar with accessibility support and optional overlay.
 *
 * @param {Object} params - The parameters for navbar toggle functionality
 * @param {string | HTMLElement} params.navbarElement - The navbar element to toggle
 * @param {Function} [params.onToggle] - Optional callback function called when navbar state changes
 * @description
 * Required HTML structure:
 * ```html
 * <button data-nav-trigger data-toggle-nav="navbar-id">Toggle</button>
 * <nav id="navbar-id">...</nav>
 * <div data-nav-overlay data-navbar-id="navbar-id"></div>
 * ```
 */
export declare const toggleNavbar: ({ navbarElement, onToggle }: {
    navbarElement: string | HTMLElement;
    onToggle?: ({ isExpanded }: {
        isExpanded: boolean;
    }) => void;
}) => {
    cleanup: () => void;
    close: () => void;
    toggle: () => void;
} | undefined;

export declare type TogglerOptions = {
    trigger: HTMLElement | string;
    onToggle?: ({ isExpanded }: {
        isExpanded: boolean;
    }) => void;
    targets: {
        element: HTMLElement | string;
        attributes: {
            initial: AttributeMap;
            to: AttributeMap;
        };
    }[];
};

export { }