@amcharts/amcharts5-mcp 1.4.0 → 1.6.0

package/content/timeline.md

@@ -214,7 +214,7 @@ series.set("snapTooltip", true);
 Bullets on timeline charts work the same as XY charts:
 
 ```js
-series.bullets.push(function() {
+series.bullets.push(function(root, series, dataItem) {
   return am5.Bullet.new(root, {
     sprite: am5.Circle.new(root, {
       radius: 5,
@@ -258,7 +258,7 @@ series.bullets.push(function(root, series, dataItem) {
 
 ```js
 // Click on data points (via bullets)
-series.bullets.push(function() {
+series.bullets.push(function(root, series, dataItem) {
   var circle = am5.Circle.new(root, {
     radius: 5,
     fill: series.get("fill"),
@@ -346,7 +346,7 @@ chart.get("cursor").events.on("cursormoved", function(ev) {
     series.fills.template.setAll({ visible: true, fillOpacity: 0.3 });
 
     // Add bullets
-    series.bullets.push(function() {
+    series.bullets.push(function(root, series, dataItem) {
       return am5.Bullet.new(root, {
         sprite: am5.Circle.new(root, {
           radius: 4,

package/content/venn.md

@@ -147,6 +147,10 @@ series.labels.template.adapters.add("text", function(text, target) {
 });
 ```
 
+## Serialization gotcha: custom hover 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.8 — 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()`.
+
 ## Click events
 
 ```js
@@ -156,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,6 +79,8 @@ 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.
+
 ### excludeWords example
 
 ```js

package/content/xy.md

@@ -95,6 +95,7 @@ chart.set("cursor", am5xy.XYCursor.new(root, {
 ### Scrollbar
 ```js
 chart.set("scrollbarX", am5.Scrollbar.new(root, { orientation: "horizontal" }));
+// opposite: true (5.20.2) puts scrollbarX below the plot / scrollbarY on the left
 ```
 
 ### Legend
@@ -166,7 +167,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
@@ -191,6 +192,10 @@ const xAxis = chart.xAxes.push(am5xy.DateAxis.new(root, {
 - `markUnitChange: true` — highlights when time unit changes on axis labels (e.g., new month)
 - `tooltipDateFormat` — format string for cursor tooltip
 
+**Live updates — two settings that do not refresh on `set()`:**
+- **Date format maps** (`dateFormats`, `periodChangeDateFormats`, `minorDateFormats`): after `axis.set("dateFormats", {...})` already-rendered labels keep their old text. `axis.markDirtyValues()` is not enough — call **`axis.markDirtySize()`** to make the axis re-run label formatting.
+- **`groupIntervals`** (with `groupData: true`): amCharts only (re)computes grouping when a series' data is set, so changing the allowed intervals on an already-grouped axis does nothing until you re-set the data on every series bound to the axis: `series.data.setAll(series.data.values.slice())`.
+
 **Data format:**
 ```js
 series.data.setAll([
@@ -324,7 +329,12 @@ series.columns.template.setAll({
   width: am5.percent(80),        // column width
 });
 
-// Individual column colors from data:
+// Individual column colors (5.20.4) — declarative, serializes to JSON:
+series.set("colorByDataItem", true);          // each column takes the next color from series.get("colors")
+// series.set("colors", am5.ColorSet.new(root, { colors: [...] }));   // optional own palette (the series makes one if absent)
+// Per-item color from data instead: templateField + a `fill` in each data item (see pie.md "Data-driven slice colors")
+
+// Pre-5.20.4 fallback — an adapter (does NOT survive JSON serialization):
 series.columns.template.adapters.add("fill", (fill, target) => {
   return chart.get("colors").getIndex(series.columns.indexOf(target));
 });
@@ -403,6 +413,7 @@ Enables zooming/panning via scrollbar. Can optionally include a preview chart.
 // Simple scrollbar:
 chart.set("scrollbarX", am5.Scrollbar.new(root, {
   orientation: "horizontal"
+  // opposite: true   // (5.20.2) place below the plot instead of above (scrollbarY: left instead of right)
 }));
 
 // Scrollbar with preview chart:
@@ -579,6 +590,14 @@ series.bullets.push(function(root, series, dataItem) {
 
 // Auto-hide bullets when too close together
 series.set("minBulletDistance", 20);
+
+// 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)
@@ -610,8 +629,13 @@ var series2 = chart.series.push(am5xy.LineSeries.new(root, {
   xAxis: xAxis, yAxis: yAxis2,
   valueYField: "units", valueXField: "date"
 }));
+
+// Removing an axis — go through the list, NOT axis.dispose():
+chart.yAxes.removeValue(yAxis2);   // the list auto-disposes the removed axis
 ```
 
+`axis.dispose()` marks the axis disposed but **leaves it in `chart.yAxes`/`chart.xAxes`** (unlike `series.dispose()`, which removes itself from `chart.series`). The stale entry keeps rendering in anything built from the list and makes `ChartSerializer` throw `Template is disposed`. Always use `removeValue(axis)` / `removeIndex(i)`.
+
 ## Axis titles
 
 ```js
@@ -669,8 +693,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

package/extended/charts/map-chart/map-line-series.md

@@ -268,7 +268,7 @@ lineSeries.pushDataItem({
 
 This can also work the other way around: we can make a data item form map line series "stick" to any point on a line.
 
-All we have to do is to set `lineDataItem` to a data item of the specific line, as well as `positionOnLine` to indicate relative position, when creating a point series data item:
+All we have to do is to set `lineDataItem` to a data item of the specific line, as well as `positionOnLine` to indicate relative position, when creating a point series data item (since 5.20.6 the same can be done in regular data — see "Points on a line via data" below):
 
 // Create line series
 let lineSeries = chart.series.push(
@@ -369,4 +369,113 @@ If set, this will be added to the angle calculated by `autoRotate`. Can be used
 
 The below example uses above code, albeit with the slightly more sophisticated image as a point bullet:
 
+### Points on a line via data (5.20.6)
+
+Since 5.20.6, `lineId`, `positionOnLine`, `autoRotate` and `autoRotateAngle` can be given in point series' data, so a point placed on a line no longer needs to be created with `pushDataItem()` and a `lineDataItem`. `lineId` is the `id` of a line in this line series' data (the line series' `idField`, `"id"` by default). Pushing the line series to the chart before the point series is a safe precaution.
+
+The data fields are read via these point series settings, which all have defaults, so nothing needs to be set:
+
+Setting
+
+Default
+
+`lineIdField`
+
+`"lineId"`
+
+`positionOnLineField`
+
+`"positionOnLine"`
+
+`autoRotateField`
+
+`"autoRotate"`
+
+`autoRotateAngleField`
+
+`"autoRotateAngle"`
+
+`autoRotate` and `autoRotateAngle` values in data take precedence over the same settings on the bullet.
+
+```javascript
+// Create line series
+var lineSeries = chart.series.push(
+  am5map.MapLineSeries.new(root, {})
+);
+
+lineSeries.data.setAll([{
+  id: "route",
+  geometry: {
+    type: "LineString",
+    coordinates: [
+      [ -73.778137, 40.641312 ],
+      [ -0.454296, 51.470020 ],
+      [ 116.597504, 40.072498 ]
+    ]
+  }
+}]);
+
+// Create point series
+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(0xff0000)
+    })
+  });
+});
+
+pointSeries.data.setAll([{
+  lineId: "route",
+  positionOnLine: 0.7,
+  autoRotate: true
+}]);
+```
+
+NOTE This matters when the chart is [serialized](https://www.amcharts.com/docs/v5/concepts/serializing/chart-serializer/): points created with `pushDataItem()` are not data rows, so they are not part of a serialized config. Points given as data rows are.
+
+#### Animating a point along a line (5.20.8)
+
+To make a point travel along its line, give the bullet's sprite an [`animations`](https://www.amcharts.com/docs/v5/concepts/animations/) entry with `target: "dataItem"` that animates `positionOnLine`. Unlike a `dataItem.animate()` call in code, this is part of the config, so it survives serialization.
+
+```javascript
+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,
+      animations: [{
+        target: "dataItem",
+        key: "positionOnLine",
+        from: 0,
+        to: 1,
+        duration: 6000,
+        loops: 0,
+        yoyo: true,
+        easing: "cubic",
+        ease: "inOut"
+      }]
+    })
+  });
+});
+
+planeSeries.data.setAll([{
+  lineId: "route",
+  positionOnLine: 0,
+  autoRotate: true
+}]);
+```
+
+Since 5.20.8, an auto-rotating point turns round (180° is added to its angle) while such an `animations` entry moves it back toward the start of the line — e.g. on the way back of a `yoyo` — so the plane faces the way it is travelling. This applies only to an `animations` entry on the bullet's sprite; a point moved from code with `dataItem.animate()` is not turned round, and that code is expected to turn it itself (e.g. via `autoRotateAngle`).
+
 

package/extended/charts/map-chart/map-point-series.md

@@ -438,7 +438,7 @@ lineSeries.pushDataItem({
 
 This can also work the other way around: we can make a data item form map line series "stick" to any point on a line.
 
-All we have to do is to set `lineDataItem` to a data item of the specific line, as well as `positionOnLine` to indicate relative position, when creating a point series data item:
+All we have to do is to set `lineDataItem` to a data item of the specific line, as well as `positionOnLine` to indicate relative position, when creating a point series data item (since 5.20.6 the same can be done in regular data — see "Points on a line via data" below):
 
 // Create line series
 let lineSeries = chart.series.push(
@@ -539,6 +539,115 @@ If set, this will be added to the angle calculated by `autoRotate`. Can be used
 
 The below example uses above code, albeit with the slightly more sophisticated image as a point bullet:
 
+### Points on a line via data (5.20.6)
+
+Since 5.20.6, `lineId`, `positionOnLine`, `autoRotate` and `autoRotateAngle` can be given in point series' data, so a point placed on a line no longer needs to be created with `pushDataItem()` and a `lineDataItem`. `lineId` is the `id` of a line in a map line series' data (the line series' `idField`, `"id"` by default). Pushing the line series to the chart before the point series is a safe precaution.
+
+The data fields are read via these point series settings, which all have defaults, so nothing needs to be set:
+
+Setting
+
+Default
+
+`lineIdField`
+
+`"lineId"`
+
+`positionOnLineField`
+
+`"positionOnLine"`
+
+`autoRotateField`
+
+`"autoRotate"`
+
+`autoRotateAngleField`
+
+`"autoRotateAngle"`
+
+`autoRotate` and `autoRotateAngle` values in data take precedence over the same settings on the bullet. (`polygonIdField`, on the other hand, still has no default and needs to be set to use polygon ids in data.)
+
+```javascript
+// Create line series
+var lineSeries = chart.series.push(
+  am5map.MapLineSeries.new(root, {})
+);
+
+lineSeries.data.setAll([{
+  id: "route",
+  geometry: {
+    type: "LineString",
+    coordinates: [
+      [ -73.778137, 40.641312 ],
+      [ -0.454296, 51.470020 ],
+      [ 116.597504, 40.072498 ]
+    ]
+  }
+}]);
+
+// Create point series
+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(0xff0000)
+    })
+  });
+});
+
+pointSeries.data.setAll([{
+  lineId: "route",
+  positionOnLine: 0.7,
+  autoRotate: true
+}]);
+```
+
+NOTE This matters when the chart is [serialized](https://www.amcharts.com/docs/v5/concepts/serializing/chart-serializer/): points created with `pushDataItem()` are not data rows, so they are not part of a serialized config. Points given as data rows are.
+
+#### Animating a point along a line (5.20.8)
+
+To make a point travel along its line, give the bullet's sprite an [`animations`](https://www.amcharts.com/docs/v5/concepts/animations/) entry with `target: "dataItem"` that animates `positionOnLine`. Unlike a `dataItem.animate()` call in code, this is part of the config, so it survives serialization.
+
+```javascript
+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,
+      animations: [{
+        target: "dataItem",
+        key: "positionOnLine",
+        from: 0,
+        to: 1,
+        duration: 6000,
+        loops: 0,
+        yoyo: true,
+        easing: "cubic",
+        ease: "inOut"
+      }]
+    })
+  });
+});
+
+planeSeries.data.setAll([{
+  lineId: "route",
+  positionOnLine: 0,
+  autoRotate: true
+}]);
+```
+
+Since 5.20.8, an auto-rotating point turns round (180° is added to its angle) while such an `animations` entry moves it back toward the start of the line — e.g. on the way back of a `yoyo` — so the plane faces the way it is travelling. This applies only to an `animations` entry on the bullet's sprite; a point moved from code with `dataItem.animate()` is not turned round, and that code is expected to turn it itself (e.g. via `autoRotateAngle`).
+
 
 ## Hover behavior
 

package/extended/charts/map-chart/map-polygon-series.md

@@ -378,6 +378,53 @@ polygonSeries.mapPolygons.template.events.on("click", function(ev) {
   }
 });
 
+### Linking via `urlField` (5.20.7)
+
+Since 5.20.7 a click handler is not needed: set series' `urlField` to the data field holding the URL, and clicking a polygon that has one opens it. `linkTarget` sets where it opens.
+
+```javascript
+var polygonSeries = chart.series.push(
+  am5map.MapPolygonSeries.new(root, {
+    geoJSON: am5geodata_worldLow,
+    urlField: "url",
+    linkTarget: "_blank"
+  })
+);
+
+polygonSeries.data.setAll([{
+  id: "US",
+  url: "https://en.wikipedia.org/wiki/United_States"
+}, {
+  id: "CA",
+  url: "https://en.wikipedia.org/wiki/Canada"
+}, {
+  id: "MX",
+  url: "https://en.wikipedia.org/wiki/Mexico"
+}]);
+```
+
+Setting
+
+Default
+
+Comment
+
+`urlField`
+
+(none)
+
+A data field holding the URL to open when the data item's element is clicked. Links are off until this is set.
+
+`linkTarget`
+
+`"_self"`
+
+Where the URL opens: `"_self"` (same window, like a plain link), `"_blank"` (new tab, opened with `noopener`), or a named window/frame. A chart embedded in an iframe usually wants `"_blank"` or `"_top"`.
+
+Polygons with a URL get a pointer cursor automatically, unless you set a `cursorOverStyle` yourself. `urlField` can be set after the data, and a URL added to an item later (e.g. via `data.setIndex()`) links too. Script URLs (`javascript:`, `data:`, `vbscript:`) are not opened. To intercept links (e.g. in an editor), override the series' `openUrl(dataItem)` method.
+
+The same settings work on other series: they link bullets of any series, columns (including candlesticks, OHLC and Gantt bars), pie/funnel/pyramid/pictorial slices, Venn slices, and map lines. Hierarchy nodes, flow nodes and links, word cloud words and map Sankey nodes are not linked — use a click handler for those.
+
 ## Excluding or including polygons
 
 Series can be set up to either exclude certain polygons out of the loaded geodata, or only include specific ones.

package/extended/charts/xy-chart/axes/category-axis.md

@@ -60,6 +60,8 @@ Or it can be a subset of data.
 
 IMPORTANTThe order of categories needs to be the same in both series' and axis' data.
 
+NOTE Since 5.20.6, series items are drawn even when the series' data is not in the same order as the axis categories — for example, a Gantt-like column chart where several items share a category and the data is sorted by date. (Before, some of those items were not drawn at all.) A line series, however, still connects its points in data order, so for lines keep the series data in category order.
+
 Having different data for category axis makes sense in the situations where we want to have only specific categories displayed:
 
 let xAxis = chart.xAxes.push(

package/extended/concepts/animations.md

@@ -102,6 +102,124 @@ handDataItem.animate({
 });
 
 
+## Declarative animations (`animations` setting)
+
+Since 5.20.8 every element has an `animations` setting: a list of animations described as data instead of started with `animate()`. Being a plain setting, it can be set like any other — on an element, a template, a bullet's sprite, or in a [JSON config](https://www.amcharts.com/docs/v5/concepts/serializing/) — and a [serialized](https://www.amcharts.com/docs/v5/concepts/serializing/chart-serializer/) chart keeps it.
+
+NOTE The typings (and API reference) mark `animations` as `@since 5.21.0`, but it shipped in 5.20.8.
+
+Each entry in the list is an object with these fields:
+
+Field
+
+Default
+
+Comment
+
+`key`
+
+(required)
+
+Setting to animate. With `target: "dataItem"`, a value of the element's data item.
+
+`from`
+
+current value
+
+Value to start from.
+
+`to`
+
+(required)
+
+Value to animate to.
+
+`duration`
+
+(required)
+
+Duration in milliseconds. With `yoyo`, it is the duration of one way, so a full there-and-back takes twice as long.
+
+`delay`
+
+`0`
+
+Milliseconds to wait before starting.
+
+`loops`
+
+`1`
+
+How many times to play the animation. `0` plays it forever (`Infinity` works too in JavaScript).
+
+`yoyo`
+
+`false`
+
+Go back to `from` after reaching `to`, rather than jumping back.
+
+`easing`
+
+`"linear"`
+
+Easing **by name**: `"linear"`, `"quad"`, `"cubic"`, `"exp"`, `"sine"`, `"circle"`, `"bounce"` or `"elastic"`. An unknown name silently falls back to linear. Functions are not accepted here.
+
+`ease`
+
+`"in"`
+
+Which way the easing applies: `"in"`, `"out"` or `"inOut"` — the same as wrapping the function in `am5.ease.out()` or `am5.ease.inOut()`.
+
+`target`
+
+`"self"`
+
+`"self"` animates a setting of the element; `"dataItem"` animates a value of the element's data item.
+
+The following makes each bullet pulse, for ever:
+
+```javascript
+series.bullets.push(function (root, series, dataItem) {
+  return am5.Bullet.new(root, {
+    sprite: am5.Circle.new(root, {
+      radius: 6,
+      animations: [
+        { key: "scale", from: 1, to: 1.6, duration: 800, loops: 0, yoyo: true, easing: "sine" },
+        { key: "opacity", from: 1, to: 0.3, duration: 800, loops: 0, yoyo: true }
+      ]
+    })
+  });
+});
+```
+
+The animations start when the setting is applied, restart when it changes (the settings they animated are put back to what they held first), and stop when the element is disposed.
+
+IMPORTANT With `from` omitted, the animation starts from the setting's current value. If that value is `undefined`, the element jumps straight to `to` and nothing animates. `scale`, `opacity` and `rotation` are fine (the theme gives them a value), but settings like `dx` or `fill`, or a data item value that is not set yet (e.g. a map point without `positionOnLine`), need an explicit `from`.
+
+With `target: "dataItem"`, the entry animates the data item the element belongs to — for example, a map point's `positionOnLine`, which flies the point along its line. See "[Map point series: Points on a line](https://www.amcharts.com/docs/v5/charts/map-chart/map-point-series/#Points_on_a_line)".
+
+In a JSON config, colors and percents in `from`/`to` are written in their object form:
+
+```json
+{
+  "type": "Circle",
+  "settings": {
+    "radius": 6,
+    "animations": [{
+      "key": "fill",
+      "from": { "type": "Color", "value": "#ff0000" },
+      "to": { "type": "Color", "value": "#0000ff" },
+      "duration": 1000,
+      "loops": 0,
+      "yoyo": true
+    }]
+  }
+}
+```
+
+A serialized chart keeps the values the animated settings were configured with, never ones caught mid-animation. `ChartSerializer` can also turn a never-ending animation started in code with `animate()` into an `animations` entry — see its `runningAnimations` setting in "[Chart serializer](https://www.amcharts.com/docs/v5/concepts/serializing/chart-serializer/)".
+
+
 ## Animating between states
 
 When element [state](https://www.amcharts.com/docs/v5/concepts/settings/states/) is applied, its values will replace current setting values.
@@ -328,12 +446,12 @@ Will overshoot end value, then bounce back a few times before settling down at t
 
 Constant speed during all duration.
 
-`am5.ease.pow`
-
 `am5.ease.quad`
 
 `am5.ease.sine`
 
+NOTE `am5.ease.pow` is not a ready-to-use easing: it is `pow(t, e)` and needs an exponent as its second parameter. Passed directly as `easing`, the exponent is `undefined` and the animation produces `NaN`. Wrap it in a function instead: `easing: function(t) { return am5.ease.pow(t, 3); }`.
+
 Below demo shows the behavior of various basic easing functions:
 
 
@@ -375,4 +493,20 @@ The basic easing function is applied at the end animation.
 
 Plays animation to the end value, then returns back to the starting value, using supplied basic function.
 
+### Easing functions by name (5.20.8)
+
+The eight basic easing functions listed above carry a name, which is what lets the [`animations` setting](#Declarative_animations_animations_setting) and JSON configs refer to them as strings.
+
+`am5.ease.byName(name, mode)` returns an easing function by its name — `"linear"`, `"quad"`, `"cubic"`, `"exp"`, `"sine"`, `"circle"`, `"bounce"` or `"elastic"` — optionally wrapped by `mode`: `"in"` (default), `"out"` or `"inOut"`. An unknown name gives `linear`.
+
+`am5.ease.easingInfo(easing)` does the opposite: it returns `{ easing, ease?, yoyo? }` describing a function, or `undefined` for one that cannot be named. Functions made with `out()`, `inOut()` and `yoyo()` keep the name of the function they wrap; a function of your own, a wrapped `pow`, or a combination like `out(yoyo(...))` has none.
+
+```javascript
+am5.ease.byName("cubic", "out");                     // same as am5.ease.out(am5.ease.cubic)
+am5.ease.easingInfo(am5.ease.yoyo(am5.ease.sine));   // { easing: "sine", yoyo: true }
+am5.ease.easingInfo(function(t) { return t * t; });  // undefined
+```
+
+NOTE The typings mark `byName()`, `easingInfo()` and `IEasingInfo` as `@since 5.21.0`, but they shipped in 5.20.8.
+
 

package/extended/concepts/data.md

@@ -773,6 +773,8 @@ am5.net.load("/data/mydata.csv").then(function(result) {
   console.log("Error loading " + result.xhr.responseURL);
 });
 
+NOTE Since 5.20.7, `CSVParser.parse()` copes with an empty string, such as an empty response from a server. Before, it looped until it ran out of memory and threw "Invalid array length". With `useColumnNames: true` an empty string now parses to an empty array (`[]`); without it, to a single empty row (`[{}]`) — check for an empty `result.response` before parsing if you need to tell the two apart.
+
 We can also use standalone data parser to parse date/numeric/color fields in data after it is parsed:
 
 am5.net.load("/data/mydata.csv").then(function(result) {

package/extended/concepts/events.md

@@ -166,6 +166,20 @@ xAxis.onPrivate("selectionMax", function(value, target) {
   console.log("End date changed:", end);
 });
 
+### One-shot handlers (5.20.4)
+
+`once(key, callback)` works like `on()` but fires only the first time that setting changes (or is set), then removes itself. `onceDebounced(key, callback, delay)` is the debounced version. Both return an `IDisposer`.
+
+series.once("visible", function(visible, target) {
+  console.log("First visibility change", visible);
+});
+
+xAxis.onceDebounced("start", function(start) {
+  console.log("Zoom settled at", start);
+}, 300);
+
+(Do not confuse with `events.once("eventName", …)`, which has existed for regular events all along.)
+
 ### Removing
 
 Turning off value change events are similar to regular events: we can just use `off()` or `offPrivate()` methods.