apexcharts-skill 1.2.1 → 2.0.0

package/references/bar-charts.md

@@ -5,6 +5,8 @@
 - **Column** (`'bar'`) — Vertical column chart (the default for `type: 'bar'`)
 - **Bar** (`'bar'` + `plotOptions.bar.horizontal: true`) — Horizontal bar chart
 - **Range Bar** (`'rangeBar'`) — Bars with start/end values (used for timelines, Gantt charts)
+- **Funnel** (`'funnel'`, **new in v6**): Stage-by-stage drop-off chart
+- **Pyramid** (`'pyramid'`, **new in v6**): A funnel with the wide base at the bottom
 
 ## Tree-Shakeable Import
 
@@ -12,8 +14,11 @@
 import ApexCharts from 'apexcharts/bar'
 // Registers: bar, column, rangeBar
 // Aliases: apexcharts/column, apexcharts/rangeBar
+// Also covers funnel + pyramid (they normalize to the bar engine in v6)
 ```
 
+**v6 note:** `funnel` and `pyramid` are first-class `chart.type` aliases that render through the bar engine. Use them directly as `chart.type`; you do **not** need `plotOptions.bar.isFunnel`. `plotOptions.funnel` carries the funnel-specific shape options.
+
 ---
 
 ## Data Formats
@@ -140,6 +145,43 @@ import ApexCharts from 'apexcharts/bar'
 }
 ```
 
+### Funnel (v6)
+
+Values are a flat number array in the standard `[{ name, data }]` wrapper; stage labels go in `xaxis.categories`. Order values **largest → smallest**.
+
+```js
+{
+  chart: { type: 'funnel', height: 350 },
+  series: [{ name: 'Recruitment', data: [1380, 1100, 990, 880, 740, 548, 330, 200] }],
+  xaxis: { categories: ['Sourced', 'Screened', 'Assessed', 'HR', 'Technical', 'Verify', 'Offered', 'Hired'] },
+  plotOptions: {
+    // shape: 'rectangle' (default, centered rectangles) | 'trapezoid' (continuous sloped sides)
+    funnel: { shape: 'trapezoid', lastShape: 'flat' },  // lastShape: 'flat' | 'taper' (trapezoid only)
+    bar: { borderRadius: 0, barHeight: '80%' }           // cosmetic bar props still apply
+  },
+  dataLabels: {
+    enabled: true,
+    formatter: (val, opt) => opt.w.globals.labels[opt.dataPointIndex] + ':  ' + val
+  },
+  legend: { show: false }
+}
+```
+
+### Pyramid (v6)
+
+Same shape as funnel, but order values **smallest → largest** so the wide base sits at the bottom.
+
+```js
+{
+  chart: { type: 'pyramid', height: 350 },
+  series: [{ name: '', data: [200, 330, 548, 740, 880, 990, 1100, 1380] }],
+  xaxis: { categories: ['Sweets', 'Processed', 'Fats', 'Meat', 'Legumes', 'Dairy', 'Produce', 'Grains'] },
+  plotOptions: { bar: { distributed: true } },  // one color per stage
+  dataLabels: { enabled: true, formatter: (val, opt) => opt.w.globals.labels[opt.dataPointIndex] },
+  legend: { show: false }
+}
+```
+
 ---
 
 ## Key plotOptions.bar Options
