@flexilla/dropdown/dist/index.d.ts

Utilities package for flexilla library

import { Placement } from 'flexipop';
import { Placement as Placement_2 } from '@flexilla/create-overlay';
import { Placement as Placement_3 } from 'flexipop/create-overlay';

/**
 * A class that creates and manages dropdown functionality with popover positioning.
 * Provides click or hover trigger strategies, customizable placement, and keyboard navigation.
 *
 * @example
 * ```ts
 * // Auto initialize all dropdowns with data-fx-dropdown attribute
 * Dropdown.autoInit()
 *
 * // Initialize a specific dropdown
 * const dropdown = new Dropdown('#myDropdown', {
 *   triggerStrategy: 'hover',
 *   placement: 'bottom-start',
 *   offsetDistance: 8
 * })
 *
 * // Control programmatically
 * dropdown.show()
 * dropdown.hide()
 * ```
 */
export declare class Dropdown {
    private triggerElement;
    private contentElement;
    private options;
    private OverlayInstance;
    private navigationKeys;
    private triggerStrategy;
    private placement;
    private offsetDistance;
    private preventFromCloseOutside;
    private preventFromCloseInside;
    private defaultState;
    /**
     * Creates a new Dropdown instance
     * @param dropdown - The dropdown content element or selector
     * @param options - Configuration options for the dropdown
     * @throws {Error} If provided elements are not valid HTMLElements
     */
    constructor(dropdown: string | HTMLElement, options?: DropdownOptions);
    private onToggle;
    private beforeShow;
    private beforeHide;
    private onShow;
    private onHide;
    /**
     * Shows the dropdown
     */
    show: () => void;
    /**
     * Hides the dropdown
     */
    hide: () => void;
    /**
     * Updates the dropdown's placement and offset settings and show it
     * @param options - The new placement and offset options
     */
    setShowOptions: ({ placement, offsetDistance }: {
        placement: Placement_3;
        offsetDistance?: number;
    }) => void;
    /**
     * Updates the dropdown's placement and offset settings
     * @param options - The new placement and offset options
     */
    setOptions: ({ placement, offsetDistance }: {
        placement: Placement_3;
        offsetDistance?: number;
    }) => void;
    /**
     * Updates the dropdown trigger reference Element and options
     * The new set trigger will be used as reference for the Dropdown
     */
    setPopperTrigger: (trigger: HTMLElement, options: {
        placement?: Placement_3;
        offsetDistance?: number;
    }) => void;
    /**
     * Removes all event listeners
     */
    cleanup: () => void;
    /**
     * Automatically initializes all dropdown elements that match the given selector
     * @param selector - The selector to find dropdown elements (default: "[data-fx-dropdown]")
     */
    static autoInit: (selector?: string) => void;
    /**
     * Initializes a single dropdown instance
     * @param dropdown - The dropdown element or selector
     * @param options - Configuration options for the dropdown
     * @returns A new Dropdown instance
     */
    static init(dropdown: string | HTMLElement, options?: DropdownOptions): void;
}

/** Configuration options for the Dropdown component */
export declare type DropdownOptions = {
    /** Strategy to trigger the dropdown - either by click or hover
     * @default "click"
     */
    triggerStrategy?: "click" | "hover";
    /** Position of the dropdown relative to its trigger element
     * @see Placement from @flexilla/create-overlay
     */
    placement?: Placement_2;
    /** Prevents dropdown from closing when clicking inside the dropdown content */
    preventCloseFromInside?: boolean;
    /** Prevents dropdown from closing when clicking outside the dropdown */
    preventFromCloseOutside?: boolean;
    /** Initial state of the dropdown
     * @default "close"
     */
    defaultState?: "open" | "close";
    /** Distance in pixels between the trigger and dropdown content */
    offsetDistance?: number;
    /** Popper-specific configuration options */
    popper?: {
        eventEffect: EventEffect;
    };
    /** Callback fired when dropdown is shown */
    onShow?: () => void;
    /** Callback fired when dropdown is hidden */
    onHide?: () => void;
    /** Callback fired when dropdown visibility changes
     * @param {Object} params - Callback parameters
     * @param {boolean} [params.isHidden] - Current visibility state
     */
    onToggle?: ({ isHidden }: {
        isHidden?: boolean;
    }) => void;
};

/** Configuration for controlling event-based behavior */
declare type EventEffect = {
    /** Disable dropdown repositioning on scroll events */
    disableOnScroll?: boolean;
    /** Disable dropdown repositioning on window resize events */
    disableOnResize?: boolean;
};

export { Placement }

export { }