apexcharts-skill 3.0.0 → 3.1.0

package/SKILL.md

@@ -5,7 +5,7 @@ description: >
   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, histogram, radar, polarArea, rangeBar, rangeArea, treemap, funnel, pyramid, gauge,
-  sunburst, unit, waffle, waterfall, dumbbell, streamgraph, raincloud). Covers
+  sunburst, icicle, unit, waffle, waterfall, dumbbell, streamgraph, raincloud). Covers
   correct data formats, lifecycle, formatters, tree-shaking, SSR, and the feature
   platform (plugins, canvas renderer, custom series, small multiples, undo/redo,
   shareable views, themes, crossfilter, annotation authoring, storyboard, streaming,
@@ -15,8 +15,8 @@ description: >
   (`react-apexcharts`, `vue3-apexcharts`, `ng-apexcharts`) over the core API.
 metadata:
   author: ApexCharts
-  version: "3.0.0"
-  library_version: "7.1.0"
+  version: "3.1.0"
+  library_version: "7.6.1"
   category: data-visualization
   tags: [charts, visualization, javascript, typescript, svg, apexcharts]
   docs: https://apexcharts.com/docs/
@@ -58,13 +58,13 @@ metadata:
 > | Rewind (undo / redo) | `apexcharts/features/history` | 3.2 KB |
 > | Context menu | `apexcharts/features/context-menu` | 2.3 KB |
 >
-> The `raincloud` chart type (7.1) is Tier 2 on the same terms: `import 'apexcharts/raincloud'`. Storyboard registers Perspectives, so importing both costs no more than Storyboard alone. **Nothing fails silently**: each warns in the console when its config is present but the module is not, and degrades where it can (a trellis renders as one chart; `renderer: 'canvas'` falls back to SVG). Default bundle: 291,654 B gzipped in 6.10, 252,005 B in 7.0, 264,326 B in 7.1.
+> The `raincloud` chart type (7.1) is Tier 2 on the same terms: `import 'apexcharts/raincloud'`. Storyboard registers Perspectives, so importing both costs no more than Storyboard alone. **Nothing fails silently**: each warns in the console when its config is present but the module is not, and degrades where it can (a trellis renders as one chart; `renderer: 'canvas'` falls back to SVG). Default bundle: 291,654 B gzipped in 6.10, 252,005 B in 7.0, 264,326 B in 7.1, about 270 KB in 7.6.
 >
-> Everything else stays in the default bundle: **all chart types except raincloud**, axes, tooltips, legend, toolbar, exports, annotations, keyboard navigation, stats, morph, drilldown, themes (Facet), plugins (Weave) and custom series (Marks). See `references/tree-shaking.md` for the full tier table and `references/feature-platform.md` for each feature's API.
+> Everything else stays in the default bundle: **all chart types except `raincloud` and `icicle`**, axes, tooltips, legend, toolbar, exports, annotations, keyboard navigation, stats, morph, drilldown, themes (Facet), plugins (Weave) and custom series (Marks). See `references/tree-shaking.md` for the full tier table and `references/feature-platform.md` for each feature's API.
 >
-> **Other v7.0 breaking changes.** (1) `plotOptions.bar.borderRadiusWhenStacked` is **removed**; corner ownership now follows the stack's outer edge automatically. An unknown option is ignored, so leaving it in a config is harmless but does nothing. (2) `dataLabels.animate.enabled` now defaults to `true` (bar/column only): labels ride to their new position on a data update instead of snapping. Set `dataLabels: { animate: { enabled: false } }` for the old behavior. Everything else from v5 and v6 keeps working unchanged.
+> **Other v7.0 breaking changes.** (1) `plotOptions.bar.borderRadiusWhenStacked` was dropped as dead config in v7.0 and is a **working option again in v7.4**: `'all'` (the default) rounds both stack ends, `'last'` rounds only the far end and leaves the baseline square. Do not delete it from a config. (2) `dataLabels.animate.enabled` now defaults to `true` (bar/column only): labels ride to their new position on a data update instead of snapping. Set `dataLabels: { animate: { enabled: false } }` for the old behavior. Everything else from v5 and v6 keeps working unchanged.
 >
-> **Behaviors that are on by default** (both respect `prefers-reduced-motion`): data updates that add/remove points animate coherently, and mobile pinch-zoom / two-finger pan gestures are enabled.
+> **Behaviors that are on by default** (both respect `prefers-reduced-motion`): data updates that add/remove points animate coherently, and one-finger kinetic pan is enabled (`chart.pan.inertia`). The two-finger gestures, pinch-zoom and two-finger pan, sit behind `chart.zoom.pinch`, which defaults to `'auto'`: **on only where the toolbar reset button is present**, so an unintended zoom is always undoable. `chart.zoom.allowMouseWheelZoom` is gated the same way. Set `pinch: true` to force the gestures on a toolbar-less chart, or see `chart.zoom.resetControl` (v7.4) for the other way to satisfy the gate.
 >
 > **Premium features and licensing.** Eight features are premium: `trellis` (small multiples, 7.0), `storyboard`, `link` (crossfilter / linked views), `ink` (annotation authoring), `measure`, `context-menu`, `perspectives` (shareable views), and `history` (undo/redo). Two chart types are premium: `unit` / `waffle`, and `raincloud` (7.1). 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`. 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. Note that premium and Tier 2 are independent axes: `waterfall`, `dumbbell` and `streamgraph` are free *and* in the default bundle, while `trellis` is both premium *and* an explicit import. See the Licensing section in `references/feature-platform.md`.
 
@@ -81,7 +81,7 @@ metadata:
 9. **For mixed/combo charts**, set `type` on each individual series object, not just on `chart.type`.
 10. **RadialBar values must be 0–100** (they represent percentages).
 11. **Color hex values must include the `#` prefix** (e.g., `'#FF5733'`, not `'FF5733'`).
-12. **Nine features are NOT in the v7 default bundle.** Before writing config for `trellis`, `storyboard`, `perspectives`, `ink`, `renderer: 'canvas'`, `link`, `measure`, `history` or the context menu, add its `apexcharts/features/*` import. Same for the `raincloud` chart type. Full-bundle users need this too, not just tree-shakers. See the box above.
+12. **Nine features are NOT in the v7 default bundle.** Before writing config for `trellis`, `storyboard`, `perspectives`, `ink`, `renderer: 'canvas'`, `link`, `measure`, `history` or the context menu, add its `apexcharts/features/*` import. Same for the `raincloud` and `icicle` chart types, which are not in the default bundle either. Full-bundle users need this too, not just tree-shakers. See the box above.
 13. **Tree-shaking**: importing `apexcharts/core` gives you a bare class, and you must also import chart-type entries and feature entries separately.
 14. **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.
 15. **`violin` (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).
@@ -139,7 +139,9 @@ These use a **flat number array** for `series`, NOT the object format:
 
 **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)
+### Hierarchical Charts (sunburst, icicle)
+
+Both take the same tree, and the choice between them is a layout one: a sunburst spends the plot radially, an icicle spends it along a straight axis.
 
 **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:
 
@@ -160,12 +162,26 @@ These use a **flat number array** for `series`, NOT the object format:
 
 Configure the centre hole, corner rounding, and inter-arc gap through `plotOptions.sunburst` (see `references/circular-charts.md`).
 
