apexcharts-skill 1.0.0

package/references/grid-charts.md

@@ -0,0 +1,198 @@
+# Grid Charts Reference — ApexCharts
+
+## Chart Types Covered
+
+- **Heatmap** (`'heatmap'`) — Color-coded grid cells representing data intensity
+- **Treemap** (`'treemap'`) — Nested rectangles with area proportional to value
+
+## Tree-Shakeable Import
+
+```js
+import ApexCharts from 'apexcharts/heatmap'   # heatmap only
+import ApexCharts from 'apexcharts/treemap'    # treemap only
+```
+
+---
+
+## Data Formats
+
+### Heatmap
+
+Each series is a row; each data point is a cell. The `y` value determines the color intensity.
+
+```js
+{
+  chart: { type: 'heatmap', height: 350 },
+  series: [
+    {
+      name: 'Monday',
+      data: [
+        { x: '9am', y: 20 },
+        { x: '10am', y: 45 },
+        { x: '11am', y: 80 },
+        { x: '12pm', y: 65 }
+      ]
+    },
+    {
+      name: 'Tuesday',
+      data: [
+        { x: '9am', y: 35 },
+        { x: '10am', y: 60 },
+        { x: '11am', y: 40 },
+        { x: '12pm', y: 55 }
+      ]
+    }
+  ]
+}
+```
+
+### Treemap
+
+Flat list of `{ x, y }` where `x` is the label and `y` is the value (determines area).
+
+```js
+{
+  chart: { type: 'treemap', height: 350 },
+  series: [{
+    data: [
+      { x: 'New York', y: 218 },
+      { x: 'Los Angeles', y: 149 },
+      { x: 'Chicago', y: 106 },
+      { x: 'Houston', y: 92 },
+      { x: 'Phoenix', y: 65 }
+    ]
+  }]
+}
+```
+
+### Treemap with Groups (multiple series)
+
+```js
+{
+  chart: { type: 'treemap', height: 350 },
+  series: [
+    {
+      name: 'Fruits',
+      data: [
+        { x: 'Apple', y: 100 },
+        { x: 'Banana', y: 80 },
+        { x: 'Orange', y: 60 }
+      ]
+    },
+    {
+      name: 'Vegetables',
+      data: [
+        { x: 'Carrot', y: 70 },
+        { x: 'Potato', y: 90 }
+      ]
+    }
+  ]
+}
+```
+
+---
+
+## Key plotOptions
+
+### Heatmap
+
+```js
+plotOptions: {
+  heatmap: {
+    radius: 0,                    // border radius of cells
+    enableShades: true,           // shade intensity based on value
+    shadeIntensity: 0.5,          // shade range (0-1)
+    distributed: false,           // different color per series
+
+    colorScale: {
+      ranges: [
+        { from: 0, to: 30, color: '#00A100', name: 'Low' },
+        { from: 31, to: 60, color: '#128FD9', name: 'Medium' },
+        { from: 61, to: 100, color: '#FFB200', name: 'High' }
+      ],
+      inverse: false,
+      min: undefined,             // override auto-detected min
+      max: undefined              // override auto-detected max
+    },
+
+    useFillColorAsStroke: false
+  }
+}
+```
+
+### Treemap
+
+```js
+plotOptions: {
+  treemap: {
+    enableShades: true,
+    shadeIntensity: 0.5,
+    distributed: false,            // true = different color per cell
+
+    colorScale: {
+      ranges: [
+        { from: 0, to: 50, color: '#CD363A' },
+        { from: 51, to: 100, color: '#52B12C' }
+      ]
+    },
+
+    useFillColorAsStroke: false
+  }
+}
+```
+
+---
+
+## Complete Working Example — Heatmap
+
+```html
+<div id="chart"></div>
+<script type="module">
+  import ApexCharts from 'apexcharts'
+
+  // Generate sample heatmap data
+  function generateData(count, range) {
+    const hours = ['9am', '10am', '11am', '12pm', '1pm', '2pm', '3pm', '4pm', '5pm']
+    return hours.slice(0, count).map(hour => ({
+      x: hour,
+      y: Math.floor(Math.random() * (range.max - range.min + 1)) + range.min
+    }))
+  }
+
+  const options = {
+    chart: { type: 'heatmap', height: 350 },
+    series: [
+      { name: 'Monday', data: generateData(9, { min: 0, max: 90 }) },
+      { name: 'Tuesday', data: generateData(9, { min: 0, max: 90 }) },
+      { name: 'Wednesday', data: generateData(9, { min: 0, max: 90 }) },
+      { name: 'Thursday', data: generateData(9, { min: 0, max: 90 }) },
+      { name: 'Friday', data: generateData(9, { min: 0, max: 90 }) }
+    ],
+    plotOptions: {
+      heatmap: {
+        colorScale: {
+          ranges: [
+            { from: 0, to: 30, color: '#00A100', name: 'Low' },
+            { from: 31, to: 60, color: '#128FD9', name: 'Medium' },
+            { from: 61, to: 90, color: '#FFB200', name: 'High' }
+          ]
+        }
+      }
+    },
+    dataLabels: { enabled: true },
+    title: { text: 'Office Activity Heatmap' }
+  }
+
+  const chart = new ApexCharts(document.querySelector('#chart'), options)
+  await chart.render()
+</script>
+```
+
+---
+
+## Family-Specific Pitfalls
+
+1. **Heatmap with simple numeric arrays** — `data: [10, 20, 30]` does NOT work. Each point must be `{ x, y }` where `y` is the intensity value.
+2. **Inconsistent x-values across heatmap series** — all series should have the same set of x-values to form a proper grid. Missing cells show as gaps.
+3. **Treemap with negative values** — treemap `y` values must be positive (they represent area). Negative values cause rendering issues.
+4. **Confusing heatmap `y` with position** — in heatmap data `{ x, y }`, the `y` is the VALUE (color intensity), NOT the y-axis position. The series `name` determines the row.

