@amcharts/amcharts5-mcp 1.5.0 → 1.7.0

package/content/map.md

@@ -56,7 +56,8 @@ const chart = root.container.children.push(
     panY: "translateY",        // "translateY", "rotateY", "none"
     projection: am5map.geoMercator(),
     // homeGeoPoint: { latitude: 48.8566, longitude: 2.3522 },
-    // homeZoomLevel: 5
+    // homeZoomLevel: 5,
+    // autoHome: true              // (5.21.0) start at the home position
   })
 );
 
@@ -143,7 +144,7 @@ polygonSeries.set("geoJSON", geojson);
 chart.zoomToGeoBounds({ left: -8.6, right: 1.8, top: 60.9, bottom: 49.9 }, 500);
 ```
 
-`zoomToGeoBounds(bounds, duration?)` is more reliable than `homeGeoPoint` + `homeZoomLevel` + `goHome()` when the only series is custom polygons.
+`zoomToGeoBounds(bounds, duration?)` is the most direct way to fit custom polygons. Since 5.21.0 it uses the `duration` you pass (it rotated with `animationDuration`) and no longer modifies the bounds object; `goHome()` also works when called before the map is ready or on a rotated map, and `autoHome: true` does the initial trip for you (see "Zoom controls").
 
 ### Choropleth (heat map) via heat rules
 
@@ -218,6 +219,10 @@ 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.
+
+**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)
 
 ```js
@@ -263,7 +268,7 @@ lineSeries2.data.setAll([
 ]);
 ```
 
-`pointsToConnect` wins if a data item has both. Fixed points (`fixed: true`) cannot be used with either.
+`pointsToConnect` wins if a data item has both. Fixed points (`fixed: true`) cannot be used with either. `altitude` on `mapLines.template` (5.21.0) arcs lines above the surface — see "Raised lines and points". Changing `lineType` on the series or a data item redraws lines already drawn since 5.21.0.
 
 ### MapSankeySeries (geographic flow bands)
 
@@ -445,7 +450,7 @@ sankeySeries.events.on("datavalidated", function() {
 });
 ```
 
-Bullets automatically hide on the back side of the globe (orthographic projection).
+Bullets automatically hide on the back side of the globe (orthographic projection). Since 5.21.0 they are drawn above the flows, and bullets that are not moving along their flow follow the map when it moves (before, they stayed behind).
 
 #### Multi-level flows
 