+**Icicle *(v7.6, free, opt-in import)*** is the same partition in cartesian coordinates: one band per depth level, each child sized inside its parent's extent. Same data shape as the sunburst, and it also reads an existing `drilldown` config as plain data (no drilldown runtime needed). Labels stay horizontal at every depth and same-depth siblings line up across branches, which is what makes it the better pick for deep trees, call stacks and path funnels.
+
+```js
+import ApexCharts from 'apexcharts/icicle'   // NOT in the default bundle
+
+{
+  chart: { type: 'icicle' },
+  series: [{ data: [ /* the same { x, y, children } tree as above */ ] }],
+  plotOptions: { icicle: { direction: 'up' } }   // flame-graph orientation
+}
+```
+
+A branch may omit its own `y` and be the sum of its children *(fixed in v7.6 for both partition types)*. Configure depth direction, band thickness, leaf behaviour and zoom through `plotOptions.icicle` (see `references/grid-charts.md`).
+
 ---
 
 ## 3. Package / Module Map
 
 ```
-# Default bundle (every chart type except raincloud, plus the Tier 1 features)
+# Default bundle (every chart type except raincloud and icicle, plus the Tier 1 features)
 import ApexCharts from 'apexcharts'
 
 # Bare core (no chart types, no optional features — must register manually)
@@ -196,6 +212,7 @@ 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/icicle'        # icicle (v7.6, hierarchical): opt-in, NOT in the default bundle
 import ApexCharts from 'apexcharts/unit'          # unit + waffle (v6.6, premium)
 # funnel + pyramid render through the bar engine; use apexcharts/bar
 
@@ -241,7 +258,7 @@ import ApexCharts from 'apexcharts/ssr'    # Node.js: renderToString, renderToHT
 import ApexCharts from 'apexcharts/client' # Browser: explicit client import for hydration
 ```
 
-**Note (v7):** `apexcharts` gives you every chart type except `raincloud`, plus the Tier 1 features. The nine Tier 2 features and `raincloud` need their own import **whatever entry point you started from**. `apexcharts/features/all` is the Tier 1 set, so it is not a shortcut past this. Tree-shaking entries (`/core`, `/line`, etc.) are for reducing bundle size below the default.
+**Note (v7):** `apexcharts` gives you every chart type except `raincloud` and `icicle`, plus the Tier 1 features. The nine Tier 2 features, `raincloud` and `icicle` need their own import **whatever entry point you started from**. `apexcharts/features/all` is the Tier 1 set, so it is not a shortcut past this. Tree-shaking entries (`/core`, `/line`, etc.) are for reducing bundle size below the default.
 
 **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.
 
@@ -416,6 +433,12 @@ Also: do NOT use `xaxis.categories` when your data already has `{ x, y }` format
 { tooltip: { shared: false, intersect: true } }
 ```
 
+**Reaching content inside a `custom` tooltip *(v7.6)***: a tooltip closes as the pointer leaves the data point, so a link or button returned by `custom` can never be clicked. `tooltip.interactive: true` holds it open while the pointer is over it. It is off by default, and while it is on `followCursor` is **ignored** (a tooltip that trails the cursor retreats from every approach); the configured `followCursor` value is left alone and applies again the moment `interactive` goes back off.
+
+```js
+{ tooltip: { interactive: true, custom: ({ seriesIndex }) => `<a href="/detail/${seriesIndex}">Open</a>` } }
+```
+
 ### Pitfall 7: Wrong formatter signatures
 
 ❌ **WRONG** — using y-axis formatter signature for tooltip:
@@ -551,26 +574,20 @@ import ApexCharts from 'apexcharts'
 import 'apexcharts/features/trellis'
 ```
 
-Same for `storyboard`, `perspectives`, `ink`, `renderer: 'canvas'`, `link`, `measure`, `history`, `contextMenu`, and the `raincloud` chart type. Check the console: each one names both import routes when its config is present without it.
+Same for `storyboard`, `perspectives`, `ink`, `renderer: 'canvas'`, `link`, `measure`, `history`, `contextMenu`, and the `raincloud` chart type. Check the console: each one names both import routes when its config is present without it. `icicle` is the exception to the "warns and degrades" rule: an unregistered chart type **throws**, and the thrown message names both routes.
 
 ### Pitfall 15: SSR — wrong import path
 
-❌ **WRONG** — using browser bundle in Node.js:
-```js
-// On server:
-import ApexCharts from 'apexcharts'
-await ApexCharts.renderToString(options)  // renderToString doesn't exist!
-```
-
-✅ **CORRECT** — use SSR entry point:
+`apexcharts` resolves by environment: the `"."` export's `node` condition points at the SSR bundle, so `import ApexCharts from 'apexcharts'` on a server **does** carry `renderToString` / `renderToHTML`. Import `apexcharts/ssr` explicitly anyway, so the intent survives a bundler that resolves the `browser` condition while targeting Node:
 ```js
 // On server:
 import ApexCharts from 'apexcharts/ssr'
 const svg = await ApexCharts.renderToString(options)
 
-// On client (for hydration):
+// On client (for hydration): target the wrapper renderToHTML emitted,
+// which carries data-apexcharts-hydrate and NO id.
 import ApexCharts from 'apexcharts'  // or 'apexcharts/client'
-ApexCharts.hydrate(document.querySelector('#chart'))
+ApexCharts.hydrateAll()  // or hydrate(document.querySelector('[data-apexcharts-hydrate]'))
 ```
 
 ### Pitfall 16: updateOptions vs updateSeries vs appendData
@@ -729,7 +746,7 @@ Every feature below is off by default in config terms. The **Tier** column is ab
 
 | Feature | Tier | Import | One-liner |
 |---|---|---|---|
-| **Weave** (plugins) | 1 | `apexcharts/features/weave` | Publish reusable chart plugins against a stable `ApexCharts.registerPlugin({ name, setup })` API; activate per chart with `plugins: [{ name }]`. |
+| **Weave** (plugins) | 1 | `apexcharts/features/weave` | Publish reusable chart plugins against a stable `ApexCharts.registerPlugin({ name, setup })` API; activate per chart with `plugins: [{ name }]`. Contract is at **v6** (v7.5): `info`/`categories`/`markDerived` (v2), `reserve` (v3), `pointer` (v4), `claim`/`drawn`/`declare`/`can` (v6). Declare the **lowest** `apiVersion` you can run on and feature-detect the rest: a host older than the version you declare skips your plugin outright. |
 | **Marks** (custom series) | 1 | `apexcharts/features/marks` | `ApexCharts.registerSeriesType(name, { renderItem })` for first-class custom marks (lollipop, bullet). Baseline is `scales.y(0)`, **not** `api.zeroY`. |
 | **Facet** (themes/tokens) | 1 | `apexcharts/features/facet` | `theme: { follow: 'os', name }`, `--apx-*` CSS custom props, `ApexCharts.registerTheme`. |
 | **Drilldown** | 1 | `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. |
@@ -759,7 +776,7 @@ For detailed chart-family-specific options, data format variants, and full worki
 | Bar, Column, Range Bar, Timeline/Gantt, Funnel, Pyramid, Waterfall, Dumbbell | `references/bar-charts.md` |
 | Candlestick, Box Plot, Violin, Histogram, Raincloud | `references/financial-charts.md` |
 | Pie, Donut, Polar Area, Radial Bar, Gauge, Sunburst, Unit, Waffle, Pictograms | `references/circular-charts.md` |
-| Heatmap, Treemap | `references/grid-charts.md` |
+| Heatmap (incl. cell shapes), Treemap, Icicle | `references/grid-charts.md` |
 | Radar | `references/radar-charts.md` |
 | Feature platform (small multiples, plugins, canvas, undo/redo, themes, crossfilter, storyboard, ...) | `references/feature-platform.md` |
 | Bundle tiers, Tree-shaking, Bundle optimization | `references/tree-shaking.md` |

package/package.json

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

@@ -304,7 +304,7 @@ plotOptions: {
     distributed: false,       // true = different color per data point
     borderRadius: 4,          // rounded corners (number or object)
     borderRadiusApplication: 'end',  // 'end' | 'around'
-    // borderRadiusWhenStacked was REMOVED in v7.0, see the note below
+    borderRadiusWhenStacked: 'all',  // 'all' (default) | 'last'; stacked bars only, see the note below
 
     dataLabels: {
       position: 'top',        // 'top' | 'center' | 'bottom'
@@ -322,7 +322,12 @@ plotOptions: {
 }
 ```
 
