apexcharts-skill 2.1.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,18 @@
 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`.
 
 ---
 
@@ -182,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
@@ -195,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'
@@ -213,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`.
@@ -307,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'`.
+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

@@ -8,7 +8,7 @@
 - **Radial Bar** (`'radialBar'`): Circular progress chart (one or more concentric tracks)
 - **Gauge** (`'gauge'`, **new in v6**): Single-value gauge with arc/needle shapes, colored bands, and ticks
 - **Sunburst** (`'sunburst'`, **new in v6.7, free**): Hierarchical nested pie/donut; concentric rings, one per level
-- **Unit / Waffle** (`'unit'` / `'waffle'`, **new in v6.6, premium**): One mark per unit of value (dot clusters, pictograms, waffles, beeswarms, parliament)
+- **Unit / Waffle** (`'unit'` / `'waffle'`, **new in v6.6, premium**): One mark per unit of value (dot clusters, pictograms, waffles, beeswarms, parliament, custom layouts and the v6.10 shape kit)
 
 ## Tree-Shakeable Import
 
@@ -26,8 +26,16 @@ import ApexCharts from 'apexcharts/sunburst'
 
 import ApexCharts from 'apexcharts/unit'
 // Registers: unit + waffle (v6.6). Premium: watermarked until a license is set.
+
+import { heart, outlined, glyphs, preview } from 'apexcharts/unit-shapes'
+// Unit-chart shape kit (v6.10), named exports tree-shaken per shape. See "Unit shapes" below.
+
+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
@@ -149,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:
 
@@ -168,11 +176,103 @@ Data is the same flat number array + `labels` shape as pie:
 - `packed`: one shared blob, coloured by group (`sortByGroup: true` nests the minority in the centre).
 - `columns`: each category is a vertical bar built from stacked dots (a waffle column).
 - `grid`: one waffle lattice, a part-to-whole square "pie" (`grid.total: 100` rounds it to a fixed cell budget for a percentage waffle; `grid.split: true` makes small-multiple mini-waffles).
-- `scatter`: a beeswarm on real value axes (`scatter.y: 'lanes'` default, or `'value'` for a 2D value-value plot; `scatter.sizeRange` for area-scaled bubbles).
+- `scatter`: a beeswarm on real value axes (`scatter.y: 'lanes'` default, or `'value'` for a 2D value-value plot; `scatter.sizeRange` for area-scaled bubbles). Since **v6.7.1** `scatter.orientation: 'horizontal' | 'vertical'` picks the beeswarm axis (lanes mode only): `'horizontal'` (default) puts the value on X with category lanes on Y; `'vertical'` puts the value on Y with lanes as columns. The value-axis keys (`xMin`/`xMax`/`xTitle`/`xFormatter`/`tickAmount`) describe the value axis in both orientations.
 - `arc` (**v6.7**): a parliament / hemicycle, seats in concentric arced rows across an annulus, filled in category order.
+- `custom` (**v6.9**): positions come from you. `plotOptions.unit.positions` is either a function `(objects, rect) => [{ id, x, y, r? }]` or the name of a layout registered with `ApexCharts.registerUnitLayout(name, fn)`. `objects` carries identity and data per mark (`{ id, index, seriesIndex, dataPointIndex, label, value, datum, r }`), `rect` is the plot area in pixels. A layout is objects in, positions out; the engine already tweens position, radius, and colour and keeps mark identity across a relayout. Marks whose id the provider omits animate out; unknown ids are ignored.
 
 **Also available:** `shape` (`'circle'` | `'square'` | `'image'` pictogram with `image.tint`); per-mark object data `series: [{ name, data: [{ value, x, z, name, fillColor, id }] }]`; `transition` (`'group'` default | `'flow'` crowd migration | `'identity'` keyed by `id`/`name`); numeric or `'auto'` dot `size`; `sizeByValue` bubbles; `unitValue` (1 mark = N units); `maxUnits` cap; per-cluster `clusterLabels`; and per-mark `tooltip.formatter`.
 
