apexcharts-skill 2.2.0 → 3.0.0

package/references/bar-charts.md

@@ -7,6 +7,8 @@
 - **Range Bar** (`'rangeBar'`) — Bars with start/end values (used for timelines, Gantt charts)
 - **Funnel** (`'funnel'`, **new in v6**): Stage-by-stage drop-off chart
 - **Pyramid** (`'pyramid'`, **new in v6**): A funnel with the wide base at the bottom
+- **Waterfall** (`'waterfall'`, **new in v7.1**): Deltas that accumulate into a running total
+- **Dumbbell** (`'dumbbell'`, **new in v7.1**): Two or more measures per category, joined by a connector
 
 ## Tree-Shakeable Import
 
@@ -14,10 +16,16 @@
 import ApexCharts from 'apexcharts/bar'
 // Registers: bar, column, rangeBar
 // Aliases: apexcharts/column, apexcharts/rangeBar
-// Also covers funnel + pyramid (they normalize to the bar engine in v6)
+// Also covers funnel + pyramid (they normalize to the bar engine)
+
+// waterfall and dumbbell (v7.1) each add a feature module on top of the bar engine:
+import ApexCharts from 'apexcharts/waterfall'  // == apexcharts/bar + features/waterfall
+import ApexCharts from 'apexcharts/dumbbell'   // == apexcharts/bar + features/dumbbell
 ```
 
-**v6 note:** `funnel` and `pyramid` are first-class `chart.type` aliases that render through the bar engine. Use them directly as `chart.type`; you do **not** need `plotOptions.bar.isFunnel`. `plotOptions.funnel` carries the funnel-specific shape options.
+Both are **Tier 1**, so the default `apexcharts` bundle already has them and no import is needed there.
+
+**Alias note:** `funnel` and `pyramid` are first-class `chart.type` aliases that render through the bar engine. Use them directly as `chart.type`; you do **not** need `plotOptions.bar.isFunnel`. `plotOptions.funnel` carries the funnel-specific shape options.
 
 **Histogram (v6.9):** `chart.type: 'histogram'` also renders through the bar pathway, but its series carry raw observations that the chart bins itself, and the binning needs the stats feature (`apexcharts/histogram` entry, or `apexcharts/features/stats` alongside `apexcharts/bar`). It is documented with the other statistical charts in `references/financial-charts.md`.
 
@@ -184,6 +192,105 @@ Same shape as funnel, but order values **smallest → largest** so the wide base
 }
 ```
 
+### Waterfall (v7.1)
+
+`chart.type: 'waterfall'` **accumulates the running total for you**. The series holds the **deltas**; a row flagged `isSubtotal` or `isTotal` draws the running total from zero at that position and carries **no `y` of its own**. Connectors bridge each bar's finish to the next one's start, and rising, falling and total bars take their own colors.
+
+```js
+{
+  chart: { type: 'waterfall', height: 350 },
+  series: [{
+    name: 'Operating income',
+    data: [
+      { x: 'Net revenue',        y:  8786000 },
+      { x: 'Cost of sales',      y: -2786000 },
+      { x: 'Gross profit',       isSubtotal: true },   // no y: measured for you
+      { x: 'Operating expenses', y: -1786000 },
+      { x: 'Operating income',   isTotal: true },      // no y: sum from zero
+    ],
+  }],
+}
+```
+
+**Row shape** (`ApexWaterfallPoint`, every field optional so a series can mix the two kinds freely):
+
+| Field | Meaning |
+|---|---|
+| `x` | Category label, timestamp, or `Date` |
+| `y` | The **step**: the signed amount it moves the running total by. Omit on a subtotal / total row. |
+| `isSubtotal` | Sum of the steps since the previous subtotal / total bar |
+| `isTotal` | Sum of every step from zero |
+| `fillColor` | Overrides the semantic fill for this row |
+
+**`plotOptions.waterfall`:**
+
+```js
+plotOptions: {
+  waterfall: {
+    colors: {
+      positive: '#00A86F',   // a step that raises the running total
+      negative: '#FF4560',   // a step that lowers it
+      subtotal: undefined,   // defaults to the series color from the active palette
+      total: undefined,      // same default, so running totals stay distinct from steps
+    },
+    connectors: {
+      show: true,            // without them the floating columns read as unrelated bars
+      color: undefined,      // defaults to grid.borderColor, so it is theme-aware
+      strokeWidth: 1,
+      strokeDashArray: 3,
+    },
+  },
+}
+```
+
+A datum's own `fillColor` always wins over `plotOptions.waterfall.colors`.
+
+### Dumbbell (v7.1)
+
+`chart.type: 'dumbbell'` compares two or more measures per category. **Each series is one measure**, and the chart joins them with a connector per category. You do not zip the values into `[low, high]` pairs.
+
+```js
+{
+  chart: { type: 'dumbbell', height: 350 },
+  series: [
+    { name: '2020', data: [{ x: 'Backend', y: 92 }, { x: 'Frontend', y: 78 }] },
+    { name: '2025', data: [{ x: 'Backend', y: 118 }, { x: 'Frontend', y: 96 }] },
+  ],
+  plotOptions: { bar: { horizontal: true } },  // rows; omit for columns
+}
+```
+
+The connector's thickness is `plotOptions.bar.barHeight` (rows) or `columnWidth` (columns), and the size of the marked ends is `markers.size`: they are the bar and its markers, so they are configured as such.
+
+**`plotOptions.bar.dumbbell`:**
+
+```js
+plotOptions: {
+  bar: {
+    dumbbell: {
+      connector: {
+        color: undefined,   // undefined = a gradient between the two endpoint colours,
+                            // resolved per row so a row where the measures cross runs the right way
+        opacity: 0.55,      // the join is context for the marked ends, not a third mark
+      },
+      dataLabels: {
+        enabled: true,      // default on for chart.type 'dumbbell', off for the bare isDumbbell flag
+        offset: 6,          // px clear of the marked end, outward from the connector
+        colorFromMarker: true,
+        // formatter(value, { seriesIndex, dataPointIndex, endpointIndex, w })
+        // NOTE: defaults to the value axis' label formatter, NOT dataLabels.formatter
+        // (on a range bar that one reads out end - start, which is the gap, not the endpoint)
+      },
+      tooltip: { differenceLabel: 'Difference' },
+    },
+  },
+}
+```
+
+With three or more measures only the two extremes are labelled: anything between them sits on the connector, where a label has nowhere to go that is not over the line or over its neighbour.
+
+**Versus the older range-bar form.** `plotOptions.bar.isDumbbell` on a `rangeBar` with `y: [lo, hi]` pairs still works and is a different chart: one series, endpoint colours from `plotOptions.bar.dumbbellColors` (`[[startColor, endColor]]`). `chart.type: 'dumbbell'` takes one series per measure and colours each dot after the series it belongs to, from `colors`. Prefer the type unless you already have paired data.
+
 ---
 
 ## Key plotOptions.bar Options
