apexcharts 8.2.0 → 8.3.0

package/src/modules/legend/HeatmapGradientLegend.js

@@ -48,6 +48,8 @@ export default class HeatmapGradientLegend {
     this._max = 0
     /** @type {any} */
     this._geom = null
+    /** @type {any} */
+    this._grad = null
     /** @type {any[]} */
     this._bandHitEls = []
     /** @type {number} Currently highlighted band index (-1 = none). */
@@ -58,6 +60,8 @@ export default class HeatmapGradientLegend {
      * @type {HTMLElement|null}
      */
     this._targetEl = null
+    /** @type {(() => any[])|null} detached mode: every panel's w */
+    this.panelsW = null
     this._onCellEnter = this._onCellEnter.bind(this)
     this._onCellLeave = this._onCellLeave.bind(this)
     this._onBandEnter = this._onBandEnter.bind(this)
@@ -217,15 +221,8 @@ export default class HeatmapGradientLegend {
       linearGrad.setAttribute('y2', '0')
     }
 
-    const { min, max, stops, bands } = this._computeStops()
-    this._min = min
-    this._max = max
-    stops.forEach((s) => {
-      const stopEl = BrowserAPIs.createElementNS(SVG_NS, 'stop')
-      stopEl.setAttribute('offset', `${(s.percent * 100).toFixed(2)}%`)
-      stopEl.setAttribute('stop-color', s.color)
-      linearGrad.appendChild(stopEl)
-    })
+    this._grad = linearGrad
+    const { min, max, bands } = this._paintStops()
     defs.appendChild(linearGrad)
     svg.appendChild(defs)
 
@@ -498,6 +495,9 @@ export default class HeatmapGradientLegend {
    * Honors `legend.offsetX/offsetY` for user nudging. Safe to call repeatedly.
    */
   repositionToPlot() {
+    // The cells' y extent and hasNegs exist only now (draw runs before
+    // coreCalculations), so shade the strip again against them.
+    if (this._grad) this._paintStops()
     if (!Environment.isBrowser()) return
     // Detached mode (trellis): the host slot owns layout entirely.
     if (this._targetEl) return
@@ -672,7 +672,7 @@ export default class HeatmapGradientLegend {
     if (idx < 0 || idx === this._activeBandIndex) return
     this._activeBandIndex = idx
     this.ctx?.events?.fireEvent?.('legendHover', [this.ctx, idx, w])
-    new Series(w).highlightRangeInSeries(idx, 'highlight')
+    this._highlightRange(idx, 'highlight')
   }
 
   /** Leaving a band clears the highlight. */
@@ -680,7 +680,18 @@ export default class HeatmapGradientLegend {
     if (this._activeBandIndex < 0) return
     const idx = this._activeBandIndex
     this._activeBandIndex = -1
-    new Series(this.w).highlightRangeInSeries(idx, 'reset')
+    this._highlightRange(idx, 'reset')
+  }
+
+  /**
+   * A shared trellis strip sets `panelsW` so a band reaches every panel.
+   * @param {number} idx
+   * @param {'highlight'|'reset'} action
+   */
+  _highlightRange(idx, action) {
+    ;(this.panelsW?.() || [this.w]).forEach((/** @type {any} */ w) =>
+      new Series(w).highlightRangeInSeries(idx, action),
+    )
   }
 
   _attachHoverListeners() {
@@ -702,11 +713,12 @@ export default class HeatmapGradientLegend {
    * @param {...any} args
    */
   _onCellEnter(...args) {
-    const w = this.w
     if (!this.arrowEl) return
     // The opts object is the last argument.
     const opts = args[args.length - 1]
     if (!opts || typeof opts !== 'object') return
+    // the hovered chart: a shared trellis strip hears every panel
+    const w = opts.w || this.w
     const i = opts.seriesIndex
     const j = opts.dataPointIndex
     if (typeof i !== 'number' || typeof j !== 'number') return
@@ -845,6 +857,22 @@ export default class HeatmapGradientLegend {
     return polygon
   }
 
+  /** (Re)write the strip's stops; returns `_computeStops()`. */
+  _paintStops() {
+    const r = this._computeStops()
+    const grad = this._grad
+    this._min = r.min
+    this._max = r.max
+    grad.innerHTML = ''
+    r.stops.forEach((s) => {
+      const stopEl = BrowserAPIs.createElementNS(SVG_NS, 'stop')
+      stopEl.setAttribute('offset', `${(s.percent * 100).toFixed(2)}%`)
+      stopEl.setAttribute('stop-color', s.color)
+      grad.appendChild(stopEl)
+    })
+    return r
+  }
+
   /**
    * Build gradient stops + return effective min/max.
    * - If `colorScale.ranges` is set, stops are placed at each range boundary
@@ -898,7 +926,9 @@ export default class HeatmapGradientLegend {
     // one-sided = the historical expand-not-clamp semantics.
     let min = dataMin
     let max = dataMax
-    if (typeof cs.min !== 'undefined' && typeof cs.max !== 'undefined' && cs.max > cs.min) {
+    const csWindow =
+      typeof cs.min !== 'undefined' && typeof cs.max !== 'undefined' && cs.max > cs.min
+    if (csWindow) {
       min = cs.min
       max = cs.max
     } else {
@@ -956,45 +986,46 @@ export default class HeatmapGradientLegend {
       // is the documented behavior).
       const baseColor = w.globals.colors[0] || '#008FFB'
       const utils = new Utils()
-      const plot = w.config.plotOptions[w.config.chart.type] || {}
+      const type = w.config.chart.type
+      const plot = w.config.plotOptions[type] || {}
       const shadeIntensity = plot.shadeIntensity ?? 0.5
-      const hasNegs = /** @type {any} */ (w.globals).hasNegs
+      const g = /** @type {any} */ (w.globals)
+      const hasNegs = g.hasNegs
+      // A non-distributed heatmap's cells shade against the niced y extent
+      // and clamp into it (determineColor); use it once coreCalculations ran.
+      // A one-sided colorScale.max past maxY is ignored there, so cap at maxY.
+      const yExt =
+        type === 'heatmap' && !plot.distributed && !csWindow && g.maxY >= g.minY
+      const hi = yExt ? g.maxY : max
+      const total =
+        Math.abs(hi) + Math.abs(yExt ? (cs.min < g.minY ? cs.min : g.minY) : min)
+      const k = shadeIntensity * 1.25
       const n = Math.max(2, cfg.stops || 16)
       for (let s = 0; s < n; s++) {
         const t = s / (n - 1) // 0..1
-        // Map t to the shade percent the cell at that t would receive.
+        // Map t to the shade fraction the cell at that t would receive.
         // determineColor computes percent = 100*val/(|min|+|max|), so the cell
-        // sitting at value v = min + t*(max-min) gets percent_v.
-        const v = min + t * (max - min)
-        const total = Math.abs(max) + Math.abs(min)
-        const percent_v = total === 0 ? 0 : (100 * v) / total
-        let colorShadePercent
-        if (hasNegs) {
-          if (plot.reverseNegativeShade) {
-            colorShadePercent =
-              percent_v < 0
-                ? (percent_v / 100) * (shadeIntensity * 1.25)
-                : (1 - percent_v / 100) * (shadeIntensity * 1.25)
-          } else {
-            colorShadePercent =
-              percent_v <= 0
-                ? 1 - (1 + percent_v / 100) * shadeIntensity
-                : (1 - percent_v / 100) * shadeIntensity
-          }
-        } else {
-          colorShadePercent = 1 - percent_v / 100
-        }
-        // Clamp to a reasonable range to avoid color blowout.
-        if (colorShadePercent > 1) colorShadePercent = 1
-        if (colorShadePercent < -1) colorShadePercent = -1
+        // sitting at value v = min + t*(max-min) gets p = v / total.
+        const p =
+          total === 0 ? 0 : Math.min(min + t * (max - min), hi) / total
+        // Clamp to a reasonable range to avoid color blowout. Treemap tiles
+        // scale the plain shade too (getShadeColor).
+        const c = Math.max(
+          -1,
+          Math.min(
+            1,
+            hasNegs
+              ? plot.reverseNegativeShade
+                ? (p < 0 ? p : 1 - p) * k
+                : p <= 0
+                  ? 1 - (1 + p) * shadeIntensity
+                  : (1 - p) * shadeIntensity
+              : (1 - p) * (type === 'treemap' ? k : 1),
+          ),
+        )
 
         const shaded = plot.enableShades
-          ? utils.shadeColor(
-              w.config.theme.mode === 'dark'
-                ? colorShadePercent * -1
-                : colorShadePercent,
-              baseColor,
-            )
+          ? utils.shadeColor(w.config.theme.mode === 'dark' ? -c : c, baseColor)
           : baseColor
         stops.push({ percent: t, color: shaded })
       }

package/src/modules/legend/Helpers.js

@@ -55,6 +55,8 @@ export default class Helpers {
    */
   toggleDataSeries(seriesCnt, isHidden) {
     const w = this.w
+    // a legendClick handler may have destroyed the chart
+    if (!w.dom.baseEl) return
     if (w.globals.axisCharts || w.config.chart.type === 'radialBar') {
       w.globals.resized = true // we don't want initial animations again
 

package/src/modules/legend/Legend.js

@@ -74,6 +74,11 @@ class Legend {
     const gl = w.globals
     const cnf = w.config
 
+    // Tear down any previous gradient legend every render, so hiding the
+    // legend does not leave its listeners and repositioning behind.
+    this.heatmapGradientLegend?.destroy()
+    this.heatmapGradientLegend = null
+
     // Recompute each render: the Legend instance is reused across updates, so a
     // value cached in the constructor would go stale when updateOptions changes
     // the type / distributed flag / series count (e.g. a distributed single-series
@@ -106,12 +111,6 @@ class Legend {
         elLegendWrap.removeChild(elLegendWrap.firstChild)
       }
 
-      // Tear down any previous gradient-legend listeners before re-rendering.
-      if (this.heatmapGradientLegend) {
-        this.heatmapGradientLegend.destroy()
-        this.heatmapGradientLegend = null
-      }
-
       if (HeatmapGradientLegend.isEnabled(w)) {
         this.heatmapGradientLegend = new HeatmapGradientLegend(w, this.ctx)
         this.heatmapGradientLegend.draw()
@@ -381,7 +380,8 @@ class Legend {
       // by index: groups may reuse series names, and an unnamed series has
       // none to match
       const lg = legendGroups[w.labelData.seriesGroupIndex[i]]
-      if (lg) elLegendWrap.appendChild(lg)
+      // once: re-appending moves the group, reordering interleaved groups
+      if (lg && !lg.parentNode) elLegendWrap.appendChild(lg)
       ;(lg || elLegendWrap).appendChild(elLegend)
 
       elLegendWrap.classList.add(
@@ -537,10 +537,8 @@ class Legend {
     const hoverOverLegend = isLegendItem(target)
 
     if (w.config.chart.type !== 'heatmap' && !this.isBarsDistributed) {
-      if (
-        !target.classList.contains('apexcharts-inactive-legend') &&
-        hoverOverLegend
-      ) {
+      // closest: the text span of a hidden item carries no inactive class
+      if (hoverOverLegend && !target.closest('.apexcharts-inactive-legend')) {
         const series = new Series(this.ctx.w)
         series.toggleSeriesOnHover(e, target)
       }
@@ -585,7 +583,8 @@ class Legend {
       // can keep toggling without having to re-tab to the legend.
       if (rel !== null && w.config.legend.onItemClick.toggleDataSeries) {
         requestAnimationFrame(() => {
-          const restored = w.dom.baseEl.querySelector(
+          // the chart may have been destroyed before this frame
+          const restored = w.dom.baseEl?.querySelector(
             `.apexcharts-legend-series[rel="${rel}"]`,
           )
           if (restored) /** @type {HTMLElement} */ (restored).focus()

package/src/modules/settings/Options.js

@@ -788,7 +788,14 @@ export default class Options {
           // asked for and nobody can undo is a trap. Set either to true to
           // force the gesture on regardless (for a page that supplies its own
           // reset control), or false to turn it off outright.
+          //
+          // The 'auto' wheel is also cooperative: a bare wheel scrolls the
+          // page, and Ctrl/Cmd + wheel (or a trackpad pinch) zooms, so a page
+          // of charts scrolls past them. `true` zooms on every wheel.
           allowMouseWheelZoom: 'auto',
+          // With the cooperative wheel, a bare scroll over the chart briefly
+          // shows how to zoom it ("Use Ctrl + scroll to zoom").
+          wheelHint: true,
           // Momentum: two-finger pinch-zoom on touch devices. Zooms the x-axis
           // around the pinch centroid (matching the x-only wheel/toolbar zoom),
           // frame-by-frame rather than the 400ms wheel throttle.

package/src/modules/streamgraph/StreamLabels.js

@@ -276,6 +276,7 @@ export default class StreamLabels {
               maxWidth: span,
               fontSize: `${px}px`,
               fontFamily,
+              fontWeight,
             })
       if (!text || text === '...') continue
       const drawnWidth =

package/src/modules/tooltip/Tooltip.js

@@ -2137,14 +2137,28 @@ export default class Tooltip {
         shared: this.showOnIntersect ? false : this.tConfig.shared,
       })
 
-      if (hasMarkers || dynamicPoints) {
+      // A shared tooltip speaks for every series at `j`, so in a combo the
+      // line's hover dots and the columns' hover state both follow it,
+      // whichever series the pointer is nearest. Only the box goes to the
+      // captured series' mark. Gating the bars on the captured series having
+      // no markers left the dots on the last column the line was nearest to.
+      const capturedPoints = hasMarkers || dynamicPoints
+      if (
+        capturedPoints ||
+        (w.globals.comboCharts &&
+          !canvasMode &&
+          this.tooltipUtil.hasVisibleMarkers())
+      ) {
         handlePoints()
-      } else if (this.tooltipUtil.hasBars()) {
+      }
+      if (this.tooltipUtil.hasBars()) {
         if (canvasMode) {
           // canvas: bars/candles paint to the bitmap, so the paths /
           // hover-filter machinery below is DOM-only. Position straight off
           // the cached bar coords.
-          ttCtx.tooltipPosition.moveStickyTooltipOverBars(j, capturedSeries)
+          if (!capturedPoints) {
+            ttCtx.tooltipPosition.moveStickyTooltipOverBars(j, capturedSeries)
+          }
         } else if (
           [...bars].some((/** @type {Element} */ b) => b.querySelector('path'))
         ) {
@@ -2157,7 +2171,9 @@ export default class Tooltip {
           // de-activate first
           this.deactivateHoverFilter()
 
-          ttCtx.tooltipPosition.moveStickyTooltipOverBars(j, capturedSeries)
+          if (!capturedPoints) {
+            ttCtx.tooltipPosition.moveStickyTooltipOverBars(j, capturedSeries)
+          }
 
           for (let b = 0; b < paths.length; b++) {
             graphics.pathMouseEnter(

package/src/modules/tooltip/Utils.js

@@ -714,6 +714,14 @@ export default class Utils {
     return markers.length > 0
   }
 
+  /**
+   * Whether any visible series has a marker node, its points' or its hover
+   * dot's.
+   */
+  hasVisibleMarkers() {
+    return this.getAllMarkers(true).some(Boolean)
+  }
+
   /**
    * @param {any} point
    * @param {number} size

package/src/modules/trellis/Trellis.js

@@ -1032,8 +1032,14 @@ export default class Trellis {
         // gap is the breathing room here).
         parentHeightOffset: 0,
         toolbar: { show: false },
+        // the shared toolbar owns the one reset (TrellisSync.resetAll); with
+        // toolbar 'none' a panel's own reset is the only way back, unless the
+        // page turned it off
         zoom: {
           enabled: this.cfg.zoom !== 'none',
+          resetControl:
+            this.cfg.toolbar == 'none' &&
+            w.config.chart.zoom.resetControl !== false,
         },
         ...(animationsOff ? { animations: { enabled: false } } : {}),
         // Grid-level canvas auto-selection (P2): a uniform explicit backend,

package/src/modules/trellis/TrellisChrome.js

@@ -44,6 +44,8 @@ export default class TrellisChrome {
     this.gradientLegend = null
     /** @type {(() => void)|null} unsubscribe for a deferred gradient build */
     this._gradPending = null
+    /** @type {any} the strip's panel hover wiring (and panelMounted hook) */
+    this._gradWire = null
   }
 
   /**
@@ -299,17 +301,24 @@ export default class TrellisChrome {
     const legend = new HeatmapGradientLegend(chart.w, chart.ctx)
     legend.draw(slot)
     this.gradientLegend = legend
+    // a band highlights its range in every mounted panel
+    legend.panelsW = () =>
+      t.panels.filter((p) => p.chart).map((p) => /** @type {any} */ (p.chart).w)
 
     // The instance's own hover wiring only hears ITS panel; mirror the same
-    // handlers onto every other mounted panel so the arrow follows the
-    // cursor anywhere in the grid.
-    t.panels.forEach((p) => {
-      if (!p.chart || p === mounted) return
-      const ev = /** @type {any} */ (p.chart).ctx?.events
-      if (!ev?.addEventListener) return
+    // handlers onto every other panel, mounted now or later, so the arrow
+    // follows the cursor anywhere in the grid. Doubles as the host's
+    // panelMounted listener (ctx, { chart }).
+    /** @type {any} */
+    const wire = (/** @type {any} */ _, /** @type {any} */ p) => {
+      const ev = p.chart !== chart && p.chart?.ctx.events
+      if (!ev) return
       ev.addEventListener('dataPointMouseEnter', legend._onCellEnter)
       ev.addEventListener('dataPointMouseLeave', legend._onCellLeave)
-    })
+    }
+    t.panels.forEach((p) => wire(0, p))
+    t.ctx.events.addEventListener('panelMounted', wire)
+    this._gradWire = wire
   }
 
   /** Tear down the shared gradient strip (P5). */
@@ -319,6 +328,8 @@ export default class TrellisChrome {
       t.ctx.events.removeEventListener?.('panelMounted', this._gradPending)
       this._gradPending = null
     }
+    // the panels' own buses die with them right after (teardown)
+    t.ctx.events.removeEventListener('panelMounted', this._gradWire)
     if (this.gradientLegend) {
       try {
         this.gradientLegend.destroy()

package/src/modules/trellis/TrellisSync.js

@@ -310,6 +310,8 @@ export default class TrellisSync {
       })
     }
     const loop = () => {
+      // a teardown (rebuild or destroy) under a resting pointer ends the loop
+      if (elGrid !== this.trellis.elGrid) return (raf = 0)
       apply()
       raf = hoverTarget ? requestAnimationFrame(loop) : 0
     }

package/src/renderers/canvas/CanvasGraphics.js

@@ -1023,6 +1023,7 @@ export default class CanvasGraphics {
     cmd.strokeWidth = opts.strokeWidth
     cmd.fill = opts.fill
     cmd.lineCap = opts.strokeLinecap
+    cmd.strokeDash = this._g.seriesDash(opts.realIndex)
     cmd.si = opts.realIndex
     // Data point identity. Only a mark that stands for one point (a bar-like:
     // Bar.renderSeries) passes `j`; a line or area path stands for the whole

package/src/ssr/DOMShim.js

@@ -59,6 +59,16 @@ class SSRElement {
     this.attributes.set(name, value)
   }
 
+  /**
+   * Namespaced attributes serialize by their qualified name.
+   * @param {any} _ns
+   * @param {string} name
+   * @param {any} value
+   */
+  setAttributeNS(_ns, name, value) {
+    this.setAttribute(name, value)
+  }
+
   /**
    * @param {string} name
    */

package/src/types/internal.d.ts

@@ -110,6 +110,12 @@ export interface InteractState {
     rafId: number | null
     endTimer: any
   }
+  // Cooperative wheel: fade-out timer for the "Ctrl + scroll to zoom" hint.
+  wheelHintTimer?: any
+  // Keyboard nav handing focus across an update that replaces the SVG:
+  // [seriesIndex, dataPointIndex, active, tooltipDismissed], set on destroy,
+  // taken on init.
+  keyNav?: [number, number, boolean, boolean] | null
 }
 
 /** Label formatter functions — lives on `w.formatters` */
@@ -569,9 +575,9 @@ export interface ChartGlobals
   seriesYvalues: number[][]
   seriesYAxisMap: number[][]
   seriesYAxisReverseMap: number[]
-  barGroups: string[]
-  lineGroups: string[]
-  areaGroups: string[]
+  barGroups: number[]
+  lineGroups: number[]
+  areaGroups: number[]
   hasSeriesGroups: boolean
 
   // ── Layout extras (ephemeral) ─────────────────────────────────────────────

package/types/apexcharts.d.ts

@@ -336,11 +336,11 @@ declare class ApexCharts {
   /** Returns the sum of all data points whose x value falls within [minX, maxX]. */
   getSeriesTotalXRange(minX: number, maxX: number): number[]
 
-  /** Returns the highest y value in the specified series. */
-  getHighestValueInSeries(seriesIndex?: number): number
+  /** Returns the highest y value in the specified series, or undefined for an index with no series. */
+  getHighestValueInSeries(seriesIndex?: number): number | undefined
 
-  /** Returns the lowest y value in the specified series. */
-  getLowestValueInSeries(seriesIndex?: number): number
+  /** Returns the lowest y value in the specified series, or undefined for an index with no series. */
+  getLowestValueInSeries(seriesIndex?: number): number | undefined
 
   /** Returns the sum of each series (totals used for percentage calculations). */
   getSeriesTotal(): number[]
@@ -2236,13 +2236,21 @@ type ApexChart = {
     type?: 'x' | 'y' | 'xy'
     autoScaleYaxis?: boolean
     /**
-     * Cursor-anchored zoom on mouse wheel / trackpad. `'auto'` enables it only
-     * when the toolbar's reset button is present, so an unintended scroll-zoom
-     * is always undoable; `true` forces it on even with the toolbar hidden.
-     * Requires `enabled: true`.
+     * Cursor-anchored zoom on mouse wheel / trackpad. `'auto'` is cooperative:
+     * a bare wheel scrolls the page, and Ctrl/Cmd + wheel (or a trackpad
+     * pinch) zooms. It is offered only when the toolbar's reset button is
+     * present, so a zoom is always undoable. `true` zooms on every wheel, even
+     * with the toolbar hidden. Requires `enabled: true`.
      * @default 'auto'
      */
     allowMouseWheelZoom?: boolean | 'auto'
+    /**
+     * With the cooperative `'auto'` wheel, a bare scroll over the chart
+     * briefly shows how to zoom it. The text is the locale's
+     * `toolbar.wheelZoomHint`, where `{key}` becomes Ctrl or ⌘.
+     * @default true
+     */
+    wheelHint?: boolean
     /**
      * Momentum: enable two-finger pinch-zoom on touch devices. Zooms the x-axis
      * around the pinch centroid, frame-by-frame. `'auto'` enables it only when
@@ -2869,6 +2877,8 @@ type ApexLocale = {
       exportToSVG?: string
       exportToPNG?: string
       exportToCSV?: string
+      /** The cooperative wheel's hint; `{key}` becomes Ctrl or ⌘. Default 'Use {key} + scroll to zoom'. */
+      wheelZoomHint?: string
     }
     /** The highlight filter add-on's words. */
     highlightFilter?: {
@@ -3781,7 +3791,8 @@ type ApexPlotOptions = {
      * recolours) across a regroup - the circles-to-bars transition.
      * 'identity': keyed by each datum's `id`/`name`, so a SPECIFIC unit migrates
      * across any regroup or relayout keeping its colour and size. Requires the
-     * per-unit object form with unique ids/names.
+     * per-unit object form with unique ids/names (a repeated one is tracked by
+     * its order of appearance).
      */
     transition?: 'group' | 'flow' | 'identity'
     /**
@@ -3919,7 +3930,10 @@ type ApexPlotOptions = {
       sizeField?: string
       /** `[minRadius, maxRadius]` in px: turns dots into area-scaled bubbles. */
       sizeRange?: [number, number]
-      /** Left-gutter width reserved for lane (category) labels (lanes mode). */
+      /**
+       * Left-gutter width reserved for lane (category) labels (lanes mode).
+       * Defaults to the widest label, up to a third of the plot.
+       */
       laneLabelWidth?: number
       /** Draw the faint gridlines. Defaults to true. */
       gridlines?: boolean
@@ -3991,7 +4005,11 @@ type ApexPlotOptions = {
     borderRadius?: number
     /** 1 dot represents this many units of value (waffle scaling). */
     unitValue?: number
-    /** Safety cap on total dots; counts scale down proportionally above it. */
+    /**
+     * Safety cap on total dots; counts scale down proportionally above it (a
+     * scatter keeps an even sample of each category). A split grid draws a
+     * fixed number of cells per tile and is not capped.
+     */
     maxUnits?: number
     /** Packed layout: order categories smallest-first (minority centred). */
     sortByGroup?: boolean
@@ -5327,7 +5345,8 @@ interface ApexUnitObject {
    * Stable identity. The datum's own `id`/`name` when the per-unit object form
    * supplies one, so a provider can address a specific unit ("Texas",
    * "employee 41") rather than a positional slot; otherwise
-   * `"<seriesIndex>:<dataPointIndex>"`.
+   * `"<seriesIndex>:<dataPointIndex>"`. A repeated one is suffixed by its
+   * order of appearance (`"Alex#2"`).
    */
   id: string
   /** Global draw order across every category. */