@amcharts/amcharts5-mcp 1.1.9 → 1.3.2

package/README.md

@@ -10,6 +10,104 @@ Instead of loading the entire amCharts reference into the AI's context window, t
 
 ## Quick Start
 
+The easiest way is the **hosted server** — no install, just add one URL. Prefer to
+run it yourself? See [Local install](#local-install-npx) below.
+
+### Hosted (no install) — recommended
+
+Point your AI client at:
+
+```
+https://mcp.amcharts.com/mcp
+```
+
+**Claude Code**
+
+```bash
+claude mcp add --transport http amcharts5 https://mcp.amcharts.com/mcp
+```
+
+**Claude Desktop / claude.ai** — Settings → Connectors → **Add custom connector**, then paste `https://mcp.amcharts.com/mcp`.
+
+**Cursor** — `.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "amcharts5": {
+      "url": "https://mcp.amcharts.com/mcp"
+    }
+  }
+}
+```
+
+**VS Code + GitHub Copilot** — `.vscode/mcp.json`:
+
+```json
+{
+  "servers": {
+    "amcharts5": {
+      "type": "http",
+      "url": "https://mcp.amcharts.com/mcp"
+    }
+  }
+}
+```
+
+**Windsurf** — `~/.codeium/windsurf/mcp_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "amcharts5": {
+      "serverUrl": "https://mcp.amcharts.com/mcp"
+    }
+  }
+}
+```
+
+**ChatGPT** (Plus/Pro/Enterprise with connectors/developer mode enabled) — Settings → **Connectors** → **Add custom connector**, then paste `https://mcp.amcharts.com/mcp`.
+
+**Cline** (VS Code extension) — open the **MCP Servers** panel → **Remote Servers**, paste `https://mcp.amcharts.com/mcp`, or add to its MCP settings JSON:
+
+```json
+{
+  "mcpServers": {
+    "amcharts5": {
+      "type": "streamableHttp",
+      "url": "https://mcp.amcharts.com/mcp"
+    }
+  }
+}
+```
+
+**Clients that only support local (stdio) servers** (e.g. Zed, Continue, Amazon Q Developer) — bridge to the hosted URL with [`mcp-remote`](https://www.npmjs.com/package/mcp-remote). Use this as the server's run command in the client's config:
+
+```bash
+npx mcp-remote https://mcp.amcharts.com/mcp
+```
+
+For example, in a `command`/`args` style config:
+
+```json
+{
+  "mcpServers": {
+    "amcharts5": {
+      "command": "npx",
+      "args": ["-y", "mcp-remote", "https://mcp.amcharts.com/mcp"]
+    }
+  }
+}
+```
+
+Any other MCP client that accepts a remote server URL works too — use the `/mcp`
+endpoint (Streamable HTTP) or `/sse` (legacy SSE). For URL-only clients that still
+expect a command, use the `mcp-remote` bridge shown above.
+
+## Local install (npx)
+
+Prefer running it yourself? The server is also published to npm and runs over stdio.
+
 ### Claude Code
 
 For **all projects** (global, recommended):

package/content/SKILL.md

@@ -164,6 +164,34 @@ series.set("tooltip", am5.Tooltip.new(root, {
 
 **Inline formatting:** `"[bold]{name}[/]: [fontSize: 20px]{value}[/]"`
 
+**A tooltip with no text renders as an empty bubble.** Enabling a `am5.Tooltip` without `labelText` (or `series.tooltipText`) shows a blank tooltip. Series text lives on `tooltip.labelText` or `series.set("tooltipText", ...)`; for column/bar charts the text usually goes on `series.columns.template.set("tooltipText", "{categoryX}: {valueY}")`.
+
+### Styling a tooltip
+
+The tooltip background is a **`PointedRectangle`** (NOT a `RoundedRectangle`), so it has a single `cornerRadius` — there are no `cornerRadiusTL/TR/BL/BR`:
+
+```js
+const tooltip = am5.Tooltip.new(root, { labelText: "{valueY}" });
+
+// Background color + shape — must turn OFF getFillFromSprite, else bg copies the series color
+tooltip.set("getFillFromSprite", false);
+tooltip.get("background").setAll({
+  fill: am5.color(0x000000),
+  fillOpacity: 0.8,
+  stroke: am5.color(0xffffff),
+  strokeOpacity: 0.3,
+  cornerRadius: 6        // single radius — PointedRectangle, not four corners
+});
+
+// Text color — must turn OFF autoTextColor (it auto-picks for contrast), then set on the label
+tooltip.set("autoTextColor", false);
+tooltip.label.setAll({ fill: am5.color(0xffffff) });   // tooltip.label is read-only accessor
+
+series.set("tooltip", tooltip);
+```
+
+`getStrokeFromSprite` (default `false`) copies the sprite's stroke color when `true`.
+
 ## Chart title
 
 Do NOT add titles as HTML elements — they are outside the canvas and won't appear in exports. Add an `am5.Label` to the container BEFORE the chart, and set `verticalLayout`:
@@ -358,8 +386,15 @@ sprite.setAll({ fill: am5.color(0xff0000), strokeWidth: 2 });
 // Read current value
 const fill = sprite.get("fill");
 const width = sprite.getPrivate("width"); // read-only internal values
+
+// set() RETURNS the value — handy for capturing the created object inline:
+const cursor = chart.set("cursor", am5xy.XYCursor.new(root, {}));
 ```
 
+**Reading back a `Percent`:** a `Percent` exposes two numbers — `.percent` is the 0–100 value, `.value` is the normalized 0–1 fraction. `am5.percent(50).percent === 50` but `am5.percent(50).value === 0.5`. When you read a percent setting back (e.g. `sprite.get("x")` after setting `am5.percent(50)`), use `.percent` for a 0–100 number; `.value` gives `0.5`.
+
+**Reading animated settings is unreliable mid-animation.** Right after `series.appear()` / `chart.appear()`, animated settings like `opacity` are still transitioning — `get("opacity")` can return `0` (the start value). Read such settings after the animation completes, or don't persist values read during appear (a common way to accidentally bake `opacity:0` into generated code).
+
 ## Dynamic data
 
 ```js
@@ -639,7 +674,7 @@ onUnmounted(() => { root.dispose(); });
 26. **`VoronoiTreemap` has NO `.rectangles` property** — Unlike `Treemap` (which has `series.rectangles.template`), `VoronoiTreemap` renders organic polygon cells. Style via `series.nodes.template` and its children, not `.rectangles`.
 27. **Labels with data placeholders need `populateText: true`** — When a Label uses data field placeholders like `text: "{name}"`, you MUST also set `populateText: true`. Without it, the placeholder is not resolved and the label appears blank. This applies everywhere Labels display dynamic data — bullet labels, map point labels, etc. Example: `am5.Label.new(root, { text: "{name}", populateText: true, ... })`.
 28. **Easing: `am5.ease.in()` does NOT exist** — amCharts 5 provides base easing functions (`am5.ease.cubic`, `am5.ease.bounce`, `am5.ease.elastic`, `am5.ease.linear`, `am5.ease.quad`, `am5.ease.sine`, `am5.ease.circle`, `am5.ease.exp`, `am5.ease.pow`) and three modifiers: `am5.ease.out()`, `am5.ease.inOut()`, `am5.ease.yoyo()`. Usage: `am5.ease.cubic` (ease-in by default), `am5.ease.out(am5.ease.cubic)` (ease-out), `am5.ease.inOut(am5.ease.cubic)` (ease in+out). There is NO `am5.ease.in()` — using it throws a runtime error. The base functions already ease-in by default.
-29. **Use `forceHidden` instead of `visible: false` when you need to guarantee something stays hidden** — amCharts internally manages `visible` on many elements (cursor lines, labels, ticks, tooltips, grid, etc.), toggling them on/off in response to user interaction or data changes. If you set `visible: false`, the library may set it back to `true`. `forceHidden: true` overrides all system visibility changes and keeps the element hidden regardless. Examples: `cursor.lineX.set("forceHidden", true)`, `yRenderer.labels.template.set("forceHidden", true)`, `xRenderer.grid.template.set("forceHidden", true)`. For cursor lines specifically, always access `cursor.lineX`/`cursor.lineY` after creation — do NOT pass them as constructor options.
+29. **`forceHidden` vs `visible`** — `forceHidden: true` ALWAYS hides an element, immune to states, themes/library and even `show()`. `visible` is weaker: amCharts re-manages it on many elements (notably cursor lines, but also labels, ticks, tooltips, grid) in response to interaction or data changes, so a `visible: false` you set may be flipped back to `true`. Rules of thumb: for a **persistent hide**, use `forceHidden: true` (`cursor.lineX.set("forceHidden", true)`, `yRenderer.labels.template.set("forceHidden", true)`, `xRenderer.grid.template.set("forceHidden", true)`). To **reveal** an element that defaults hidden — notably **axis ticks** (`ticks.template` defaults to `visible:false`) — you must raise `visible: true`; flipping `forceHidden` alone won't show it. For cursor lines specifically, always access `cursor.lineX`/`cursor.lineY` after creation — do NOT pass them as constructor options.
 30. **`snapTooltip: true` on series for cursor tooltip snapping** — When using a cursor and you want tooltips to snap to data points, set `snapTooltip: true` on the series in addition to (or instead of) `snapToSeries` on the cursor. This is especially useful for timeline/curve charts.
 31. **Globe rotation uses negative coordinates** — To center the globe (`geoOrthographic`) on a geographic point, set `rotationX` to **-longitude** and `rotationY` to **-latitude**. E.g., to center on Paris (48.86°N, 2.35°E): `chart.animate({ key: "rotationX", to: -2.35 }); chart.animate({ key: "rotationY", to: -48.86 });`. Using positive values rotates the globe the wrong way.
 32. **`positionOnLine` with multi-segment lines limits per-segment control** — `MapPointSeries` data items can animate along a line via `positionOnLine` (0→1). If the line has 3+ points (multi-segment), position 0.5 is the midpoint of the *entire* path, making per-segment effects (scaling at each segment midpoint, pausing between segments, etc.) difficult. For advanced per-segment animations, use **single-segment lines** (2 points each) and animate the bullet across them sequentially. E.g., instead of one line [A,B,C,D], create [A,B], [B,C], [C,D].
@@ -679,6 +714,32 @@ If you have the ability to run shell commands, validate your generated chart cod
 
 Skip this step entirely if you cannot execute code (e.g., chat-only context with no tool access).
 
+## Recent API changes (newer than the bundled class reference)
+
+The bundled per-class API reference was snapshotted on **2026-03-15**, so it predates the changes below. Prefer these names/settings; for anything newer, verify against the live docs (see next section).
+
+**Renamed settings (old name still works but is deprecated — use the new one):**
+
+| Class(es) | Old | New | Since |
+|-----------|-----|-----|-------|
+| `MovingAverage`, `MovingAverageDeviation`, `MovingAverageEnvelope`, `BollingerBands` | `type` | `maType` | 5.18.0 |
+| `VoronoiTreemap` | `type` | `shapeType` | 5.18.0 |
+
+```js
+// Moving-average indicators: use maType, not type
+am5stock.MovingAverage.new(root, { maType: "exponential", period: 20 });
+am5hierarchy.VoronoiTreemap.new(root, { shapeType: "rectangle" }); // was: type
+```
+
+**New settings / methods worth knowing:**
+- `Tree`: `fitNodes` (5.18.0, exclude hidden nodes from layout), `nodeSeparation` (5.16.2, custom node-spacing fn), `clustered` (5.16.2, dendrogram layout — leaves at same depth).
+- `ValueAxis`: `syncZeros` (5.16.2, align zero across synced axes — needs `syncWithAxis`).
+- `Hierarchy`: `parentIdField` setting + `setFlatData(data)` method (5.16.2) — feed flat `{id, parentId}` data instead of nested `children`.
+- All entities: `onDebounced(key, cb, delay)` / `offDebounced(key, cb?)` and `onPrivateDebounced` / `offDebouncedPrivate` (5.17.3) — fire once after rapid changes settle.
+- `Label`: `fontFamily: "inherit"` (5.17.3) uses the chart container's computed font.
+- `MapSankeySeries` (5.17.0) — Sankey overlaid on a map; auto-resolves `sourceId`/`targetId` once `polygonSeries` geoJSON loads (5.17.1), so no `datavalidated` wrapper needed. See `references/map.md`.
+- `MapPointSeries` defaults changed to `longitudeField: "longitude"`, `latitudeField: "latitude"` (5.16.1).
+
 ## Verify unfamiliar API before using it
 
 If you are unsure whether a method, property, or setting exists on an amCharts 5 class, **verify it before using it**. Check the class reference (class name in lowercase, e.g. `LineSeries` → `lineseries`):

package/content/gantt.md

@@ -47,10 +47,10 @@ var chart = root.container.children.push(
 | `editable` | boolean | `true` | Allow user to add, edit, remove, drag tasks |
 | `durationUnit` | string | `"day"` | `"year"`, `"month"`, `"week"`, `"day"`, `"hour"`, `"minute"`, `"second"` |
 | `weekends` | number[] | `[0, 6]` | Non-working days (0=Sun, 1=Mon, ... 6=Sat) |
-| `excludeWeekends` | boolean | `true` | Whether to exclude weekends from task durations |
+| `excludeWeekends` | boolean | `false` | Whether to exclude weekends from task durations |
 | `holidays` | Date[] | `[]` | Specific non-working dates |
 | `snapThreshold` | number | `0.5` | Drag snap position within a period (0–1) |
-| `sidebarWidth` | number | — | Sidebar width in pixels or Percent |
+| `sidebarWidth` | number \| Percent | `30%` | Sidebar width in pixels or Percent |
 
 ## Data structure
 
@@ -134,7 +134,7 @@ Set `duration: 0` to create milestone markers.
 ```js
 chart.yAxis.setAll({
   minCellHeight: 80,    // row height in pixels (default: 70)
-  childCellSize: 1,     // child row size relative to parent (default: 0.7, 1 = same)
+  childCellSize: 1,     // child row size relative to parent (default: 0.8, 1 = same)
   childShift: 0         // child label indent in pixels (default: 25)
 });
 ```

package/content/stock.md

@@ -216,7 +216,7 @@ stockChart.indicators.push(am5stock.Volume.new(root, {
 | Indicator | Class | Needs volumeSeries |
 |-----------|-------|--------------------|
 | Moving Average | `MovingAverage` | No |
-| Moving Average Cross | `MovingAverageCross` | No |
+| Moving Average Cross | `MACross` | No |
 | Moving Average Envelope | `MovingAverageEnvelope` | No |
 | Moving Average Deviation | `MovingAverageDeviation` | No |
 | Bollinger Bands | `BollingerBands` | No |
@@ -281,8 +281,9 @@ var data = [
 ## Events
 
 ```js
-// Period changed
-stockChart.events.on("periodselected", (ev) => {
+// Period changed — the `periodselected` event fires on the PeriodSelector
+// instance, NOT on stockChart. Attach the handler to the selector you created.
+periodSelector.events.on("periodselected", (ev) => {
   console.log("Period:", ev.period);
 });
 

package/content/timeline.md

@@ -48,20 +48,24 @@ const chart = root.container.children.push(
   am5timeline.SerpentineChart.new(root, {
     orientation: "vertical",  // "vertical" | "horizontal"
     levelCount: 3,            // number of bends/turns
-    yAxisRadius: am5.percent(25),   // curve thickness
-    yAxisInnerRadius: -25,          // inner radius (negative = percentage of radius)
+    startLocation: 0,         // relative start of the "road" (0-1)
+    endLocation: 1,           // relative end of the "road" (0-1)
+    yAxisRadius: am5.percent(50),   // band thickness (Percent); applied to the Y axes' radius
   })
 );
 ```
 
-**Serpentine settings:**
+**Serpentine settings** (`ISerpentineChartSettings`):
 
-| Setting | Type | Description |
-|---------|------|-------------|
-| `orientation` | `"vertical"` \| `"horizontal"` | Direction of the snake pattern |
-| `levelCount` | number | Number of turns/bends |
-| `yAxisRadius` | percent/number | Outer radius of the curve |
-| `yAxisInnerRadius` | number | Inner radius (0 = filled, negative = relative) |
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| `orientation` | `"vertical"` \| `"horizontal"` | `"vertical"` | Direction of the snake pattern |
+| `levelCount` | number | `3` | Number of turns/bends |
+| `startLocation` | number | `0` | Relative location (0-1) of the start |
+| `endLocation` | number | `1` | Relative location (0-1) of the end |
+| `yAxisRadius` | `Percent` | `50%` | Band thickness — applied to every Y axis renderer's radius |
+
+> There is no `yAxisInnerRadius` setting on the chart. Band thickness is controlled by `yAxisRadius` (a `Percent`). For a plain `CurveChart` (no Serpentine/Spiral wrapper) the Y-axis band length is set via `AxisRendererCurveY`'s `axisLength` instead.
 
 ### SpiralChart
 
@@ -71,23 +75,25 @@ Wraps the chart into a spiral shape.
 const chart = root.container.children.push(
   am5timeline.SpiralChart.new(root, {
     levelCount: 3,             // number of spiral rings
-    inversed: true,            // spiral direction
+    startAngle: -90,           // start angle in degrees
     endAngle: -135,            // end angle in degrees
-    yAxisRadius: am5.percent(70),
-    yAxisInnerRadius: 0,
-    innerRadius: am5.percent(30),  // inner hole radius
+    yAxisRadius: am5.percent(60),  // band thickness (Percent)
+    innerRadius: am5.percent(30),  // inner hole radius (Percent)
   })
 );
 ```
 
-**Spiral settings:**
+**Spiral settings** (`ISpiralChartSettings`):
+
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| `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 |
 
-| Setting | Type | Description |
-|---------|------|-------------|
-| `levelCount` | number | Number of spiral rings |
-| `inversed` | boolean | Spiral direction |
-| `endAngle` | number | Where the spiral ends (degrees) |
-| `innerRadius` | percent/number | Size of the center hole |
+> 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.)
 
 ### CurveChart
 
@@ -306,8 +312,7 @@ chart.get("cursor").events.on("cursormoved", function(ev) {
       am5timeline.SerpentineChart.new(root, {
         orientation: "vertical",
         levelCount: 3,
-        yAxisRadius: am5.percent(25),
-        yAxisInnerRadius: -25
+        yAxisRadius: am5.percent(50)
       })
     );
 
@@ -399,10 +404,9 @@ chart.get("cursor").events.on("cursormoved", function(ev) {
     var chart = root.container.children.push(
       am5timeline.SpiralChart.new(root, {
         levelCount: 3,
-        inversed: true,
+        startAngle: -90,
         endAngle: -135,
-        yAxisRadius: am5.percent(70),
-        yAxisInnerRadius: 0,
+        yAxisRadius: am5.percent(60),
         innerRadius: am5.percent(30)
       })
     );

package/content/ui-elements.md

@@ -81,14 +81,16 @@ button.get("background").states.create("down", {
 ### Togglable button
 
 ```js
+// There is no `togglable` setting on Button. Make it a toggle by setting
+// `toggleKey: "active"` (a Sprite setting) — clicks then flip the `active` boolean.
 var button = container.children.push(am5.Button.new(root, {
-  togglable: true,
+  toggleKey: "active",
   label: am5.Label.new(root, { text: "Toggle" })
 }));
 
-// Check active state
+// Check active state via the `active` setting (there is no isActive() method)
 button.events.on("click", function(ev) {
-  var isActive = ev.target.isActive();
+  var isActive = ev.target.get("active");
   console.log("Active:", isActive);
 });
 ```

package/content/wordcloud.md

@@ -57,10 +57,10 @@ series.appear(1000);
 |---------|------|---------|-------------|
 | `categoryField` | string | — | Data field for word text (required) |
 | `valueField` | string | — | Data field for word weight/size (required) |
-| `maxFontSize` | percent/number | `am5.percent(20)` | Maximum font size |
-| `minFontSize` | percent/number | `am5.percent(2)` | Minimum font size |
-| `angles` | number[] | `[0, -90]` | Allowed rotation angles for words |
-| `randomness` | number (0–1) | `0.2` | Layout randomness (0 = ordered by value, 1 = fully random) |
+| `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 |
+| `randomness` | number (0–1) | `0` | Layout randomness (0 = ordered by value, 1 = fully random) |
 | `minWordLength` | number | `1` | Skip words shorter than this |
 | `maxCount` | number | — | Maximum number of words to display |
 | `excludeWords` | string[] | `[]` | Words to exclude |

package/content/xy.md

@@ -81,6 +81,8 @@ The field name combines the **value type** + **axis direction**:
 - Date axis on X → `valueXField: "date"` (dates are numeric timestamps)
 - Open/high/low/close → `openValueYField`, `highValueYField`, `lowValueYField`, `valueYField`
 
+**There is NO `dateXField` in v5** (a common wrong guess carried over from v4). A `DateAxis` series reads its date from `valueXField`, pointing at a numeric timestamp (`new Date(...).getTime()`).
+
 ## Common additions
 
 ### Cursor
@@ -109,7 +111,11 @@ legend.data.setAll(chart.series.values);
 series.set("tooltip", am5.Tooltip.new(root, {
   labelText: "{name}: {valueY}"
 }));
+
+// For column/bar series the tooltip text often lives on the columns template instead:
+series.columns.template.set("tooltipText", "{categoryX}: {valueY}");
 ```
+A tooltip enabled with no `labelText`/`tooltipText` shows an empty bubble — always give it text. See SKILL.md → Tooltip for background/text styling.
 
 ### Stacking
 ```js
@@ -253,6 +259,11 @@ renderer.labels.template.setAll({
 });
 ```
 
+**Axis sub-element defaults:** grid and labels are visible by default; **ticks default to `visible:false`**. To show ticks you must raise `visible` (and give them a non-zero `strokeOpacity`) — toggling `forceHidden` won't reveal them:
+```js
+renderer.ticks.template.setAll({ visible: true, strokeOpacity: 0.5, length: 5 });
+```
+
 ## LineSeries
 
 For line and area charts.
@@ -659,7 +670,7 @@ am5xy.XYChart.new(root, {
   wheelX: "panX",                 // mouse wheel: "panX", "panY", "zoomX", "zoomY", "none"
   wheelY: "zoomX",                // mouse wheel vertical
   pinchZoomX: true,               // mobile pinch zoom on X
-  arrangeFields: false,           // auto-arrange overlapping fields
+  arrangeTooltips: true,          // de-overlap stacked series tooltips (NOTE: there is no `arrangeFields` setting)
   maxTooltipDistance: 0,           // show tooltips for nearby series (-1 = all)
 })
 ```

package/extended/examples/maps/map-sankey-series.md

@@ -0,0 +1,129 @@
+---
+title: "Map Sankey Series"
+source: "https://www.amcharts.com/docs/v5/charts/map-chart/map-sankey-series/"
+category: "maps"
+added: "2026-06-04"
+---
+
+`MapSankeySeries` (added in amCharts 5.17.0) draws variable-width curved bands between geographic points on a `MapChart` — a Sankey diagram projected onto a map, where band thickness encodes a numeric `value`. It extends `MapPolygonSeries` and generates real GeoJSON geometry, so bands follow the projection during pan, zoom, and globe rotation.
+
+Key implementation details
+A `MapSankeySeries` needs a reference `polygonSeries` (a `MapPolygonSeries` with geodata) to resolve country IDs to geographic centroids. Provide flow data as `{ sourceId, targetId, value }` using ISO 3166-1 alpha-2 country codes, or as explicit `{ sourceLongitude, sourceLatitude, targetLongitude, targetLatitude, value }` coordinates. When using `sourceId`/`targetId`, the series automatically waits for `polygonSeries` to finish parsing its geoJSON before resolving centroids — no `datavalidated` wrapper around `data.setAll()` is needed.
+
+Key settings (on `MapSankeySeries`):
+- `polygonSeries` — the `MapPolygonSeries` used to look up centroids (required for `sourceId`/`targetId` data).
+- `maxWidth` (default `5`) — maximum band width, in geographic degrees.
+- `controlPointDistance` (default `0.5`) — bezier curvature of the bands.
+- `nodeType` (default `"circle"`) — node shape: `"circle"` or `"bar"`.
+- `nodePadding` — extra padding around node shapes, in degrees.
+
+**WARNING:** never call `polygonSeries.data.setAll()` with your own objects — that replaces the geoJSON-derived data items and breaks `MapSankeySeries` centroid resolution. To set per-country properties (e.g. colors), iterate the existing data items inside the polygon series' `datavalidated` event instead.
+
+## JavaScript
+
+```javascript
+// Create root element
+// https://www.amcharts.com/docs/v5/getting-started/#Root_element
+var root = am5.Root.new("chartdiv");
+
+// Set themes
+// https://www.amcharts.com/docs/v5/concepts/themes/
+root.setThemes([am5themes_Animated.new(root)]);
+
+// Create the map chart
+// https://www.amcharts.com/docs/v5/charts/map-chart/
+var chart = root.container.children.push(am5map.MapChart.new(root, {
+  panX: "rotateX",
+  panY: "translateY",
+  projection: am5map.geoNaturalEarth1()
+}));
+
+// Country polygons — also used by the Sankey series to resolve centroids
+// https://www.amcharts.com/docs/v5/charts/map-chart/map-polygon-series/
+var polygonSeries = chart.series.push(am5map.MapPolygonSeries.new(root, {
+  geoJSON: am5geodata_worldLow
+}));
+polygonSeries.mapPolygons.template.setAll({
+  fill: am5.color(0xdddddd),
+  stroke: am5.color(0xffffff),
+  strokeWidth: 0.5
+});
+
+// Highlight the countries involved (set fills on existing geoJSON data items —
+// do NOT call polygonSeries.data.setAll() with custom objects)
+var endpoints = ["BR", "VN", "CO", "DE", "US", "FR", "JP", "CA"];
+polygonSeries.events.on("datavalidated", function () {
+  am5.array.each(polygonSeries.dataItems, function (di) {
+    if (endpoints.indexOf(di.get("id")) !== -1) {
+      di.get("mapPolygon").set("fill", am5.color(0xb0c4a0));
+    }
+  });
+});
+
+// Map Sankey series
+// https://www.amcharts.com/docs/v5/charts/map-chart/map-sankey-series/
+var sankeySeries = chart.series.push(am5map.MapSankeySeries.new(root, {
+  polygonSeries: polygonSeries,
+  maxWidth: 3,
+  controlPointDistance: 0.4,
+  nodePadding: 0.3
+}));
+
+// Band (link) appearance
+sankeySeries.mapPolygons.template.setAll({
+  fill: am5.color(0x6b4f3a),
+  fillOpacity: 0.6,
+  strokeOpacity: 0,
+  tooltipText: "{sourceNode.name} → {targetNode.name}: {value}"
+});
+
+// Node appearance
+sankeySeries.nodes.mapPolygons.template.setAll({
+  fill: am5.color(0x3c2415),
+  stroke: am5.color(0xffffff),
+  strokeWidth: 1,
+  tooltipText: "{name}: {sum}"
+});
+
+// Flow data — { sourceId, targetId, value } using ISO 3166-1 alpha-2 codes.
+// Set directly: the series auto-resolves IDs once polygonSeries loads its geoJSON.
+sankeySeries.data.setAll([
+  // Producers → hubs
+  { sourceId: "BR", targetId: "US", value: 450 },
+  { sourceId: "BR", targetId: "DE", value: 350 },
+  { sourceId: "VN", targetId: "DE", value: 200 },
+  { sourceId: "CO", targetId: "US", value: 250 },
+  // Hubs → consumer markets
+  { sourceId: "DE", targetId: "FR", value: 150 },
+  { sourceId: "US", targetId: "CA", value: 120 },
+  { sourceId: "US", targetId: "JP", value: 80 }
+]);
+
+// Auto-created nodes only know their id — give them readable names
+var countryNames = {
+  BR: "Brazil", VN: "Vietnam", CO: "Colombia", DE: "Germany",
+  US: "United States", FR: "France", JP: "Japan", CA: "Canada"
+};
+sankeySeries.events.on("datavalidated", function () {
+  am5.array.each(sankeySeries.nodes.dataItems, function (di) {
+    var id = di.get("id");
+    if (id && countryNames[id]) {
+      di.set("name", countryNames[id]);
+    }
+  });
+});
+
+// ALTERNATIVE — explicit coordinates instead of country IDs (no polygonSeries
+// lookup needed for these endpoints). Optional `waypoints` route the band
+// through intermediate points (keys MUST be "longitude"/"latitude"):
+// sankeySeries.data.setAll([
+//   {
+//     sourceLongitude: -47.9, sourceLatitude: -15.8,   // Brasília
+//     targetLongitude: 13.4,  targetLatitude: 52.5,    // Berlin
+//     value: 350,
+//     waypoints: [{ longitude: -25.0, latitude: 20.0 }]
+//   }
+// ]);
+
+chart.appear(1000, 100);
+```

package/extended/reference/hierarchy.md

@@ -32,6 +32,7 @@ Extended by: LinkedHierarchy, Pack, Partition, Treemap, VoronoiTreemap
 - **downDepth** (`undefined | number`) — Number of child levels to open when clicking on a node. Click here for more info
 - **fillField** (`undefined | string`) — A field in data that holds color used for fills for various elements, such as nodes.
 - **initialDepth** (`undefined | number`) — Number of levels to show on chart's first load. Click here for more info
+- **parentIdField** (`undefined | string`) — A field in data that holds the parent node's ID. Used with the `setFlatData(data)` method to build the hierarchy from a flat array (with parent-ID references) instead of nested `children`. @since 5.16.2
 - **patterns** (`PatternSet`) — A PatternSet to use when asigning patterns for nodes. Click here for more info @since 5.10.0
 - **selectedDataItem** (`DataItem`) — A data item for currently selected node. Click here for more info
 - **singleBranchOnly** (`undefined | false | true`) — If set to true will make all other branches collapse when some branch is expanded.

package/extended/reference/ihierarchysettings.md

@@ -99,6 +99,7 @@ Extended by: ILinkedHierarchySettings, IPackSettings, IPartitionSettings, ITreem
 - **downDepth** (`undefined | number`) — Number of child levels to open when clicking on a node. Click here for more info
 - **fillField** (`undefined | string`) — A field in data that holds color used for fills for various elements, such as nodes.
 - **initialDepth** (`undefined | number`) — Number of levels to show on chart's first load. Click here for more info
+- **parentIdField** (`undefined | string`) — A field in data that holds the parent node's ID. Used with the `setFlatData(data)` method to build the hierarchy from a flat array (with parent-ID references) instead of nested `children`. @since 5.16.2
 - **patterns** (`PatternSet`) — A PatternSet to use when asigning patterns for nodes. Click here for more info @since 5.10.0
 - **selectedDataItem** (`DataItem`) — A data item for currently selected node. Click here for more info
 - **singleBranchOnly** (`undefined | false | true`) — If set to true will make all other branches collapse when some branch is expanded.

package/extended/reference/imovingaveragedeviationsettings.md

@@ -73,5 +73,6 @@ Extends: IChartIndicatorSettings
 
 - **decreasingColor** (`Color`) — Decreasing color.
 - **increasingColor** (`Color`) — Increasing color.
-- **type** (`"simple" | "weighted" | "exponential" | "dema" | "tema"`) — Default "simple" Type of the moving average.
+- **maType** (`"simple" | "weighted" | "exponential" | "dema" | "tema"`) — Default "simple" Type of the moving average. (Renamed from `type` in 5.18.0.)
+- **type** (`"simple" | "weighted" | "exponential" | "dema" | "tema"`) — *Deprecated since 5.18.0 — use `maType` (still works).* Default "simple" Type of the moving average.
 - **unit** (`"points" | "percent"`) — Default "points" How units are calculated.

package/extended/reference/imovingaveragesettings.md

@@ -73,4 +73,5 @@ Extended by: IBollingerBandsSettings, IMovingAverageEnvelopeSettings
 ## Properties
 
 - **offset** (`undefined | number`) — Default 0 Offset.
-- **type** (`"simple" | "weighted" | "exponential" | "dema" | "tema"`) — Default "simple" Type of the moving average.
+- **maType** (`"simple" | "weighted" | "exponential" | "dema" | "tema"`) — Default "simple" Type of the moving average. (Renamed from `type` in 5.18.0.)
+- **type** (`"simple" | "weighted" | "exponential" | "dema" | "tema"`) — *Deprecated since 5.18.0 — use `maType` (still works).* Default "simple" Type of the moving average.

package/extended/reference/iserpentinechartsettings.md

@@ -75,4 +75,5 @@ Extends: ICurveChartSettings
 - **levelCount** (`undefined | number`) — Default 3 Number of levels in the chart.
 - **orientation** (`"horizontal" | "vertical"`) — Default "vertical" Orientation of the serpatine.
 - **startLocation** (`undefined | number`) — Relative location (0-1) of the start postion. @defult 0
+- **yAxisRadius** (`Percent`) — Default 50% Radius of the Y-axis (band thickness); applied to every Y axis renderer's radius.
 

package/extended/reference/ispiralchartsettings.md

@@ -75,4 +75,5 @@ Extends: ICurveChartSettings
 - **innerRadius** (`Percent`) — Default 60% Inner radius of the spiral in percent.
 - **levelCount** (`undefined | number`) — Default 3 Numer of spiral circles.
 - **startAngle** (`undefined | number`) — Default -90 Start angle of the spiral in degrees.
+- **yAxisRadius** (`Percent`) — Default 50% Y-axis radius in percent (band thickness); applied to every Y axis renderer's radius.
 

package/extended/reference/itreesettings.md

@@ -91,5 +91,8 @@ Extends: ILinkedHierarchySettings
 
 ## Properties
 
+- **clustered** (`undefined | false | true`) — Default false If set to true, uses a cluster (dendrogram) layout where all leaf nodes are placed at the same depth. @since 5.16.2
+- **fitNodes** (`undefined | false | true`) — Default false If set to true, hidden nodes are excluded from the layout, giving more space to visible ones. @since 5.18.0
 - **inversed** (`undefined | false | true`) — Default false If set to true, will flip the tree direction. @since 5.2.4
+- **nodeSeparation** (`undefined | (a: DataItem, b: DataItem) => number`) — Custom node-separation function; receives two data items and returns a numeric spacing value. @since 5.16.2
 - **orientation** (`"horizontal" | "vertical"`) — Default "vertical" Orientation of the diagram.

package/extended/reference/ivalueaxissettings.md

@@ -87,5 +87,6 @@ Extended by: IDateAxisSettings, IDurationAxisSettings
 - **strictMinMax** (`undefined | false | true`) — Force axis scale to be precisely at values as set in min and/or max. In case min and/or max is not set, the axis will fix its scale to precise lowest and highest values available through all of the series attached to it. This effectively locks the axis from auto-zooming itself when chart is zoomed in. If you need to zoom to actual low/high values within currently visible scope, use strictMinMaxSelection instead. Use extraMin and extraMax to add extra "padding". Click here for more info
 - **strictMinMaxSelection** (`undefined | false | true`) — Force axis to auto-zoom to exact lowest and highest values from attached series' data items within currently visible range. This is a good feature when your series is plotted from derivative values, like valueYChangeSelection as it helps to avoid frequent jumping of series to adjusted min and max of the axis. This will not work if strictMinMax is set to true (the axis will not zoom at all in this case). Use extraMin and extraMax to add extra "padding". @since 5.1.11
 - **syncWithAxis** (`ValueAxis`) — This setting can be set to an instance of another ValueAxis. If set the grid of this axis will be synced with grid of the target axis. NOTE: this is not 100% guaranteed to work. In some rare cases perfect sync might not be possible. Click here for more info
+- **syncZeros** (`undefined | false | true`) — Aligns the zero baseline across synced axes. Works only if `syncWithAxis` is set and zero is within the min/max of the axis. @since 5.16.2
 - **tooltipNumberFormat** (`string | NumberFormatOptions`) — A numeric format used for numbers displayed in axis tooltip. Click here for more info
 - **treatZeroAs** (`undefined | number`) — Treat zero values as some other value. Useful in situations where zero would result in error, i.e. logarithmic scale. Click here for more info

package/extended/reference/ivoronoitreemapsettings.md

@@ -95,4 +95,5 @@ Extends: IHierarchySettings
 - **cornerCount** (`undefined | number`) — Default 120 Number of corners when type is "polygon". 120 means the polygoon will look like a circle. NOTE: this setting is ignored if type="rectangle".
 - **maxIterationCount** (`undefined | number`) — Default 100 Maximum allowed number of iterations when computing the layout. Computation is stopped when it number of iterations is reached, even if the convergenceRatio is not yet reached. Bigger number means finer results, but slower performance.
 - **minWeightRatio** (`undefined | number`) — Default 0.005 Minimum weight ratio which allows computing the minimum allowed weight (= [maximum weight] * minWeightRatio). Setting very small minWeigtRatio might result flickering. NOTE: the nodes that have smaller weight will be scaled up and will not represent their true value correctly.
-- **type** (`"rectangle" | "polygon"`) — Default "polygon" Type of the diagram's shape. Click here for more info
+- **shapeType** (`"rectangle" | "polygon"`) — Default "polygon" Type of the diagram's shape. (Renamed from `type` in 5.18.0.) Click here for more info
+- **type** (`"rectangle" | "polygon"`) — *Deprecated since 5.18.0 — use `shapeType` (still works).* Default "polygon" Type of the diagram's shape.

package/extended/reference/movingaverage.md

@@ -24,7 +24,8 @@ Extended by: BollingerBands, MovingAverageEnvelope
 ## Settings
 
 - **offset** (`undefined | number`) — Default 0 Offset.
-- **type** (`"simple" | "weighted" | "exponential" | "dema" | "tema"`) — Default "simple" Type of the moving average.
+- **maType** (`"simple" | "weighted" | "exponential" | "dema" | "tema"`) — Default "simple" Type of the moving average. (Renamed from `type` in 5.18.0.)
+- **type** (`"simple" | "weighted" | "exponential" | "dema" | "tema"`) — *Deprecated since 5.18.0 — use `maType` (still works).* Default "simple" Type of the moving average.
 
 ## Properties