apexcharts 7.2.0 → 7.4.0

package/src/modules/weave/PluginAPI.js

@@ -20,12 +20,22 @@
  * v3 added `api.reserve()`, for a plugin that renders its own UI inside the
  * chart's container and needs the chart to make room for it.
  *
+ * v4 added `api.pointer()`, so a plugin can learn which data point a viewer is
+ * pointing at or has selected. The chart already computed that for its own
+ * tooltip and its `dataPoint*` events; before this a plugin either re-derived
+ * it from raw pixels or did without.
+ *
+ * v5 added `api.info.stroke`, the caller's own `stroke.dashArray`. That option
+ * is indexed by series position, so a plugin that wants its own derived series
+ * dashed must write the whole array; reporting the current value is what lets
+ * it put back what it found instead of flattening the caller's dashed lines.
+ *
  * Feature-detect rather than bumping `apiVersion` unless the plugin genuinely
  * cannot work without the new surface: a plugin declaring v3 is SKIPPED
  * outright on a v2 host, so `apiVersion: 2` plus `typeof api.reserve ===
  * 'function'` keeps one build working on both.
  */
-export const WEAVE_API_VERSION = 3
+export const WEAVE_API_VERSION = 5
 
 /**
  * Public chart methods safe to expose to plugins (each bound to ctx). Excludes
@@ -302,6 +312,21 @@ export function buildPluginAPI(host, record) {
             ? w.config.dataLabels.enabledOnSeries.slice()
             : null,
         }),
+        // The caller's own dashing, reported for the same reason and against
+        // the same trap (v5). `stroke.dashArray` is indexed by series position
+        // with no per-series escape hatch, so a plugin that wants ITS OWN
+        // computed series dashed has to write the whole array, and writing one
+        // without knowing what was there discards the caller's dashed lines
+        // with nothing to restore them from.
+        //
+        // A scalar applies to every series and an array is per series. There is
+        // no "unset" to report: the option defaults to 0, and 0 already means
+        // no dashing, so restoring it restores exactly what was there.
+        stroke: Object.freeze({
+          dashArray: Array.isArray(w.config.stroke && w.config.stroke.dashArray)
+            ? w.config.stroke.dashArray.slice()
+            : (w.config.stroke && w.config.stroke.dashArray) || 0,
+        }),
       })
     },
 
@@ -372,6 +397,37 @@ export function buildPluginAPI(host, record) {
       return api
     },
 
+    /**
+     * Subscribe to the data point a viewer is pointing at.
+     *
+     * The chart already knows this: it resolves the series and point under the
+     * pointer for its own tooltip and fires `dataPointMouseEnter`,
+     * `dataPointMouseLeave` and `dataPointSelection` for the caller. This
+     * forwards the same three, so a plugin gets the host's answer rather than
+     * hit-testing the SVG itself and disagreeing with the tooltip.
+     *
+     * The payload is normalised rather than the chart's own argument list,
+     * which passes `w`. A plugin must not receive `w`, and the three things a
+     * plugin actually wants (which series, which point, what the point is
+     * called) are exactly what the chart has already resolved.
+     *
+     * `category` is the resolved display label, the same string `api.categories`
+     * carries, because a plugin coordinating two charts keys on the label
+     * rather than on an index that means something different on each chart.
+     *
+     * Nothing here gives a plugin the ability to intercept or cancel: the
+     * chart's own tooltip, selection state and caller events are unaffected,
+     * and a handler that throws is contained rather than allowed to break the
+     * interaction it was watching.
+     *
+     * @param {(e: {type: 'enter'|'leave'|'select', seriesIndex: number, dataPointIndex: number, category: string|undefined, seriesName: string|undefined, selected: boolean|undefined}) => void} fn
+     * @returns {() => void} unsubscribe
+     * @since Weave v4
+     */
+    pointer(fn) {
+      return host._onPointer(record.def.name, fn)
+    },
+
     // ── custom events out to the host app ──
     /**
      * Fires as `plugin:<pluginName>:<name>` on the chart's event bus. The

package/src/modules/weave/WeaveHost.js

@@ -50,6 +50,10 @@ export default class WeaveHost {
     this._reserved = null
     /** @type {any} pending re-render for a changed reservation */
     this._reserveTimer = null
