@amcharts/amcharts5-mcp 1.7.1 → 1.9.0

package/content/map.md

@@ -42,7 +42,16 @@ Pattern: camelCase country name + detail level. E.g. `germanyLow`, `canadaHigh`,
   - CDN: `https://cdn.amcharts.com/lib/5/geodata/region/world/europeLow.js`
   - Global: `am5geodata_region_world_europeLow`
 - For a map of European countries, use `worldLow.js` and filter with `include: ["DE", "FR", "IT", ...]`
-- US congressional districts: `geodata/usaCongressionalLow.js` (may not be available on all CDN versions)
+- **US congressional districts** come in versioned packs under `geodata/region/usa/<pack>/`, each with `usaCongressionalLow.js` / `usaCongressionalHigh.js` (all states) and per-state `<st>Low.js` / `<st>High.js` (e.g. `txLow.js`). There is no top-level `geodata/usaCongressionalLow.js`.
+
+| Pack | Districts |
+|------|-----------|
+| `congressional` | 117th Congress (the original set; the 116th used the same districts) |
+| `congressional2022` | 118th |
+| `congressional2025` | 119th |
+| `congressional120` | 120th, the newest (geodata 5.1.6; includes proposed changes) |
+
+**Global names** are `am5geodata_` + the path below `geodata/`, with `/` → `_` and case kept: `geodata/region/usa/congressional120/usaCongressionalLow.js` → `am5geodata_region_usa_congressional120_usaCongressionalLow`; ES import `@amcharts/amcharts5-geodata/region/usa/congressional120/usaCongressionalLow`. The npm package has the same maps (default exports, raw GeoJSON under `json/`, also on the CDN as `geodata/json/<path>.json`), and its `loadMap("region/usa/congressional120/txLow")` loads any map by path. Where the amCharts MCP server is connected, its `list_geodata(filter)` tool lists every map with its CDN path, global name and ES import.
 
 ## Core setup
 
@@ -168,6 +177,8 @@ const heatLegend = chart.children.push(am5.HeatLegend.new(root, {
 }));
 ```
 
+For a scale through more than two colors (5.21.2), give the heat rule `stops` instead of `min`/`max` and the legend `colors` instead of `startColor`/`endColor`: see SKILL.md "Heat rules". `Adaptive` and `Monochrome` themes take `mapShade: true` (5.21.2) for map land in a lighter shade of their base color.
+
 **Styling heat-legend segments.** With `stepCount: N` the legend draws N discrete `RoundedRectangle` markers inside `heatLegend.markerContainer`, all styled through `heatLegend.markers.template` (it accepts the usual Graphics settings — `stroke`, `strokeWidth`, `strokeOpacity`, `fillOpacity`, `cornerRadius*`, `tooltipText` for a per-block hover tooltip). Segment **thickness** is the marker's cross-axis size: a **vertical** legend uses the marker `width` (default `15`) with `height: 100%`; a **horizontal** legend uses `height` (default `15`) with `width: 100%`. Style via the template — `heatLegend.markers.values` can read empty even while `markerContainer.children` holds the rectangles.
 
 ```js
