Main Tooltip Component

/**
 * Main tooltip component providing comprehensive tooltip functionality
 * @param props - Configuration options for the tooltip
 * @returns React component with forwardRef support
 */
function Tooltip(props: ITooltipController): React.ReactElement;

interface ITooltipController {
  /** Unique identifier for the tooltip (required) */
  id?: string;
  /** CSS class name for the tooltip container */
  className?: string;
  /** CSS class name for the tooltip arrow */
  classNameArrow?: string;
  /** Text content for the tooltip */
  content?: string;
  /** HTML content (deprecated, use children or render instead) */
  html?: string;
  /** Custom render function for dynamic content */
  render?: (render: { content: string | null; activeAnchor: HTMLElement | null }) => ChildrenType;
  /** Tooltip placement position */
  place?: PlacesType;
  /** Distance from anchor element in pixels */
  offset?: number;
  /** Visual theme variant */
  variant?: VariantType;
  /** CSS selector for anchor elements */
  anchorSelect?: string;
  /** ID of anchor element (deprecated, use anchorSelect or data-tooltip-id) */
  anchorId?: string;
  /** HTML wrapper element type */
  wrapper?: WrapperType;
  /** React children content */
  children?: ChildrenType;
  /** Event types to trigger tooltip (deprecated, use openEvents/closeEvents) */
  events?: EventsType[];
  /** Open tooltip on click instead of hover */
  openOnClick?: boolean;
  /** Positioning strategy: absolute or fixed */
  positionStrategy?: PositionStrategy;
  /** Floating UI middleware for advanced positioning */
  middlewares?: Middleware[];
  /** Delay before showing tooltip in milliseconds */
  delayShow?: number;
  /** Delay before hiding tooltip in milliseconds */
  delayHide?: number;
  /** Allow tooltip to float and follow cursor */
  float?: boolean;
  /** Hide tooltip completely */
  hidden?: boolean;
  /** Disable arrow display */
  noArrow?: boolean;
  /** Allow tooltip content to be clickable */
  clickable?: boolean;
  /** Close on Escape key (deprecated, use globalCloseEvents) */
  closeOnEsc?: boolean;
  /** Close on scroll (deprecated, use globalCloseEvents) */
  closeOnScroll?: boolean;
  /** Close on window resize (deprecated, use globalCloseEvents) */
  closeOnResize?: boolean;
  /** Events to open tooltip on anchor elements */
  openEvents?: AnchorOpenEvents;
  /** Events to close tooltip on anchor elements */
  closeEvents?: AnchorCloseEvents;  
  /** Global events that close the tooltip */
  globalCloseEvents?: GlobalCloseEvents;
  /** Disable default behavior for manual control only */
  imperativeModeOnly?: boolean;
  /** Inline CSS styles */
  style?: CSSProperties;
  /** Fixed position coordinates */
  position?: IPosition;
  /** Controlled open state */
  isOpen?: boolean;
  /** Default open state for uncontrolled usage */
  defaultIsOpen?: boolean;
  /** Disable CSS injection (true, false, or 'core') */
  disableStyleInjection?: boolean | 'core';
  /** Border styling (width > 3px may break arrow positioning) */
  border?: CSSProperties['border'];
  /** Tooltip opacity */
  opacity?: CSSProperties['opacity'];
  /** Arrow background color */
  arrowColor?: CSSProperties['backgroundColor'];
  /** Arrow size in pixels */
  arrowSize?: number;
  /** State setter function for controlled usage */
  setIsOpen?: (value: boolean) => void;
  /** Callback after tooltip shows */
  afterShow?: () => void;
  /** Callback after tooltip hides */
  afterHide?: () => void;
  /** Function to conditionally disable tooltip */
  disableTooltip?: (anchorRef: HTMLElement | null) => boolean;
  /** ARIA role for accessibility */
  role?: React.AriaRole;
}

import { Tooltip } from "react-tooltip";

// Basic declarative usage
<div>
  <button data-tooltip-id="basic" data-tooltip-content="Basic tooltip">
    Hover me
  </button>
  <Tooltip id="basic" />
</div>

// Advanced configuration
<div>
  <button data-tooltip-id="advanced" data-tooltip-content="Advanced tooltip">
    Hover me  
  </button>
  <Tooltip 
    id="advanced"
    place="top"
    variant="success"
    offset={15}
    delayShow={500}
    delayHide={200}
    clickable
    noArrow
    style={{ fontSize: '14px' }}
  />
</div>

