apexcharts 7.3.0 → 7.5.0

package/src/modules/helpers/UpdateHelpers.js

@@ -180,9 +180,10 @@ export default class UpdateHelpers {
                 ? prevInitialSeries
                 : Utils.copySeriesShallow(w.config.series)
             w.globals.initialConfig = initialConfig
-            // lazy snapshot: deep clone deferred to first read
-            w.globals.initialSeries = w.config.series
-
+            if (options.series) {
+              // lazy snapshot: deep clone deferred to first read
+              w.globals.initialSeries = w.config.series
+            }
           }
 
           // Keep legend-hidden (collapsed) series hidden across ANY series
@@ -277,6 +278,9 @@ export default class UpdateHelpers {
         w.globals.treemapRawSeries = null
       }
 
+      const definedSeries = newSeries
+      let reconciledCollapses = false
+
       // Keep legend-hidden (collapsed) series hidden across a data update,
       // reconciled BY CATEGORY NAME by the same code the options path uses: a
       // name still present stays hidden at its possibly-new index, one the
@@ -299,11 +303,15 @@ export default class UpdateHelpers {
           s && typeof s === 'object' ? { ...s } : s,
         )
         this.ctx.series.reconcileCollapsedByName(newSeries)
+        reconciledCollapses = true
       }
 
       this.ctx.data.resetParsingFlags()
       // Phase 1: return value captured; writer stubs are no-ops.
-      const parsedState = this.ctx.data.parseData(newSeries)
+      const parsedState = this.ctx.data.parseData(
+        newSeries,
+        overwriteInitialSeries,
+      )
       this.ctx._writeParsedSeriesData(parsedState.seriesData)
       this.ctx._writeParsedRangeData(parsedState.rangeData)
       this.ctx._writeParsedCandleData(parsedState.candleData)
@@ -315,14 +323,23 @@ export default class UpdateHelpers {
         // defined. A copy, never the live array: this site used to assign
         // w.config.series itself, restoring the very alias #5118 came from, so
         // one updateSeries() would undo the capture Globals.init now makes.
-        // initialSeries was already captured by parseData above through the
-        // lazy-snapshot setter, so no deep clone happens here either.
+        // Both snapshots come off the array the caller handed in once the
+        // reconcile above has run, since that emptied the collapsed rows and
+        // parseData baselines from what it parses: the baseline would forget
+        // the data of exactly the series the viewer switched off.
+        // _updateOptions gets this for free, it reconciles after capturing.
         if (w.globals.initialConfig) {
           w.globals.initialConfig.series = Utils.copySeriesShallow(
-            w.config.series,
+            reconciledCollapses ? definedSeries : w.config.series,
           )
         }
-        w.globals.initialSeries = w.config.series
+        // With no reconcile, initialSeries stays as parseData left it: on the
+        // raw-stash and dataReducer types config.series holds rows this library
+        // derived, and reassigning it here made the baseline the bin counts,
+        // the accumulated pairs or the downsampled window (#5283).
+        if (reconciledCollapses) {
+          w.globals.initialSeries = definedSeries
+        }
       }
 
       // Use the fast path when the series structure is compatible:

package/src/modules/settings/Globals.js

