apexcharts-skill 2.2.0 → 3.1.0

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

@@ -1,14 +1,32 @@
-# Tree-Shaking & Bundle Optimization — ApexCharts
+# Bundle Tiers, Tree-Shaking & Optimization: ApexCharts
+
+## ⚠️ What changed in v7.0
+
+**In v6, the default bundle contained every feature. In v7 it does not.** Nine features are **Tier 2**: shipped in the package, absent from every bundle, and reachable only through an explicit import. This applies to the default `apexcharts` bundle, not just to tree-shaken builds, and it is the most common v6 → v7 upgrade failure.
+
+```js
+import ApexCharts from 'apexcharts'
+import 'apexcharts/features/trellis'   // Tier 2: required even on the default bundle
+```
+
+| | gzip |
+|---|---|
+| 6.10.0 default bundle | 291,654 B |
+| 7.0.0 default bundle | 252,005 B (**-13.6%**) |
+| 7.1.0 default bundle | 264,326 B (three new chart types) |
+
+If you use none of the nine, upgrading is `npm install apexcharts@7` and nothing else.
 
 ## Overview
 
-ApexCharts supports three import strategies with different bundle sizes:
+ApexCharts supports four import strategies with different bundle sizes:
 
 | Strategy | Import | Includes |
 |---|---|---|
-| Full bundle | `import ApexCharts from 'apexcharts'` | All chart types + all features |
-| Per-type entry | `import ApexCharts from 'apexcharts/line'` | Specific chart family + core (no optional features) |
+| 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. |
 
 ---
 
@@ -26,9 +44,13 @@ Each entry point registers a family of related chart types:
 | `apexcharts/bar` | bar, column, rangeBar |
 | `apexcharts/column` | same as /bar |
 | `apexcharts/rangeBar` | same as /bar |
