Chart Management

/**
 * Initialize ECharts instance on a DOM element
 * @param dom - DOM element to render chart in (optional, can be null)
 * @param theme - Theme name or theme object (optional)
 * @param opts - Initialization options (optional)
 * @returns ECharts instance
 */
function init(dom?: HTMLElement | null, theme?: string | ThemeOption, opts?: EChartsInitOpts): EChartsType;

interface EChartsInitOpts {
  /** Device pixel ratio for high-DPI displays */
  devicePixelRatio?: number;
  /** Rendering backend: canvas (default) or svg */
  renderer?: 'canvas' | 'svg';
  /** Initial chart width in pixels */
  width?: number;
  /** Initial chart height in pixels */
  height?: number;
  /** Locale for internationalization */
  locale?: string;
  /** Use UTC time (default: false) */
  useDirtyRect?: boolean;
  /** Use dirty rectangle optimization (default: false) */
  useCoarsePointer?: boolean;
  /** Whether to handle pointer events */
  pointerSize?: number;
  /** SSR mode (server-side rendering) */
  ssr?: boolean;
}

import * as echarts from 'echarts';

// Basic initialization
const chart = echarts.init(document.getElementById('chart-container'));

// With theme and options
const chart = echarts.init(
  document.getElementById('chart-container'),
  'dark',
  { 
    renderer: 'svg',
    devicePixelRatio: 2 
  }
);

interface EChartsType {
  /**
   * Set chart option (configuration)
   * @param option - Chart configuration object
   * @param opts - Configuration options
   */
  setOption(option: EChartsOption, opts?: SetOptionOpts): void;
  
  /**
   * Get current chart option
   * @returns Current chart configuration
   */
  getOption(): EChartsOption;
  
  /**
   * Clear chart content
   */
  clear(): void;
}

interface SetOptionOpts {
  /** Whether to merge with previous option (default: false) */
  notMerge?: boolean;
  /** Array of component keys to replace instead of merge */
  replaceMerge?: string | string[];
  /** Whether to suppress events during update (default: false) */
  silent?: boolean;
}

// Set initial configuration
chart.setOption({
  title: { text: 'My Chart' },
  series: [{ type: 'bar', data: [1, 2, 3] }]
});

// Update configuration (merge by default)
chart.setOption({
  title: { text: 'Updated Chart' }
});

// Replace configuration completely
chart.setOption(newOption, { notMerge: true });

// Get current configuration
const currentOption = chart.getOption();

interface EChartsType {
  /**
   * Resize chart to fit container or specified dimensions
   * @param opts - Resize options
   */
  resize(opts?: ResizeOpts): void;
  
  /**
   * Get chart DOM container element
   * @returns DOM element containing the chart
   */
  getDom(): HTMLElement;
  
  /**
   * Get chart width in pixels
   * @returns Chart width
   */
  getWidth(): number;
  
  /**
   * Get chart height in pixels
   * @returns Chart height
   */
  getHeight(): number;
  
  /**
   * Get ZRender instance (low-level rendering engine)
   * @returns ZRender instance
   */
  getZr(): zrender.ZRenderType;
}

interface ResizeOpts {
  /** New width in pixels */
  width?: number;
  /** New height in pixels */
  height?: number;
  /** Whether to suppress resize event (default: false) */
  silent?: boolean;
}

// Responsive resize
window.addEventListener('resize', () => {
  chart.resize();
});

// Resize to specific dimensions
chart.resize({ width: 800, height: 600 });

// Get chart dimensions
const width = chart.getWidth();
const height = chart.getHeight();

interface EChartsType {
  /**
   * Dispose chart instance and free resources
   */
  dispose(): void;
  
  /**
   * Check if chart instance is disposed
   * @returns True if disposed
   */
  isDisposed(): boolean;
}

/**
 * Dispose chart instance by chart object, DOM element, or element ID
 * @param chart - Chart instance, DOM element, or element ID
 */
function dispose(chart: EChartsType | HTMLElement | string): void;

/**
 * Get chart instance by DOM element
 * @param dom - DOM element containing chart
 * @returns Chart instance or undefined
 */