+    /** @type {Map<string, Function[]>|null} plugin name -> pointer handlers */
+    this._pointerSubs = null
+    /** @type {Array<[string, Function]>|null} chart listeners to remove on teardown */
+    this._pointerWired = null
 
     this._onUpdated = this._onUpdated.bind(this)
     this._init()
@@ -385,6 +389,143 @@ export default class WeaveHost {
     this._repairInitialSeries()
   }
 
+  /**
+   * Subscribe a plugin to the data point the viewer is pointing at.
+   *
+   * Wired lazily: a chart whose plugins never ask pays nothing, and the chart
+   * fires these three events whether or not anyone is listening, so there is no
+   * cost to the chart either way.
+   *
+   * The chart's own handler signature is `(e, ctx, {seriesIndex,
+   * dataPointIndex, w})`. `w` stops here: what reaches a plugin is the
+   * normalised payload documented on `api.pointer`.
+   *
+   * @param {string} pluginName
+   * @param {Function} fn
+   * @returns {() => void} unsubscribe
+   */
+  _onPointer(pluginName, fn) {
+    if (typeof fn !== 'function') return () => {}
+    if (!this._pointerSubs) this._pointerSubs = new Map()
+    const list = this._pointerSubs.get(pluginName) || []
+    list.push(fn)
+    this._pointerSubs.set(pluginName, list)
+    this._wirePointer()
+    return () => {
+      const current = this._pointerSubs && this._pointerSubs.get(pluginName)
+      if (!current) return
+      const i = current.indexOf(fn)
+      if (i > -1) current.splice(i, 1)
+    }
+  }
+
+  /** Attach to the chart's own data point events, once. */
+  _wirePointer() {
+    if (this._pointerWired) return
+    if (!this.ctx || typeof this.ctx.addEventListener !== 'function') return
+    /** @type {Array<['enter'|'leave'|'select', string]>} */
+    const map = [
+      ['enter', 'dataPointMouseEnter'],
+      ['leave', 'dataPointMouseLeave'],
+      ['select', 'dataPointSelection'],
+    ]
+    this._pointerWired = []
+    for (const [type, name] of map) {
+      const handler = (/** @type {any} */ _e, /** @type {any} */ _ctx, /** @type {any} */ opts) => {
+        this._emitPointer(type, opts)
+      }
+      this.ctx.addEventListener(name, handler)
+      this._pointerWired.push([name, handler])
+    }
+  }
+
+  /**
+   * Hand one pointer event to every subscribed plugin.
+   *
+   * A handler that throws is contained per plugin, on the same terms as every
+   * other plugin callback here: this runs inside the viewer's own hover, and a
+   * plugin breaking the chart's interaction would be the worst failure mode
+   * this facade has.
+   *
+   * @param {'enter'|'leave'|'select'} type
+   * @param {any} opts
+   */
+  _emitPointer(type, opts) {
+    if (!this._pointerSubs || !this._pointerSubs.size) return
+    const seriesIndex = opts && typeof opts.seriesIndex === 'number' ? opts.seriesIndex : -1
+    const dataPointIndex =
+      opts && typeof opts.dataPointIndex === 'number' ? opts.dataPointIndex : -1
+    // The host's OWN category resolution, the same one `api.categories` reads.
+    // `globals.labels` is the raw slot list and on a category axis it is
+    // [1,2,3,4], so keying a cross-chart selection on it would key on a number
+    // that means something different on every chart. Measured: a chart with
+    // xaxis.categories ['Jan'..'Apr'] reported category 3 rather than 'Mar'.
+    const labels = this._categories() || []
+    const w = this.w
+    const config = (w && w.config && w.config.series) || []
+    const payload = {
+      type,
+      seriesIndex,
+      dataPointIndex,
+      category: dataPointIndex > -1 ? labels[dataPointIndex] : undefined,
+      // A pie/donut carries bare numbers in `series`, so there is no name to
+      // read: undefined rather than a guess, on the same terms as `category`.
+      seriesName: WeaveHost._seriesName(config, seriesIndex),
+      // Only meaningful on a select: the chart hands back its whole selection
+      // set, and what a plugin wants to know is whether THIS point is now in
+      // it, so a second click reads as a deselect rather than another select.
+      selected: type === 'select' ? WeaveHost._isSelected(opts, seriesIndex, dataPointIndex) : undefined,
+    }
+    for (const [name, handlers] of this._pointerSubs) {
+      for (const fn of handlers.slice()) {
+        try {
+          fn(payload)
+        } catch (e) {
+          console.warn(
+            '[apexcharts] plugin "' + name + '" threw in a pointer handler',
+            e
+          )
+        }
+      }
+    }
+  }
+
+  /**
+   * The configured name of series `i`, where there is one.
+   *
+   * @param {any[]} config
+   * @param {number} i
+   * @returns {string|undefined}
+   */
+  static _seriesName(config, i) {
+    if (i < 0) return undefined
+    const entry = config[i]
+    if (!entry || typeof entry !== 'object') return undefined
+    return typeof entry.name === 'string' ? entry.name : undefined
+  }
+
+  /**
+   * Whether the chart now counts this point as selected.
+   *
+   * `selectedDataPoints` is an array per series of the indexes selected in it.
+   * Absent on a chart type that does not carry point selection, in which case
+   * the answer is undefined rather than false: "not selected" and "selection
+   * does not apply here" are different, and a plugin keying on it should be
+   * able to tell.
+   *
+   * @param {any} opts
+   * @param {number} seriesIndex
+   * @param {number} dataPointIndex
+   * @returns {boolean|undefined}
+   */
+  static _isSelected(opts, seriesIndex, dataPointIndex) {
+    const all = opts && opts.selectedDataPoints
+    if (!Array.isArray(all) || seriesIndex < 0) return undefined
+    const mine = all[seriesIndex]
+    if (!Array.isArray(mine)) return false
+    return mine.indexOf(dataPointIndex) > -1
+  }
+
   /**
    * Record a plugin's container reservation and re-render if it changed.
    *
@@ -657,6 +798,13 @@ export default class WeaveHost {
       this.active = []
       this._derived = null
       this._reserved = null
+      this._pointerSubs = null
+      if (this._pointerWired) {
+        for (const [name, handler] of this._pointerWired) {
+          this.ctx.removeEventListener && this.ctx.removeEventListener(name, handler)
+        }
+        this._pointerWired = null
+      }
       // Nothing left to re-render for, and firing this after a destroy would
       // call update() on a torn-down chart.
       if (this._reserveTimer != null) {

package/src/ssr/DOMShim.js

@@ -4,6 +4,14 @@
  * Provides just enough SVG element emulation to create chart structure without full DOM
  */
 
