@amcharts/amcharts5-mcp 1.3.2 → 1.5.0

package/content/wordcloud.md

@@ -57,15 +57,29 @@ series.appear(1000);
 |---------|------|---------|-------------|
 | `categoryField` | string | — | Data field for word text (required) |
 | `valueField` | string | — | Data field for word weight/size (required) |
-| `maxFontSize` | number \| Percent | `100` | Maximum font size (a `Percent` is relative to the smaller chart dimension) |
-| `minFontSize` | number \| Percent | `10` | Minimum font size (a `Percent` is relative to the smaller chart dimension) |
-| `angles` | number[] | `[0]` | Allowed rotation angles for words |
+| `maxFontSize` | number \| Percent | `am5.percent(15)` | Maximum font size (a `Percent` is relative to the smaller chart dimension) |
+| `minFontSize` | number \| Percent | `am5.percent(2)` | Minimum font size (a `Percent` is relative to the smaller chart dimension) |
+| `angles` | number[] | `[0, -90]` | Allowed rotation angles for words. **Any angle works** as of 5.20.1 (e.g. `[0, -30, -45]`), not just `0`/`±90` as in earlier versions |
+| `randomizeAngles` | boolean | `true` | `true` = each word picks a random angle from `angles`. `false` = words cycle through `angles` in order (word 0 → `angles[0]`, …) which, with `randomness: 0`, makes the layout reproducible. *(5.20.1)* |
 | `randomness` | number (0–1) | `0` | Layout randomness (0 = ordered by value, 1 = fully random) |
+| `allowNesting` | boolean | `true` | `true` = small words tuck into the concavities of bigger ones (tight packing, bounding boxes may overlap). `false` = whole bounding boxes are packed so they never overlap — use this when labels have an opaque `background`. *(5.20.1)* |
 | `minWordLength` | number | `1` | Skip words shorter than this |
+| `minValue` | number | — | Skip words occurring fewer times than this |
 | `maxCount` | number | — | Maximum number of words to display |
 | `excludeWords` | string[] | `[]` | Words to exclude |
 | `text` | string | — | Raw text to parse — words are extracted and weighted by frequency automatically |
 | `colors` | ColorSet | — | Color set for words |
+| `fillField` | string | — | Data field holding a per-word label fill color |
+| `autoFit` | boolean | `true` | Scale font sizes down so all words fit the available area |
+| `step` | number | `15` | Step size used when searching for the next word placement |
+| `svgPath` | string | — | Arrange words to fill this SVG path shape (experimental) *(5.20.1)* |
+| `maskByShape` | boolean | `false` | Clip words to the `svgPath` outline for a crisp silhouette. Requires `svgPath`. *(5.20.1)* |
+| `shapeTolerance` | number | `0` | Extra pixels a word may spill past the `svgPath` outline; negative pulls words inside, creating padding. Requires `svgPath`. *(5.20.1)* |
+| `animationDuration` | number | — | Duration of word animation on chart resize |
+| `sequencedInterpolation` | boolean | `true` | Stagger the word reveal instead of showing all at once |
+| `sequencedDelay` | number | `15` | Milliseconds between words when `sequencedInterpolation` is on |
+
+**Parser settings and `text`:** `minValue`, `maxCount`, `minWordLength` and `excludeWords` are consumed when `text` is parsed. Since **5.20.0** changing any of them on a live series re-parses `text` automatically. On older versions they only took effect on the next `text` assignment — set them **before** `text`, or re-assign `text` after changing them.
 
 ### excludeWords example
 