function getInstanceByDom(dom: HTMLElement): EChartsType | undefined;

/**
 * Get chart instance by element ID
 * @param key - Element ID
 * @returns Chart instance or undefined
 */
function getInstanceById(key: string): EChartsType | undefined;

// Proper cleanup
const chart = echarts.init(document.getElementById('chart'));

// Later, when chart is no longer needed
chart.dispose();

// Or dispose by DOM element
echarts.dispose(document.getElementById('chart'));

// Check if chart exists
const existingChart = echarts.getInstanceByDom(document.getElementById('chart'));
if (existingChart) {
  existingChart.setOption(newOption);
} else {
  const newChart = echarts.init(document.getElementById('chart'));
}

/**
 * Connect multiple charts for synchronized interaction
 * @param groupId - Group identifier or array of chart instances
 * @returns Group identifier
 */
function connect(groupId: string | EChartsType[]): string;

/**
 * Disconnect charts from a group
 * @param groupId - Group identifier
 */
function disconnect(groupId: string): void;

/**
 * Get data URL for all connected charts in a group
 * @param opts - Export options
 * @returns Data URL containing all connected charts
 */
function getConnectedDataURL(opts?: ConnectedDataURLOptions): string;

interface ConnectedDataURLOptions {
  /** Image type (default: 'png') */
  type?: string;
  /** Pixel ratio for high-DPI (default: 1) */
  pixelRatio?: number;
  /** Background color */
  backgroundColor?: string;
  /** Whether to exclude components from export */
  excludeComponents?: string[];
}

// Create multiple charts
const chart1 = echarts.init(document.getElementById('chart1'));
const chart2 = echarts.init(document.getElementById('chart2'));

// Connect charts for synchronized interaction
echarts.connect([chart1, chart2]);

// Or connect with group ID
echarts.connect('myGroup');
chart1.group = 'myGroup';
chart2.group = 'myGroup';

// Export all connected charts
const dataURL = echarts.getConnectedDataURL({
  type: 'png',
  pixelRatio: 2
});

// Disconnect charts
echarts.disconnect('myGroup');

interface EChartsType {
  /**
   * Show loading animation
   * @param name - Loading effect name (optional)
   * @param cfg - Loading configuration (optional)
   */
  showLoading(name?: string, cfg?: LoadingOptions): void;
  
  /**
   * Hide loading animation
   */
  hideLoading(): void;
}

interface LoadingOptions {
  /** Loading text */
  text?: string;
  /** Text color */
  color?: string;
  /** Text size */
  textColor?: string;
  /** Mask color */
  maskColor?: string;
  /** Z-index of loading layer */
  zlevel?: number;
  /** Font size */
  fontSize?: number;
  /** Show spinning effect */
  showSpinner?: boolean;
  /** Spinner radius */
  spinnerRadius?: number;
  /** Line width */
  lineWidth?: number;
  /** Font weight */
  fontWeight?: string;
  /** Font style */
  fontStyle?: string;
  /** Font family */
  fontFamily?: string;
}

// Show default loading
chart.showLoading();

// Show loading with custom text
chart.showLoading('default', {
  text: 'Loading data...',
  color: '#4dabf7',
  textColor: '#000',
  maskColor: 'rgba(255, 255, 255, 0.8)',
  fontSize: 12
});

// Hide loading when data is ready
chart.hideLoading();

interface EChartsType {
  // Core lifecycle methods
  setOption(option: EChartsOption, opts?: SetOptionOpts): void;
  getOption(): EChartsOption;
  resize(opts?: ResizeOpts): void;
  dispose(): void;
  isDisposed(): boolean;
  
  // Display and layout
  getDom(): HTMLElement;
  getWidth(): number;
  getHeight(): number;
  getZr(): zrender.ZRenderType;
  
  // Loading states
  showLoading(name?: string, cfg?: LoadingOptions): void;
  hideLoading(): void;
  
  // Multi-chart properties
  group?: string;
  
  // Additional instance properties and methods covered in other sections
  // (events, data operations, export, etc.)
}

type ThemeOption = {
  color?: string[];
  backgroundColor?: string;
  textStyle?: TextStyleOption;
  [key: string]: any;
};