@esri/calcite-components/dist/utils/floating-ui.d.ts

Web Components for Esri's Calcite Design System.

import { Placement, Strategy, VirtualElement } from '@floating-ui/dom';
import { Layout } from '../components/interfaces';
/**
 * Positions the floating element relative to the reference element.
 *
 * **Note:** exported for testing purposes only
 *
 * @param root0
 * @param root0.referenceEl
 * @param root0.floatingEl
 * @param root0.overlayPositioning
 * @param root0.placement
 * @param root0.flipDisabled
 * @param root0.flipPlacements
 * @param root0.offsetDistance
 * @param root0.offsetSkidding
 * @param root0.arrowEl
 * @param root0.type
 * @param component
 * @param root0.referenceEl.referenceEl
 * @param root0.referenceEl.floatingEl
 * @param root0.referenceEl.overlayPositioning
 * @param root0.referenceEl.placement
 * @param root0.referenceEl.flipDisabled
 * @param root0.referenceEl.flipPlacements
 * @param root0.referenceEl.offsetDistance
 * @param root0.referenceEl.offsetSkidding
 * @param root0.referenceEl.arrowEl
 * @param root0.referenceEl.type
 * @param component.referenceEl
 * @param component.floatingEl
 * @param component.overlayPositioning
 * @param component.placement
 * @param component.flipDisabled
 * @param component.flipPlacements
 * @param component.offsetDistance
 * @param component.offsetSkidding
 * @param component.arrowEl
 * @param component.type
 */
export declare const positionFloatingUI: (component: FloatingUIComponent, { referenceEl, floatingEl, overlayPositioning, placement, flipDisabled, flipPlacements, offsetDistance, offsetSkidding, arrowEl, type, }: {
    referenceEl: ReferenceElement;
    floatingEl: HTMLElement;
    overlayPositioning: Strategy;
    placement: LogicalPlacement;
    flipDisabled?: boolean;
    flipPlacements?: FlipPlacement[];
    offsetDistance?: number;
    offsetSkidding?: number;
    arrowEl?: SVGSVGElement;
    type: UIType;
}) => Promise<void>;
/** Exported for testing purposes only */
export declare const placementDataAttribute = "data-placement";
export type ReferenceElement = VirtualElement | Element;
type UIType = "menu" | "tooltip" | "popover";
export type OverlayPositioning = Strategy;
/**
 * Variation Placements change based on element direction.
 *
 * These variation placements will automatically flip "left"/"right" depending on LTR/RTL direction.
 *
 * Floating-ui has no plans to offer this functionality out of the box at this time.
 *
 * see: https://github.com/floating-ui/floating-ui/issues/1563 and https://github.com/floating-ui/floating-ui/discussions/1549
 */
