apexcharts-skill 1.0.0

package/references/circular-charts.md

@@ -0,0 +1,218 @@
+# Circular Charts Reference — ApexCharts
+
+## Chart Types Covered
+
+- **Pie** (`'pie'`) — Standard pie chart
+- **Donut** (`'donut'`) — Pie chart with hollow center
+- **Polar Area** (`'polarArea'`) — Radial segments with equal angles, varying radius
+- **Radial Bar** (`'radialBar'`) — Circular progress/gauge chart
+
+## Tree-Shakeable Import
+
+```js
+import ApexCharts from 'apexcharts/pie'
+// Registers: pie, donut, polarArea
+// Aliases: apexcharts/donut, apexcharts/polarArea
+
+import ApexCharts from 'apexcharts/radialBar'
+// Registers: radialBar (separate entry point)
+```
+
+---
+
+## Data Format
+
+**The canonical format for circular charts is a flat number array for `series` paired with a `labels` array.** The x/y object format used by axis charts also works (ApexCharts normalizes it by extracting `y` as the value and `x` as the label), but it is not recommended — prefer the flat array form for clarity and predictability.
+
+### Pie / Donut / Polar Area
+
+```js
+{
+  chart: { type: 'pie', height: 350 },  // or 'donut' or 'polarArea'
+  series: [44, 55, 13, 43, 22],
+  labels: ['Team A', 'Team B', 'Team C', 'Team D', 'Team E']
+}
+```
+
+### Radial Bar (values 0–100)
+
+```js
+{
+  chart: { type: 'radialBar', height: 350 },
+  series: [76, 67, 61, 90],
+  labels: ['Apples', 'Oranges', 'Bananas', 'Berries']
+}
+```
+
+**Important:** RadialBar values represent percentages (0–100). Values above 100 will overflow the track.
+
+---
+
+## Key plotOptions
+
+### Pie / Donut
+
+```js
+plotOptions: {
+  pie: {
+    startAngle: 0,
+    endAngle: 360,
+    expandOnClick: true,       // expand slice on click
+    offsetX: 0,
+    offsetY: 0,
+
+    customScale: 1,            // scale the pie (0.5 = half size)
+
+    dataLabels: {
+      offset: 0,               // move labels away from center
+      minAngleToShowLabel: 10   // hide labels on tiny slices
+    },
+
+    donut: {
+      size: '65%',              // donut hole size (percentage string)
+      background: 'transparent',
+
+      labels: {
+        show: true,             // show center labels
+        name: {
+          show: true,
+          fontSize: '22px',
+          fontWeight: 600,
+          offsetY: -10
+        },
+        value: {
+          show: true,
+          fontSize: '16px',
+          formatter: (val) => val   // format the numeric value
+        },
+        total: {
+          show: true,
+          label: 'Total',
+          formatter: (w) => {
+            // w.globals.seriesTotals is array of values
+            return w.globals.seriesTotals.reduce((a, b) => a + b, 0)
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+### Radial Bar
+
+```js
+plotOptions: {
+  radialBar: {
+    startAngle: -135,
+    endAngle: 135,
+
+    hollow: {
+      size: '70%',              // size of the hollow center
+      background: 'transparent'
+    },
+
+    track: {
+      show: true,
+      background: '#f2f2f2',    // track background color
+      strokeWidth: '97%',
+      margin: 5                 // margin between tracks
+    },
+
+    dataLabels: {
+      name: {
+        show: true,
+        fontSize: '16px'
+      },
+      value: {
+        show: true,
+        fontSize: '14px',
+        formatter: (val) => `${val}%`
+      },
+      total: {
+        show: true,
+        label: 'Total',
+        formatter: (w) => {
+          const total = w.globals.seriesTotals.reduce((a, b) => a + b, 0)
+          return `${(total / w.globals.series.length).toFixed(1)}%`
+        }
+      }
+    }
+  }
+}
+```
+
+### Polar Area
+
+```js
+plotOptions: {
+  polarArea: {
+    rings: {
+      strokeWidth: 1,
+      strokeColor: '#e8e8e8'
+    },
+    spokes: {
+      strokeWidth: 1,
+      connectorColors: '#e8e8e8'
+    }
+  }
+}
+```
+
+---
+
+## Complete Working Example — Donut with Center Label
+
+```html
+<div id="chart"></div>
+<script type="module">
+  import ApexCharts from 'apexcharts'
+
+  const options = {
+    chart: {
+      type: 'donut',
+      height: 350
+    },
+    series: [44, 55, 41, 17, 15],
+    labels: ['Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday'],
+    plotOptions: {
+      pie: {
+        donut: {
+          size: '65%',
+          labels: {
+            show: true,
+            name: { show: true },
+            value: {
+              show: true,
+              formatter: (val) => `${val} tasks`
+            },
+            total: {
+              show: true,
+              label: 'Total',
+              formatter: (w) => {
+                return w.globals.seriesTotals.reduce((a, b) => a + b, 0) + ' tasks'
+              }
+            }
+          }
+        }
+      }
+    },
+    legend: { position: 'bottom' },
+    title: { text: 'Tasks by Day', align: 'center' }
+  }
+
+  const chart = new ApexCharts(document.querySelector('#chart'), options)
+  await chart.render()
+</script>
+```
+
+---
+
+## Family-Specific Pitfalls
+
+1. **Using axis-chart series format** — `series: [{ name: 'A', data: [44, 55] }]` is WRONG for pie/donut. The x/y object form `series: [{ data: [{ x: 'A', y: 44 }] }]` works (ApexCharts normalizes it), but the canonical form is preferred: `series: [44, 55]` (flat array) + `labels: ['A', 'B']`.
+2. **RadialBar values above 100** — values represent percentages and will overflow. If you have raw values, calculate percentages first: `(value / max) * 100`.
+3. **Missing `labels` array** — without `labels`, pie/donut slices show as "undefined" in tooltips and legend.
+4. **Donut center labels not showing** — must set `plotOptions.pie.donut.labels.show: true` explicitly.
+5. **`total.formatter` signature** — receives `w` (the full chart config object), NOT a simple value. Access `w.globals.seriesTotals` for the array of current values.
+6. **Polar Area confused with Radar** — polar area uses `series: [num]` (flat), radar uses `series: [{ data: [num] }]` (axis format). They look similar but have different data shapes.

package/references/financial-charts.md

@@ -0,0 +1,157 @@
+# Financial Charts Reference — ApexCharts
+
+## Chart Types Covered
+
+- **Candlestick** (`'candlestick'`) — OHLC (Open, High, Low, Close) financial chart
+- **Box Plot** (`'boxPlot'`) — Statistical distribution chart showing min, Q1, median, Q3, max
+
+## Tree-Shakeable Import
+
+```js
+import ApexCharts from 'apexcharts/candlestick'
+// Registers: candlestick, boxPlot
+// Alias: apexcharts/boxPlot
+```
+
+---
+
+## Data Formats
+
+### Candlestick — OHLC
+
+The `y` value must be an array of exactly 4 numbers: `[Open, High, Low, Close]`
+
+```js
+{
+  chart: { type: 'candlestick', height: 350 },
+  series: [{
+    data: [
+      { x: new Date('2024-01-01').getTime(), y: [51.98, 56.29, 51.59, 53.85] },
+      { x: new Date('2024-01-02').getTime(), y: [53.66, 54.99, 51.35, 52.95] },
+      { x: new Date('2024-01-03').getTime(), y: [52.76, 57.35, 52.15, 57.03] }
+    ]
+  }],
+  xaxis: { type: 'datetime' }
+}
+```
+
+**Alternative 2D array formats:**
+
+```js
+// Nested: [x, [O, H, L, C]]
+data: [
+  [new Date('2024-01-01').getTime(), [51.98, 56.29, 51.59, 53.85]],
+  [new Date('2024-01-02').getTime(), [53.66, 54.99, 51.35, 52.95]]
+]
+
+// Flat: [x, O, H, L, C] (5 elements)
+data: [
+  [new Date('2024-01-01').getTime(), 51.98, 56.29, 51.59, 53.85],
+  [new Date('2024-01-02').getTime(), 53.66, 54.99, 51.35, 52.95]
+]
+```
+
+### Box Plot — Five-Number Summary
+
+The `y` value must be an array of exactly 5 numbers: `[min, Q1, median, Q3, max]`
+
+```js
+{
+  chart: { type: 'boxPlot', height: 350 },
+  series: [{
+    data: [
+      { x: 'Jan 2024', y: [54, 66, 69, 75, 88] },
+      { x: 'Feb 2024', y: [43, 65, 69, 76, 81] },
+      { x: 'Mar 2024', y: [31, 39, 45, 51, 59] }
+    ]
+  }]
+}
+```
+
+---
+
+## Key plotOptions
+
+### Candlestick Colors
+
+```js
+plotOptions: {
+  candlestick: {
+    colors: {
+      upward: '#00B746',     // color when Close > Open (bullish)
+      downward: '#EF403C'    // color when Close < Open (bearish)
+    },
+    wick: {
+      useFillColor: true     // wick color matches candle body
+    }
+  }
+}
+```
+
+### Box Plot Colors
+
+```js
+plotOptions: {
+  boxPlot: {
+    colors: {
+      upper: '#00E396',      // color for upper quartile
+      lower: '#008FFB'       // color for lower quartile
+    }
+  }
+}
+```
+
+---
+
+## Complete Working Example — Candlestick Chart
+
+```html
+<div id="chart"></div>
+<script type="module">
+  import ApexCharts from 'apexcharts'
+
+  const options = {
+    chart: {
+      type: 'candlestick',
+      height: 350
+    },
+    series: [{
+      name: 'AAPL',
+      data: [
+        { x: new Date('2024-01-02').getTime(), y: [185.09, 185.60, 183.66, 185.56] },
+        { x: new Date('2024-01-03').getTime(), y: [184.22, 185.88, 183.43, 184.25] },
+        { x: new Date('2024-01-04').getTime(), y: [182.15, 183.09, 180.88, 181.91] },
+        { x: new Date('2024-01-05').getTime(), y: [181.99, 182.76, 180.17, 181.18] },
+        { x: new Date('2024-01-08').getTime(), y: [181.79, 185.60, 181.32, 185.56] }
+      ]
+    }],
+    xaxis: { type: 'datetime' },
+    yaxis: {
+      tooltip: { enabled: true },
+      labels: { formatter: (val) => `$${val.toFixed(2)}` }
+    },
+    plotOptions: {
+      candlestick: {
+        colors: {
+          upward: '#26a69a',
+          downward: '#ef5350'
+        }
+      }
+    },
+    title: { text: 'AAPL Stock Price', align: 'left' }
+  }
+
+  const chart = new ApexCharts(document.querySelector('#chart'), options)
+  await chart.render()
+</script>
+```
+
+---
+
+## Family-Specific Pitfalls
+
+1. **Wrong OHLC order** — must be `[Open, High, Low, Close]`, not `[High, Low, Open, Close]` or any other order.
+2. **Box Plot with wrong array length** — must be exactly 5 values `[min, Q1, median, Q3, max]`. Fewer or more values cause rendering errors.
+3. **Using simple numeric array** — `data: [10, 20, 30]` does NOT work for candlestick/boxPlot. Each point requires an array in `y`.
+4. **Missing `xaxis.type: 'datetime'`** — candlestick charts with date x-values need `xaxis: { type: 'datetime' }` to format dates correctly.
+5. **Confusing candlestick with boxPlot** — candlestick is 4 values (OHLC), boxPlot is 5 values (five-number summary). They share the same entry point but have different data shapes.

package/references/framework-wrappers.md

@@ -0,0 +1,251 @@
+# Framework Integration — ApexCharts
+
+## Official Wrappers
+
+| Framework | Package | Install |
+|---|---|---|
+| React | `react-apexcharts` | `npm install react-apexcharts apexcharts` |
+| Vue 3 | `vue3-apexcharts` | `npm install vue3-apexcharts apexcharts` |
+| Angular | `ng-apexcharts` | `npm install ng-apexcharts apexcharts` |
+
+**Important:** All wrappers require `apexcharts` as a peer dependency. Install both packages.
+
+---
+
+## React
+
+### Basic Usage
+
+```jsx
+import React from 'react'
+import Chart from 'react-apexcharts'
+
+function MyChart() {
+  const options = {
+    chart: { type: 'line' },
+    xaxis: { categories: ['Jan', 'Feb', 'Mar', 'Apr'] }
+  }
+
+  const series = [{
+    name: 'Sales',
+    data: [30, 40, 35, 50]
+  }]
+
+  return <Chart options={options} series={series} type="line" height={350} />
+}
+```
+
+### Updating Data
+
+Pass new `series` or `options` props — the wrapper handles `updateSeries` / `updateOptions` internally:
+
+```jsx
+function LiveChart() {
+  const [series, setSeries] = useState([{ data: [30, 40, 35] }])
+
+  const addData = () => {
+    setSeries([{ data: [...series[0].data, Math.random() * 100] }])
+  }
+
+  return (
+    <>
+      <Chart options={options} series={series} type="line" height={350} />
+      <button onClick={addData}>Add Point</button>
+    </>
+  )
+}
+```
+
+### Common React Pitfall: Cleanup
+
+The wrapper handles `destroy()` automatically on unmount. But if you use the vanilla API directly:
+
+```jsx
+// ❌ WRONG — no cleanup
+useEffect(() => {
+  const chart = new ApexCharts(ref.current, options)
+  chart.render()
+}, [])
+
+// ✅ CORRECT — destroy on unmount
+useEffect(() => {
+  const chart = new ApexCharts(ref.current, options)
+  chart.render()
+  return () => chart.destroy()
+}, [])
+```
+
+### SSR with Next.js
+
+For Next.js, use dynamic import to avoid SSR issues with the wrapper:
+
+```jsx
+import dynamic from 'next/dynamic'
+
+const Chart = dynamic(() => import('react-apexcharts'), { ssr: false })
+
+export default function Page() {
+  return <Chart options={options} series={series} type="line" height={350} />
+}
+```
+
+Or use the native SSR approach (see `references/ssr.md`).
+
+---
+
+## Vue 3
+
+### Setup
+
+```js
+// main.js
+import { createApp } from 'vue'
+import VueApexCharts from 'vue3-apexcharts'
+import App from './App.vue'
+
+const app = createApp(App)
+app.use(VueApexCharts)
+app.mount('#app')
+```
+
+### Basic Usage
+
+```vue
+<template>
+  <apexchart
+    type="bar"
+    height="350"
+    :options="chartOptions"
+    :series="series"
+  />
+</template>
+
+<script setup>
+import { ref } from 'vue'
+
+const chartOptions = ref({
+  chart: { type: 'bar' },
+  xaxis: { categories: ['Jan', 'Feb', 'Mar'] },
+  plotOptions: { bar: { horizontal: false } }
+})
+
+const series = ref([
+  { name: 'Revenue', data: [44, 55, 41] }
+])
+</script>
+```
+
+### Updating Data
+
+The wrapper watches for changes to `series` and `options` props and calls the appropriate update methods:
+
+```vue
+<script setup>
+const series = ref([{ data: [44, 55, 41] }])
+
+function updateData() {
+  // Mutating the ref triggers re-render
+  series.value = [{ data: [10, 20, 30] }]
+}
+</script>
+```
+
+### Common Vue Pitfall: Reactive Config Mutation
+
+```js
+// ❌ WRONG — directly mutating deep config can miss reactivity
+chartOptions.value.xaxis.categories.push('Apr')
+
+// ✅ CORRECT — replace the whole object
+chartOptions.value = {
+  ...chartOptions.value,
+  xaxis: { categories: ['Jan', 'Feb', 'Mar', 'Apr'] }
+}
+```
+
+---
+
+## Angular
+
+### Setup
+
+```typescript
+// app.module.ts
+import { NgApexchartsModule } from 'ng-apexcharts'
+
+@NgModule({
+  imports: [NgApexchartsModule]
+})
+export class AppModule {}
+```
+
+### Basic Usage
+
+```typescript
+// chart.component.ts
+import { Component } from '@angular/core'
+
+@Component({
+  selector: 'app-chart',
+  template: `
+    <apx-chart
+      [series]="series"
+      [chart]="chartOptions"
+      [xaxis]="xaxis"
+    ></apx-chart>
+  `
+})
+export class ChartComponent {
+  chartOptions = { type: 'line' as const, height: 350 }
+  series = [{ name: 'Sales', data: [30, 40, 35, 50] }]
+  xaxis = { categories: ['Jan', 'Feb', 'Mar', 'Apr'] }
+}
+```
+
+### Updating Data
+
+```typescript
+updateChart() {
+  this.series = [{ name: 'Sales', data: [10, 20, 30, 40] }]
+}
+```
+
+---
+
+## Vanilla JS (No Framework)
+
+```html
+<div id="chart"></div>
+
+<!-- CDN -->
+<script src="https://cdn.jsdelivr.net/npm/apexcharts"></script>
+
+<script>
+  const options = {
+    chart: { type: 'line', height: 350 },
+    series: [{ name: 'Sales', data: [30, 40, 35, 50] }],
+    xaxis: { categories: ['Q1', 'Q2', 'Q3', 'Q4'] }
+  }
+
+  const chart = new ApexCharts(document.querySelector('#chart'), options)
+  chart.render()
+</script>
+```
+
+### CDN Links
+
+```
+https://cdn.jsdelivr.net/npm/apexcharts
+https://cdn.jsdelivr.net/npm/apexcharts@5/dist/apexcharts.min.js
+https://unpkg.com/apexcharts
+```
+
+---
+
+## Common Framework Pitfalls
+
+1. **Missing peer dependency** — `react-apexcharts`, `vue3-apexcharts`, and `ng-apexcharts` all require `apexcharts` as a separate dependency.
+2. **SSR with wrapper components** — most wrappers access `window`/`document` and crash in SSR. Use dynamic imports with `{ ssr: false }` or the native SSR API.
+3. **Not destroying on unmount (vanilla API in React/Vue)** — causes memory leaks and duplicate charts. The official wrappers handle this automatically.
+4. **Mutating config objects in place (Vue)** — deep mutations may not trigger reactivity. Replace the entire object or use `ref` at the right level.
+5. **Rendering in hidden containers** — charts rendered in hidden tabs/modals have zero dimensions. Call `chart.updateOptions({})` or trigger a resize after showing the container.