@@ -242,3 +284,5 @@ series: [{
 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.
+6. **Funnel/pyramid value ordering**: funnel expects values ordered largest-to-smallest and pyramid smallest-to-largest. The renderer does not sort for you; unsorted data produces a jagged shape. Stage labels come from `xaxis.categories`, and per-stage labels in `dataLabels.formatter` are read via `opt.w.globals.labels[opt.dataPointIndex]`.
+7. **Reaching for `plotOptions.bar.isFunnel` in v6**: unnecessary. Set `chart.type: 'funnel'` (or `'pyramid'`) and use `plotOptions.funnel` for shape options.

package/references/circular-charts.md

@@ -5,7 +5,8 @@
 - **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
+- **Radial Bar** (`'radialBar'`): Circular progress chart (one or more concentric tracks)
+- **Gauge** (`'gauge'`, **new in v6**): Single-value gauge with arc/needle shapes, colored bands, and ticks
 
 ## Tree-Shakeable Import
 
@@ -16,6 +17,7 @@ import ApexCharts from 'apexcharts/pie'
 
 import ApexCharts from 'apexcharts/radialBar'
 // Registers: radialBar (separate entry point)
+// Also covers gauge (it normalizes to the radialBar engine in v6)
 ```
 
 ---
@@ -46,6 +48,52 @@ import ApexCharts from 'apexcharts/radialBar'
 
 **Important:** RadialBar values represent percentages (0–100). Values above 100 will overflow the track.
 
+### Gauge (v6)
+
+A gauge is a single-value `radialBar` alias. Series is a flat one-element array; the value maps to the `min..max` domain (defaults 0-100). All configuration lives under `plotOptions.radialBar`; there is **no `plotOptions.gauge`**.
+
+```js
+// Minimal gauge:
+{
+  chart: { type: 'gauge', height: 350 },
+  series: [72],
+  labels: ['Progress']
+}
+```
+
+```js
+// Needle gauge with colored bands and ticks:
+{
+  chart: { type: 'gauge', height: 360 },
+  series: [68],
+  labels: ['Speed'],
+  plotOptions: {
+    radialBar: {
+      shape: 'needle',          // 'arc' (default, filled value-arc) | 'needle' (rotating pointer)
+      startAngle: -135, endAngle: 135,
+      min: 0, max: 100,          // value-to-angle domain
+      bands: [                   // colored threshold segments in the min..max domain
+        { from: 0, to: 30, color: '#FF4560' },
+        { from: 30, to: 70, color: '#FEB019' },
+        { from: 70, to: 100, color: '#00E396' }
+      ],
+      bandsStyle: { strokeWidth: '50%', gap: 1 },
+      ticks: {
+        show: true,
+        major: { count: 11, length: 8, width: 2, color: '#334155', placement: 'outside' },
+        minor: { count: 1, length: 4, width: 1, color: '#94A3B8', placement: 'outside' },
+        labels: { show: true, offset: 6, fontSize: '11px' }
+      },
+      needle: { color: '#0F172A', length: '60%', baseWidth: 6, tipWidth: 1 },
+      hollow: { size: '70%' },
+      dataLabels: { name: { show: false }, value: { offsetY: 32, fontSize: '28px', fontWeight: 700 } }
+    }
+  }
+}
+```
+
+A plain radialBar is effectively a gauge with `shape: 'arc'`. A semi-circle gauge is `startAngle: -90, endAngle: 90`.
+
 ---
 
 ## Key plotOptions
@@ -216,3 +264,5 @@ plotOptions: {
 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.
+7. **Looking for `plotOptions.gauge`**: it does not exist. Gauge is a `radialBar` alias; configure `shape`, `bands`, `ticks`, `needle`, and `min`/`max` under `plotOptions.radialBar`.
+8. **Gauge value outside `min`/`max`**: unlike a plain radialBar (fixed 0-100), a gauge maps its value to the `min..max` domain you set. A value beyond that domain saturates at the arc ends.

package/references/financial-charts.md

@@ -1,9 +1,10 @@
-# Financial Charts Reference — ApexCharts
+# Financial & Statistical 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
+- **Violin** (`'violin'`, **new in v6**): Statistical distribution chart showing a density curve per category, optionally with the raw sample points overlaid as jitter
 
 ## Tree-Shakeable Import
 
@@ -11,6 +12,9 @@
 import ApexCharts from 'apexcharts/candlestick'
 // Registers: candlestick, boxPlot
 // Alias: apexcharts/boxPlot
+
+import ApexCharts from 'apexcharts/violin'
+// Registers: violin (separate entry point, new in v6)
 ```
 
 ---
@@ -68,6 +72,57 @@ The `y` value must be an array of exactly 5 numbers: `[min, Q1, median, Q3, max]
 }
 ```
 
+### Violin: Density Profile (v6)
+
+Each point is `{ x, y: { density, points } }`:
+
+- `density` (**required**): an array of `[value, weight]` pairs describing the precomputed density/KDE profile.
+- `points` (optional): a flat array of raw observations, rendered as jitter dots.
+
+```js
+{
+  chart: { type: 'violin', height: 420 },
+  series: [{
+    name: 'Session duration',
+    data: [
+      {
+        x: 'Direct',
+        y: {
+          density: [[20, 0.02], [30, 0.08], [40, 0.18], [50, 0.10], [60, 0.03]], // [value, weight]
+          points: [22, 31, 38, 41, 47, 52, 58]                                    // raw observations
+        }
+      },
+      {
+        x: 'Referral',
+        y: {
+          density: [[25, 0.03], [35, 0.12], [45, 0.20], [55, 0.09], [65, 0.02]],
+          points: [27, 34, 44, 48, 53, 61]
+        }
+      }
+    ]
+  }],
+  plotOptions: {
+    violin: {
+      bandwidthScale: 1,          // multiplies the density-derived half-width
+      normalize: 'individual',     // 'individual' (each violin to its own peak) | 'group' (shared scale)
+      points: { show: false }      // set show:true to overlay the raw points as jitter
+    }
+  }
+}
+```
+
+**Orientation and per-category color come from `plotOptions.bar`** (violin reuses the bar renderer):
+
+```js
+plotOptions: {
+  bar: { horizontal: true, distributed: true },  // horizontal violins, one color each
+  violin: {
+    normalize: 'group',
+    points: { show: true, shape: 'circle', size: 3, jitter: 0.9, strokeWidth: 0 }
+  }
+}
+```
+
 ---
 
 ## Key plotOptions
@@ -155,3 +210,5 @@ plotOptions: {
 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.
+6. **Violin with a plain numeric `y`**: violin points need `y: { density: [[value, weight], ...] }`, not a number. The `density` profile is precomputed (ApexCharts does not run a KDE for you); `points` for the raw-sample jitter overlay is optional.
+7. **Violin orientation set on the wrong namespace**: horizontal violins and per-violin colors come from `plotOptions.bar` (`horizontal`, `distributed`), while `bandwidthScale`, `normalize`, and `points` live under `plotOptions.violin`.

package/references/ssr.md

@@ -22,37 +22,43 @@ import ApexCharts from 'apexcharts/client'
 
 ## Server-Side API
 
-### renderToString(options)
+### renderToString(options, ssrOptions?)
 
-Returns a raw SVG string suitable for embedding:
+Returns a raw SVG string suitable for embedding. Pass width/height in the **second** argument (SSR has no DOM to measure).
 
 ```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'] }
-})
+// renderToString(options, { width?, height?, scale? })
+const svgString = await ApexCharts.renderToString(
+  {
+    chart: { type: 'line' },
+    series: [{ name: 'Sales', data: [30, 40, 35, 50] }],
+    xaxis: { categories: ['Q1', 'Q2', 'Q3', 'Q4'] }
+  },
+  { width: 600, height: 350 }
+)
 
 // svgString is raw <svg>...</svg> markup
 ```
 
-### renderToHTML(options)
+### renderToHTML(options, ssrOptions?)
 
 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
+// renderToHTML(options, { width?, height?, scale?, className? })
+const htmlString = await ApexCharts.renderToHTML(
+  {
+    chart: {
+      type: 'bar',
+      id: 'my-chart'   // id is important for hydration targeting
+    },
+    series: [{ data: [44, 55, 41, 67] }],
+    xaxis: { categories: ['A', 'B', 'C', 'D'] }
   },
-  series: [{ data: [44, 55, 41, 67] }],
-  xaxis: { categories: ['A', 'B', 'C', 'D'] }
-})
+  { width: 600, height: 350 }
+)
 
 // htmlString is <div id="my-chart" data-apexcharts>...<svg>...</svg></div>
 ```
@@ -63,19 +69,19 @@ const htmlString = await ApexCharts.renderToHTML({
 
 After the server-rendered HTML is in the DOM, hydrate it to make it interactive:
 
-### hydrate(element)
+### hydrate(element, clientOptions?)
 
 ```js
 import ApexCharts from 'apexcharts'
 
-// Hydrate a specific chart element
+// Hydrate a specific chart element (optionally merge client-only options)
 const chart = ApexCharts.hydrate(document.querySelector('#my-chart'))
 ```
 
-### hydrateAll()
+### hydrateAll(selector?, clientOptions?)
 
 ```js
-// Hydrate all server-rendered charts on the page
+// Hydrate all server-rendered charts on the page (optionally scope by selector)
 ApexCharts.hydrateAll()
 ```
 
@@ -101,11 +107,14 @@ 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'] }
-  })
+  const chartHTML = await ApexCharts.renderToHTML(
+    {
+      chart: { type: 'line', id: 'sales-chart' },
+      series: [{ name: 'Sales', data: [30, 40, 35, 50, 49, 60] }],
+      xaxis: { categories: ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun'] }
+    },
+    { width: 600, height: 350 }
+  )
 
   res.send(`
     <!DOCTYPE html>
@@ -136,11 +145,14 @@ app.listen(3000)
 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'] }
-  })
+  const chartHTML = await ApexCharts.renderToHTML(
+    {
+      chart: { type: 'line', id: 'my-chart' },
+      series: [{ data: [10, 20, 30] }],
+      xaxis: { categories: ['A', 'B', 'C'] }
+    },
+    { width: 600, height: 350 }
+  )
 
   return (
     <>
@@ -176,11 +188,14 @@ export default function HydrateCharts() {
 // 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'] }
-  })
+  return await ApexCharts.renderToHTML(
+    {
+      chart: { type: 'bar', id: 'my-chart' },
+      series: [{ data: [44, 55, 41] }],
+      xaxis: { categories: ['A', 'B', 'C'] }
+    },
+    { width: 600, height: 350 }
+  )
 })
 
 // Client-side hydration