-**⚠️ `borderRadiusWhenStacked` was removed in v7.0.** Rounded corners on a stacked bar are no longer a setting: corner ownership follows the **outer edge** of the stack, which is what `'last'` approximated and what `'all'` got wrong on any stack whose last series was empty. An unknown option is ignored, so leaving it in a config is harmless but does nothing. Delete it. Related v7.0 fixes: a stacked bar's bottom cap is now the top-rounded path mirrored (caps no longer invert or pop when a series collapses and rises again), and grouped stacked charts resolve caps per group rather than chart-wide, so every group gets its own bottom and top radius.
+**⚠️ `borderRadiusWhenStacked`: dropped in v7.0, restored working in v7.4.** v7.0 removed it as dead config (it had not been read for some time) and let corner ownership follow the stack's **outer edge** automatically. v7.4 made it a real option again, so at v7.4+ it is live and must not be deleted from a config:
+
+- `'all'` (the default) keeps the v7.0 look, both ends of the stack rounded. Existing charts are unchanged.
+- `'last'` rounds only the far end and leaves the baseline square.
+
+A stack of a single data point also stopped rounding its baseline in v7.4, which on a horizontal 100% stack with one category used to round the first segment on its inner edge. Related v7.0 fixes: a stacked bar's bottom cap is now the top-rounded path mirrored (caps no longer invert or pop when a series collapses and rises again), and grouped stacked charts resolve caps per group rather than chart-wide, so every group gets its own bottom and top radius.
 
 **⚠️ `dataLabels.animate.enabled` now defaults to `true` (v7.0), bar/column only.** Labels ride to their new position on a data-change update instead of snapping there, so they reflow on the same clock as the bars, markers and axis ticks. A label that has not moved is a per-label no-op; speed and easing follow `chart.animations.dynamicAnimation`. For the pre-v7 behavior:
 
@@ -332,7 +337,7 @@ dataLabels: { animate: { enabled: false } }
 
 ### 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`.
+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 `dataLabels` flags complete the effect, both **bar / column only**: `animate.enabled` is **on by default** since v7.0 (it was opt-in before), and `countUp.enabled` is off. their speed and easing follow `chart.animations.dynamicAnimation`.
 
 ```js
 const options = {
@@ -428,5 +433,5 @@ series: [{
 8. **Pre-computing the running total for a waterfall** *(v7.1)*: the series carries the **deltas**; the chart accumulates. Feeding it cumulative values draws each bar from zero to the total, which is a column chart with extra steps.
 9. **Giving a waterfall subtotal row a `y`** *(v7.1)*: `isSubtotal` / `isTotal` rows are measured for you. Supply `x` and the flag, nothing else.
 10. **Zipping dumbbell values into `y: [lo, hi]`** *(v7.1)*: that is the older `plotOptions.bar.isDumbbell` range-bar form. `chart.type: 'dumbbell'` wants one series per measure, each with plain `{ x, y }` points.
-11. **Setting `borderRadiusWhenStacked`**: removed in v7.0. The option is ignored; stacked corner ownership follows the stack's outer edge automatically.
+11. **Assuming `borderRadiusWhenStacked` is still removed**: it was dead config in v7.0 through v7.3 and is a working option again from v7.4 (`'all'` default, `'last'` to leave the baseline square). Guidance written for v7.0 says to delete it; on v7.4+ that silently reverts a deliberate `'last'` to `'all'`.
 12. **Expecting data labels to snap on update** *(v7.0)*: `dataLabels.animate.enabled` now defaults to `true` on bar/column. Set it to `false` for the old behavior.

package/references/cartesian-charts.md

@@ -254,6 +254,25 @@ xaxis: {
 }
 ```
 
+### A way out of a zoom when the toolbar is hidden (v7.4)
+
+Hiding the toolbar does not disable drag-to-zoom (a drag is a deliberate gesture, unlike the wheel and the pinch), so a viewer can zoom a bare chart and then have nothing on screen that puts the range back.
+
+```js
+chart: {
+  toolbar: { show: false },
+  zoom: { enabled: true, resetControl: 'auto' }   // 'auto' is the default
+}
+```
+
+While the chart **is** zoomed and nothing else can reset it, one reset control is drawn where the toolbar would have been, and it goes when the range does. `Escape` resets under the same gate, and the event is left alone so a page listening for it still hears it.
+
+- `'auto'` (default): supply both only where there is no reset button already. A chart nobody zooms is untouched, so `toolbar: { show: false }` still means an empty chart for every viewer who does not zoom.
+- `true`: also force the control on where `toolbar.tools.reset` is off, which is the same dead end as a hidden toolbar.
+- `false`: turn off both the control and the key, for a page that supplies its own reset.
+
+Requires `zoom.enabled: true`. A completed drag-zoom now also focuses the chart, so the `+`, `-` and `0` keys are reachable straight after a mouse zoom.
+
 ---
 
 ## Complete Working Example — Line Chart with Datetime

package/references/circular-charts.md

@@ -155,6 +155,10 @@ A sunburst draws a hierarchy as concentric rings: the first level fills a donut
 
 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.
 
+A branch may **omit its own `y`** and be the sum of its children. That is the documented shape, but it only began working in v7.6: before that the non-axis parser required every datum to carry `x` and `y`, so a branch with only `children` was dropped, the series came back empty, and the chart drew nothing while warning about pie data. The samples all gave their top-level nodes a `y`, which is what hid it from the moment sunburst shipped.
+
+**The same tree in cartesian coordinates** is the `icicle` type *(v7.6)*: one band per depth level instead of concentric rings, labels horizontal at every depth, and `direction: 'up'` for flame graphs. It is an opt-in import. See `references/grid-charts.md`.
+
 ### 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/feature-platform.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.

package/references/feature-platform.md

@@ -7,7 +7,7 @@ ApexCharts ships an opt-in feature platform on top of the chart core. **Every v5
 Whether you need the `features/*` import depends on the feature's **tier**, and this changed in v7.0.
 
 - **Tier 1** is in the default `import ApexCharts from 'apexcharts'` bundle: `exports`, `legend`, `toolbar`, `annotations`, `keyboard`, `morph`, `drilldown`, `weave`, `marks`, `facet`, `stats`, and the v7.1 `waterfall` / `dumbbell` / `streamgraph` chart types. Import these only if you started from `apexcharts/core` or a per-type entry.
