@amcharts/amcharts5-mcp 1.7.0 → 1.8.0

package/content/timeline.md

@@ -90,8 +90,8 @@ const chart = root.container.children.push(
 | `levelCount` | number | `3` | Number of spiral rings |
 | `startAngle` | number | `-90` | Where the spiral starts (degrees) |
 | `endAngle` | number | `0` | Where the spiral ends (degrees) |
-| `innerRadius` | `Percent` | `60%` | Size of the center hole |
-| `yAxisRadius` | `Percent` | `50%` | Band thickness — applied to every Y axis renderer's radius |
+| `innerRadius` | `Percent` | `20%` | Size of the center hole |
+| `yAxisRadius` | `Percent` | `60%` | Band thickness — applied to every Y axis renderer's radius |
 
 > There is no `inversed` or `yAxisInnerRadius` setting on `SpiralChart`. To reverse direction use the `startAngle`/`endAngle` pair. (`inversed` is a valid axis-renderer setting, but not a chart setting.)
 
@@ -119,6 +119,8 @@ const xRenderer = am5timeline.AxisRendererCurveX.new(root, {
 });
 ```
 
+On a `CurveChart` the `AxisRendererCurveX` `points` are scaled and centered to fit the plot area. Before 5.21.1 a path scaled down this way got far too many labels and grid lines.
+
 ## Axes
 
 Same axis types as XY charts, but with Curve renderers.
@@ -230,28 +232,25 @@ Use bullets with labels to show discrete events (milestones, releases) along the
 
 ```js
 series.bullets.push(function(root, series, dataItem) {
-  var dc = dataItem.dataContext;
-  if (dc.milestone) {
-    return am5.Bullet.new(root, {
-      sprite: am5.Container.new(root, {
-        children: [
-          am5.Circle.new(root, { radius: 8, fill: am5.color(0xff5733) }),
-          am5.Label.new(root, {
-            text: dc.label || "",
-            centerX: am5.percent(50),
-            centerY: am5.percent(100),
-            dy: -15,
-            fontSize: 11,
-            populateText: true
-          })
-        ]
-      })
-    });
+  if (dataItem.dataContext.milestone) {
+    // Container has no `children` setting: create it, then push the children
+    var marker = am5.Container.new(root, {});
+    marker.children.push(am5.Circle.new(root, { radius: 8, fill: am5.color(0xff5733) }));
+    marker.children.push(am5.Label.new(root, {
+      text: "{label}",
+      populateText: true,     // a Label you create fills {placeholders} only with this
+      centerX: am5.percent(50),
+      centerY: am5.percent(100),
+      dy: -10,
+      fontSize: 11
+    }));
+    return am5.Bullet.new(root, { sprite: marker });
   }
   return am5.Bullet.new(root, {
     sprite: am5.Circle.new(root, { radius: 3, fill: series.get("fill") })
   });
 });
+// data rows: { date: …, value: 1, milestone: true, label: "Release" }
 ```
 
 ## Events on timeline elements
@@ -437,8 +436,6 @@ chart.get("cursor").events.on("cursormoved", function(ev) {
     }));
 
     series.columns.template.setAll({
-      cornerRadiusTL: 5,
-      cornerRadiusTR: 5,
       strokeOpacity: 0
     });
 

package/content/ui-elements.md

@@ -101,6 +101,8 @@ button.events.on("click", function(ev) {
 
 A single-value slider control. Values range from 0 to 1 (relative positions).
 
+Need the handle on a chart axis instead (a draggable playhead on a date axis)? Use an axis range whose `AxisBullet` holds a `Button` with `themeTags: ["resize", "horizontal"]`, and move the range in the button's `dragged` event — see `examples/line-area/line-chart-with-range-slider`.
+
 ```js
 var slider = container.children.push(am5.Slider.new(root, {
   orientation: "horizontal",  // or "vertical"
@@ -181,6 +183,7 @@ chart.set("scrollbarX", am5xy.XYChartScrollbar.new(root, {
   orientation: "horizontal",
   height: 50
 }));
+// the preview draws nothing until scrollbar.chart gets axes and a series with data: see references/xy.md → Scrollbar
 ```
 
 ### Position

package/content/xy.md

@@ -209,6 +209,8 @@ series.data.setAll([
 ]);
 ```
 
+String dates need a `DataProcessor` with `dateFields: ["date"]` (see SKILL.md "Data processor"). With a `dateFormat` (e.g. `"yyyy-MM-dd"`) they are read as local time (UTC with `root.utc: true`). Without one, since 5.21.1 the browser's `Date` parses them, and a date-only string such as `"2024-01-01"` is midnight **UTC**. Before 5.21.1 every such string became 1 January 1970.
+
 ## ValueAxis
 
 Used for numeric values. Auto-calculates min/max from data.
@@ -232,6 +234,15 @@ const yAxis = chart.yAxes.push(am5xy.ValueAxis.new(root, {
 
 A `logarithmic` axis cannot show values ≤ 0. Since 5.21.0 such data logs a console warning ("…Set `treatZeroAs` to show them.") instead of silently drawing nothing — set `treatZeroAs` (e.g. `0.1`) when the data has zeros.
 
+**Zooming to values right after changing `min`/`max`:** `zoomToValues()` converts with the axis's current range, which updates a frame after `setAll({ min, max })`. In the same tick, compute the positions yourself, or call `zoomToValues()` on the next frame:
+
+```js
+yAxis.setAll({ min: 0, max: 200 });
+yAxis.zoom((50 - 0) / (200 - 0), (100 - 0) / (200 - 0));   // = zoomToValues(50, 100) on the new range
+```
+
+`maxZoomFactor` (how far an axis can zoom in) is an **axis** setting, not an `XYChart` one.
+
 ## AxisRendererX / AxisRendererY
 
 Controls visual rendering of an axis. Every axis MUST have a renderer.
@@ -310,6 +321,14 @@ series.strokes.template.setAll({
 - `connect: true` — connect lines over missing data (default: true). Set `false` for line breaks at gaps
 - `minDistance: 10` — min pixel distance between points before simplifying
 
+**Per-segment colors from data:** a data item that carries `strokeSettings` (or `fillSettings`) starts a new segment drawn with those settings, through `templateField`:
+```js
+series.strokes.template.setAll({ templateField: "strokeSettings", strokeWidth: 2 });
+series.fills.template.setAll({ visible: true, fillOpacity: 0.5, templateField: "fillSettings" });
+// data: { year: "2015", value: 23.5, strokeSettings: { stroke: am5.color(0xff0000) }, fillSettings: { fill: am5.color(0xff0000) } }
+```
+Full demo: `examples/line-area/line-with-changing-color`. To color by value ranges instead (e.g. below zero), use an axis range (see "Axis ranges").
+
 ## ColumnSeries
 
 For vertical columns or horizontal bars.
@@ -374,6 +393,14 @@ const series = chart.series.push(am5xy.CandlestickSeries.new(root, {
 }));
 ```
 
+**Candlesticks on a `ValueAxis` X** (e.g. candle index; the `CandlestickSeries` takes the body width from `openValueXField` + `valueXField`): the wick is drawn at the `valueXField` edge, not the middle, because a `ValueAxis` ignores the cell location (still in 5.21.2). Shift the wick by half the body, or use a `DateAxis`:
+
+```js
+["lowX0", "lowX1", "highX0", "highX1"].forEach(function (k) {
+  series.columns.template.adapters.add(k, function (v, target) { return v - target.width() / 2; });
+});
+```
+
 ## XYCursor
 
 Adds crosshair and enables tooltips on hover.
@@ -446,8 +473,11 @@ const sbSeries = scrollbar.chart.series.push(am5xy.LineSeries.new(root, {
   valueYField: "value",
   valueXField: "date"
 }));
+sbSeries.data.setAll(data);   // the preview series needs the data too
 ```
 
+`XYChartScrollbar` has no `xAxis`/`yAxis` settings: its preview is a chart of its own, `scrollbar.chart`, so its axes go into `scrollbar.chart.xAxes`/`yAxes` as above. Axes passed to `XYChartScrollbar.new()` are never added to it, and the preview series then throws.
+
 ## Legend
 
 ```js
@@ -568,6 +598,22 @@ series.data.setAll([
 ]);
 ```
 
+**Equal scale on both axes** (orbits, floor plans: 1 unit = the same pixels on X and Y). There is no setting for it; fix both ranges and widen the longer side whenever the plot is resized:
+
+```js
+var R = 10;   // half the range shown on the shorter side
+var xAxis = chart.xAxes.push(am5xy.ValueAxis.new(root, { strictMinMax: true, min: -R, max: R, renderer: am5xy.AxisRendererX.new(root, {}) }));
+var yAxis = chart.yAxes.push(am5xy.ValueAxis.new(root, { strictMinMax: true, min: -R, max: R, renderer: am5xy.AxisRendererY.new(root, {}) }));
+chart.plotContainer.events.on("boundschanged", function () {
+  var w = chart.plotContainer.width(), h = chart.plotContainer.height();
+  if (!w || !h) return;
+  var rx = w > h ? R * w / h : R, ry = w > h ? R : R * h / w;
+  xAxis.setAll({ min: -rx, max: rx });
+  yAxis.setAll({ min: -ry, max: ry });
+});
+// wheelY: "zoomXY" on the XYChart keeps the aspect while zooming
+```
+
 ## Bullets (data point markers)
 
 ```js
@@ -741,16 +787,29 @@ Each added line series takes the next entry by position, wrapping around when th
 
 ## Series gradients (5.20.0)
 
-`Series` accepts `fillGradient` and `strokeGradient`:
+Put a gradient on the element that draws it: `series.fills.template` (area), `series.columns.template` (columns), `series.strokes.template` (`strokeGradient`, the line):
+
+```js
+series.fills.template.setAll({ visible: true, fillOpacity: 1 });
+series.fills.template.set("fillGradient", am5.LinearGradient.new(root, {
+  stops: [{ opacity: 0.6 }, { opacity: 0 }],   // stops without a color take the element's fill
+  rotation: 90                                  // top to bottom
+}));
+```
+
+`Series` also has `fillGradient` and `strokeGradient` settings (5.20.0), but the series' own fills, lines and columns don't use them: they are handed to bullets. A bullet `Graphics` that sets none of `fill`, `fillGradient`, `fillPattern`, `stroke`, `strokeGradient` inherits all of them from its series, so bullets pick up series gradients and patterns automatically.
+
+**`LinearGradient` `rotation` only works from 0 to 90** (a bug in 5.20.8–5.21.2, any element). Other angles give a flat or wrong fill, and with a transparent end stop the shape can vanish. For the opposite direction keep the angle in that range and reverse the `stops`: 180 = `rotation: 0` with reversed stops, 270 = `rotation: 90` with reversed stops:
 
 ```js
-series.set("fillGradient", am5.LinearGradient.new(root, {
-  stops: [{ opacity: 0.6 }, { opacity: 0 }],
-  rotation: 90
+// what rotation: 180 with stops [{ opacity: 0.6 }, { opacity: 0 }] should draw (it doesn't):
+series.fills.template.set("fillGradient", am5.LinearGradient.new(root, {
+  rotation: 0,
+  stops: [{ opacity: 0 }, { opacity: 0.6 }]    // the same stops, reversed: clear on the left, 0.6 on the right
 }));
 ```
 
-A bullet `Graphics` that sets none of `fill`, `fillGradient`, `fillPattern`, `stroke`, `strokeGradient` now inherits all of them from its series, so bullets pick up series gradients and patterns automatically.
+`RadialGradient` is centered on map polygons, line and area fills and bullets since 5.21.1 (with `target` set, on the target). 5.21.1 put one with pixel `x`/`y` off-center on radar fills and similar shapes; 5.21.2 fixes that.
 
 ## Changing fields and axes after creation (5.20.0)
 
@@ -765,6 +824,18 @@ series.set("yAxis", secondaryYAxis);
 
 Both were previously fixed at creation time. Re-setting the series data is required for a value-field change to take effect.
 
+## Moving a point without touching the data list
+
+XY series draw from the **working** values (`valueXWorking`, `valueYWorking`), so `dataItem.set("valueY", v)` changes nothing on screen. Set the working keys too, or change the data row:
+
+```js
+var dataItem = series.dataItems[0];
+dataItem.setAll({ valueX: 4, valueY: 7, valueXWorking: 4, valueYWorking: 7 });   // jumps
+
+series.data.setIndex(0, { x: 4, y: 7 });   // animates over interpolationDuration
+// per-frame updates through setIndex: set interpolationDuration: 0 on the series, or the points lag behind
+```
+
 ---
 
 # amCharts 5 XY Charts — Working Examples

package/extended/charts/map-chart.md

@@ -60,10 +60,16 @@ The global name of the regional map will reflect its sub-directory structure.
 
 For example, congressional district map of Florida would load like this:
 
-import am5geodata\_region\_usa\_congressional2022\_worldLow from "@amcharts/amcharts5-geodata/region/usa/congressional2022/flLow";
+```javascript
+import am5geodata_region_usa_congressional120_flLow from "@amcharts/amcharts5-geodata/region/usa/congressional120/flLow";
+```
 
-<!-- Will load as a global <span style="background-color: inherit;font-family: inherit;font-size: inherit;color: initial">am5geodata\_region\_usa\_congressional\_worldLo</span>w variable -->
-<script src="https://cdn.amcharts.com/lib/5/geodata/region/usa/congressional2022/worldLow.js"></script>
+```html
+<!-- Loads as the global am5geodata_region_usa_congressional120_flLow -->
+<script src="https://cdn.amcharts.com/lib/5/geodata/region/usa/congressional120/flLow.js"></script>
+```
+
+NOTE The global name is `am5geodata_` plus the path below `geodata/` with `/` turned into `_`. The US congressional maps come in versioned packs: `congressional` (117th Congress, the original set), `congressional2022` (118th), `congressional2025` (119th) and `congressional120` (120th, the newest, in geodata 5.1.6). Each pack has `usaCongressionalLow`/`High` and one map per state (`flLow`, `caLow`, …). The MCP server's `list_geodata` tool lists every map with its path, global name and import. *(Corrected: the published example loads `congressional2022/worldLow.js`, which does not exist.)*
 
 MORE INFOFor more information on how to use regional maps, visit "[Using regional maps](https://www.amcharts.com/docs/v5/tutorials/using-regional-maps/)" tutorial.
 

package/extended/concepts/colors-gradients-and-patterns.md

@@ -22,6 +22,21 @@ Typical settings to use colors for is `fill` which indicates area fill color, an
 
 Text color is specified via its `fill` setting.
 
+### Blending colors (5.21.2)
+
+`am5.Color.interpolateColors(position, colors, mode)` returns a color on a scale through any number of colors, spread evenly. `position` runs from `0` (the first color) to `1` (the last), so with three colors `0.5` gives the middle one; values outside that range get the first or last color. `mode` is `"rgb"` (default) or `"hsl"`. For two colors, `am5.Color.interpolate(position, from, to, mode)` does the same.
+
+```javascript
+// Red, yellow and green, from the interface colors
+const ic = root.interfaceColors;
+const scale = [ic.get("negative"), ic.get("warning"), ic.get("positive")];
+
+am5.Color.interpolateColors(0.5, scale);  // the "warning" yellow
+am5.Color.interpolateColors(0.25, scale); // halfway between red and yellow
+```
+
+To color series elements by value on such a scale, use a heat rule's [`stops`](https://www.amcharts.com/docs/v5/concepts/settings/heat-rules/#multiple-stops) setting, and show it in a heat legend with its [`colors`](https://www.amcharts.com/docs/v5/concepts/legend/heat-legend/#More_than_two_colors) setting.
+
 ## Color sets
 
 Colors sets are basically collections of colors with ability to generate new colors according to certain rules as needed.
@@ -130,6 +145,18 @@ Primary button background when pressed.
 
 Primary button background when active.
 
+`primaryButtonDisabled`
+
+0xdadada
+
+Primary button fill color when disabled.
+
+`primaryButtonTextDisabled`
+
+0xffffff
+
+Primary button text color when disabled.
+
 `primaryButtonText`
 
 0xffffff
@@ -226,6 +253,12 @@ Color to express positive value (e.g. in candlesticks).
 
 Color to express negative value (e.g. in candlesticks).
 
+`warning` *(5.21.2)*
+
+0xf2c230
+
+A yellow between `negative` and `positive`: a warning, or the middle of a scale from bad to good (e.g. heat rule [`stops`](https://www.amcharts.com/docs/v5/concepts/settings/heat-rules/#multiple-stops)).
+
 NOTEDefault colors may be overridden by [themes](https://www.amcharts.com/docs/v5/concepts/themes/).
 
 ### Using interface colors

package/extended/concepts/data.md

@@ -541,7 +541,7 @@ i
 
 Date/time formatted according to [ISO8601 format](http://en.wikipedia.org/wiki/ISO_8601).
 
-NOTE If `dateFormat` is not set, and processor encounters a string-based value it needs to parse, it will use chart-wide date format (`root.dateFormatter.dateFormat`).
+NOTE If `dateFormat` is not set, string dates are read by the browser's `Date` (as `new Date(string)` would), not with the chart-wide date format (`root.dateFormatter.dateFormat`). The browser takes a date-only string such as `"2024-03-15"` as midnight UTC, and a date-time string such as `"2024-03-15T10:00:00"` as local time. Before 5.21.1, string dates without a `dateFormat` were all read as 1 January 1970, so older versions need `dateFormat` set. *(5.21.1)*
 
 
 ### Parsing colors

package/extended/concepts/legend/heat-legend.md

@@ -1,7 +1,7 @@
 ---
 title: "Heat legend"
 source: "https://www.amcharts.com/docs/v5/concepts/legend/heat-legend/"
-scraped: "2026-03-15"
+scraped: "2026-10-18"
 ---
 
 Heat legend is a visual tool that usually compliments a chart with [heat rules](https://www.amcharts.com/docs/v5/concepts/settings/heat-rules/).
@@ -10,7 +10,7 @@ Heat legend is a visual tool that usually compliments a chart with [heat rules](
 
 We can add a heat legend like a regular legend, by pushing and instance of `[HeatLegend](https://www.amcharts.com/docs/v5/reference/heatlegend/)` into chart's children.
 
-Heat legend also requires at least two settings: `startColor` and `endColor`.
+Heat legend also requires at least two settings: `startColor` and `endColor` (or [`colors`](#More_than_two_colors) instead).
 
 Those will define colors for start (lowest value end) and end (highest value end) of the legend.
 
@@ -114,12 +114,47 @@ var heatLegend = chart.children.push(
   })
 );
 
+
 `stepCount: 1` (default)
 
+
 `stepCount: 5`
 
+
 `stepCount: 10`
 
+## More than two colors
+
+For a scale through more than two colors, e.g. red to yellow to green, use `colors` instead of `startColor` and `endColor`. The colors go from the lowest value end to the highest:
+
+let heatLegend = chart.children.push(
+  am5.HeatLegend.new(root, {
+    orientation: "vertical",
+    colors: \[
+      root.interfaceColors.get("negative"),
+      root.interfaceColors.get("warning"),
+      root.interfaceColors.get("positive")
+    \]
+  })
+);
+
+var heatLegend = chart.children.push(
+  am5.HeatLegend.new(root, {
+    orientation: "vertical",
+    colors: \[
+      root.interfaceColors.get("negative"),
+      root.interfaceColors.get("warning"),
+      root.interfaceColors.get("positive")
+    \]
+  })
+);
+
+By default, the legend shows a gradient through all the colors, spread evenly along it. With `stepCount` set to anything above `1`, it shows one step per color instead: the number itself is ignored.
+
+Tooltips shown with [`showValue()`](#Triggering_tooltip) take their color from the same scale.
+
+NOTE`colors` is available since version 5.21.2. To color chart elements on the same scale, use heat rule's [`stops`](https://www.amcharts.com/docs/v5/concepts/settings/heat-rules/#multiple-stops) setting with the same colors.
+
 ## Tooltip
 
 ### Setting scale
@@ -149,13 +184,13 @@ var heatLegend = chart.children.push(
 If we don't know extreme values, we can extract that from series, when its data is validated:
 
 series.events.on("datavalidated", function () {
-  heatLegend.set("startValue", series.getPrivate("valueHigh"));
-  heatLegend.set("endValue", series.getPrivate("valueLow"));
+  heatLegend.set("startValue", series.getPrivate("valueLow"));
+  heatLegend.set("endValue", series.getPrivate("valueHigh"));
 });
 
 series.events.on("datavalidated", function () {
-  heatLegend.set("startValue", series.getPrivate("valueHigh"));
-  heatLegend.set("endValue", series.getPrivate("valueLow"));
+  heatLegend.set("startValue", series.getPrivate("valueLow"));
+  heatLegend.set("endValue", series.getPrivate("valueHigh"));
 });
 
 ### Triggering tooltip

package/extended/concepts/settings/heat-rules.md

@@ -1,7 +1,7 @@
 ---
 title: "Heat rules"
 source: "https://www.amcharts.com/docs/v5/concepts/settings/heat-rules/"
-scraped: "2026-03-15"
+scraped: "2026-10-18"
 ---
 
 Heat rules is a way to apply value-dependent setting values on series elements.
@@ -56,11 +56,11 @@ A settings key to apply heat value to on actual elements.
 
 `min`
 
-Lower end value of the spectrum, corresponding to the lowest value in all elements affected by the heat rule.
+Lower end value of the spectrum, corresponding to the lowest value in all elements affected by the heat rule. Not needed if [`stops`](#multiple-stops) is set.
 
 `max`
 
-Higher end value of the spectrum, corresponding to the highest value in all elements affected by the heat rule.
+Higher end value of the spectrum, corresponding to the highest value in all elements affected by the heat rule. Not needed if [`stops`](#multiple-stops) is set.
 
 `dataField`
 
@@ -248,6 +248,90 @@ NOTE If we set `minValue` and `maxValue` we don't need series to aggregate value
 
 NOTE Before 5.21.0, `minValue: 0` and `maxValue: 0` were ignored, and the series' lowest or highest value was used instead. Since 5.21.0 a `0` is used like any other value.
 
+## Multiple stops
+
+`min` and `max` make a scale between two values. For a scale through more than two, e.g. red to yellow to green, use `stops` instead: an array of values, from the lowest to the highest.
+
+series.set("heatRules", \[{
+  target: series.columns.template,
+  dataField: "valueY",
+  stops: \[
+    root.interfaceColors.get("negative"),
+    root.interfaceColors.get("warning"),
+    root.interfaceColors.get("positive")
+  \],
+  key: "fill"
+}\])
+
+series.set("heatRules", \[{
+  target: series.columns.template,
+  dataField: "valueY",
+  stops: \[
+    root.interfaceColors.get("negative"),
+    root.interfaceColors.get("warning"),
+    root.interfaceColors.get("positive")
+  \],
+  key: "fill"
+}\])
+
+The element with the lowest value gets the first stop, and the one with the highest value gets the last. The stops are spread evenly across the range, so in the above, the middle value gets yellow, and the values in between blend from one stop to the next.
+
+Stops can be numbers, percents, or colors, but all of one kind. If `minValue` and `maxValue` are set, values outside that range get the first or last stop.
+
+NOTE`stops` is available since version 5.21.2. To show the same scale in a [heat legend](https://www.amcharts.com/docs/v5/concepts/legend/heat-legend/), pass the same colors to its `colors` setting.
+
+## Logarithmic scale
+
+By default, values are spread between `min` and `max` (or across `stops`) on a linear scale.
+
+If values differ by orders of magnitude, e.g. populations of countries, a few very large values would get the far end of the scale, while all the others would end up close together near its start. Setting `logarithmic: true` spreads them on a logarithmic scale instead, so the differences between smaller values show too:
+
+polygonSeries.set("heatRules", \[{
+  target: polygonSeries.mapPolygons.template,
+  dataField: "value",
+  min: am5.color(0xffd19a),
+  max: am5.color(0xb3261e),
+  logarithmic: true,
+  key: "fill"
+}\])
+
+polygonSeries.set("heatRules", \[{
+  target: polygonSeries.mapPolygons.template,
+  dataField: "value",
+  min: am5.color(0xffd19a),
+  max: am5.color(0xb3261e),
+  logarithmic: true,
+  key: "fill"
+}\])
+
+NOTEA logarithmic scale works with values above zero only.
+
+## Elements without a value
+
+Elements whose data item has no value in `dataField` are not affected by the heat rule, and keep the setting value from their template. E.g. countries on a map that are not in data.
+
+To give such elements a specific value instead, use the `neutral` setting:
+
+polygonSeries.set("heatRules", \[{
+  target: polygonSeries.mapPolygons.template,
+  dataField: "value",
+  min: am5.color(0xffd19a),
+  max: am5.color(0xb3261e),
+  neutral: am5.color(0xdddddd),
+  key: "fill"
+}\])
+
+polygonSeries.set("heatRules", \[{
+  target: polygonSeries.mapPolygons.template,
+  dataField: "value",
+  min: am5.color(0xffd19a),
+  max: am5.color(0xb3261e),
+  neutral: am5.color(0xdddddd),
+  key: "fill"
+}\])
+
+The above will make countries with no data light gray.
+
 ## Custom functions
 
 If we need to do something fancier than just set value of a setting, we can use heat rule's `customFunction` property.
@@ -261,10 +345,16 @@ If set, instead of setting value of the setting directly on an element, this fun
 
 It'll be up to the custom function to determine what settings and to what values to set.
 
+The function is also called for elements without a value, with the value parameter `undefined`.
+
 series.set("heatRules", \[{
   target: series.columns.template,
   dataField: "value",
   customFunction: function(sprite, min, max, value) {
+    if (value === undefined) {
+      // No value: leave the element as it is
+      return;
+    }
     if (value < 100) {
       sprite.set("fill", am5.color(0xff0000));
     }
@@ -278,6 +368,10 @@ series.set("heatRules", \[{
   target: series.columns.template,
   dataField: "value",
   customFunction: function(sprite: am5.Sprite, min, max, value) {
+    if (value === undefined) {
+      // No value: leave the element as it is
+      return;
+    }
     if (value < 100) {
       (sprite as am5.Graphics).set("fill", am5.color(0xff0000));
     }
@@ -291,6 +385,10 @@ series.set("heatRules", \[{
   target: series.columns.template,
   dataField: "value",
   customFunction: function(sprite, min, max, value) {
+    if (value === undefined) {
+      // No value: leave the element as it is
+      return;
+    }
     if (value < 100) {
       sprite.set("fill", am5.color(0xff0000));
     }

package/extended/concepts/themes.md

@@ -185,7 +185,8 @@ root.setThemes([
   am5themes_Animated.new(root),
   am5themes_Adaptive(root, {
     baseColor: 0x2c6e91,   // primary base color. The FIRST generated color is this color,
-                           // so a brand color always appears in the chart.
+                           // so a brand color always appears in the chart
+                           // (unless keepContrast has to change it, see below).
                            // Default: green-to-yellow (#4b8e39 first, #ffdd00 last)
     baseColor2: 0xffdd00,  // optional: palette spans the two colors, interpolated in OKLCH,
                            // instead of fanning out from a single hue
@@ -195,6 +196,27 @@ root.setThemes([
 ]);
 ```
 
+#### More settings (5.21.2)
+
+Both themes also take these settings, all off by default:
+
+- `interleave: true` takes the colors in an alternating order (1, 4, 2, 5, 3, 6), so series next to each other differ more. It helps most with Adaptive's `baseColor2`, whose gradient puts similar colors side by side. In Monochrome, the `accent` stays first.
+- `mapShade: true` fills map polygons with a mid shade of the base color (`baseColor` in Adaptive, `color` in Monochrome), about as light as a map's default land, instead of the base color itself.
+- `keepContrast` lightens (in dark mode) or darkens colors that would have too little contrast with the background, keeping their hue: `true` for at least 3:1, or a ratio, e.g. `4.5`. It applies to the series colors and the primary buttons. In Adaptive it also covers `baseColor` and `baseColor2`, so the first color may no longer be exactly `baseColor`. In Monochrome it also covers the `accent`, and the end of the ramp nearest the background moves, with the other shades spread evenly up to it.
+
+```javascript
+root.setThemes([
+  am5themes_Animated.new(root),
+  am5themes_Adaptive(root, {
+    baseColor: 0xffee88,   // too light on white: keepContrast darkens it to 3:1
+    baseColor2: 0x2c6e91,
+    interleave: true,
+    mapShade: true,
+    keepContrast: true     // or a ratio, e.g. 4.5
+  })
+]);
+```
+
 ## Applying
 
 Each chart can have multiple themes applied to it.

package/extended/examples/candlestick-ohlc/box-plot-chart.md

@@ -2,7 +2,7 @@
 title: "Box Plot Chart"
 source: "https://www.amcharts.com/demos/box-plot-chart/"
 category: "candlestick-ohlc"
-scraped: "2026-10-08"
+scraped: "2026-10-18"
 ---
 
 A box plot sums up a spread of values in one mark: the box holds the middle half, the line across it is the median, and the whiskers reach the lowest and highest values. Here, nine days side by side.

package/extended/examples/candlestick-ohlc/candlestick-chart.md

@@ -2,7 +2,7 @@
 title: "Candlestick Chart"
 source: "https://www.amcharts.com/demos/candlestick-chart/"
 category: "candlestick-ohlc"
-scraped: "2026-10-08"
+scraped: "2026-10-18"
 ---
 
 A candlestick chart packs a day of trading into one mark: the body spans the opening and closing price, the wick the day’s low and high. This one holds 2,000 days; zoom out and they merge into weekly, then monthly candles.

package/extended/examples/candlestick-ohlc/ohlc-chart.md

@@ -2,7 +2,7 @@
 title: "OHLC Chart"
 source: "https://www.amcharts.com/demos/ohlc-chart/"
 category: "candlestick-ohlc"
-scraped: "2026-10-08"
+scraped: "2026-10-18"
 ---
 
 An OHLC chart shows the same four prices as a candlestick, drawn as a bar: a line from low to high, a tick to the left for the open and one to the right for the close. Zoom out and 2,000 days group into weeks and months.

package/extended/examples/candlestick-ohlc/on-demand-data-loading.md

@@ -2,7 +2,7 @@
 title: "On-Demand Data Loading"
 source: "https://www.amcharts.com/demos/on-demand-data-loading/"
 category: "candlestick-ohlc"
-scraped: "2026-10-08"
+scraped: "2026-10-18"
 ---
 
 A candlestick chart with volume that fetches its data from the server only as needed: it starts with 50 days and loads more as you drag back in time. The buttons under it switch to hourly or monthly candles.

package/extended/examples/candlestick-ohlc/professional-candlesticks.md

@@ -2,7 +2,7 @@
 title: "Professional Candlesticks"
 source: "https://www.amcharts.com/demos/professional-candlesticks/"
 category: "candlestick-ohlc"
-scraped: "2026-10-08"
+scraped: "2026-10-18"
 ---
 
 Candlesticks in the hollow style traders call professional. Each candle says two things: hollow if the day closed above its open, filled if below, and green or red for a close above or below the day before.

package/extended/examples/candlestick-ohlc/stock-chart-candlesticks.md

@@ -2,7 +2,7 @@
 title: "Stock Chart Candlesticks"
 source: "https://www.amcharts.com/demos/stock-chart-candlesticks/"
 category: "candlestick-ohlc"
-scraped: "2026-10-08"
+scraped: "2026-10-18"
 ---
 
 Fifteen years of daily Microsoft prices as candlesticks over volume. It is a plain XY chart: two value axes stacked over one date axis that skips the weekends.