+// Approximate sans-serif metrics, in em, used to estimate SVG text bounds when
+// no font engine is available to measure the glyphs.
+const CHAR_WIDTH_EM = 0.55
+const ASCENT_EM = 0.917
+const DESCENT_EM = 0.25
+const LINE_HEIGHT_EM = 1.1
+const DEFAULT_FONT_SIZE = 11
+
 /**
  * Mock SVG element for SSR environment
  */
@@ -148,6 +156,48 @@ class SSRElement {
     }
   }
 
+  getBBox() {
+    if (this.nodeName !== 'text' && this.nodeName !== 'tspan') {
+      return { x: 0, y: 0, width: 0, height: 0 }
+    }
+
+    const lines = this._textLines()
+    const longest = lines.reduce((acc, line) => Math.max(acc, line.length), 0)
+    if (!longest) {
+      return { x: 0, y: 0, width: 0, height: 0 }
+    }
+
+    const fontSize =
+      parseFloat(this.attributes.get('font-size')) || DEFAULT_FONT_SIZE
+    const width = longest * fontSize * CHAR_WIDTH_EM
+    const height =
+      fontSize * (ASCENT_EM + DESCENT_EM) +
+      (lines.length - 1) * fontSize * LINE_HEIGHT_EM
+
+    const anchor = this.attributes.get('text-anchor')
+    const x = parseFloat(this.attributes.get('x')) || 0
+    const y = parseFloat(this.attributes.get('y')) || 0
+
+    return {
+      x: anchor === 'middle' ? x - width / 2 : anchor === 'end' ? x - width : x,
+      y: y - fontSize * ASCENT_EM,
+      width,
+      height,
+    }
+  }
+
+  /**
+   * Text of this element, one entry per rendered line
+   * @returns {string[]}
+   */
+  _textLines() {
+    const tspans = this.children.filter((child) => child.nodeName === 'tspan')
+    if (tspans.length) {
+      return tspans.map((tspan) => String(tspan.textContent ?? ''))
+    }
+    return [String(this.textContent ?? '')]
+  }
+
   getRootNode() {
     /** @type {SSRElement} */
     let root = this

package/src/types/internal.d.ts

@@ -802,7 +802,7 @@ export interface ChartContext {
   eventList: string[]
 
   // Public methods on the ApexCharts instance
-  update(options?: any): Promise<any>
+  update(options?: any, overwriteInitialSeries?: boolean): Promise<any>
   getSyncedCharts(): any[]
   getGroupedCharts(): any[]
   fastUpdate(animate?: boolean, prevAxisScaleSig?: string): Promise<any>

package/src/utils/Utils.js

@@ -75,15 +75,12 @@ class Utils {
   }
 
   // A per-series shallow copy: the series OBJECTS are copied, their data arrays
-  // are shared. Almost every internal "mutation" of a series' data is a
-  // property REPLACEMENT (`series[i].data = []` on legend collapse,
-  // `series[i] = 0` for non-axis charts), and those cannot reach a copy made
-  // this way because the series object was copied at capture time. The
-  // exception is appendData(), whose push loop grows the shared data array in
-  // place, so a copy taken before it does see the appended points; see the
-  // note above defineLazyInitialSeries(). This is the same cheap shape
-  // `globals.initialSeries` captures, so snapshotting a config stays O(n)
-  // instead of deep-cloning every point.
+  // are shared. Every internal "mutation" of a series' data is a property
+  // REPLACEMENT (`series[i].data = []` on legend collapse, `series[i] = 0` for
+  // non-axis charts, appendData's concat), and those cannot reach a copy made
+  // this way because the series object was copied at capture time. This is the
+  // same cheap shape `globals.initialSeries` captures, so snapshotting a config
+  // stays O(n) instead of deep-cloning every point.
   /**
    * @param {any} series
    */

package/types/apexcharts.d.ts

@@ -1878,6 +1878,17 @@ type ApexChart = {
      * @default 'auto'
      */
     pinch?: boolean | 'auto'
+    /**
+     * The way back out of a zoom on a chart whose toolbar is hidden. While the
+     * chart is zoomed and nothing else on screen can reset it, one reset
+     * control is drawn where the toolbar would have been, and it goes when the
+     * range does; `Escape` resets the zoom as well. `'auto'` supplies both only
+     * where there is no reset button already, `true` also forces the control on
+     * where `toolbar.tools.reset` is off, and `false` turns both off for a page
+     * that supplies its own reset. Requires `enabled: true`.
+     * @default 'auto'
+     */
+    resetControl?: boolean | 'auto'
     zoomedArea?: {
       fill?: {
         color?: string
@@ -2656,6 +2667,12 @@ type ApexPlotOptions = {
     distributed?: boolean
     borderRadius?: number;
     borderRadiusApplication?: 'around' | 'end';
+    /**
+     * Which segments of a stack round. 'all' (default) caps both ends of the
+     * stack, the baseline and the far end; 'last' caps only the far end so
+     * the stack sits square on the baseline. Stacked bar/column only.
+     */
+    borderRadiusWhenStacked?: 'all' | 'last';
     hideZeroBarsWhenGrouped?: boolean
     rangeBarOverlap?: boolean
     rangeBarGroupRows?: boolean