apexcharts 8.0.1 → 8.2.0

package/types/apexcharts.d.ts

@@ -574,7 +574,7 @@ declare class ApexCharts {
    * Static, pure Perspectives helpers. Available once the feature is imported:
    * `import 'apexcharts/features/perspectives'`.
    */
-  static perspectives: {
+  static readonly perspectives: {
     decode(str: string): ApexPerspective | null
     fromURL(href?: string): ApexPerspective | null
   }
@@ -582,6 +582,8 @@ declare class ApexCharts {
   /**
    * SSR: render a chart to an SVG string on the server. Available from the
    * `apexcharts/ssr` entry (`import ApexCharts from 'apexcharts/ssr'`).
+   * The legend is HTML beside the SVG, so this standalone SVG has none and
+   * its plot fills the chart; use `renderToHTML` for a chart with its legend.
    */
   static renderToString(
     options: ApexCharts.ApexOptions,
@@ -590,7 +592,8 @@ declare class ApexCharts {
 
   /**
    * SSR: render a chart to hydration-ready HTML (SVG wrapped in the chart
-   * container). Available from the `apexcharts/ssr` entry.
+   * container), with the legend and its stylesheet beside the SVG. Available
+   * from the `apexcharts/ssr` entry.
    */
   static renderToHTML(
     options: ApexCharts.ApexOptions,
@@ -959,7 +962,9 @@ interface ApexPluginAPI {
    * The chart has already resolved this for its own tooltip, so this forwards
    * the host's answer rather than leaving a plugin to hit-test the SVG and
    * disagree with it. Nothing here can intercept or cancel: the tooltip,
-   * selection state and the caller's own events are unaffected.
+   * selection state and the caller's own events are unaffected. A handler that
+   * throws counts toward the plugin's three failures like a hook does, and a
+   * disabled or removed plugin stops being called.
    *
    * `category` is the resolved display label rather than an index, because a
    * plugin coordinating two charts keys on the label; an index means something
@@ -1010,7 +1015,8 @@ interface ApexPluginAPI {
    *
    * Returns null for an option that is not claimable, so a plugin written
    * against a newer host degrades instead of throwing. Every claim is released
-   * on teardown, on destroy, and if the host disables the plugin.
+   * on teardown, on destroy, when the plugin is removed from `plugins`, and if
+   * the host disables the plugin.
    *
    * @since Weave v6
    */
@@ -1018,6 +1024,29 @@ interface ApexPluginAPI {
     option: 'stroke.dashArray' | 'dataLabels.enabledOnSeries' | (string & {}),
     entries: Array<{ series: string | number; value: any }>
   ): ApexPluginClaim | null
+  /**
+   * Draw a PART of each value, inside the slot that value already occupies.
+   *
+   * The whole is drawn faded and the part solid in front of it, from the same
+   * baseline. The alternative for a plugin with a second number per datum is
+   * `markDerived()`, which adds a series, and a series costs the caller a
+   * legend entry, a tooltip row, an export column, a rescaled value axis and,
+   * on a bar chart, half the width of every bar they had.
+   *
+   * Null means the parts were not taken, and a plugin that gets null needs
+   * something else to do. The host says null when the highlight-filter feature
+   * is not loaded on the page, when the chart is not an axis chart, when the
+   * type draws no parts, and when the caller is already showing parts of their
+   * own. Check it per call: three of the four can change on the caller's next
+   * update.
+   *
+   * Registering, updating and releasing each re-render the chart, coalesced to
+   * one render per turn. Released on teardown, on destroy, and if the host
+   * disables the plugin.
+   *
+   * @since Weave v7
+   */
+  highlight(entries: ApexPluginHighlightEntry[]): ApexPluginHighlight | null
   /**
    * Everything drawn on this chart, including other features' output: the
    * series, the caller's annotations (ink strokes among them), and whatever
@@ -1131,6 +1160,22 @@ interface ApexPluginClaim {
   update(entries: Array<{ series: string | number; value: any }>): void
 }
 
+/** One series' parts, parallel to its data. @since Weave v7 */
+interface ApexPluginHighlightEntry {
+  /** A series NAME (resolved on every parse) or a position. */
+  series: string | number
+  /** Parallel to that series' data; null where a datum has no part. */
+  values: Array<number | null>
+}
+
+/** Live highlight parts a plugin registered. @since Weave v7 */
+interface ApexPluginHighlight {
+  /** Stop drawing these parts and re-render. Idempotent. */
+  release(): void
+  /** Replace the parts, keeping this plugin's place in the resolution order. */
+  update(entries: ApexPluginHighlightEntry[]): void
+}
+
 interface ApexPlugin {
   name: string
   apiVersion?: number
@@ -4745,9 +4790,10 @@ type ApexTooltipY = {
   }
   /**
    * `val` is `null` wherever the series has a gap, so guard before reaching
-   * for a number method: `(val) => val?.toFixed(2) ?? 'n/a'`.
+   * for a number method: `(val) => val?.toFixed(2) ?? 'n/a'`. In a shared
+   * tooltip, returning `null` or `undefined` hides that series' row.
    */
-  formatter?(val: number | null, opts?: ApexFormatterOpts): string
+  formatter?(val: number | null, opts?: ApexFormatterOpts): string | null | undefined
 }
 
 /**
@@ -4758,7 +4804,11 @@ type ApexTooltip = {
   enabled?: boolean
   enabledOnSeries?: undefined | number[]
   shared?: boolean
-  /** Ignored while `interactive` is enabled. */
+  /**
+   * Ignored while `interactive` is enabled. On horizontal bar and timeline
+   * charts the tooltip arrow pins the box to the hovered bar, so set
+   * `arrow: false` there to have the box follow the pointer.
+   */
   followCursor?: boolean
   intersect?: boolean
   inverseOrder?: boolean