@@ -197,7 +304,7 @@ plotOptions: {
     distributed: false,       // true = different color per data point
     borderRadius: 4,          // rounded corners (number or object)
     borderRadiusApplication: 'end',  // 'end' | 'around'
-    borderRadiusWhenStacked: 'last', // 'all' | 'last'
+    // borderRadiusWhenStacked was REMOVED in v7.0, see the note below
 
     dataLabels: {
       position: 'top',        // 'top' | 'center' | 'bottom'
@@ -215,6 +322,14 @@ 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.
+
+**⚠️ `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:
+
+```js
+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`.
@@ -309,4 +424,9 @@ series: [{
 4. **Timeline without `xaxis.type: 'datetime'`** — date-based range bars need `xaxis: { type: 'datetime' }` to render correctly.
 5. **`distributed: true` with multiple series** — distributed coloring applies to each data point independently. With multiple series, each point gets a unique color which is usually not desired. Use `distributed: true` only with single-series charts.
 6. **Funnel/pyramid value ordering**: funnel expects values ordered largest-to-smallest and pyramid smallest-to-largest. The renderer does not sort for you; unsorted data produces a jagged shape. Stage labels come from `xaxis.categories`, and per-stage labels in `dataLabels.formatter` are read via `opt.w.globals.labels[opt.dataPointIndex]`.
-7. **Reaching for `plotOptions.bar.isFunnel` in v6**: unnecessary. Set `chart.type: 'funnel'` (or `'pyramid'`) and use `plotOptions.funnel` for shape options.
+7. **Reaching for `plotOptions.bar.isFunnel`**: unnecessary. Set `chart.type: 'funnel'` (or `'pyramid'`) and use `plotOptions.funnel` for shape options.
+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.
+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

@@ -7,6 +7,7 @@
 - **Scatter** (`'scatter'`) — Individual data points plotted by X/Y coordinates
 - **Bubble** (`'bubble'`) — Scatter with variable-size bubbles (requires z value)
 - **Range Area** (`'rangeArea'`) — Area chart showing a range between two values
+- **Streamgraph** (`'streamgraph'`, **new in v7.1**): Series stacked as flowing bands around a chosen baseline
 
 ## Tree-Shakeable Import
 
@@ -14,8 +15,13 @@
 import ApexCharts from 'apexcharts/line'
 // Registers: line, area, scatter, bubble, rangeArea
 // Aliases: apexcharts/area, apexcharts/scatter, apexcharts/bubble, apexcharts/rangeArea
+
+// streamgraph (v7.1) adds a feature module on top of the rangeArea engine:
+import ApexCharts from 'apexcharts/streamgraph'  // == apexcharts/rangeArea + features/streamgraph
 ```
 
+Streamgraph is **Tier 1**, so the default `apexcharts` bundle already has it and no import is needed there.
+
 ---
 
 ## Data Formats (Detailed)
@@ -124,6 +130,62 @@ Always use XY format:
 }
 ```
 
+### Streamgraph (v7.1)
+
+`chart.type: 'streamgraph'` stacks the series as flowing bands around a baseline chosen to keep the whole picture readable. Series format is the same as area; **the stacking is the chart's job, so do not set `chart.stacked`**.
+
+```js
+{
+  chart: { type: 'streamgraph', height: 350 },
+  series: [
+    { name: 'Drama',  data: [{ x: '2024-01-01', y: 32 }, { x: '2024-02-01', y: 41 }] },
+    { name: 'Comedy', data: [{ x: '2024-01-01', y: 18 }, { x: '2024-02-01', y: 26 }] },
+  ],
+}
+```
+
+Curves are `monotoneCubic` by default so a band never overshoots its data, each band's name is drawn inside it sized to the room that band actually has, and hovering a band fades the others. The legend and tooltip work as on any axis chart.
+
+**`plotOptions.streamgraph`:**
+
+```js
+plotOptions: {
+  streamgraph: {
+    offset: 'wiggle',      // where the baseline goes:
+                           //   'wiggle'     (default) minimizes total weighted slope, so thick bands stay level
+                           //   'silhouette' centres the stack on one horizontal line
+                           //   'zero'       an ordinary stacked area, on the zero line
+                           //   'expand'     normalizes each column to its own total (composition, not volume)
+
+    order: 'inside-out',   // stacking order, bottom first:
+                           //   'inside-out' (default) puts early-peaking series in the middle and fans
+                           //                later peaks outward, each to whichever side is thinner
+                           //   'inverse'    the series order, reversed
+                           //   'none'       the series order as given
+
+    hover: { show: true, opacity: 0.35 },  // what the OTHER bands drop to; much above ~0.5 and the
+                                           // hovered band stops reading as picked out
+
+    labels: {
+      show: true,
+      minWidth: 24,        // a band narrower than this many px is left unlabelled rather than
+                           // given a name truncated past the point of being a name
+      minFontSize: 9,
+      maxFontSize: 30,
+      style: {
+        fontSize: 'auto',  // sizes each name to its band, bounded by min/maxFontSize.
+                           // Give a literal ('12px') to draw every name at the same size.
+        fontWeight: 600,
+        colors: undefined, // per-series override; by default each label takes black or white,
+                           // whichever reads on its own band
+      },
+    },
+  },
+}
+```
+
+`offset: 'wiggle'` with `order: 'inside-out'` is the classic streamgraph, and the pair is what keeps it readable: the middle of the stack moves least under a wiggle baseline. A faded band's name is recoloured to `chart.foreColor` rather than faded with it, because the name takes black or white by the contrast of the band at full strength.
+
 ---
 
 ## Key Options
@@ -242,6 +304,20 @@ xaxis: {
 
 1. **Bubble chart without z value** — renders with zero-size bubbles. Always provide `z` in data.
 2. **Using `xaxis.categories` with `{ x, y }` data** — categories are silently ignored when data contains x values. Choose one approach.
-3. **Datetime axis with string dates** — pass timestamps (`new Date(...).getTime()`) or `Date` objects, not raw strings like `'January 2024'`. Since v6.10 a `Date` object `x` is accepted by the types and keeps millisecond resolution (previously milliseconds were truncated, collapsing points within the same second).
+3. **Datetime axis with string dates**: pass timestamps (`new Date(...).getTime()`) or `Date` objects, not raw strings like `'January 2024'`. Since v6.10 a `Date` object `x` is accepted by the types and keeps millisecond resolution (previously milliseconds were truncated, collapsing points within the same second). **Since v7.1 a `Date` x also works on a non-datetime axis**; before that it only worked when the axis was `datetime` and stringified into garbage anywhere else, and an invalid `Date` slipped through unnoticed. Both are handled now.
 4. **`stroke.curve: 'smooth'` on sparse data** — can produce visual artifacts. Use `'monotoneCubic'` for mathematically smoother interpolation.
 5. **Range Area with single value instead of array** — `y` must be `[low, high]`, not a single number.
+6. **Setting `chart.stacked` on a streamgraph** *(v7.1)*: the chart owns its own stacking, baseline and band order through `plotOptions.streamgraph`. Reach for `offset: 'zero'` if what you actually want is a plain stacked area.
+7. **A series that starts with nulls used to mis-target the tooltip**: the hovered index resolved against the drawn points rather than the data, so the tooltip read the wrong point. Fixed in v7.1.
+8. **`autoScaleYaxis` scaling to points nobody can see**: before v7.1, zooming let one point just outside the window size the whole axis, and a series with nothing in the window still contributed. Fixed in v7.1; stacked charts now also scale to the stacked totals inside the window rather than to individual series.
+
+## Axis and layout fixes worth knowing (v7.0 / v7.1)
+
+These need no config change; they matter because a workaround you carried from an earlier version may now be unnecessary.
+
+- **Logarithmic axis geometry, and `tickAmount` on a log scale** *(v7.0)*. Log-scale positions were computed against the wrong domain, and `tickAmount` was ignored outright on a log axis. Both fixed, so `yaxis: { logarithmic: true, tickAmount: n }` now does what it says.
+- **Bar width came from the smallest gap inside one series** *(fixed v7.1)*. A single series with one tight pair of x values shrank every bar on the chart. A bar's slot now comes from the axis, the union of gaps across all series.
+- **Stacked baselines resolve by x, not by position in the array** *(fixed v7.0)*. Two series stacked on ragged data lined up by ordinal, so a series with a missing point stacked onto the wrong neighbour.
+- **A container resize arriving mid-animation was lost for good** *(fixed v7.1)*. The ResizeObserver fires once per resize and the handler dropped that callback while an animation ran, so a chart in a collapsing sidebar kept its old size.
+- **Annotations on a chart with no data** *(fixed v7.0)*. Placement was gated chart-wide on `dataPoints`, so an empty chart dropped every annotation including y-axis ones that are always placeable. Gating is now per annotation.
+- **A tooltip inside Shadow DOM followed the wrong element** *(fixed v7.0)*. Reading `e.target` after a deferred hover gets the shadow host, not the hovered mark.

package/references/circular-charts.md

@@ -29,8 +29,13 @@ import ApexCharts from 'apexcharts/unit'
 
 import { heart, outlined, glyphs, preview } from 'apexcharts/unit-shapes'
 // Unit-chart shape kit (v6.10), named exports tree-shaken per shape. See "Unit shapes" below.
+
+import { person, registerMarks } from 'apexcharts/pictograms'
+// Pictogram glyph collection (v7.0), one drawn mark per unit. See "Pictograms" below.
 ```
 
+All of these are **Tier 1** (in the default `apexcharts` bundle). Nothing in the circular family is Tier 2.
+
 ---
 
 ## Data Format
@@ -152,7 +157,7 @@ Colours, `stroke`, `legend`, and `title` behave as they do on pie and donut. A s
 
 ### Unit / Waffle (v6.6, premium)
 
-A `unit` chart renders one discrete mark for every unit of value instead of a single bar or slice, so "37 of 200" reads as a countable quantity. It is a **non-axis** chart (dispatched like pie or treemap) and is **premium**: it renders fully in trial mode with an `APEXCHARTS` watermark until an entitled license is set (see `references/v6-features.md`). On every update each mark tweens from its old position to its new one, so re-grouping, filtering, or a changing count re-forms the marks.
+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.
 
 Data is the same flat number array + `labels` shape as pie:
 
@@ -219,6 +224,45 @@ registerShapes([...])            // register so positions: '<name>' resolves by
 
 Every shape carries metadata on `shape` (category, kind, and `minUnits`: the count below which it stops being recognisable; asking for fewer logs a console warning naming the shape). From a script tag, `dist/unit-shapes.js` exposes the kit as the global `ApexUnitShapes` with every shape pre-registered, so `positions: 'heart'` works by name.
 
+### Pictograms (`apexcharts/pictograms`, v7.0)
+
+A **shape** is where the units go; a **pictogram** is what one unit looks like. They are independent, so `positions: heart` with `shape: 'pictogram'` arranges glyphs into a heart, and every other pairing is equally valid.
+
+```js
+import ApexCharts from 'apexcharts'
+import { person, registerMarks } from 'apexcharts/pictograms'
+
+registerMarks([person])   // so pictogram.mark: 'person' resolves by name
+
+const options = {
+  chart: { type: 'unit' },
+  series: [120, 80],
+  labels: ['Employed', 'Unemployed'],
+  plotOptions: {
+    unit: {
+      shape: 'pictogram',
+      pictogram: {
+        mark: 'person',      // a registered name, a { path, viewBox?, fillRule? } object,
+                             // raw path data, or an array (one per series).
+                             // A datum's own `mark` overrides all of it, so one crowd can mix glyphs.
+        fit: 'contain',      // which side of the glyph binds to the dot's box: 'contain' | 'width' | 'height'
+        scale: 1,            // nudge for glyphs that read light
+        padding: 0,          // 0..0.9 of the pitch, opening the lattice up
+        fallback: 'circle',  // drawn when a mark cannot be resolved
+      },
+    },
+  },
+}
+```
+
+A glyph is drawn as one `<path>` per unit, filled in that unit's own colour: no request, no decode, no recolour filter, which is why `'pictogram'` is the shape that scales to thousands of units. There is deliberately **no size**: a glyph is fitted to the box the dot itself would have occupied, so `plotOptions.unit.size` and `spacing` size a pictogram exactly as they size a dot.
+
+**Shipped glyphs** (each a named export, so import the one you use): `person`, `house`, `heart`, `tree`, `droplet`, `star`, `car`, `bag`, `book`, `cup`, `bulb`, `plane`. `catalog` is every glyph and ships all of them, so avoid it in an app bundle.
+
+**Custom glyphs:** `definePictogram({ name, path, viewBox?, fillRule?, category?, source? })` builds one, `registerMarks(defs)` registers them by name, `unregisterMarks(names)` removes them, and `registeredMarkNames()` lists what resolves. Any glyph also has `.with(overrides)` for a variant with some metadata replaced.
+
+**Versus `shape: 'image'`:** `'image'` fetches a raster or multi-colour icon (`plotOptions.unit.image.src`, with `tint: true` to recolour a monochrome icon to the category colour). Use it for multi-colour marks that should keep their own colours; use `'pictogram'` for anything that has to scale or follow the palette.
+
 **Outer name labels (v6.10):** a shape packed with several categories can name them in the margin with a leader line to their own dots (the pie/donut outer-label mechanism), instead of needing a legend:
 
 ```js
@@ -445,3 +489,6 @@ plotOptions: {
 10. **Expecting `unit` / `waffle` without a license to be watermark-free**: they are premium and render an `APEXCHARTS` watermark until an entitled `premium`/`enterprise` license is set. Sunburst, by contrast, is free.
 11. **Slice click behavior changed (v6.9)**: clicking a pie/donut slice now slides it out along its own mid-angle (`plotOptions.pie.expandOffset`, default 10 px) instead of darkening it and redrawing it at a larger radius, and hover traces an outline band (`plotOptions.pie.hoverOutline`) instead of lightening the fill. Set `expandOffset: 0` to keep slices in place; set `states.hover.filter.type: 'none'` to suppress the hover band.
 12. **Unit shapes below `minUnits`**: each `apexcharts/unit-shapes` shape declares the minimum dot count at which it still reads. Feeding fewer units logs a console warning naming the shape; pick a simpler shape or raise `unitValue` so the count lands above the threshold.
+13. **Confusing a shape with a pictogram** *(v7.0)*: `plotOptions.unit.positions` (from `apexcharts/unit-shapes`) is **where** the units go; `plotOptions.unit.shape: 'pictogram'` + `pictogram.mark` (from `apexcharts/pictograms`) is **what one unit looks like**. They compose freely.
+14. **Setting a size on a pictogram** *(v7.0)*: there is no `pictogram.size`. A glyph is fitted to the box the dot would have occupied, so use `plotOptions.unit.size` and `spacing`. Use `pictogram.scale` only to nudge a glyph that reads light.
+15. **Pie / radial charts pinned to the top of a tall container** *(fixed v7.1)*: the centre came from `min(width, height)`, so a tall, narrow container put the circle at the top with the leftover space below it. The circle now centres in the height it actually has. If you carried a manual `offsetY` to work around this, remove it.

package/references/{v6-features.md → feature-platform.md}

@@ -1,8 +1,35 @@
-# v6 Feature Platform: ApexCharts
+# Feature Platform: ApexCharts
 
-ApexCharts v6 adds an opt-in, tree-shakeable feature platform on top of the v5 core. **Every v5 config keeps working unchanged.** Each feature below is off by default and ships as its own `apexcharts/features/*` entry, so it only enters your bundle when you import it. When using the full `apexcharts` bundle, all features are already present.
+ApexCharts ships an opt-in feature platform on top of the chart core. **Every v5 and v6 config keeps working unchanged in v7**, apart from the two v7.0 breaking changes noted below. Each feature is off by default in config terms and ships as its own `apexcharts/features/*` entry.
 
-Two behaviors changed *on by default* (both respect `prefers-reduced-motion`):
+## ⚠️ Read first: two bundle tiers (v7.0)
+
+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.
+
+```js
+import ApexCharts from 'apexcharts'
+import 'apexcharts/features/trellis'   // Tier 2: required even here
+```
+```html
+<script src=".../dist/apexcharts.js"></script>
+<script src=".../dist/features/trellis.js"></script>
+```
+
+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.
+
+## 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.
+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
+
+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`).
@@ -18,10 +45,11 @@ Two update behaviors worth knowing (both 6.9/6.10):
 
 ## Licensing: premium features and the trial watermark
 
-Introduced in **6.5.0**, tightened in **6.7.0**. Not every v6 feature is free. Seven feature modules plus the `unit` / `waffle` chart type are **premium** and run under a lightweight, offline license check. They keep working fully without a key (trial mode), but the chart shows an unobtrusive `APEXCHARTS` watermark until an entitled license is set.
+Introduced in **6.5.0**, tightened in **6.7.0**. Not every feature is free. Eight feature modules plus two chart types are **premium** and run under a lightweight, offline license check. They keep working fully without a key (trial mode), but the chart shows an unobtrusive `APEXCHARTS` watermark until an entitled license is set.
 
 **The premium set (watermarked until entitled):**
 
+- `trellis` (small multiples, premium since **7.0.0**)
 - `storyboard` (scrollytelling)
 - `link` (crossfilter / linked views)
 - `ink` (annotation authoring)
@@ -30,8 +58,11 @@ Introduced in **6.5.0**, tightened in **6.7.0**. Not every v6 feature is free. S
 - `perspectives` (shareable view state)
 - `history` (undo/redo, Rewind)
 - 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 (including `sunburst`), and every other module (Weave, Strata / canvas, Marks, Facet / themes, Cadence, drilldown, streaming, exports, legend, toolbar, annotations, keyboard).
+**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.
 
 ### Setting a license
 
@@ -55,9 +86,73 @@ As of **6.7.0** the premium features clear the watermark only on a `premium` or
 
 ---
 
+## Trellis: small multiples that agree to the pixel (7.0)
+
+`import 'apexcharts/features/trellis'`: **Tier 2** (not in the default bundle) and **premium**.
+
+One dataset split into a grid of real charts that share a scale, a legend, a toolbar and a crosshair. Setting `trellis.by` makes the chart a trellis **host**: the series array is split into one panel per facet-key value, every panel is a real chart of the host's `chart.type`, and the trellis owns everything shared.
+
+```js
+import ApexCharts from 'apexcharts'
+import 'apexcharts/features/trellis'
+
+new ApexCharts(el, {
+  chart: { type: 'line' },
+  series: [
+    { name: 'Revenue', region: 'North', data: north },
+    { name: 'Revenue', region: 'South', data: south },
+  ],
+  trellis: { by: 'region', minPanelWidth: 260 },
+}).render()
+```
+
+`trellis.by` is the whole configuration. The grid owns the y domain (the union across panels), the x window, and a column count computed from `minPanelWidth` alone. **A series carrying no facet key repeats in every panel**, which is how you get a reference line.
+
+**In TypeScript**, use the typed `facet` field rather than an arbitrary key, or the series objects will not typecheck:
+
+```ts
+series: [
+  { name: 'Revenue', facet: 'North', data: north },
+  { name: 'Revenue', facet: 'South', data: south },
+],
+trellis: { by: 'facet', minPanelWidth: 260 },
+```
+
+**Facet accessors.** `by` is a key name on each series object (`facet` is the blessed typed field; any other key name works from plain JS) or a function `(series, index) => key`, which works from either. For a 2-D grid use `row` × `column` instead of `by`: every (row, column) combination in row-major order at a fixed column count, column labels once across the top, row labels once down the left. A series carrying only the row key repeats across that row.
+
+**Tidy-row input.** `trellis.data` takes a row table instead of `series`, pivoted by the `by` / `x` / `y` / `seriesBy` **column names**. Rows win over `series` when both are given; duplicate (panel, series, x) rows keep the last and warn, so aggregate first.
+
+| Option | Default | Notes |
+|---|---|---|
+| `columns` | `'auto'` | `'auto'` fits `minPanelWidth` columns into the container. |
+| `minPanelWidth` | `220` | Drives `'auto'` columns and the responsive collapse. |
+| `gap` / `aspectRatio` / `panelHeight` | `12` / `1.6` / none | `panelHeight` wins over `aspectRatio` and `chart.height`. |
+| `order` | `'first-seen'` | Also `'asc'`, `'desc'`, an explicit `string[]`, or a comparator. |
+| `limit` | none | Render only the first N panels (warns about the rest). |
+| `virtualize` | `'auto'` | Mounts only panels intersecting the viewport (plus one row) once the grid exceeds **64 panels**. An unmounted cell keeps its header and a fixed-height skeleton so page height never shifts; a remount restores its zoom window. **`getPanel(key)` returns `null` for an unmounted panel.** |
+| `scales` | `{ x: 'shared', y: 'shared' }` | `y` also takes `'independent-row'` / `'independent-column'` in a 2-D grid. Non-shared `y` still renders pixel-aligned panels. |
+| `emptyPanels` | `'placeholder'` | Missing (row, column) combos: a real empty panel with `noData.text`, or `'skip'` (tinted blank) or `'hide'`. |
+| `axes.labels` | `'edges'` | y labels on the first column, x labels on each column's bottom panel. Label *space* is always reserved everywhere so panels stay aligned. Also `'all'` / `'none'`. |
+| `legend` / `toolbar` | `'shared'` | One legend (toggles a series name in every panel) and one zoom/pan/reset toolbar. `'none'` to drop. |
+| `tooltip` | `'panel'` | Card in the hovered panel while the crosshair sweeps all. `'sync'` = a card per panel; `'grid'` = one card near the cursor with a row per panel, composed from the panels' own tooltips so every formatter is honored. |
+| `zoom` | `'sync'` | A zoom in any panel moves every panel. |
+| `promote` | `true` | Clicking a header expands that panel to full width with an "All panels" breadcrumb. |
+| `radiusByTotal` | `false` | Pie/donut/polarArea only: scale each panel's radius so its **area** is proportional to the panel's total. Equal-size pies cannot encode magnitude, so set this on a pie trellis. |
+| `targetTicks` | `3` | Tick-interval target for the shared nice y scale, so a small panel wears few labels. |
+| `header` | shown | `{ show, formatter(key, { dimension, index, count }), style }`. |
+| `panel` | none | `(key, { index, seriesNames }) => ApexOptions`, a per-panel override applied last. |
+
+**API.** `chart.getPanels()` returns the panels in grid order; `chart.getPanel(key)` returns one panel's own ApexCharts instance (the escape hatch to every per-chart API the trellis does not re-expose); `chart.promotePanel(key)` / `chart.restorePanels()` drive the promotion from code. `ApexCharts.trellis(el, options)` is the imperative constructor and throws if the feature is not imported.
+
+**Annotations** take `scope`: absent or `'trellis'` draws in every panel through each panel's own scale, a key or array of keys restricts it.
+
+**Per-type guardrails** keep a shared frame honest: histograms share a bin frame, violins a bandwidth, heatmaps one colour scale and a single gradient legend.
+
+---
+
 ## Weave: public plugin platform
 
-`import 'apexcharts/features/weave'`
+`import 'apexcharts/features/weave'`: Tier 1 (already in the default bundle).
 
 Publish reusable chart plugins to npm against a stable, versioned API. A plugin draws into its own sandboxed layer and subscribes to lifecycle hooks; it never touches raw internal state.
 
@@ -98,7 +193,7 @@ The `setup(api)` facade:
 
 ## Strata: hybrid SVG + canvas renderer
 
-`import 'apexcharts/features/renderer-canvas'`
+`import 'apexcharts/features/renderer-canvas'`: **Tier 2** (not in the default bundle). Free.
 
 Break the SVG node ceiling without leaving SVG behind. Below a threshold the output is identical SVG; above it, only the series layer becomes a `<canvas>` while axes, grid, tooltips, annotations, and exports stay SVG.
 
@@ -121,7 +216,7 @@ Canvas is live for line, area, bar, column, scatter, and candlestick, with share
 
 ## Marks: composable custom series types
 
-`import 'apexcharts/features/marks'`
+`import 'apexcharts/features/marks'`: Tier 1 (already in the default bundle).
 
 Register a `renderItem(ctx)` function and get a first-class series: events, shared tooltip, legend, and keyboard navigation all work with no extra wiring. Dumbbell, lollipop, and bullet ship as samples.
 
@@ -158,7 +253,7 @@ Dumbbell uses `dataType: 'rangeXY'` (datum `y` is `[start, end]`, both bounds fo
 
 ## Rewind: history and undo/redo
 
-`import 'apexcharts/features/history'`
+`import 'apexcharts/features/history'`: **Tier 2** (not in the default bundle) and **premium**.
 
 **Premium** (watermarked in trial mode until an entitled license is set, see Licensing above).
 
@@ -181,7 +276,7 @@ chart.history.entries()        // [{ id, label, at }]
 
 ## Perspectives: shareable view state
 
-`import 'apexcharts/features/perspectives'`
+`import 'apexcharts/features/perspectives'`: **Tier 2** (not in the default bundle) and **premium**.
 
 **Premium** (watermarked in trial mode until an entitled license is set, see Licensing above).
 
@@ -208,7 +303,7 @@ const options = { chart: { perspectives: { serializeOptions: ['colors', 'title']
 
 ## Facet: design tokens and OS-aware themes
 
-`import 'apexcharts/features/facet'`
+`import 'apexcharts/features/facet'`: Tier 1 (already in the default bundle).
 
 Charts read `--apx-*` CSS custom properties from the cascade, follow the OS light/dark and contrast preferences with no JS, and can reference named brand themes.
 
@@ -265,7 +360,7 @@ Built-in curve names: `linear`, `easeInSine`, `easeOutSine`, `easeInOutSine`, `e
 
 ## Link: crossfilter and cross-chart coordination
 
-`import 'apexcharts/features/link'`
+`import 'apexcharts/features/link'`: **Tier 2** (not in the default bundle) and **premium**.
 
 **Premium** (watermarked in trial mode until an entitled license is set, see Licensing above).
 
@@ -303,7 +398,7 @@ const b = {
 
 ## Ink: direct-manipulation annotation authoring
 
-`import 'apexcharts/features/ink'`
+`import 'apexcharts/features/ink'`: **Tier 2** (not in the default bundle) and **premium**.
 
 **Premium** (watermarked in trial mode until an entitled license is set, see Licensing above).
 
@@ -327,7 +422,7 @@ const options = {
 
 ## Measure: delta ruler
 
-`import 'apexcharts/features/measure'`
+`import 'apexcharts/features/measure'`: **Tier 2** (not in the default bundle) and **premium**.
 
 **Premium** (watermarked in trial mode until an entitled license is set, see Licensing above).
 
@@ -376,7 +471,7 @@ const options = {
 
 ## Context menu: Radial Actions
 
-`import 'apexcharts/features/context-menu'`
+`import 'apexcharts/features/context-menu'`: **Tier 2** (not in the default bundle) and **premium**.
 
 **Premium** (watermarked in trial mode until an entitled license is set, see Licensing above).
 
@@ -404,7 +499,7 @@ Built-in `annotate` / `xline` / `yline` items are ink-managed when the ink featu
 
 ## Storyboard: scroll-driven choreography (scrollytelling)
 
-`import 'apexcharts/features/storyboard'` (includes Perspectives)
+`import 'apexcharts/features/storyboard'` (registers Perspectives too): **Tier 2** (not in the default bundle) and **premium**.
 
 **Premium** (watermarked in trial mode until an entitled license is set, see Licensing above).
 
@@ -442,7 +537,7 @@ const options = { chart: { streaming: { enabled: true, maxPoints: 100000 } } }
 
 ## Drilldown: hierarchical drill-down
 
-`import 'apexcharts/features/drilldown'` (add `import 'apexcharts/features/morph'` for animated cross-type transitions)
+`import 'apexcharts/features/drilldown'` (add `import 'apexcharts/features/morph'` for animated cross-type transitions): both Tier 1 (already in the default bundle).
 
 Data points reference a child level via a `drilldown` id; clicking drills in, with an optional breadcrumb. Since **v6.9** drilldown also works on **line and area** charts, and levels can be resolved **async** against a backend.
 
@@ -494,7 +589,7 @@ chart.drillToRoot()
 
 ## Stats: raw-sample statistics (6.9.0)
 
-`import 'apexcharts/features/stats'`
+`import 'apexcharts/features/stats'`: Tier 1 (already in the default bundle).
 
 Free. The statistics behind three things, kept out of core so they cost nothing unless used:
 
@@ -536,8 +631,11 @@ const options = {
 
 ## Common Pitfalls
 
-1. **Forgetting the feature import**: every v6 feature is off until you `import 'apexcharts/features/<name>'` (or use the full `apexcharts` bundle). Enabling the config alone does nothing if the feature isn't in the bundle.
-2. **Using `api.zeroY` in a custom mark**: it does not exist. Use `ctx.scales.y(0)` for the baseline.
-3. **Expecting `mode: 'filter'` on `chart.link` without records**: highlight mode needs `chart.selection.enabled: true`; the crossfilter engine needs `ApexCharts.crossfilter({ id, records })` or a `dimension` extractor.
-4. **`largeDatasetThreshold` is under `chart.animations`**, not `chart` directly.
-5. **Assuming the canvas renderer supports everything**: pattern/image fills and per-point selection visuals fall back to (or stay) SVG.
+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.
+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.
+5. **Expecting `mode: 'filter'` on `chart.link` without records**: highlight mode needs `chart.selection.enabled: true`; the crossfilter engine needs `ApexCharts.crossfilter({ id, records })` or a `dimension` extractor.
+6. **Two different `largeDatasetThreshold` options.** `chart.animations.largeDatasetThreshold` (default 1000) skips update animations; `markers.largeDatasetThreshold` *(v7.0, default 0 = off)* batches a series' markers into one path. Neither lives on `chart` directly.
+7. **Assuming the canvas renderer supports everything**: pattern/image fills and per-point selection visuals fall back to (or stay) SVG.
+8. **Calling `getPanel(key)` on a virtualized trellis**: it returns `null` for a panel that is not currently mounted (grids over 64 panels virtualize by default).