[WIP] Excel and Plotly backend, and enhanced control

.github/release-notes/0.3.0.md

@@ -1,43 +1,30 @@
-# Flint 0.3
+Flint 0.3 makes charts easier to explore after they are created. The MCP App can now switch chart types and edit chart properties in place, while the original Flint spec stays compact and readable.
 
-Flint 0.3 makes charts easier to explore after they are created. The MCP App can
-now switch between compatible chart types and edit chart properties in place,
-while keeping the original Flint spec compact and readable.
+### Explore chart types
 
-## Explore chart types
-
-Move between compatible views without asking the agent to rebuild the chart.
-Flint preserves the data roles and derives the details needed by the new chart
-type.
+Move between compatible views without rebuilding the chart. For example, turn a dense Line Chart of food prices into compact Sparkline rows for easier comparison. Flint preserves the data roles and derives the details for the new chart type.
 
 <img width="1086" alt="Switching a line chart to a Sparkline in the Flint MCP App" src="https://github.com/user-attachments/assets/f9194ec7-65ab-4120-aca7-09328db8d39a" />
 
-## Edit chart properties
+### Edit chart properties
 
-Common chart properties are available directly in the widget. Changes are
-immediate, and the available controls follow the selected chart and backend.
+Edit common properties directly in the widget. For example, turn labels on in a correlation heatmap to reveal the value in every cell. Controls adapt to the selected chart and backend, and changes appear immediately.
 
 <img width="1091" alt="Turning labels on for a heatmap in the Flint MCP App" src="https://github.com/user-attachments/assets/2915bf55-a55d-4ad1-a7d7-e660732c0b46" />
 
-## Flint in Chinese
+### Flint in Chinese
 
-The website and documentation are now available in Chinese, including guides for
-getting started, authoring charts, and extending Flint.
+The website and documentation are now available in Chinese, including guides for getting started, authoring charts, and extending Flint.
 
 <img width="1239" alt="The Chinese Flint website and documentation" src="https://github.com/user-attachments/assets/1d300716-6cf1-475f-9483-00e926463d6e" />
 
-## Smaller updates
+### Also in 0.3
 
 - Added backend-neutral chart recommendations and chart transformations.
