Chart Creation and Management

/**
 * Create a new chart instance
 * @param options - Chart configuration options
 * @param callback - Optional callback function called when chart is loaded
 * @returns Chart instance
 */
function chart(options: Options, callback?: ChartCallbackFunction): Chart;

/**
 * Create a new chart with explicit container element
 * @param renderTo - Container element ID or DOM element
 * @param options - Chart configuration options  
 * @param callback - Optional callback function called when chart is loaded
 * @returns Chart instance
 */
function chart(renderTo: string | HTMLDOMElement, options: Options, callback?: ChartCallbackFunction): Chart;

type ChartCallbackFunction = (chart: Chart) => void;

import Highcharts from 'highcharts';

// Basic chart creation
const chart = Highcharts.chart({
  chart: { renderTo: 'container' },
  series: [{ data: [1, 2, 3, 4, 5] }]
});

// Chart with explicit container
const chart2 = Highcharts.chart('my-container', {
  title: { text: 'Sales Data' },
  series: [{ name: 'Sales', data: [29.9, 71.5, 106.4] }]
});

// Chart with callback
const chart3 = Highcharts.chart('container', {
  // options
}, function(chart) {
  console.log('Chart loaded with', chart.series.length, 'series');
});

class Chart {
  /**
   * Chart constructor - creates new chart instance
   * @param options - Chart configuration options
   * @param callback - Optional callback when chart is loaded
   */
  constructor(options: Options, callback?: ChartCallbackFunction);
  
  /**
   * Chart constructor with explicit container
   * @param renderTo - Container element ID or DOM element
   * @param options - Chart configuration options
   * @param callback - Optional callback when chart is loaded  
   */
  constructor(renderTo: string | HTMLDOMElement, options: Options, callback?: ChartCallbackFunction);

  /** Array of all series in the chart */
  series: Array<Series>;
  
  /** Array of all axes (x, y, color axes) */
  axes: Array<Axis>;
  
  /** Chart's x-axes */
  xAxis: Array<Axis>;
  
  /** Chart's y-axes */
  yAxis: Array<Axis>;
  
  /** Chart options/configuration */
  options: Options;
  
  /** Chart container element */
  container: HTMLDivElement;
  
  /** Chart rendering area */
  chartBackground: SVGElement;
  
  /** Chart renderer instance */
  renderer: SVGRenderer;
  
  /** Chart legend instance */
  legend: Legend;
  
  /** Chart tooltip instance */
  tooltip: Tooltip;
  
  /** Chart pointer (interaction handler) */
  pointer: Pointer;
}

class Chart {
  /**
   * Redraw the chart after changes
   * @param animation - Animation options for redraw
   */
  redraw(animation?: boolean | AnimationOptionsObject): void;

  /**
   * Update chart options
   * @param options - New chart options to merge
   * @param redraw - Whether to redraw chart immediately
   * @param oneToOne - Whether to merge one-to-one (vs deep merge)
   * @param animation - Animation options for redraw
   */
  update(options: Options, redraw?: boolean, oneToOne?: boolean, animation?: boolean | AnimationOptionsObject): void;

  /**
   * Resize chart to fit container or specific dimensions
   * @param width - New width (null for auto)
   * @param height - New height (null for auto)
   * @param animation - Animation options for resize
   */
  setSize(width?: number | null, height?: number | null, animation?: boolean | AnimationOptionsObject): void;

  /**
   * Reflow chart to fit container size changes
   */
  reflow(): void;

  /**
   * Destroy chart and clean up resources
   */
  destroy(): void;

  /**
   * Check if chart has been destroyed
   * @returns True if chart is destroyed
   */
  isDestroyed(): boolean;
}

class Chart {
  /**
   * Add a new series to the chart
   * @param options - Series configuration options
   * @param redraw - Whether to redraw chart immediately
   * @param animation - Animation options
   * @returns The added series instance
   */
  addSeries(options: SeriesOptionsType, redraw?: boolean, animation?: boolean | AnimationOptionsObject): Series;

  /**
   * Get series by ID or index
   * @param id - Series ID or index
   * @returns Series instance or undefined
   */
  get(id: string | number): Series | Axis | undefined;

  /**
   * Get all series of a specific type
   * @param type - Series type name
   * @returns Array of matching series
   */
  getSeries(type?: string): Array<Series>;
}

class Chart {
  /**
   * Show loading indicator
   * @param str - Loading text (optional)
   */
  showLoading(str?: string): void;

  /**
   * Hide loading indicator
   */
  hideLoading(): void;

  /**
   * Pan the chart by specified amounts
   * @param e - Event object or pan configuration
   * @param originalEvent - Original mouse/touch event
   */
  pan(e: Event | { chartX?: number; chartY?: number }, originalEvent?: Event): void;

  /**
   * Zoom to specific chart area
   * @param event - Zoom event object
   */
  zoom(event?: SelectEventObject): void;

  /**
   * Reset zoom to default view
   */
  zoomOut(): void;
}

class Chart {
  /**
   * Export chart as image or document
   * @param options - Export options (format, filename, etc.)
   * @param chartOptions - Additional chart options for export
   */
  exportChart(options?: ExportingOptions, chartOptions?: Options): void;

