apexcharts-skill 1.0.0

package/index.js

@@ -0,0 +1,47 @@
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+
+const packageRoot = dirname(fileURLToPath(import.meta.url));
+
+/** Absolute path to the package root (where SKILL.md lives). */
+export const packageDir = packageRoot;
+
+/** Absolute path to SKILL.md (the top-level skill index). */
+export const skillFile = join(packageRoot, 'SKILL.md');
+
+/** Absolute path to the references/ directory containing per-topic markdown docs. */
+export const referencesDir = join(packageRoot, 'references');
+
+/**
+ * Filenames of every reference doc shipped with this package, relative to
+ * `referencesDir`. Useful for iterating without scanning the filesystem.
+ */
+export const referenceFiles = [
+  'bar-charts.md',
+  'cartesian-charts.md',
+  'circular-charts.md',
+  'financial-charts.md',
+  'framework-wrappers.md',
+  'grid-charts.md',
+  'radar-charts.md',
+  'ssr.md',
+  'tree-shaking.md',
+];
+
+/** Resolve a reference file by its filename. Throws if not in the known list. */
+export function referencePath(filename) {
+  if (!referenceFiles.includes(filename)) {
+    throw new Error(
+      `Unknown reference file "${filename}". Known files: ${referenceFiles.join(', ')}`,
+    );
+  }
+  return join(referencesDir, filename);
+}
+
+export default {
+  packageDir,
+  skillFile,
+  referencesDir,
+  referenceFiles,
+  referencePath,
+};

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "apexcharts-skill",
+  "version": "1.0.0",
+  "description": "AI coding skill for ApexCharts.js — structured reference docs that help AI assistants (Claude, Cursor, Copilot, etc.) generate correct ApexCharts code.",
+  "keywords": [
+    "apexcharts",
+    "ai",
+    "skill",
+    "claude",
+    "cursor",
+    "copilot",
+    "charts",
+    "data-visualization",
+    "documentation",
+    "reference"
+  ],
+  "author": "ApexCharts <info@apexcharts.com>",
+  "license": "MIT",
+  "homepage": "https://github.com/apexcharts/apexcharts-skill#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/apexcharts/apexcharts-skill.git"
+  },
+  "bugs": {
+    "url": "https://github.com/apexcharts/apexcharts-skill/issues"
+  },
+  "type": "module",
+  "main": "index.js",
+  "exports": {
+    ".": "./index.js",
+    "./SKILL.md": "./SKILL.md",
+    "./references/*": "./references/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "index.js",
+    "SKILL.md",
+    "references"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/references/bar-charts.md

@@ -0,0 +1,244 @@
+# Bar Charts Reference — ApexCharts
+
+## Chart Types Covered
+
+- **Bar** (`'bar'`) — Horizontal bar chart (default orientation)
+- **Column** (`'bar'` + `plotOptions.bar.horizontal: false`) — Vertical bar/column chart
+- **Range Bar** (`'rangeBar'`) — Bars with start/end values (used for timelines, Gantt charts)
+
+## Tree-Shakeable Import
+
+```js
+import ApexCharts from 'apexcharts/bar'
+// Registers: bar, column, rangeBar
+// Aliases: apexcharts/column, apexcharts/rangeBar
+```
+
+---
+
+## Data Formats
+
+### Basic Bar / Column
+
+```js
+{
+  chart: { type: 'bar', height: 350 },
+  series: [{
+    name: 'Sales',
+    data: [44, 55, 41, 67, 22, 43]
+  }],
+  xaxis: {
+    categories: ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun']
+  },
+  plotOptions: {
+    bar: {
+      horizontal: true    // true = horizontal bars (default)
+                           // false = vertical columns
+    }
+  }
+}
+```
+
+### Grouped Bars (multiple series)
+
+```js
+{
+  chart: { type: 'bar', height: 350 },
+  series: [
+    { name: '2023', data: [44, 55, 41] },
+    { name: '2024', data: [53, 32, 33] }
+  ],
+  xaxis: { categories: ['Q1', 'Q2', 'Q3'] },
+  plotOptions: { bar: { horizontal: false } }
+}
+```
+
+### Stacked Bars
+
+```js
+{
+  chart: { type: 'bar', height: 350, stacked: true },
+  // stackType: '100%'  // uncomment for percentage stacking
+  series: [
+    { name: 'Product A', data: [44, 55, 41] },
+    { name: 'Product B', data: [13, 23, 20] },
+    { name: 'Product C', data: [11, 17, 15] }
+  ],
+  xaxis: { categories: ['2022', '2023', '2024'] },
+  plotOptions: { bar: { horizontal: false } }
+}
+```
+
+### Range Bar (start/end values)
+
+```js
+{
+  chart: { type: 'rangeBar', height: 350 },
+  series: [{
+    name: 'Salary Range',
+    data: [
+      { x: 'Engineering', y: [80000, 150000] },   // [start, end]
+      { x: 'Design', y: [60000, 120000] },
+      { x: 'Marketing', y: [50000, 110000] }
+    ]
+  }],
+  plotOptions: { bar: { horizontal: true } }
+}
+```
+
+### Timeline / Gantt Chart (Range Bar with dates)
+
+```js
+{
+  chart: { type: 'rangeBar', height: 350 },
+  series: [{
+    data: [
+      {
+        x: 'Design',
+        y: [new Date('2024-01-01').getTime(), new Date('2024-03-15').getTime()]
+      },
+      {
+        x: 'Development',
+        y: [new Date('2024-02-15').getTime(), new Date('2024-07-01').getTime()]
+      },
+      {
+        x: 'Testing',
+        y: [new Date('2024-06-01').getTime(), new Date('2024-08-01').getTime()]
+      }
+    ]
+  }],
+  plotOptions: {
+    bar: { horizontal: true }
+  },
+  xaxis: { type: 'datetime' }
+}
+```
+
+### Multi-Series Timeline (color-coded tasks)
+
+```js
+{
+  chart: { type: 'rangeBar', height: 350 },
+  series: [
+    {
+      name: 'Team A',
+      data: [
+        { x: 'Design', y: [new Date('2024-01-01').getTime(), new Date('2024-03-01').getTime()] },
+        { x: 'Code', y: [new Date('2024-03-01').getTime(), new Date('2024-06-01').getTime()] }
+      ]
+    },
+    {
+      name: 'Team B',
+      data: [
+        { x: 'Design', y: [new Date('2024-02-01').getTime(), new Date('2024-04-01').getTime()] },
+        { x: 'Test', y: [new Date('2024-04-01').getTime(), new Date('2024-07-01').getTime()] }
+      ]
+    }
+  ],
+  plotOptions: { bar: { horizontal: true } },
+  xaxis: { type: 'datetime' }
+}
+```
+
+---
+
+## Key plotOptions.bar Options
+
+```js
+plotOptions: {
+  bar: {
+    horizontal: true,         // true = horizontal bars, false = vertical columns
+    columnWidth: '70%',       // width of each column (string percentage)
+    barHeight: '70%',         // height of each bar when horizontal
+    distributed: false,       // true = different color per data point
+    borderRadius: 4,          // rounded corners (number or object)
+    borderRadiusApplication: 'end',  // 'end' | 'around'
+    borderRadiusWhenStacked: 'last', // 'all' | 'last'
+
+    dataLabels: {
+      position: 'top',        // 'top' | 'center' | 'bottom'
+      orientation: 'horizontal'  // 'horizontal' | 'vertical'
+    },
+
+    colors: {
+      ranges: [{
+        from: 0,
+        to: 50,
+        color: '#F15B46'       // conditional coloring by value range
+      }]
+    }
+  }
+}
+```
+
+### Goals / Target Markers
+
+```js
+series: [{
+  name: 'Actual',
+  data: [
+    {
+      x: 'Q1',
+      y: 400,
+      goals: [{
+        name: 'Target',
+        value: 500,
+        strokeWidth: 5,
+        strokeColor: '#775DD0'
+      }]
+    }
+  ]
+}]
+```
+
+---
+
+## Complete Working Example — Grouped Column Chart
+
+```html
+<div id="chart"></div>
+<script type="module">
+  import ApexCharts from 'apexcharts'
+
+  const options = {
+    chart: {
+      type: 'bar',
+      height: 350
+    },
+    series: [
+      { name: '2023', data: [44, 55, 57, 56, 61] },
+      { name: '2024', data: [76, 85, 101, 98, 87] }
+    ],
+    xaxis: {
+      categories: ['Feb', 'Mar', 'Apr', 'May', 'Jun']
+    },
+    plotOptions: {
+      bar: {
+        horizontal: false,
+        columnWidth: '55%',
+        borderRadius: 4
+      }
+    },
+    dataLabels: { enabled: false },
+    stroke: { show: true, width: 2, colors: ['transparent'] },
+    yaxis: { title: { text: 'Revenue ($K)' } },
+    fill: { opacity: 1 },
+    tooltip: {
+      y: { formatter: (val) => `$${val}K` }
+    }
+  }
+
+  const chart = new ApexCharts(document.querySelector('#chart'), options)
+  await chart.render()
+</script>
+```
+
+---
+
+## Family-Specific Pitfalls
+
+1. **Forgetting `plotOptions.bar.horizontal: false` for column charts** — ApexCharts defaults to horizontal bars. Set `horizontal: false` explicitly for vertical columns.
+2. **Stacking with `chart.stacked: true` but missing on bar type** — stacking only works on `type: 'bar'` (and `'area'`). It does NOT work on line, scatter, etc.
+3. **Range Bar with single value instead of array** — `y` must be `[start, end]`, not a single number.
+4. **Timeline without `xaxis.type: 'datetime'`** — date-based range bars need `xaxis: { type: 'datetime' }` to render correctly.
+5. **`distributed: true` with multiple series** — distributed coloring applies to each data point independently. With multiple series, each point gets a unique color which is usually not desired. Use `distributed: true` only with single-series charts.

package/references/cartesian-charts.md

@@ -0,0 +1,247 @@
+# Cartesian Charts Reference — ApexCharts
+
+## Chart Types Covered
+
+- **Line** (`'line'`) — Standard line chart connecting data points
+- **Area** (`'area'`) — Line chart with filled area below
+- **Scatter** (`'scatter'`) — Individual data points plotted by X/Y coordinates
+- **Bubble** (`'bubble'`) — Scatter with variable-size bubbles (requires z value)
+- **Range Area** (`'rangeArea'`) — Area chart showing a range between two values
+
+## Tree-Shakeable Import
+
+```js
+import ApexCharts from 'apexcharts/line'
+// Registers: line, area, scatter, bubble, rangeArea
+// Aliases: apexcharts/area, apexcharts/scatter, apexcharts/bubble, apexcharts/rangeArea
+```
+
+---
+
+## Data Formats (Detailed)
+
+### Simple Array (categories on x-axis)
+
+```js
+{
+  chart: { type: 'line', height: 350 },
+  series: [{
+    name: 'Sales',
+    data: [30, 40, 35, 50, 49, 60, 70]
+  }],
+  xaxis: {
+    categories: ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun']
+  }
+}
+```
+
+### XY Object Format (numeric or datetime x-axis)
+
+```js
+{
+  chart: { type: 'line', height: 350 },
+  series: [{
+    name: 'Sales',
+    data: [
+      { x: new Date('2024-01-01').getTime(), y: 30 },
+      { x: new Date('2024-02-01').getTime(), y: 40 },
+      { x: new Date('2024-03-01').getTime(), y: 35 }
+    ]
+  }],
+  xaxis: { type: 'datetime' }
+  // Do NOT use xaxis.categories with {x, y} data — categories are ignored
+}
+```
+
+### 2D Array Format (alternative to object format)
+
+```js
+series: [{
+  name: 'Sales',
+  data: [
+    [1704067200000, 30],  // [timestamp, value]
+    [1706745600000, 40],
+    [1709251200000, 35]
+  ]
+}]
+```
+
+### Missing Data Points
+
+Use `null` to create gaps in the line:
+```js
+series: [{ data: [10, 25, null, null, 50, 60] }]
+```
+
+### Scatter Chart
+
+Always use XY format:
+```js
+{
+  chart: { type: 'scatter', height: 350 },
+  series: [{
+    name: 'Sample A',
+    data: [
+      { x: 16.4, y: 5.4 },
+      { x: 21.7, y: 2 },
+      { x: 25.4, y: 3 }
+    ]
+  }],
+  xaxis: { type: 'numeric' }
+}
+```
+
+### Bubble Chart (z is required)
+
+```js
+{
+  chart: { type: 'bubble', height: 350 },
+  series: [{
+    name: 'Product A',
+    data: [
+      { x: 2020, y: 30, z: 10 },   // z = bubble size
+      { x: 2021, y: 40, z: 25 },
+      { x: 2022, y: 35, z: 15 }
+    ]
+  }],
+  xaxis: { type: 'numeric' }
+}
+```
+
+### Range Area
+
+```js
+{
+  chart: { type: 'rangeArea', height: 350 },
+  series: [{
+    name: 'Temperature Range',
+    data: [
+      { x: 'Jan', y: [-2, 10] },   // [low, high]
+      { x: 'Feb', y: [0, 12] },
+      { x: 'Mar', y: [3, 16] }
+    ]
+  }]
+}
+```
+
+---
+
+## Key Options
+
+### Stroke / Curve Types
+
+```js
+stroke: {
+  curve: 'smooth',       // 'smooth' | 'straight' | 'stepline' | 'linestep' | 'monotoneCubic'
+  width: 2,              // line thickness (number or array per series)
+  dashArray: 0            // 0 = solid, number = dashed (or array per series)
+}
+```
+
+### Markers
+
+```js
+markers: {
+  size: 5,                // 0 = hidden (default for line/area)
+  shape: 'circle',        // 'circle' | 'square' | 'diamond' | etc.
+  hover: { sizeOffset: 3 }
+}
+```
+
+### Area Fill
+
+```js
+fill: {
+  type: 'gradient',
+  gradient: {
+    shadeIntensity: 1,
+    opacityFrom: 0.7,
+    opacityTo: 0.2,
+    stops: [0, 90, 100]
+  }
+}
+```
+
+### Datetime X-Axis
+
+```js
+xaxis: {
+  type: 'datetime',
+  labels: {
+    datetimeUTC: false,    // false = local time, true = UTC
+    datetimeFormatter: {
+      year: 'yyyy',
+      month: "MMM 'yy",
+      day: 'dd MMM',
+      hour: 'HH:mm'
+    }
+  }
+}
+```
+
+### Forecast Data Points
+
+```js
+{
+  forecastDataPoints: {
+    count: 3,              // last N data points shown as forecast
+    fillOpacity: 0.5,
+    strokeWidth: 1,
+    dashArray: 4
+  }
+}
+```
+
+---
+
+## Complete Working Example — Line Chart with Datetime
+
+```html
+<div id="chart"></div>
+<script type="module">
+  import ApexCharts from 'apexcharts'
+
+  const options = {
+    chart: {
+      type: 'line',
+      height: 350,
+      zoom: { enabled: true }
+    },
+    series: [{
+      name: 'Page Views',
+      data: [
+        { x: new Date('2024-01-01').getTime(), y: 4500 },
+        { x: new Date('2024-02-01').getTime(), y: 5200 },
+        { x: new Date('2024-03-01').getTime(), y: 4800 },
+        { x: new Date('2024-04-01').getTime(), y: 6100 },
+        { x: new Date('2024-05-01').getTime(), y: 5900 },
+        { x: new Date('2024-06-01').getTime(), y: 7200 }
+      ]
+    }],
+    xaxis: { type: 'datetime' },
+    yaxis: {
+      title: { text: 'Views' },
+      labels: { formatter: (val) => val.toFixed(0) }
+    },
+    stroke: { curve: 'smooth', width: 3 },
+    title: { text: 'Monthly Page Views', align: 'left' },
+    tooltip: {
+      x: { format: 'MMM yyyy' },
+      y: { formatter: (val) => `${val.toLocaleString()} views` }
+    }
+  }
+
+  const chart = new ApexCharts(document.querySelector('#chart'), options)
+  await chart.render()
+</script>
+```
+
+---
+
+## Family-Specific Pitfalls
+
+1. **Bubble chart without z value** — renders with zero-size bubbles. Always provide `z` in data.
+2. **Using `xaxis.categories` with `{ x, y }` data** — categories are silently ignored when data contains x values. Choose one approach.
+3. **Datetime axis with string dates** — pass timestamps (`new Date(...).getTime()`) or `Date` objects, not raw strings like `'January 2024'`.
+4. **`stroke.curve: 'smooth'` on sparse data** — can produce visual artifacts. Use `'monotoneCubic'` for mathematically smoother interpolation.
+5. **Range Area with single value instead of array** — `y` must be `[low, high]`, not a single number.