apexcharts-skill 2.0.1 → 2.2.0

package/README.md

@@ -20,10 +20,10 @@ This skill targets **ApexCharts v6** (backward compatible with v5 configs).
 
 ### Coverage
 
-- **20 chart types**: line, area, bar, pie, donut, radialBar, scatter, bubble, heatmap, candlestick, boxPlot, violin, radar, polarArea, rangeBar, rangeArea, treemap, funnel, pyramid, gauge
+- **24 chart types**: line, area, bar, pie, donut, radialBar, scatter, bubble, heatmap, candlestick, boxPlot, violin, histogram, radar, polarArea, rangeBar, rangeArea, treemap, funnel, pyramid, gauge, sunburst, unit, waffle
 - **Correct data formats** for every chart type
 - **Common pitfalls** with wrong/correct code examples
-- **v6 feature platform**: plugins (Weave), canvas renderer (Strata), custom series (Marks), undo/redo (Rewind), shareable views (Perspectives), themes (Facet), easing (Cadence), crossfilter (Link), annotation authoring (Ink), measure ruler, context menu, storyboard, streaming, drilldown
+- **v6 feature platform**: plugins (Weave), canvas renderer (Strata), custom series (Marks), undo/redo (Rewind), shareable views (Perspectives), themes (Facet), easing (Cadence), crossfilter (Link), annotation authoring (Ink), measure ruler, context menu, storyboard, streaming, drilldown, raw-sample statistics (Stats), unit-chart shape kit (`apexcharts/unit-shapes`)
 - **Tree-shaking** and bundle optimization patterns
 - **SSR** (server-side rendering) and hydration
 - **Framework integration**: React, Vue 3, Angular
@@ -80,8 +80,8 @@ const barCharts = await readFile(referencePath('bar-charts.md'), 'utf8');
 ├── references/
 │   ├── cartesian-charts.md     # line, area, scatter, bubble, rangeArea
 │   ├── bar-charts.md           # bar, column, rangeBar, timeline/Gantt, funnel, pyramid
-│   ├── financial-charts.md     # candlestick, boxPlot, violin
-│   ├── circular-charts.md      # pie, donut, polarArea, radialBar, gauge
+│   ├── financial-charts.md     # candlestick, boxPlot, violin, histogram
+│   ├── circular-charts.md      # pie, donut, polarArea, radialBar, gauge, sunburst, unit, waffle
 │   ├── grid-charts.md          # heatmap, treemap
 │   ├── radar-charts.md         # radar
 │   ├── v6-features.md          # v6 feature platform (plugins, canvas, undo/redo, themes, ...)

package/SKILL.md

@@ -4,7 +4,8 @@ description: >
   AI skill for building ApexCharts.js charts and data visualizations (targets v6).
   Use when the user asks to create, configure, or troubleshoot any chart using ApexCharts
   (line, area, bar, pie, donut, radialBar, scatter, bubble, heatmap, candlestick, boxPlot,
-  violin, radar, polarArea, rangeBar, rangeArea, treemap, funnel, pyramid, gauge). Covers
+  violin, histogram, radar, polarArea, rangeBar, rangeArea, treemap, funnel, pyramid, gauge,
+  sunburst, unit, waffle). Covers
   correct data formats, lifecycle, formatters, tree-shaking, SSR, and the v6 feature
   platform (plugins, canvas renderer, custom series, undo/redo, shareable views, themes,
   crossfilter, annotation authoring, storyboard, streaming, drilldown). In React /
@@ -12,8 +13,8 @@ description: >
   (`react-apexcharts`, `vue3-apexcharts`, `ng-apexcharts`) over the core API.
 metadata:
   author: ApexCharts
-  version: "2.0.1"
-  library_version: "6.2.0"
+  version: "2.2.0"
+  library_version: "6.10.0"
   category: data-visualization
   tags: [charts, visualization, javascript, typescript, svg, apexcharts]
   docs: https://apexcharts.com/docs/
@@ -31,6 +32,8 @@ metadata:
 > Wrappers handle `destroy()` automatically on unmount, accept reactive props, and forward events as idiomatic framework events. Use the core API directly only when no framework is detected, or when the user explicitly asks for vanilla. See `references/framework-wrappers.md`.
 
 > **Targets ApexCharts v6.** v6 is backward compatible: existing v5 configs keep working unchanged. Everything new (the plugin platform, canvas renderer, custom series, undo/redo, shareable views, themes, crossfilter, annotation authoring, storyboard, streaming, drilldown) is opt-in and tree-shakeable. Two behaviors changed *on by default* (both respect `prefers-reduced-motion`): (1) data updates that add/remove points now animate coherently, and (2) mobile pinch-zoom / two-finger pan gestures are enabled. See `references/v6-features.md` for the full v6 surface.
+>
+> **Premium features and licensing (6.5.0+).** Seven of the v6 features are premium: `storyboard`, `link` (crossfilter / linked views), `ink` (annotation authoring), `measure`, `context-menu`, `perspectives` (shareable views), and `history` (undo/redo). The `unit` / `waffle` chart type is also premium (6.6.0+). These still function fully, but render an `APEXCHARTS` trial watermark until an entitled license is set via `ApexCharts.setLicense(key)` (static) or per-chart `chart.license`. As of 6.7.0 they require a `premium` or `enterprise` plan; a `pro` key or the free tier keeps the watermark. Every other chart type and free module is never gated. See the Licensing section in `references/v6-features.md`.
 
 ## 1. Critical Rules
 
@@ -47,8 +50,9 @@ metadata:
 11. **Color hex values must include the `#` prefix** (e.g., `'#FF5733'`, not `'FF5733'`).
 12. **Tree-shaking**: importing `apexcharts/core` gives you a bare class — you must also import chart-type entries and feature entries separately.
 13. **v6 first-class aliases**: `funnel` and `pyramid` render through the bar engine; `gauge` renders through radialBar. Use them as `chart.type` directly (no `plotOptions.bar.isFunnel` needed). They are covered by the `apexcharts/bar` and `apexcharts/radialBar` tree-shaking entries respectively.
-14. **`violin` (v6, statistical)** uses a per-point density profile: `data: [{ x, y: { density: [[value, weight], ...], points?: [number] } }]`, not a plain number.
+14. **`violin` (v6, statistical)** uses a per-point density profile: `data: [{ x, y: { density: [[value, weight], ...], points?: [number] } }]`, not a plain number. Since v6.9 a datum may instead supply only raw observations (`points: [number]`, no `y`) and the library derives the density via KDE (needs `apexcharts/features/stats` when tree-shaking).
 15. **`render()` is idempotent (v6)**: calling `render()` twice on the same instance returns the same promise instead of building a duplicate chart. You still must `destroy()` before creating a *new* instance on the same element.
+16. **`histogram` (v6.9)** series carry **raw observations** (one number per event), not pre-aggregated counts; the chart chooses bin edges and counts them. Binning ships behind the stats feature: use the `apexcharts/histogram` entry, or `import 'apexcharts/features/stats'` alongside `apexcharts/bar` (the full `apexcharts` bundle already includes it).
 
 ---
 
@@ -68,22 +72,23 @@ This is the most critical reference. Using the wrong data format is the #1 cause
 | Range Area | `'rangeArea'` | `[{ name, data: [{ x, y: [low, high] }] }]` | `series: [{ name: 'Temp', data: [{ x: 'Jan', y: [5, 15] }] }]` |
 | Range Bar | `'rangeBar'` | `[{ name, data: [{ x, y: [start, end] }] }]` — for timeline/Gantt, use timestamps | `series: [{ name: 'Tasks', data: [{ x: 'Design', y: [1, 5] }] }]` |
 | Candlestick | `'candlestick'` | `[{ data: [{ x, y: [O, H, L, C] }] }]` — array of 4: Open, High, Low, Close | `series: [{ data: [{ x: new Date('2024-01-01'), y: [51, 56, 48, 53] }] }]` |
