Flint excel

.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

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 = (
@@ -1009,13 +1009,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/architecture.md

@@ -39,10 +39,10 @@ Most design logic lives in Stages 1–2 and is identical across backends.
 |-------|------------|----------------|-------------|
 | **1. Compiler frontend** | Resolve semantic context | Phase 0 — `resolveChannelSemantics()` | `ChannelSemantics` per channel |
 | **2. Optimizer** | Fit layout to canvas | Phase 1 — `computeLayout()`, `filterOverflow()` | `LayoutResult`, truncated data |
-| **3. Code generator** | Emit library-native spec | Phase 2 — `build*Encodings()`, `template.instantiate()` | VL / EC / CJS spec |
+| **3. Code generator** | Emit backend-native output | Phase 2 — `build*Encodings()`, `template.instantiate()` | VL / EC / CJS spec or Office.js program |
 
 ```text
-assembleVegaLite(input)   // or assembleECharts, assembleChartjs
+assembleVegaLite(input)   // or assembleECharts, assembleChartjs, assembleExcel
        │
        ▼
 ══ STAGE 1 — COMPILER FRONTEND (core/) ═════════════════════════
@@ -150,6 +150,27 @@ Registries: `vlTemplateDefs`, `ecTemplateDefs`, `cjsTemplateDefs`. Lookup: `vlGe
 
 New backends implement Stage 3 only; the frontend and optimizer stay unchanged. See [Extending backends](/documentation/adding-a-backend).
 
+### Excel backend
+
+Excel is a Stage 3 backend in `packages/flint-js`, parallel to Vega-Lite, ECharts, and Chart.js. It is not a separate package or an additional architectural layer.
+
+Office.js is imperative and requires an Excel host, so the backend first builds a typed native-chart artifact (`ExcelNativeChartSpec`) containing the worksheet matrix, native chart type, series bindings, dimensions, axes, labels, legend, and formatting. This versioned artifact is the contract between compilation and execution.
+
+The native-chart plan is an intermediate representation of the Excel backend, not a second user-authored chart specification. Callers continue to author the same semantic Flint input used by every backend:
+
+```text
+semantic Flint input
+       │
+       ▼
+assembleExcel() → ExcelNativeChartSpec
+                      │
+                      ├── renderExcelChart(Excel, artifact) → native Excel chart
+                      │
+                      └── generateOfficeJs(artifact) → standalone Office.js source
+```
+
+The normal add-in path transports the artifact and passes it, with the live Excel host, to `renderExcelChart()`. `generateOfficeJs()` is an optional projection for callers that need portable Office.js source; it is not a second contract or a required step in rendering. Host concerns such as worksheet selection, image capture, and process lifecycle stay outside compilation. Test harnesses may provide those host services, but they do not define Excel chart semantics.
+
 ---
 
 # §6 Inputs
@@ -178,9 +199,11 @@ packages/flint-js/src/
 ├── vegalite/       Stage 3 — Vega-Lite templates + assembleVegaLite
 ├── echarts/        Stage 3 — ECharts templates + assembleECharts
 ├── chartjs/        Stage 3 — Chart.js templates + assembleChartjs
+├── excel/          Stage 3 — native Excel chart planning + Office.js generation
 └── test-data/      gallery fixtures (TEST_GENERATORS)
 
 packages/flint-py/  Python port preview (package planned later)
+test-harness/excel/ Office.js runner + visual evaluations of Excel artifacts
 site/               demo site (gallery, editor, documentation)
 ```
 

docs/reference-vegalite.md

@@ -6,7 +6,7 @@ The Vega-Lite backend serves as Flint's reference implementation and offers the
 
 ## What this page covers
 
-This reference lists the 34 chart types currently supported by the Vega-Lite backend, grouped into 6 categories. Each chart entry shows:
+This reference lists the 35 chart types currently supported by the Vega-Lite backend, grouped into 6 categories. Each chart entry shows:
 
 - **Encoding channels** — the visual roles accepted in `chart_spec.encodings`, such as `x`, `y`, `color`, `size`, `column`, or `row`.
 - **Options** — template-specific `chart_spec.chartProperties` keys, including control type, domain, default, availability, and description.
@@ -345,6 +345,16 @@ _No template-specific parameters._
 | `sortSlices` | choice | `none` (Data order), `descending` (Largest first), `ascending` (Smallest first) | `none` | always | Sort slices |
 | `independentYAxis` | toggle | on / off | `false` | conditional | Use independent y-scales for facets. |
 
+### Donut Chart
+
+**Encoding channels:** `size`, `color`, `column`, `row`
+
+| Parameter | Control | Domain | Default | Availability | Description |
+|---|---|---|---|---|---|
+| `innerRadius` | number | 0 – 100 (step 5) | `0` | always | Inner radius as a percentage of the outer radius. |
+| `sortSlices` | choice | `none` (Data order), `descending` (Largest first), `ascending` (Smallest first) | `none` | always | Sort slices |
+| `independentYAxis` | toggle | on / off | `false` | conditional | Use independent y-scales for facets. |
+
 ### ![](chart-icon-rose.svg) Rose Chart
 
 **Encoding channels:** `x`, `y`, `color`, `column`, `row`

packages/flint-js/package.json

@@ -50,11 +50,21 @@
       "import": "./dist/echarts/index.js",
       "require": "./dist/echarts/index.cjs"
     },
+    "./plotly": {
+      "types": "./dist/plotly/index.d.ts",
+      "import": "./dist/plotly/index.js",
+      "require": "./dist/plotly/index.cjs"
+    },
     "./chartjs": {
       "types": "./dist/chartjs/index.d.ts",
       "import": "./dist/chartjs/index.js",
       "require": "./dist/chartjs/index.cjs"
     },
+    "./excel": {
+      "types": "./dist/excel/index.d.ts",
+      "import": "./dist/excel/index.js",
+      "require": "./dist/excel/index.cjs"
+    },
     "./test-data": {
       "types": "./dist/test-data/index.d.ts",
       "import": "./dist/test-data/index.js",
@@ -87,6 +97,7 @@
   },
   "peerDependencies": {
     "chart.js": "^4.0.0",
+    "plotly.js": "^2.0.0 || ^3.0.0",
     "echarts": "^5.0.0 || ^6.0.0",
     "vega": "^5.0.0 || ^6.0.0",
     "vega-lite": "^5.0.0 || ^6.0.0"
@@ -103,6 +114,9 @@
     },
     "chart.js": {
       "optional": true
+    },
+    "plotly.js": {
+      "optional": true
     }
   },
   "devDependencies": {