@@ -77,7 +91,81 @@ am5wc.WordCloud.new(root, {
 });
 ```
 
-**Note:** amCharts WordCloud does not support mask/shape rendering (words constrained to a custom shape). Words are arranged in a rectangular area.
+## Shaped word clouds — `svgPath` (5.20.1)
+
+Words can be arranged to fill an arbitrary shape. The path is scaled proportionally to fit the plot area.
+
+```js
+var series = root.container.children.push(
+  am5wc.WordCloud.new(root, {
+    categoryField: "tag",
+    valueField: "weight",
+    svgPath: "M10,30 A20,20 0,0,1 50,30 A20,20 0,0,1 90,30 Q90,60 50,90 Q10,60 10,30 z", // heart
+    maskByShape: true,     // clip letters that overhang the outline
+    shapeTolerance: -4,    // negative = padding inside the shape
+    angles: [0],           // simple shapes fill better with fewer angles
+    minFontSize: am5.percent(2),
+    maxFontSize: am5.percent(12)
+  })
+);
+```
+
+The shape outline itself is drawn behind the words as `series.shape` (a `Graphics`), by default a faint 10%-opacity silhouette. Style or hide it:
+
+```js
+series.shape.setAll({ fill: am5.color(0xff3366), fillOpacity: 0.08 });
+series.shape.set("fillOpacity", 0);      // no visible silhouette, words only
+```
+
+Style `fill`/`stroke` only — the series manages the shape's geometry (`svgPath`, `scale`, `x`, `y`) and its `forceHidden` flag, so setting those is pointless. To hide the silhouette use `fillOpacity: 0`.
+
+**Caveats:** this is an experimental feature and the fit is approximate. Favor simple, bold shapes over thin or highly concave ones, and tune `shapeTolerance`, `maskByShape`, `angles`, `minFontSize`/`maxFontSize` per shape. `shapeTolerance` affects placement only — the drawn outline never moves.
+
+## Diagonal angles (5.20.1)
+
+Before 5.20.1 only `0`, `90` and `-90` were handled. The layout rewrite rasterizes each word and its collision mask at the word's actual angle, so arbitrary angles now work — and neighbors pack into the corners of a rotated word's footprint instead of reserving its full axis-aligned bounding box.
+
+```js
+am5wc.WordCloud.new(root, {
+  categoryField: "tag",
+  valueField: "weight",
+  angles: [0, -30, -45, -60, -90]
+});
+```
+
+One caveat: if a word comes out very wide relative to the available area, the layout flips it to `0` or `±90` for a better fit — but only when that value is present in your `angles` array. Leave them out and your angles are used as given.
+
+## Reproducible layouts
+
+By default word placement is randomized, so the cloud looks different on every render. For a stable layout:
+
+```js
+am5wc.WordCloud.new(root, {
+  categoryField: "tag",
+  valueField: "weight",
+  randomness: 0,           // order strictly by value
+  randomizeAngles: false   // cycle `angles` in order instead of picking randomly
+});
+```
+
+## Labels with opaque backgrounds
+
+Nesting lets small words sit inside the gaps of larger ones, which looks wrong once labels have a solid background — the background rectangles slide over neighbors. Turn nesting off so whole bounding boxes are packed:
+
+```js
+series.set("allowNesting", false);
+series.labels.template.setAll({
+  background: am5.RoundedRectangle.new(root, { fill: am5.color(0x1f2933), fillOpacity: 1 })
+});
+```
+
+## Breaking change in 5.20.1
+
+The layout is now computed synchronously in a single pass instead of one word per animation frame — much faster for large clouds. Consequences for existing code:
+
+- The per-data-item `ghostLabel` no longer exists — `dataItem.get("ghostLabel")` returns `undefined`.
+- Labels are held in an internal container, so code walking `series.children` to find labels breaks. Use `series.labels` (the `ListTemplate`) or `dataItem.get("label")`.
+- The reveal is staggered via `sequencedInterpolation`/`sequencedDelay` (defaults `true` / `15`ms) rather than by the layout itself.
 
 ## Customizing labels
 

package/content/xy.md

@@ -95,6 +95,7 @@ chart.set("cursor", am5xy.XYCursor.new(root, {
 ### Scrollbar
 ```js
 chart.set("scrollbarX", am5.Scrollbar.new(root, { orientation: "horizontal" }));