-| Box Plot | `'boxPlot'` | `[{ data: [{ x, y: [min, Q1, median, Q3, max] }] }]` — array of 5 | `series: [{ data: [{ x: 'Group A', y: [10, 20, 30, 40, 50] }] }]` |
-| Violin *(v6)* | `'violin'` | `[{ name, data: [{ x, y: { density: [[value, weight], ...], points?: [number] } }] }]` | `series: [{ name: 'Sessions', data: [{ x: 'A', y: { density: [[20, 0.1], [30, 0.2]], points: [21, 29] } }] }]` |
+| Box Plot | `'boxPlot'` | `[{ data: [{ x, y: [min, Q1, median, Q3, max] }] }]` — array of 5. *(v6.9)* Or supply the raw sample instead: `[{ data: [{ x, points: [number] }] }]` and the quartiles are computed (R type 7; needs the stats feature). | `series: [{ data: [{ x: 'Group A', y: [10, 20, 30, 40, 50] }] }]` |
+| Violin *(v6)* | `'violin'` | `[{ name, data: [{ x, y: { density: [[value, weight], ...], points?: [number] } }] }]`. *(v6.9)* Or supply the raw sample instead: `[{ name, data: [{ x, points: [number] }] }]` and the density is derived via KDE (needs the stats feature). | `series: [{ name: 'Sessions', data: [{ x: 'A', y: { density: [[20, 0.1], [30, 0.2]], points: [21, 29] } }] }]` |
+| Histogram *(v6.9)* | `'histogram'` | `[{ name, data: [number] }]`: **raw observations**, one number per event, NOT pre-binned counts. The chart bins them (needs the stats feature). | `series: [{ name: 'Latency', data: [102, 87, 143, 91] }]` |
 | Heatmap | `'heatmap'` | `[{ name, data: [{ x, y: number }] }]` — y is the intensity value | `series: [{ name: 'Mon', data: [{ x: '10am', y: 45 }] }]` |
-| Treemap | `'treemap'` | `[{ data: [{ x, y: number }] }]` — y is the area/value | `series: [{ data: [{ x: 'Item A', y: 100 }, { x: 'Item B', y: 60 }] }]` |
+| Treemap | `'treemap'` | `[{ data: [{ x, y: number }] }]` — y is the area/value. *(v6.9)* A datum may carry `children` to any depth for a nested treemap (see `references/grid-charts.md`). | `series: [{ data: [{ x: 'Item A', y: 100 }, { x: 'Item B', y: 60 }] }]` |
 | Radar | `'radar'` | `[{ name, data: [number] }]` + `xaxis: { categories: [...] }` | `series: [{ name: 'Skill', data: [80, 50, 30, 40, 100] }]` |
 | Funnel *(v6)* | `'funnel'` | `[{ name, data: [number] }]` + `xaxis: { categories: [...] }`. Order values **largest→smallest**. | `series: [{ data: [1380, 990, 548, 200] }]` |
 | Pyramid *(v6)* | `'pyramid'` | Same as funnel; order values **smallest→largest** (wide base at bottom). | `series: [{ data: [200, 548, 990, 1380] }]` |
 
-### Non-Axis Charts (pie, donut, radialBar, polarArea, gauge)
+### Non-Axis Charts (pie, donut, radialBar, polarArea, gauge, unit, waffle)
 
 These use a **flat number array** for `series`, NOT the object format:
 
 ```js
 // CORRECT — flat number array + labels
 {
-  chart: { type: 'pie' },  // or 'donut', 'polarArea', 'radialBar', 'gauge'
+  chart: { type: 'pie' },  // or 'donut', 'polarArea', 'radialBar', 'gauge', 'unit', 'waffle'
   series: [44, 55, 13, 43, 22],
   labels: ['Team A', 'Team B', 'Team C', 'Team D', 'Team E']
 }
@@ -91,6 +96,29 @@ These use a **flat number array** for `series`, NOT the object format:
 
 **Gauge *(v6)*** is a single-value radialBar alias: `series: [72]`, `labels: ['Progress']`. Configure the arc/needle, colored bands, ticks, and `min`/`max` domain through `plotOptions.radialBar` (see `references/circular-charts.md`).
 
+**Unit / Waffle *(v6.6, premium)*** render one mark per unit of value (dot clusters, pictograms, waffles, beeswarms). Same flat-array + `labels` shape as pie; layout is chosen through `plotOptions.unit.layout`. A per-mark object form (`series: [{ name, data: [{ value, x, z, name, fillColor, id }] }]`) gives each mark its own color, position, size, and tooltip. `waffle` is a preset alias of `unit` (grid layout). Both render an `APEXCHARTS` watermark until an entitled license is set. See `references/circular-charts.md`.
+
+### Hierarchical Charts (sunburst)
+
+**Sunburst *(v6.7, free)*** draws tree-structured data as concentric rings (a nested pie / donut). It uses the axis-style `[{ data: [...] }]` wrapper, but each datum is an `{ x, y, children }` node nested to any depth:
+
+```js
+{
+  chart: { type: 'sunburst' },
+  series: [{
+    data: [
+      { x: 'Mobile', y: 55, children: [
+        { x: 'iOS', y: 30, children: [{ x: 'iOS 17', y: 18 }, { x: 'iOS 16', y: 9 }] },
+        { x: 'Android', y: 23 }
+      ] },
+      { x: 'Desktop', y: 33, children: [{ x: 'Windows', y: 20 }, { x: 'macOS', y: 10 }] }
+    ]
+  }]
+}
+```
+
+Configure the centre hole, corner rounding, and inter-arc gap through `plotOptions.sunburst` (see `references/circular-charts.md`).
+
 ---
 
 ## 3. Package / Module Map
@@ -114,6 +142,7 @@ import ApexCharts from 'apexcharts/rangeBar'      # same as /bar
 import ApexCharts from 'apexcharts/candlestick'   # candlestick, boxPlot
 import ApexCharts from 'apexcharts/boxPlot'       # same as /candlestick
 import ApexCharts from 'apexcharts/violin'        # violin (v6)
+import ApexCharts from 'apexcharts/histogram'     # histogram (v6.9): bar engine + the stats feature
 import ApexCharts from 'apexcharts/pie'           # pie, donut, polarArea
 import ApexCharts from 'apexcharts/donut'         # same as /pie
 import ApexCharts from 'apexcharts/polarArea'     # same as /pie
@@ -121,14 +150,20 @@ import ApexCharts from 'apexcharts/radialBar'     # radialBar + gauge (v6)
 import ApexCharts from 'apexcharts/radar'         # radar only
 import ApexCharts from 'apexcharts/heatmap'       # heatmap only
 import ApexCharts from 'apexcharts/treemap'       # treemap only
+import ApexCharts from 'apexcharts/sunburst'      # sunburst (v6.7, hierarchical)
+import ApexCharts from 'apexcharts/unit'          # unit + waffle (v6.6, premium)
 # funnel + pyramid (v6) render through the bar engine; use apexcharts/bar
 
+# Unit-chart shape kit (v6.10): named exports, tree-shaken per shape (~4 KB gzipped each)
+import { heart, outlined, glyphs, preview } from 'apexcharts/unit-shapes'
+
 # Optional features (side-effect imports — just import, no default export needed)
 import 'apexcharts/features/exports'         # PNG/SVG/CSV export methods
 import 'apexcharts/features/legend'          # Interactive legend component
 import 'apexcharts/features/toolbar'         # Toolbar (zoom, pan, download buttons)
 import 'apexcharts/features/annotations'     # X/Y/point/text/image annotations
 import 'apexcharts/features/keyboard'        # Keyboard navigation (accessibility)
+import 'apexcharts/features/stats'           # Statistics (v6.9): histogram binning, boxPlot/violin raw samples, rowSeries()
 # v6 feature platform (all opt-in, all tree-shakeable)
 import 'apexcharts/features/morph'           # Animated chart-type morphs
 import 'apexcharts/features/drilldown'       # Hierarchical drill-down
@@ -152,6 +187,8 @@ import ApexCharts from 'apexcharts/client' # Browser: explicit client import for
 
 **Note:** When using `apexcharts` (full bundle), all chart types and features are included automatically. Tree-shaking entries (`/core`, `/line`, etc.) are for reducing bundle size.
 
+**Note (v6.9):** ApexCharts is no longer dependency-free: it depends on `apex-commons` at runtime. npm resolves it automatically and the browser (script-tag) bundles inline it, so no action is needed; it only matters for tooling that assumed zero dependencies.
+
 ---
 
 ## 4. Core Lifecycle Pattern
@@ -215,6 +252,8 @@ chart.destroy()
 
 **Important:** All formatters must return a `string` (or `number` for `dataLabels.formatter`). Never return `undefined`.
 
+**Per-point data label offsets (v6.8):** `dataLabels.offsetX` and `dataLabels.offsetY` accept `number | ((opts) => number)`. The function receives `{ series, seriesIndex, dataPointIndex, w }` (same signature as `dataLabels.style.colors` functions), so colliding labels from two series at the same x can be pushed apart, e.g. `offsetY: ({ seriesIndex }) => (seriesIndex === 0 ? -12 : 12)`. Keep it pure; it may be called more than once per label.
+
 ---
 
 ## 6. Pitfalls & Anti-Patterns
@@ -508,6 +547,7 @@ await chart.updateOptions({ title: { text: 'New Title' } })
 | `exportToCSV(options?)` | Trigger CSV download. |
 | `setLocale(localeName)` | Switch locale. |
 | `toggleDataPointSelection(seriesIndex, dataPointIndex?)` | Select/deselect data point. |
+| `rowSeries(opts?)` | *(v6.9)* Returns the raw rows behind this chart's marks as a unit-chart series (one cluster per mark), or `null` when the type has no row source (works for histogram / boxPlot / violin, needs `apexcharts/features/stats`). `opts.maxRows` caps the output (default 3000). |
 | `getState()` | Returns snapshot of chart state. |
 | `addEventListener(name, handler)` | Subscribe to chart event. |
 | `removeEventListener(name, handler)` | Unsubscribe from chart event. |
@@ -531,6 +571,7 @@ await chart.updateOptions({ title: { text: 'New Title' } })
 |---|---|
 | `ApexCharts.exec(chartID, fn, ...args)` | Call method on chart by its `chart.id`. |
 | `ApexCharts.getChartByID(chartID)` | Get chart instance by id. |
+| `ApexCharts.setLicense(key)` | *(v6.5)* Set the license key that clears the premium-feature trial watermark. Static, family-shared, offline, SSR-safe; call before `render()`. Per-chart override is `chart.license`. As of 6.7.0 requires a `premium`/`enterprise` plan. |
 | `ApexCharts.merge(target, source)` | Deep-merge objects. |
 | `ApexCharts.use(typeMap)` | Register chart type constructors (tree-shaking). |
 | `ApexCharts.registerFeatures(featureMap)` | Register optional feature modules. |
@@ -538,6 +579,7 @@ await chart.updateOptions({ title: { text: 'New Title' } })
 | `ApexCharts.registerSeriesType(name, def) / unregisterSeriesType(name)` | *(v6, Marks)* Register a custom series type. |
 | `ApexCharts.registerTheme(name, def) / unregisterTheme(name)` | *(v6, Facet)* Register a named brand theme. |
 | `ApexCharts.registerEasing(name, fn)` | *(v6, Cadence)* Register a custom easing curve. |
+| `ApexCharts.registerUnitLayout(name, fn) / unregisterUnitLayout(name)` | *(v6.9)* Register a named unit-chart layout, referenceable via `plotOptions.unit.positions: '<name>'` with `layout: 'custom'`. |
 | `ApexCharts.crossfilter({ id, records }) / getCrossfilter(id)` | *(v6, Link)* Create / fetch a crossfilter engine. |
 | `ApexCharts.perspectives.fromURL(href)` | *(v6)* Decode a perspective token from a URL. |
 
@@ -595,6 +637,7 @@ await chart.updateOptions({ title: { text: 'New Title' } })
       drillDownStart: (info, chart, options) => {},// drilldown
       drillDownEnd: (info, chart, options) => {},  // drilldown
       drillUp: (info, chart, options) => {},       // drilldown
+      drillDownError: ({ id, error }, chart, options) => {}, // drilldown (v6.9): async level failed; view unchanged
     }
   }
 }
@@ -621,7 +664,8 @@ All of the following are new in v6, off by default, and each ships as a `apexcha
 | **Context menu** | `apexcharts/features/context-menu` | `chart: { contextMenu: { enabled, items } }` for point-specific right-click actions. |
 | **Storyboard** (scrollytelling) | `apexcharts/features/storyboard` | `chart.storyboard.bind({ beats })` pairs prose sections with saved views. |
 | **Streaming** | core | `chart: { streaming: { enabled, maxPoints } }` for constant-velocity rolling-window scroll. |
