@amcharts/amcharts5-mcp 1.0.0

package/amcharts5-skill/amcharts5-skill/references/hierarchy.md

@@ -0,0 +1,568 @@
+# Hierarchy Charts — Treemap, Sunburst, Force-Directed
+
+
+## Required imports
+
+### ES modules
+```ts
+import * as am5 from "@amcharts/amcharts5";
+import * as am5hierarchy from "@amcharts/amcharts5/hierarchy";
+import am5themes_Animated from "@amcharts/amcharts5/themes/Animated";
+```
+
+### CDN
+```html
+<script src="https://cdn.amcharts.com/lib/5/index.js"></script>
+<script src="https://cdn.amcharts.com/lib/5/hierarchy.js"></script>
+<script src="https://cdn.amcharts.com/lib/5/themes/Animated.js"></script>
+```
+
+## Data structure (shared by all hierarchy types)
+
+```js
+var data = [{
+  name: "Root",
+  children: [{
+    name: "Category A",
+    children: [
+      { name: "Item A1", value: 100 },
+      { name: "Item A2", value: 80 }
+    ]
+  }, {
+    name: "Category B",
+    children: [
+      { name: "Item B1", value: 60 },
+      { name: "Item B2", value: 40 }
+    ]
+  }]
+}];
+
+// Set on series:
+series.data.setAll(data);
+```
+
+## Series types
+
+| Class | Use for | Module |
+|-------|---------|--------|
+| `am5hierarchy.Treemap` | Nested rectangles showing proportions | hierarchy |
+| `am5hierarchy.ForceDirected` | Force-directed bubble/node graph | hierarchy |
+| `am5hierarchy.Sunburst` | Concentric ring chart (hierarchical pie) | hierarchy |
+| `am5hierarchy.Pack` | Packed circles (bubble chart) | hierarchy |
+| `am5hierarchy.Partition` | Rectangular partition layout | hierarchy |
+| `am5hierarchy.Tree` | Traditional tree layout (org charts) | hierarchy |
+| `am5hierarchy.VoronoiTreemap` | Voronoi-based treemap | hierarchy |
+
+## Treemap
+
+```js
+const root = am5.Root.new("chartdiv");
+root.setThemes([am5themes_Animated.new(root)]);
+
+const container = root.container.children.push(am5.Container.new(root, {
+  width: am5.percent(100),
+  height: am5.percent(100),
+  layout: root.verticalLayout
+}));
+
+const series = container.children.push(am5hierarchy.Treemap.new(root, {
+  valueField: "value",
+  categoryField: "name",
+  childDataField: "children",
+  initialDepth: 2,           // how many levels visible initially
+  topDepth: 1,               // hide root node (start from first children)
+  layoutAlgorithm: "squarify",  // "squarify" | "binary" | "slice" | "dice" | "sliceDice"
+  nodePaddingOuter: 4,
+  nodePaddingInner: 4
+}));
+
+// Configure rectangle appearance
+series.rectangles.template.setAll({
+  strokeWidth: 2,
+  stroke: am5.color(0xffffff),
+  cornerRadiusTL: 4,
+  cornerRadiusTR: 4,
+  cornerRadiusBL: 4,
+  cornerRadiusBR: 4
+});
+
+// Tooltip
+series.nodes.template.set("tooltipText", "{category}: [bold]{sum}[/]");
+
+// Labels
+series.labels.template.setAll({
+  text: "{category}",
+  fontSize: 14
+});
+
+series.data.setAll(data);
+series.appear(1000);
+```
+
+## Force-Directed Tree
+
+```js
+const series = container.children.push(am5hierarchy.ForceDirected.new(root, {
+  valueField: "value",
+  categoryField: "name",
+  childDataField: "children",
+  idField: "name",               // for cross-linking
+  linkWithField: "linkWith",     // optional: cross-link nodes
+  minRadius: 20,
+  maxRadius: 80,
+  initialFrames: 200,            // frames of physics simulation
+  centerStrength: 0.5,
+  manyBodyStrength: -15,
+  topDepth: 1
+}));
+
+// Circle appearance
+series.circles.template.setAll({
+  fillOpacity: 0.8,
+  strokeWidth: 2,
+  stroke: am5.color(0xffffff)
+});
+
+// Labels
+series.labels.template.setAll({
+  text: "{category}",
+  fill: am5.color(0xffffff),
+  fontSize: 12
+});
+
+// Links between nodes
+series.links.template.setAll({
+  strokeWidth: 1,
+  strokeOpacity: 0.5
+});
+
+// Outer circles (parent nodes indicator)
+series.outerCircles.template.setAll({
+  strokeWidth: 2,
+  strokeDasharray: [4, 4]
+});
+
+series.data.setAll(data);
+```
+
+## Sunburst
+
+```js
+const series = container.children.push(am5hierarchy.Sunburst.new(root, {
+  valueField: "value",
+  categoryField: "name",
+  childDataField: "children",
+  radius: am5.percent(95),
+  innerRadius: am5.percent(20),   // hole in center
+  // startAngle: -90,              // default: -90
+  // endAngle: 270                 // default: 270 (full circle)
+}));
+
+series.nodes.template.set("tooltipText", "{category}: [bold]{sum}[/]");
+series.labels.template.set("forceHidden", true);  // hide labels if crowded
+
+series.data.setAll(data);
+```
+
+## Pack (Packed Circles)
+
+```js
+const series = container.children.push(am5hierarchy.Pack.new(root, {
+  valueField: "value",
+  categoryField: "name",
+  childDataField: "children",
+  nodePadding: 5
+}));
+
+series.circles.template.setAll({
+  fillOpacity: 0.7,
+  strokeWidth: 2,
+  stroke: am5.color(0xffffff)
+});
+
+series.data.setAll(data);
+```
+
+## Tree
+
+```js
+const series = container.children.push(am5hierarchy.Tree.new(root, {
+  valueField: "value",
+  categoryField: "name",
+  childDataField: "children",
+  orientation: "horizontal",   // "horizontal" | "vertical"
+  topDepth: 0
+}));
+
+series.circles.template.setAll({
+  radius: 15,
+  fillOpacity: 0.9
+});
+
+series.links.template.setAll({
+  strokeWidth: 2,
+  strokeOpacity: 0.5
+});
+
+series.labels.template.setAll({
+  text: "{category}",
+  fontSize: 12
+});
+
+series.data.setAll(data);
+```
+
+## Partition
+
+```js
+const series = container.children.push(am5hierarchy.Partition.new(root, {
+  valueField: "value",
+  categoryField: "name",
+  childDataField: "children",
+  orientation: "horizontal",   // "horizontal" | "vertical"
+  initialDepth: 3
+}));
+
+series.rectangles.template.setAll({
+  strokeWidth: 1,
+  stroke: am5.color(0xffffff)
+});
+
+series.data.setAll(data);
+```
+
+## VoronoiTreemap
+
+**Note:** VoronoiTreemap has NO `.rectangles` property. Unlike `Treemap` (which has `series.rectangles.template`), VoronoiTreemap renders organic polygon cells. Style via `series.nodes.template` and its children.
+
+```js
+const series = container.children.push(am5hierarchy.VoronoiTreemap.new(root, {
+  valueField: "value",
+  categoryField: "name",
+  childDataField: "children",
+  initialDepth: 2,
+  topDepth: 1
+}));
+
+series.data.setAll(data);
+```
+
+## Flat data with parentField (database-friendly)
+
+Instead of nested `children` arrays, use flat data with `id` and `parentId` fields:
+
+```js
+const series = container.children.push(am5hierarchy.Treemap.new(root, {
+  valueField: "value",
+  categoryField: "name",
+  childDataField: "children",  // still required
+  parentIdField: "parentId",   // enables flat data
+  idField: "id"
+}));
+
+// Flat data (e.g., from a database query)
+series.data.setAll([
+  { id: "root", name: "Root", children: [] },
+  { id: "a", name: "Group A", parentId: "root", children: [] },
+  { id: "b", name: "Group B", parentId: "root", children: [] },
+  { id: "a1", name: "Item A1", parentId: "a", value: 100 },
+  { id: "a2", name: "Item A2", parentId: "a", value: 60 },
+  { id: "b1", name: "Item B1", parentId: "b", value: 80 }
+]);
+```
+
+## Common configuration
+
+### Node colors
+```js
+// From color set (automatic)
+series.get("colors").set("colors", [
+  am5.color(0x095256), am5.color(0x087f8c),
+  am5.color(0x5aaa95), am5.color(0x86a873)
+]);
+
+// Per-node via data + templateField
+// { name: "A", value: 100, nodeSettings: { fill: am5.color(0xff0000) } }
+// series.nodes.template.set("templateField", "nodeSettings");
+```
+
+### Drill-down (built-in for Treemap, Sunburst)
+Clicking a node zooms into its children. Configure with:
+```js
+series.set("topDepth", 1);       // hide root
+series.set("initialDepth", 2);   // initial visible depth
+series.set("downDepth", 1);      // how many levels to reveal on drill-down
+```
+
+### Breadcrumbs (for navigation)
+
+amCharts 5 provides a built-in `BreadcrumbBar` component for hierarchy navigation:
+
+```js
+const breadcrumbs = container.children.push(am5hierarchy.BreadcrumbBar.new(root, {
+  series: series
+}));
+```
+
+### Events on hierarchy nodes
+
+```js
+// Node click
+series.nodes.template.events.on("click", function(ev) {
+  var data = ev.target.dataItem.dataContext;
+  console.log("Clicked:", data.name);
+});
+
+// Data validated (after render)
+series.events.on("datavalidated", function() {
+  console.log("Hierarchy rendered");
+});
+```
+
+## Disposal
+
+```js
+root.dispose();
+```
+
+
+---
+
+# amCharts 5 Hierarchy Charts — Working Examples
+
+## Example 1: Treemap
+
+```html
+<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="UTF-8">
+  <title>Treemap</title>
+  <script src="https://cdn.amcharts.com/lib/5/index.js"></script>
+  <script src="https://cdn.amcharts.com/lib/5/hierarchy.js"></script>
+  <script src="https://cdn.amcharts.com/lib/5/themes/Animated.js"></script>
+  <style>#chartdiv { width: 100%; height: 500px; }</style>
+</head>
+<body>
+  <div id="chartdiv"></div>
+  <script>
+    var root = am5.Root.new("chartdiv");
+    root.setThemes([am5themes_Animated.new(root)]);
+
+    var container = root.container.children.push(am5.Container.new(root, {
+      width: am5.percent(100),
+      height: am5.percent(100),
+      layout: root.verticalLayout
+    }));
+
+    var series = container.children.push(am5hierarchy.Treemap.new(root, {
+      valueField: "value",
+      categoryField: "name",
+      childDataField: "children",
+      initialDepth: 2,
+      topDepth: 1,
+      layoutAlgorithm: "squarify",
+      nodePaddingOuter: 4,
+      nodePaddingInner: 2
+    }));
+
+    series.rectangles.template.setAll({
+      strokeWidth: 2,
+      stroke: am5.color(0xffffff),
+      cornerRadiusTL: 3, cornerRadiusTR: 3,
+      cornerRadiusBL: 3, cornerRadiusBR: 3
+    });
+
+    series.nodes.template.set("tooltipText", "{category}: {sum}");
+    series.labels.template.setAll({ text: "{category}", fontSize: 13 });
+
+    series.data.setAll([{
+      name: "Root",
+      children: [{
+        name: "Technology",
+        children: [
+          { name: "Smartphones", value: 500 },
+          { name: "Laptops", value: 380 },
+          { name: "Tablets", value: 220 },
+          { name: "Wearables", value: 150 }
+        ]
+      }, {
+        name: "Media",
+        children: [
+          { name: "Streaming", value: 350 },
+          { name: "Gaming", value: 280 },
+          { name: "Music", value: 180 },
+          { name: "News", value: 90 }
+        ]
+      }, {
+        name: "Finance",
+        children: [
+          { name: "Banking", value: 300 },
+          { name: "Insurance", value: 200 },
+          { name: "Investing", value: 250 }
+        ]
+      }]
+    }]);
+
+    series.appear(1000);
+  </script>
+</body>
+</html>
+```
+
+## Example 2: Force-directed tree
+
+```html
+<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="UTF-8">
+  <title>Force-Directed Tree</title>
+  <script src="https://cdn.amcharts.com/lib/5/index.js"></script>
+  <script src="https://cdn.amcharts.com/lib/5/hierarchy.js"></script>
+  <script src="https://cdn.amcharts.com/lib/5/themes/Animated.js"></script>
+  <style>#chartdiv { width: 100%; height: 600px; }</style>
+</head>
+<body>
+  <div id="chartdiv"></div>
+  <script>
+    var root = am5.Root.new("chartdiv");
+    root.setThemes([am5themes_Animated.new(root)]);
+
+    var container = root.container.children.push(am5.Container.new(root, {
+      width: am5.percent(100),
+      height: am5.percent(100),
+      layout: root.verticalLayout
+    }));
+
+    var series = container.children.push(am5hierarchy.ForceDirected.new(root, {
+      valueField: "value",
+      categoryField: "name",
+      childDataField: "children",
+      minRadius: 15,
+      maxRadius: 60,
+      initialFrames: 200,
+      topDepth: 1,
+      centerStrength: 0.3,
+      manyBodyStrength: -10
+    }));
+
+    series.circles.template.setAll({
+      fillOpacity: 0.85,
+      strokeWidth: 2,
+      stroke: am5.color(0xffffff)
+    });
+
+    series.labels.template.setAll({
+      text: "{category}",
+      fill: am5.color(0xffffff),
+      fontSize: 11,
+      oversizedBehavior: "truncate",
+      maxWidth: 80
+    });
+
+    series.outerCircles.template.setAll({
+      strokeDasharray: [3, 3],
+      strokeOpacity: 0.3
+    });
+
+    series.nodes.template.set("tooltipText", "{category}: {value}");
+
+    series.data.setAll([{
+      name: "Team", value: 0,
+      children: [{
+        name: "Engineering", value: 0,
+        children: [
+          { name: "Frontend", value: 8 },
+          { name: "Backend", value: 12 },
+          { name: "DevOps", value: 5 },
+          { name: "QA", value: 4 }
+        ]
+      }, {
+        name: "Product", value: 0,
+        children: [
+          { name: "Design", value: 6 },
+          { name: "Research", value: 3 },
+          { name: "PM", value: 4 }
+        ]
+      }, {
+        name: "Business", value: 0,
+        children: [
+          { name: "Sales", value: 10 },
+          { name: "Marketing", value: 7 },
+          { name: "Support", value: 8 }
+        ]
+      }]
+    }]);
+
+    series.appear(1000);
+  </script>
+</body>
+</html>
+```
+
+## Example 3: Sunburst chart
+
+```html
+<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="UTF-8">
+  <title>Sunburst</title>
+  <script src="https://cdn.amcharts.com/lib/5/index.js"></script>
+  <script src="https://cdn.amcharts.com/lib/5/hierarchy.js"></script>
+  <script src="https://cdn.amcharts.com/lib/5/themes/Animated.js"></script>
+  <style>#chartdiv { width: 100%; height: 600px; }</style>
+</head>
+<body>
+  <div id="chartdiv"></div>
+  <script>
+    var root = am5.Root.new("chartdiv");
+    root.setThemes([am5themes_Animated.new(root)]);
+
+    var container = root.container.children.push(am5.Container.new(root, {
+      width: am5.percent(100),
+      height: am5.percent(100)
+    }));
+
+    var series = container.children.push(am5hierarchy.Sunburst.new(root, {
+      valueField: "value",
+      categoryField: "name",
+      childDataField: "children",
+      radius: am5.percent(95),
+      innerRadius: am5.percent(15)
+    }));
+
+    series.nodes.template.set("tooltipText", "{category}: {sum}");
+    series.labels.template.set("forceHidden", true);
+
+    series.data.setAll([{
+      name: "Revenue",
+      children: [{
+        name: "Products",
+        children: [
+          { name: "SaaS", value: 450 },
+          { name: "On-Premise", value: 120 },
+          { name: "Mobile", value: 200 }
+        ]
+      }, {
+        name: "Services",
+        children: [
+          { name: "Consulting", value: 180 },
+          { name: "Training", value: 80 },
+          { name: "Support", value: 160 }
+        ]
+      }, {
+        name: "Licensing",
+        children: [
+          { name: "Enterprise", value: 300 },
+          { name: "SMB", value: 150 }
+        ]
+      }]
+    }]);
+
+    series.appear(1000);
+  </script>
+</body>
+</html>
+```