-- **Tier 2 is not in any bundle.** Nine features (`trellis`, `storyboard`, `perspectives`, `ink`, `renderer-canvas`, `link`, `measure`, `history`, `context-menu`) plus the `raincloud` chart type require an explicit import **whatever entry point you used**, the full bundle included.
+- **Tier 2 is not in any bundle.** Nine features (`trellis`, `storyboard`, `perspectives`, `ink`, `renderer-canvas`, `link`, `measure`, `history`, `context-menu`) plus the `raincloud` (premium) and `icicle` (free) chart types require an explicit import **whatever entry point you used**, the full bundle included.
 
 ```js
 import ApexCharts from 'apexcharts'
@@ -20,11 +20,11 @@ import 'apexcharts/features/trellis'   // Tier 2: required even here
 
 Nothing fails silently: each Tier 2 module warns in the console when its configuration is present but the module is not, and names both import routes. Where the chart can still draw something sensible it does and says what it did: a trellis renders as a single chart, `renderer: 'canvas'` falls back to SVG. `apexcharts/features/all` is the **Tier 1** set and is not a shortcut past this.
 
-Why: 24% of the 6.10.0 default bundle was licence-gated premium code that an unlicensed user could only run watermarked, and everybody downloaded it. The default bundle went 291,654 B gzipped (6.10.0) to 252,005 B (7.0.0), and 264,326 B in 7.1.0 with the three new free chart types. See `references/tree-shaking.md` for the full tier table and per-module sizes.
+Why: 24% of the 6.10.0 default bundle was licence-gated premium code that an unlicensed user could only run watermarked, and everybody downloaded it. The default bundle went 291,654 B gzipped (6.10.0) to 252,005 B (7.0.0), and 264,326 B in 7.1.0 with the three new free chart types. It is about 270 KB at 7.6.1 (measured on the shipped dist with gzip -9; the upstream build report gzips at a different level and prints a few hundred bytes more). See `references/tree-shaking.md` for the full tier table and per-module sizes.
 
 ## Two v7.0 breaking changes
 
-1. **`plotOptions.bar.borderRadiusWhenStacked` is removed.** Rounded corners on a stacked bar are no longer a setting: corner ownership follows the **outer edge** of the stack, which is what `'last'` approximated and what `'all'` got wrong on any stack whose last series was empty. An unknown option is ignored, so leaving it in place is harmless but does nothing.
+1. **`plotOptions.bar.borderRadiusWhenStacked` was dropped in v7.0, and came back working in v7.4.** In v7.0 it had not been read for some time and was removed as dead config, with corner ownership following the stack's **outer edge** automatically. v7.4 made it a real option again: `'all'` (the default) keeps that look with both stack ends rounded, and `'last'` rounds only the far end and leaves the baseline square. A one-point stack no longer rounds its baseline either. Treat it as live, not as legacy.
 2. **`dataLabels.animate.enabled` now defaults to `true`** (bar and column only). Labels ride to their new position on a data-change update instead of snapping there, so they reflow on the same clock as the bars, markers and axis ticks. Speed and easing follow `chart.animations.dynamicAnimation`. A label that has not moved is a per-label no-op. Set `dataLabels: { animate: { enabled: false } }` for the old behavior.
 
 ## Behaviors that are on by default
@@ -32,7 +32,7 @@ Why: 24% of the 6.10.0 default bundle was licence-gated premium code that an unl
 Carried over from v6, both respecting `prefers-reduced-motion`:
 
 1. **Coherent variable-length data transitions**: updates that add/remove data points animate as one coordinated motion instead of popping. Appended bars grow from the baseline, removed bars shrink and fade, line/area fills reshape over the union of old and new points, and markers/bubbles/axis labels ride along. Scatter and bubble now animate on dynamic updates for the first time. Disable per chart with `chart.animations.dynamicAnimation.enabled: false`; auto-skipped above `chart.animations.largeDatasetThreshold` (default 1000) and under `prefers-reduced-motion`.
-2. **Native-feeling mobile gestures**: two-finger pinch-zoom, two-finger pan, and kinetic inertia after a flick, with axis rails so a vertical swipe still scrolls the page. Configure via `chart.zoom.pinch` (default `true`) and `chart.pan.inertia` (default `true`, `friction` default `0.92`).
+2. **Native-feeling mobile gestures**: two-finger pinch-zoom, two-finger pan, and kinetic inertia after a flick, with axis rails so a vertical swipe still scrolls the page. Configure via `chart.zoom.pinch` (default `'auto'`) and `chart.pan.inertia` (default `true`, `friction` default `0.92`). **`'auto'` is not the same as `true`**: it enables pinch only where the toolbar reset button is present, so a zoom is always undoable. A chart with `toolbar: { show: false }` gets no pinch zoom until `pinch: true` forces it. `chart.zoom.allowMouseWheelZoom` is gated the same way, and `chart.zoom.resetControl` (v7.4) is the other half of that bargain.
 
 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.
 
@@ -60,7 +60,7 @@ Introduced in **6.5.0**, tightened in **6.7.0**. Not every feature is free. Eigh
 - the `unit` / `waffle` chart type (premium since **6.6.0**, the first premium chart type)
 - the `raincloud` chart type (premium since **7.1.0**)
 
-**Everything else is free and never gated**: every other chart type (`sunburst`, and the v7.1 `waterfall` / `dumbbell` / `streamgraph`), and every other module (Weave, Strata / canvas, Marks, Facet / themes, Cadence, drilldown, streaming, exports, legend, toolbar, annotations, keyboard, stats).
+**Everything else is free and never gated**: every other chart type (`sunburst`, the v7.1 `waterfall` / `dumbbell` / `streamgraph`, and the v7.6 `icicle`, which is an opt-in import but free), and every other module (Weave, Strata / canvas, Marks, Facet / themes, Cadence, drilldown, streaming, exports, legend, toolbar, annotations, keyboard, stats).
 
 **Premium and Tier 2 are independent axes.** Premium is about the watermark; Tier 2 is about the bundle. `renderer-canvas` is Tier 2 and free. `waterfall`, `dumbbell` and `streamgraph` are Tier 1 and free. `unit` / `waffle` is premium but Tier 1 (it is a chart type in the default bundle). `trellis` and `raincloud` are both.
 
@@ -181,13 +181,117 @@ The `setup(api)` facade:
 
 - `api.on(hook, fn)` / `api.off(hook, fn)`: hooks: `'afterParse' | 'afterScales' | 'draw' | 'afterUpdate' | 'destroy'`.
 - `api.layer(opts?)`: a plugin-owned drawing surface (`path`, `line`, `rect`, `circle`, `text`, `clear`); call it inside draw handlers only, layers are wiped each pass.
-- `api.scales` (readonly): `x(v)`, `y(v, axis?)`, `domainX`, `domainY(axis?)`, `gridWidth`, `gridHeight`, `ratios`.
-- `api.data` (readonly): `[{ name?, hidden, color?, points: [{ x, y }] }]`.
+- `api.scales` (readonly): `x(v)`, `y(v, axis?)`, `domainX`, `domainY(axis?)`, `gridWidth`, `gridHeight`, `ratios`. **`null` on a non-axis chart**, so it is a fact about the chart rather than about the host and is deliberately not a capability.
+- `api.data` (readonly): `[{ name?, hidden, color?, points: [{ x, y }], raw }]`.
 - `api.theme`: `{ mode, foreColor, seriesColor(i), token(name) }`.
 - `api.store`: per-instance mutable state bag.
 - `api.emit(name, detail?)`: dispatches `plugin:<name>:<event>` on the chart; `api.chart`, `api.el`, `api.name`, `api.version`, `api.options` round out the facade.
 
-`apiVersion` gates the contract so raw internals can keep changing safely.
+### Declare the lowest version you can run on, then feature-detect (v2+)
+
+`apiVersion` gates the contract so raw internals can keep changing safely, but it is **not** how you ask for a newer member. A plugin declaring a version **newer than the host is skipped outright**, so declaring the latest is how one build stops working on older hosts. Declare the lowest version your plugin can actually run on, and discover anything above that:
+
+```js
+// v6 hosts: ask by name.
+if (api.can('claim')) { /* ... */ }
+api.capabilities            // the whole frozen list, for logging and support
+
+// Older hosts, or a plugin that must run on both: probe the member.
+if (typeof api.pointer === 'function') { /* ... */ }
+```
+
+Each capability name is probed off the facade that was actually built, so a member that is ever made conditional drops out of the list instead of being advertised and then missing. Names are permanent once published.
+
+The version gate was an exact-match check before v2, which would have disabled every v1 plugin on the first additive change. It is forward-compatible now: an older plugin is served, and only one needing a newer host is skipped.
+
+### v2: know what you are attached to
+
+```js
+api.info          // { type, axisChart, datetimeX, horizontalBars,
+                  //   dataLabels: { enabled, enabledOnSeries },
+                  //   stroke: { dashArray },   // v5
+                  //   title }                  // v6, '' when untitled
+api.categories    // display labels per x position, resolved config-first
+api.data[0].raw   // the caller's own data array for that series, unparsed
+api.markDerived(['Revenue (forecast)'])   // these series are mine, not the caller's
+```
+
+- **`info` is how a plugin decides whether it applies at all**, instead of adding a series and letting the core warn at the user.
+- **Read `categories`, never `globals.categoryLabels`.** The globals are populated after a mount and empty after an `updateSeries()`, so reading them directly gives real labels on first paint and ordinals after any update.
+- **`raw` is fine to read and wrong to copy**: the three accepted data shapes are not interchangeable, so the normalised `points` are what you compute from.
+- **`markDerived` is not optional if the plugin adds series.** The core cannot tell a plugin's series from the caller's, and the host uses this to keep them out of the initial-series snapshot. Without it, `resetSeries()` hands the user the plugin's computed output as if it were their own data. It is idempotent; pass `[]` when the plugin's series are gone. It is also what puts the plugin's name on those series in `drawn()`.
+
+Also fixed in v2: every Weave plugin silently did nothing on a pie, donut or radialBar, because those hold one number per entry and the snapshot called `.map` on it. Each slice is presented as a one-point series now.
+
+### v3: reserve room for the plugin's own UI
+
+```js
+api.reserve({ right: 120 })   // px; pass null (or all zeros) to give it back
+```
+
+A plugin rendering beside the chart cannot make room for itself: the chart sizes from the element the caller handed it, so a sibling inserted there does not narrow it. Reservations are per plugin and summed, so two plugins each asking for a right-hand gutter get one each, and the total is clamped so the chart keeps at least half the container on each axis. An unchanged box does nothing, so calling it on every render is free.
+
+### v4: what the viewer is pointing at
+
+```js
+const off = api.pointer((e) => {
+  // e.type            'enter' | 'leave' | 'select'
+  // e.seriesIndex / e.dataPointIndex
+  // e.category        resolved display label ('Mar'), not an index
+  // e.seriesName      undefined on a pie
+  // e.selected        on 'select' only: is the point now in or out
+  // e.modifiers       { shift, ctrl, alt, meta } (v6)
+})
+off()   // pointer() returns its unsubscribe
+```
+
+Forwards the chart's own `dataPointMouseEnter`, `dataPointMouseLeave` and `dataPointSelection` as one payload, so a plugin does not hit-test the SVG and then disagree with the tooltip on the same pixel. **Nothing here can intercept or cancel**: the tooltip, the selection state and the caller's own `dataPoint*` events are unaffected, and a handler that throws is contained.
+
+`category` is the resolved label because a plugin coordinating two charts keys on the label; an index means something different on every chart. `modifiers` is always all four booleans, never partial and never undefined (all false where there was no DOM event), because a plugin reads `e.modifiers.shift` inside a viewer's click and a sometimes-missing key is how that becomes a crash.
+
+### v6: set a positional option for your own series (`claim`)
+
+`stroke.dashArray` and `dataLabels.enabledOnSeries` are indexed by series position with no per-series form, so a plugin wanting one value for its own series used to write the array covering every series and put the caller's back afterwards.
+
+```js
+const claim = api.claim('stroke.dashArray', [
+  { series: 'Revenue (forecast)', value: 6 },
+])
+claim.update([{ series: 'Revenue (forecast)', value: 4 }])
+claim.release()
+```
+
+The host resolves a claim **where the option is read**, so nothing is written: there is nothing to restore, releasing is a deletion, and the caller's own `updateOptions` composes with the claim instead of reverting it. Claims resolve in order, so two plugins on one series produce a defined winner rather than whichever ran last.
+
+- **Name the series rather than its position where you can.** A name is resolved each time the option is read, so the claim follows that series when the caller adds, removes or reorders others.
+- **Claimable options are an allowlist** (`stroke.dashArray`, `dataLabels.enabledOnSeries` to begin with), each declaring its value type so a wrong one is dropped rather than drawn. An option that is not on the list returns **`null` rather than throwing**, so a plugin built against a newer host degrades instead of breaking. Check the return.
+- Every claim is released on teardown, on destroy, and if the host disables the plugin after repeated errors, so none can outlive the plugin holding it.
+
+`api.info.stroke` (v5) exists for the older read-and-restore pattern and reports what is configured, a scalar or one entry per series, copied on the way out. Prefer `claim()` where the host has it: the restore is stale the moment the caller calls `updateOptions`, it leaks if the plugin throws in between, and two plugins doing it at once fight.
+
+### v6: an inventory of what is on the chart (`drawn` / `declare`)
+
+```js
+api.drawn()   // [{ id, kind: 'series' | 'annotation' | 'overlay', label, owner, visible }, ...]
+
+api.on('draw', () => {
+  api.declare({ id: 'trend-1', label: 'Trend' })   // declare from the draw handler
+})
+```
+
+`drawn()` reports the series, the caller's annotations and whatever plugins have declared. An ink stroke a viewer drew is an annotation too, but reports `owner: 'ink'` rather than `'core'` (fixed in v7.6.1): crediting a viewer's note to the caller is the one case the `owner` field exists to get right. **Every entry names its `owner`**, and that is the point rather than decoration: the list is only ever as complete as the features that opted in, so a layers panel or an export summary can say what its inventory covers instead of presenting a partial list as everything.
+
+- **Read only, deliberately.** Removing or hiding another feature's output would mean one plugin reaching into another's state with no way for the owner to refuse.
+- **Declare from the draw handler.** Declarations are cleared with the layers at the start of every draw, so an inventory cannot outlive the drawing it describes. Declaring the same id twice replaces it rather than growing a duplicate row.
+- **Annotations carry no caller id.** The `id` on a point annotation is the key of a deferred-execution entry rather than a handle on the drawing, so entries fall back to `annotation:<type>:<index>` and take their label from `label.text` where the caller wrote one.
+
+### The types a plugin author works with
+
+Declared in the shipped `apexcharts.d.ts`: `ApexPluginAPI` (the `setup(api)` facade), `ApexPluginSeries`, `ApexPluginScales`, `ApexPluginLayer`, `ApexPluginHook`, `ApexPluginPayload`, and for the v6 additions `ApexPluginChartInfo` (`api.info`), `ApexPluginPointerEvent` (the `pointer` payload), `ApexPluginClaim` (`{ release(), update(entries) }`) and `ApexDrawnItem` (a `drawn()` row).
+
+### Typing gap at 7.6.1
+
+`api.categories` and `data[].raw` are real at runtime (both shipped in v2) but are **not declared** in the shipped `apexcharts.d.ts`: `ApexPluginAPI` has no `categories` member and `ApexPluginSeries` is typed as `{ name?, hidden, color?, points }`. TypeScript rejects both. Cast the facade where you need them, and do not read the absence as "removed".
 
 ---
 
@@ -204,7 +308,7 @@ import 'apexcharts/features/renderer-canvas'
 const options = {
   chart: {
     renderer: 'auto',        // 'svg' | 'canvas' | 'auto'
-    rendererThreshold: 5000, // point count above which 'auto' picks canvas
+    rendererThreshold: 8000, // point count above which 'auto' picks canvas (default 8000)
   },
 }
 // chart.getActiveRenderer()  // => 'svg' | 'canvas'
@@ -261,7 +365,7 @@ Generic Ctrl-Z over a command journal. Zooms, series toggles, option changes, an
 
 ```js
 const options = {
-  chart: { history: { enabled: true, maxDepth: 50, coalesceMs: 300, keyboard: true } },
+  chart: { history: { enabled: true, maxDepth: 100, coalesceMs: 250, keyboard: true } },  // those are the defaults
 }
 
 chart.history.undo(animate?)   // and .redo(animate?)