-| **Drilldown** | `apexcharts/features/drilldown` | `drilldown: { enabled, series }` + a `drilldown` id on data points; `chart.drillDown()/drillUp()`. |
+| **Drilldown** | `apexcharts/features/drilldown` | `drilldown: { enabled, series }` + a `drilldown` id on data points; `chart.drillDown()/drillUp()`. v6.9 adds line/area support, async levels (`onDrillDown` may return a Promise), a loading overlay, and the `drillDownError` event. |
+| **Stats** | `apexcharts/features/stats` | *(v6.9)* Statistics behind histogram binning, boxPlot/violin raw-sample summaries (R type 7 quartiles, KDE), and `chart.rowSeries()`. The `apexcharts/histogram` entry includes it. |
 
 ## 10. Reference Routing Table
 
@@ -631,8 +675,8 @@ For detailed chart-family-specific options, data format variants, and full worki
 |---|---|
 | Line, Area, Scatter, Bubble, Range Area | `references/cartesian-charts.md` |
 | Bar, Column, Range Bar, Timeline/Gantt, Funnel, Pyramid | `references/bar-charts.md` |
-| Candlestick, Box Plot, Violin | `references/financial-charts.md` |
-| Pie, Donut, Polar Area, Radial Bar, Gauge | `references/circular-charts.md` |
+| Candlestick, Box Plot, Violin, Histogram | `references/financial-charts.md` |
+| Pie, Donut, Polar Area, Radial Bar, Gauge, Sunburst, Unit, Waffle | `references/circular-charts.md` |
 | Heatmap, Treemap | `references/grid-charts.md` |
 | Radar | `references/radar-charts.md` |
 | v6 feature platform (plugins, canvas, undo/redo, themes, crossfilter, storyboard, ...) | `references/v6-features.md` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "apexcharts-skill",
-  "version": "2.0.1",
+  "version": "2.2.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",

package/references/bar-charts.md

@@ -19,6 +19,8 @@ import ApexCharts from 'apexcharts/bar'
 
 **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.
 
+**Histogram (v6.9):** `chart.type: 'histogram'` also renders through the bar pathway, but its series carry raw observations that the chart bins itself, and the binning needs the stats feature (`apexcharts/histogram` entry, or `apexcharts/features/stats` alongside `apexcharts/bar`). It is documented with the other statistical charts in `references/financial-charts.md`.
+
 ---
 
 ## Data Formats
@@ -213,6 +215,28 @@ plotOptions: {
 }
 ```
 
+### Bar Chart Race (v6.4)
+
+A reorder update animates into a bar chart race: when you re-sort the data and update the chart, the bars slide to their new ranks and their category labels ride along automatically (whenever `dynamicAnimation` is on). Two opt-in `dataLabels` flags complete the effect. Both are off by default and apply to **bar / column only**; their speed and easing follow `chart.animations.dynamicAnimation`.
+
+```js
+const options = {
+  chart: {
+    type: 'bar',
+    animations: { dynamicAnimation: { speed: 800 } },
+  },
+  plotOptions: { bar: { horizontal: true } },
+  dataLabels: {
+    enabled: true,
+    animate: { enabled: true },  // value labels ride to the new rank instead of snapping
+    countUp: { enabled: true },  // and count up/down from the previous value (formatter runs each frame)
+  },
+}
+// On each frame, re-sort your data and call updateOptions (or updateSeries) with the
+// new series and categories. Bars, category labels, and value labels animate together.
+// Rotated axis labels ride correctly too.
+```
+
 ### Goals / Target Markers
 
 ```js

package/references/cartesian-charts.md

