Interactivity and Events

/**
 * Add event listener to element or class
 * @param el - Target element or constructor
 * @param type - Event type name
 * @param fn - Event handler function
 * @param options - Event options
 * @returns Function to remove the event listener
 */
function addEvent<T>(el: T | Class<T>, type: string, fn: Function | EventCallbackFunction<T>, options?: EventOptionsObject): Function;

/**
 * Fire custom event on element
 * @param el - Target element
 * @param type - Event type name
 * @param eventArguments - Event data object
 * @param defaultFunction - Default handler function
 */
function fireEvent<T>(el: T, type: string, eventArguments?: Event | Dictionary<any>, defaultFunction?: Function | EventCallbackFunction<T>): void;

/**
 * Remove event listener from element
 * @param el - Target element or constructor  
 * @param type - Event type name (optional, removes all if not specified)
 * @param fn - Specific handler function to remove
 */
function removeEvent<T>(el: T | Class<T>, type?: string, fn?: EventCallbackFunction<T>): void;

type EventCallbackFunction<T> = (this: T, ...args: any[]) => any;

interface EventOptionsObject {
  /** Event priority order */
  order?: number;
  
  /** Use passive event listener */
  passive?: boolean;
}

class Pointer {
  /** Chart instance */
  chart: Chart;
  
  /** Currently hovered points */
  hoverPoints: Array<Point>;
  
  /** Currently hovered series */
  hoverSeries: Series;
  
  /** Whether mouse is down */
  isDirectTouch: boolean;
  
  /** Selection rectangle */
  selectionMarker: SVGElement;
  
  /** Chart container element */
  chartContainer: HTMLDivElement;
  
  /**
   * Get coordinates from mouse/touch event
   * @param e - Mouse or touch event
   * @returns Coordinate object with chartX, chartY
   */
  getCoordinates(e: PointerEventObject): PointerEventObject;
  
  /**
   * Find nearest point to coordinates
   * @param series - Series to search in
   * @param kdCompare - Comparison function
   * @returns Nearest point
   */
  findNearestKDPoint(series: Array<Series>, kdCompare?: Function): Point;
  
  /**
   * Run point hover event
   * @param point - Point to hover
   * @param e - Mouse event
   */
  runPointActions(point?: Point, e?: PointerEventObject): void;
  
  /**
   * Reset mouse/touch state
   * @param allowMove - Whether to allow move events
   * @param delay - Reset delay in milliseconds
   */
  reset(allowMove?: boolean, delay?: number): void;
}

interface PointerEventObject {
  /** Chart X coordinate */
  chartX: number;
  
  /** Chart Y coordinate */
  chartY: number;
  
  /** Original event object */
  originalEvent?: Event;
  
  /** Event target element */
  target?: Element;
  
  /** Event type */
  type?: string;
}

class Tooltip {
  /** Chart instance */
  chart: Chart;
  
  /** Tooltip options */
  options: TooltipOptions;
  
  /** Tooltip label element */
  label: SVGElement;
  
  /** Tooltip shared state */
  shared: boolean;
  
  /** Currently shown points */
  points: Array<Point>;
  
  /**
   * Show tooltip for points
   * @param points - Point or array of points
   * @param mouseEvent - Mouse event object
   */
  refresh(points: Point | Array<Point>, mouseEvent?: PointerEventObject): void;
  
  /**
   * Hide tooltip
   * @param delay - Hide delay in milliseconds
   */
  hide(delay?: number): void;
  
  /**
   * Move tooltip to new position
   * @param x - X coordinate
   * @param y - Y coordinate
   * @param isNew - Whether this is a new tooltip
   * @param isInside - Whether cursor is inside plot area
   * @param anchor - Anchor point
   */
  move(x: number, y: number, isNew?: boolean, isInside?: boolean, anchor?: Point): void;
  
  /**
   * Update tooltip options
   * @param options - New tooltip options
   */
  update(options: TooltipOptions): void;
  
  /**
   * Destroy tooltip
   */
  destroy(): void;
}

interface TooltipOptions {
  /** Enable tooltip */
  enabled?: boolean;
  
