apexcharts-skill 2.2.0 → 3.0.0

package/references/financial-charts.md

@@ -6,6 +6,7 @@
 - **Box Plot** (`'boxPlot'`) — Statistical distribution chart showing min, Q1, median, Q3, max
 - **Violin** (`'violin'`, **new in v6**): Statistical distribution chart showing a density curve per category, optionally with the raw sample points overlaid as jitter
 - **Histogram** (`'histogram'`, **new in v6.9**): Bins raw observations into columns; the series carries the sample, the chart does the aggregating
+- **Raincloud** (`'raincloud'`, **new in v7.1, premium, Tier 2**): A distribution shown three ways at once: a half-violin for the shape, a box for the summary, and the observations themselves as "rain" underneath
 
 ## Tree-Shakeable Import
 
@@ -20,12 +21,17 @@ import ApexCharts from 'apexcharts/violin'
 import ApexCharts from 'apexcharts/histogram'
 // Registers: histogram (v6.9), the bar engine plus the stats feature
 
+import ApexCharts from 'apexcharts/raincloud'
+// Registers: raincloud (v7.1), the violin engine plus the raincloud feature
+
 // The statistics (histogram binning, boxPlot/violin raw-sample summaries,
 // rowSeries()) live behind one optional feature. apexcharts/histogram already
 // includes it; boxPlot/violin raw samples need it explicitly when tree-shaking:
 import 'apexcharts/features/stats'
 ```
 
+**⚠️ 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.
+
 **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).
 
 ---
@@ -216,6 +222,65 @@ The series carries **raw observations** (a flat number array, or `{ y }` objects
 - `overlap: true` (the default with multiple series) also softens the fill and drops the bin separator stroke so the overlapping region reads; both remain overridable. A single series is unaffected either way.
 - Do NOT pass pre-aggregated counts; that is a plain `bar` chart. The histogram's job is the binning.
 
+### Raincloud (v7.1, premium, Tier 2)
+
+`chart.type: 'raincloud'` shows a distribution three ways at once: the **half-violin** is the shape, the **box** is the summary, and the **rain** underneath is the observations themselves. You hand it the raw values and it does the rest.
+
+```js
+import ApexCharts from 'apexcharts'
+import 'apexcharts/raincloud'   // Tier 2: required even on the full bundle
+
+new ApexCharts(el, {
+  chart: { type: 'raincloud', height: 350 },
+  series: [{
+    name: 'Weight gain',
+    data: [
+      { x: 'Control',   points: [3.1, 4.7, 2.9, 5.2, 3.8, 4.1] },
+      { x: 'Treatment', points: [6.4, 7.1, 5.8, 6.9, 7.6, 6.2] },
+    ],
+  }],
+}).render()
+```
+
+Raincloud is a **preset over the violin engine**, so it is configured through `plotOptions.violin`. The type sets three of those defaults for you:
+
+| `plotOptions.violin` key | Raincloud preset | Plain violin default |
+|---|---|---|
+| `side` | `'right'` (or `'top'` when horizontal), a half-violin | `'both'` |
+| `box.show` | `true` (the "umbrella") | `false` |
+| `box.whiskers` | `'tukey'` (1.5×IQR fences clamped to the data) | `'minmax'` |
+| `points.position` | `'left'` (or `'bottom'` when horizontal), the "rain" gets its own lane | `'center'` |
+
+Everything else is the violin surface, so override it there:
+
+```js
+plotOptions: {
+  violin: {
+    box: {
+      width: '15%',        // fraction of the category slot reserved for the box lane
+      capWidth: 0.5,       // whisker cap length, 0..1 of the box lane width
+      fillColor: undefined,// defaults to the series colour
+      strokeWidth: 1,
+    },
+    points: {
+      laneWidth: '40%',    // fraction of the category slot for the off-centre lane
+      jitter: 0.5,         // 0..1 of the half-width to scatter within
+      size: 3,
+      maxPoints: undefined,// cap per violin; observations beyond it are stride-thinned
+      fillColor: 'series-dark', // or 'series', or any literal colour
+      strokeColor: '#fff',
+      strokeWidth: 1,
+    },
+    kde: { bandwidth: undefined, resolution: 64 },
+    normalize: 'individual',  // or 'group' to keep widths proportional across categories
+  },
+}
+```
+
+The rain **is** the outlier display, so the box draws no outlier dots of its own. Off-centre dots ignore `constrainToViolin`. A `y.summary` supplied by hand as `[whiskerLow, q1, median, q3, whiskerHigh]` is drawn exactly as given rather than derived.
+
+**The alias rewrites `chart.type` to `'violin'` at runtime.** Code that reads the live config (a formatter reading `w.config.chart.type`, a `chart.getState()` consumer, a plugin) sees `'violin'`, not `'raincloud'`; the requested type is kept on `chart.requestedType`. Branch on `requestedType` if you need to tell a raincloud from a plain violin. This is also how licensing distinguishes them: plain violins are free and never watermark.
+
 ### `rowSeries()`: the rows behind a summary mark (v6.9)
 
 A histogram bin, a box, and a violin all stand for rows the chart is already holding. `chart.rowSeries()` returns them as a unit-chart series (one cluster per mark, one datum per row), so a summary can be opened into its observations:
@@ -318,3 +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'`.
+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/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`, 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**: the only chart type absent from the default bundle. |
 | `apexcharts/histogram` | histogram *(new in v6.9)*: the bar engine plus the stats feature |
 | `apexcharts/pie` | pie, donut, polarArea |
 | `apexcharts/donut` | same as /pie |
@@ -40,8 +62,19 @@ Each entry point registers a family of related chart types:
 | `apexcharts/sunburst` | sunburst *(new in v6.7, free)* |
 | `apexcharts/unit` | unit, **waffle** *(new in v6.6, premium: watermarked until licensed)* |
 | `apexcharts/unit-shapes` | *(new in v6.10)* not a chart entry: named shape exports for the unit chart (`heart`, `house`, ... plus `outlined`, `glyphs`, `preview`), tree-shaken per shape (~4 KB gzipped each). See `references/circular-charts.md`. |
+| `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 +86,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.
 
-Features are optional modules that add functionality. When using per-type entries or core, features must be explicitly imported.
+### Tier 1: in the default `apexcharts` bundle
+
+Import these only when you started from `/core` or a per-type entry.
 
 | Feature | Import | What It Adds |
 |---|---|---|
@@ -65,33 +105,78 @@ 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>
+```
+
+**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.
+
+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 +256,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` type 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.