+| `apexcharts/waterfall` | waterfall *(new in v7.1)*: the bar engine plus the waterfall feature |
+| `apexcharts/dumbbell` | dumbbell *(new in v7.1)*: the bar engine plus the dumbbell feature |
+| `apexcharts/streamgraph` | streamgraph *(new in v7.1)*: the rangeArea engine plus the streamgraph feature |
 | `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**: 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 |
@@ -38,10 +60,22 @@ 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. |
+
+**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.
+**Entries that bundle a feature.** Four types render through an existing engine but have their own entry because that entry also pulls in a feature module. Each is equivalent to the engine entry plus the feature:
+
+| Entry | Equivalent to |
+|---|---|
+| `apexcharts/histogram` | `apexcharts/bar` + `import 'apexcharts/features/stats'` |
+| `apexcharts/waterfall` | `apexcharts/bar` + `import 'apexcharts/features/waterfall'` |
+| `apexcharts/dumbbell` | `apexcharts/bar` + `import 'apexcharts/features/dumbbell'` |
+| `apexcharts/streamgraph` | `apexcharts/rangeArea` + `import 'apexcharts/features/streamgraph'` |
+| `apexcharts/raincloud` | `apexcharts/violin` + `import 'apexcharts/features/raincloud'` |
 
 ### Using Multiple Chart Types
 
@@ -53,9 +87,16 @@ import 'apexcharts/bar'   // side-effect: registers bar types onto the same clas
 
 ---
 
-## Optional Features
+## Optional Features: Tier 1 vs Tier 2
+
+Two questions decide whether you need a `features/*` import:
+
+1. **Which entry point did you start from?** `apexcharts/core` and the per-type entries carry no optional features at all, so every feature you want needs its import.
+2. **Which tier is the feature?** Tier 1 is in the default `apexcharts` bundle. **Tier 2 is in no bundle**, so it needs its import even there.
+
+### Tier 1: in the default `apexcharts` bundle
 
-Features are optional modules that add functionality. When using per-type entries or core, features must be explicitly imported.
+Import these only when you started from `/core` or a per-type entry.
 
 | Feature | Import | What It Adds |
 |---|---|---|
@@ -65,33 +106,80 @@ Features are optional modules that add functionality. When using per-type entrie
 | 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`) |
-| Perspectives *(v6)* | `import 'apexcharts/features/perspectives'` | Shareable view state |
-| Storyboard *(v6)* | `import 'apexcharts/features/storyboard'` | Scrollytelling (includes perspectives) |
-| Facet *(v6)* | `import 'apexcharts/features/facet'` | Design tokens + OS-aware themes |
-| Weave *(v6)* | `import 'apexcharts/features/weave'` | Public plugin platform |
-| Renderer / Strata *(v6)* | `import 'apexcharts/features/renderer-canvas'` | Hybrid SVG + canvas renderer |
-| Marks *(v6)* | `import 'apexcharts/features/marks'` | Custom series types (`registerSeriesType`) |
-| Link *(v6)* | `import 'apexcharts/features/link'` | Crossfilter / linked views |
-| Ink *(v6)* | `import 'apexcharts/features/ink'` | On-chart annotation authoring |
-| Measure *(v6)* | `import 'apexcharts/features/measure'` | Measure / delta ruler |
-| Context menu *(v6)* | `import 'apexcharts/features/context-menu'` | Right-click / long-press context menu |
-| All | `import 'apexcharts/features/all'` | All of the above |
-
-**Important:** Tooltip is always included in core (it cannot be tree-shaken). 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.
+| Morph | `import 'apexcharts/features/morph'` | Animated chart-type morphs |
+| Drilldown | `import 'apexcharts/features/drilldown'` | Hierarchical drill-down |
+| Facet | `import 'apexcharts/features/facet'` | Design tokens + OS-aware themes |
+| Weave | `import 'apexcharts/features/weave'` | Public plugin platform |
+| Marks | `import 'apexcharts/features/marks'` | Custom series types (`registerSeriesType`) |
+| Waterfall *(v7.1)* | `import 'apexcharts/features/waterfall'` | The `waterfall` chart type |
+| Dumbbell *(v7.1)* | `import 'apexcharts/features/dumbbell'` | The `dumbbell` chart type |
+| Streamgraph *(v7.1)* | `import 'apexcharts/features/streamgraph'` | The `streamgraph` chart type |
+| All Tier 1 | `import 'apexcharts/features/all'` | Every row above, and **only** those |
+
+Tier 1 is a **budget, not an index**: upstream, a module earns a place only if it is under ~5 KB gzipped on top of core, needs no peer dependency or separate asset, and is useful to a majority of charts. The first seven predate the budget and are grandfathered.
+
+### Tier 2: in NO bundle; always an explicit import
+
+Required whatever entry point you used, the default `apexcharts` bundle included.
+
+| Feature | Import | gzip | Premium | What It Adds |
+|---|---|---|---|---|
+| Trellis *(v7.0)* | `import 'apexcharts/features/trellis'` | 25.7 KB | yes | Small multiples: a grid of real charts sharing scale, legend, toolbar, crosshair |
+| Storyboard | `import 'apexcharts/features/storyboard'` | 8.0 KB | yes | Scrollytelling (registers Perspectives too) |
+| Perspectives | `import 'apexcharts/features/perspectives'` | 6.7 KB | yes | Shareable view state |
+| Ink | `import 'apexcharts/features/ink'` | 6.2 KB | yes | On-chart annotation authoring |
+| Renderer / Strata | `import 'apexcharts/features/renderer-canvas'` | 6.0 KB | no | Hybrid SVG + canvas renderer |
+| Link | `import 'apexcharts/features/link'` | 5.3 KB | yes | Crossfilter / linked views |
+| Measure | `import 'apexcharts/features/measure'` | 4.6 KB | yes | Measure / delta ruler |
+| History / Rewind | `import 'apexcharts/features/history'` | 3.2 KB | yes | Undo/redo (`chart.history`) |
+| Context menu | `import 'apexcharts/features/context-menu'` | 2.3 KB | yes | Right-click / long-press context menu |
+| Raincloud *(v7.1)* | `import 'apexcharts/features/raincloud'` | n/a | yes | The `raincloud` chart type (or use the `apexcharts/raincloud` entry) |
+
+Storyboard registers Perspectives, so importing both costs no more than Storyboard alone.
+
+**`apexcharts/features/all` does not include Tier 2**, by design: upstream has a tier-budget test that fails the build if a Tier 2 feature reappears in it.
+
+**Nothing fails silently on Tier 2.** Each module warns in the console when its configuration is present but the module is not, and the warning names both the ESM and script-tag route. Where the chart can still draw something sensible it does and says what it did instead: a trellis renders as a single chart, `renderer: 'canvas'` falls back to SVG.
+
+---
+
+## Script tags: the lean core channel (v7.0)
+
+Tree-shaking only ever helped people with a build step. A page using a `<script>` tag had one artifact and no way to decline any of it. `dist/apexcharts.core.js` is the chart class with no chart types and no optional features, assembled from separate tags:
+
+```html
+<script src=".../dist/apexcharts.core.js"></script>
+<script src=".../dist/line.js"></script>
+<script src=".../dist/features/legend.js"></script>
+```
+
+**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:
+
+```html
+<script src=".../dist/apexcharts.js"></script>
+<script src=".../dist/features/trellis.js"></script>
+```
+
+**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 `feature-platform.md` for the config and API of each 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:
+It depends on the tier.
+
+**Tier 1 features fail silently.** If you use a per-type entry without importing legend:
 - No legend appears, no error thrown
 - `chart.toolbar` is undefined, toolbar doesn't render
 - `addXaxisAnnotation()` does nothing
 - `dataURI()` / `exportToCSV()` throw because the feature isn't registered
 
+**Tier 2 features announce themselves.** Each warns in the console when its configuration is present but the module is not, naming both the ESM and the script-tag route, and degrades predictably where it can: a `trellis` config renders as one ordinary chart, `renderer: 'canvas'` falls back to SVG. If a v7 chart is quietly missing a feature you configured, **check the console before the config**.
+
 ---
 
 ## Bare Core Usage
@@ -171,7 +259,10 @@ export default {
 
 ## Common Pitfalls
 
-1. **Missing feature imports** — features fail silently. If legend/toolbar/annotations don't appear, check imports.
-2. **Importing `apexcharts` AND `apexcharts/line`** — creates duplicate bundles. Use one strategy.
-3. **Vite duplicate bundle issue** — without `optimizeDeps.include`, Vite may bundle ApexCharts twice.
-4. **Calling `dataURI()` without exports feature** — throws an error. Import `apexcharts/features/exports` first.
+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.)*
+5. **Vite duplicate bundle issue**: without `optimizeDeps.include`, Vite may bundle ApexCharts twice.
+6. **Calling `dataURI()` without exports feature**: throws an error. Import `apexcharts/features/exports` first.
+7. **`require('apexcharts/line')` used to throw** `h.use is not a function` in every published version with sub-path entries, because rollup's default CJS interop assumes `require()` returns the export itself. Fixed in **7.0.0**; below that, use ESM `import` for sub-path entries.