  /** Tooltip background color */
  backgroundColor?: ColorType;
  
  /** Tooltip border settings */
  borderColor?: ColorString;
  borderWidth?: number;
  borderRadius?: number;
  
  /** Tooltip shadow */
  shadow?: boolean | ShadowOptionsObject;
  
  /** Tooltip CSS styles */
  style?: CSSObject;
  
  /** Tooltip padding */
  padding?: number;
  
  /** Use HTML rendering */
  useHTML?: boolean;
  
  /** Tooltip format string */
  headerFormat?: string;
  pointFormat?: string;
  footerFormat?: string;
  
  /** Tooltip formatter function */
  formatter?: TooltipFormatterCallbackFunction;
  
  /** Tooltip positioner function */
  positioner?: TooltipPositionerCallbackFunction;
  
  /** Whether to share tooltip between series */
  shared?: boolean;
  
  /** Tooltip split behavior */
  split?: boolean;
  
  /** Tooltip follow pointer */
  followPointer?: boolean;
  
  /** Tooltip follow touch move */
  followTouchMove?: boolean;
  
  /** Tooltip sticky behavior */
  stickOnContact?: boolean;
  
  /** Tooltip hide delay */
  hideDelay?: number;
  
  /** Tooltip snap behavior */
  snap?: number;
  
  /** Outside plot area behavior */
  outside?: boolean;
  
  /** Tooltip value decimals */
  valueDecimals?: number;
  
  /** Tooltip value prefix */
  valuePrefix?: string;
  
  /** Tooltip value suffix */
  valueSuffix?: string;
  
  /** Tooltip crosshairs */
  crosshairs?: boolean | Array<boolean | AxisCrosshairOptions>;
  
  /** Animation settings */
  animation?: boolean | AnimationOptionsObject;
}

type TooltipFormatterCallbackFunction = (this: TooltipFormatterContextObject) => string | false;
type TooltipPositionerCallbackFunction = (this: Tooltip, labelWidth: number, labelHeight: number, point: Point) => PositionObject;

interface TooltipFormatterContextObject {
  /** Current point */
  point: Point;
  
  /** Points array (for shared tooltips) */
  points?: Array<Point>;
  
  /** Series */
  series: Series;
  
  /** Point x value */
  x: number;
  
  /** Point y value */
  y: number;
  
  /** Point color */
  color: ColorString;
  
  /** Point key/category */
  key: string | number;
  
  /** Percentage (for pie charts) */
  percentage?: number;
  
  /** Total (for stacked series) */
  total?: number;
}

class Legend {
  /** Chart instance */
  chart: Chart;
  
  /** Legend options */
  options: LegendOptions;
  
  /** Legend box element */
  box: SVGElement;
  
  /** Legend group element */
  group: SVGElement;
  
  /** Legend display state */
  display: boolean;
  
  /** Array of legend items */
  allItems: Array<Series | Point>;
  
  /**
   * Render the legend
   */
  render(): void;
  
  /**
   * Update legend options
   * @param options - New legend options
   */
  update(options: LegendOptions, redraw?: boolean): void;
  
  /**
   * Color up the legend item
   * @param item - Legend item (series or point)
   */
  colorizeItem(item: Series | Point, visible: boolean): void;
  
  /**
   * Position legend items
   */
  positionItems(): void;
  
  /**
   * Destroy legend
   */
  destroy(): void;
}

interface ChartEventsOptions {
  /**
   * Fired when chart is loaded and rendered
   * @param event - Load event object
   */
  load?: ChartLoadCallbackFunction;
  
  /**
   * Fired when chart is rendered
   * @param event - Render event object
   */
  render?: ChartRenderCallbackFunction;
  
  /**
   * Fired when chart is redrawn
   * @param event - Redraw event object
   */
  redraw?: ChartRedrawCallbackFunction;
  
  /**
   * Fired when chart container is clicked
   * @param event - Click event object
   */
  click?: ChartClickCallbackFunction;
  
  /**
   * Fired when chart area is selected
   * @param event - Selection event object
   */
  selection?: ChartSelectionCallbackFunction;
  