@@ -197,5 +212,5 @@ onMounted(async () => {
 
 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.
+3. **Missing width/height**: SSR has no DOM to measure. Pass explicit dimensions in the **second** argument: `renderToString(options, { width, height })` / `renderToHTML(options, { width, height })`.
 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

@@ -6,7 +6,7 @@ ApexCharts supports three import strategies with different bundle sizes:
 
 | Strategy | Import | Includes |
 |---|---|---|
-| Full bundle | `import ApexCharts from 'apexcharts'` | All 16 chart types + all features |
+| Full bundle | `import ApexCharts from 'apexcharts'` | All 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 |
 
@@ -28,14 +28,17 @@ Each entry point registers a family of related chart types:
 | `apexcharts/rangeBar` | same as /bar |
 | `apexcharts/candlestick` | candlestick, boxPlot |
 | `apexcharts/boxPlot` | same as /candlestick |
+| `apexcharts/violin` | violin *(new in v6)* |
 | `apexcharts/pie` | pie, donut, polarArea |
 | `apexcharts/donut` | same as /pie |
 | `apexcharts/polarArea` | same as /pie |
-| `apexcharts/radialBar` | radialBar |
+| `apexcharts/radialBar` | radialBar, **gauge** *(v6 alias)* |
 | `apexcharts/radar` | radar |
 | `apexcharts/heatmap` | heatmap |
 | `apexcharts/treemap` | treemap |
 
+**v6 first-class aliases:** `funnel` and `pyramid` render through the bar engine, so `apexcharts/bar` covers them. `gauge` renders through radialBar, so `apexcharts/radialBar` covers it. There is no separate `apexcharts/funnel`, `apexcharts/pyramid`, or `apexcharts/gauge` entry.
+
 ### Using Multiple Chart Types
 
 ```js
@@ -57,9 +60,22 @@ Features are optional modules that add functionality. When using per-type entrie
 | 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) |
+| Morph *(v6)* | `import 'apexcharts/features/morph'` | Animated chart-type morphs |
+| Drilldown *(v6)* | `import 'apexcharts/features/drilldown'` | Hierarchical drill-down |
+| History / Rewind *(v6)* | `import 'apexcharts/features/history'` | Undo/redo (`chart.history`) |
+| Perspectives *(v6)* | `import 'apexcharts/features/perspectives'` | Shareable view state |
+| Storyboard *(v6)* | `import 'apexcharts/features/storyboard'` | Scrollytelling (includes perspectives) |
+| Facet *(v6)* | `import 'apexcharts/features/facet'` | Design tokens + OS-aware themes |
+| Weave *(v6)* | `import 'apexcharts/features/weave'` | Public plugin platform |
+| Renderer / Strata *(v6)* | `import 'apexcharts/features/renderer-canvas'` | Hybrid SVG + canvas renderer |
+| Marks *(v6)* | `import 'apexcharts/features/marks'` | Custom series types (`registerSeriesType`) |
+| Link *(v6)* | `import 'apexcharts/features/link'` | Crossfilter / linked views |
+| Ink *(v6)* | `import 'apexcharts/features/ink'` | On-chart annotation authoring |
+| Measure *(v6)* | `import 'apexcharts/features/measure'` | Measure / delta ruler |
+| Context menu *(v6)* | `import 'apexcharts/features/context-menu'` | Right-click / long-press context menu |
 | All | `import 'apexcharts/features/all'` | All of the above |
 
-**Important:** Tooltip is always included in core — it cannot be tree-shaken.
+**Important:** Tooltip is always included in core (it cannot be tree-shaken). Easing (Cadence) and real-time streaming are also core, so they need no feature import. See `v6-features.md` for the config and API of each v6 feature.
 
 ### What Happens If You Forget a Feature