  /**
   * Print the chart
   */
  print(): void;

  /**
   * Get chart as SVG string
   * @param chartOptions - Additional chart options for SVG generation
   * @returns SVG string representation
   */
  getSVG(chartOptions?: Options): string;

  /**
   * Download chart as image
   * @param options - Download options
   */
  downloadChart(options?: ExportingOptions): void;
}

// Chart lifecycle management
const chart = Highcharts.chart('container', {
  title: { text: 'Dynamic Chart' },
  series: []
});

// Add series dynamically
chart.addSeries({
  name: 'New Series',
  data: [1, 2, 3, 4, 5]
});

// Update chart options
chart.update({
  title: { text: 'Updated Chart Title' },
  colors: ['#ff0000', '#00ff00', '#0000ff']
});

// Resize chart
chart.setSize(800, 400);

// Export functionality
chart.exportChart({
  type: 'image/png',
  filename: 'my-chart'
});

// Print chart
chart.print();

// Clean up
chart.destroy();

interface ChartOptions {
  /** Chart type - affects default series type */
  type?: string;
  
  /** HTML element ID or DOM element for chart container */
  renderTo?: string | HTMLDOMElement;
  
  /** Chart width in pixels */
  width?: number;
  
  /** Chart height in pixels */
  height?: number;
  
  /** Chart background color */
  backgroundColor?: ColorType;
  
  /** Chart border settings */
  borderColor?: ColorString;
  borderWidth?: number;
  borderRadius?: number;
  
  /** Chart margin settings */
  margin?: Array<number>;
  marginTop?: number;
  marginRight?: number;
  marginBottom?: number;
  marginLeft?: number;
  
  /** Chart spacing settings */
  spacing?: Array<number>;
  spacingTop?: number;
  spacingRight?: number;
  spacingBottom?: number;
  spacingLeft?: number;
  
  /** Chart zoom and pan settings */
  zoomType?: string;
  panKey?: string;
  panning?: boolean | PanningOptions;
  
  /** Animation settings */
  animation?: boolean | AnimationOptionsObject;
  
  /** Responsive design settings */
  reflow?: boolean;
  
  /** Style overrides */
  style?: CSSObject;
  
  /** Chart class name */
  className?: string;
  
  /** 3D chart settings */
  options3d?: Chart3dOptions;
  
  /** Parallel axes configuration */
  parallelAxes?: ParallelAxesOptions;
  
  /** Chart events */
  events?: ChartEventsOptions;
}

interface ChartEventsOptions {
  /** Fired when chart is loaded */
  load?: ChartLoadCallbackFunction;
  
  /** Fired when chart is rendered */
  render?: ChartRenderCallbackFunction;
  
  /** Fired when chart is redrawn */
  redraw?: ChartRedrawCallbackFunction;
  
  /** Fired when chart is clicked */
  click?: ChartClickCallbackFunction;
  
  /** Fired when selection is made */
  selection?: ChartSelectionCallbackFunction;
  
  /** Fired when series is added */
  addSeries?: ChartAddSeriesCallbackFunction;
}

/**
 * Global error handling function
 * @param code - Error code or message
 * @param stop - Whether to stop execution
 * @param chart - Chart instance (if available)
 * @param params - Additional error parameters
 */
function error(code: number | string, stop?: boolean, chart?: Chart, params?: Dictionary<string>): void;

/**
 * Merge objects together, extending target with source properties
 * @param extend - If true, deep merge; if object, serves as target
 * @param sources - Source objects to merge
 * @returns Merged object
 */
function merge<T>(extend: true | T, ...sources: Array<object | undefined>): T;

/**
 * Extend an object with properties from another object
 * @param a - Target object to extend
 * @param b - Source object with properties to add
 * @returns Extended object
 */
function extend<T>(a: T | undefined, b: Partial<T>): T;

/**
 * Pick the first non-null/undefined value from arguments
 * @param items - Values to check
 * @returns First defined value
 */
function pick<T>(...items: Array<T | null | undefined>): T;

/**
 * Convert value to array if not already an array
 * @param obj - Value to convert
 * @returns Array containing the value(s)
 */
function splat(obj: any): any[];

/**
 * Wrap a method with additional functionality
 * @param obj - Object containing the method
 * @param method - Method name to wrap
 * @param func - Wrapper function
 */
function wrap(obj: any, method: string, func: WrapProceedFunction): void;

/**
 * Function type for wrapping methods with proceed callback
 * @param arg1 - First argument passed to proceed
 * @param arg2 - Second argument passed to proceed  
 * @param arg3 - Third argument passed to proceed
 * @returns Return value of the original function
 */
type WrapProceedFunction = (arg1?: any, arg2?: any, arg3?: any) => any;

import Highcharts from 'highcharts';

// Merge configuration objects
const defaultConfig = { chart: { type: 'line' } };
const userConfig = { chart: { width: 800 }, title: { text: 'My Chart' } };
const finalConfig = Highcharts.merge(defaultConfig, userConfig);

// Pick first valid value
const width = Highcharts.pick(chart.options.chart.width, 600, 400);

// Convert to array
const seriesArray = Highcharts.splat(chart.series[0]);

// Extend object safely
const extendedOptions = Highcharts.extend({}, baseOptions);