@@ -563,7 +667,8 @@ const options = {
                                               // 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()
+                                              // clear with chart.clearDrilldownCache(id?), the public
+                                              // typed method (it delegates to the 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' },
@@ -631,7 +736,7 @@ const options = {
 
 ## Common Pitfalls
 
-1. **Assuming the full bundle still carries everything *(the #1 v6 → v7 mistake)*.** In v6, `import ApexCharts from 'apexcharts'` was enough for every feature. In v7 the nine Tier 2 features and the `raincloud` type need their own import on top of it. Read the console: each one names both routes when its config is present without it.
+1. **Assuming the full bundle still carries everything *(the #1 v6 → v7 mistake)*.** In v6, `import ApexCharts from 'apexcharts'` was enough for every feature. In v7 the nine Tier 2 features and the `raincloud` and `icicle` types need their own import on top of it. Read the console: each one names both routes when its config is present without it.
 2. **Forgetting the feature import on a tree-shaken build**: a Tier 1 feature is in the default bundle but not in `apexcharts/core` or a per-type entry, so those builds still need `import 'apexcharts/features/<name>'`.
 3. **Reaching for `apexcharts/features/all` to fix either of the above**: it is the Tier 1 set only, by design (`tests/unit/feature-tier-budget.spec.js` upstream fails the build if a Tier 2 feature reappears in it).
 4. **Using `api.zeroY` in a custom mark**: it does not exist. Use `ctx.scales.y(0)` for the baseline.

package/references/financial-charts.md

@@ -30,7 +30,7 @@ import ApexCharts from 'apexcharts/raincloud'
 import 'apexcharts/features/stats'
 ```
 
-**⚠️ Raincloud is Tier 2 (v7.1).** Unlike every other chart type, it is **not in the default `apexcharts` bundle**. On the full bundle add `import 'apexcharts/raincloud'` (or `import 'apexcharts/features/raincloud'`); from a script tag add `dist/features/raincloud.js` after `apexcharts.js`. It is also premium, so it renders an `APEXCHARTS` watermark until an entitled license is set.
+**⚠️ Raincloud is Tier 2 (v7.1).** It is **not in the default `apexcharts` bundle**, one of only two chart types that are not (the other is `icicle`, v7.6, which is free). On the full bundle add `import 'apexcharts/raincloud'` (or `import 'apexcharts/features/raincloud'`); from a script tag add `dist/features/raincloud.js` after `apexcharts.js`. It is also premium, so it renders an `APEXCHARTS` watermark until an entitled license is set.
 
 **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).
 
@@ -383,6 +383,6 @@ plotOptions: {
 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).
-11. **Expecting `raincloud` to work on the full bundle** *(v7.1)*: it is the one chart type that is Tier 2. `import ApexCharts from 'apexcharts'` alone gives you a console warning and no raincloud. Add `import 'apexcharts/raincloud'`.
+11. **Expecting `raincloud` to work on the full bundle** *(v7.1)*: it is one of two chart types outside the default bundle (the other is `icicle`, v7.6). `import ApexCharts from 'apexcharts'` alone gives you a console warning and no raincloud, because `raincloud` aliases the violin engine and degrades; an unregistered `icicle` throws instead. Add `import 'apexcharts/raincloud'`.
 12. **Looking for `plotOptions.raincloud`**: there is none. Raincloud is a preset over the violin engine, so configure it through `plotOptions.violin` (`side`, `box`, `points`, `kde`, `normalize`).
 13. **Giving a raincloud a `y`**: it takes the raw sample per category: `data: [{ x, points: [number] }]`. A precomputed `y.summary` is honored for the box, but the density and the rain need the observations.

package/references/framework-wrappers.md

@@ -236,7 +236,7 @@ updateChart() {
 
 ```
 https://cdn.jsdelivr.net/npm/apexcharts
-https://cdn.jsdelivr.net/npm/apexcharts@5/dist/apexcharts.min.js
+https://cdn.jsdelivr.net/npm/apexcharts@7/dist/apexcharts.min.js
 https://unpkg.com/apexcharts
 ```
 

package/references/grid-charts.md

@@ -4,14 +4,18 @@
 
 - **Heatmap** (`'heatmap'`) — Color-coded grid cells representing data intensity
 - **Treemap** (`'treemap'`) — Nested rectangles with area proportional to value
+- **Icicle** (`'icicle'`) *(v7.6)* — A hierarchy as stacked bands, one per depth level
 
 ## Tree-Shakeable Import
 
 ```js
 import ApexCharts from 'apexcharts/heatmap'   # heatmap only
 import ApexCharts from 'apexcharts/treemap'    # treemap only
+import ApexCharts from 'apexcharts/icicle'     # icicle (v7.6): opt-in, see below
 ```
 
+`icicle` is **not in the default bundle**. Unlike every other type here, `import ApexCharts from 'apexcharts'` does not carry its class, so `chart.type: 'icicle'` throws until the sub-entry (or `dist/icicle.js` after the ApexCharts script) has registered it. Loading the full bundle is not a workaround, which is what the v7.6.1 error message was corrected to stop suggesting.
+
 ---
 
 ## Data Formats
@@ -182,6 +186,33 @@ plotOptions: {
 
 The hierarchy resolver is shared with sunburst, including the `drilldown: '<id>'` adapter (opted into via `nested.drilldownAsLevels`).
 
+### Icicle (v7.6)
+
+Same hierarchy as the sunburst, drawn in cartesian coordinates: one band per depth level, each child sized inside its parent's extent along the value axis. Axis-style `[{ data: [...] }]` wrapper, `{ x, y, children }` nodes to any depth.
+
+```js
+import ApexCharts from 'apexcharts/icicle'   // required: not in the default bundle
+
+const options = {
+  chart: { type: 'icicle' },
+  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 }] }
+    ]
+  }]
+}
+```
+
+- A branch may **omit its own `y`** and be the sum of its children. This is the documented shape for both partition types, and it only started working in v7.6: before that the non-axis parser dropped any node carrying `children` without `x` and `y`, and the chart drew nothing at all while warning about pie data.
+- A node may carry `drilldown: '<id>'` instead of `children`, and the matching `drilldown.series` entry is read as the next level. It is read as plain data, so no drilldown feature import is needed.
+- Sibling order follows the array by default (`sort: 'none'`). Set `plotOptions.icicle.sort` to `'value'` or `'name'` to override it.
+
+**Choosing between icicle and sunburst.** Both resolve the same tree. An icicle keeps labels horizontal at every depth and puts depth on a straight axis, so same-depth siblings line up across branches and deep trees stay readable; a sunburst spends its area radially and reads better for shallow, wide trees. `direction: 'up'` is the flame-graph orientation, for call stacks and path funnels.
+
 ---
 
 ## Key plotOptions
@@ -191,7 +222,8 @@ The hierarchy resolver is shared with sunburst, including the `drilldown: '<id>'
 ```js
 plotOptions: {
   heatmap: {
-    radius: 0,                    // border radius of cells
+    shape: 'rect',                // 'rect' (default) | 'hexagon' | 'circle' | 'diamond' (v7.2)
+    radius: 0,                    // border radius of cells ('rect' only)
     enableShades: true,           // shade intensity based on value
     shadeIntensity: 0.5,          // shade range (0-1)
     distributed: false,           // different color per series
@@ -212,6 +244,21 @@ plotOptions: {
 }
 ```
 