+// opposite: true (5.20.2) puts scrollbarX below the plot / scrollbarY on the left
 ```
 
 ### Legend
@@ -191,6 +192,10 @@ const xAxis = chart.xAxes.push(am5xy.DateAxis.new(root, {
 - `markUnitChange: true` — highlights when time unit changes on axis labels (e.g., new month)
 - `tooltipDateFormat` — format string for cursor tooltip
 
+**Live updates — two settings that do not refresh on `set()`:**
+- **Date format maps** (`dateFormats`, `periodChangeDateFormats`, `minorDateFormats`): after `axis.set("dateFormats", {...})` already-rendered labels keep their old text. `axis.markDirtyValues()` is not enough — call **`axis.markDirtySize()`** to make the axis re-run label formatting.
+- **`groupIntervals`** (with `groupData: true`): amCharts only (re)computes grouping when a series' data is set, so changing the allowed intervals on an already-grouped axis does nothing until you re-set the data on every series bound to the axis: `series.data.setAll(series.data.values.slice())`.
+
 **Data format:**
 ```js
 series.data.setAll([
@@ -324,7 +329,12 @@ series.columns.template.setAll({
   width: am5.percent(80),        // column width
 });
 
-// Individual column colors from data:
+// Individual column colors (5.20.4) — declarative, serializes to JSON:
+series.set("colorByDataItem", true);          // each column takes the next color from series.get("colors")
+// series.set("colors", am5.ColorSet.new(root, { colors: [...] }));   // optional own palette (the series makes one if absent)
+// Per-item color from data instead: templateField + a `fill` in each data item (see pie.md "Data-driven slice colors")
+
+// Pre-5.20.4 fallback — an adapter (does NOT survive JSON serialization):
 series.columns.template.adapters.add("fill", (fill, target) => {
   return chart.get("colors").getIndex(series.columns.indexOf(target));
 });
@@ -382,6 +392,17 @@ chart.set("cursor", am5xy.XYCursor.new(root, { snapToSeries: [series] }));
 
 **Do NOT** pass `lineX`/`lineY` as constructor options to `XYCursor.new()`. Always access `cursor.lineX` / `cursor.lineY` after creation.
 
+**Easier edge selections (`clickTolerance`, 5.20.0)** — by default a zoom/select drag can only begin inside the plot area, which makes selecting right up to an edge fiddly. `clickTolerance` widens the area where a press may *start*:
+
+```js
+chart.set("cursor", am5xy.XYCursor.new(root, {
+  behavior: "selectX",
+  clickTolerance: 20    // px outside the plot area where a drag may start (default 0)
+}));
+```
+
+The selection itself still starts at the plot edge — the press point is clamped into the plot area.
+
 For timeline charts, use `am5timeline.CurveCursor` instead — see `references/timeline.md`.
 
 ## Scrollbar
@@ -392,6 +413,7 @@ Enables zooming/panning via scrollbar. Can optionally include a preview chart.
 // Simple scrollbar:
 chart.set("scrollbarX", am5.Scrollbar.new(root, {
   orientation: "horizontal"
+  // opposite: true   // (5.20.2) place below the plot instead of above (scrollbarY: left instead of right)
 }));
 
 // Scrollbar with preview chart:
@@ -599,8 +621,13 @@ var series2 = chart.series.push(am5xy.LineSeries.new(root, {
   xAxis: xAxis, yAxis: yAxis2,
   valueYField: "units", valueXField: "date"
 }));
+
+// Removing an axis — go through the list, NOT axis.dispose():
+chart.yAxes.removeValue(yAxis2);   // the list auto-disposes the removed axis
 ```
 
+`axis.dispose()` marks the axis disposed but **leaves it in `chart.yAxes`/`chart.xAxes`** (unlike `series.dispose()`, which removes itself from `chart.series`). The stale entry keeps rendering in anything built from the list and makes `ChartSerializer` throw `Template is disposed`. Always use `removeValue(axis)` / `removeIndex(i)`.
+
 ## Axis titles
 
 ```js
@@ -675,6 +702,45 @@ am5xy.XYChart.new(root, {
 })
 ```
 
+## Distinguishing line series without color (5.20.0)
+
+`XYChart` can cycle stroke widths and dash patterns across line series as they are added, exactly the way `colors` cycles series colors. Useful for print, for color-blind-safe output, or with the `Patterns` theme.
+
+```js
+const chart = root.container.children.push(am5xy.XYChart.new(root, {
+  strokeWidths: [3, 2, 2],                    // px, cycled per line series
+  strokeDasharrays: [0, [6, 3], [2, 2]]       // 0 or [] = solid line
+}));
+```
+
+Each added line series takes the next entry by position, wrapping around when the array runs out.
+
+## Series gradients (5.20.0)
+
+`Series` accepts `fillGradient` and `strokeGradient`:
+
+```js
+series.set("fillGradient", am5.LinearGradient.new(root, {
+  stops: [{ opacity: 0.6 }, { opacity: 0 }],
+  rotation: 90
+}));
+```
+
+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.
+
+## Changing fields and axes after creation (5.20.0)
+
+```js
+// Swap which data field a series plots — then re-set the data
+series.set("valueYField", "profit");
+series.data.setAll(data);
+
+// Move a series to a different axis
+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.
+
 ---
 
 # amCharts 5 XY Charts — Working Examples

package/extended/charts/word-cloud.md

@@ -2,6 +2,8 @@
 title: "Word cloud"
 source: "https://www.amcharts.com/docs/v5/charts/word-cloud/"
 scraped: "2026-03-15"
+updated: "2026-08-05"
+updatedFor: "@amcharts/amcharts5@5.20.1"
 ---
 
 [Word clouds](https://en.wikipedia.org/wiki/Tag_cloud) (or tag clouds) help visualize weight or importance of individual words from a keyword list or a free-form text.
@@ -247,13 +249,27 @@ Series setting responsible for identifying possible angles is named `angles`.
 
 It's an array of numbers, and the default is `[0, -90]` meaning that words can come at zero (horizontal) or 90 (vertical) angle.
 
-The only supported values are `0`, `90`, and `-90`.
-
 To make all words horizontal, set it to `[0]`. To make all vertical, use `[90]`.
 
+**Any angle is supported as of 5.20.1.** Earlier versions only handled `0`, `90` and `-90`; the layout rewrite in 5.20.1 rasterizes each word and its collision mask at the word's actual angle, so diagonal values work and neighboring words pack into the corners of a rotated word's footprint rather than reserving its full axis-aligned bounding box.
+
+```javascript
+am5wc.WordCloud.new(root, {
+  categoryField: "tag",
+  valueField: "weight",
+  angles: [0, -30, -45, -60, -90]   // arbitrary angles, not just 0/±90
+});
+```
+
+NOTE There is one place where `0` and `±90` still get special treatment: if a word comes out very wide relative to the available area, the layout will flip it to `0` or `±90` for a better fit — but only if that value is present in your `angles` array. Omit them and your angles are used as given.
+
+#### Choosing angles
+
+`randomizeAngles` (default `true`) picks a random entry from `angles` for each word. Set it to `false` to cycle through `angles` in order — combined with `randomness: 0` this produces a reproducible layout.
+
 #### Rotating whole series
 
-Even though non-horizontal/vertical angles are not supported, the whole series can easily be rotated to achieve intermediate angle effect by `rotation` and relative centering settings to the series itself.
+Instead of (or in addition to) rotating individual words, the whole series can be rotated using `rotation` and relative centering settings on the series itself.
 
 let series = root.container.children.push(
   am5wc.WordCloud.new(root, {

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

@@ -2,6 +2,8 @@
 title: "Patterns"
 source: "https://www.amcharts.com/docs/v5/concepts/colors-gradients-and-patterns/patterns/"
 scraped: "2026-03-15"
+updated: "2026-08-05"
+updatedFor: "@amcharts/amcharts5@5.20.1"
 ---
 
 This tutorial looks at how we can create patterns to use for element fills ant outlines.
@@ -43,8 +45,57 @@ Example
 
 `[PathPattern](https://www.amcharts.com/docs/v5/reference/pathpattern/)`
 
+`[StarPattern](https://www.amcharts.com/docs/v5/reference/starpattern/)` (5.20.0)
+
+`[TrianglePattern](https://www.amcharts.com/docs/v5/reference/trianglepattern/)` (5.20.0)
+
 Patterns can be customized by applying rotation, gap, stroke, and other settings, which we'll explore in a bit.
 
+### Star and triangle patterns (5.20.0)
+
+`StarPattern` and `TrianglePattern` work like `RectanglePattern`/`CirclePattern` — a grid of shapes with a `gap` between them, and an optional `checkered` mode that places only every second shape.
+
+```javascript
+columnSeries.columns.template.set("fillPattern", am5.StarPattern.new(root, {
+  color: am5.color(0xffffff),
+  radius: 5,               // outer radius of the star, in pixels. Default: 5
+  innerRadius: am5.percent(50), // inner radius: pixels or a percent of `radius`. Default: 50%
+  spikes: 5,               // number of spikes. Default: 5
+  gap: 6,                  // gap between stars, in pixels. Default: 6
+  checkered: false,        // place every second star. Default: false
+  centered: true           // center stars in their grid cell. Default: true
+}));
+
+columnSeries.columns.template.set("fillPattern", am5.TrianglePattern.new(root, {
+  color: am5.color(0xffffff),
+  maxWidth: 8,             // width of the triangle, in pixels. Default: 8
+  maxHeight: 8,            // height of the triangle, in pixels. Default: 8
+  gap: 6,                  // gap between triangles, in pixels. Default: 6
+  checkered: false,
+  centered: true
+}));
+```
+
+### `rotateShapes` (5.20.0)
+
+`RectanglePattern`, `StarPattern` and `TrianglePattern` accept a `rotateShapes` setting (default `false`).
+
+When `false`, `rotation` rotates the whole pattern grid. That does not tile periodically on an axis-aligned tile, so you usually have to enlarge `width`/`height` and tweak `gap` to avoid seams — expensive on large tiles.
+
+When `true`, `rotation` instead rotates **each shape around its own center** while the grid stays axis-aligned. This tiles seamlessly (a small `width`/`height` is enough) and is significantly faster.
+
+```javascript
+columnSeries.columns.template.set("fillPattern", am5.RectanglePattern.new(root, {
+  color: am5.color(0xffffff),
+  rotation: 45,
+  rotateShapes: true    // rotate each rectangle, not the whole grid
+}));
+```
+
+NOTE Star, triangle, rectangle and circle patterns normalize an oversized `width`/`height` down to a single repeat cell (2×2 cells when `checkered`), since the grid repeats every cell anyway. This optimization is skipped when a whole-pattern `rotation` is set — another reason to prefer `rotateShapes`.
+
+NOTE As of 5.20.0, `PathPattern` repeats its `svgPath` as a grid itself instead of drawing once and letting the rendering engine repeat it.
+
 ## Setting pattern
 
 To set a pattern fill on an element, we need to assign it to element's `fillPattern` setting.
@@ -243,6 +294,8 @@ For more configuration options, visit following class references:
 -   [`RectanglePattern` settings](https://www.amcharts.com/docs/v5/reference/linepattern/#Settings)
 -   [`CirclePattern` settings](https://www.amcharts.com/docs/v5/reference/linepattern/#Settings)
 -   [`PathPattern` settings](https://www.amcharts.com/docs/v5/reference/pathpattern/#Settings)
+-   [`StarPattern` settings](https://www.amcharts.com/docs/v5/reference/starpattern/#Settings)
+-   [`TrianglePattern` settings](https://www.amcharts.com/docs/v5/reference/trianglepattern/#Settings)
 
 ## Examples
 

package/extended/concepts/events.md

@@ -2,6 +2,8 @@
 title: "Events"
 source: "https://www.amcharts.com/docs/v5/concepts/events/"
 scraped: "2026-03-15"
+updated: "2026-08-05"
+updatedFor: "@amcharts/amcharts5@5.20.1"
 ---
 
 ## User interactions
@@ -82,6 +84,22 @@ For example, a Scrollbar might invoke a `rangechanged` event when its selection
 
 For a complete list of element's events, see "Events" section in its class reference. Here's a [link](https://www.amcharts.com/docs/v5/reference/scrollbar/#Events) to `Scrollbar` events as an example.
 
+## Global pointer events
+
+Regular pointer events like `pointerdown` fire only when the pointer is over the element itself. The "global" variants fire on **every** element for a pointer action anywhere on the chart surface, which is what you need for drag-style interactions that must keep tracking once the pointer leaves the element.
+
+Available on all elements:
+
+-   `globalpointermove`
+-   `globalpointerup`
+-   `globalpointerdown` — added in 5.20.0
+
+```javascript
+series.columns.template.events.on("globalpointerdown", function(ev) {
+  // fires on a press anywhere on the chart surface
+});
+```
+
 ## Debounced events
 
 Starting with version `5.14`, we can create debounced events, i.e. ensuring that event handler will be invoked only once during specific timeframe.
@@ -148,6 +166,20 @@ xAxis.onPrivate("selectionMax", function(value, target) {
   console.log("End date changed:", end);
 });
 
+### One-shot handlers (5.20.4)
+
+`once(key, callback)` works like `on()` but fires only the first time that setting changes (or is set), then removes itself. `onceDebounced(key, callback, delay)` is the debounced version. Both return an `IDisposer`.
+
+series.once("visible", function(visible, target) {
+  console.log("First visibility change", visible);
+});
+
+xAxis.onceDebounced("start", function(start) {
+  console.log("Zoom settled at", start);
+}, 300);
+
+(Do not confuse with `events.once("eventName", …)`, which has existed for regular events all along.)
+
 ### Removing
 
 Turning off value change events are similar to regular events: we can just use `off()` or `offPrivate()` methods.

package/extended/concepts/serializing/chart-serializer.md

@@ -92,6 +92,16 @@ Include adapters in the output.
 
 Export functions as references or stringify them.
 
+`includeRoot`
+
+`boolean`
+
+`false`
+
+Add a top-level `root` section with the `Root` object's settings and properties (`interfaceColors`, formatters, `utc`, `fps`, `tabindex`) to the output. `JsonParser` applies a `root` section before parsing the chart. *(5.20.2)*
+
+**What gets serialized (5.20.3+):** only **user-set** settings — theme and library defaults are left out, so the output is much smaller than in earlier versions and a value you never set will not appear. Chart-set values and data a chart builds for itself (a flow's nodes, a word cloud's words) are not written. Objects pointing at one another are written as references (e.g. `"@series.get('fill')"`) instead of copies, and big values (a map's `geoJSON`, a `Root`'s locale) are written as the name of the pack they came from and rebuilt on parse.
+
 The below instructs serializer to include both states and adapters in the output:
 
 const serializer = am5plugins\_json.ChartSerializer.new(root, {
@@ -137,13 +147,17 @@ pieSeries.children.push(am5.Label.new(root, {
 -   Venn
 -   WordCloud
 -   MapChart
+-   Gantt *(5.20.3)*
 
 ## Limitations
 
 ### Limited functionality
 
--   Bullets (series or axis): No support for bullets that reference outside objects or context-based bullets (where bullet code depends on context to determine its appearance)
+-   Bullets (series or axis): No support for bullets that reference outside objects or context-based bullets (where bullet code depends on context to determine its appearance). Declare bullet factories as `function(root, series, dataItem)` — a factory that closes over an outer `root` dangles on re-bind.
 -   Bullets or adapters that rely on global variables. Parser runs in a different scope, thus global variables might not be available.
+-   **Adapters do not round-trip.** With `includeAdapters: true` each adapter is written as `{ key, callback: "function (…) {…}" }` (a string) — `JsonParser` does not turn it back into a function. Before 5.20.4 the string was registered as a callback and crashed the chart (`i[s] is not a function` in `Entity.fold`); since 5.20.4 such adapters are skipped on parse. Prefer declarative equivalents (`colorByDataItem` on column series, per-item `fill` + `templateField`, `heatRules`).
+-   **Serialize the chart's top-level container child, not a bare series.** A series whose settings point back at itself (e.g. `selectedDataItem`, a `DataItem` whose `component` is the series) forms a cycle; serialized on its own it overflows `removeEmptyObjects` pruning or makes `JSON.stringify` throw "Converting circular structure". As a child of the serialized container it becomes a `#series-0` reference and the cycle disappears.
+-   A bullet heat rule's throwaway sprite (created while the serializer introspects the bullet factory) has no `dataItem`; as of 5.20.5 the heat-rule loop then throws and, on a `LineSeries`, the stroke disappears. Have the factory call `sprite._setDataItem(dataItem)` or serialize before adding the rule.
 
 ### Unsupported features
 
@@ -153,8 +167,9 @@ pieSeries.children.push(am5.Label.new(root, {
 -   Templates: `setup` function
 -   Custom draw functions
 -   Events
+-   `ZoomableContainer`: its `contents.children` and any `ZoomTools` are not serialized — a serialized `ZoomableContainer` parses back empty. Use `SerialChartContainer` (5.20.2), which builds its own zoomable wrapper, or re-wrap in code after parsing.
+-   Venn: `hoverGraphics` and slice-template `states` are not serialized — re-apply a custom hover in code after parsing.
 
 ### Unsupported chart types
 
--   Gantt
 -   StockChart

package/extended/concepts/serializing.md

@@ -659,6 +659,8 @@ Since adapters are functions, they can't technically be part of a serialized JSO
   }\]
 }
 
+**Adapters and JSON round-trips:** a function reference works only when the config is a JavaScript object in the same scope. Once the config has been through `JSON.stringify` (or `ChartSerializer` with `functionsAs: "string"`), the callback is a string — `JsonParser` does not evaluate it, and since 5.20.4 such an adapter is skipped (before that it was registered as-is and crashed the chart with `i[s] is not a function`). Effects that must survive a round-trip need a declarative equivalent: `colorByDataItem` on column series (5.20.4), a per-item `fill` field with `templateField`, or `heatRules`.
+
 ## Parsing
 
 To parse serialized configs, we'll need:
@@ -679,6 +681,18 @@ parser.parse({
   // ...
 });
 
+### Parse options (`IParseSettings`)
+
+The second argument of `parse()` is an options object — these are **not** settings of the parser itself:
+
+-   `parent` — a `Container` to place the parsed chart into.
+-   `updateTargets` *(5.20.3)* — `"strict"` (default): when the source object has a `type`, a new object of that type is created and replaces the existing one. `"soft"`: if source and target are the same type, only settings are applied onto the existing object (as if `type` had not been specified); objects are replaced only when the types differ. Use `"soft"` to update a live chart from a modified config without rebuilding it.
+
+var parser = am5plugins\_json.JsonParser.new(root);
+parser.parse(config, { parent: root.container, updateTargets: "soft" });
+
+A config may also carry a top-level `root` section *(5.20.2)* whose `settings`/`properties` are applied to the `Root` object before the chart is parsed (`ChartSerializer` writes one when `includeRoot: true`).
+
 ### Post-parse handler
 
 The `parse()` method is asynchronous and returns a `Promise`.

package/extended/concepts/themes.md

@@ -2,6 +2,8 @@
 title: "Themes"
 source: "https://www.amcharts.com/docs/v5/concepts/themes/"
 scraped: "2026-03-15"
+updated: "2026-08-05"
+updatedFor: "@amcharts/amcharts5@5.20.1"
 ---
 
 Themes can be used to apply a collection of settings to chart's elements easily, with a a single line of code.
@@ -62,6 +64,95 @@ A theme that can be used to enable responsive features of the chart - adapting s
 
 A theme that adds alternative default colors.
 
+## Themes added in 5.20.0
+
+The list above is the pre-5.20 set. Version 5.20.0 added a large batch of palette themes, dark variants, and two parameterized themes. All live in `/themes` and load exactly like the others.
+
+### New palette themes
+
+Theme name
+
+Comment
+
+`Colorblind`
+
+A color-blindness-safe palette based on the Okabe-Ito color set.
+
+`Ember`
+
+A warm, fire-oriented palette.
+
+`Midnight`
+
+A dark theme.
+
+`Nord`
+
+A palette based on the Nord color scheme.
+
+`Pastel`
+
+A soft, low-saturation palette.
+
+`Patterns`
+
+Uses pattern fills instead of flat colors — useful for print, monochrome output, and accessibility.
+
+`Petroleum`
+
+A deep blue-green palette.
+
+`Savanna`
+
+A warm, earthy palette.
+
+### New dark variants
+
+Dark counterparts were added for most palette themes: `ColorblindDark`, `DatavizDark`, `FrozenDark`, `KellyDark`, `MaterialDark`, `MoonriseDark`, `NordDark`, `PastelDark`, `PatternsDark`, `SpiritedDark`.
+
+Each already carries dark background and interface colors, so you should NOT additionally apply the `Dark` theme when using one.
+
+### Parameterized themes: `Monochrome` and `Adaptive`
+
+These two themes generate their palette from colors you supply, using OKLCH so the result stays perceptually balanced (even lightness/chroma, evenly spread hues). Because a theme cannot take constructor parameters, they ship as **factory functions** — call them with `(root, settings)`. A `.new(root, settings)` alias also works.
+
+Both are additive: they do not modify any built-in theme.
+
+`Monochrome` — a single-hue lightness ramp:
+
+```javascript
+import am5themes_Monochrome from "@amcharts/amcharts5/themes/Monochrome";
+
+root.setThemes([
+  am5themes_Animated.new(root),
+  am5themes_Monochrome(root, {
+    color: 0x2c6e91,    // base color of the ramp; hex number, CSS string, or Color. Default: #2e7c9e (blue)
+    accent: 0xff7f0e,   // optional: applied to the FIRST series only, so one series stands out
+    count: 7,           // number of steps in the ramp. Default: 7
+    dark: false         // true = dark background + interface colors, ramp runs light-to-mid. Default: false
+  })
+]);
+```
+
+`Adaptive` — a full palette generated from one or two base colors:
+
+```javascript
+import am5themes_Adaptive from "@amcharts/amcharts5/themes/Adaptive";
+
+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.
+                           // 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
+    count: 10,             // number of series colors to generate. Default: 10
+    dark: false            // true = faintly base-tinted dark background + matching interface colors
+  })
+]);
+```
+
 ## Applying
 
 Each chart can have multiple themes applied to it.

package/extended/reference/ibasecolumnseriesdataitem.md

@@ -337,3 +337,4 @@ Extended by: IColumnSeriesDataItem, IRadarColumnSeriesDataItem, ICurveColumnSeri
 - **graphics** (`Graphics`) — An actual Graphics element (Column/Slice/Candlestick/OHLC).
 - **legendDataItem** (`DataItem`) — If data items from this series are used to feed a Legend, this will hold a reference to the equivalent Legend data item. Click here for more info
 - **rangeGraphics** (`Array`) — In case axis ranges are added to the series, it creates a separate element (Graphics) for each axis range. This array holds them all.
+- **fill** (`Color`) — Color of the column, when the series colors each data item separately (colorByDataItem). @since 5.20.4

package/extended/reference/ibasecolumnseriessettings.md

@@ -86,3 +86,5 @@ Extended by: IColumnSeriesSettings, IRadarColumnSeriesSettings, ICurveColumnSeri
 - **adjustBulletPosition** (`undefined | false | true`) — Default true Whether positions of bullets should be calculated based on portion of column currently visual (true) or the whole length/height of the column (false).
 - **clustered** (`undefined | false | true`) — Default true Indicates if series must divvy up available space with other column series (true; default) or take up the whole available space (false). Click here for more info
 - **useLastColorForLegendMarker** (`undefined | false | true`) — If set to true will use color of the last visible column for legend marker. Otherwise, series fill/stroke will be used. @since 5.1.13
+- **colorByDataItem** (`undefined | false | true`) — Default false If set to true, each column gets its own color from `colors`, instead of the whole series sharing one color. @since 5.20.4
+- **colors** (`ColorSet`) — A ColorSet to take colors from when colorByDataItem is set. The series makes its own if none is given, rather than taking the chart's: the chart's palette is stepped once per series, and one palette per series also means editing one does not change the others. @since 5.20.4

package/extended/reference/ichartserializersettings.md

@@ -175,3 +175,4 @@ Extends: ISerializerSettings
 
 - **includeProjection** (`undefined | false | true`) — Default false Include projection settings in the output. If enabled, the projection function will be included in the output, according to the functionsAs setting.
 - **removeEmptyObjects** (`undefined | false | true`) — Default true Remove empty objects from the output.
+- **includeRoot** (`undefined | false | true`) — Default false If set to true, adds a top-level `root` section with the Root object's settings and properties (interfaceColors, formatters, utc, fps, tabindex) to the serialized output. JsonParser applies a `root` section before parsing the chart. @since 5.20.2

package/extended/reference/imapchartsettings.md

@@ -75,3 +75,5 @@ Extends: ISerialChartSettings
 - **zoomControl** (`ZoomControl`) — A ZoomControl instance. Click here for more info
 - **zoomLevel** (`undefined | number`) — Current zoom level.
 
+- **boxZoom** (`"none" | "drag" | "shift" | "ctrl" | "alt"`) — Default "none" Allows zooming the map to an area drawn with a pointer. The value is the key that must be held while dragging; "drag" means no key is needed — since a plain drag pans the map, use "drag" with panX/panY set to "none". The drawn area is represented by the boxZoomSelection element. NOT a boolean. @since 5.20.2
+- **doubleClickZoom** (`undefined | false | true`) — Default true Setting true will make map zoom in on a double click (or double tap), and zoom out on a shift + double click. On maps panned by rotating (panX: "rotateX" and/or panY: "rotateY") the clicked location is rotated to the center of the map; otherwise it stays under the pointer. @since 5.20.2

package/extended/reference/imaplineseriesdataitem.md

@@ -20,3 +20,4 @@ Extended by: IGraticuleSeriesDataItem
 - **lineType** (`"curved" | "straight"`) — Default "curved" A line type. "curved" (default) - connects points using shortest distance, which will result in curved lines based on map projection. "straight" - connects points using visually straight lines, and will not cross the -180/180 longitude. @since 5.2.32
 - **mapLine** (`MapLine`) — Related MapLine object.
 - **pointsToConnect** (`Array`) — An array of data items from MapPointSeries to use as line end-points. Note, fixed points can not be used here.
+- **pointIds** (`Array<string>`) — Ids of the points (data items of the series set in pointSeries, matched by their id) a line connects, e.g. `{ pointIds: ["JFK", "LAX"] }`. The line waits for every id to match a point before it is drawn, so it is never drawn short. Fixed points cannot be used, same as with pointsToConnect. Ignored if pointsToConnect is set on the same data item. @since 5.20.3

package/extended/reference/imaplineseriessettings.md

@@ -88,3 +88,5 @@ Extended by: IGraticuleSeriesSettings
 
 - **clipBack** (`undefined | false | true`) — If set to true will hide line segments that are in the invisible range of the map. For example on the side of the globe facing away from the viewer when used with Orthographic projection. NOTE: not all projections have invisible side.
 - **lineType** (`"curved" | "straight"`) — Default "curved" A line type. "curved" (default) - connects points using shortest distance, which will result in curved lines based on map projection. "straight" - connects points using visually straight lines, and will not cross the -180/180 longitude. @since 5.2.24
+- **pointIdsField** (`undefined | string`) — Default "pointIds" A field in data that holds ids of the points a line connects. @since 5.20.3
+- **pointSeries** (`MapPointSeries`) — A MapPointSeries the pointIds of a data item are looked up in. @since 5.20.3

package/extended/reference/iparsesettings.md

@@ -2,11 +2,17 @@
 title: "IParseSettings"
 type: "interface"
 source: "https://www.amcharts.com/docs/v5/reference/iparsesettings/"
-scraped: "2026-03-15"
+scraped: "2026-09-14"
 ---
 
-Inheritance
+Options object passed as the **second argument** of `JsonParser.parse(config, options)`. These are not settings of the parser object itself.
 
-## Properties
+```javascript
+const parser = am5plugins_json.JsonParser.new(root);
+const chart = await parser.parse(config, { parent: root.container, updateTargets: "soft" });
+```
 
+## Properties
 
+- **parent** (`Container`) — Parent container to place the parsed chart into.
+- **updateTargets** (`"strict" | "soft"`) — Default "strict" If set to "strict" and source object has `type` set, a new object of that type will be created and used in place of existing one. In case of "soft", parser will check if source and target objects are of the same type and overwrite only if types differ. Otherwise only settings will be applied, just like if the `type` was not specified at all. @since 5.20.3