export type EffectivePlacement = Placement;
export declare const placements: readonly ["auto", "auto-start", "auto-end", "top", "top-start", "top-end", "bottom", "bottom-start", "bottom-end", "right", "right-start", "right-end", "left", "left-start", "left-end", "leading-start", "leading", "leading-end", "trailing-end", "trailing", "trailing-start"];
export type LogicalPlacement = (typeof placements)[number];
export declare const effectivePlacements: EffectivePlacement[];
export declare const menuPlacements: MenuPlacement[];
export declare const menuEffectivePlacements: EffectivePlacement[];
export type FlipPlacement = Exclude<LogicalPlacement, "auto" | "auto-start" | "auto-end">;
export declare const flipPlacements: FlipPlacement[];
export type MenuPlacement = Extract<LogicalPlacement, "top-start" | "top" | "top-end" | "bottom-start" | "bottom" | "bottom-end">;
export declare const defaultMenuPlacement: MenuPlacement;
export declare const defaultEndMenuPlacement: MenuPlacement;
export interface FloatingUIComponent {
    /** Whether the component is opened. */
    open: boolean;
    /** Describes the type of positioning to use for the overlaid content. If your element is in a fixed container, use the 'fixed' value. */
    overlayPositioning: OverlayPositioning;
    /**
     * Determines where the component will be positioned relative to the referenceElement.
     *
     * Possible values: "auto", "auto-start", "auto-end", "top", "right", "bottom", "left", "top-start", "top-end", "right-start", "right-end", "bottom-start", "bottom-end", "left-start", "left-end", "leading-start", "leading", "leading-end", "trailing-end", "trailing",  or "trailing-start".
     */
    placement: LogicalPlacement;
    /**
     * Updates the position of the component.
     *
     * @param delayed – (internal) when true, it will reposition the component after a delay. the default is false. This is useful for components that have multiple watched properties that schedule repositioning.
     */
    reposition: (delayed?: boolean) => Promise<void>;
    /**
     * Used to store the effective floating layout for components that use arrows.
     *
     * This is an internal property and should:
     *
     * - only be used for components that support arrows
     * - use the `@State` decorator
     * - be initialized to "vertical"
     *
     * Possible values: "vertical" or "horizontal".
     *
     * See [FloatingArrow](https://github.com/Esri/calcite-design-system/blob/dev/src/components/functional/FloatingArrow.tsx)
     */
    floatingLayout?: FloatingLayout;
    /** The `floatingElement` containing the floating ui. */
    floatingEl: HTMLElement;
    /** The `referenceElement` used to position the component according to its `placement` value. */
    referenceEl: ReferenceElement;
}
export type FloatingLayout = Extract<Layout, "vertical" | "horizontal">;
export declare const FloatingCSS: {
    animation: string;
    animationActive: string;
    arrow: string;
    arrowStroke: string;
};
export declare function filterValidFlipPlacements(placements: string[], el: HTMLElement): EffectivePlacement[];
export declare function getEffectivePlacement(placement: LogicalPlacement, isRTL?: boolean): EffectivePlacement;
/**
 * Convenience function to manage `reposition` calls for FloatingUIComponents that use `positionFloatingUI.
 *
 * Note: this is not needed for components that use `calcite-popover`.
 *
 * @param component - A floating-ui component.
 * @param options - Reposition parameters.
 * @param options.referenceEl - The `referenceElement` used to position the component according to its `placement` value.
 * @param options.floatingEl - The `floatingElement` containing the floating ui.
 * @param options.overlayPositioning - type of positioning to use for the overlaid content.
 * @param options.placement - Determines where the component will be positioned relative to the `referenceElement`.
 * @param options.flipDisabled - Prevents flipping the component's placement when overlapping its `referenceElement`.
 * @param options.flipPlacements - Defines the available placements that can be used when a flip occurs.
 * @param options.offsetDistance - Offsets the position of the popover away from the `referenceElement`.
 * @param options.offsetSkidding - Offsets the position of the component along the `referenceElement`.
 * @param options.arrowEl - A customizable arrow element.
 * @param options.type - The type of floating UI.
 * @param delayed - Reposition the component after a delay.
 * @returns {Promise<void>}
 */
export declare function reposition(component: FloatingUIComponent, options: Parameters<typeof positionFloatingUI>[1], delayed?: boolean): Promise<void>;
type PendingFloatingUIState = {
    state: "pending";
};
type ActiveFloatingUIState = {
    state: "active";
    cleanUp: () => void;
};
type TrackedFloatingUIState = PendingFloatingUIState | ActiveFloatingUIState;
/**
 * Exported for testing purposes only
 *
 * @private
 */
export declare const autoUpdatingComponentMap: WeakMap<FloatingUIComponent, TrackedFloatingUIState>;
/**
 * Helper to hide the floating element when the component is closed. This should be called within onClose() of an OpenCloseComponent.
 *
 * @param component - A floating-ui component.
 */
export declare function hideFloatingUI(component: FloatingUIComponent): void;
/**
 * Helper to set up floating element interactions on connectedCallback.
 *
 * @param component - A floating-ui component.
 * @returns {Promise<void>}
 */
export declare function connectFloatingUI(component: FloatingUIComponent): Promise<void>;
/**
 * Helper to tear down floating element interactions on disconnectedCallback.
 *
 * @param component - A floating-ui component.
 */
export declare function disconnectFloatingUI(component: FloatingUIComponent): void;
/**
 * Default offset the position of the floating element away from the reference element.
 *
 * @default 6
 */
export declare const defaultOffsetDistance: number;
export {};