+#### Cell shapes (v7.2)
+
+`shape` changes what a cell is drawn as, without changing the data format or anything else about the chart:
+
+- `'circle'` and `'diamond'` are inscribed in the cell box the heatmap already lays out.
+- `'hexagon'` is a real honeycomb tilemap: pointy-top hexagons, alternate rows offset half a cell so neighbours share a full edge, with the lattice's overhang reserved as extra grid padding so offset rows never cover the axis labels.
+
+Three constraints worth knowing before choosing one:
+
+- **`radius` applies to `'rect'` only.** Corner rounding is ignored by the other three.
+- **`'hexagon'` is categorical-layout only.** On a numeric or datetime x axis it falls back to `'rect'` silently.
+- **Non-rect shapes always render as SVG.** The canvas renderer declines them the same way it declines image fills, so a large heatmap that needs `renderer: 'canvas'` for its cell count has to stay on `'rect'`.
+
+Shaped cells keep the `apexcharts-heatmap-rect` class and the same attribute contract, so tooltips, keyboard navigation, legend range highlighting and the color tween on a data update all behave unchanged.
+
 ### Treemap
 
 ```js
@@ -233,6 +280,46 @@ plotOptions: {
 }
 ```
 
+### Icicle (v7.6)
+
+```js
+plotOptions: {
+  icicle: {
+    direction: 'down',        // 'down' (root on top, default) | 'up' (flame graph) | 'right' | 'left'
+    levelSize: 'equal',       // 'equal' | px number | '%' string: thickness of one depth band
+    maxDepth: 'auto',         // 'auto' (whole tree) | number of levels from the focused one
+    spacing: 1,               // gap between adjacent cells (px)
+    borderRadius: 0,          // corner rounding (px)
+    leaf: 'stop',             // 'stop' (default): a shallow branch ends at its own band
+                              // 'extend': it stretches to the far edge
+    partition: 'normalize',   // 'normalize' | 'strict'
+    sort: 'none',             // 'none' | 'value' | 'name'
+    tint: 0,                  // per-depth lightening of the parent colour (0 = same, 1 = white)
+    zoomOnClick: true,        // click a cell to zoom into its branch (breadcrumb to go back)
+    zoomType: 'value',        // 'value' (default) | 'both'
+    dataLabels: {
+      show: true,
+      minSizeToShow: 30,      // hide the label on cells shorter than this (px)
+      align: 'center',        // 'left' | 'center' | 'right'; a flame graph wants 'left'
+      rotate: 'auto',         // 'auto' | 'always' | 'never'
+      showValue: false,
+      style: { fontSize: '12px', fontFamily: undefined, fontWeight: 400, colors: undefined }
+    }
+  }
+}
+```
+
+Four defaults differ from the sunburst's, each for a reason worth knowing before overriding it:
+
+- **`leaf: 'stop'`** leaves the white space that shows how deep each branch goes. `'extend'` fills the plot, which is what a treemap does and makes an icicle stop reading as a hierarchy.
+- **`tint: 0`** keeps one hue per branch, so the eye can follow a branch down the levels.
+- **The palette lands on the shallowest level that branches.** A single-root tree is the normal shape here, and colouring by root would paint everything one hue.
+- **The legend is off**, since every cell carries its own label.
+
+**`zoomType` is the one to understand.** `'value'` (the default) rescales the value axis only: the clicked branch stretches to fill the width, its subtree stretches with it, and no level moves. The ancestors stay above it, clamped to the plot, which is what makes them read as context. `'both'` also re-bands the depth axis, promoting the branch to the top level, which spends the whole plot on it at the cost of the reader's place in the tree. The values are not called `'x'` and `'y'` because `direction` decides which screen axis the value axis is.
+
+A click that would not change the view is refused rather than performed: clicking a lone root, or a leaf inside the focused branch, leaves the chart alone, and the cursor reads `pointer` only on cells where a zoom would actually move something.
+
 ---
 
 ## Complete Working Example — Heatmap
