ws.charts

add(config: ChartConfig): Promise<string>;

Add a chart to the sheet. Returns the chart ID.

get(chartId: string): Promise<Chart | null>;

Get a chart by ID, or null if not found.

update(chartId: string, updates: Partial<ChartConfig>): Promise<void>;

Update a chart's configuration.

remove(chartId: string): Promise<void>;

Remove a chart by ID.

list(): Promise<Chart[]>;

List all charts in the sheet.

duplicate(chartId: string): Promise<string>;

Duplicate a chart, offsetting the copy by 2 rows. Returns the new chart ID.

exportImage(chartId: string, options?: ImageExportOptions): Promise<string>;

Export a chart as an image. Note: This is a stub — actual rendering requires a canvas context. The bridge integration will be wired in Wave 4.

setDataRange(chartId: string, range: string): Promise<void>;

Set a chart's data range (A1 notation).

setType(chartId: string, type: ChartType, subType?: string): Promise<void>;

Set a chart's type and optional sub-type.

getCount(): Promise<number>;

Get the total number of charts on this sheet.

getByName(name: string): Promise<Chart | null>;

Find a chart by its name, or null if not found.

bringToFront(chartId: string): Promise<void>;

Bring a chart to the front (highest z-index).

sendToBack(chartId: string): Promise<void>;

Send a chart to the back (lowest z-index).

bringForward(chartId: string): Promise<void>;

Bring a chart forward by one layer.

sendBackward(chartId: string): Promise<void>;

Send a chart backward by one layer.

linkToTable(chartId: string, tableId: string): Promise<void>;

Link a chart to a table so it auto-updates with the table's data.

unlinkFromTable(chartId: string): Promise<void>;

Unlink a chart from its source table.

isLinkedToTable(chartId: string): Promise<boolean>;

Check whether a chart is linked to a table.

addSeries(chartId: string, config: SeriesConfig): Promise<number>;

Add a data series to a chart. Returns the new series index.

removeSeries(chartId: string, index: number): Promise<void>;

Remove a data series by index.

getSeries(chartId: string, index: number): Promise<SeriesConfig>;

Get a data series by index.

updateSeries(chartId: string, index: number, updates: Partial<SeriesConfig>): Promise<void>;

Update a data series at the given index.

getSeriesCount(chartId: string): Promise<number>;

Get the number of data series in a chart.

reorderSeries(chartId: string, fromIndex: number, toIndex: number): Promise<void>;

Reorder a series from one index to another.

setSeriesValues(chartId: string, index: number, range: string): Promise<void>;

Set the values range for a series (A1 notation).

setSeriesCategories(chartId: string, index: number, range: string): Promise<void>;

Set the categories range for a series (A1 notation).

formatPoint(
    chartId: string,
    seriesIndex: number,
    pointIndex: number,
    format: { fill?: string; border?: ChartBorder },
  ): Promise<void>;

Format an individual data point within a series.

setPointDataLabel(
    chartId: string,
    seriesIndex: number,
    pointIndex: number,
    config: DataLabelConfig,
  ): Promise<void>;

Set the data label configuration for an individual data point.

addTrendline(
    chartId: string,
    seriesIndex: number,
    config: TrendlineConfig,
  ): Promise<number>;

Add a trendline to a series. Returns the new trendline index.

removeTrendline(
    chartId: string,
    seriesIndex: number,
    trendlineIndex: number,
  ): Promise<void>;

Remove a trendline from a series by index.

getTrendline(
    chartId: string,
    seriesIndex: number,
    trendlineIndex: number,
  ): Promise<TrendlineConfig | null>;

Get a trendline configuration by index, or null if not found.

getTrendlineCount(chartId: string, seriesIndex: number): Promise<number>;

Get the number of trendlines on a series.

getDataTable(chartId: string): Promise<DataTableConfig | null>;

Get the chart's data table configuration, or null if none.

getItemAt(index: number): Promise<Chart | null>;

Get a chart by its positional index, or null if out of range.

setBubbleSizes(chartId: string, seriesIndex: number, range: string): Promise<void>;

Set the bubble sizes range for a series (A1 notation).

onActivated(handler: (args: { chartId: string }) => void): { dispose(): void };

Register a handler for chart activation events. Returns a disposable.

onDeactivated(handler: (args: { chartId: string }) => void): { dispose(): void };

Register a handler for chart deactivation events. Returns a disposable.

getAxisItem(
    chartId: string,
    type: 'category' | 'value' | 'series',
    group: 'primary' | 'secondary',
  ): Promise<SingleAxisConfig | null>;

Get an axis by OfficeJS type/group identifiers.

setAxisTitle(chartId: string, axisType: 'category' | 'value', formula: string): Promise<void>;

Set axis title from a formula string.

setCategoryNames(chartId: string, range: string): Promise<void>;

Set category axis labels from a cell range (A1 notation).

getSeriesDimensionValues(
    chartId: string,
    seriesIndex: number,
    dimension: ChartSeriesDimension,
  ): Promise<(string | number)[]>;

Get computed values for a series dimension.

getSeriesDimensionDataSourceString(
    chartId: string,
    seriesIndex: number,
    dimension: ChartSeriesDimension,
  ): Promise<string>;

Get the range/formula string for a series dimension.

getSeriesDimensionDataSourceType(
    chartId: string,
    seriesIndex: number,
    dimension: ChartSeriesDimension,
  ): Promise<string>;

Get the data source type for a series dimension ('range' | 'literal' | 'formula').

getDataLabelSubstring(
    chartId: string,
    seriesIndex: number,
    pointIndex: number,
    start: number,
    length: number,
  ): Promise<ChartFormatString>;

Get a rich text substring from a data label.

setDataLabelHeight(
    chartId: string,
    seriesIndex: number,
    pointIndex: number,
    value: number,
  ): Promise<void>;

Set the height of a data label.

setDataLabelWidth(
    chartId: string,
    seriesIndex: number,
    pointIndex: number,
    value: number,
  ): Promise<void>;

Set the width of a data label.

getDataLabelTailAnchor(
    chartId: string,
    seriesIndex: number,
    pointIndex: number,
  ): Promise<{ row: number; col: number }>;

Get the tail anchor point for a data label's leader line.

setTitleFormula(chartId: string, formula: string): Promise<void>;

Set chart title from a formula string.

getTitleSubstring(chartId: string, start: number, length: number): Promise<ChartFormatString>;

Get a rich text substring from the chart title.

activate(chartId: string): Promise<void>;

Activate (select + focus) a chart. Emits 'chart:selected' event and scrolls chart into view.