// Custom content with render function
<div>
  <span data-tooltip-id="custom">Custom content</span>
  <Tooltip 
    id="custom"
    render={({ content, activeAnchor }) => (
      <div>
        <strong>{content}</strong>
        <br />
        <small>Element: {activeAnchor?.tagName}</small>
      </div>
    )}
  />
</div>

/**
 * Ref interface for programmatic tooltip control
 */
interface TooltipRefProps {
  /** Programmatically open the tooltip */
  open: (options?: TooltipImperativeOpenOptions) => void;
  /** Programmatically close the tooltip */  
  close: (options?: TooltipImperativeCloseOptions) => void;
  /** Currently active anchor element (readonly) */
  readonly activeAnchor: HTMLElement | null;
  /** Current placement position (readonly) */
  readonly place: PlacesType;
  /** Current open state (readonly) */
  readonly isOpen: boolean;
}

interface TooltipImperativeOpenOptions {
  /** CSS selector for anchor elements */
  anchorSelect?: string;
  /** Fixed position coordinates */
  position?: IPosition;
  /** Placement position */
  place?: PlacesType;
  /** Content to display */
  content?: ChildrenType;
  /** Delay before opening in milliseconds */
  delay?: number;
}

interface TooltipImperativeCloseOptions {
  /** Delay before closing in milliseconds */
  delay?: number;
}

import { useRef } from 'react';
import { Tooltip, type TooltipRefProps } from 'react-tooltip';

function MyComponent() {
  const tooltipRef = useRef<TooltipRefProps>(null);
  
  const handleShowTooltip = () => {
    tooltipRef.current?.open({
      anchorSelect: '#my-button',
      content: 'Programmatically opened!',
      place: 'top'
    });
  };
  
  const handleHideTooltip = () => {
    tooltipRef.current?.close({ delay: 1000 });
  };
  
  return (
    <div>
      <button id="my-button">Target Element</button>
      <button onClick={handleShowTooltip}>Show Tooltip</button>
      <button onClick={handleHideTooltip}>Hide Tooltip</button>
      
      <Tooltip 
        id="imperative-tooltip"
        ref={tooltipRef}
        imperativeModeOnly
      />
    </div>
  );
}

interface AnchorOpenEvents {
  mouseenter?: boolean;
  focus?: boolean;
  mouseover?: boolean;
  click?: boolean;
  dblclick?: boolean;
  mousedown?: boolean;
}

interface AnchorCloseEvents {
  mouseleave?: boolean;
  blur?: boolean;
  mouseout?: boolean;
  click?: boolean;
  dblclick?: boolean;
  mouseup?: boolean;
}

interface GlobalCloseEvents {
  escape?: boolean;
  scroll?: boolean;
  resize?: boolean;
  clickOutsideAnchor?: boolean;
}

// Custom event configuration
<Tooltip 
  id="custom-events"
  openEvents={{ click: true, focus: true }}
  closeEvents={{ blur: true }}
  globalCloseEvents={{ escape: true, clickOutsideAnchor: true }}
/>

// Click-to-toggle behavior
<Tooltip 
  id="click-toggle"
  openEvents={{ click: true }}
  closeEvents={{ click: true }}
  globalCloseEvents={{ clickOutsideAnchor: true }}
/>

// Extended HTMLAttributes interface
interface HTMLAttributes<T> {
  'data-tooltip-id'?: string;
  'data-tooltip-place'?: PlacesType;
  'data-tooltip-content'?: string | null;
  'data-tooltip-html'?: string | null;
  'data-tooltip-variant'?: VariantType;
  'data-tooltip-offset'?: number;
  'data-tooltip-wrapper'?: WrapperType;
  'data-tooltip-events'?: EventsType[];
  'data-tooltip-position-strategy'?: PositionStrategy;
  'data-tooltip-delay-show'?: number;
  'data-tooltip-delay-hide'?: number;
  'data-tooltip-float'?: boolean;
  'data-tooltip-hidden'?: boolean;
  'data-tooltip-class-name'?: string;
}

<!-- Basic data attributes -->
<button 
  data-tooltip-id="data-example"
  data-tooltip-content="Hello from data attributes!"
  data-tooltip-place="bottom"
  data-tooltip-variant="success"
>
  Hover me
</button>

<!-- Advanced data attributes -->
<span
  data-tooltip-id="advanced-data"
  data-tooltip-content="Advanced configuration"
  data-tooltip-delay-show="500"
  data-tooltip-delay-hide="200"
  data-tooltip-offset="15"
  data-tooltip-class-name="custom-tooltip"
>
  Advanced example
</span>

type WrapperType = ElementType | 'div' | 'span';
type ChildrenType = Element | ElementType | ReactNode;
type Middleware = any; // Floating UI middleware type