@@ -464,7 +469,7 @@ sankeySeries.data.setAll([
 
 ### Animating bullets along lines (positionOnLine)
 
-`MapPointSeries` data items have a `positionOnLine` setting (0–1) that positions the point along a line. Combined with `lineDataItem` and `autoRotate`, this enables flight-path-style animations.
+`MapPointSeries` data items have a `positionOnLine` setting (0–1) that positions the point along a line. Combined with `lineDataItem` (or, since 5.20.6, a `lineId` data field) and `autoRotate`, this enables flight-path-style animations.
 
 ```js
 // Create a point that follows a line
@@ -496,20 +501,202 @@ plane.on("positionOnLine", function(pos) {
 });
 ```
 
+**Data-row form + declared flight (5.20.6 / 5.20.8)** — no data-item references and no `animate()` call, so the whole thing survives `ChartSerializer` (points added with `pushDataItem()` are not serialized; `data` rows are):
+
+```js
+var lineSeries = chart.series.push(am5map.MapLineSeries.new(root, {}));   // push before the point series
+lineSeries.data.setAll([{ id: "jfk-lhr",
+  geometry: { type: "LineString", coordinates: [[-73.78, 40.64], [-0.45, 51.47]] } }]);
+
+var planeSeries = chart.series.push(am5map.MapPointSeries.new(root, {}));
+planeSeries.bullets.push(function (root, series, dataItem) {
+  return am5.Bullet.new(root, {
+    sprite: am5.Graphics.new(root, {
+      svgPath: "m2,106h28l24,30h72l-44,-133h35l80,132h98c21,0 21,34 0,34l-98,0 -80,134h-35l43,-133h-71l-24,30h-28l15,-47",
+      scale: 0.06, centerX: am5.p50, centerY: am5.p50,
+      // loops: 0 = forever; yoyo flies back; keep `from` explicit (a row without positionOnLine would jump to `to`)
+      animations: [{ target: "dataItem", key: "positionOnLine", from: 0, to: 1,
+                     duration: 6000, loops: 0, yoyo: true, easing: "cubic", ease: "inOut" }]
+    })
+  });
+});
+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.
+
 **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.
 - For advanced per-segment animations (e.g., scaling the bullet differently at the midpoint of each segment, or pausing between segments), use **single-segment lines** (2 points each) instead of one multi-segment line. This gives you full control: animate `positionOnLine` from 0 to 1 on each segment line sequentially, with independent timing, easing, and callbacks per segment.
 - Example: instead of one line with points [A, B, C, D], create three lines: [A,B], [B,C], [C,D] and animate the bullet across them one at a time.
 
+### Raised lines and points — `altitude` (5.21.0)
+
+`altitude` on a `MapLine` lifts each leg (one point to the next) into an arc, in **metres** at its middle (`400000` ≈ the ISS). Once set (even `0`), the line's ends sit at the `altitude` of the points it connects (or the third value of their coordinates); without it the line stays on the surface. Not applied to `lineType: "straight"`. On flat maps lines rise up the screen.
+
+```js
+var pointSeries = chart.series.push(am5map.MapPointSeries.new(root, {}));
+pointSeries.bullets.push(function (root, series, dataItem) {
+  return am5.Bullet.new(root, {
+    sprite: am5.Circle.new(root, { radius: 5, fill: am5.color(0xff621f), tooltipText: "{title}" })
+  });
+});
+pointSeries.data.setAll([
+  { id: "london", title: "London", latitude: 51.5072, longitude: -0.1276 },
+  { id: "new-york", title: "New York", latitude: 40.7128, longitude: -74.006 },
+  { id: "singapore", title: "Singapore", latitude: 1.3521, longitude: 103.8198 }
+]);
+
+var lineSeries = chart.series.push(am5map.MapLineSeries.new(root, { pointSeries: pointSeries }));
+lineSeries.mapLines.template.setAll({
+  altitude: 1000000,   // each route rises 1,000 km in its middle and lands on both cities
+  stroke: am5.color(0xff621f),
+  strokeWidth: 2
+});
+lineSeries.data.setAll([{ pointIds: ["london", "new-york"] }, { pointIds: ["london", "singapore"] }]);
+
+// Points raised by a data value — altitudeField has NO default, so declare it
+var satSeries = chart.series.push(am5map.MapPointSeries.new(root, { altitudeField: "altitude" }));
+satSeries.bullets.push(function (root, series, dataItem) {
+  return am5.Bullet.new(root, { sprite: am5.Circle.new(root, { radius: 4, fill: am5.color(0x0066cc) }) });
+});
+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).
+
+### Bullets on the surface — `surfaceBullets` (5.21.0)
+
+`surfaceBullets: true` on a `MapPointSeries` lays its bullets onto the map: each turns, squashes and stretches with the projection, as if painted on — on a globe they flatten towards the edge, on Mercator they grow towards the poles. Default `false` (bullets stay upright and unscaled).
+
+```js
+var pointSeries = chart.series.push(am5map.MapPointSeries.new(root, {
+  surfaceBullets: true
+}));
+pointSeries.bullets.push(function (root, series, dataItem) {
+  return am5.Bullet.new(root, {
+    sprite: am5.Graphics.new(root, {   // a pin with its tip at the point
+      svgPath: "M0,0 C-5,-7 -9,-11 -9,-17 A9,9 0 1 1 9,-17 C9,-11 5,-7 0,0 Z M0,-20.5 A3.5,3.5 0 1 0 0,-13.5 A3.5,3.5 0 1 0 0,-20.5 Z",
+      fill: am5.color(0xff621f),
+      tooltipText: "{title}"
+    })
+  });
+});
+pointSeries.data.setAll([
+  { title: "London", latitude: 51.5072, longitude: -0.1276 },
+  { title: "Tokyo", latitude: 35.6895, longitude: 139.6917 }
+]);
+```
+
+Heat-rule-sized circles work too (`polygonIdField` + a bullet `am5.Template` as the rule target) — circles that lie flat on a globe.
+
+### Pixel maps — `PixelMapSeries` (5.21.0)
+
+`am5map.PixelMapSeries` extends `MapPolygonSeries` and draws its polygons as a grid of pixels that rotate and zoom with the map. Each pixel takes the look of the polygon it falls in, so **style `mapPolygons.template`, not the pixels** — heat rules, `templateField`, states and tooltips work as on `MapPolygonSeries` (the polygons stay, invisible, to take hover and clicks).
+
+```js
+var pixelSeries = chart.series.push(am5map.PixelMapSeries.new(root, {
+  geoJSON: am5geodata_worldLow,
+  pixelType: "circle",       // "square" (default), "circle", "diamond", "hexagon"
+  step: 2,                   // degrees between pixel centers (default 2)
+  uniform: true,             // an even on-screen grid of same-size pixels, like a pixel image of the map
+  valueField: "value",
+  calculateAggregates: true  // the heat rule needs the value range
+}));
+pixelSeries.mapPolygons.template.setAll({
+  fill: root.interfaceColors.get("disabled"),   // countries without data
+  tooltipText: "{name}: {value}"
+});
+pixelSeries.set("heatRules", [{
+  target: pixelSeries.mapPolygons.template, dataField: "value",
+  min: am5.color(0xffd19a), max: am5.color(0xb3261e), key: "fill"
+}]);
+pixelSeries.data.setAll([{ id: "US", value: 38 }, { id: "IN", value: 28 }, { id: "NG", value: 18 }]);
+```
+
+3D columns — the height of each polygon's columns comes from `MapPolygon` `pixelHeight` (`0`–`1` of `columnHeight`; set it with a heat rule or `templateField`); without it, from the polygon's value between the series' low and high (needs `calculateAggregates`):
+
+```js
+var columns = chart.series.push(am5map.PixelMapSeries.new(root, {
+  geoJSON: am5geodata_worldLow,
+  valueField: "value",
+  calculateAggregates: true,
+  columnHeight: 0.15      // tallest column = 15% of the globe's radius (0 = flat, the default)
+}));
+columns.set("heatRules", [{
+  target: columns.mapPolygons.template, dataField: "value",
+  min: 0.1, max: 1, key: "pixelHeight"
+}]);
+columns.mapPolygons.template.setAll({ stroke: am5.color(0xffffff), strokeWidth: 0.5 }); // outline each pixel
+columns.data.setAll([{ id: "CN", value: 1410 }, { id: "IN", value: 1430 }, { id: "ID", value: 277 }]);
+```
+
+| Setting | Default | Notes |
+|---------|---------|-------|
+| `step` | `2` | Degrees between pixel centers (with `uniform`, measured at the map's center). Finest `0.001`; a step that would make more than **500,000 pixels** is coarsened, with a console warning — small maps can take a fine step (e.g. `0.01` for a small country) |
+| `pixelSize` | `0.8` | Pixel size relative to `step`; `1` = neighbors touch |
+| `pixelType` | `"square"` | `"circle"`, `"diamond"`, `"hexagon"` |
+| `stagger` | unset | Shift every other row by half a pixel; unset = squares in columns, circles staggered; hexagons/diamonds always staggered |
+| `equalArea` | `true` | Fewer pixels per row towards the poles; `false` = same count every row |
+| `equalWidth` | `false` | Every pixel as wide as on the equator (overlap towards the poles); not with `uniform` |
+| `uniform` | `false` | Even on-screen grid, upright same-size pixels; `equalArea` and `columnHeight` do not apply |
+| `columnHeight` | `0` | Raises pixels into columns; tallest = this share of the globe's radius |
+| `pixelHeightFunction` | — | `(dataItem, longitude, latitude) => 0..1` per pixel; overrides `pixelHeight`; **not saved** to JSON (heat-rule heights are) |
+
+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`.
+
+### 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.
+
+```js
+var raster = chart.series.push(am5map.MapRasterSeries.new(root, {
+  src: "https://cdn.amcharts.com/lib/5/geodata/images/earthDay2048.jpg",       // the world by day
+  nightSrc: "https://cdn.amcharts.com/lib/5/geodata/images/earthNight2048.jpg", // optional: city lights at night
+  sunDate: "now"   // or sunPosition: { longitude, latitude } — needed only with nightSrc
+}));
+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`).
+- `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.
+
+### Night shading — `NightSeries` and `getSunPosition()` (5.21.0)
+
+`am5map.NightSeries` shades the part of the map where it is night, with the twilight in steps, and shows the sun. It never affects the map's bounds.
+
+```js
+chart.series.push(am5map.MapPolygonSeries.new(root, { geoJSON: am5geodata_worldLow }));
+
+var night = chart.series.push(am5map.NightSeries.new(root, {
+  sunDate: "now",        // "now" (moves on every minute), a timestamp, a date string or a Date
+  sunAltitude: 2000000   // metres: keeps the sun in view a little past a globe's edge (default 0)
+}));
+night.mapPolygons.template.setAll({ fill: am5.color(0x000033), fillOpacity: 0.6 }); // full night (default black, 0.5)
+night.get("sun").setAll({ radius: 12 });   // the sun is a Circle the series makes; or set any sprite as `sun`
+
+// …or a fixed moment instead of the clock — where the sun is overhead at a given time:
+// am5map.NightSeries.new(root, { sunPosition: am5map.getSunPosition(new Date("2026-06-21T12:00:00Z")) })
+```
+
+- `sunDate` overrides `sunPosition`. To change a `Date`, set a new object — mutating the same one goes unnoticed.
+- `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`.
+
 ## Zoom controls
 
 ```js
 chart.set("zoomControl", am5map.ZoomControl.new(root, {}));
+// its home button is hidden by default: zoomControl.homeButton.set("visible", true)
 
 // Programmatic zoom
 chart.zoomToGeoPoint({ latitude: 48.86, longitude: 2.35 }, 5);  // zoom level 5
 
-// Zoom to a polygon
+// Zoom to a polygon (5.21.0: prefer clickZoom, below)
 polygonSeries.mapPolygons.template.events.on("click", function(ev) {
   polygonSeries.zoomToDataItem(ev.target.dataItem);
 });
@@ -535,6 +722,32 @@ am5map.MapChart.new(root, {
 chart.boxZoomSelection.setAll({ fill: am5.color(0x1e88e5), fillOpacity: 0.15 });
 ```
 
+**Zoom to a clicked polygon — `clickZoom` (5.21.0).** One setting replaces the click-handler + `zoomToDataItem` + background-click recipe: a click zooms to the polygon (on a map panned by rotating — `panX: "rotateX"`/`panY: "rotateY"` — the globe also turns to it); clicking it again or the map background goes back home. The polygon zoomed to is `active`, so an `"active"` state marks it. Default `false`; works from JSON.
+
+```js
+var polygonSeries = chart.series.push(am5map.MapPolygonSeries.new(root, {
+  geoJSON: am5geodata_worldLow,
+  clickZoom: true
+}));
+polygonSeries.mapPolygons.template.setAll({ tooltipText: "{name}", interactive: true });
+polygonSeries.mapPolygons.template.states.create("active", {
+  fill: root.interfaceColors.get("primaryButtonActive")
+});
+```
+
+**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
+var chart = root.container.children.push(am5map.MapChart.new(root, {
+  projection: am5map.geoMercator(),
+  homeGeoPoint: { longitude: 14, latitude: 51 },   // central Europe…
+  homeZoomLevel: 3.5,                              // …zoomed in 3.5 times
+  autoHome: true
+}));
+```
+
+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)
 
 ```js
@@ -616,11 +829,14 @@ am5map.MapChart.new(root, {
   wheelSensitivity: 1,      // zoom speed multiplier
   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
 })
 ```
 
 **Polygon IDs** use ISO 3166-1 alpha-2 codes (e.g., `"US"`, `"CN"`, `"DE"`, `"FR"`).
 
+**Accessibility (5.21.0):** focusable map polygons can be focused (they could not before), objects left out with `include`/`exclude` get no focus element, objects panned or zoomed out of view are not TAB stops until at least partly back in view, and the zoom level is announced to screen readers once zooming settles.
+
 ## Events on map elements
 
 ```js
@@ -644,8 +860,16 @@ pointSeries.bullets.push(function(root, series, dataItem) {
 chart.on("zoomLevel", function(zoomLevel) {
   console.log("Zoom:", zoomLevel);
 });
+
+// Links without a click handler (5.20.7): urlField on MapPolygonSeries, MapLineSeries or MapPointSeries (bullets)
+var linkedSeries = chart.series.push(am5map.MapPolygonSeries.new(root, {
+  geoJSON: am5geodata_worldLow, urlField: "url", linkTarget: "_blank"   // linkTarget default "_self"
+}));
+linkedSeries.data.setAll([{ id: "US", url: "https://en.wikipedia.org/wiki/United_States" }]);
 ```
 
+`urlField` has no default (links are off until set); the pointer cursor is set automatically unless you set `cursorOverStyle`; `javascript:`/`data:`/`vbscript:` URLs are never opened; override `series.openUrl(dataItem)` to intercept. `MapSankeySeries` nodes are not linked — keep a `click` handler there.
+
 ## Disposal
 
 ```js

package/content/pie.md

@@ -55,7 +55,7 @@ chart.appear(1000, 100);
 | Setting | Type | Description |
 |---------|------|-------------|
 | `radius` | percent/number | Outer radius (default: `am5.percent(80)`) |
-| `innerRadius` | percent/number | Inner hole for donut (default: 0). Percent is relative to radius |
+| `innerRadius` | percent/number | Inner hole for donut (default: 0). Percent is relative to radius. `am5.percent(0)` broke the chart before 5.21.0 — use `0` (or omit it) for a plain pie |
 | `startAngle` | number | Start angle in degrees (default: -90) |
 | `endAngle` | number | End angle in degrees (default: 270) |
 
@@ -320,6 +320,10 @@ outerSeries.data.setAll(outerData);
 innerSeries.data.setAll(innerData);
 ```
 
+A negative `innerRadius` (pixels in from the outer edge, a fixed-width ring) with several series sizes the rings correctly since 5.21.0.
+
+**`calculateAggregates` on pie/funnel series (5.21.0):** with `calculateAggregates: true` the change fields — `{valueChange}`/`{valueChangePercent}` (vs. the first slice) and `{valueChangePrevious}`/`{valueChangePreviousPercent}` (vs. the previous one) — are real numbers; before 5.21.0 they were `NaN` on non-XY series (pie, map heat maps). `{valuePercentTotal}` and the totals were not affected.
+
 ## Data-driven slice colors (templateField)
 
 ```js
@@ -346,8 +350,16 @@ series.slices.template.events.on("pointerover", function(ev) {
 series.slices.template.events.on("pointerout", function(ev) {
   ev.target.set("scale", 1);
 });
+
+// Open a URL on click without a handler (5.20.7) — pie, funnel, pyramid and pictorial slices (and bullets)
+series.set("urlField", "url");          // data row: { category: "A", value: 40, url: "https://…" }
+series.set("linkTarget", "_blank");     // default "_self"
 ```
 
+`urlField` has no default (links off until set); the pointer cursor is set automatically unless you set `cursorOverStyle`; `javascript:`/`data:`/`vbscript:` URLs are never opened; override `series.openUrl(dataItem)` to intercept.
+
+**Keyboard (5.21.0):** `series.slices.template.set("focusable", true)` makes slices TAB-reachable — before 5.21.0 focusable pie slices could not be focused. A focusable slice that toggles on click is exposed as a toggle button (`aria-pressed`).
+
 ## Disposal
 
 ```js

package/content/radar.md

@@ -44,10 +44,12 @@ const chart = root.container.children.push(
 | Setting | Type | Description |
 |---------|------|-------------|
 | `radius` | percent/number | Outer radius (default: `am5.percent(80)`) |
-| `innerRadius` | percent/number | Inner radius / hole size (default: 0) |
+| `innerRadius` | percent/number | Inner radius / hole size (default: 0). `am5.percent(0)` broke the chart before 5.21.0 — use `0` there |
 | `startAngle` | number | Start angle in degrees (default: -90) |
 | `endAngle` | number | End angle in degrees (default: 270) |
 
+Since 5.21.0 the radar's radius also leaves room for a legend placed inside the chart (it ignored it).
+
 ## Axes — use circular + radial renderers
 
 ```js
@@ -68,6 +70,8 @@ const yAxis = chart.yAxes.push(am5xy.ValueAxis.new(root, {
 }));
 ```
 
+`AxisRendererRadial` takes its own `radius`/`innerRadius` (pixels or `Percent` of the chart's radius) and `startAngle`/`endAngle`; unset, the chart's are used. A **negative** `radius` is measured in from the chart's radius, as on `AxisRendererCircular` — e.g. `radius: -20` leaves a 20 px ring outside the axis (it broke the axis before 5.21.0); a negative `innerRadius` is measured in from the axis' outer radius. With an `innerRadius` on a renderer, `RadarColumnSeries` tooltips point at the right place since 5.21.0.
+
 ### Circular renderer label options
 
 ```js
@@ -87,7 +91,7 @@ xAxis.get("renderer").labels.template.setAll({
 |-------|---------|
 | `am5radar.RadarLineSeries` | Lines on radar chart (spider chart) |
 | `am5radar.RadarColumnSeries` | Columns on radar chart |
-| `am5radar.SmoothedRadarLineSeries` | Smoothed/curved radar lines |
+| `am5radar.SmoothedRadarLineSeries` | Smoothed/curved radar lines (`tension`, default `0.5`; `1` = straight — changing it after creation works since 5.21.0) |
 
 ```js
 // Radar line series (spider chart)

package/content/stock.md

@@ -263,6 +263,8 @@ Several indicators changed behavior. If you have hardcoded expectations or saved
 
 All indicators now enforce min/max limits on their numeric settings, so extreme values entered in the settings modal can no longer freeze the page (e.g. a Volume Profile row count of 24,000).
 
+**Fixed in 5.21.0:** changing column colors after creation now recolors the columns already drawn — `increasingColor`/`decreasingColor` on `Volume`, `MACD`, `AwesomeOscillator`, `MovingAverageDeviation` and `HeikinAshi`, `upColor`/`downColor` on `VolumeProfile` (e.g. `indicator.set("increasingColor", am5.color(0x00aa00))`). An indicator drawn in its own panel now has its `legend` and `cursor` properties set (they were always `undefined`). Erasing the first stock drawing reports its real `index` in `drawingremoved`.
+
 ### Custom indicator editable settings (5.20.0)
 
 `IIndicatorEditableSetting` gained three properties for the settings modal:
@@ -318,6 +320,10 @@ var data = [
 | Reset | `am5stock.ResetControl` | Reset chart to defaults |
 | Interval | `am5stock.IntervalControl` | Switch time interval |
 
+**Keyboard (5.21.0):** `StockToolbar` `focusable` now defaults to `true` — toolbar buttons are TAB stops and lists work with arrow keys; set `focusable: false` on the `StockToolbar` to get the old behavior. The settings dialog (`am5.Modal`) traps focus while open and gives it back on close; panel and legend icon buttons and overbought/oversold grips have screen-reader names.
+
+**`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.
+
 ## Events
 
 ```js

package/content/ui-elements.md

@@ -6,7 +6,7 @@ amCharts 5 provides built-in interactive UI widgets in the core package. **Prefe
 
 ## Imports
 
-All UI elements are in the core package (`am5`) except ColorPicker.
+All UI elements are in the core package (`am5`) except ColorPicker (and ExportingMenu, which is part of the exporting plugin).
 
 ### CDN / script tags
 ```html
@@ -183,6 +183,20 @@ chart.set("scrollbarX", am5xy.XYChartScrollbar.new(root, {
 }));
 ```
 
+### Position
+
+`opposite` puts a chart's scrollbar on the other side: a horizontal one below the plot, a vertical one on the left. `outsideAxes` sets whether it sits beyond the axes on that side (`true`) or between them and the plot (`false`); unset, the chart decides. Both can be changed at any time and are saved in JSON.
+
+```js
+chart.set("scrollbarX", am5.Scrollbar.new(root, {
+  orientation: "horizontal",
+  opposite: true,      // below the plot
+  outsideAxes: true    // below the X axis labels too
+}));
+```
+
+`opposite` (5.20.2) and `outsideAxes` (5.21.0) work only for scrollbars set as a chart's `scrollbarX`/`scrollbarY` (not to be confused with the axis renderer's `opposite`). A scrollbar hidden with `visible: false`, `forceHidden` or `hide()` no longer leaves an empty band (5.21.0).
+
 ### Styling
 
 ```js
@@ -284,7 +298,8 @@ An HTML overlay dialog.
 
 ```js
 var modal = am5.Modal.new(root, {
-  content: "<h2>Notice</h2><p>Chart data is loading...</p>"
+  content: "<h2>Notice</h2><p>Chart data is loading...</p>",
+  ariaLabel: "Loading"   // (5.21.0) dialog name for screen readers; default: the first heading in content
 });
 
 modal.open();
@@ -297,6 +312,21 @@ modal.events.on("closed", function() {
 modal.close();
 ```
 
+Since 5.21.0 a `Modal` (also the one `StockChart` settings use) is a dialog to screen readers: focus moves into it when it opens, TAB stays inside it, and closing it gives focus back.
+
+---
+
+## ExportingMenu
+
+The exporting plugin's menu (`am5plugins_exporting.ExportingMenu`, requires `plugins/exporting.js`) is an HTML overlay too; see SKILL.md → Exporting. Since 5.21.0 it lists an **SVG** image item by default — remove it with `svgOptions: { disabled: true }` on the `Exporting` object — and is accessible: items are menu items to screen readers, the icon tells whether the menu is open, and closing the menu returns focus to the icon.
+
+```js
+am5plugins_exporting.Exporting.new(root, {
+  menu: am5plugins_exporting.ExportingMenu.new(root, {}),
+  svgOptions: { disabled: true }   // no "SVG" item; pngOptions/jpgOptions/pdfOptions take `disabled` too
+});
+```
+
 ---
 
 ## ColorPicker

package/content/venn.md

@@ -147,9 +147,9 @@ series.labels.template.adapters.add("text", function(text, target) {
 });
 ```
 
-## Serialization gotcha: custom hover is not captured
+## Serialization gotcha: `hoverGraphics` is not captured
 
-`series.hoverGraphics` (the dashed set outline used in the amCharts venn demo) and `slices.template.states.create("hover", …)` are **not** written by `am5plugins_json.ChartSerializer` as of 5.20.5 — a venn rebuilt from JSON loses any custom hover look (`slices.template.tooltipText` does round-trip). Re-apply `hoverGraphics.setAll({...})` in code after `JsonParser.parse()`.
+`series.hoverGraphics` (the dashed set outline used in the amCharts venn demo) is **not** written by `am5plugins_json.ChartSerializer` as of 5.21.0 — a venn rebuilt from JSON loses that outline. Re-apply `hoverGraphics.setAll({...})` in code after `JsonParser.parse()`. Slice-template states (`slices.template.states.create("hover", …)`) and `slices.template.tooltipText` do round-trip. Before 5.21.0 a `Venn` pushed straight into `root.container` could not be serialized on its own (stack overflow) — wrap it in a `Container` or upgrade.
 
 ## Click events
 
@@ -160,6 +160,8 @@ series.slices.template.events.on("click", function(ev) {
 });
 ```
 
+To open a URL on click, no handler is needed (5.20.7): `am5venn.Venn.new(root, { …, urlField: "url", linkTarget: "_blank" })` (`linkTarget` default `"_self"`) links each slice — sets and intersections — to the `url` in its data row; the pointer cursor is set automatically.
+
 ## Legend
 
 ```js

package/content/wordcloud.md

@@ -79,7 +79,7 @@ series.appear(1000);
 | `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.
+**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. Before **5.21.0** a word failing more than one of `minValue`, `minWordLength` and `excludeWords` also removed a neighbouring word — if you filtered words out of the data yourself to avoid that, the settings are safe to use now.
 
 ### excludeWords example
 

package/content/xy.md

@@ -60,6 +60,8 @@ chart.appear(1000, 100);
 | `am5xy.DurationAxis` | Duration values | `value` | No |
 | `am5xy.GaplessDateAxis` | Time data without gaps | `value` (timestamps) | No |
 
+`DurationAxis` values are amounts of its `baseUnit` (e.g. `"second"`), labelled by `root.durationFormatter` (`durationFormat`, `durationFormats`). Since 5.21.0 durations between a month and a year use the month formats again (`1m 15d 00:00:00`, not `45d 00:00:00`), and format codes `H`, `D`, `Y`, `K`, `k`, `n` work (they gave `NaN`, e.g. `"HH:mm:ss"`). `GaplessDateAxis` with grouped data and `root.timezone` set no longer stays blank (5.21.0).
+
 ## Series types
 
 | Series class | Use for |
@@ -96,6 +98,7 @@ chart.set("cursor", am5xy.XYCursor.new(root, {
 ```js
 chart.set("scrollbarX", am5.Scrollbar.new(root, { orientation: "horizontal" }));
 // opposite: true (5.20.2) puts scrollbarX below the plot / scrollbarY on the left
+// outsideAxes: true (5.21.0) puts it beyond the axes on its side, false between them and the plot
 ```
 
 ### Legend
@@ -167,7 +170,7 @@ xAxis.data.setAll(data);
 - `tooltip` — shows category under cursor
 
 **Gotchas:**
-- Category order in axis data and series data must match
+- Since 5.20.6 series data need **not** follow the axis-category order for every item to be drawn (before, out-of-order items — e.g. Gantt-like column charts sorted by date — could silently disappear). Line series still connect points in **data** order, so keep line data in category order.
 - Forgetting `xAxis.data.setAll()` is the #1 mistake — the chart will render empty
 
 ## DateAxis
@@ -227,6 +230,8 @@ 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.
+
 ## AxisRendererX / AxisRendererY
 
 Controls visual rendering of an axis. Every axis MUST have a renderer.
@@ -413,8 +418,10 @@ 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)
+  // opposite: true     // (5.20.2) place below the plot instead of above (scrollbarY: left instead of right)
+  // outsideAxes: true  // (5.21.0) beyond the axes on that side; false = between axes and plot; unset = chart decides
 }));
+// Hiding it (visible: false / forceHidden / hide()) leaves no empty band above the plot since 5.21.0
 
 // Scrollbar with preview chart:
 const scrollbar = am5xy.XYChartScrollbar.new(root, {
@@ -590,6 +597,17 @@ series.bullets.push(function(root, series, dataItem) {
 
 // Auto-hide bullets when too close together
 series.set("minBulletDistance", 20);
+
+// Bullets at the same spot can stack instead of overlapping: am5.Bullet.new(root, { stacked: "up" | "down" | "auto", ... })
+// (XY only; "up", and "auto" in the lower half, overlapped on vertical series before 5.21.0)
+
+// Pulsing bullet declared as data (5.20.8) — survives JSON serialization, unlike animate()
+series.bullets.push(function(root, series, dataItem) {
+  return am5.Bullet.new(root, {
+    sprite: am5.Circle.new(root, { radius: 5, fill: series.get("fill"),
+      animations: [{ key: "scale", from: 1, to: 1.6, duration: 800, loops: 0, yoyo: true, easing: "sine" }] })
+  });
+});
 ```
 
 ## Dual Y-axis (multiple value axes)
@@ -685,8 +703,14 @@ series.bullets.push(function(root, series, dataItem) {
 xAxis.events.on("rangechanged", function() {
   console.log("Axis range changed (zoomed/scrolled)");
 });
+
+// Open a URL on click without a handler (5.20.7): columns and bullets of the series are linked
+series.set("urlField", "url");          // data row: { category: "A", value: 10, url: "https://…" }
+series.set("linkTarget", "_blank");     // default "_self"
 ```
 
+`urlField` has no default (links off until set) and works on every series' bullets and on all column-type series (`ColumnSeries`, `CandlestickSeries`, `OHLCSeries`, Gantt). The pointer cursor is set automatically unless you set `cursorOverStyle`; `javascript:`/`data:`/`vbscript:` URLs are never opened; override `series.openUrl(dataItem)` to intercept.
+
 ## Chart settings reference
 
 ```js