  /**
   * Fired when series is added to chart
   * @param event - Add series event object
   */
  addSeries?: ChartAddSeriesCallbackFunction;
  
  /**
   * Fired when chart is drilled down
   * @param event - Drilldown event object
   */
  drilldown?: ChartDrilldownCallbackFunction;
  
  /**
   * Fired when chart is drilled up
   * @param event - Drillup event object
   */
  drillup?: ChartDrillupCallbackFunction;
  
  /**
   * Fired when chart enters fullscreen
   * @param event - Fullscreen event object
   */
  fullscreenOpen?: ChartFullscreenCallbackFunction;
  
  /**
   * Fired when chart exits fullscreen
   * @param event - Fullscreen event object
   */
  fullscreenClose?: ChartFullscreenCallbackFunction;
}

type ChartLoadCallbackFunction = (this: Chart, event: Event) => void;
type ChartRenderCallbackFunction = (this: Chart, event: Event) => void;
type ChartRedrawCallbackFunction = (this: Chart, event: Event) => void;
type ChartClickCallbackFunction = (this: Chart, event: PointerEventObject) => void;
type ChartSelectionCallbackFunction = (this: Chart, event: SelectEventObject) => boolean | undefined;
type ChartAddSeriesCallbackFunction = (this: Chart, event: ChartAddSeriesEventObject) => void;

interface SeriesEventsOptions {
  /**
   * Fired when series animation is complete
   * @param event - Animation event object
   */
  afterAnimate?: SeriesEventCallbackFunction;
  
  /**
   * Fired when legend checkbox is clicked
   * @param event - Checkbox event object
   */
  checkboxClick?: SeriesCheckboxClickCallbackFunction;
  
  /**
   * Fired when series is clicked
   * @param event - Click event object
   */
  click?: SeriesClickCallbackFunction;
  
  /**
   * Fired when series is hidden
   * @param event - Hide event object
   */
  hide?: SeriesEventCallbackFunction;
  
  /**
   * Fired when series is shown
   * @param event - Show event object
   */
  show?: SeriesEventCallbackFunction;
  
  /**
   * Fired when mouse enters series
   * @param event - Mouse event object
   */
  mouseOver?: SeriesEventCallbackFunction;
  
  /**
   * Fired when mouse leaves series
   * @param event - Mouse event object
   */
  mouseOut?: SeriesEventCallbackFunction;
  
  /**
   * Fired when series legend item is clicked
   * @param event - Legend click event object
   */
  legendItemClick?: SeriesLegendItemClickCallbackFunction;
}

type SeriesEventCallbackFunction = (this: Series, event?: Event) => void;
type SeriesClickCallbackFunction = (this: Series, event: SeriesClickEventObject) => void;
type SeriesCheckboxClickCallbackFunction = (this: Series, event: SeriesCheckboxClickEventObject) => void;
type SeriesLegendItemClickCallbackFunction = (this: Series, event: SeriesLegendItemClickEventObject) => boolean | undefined;

interface PointEventsOptions {
  /**
   * Fired when point is clicked
   * @param event - Click event object
   */
  click?: PointClickCallbackFunction;
  
  /**
   * Fired when mouse enters point
   * @param event - Mouse event object
   */
  mouseOver?: PointEventCallbackFunction;
  
  /**
   * Fired when mouse leaves point
   * @param event - Mouse event object
   */
  mouseOut?: PointEventCallbackFunction;
  
  /**
   * Fired when point is removed
   * @param event - Remove event object
   */
  remove?: PointEventCallbackFunction;
  
  /**
   * Fired when point is selected
   * @param event - Select event object
   */
  select?: PointSelectCallbackFunction;
  
  /**
   * Fired when point is unselected
   * @param event - Unselect event object
   */
  unselect?: PointEventCallbackFunction;
  
  /**
   * Fired when point is updated
   * @param event - Update event object
   */
  update?: PointEventCallbackFunction;
  
  /**
   * Fired when point is dragged
   * @param event - Drag event object
   */
  drag?: PointDragCallbackFunction;
  