@@ -242,6 +242,6 @@ xaxis: {
 
 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'`.
+3. **Datetime axis with string dates** — pass timestamps (`new Date(...).getTime()`) or `Date` objects, not raw strings like `'January 2024'`. Since v6.10 a `Date` object `x` is accepted by the types and keeps millisecond resolution (previously milliseconds were truncated, collapsing points within the same second).
 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.

package/references/circular-charts.md

@@ -7,6 +7,8 @@
 - **Polar Area** (`'polarArea'`) — Radial segments with equal angles, varying radius
 - **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
+- **Sunburst** (`'sunburst'`, **new in v6.7, free**): Hierarchical nested pie/donut; concentric rings, one per level
+- **Unit / Waffle** (`'unit'` / `'waffle'`, **new in v6.6, premium**): One mark per unit of value (dot clusters, pictograms, waffles, beeswarms, parliament, custom layouts and the v6.10 shape kit)
 
 ## Tree-Shakeable Import
 
@@ -18,6 +20,15 @@ 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)
+
+import ApexCharts from 'apexcharts/sunburst'
+// Registers: sunburst (v6.7, hierarchical). Free, not gated.
+
+import ApexCharts from 'apexcharts/unit'
+// Registers: unit + waffle (v6.6). Premium: watermarked until a license is set.
+
+import { heart, outlined, glyphs, preview } from 'apexcharts/unit-shapes'
+// Unit-chart shape kit (v6.10), named exports tree-shaken per shape. See "Unit shapes" below.
 ```
 
 ---
@@ -94,6 +105,157 @@ A gauge is a single-value `radialBar` alias. Series is a flat one-element array;
 
 A plain radialBar is effectively a gauge with `shape: 'arc'`. A semi-circle gauge is `startAngle: -90, endAngle: 90`.
 
+### Sunburst (v6.7)
+
+A sunburst draws a hierarchy as concentric rings: the first level fills a donut around the centre hole, and each deeper level stacks outward, with every child arc constrained to its parent's angular wedge. It is a **free** chart type (not gated). Data uses the axis-style `[{ data: [...] }]` wrapper, but each datum is an `{ x, y, children }` node nested to any depth. A leaf node omits `children`.
+
+```js
+{
+  chart: { type: 'sunburst', height: 380 },
+  series: [{
+    data: [
+      { x: 'Mobile', y: 55, children: [
+        { x: 'iOS', y: 30, children: [
+          { x: 'iOS 17', y: 18 },
+          { x: 'iOS 16', y: 9 }
+        ] },
+        { x: 'Android', y: 23 }
+      ] },
+      { x: 'Desktop', y: 33, children: [
+        { x: 'Windows', y: 20 },
+        { x: 'macOS', y: 10 }
+      ] }
+    ]
+  }],
+  plotOptions: {
+    sunburst: {
+      innerSize: '25%',      // centre hole radius as a % of max radius (or px)
+      borderRadius: 5,       // round the arc corners (px), same semantics as pie.borderRadius
+      spacing: 1,            // gap between adjacent arcs (px), same semantics as pie.spacing
+      startAngle: 0,
+      endAngle: 360,
+      leaf: 'extend',        // 'extend' draws a shallow branch's leaf to the rim | 'stop'
+      partition: 'normalize', // angular partition of a parent's wedge among children: 'normalize' | 'strict'
+      tint: 0,               // per-depth lightening of the parent colour (0 = same, 1 = white)
+      zoomOnClick: true,     // click a wedge to zoom into its branch (breadcrumb to go back). Default true
+      dataLabels: {
+        show: true,
+        minAngleToShow: 5,   // hide the label on any arc narrower than this (degrees)
+        style: { fontSize: '12px', colors: ['#fff'] }
+      }
+    }
+  }
+}
+```
+
+Colours, `stroke`, `legend`, and `title` behave as they do on pie and donut. A sunburst can also adapt an existing `drilldown` config instead of a native `children` hierarchy.
+
+### Unit / Waffle (v6.6, premium)
+
+A `unit` chart renders one discrete mark for every unit of value instead of a single bar or slice, so "37 of 200" reads as a countable quantity. It is a **non-axis** chart (dispatched like pie or treemap) and is **premium**: it renders fully in trial mode with an `APEXCHARTS` watermark until an entitled license is set (see `references/v6-features.md`). On every update each mark tweens from its old position to its new one, so re-grouping, filtering, or a changing count re-forms the marks.
+
+Data is the same flat number array + `labels` shape as pie:
+
+```js
+{
+  chart: { type: 'unit', height: 360 },
+  series: [276, 266, 3],
+  labels: ['For', 'Against', 'Abstain'],
+  plotOptions: { unit: { layout: 'grouped' } }
+}
+```
+
+**Layouts** via `plotOptions.unit.layout`:
+
+- `grouped` (default): one phyllotaxis blob per category, laid out in a row.
+- `packed`: one shared blob, coloured by group (`sortByGroup: true` nests the minority in the centre).
+- `columns`: each category is a vertical bar built from stacked dots (a waffle column).
+- `grid`: one waffle lattice, a part-to-whole square "pie" (`grid.total: 100` rounds it to a fixed cell budget for a percentage waffle; `grid.split: true` makes small-multiple mini-waffles).
+- `scatter`: a beeswarm on real value axes (`scatter.y: 'lanes'` default, or `'value'` for a 2D value-value plot; `scatter.sizeRange` for area-scaled bubbles). Since **v6.7.1** `scatter.orientation: 'horizontal' | 'vertical'` picks the beeswarm axis (lanes mode only): `'horizontal'` (default) puts the value on X with category lanes on Y; `'vertical'` puts the value on Y with lanes as columns. The value-axis keys (`xMin`/`xMax`/`xTitle`/`xFormatter`/`tickAmount`) describe the value axis in both orientations.
+- `arc` (**v6.7**): a parliament / hemicycle, seats in concentric arced rows across an annulus, filled in category order.
+- `custom` (**v6.9**): positions come from you. `plotOptions.unit.positions` is either a function `(objects, rect) => [{ id, x, y, r? }]` or the name of a layout registered with `ApexCharts.registerUnitLayout(name, fn)`. `objects` carries identity and data per mark (`{ id, index, seriesIndex, dataPointIndex, label, value, datum, r }`), `rect` is the plot area in pixels. A layout is objects in, positions out; the engine already tweens position, radius, and colour and keeps mark identity across a relayout. Marks whose id the provider omits animate out; unknown ids are ignored.
+
+**Also available:** `shape` (`'circle'` | `'square'` | `'image'` pictogram with `image.tint`); per-mark object data `series: [{ name, data: [{ value, x, z, name, fillColor, id }] }]`; `transition` (`'group'` default | `'flow'` crowd migration | `'identity'` keyed by `id`/`name`); numeric or `'auto'` dot `size`; `sizeByValue` bubbles; `unitValue` (1 mark = N units); `maxUnits` cap; per-cluster `clusterLabels`; and per-mark `tooltip.formatter`.
+
+**Motion (v6.9):** marks travel on a damped spring by default, so an update landing mid-flight retargets with the marks' velocity instead of restarting them (a dragged slider reads as continuous motion, not stutter). Configure via `plotOptions.unit.gather`: `motion: 'auto' | 'spring' | 'tween'`, `spring: 'crisp' | 'gentle' | 'snappy'`, `easing: 'outCubic' | 'inOutCubic' | 'outBack'` (setting `easing` implies tween), and `enter: 'burst' | 'fade' | 'rise'`.
+
+### Unit shapes (`apexcharts/unit-shapes`, v6.10)
+
+A companion kit of **39 shapes** a count can take (a heart, a house, a globe, the figure 1,024 drawn in 1,024 dots). Each shape is a plain callable layout, so it plugs straight into `plotOptions.unit.positions` with `layout: 'custom'`; no registration step. The entry point is tree-shaken per shape (about 4 KB gzipped each). Dots are packed to fill the outline, so one shape serves 40 dots in a sparkline and 3,000 in a poster.
+
+```js
+import ApexCharts from 'apexcharts'
+import { heart } from 'apexcharts/unit-shapes'
+
+new ApexCharts(el, {
+  chart: { type: 'unit' },
+  series: [57600, 16800, 4200, 3400],
+  labels: ['Repeat donors', 'First-time', 'Workplace drives', 'Emergency call-ups'],
+  plotOptions: {
+    unit: { layout: 'custom', positions: heart, unitValue: 100 },
+  },
+}).render()
+```
+
+Three kinds:
+
+- **Silhouettes** (29, filled outlines): `heart`, `house`, `tree`, `leaf`, `flame`, `droplet`, `fish`, `sun`, `human`, `group`, `star`, `crown`, `trophy`, `moneybag`, `funnel`, `shield`, `gear`, `robot`, `bulb`, `flask`, `car`, `plane`, `rocket`, `battery`, `pin`, `mountain`, `cross`, `bolt`, `arrow`.
+- **Strokes** (7, packed centrelines for things with no interior): `check`, `wifi`, `pulse`, `xmark`, `percent`, `question`, `spiral`.
+- **Generated** (3, positions from maths, no outline): `globe`, `target`, `pyramid`.
+
+Composition helpers (also exported from `apexcharts/unit-shapes`):
+
+```js
+outlined(heart)                  // hollow twin: trace the outline instead of filling it (silhouettes only)
+heart.with({ order: 'cols' })    // variant: where each series band lands ('rows' | 'rowsUp' | 'cols' |
+                                 // 'colsRev' | 'centerOut' | 'centerIn'); battery fills like a charge
+                                 // meter because its order is 'cols'
+glyphs('1,024')                  // a number, drawn in that many dots (digits plus '-', '.', ',', ':')
+preview(heart, { series })       // render to a standalone SVG string, no chart and no DOM (build-time galleries)
+shapeFrom(path, opts?)           // your own outline, packed like the catalog's
+strokeFrom(path, opts?)          // your own centreline
+registerShapes([...])            // register so positions: '<name>' resolves by string
+```
+
+Every shape carries metadata on `shape` (category, kind, and `minUnits`: the count below which it stops being recognisable; asking for fewer logs a console warning naming the shape). From a script tag, `dist/unit-shapes.js` exposes the kit as the global `ApexUnitShapes` with every shape pre-registered, so `positions: 'heart'` works by name.
+
+**Outer name labels (v6.10):** a shape packed with several categories can name them in the margin with a leader line to their own dots (the pie/donut outer-label mechanism), instead of needing a legend:
+
+```js
+plotOptions: {
+  unit: { clusterLabels: { external: { show: true } } },
+}
+```
+
+`clusterLabels.external` also takes `connector: { show, width, color, gap, length }`, `offsetX`, `offsetY`. It applies to `layout: 'custom'` only and reads best on silhouettes whose category bands stack vertically. The gutter is reserved before the dot size is chosen, so the shape stays centred but renders slightly smaller.
+
+`waffle` is a thin alias of `unit` that presets the `grid` layout with square cells. With `grid.total: 100` the values are largest-remainder rounded to exactly 100 cells, so the grid reads as percentages. The original alias is preserved on the read-only `chart.requestedType`; an explicit `layout` or `shape` still wins.
+
+```js
+{
+  chart: { type: 'waffle', height: 360 },
+  series: [35, 23, 15, 9, 8, 6, 4],
+  labels: ['Coal', 'Gas', 'Hydro', 'Nuclear', 'Wind', 'Solar', 'Other'],
+  plotOptions: { unit: { grid: { columns: 10, total: 100 } } }
+}
+```
+
+A parliament (hemicycle) seat chart:
+
+```js
+{
+  chart: { type: 'unit', height: 320 },
+  series: [120, 95, 60, 25],
+  labels: ['Party A', 'Party B', 'Party C', 'Party D'],
+  plotOptions: {
+    unit: {
+      layout: 'arc',
+      arc: { startAngle: -90, endAngle: 90, innerRadiusRatio: 0.4, rows: 'auto' }
+    }
+  }
+}
+```
+
 ---
 
 ## Key plotOptions
@@ -105,12 +267,25 @@ plotOptions: {
   pie: {
     startAngle: 0,
     endAngle: 360,
-    expandOnClick: true,       // expand slice on click
+    expandOnClick: true,       // react to a slice click at all
+    expandOffset: 10,          // (v6.9) how far the clicked slice slides out (px) along its mid-angle.
+                               // The slice is translated, not redrawn bigger, so the quantity it
+                               // encodes is unchanged. 0 keeps it in place. Ignored for polarArea.
+    hoverOutline: {            // (v6.9) hover traces a translucent band outside the slice rim
+      show: true,              // instead of lightening the fill
+      size: 8,                 // band thickness (px)
+      gap: 0,                  // clearance between slice rim and band (px)
+      opacity: 0.3,
+      color: undefined         // defaults to the hovered slice's own color
+    },
     offsetX: 0,
     offsetY: 0,
 
     customScale: 1,            // scale the pie (0.5 = half size)
 
+    borderRadius: 0,           // (v6.7) round each slice's corners (px). Applies to pie, donut, polarArea
+    spacing: 0,                // (v6.7) gap between adjacent slices (px). Applies to pie, donut, polarArea
+
     dataLabels: {
       offset: 0,               // move labels away from center
       minAngleToShowLabel: 10   // hide labels on tiny slices
@@ -266,3 +441,7 @@ plotOptions: {
 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.
+9. **Legend click now toggles the slice (v6.7 behavior change)**: on pie, donut, and polarArea a legend click hides and shows the slice (like other chart types). Previously it darkened and expanded the slice. If your app relied on the old darken-and-expand behavior, review this.
+10. **Expecting `unit` / `waffle` without a license to be watermark-free**: they are premium and render an `APEXCHARTS` watermark until an entitled `premium`/`enterprise` license is set. Sunburst, by contrast, is free.
+11. **Slice click behavior changed (v6.9)**: clicking a pie/donut slice now slides it out along its own mid-angle (`plotOptions.pie.expandOffset`, default 10 px) instead of darkening it and redrawing it at a larger radius, and hover traces an outline band (`plotOptions.pie.hoverOutline`) instead of lightening the fill. Set `expandOffset: 0` to keep slices in place; set `states.hover.filter.type: 'none'` to suppress the hover band.
+12. **Unit shapes below `minUnits`**: each `apexcharts/unit-shapes` shape declares the minimum dot count at which it still reads. Feeding fewer units logs a console warning naming the shape; pick a simpler shape or raise `unitValue` so the count lands above the threshold.

package/references/financial-charts.md

@@ -5,6 +5,7 @@
 - **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
+- **Histogram** (`'histogram'`, **new in v6.9**): Bins raw observations into columns; the series carries the sample, the chart does the aggregating
 
 ## Tree-Shakeable Import
 
@@ -15,8 +16,18 @@ import ApexCharts from 'apexcharts/candlestick'
 
 import ApexCharts from 'apexcharts/violin'
 // Registers: violin (separate entry point, new in v6)
+
+import ApexCharts from 'apexcharts/histogram'
+// Registers: histogram (v6.9), the bar engine plus the stats feature
+
+// The statistics (histogram binning, boxPlot/violin raw-sample summaries,
+// rowSeries()) live behind one optional feature. apexcharts/histogram already
+// includes it; boxPlot/violin raw samples need it explicitly when tree-shaking:
+import 'apexcharts/features/stats'
 ```
 
