Core Plotting Functions

/**
 * Creates a new plot from scratch
 * @param graphDiv - DOM element ID (string) or element reference
 * @param data - Array of trace objects defining the data and chart types
 * @param layout - Layout object controlling plot appearance (optional)
 * @param config - Configuration object for plot behavior (optional)
 * @returns Promise that resolves to the graph div element
 */
function newPlot(
  graphDiv: string | HTMLElement,
  data: PlotData,
  layout?: Partial<Layout>,
  config?: Partial<Config>
): Promise<HTMLElement>;

import Plotly from 'plotly.js-dist';

// Basic line chart
const data = [{
  x: [1, 2, 3, 4],
  y: [10, 11, 12, 13],
  type: 'scatter',
  mode: 'lines+markers'
}];

const layout = {
  title: 'Sample Line Chart',
  xaxis: { title: 'X Axis' },
  yaxis: { title: 'Y Axis' }
};

await Plotly.newPlot('chart-div', data, layout);

// Multiple traces
const multiData = [
  {
    x: [1, 2, 3, 4],
    y: [10, 11, 12, 13],
    name: 'Series 1',
    type: 'scatter'
  },
  {
    x: [1, 2, 3, 4],
    y: [16, 15, 14, 13],
    name: 'Series 2',
    type: 'scatter'
  }
];

await Plotly.newPlot('multi-chart', multiData, { title: 'Multiple Series' });

/**
 * Smart update function with automatic diffing for optimal performance
 * @param graphDiv - DOM element ID (string) or element reference
 * @param data - Array of trace objects
 * @param layout - Layout object (optional)
 * @param config - Configuration object (optional)
 * @returns Promise that resolves to the graph div element
 */
function react(
  graphDiv: string | HTMLElement,
  data: PlotData,
  layout?: Partial<Layout>,
  config?: Partial<Config>
): Promise<HTMLElement>;

// Initial plot
let currentData = [{
  x: [1, 2, 3],
  y: [4, 5, 6],
  type: 'scatter'
}];

await Plotly.newPlot('chart', currentData);

// Efficient update - only changes what's different
currentData[0].y = [7, 8, 9];
await Plotly.react('chart', currentData);

// Adding a new trace efficiently
currentData.push({
  x: [1, 2, 3],
  y: [1, 2, 3],
  type: 'bar'
});
await Plotly.react('chart', currentData);

/**
 * Forces a complete redraw of an existing plot
 * @param graphDiv - DOM element ID (string) or element reference
 * @returns Promise that resolves to the graph div element
 */
function redraw(graphDiv: string | HTMLElement): Promise<HTMLElement>;

// After external DOM changes that might affect plot
await Plotly.redraw('my-chart');

// After window resize or container changes
window.addEventListener('resize', async () => {
  await Plotly.redraw('responsive-chart');
});

/**
 * Completely removes a plot and cleans up all resources
 * @param graphDiv - DOM element ID (string) or element reference
 * @returns The graph div element
 */
function purge(graphDiv: string | HTMLElement): HTMLElement;

// Clean up before removing from DOM
Plotly.purge('chart-to-remove');
document.getElementById('chart-to-remove').remove();

// Clean up in React componentWillUnmount
componentWillUnmount() {
  if (this.chartRef.current) {
    Plotly.purge(this.chartRef.current);
  }
}

// Plot creation/update events
interface PlotEvents {
  'plotly_afterplot': () => void;
  'plotly_beforeplot': () => void;
  'plotly_plotready': () => void;
}

const chartDiv = document.getElementById('my-chart');

chartDiv.on('plotly_afterplot', () => {
  console.log('Plot rendering complete');
});

chartDiv.on('plotly_plotready', () => {
  console.log('Plot is ready for interaction');
});

await Plotly.newPlot('my-chart', data, layout);

try {
  await Plotly.newPlot('chart', invalidData);
} catch (error) {
  console.error('Plot creation failed:', error.message);
}

// Validate data before plotting
const errors = Plotly.validate(data, layout);
if (errors.length > 0) {
  console.error('Validation errors:', errors);
} else {
  await Plotly.newPlot('chart', data, layout);
}

// Configuration options for core plotting
interface Config {
  displayModeBar?: boolean | 'hover';
  displaylogo?: boolean;
  responsive?: boolean;
  editable?: boolean;
  scrollZoom?: boolean;
  doubleClick?: 'reset' | 'autosize' | 'reset+autosize' | false;
  showTips?: boolean;
  locale?: string;
  modeBarButtons?: string[][];
}

// Basic plot data structure
type PlotData = Array<Partial<PlotlyTrace>>;

interface PlotlyTrace {
  type: string;
  name?: string;
  visible?: boolean | 'legendonly';
  showlegend?: boolean;
  opacity?: number;
  x?: any[];
  y?: any[];
  z?: any[];
  [key: string]: any;
}