-- Improved sparse area charts, grouped bars, boxplots, Gantt charts, and
-  Waterfall charts across supported backends.
-- Improved semantic formatting for axes, aggregates, and Sparkline averages.
-- Sparklines now self-scale each row and no longer expose a shared-Y option.
-- Added PNG copy, download, and reset actions to the MCP App.
-- Expanded chart-property guidance in the bundled agent skill and reference
-  documentation.
-
-See the [changelog](https://github.com/microsoft/flint-chart/blob/main/CHANGELOG.md#030---2026-07-19)
-for migration notes and the complete technical summary.
+- Improved sparse areas, grouped bars, boxplots, Gantt charts, and Waterfall charts across backends.
+- Improved semantic formatting and made Sparkline rows self-scale by default.
+- Added PNG copy, download, and reset actions, plus expanded agent guidance.
+
+See the [changelog](https://github.com/microsoft/flint-chart/blob/main/CHANGELOG.md#030---2026-07-19) for migration notes and the complete technical summary.
 
 **Full Changelog**: https://github.com/microsoft/flint-chart/compare/0.2.1...0.3.0

.github/workflows/npm-publish.yml

@@ -34,6 +34,7 @@ jobs:
 
       - name: Audit production dependencies
         run: npm audit --omit=dev --audit-level=moderate
+        continue-on-error: true
 
       - name: Check package versions
         shell: bash

CHANGELOG.md

@@ -4,13 +4,78 @@ Starting with version 0.2.1, all notable changes to `flint-chart` and
 `flint-chart-mcp` are documented in this file. The two npm packages are
 versioned and released together, so each release entry covers both packages.
 Versions 0.2.1 and 0.2.2 were development milestones and were not published to
-npm; 0.3.0 is the next public release after 0.2.0.
+npm; 0.3.0 resumed public releases after 0.2.0.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-07-24
+
+### Added
+
+- Excel backend: 18 chart templates compile the same semantic Flint input into
+  native, editable Office.js charts — Bar, Grouped/Stacked Bar, Pyramid, Line,
+  Area, Scatter, Connected Scatter, Pie, Donut, Histogram, Boxplot,
+  Candlestick, Waterfall, Radar, Funnel, Treemap, and Sunburst. The backend
+  emits a rectangular data range plus native chart/axis/legend/series metadata,
+  includes Office.js code generation and runtime helpers, and was visually
+  audited across 117 cases with `test-harness/excel/`.
+- Plotly backend: expanded from the four original acceptance templates (Bar,
+  Line, Area, Scatter) to 33 chart types — grouped/stacked bar, pyramid,
+  histogram, boxplot, violin, density, ECDF, strip plot, connected scatter,
+  range area, streamgraph, slope, bump, waterfall, candlestick, heatmap,
+  lollipop, bullet, Gantt, ranged dot plot, regression, pie, donut, radar,
+  rose, KPI card, and the Plotly-native opportunity charts Funnel and Gauge —
+  leaning on Plotly's own native trace types (`box`, `violin`, `candlestick`,
+  `waterfall`, `heatmap`, `scatterpolar`, `barpolar`, `indicator`, `funnel`)
+  wherever one exists.
+- Plotly backend: closed the four remaining registry gaps and added the
+  Plotly-native Density Contour statistical chart, now 38 chart types.
+  - Map, Choropleth — native `scattergeo`/`choropleth` traces with Plotly's
+    own built-in geo atlas (no TopoJSON fetch/join). Share the Vega-Lite
+    Map/Choropleth's region-name/code gazetteer (`chart-types/geo.ts`, moved
+    out of `vegalite/templates/` to be backend-shared), extended with USPS/
+    ISO-alpha-3 code resolvers for Plotly's native `locations` binding.
+  - Sparkline, Bar Table — composite, self-contained Plotly figures (their
+    own multi-axis-pair grid + paper-anchored annotations) rather than the
+    generic column/row facet combiner, which only supports one cartesian
+    axis pair per panel. A new `ChartTemplateDef.selfManagesFacets` flag lets
+    a template opt out of the assembler's generic facet-splitting pass even
+    though it declares `x`/`y` channels.
+- Plotly scatter/strip plots now use a native continuous colorscale +
+  colorbar for quantitative/temporal `color` fields instead of grouping them
+  like a categorical legend.
+- `docs/reference-plotly.md` — generated chart reference for the Plotly
+  backend (`npm run gen:reference`).
+- `test-harness/plotly/` — a headless-Chromium render/audit harness for the
+  Plotly backend (spec → PNG, contact sheets, VLM review script, and a
+  per-chart-type inspection list), mirroring the Excel backend's visual audit
+  harness.
+
+### Fixed
+
+- Plotly: a shared column/row facet-splitting pass ran for every template,
+  including axis-less ones (Pie, Donut, Radar, Rose, Gauge, KPI Card, Funnel)
+  that use the `column` channel for their own internal per-item grouping —
+  this collapsed multi-item Gauge/KPI grids onto identical, fully-overlapping
+  domains. Faceting is now gated on the template declaring `x`/`y` channels,
+  mirroring the ECharts backend's own guard.
+- Plotly Choropleth: Plotly's own built-in `'Blues'` colorscale runs
+  dark→light as the value increases — the opposite of the light→dark
+  sequential convention used everywhere else, which made the *highest*-value
+  region read as the palest. Replaced with an explicit light→dark stop array.
+- Plotly Bar Table (faceted): each facet cell's per-cell `xaxis{n}`/
+  `yaxis{n}` pair needs an explicit `anchor` to each other — without it every
+  cell's category tick labels rendered at the same horizontal position
+  (overlapping across cells). Also fixed: long category names now truncate
+  with an ellipsis instead of overflowing past the figure's own edge; a
+  column-only facet with more panels than fit is now actually wrapped (using
+  this template's own minimum panel-width estimate, not the shared layout
+  engine's narrower default); sub-1 magnitude values no longer round away to
+  "0"; a single-row table no longer collapses to an unreadably short figure.
+
 ## [0.3.0] - 2026-07-19
 
 ### Added
@@ -105,7 +170,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Treated only lowercase `start` and `end` Waterfall Type values as total
   anchors in Vega-Lite; other values now remain floating deltas colored by sign.
 
-[Unreleased]: https://github.com/microsoft/flint-chart/compare/0.3.0...HEAD
+[Unreleased]: https://github.com/microsoft/flint-chart/compare/0.4.0...HEAD
+[0.4.0]: https://github.com/microsoft/flint-chart/compare/0.3.0...0.4.0
 [0.3.0]: https://github.com/microsoft/flint-chart/compare/88fbeb5ebf07f18a1cf661ebef71cc570b7425d6...0.3.0
 [0.2.2]: https://github.com/microsoft/flint-chart/compare/0.2.1...6a9d4e4155e3d9e2bed3fa9adf5316914f791478
 [0.2.1]: https://github.com/microsoft/flint-chart/compare/c8e20b052ad9ddad29ba3ecfc825948c424e5ba5...0.2.1

README.md

@@ -2,6 +2,7 @@
 
 [![npm: flint-chart](https://img.shields.io/npm/v/flint-chart.svg?label=npm%3A%20flint-chart)](https://www.npmjs.com/package/flint-chart)
 [![npm: flint-chart-mcp](https://img.shields.io/npm/v/flint-chart-mcp.svg?label=npm%3A%20flint-chart-mcp)](https://www.npmjs.com/package/flint-chart-mcp)
+[![arXiv: 2607.20775](https://img.shields.io/badge/arXiv-2607.20775-b31b1b.svg)](https://arxiv.org/abs/2607.20775)
 [![CI](https://github.com/microsoft/flint-chart/actions/workflows/ci.yml/badge.svg)](https://github.com/microsoft/flint-chart/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 
@@ -15,18 +16,19 @@ derives optimized chart settings from the data, semantic types, chart type, and
 encodings. The result is a compact chart specification that agents can produce
 reliably, people can edit directly, and multiple backends can render as native
 [Vega-Lite](https://vega.github.io/vega-lite/),
-[ECharts](https://echarts.apache.org/), or
-[Chart.js](https://www.chartjs.org/) specs.
+[ECharts](https://echarts.apache.org/),
+[Chart.js](https://www.chartjs.org/), or
+[Plotly](https://plotly.com/javascript/) specs, and native Excel charts through Office.js.
 
 This repo contains two main components:
 
 - **`flint-chart`**: a JavaScript/TypeScript library that compiles the same
-  Flint input into Vega-Lite, ECharts, or Chart.js specs.
+  Flint input into Vega-Lite, ECharts, Chart.js, Plotly, or Excel-native output.
 - **`flint-chart-mcp`**: an MCP server that lets agents create, validate, and
   render charts directly from a chat or coding environment.
 
 <p align="center">
-  <img src="docs/figs/chartwall.png" alt="A wall of charts produced by Flint: bar, line, scatter, heatmap, donut, radar, streamgraph, boxplot, grouped bar, rose, Sankey, and treemap, rendered across Vega-Lite, ECharts, and Chart.js." width="100%">
+  <img src="docs/figs/chartwall.png" alt="A wall of charts produced by Flint across its supported visualization backends." width="100%">
 </p>
 
 ## Features
@@ -36,16 +38,19 @@ This repo contains two main components:
   semantic types such as `Rank`, `Temperature`, `Price`, or `Country`.
 - **Automatic layout.** Flint adapts sizing, spacing, labels, marks, and legends
   to the data cardinality, chart design, and canvas constraints.
-- **Multiple backends.** Compile one input to 30+ chart types across
+- **Multiple backends.** Compile one input to backend-native output across
   [Vega-Lite](https://vega.github.io/vega-lite/),
-  [ECharts](https://echarts.apache.org/), and
-  [Chart.js](https://www.chartjs.org/), with more to come soon.
+  [ECharts](https://echarts.apache.org/),
+  [Chart.js](https://www.chartjs.org/),
+  [Plotly](https://plotly.com/javascript/), and native Excel charts.
 - **Agent-ready chart authoring.** The MCP server gives agents Flint tools and
   chart guidance so they can choose a template, validate it, and open an
   interactive chart view in MCP-capable clients.
 
 ## Updates
 
+- **July 24, 2026** — Flint 0.4.0 adds 38 Plotly chart types and 18 native,
+  editable Excel chart templates. ([v0.4.0](https://github.com/microsoft/flint-chart/releases/tag/0.4.0))
 - **July 19, 2026** — Flint 0.3.0 adds dynamic chart widgets that switch chart
   types and edit chart properties in place. ([v0.3.0](https://github.com/microsoft/flint-chart/releases/tag/0.3.0))
 - **July 15, 2026** — Flint 0.2.2 added compact dodge modes and grouped violin
@@ -97,15 +102,19 @@ const spec = assembleVegaLite({
 Swap the backend without changing the input shape:
 
 ```ts
-import { assembleECharts, assembleChartjs } from 'flint-chart';
+import { assembleECharts, assembleChartjs, assemblePlotly, assembleExcel } from 'flint-chart';
 
 const echartsOption = assembleECharts(input);
 const chartjsConfig = assembleChartjs(input);
+const plotlyFigure = assemblePlotly(input);
+const excelArtifact = assembleExcel(input);
 ```
 
-See the [API reference](docs/api-reference.md), [backend references](docs/reference-vegalite.md),
-and [live editor](https://microsoft.github.io/flint-chart/#/editor) for more
-library examples.
+See the [API reference](docs/api-reference.md), backend references for
+[Vega-Lite](docs/reference-vegalite.md), [ECharts](docs/reference-echarts.md),
+[Chart.js](docs/reference-chartjs.md), [Plotly](docs/reference-plotly.md), and
+[Excel](docs/reference-excel.md), plus the
+[live editor](https://microsoft.github.io/flint-chart/#/editor) for more library examples.
 
 ## Use Flint As An MCP Server
 

agent-skills/flint-chart-author/SKILL.md

@@ -250,8 +250,8 @@ support a subset (verify if targeting a non-VL backend):
   `"Funnel"`, `"Treemap"`, `"Sunburst"`, `"Sankey"`,
   `"Parallel Coordinates"`, `"Graph"`, `"Tree"`.
 - **Chart.js** supports: Scatter, Bubble, Bar, Grouped Bar, Stacked Bar,
-  Combo, Line, Area, Range Area, Pie, Doughnut, Histogram, Radar, Rose, Slope,
-  Connected Scatter.
+  Combo, Line, Bump, Area, Range Area, Pie, Doughnut, Histogram, Radar, Rose,
+  Slope, Connected Scatter.
 
 You do not need to call the library or inspect its source to author the
 input — pick from this table.

docs/README.md

@@ -851,9 +851,9 @@ interface ChartTemplateDef {
 
 ### `OverflowStrategy`
 
-Customizable per-template. The default strategy in `filter-overflow.ts` handles:
-connected marks (keep all for continuity), user sorts, auto-sorts,
-bar sum-aggregate, numeric sort, first-N.
+Customizable per-template. The default strategy in `filter-overflow.ts` keeps
+the first values in the selected display order: explicit user sort, canonical
+semantic order, numeric order, then data encounter order.
 
 ```typescript
 type OverflowStrategy = (
@@ -917,42 +917,20 @@ visualization decisions:
 
 ## Template Catalog
 
-### Vega-Lite (30 chart types)
-
-| Category | Charts |
-|----------|--------|
-| **Scatter & Point** | Scatter Plot, Regression, Ranged Dot Plot, Boxplot, Strip Plot |
-| **Bar** | Bar Chart, Grouped Bar Chart, Stacked Bar Chart, Histogram, Heatmap, Lollipop Chart, Pyramid Chart |
-| **Line & Area** | Line Chart, Dotted Line Chart, Bump Chart, Area Chart, Streamgraph |
-| **Part-to-Whole** | Pie Chart, Rose Chart, Waterfall Chart |
-| **Statistical** | Density Plot, Candlestick Chart, Radar Chart |
-| **Map** | US Map, World Map |
-
-### ECharts (28 chart types)
-
-| Category | Charts |
-|----------|--------|
-| **Scatter & Point** | Scatter Plot, Regression, Ranged Dot Plot, Boxplot, Strip Plot |
-| **Bar** | Bar Chart, Grouped Bar Chart, Stacked Bar Chart, Histogram, Heatmap, Lollipop Chart, Pyramid Chart |
-| **Line & Area** | Line Chart, Dotted Line Chart, Bump Chart, Area Chart, Streamgraph |
-| **Part-to-Whole** | Pie Chart, Funnel Chart, Treemap, Sunburst Chart |
-| **Polar** | Radar Chart, Rose Chart |
-| **Financial** | Candlestick Chart |
-| **Indicator** | Gauge Chart |
-| **Flow** | Sankey Diagram |
-| **Other** | Waterfall Chart, Density Plot |
-
-### Chart.js (10 chart types)
-
-| Category | Charts |
-|----------|--------|
-| **Scatter & Point** | Scatter Plot |
-| **Bar** | Bar Chart, Grouped Bar Chart, Stacked Bar Chart, Histogram |
-| **Line & Area** | Line Chart, Area Chart |
-| **Part-to-Whole** | Pie Chart |
-| **Polar** | Radar Chart, Rose Chart |
-
-**68 template definitions** across 3 backends.
+Flint currently ships **149 backend template registrations** across five
+backends. Chart names overlap because the same semantic input can target more
+than one renderer.
+
+| Backend | Registered chart types | Generated reference |
+|---|---:|---|
+| Vega-Lite | 35 | [Vega-Lite charts](reference-vegalite.md) |
+| ECharts | 37 | [ECharts charts](reference-echarts.md) |
+| Chart.js | 21 | [Chart.js charts](reference-chartjs.md) |
+| Plotly | 38 | [Plotly charts](reference-plotly.md) |
+| Excel | 18 | [Excel charts](reference-excel.md) |
+
+Run `npm run gen:reference` after changing a template registry. The generated
+pages are the source of truth for chart names, channels, and exposed options.
 
 Each template defines:
 1. **`template`** — spec skeleton (mark + encoding structure)
@@ -1009,13 +987,14 @@ When discrete channels overflow the canvas budget, the library:
    count, placeholder string
 5. Emits `ChartWarning` for the UI
 
-The default overflow strategy priority:
-1. Connected marks (line, area) → keep all (truncation breaks continuity)
-2. User-specified sort → keep top/bottom N by sort order
-3. Quantitative opposite axis → sort by opposite, keep top N
-4. Bar with count aggregate → sum-aggregate and keep top N
-5. Numeric field → numeric sort, keep first N
-6. Fallback → keep first N in data order
+The default overflow strategy follows the chart's display order:
+1. User-specified sort → keep the first N values in that order
+2. Canonical semantic order (months, ranks, quarters, etc.) → keep the first N
+3. Numeric discrete field → numeric ascending, keep the first N
+4. Fallback → keep the first N in data encounter order
+
+Overflow does not introduce a measure-based top-N ranking. Select an explicit
+value sort when the largest or smallest categories should be retained.
 
 ---
 

docs/adding-a-backend.md

@@ -1,6 +1,6 @@
 # Extending backends
 
-Add a backend when Flint needs to target a new rendering library or spec format. A backend is an `assemble<Backend>(input)` orchestrator plus a `templates/` registry; together they turn shared compiler output into a native chart spec. Existing references live under `packages/flint-js/src/`: `vegalite/`, `echarts/`, and `chartjs/`.
+Add a backend when Flint needs to target a new rendering library or spec format. A backend is an `assemble<Backend>(input)` orchestrator plus a `templates/` registry; together they turn shared compiler output into a native chart spec or artifact. Existing references live under `packages/flint-js/src/`: `vegalite/`, `echarts/`, `chartjs/`, `plotly/`, and `excel/`.
 
 For pipeline stages and repo layout, see [Architecture](/documentation/architecture).