+**Raw samples (v6.9):** boxPlot, violin, and histogram can all take the raw observations and compute the statistics themselves (quartiles for boxPlot, KDE density for violin, bin counts for histogram). Precomputed summaries keep working exactly as before. With the full `apexcharts` bundle the stats feature is always present; with tree-shaking entries it must be imported (without it, a raw-sample boxPlot/violin datum has nothing to summarize and a histogram warns and draws nothing).
+
 ---
 
 ## Data Formats
@@ -72,11 +83,39 @@ The `y` value must be an array of exactly 5 numbers: `[min, Q1, median, Q3, max]
 }
 ```
 
+### Box Plot: Raw Sample (v6.9)
+
+Instead of a five-number `y`, a datum may supply the raw observations in `points` and the library computes the summary (quartiles interpolate between ranks, R type 7). Requires `apexcharts/features/stats` when tree-shaking. `points` is the same field used for the jitter-dot overlay, so the sample lives in one place whether you summarize it or the library does.
+
+```js
+{
+  chart: { type: 'boxPlot', height: 350 },
+  series: [{
+    data: [
+      { x: 'Phone', points: [1.2, 1.9, 3.4, 2.2, 2.8, 4.1, 1.7] },
+      { x: 'Tablet', points: [2.4, 3.1, 3.9, 2.9, 4.6, 3.3] }
+    ]
+  }],
+  plotOptions: {
+    boxPlot: {
+      whiskers: 'minmax',           // 'minmax' (default): whiskers reach the extremes, nothing hidden
+                                    // 'tukey': stop at the last observation within 1.5 × IQR of each quartile
+      points: { show: true }        // overlay the observations as jitter dots
+    }
+  }
+}
+```
+
+- `whiskers` only applies when the summary is **derived** from `points`; a precomputed five-number `y` is drawn exactly as given.
+- With `whiskers: 'tukey'`, observations beyond the fence fall outside the whisker, so pair it with `points: { show: true }` or they become invisible.
+- `plotOptions.boxPlot.points` also takes `shape` (`'circle'` | `'square'`), `size`, `jitter` (0..1 fraction of the box half-width), `maxPoints` (cap per box, stride-thinned beyond), `opacity`, `fillColor` (`'series-dark'` default | `'series'` | any color), `strokeColor`, `strokeWidth`, and a value-driven `colorScale: { colors, min, max, steps }`.
+- A datum with both `y` and `points` draws the given summary and overlays the points as jitter.
+
 ### 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.
