Dev

CHANGELOG.md

@@ -0,0 +1,38 @@
+# Changelog
+
+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.
+
+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.2.1] - 2026-07-13
+
+### Added
+
+- Exported backend-neutral banded-axis detection from `flint-chart/core`, so
+  custom backends and host extensions can reuse Flint's axis semantics without
+  depending on Vega-Lite implementation files.
+
+### Changed
+
+- Expanded the standalone and MCP-bundled authoring skill with Waterfall Type
+  column and `totals` guidance.
+- Updated generated backend references to list the accepted values for discrete
+  chart properties.
+
+### Fixed
+
+- Normalized discrete chart property values across all backends: display labels
+  are coerced to canonical values, invalid values fall back safely with a
+  warning, and nullable option metadata no longer causes failures.
+- Made ECharts and Chart.js Rose Chart radii proportional to the square root of
+  values, so rendered wedge areas represent the data accurately.
+- 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.2.1...HEAD
+[0.2.1]: https://github.com/microsoft/flint-chart/compare/c8e20b052ad9ddad29ba3ecfc825948c424e5ba5...0.2.1

README.md

@@ -141,7 +141,8 @@ The [project site](https://microsoft.github.io/flint-chart/) is the main entry
 point for examples, the live editor, and concept docs. For source-level
 references, start with the [API reference](docs/api-reference.md), the
 [Flint MCP project page](https://microsoft.github.io/flint-chart/#/mcp), or the
-[Development guide](docs/DEVELOPMENT.md).
+[Development guide](docs/DEVELOPMENT.md). See the [changelog](CHANGELOG.md) for
+notable changes in each release.
 
 ---
 

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

@@ -186,7 +186,7 @@ properties"). Required channels are noted.
 | `"Stacked Bar Chart"` | x, y, color, column, row | prop `stackMode` |
 | `"Pyramid Chart"` | x, y, color | diverging horizontal bars |
 | `"Lollipop Chart"` | x, y, color, column, row | prop `dotSize` |
-| `"Waterfall Chart"` | x, y, color, column, row | prop `cornerRadius` |
+| `"Waterfall Chart"` | x, y, color, column, row | `color` = Type column, values `start`/`delta`/`end` only; omit it for auto sign coloring; props `cornerRadius`, `totals` |
 | `"Gantt Chart"` | y, x, x2, color, detail, column, row | x = start, x2 = end |
 | `"Bullet Chart"` | y, x, goal, color, column, row | `goal` required (target) |
 | `"Histogram"` | x, color, column, row | x = measure to bin; prop `binCount` |
@@ -232,6 +232,18 @@ channel**:
 Rule of thumb: comparing parts-to-whole → Stacked; comparing values
 side-by-side → Grouped (use `group`); single series → Bar.
 
+**Waterfall color is a special "Type" column, not a free category.** On a
+`"Waterfall Chart"` the `color` channel is reserved for a *type* field whose
+values are literally `start`, `delta`, and `end` — it drives which bars anchor
+to zero, not an arbitrary grouping. Do **not** bind `color` to an
+`Increase`/`Decrease` (or up/down, gain/loss) category: the up/down direction is
+already derived from the **sign** of the `y` value and colored automatically
+(green up / red down). For the common case, **omit `color` entirely** and let
+Flint infer the start/delta/end and per-bar sign coloring. To force which bars
+are anchored totals, use the `totals` property (`first`/`last`/`both`), not a
+color field. Only bind `color` when you genuinely have a `start`/`delta`/`end`
+type column.
+
 **Backend coverage.** Vega-Lite supports all of the above. Other backends
 support a subset (verify if targeting a non-VL backend):
 
@@ -352,6 +364,7 @@ derived). Values are clamped to the ranges shown.
 | Rose Chart | `padAngle` | 0–0.1 (0) | Gap between slices |
 | Lollipop | `dotSize` | 20–300 (80) | Circle size (px) |
 | Waterfall | `cornerRadius` | 0–8 (0) | Round bar corners |
+| Waterfall | `totals` | `auto` \| `none` \| `first` \| `last` \| `both` (`auto`) | Which bars anchor to zero as totals (only when no Type column) |
 | Regression | `regressionMethod` | `linear` \| `log` \| `exp` \| `pow` \| `quad` \| `poly` (`linear`) | Fit method |
 | Regression | `polyOrder` | 1–5 (3) | Polynomial order (when `poly`) |
 | Radar | `filled` | boolean (true) | Fill the polygon |

docs/reference-chartjs.md

@@ -119,7 +119,7 @@ _No template-specific parameters._
 
 | Parameter | Control | Domain | Default | Availability | Description |
 |---|---|---|---|---|---|
-| `interpolate` | choice | `Default (linear)`, `Linear`, `Monotone (smooth)`, `Step`, `Step Before`, `Step After` | — | always | Line or area interpolation method. |
+| `interpolate` | choice | Default (linear) _(default)_, `linear` (Linear), `monotone` (Monotone (smooth)), `step` (Step), `step-before` (Step Before), `step-after` (Step After) | — | always | Line or area interpolation method. |
 
 ### ![](chart-icon-slope.svg) Slope Chart
 
@@ -133,9 +133,9 @@ _No template-specific parameters._
 
 | Parameter | Control | Domain | Default | Availability | Description |
 |---|---|---|---|---|---|
-| `interpolate` | choice | `Default (linear)`, `Linear`, `Monotone (smooth)` | — | always | Line or area interpolation method. |
+| `interpolate` | choice | Default (linear) _(default)_, `linear` (Linear), `monotone` (Monotone (smooth)) | — | always | Line or area interpolation method. |
 | `opacity` | number | 0.1 – 1 (step 0.05) | `0.4` | always | Mark opacity. |
-| `stackMode` | choice | `Stacked (default)`, `Layered (overlap)` | — | always | Stacking strategy for overlapping series. |
+| `stackMode` | choice | Stacked (default) _(default)_, `layered` (Layered (overlap)) | — | always | Stacking strategy for overlapping series. |
 
 ### ![](chart-icon-range-area.svg) Range Area Chart
 
@@ -160,7 +160,7 @@ _No template-specific parameters._
 | Parameter | Control | Domain | Default | Availability | Description |
 |---|---|---|---|---|---|
 | `innerRadius` | number | 0 – 60 (step 5) | `0` | always | Inner radius as a percentage of the outer radius. |
-| `sortSlices` | choice | `Data order`, `Largest first`, `Smallest first` | `Data order` | always | Sort slices |
+| `sortSlices` | choice | `none` (Data order), `descending` (Largest first), `ascending` (Smallest first) | `none` | always | Sort slices |
 
 ### ![](chart-icon-doughnut.svg) Doughnut Chart
 
@@ -169,7 +169,7 @@ _No template-specific parameters._
 | Parameter | Control | Domain | Default | Availability | Description |
 |---|---|---|---|---|---|
 | `innerRadius` | number | 20 – 80 (step 5) | `55` | always | Inner radius as a percentage of the outer radius. |
-| `sortSlices` | choice | `Data order`, `Largest first`, `Smallest first` | `Data order` | always | Sort slices |
+| `sortSlices` | choice | `none` (Data order), `descending` (Largest first), `ascending` (Smallest first) | `none` | always | Sort slices |
 
 ## Polar
 
@@ -179,7 +179,7 @@ _No template-specific parameters._
 
 | Parameter | Control | Domain | Default | Availability | Description |
 |---|---|---|---|---|---|
-| `filled` | choice | `Filled (default)`, `Outline only` | — | always | Fill the enclosed radar area. |
+| `filled` | choice | `true` (Filled (default)), `false` (Outline only) | — | always | Fill the enclosed radar area. |
 | `fillOpacity` | number | 0.05 – 0.8 (step 0.05) | `0.3` | always | Fill opacity for the area or region. |
 
 ### ![](chart-icon-rose.svg) Rose Chart
@@ -188,5 +188,5 @@ _No template-specific parameters._
 
 | Parameter | Control | Domain | Default | Availability | Description |
 |---|---|---|---|---|---|
-| `alignment` | choice | `Left (default)`, `Center` | — | always | Segment alignment for radial charts. |
-| `sortSlices` | choice | `Data order`, `Largest first`, `Smallest first` | `Data order` | always | Sort slices |
+| `alignment` | choice | `left` (Left (default)), `center` (Center) | — | always | Segment alignment for radial charts. |
+| `sortSlices` | choice | `none` (Data order), `descending` (Largest first), `ascending` (Smallest first) | `none` | always | Sort slices |

docs/reference-echarts.md

@@ -43,7 +43,7 @@ The **Availability** column shows whether a parameter is `always` available or `
 
 | Parameter | Control | Domain | Default | Availability | Description |
 |---|---|---|---|---|---|
-| `regressionMethod` | choice | `Linear`, `Logarithmic`, `Exponential`, `Power`, `Quadratic`, `Polynomial` | `Linear` | always | Regression fit method. |
+| `regressionMethod` | choice | `linear` (Linear), `log` (Logarithmic), `exp` (Exponential), `pow` (Power), `quad` (Quadratic), `poly` (Polynomial) | `linear` | always | Regression fit method. |
 | `polyOrder` | number | 2 – 10 (step 1) | `3` | always | Polynomial order for the regression fit. |
 
 ### ![](chart-icon-connected-scatter.svg) Connected Scatter Plot
@@ -64,7 +64,7 @@ _No template-specific parameters._
 
 | Parameter | Control | Domain | Default | Availability | Description |
 |---|---|---|---|---|---|
-| `whiskerMethod` | choice | `Tukey (1.5 × IQR)`, `Min–Max` | `Tukey (1.5 × IQR)` | always | Whiskers |
+| `whiskerMethod` | choice | `iqr` (Tukey (1.5 × IQR)), `minmax` (Min–Max) | `iqr` | always | Whiskers |
 | `showOutliers` | toggle | on / off | `true` | conditional | Outliers |
 
 ### ![](chart-icon-strip-plot.svg) Strip Plot
@@ -95,7 +95,7 @@ _No template-specific parameters._
 
 | Parameter | Control | Domain | Default | Availability | Description |
 |---|---|---|---|---|---|
-| `stackMode` | choice | `Stacked (default)`, `Normalize (100%)`, `Layered (overlap)` | — | conditional | Stacking strategy for overlapping series. |
+| `stackMode` | choice | Stacked (default) _(default)_, `normalize` (Normalize (100%)), `layered` (Layered (overlap)) | — | conditional | Stacking strategy for overlapping series. |
 
 ### ![](chart-icon-lollipop.svg) Lollipop Chart
 
@@ -131,7 +131,7 @@ _No template-specific parameters._
 
 | Parameter | Control | Domain | Default | Availability | Description |
 |---|---|---|---|---|---|
-| `interpolate` | choice | `Default (linear)`, `Linear`, `Monotone (smooth)`, `Step`, `Step Before`, `Step After` | — | always | Line or area interpolation method. |
+| `interpolate` | choice | Default (linear) _(default)_, `linear` (Linear), `monotone` (Monotone (smooth)), `step` (Step), `step-before` (Step Before), `step-after` (Step After) | — | always | Line or area interpolation method. |
 | `showPoints` | toggle | on / off | `false` | always | Overlay point markers on the line. |
 
 ### ![](chart-icon-bump.svg) Bump Chart
@@ -152,9 +152,9 @@ _No template-specific parameters._
 
 | Parameter | Control | Domain | Default | Availability | Description |
 |---|---|---|---|---|---|
-| `interpolate` | choice | `Default (linear)`, `Linear`, `Monotone (smooth)`, `Step`, `Step Before`, `Step After` | — | always | Line or area interpolation method. |
+| `interpolate` | choice | Default (linear) _(default)_, `linear` (Linear), `monotone` (Monotone (smooth)), `step` (Step), `step-before` (Step Before), `step-after` (Step After) | — | always | Line or area interpolation method. |
 | `opacity` | number | 0.1 – 1 (step 0.05) | `0.7` | always | Mark opacity. |
-| `stackMode` | choice | `Stacked (default)`, `Normalize (100%)`, `Center`, `Layered (overlap)` | — | always | Stacking strategy for overlapping series. |
+| `stackMode` | choice | Stacked (default) _(default)_, `normalize` (Normalize (100%)), `center` (Center), `layered` (Layered (overlap)) | — | always | Stacking strategy for overlapping series. |
 
 ### ![](chart-icon-streamgraph.svg) Streamgraph
 
@@ -178,17 +178,17 @@ _No template-specific parameters._
 |---|---|---|---|---|---|
 | `innerRadius` | number | 0 – 60 (step 5) | `0` | always | Inner radius as a percentage of the outer radius. |
 | `cornerRadius` | number | 0 – 10 (step 1) | `0` | always | Corner radius for supported marks. |
-| `sortSlices` | choice | `Data order`, `Largest first`, `Smallest first` | `Data order` | always | Sort slices |
-| `labelType` | choice | `Name + %`, `Name`, `Value`, `Percent`, `None` | `Name + %` | always | Labels |
+| `sortSlices` | choice | `none` (Data order), `descending` (Largest first), `ascending` (Smallest first) | `none` | always | Sort slices |
+| `labelType` | choice | `categoryPercent` (Name + %), `category` (Name), `value` (Value), `percent` (Percent), `none` (None) | `categoryPercent` | always | Labels |
 
 ### ![](chart-icon-funnel.svg) Funnel Chart
 
 **Encoding channels:** `y`, `size`
 
 | Parameter | Control | Domain | Default | Availability | Description |
 |---|---|---|---|---|---|
-| `sort` | choice | `Descending (default)`, `Ascending`, `Original order` | — | always | Sort order for ordered stages or categories. |
-| `orient` | choice | `Vertical (default)`, `Horizontal` | — | always | Chart orientation. |
+| `sort` | choice | `descending` (Descending (default)), `ascending` (Ascending), `none` (Original order) | — | always | Sort order for ordered stages or categories. |
+| `orient` | choice | `vertical` (Vertical (default)), `horizontal` (Horizontal) | — | always | Chart orientation. |
 | `gap` | number | 0 – 20 (step 1) | `2` | always | Gap between segments. |
 
 ### ![](chart-icon-treemap.svg) Treemap
@@ -197,7 +197,7 @@ _No template-specific parameters._
 
 | Parameter | Control | Domain | Default | Availability | Description |
 |---|---|---|---|---|---|
-| `breadcrumb` | choice | `Show (default)`, `Hide` | — | always | Show or hide treemap breadcrumb navigation. |
+| `breadcrumb` | choice | `true` (Show (default)), `false` (Hide) | — | always | Show or hide treemap breadcrumb navigation. |
 
 ### ![](chart-icon-sunburst.svg) Sunburst Chart
 
@@ -206,15 +206,15 @@ _No template-specific parameters._
 | Parameter | Control | Domain | Default | Availability | Description |
 |---|---|---|---|---|---|
 | `innerRadius` | number | 0 – 80 (step 5) | `0` | always | Inner radius as a percentage of the outer radius. |
-| `labelRotate` | choice | `Radial (default)`, `Tangential`, `Horizontal` | — | always | Label orientation for sunburst sectors. |
+| `labelRotate` | choice | `radial` (Radial (default)), `tangential` (Tangential), `0` (Horizontal) | — | always | Label orientation for sunburst sectors. |
 
 ### ![](chart-icon-tree.svg) Tree
 
 **Encoding channels:** `color`, `detail`, `size`
 
 | Parameter | Control | Domain | Default | Availability | Description |
 |---|---|---|---|---|---|
-| `orient` | choice | `Left → Right (default)`, `Top → Bottom` | — | always | Chart orientation. |
+| `orient` | choice | `LR` (Left → Right (default)), `TB` (Top → Bottom) | — | always | Chart orientation. |
 
 ## Statistical
 
@@ -287,8 +287,8 @@ _No template-specific parameters._
 
 | Parameter | Control | Domain | Default | Availability | Description |
 |---|---|---|---|---|---|
-| `shape` | choice | `Polygon (default)`, `Circle` | — | always | Grid |
-| `filled` | choice | `Filled (default)`, `Outline only` | — | always | Fill the enclosed radar area. |
+| `shape` | choice | Polygon (default) _(default)_, `circle` (Circle) | — | always | Grid |
+| `filled` | choice | `true` (Filled (default)), `false` (Outline only) | — | always | Fill the enclosed radar area. |
 | `fillOpacity` | number | 0.05 – 0.8 (step 0.05) | `0.3` | always | Fill opacity for the area or region. |
 
 ### ![](chart-icon-rose.svg) Rose Chart
@@ -297,8 +297,8 @@ _No template-specific parameters._
 
 | Parameter | Control | Domain | Default | Availability | Description |
 |---|---|---|---|---|---|
-| `alignment` | choice | `Left (default)`, `Center` | — | always | Segment alignment for radial charts. |
-| `sortSlices` | choice | `Data order`, `Largest first`, `Smallest first` | `Data order` | always | Sort slices |
+| `alignment` | choice | `left` (Left (default)), `center` (Center) | — | always | Segment alignment for radial charts. |
+| `sortSlices` | choice | `none` (Data order), `descending` (Largest first), `ascending` (Smallest first) | `none` | always | Sort slices |
 
 ## Indicator
 
@@ -310,7 +310,7 @@ _No template-specific parameters._
 |---|---|---|---|---|---|
 | `min` | number | 0 – 1000 (step 10) | `0` | always | Min |
 | `max` | number | 0 – 10000 (step 100) | `100` | always | Max |
-| `showProgress` | choice | `Show (default)`, `Hide` | — | always | Progress |
+| `showProgress` | choice | `true` (Show (default)), `false` (Hide) | — | always | Progress |
 
 ## Flow
 
@@ -320,7 +320,7 @@ _No template-specific parameters._
 
 | Parameter | Control | Domain | Default | Availability | Description |
 |---|---|---|---|---|---|
-| `orient` | choice | `Horizontal (default)`, `Vertical` | — | always | Chart orientation. |
+| `orient` | choice | `horizontal` (Horizontal (default)), `vertical` (Vertical) | — | always | Chart orientation. |
 | `nodeWidth` | number | 5 – 40 (step 5) | `20` | always | Node Width |
 | `nodeGap` | number | 2 – 30 (step 2) | `10` | always | Node Gap |
 
@@ -330,4 +330,4 @@ _No template-specific parameters._
 
 | Parameter | Control | Domain | Default | Availability | Description |
 |---|---|---|---|---|---|
-| `layout` | choice | `Circular (default)`, `Force-directed` | — | always | Layout |
+| `layout` | choice | `circular` (Circular (default)), `force` (Force-directed) | — | always | Layout |