import { TooltipComponentProps } from "../Tooltip/Tooltip.types.js";
import { DropdownItems } from "../ButtonWithDropdown/ButtonWithDropdown.types.js";

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

/**
 * Props for the TriggerWithDropdown component that creates a custom trigger with an attached dropdown menu.
 * Extends TooltipComponentProps to support tooltip functionality on the trigger element.
 *
 * Use this component when you need full control over the trigger element's appearance.
 * If you want a standard Qomponents Button as the trigger, use ButtonWithDropdown instead.
 */
type TriggerWithDropdownProps = {
  /**
   * Array of items to display in the dropdown menu.
   * Each item can be interactive (with onClick) or decorative (labels/dividers).
   * Items can also contain sub-menus for hierarchical organization.
   */
  dropdownItems: DropdownItems[];
  /**
   * React element to use as the clickable trigger.
   * Can be any React element — icon, text, custom component, etc.
   */
  triggerIcon: React.ReactNode;
  /**
   * HTML ID attribute for the dropdown trigger element.
   * Should be unique across the page for proper HTML semantics and accessibility.
   */
  id?: string;
  /**
   * Additional CSS classes to apply to the dropdown trigger.
   * Use this to customize the trigger's appearance beyond default styling.
   */
  extraClassNames?: string;
  /**
   * Test ID attribute for the dropdown container element used in automated testing.
   * Applied to the main container that wraps both trigger and dropdown content.
   */
  containerTestId?: string;
  /**
   * Additional CSS classes to apply to the dropdown content container.
   * Use this to customize the dropdown menu's appearance, spacing, or styling.
   */
  contentExtraClassNames?: string;
  /**
   * When true, disables the dropdown trigger preventing user interaction.
   * Disabled triggers appear visually dimmed and don't open the dropdown when clicked.
   */
  disabled?: boolean;
  /**
   * Horizontal alignment of the dropdown content relative to the trigger:
   * - `start`: Aligns to the left edge of the trigger
   * - `center`: Centers the dropdown 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 dropdown further from the trigger in the align direction.
   */
  alignOffset?: number;
  /**
   * Position of the dropdown relative to the trigger element:
   * - `top`: Dropdown appears above the trigger
   * - `bottom`: Dropdown appears below the trigger
   * - `left`: Dropdown appears to the left of the trigger
   * - `right`: Dropdown appears to the right of the trigger
   */
  placement?: 'top' | 'bottom' | 'left' | 'right';
  /**
   * Numeric offset in pixels from the placement position.
   * Positive values move the dropdown further away from the trigger.
   */
  placementOffset?: number;
  /**
   * When true, displays a visual arrow pointing from the dropdown to the trigger.
   * Helps users understand the relationship between trigger and dropdown content.
   */
  hasArrow?: boolean;
  /**
   * Controls whether the dropdown is currently open and visible.
   * Use this for controlled dropdown behavior where you manage open state externally.
   */
  isOpen?: boolean;
  /**
   * Callback function triggered when the dropdown 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, automatically focuses the trigger button when the dropdown closes.
   * Improves keyboard navigation and accessibility by returning focus to the trigger.
   */
  setFocusOnTriggerOnClose?: boolean;
  /**
   * When true, traps keyboard focus within the dropdown when it's open.
   * Prevents users from tabbing outside the dropdown, improving accessibility.
   */
  keepFocusInsideDropdown?: boolean;
  /**
   * Callback function triggered when the dropdown container is clicked.
   * Receives the click event. Use this for handling container-level interactions.
   */
  onContainerClick?: (e: React.MouseEvent<HTMLDivElement>) => void;
} & TooltipComponentProps;
//#endregion
export { TriggerWithDropdownProps };