+- `density`: an array of `[value, weight]` pairs describing the precomputed density/KDE profile. Drawn exactly as given.
 - `points` (optional): a flat array of raw observations, rendered as jitter dots.
 
 ```js
@@ -111,6 +150,32 @@ Each point is `{ x, y: { density, points } }`:
 }
 ```
 
+### Violin: Raw Sample (v6.9)
+
+A datum may instead supply only the raw observations (in `points`, no `y`) and the library derives the density itself via kernel density estimation. Requires `apexcharts/features/stats` when tree-shaking. `plotOptions.violin.kde` tunes the estimation; it is ignored when a precomputed `density` profile is given.
+
+```js
+{
+  chart: { type: 'violin', height: 420 },
+  series: [{
+    name: 'Session duration',
+    data: [
+      { x: 'Direct', points: [22, 31, 38, 41, 47, 52, 58, 33, 40] },
+      { x: 'Referral', points: [27, 34, 44, 48, 53, 61, 39] }
+    ]
+  }],
+  plotOptions: {
+    violin: {
+      kde: {
+        bandwidth: undefined,   // kernel width in value units; unset = Silverman's rule of thumb
+        resolution: 64          // density samples per violin (default 64)
+      },
+      points: { show: true }    // the same sample doubles as the jitter overlay
+    }
+  }
+}
+```
+
 **Orientation and per-category color come from `plotOptions.bar`** (violin reuses the bar renderer):
 
 ```js
@@ -123,6 +188,44 @@ plotOptions: {
 }
 ```
 
+### Histogram (v6.9)
+
+The series carries **raw observations** (a flat number array, or `{ y }` objects), one number per event; the chart chooses the bin width and counts them. It renders through the bar pathway (like funnel, pyramid, gauge, and waffle), so stacking, zoom, export, and animation all work on the bins. Import from `apexcharts/histogram`, or add `import 'apexcharts/features/stats'` alongside `apexcharts/bar`; the full `apexcharts` bundle already includes it. Without the stats feature the chart warns and draws nothing.
+
+```js
+{
+  chart: { type: 'histogram', height: 350 },
+  series: [{ name: 'Latency', data: [102, 87, 143, 91, 118, 95, 132, 88, 107] }],
+  plotOptions: {
+    histogram: {
+      bins: 'auto',        // 'auto' | 'fd' | 'sturges' | 'scott' | 'rice' | 'sqrt' | number (fixed count)
+                           // 'auto' takes the narrower of Freedman-Diaconis and Sturges
+      binWidth: undefined, // explicit bin width in value units; wins over `bins` when the
+                           // boundaries carry meaning (decades, 5-minute buckets)
+      range: undefined,    // [min, max] to bin over instead of the data's own extent
+      normalize: 'count',  // 'count' | 'relative' (percent of series total) | 'density' (total area = 1)
+      cumulative: false,   // running total across bins (a CDF)
+      overlap: true        // multi-series: draw each series across the full bin (overlay).
+                           // false = side-by-side grouped bars per bin
+    }
+  }
+}
+```
+
+- **All series share one set of bin edges** derived from their combined extent, so two distributions stay comparable instead of putting different bars at the same x.
+- `overlap: true` (the default with multiple series) also softens the fill and drops the bin separator stroke so the overlapping region reads; both remain overridable. A single series is unaffected either way.
+- Do NOT pass pre-aggregated counts; that is a plain `bar` chart. The histogram's job is the binning.
+
+### `rowSeries()`: the rows behind a summary mark (v6.9)
+
+A histogram bin, a box, and a violin all stand for rows the chart is already holding. `chart.rowSeries()` returns them as a unit-chart series (one cluster per mark, one datum per row), so a summary can be opened into its observations:
+
+```js
+chart.updateOptions({ chart: { type: 'unit' }, series: chart.rowSeries() })
+```
+
+Returns `null` when the current type has no row source or the stats feature is not loaded. `chart.rowSeries({ maxRows })` caps the dots produced (default 3000); past the cap every cluster is thinned by one shared stride so relative sizes survive. With the `morph` feature loaded, each dot animates out of the part of the mark that stood for it.
+
 ---
 
 ## Key plotOptions