package/references/radar-charts.md

@@ -0,0 +1,97 @@
+# Radar Charts Reference — ApexCharts
+
+## Chart Types Covered
+
+- **Radar** (`'radar'`) — Spider/web chart comparing multiple variables across categories
+
+## Tree-Shakeable Import
+
+```js
+import ApexCharts from 'apexcharts/radar'
+// Registers: radar only
+```
+
+---
+
+## Data Format
+
+Radar charts use the axis-chart series format with simple numeric arrays. Categories define the spoke labels.
+
+```js
+{
+  chart: { type: 'radar', height: 350 },
+  series: [
+    { name: 'Player A', data: [80, 50, 30, 40, 100, 20] },
+    { name: 'Player B', data: [60, 70, 90, 50, 40, 60] }
+  ],
+  xaxis: {
+    categories: ['Speed', 'Strength', 'Agility', 'Endurance', 'Accuracy', 'Teamwork']
+  }
+}
+```
+
+**Important:** The number of values in each `data` array must match the number of `categories`.
+
+---
+
+## Key plotOptions
+
+```js
+plotOptions: {
+  radar: {
+    size: undefined,            // radar chart radius (auto-calculated if undefined)
+    offsetX: 0,
+    offsetY: 0,
+
+    polygons: {
+      strokeColors: '#e8e8e8',  // polygon border color
+      strokeWidth: 1,
+      connectorColors: '#e8e8e8', // spoke line color
+
+      fill: {
+        colors: undefined        // alternating fill colors for concentric rings
+        // e.g., ['#f8f8f8', '#fff'] for zebra striping
+      }
+    }
+  }
+}
+```
+
+---
+
+## Complete Working Example
+
+```html
+<div id="chart"></div>
+<script type="module">
+  import ApexCharts from 'apexcharts'
+
+  const options = {
+    chart: { type: 'radar', height: 400 },
+    series: [
+      { name: 'Budget', data: [80, 50, 30, 40, 100, 20] },
+      { name: 'Actual', data: [60, 70, 90, 50, 40, 60] }
+    ],
+    xaxis: {
+      categories: ['Marketing', 'Engineering', 'Sales', 'Support', 'R&D', 'Operations']
+    },
+    stroke: { width: 2 },
+    fill: { opacity: 0.2 },
+    markers: { size: 4 },
+    yaxis: { stepSize: 20 },
+    title: { text: 'Budget vs Actual Spend', align: 'center' }
+  }
+
+  const chart = new ApexCharts(document.querySelector('#chart'), options)
+  await chart.render()
+</script>
+```
+
+---
+
+## Family-Specific Pitfalls
+
+1. **Missing `xaxis.categories`** — without categories, spokes have no labels. Always provide category names.
+2. **Data length mismatch** — each series `data` array must have exactly as many values as there are categories.
+3. **Confusing with polar area** — radar uses `series: [{ data: [...] }]` (axis format), polar area uses `series: [num]` (flat array). They look similar but have completely different data shapes.
+4. **Using `{ x, y }` format** — radar charts expect simple number arrays, NOT `{ x, y }` objects.