  /**
   * Fired when point drag ends
   * @param event - Drop event object
   */
  drop?: PointDropCallbackFunction;
}

type PointEventCallbackFunction = (this: Point, event?: Event) => void;
type PointClickCallbackFunction = (this: Point, event: PointClickEventObject) => void;
type PointSelectCallbackFunction = (this: Point, event: PointSelectEventObject) => void;
type PointDragCallbackFunction = (this: Point, event: PointDragEventObject) => void;
type PointDropCallbackFunction = (this: Point, event: PointDropEventObject) => void;

interface ChartOptions {
  /** Zoom type configuration */
  zoomType?: ZoomTypeValue; // 'x' | 'y' | 'xy'
  
  /** Pan key modifier */
  panKey?: PanKeyValue; // 'shift' | 'ctrl' | 'alt' | 'meta'
  
  /** Panning configuration */
  panning?: boolean | PanningOptions;
  
  /** Zoom reset button */
  resetZoomButton?: ResetZoomButtonOptions;
}

interface PanningOptions {
  /** Enable panning */
  enabled?: boolean;
  
  /** Panning type */
  type?: string; // 'x' | 'y' | 'xy'
}

interface ResetZoomButtonOptions {
  /** Button position */
  position?: AlignObject;
  
  /** Button theme */
  theme?: SVGAttributes;
  
  /** Relative to plot area or spacing box */
  relativeTo?: ButtonRelativeToValue;
}

type ZoomTypeValue = 'x' | 'y' | 'xy';
type PanKeyValue = 'shift' | 'ctrl' | 'alt' | 'meta';

interface SelectEventObject {
  /** Selection x-axis extremes */
  xAxis?: Array<ExtremesObject>;
  
  /** Selection y-axis extremes */
  yAxis?: Array<ExtremesObject>;
  
  /** Original mouse event */
  originalEvent?: Event;
  
  /** Prevent default selection behavior */
  preventDefault(): void;
  
  /** Reset selection */
  resetSelection(): void;
}

interface ExtremesObject {
  /** Axis instance */
  axis: Axis;
  
  /** Selection minimum value */
  min: number;
  
  /** Selection maximum value */
  max: number;
}

// Chart with comprehensive event handling
const interactiveChart = Highcharts.chart('container', {
  chart: {
    zoomType: 'xy',
    events: {
      load: function() {
        console.log('Chart loaded');
      },
      selection: function(event) {
        if (event.xAxis) {
          console.log('Selected X range:', event.xAxis[0].min, event.xAxis[0].max);
        }
        return true; // Allow selection
      },
      click: function(event) {
        console.log('Chart clicked at:', event.chartX, event.chartY);
      }
    }
  },
  
  tooltip: {
    shared: true,
    formatter: function() {
      let tooltip = '<b>' + this.x + '</b><br/>';
      this.points.forEach(function(point) {
        tooltip += point.series.name + ': ' + point.y + '<br/>';
      });
      return tooltip;
    }
  },
  
  plotOptions: {
    series: {
      point: {
        events: {
          click: function() {
            alert('Point clicked: ' + this.y);
          },
          mouseOver: function() {
            this.series.chart.renderer.text(
              'Hovering point: ' + this.y,
              100, 50
            ).add();
          }
        }
      },
      events: {
        mouseOver: function() {
          this.update({ color: '#ff0000' });
        },
        mouseOut: function() {
          this.update({ color: null });
        },
        legendItemClick: function() {
          return confirm('Toggle series visibility?');
        }
      }
    }
  },
  
  series: [{
    name: 'Interactive Series',
    data: [29.9, 71.5, 106.4, 129.2, 144.0, 176.0],
    allowPointSelect: true,
    cursor: 'pointer'
  }]
});

// Custom event handling
addEvent(interactiveChart, 'render', function() {
  console.log('Chart rendered');
});

// Dynamic tooltip updates
interactiveChart.tooltip.update({
  backgroundColor: '#000000',
  style: { color: '#ffffff' }
});

// Programmatic zoom
interactiveChart.xAxis[0].setExtremes(1, 4);

// Custom point selection
interactiveChart.series[0].data[0].select(true);