@@ -289,3 +376,6 @@ plotOptions: {
 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.
+6. **`chart.type: 'icicle'` on the default bundle (v7.6)** — icicle is opt-in and the default build carries no class for it, so this throws. Add `import ApexCharts from 'apexcharts/icicle'` (or load `dist/icicle.js` after the ApexCharts script). Loading the full `apexcharts.js` does **not** help: it does not carry the class either.
+7. **Reaching for `zoomType: 'both'` to make a branch fill the plot** — `'value'` already stretches the branch across the full width; what `'both'` additionally does is move every level, which costs the reader their place in the tree. Change it only when the ancestors genuinely do not matter.
+8. **Expecting `sort: 'value'` on a flame graph** — `'name'` is the flame-graph convention, because it holds a frame in the same place across profiles so two runs of one program can be compared by eye.

package/references/ssr.md

@@ -52,7 +52,7 @@ const htmlString = await ApexCharts.renderToHTML(
   {
     chart: {
       type: 'bar',
-      id: 'my-chart'   // id is important for hydration targeting
+      id: 'my-chart'   // for chart.exec() targeting; NOT what hydration looks for
     },
     series: [{ data: [44, 55, 41, 67] }],
     xaxis: { categories: ['A', 'B', 'C', 'D'] }
@@ -60,7 +60,12 @@ const htmlString = await ApexCharts.renderToHTML(
   { width: 600, height: 350 }
 )
 
-// htmlString is <div id="my-chart" data-apexcharts>...<svg>...</svg></div>
+// htmlString is:
+//   <div class="apexcharts-ssr-wrapper" data-apexcharts-hydrate data-apexcharts-config="...">
+//     <svg>...</svg>
+//   </div>
+// The wrapper carries NO id. `chart.id` is not copied onto it, and the config
+// travels in data-apexcharts-config, which is what hydration reads.
 ```
 
 ---
@@ -74,14 +79,17 @@ After the server-rendered HTML is in the DOM, hydrate it to make it interactive:
 ```js
 import ApexCharts from 'apexcharts'
 
-// Hydrate a specific chart element (optionally merge client-only options)
-const chart = ApexCharts.hydrate(document.querySelector('#my-chart'))
+// Hydrate a specific chart element (optionally merge client-only options).
+// Select the emitted wrapper, not a chart id: `#my-chart` matches nothing.
+const chart = ApexCharts.hydrate(document.querySelector('[data-apexcharts-hydrate]'))
 ```
 
 ### hydrateAll(selector?, clientOptions?)
 
 ```js
-// Hydrate all server-rendered charts on the page (optionally scope by selector)
+// Hydrate all server-rendered charts on the page (optionally scope by selector).
+// The selector defaults to '[data-apexcharts-hydrate]', which is why this works
+// with no argument and a #id selector does not.
 ApexCharts.hydrateAll()
 ```
 
@@ -210,7 +218,8 @@ onMounted(async () => {
 
 ## Common Pitfalls
 
-1. **Using `apexcharts` in Node.js without SSR methods** — the default export auto-resolves based on environment, but `renderToString` is only available via `apexcharts/ssr`.
-2. **Forgetting to hydrate on the client** — server-rendered charts are static SVGs. Without `hydrate()`, they have no interactivity (no tooltips, zoom, click events).
-3. **Missing 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`).
+1. **Assuming `apexcharts` has no SSR methods in Node** — it does: the `"."` export's `node` condition resolves to the SSR bundle, so `renderToString` and `renderToHTML` are there. Import `apexcharts/ssr` explicitly anyway, because a bundler told to target Node can still resolve the `browser` condition, and then they really are missing.
+2. **Hydrating by chart id** — `renderToHTML` emits `<div class="apexcharts-ssr-wrapper" data-apexcharts-hydrate data-apexcharts-config="...">` with no `id`, so `querySelector('#my-chart')` returns null. Use `hydrateAll()`, or select `[data-apexcharts-hydrate]`.
+3. **Forgetting to hydrate on the client** — server-rendered charts are static SVGs. Without `hydrate()`, they have no interactivity (no tooltips, zoom, click events).
+4. **Missing width/height**: SSR has no DOM to measure. Pass explicit dimensions in the **second** argument: `renderToString(options, { width, height })` / `renderToHTML(options, { width, height })`.
+5. **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

@@ -23,7 +23,7 @@ ApexCharts supports four import strategies with different bundle sizes:
 
 | Strategy | Import | Includes |
 |---|---|---|
-| Default bundle | `import ApexCharts from 'apexcharts'` | Every chart type except `raincloud`, plus the **Tier 1** features. **Not** the nine Tier 2 features. |
+| Default bundle | `import ApexCharts from 'apexcharts'` | Every chart type except `raincloud` and `icicle`, plus the **Tier 1** features. **Not** the nine Tier 2 features. |
 | Per-type entry | `import ApexCharts from 'apexcharts/line'` | Specific chart family + core (no optional features at all) |
 | Bare core | `import ApexCharts from 'apexcharts/core'` | Core class only — must manually register everything |
 | Lean core, no bundler *(v7.0)* | `<script src=".../dist/apexcharts.core.js">` | Script-tag equivalent of bare core, assembled from separate tags. See below. |
@@ -50,7 +50,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/raincloud` | raincloud *(new in v7.1, premium)*: the violin engine plus the raincloud feature. **Tier 2**: the only chart type absent from the default bundle. |
+| `apexcharts/raincloud` | raincloud *(new in v7.1, premium)*: the violin engine plus the raincloud feature. **Tier 2**: absent from the default bundle (with `icicle`, the two that are). |
 | `apexcharts/histogram` | histogram *(new in v6.9)*: the bar engine plus the stats feature |
 | `apexcharts/pie` | pie, donut, polarArea |
 | `apexcharts/donut` | same as /pie |
@@ -60,6 +60,7 @@ Each entry point registers a family of related chart types:
 | `apexcharts/heatmap` | heatmap |
 | `apexcharts/treemap` | treemap |
 | `apexcharts/sunburst` | sunburst *(new in v6.7, free)* |
+| `apexcharts/icicle` | icicle *(new in v7.6, free)*: the sunburst's partition in cartesian coordinates. **Opt-in**: the default bundle carries no icicle class, only the settings literals and a few string branches, so `chart.type: 'icicle'` throws until this entry, or `dist/icicle.js` after the ApexCharts script, has registered it. Loading the full `apexcharts.js` is **not** a way around that. The entry contains no other chart class. |
 | `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`. |
 | `apexcharts/pictograms` | *(new in v7.0)* not a chart entry: a drawn glyph per unit for the unit chart (`person`, `house`, `heart`, `tree`, `droplet`, `star`, `car`, `bag`, `book`, `cup`, `bulb`, `plane`), plus `definePictogram` / `registerMarks` / `catalog`. Import the glyph you use, not `catalog`, which ships all of them. |
@@ -152,7 +153,9 @@ Tree-shaking only ever helped people with a build step. A page using a `<script>
 <script src=".../dist/features/legend.js"></script>
 ```
 
-**136,921 B gzipped**, against 252,005 for the full bundle. Purely additive: `apexcharts.js` is unchanged, and a page that wants everything should keep loading it rather than assembling it from parts.
+**About 144 KB gzipped**, against about 270 KB for the full bundle (`dist/apexcharts.core.min.js` and `dist/apexcharts.min.js` at 7.6.1, gzip -9). Treat both as approximate: the upstream build report gzips at a different level and prints figures a few hundred bytes apart from these, and the numbers move every release. Purely additive: `apexcharts.js` is unchanged, and a page that wants everything should keep loading it rather than assembling it from parts.
+
+The two opt-in chart types are not in that table, because neither is a `features/*` module: `raincloud` is reached through `apexcharts/raincloud` and `icicle` through `apexcharts/icicle` (see the entry table above).
 
 Every Tier 2 feature has a `dist/features/<name>.js` artifact for this channel too, and a full-bundle page still needs it:
 
@@ -256,7 +259,7 @@ export default {
 
 ## Common Pitfalls
 
-1. **Assuming the default bundle still has everything *(v7)***: the nine Tier 2 features and the `raincloud` type need their own import on top of `import ApexCharts from 'apexcharts'`. This is the most common v6 → v7 upgrade failure.
+1. **Assuming the default bundle still has everything *(v7)***: the nine Tier 2 features and the `raincloud` and `icicle` types need their own import on top of `import ApexCharts from 'apexcharts'`. This is the most common v6 → v7 upgrade failure.
 2. **Reaching for `apexcharts/features/all` to fix it**: that is the Tier 1 set by design and pulls in no Tier 2 module.
 3. **Missing feature imports on a tree-shaken build**: Tier 1 features fail silently. If legend/toolbar/annotations don't appear, check imports.
 4. **Importing `apexcharts` AND `apexcharts/line`**: creates duplicate bundles. Use one strategy. *(v7.0 fixed the related internal bug where the default bundle inlined its own core copy while add-ons resolved `apexcharts/core`, so an app importing both got two classes, ~130 KB gzipped of duplicate core, and a feature that never registered. They now share one core.)*