package/references/ssr.md

@@ -0,0 +1,201 @@
+# Server-Side Rendering (SSR) — ApexCharts
+
+## Overview
+
+ApexCharts supports SSR for generating chart SVGs on the server (Node.js) and hydrating them on the client for interactivity.
+
+## Import Paths
+
+```js
+// Server (Node.js) — includes renderToString, renderToHTML
+import ApexCharts from 'apexcharts/ssr'
+
+// Client (Browser) — for hydration after SSR
+import ApexCharts from 'apexcharts'          // auto-detects browser
+// or explicitly:
+import ApexCharts from 'apexcharts/client'
+```
+
+**Important:** The default `import ApexCharts from 'apexcharts'` uses Node.js conditional exports. In Node.js, it automatically resolves to the SSR bundle. In browsers (bundlers), it resolves to the client bundle.
+
+---
+
+## Server-Side API
+
+### renderToString(options)
+
+Returns a raw SVG string suitable for embedding:
+
+```js
+import ApexCharts from 'apexcharts/ssr'
+
+const svgString = await ApexCharts.renderToString({
+  chart: { type: 'line', height: 350, width: 600 },
+  series: [{ name: 'Sales', data: [30, 40, 35, 50] }],
+  xaxis: { categories: ['Q1', 'Q2', 'Q3', 'Q4'] }
+})
+
+// svgString is raw <svg>...</svg> markup
+```
+
+### renderToHTML(options)
+
+Returns an HTML string with a wrapper `<div>` containing the SVG, ready for hydration:
+
+```js
+const htmlString = await ApexCharts.renderToHTML({
+  chart: {
+    type: 'bar',
+    height: 350,
+    width: 600,
+    id: 'my-chart'   // id is important for hydration targeting
+  },
+  series: [{ data: [44, 55, 41, 67] }],
+  xaxis: { categories: ['A', 'B', 'C', 'D'] }
+})
+
+// htmlString is <div id="my-chart" data-apexcharts>...<svg>...</svg></div>
+```
+
+---
+
+## Client-Side Hydration
+
+After the server-rendered HTML is in the DOM, hydrate it to make it interactive:
+
+### hydrate(element)
+
+```js
+import ApexCharts from 'apexcharts'
+
+// Hydrate a specific chart element
+const chart = ApexCharts.hydrate(document.querySelector('#my-chart'))
+```
+
+### hydrateAll()
+
+```js
+// Hydrate all server-rendered charts on the page
+ApexCharts.hydrateAll()
+```
+
+### isHydrated(element)
+
+```js
+// Check if an element has already been hydrated
+if (!ApexCharts.isHydrated(el)) {
+  ApexCharts.hydrate(el)
+}
+```
+
+---
+
+## Full SSR + Hydration Example
+
+### Server (Node.js / Express)
+
+```js
+import express from 'express'
+import ApexCharts from 'apexcharts/ssr'
+
+const app = express()
+
+app.get('/', async (req, res) => {
+  const chartHTML = await ApexCharts.renderToHTML({
+    chart: { type: 'line', height: 350, width: 600, id: 'sales-chart' },
+    series: [{ name: 'Sales', data: [30, 40, 35, 50, 49, 60] }],
+    xaxis: { categories: ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun'] }
+  })
+
+  res.send(`
+    <!DOCTYPE html>
+    <html>
+    <head><title>Chart</title></head>
+    <body>
+      ${chartHTML}
+      <script type="module">
+        import ApexCharts from '/node_modules/apexcharts/dist/apexcharts.esm.js'
+        ApexCharts.hydrateAll()
+      </script>
+    </body>
+    </html>
+  `)
+})
+
+app.listen(3000)
+```
+
+---
+
+## SSR with Frameworks
+
+### Next.js (React)
+
+```jsx
+// app/page.js (Server Component)
+import ApexCharts from 'apexcharts/ssr'
+
+export default async function Page() {
+  const chartHTML = await ApexCharts.renderToHTML({
+    chart: { type: 'line', height: 350, id: 'my-chart' },
+    series: [{ data: [10, 20, 30] }],
+    xaxis: { categories: ['A', 'B', 'C'] }
+  })
+
+  return (
+    <>
+      <div dangerouslySetInnerHTML={{ __html: chartHTML }} />
+      <HydrateCharts />
+    </>
+  )
+}
+
+// components/HydrateCharts.js (Client Component)
+'use client'
+import { useEffect } from 'react'
+
+export default function HydrateCharts() {
+  useEffect(() => {
+    import('apexcharts').then(({ default: ApexCharts }) => {
+      ApexCharts.hydrateAll()
+    })
+  }, [])
+  return null
+}
+```
+
+### Nuxt 3 (Vue)
+
+```vue
+<!-- pages/index.vue -->
+<template>
+  <div v-html="chartHTML" />
+</template>
+
+<script setup>
+// Server-side
+const chartHTML = await useAsyncData('chart', async () => {
+  const ApexCharts = (await import('apexcharts/ssr')).default
+  return await ApexCharts.renderToHTML({
+    chart: { type: 'bar', height: 350, id: 'my-chart' },
+    series: [{ data: [44, 55, 41] }],
+    xaxis: { categories: ['A', 'B', 'C'] }
+  })
+})
+
+// Client-side hydration
+onMounted(async () => {
+  const ApexCharts = (await import('apexcharts')).default
+  ApexCharts.hydrateAll()
+})
+</script>
+```
+
+---
+
+## Common Pitfalls
+
+1. **Using `apexcharts` in Node.js without SSR methods** — the default export auto-resolves based on environment, but `renderToString` is only available via `apexcharts/ssr`.
+2. **Forgetting to hydrate on the client** — server-rendered charts are static SVGs. Without `hydrate()`, they have no interactivity (no tooltips, zoom, click events).
+3. **Missing `chart.width`** — SSR has no DOM to measure container width. Always provide explicit `width` for server rendering.
+4. **Hydrating before DOM is ready** — call `hydrate()` after the server-rendered HTML is in the DOM (use `onMounted`, `useEffect`, or `DOMContentLoaded`).

