@amcharts/amcharts5-mcp 1.2.0 → 1.4.0

package/README.md

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

package/content/SKILL.md

@@ -105,7 +105,16 @@ root.dateFormatter.setAll({ dateFormat: "yyyy-MM-dd" });
 root.numberFormatter.setAll({ numberFormat: "#,###.##" });
 ```
 
-**Available themes:** `Animated`, `Dark`, `Frozen`, `Dataviz`, `Material`, `Moonrise`, `Spirited`, `Kelly`, `Micro`, `Responsive`.
+**Available themes** (as of 5.20.0):
+
+| Kind | Themes |
+|------|--------|
+| Behavioral | `Animated` (animations), `Micro` (stripped-down micro charts), `Responsive` (size-based rules) |
+| Light palettes | `Dataviz`, `Frozen`, `Kelly`, `Material`, `Moonrise`, `Spirited`, `Ember`, `Nord`, `Pastel`, `Petroleum`, `Savanna`, `Colorblind` (Okabe-Ito, color-blindness safe), `Patterns` (pattern fills instead of flat colors) |
+| Dark | `Dark`, `Midnight`, plus a dark variant of most palettes: `DatavizDark`, `FrozenDark`, `KellyDark`, `MaterialDark`, `MoonriseDark`, `SpiritedDark`, `NordDark`, `PastelDark`, `ColorblindDark`, `PatternsDark` |
+| Parameterized (5.20.0) | `Monochrome`, `Adaptive` — see below |
+
+Palette themes are additive: combine with `Animated`, e.g. `root.setThemes([am5themes_Animated.new(root), am5themes_Nord.new(root)])`. The `*Dark` variants already carry dark interface colors, so do NOT also add `Dark`.
 
 ## Colors
 
@@ -458,6 +467,39 @@ series.columns.template.states.create("active", {
 // State animation: stateAnimationDuration, stateAnimationEasing
 ```
 