@@ -206,9 +309,12 @@ plotOptions: {
 ## 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`.
+2. **Box Plot with wrong array length** — a summary `y` must be exactly 5 values `[min, Q1, median, Q3, max]`. Fewer or more values cause rendering errors. (Since v6.9 the alternative is no `y` at all: put the raw sample in `points` and the summary is computed.)
+3. **Using simple numeric array** — `data: [10, 20, 30]` does NOT work for candlestick/boxPlot. Each point requires an array in `y` (or, for boxPlot since v6.9, a raw sample in `points`). For a distribution of a flat number array, use `chart.type: 'histogram'` instead.
 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`.
+6. **Violin with a plain numeric `y`**: violin points need `y: { density: [[value, weight], ...] }` or (v6.9) raw observations in `points`, not a single number. With a precomputed `density` profile it is drawn exactly as given; with raw `points` the KDE runs for you (stats feature required when tree-shaking).
+7. **Violin orientation set on the wrong namespace**: horizontal violins and per-violin colors come from `plotOptions.bar` (`horizontal`, `distributed`), while `bandwidthScale`, `kde`, `normalize`, and `points` live under `plotOptions.violin`.
+8. **Feeding a histogram pre-binned counts**: the series must carry raw observations. If you already have counts per bucket, use a `bar` chart; a histogram would bin your counts as if they were measurements.
+9. **`whiskers: 'tukey'` on a precomputed boxPlot summary**: `plotOptions.boxPlot.whiskers` only applies when the summary is derived from `points`. A five-number `y` is drawn exactly as given.
+10. **Raw samples with tree-shaking but no stats feature**: `apexcharts/candlestick` and `apexcharts/violin` alone cannot summarize `points`. Add `import 'apexcharts/features/stats'` (the `apexcharts/histogram` entry and the full bundle already include it).

package/references/grid-charts.md

@@ -46,6 +46,49 @@ Each series is a row; each data point is a cell. The `y` value determines the co
 }
 ```
 
+#### Continuous numeric / datetime x-axis (v6.4)
+
+By default a heatmap tiles one cell per column by index. On a **numeric or datetime** x-axis (`xaxis.type: 'numeric'` or `'datetime'`), cells are instead placed at their real x value, so irregular spacing and gaps render as real empty space: a missing hour is a gap in the grid, not a squeezed column, and the axis shows sparse proportional ticks rather than one label per cell. Rows stay categorical (one series per row).
+
+```js
+{
+  chart: { type: 'heatmap', height: 350 },
+  xaxis: { type: 'datetime' },
+  series: [{
+    name: 'Server 1',
+    data: [
+      { x: new Date('2024-01-01T09:00').getTime(), y: 20 },
+      { x: new Date('2024-01-01T11:00').getTime(), y: 80 }, // 10:00 is absent -> real gap
+      { x: new Date('2024-01-01T12:00').getTime(), y: 65 }
+    ]
+  }]
+}
+```
+
+#### Canvas rendering for large heatmaps (v6.4)
+
+With `chart.renderer: 'canvas'` (or `'auto'` past `chart.rendererThreshold`) and the canvas feature imported, heatmap cells paint to a single canvas instead of one `<rect>` per cell, which is several times faster for large grids (roughly 3x at 50,000+ cells).
+
+```js
+import ApexCharts from 'apexcharts'
+import 'apexcharts/features/renderer-canvas'
+
+const options = {
+  chart: {
+    type: 'heatmap',
+    renderer: 'canvas',   // 'svg' | 'canvas' | 'auto'
+  },
+}
+```
+
+#### Heatmap default changes (v6.4)
+
+Three heatmap defaults changed in 6.4.0. Each is a default, not a removal:
+
+- **Tooltip anchored above the cell.** The heatmap tooltip now sits centered above the hovered cell with a downward arrow pointing at it (flipping below when the cell is against the top edge), instead of following the cursor.
+- **Zoom is off by default.** Re-enable with `chart.zoom: { enabled: true }` if you need it.
+- **Y-axis label thinning.** Dense y-axis (row) labels are thinned to fit.
+
 ### Treemap
 
 Flat list of `{ x, y }` where `x` is the label and `y` is the value (determines area).
@@ -90,6 +133,55 @@ Flat list of `{ x, y }` where `x` is the label and `y` is the value (determines
 }
 ```
 
+### Nested Treemap (v6.9)
+
+A datum may carry `children` to any depth; every branch is drawn as a real container with a header strip and its children inset below it, and a container's area is exactly the sum of its children. A branch normally omits `y` and takes the sum of its children; a leaf supplies one. Flat inputs are untouched and render identically to before.
+
+```js
+{
+  chart: { type: 'treemap', height: 400 },
+  series: [{
+    data: [
+      { x: 'Technology', children: [
+        { x: 'Software', children: [
+          { x: 'Acme Corp', y: 120 },
+          { x: 'Initech', y: 80 }
+        ] },
+        { x: 'Hardware', y: 95 }
+      ] },
+      { x: 'Energy', children: [
+        { x: 'Solar Co', y: 60 },
+        { x: 'Wind Ltd', y: 45 }
+      ] }
+    ]
+  }]
+}
+```
+
+Nested-specific options under `plotOptions.treemap`:
+
+```js
+plotOptions: {
+  treemap: {
+    nested: {
+      enabled: true,           // 'auto' behavior: parents appear as soon as the data is nested;
+                               // false forces the flat two-level layout
+      drilldownAsLevels: false // read `drilldown: '<id>'` ids on data points as extra levels
+                               // instead of as click targets for the drilldown feature.
+                               // Default false ("descend on click" is the historical meaning)
+    },
+    parents: {                 // how branch containers are drawn once the data is nested
+      show: 'auto'             // 'auto' (on when the data carries children) | true | false
+      // plus header/label styling and a tooltip.formatter receiving
+      // { name, value, depth, leafCount, percentOfParent, percentOfTotal, node, w }
+    },
+    levels: [ /* per-depth overrides of `parents`, indexed from the outermost drawn group */ ]
+  }
+}
+```
+
+The hierarchy resolver is shared with sunburst, including the `drilldown: '<id>'` adapter (opted into via `nested.drilldownAsLevels`).
+
 ---
 
 ## Key plotOptions
@@ -196,3 +288,4 @@ plotOptions: {
 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.
+5. **Nested treemap branch carrying its own `y` (v6.9)**: a branch node normally omits `y`; its area is the sum of its children. Only leaves supply values. Flattening a hierarchy by hand is no longer necessary; pass `children` instead.

package/references/tree-shaking.md

@@ -29,6 +29,7 @@ Each entry point registers a family of related chart types:
 | `apexcharts/candlestick` | candlestick, boxPlot |
 | `apexcharts/boxPlot` | same as /candlestick |
 | `apexcharts/violin` | violin *(new in v6)* |
+| `apexcharts/histogram` | histogram *(new in v6.9)*: the bar engine plus the stats feature |
 | `apexcharts/pie` | pie, donut, polarArea |
 | `apexcharts/donut` | same as /pie |
 | `apexcharts/polarArea` | same as /pie |
@@ -36,8 +37,11 @@ Each entry point registers a family of related chart types:
 | `apexcharts/radar` | radar |
 | `apexcharts/heatmap` | heatmap |
 | `apexcharts/treemap` | treemap |
+| `apexcharts/sunburst` | sunburst *(new in v6.7, free)* |
+| `apexcharts/unit` | unit, **waffle** *(new in v6.6, premium: watermarked until licensed)* |
+| `apexcharts/unit-shapes` | *(new in v6.10)* not a chart entry: named shape exports for the unit chart (`heart`, `house`, ... plus `outlined`, `glyphs`, `preview`), tree-shaken per shape (~4 KB gzipped each). See `references/circular-charts.md`. |
 
-**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.
+**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. `histogram` also renders through the bar engine but has its own `apexcharts/histogram` entry because it bundles the stats feature; `apexcharts/bar` + `import 'apexcharts/features/stats'` is equivalent.
 
 ### Using Multiple Chart Types
 
@@ -60,6 +64,7 @@ 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) |
+| Stats *(v6.9)* | `import 'apexcharts/features/stats'` | Histogram binning, boxPlot/violin raw-sample summaries, `rowSeries()` |
 | 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`) |
@@ -77,6 +82,8 @@ Features are optional modules that add functionality. When using per-type entrie
 
 **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.
 
+**Runtime dependency (v6.9):** ApexCharts is no longer dependency-free: it depends on `apex-commons` at runtime (license manager, crossfilter engine, spring primitives shared across the ApexCharts family). npm resolves it automatically, and the browser (script-tag) bundles inline it, so no configuration is needed; bundlers just see one more resolvable package. The `apexcharts/unit` and `apexcharts/unit-shapes` sub-entry points resolve for bundlers and script tags alike (from a script tag, `dist/unit-shapes.js` exposes the global `ApexUnitShapes`).
+
 ### What Happens If You Forget a Feature
 
 Features fail **silently**. If you use a per-type entry without importing legend:

package/references/v6-features.md

@@ -9,6 +9,50 @@ Two behaviors changed *on by default* (both respect `prefers-reduced-motion`):
 
 Also new by default: **`render()` is idempotent**: a repeated `render()` (e.g. a framework double-invoking an effect) returns the same promise instead of building a duplicate chart. `destroy()` clears it so an instance can render fresh.
 
+Two update behaviors worth knowing (both 6.9/6.10):
+
+- **Function-valued options are compared by identity (6.10)**: `update()` skips a redundant render by comparing the incoming options with the previous ones. Passing a *different* function (a new `dataLabels.formatter`, custom tooltip, `plotOptions.unit.positions`) gets the render it asked for; passing the *same* function twice still skips. Building a fresh closure on every update means a render every time.
+- **A type change re-chooses type defaults (6.9)**: `updateOptions({ chart: { type } })` now re-picks the defaults that decide what a chart reads, says, hit-tests, or offers as interaction (e.g. a boxPlot-to-violin switch gets the right tooltip formatter). Deliberate paint choices and anything you set yourself are never re-chosen.
+
+---
+
+## Licensing: premium features and the trial watermark
+
+Introduced in **6.5.0**, tightened in **6.7.0**. Not every v6 feature is free. Seven feature modules plus the `unit` / `waffle` chart type are **premium** and run under a lightweight, offline license check. They keep working fully without a key (trial mode), but the chart shows an unobtrusive `APEXCHARTS` watermark until an entitled license is set.
+
+**The premium set (watermarked until entitled):**
+
+- `storyboard` (scrollytelling)
+- `link` (crossfilter / linked views)
+- `ink` (annotation authoring)
+- `measure` (delta ruler)
+- `context-menu` (`contextMenu`)
+- `perspectives` (shareable view state)
+- `history` (undo/redo, Rewind)
+- the `unit` / `waffle` chart type (premium since **6.6.0**, the first premium chart type)
+
+**Everything else is free and never gated**: every other chart type (including `sunburst`), and every other module (Weave, Strata / canvas, Marks, Facet / themes, Cadence, drilldown, streaming, exports, legend, toolbar, annotations, keyboard).
+
+### Setting a license
+
+```js
+// Static: applies to every chart on the page. Call before render().
+ApexCharts.setLicense('APEX-...')
+
+// Per-chart: overrides the static key and window.Apex.license for this chart.
+const options = { chart: { license: 'APEX-...' } }
+```
+
+Both are typed: `ApexCharts.setLicense(key: string)` (static) and `chart.license?: string`.
+
+- **In use, not bundled.** Importing a premium module without actually enabling it does not watermark; only *using* it does.
+- **Live.** A late `setLicense(validKey)` followed by an update clears an on-screen watermark; no full re-render needed. The watermark is re-evaluated on every render/update.
+- **One key across the family.** The key format is shared across the ApexCharts family (apexgantt, apextree, apexsankey, apex-grid-enterprise, apexstock), validated offline with no network call. SSR-safe.
+
+### Plan entitlement (6.7.0 behavior change)
+
+As of **6.7.0** the premium features clear the watermark only on a `premium` or `enterprise` plan. A valid `pro` key, or the free tier, keeps them in trial mode with the watermark and logs a one-time upgrade notice (it is **not** treated as an invalid key). **Existing `pro`-plan customers using these features will now see the watermark.** No functionality is blocked in any case, the watermark is the only effect.
+
 ---
 
 ## Weave: public plugin platform
