# Charts

Spreadsheet ships a rich chart pipeline with full XLSX + ODS round-trip on every supported chart type. The render backend is ECharts by default; Plotly is available as an opt-in (`@rowsncolumns/charts/plotly/basic-chart`).

## Supported chart types

All round-trip via XLSX import + export unless noted.

| Type                         | Notes                                                                                                                                 |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| Column (clustered / stacked) |                                                                                                                                       |
| Bar (clustered / stacked)    |                                                                                                                                       |
| Line (smooth / stepped)      |                                                                                                                                       |
| Area                         |                                                                                                                                       |
| Pie / doughnut               |                                                                                                                                       |
| Scatter                      |                                                                                                                                       |
| Bubble                       | Size dimension on top of scatter                                                                                                      |
| Radar                        |                                                                                                                                       |
| Treemap                      |                                                                                                                                       |
| Sunburst                     |                                                                                                                                       |
| Stock (line-derived)         | OHLC / candlestick variants deferred                                                                                                  |
| Waterfall                    | Emitted as `c15:waterfallChart` in `mc:Choice` + `c:barChart` fallback — Excel 2016+ renders natively, older Excel falls back to bars |
| Funnel                       | Same `c15:funnelChart` / fallback shape                                                                                               |
| Histogram                    | Auto/Sturges binning + bin-count override                                                                                             |
| Box & whisker                | quartileMethod, showMean, showOutlier                                                                                                 |
| Combo (mixed series)         | Per-series `seriesChartType` picker                                                                                                   |
| Dual-axis                    | `secondaryValueAxisOptions` round-trips                                                                                               |

Not yet supported: 3D variants (bar3D / column3D / pie3D / line3D / area3D), surface, OHLC / candlestick stock. These need `echarts-gl` and are deferred.

## Chart features

Every chart supports:

* **Titles, legends, axis labels** — formula-driven titles & labels (range references resolved at render)
* **Data labels** — value / category / percent
* **Trendlines** — linear, polynomial, exponential, log
* **Error bars** — value / percentage / stdev / custom
* **Data label styles** — number formats applied per series
* **Series colors** — per series + theme accents
* **Series gradient fills** — linear (with `degree`) and path (with `left`/`right`/`top`/`bottom` insets). Mirrors OOXML `<a:gradFill>` inside `<c:spPr>`. Set `series[].gradient` on the chart spec.
* **Negative-value coloring** — `invertIfNegative` + `negativeColor` on bar/column series
* **Chart move + resize** with anchor cell + pixel offsets
* **Chart editing UI** — `ChartEditorDialog` + `ChartEditor` components

## Installation

```bash
npm install @rowsncolumns/charts
```

ECharts is a peer dependency for the default backend:

```bash
npm install echarts echarts-for-react
```

For Plotly:

```bash
npm install @rowsncolumns/charts plotly.js react-plotly.js
```

## Basic usage

Wire charts through the `useCharts` hook (`@rowsncolumns/charts`) and pass the resulting handlers to `CanvasGrid`:

```tsx
import { useCharts, ChartEditorDialog, ChartEditor } from "@rowsncolumns/charts";

const App = () => {
  const [charts, onChangeCharts] = useState<EmbeddedChart[]>([]);

  const {
    onRequestEditChart,
    onDeleteChart,
    onMoveChart,
    onResizeChart,
    onUpdateChart,
    onCreateChart,
    selectedChart,
  } = useCharts({
    createHistory,
    onChangeCharts,
    getFormattedValue,
    getEffectiveValue,
  });

  return (
    <SpreadsheetProvider>
      <CanvasGrid
        charts={charts}
        onMoveChart={onMoveChart}
        onResizeChart={onResizeChart}
        onDeleteChart={onDeleteChart}
        onRequestEditChart={onRequestEditChart}
      />
      <ChartEditorDialog>
        <ChartEditor
          chart={selectedChart}
          onUpdate={onUpdateChart}
        />
      </ChartEditorDialog>
    </SpreadsheetProvider>
  );
};
```

## Series gradient fills

Set `gradient` on any series — overrides `color`:

```ts
const chart: EmbeddedChart = {
  chartId: "c1",
  position: { /* … */ },
  spec: {
    chartType: "column",
    title: "Q1 Sales",
    domains: [{ sources: [/* category range */] }],
    series: [
      {
        dataLabel: "Revenue",
        gradient: {
          type: "linear",
          degree: 90,
          stops: [
            { position: 0, color: "#fde68a" },
            { position: 1, color: "#dc2626" },
          ],
        },
        sources: [/* value range */],
      },
    ],
  },
};
```

For radial fills use `type: "path"` with `left` / `right` / `top` / `bottom` insets (0..1 each):

```ts
gradient: {
  type: "path",
  left: 0.5,
  right: 0.5,
  top: 0.5,
  bottom: 0.5,
  stops: [
    { position: 0, color: "#ffffff" },
    { position: 1, color: "#7c3aed" },
  ],
}
```

ODS export emits the equivalent `<draw:gradient>` definition; XLSX export emits `<a:gradFill>` inside `<c:spPr>`.

## Bringing your own renderer

The default ECharts component is bundled, but charts are agnostic of the rendering layer. Pass your own component via the chart prop pipeline — the spec data flow is independent.

For an alternative renderer, import a different chart component (e.g. `import "@rowsncolumns/charts/plotly/basic-chart"`) — the spec format is identical.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.rowsncolumns.app/configuration/features/charts.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.