@@ -554,16 +554,11 @@ export default class Globals {
    * which cannot reach the captured copies because each series object was
    * copied at capture time.
    *
-   * The one in-place mutator is appendData(), whose push loop grows the shared
-   * data array. Re-capturing after it does not undo that: the pushed points
-   * are already in the array both snapshots point at, so a snapshot taken
-   * before the append reads back as appended. That is the documented
-   * behaviour of appendData(overwriteInitialSeries = true), and the `false`
-   * case is not honoured for a separate, older reason: Data.parseData()
-   * re-captures initialSeries unconditionally on the re-render appendData
-   * triggers. Detaching would mean copying the data arrays, which is exactly
-   * the per-point cost this snapshot exists to avoid. The same exception
-   * applies to `initialConfig.series`, which is captured with the same shape.
+   * appendData() used to be the exception, growing the shared data array in
+   * place. It now replaces the array instead (`data = data.concat(newData)`):
+   * one array copy per call, against the per-point cost this snapshot exists
+   * to avoid. With that, no internal edit can reach a captured copy. The same
+   * holds for `initialConfig.series`, which is captured with the same shape.
    *
    * @param {Record<string, any>} globals
    */

package/src/modules/settings/Options.js

@@ -769,6 +769,17 @@ export default class Options {
           // around the pinch centroid (matching the x-only wheel/toolbar zoom),
           // frame-by-frame rather than the 400ms wheel throttle.
           pinch: 'auto',
+          // Drag-to-zoom is deliberate, so it is not gated the way those two
+          // are: it stays on with the toolbar hidden. The reset button that
+          // undoes it does not, which leaves the viewer in a window with no
+          // exit. So 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. A chart nobody zooms is
+          // untouched. Set false for a page that supplies its own reset (which
+          // also turns off the Escape shortcut), or true to force the control
+          // on whenever the chart is zoomed, even where `toolbar.tools.reset`
+          // is off.
+          resetControl: 'auto',
           zoomedArea: {
             fill: {
               color: '#90CAF9',
@@ -832,6 +843,10 @@ export default class Options {
           distributed: false,
           borderRadius: 0,
           borderRadiusApplication: 'around', // [around, end]
+          // Which segments of a stack round. 'all' caps both ends of the
+          // stack (baseline and far end); 'last' caps only the far end, so
+          // the stack sits square on the baseline. Stacked charts only.
+          borderRadiusWhenStacked: 'all', // [all, last]
           rangeBarOverlap: true,
           rangeBarGroupRows: false,
           hideZeroBarsWhenGrouped: false,

package/src/modules/weave/Claims.js

@@ -0,0 +1,231 @@
+// @ts-check
+/**
+ * Positional option claims: how a plugin sets an option for ITS OWN series.
+ *
+ * Some chart options are indexed by series position with no per-series escape
+ * hatch. `stroke.dashArray` is the clearest: a plugin that adds a projection and
+ * wants only the projection dashed has to write the array covering every series.
+ * Done in the plugin, that has four failure modes, three of which no amount of
+ * care can fix:
+ *
+ *   1. it flattens the caller's own dashes, unless it first reads them,
+ *   2. it restores a stale value if the caller changed the option meanwhile,
+ *   3. it leaks the write permanently if the plugin throws before restoring,
+ *   4. two plugins fight, and whichever releases last restores the other's write.
+ *
+ * So the plugin declares a CLAIM and the host answers the question where the
+ * option is READ. Nothing is written to `w.config`: the caller's configuration
+ * is what it always was, and a claim is an overlay consulted at the point of
+ * use. Releasing a claim is therefore not a restore, it is a deletion, and
+ * there is nothing to put back or to get wrong.
+ *
+ * ## Why this is an allowlist
+ *
+ * An unbounded `claim(path, value)` is "write anything to the caller's config",
+ * which is the thing this platform refuses to do. An option earns a place here
+ * only if it is positional, has no per-series alternative in the caller's own
+ * data, and is read in few enough places to resolve at all. `colors` fails the
+ * second test: a series carries its own `color`, so a plugin adding one sets it
+ * there and needs nothing from the host.
+ *
+ * ## Where the state lives
+ *
+ * On `w`, beside `dom` and `interact`, for the reason those two are there
+ * rather than in globals: `initGlobalVars` runs again on every `resetGlobals`,
+ * so anything in globals is wiped by an `updateSeries`. A claim has to survive
+ * a caller's update, because the point of it is that the caller's own changes
+ * and the plugin's claim compose instead of overwriting each other. Created
+ * lazily, so a chart with no claims carries nothing and a build without the
+ * Weave host never creates it at all.
+ *
+ * See `plans/26-weave-capabilities.md`.
+ *
+ * @module weave/Claims
+ */
+
+/**
+ * Options a plugin may claim, and the value type each takes per series.
+ *
+ * Adding a row is a decision about the three-part test in this file's header,
+ * not a convenience. `tests/unit/weave-claims.spec.js` asserts the shape of
+ * this table so a row cannot be added without one.
+ *
+ * `dataLabels.enabledOnSeries` is a membership list in the caller's config and
+ * a boolean here on purpose: a claim answers "does THIS series print labels",
+ * which is the question the consumption site asks, rather than restating the
+ * caller's list shape.
+ */
+export const CLAIMABLE = Object.freeze({
+  'stroke.dashArray': Object.freeze({ type: 'number' }),
+  'dataLabels.enabledOnSeries': Object.freeze({ type: 'boolean' }),
+})
+
+/**
+ * @typedef {Object} ClaimEntry
+ * @property {string|number} series  a series NAME, or a position
+ * @property {any} value
+ */
+
+/**
+ * @typedef {Object} ClaimRecord
+ * @property {string} owner
+ * @property {string} option
+ * @property {ClaimEntry[]} entries
+ */
+
+/**
+ * The per-chart store, created on first claim.
+ * @param {any} w
+ */
+function store(w) {
+  if (!w.weaveClaims) w.weaveClaims = { byOption: new Map() }
+  return w.weaveClaims
+}
+
+/** @param {any} w @param {string} option @returns {ClaimRecord[]} */
+function claimsFor(w, option) {
+  const s = store(w)
+  if (!s.byOption.has(option)) s.byOption.set(option, [])
+  return s.byOption.get(option)
+}
+
+/**
+ * Keep the entries this option can actually use, warning about the rest.
+ *
+ * A bad entry is dropped rather than failing the whole claim: a plugin claiming
+ * ten series and getting one wrong should still dash the nine, and the warning
+ * names the option and the value so the tenth is findable.
+ *
+ * @param {string} option
+ * @param {any} entries
+ * @returns {ClaimEntry[]}
+ */
+export function normaliseEntries(option, entries) {
+  const spec = /** @type {Record<string, {type: string}>} */ (CLAIMABLE)[option]
+  const out = []
+  for (const entry of Array.isArray(entries) ? entries : []) {
+    if (!entry || (typeof entry.series !== 'string' && typeof entry.series !== 'number')) {
+      console.warn(
+        `[apexcharts] claim on "${option}": each entry needs a series name or index.`,
+      )
+      continue
+    }
+    if (typeof entry.value !== spec.type) {
+      console.warn(
+        `[apexcharts] claim on "${option}": expected a ${spec.type} for series ${String(
+          entry.series,
+        )}, got ${typeof entry.value}.`,
+      )
+      continue
+    }
+    out.push({ series: entry.series, value: entry.value })
+  }
+  return out
+}
+
+/**
+ * Register a claim. Returns null for an option that is not claimable, so a
+ * plugin written against a newer host degrades instead of throwing.
+ *
+ * @param {any} w
+ * @param {string} owner  plugin name
+ * @param {string} option
+ * @param {any} entries
+ * @returns {ClaimRecord|null}
+ */
+export function addClaim(w, owner, option, entries) {
+  if (!Object.prototype.hasOwnProperty.call(CLAIMABLE, option)) {
+    console.warn(
+      `[apexcharts] "${option}" is not a claimable option. Claimable: ${Object.keys(
+        CLAIMABLE,
+      ).join(', ')}.`,
+    )
+    return null
+  }
+  const record = { owner, option, entries: normaliseEntries(option, entries) }
+  // Appended, so the LAST claim on a series wins and the order is the order
+  // plugins ran in. Deterministic, and independent of render order.
+  claimsFor(w, option).push(record)
+  return record
+}
+
+/**
+ * Drop one claim. Idempotent: releasing twice is not an error.
+ * @param {any} w
+ * @param {ClaimRecord} record
+ */
+export function releaseClaim(w, record) {
+  if (!w.weaveClaims || !record) return
+  const list = w.weaveClaims.byOption.get(record.option)
+  if (!list) return
+  const at = list.indexOf(record)
+  if (at > -1) list.splice(at, 1)
+}
+
+/**
+ * Drop every claim held by one plugin.
+ *
+ * Called on teardown and when the host disables a plugin after repeated hook
+ * failures, which is what makes failure mode 3 unreachable: a plugin cannot
+ * leave a claim behind, however badly it behaves.
+ *
+ * @param {any} w
+ * @param {string} owner
+ */
+export function releaseOwner(w, owner) {
+  if (!w.weaveClaims) return
+  for (const [option, list] of w.weaveClaims.byOption) {
+    const kept = list.filter((/** @type {ClaimRecord} */ c) => c.owner !== owner)
+    if (kept.length !== list.length) w.weaveClaims.byOption.set(option, kept)
+  }
+}
+
+/**
+ * Which series an entry names, or -1.
+ *
+ * A NAME is resolved here rather than at claim time, which is what lets a claim
+ * survive the caller adding, removing or reordering series: the position a name
+ * resolves to is read fresh every time the option is. A number is taken as a
+ * position, for charts whose series have no names.
+ *
+ * @param {any} w @param {string|number} series
+ */
+function indexOfSeries(w, series) {
+  if (typeof series === 'number') return series
+  const list = (w.config && w.config.series) || []
+  for (let i = 0; i < list.length; i++) {
+    if (list[i] && list[i].name === series) return i
+  }
+  return -1
+}
+
+/**
+ * The value of a claimable option for one series: a claim if one names it,
+ * otherwise what the caller configured.
+ *
+ * The hot path is the absence of claims, which is every chart that has no
+ * plugin doing this: one property check and out. Call it with the value the
+ * caller's config resolves to, so this file never has to know the shape of
+ * an option, only that a claim overrides it.
+ *
+ * @template T
+ * @param {any} w
+ * @param {string} option
+ * @param {number} seriesIndex
+ * @param {T} fallback  what the caller's own config says for this series
+ * @returns {T}
+ */
+export function resolveClaimed(w, option, seriesIndex, fallback) {
+  if (!w || !w.weaveClaims) return fallback
+  const list = w.weaveClaims.byOption.get(option)
+  if (!list || !list.length) return fallback
+
+  let resolved = fallback
+  // Forwards, so the last claim naming this series wins: see addClaim.
+  for (const claim of list) {
+    for (const entry of claim.entries) {
+      if (indexOfSeries(w, entry.series) === seriesIndex) resolved = entry.value
+    }
+  }
+  return resolved
+}

package/src/modules/weave/Drawn.js

@@ -0,0 +1,169 @@
+// @ts-check
+/**
+ * What is drawn on this chart, as one list a plugin can read.
+ *
+ * A plugin sees the chart through the facade, and the facade told it about the
+ * chart's series and nothing else: not the caller's annotations, not another
+ * feature's ink, not another plugin's overlay. So the panel everyone reaches
+ * for first (list what is on this chart, so a viewer can see what is there)
+ * could only ever enumerate the asking plugin's own tools, which its toolbar
+ * already shows.
+ *
+ * The alternative to this file is one narrow member per question: a Layers API,
+ * then an export that wants to list contents, then an a11y summary. Publishing
+ * the inventory once answers all three.
+ *
+ * ## Read only, deliberately
+ *
+ * Nothing here removes or hides anything. A list you can act on means letting a
+ * plugin change another feature's output, which is a much larger promise than
+ * this platform makes today and is a decision of its own. See
+ * `plans/26-weave-capabilities.md` §3.4.
+ *
+ * ## Partial by design, and it says so
+ *
+ * Every contributor is opt in. A feature that declares nothing is simply absent
+ * rather than approximated, which is why each entry carries `owner`: a reader
+ * can tell what the list covers instead of assuming it is exhaustive.
+ *
+ * @module weave/Drawn
+ */
+
+/**
+ * @typedef {Object} DrawnItem
+ * @property {string} id      stable within this chart, opaque to readers
+ * @property {'series'|'annotation'|'overlay'} kind
+ * @property {string} label   a human name where one exists
+ * @property {string} owner   'core', or the plugin name that put it there
+ * @property {boolean} visible
+ */
+
+/** Annotation buckets in config, in the order a reader meets them. */
+const ANNOTATION_TYPES = ['xaxis', 'yaxis', 'points', 'texts', 'images']
+
+/**
+ * Whether the viewer has switched this series off in the legend.
+ *
+ * Both collapse lists, because a series on a secondary axis lands in the
+ * ancillary one and is just as hidden to the person looking at the chart.
+ *
+ * @param {any} w @param {number} index
+ */
+function seriesVisible(w, index) {
+  const gl = w.globals
+  return (
+    (gl.collapsedSeriesIndices || []).indexOf(index) < 0 &&
+    (gl.ancillaryCollapsedSeriesIndices || []).indexOf(index) < 0
+  )
+}
+
+/**
+ * The chart's own series, including any a plugin added.
+ *
+ * Owner comes from the same `markDerived` bookkeeping that protects a caller's
+ * reset, so a computed series is attributed to the plugin that computed it
+ * rather than to the chart.
+ *
+ * @param {any} w @param {any} host @returns {DrawnItem[]}
+ */
+function seriesItems(w, host) {
+  const derived = host && host._derived
+  /** @param {string} name */
+  const ownerOf = (name) => {
+    if (!derived) return 'core'
+    for (const [plugin, names] of derived) {
+      if (names.indexOf(name) > -1) return plugin
+    }
+    return 'core'
+  }
+
+  return (w.config.series || []).map((/** @type {any} */ s, /** @type {number} */ i) => {
+    const label = s && s.name ? String(s.name) : `Series ${i + 1}`
+    return {
+      id: `series:${i}`,
+      kind: /** @type {const} */ ('series'),
+      label,
+      owner: ownerOf(label),
+      visible: seriesVisible(w, i),
+    }
+  })
+}
+
+/**
+ * The caller's annotations, and anything that draws by creating one.
+ *
+ * Ink strokes arrive here rather than through a contributor of their own: an
+ * ink stroke IS an annotation, written into `config.annotations` with an id of
+ * its own (`InkLayer.js`). Attribution is the `owner` an author set on the
+ * record, so a feature that creates annotations says so rather than this file
+ * pattern-matching ids.
+ *
+ * @param {any} w @returns {DrawnItem[]}
+ */
+function annotationItems(w) {
+  const config = w.config.annotations || {}
+  /** @type {DrawnItem[]} */
+  const out = []
+
+  for (const type of ANNOTATION_TYPES) {
+    const list = Array.isArray(config[type]) ? config[type] : []
+    list.forEach((/** @type {any} */ anno, /** @type {number} */ i) => {
+      if (!anno) return
+      out.push({
+        // An annotation carries an id only when someone gave it one, so the
+        // synthesised form is what most config-declared annotations get. It is
+        // stable for as long as the list is, which is what a reader needs.
+        id: anno.id ? String(anno.id) : `annotation:${type}:${i}`,
+        kind: /** @type {const} */ ('annotation'),
+        label: labelOfAnnotation(anno, type, i),
+        owner: anno.owner ? String(anno.owner) : 'core',
+        // An annotation is drawn whenever it is in the config: there is no
+        // hidden state for one, unlike a series.
+        visible: true,
+      })
+    })
+  }
+  return out
+}
+
+/**
+ * The most useful name an annotation has: its label text, then its own id,
+ * then what kind it is. A reader is choosing between rows, so a row that says
+ * "Launch" beats one that says "xaxis annotation 2".
+ *
+ * @param {any} anno @param {string} type @param {number} i
+ */
+function labelOfAnnotation(anno, type, i) {
+  const text = anno.label && anno.label.text
+  if (text) return String(text)
+  if (anno.text) return String(anno.text)
+  if (anno.id) return String(anno.id)
+  return `${type} annotation ${i + 1}`
+}
+
+/**
+ * Everything on the chart, in reading order: series, then annotations, then
+ * what plugins have declared.
+ *
+ * Rebuilt per call rather than cached. It is a projection of live state, and a
+ * remembered inventory is a list of what WAS drawn.
+ *
+ * @param {any} w @param {any} host @returns {DrawnItem[]}
+ */
+export function collectDrawn(w, host) {
+  const declared = []
+  if (host && host._declared) {
+    for (const [plugin, items] of host._declared) {
+      for (const item of items) {
+        declared.push({
+          id: `overlay:${plugin}:${item.id}`,
+          kind: /** @type {const} */ ('overlay'),
+          label: item.label,
+          owner: plugin,
+          visible: item.visible !== false,
+        })
+      }
+    }
+  }
+  return [...seriesItems(w, host), ...annotationItems(w), ...declared]
+}