@@ -221,6 +232,12 @@ pointSeries2.data.setAll([
 
 `surfaceBullets: true` (5.21.0) lays the bullets onto the map surface, and `altitudeField` (5.21.0) raises points — see "Bullets on the surface" and "Raised lines and points" below.
 
+**A point's bullet sprite:** `dataItem.bullets` is a plain array property, not a setting (`dataItem.get("bullets")` is `undefined`), on every series type:
+
+```js
+var sprite = pointSeries.dataItems[0].bullets?.[0]?.get("sprite");   // the Circle made by the bullet function
+```
+
 **Points on lines as data rows (5.20.6):** `MapPointSeries` has `lineIdField` (default `"lineId"`), `positionOnLineField` (default `"positionOnLine"`), `autoRotateField` (default `"autoRotate"`) and `autoRotateAngleField` (default `"autoRotateAngle"`), so a point on a `MapLine` can be a plain row — `{ lineId: "jfk-lhr", positionOnLine: 0.5, autoRotate: true }`, where `lineId` is the line's data `id` in a `MapLineSeries` of the same chart — instead of `pushDataItem({ lineDataItem, positionOnLine })`. Data values of `autoRotate`/`autoRotateAngle` win over the bullet's own setting. `polygonIdField` still has **no** default — declare it as above. See "Animating bullets along lines".
 
 ### MapLineSeries (connections, routes)
@@ -363,6 +380,7 @@ polygonSeries.events.on("datavalidated", function() {
 | `nodeWidth` | number | `1` | Bar width in degrees (bar nodeType only) |
 | `nodePadding` | number | `0.3` | Extra padding on node shapes in degrees |
 | `antimeridian` | string | `"short"` | `"short"` for shortest path, `"long"` to avoid ±180° crossing |
+| `linkColorMode` | string | `"solid"` | `"solid"`: every band takes `mapPolygons.template`'s fill; `"source"` / `"target"`: each band takes that node's fill, so the nodes need colors (see "Band appearance"). Followed since 5.21.1, also when node fills change |
 | `sourceIdField` | string | `"sourceId"` | Data field for source polygon ID |
 | `targetIdField` | string | `"targetId"` | Data field for target polygon ID |
 | `sourceLongitudeField` | string | `"sourceLongitude"` | Data field for source longitude |
@@ -384,6 +402,16 @@ sankeySeries.mapPolygons.template.setAll({
 });
 ```
 
+Bands colored like their nodes — map nodes get no colors of their own, so give them a `ColorSet` (before the data):
+
+```js
+var sankeySeries = chart.series.push(am5map.MapSankeySeries.new(root, {
+  polygonSeries: polygonSeries,
+  linkColorMode: "source"     // each band takes its source node's fill ("target": its target's)
+}));
+sankeySeries.nodes.set("colors", am5.ColorSet.new(root, {}));   // map nodes have no colors by default
+```
+
 Per-link control point overrides in data:
 ```js
 sankeySeries.data.setAll([
@@ -523,7 +551,7 @@ planeSeries.bullets.push(function (root, series, dataItem) {
 planeSeries.data.setAll([{ lineId: "jfk-lhr", positionOnLine: 0, autoRotate: true }]);
 ```
 
-**Direction on the way back (5.20.8):** an `autoRotate` point turns round to face its travel direction **only** while an `animations` entry on its bullet sprite (`target: "dataItem"`, `key: "positionOnLine"`) moves it back toward the line start. A point moved by `dataItem.animate()` from code keeps facing the line's direction — that code has to turn it (Example 4 rotates its plane between segments itself). An endless loop started on a data item in code is saved by `ChartSerializer` since 5.21.0 (not in 5.20.8), but only the first one found, written onto the bullet sprite — after parsing every point of the series plays it; a declared entry per bullet is the predictable form. Since 5.21.0 every point placed on a line follows the line when it changes (e.g. gets an `altitude`), not just one of them.
+**Direction on the way back (5.20.8):** an `autoRotate` point turns round to face its travel direction **only** while an `animations` entry on its bullet sprite (`target: "dataItem"`, `key: "positionOnLine"`) moves it back toward the line start. A point moved by `dataItem.animate()` from code keeps facing the line's direction — that code has to turn it (Example 4 rotates its plane between segments itself). An endless loop started on a data item in code is saved by `ChartSerializer` since 5.21.0 (not in 5.20.8). In 5.21.0–5.21.2 only the first one found was saved, on the bullet sprite, so after parsing every point played it. Since 5.21.3 loops that differ per point are saved in each point's data row, under the bullet sprite's `templateField` (`"bulletSettings"` if none is set); one loop shared by all points still goes on the sprite. Where the rows can't hold them, the first one still goes on the sprite for all: points made from geodata, a sprite with its own `animations`, or a loop animating object values. Since 5.21.0 every point placed on a line follows the line when it changes (e.g. gets an `altitude`), not just one of them.
 
 **IMPORTANT — Multi-segment lines and `positionOnLine`:**
 - `positionOnLine` treats the entire line as one unit (0 = start, 1 = end). If a line has multiple segments (i.e. `pointsToConnect` has 3+ points), position 0.5 is the midpoint of the *entire* path.
@@ -563,7 +591,22 @@ satSeries.bullets.push(function (root, series, dataItem) {
 satSeries.data.setAll([{ latitude: 10, longitude: 0, altitude: 400000 }]);   // metres
 ```
 
-A point on a line takes the line's altitude. `mapLine.positionToAltitude(position)` returns the altitude (m) at `0`–`1` along a line. Works best on a globe (`geoOrthographic`, see `map-altitude-arcs` in the npm package examples).
+A point on a line takes the line's altitude. `mapLine.positionToAltitude(position)` returns the altitude (m) at `0`–`1` along a line. Works best on a globe (`geoOrthographic`, see `map-altitude-arcs` in the npm package examples). Raised lines draw 3–4 times faster since 5.21.1.
+
+**Heights per coordinate:** once a line's `altitude` is set (`0` for none), the third value of each coordinate is that point's height in metres, and a non-zero `altitude` adds its arc to each leg on top. One line can then change height along its length (a descent from orbit, relief along a parallel); without `altitude` the third values are ignored. The demo "Globe with raised parallels" (`maps/globe-with-raised-parallels`) does this.
+
+```js
+var pathSeries = chart.series.push(am5map.MapLineSeries.new(root, {}));
+pathSeries.mapLines.template.setAll({ altitude: 0, stroke: am5.color(0xff621f), strokeWidth: 2 });
+pathSeries.data.setAll([{ geometry: { type: "LineString",
+  coordinates: [[0, 0, 800000], [20, 10, 400000], [40, 15, 0]] } }]);   // [longitude, latitude, metres]
+```
+
+**Where a raised point is on screen:** for a `MapPointSeries` point, `dataItem.get("point")` is its raised position (`{ x, y }`) and `dataItem.get("clipped")` says whether it is hidden. For any other longitude, latitude and height `h` (MapUtils' `projectAltitude` is not exported): on a globe, `screen = T + (P − T) × (1 + h / R)`, with `P = chart.convert({ longitude, latitude })` the surface point, `T = chart.get("projection").translate()` the globe's center and `R = 6371008.8` m; on a flat map, `P` moved up by `h / R × projection.scale()`.
+
+**`clipFront: true`** on a point series hides the points on the near side. With points raised high (`altitudeField`), what is left are the ones behind the globe that rise past its edge: a starfield behind the globe (`clipBack`, default `true`, still hides those the globe covers).
+
+**`ClusteredPointSeries` with `altitudeField`:** a cluster's bullet floats at the average altitude of its points (the cluster data item gets `altitude`); points still cluster by their distance on screen.
 
 ### Bullets on the surface — `surfaceBullets` (5.21.0)
 
@@ -645,6 +688,35 @@ columns.data.setAll([{ id: "CN", value: 1410 }, { id: "IN", value: 1430 }, { id:
 
 Pixels have no outline by default (the theme keeps pixel polygons at `strokeWidth: 0`); set `strokeWidth` (and `stroke`) on `mapPolygons.template` to outline each pixel. `pixelSeries.pixels` is the `Graphics` that draws them all: `am5.renderToSVG(pixelSeries.pixels)` exports just the pixels, with each polygon's pixels in a `<g id="US" data-name="United States">`. `include`/`exclude` work as on `MapPolygonSeries`.
 
+**The classic dotted map** is `pixelType: "circle"` with `uniform: true`. Without `uniform` the pixels lie on the surface, so on projections such as `geoEqualEarth` the circles near the poles widen into ovals.
+
+**`step` for one country:** `step` is in degrees, so the default `2` suits the world but leaves a country only a few pixels. Derive it from the area shown, its longer side divided by the pixels wanted across it:
+
+```js
+var geodata = am5geodata_germanyLow;
+var b = am5map.getGeoBounds({ type: "GeometryCollection",
+  geometries: geodata.features.map(function (f) { return f.geometry; }) });   // { left, right, top, bottom } in degrees
+var countrySeries = chart.series.push(am5map.PixelMapSeries.new(root, {
+  geoJSON: geodata,
+  step: Math.max(b.right - b.left, b.top - b.bottom) / 60   // about 60 pixels across
+}));
+```
+
+(`getGeoBounds` spans `-180`…`180` for a shape that crosses the 180th meridian.)
+
+**Random column heights:** `pixelHeightFunction` runs again for every pixel whenever heights are recomputed (data changes, a hover state that sets `MapPolygon` `pixelHeight`, …), so `Math.random()` makes the columns jump. Use a deterministic hash of longitude and latitude, times the polygon's own height so per-polygon heights still apply:
+
+```js
+var hashed = chart.series.push(am5map.PixelMapSeries.new(root, {
+  geoJSON: am5geodata_worldLow,
+  columnHeight: 0.1,
+  pixelHeightFunction: function (dataItem, longitude, latitude) {
+    var h = Math.sin(longitude * 12.9898 + latitude * 78.233) * 43758.5453;
+    return (h - Math.floor(h)) * dataItem.get("mapPolygon").get("pixelHeight", 1);
+  }
+}));
+```
+
 ### Satellite images — `MapRasterSeries` (5.21.0)
 
 `am5map.MapRasterSeries` shows one image of the whole world, reprojected as the map turns and zooms (on the GPU with WebGL2 for orthographic, equirectangular, Mercator, Equal Earth and Natural Earth; on the CPU otherwise). With `nightSrc` and a sun position it shows day where the sun is up and night where it is down, blended across twilight.
@@ -659,7 +731,7 @@ raster.events.on("loaded", function () { /* src (and nightSrc) are drawn */ });
 raster.events.on("loaderror", function () { /* failed, or cross-origin without CORS */ });
 ```
 
-- The image must be **equirectangular** ("plate carrée": longitude −180…180 left to right, latitude 90…−90 top to bottom). The geodata package ships `geodata/images/earthDay2048.jpg` and `earthNight2048.jpg` (NASA Earth Observatory — credit it, e.g. a small `am5.Label`).
+- The image must be **equirectangular** ("plate carrée": longitude −180…180 left to right, latitude 90…−90 top to bottom). The CDN has `geodata/images/{earthDay,earthNight,moon,mars}{2048,4096}.jpg`, e.g. `https://cdn.amcharts.com/lib/5/geodata/images/moon4096.jpg` (the npm geodata package has no images). The Earth images are from NASA Earth Observatory: credit the source, e.g. with a small `am5.Label`.
 - `cors` (default `"anonymous"`): a cross-origin image is drawn only if its server sends CORS headers. A page opened from disk (`file://`) cannot read an image file beside it — serve the page, or use the CDN copy.
 - The series counts as the whole world in the map's bounds; on a regional map set `affectsBounds: false`. The projection needs `invert`, so nothing is drawn while `animateProjection()` runs.
 - Draw country borders over it with a `MapPolygonSeries` pushed after it, `fillOpacity: 0` on `mapPolygons.template`. `twilight` (default `12` degrees of sun height) sets how wide the day/night blend is.
@@ -686,6 +758,20 @@ night.get("sun").setAll({ radius: 12 });   // the sun is a Circle the series mak
 - `twilight` (default `12`) and `twilightSteps` (default `4`, number of shades from day to full night).
 - `sunAltitude` is for looks: `1000000`–`5000000` suits a globe.
 - `am5map.getSunPosition(date?)` takes a `Date` (default now) and returns the `{ longitude, latitude }` where the sun is directly overhead — also for `MapRasterSeries` `sunPosition`, or to place a sun marker on a `MapPointSeries`.
+- **JSON:** a saved chart keeps `sunDate`, never the `sunPosition` worked out from it, so a `"now"` map still follows the clock after parsing.
+
+**Day and night on another body.** `sunDate` is the Earth's sun only, so for the Moon or Mars set `sunPosition` to that body's sub-solar point (from your own ephemeris), and leave `sunDate` unset (it wins). A small `twilight` gives an airless body's sharp edge:
+
+```js
+chart.series.push(am5map.MapRasterSeries.new(root, {
+  src: "https://cdn.amcharts.com/lib/5/geodata/images/moon2048.jpg"
+}));
+var lunarNight = chart.series.push(am5map.NightSeries.new(root, {
+  sunPosition: { longitude: 30, latitude: 1.5 },   // the Moon's sub-solar point
+  twilight: 1.5                                    // default 12 (degrees)
+}));
+lunarNight.get("sun").set("forceHidden", true);    // hide the sun marker
+```
 
 ## Zoom controls
 
@@ -735,6 +821,8 @@ polygonSeries.mapPolygons.template.states.create("active", {
 });
 ```
 
+`clickZoom` sets `active` itself, so `toggleKey: "active"` is not needed (with it, the two still agree).
+
 **Start at the home position — `autoHome` (5.21.0).** Goes to the home position (`homeGeoPoint`, `homeZoomLevel`, `homeRotationX`/`homeRotationY`) once the map is loaded, as `goHome()` does — animated when `animationDuration` is set (the Animated theme sets it), at once otherwise. No `goHome()` call in a `datavalidated` handler needed, so a map loaded from JSON can start zoomed in. Default `false`.
 
 ```js
@@ -746,6 +834,22 @@ var chart = root.container.children.push(am5map.MapChart.new(root, {
 }));
 ```
 
+With `autoHome` and no `homeZoomLevel`, home zoom is `1`, so a starting `zoomLevel` is overridden: set `homeZoomLevel` to the same value. Without `autoHome`, a `zoomLevel` given to `MapChart.new()` is the starting zoom (since 5.21.1; before, one set before the map loaded was ignored or left the map blank).
+
+**Home on a globe.** On a map that pans by rotating (`panX: "rotateX"`, `panY: "rotateY"`), `goHome()` and the home button restore the rotation only from `homeRotationX` / `homeRotationY` (−longitude / −latitude). `homeGeoPoint` alone leaves the rotation as it is and shifts the globe sideways.
+
+```js
+var globe = root.container.children.push(am5map.MapChart.new(root, {
+  projection: am5map.geoOrthographic(),
+  panX: "rotateX",
+  panY: "rotateY",
+  homeRotationX: -10,   // home = centered on 10°E…
+  homeRotationY: -50    // …50°N
+}));
+```
+
+**`zoomStep`** (default `2`) is a multiplier, not an increment: `zoomIn()` and the + button multiply `zoomLevel` by it, `zoomOut()` divides, and the mouse wheel and double clicks use it too, one step per wheel event whatever its size. So keep it above `1` (`1` does nothing, below `1` reverses); `zoomStep: 1.1`–`1.2` gives fine control, e.g. on trackpads, which fire many small wheel events. `wheelSensitivity` does not affect wheel zoom, only wheel rotation.
+
 Fixed in 5.21.0: `goHome()` went to the wrong place before the map was ready or on a rotated map (globe); a zoomed-in map could not be dragged to its edges (with `maxPanOut: 0` not at all); `zoomToGeoBounds()` rotated with `animationDuration` instead of the given duration and changed the bounds object; `MapPointSeries.zoomToDataItems(items, true)` / `ClusteredPointSeries.zoomToCluster()` turned a globe to the wrong point; `chart.geoPoint()` and `getPolygonByGeoPoint()` were off on charts with padding.
 
 ## Globe (orthographic projection)
@@ -768,6 +872,8 @@ chart.animate({ key: "rotationY", to: -paris.latitude, duration: 1500, easing: a
 
 **IMPORTANT — Globe rotation direction:** To center the globe on a geographic point, set `rotationX` to **negative longitude** and `rotationY` to **negative latitude**. This is because rotation moves the globe under the camera: rotating X by -2.35 brings longitude 2.35 to the center. A common mistake is using positive coordinates, which rotates the globe in the wrong direction.
 
+Setting `rotationX`/`rotationY`/`rotationZ` on every frame (e.g. a camera that follows a moving point) performs fine.
+
 ## GraticuleSeries (grid lines / ocean background)
 
 ```js
@@ -825,8 +931,9 @@ am5map.MapChart.new(root, {
   rotationX: 0,             // center longitude
   rotationY: 0,             // center latitude
   rotationZ: 0,             // tilt
-  wheelY: "zoom",           // "zoom", "none"
-  wheelSensitivity: 1,      // zoom speed multiplier
+  wheelY: "zoom",           // "zoom", "rotateX", "rotateY", "none"
+  zoomStep: 2,              // zoom multiplier per step: buttons, wheel, double click (see "Zoom controls")
+  wheelSensitivity: 1,      // how far the wheel rotates the map ("rotateX"/"rotateY" only), not zoom speed
   doubleClickZoom: true,    // (5.20.2) double click zooms in, shift+double click out — default true
   boxZoom: "none",          // (5.20.2) "none" | "drag" | "shift" | "ctrl" | "alt" — key held to drag a zoom box
   autoHome: false,          // (5.21.0) true = go to homeGeoPoint/homeZoomLevel once loaded
@@ -872,6 +979,8 @@ linkedSeries.data.setAll([{ id: "US", url: "https://en.wikipedia.org/wiki/United
 
 ## Disposal
 
+In a React, Vue, Angular, Svelte or React Native app, use amCharts' framework package, which disposes the root with the component (SKILL.md, "Frameworks"). Otherwise dispose the root when the component goes away:
+
 ```js
 root.dispose();
 ```

package/content/pie.md

@@ -70,8 +70,8 @@ chart.appear(1000, 100);
 | `alignLabels` | boolean | Align labels in column (default: true). Set false for radial/inside labels |
 | `legendLabelText` | string | Legend label format, e.g. `"{category}"` |
 | `legendValueText` | string | Legend value format, e.g. `"{value}"` |
-| `startAngle` | number | Start angle in degrees (default: inherits from chart). Must match PieChart's startAngle for semi-circle |
-| `endAngle` | number | End angle in degrees (default: inherits from chart). Must match PieChart's endAngle for semi-circle |
+| `startAngle` | number | Start angle in degrees (default: `-90`). Must match PieChart's startAngle for semi-circle |
+| `endAngle` | number | End angle in degrees (default: `270`). Must match PieChart's endAngle for semi-circle |
 
 ### Labels
 
@@ -132,6 +132,15 @@ series.slices.template.adapters.add("fill", function(fill, target) {
 // series.slices.template.set("templateField", "sliceSettings");
 ```
 
+### Changing slice values live
+
+Percent series (pie, funnel, pyramid, pictorial) size slices from each data item's `valueWorking`, not `value`, so `dataItem.set("value", v)` moves nothing, and `series.markDirtyValues()` doesn't help. Change the data row, or set both keys:
+
+```js
+series.data.setIndex(0, { category: "A", value: 80 });        // animates (Animated theme)
+series.dataItems[1].setAll({ value: 5, valueWorking: 5 });    // jumps: for per-frame updates, e.g. a countdown donut
+```
+
 ## Funnel chart setup
 
 ```js
@@ -147,7 +156,7 @@ const series = chart.series.push(
     valueField: "value",
     categoryField: "stage",
     orientation: "vertical",   // "vertical" or "horizontal"
-    bottomRatio: 0,            // 0 = trapezoids (classic funnel), 1 = rectangles
+    bottomRatio: 0,            // 0 = rectangles (default), 1 = each slice narrows to the next (trapezoids)
     alignLabels: true
   })
 );
@@ -164,8 +173,8 @@ series.data.setAll([
 
 | Setting | Type | Description |
 |---------|------|-------------|
-| `orientation` | `"vertical" \| "horizontal"` | Direction of the funnel (required) |
-| `bottomRatio` | number (0–1) | 0 = trapezoids (classic funnel), 1 = rectangles (default) |
+| `orientation` | `"vertical" \| "horizontal"` | Direction of the funnel (default: `"vertical"`) |
+| `bottomRatio` | number (0–1) | 0 = rectangular slices (default); 1 = each slice narrows to the next (trapezoids) |
 | `alignLabels` | boolean | Align labels in a column (default: true) |
 
 ### Slice links (connectors between funnel slices)
@@ -245,7 +254,7 @@ series.data.setAll([
 | `orientation` | `"vertical"` \| `"horizontal"` | Fill direction |
 | `startLocation` | number (0–1) | Where the fill starts within the shape |
 | `endLocation` | number (0–1) | Where the fill ends within the shape |
-| `alignLabels` | boolean | Align labels outside the shape |
+| `alignLabels` | boolean | Align labels in a column outside the shape (default: true), as on funnel and pyramid |
 
 **Getting SVG paths:** Use any vector editor (Adobe Illustrator, Inkscape, Figma) to draw a shape and export as SVG, then extract the `d` attribute from the `<path>` element.
 
@@ -362,6 +371,8 @@ series.set("linkTarget", "_blank");     // default "_self"
 
 ## Disposal
 
+In a React, Vue, Angular, Svelte or React Native app, use amCharts' framework package, which disposes the root with the component (SKILL.md, "Frameworks"). Otherwise dispose the root when the component goes away:
+
 ```js
 root.dispose();
 ```

package/content/radar.md

@@ -315,6 +315,8 @@ handDataItem.animate({
 
 ## Disposal
 
+In a React, Vue, Angular, Svelte or React Native app, use amCharts' framework package, which disposes the root with the component (SKILL.md, "Frameworks"). Otherwise dispose the root when the component goes away:
+
 ```js
 root.dispose();
 ```
@@ -570,8 +572,7 @@ root.dispose();
       strokeOpacity: 0,
       fillOpacity: 0.8,
       width: am5.percent(80),
-      cornerRadiusTL: 3,
-      cornerRadiusTR: 3
+      cornerRadius: 3          // radar columns are Slices: one cornerRadius, no cornerRadiusTL/TR
     });
 
     // Color each column differently

package/content/stock.md

@@ -324,6 +324,8 @@ var data = [
 
 **`PeriodSelector` labels (5.21.0):** a period without a `name` is labeled from its unit and count — `{ timeUnit: "month" }` shows `MONTH1`, `{ timeUnit: "ytd" }` shows `YTD` (before: `MONTHundefined`, `YTDundefined`). Give each period a `name` for nicer labels.
 
+**Time zones (5.21.1):** `PeriodSelector` and `DateRangeSelector` count periods and dates in `root.timezone` (or UTC with `root.utc`), like the date axis; before 5.21.1 they used the viewer's time zone. Charts with `root.timezone` are also much faster (up to 16 times) and keep grid, labels and data groups on the hour across daylight saving changes.
+
 ## Events
 
 ```js
@@ -341,6 +343,8 @@ valueSeries.events.on("datavalidated", () => {
 
 ## Disposal
 
+In a React, Vue, Angular, Svelte or React Native app, use amCharts' framework package, which disposes the root with the component (SKILL.md, "Frameworks"). Otherwise dispose the root when the component goes away:
+
 ```js
 root.dispose();
 ```

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

@@ -132,7 +132,7 @@ am5xy.ColumnSeries.new(root, {
 
 ## Disposal (SPA frameworks)
 
-Always dispose on component unmount:
+In a React, Vue, Angular, Svelte or React Native app, use amCharts' framework package, which disposes the root with the component (SKILL.md, "Frameworks"). Otherwise dispose the root on component unmount:
 ```js
 root.dispose();
 ```
@@ -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 since 5.20.8, still in 5.21.3, 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.