@amcharts/amcharts5-mcp 1.0.0

package/amcharts5-skill/amcharts5-skill/references/ui-elements.md

@@ -0,0 +1,393 @@
+# UI Elements — Buttons, Sliders, Steppers, and More
+
+Docs: https://www.amcharts.com/docs/v5/concepts/common-elements/
+
+amCharts 5 provides built-in interactive UI widgets in the core package. **Prefer these over HTML elements** when building interactive controls, unless the user instructs otherwise.
+
+## Imports
+
+All UI elements are in the core package (`am5`) except ColorPicker.
+
+### CDN / script tags
+```html
+<script src="https://cdn.amcharts.com/lib/5/index.js"></script>
+<!-- ColorPicker only: -->
+<script src="https://cdn.amcharts.com/lib/5/plugins/colorPicker.js"></script>
+```
+
+### ES modules
+```ts
+import * as am5 from "@amcharts/amcharts5";
+// ColorPicker only:
+import * as am5plugins_colorPicker from "@amcharts/amcharts5/plugins/colorPicker";
+```
+
+---
+
+## Button
+
+A clickable button with label, icon, and background. Supports hover, down, and active states.
+
+```js
+var button = container.children.push(am5.Button.new(root, {
+  label: am5.Label.new(root, {
+    text: "Click me",
+    fontSize: 14,
+    paddingTop: 5,
+    paddingRight: 10,
+    paddingBottom: 5,
+    paddingLeft: 10
+  })
+}));
+
+button.events.on("click", function(ev) {
+  console.log("Button clicked!");
+});
+```
+
+### Button with icon
+
+```js
+var button = container.children.push(am5.Button.new(root, {
+  icon: am5.Graphics.new(root, {
+    fill: am5.color(0xffffff),
+    svgPath: "M11,5 L9,5 L9,9 L5,9 L5,11 L9,11 L9,15 L11,15 L11,11 L15,11 L15,9 L11,9 Z"
+  }),
+  label: am5.Label.new(root, { text: "Add" })
+}));
+```
+
+### Button background styling
+
+```js
+button.get("background").setAll({
+  fill: am5.color(0x297373),
+  fillOpacity: 0.9,
+  cornerRadiusTL: 5,
+  cornerRadiusTR: 5,
+  cornerRadiusBR: 5,
+  cornerRadiusBL: 5
+});
+
+button.get("background").states.create("hover", {
+  fill: am5.color(0x3a9a9a)
+});
+
+button.get("background").states.create("down", {
+  fill: am5.color(0x1a5555)
+});
+```
+
+### Togglable button
+
+```js
+var button = container.children.push(am5.Button.new(root, {
+  togglable: true,
+  label: am5.Label.new(root, { text: "Toggle" })
+}));
+
+// Check active state
+button.events.on("click", function(ev) {
+  var isActive = ev.target.isActive();
+  console.log("Active:", isActive);
+});
+```
+
+---
+
+## Slider
+
+A single-value slider control. Values range from 0 to 1 (relative positions).
+
+```js
+var slider = container.children.push(am5.Slider.new(root, {
+  orientation: "horizontal",  // or "vertical"
+  start: 0.5,                // initial position (0-1)
+  width: am5.percent(80),
+  centerX: am5.percent(50),
+  x: am5.percent(50)
+}));
+
+slider.events.on("rangechanged", function(ev) {
+  // ev.start = current position (0-1)
+  var value = ev.start;
+  console.log("Slider value:", value);
+});
+```
+
+### Converting slider 0-1 to a custom range
+
+```js
+// Map 0-1 to 0-100
+slider.events.on("rangechanged", function(ev) {
+  var mappedValue = Math.round(ev.start * 100);
+  label.set("text", mappedValue + "%");
+});
+
+// Map 0-1 to 20-200
+slider.events.on("rangechanged", function(ev) {
+  var min = 20, max = 200;
+  var mappedValue = min + ev.start * (max - min);
+});
+```
+
+### Styling the slider
+
+```js
+// Style the thumb (draggable part)
+slider.thumb.setAll({
+  fill: am5.color(0x297373),
+  width: 20,
+  height: 20
+});
+
+// Style the start grip
+slider.startGrip.setAll({
+  visible: false  // hide if not needed
+});
+```
+
+---
+
+## Scrollbar
+
+A two-grip range selector for selecting a range within data.
+
+```js
+// Standalone scrollbar
+var scrollbar = container.children.push(am5.Scrollbar.new(root, {
+  orientation: "horizontal",
+  start: 0.2,   // initial range start
+  end: 0.8      // initial range end
+}));
+
+scrollbar.events.on("rangechanged", function(ev) {
+  console.log("Range:", ev.start, "-", ev.end);
+});
+```
+
+### On XY charts
+
+```js
+// Add scrollbar to chart
+chart.set("scrollbarX", am5.Scrollbar.new(root, {
+  orientation: "horizontal"
+}));
+
+// Scrollbar with miniature chart preview
+chart.set("scrollbarX", am5xy.XYChartScrollbar.new(root, {
+  orientation: "horizontal",
+  height: 50
+}));
+```
+
+### Styling
+
+```js
+var scrollbar = chart.get("scrollbarX");
+scrollbar.thumb.setAll({ fill: am5.color(0x550000), fillOpacity: 0.1 });
+scrollbar.startGrip.set("scale", 0.7);
+scrollbar.endGrip.set("scale", 0.7);
+```
+
+---
+
+## NumericStepper
+
+An interactive number input with increment/decrement buttons.
+
+```js
+var stepper = container.children.push(am5.NumericStepper.new(root, {
+  value: 10
+}));
+
+// Read value
+var val = stepper.get("value");
+
+// Set value programmatically
+stepper.set("value", 25);
+
+// Listen for changes
+stepper.on("value", function(value) {
+  console.log("New value:", value);
+});
+```
+
+---
+
+## ProgressPie
+
+A circular progress indicator shaped as a pie/donut.
+
+```js
+var progress = container.children.push(am5.ProgressPie.new(root, {
+  radius: am5.percent(80),
+  innerRadius: am5.percent(60),
+  value: 65,
+  numberFormat: "#'%'"
+}));
+
+// Animate value change
+progress.animate({
+  key: "value",
+  to: 100,
+  duration: 2000
+});
+
+// Customize appearance
+progress.slice.setAll({ fill: am5.color(0x297373) });
+progress.backgroundSlice.setAll({ fill: am5.color(0xdddddd) });
+```
+
+---
+
+## SpriteResizer
+
+Adds drag-to-resize handles to any sprite.
+
+```js
+var targetSprite = container.children.push(am5.Graphics.new(root, {
+  fill: am5.color(0x297373),
+  draw: function(display) {
+    display.drawRect(0, 0, 200, 100);
+  }
+}));
+
+var resizer = container.children.push(am5.SpriteResizer.new(root, {
+  sprite: targetSprite
+}));
+```
+
+---
+
+## EditableLabel
+
+A label that becomes an editable text field when clicked.
+
+```js
+var label = container.children.push(am5.EditableLabel.new(root, {
+  text: "Click to edit",
+  editOn: "click",       // "click" | "dblclick" | "rightclick" | "none"
+  multiLine: false,
+  fontSize: 16,
+  fill: am5.color(0x000000)
+}));
+```
+
+---
+
+## Modal
+
+An HTML overlay dialog.
+
+```js
+var modal = am5.Modal.new(root, {
+  content: "<h2>Notice</h2><p>Chart data is loading...</p>"
+});
+
+modal.open();
+
+modal.events.on("closed", function() {
+  console.log("Modal closed");
+});
+
+// Close programmatically
+modal.close();
+```
+
+---
+
+## ColorPicker
+
+**Requires** `plugins/colorPicker.js` loaded before use.
+
+```js
+var picker = container.children.push(
+  am5plugins_colorPicker.ColorPicker.new(root, {
+    color: am5.color(0xff0000),
+    colorOpacity: 1
+  })
+);
+
+picker.events.on("colorchanged", function(ev) {
+  console.log("New color:", ev.color);
+  console.log("Opacity:", ev.colorOpacity);
+});
+```
+
+---
+
+## Layout examples
+
+### Vertical layout — chart with controls below
+
+```js
+var outerContainer = root.container.children.push(am5.Container.new(root, {
+  width: am5.percent(100),
+  height: am5.percent(100),
+  layout: root.verticalLayout
+}));
+
+// Chart takes most space
+var chart = outerContainer.children.push(am5xy.XYChart.new(root, {
+  width: am5.percent(100),
+  height: am5.percent(80)
+}));
+
+// Controls row below
+var controlsRow = outerContainer.children.push(am5.Container.new(root, {
+  width: am5.percent(100),
+  height: am5.percent(20),
+  layout: root.horizontalLayout,
+  paddingTop: 10
+}));
+
+controlsRow.children.push(am5.Slider.new(root, {
+  orientation: "horizontal",
+  width: am5.percent(60)
+}));
+
+controlsRow.children.push(am5.Button.new(root, {
+  label: am5.Label.new(root, { text: "Reset" })
+}));
+```
+
+### Grid layout — dashboard with multiple charts
+
+```js
+var grid = root.container.children.push(am5.Container.new(root, {
+  width: am5.percent(100),
+  height: am5.percent(100),
+  layout: am5.GridLayout.new(root, { maxColumns: 2, fixedWidthGrid: true })
+}));
+
+// Each child fills one grid cell
+var chart1Container = grid.children.push(am5.Container.new(root, {
+  width: am5.percent(100),
+  height: 300
+}));
+var chart2Container = grid.children.push(am5.Container.new(root, {
+  width: am5.percent(100),
+  height: 300
+}));
+```
+
+### Horizontal layout — legend + chart side by side
+
+```js
+var row = root.container.children.push(am5.Container.new(root, {
+  width: am5.percent(100),
+  height: am5.percent(100),
+  layout: root.horizontalLayout
+}));
+
+var legend = row.children.push(am5.Legend.new(root, {
+  width: 200,
+  layout: root.verticalLayout
+}));
+
+var chart = row.children.push(am5xy.XYChart.new(root, {
+  width: am5.percent(100),
+  height: am5.percent(100)
+}));
+```