@wix/design-system/dist/types/PopoverNext/PopoverNext.types.d.ts

@wix/design-system

import React, { type KeyboardEvent } from 'react';
import type { Side, OpenChangeReason, UseRoleProps, Placement } from '@floating-ui/react';
import { type ValuesOf } from '../utils/typeUtils';
import { APPEND_TO } from './PopoverNext.constants';
export type PopoverSkin = 'dark' | 'light';
export type PopoverNextContentProps = React.HTMLProps<HTMLDivElement>;
export type PopoverNextTriggerProps = {
    /**
     * Element to render as the popover trigger.
     *
     * If `children` is a custom React component, it must:
     * - Accept and forward a `ref` to the underlying DOM element for popover positioning.
     * - Pass `aria-*` attributes down to the underlying DOM element for accessibility.
     * - If interactive, must also forward interaction handlers (e.g., `onClick`).
     *
     * If `children` is a native HTML element, no additional requirements are needed.
     */
    children: React.ReactNode;
    /** Specifies a CSS class name to be appended to the component’s root element.
     * @internal
     */
    className?: string;
};
export type Predicate = (el: HTMLElement) => boolean;
export type AppendTo = ValuesOf<typeof APPEND_TO> | Predicate | Element | null;
export type PopoverNextProps = {
    /** Applies a data-hook HTML attribute to the trigger element that can be used in tests. */
    dataHook?: string;
    /** Applies a data-list-type HTML attribute to the content element. */
    dataListType?: string;
    /** Specifies a CSS class name to be appended to the component’s root element.
     * @internal
     */
    className?: string;
    /** <PopoverNext.Trigger /> and <PopoverNext.Content /> components */
    children: React.ReactNode;
    /** Specifies if content is visible.
     * @default false
     */
    open?: boolean;
    /** @deprecated use open instead. */
    shown?: boolean;
    /** Callback to invoke when the content is opened or closed. */
    onOpenChange: (open: boolean, reason?: OpenChangeReason) => void;
    /** onClick on the component. */
    onClick?: React.MouseEventHandler<HTMLElement>;
    /** Specifies if focus is fully trapped inside the content while it is rendered.
     * @internal
     * @default true
     */
    focusManagerEnabled?: boolean;
    /** Provides callback to invoke when clicked outside of the popover */
    onClickOutside?: (event: TouchEvent | MouseEvent) => void;
    /** The classname to be passed to the popover's content container */
    contentClassName?: string;
    /** Specifies the node the popover content will be appended to.
     * @default parent
     */
    appendTo?: AppendTo;
    /** Controls rendering of overlay element, which helps catching click outside events. When 'true' renders a default overlay element. Allows passing custom node to be used as an overlay instead of a default one.
     * @default false
     */
    overlay?: React.ReactNode;
    /**
     * Specifies if the content has a minimum width equal to the trigger element's width.
     * The content can expand up to the specified `maxWidth` value.
     * @default false
     */
    dynamicWidth?: boolean;
    /** Specifies content width. */
    width?: React.CSSProperties['width'];
    /** Specifies content `min-width`. */
    minWidth?: React.CSSProperties['minWidth'];
    /** Specifies content `max-width`. */
    maxWidth?: React.CSSProperties['maxWidth'];
    /** Specifies content `z-index`.
     * @default 1000
     */
    zIndex?: React.CSSProperties['zIndex'];
    /** Popover will not be closed if an element with this class is clicked. */
    excludeClass?: string;
    /** Delay hiding the popover content (ms).
     * @default 0
     * @deprecated use transitionSettings closeDelay
     */
    hideDelay?: number;
    /** Translates the popover content along the specified axes. */
    moveBy?: {
        x?: number;
        y?: number;
    };
    /** Callback to invoke on popover trigger and content mouse enter. */
    onMouseEnter?: React.MouseEventHandler<HTMLDivElement>;
    /** Callback to invoke on popover trigger and content mouse leave. */
    onMouseLeave?: React.MouseEventHandler<HTMLDivElement>;
    /**
     * Whether to enable the flip behaviour. This behaviour is used to flip the `<Popover/>`'s placement
     * when it starts to overlap the trigger element (`<Popover.Trigger/>`).
     * @default true
     */
    flip?: boolean;
    /** Specifies the popover placement relative to the trigger element (`<Popover.Trigger/>`)
     * @default 'bottom'
     */
    placement?: Placement | 'auto' | 'auto-start' | 'auto-end';
    /**
     * To keep the `<Popover/>` at it's
     * original placement even when it's being positioned outside the boundary.
     * @default false
     */
    fixed?: boolean;
    /** Show Delay in ms
     * @deprecated use transitionSettings openDelay
     */
    showDelay?: number;
    /** Animation timer
     * @deprecated use transitionSettings duration
     */
    timeout?: number | {
        enter?: number;
        exit?: number;
    };
    /** Callback to invoke on popover trigger when key is pressed. */
    onKeyDown?: (event: KeyboardEvent) => void;
    /**
     * Components skin value. Can be dark or light.
     * @default light
     */
    skin?: PopoverSkin;
    /** @deprecated use skin instead. */
    theme?: PopoverSkin;
    /** Specifies popover content transitioning. */
    transitionSettings?: {
        /** Open delay in ms */
        openDelay?: number;
        /** Close delay in ms */
        closeDelay?: number;
        /** Transition duration */
        duration?: number | {
            open?: number;
            close?: number;
        };
        /** Handles opacity */
        opacity?: {
            open?: string | number;
            close?: string | number;
        };
        /**
         * overrides calculated side
         * ( top | bottom | left | right)
         */
        transformOrigin?: ((side: Side) => string) | string;
        /**
         * depending on side
         * ( top | bottom | left | right)
         * returns transform value.
         */
        transform?: ((side: Side) => string) | string;
    };
    /** Target element role value */
    role?: UseRoleProps['role'];
    /**
     * Tabindex for popover content element
     */
    tabIndex?: number;
    ['aria-label']?: string;
    ['aria-labelledby']?: string;
    ['aria-describedby']?: string;
    /** Inline style */
    style?: any;
    /** Id */
    id?: string;
    fluid?: boolean;
    /** Adds enter and exit animation
     * @deprecated use transitionSettings
     * @default false
     */
    animate?: boolean;
    /** Callback to invoke when popover is shown */
    onShow?: () => void;
    /** Callback to invoke when popover is hidden */
    onHide?: () => void;
    /** Show arrow for the popover.
     * @default false
     */
    showArrow?: boolean;
    /** Custom arrow element. */
    customArrow?: (placement: PopoverNextProps['placement'], arrowProps: object) => React.ReactNode;
    /** Moves arrow by set amount. */
    moveArrowTo?: number;
    /**
     * Options controlling how the popover keeps its position in sync with
     * the trigger element while it is shown.
     */
    autoUpdateOptions?: {
        /**
         * When `true`, the popover position is recalculated on every
         * `requestAnimationFrame` while the popover is shown. Useful when the
         * trigger element moves due to layout changes that the positioning
         * library does not detect automatically (e.g. animated containers,
         * transform-based motion).
         *
         * Note: enabling this runs a continuous rAF loop for as long as the
         * popover is open, so prefer leaving it off unless you actually need it.
         * @default false
         */
        animationFrame?: boolean;
    };
};
//# sourceMappingURL=PopoverNext.types.d.ts.map