@@ -116,6 +160,8 @@ Dumbbell uses `dataType: 'rangeXY'` (datum `y` is `[start, end]`, both bounds fo
 
 `import 'apexcharts/features/history'`
 
+**Premium** (watermarked in trial mode until an entitled license is set, see Licensing above).
+
 Generic Ctrl-Z over a command journal. Zooms, series toggles, option changes, and annotation edits are recorded; high-frequency gestures coalesce into a single step.
 
 ```js
@@ -137,6 +183,8 @@ chart.history.entries()        // [{ id, label, at }]
 
 `import 'apexcharts/features/perspectives'`
 
+**Premium** (watermarked in trial mode until an entitled license is set, see Licensing above).
+
 Serialize the exact view (zoom window, hidden series, selection, annotations, theme) into a compact token you can put in a URL and restore anywhere.
 
 ```js
@@ -219,6 +267,8 @@ Built-in curve names: `linear`, `easeInSine`, `easeOutSine`, `easeInOutSine`, `e
 
 `import 'apexcharts/features/link'`
 
+**Premium** (watermarked in trial mode until an entitled license is set, see Licensing above).
+
 Coordinate a group of charts without wiring.
 
 ```js
@@ -255,6 +305,8 @@ const b = {
 
 `import 'apexcharts/features/ink'`
 
+**Premium** (watermarked in trial mode until an entitled license is set, see Licensing above).
+
 Annotations become draggable and resizable, with click-to-create, snap to gridlines, and a floating editor card (rename, recolor, bold, font size, marker size/shape, delete). Every edit is undoable when Rewind is enabled.
 
 ```js
@@ -277,6 +329,8 @@ const options = {
 
 `import 'apexcharts/features/measure'`
 
+**Premium** (watermarked in trial mode until an entitled license is set, see Licensing above).
+
 Hold a key and drag to read the change, percent, range, and slope between two points; on release the ruler pins as a data-anchored overlay that re-projects on zoom and resize.
 
 ```js
@@ -324,6 +378,8 @@ const options = {
 
 `import 'apexcharts/features/context-menu'`
 
+**Premium** (watermarked in trial mode until an entitled license is set, see Licensing above).
+
 Right-click or long-press a data point for actions that operate at that exact point.
 
 ```js
@@ -350,6 +406,8 @@ Built-in `annotate` / `xline` / `yline` items are ink-managed when the ink featu
 
 `import 'apexcharts/features/storyboard'` (includes Perspectives)
 
+**Premium** (watermarked in trial mode until an entitled license is set, see Licensing above).
+
 Pair prose sections with saved views. Scrolling a beat past the viewport trigger applies its view; scrolling back reverses it. A beat can also merge an `options` payload to restyle or morph `chart.type` inside one animated transition.
 
 ```js
@@ -386,7 +444,7 @@ const options = { chart: { streaming: { enabled: true, maxPoints: 100000 } } }
 
 `import 'apexcharts/features/drilldown'` (add `import 'apexcharts/features/morph'` for animated cross-type transitions)
 
-Data points reference a child level via a `drilldown` id; clicking drills in, with an optional breadcrumb.
+Data points reference a child level via a `drilldown` id; clicking drills in, with an optional breadcrumb. Since **v6.9** drilldown also works on **line and area** charts, and levels can be resolved **async** against a backend.
 
 ```js
 import 'apexcharts/features/drilldown'
@@ -404,14 +462,23 @@ const options = {
     series: [
       { id: '2021', name: '2021 by Channel', data: [/* ... */], chart: { type: 'bar' } },
     ],
-    // or resolve lazily:
-    onDrillDown: (ctx) => ({ id: ctx.point.drilldown, name: '...', data: [] }),
+    // or resolve lazily; may return a Promise (v6.9):
+    onDrillDown: async (ctx) => ({ id: ctx.point.drilldown, name: '...', data: await fetchLevel(ctx) }),
+    loading: { show: true, text: 'Loading' }, // (v6.9) overlay while an async level resolves;
+                                              // false disables it. role="status", aria-live="polite",
+                                              // spinner flattens to a pulse under prefers-reduced-motion
+    cache: true,                              // (v6.9) cache onDrillDown results by id (default true);
+                                              // clear with the drilldown module's clearCache()
+    // (v6.9) line/area only: the dot marking a drillable point when the chart
+    // draws no markers. Only drillable points get one, so it reads as "these open".
+    marker: { show: true, size: 6, shape: 'circle', fillColor: undefined, strokeColor: '#fff' },
   },
   chart: {
     events: {
       drillDownStart: (info, chart, options) => {},
       drillDownEnd: (info, chart, options) => {},
       drillUp: (info, chart, options) => {},
+      drillDownError: ({ id, error }, chart, options) => {}, // (v6.9) async level failed
     },
   },
 }
@@ -421,6 +488,50 @@ chart.drillUp()
 chart.drillToRoot()
 ```
 
+**Async failure semantics (v6.9):** a failed fetch never strands the view. On a throw, a rejection, or a resolver returning something without a `data` array, the chart stays where it was, the breadcrumb is untouched, nothing is cached, and `drillDownError` fires. A second click while one resolve is in flight is ignored rather than starting a second request.
+
+---
+
+## Stats: raw-sample statistics (6.9.0)
+
+`import 'apexcharts/features/stats'`
+
+Free. The statistics behind three things, kept out of core so they cost nothing unless used:
+
+- **Histogram binning**: `chart.type: 'histogram'` bins raw observations (the `apexcharts/histogram` entry includes this feature automatically).
+- **Raw samples for boxPlot and violin**: a datum supplying `points: [number]` instead of a summary `y` gets its quartiles (R type 7) or KDE density computed.
+- **`chart.rowSeries(opts?)`**: returns the rows behind the chart's marks as a unit-chart series (one cluster per mark), or `null` when the type has no row source. `chart.updateOptions({ chart: { type: 'unit' }, series: chart.rowSeries() })` opens a summary into its observations; with the `morph` feature loaded each dot leaves from the part of the mark that stood for it.
+
+Full data shapes and options are in `references/financial-charts.md`. The full `apexcharts` bundle includes it.
+
+---
+
+## Point annotation tooltips (6.7.0)
+
+`import 'apexcharts/features/annotations'` (free, part of the standard annotations module)
+
+A point annotation can now show its own hover tooltip, so an annotated marker carries explanatory text without a separate custom element. Add `tooltip` to any entry in `annotations.points`:
+
+```js
+const options = {
+  annotations: {
+    points: [{
+      x: 'Mar',
+      y: 62,
+      marker: { size: 6, fillColor: '#FF4560' },
+      label: { text: 'Peak' },
+      tooltip: {
+        enabled: true,
+        text: 'All-time high: 62',   // string, or an array joined with line breaks; falls back to label.text
+        // formatter: (opts) => `<b>${opts.annotation.label.text}</b>`  // HTML, takes precedence over text
+      },
+    }],
+  },
+}
+```
+
+`tooltip.formatter` receives `{ annotation, seriesIndex, id, ... }` and returns HTML.
+
 ---
 
 ## Common Pitfalls