import { TooltipComponentProps } from "../Tooltip/Tooltip.types.js";
import React from "react";

//#region src/ButtonWithPopover/ButtonWithPopover.types.d.ts

/**
 * Props for the ButtonWithPopover component that creates a button with an attached popover.
 * Extends TooltipComponentProps to support tooltip functionality on the trigger button.
 */
type ButtonWithPopoverProps = {
  /**
   * React element to use as the clickable trigger for the popover.
   * Can be an icon, text, button, or any interactive element that users click to open the popover.
   */
  trigger?: React.ReactNode;
  /**
   * Content to display inside the popover when it's open.
   * Can be any React elements including forms, lists, complex layouts, or interactive components.
   */
  children: React.ReactNode;
  /**
   * HTML ID attribute for the popover trigger element.
   * Should be unique across the page for proper HTML semantics and accessibility.
   */
  id?: string;
  /**
   * Test ID attribute for the popover container element used in automated testing.
   * Applied to the main container that wraps both trigger and popover content.
   */
  containerTestId?: string;
  /**
   * When true, disables the popover trigger preventing user interaction.
   * Disabled triggers appear visually dimmed and don't open the popover when clicked.
   */
  disabled?: boolean;
  /**
   * Callback function triggered when the trigger is clicked.
   * Receives the current open state as a parameter. Note: this doesn't control popover opening,
   * it's mainly for tracking or analytics purposes.
   */
  onClick?: (isOpen: boolean) => void;
  /**
   * Horizontal alignment of the popover content relative to the trigger:
   * - `start`: Aligns to the left edge of the trigger
   * - `center`: Centers the popover on the trigger
   * - `end`: Aligns to the right edge of the trigger
   */
  align?: 'start' | 'center' | 'end';
  /**
   * Numeric offset in pixels from the aligned position.
   * Positive values move the popover further from the trigger in the align direction.
   */
  alignOffset?: number;
  /**
   * Position of the popover relative to the trigger element:
   * - `top`: Popover appears above the trigger
   * - `bottom`: Popover appears below the trigger
   * - `left`: Popover appears to the left of the trigger
   * - `right`: Popover appears to the right of the trigger
   */
  placement?: 'top' | 'bottom' | 'left' | 'right';
  /**
   * Numeric offset in pixels from the placement position.
   * Positive values move the popover further away from the trigger.
   */
  placementOffset?: number;
  /**
   * Controls whether the popover is currently open and visible.
   * Use this for controlled popover behavior where you manage open state externally.
   */
  isOpen?: boolean;
  /**
   * Callback function triggered when the popover open state changes.
   * Receives the new open state as a boolean parameter. Use this to sync with external state.
   */
  onOpenChange?: (isOpen: boolean) => void;
  /**
   * When true, displays a visual arrow pointing from the popover to the trigger.
   * Helps users understand the relationship between trigger and popover content.
   */
  hasArrow?: boolean;
  /**
   * When true, enables the popover to open when hovering over the trigger.
   * Useful for preview or quick-info popovers that don't require clicking.
   */
  isHoverEnabled?: boolean;
  /**
   * Delay in milliseconds before the popover opens when hover is enabled.
   * Prevents accidental popover opening from brief mouse movements.
   * Only relevant when `isHoverEnabled` is true.
   */
  hoverOpenDelay?: number;
  /**
   * Additional CSS classes to apply to the trigger container element.
   * Use this to customize the trigger's appearance beyond default styling.
   */
  extraTriggerClassNames?: string;
  /**
   * Additional CSS classes to apply to the popover content container.
   * Use this to customize the popover's appearance, spacing, or styling.
   */
  extraPopoverClassNames?: string;
  /**
   * When true, automatically closes the popover when any content inside it is clicked.
   * Useful for action popovers where selecting an option should close the popover.
   */
  isCloseOnContentClick?: boolean;
  /**
   * Callback function triggered when user interacts outside the popover content.
   * This includes clicks, taps, and focus events outside the popover area.
   * Use this to handle outside interactions or implement custom close behavior.
   */
  onInteractOutside?: () => void;
  /**
   * Callback function triggered when user clicks/taps outside the popover content.
   * More specific than `onInteractOutside`, focusing only on pointer down events.
   * Use this for custom outside-click handling.
   */
  onPointerDownOutside?: () => void;
  /**
   * When true, merges the trigger functionality with the provided trigger element.
   * Instead of wrapping the trigger in a button, it adds trigger behavior to the element itself.
   * Useful when the trigger element is already interactive.
   */
  isTriggerAsChild?: boolean;
  /**
   * When true, makes the trigger button expand to fill the full width of its container.
   * Useful for layout consistency or when the trigger should span the available space.
   */
  shouldTriggerFullWidth?: boolean;
  /**
   * When true, renders the popover content in a React portal.
   * This moves the popover to the end of the document body, which can help with
   * z-index issues and ensure the popover appears above other content.
   */
  isPortal?: boolean;
  /**
   * When true, hides the popover when the trigger element is scrolled out of view
   * or when scrolling occurs in any ancestor container.
   * This prevents the popover from appearing detached from its trigger during scroll.
   */
  hideWhenDetached?: boolean;
} & TooltipComponentProps;
//#endregion
export { ButtonWithPopoverProps };