package/references/tree-shaking.md

@@ -0,0 +1,154 @@
+# Tree-Shaking & Bundle Optimization — ApexCharts
+
+## Overview
+
+ApexCharts supports three import strategies with different bundle sizes:
+
+| Strategy | Import | Includes |
+|---|---|---|
+| Full bundle | `import ApexCharts from 'apexcharts'` | All 16 chart types + all features |
+| Per-type entry | `import ApexCharts from 'apexcharts/line'` | Specific chart family + core (no optional features) |
+| Bare core | `import ApexCharts from 'apexcharts/core'` | Core class only — must manually register everything |
+
+---
+
+## Per-Type Entry Points
+
+Each entry point registers a family of related chart types:
+
+| Entry Point | Chart Types Registered |
+|---|---|
+| `apexcharts/line` | line, area, scatter, bubble, rangeArea |
+| `apexcharts/area` | same as /line |
+| `apexcharts/scatter` | same as /line |
+| `apexcharts/bubble` | same as /line |
+| `apexcharts/rangeArea` | same as /line |
+| `apexcharts/bar` | bar, column, rangeBar |
+| `apexcharts/column` | same as /bar |
+| `apexcharts/rangeBar` | same as /bar |
+| `apexcharts/candlestick` | candlestick, boxPlot |
+| `apexcharts/boxPlot` | same as /candlestick |
+| `apexcharts/pie` | pie, donut, polarArea |
+| `apexcharts/donut` | same as /pie |
+| `apexcharts/polarArea` | same as /pie |
+| `apexcharts/radialBar` | radialBar |
+| `apexcharts/radar` | radar |
+| `apexcharts/heatmap` | heatmap |
+| `apexcharts/treemap` | treemap |
+
+### Using Multiple Chart Types
+
+```js
+// Import multiple entry points for a mixed chart
+import ApexCharts from 'apexcharts/line'
+import 'apexcharts/bar'   // side-effect: registers bar types onto the same class
+```
+
+---
+
+## Optional Features
+
+Features are optional modules that add functionality. When using per-type entries or core, features must be explicitly imported.
+
+| Feature | Import | What It Adds |
+|---|---|---|
+| Legend | `import 'apexcharts/features/legend'` | Interactive legend component |
+| Toolbar | `import 'apexcharts/features/toolbar'` | Zoom, pan, download buttons |
+| Annotations | `import 'apexcharts/features/annotations'` | X/Y/point/text/image annotations |
+| Exports | `import 'apexcharts/features/exports'` | `dataURI()`, `getSvgString()`, `exportToCSV()` |
+| Keyboard | `import 'apexcharts/features/keyboard'` | Keyboard navigation (accessibility) |
+| All | `import 'apexcharts/features/all'` | All of the above |
+
+**Important:** Tooltip is always included in core — it cannot be tree-shaken.
+
+### What Happens If You Forget a Feature
+
+Features fail **silently**. If you use a per-type entry without importing legend:
+- No legend appears, no error thrown
+- `chart.toolbar` is undefined, toolbar doesn't render
+- `addXaxisAnnotation()` does nothing
+- `dataURI()` / `exportToCSV()` throw because the feature isn't registered
+
+---
+
+## Bare Core Usage
+
+For maximum control, import core and register everything manually:
+
+```js
+import ApexCharts from 'apexcharts/core'
+
+// Register chart types manually
+import { Line } from 'apexcharts/src/charts/Line.js'
+ApexCharts.use({ line: Line, area: Line })
+
+// Register features manually
+import { Legend } from 'apexcharts/src/modules/legend/Legend.js'
+ApexCharts.registerFeatures({ legend: Legend })
+```
+
+This approach is rarely needed — per-type entries with feature imports cover most use cases.
+
+---
+
+## Example: Minimal Line Chart Bundle
+
+```js
+import ApexCharts from 'apexcharts/line'
+import 'apexcharts/features/legend'
+import 'apexcharts/features/toolbar'
+
+const chart = new ApexCharts(el, {
+  chart: { type: 'line', height: 350 },
+  series: [{ data: [10, 20, 30] }],
+  xaxis: { categories: ['A', 'B', 'C'] }
+})
+await chart.render()
+```
+
+## Example: Mixed Chart (Line + Bar)
+
+```js
+import ApexCharts from 'apexcharts/line'
+import 'apexcharts/bar'
+import 'apexcharts/features/legend'
+
+const chart = new ApexCharts(el, {
+  chart: { type: 'line', height: 350 },
+  series: [
+    { name: 'Revenue', type: 'column', data: [44, 55, 57] },
+    { name: 'Profit', type: 'line', data: [15, 25, 35] }
+  ],
+  xaxis: { categories: ['Q1', 'Q2', 'Q3'] }
+})
+await chart.render()
+```
+
+---
+
+## Vite Configuration
+
+When using Vite with tree-shaking entries, configure `optimizeDeps` to prevent duplicate bundles:
+
+```js
+// vite.config.js
+export default {
+  optimizeDeps: {
+    include: [
+      'apexcharts/line',
+      'apexcharts/features/legend',
+      'apexcharts/features/toolbar'
+      // Add all apexcharts entries you use
+    ]
+  }
+}
+```
+
+---
+
+## Common Pitfalls
+
+1. **Missing feature imports** — features fail silently. If legend/toolbar/annotations don't appear, check imports.
+2. **Importing `apexcharts` AND `apexcharts/line`** — creates duplicate bundles. Use one strategy.
+3. **Vite duplicate bundle issue** — without `optimizeDeps.include`, Vite may bundle ApexCharts twice.
+4. **Calling `dataURI()` without exports feature** — throws an error. Import `apexcharts/features/exports` first.