+## Parameterized themes — Monochrome & Adaptive (5.20.0)
+
+Two themes generate their palette from colors you pass in (OKLCH-based, so the result stays perceptually balanced). Because a theme cannot take constructor parameters, these ship as **factory functions** — call them with `(root, settings)`; `.new(root, settings)` also works.
+
+```js
+import am5themes_Monochrome from "@amcharts/amcharts5/themes/Monochrome";
+import am5themes_Adaptive from "@amcharts/amcharts5/themes/Adaptive";
+
+// Monochrome — single-hue lightness ramp
+root.setThemes([
+  am5themes_Animated.new(root),
+  am5themes_Monochrome(root, {
+    color: 0x2c6e91,   // base hue (default: blue #2e7c9e)
+    accent: 0xff7f0e,  // optional — applied to the FIRST series only, so it pops
+    count: 7,          // steps in the ramp (default 7)
+    dark: false        // true = dark background + light-to-mid ramp
+  })
+]);
+
+// Adaptive — full palette generated from one or two base colors
+root.setThemes([
+  am5themes_Animated.new(root),
+  am5themes_Adaptive(root, {
+    baseColor: 0x2c6e91,   // first generated color IS this color (good for brand colors)
+    baseColor2: 0xffdd00,  // optional — palette spans the two colors
+    count: 10,             // number of series colors (default 10)
+    dark: false
+  })
+]);
+```
+
+Both are additive (they do not modify built-in themes) and both handle dark mode themselves via `dark: true` — do not also add the `Dark` theme.
+
 ## Custom themes
 
 ```js
@@ -660,7 +702,7 @@ onUnmounted(() => { root.dispose(); });
 12. **CDN script load order** — `index.js` must load first, then `xy.js`, then any package that depends on it (`radar.js`, `timeline.js`, `gantt.js`). Wrong order causes runtime errors. Correct order: `index.js` → `xy.js` → `radar.js` / `timeline.js` / `gantt.js` → `themes/*.js`.
 13. **No `minorGrid` / `minorTicks` / `minorLabels` objects** — These do not exist on axes. Minor grid is enabled via boolean flags on the **renderer**: `minorGridEnabled: true` and optionally `minorLabelsEnabled: true`. Styling is done through theme rules targeting the `"minor"` tag, not through separate object properties.
 14. **Flow chart animated bullets go on `series.bullets`, NOT `series.links.template.bullets`** — To animate labels/circles flowing along Sankey or Chord links, use `series.bullets.push(function(...) { ... })`. Animate `bullet.locationX` (Sankey) or `bullet.locationY` (Chord) from 0→1 with `loops: Infinity`. Use an adapter on opacity for fade effect. See `references/flow.md` → "Animated bullets along links".
-15. **`MapPointSeries` needs `latitudeField`/`longitudeField` when using `data.setAll()`** — If point data has `latitude`/`longitude` fields, the series must declare them: `am5map.MapPointSeries.new(root, { latitudeField: "latitude", longitudeField: "longitude" })`. Without these, points silently won't appear. This is NOT needed when using `pushDataItem({ latitude: ..., longitude: ... })` which passes coordinates directly.
+15. **`MapPointSeries` needs `latitudeField`/`longitudeField` when your data fields are named anything other than `latitude`/`longitude`** — Since 5.16.1 the series defaults to `latitudeField: "latitude"`, `longitudeField: "longitude"`, so data using exactly those names works with no declaration. Any other naming (`lat`/`lng`, `y`/`x`, …) must be declared or the points silently won't appear: `am5map.MapPointSeries.new(root, { latitudeField: "lat", longitudeField: "lng" })`. Neither is needed with `pushDataItem({ latitude: ..., longitude: ... })`, which passes coordinates directly. On amCharts **older than 5.16.1** there were no defaults, so declare the fields explicitly if you must support those versions.
 16. **`data.setAll()` does NOT animate — use `data.setIndex()` for animated updates** — When the user asks to update/refresh data with animation, do NOT use `series.data.setAll(newData)` — it replaces everything instantly with no transition. Instead, update each item with `series.data.setIndex(i, newItem)` which triggers smooth value animation. For full replacement with animation, loop: `newData.forEach(function(item, i) { series.data.setIndex(i, item); })`.
 17. **`color.lighten()` / `color.darken()` are NOT instance methods** — `am5.color(0xff0000).lighten(0.3)` does NOT work. Use static methods: `am5.Color.lighten(color, 0.3)` to lighten, `am5.Color.lighten(color, -0.3)` to darken. There is NO `darken()` method — use negative lighten. Also available: `am5.Color.brighten()`, `am5.Color.saturate()`.
 18. **Venn diagram has no `VennDiagram` class** — `am5venn.Venn` is pushed directly into a `Container`, NOT into a chart's `series`. See `references/venn.md`.
@@ -716,7 +758,7 @@ Skip this step entirely if you cannot execute code (e.g., chat-only context with
 
 ## Recent API changes (newer than the bundled class reference)
 
-The bundled per-class API reference was snapshotted on **2026-03-15**, so it predates the changes below. Prefer these names/settings; for anything newer, verify against the live docs (see next section).
+The bundled per-class API reference was snapshotted on **2026-03-15**, so it predates the changes below. Latest release covered here: **5.20.1** (2026-08-03). Prefer these names/settings; for anything newer, verify against the live docs (see next section).
 
 **Renamed settings (old name still works but is deprecated — use the new one):**
 
@@ -731,14 +773,50 @@ am5stock.MovingAverage.new(root, { maType: "exponential", period: 20 });
 am5hierarchy.VoronoiTreemap.new(root, { shapeType: "rectangle" }); // was: type
 ```
 
+**Breaking change — WordCloud internals (5.20.1):** the layout is now computed synchronously in one pass (much faster). The per-data-item `ghostLabel` is gone and labels live in an internal container, so `dataItem.get("ghostLabel")` and any code walking `series.children` to find labels must be updated — use `series.labels` / `dataItem.get("label")` instead.
+
 **New settings / methods worth knowing:**
+
+*Themes & styling*
+- 20+ new themes (5.20.0): `Midnight`, `Ember`, `Nord`, `Pastel`, `Colorblind`, `Patterns`, `Petroleum`, `Savanna`, plus `*Dark` variants of most palettes. Two parameterized factory themes, `Monochrome` and `Adaptive` — see "Parameterized themes" above.
+- New fill patterns (5.20.0): `am5.StarPattern` (`radius`, `innerRadius`, `spikes`, `gap`, `checkered`) and `am5.TrianglePattern` (`maxWidth`, `maxHeight`, `gap`, `checkered`).
+- `rotateShapes` (5.20.0) on `RectanglePattern`/`StarPattern`/`TrianglePattern`: `rotation` then spins each shape around its own center instead of the whole grid — tiles seamlessly and is much faster. Prefer it over a whole-pattern `rotation` on large tiles.
+- `Series`: `fillGradient` / `strokeGradient` settings. A bullet `Graphics` with no paint of its own (`fill`, `fillGradient`, `fillPattern`, `stroke`, `strokeGradient`) now inherits all of them from its series — and on pie, funnel, flow and hierarchy charts, from its own slice/node (5.20.0–5.20.1).
+
+*XY charts*
+- `XYChart`: `strokeWidths` (array of pixel widths) and `strokeDasharrays` (array of dash arrays) — cycled across line series as they are added, exactly like `colors`. Lets series be told apart without relying on color, e.g. with the `Patterns` theme.
+- `XYCursor`: `clickTolerance` (default `0`) — how many pixels outside the plot area a press may start and still begin a zoom/selection. The selection itself still starts at the plot edge.
+- `XYSeries`: a value field (`valueYField`, `openValueYField`, …) can now be changed after creation — re-set the series data afterwards for it to take effect. A series can also be reassigned to a different `xAxis`/`yAxis` after creation.
+
+*WordCloud (5.20.1)*
+- `svgPath` arranges words into a shape (experimental), with `maskByShape` to clip them to the outline and `shapeTolerance` to control spill (negative = padding inside). See `references/wordcloud.md`.
+- `randomizeAngles: false` cycles `angles` in order for a reproducible layout; `allowNesting: false` packs words as non-overlapping bounding boxes (use it when labels have opaque backgrounds).
+- `angles` now accepts **any** angle (e.g. `[0, -30, -45]`). Before 5.20.1 only `0`/`±90` were handled, and the old docs said so explicitly — that restriction is gone.
+
+*Core / events*
+- New `globalpointerdown` event on all elements — fires on a press anywhere on the chart surface, mirroring `globalpointermove`/`globalpointerup`.
+- `Root`: `sanitizeHTML` (5.19.0, default `true`) — dynamically-set HTML (`html`/`labelHTML`, HTML tooltips, modal content) is sanitized; set `false` to opt out. Exports gained `escapeFormulas` (default `true`) to guard CSV/XLSX against formula injection.
+- `Root`: `ariaLabel` is now applied to the `<div>` holding the chart's focusable elements (5.20.0).
+- `Label`: `oversizedBehavior: "truncate"` now ignores `maxHeight` (there is no way to truncate text vertically).
+- A `Container`'s `Rectangle`/`RoundedRectangle` background now defaults `crisp` to `true` unless set explicitly (5.20.0).
+
+*Maps*
+- `MapChart`: `projectionName` (5.19.0) — string alternative to `projection`, e.g. `"geoOrthographic"`, mainly for JSON config. Register extra ones with `am5map.registerProjection()`. Bundled projections are no longer eagerly imported, so unused ones tree-shake away.
+- `MapSankeySeries` (5.17.0) — Sankey overlaid on a map; auto-resolves `sourceId`/`targetId` once `polygonSeries` geoJSON loads (5.17.1), so no `datavalidated` wrapper needed. See `references/map.md`.
+- `MapPointSeries` defaults changed to `longitudeField: "longitude"`, `latitudeField: "latitude"` (5.16.1).
+
+*Hierarchy & axes*
 - `Tree`: `fitNodes` (5.18.0, exclude hidden nodes from layout), `nodeSeparation` (5.16.2, custom node-spacing fn), `clustered` (5.16.2, dendrogram layout — leaves at same depth).
 - `ValueAxis`: `syncZeros` (5.16.2, align zero across synced axes — needs `syncWithAxis`).
 - `Hierarchy`: `parentIdField` setting + `setFlatData(data)` method (5.16.2) — feed flat `{id, parentId}` data instead of nested `children`.
-- All entities: `onDebounced(key, cb, delay)` / `offDebounced(key, cb?)` and `onPrivateDebounced` / `offDebouncedPrivate` (5.17.3) — fire once after rapid changes settle.
+
+*Stock*
+- Indicator numeric settings now enforce min/max limits, so extreme values can no longer freeze the page. `IIndicatorEditableSetting` gained `scale`, `maxValue` and `step` (5.20.0).
+- Volume Profile now spreads each bar's volume across its full high/low range instead of placing it all at the close. Several indicator math fixes (Williams %R, Momentum, RSI, Moving Average Cross defaults, Commodity Channel Index) landed in 5.19.0–5.20.0 — see `references/stock.md`.
+
+*All entities*
+- `onDebounced(key, cb, delay)` / `offDebounced(key, cb?)` and `onPrivateDebounced` / `offDebouncedPrivate` (5.17.3) — fire once after rapid changes settle.
 - `Label`: `fontFamily: "inherit"` (5.17.3) uses the chart container's computed font.
-- `MapSankeySeries` (5.17.0) — Sankey overlaid on a map; auto-resolves `sourceId`/`targetId` once `polygonSeries` geoJSON loads (5.17.1), so no `datavalidated` wrapper needed. See `references/map.md`.
-- `MapPointSeries` defaults changed to `longitudeField: "longitude"`, `latitudeField: "latitude"` (5.16.1).
 
 ## Verify unfamiliar API before using it
 

package/content/gantt.md

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

package/content/map.md

@@ -166,7 +166,9 @@ pointSeries.bullets.push(function() {
   });
 });
 
-// Add points via data — requires latitudeField/longitudeField on the series
+// Add points via data. Fields named "latitude"/"longitude" are the series
+// defaults since 5.16.1; any other naming must be declared via
+// latitudeField/longitudeField or the points silently won't render.
 pointSeries.data.setAll([
   { latitude: 48.8566, longitude: 2.3522, name: "Paris" },
   { latitude: 40.7128, longitude: -74.0060, name: "New York" },

package/content/stock.md

@@ -185,7 +185,10 @@ stockChart.indicators.push(am5stock.MovingAverage.new(root, {
   stockSeries: valueSeries,
   legend: legend,
   period: 20,
-  type: "simple"  // "simple", "weighted", "exponential", "dema", "tema"
+  maType: "simple"  // "simple", "weighted", "exponential", "dema", "tema"
+                    // NOTE: `type` was renamed to `maType` in 5.18.0 — `type` still
+                    // works but is deprecated. Same for MovingAverageDeviation,
+                    // MovingAverageEnvelope and BollingerBands.
 }));
 
 // RSI (creates its own panel)
@@ -216,7 +219,7 @@ stockChart.indicators.push(am5stock.Volume.new(root, {
 | Indicator | Class | Needs volumeSeries |
 |-----------|-------|--------------------|
 | Moving Average | `MovingAverage` | No |
-| Moving Average Cross | `MovingAverageCross` | No |
+| Moving Average Cross | `MACross` | No |
 | Moving Average Envelope | `MovingAverageEnvelope` | No |
 | Moving Average Deviation | `MovingAverageDeviation` | No |
 | Bollinger Bands | `BollingerBands` | No |
@@ -244,6 +247,43 @@ stockChart.indicators.push(am5stock.Volume.new(root, {
 
 All classes are under `am5stock.*` (e.g., `am5stock.BollingerBands`).
 
+### Indicator changes in 5.19.0–5.20.0
+
+Several indicators changed behavior. If you have hardcoded expectations or saved settings, re-check them:
+
+| Indicator | Change | Version |
+|-----------|--------|---------|
+| `VolumeProfile` | Each bar's volume is now distributed across the full high/low range it traded, instead of being placed entirely at the closing price. Also no longer errors in `ticks` count mode when the visible price range is flat. | 5.20.0 |
+| `MACross` | Default fast/slow periods were inverted; defaults are now `fastPeriod: 9`, `period: 21`. | 5.20.0 |
+| `WilliamsR` | Used a `period + 1` lookback and treated a missing high/low as `0`; now uses exactly `period` bars. | 5.20.0 |
+| `Momentum` | Skipped its first computable value; now plots from `period` bars onward. | 5.20.0 |
+| `RelativeStrengthIndex` | Returned `0` (max "oversold") for a perfectly flat market; now returns a neutral `50`. | 5.20.0 |
+| `AccelerationBands` | `factor` now displays as the conventional `1` instead of `0.001` in both the settings modal and the legend; upper/lower bands were swapped so `upperColor`/`lowerColor` apply correctly. | 5.20.0–5.20.1 |
+| `CommodityChannelIndex` | Typical price was computed as `(high + low + close) / 2` instead of `/ 3`, inflating values. | 5.19.0 |
+
+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).
+
+### Custom indicator editable settings (5.20.0)
+
+`IIndicatorEditableSetting` gained three properties for the settings modal:
+
+```js
+_editableSettings: [{
+  key: "period",
+  name: "Period",
+  type: "number",
+  minValue: 1,
+  maxValue: 200,   // 5.20.0 — upper bound enforced by the input
+  step: 1          // 5.20.0 — step; a step of 1 also marks the value as an integer
+}, {
+  key: "factor",
+  name: "Factor",
+  type: "number",
+  scale: 1000      // 5.20.0 — display multiplier for the modal ONLY:
+                   // shown value = stored × scale, divided back on save
+}]
+```
+
 ## Data format
 
 ```js
@@ -281,8 +321,9 @@ var data = [
 ## Events
 
 ```js
-// Period changed
-stockChart.events.on("periodselected", (ev) => {
+// Period changed — the `periodselected` event fires on the PeriodSelector
+// instance, NOT on stockChart. Attach the handler to the selector you created.
+periodSelector.events.on("periodselected", (ev) => {
   console.log("Period:", ev.period);
 });
 

package/content/timeline.md

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

package/content/ui-elements.md

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

package/content/wordcloud.md

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

package/content/xy.md

@@ -382,6 +382,17 @@ chart.set("cursor", am5xy.XYCursor.new(root, { snapToSeries: [series] }));
 
 **Do NOT** pass `lineX`/`lineY` as constructor options to `XYCursor.new()`. Always access `cursor.lineX` / `cursor.lineY` after creation.
 
+**Easier edge selections (`clickTolerance`, 5.20.0)** — by default a zoom/select drag can only begin inside the plot area, which makes selecting right up to an edge fiddly. `clickTolerance` widens the area where a press may *start*:
+
+```js
+chart.set("cursor", am5xy.XYCursor.new(root, {
+  behavior: "selectX",
+  clickTolerance: 20    // px outside the plot area where a drag may start (default 0)
+}));
+```
+
+The selection itself still starts at the plot edge — the press point is clamped into the plot area.
+
 For timeline charts, use `am5timeline.CurveCursor` instead — see `references/timeline.md`.
 
 ## Scrollbar
@@ -670,11 +681,50 @@ am5xy.XYChart.new(root, {
   wheelX: "panX",                 // mouse wheel: "panX", "panY", "zoomX", "zoomY", "none"
   wheelY: "zoomX",                // mouse wheel vertical
   pinchZoomX: true,               // mobile pinch zoom on X
-  arrangeFields: false,           // auto-arrange overlapping fields
+  arrangeTooltips: true,          // de-overlap stacked series tooltips (NOTE: there is no `arrangeFields` setting)
   maxTooltipDistance: 0,           // show tooltips for nearby series (-1 = all)
 })
 ```
 
+## Distinguishing line series without color (5.20.0)
+
+`XYChart` can cycle stroke widths and dash patterns across line series as they are added, exactly the way `colors` cycles series colors. Useful for print, for color-blind-safe output, or with the `Patterns` theme.
+
+```js
+const chart = root.container.children.push(am5xy.XYChart.new(root, {
+  strokeWidths: [3, 2, 2],                    // px, cycled per line series
+  strokeDasharrays: [0, [6, 3], [2, 2]]       // 0 or [] = solid line
+}));
+```
+
+Each added line series takes the next entry by position, wrapping around when the array runs out.
+
+## Series gradients (5.20.0)
+
+`Series` accepts `fillGradient` and `strokeGradient`:
+
+```js
+series.set("fillGradient", am5.LinearGradient.new(root, {
+  stops: [{ opacity: 0.6 }, { opacity: 0 }],
+  rotation: 90
+}));
+```
+
+A bullet `Graphics` that sets none of `fill`, `fillGradient`, `fillPattern`, `stroke`, `strokeGradient` now inherits all of them from its series, so bullets pick up series gradients and patterns automatically.
+
+## Changing fields and axes after creation (5.20.0)
+
+```js
+// Swap which data field a series plots — then re-set the data
+series.set("valueYField", "profit");
+series.data.setAll(data);
+
+// Move a series to a different axis
+series.set("yAxis", secondaryYAxis);
+```
+
+Both were previously fixed at creation time. Re-setting the series data is required for a value-field change to take effect.
+
 ---
 
 # amCharts 5 XY Charts — Working Examples