vira/dist/util/pop-up-manager.d.ts

A simple and highly versatile design system using element-vir.

import { type MaybePromise } from '@augment-vir/common';
import { type Coords, type NavController } from 'device-navigation';
import { type ExtractEventByType, type ExtractEventTypes, type ListenOptions, ListenTarget, type RemoveListenerCallback } from 'typed-event-target';
/**
 * Used to prevent pop-ups from closing when a text input is active.
 *
 * @category Internal
 */
export declare function isInputLikeElement(element: Element): boolean;
/**
 * A type used for representing a rectangle's position.
 *
 * @category Internal
 */
export type PositionRect = {
    top: number;
    left: number;
    right: number;
    bottom: number;
};
/**
 * The default empty {@link PositionRect}, with all values set to 0.
 *
 * @category Internal
 */
export declare const emptyPositionRect: PositionRect;
/**
 * Options for {@link PopUpManager}.
 *
 * @category PopUp
 */
export type PopUpManagerOptions = {
    /**
     * The minimum number of pixels for allowing the pop-up to go downwards. If the downward
     * available space is less than this, and if the upwards available space is
     * `verticalDiffThreshold` more than the downwards space, the pop-up will be directed upwards.
     *
     * Equation:
     *
     *     const directUpwards =
     *         downwardsSpace < minDownSpace &&
     *         upwardsSpace > DownwardsSpace + verticalDiffThreshold;
     *
     * @default 200
     */
    minDownSpace: number;
    /**
     * The minimum number of pixels for allowing the pop-up to go rightwards. If the rightward
     * available space is less than this, and if the leftwards available space is
     * `horizontalDiffThreshold` more than the rightwards space, the pop-up will be directed
     * leftwards.
     *
     * Equation:
     *
     *     const directLeftwards =
     *         rightwardsSpace < minRightSpace &&
     *         leftwardsSpace > rightwardsSpace + horizontalDiffThreshold;
     *
     * @default 400
     */
    minRightSpace: number;
    /**
     * The number of pixels required for the upwards available space to be bigger than the downwards
     * available space before directing the pop-up upwards.
     *
     * Equation:
     *
     *     const directUpwards =
     *         downwardsSpace < minDownSpace &&
     *         upwardsSpace > DownwardsSpace + verticalDiffThreshold;
     *
     * @default 20
     */
    verticalDiffThreshold: number;
    /**
     * The number of pixels required for the leftwards available space to be bigger than the
     * rightwards available space before directing the pop-up leftwards.
     *
     * Equation:
     *
     *     const directLeftwards =
     *         rightwardsSpace < minRightSpace &&
     *         leftwardsSpace > rightwardsSpace + horizontalDiffThreshold;
     *
     * @default 100
     */
    horizontalDiffThreshold: number;
    /**
     * Supports navigation of the pop up via the `device-navigation` package.
     *
     * @default true
     */
    supportNavigation: boolean;
};
/**
 * Output type from `PopUpManager.showPopUp`
 *
 * @category PopUp
 */
export type ShowPopUpResult = {
    /**
     * Indicates if the "pop up" should pop in the downwards direction or not. If not, it should pop
     * in the upwards direction. This is determined by how much space is available on either side of
     * the root element.
     */
    popDown: boolean;
    /**
     * Indicates if the "pop up" should pop in the rightwards direction or not. If not, it should
     * pop in the leftwards direction. This is determined by how much space is available on either
     * side of the root element.
     */
    popRight: boolean;
    positions: Record<'root' | 'container' | 'diff', PositionRect>;
};
declare const HidePopUpEvent_base: (new (eventInitDict?: EventInit) => Event & import("typed-event-target").TypedEvent<"hide-pop-up">) & Pick<{
    new (type: string, eventInitDict?: EventInit): Event;
    prototype: Event;
    readonly NONE: 0;
    readonly CAPTURING_PHASE: 1;
    readonly AT_TARGET: 2;
    readonly BUBBLING_PHASE: 3;
}, "prototype" | "NONE" | "CAPTURING_PHASE" | "AT_TARGET" | "BUBBLING_PHASE"> & Pick<import("typed-event-target").TypedEvent<"hide-pop-up">, "type">;
/**
 * An event fired from {@link PopUpManager} when the pop up should be hidden.
 *
 * @category PopUp
 */
export declare class HidePopUpEvent extends HidePopUpEvent_base {
}
declare const NavSelectEvent_base: (new (eventInitDict: {
    bubbles?: boolean;
    cancelable?: boolean;
    composed?: boolean;
    detail: Coords;
}) => import("typed-event-target").TypedCustomEvent<Coords, "nav-select">) & Pick<{
    new (type: string, eventInitDict?: EventInit): Event;
    prototype: Event;
    readonly NONE: 0;
    readonly CAPTURING_PHASE: 1;
    readonly AT_TARGET: 2;
    readonly BUBBLING_PHASE: 3;
}, "prototype" | "NONE" | "CAPTURING_PHASE" | "AT_TARGET" | "BUBBLING_PHASE"> & Pick<import("typed-event-target").TypedCustomEvent<Coords, "nav-select">, "type">;
/**
 * An event fired from {@link PopUpManager} when an individual item in the pop up has been selected
 * by the user.
 *
 * @category PopUp
 */
export declare class NavSelectEvent extends NavSelectEvent_base {
}
/**
 * All events that can be emitted by {@link PopUpManager}.
 *
 * @category Internal
 */
export type PopUpManagerEvents = HidePopUpEvent | NavSelectEvent;
/**
 * A "pop up" manager for items that pop up from the HTML page, like dropdowns or menus.
 *
 * @category PopUp
 */
export declare class PopUpManager {
    readonly navController: NavController;
    protected listenTarget: ListenTarget<PopUpManagerEvents>;
    options: PopUpManagerOptions;
    /** Callbacks that remove the global listeners attached while a pop up is shown. */
    protected cleanupCallbacks: (() => void)[];
    protected lastRootElement: HTMLElement | undefined;
    constructor(navController: NavController, options?: Partial<PopUpManagerOptions> | undefined);
    /**
     * Attaches the global listeners (page activation, navigation, mousedown, and keydown) that
     * control the currently shown pop up.
     */
    protected attachGlobalListeners(): void;
    /** Listen to events emitted from a {@link PopUpManager} instance. */
    listen<const EventDefinition extends Readonly<{
        type: ExtractEventTypes<PopUpManagerEvents>;
    }>>(event: EventDefinition, listener: (event: ExtractEventByType<PopUpManagerEvents, EventDefinition['type']>) => MaybePromise<void>, options?: ListenOptions | undefined): RemoveListenerCallback;
    /** Trigger removal or hiding of the pop up. */
    removePopUp(): void;
    /** Trigger showing the pop up. */
    showPopUp(rootElement: HTMLElement, options?: Partial<PopUpManagerOptions> | undefined): ShowPopUpResult;
    /**
     * Cleanup and destroy the {@link PopUpManager} instance. This:
     *
     * - Removes the existing pop up
     * - Cleans up all internal and external listeners
     */
    destroy(): void;
}
export {};