+**Motion (v6.9):** marks travel on a damped spring by default, so an update landing mid-flight retargets with the marks' velocity instead of restarting them (a dragged slider reads as continuous motion, not stutter). Configure via `plotOptions.unit.gather`: `motion: 'auto' | 'spring' | 'tween'`, `spring: 'crisp' | 'gentle' | 'snappy'`, `easing: 'outCubic' | 'inOutCubic' | 'outBack'` (setting `easing` implies tween), and `enter: 'burst' | 'fade' | 'rise'`.
+
+### Unit shapes (`apexcharts/unit-shapes`, v6.10)
+
+A companion kit of **39 shapes** a count can take (a heart, a house, a globe, the figure 1,024 drawn in 1,024 dots). Each shape is a plain callable layout, so it plugs straight into `plotOptions.unit.positions` with `layout: 'custom'`; no registration step. The entry point is tree-shaken per shape (about 4 KB gzipped each). Dots are packed to fill the outline, so one shape serves 40 dots in a sparkline and 3,000 in a poster.
+
+```js
+import ApexCharts from 'apexcharts'
+import { heart } from 'apexcharts/unit-shapes'
+
+new ApexCharts(el, {
+  chart: { type: 'unit' },
+  series: [57600, 16800, 4200, 3400],
+  labels: ['Repeat donors', 'First-time', 'Workplace drives', 'Emergency call-ups'],
+  plotOptions: {
+    unit: { layout: 'custom', positions: heart, unitValue: 100 },
+  },
+}).render()
+```
+
+Three kinds:
+
+- **Silhouettes** (29, filled outlines): `heart`, `house`, `tree`, `leaf`, `flame`, `droplet`, `fish`, `sun`, `human`, `group`, `star`, `crown`, `trophy`, `moneybag`, `funnel`, `shield`, `gear`, `robot`, `bulb`, `flask`, `car`, `plane`, `rocket`, `battery`, `pin`, `mountain`, `cross`, `bolt`, `arrow`.
+- **Strokes** (7, packed centrelines for things with no interior): `check`, `wifi`, `pulse`, `xmark`, `percent`, `question`, `spiral`.
+- **Generated** (3, positions from maths, no outline): `globe`, `target`, `pyramid`.
+
+Composition helpers (also exported from `apexcharts/unit-shapes`):
+
+```js
+outlined(heart)                  // hollow twin: trace the outline instead of filling it (silhouettes only)
+heart.with({ order: 'cols' })    // variant: where each series band lands ('rows' | 'rowsUp' | 'cols' |
+                                 // 'colsRev' | 'centerOut' | 'centerIn'); battery fills like a charge
+                                 // meter because its order is 'cols'
+glyphs('1,024')                  // a number, drawn in that many dots (digits plus '-', '.', ',', ':')
+preview(heart, { series })       // render to a standalone SVG string, no chart and no DOM (build-time galleries)
+shapeFrom(path, opts?)           // your own outline, packed like the catalog's
+strokeFrom(path, opts?)          // your own centreline
+registerShapes([...])            // register so positions: '<name>' resolves by string
+```
+
+Every shape carries metadata on `shape` (category, kind, and `minUnits`: the count below which it stops being recognisable; asking for fewer logs a console warning naming the shape). From a script tag, `dist/unit-shapes.js` exposes the kit as the global `ApexUnitShapes` with every shape pre-registered, so `positions: 'heart'` works by name.
+
+### 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
+plotOptions: {
+  unit: { clusterLabels: { external: { show: true } } },
+}
+```
+
+`clusterLabels.external` also takes `connector: { show, width, color, gap, length }`, `offsetX`, `offsetY`. It applies to `layout: 'custom'` only and reads best on silhouettes whose category bands stack vertically. The gutter is reserved before the dot size is chosen, so the shape stays centred but renders slightly smaller.
+
 `waffle` is a thin alias of `unit` that presets the `grid` layout with square cells. With `grid.total: 100` the values are largest-remainder rounded to exactly 100 cells, so the grid reads as percentages. The original alias is preserved on the read-only `chart.requestedType`; an explicit `layout` or `shape` still wins.
 
 ```js
@@ -211,7 +311,17 @@ plotOptions: {
   pie: {
     startAngle: 0,
     endAngle: 360,
-    expandOnClick: true,       // expand slice on click
+    expandOnClick: true,       // react to a slice click at all
+    expandOffset: 10,          // (v6.9) how far the clicked slice slides out (px) along its mid-angle.
+                               // The slice is translated, not redrawn bigger, so the quantity it
+                               // encodes is unchanged. 0 keeps it in place. Ignored for polarArea.
+    hoverOutline: {            // (v6.9) hover traces a translucent band outside the slice rim
+      show: true,              // instead of lightening the fill
+      size: 8,                 // band thickness (px)
+      gap: 0,                  // clearance between slice rim and band (px)
+      opacity: 0.3,
+      color: undefined         // defaults to the hovered slice's own color
+    },
     offsetX: 0,
     offsetY: 0,
 
@@ -377,3 +487,8 @@ plotOptions: {
 8. **Gauge value outside `min`/`max`**: unlike a plain radialBar (fixed 0-100), a gauge maps its value to the `min..max` domain you set. A value beyond that domain saturates at the arc ends.
 9. **Legend click now toggles the slice (v6.7 behavior change)**: on pie, donut, and polarArea a legend click hides and shows the slice (like other chart types). Previously it darkened and expanded the slice. If your app relied on the old darken-and-expand behavior, review this.
 10. **Expecting `unit` / `waffle` without a license to be watermark-free**: they are premium and render an `APEXCHARTS` watermark until an entitled `premium`/`enterprise` license is set. Sunburst, by contrast, is free.
+11. **Slice click behavior changed (v6.9)**: clicking a pie/donut slice now slides it out along its own mid-angle (`plotOptions.pie.expandOffset`, default 10 px) instead of darkening it and redrawing it at a larger radius, and hover traces an outline band (`plotOptions.pie.hoverOutline`) instead of lightening the fill. Set `expandOffset: 0` to keep slices in place; set `states.hover.filter.type: 'none'` to suppress the hover band.
+12. **Unit shapes below `minUnits`**: each `apexcharts/unit-shapes` shape declares the minimum dot count at which it still reads. Feeding fewer units logs a console warning naming the shape; pick a simpler shape or raise `unitValue` so the count lands above the threshold.
+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.