@classic-homes/charts-core 0.1.36 → 0.2.0

package/dist/{chunk-ZRG25JNX.js → chunk-JM72YHZD.js}

@@ -1,4 +1,4 @@
-import { colors, semanticColors, borderRadius, fontFamily } from '@classic-homes/theme-tokens';
+import { semanticColors, colors, borderRadius, fontFamily } from '@classic-homes/theme-tokens';
 
 // src/theme/generator.ts
 function generateLightTheme() {
@@ -270,8 +270,43 @@ function generateDarkTheme() {
 var lightTheme = generateLightTheme();
 var darkTheme = generateDarkTheme();
 
-// src/theme/index.ts
+// src/theme/constants.ts
 var THEME_LIGHT = "classic-light";
 var THEME_DARK = "classic-dark";
 
-export { THEME_DARK, THEME_LIGHT, darkTheme, generateDarkTheme, generateLightTheme, lightTheme };
+// src/theme/semantic.ts
+var lightChartColors = {
+  series: lightTheme.color,
+  foreground: semanticColors.light.foreground,
+  mutedForeground: semanticColors.light.mutedForeground,
+  axisPointerLabel: semanticColors.light.mutedForeground,
+  divider: colors.gray[600],
+  success: semanticColors.light.success,
+  destructive: semanticColors.light.destructive
+};
+var darkChartColors = {
+  series: darkTheme.color,
+  foreground: semanticColors.dark.foreground,
+  mutedForeground: semanticColors.dark.mutedForeground,
+  // mutedForeground (gray[400]) is too light under the white label text
+  axisPointerLabel: colors.gray[600],
+  divider: colors.gray[700],
+  success: semanticColors.dark.success,
+  destructive: semanticColors.dark.destructive
+};
+function getChartColors(themeName) {
+  return themeName === THEME_DARK ? darkChartColors : lightChartColors;
+}
+function colorWithAlpha(color, alpha) {
+  let hex = /^#([\da-f]{3}|[\da-f]{6})$/i.exec(color)?.[1];
+  if (!hex) return color;
+  if (hex.length === 3) {
+    hex = hex.split("").map((c) => c + c).join("");
+  }
+  const r = parseInt(hex.slice(0, 2), 16);
+  const g = parseInt(hex.slice(2, 4), 16);
+  const b = parseInt(hex.slice(4, 6), 16);
+  return `rgba(${r}, ${g}, ${b}, ${alpha})`;
+}
+
+export { THEME_DARK, THEME_LIGHT, colorWithAlpha, darkChartColors, darkTheme, generateDarkTheme, generateLightTheme, getChartColors, lightChartColors, lightTheme };

package/dist/index.cjs

@@ -272,10 +272,45 @@ function generateDarkTheme() {
 var lightTheme = generateLightTheme();
 var darkTheme = generateDarkTheme();
 
-// src/theme/index.ts
+// src/theme/constants.ts
 var THEME_LIGHT = "classic-light";
 var THEME_DARK = "classic-dark";
 
+// src/theme/semantic.ts
+var lightChartColors = {
+  series: lightTheme.color,
+  foreground: themeTokens.semanticColors.light.foreground,
+  mutedForeground: themeTokens.semanticColors.light.mutedForeground,
+  axisPointerLabel: themeTokens.semanticColors.light.mutedForeground,
+  divider: themeTokens.colors.gray[600],
+  success: themeTokens.semanticColors.light.success,
+  destructive: themeTokens.semanticColors.light.destructive
+};
+var darkChartColors = {
+  series: darkTheme.color,
+  foreground: themeTokens.semanticColors.dark.foreground,
+  mutedForeground: themeTokens.semanticColors.dark.mutedForeground,
+  // mutedForeground (gray[400]) is too light under the white label text
+  axisPointerLabel: themeTokens.colors.gray[600],
+  divider: themeTokens.colors.gray[700],
+  success: themeTokens.semanticColors.dark.success,
+  destructive: themeTokens.semanticColors.dark.destructive
+};
+function getChartColors(themeName) {
+  return themeName === THEME_DARK ? darkChartColors : lightChartColors;
+}
+function colorWithAlpha(color, alpha) {
+  let hex = /^#([\da-f]{3}|[\da-f]{6})$/i.exec(color)?.[1];
+  if (!hex) return color;
+  if (hex.length === 3) {
+    hex = hex.split("").map((c) => c + c).join("");
+  }
+  const r = parseInt(hex.slice(0, 2), 16);
+  const g = parseInt(hex.slice(2, 4), 16);
+  const b = parseInt(hex.slice(4, 6), 16);
+  return `rgba(${r}, ${g}, ${b}, ${alpha})`;
+}
+
 // src/utils/format.ts
 function formatNumber(value, options) {
   return new Intl.NumberFormat("en-US", options).format(value);
@@ -305,7 +340,18 @@ function abbreviateNumber(value, decimals = 1) {
     abbreviated /= 1e3;
     suffixIndex++;
   }
-  return abbreviated.toFixed(decimals).replace(/\.0+$/, "") + suffixes[suffixIndex];
+  if (Math.abs(Number(abbreviated.toFixed(decimals))) >= 1e3 && suffixIndex < suffixes.length - 1) {
+    abbreviated /= 1e3;
+    suffixIndex++;
+  }
+  let fixed = abbreviated.toFixed(decimals);
+  if (fixed.includes(".")) {
+    fixed = fixed.replace(/\.?0+$/, "");
+  }
+  return fixed + suffixes[suffixIndex];
+}
+function escapeHtml(value) {
+  return String(value).replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
 }
 function createTooltipFormatter(options = {}) {
   const { showSeriesName = true, valueFormatter = formatNumber } = options;
@@ -320,9 +366,9 @@ function createTooltipFormatter(options = {}) {
       const formatted = valueFormatter(value);
       const percent = param.percent ? ` (${param.percent.toFixed(1)}%)` : "";
       if (showSeriesName && param.seriesName) {
-        return `${param.seriesName}: ${formatted}${percent}`;
+        return `${escapeHtml(param.seriesName)}: ${escapeHtml(formatted)}${percent}`;
       }
-      return `${param.name}: ${formatted}${percent}`;
+      return `${escapeHtml(param.name)}: ${escapeHtml(formatted)}${percent}`;
     }).join("<br/>");
   };
 }
@@ -376,6 +422,9 @@ function generatePieChartDescription(title, data, isDonut = false) {
   const total = data.reduce((sum, slice) => sum + slice.value, 0);
   const chartType = isDonut ? "Donut" : "Pie";
   let description = `${title}. ${chartType} chart with ${data.length} segments`;
+  if (total === 0) {
+    return `${description}. All segments have a value of 0`;
+  }
   const sorted = [...data].sort((a, b) => b.value - a.value);
   const topSegments = sorted.slice(0, 3);
   const percentages = topSegments.map((segment) => {
@@ -396,8 +445,8 @@ function generateScatterChartDescription(title, data) {
   return description;
 }
 function generateDataTable(headers, rows) {
-  const headerRow = headers.map((h) => `<th scope="col">${h}</th>`).join("");
-  const bodyRows = rows.map((row) => `<tr>${row.map((cell) => `<td>${cell}</td>`).join("")}</tr>`).join("");
+  const headerRow = headers.map((h) => `<th scope="col">${escapeHtml(h)}</th>`).join("");
+  const bodyRows = rows.map((row) => `<tr>${row.map((cell) => `<td>${escapeHtml(cell)}</td>`).join("")}</tr>`).join("");
   return `
     <table class="sr-only">
       <thead><tr>${headerRow}</tr></thead>
@@ -406,15 +455,246 @@ function generateDataTable(headers, rows) {
   `;
 }
 
+// src/utils/merge.ts
+var ALWAYS_REPLACE = ["series", "graphic"];
+function countComponents(value) {
+  if (value == null || value === false) return 0;
+  if (Array.isArray(value)) return value.filter((item) => item != null).length;
+  return 1;
+}
+function getReplaceMerge(prev, next, isComponentType) {
+  const types = new Set(ALWAYS_REPLACE);
+  if (prev) {
+    const before = prev;
+    const after = next;
+    for (const key of Object.keys(before)) {
+      if (countComponents(before[key]) > countComponents(after[key])) {
+        types.add(key);
+      }
+    }
+  }
+  return [...types].filter((type) => isComponentType(type));
+}
+function isPlainObject(value) {
+  if (value === null || typeof value !== "object") return false;
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+}
+function mergeValue(base, override, topLevel = false) {
+  if (override === void 0) return base;
+  if (topLevel && (Array.isArray(base) || Array.isArray(override))) {
+    const from = Array.isArray(base) ? base : base === void 0 ? [] : [base];
+    const to = Array.isArray(override) ? override : [override];
+    const length = Math.max(from.length, to.length);
+    return Array.from({ length }, (_, index) => mergeValue(from[index], to[index]));
+  }
+  if (isPlainObject(base) && isPlainObject(override)) {
+    const merged = { ...base };
+    for (const key of Object.keys(override)) {
+      merged[key] = mergeValue(base[key], override[key]);
+    }
+    return merged;
+  }
+  return override;
+}
+function mergeChartOption(generated, override) {
+  if (!override) return generated;
+  const base = generated;
+  const merged = { ...base };
+  for (const [key, value] of Object.entries(override)) {
+    merged[key] = mergeValue(base[key], value, true);
+  }
+  return merged;
+}
+
+// src/utils/options.ts
+function toParams(raw, getLabel) {
+  const seriesIndex = raw.seriesIndex ?? 0;
+  const dataIndex = raw.dataIndex ?? 0;
+  const name = raw.name ?? "";
+  const value = raw.value;
+  return {
+    name,
+    value: Array.isArray(value) ? value : value,
+    seriesName: raw.seriesName ?? "",
+    seriesIndex,
+    dataIndex,
+    percent: raw.percent,
+    color: typeof raw.color === "string" ? raw.color : void 0,
+    label: getLabel?.(seriesIndex, dataIndex, name)
+  };
+}
+function toTooltipParams(raw, getLabel) {
+  return {
+    ...toParams(raw, getLabel),
+    marker: typeof raw.marker === "string" ? raw.marker : "",
+    axisValue: raw.axisValue
+  };
+}
+var EDGE_ALIGN = { start: "left", center: "center", end: "right" };
+var SIDE_ALIGN = { start: "top", center: "middle", end: "bottom" };
+function buildLegend(names, config, { show, custom = false, defaults = {} }) {
+  if (custom) return { show: false, data: names };
+  if (!show) return void 0;
+  const { position = "bottom", align = "center", orient, icon, formatter, scroll } = config ?? {};
+  const legend = { ...defaults, data: names };
+  if (position === "top" || position === "bottom") {
+    legend[position] = 0;
+    if (align !== "center") legend.left = EDGE_ALIGN[align];
+  } else {
+    legend[position] = 0;
+    legend.top = SIDE_ALIGN[align];
+    legend.orient = "vertical";
+  }
+  if (orient) legend.orient = orient;
+  if (icon) legend.icon = icon;
+  if (formatter) legend.formatter = formatter;
+  if (scroll) legend.type = "scroll";
+  return legend;
+}
+function gridInset(legend, showLegend, xAxis, yAxis) {
+  const inset = {};
+  if (showLegend) {
+    const position = legend?.position ?? "bottom";
+    inset[position] = position === "left" || position === "right" ? 140 : 36;
+  }
+  if (xAxis?.name !== void 0 && (xAxis.nameLocation ?? "middle") === "middle") {
+    inset.bottom = (inset.bottom ?? 12) + 24;
+  }
+  if (yAxis?.name !== void 0 && (yAxis.nameLocation ?? "middle") === "middle") {
+    inset.left = (inset.left ?? 12) + 24;
+  }
+  return Object.keys(inset).length ? inset : void 0;
+}
+function legendCenter(config, show, fallback) {
+  if (!show) return fallback;
+  switch (config?.position) {
+    case "left":
+      return ["60%", "50%"];
+    case "right":
+      return ["40%", "50%"];
+    case "top":
+      return ["50%", "55%"];
+    default:
+      return fallback;
+  }
+}
+function anchorCenterGraphic(group, center, defaultCenter) {
+  if (center[0] === defaultCenter[0] && center[1] === defaultCenter[1]) return group;
+  const shiftY = parseFloat(center[1]) - parseFloat(defaultCenter[1]);
+  const top = typeof group.top === "string" ? `${parseFloat(group.top) + shiftY}%` : group.top;
+  return {
+    ...group,
+    left: center[0],
+    top,
+    bounding: "raw",
+    children: (group.children ?? []).map(
+      ({ left: _left, top: childTop, ...child }) => ({ ...child, x: 0, y: childTop ?? 0 })
+    )
+  };
+}
+function getLegendItems(names, palette, overrides, visible) {
+  return names.map((name, index) => ({
+    name,
+    color: overrides[index] || palette[index % palette.length] || "",
+    visible: visible[name] !== false
+  }));
+}
+function buildAxis(base, config) {
+  if (!config) return base;
+  const axis = { ...base };
+  const { show, name, nameLocation, nameGap, formatter, rotate, min, max, interval } = config;
+  if (show !== void 0) axis.show = show;
+  if (name !== void 0) {
+    axis.name = name;
+    axis.nameLocation = nameLocation ?? "middle";
+    axis.nameGap = nameGap ?? (axis.nameLocation === "middle" ? 32 : 15);
+  }
+  if (formatter !== void 0 || rotate !== void 0) {
+    const axisLabel = { ...base.axisLabel };
+    if (formatter !== void 0) axisLabel.formatter = formatter;
+    if (rotate !== void 0) axisLabel.rotate = rotate;
+    axis.axisLabel = axisLabel;
+  }
+  if (min !== void 0) axis.min = min;
+  if (max !== void 0) axis.max = max;
+  if (interval !== void 0) axis.interval = interval;
+  return axis;
+}
+function buildDataLabel(base, hidden, { show, formatter, getLabel }) {
+  if (formatter === void 0) return show ? base : hidden;
+  const wrapped = typeof formatter === "string" ? formatter : (raw) => formatter(toParams(raw, getLabel));
+  if (!show) return { ...hidden, show: false, formatter: wrapped };
+  return { ...base, show: true, formatter: wrapped };
+}
+function pointLabel(text, formatter, base = {}) {
+  if (text == null || text === "") return void 0;
+  return typeof formatter === "function" ? { ...base, show: true } : { ...base, show: true, formatter: text };
+}
+function withPointLabels(values, labels, formatter, base) {
+  if (!labels?.some((text) => text != null && text !== "")) return values;
+  return values.map((value, index) => {
+    const label = pointLabel(labels[index], formatter, base);
+    return label ? { value, label } : value;
+  });
+}
+function seriesLabelLookup(series) {
+  return (seriesIndex, dataIndex) => series[seriesIndex]?.labels?.[dataIndex] ?? void 0;
+}
+function itemLabelLookup(items) {
+  return (_seriesIndex, dataIndex) => items[dataIndex]?.label;
+}
+function nameLabelLookup(nodes) {
+  const labels = /* @__PURE__ */ new Map();
+  const visit = (list) => {
+    for (const node of list) {
+      if (node.label != null && !labels.has(node.name)) labels.set(node.name, node.label);
+      if (node.children) visit(node.children);
+    }
+  };
+  visit(nodes);
+  return (_seriesIndex, _dataIndex, name) => labels.get(name);
+}
+function hasPointLabels(series) {
+  return series.some((s) => s.labels?.some((text) => text != null && text !== ""));
+}
+function buildTooltip(base, { show, formatter, valueFormatter, getLabel }) {
+  if (!show) return void 0;
+  if (formatter === void 0 && valueFormatter === void 0) return base;
+  const tooltip = { ...base };
+  if (valueFormatter) {
+    tooltip.valueFormatter = (value) => typeof value === "number" ? valueFormatter(value) : String(value ?? "");
+  }
+  if (typeof formatter === "string") {
+    tooltip.formatter = formatter;
+  } else if (formatter) {
+    tooltip.formatter = (raw) => formatter((Array.isArray(raw) ? raw : [raw]).map((p) => toTooltipParams(p, getLabel)));
+  }
+  return tooltip;
+}
+function formatTooltipValue(value, valueFormatter) {
+  if (valueFormatter && typeof value === "number") return valueFormatter(value);
+  return String(value ?? "");
+}
+
 exports.THEME_DARK = THEME_DARK;
 exports.THEME_LIGHT = THEME_LIGHT;
 exports.abbreviateNumber = abbreviateNumber;
+exports.anchorCenterGraphic = anchorCenterGraphic;
+exports.buildAxis = buildAxis;
+exports.buildDataLabel = buildDataLabel;
+exports.buildLegend = buildLegend;
+exports.buildTooltip = buildTooltip;
+exports.colorWithAlpha = colorWithAlpha;
 exports.createTooltipFormatter = createTooltipFormatter;
+exports.darkChartColors = darkChartColors;
 exports.darkTheme = darkTheme;
+exports.escapeHtml = escapeHtml;
 exports.formatCurrency = formatCurrency;
 exports.formatDate = formatDate;
 exports.formatNumber = formatNumber;
 exports.formatPercent = formatPercent;
+exports.formatTooltipValue = formatTooltipValue;
 exports.generateBarChartDescription = generateBarChartDescription;
 exports.generateDarkTheme = generateDarkTheme;
 exports.generateDataTable = generateDataTable;
@@ -422,4 +702,17 @@ exports.generateLightTheme = generateLightTheme;
 exports.generateLineChartDescription = generateLineChartDescription;
 exports.generatePieChartDescription = generatePieChartDescription;
 exports.generateScatterChartDescription = generateScatterChartDescription;
+exports.getChartColors = getChartColors;
+exports.getLegendItems = getLegendItems;
+exports.getReplaceMerge = getReplaceMerge;
+exports.gridInset = gridInset;
+exports.hasPointLabels = hasPointLabels;
+exports.itemLabelLookup = itemLabelLookup;
+exports.legendCenter = legendCenter;
+exports.lightChartColors = lightChartColors;
 exports.lightTheme = lightTheme;
+exports.mergeChartOption = mergeChartOption;
+exports.nameLabelLookup = nameLabelLookup;
+exports.pointLabel = pointLabel;
+exports.seriesLabelLookup = seriesLabelLookup;
+exports.withPointLabels = withPointLabels;

package/dist/index.d.cts

@@ -1,6 +1,7 @@
-export { EChartsTheme, THEME_DARK, THEME_LIGHT, darkTheme, generateDarkTheme, generateLightTheme, lightTheme } from './theme/index.cjs';
-import { BarChartData, LineChartData, PieSliceData, ScatterChartData } from './types/index.cjs';
-export { AreaChartData, AreaChartProps, AreaSeriesData, BarChartProps, BarSeriesData, BaseChartProps, BaseEventParams, CandlestickChartProps, CandlestickData, CandlestickEventParams, CandlestickItem, DataPointEventParams, DonutChartProps, FunnelChartProps, FunnelSliceData, GaugeChartProps, HeatmapChartProps, HeatmapData, HeatmapEventParams, LineChartProps, LineSeriesData, PieChartProps, RadarChartData, RadarChartProps, RadarIndicator, RadarSeriesData, SankeyChartProps, SankeyData, SankeyEventParams, SankeyLink, SankeyNode, ScatterChartProps, ScatterSeriesData, SliceEventParams, TreemapChartProps, TreemapEventParams, TreemapLevel, TreemapNode } from './types/index.cjs';
+export { ChartSemanticColors, EChartsTheme, THEME_DARK, THEME_LIGHT, colorWithAlpha, darkChartColors, darkTheme, generateDarkTheme, generateLightTheme, getChartColors, lightChartColors, lightTheme } from './theme/index.cjs';
+import { BarChartData, LineChartData, PieSliceData, ScatterChartData, ChartFormatter, LabelFormatterParams, TooltipFormatterParams, AxisConfig, ChartLegendConfig, LegendItem } from './types/index.cjs';
+export { AreaChartData, AreaChartProps, AreaSeriesData, AxisChartProps, BarChartProps, BarSeriesData, BaseChartProps, BaseEventParams, CandlestickChartProps, CandlestickData, CandlestickEventParams, CandlestickItem, ChartLegendPosition, DataPointEventParams, DonutChartProps, FunnelChartProps, FunnelSliceData, GaugeChartProps, HeatmapChartProps, HeatmapData, HeatmapEventParams, LabelChartProps, LegendChartProps, LegendRenderProps, LineChartProps, LineSeriesData, PieChartProps, RadarChartData, RadarChartProps, RadarIndicator, RadarSeriesData, SankeyChartProps, SankeyData, SankeyEventParams, SankeyLink, SankeyNode, ScatterChartProps, ScatterSeriesData, SliceEventParams, TreemapChartProps, TreemapEventParams, TreemapLevel, TreemapNode } from './types/index.cjs';
+import 'echarts';
 
 /**
  * Formatting utilities for chart values
@@ -25,6 +26,11 @@ declare function formatDate(date: Date | string, options?: Intl.DateTimeFormatOp
  * Abbreviate large numbers (e.g., 1000 -> 1K, 1000000 -> 1M)
  */
 declare function abbreviateNumber(value: number, decimals?: number): string;
+/**
+ * Escape a value for interpolation into HTML. ECharts renders the string a
+ * function tooltip formatter returns as innerHTML without encoding it.
+ */
+declare function escapeHtml(value: unknown): string;
 /**
  * Create a tooltip formatter for ECharts
  */
@@ -64,4 +70,165 @@ declare function generateScatterChartDescription(title: string, data: ScatterCha
  */
 declare function generateDataTable(headers: string[], rows: (string | number)[][]): string;
 
-export { BarChartData, LineChartData, PieSliceData, ScatterChartData, abbreviateNumber, createTooltipFormatter, formatCurrency, formatDate, formatNumber, formatPercent, generateBarChartDescription, generateDataTable, generateLineChartDescription, generatePieChartDescription, generateScatterChartDescription };
+/**
+ * Helpers for applying a complete ECharts option on top of a previous one.
+ */
+/**
+ * Work out the `replaceMerge` list for `chart.setOption(next, { replaceMerge })`
+ * when `next` is a complete option that supersedes `prev`.
+ *
+ * `notMerge: true` would also drop removed series and components, but it
+ * rebuilds every component, so legend selection, dataZoom ranges and other
+ * interaction state reset on each data update. Instead this replaces only:
+ *
+ * - `series` and `graphic`, so removed series, mark lines and centre labels
+ *   disappear;
+ * - any component type that `next` has fewer of than `prev` (a hidden legend
+ *   or tooltip, a dropped volume grid and its axes).
+ *
+ * Everything else is merged, so its state survives. ECharts rejects types it
+ * has no component class for, so only types for which `isComponentType`
+ * returns true are listed; pass `echarts.ComponentModel.hasClass`.
+ */
+declare function getReplaceMerge(prev: object | null | undefined, next: object, isComponentType: (mainType: string) => boolean): string[];
+/**
+ * Deep-merge a user-supplied ECharts option over a chart's generated option.
+ *
+ * Plain objects merge key by key. Top-level component arrays (`series`,
+ * `xAxis`, `grid`, ...) merge index by index, matching how ECharts merges
+ * options, so `{ series: [{ label: { show: true } }] }` patches only the
+ * first series. Nested arrays (`data`, `center`, ...) and any other value
+ * (functions, class instances such as gradients, primitives) replace the
+ * generated one; `undefined` leaves it untouched.
+ */
+declare function mergeChartOption<T extends object>(generated: T, override: object | undefined): T;
+
+/**
+ * Builders for the label, axis, tooltip and legend parts of a chart option.
+ *
+ * Chart components pass the block they generate by default; with no
+ * customisation each builder returns that block unchanged.
+ */
+
+type AnyObject = Record<string, unknown>;
+/** Looks up the per-point label text for a data point */
+type PointLabelLookup = (seriesIndex: number, dataIndex: number, name: string) => string | undefined;
+interface BuildLegendOptions {
+    /** Whether the built-in legend is shown (the `showLegend` prop) */
+    show: boolean;
+    /**
+     * A custom legend replaces the built-in one: it is kept with `show: false`
+     * so legend selection actions keep working.
+     */
+    custom?: boolean;
+    /** Extra keys for the default bottom legend, e.g. `{ orient: 'horizontal' }` */
+    defaults?: AnyObject;
+}
+/**
+ * Build the ECharts `legend` component for a list of item names
+ */
+declare function buildLegend(names: string[], config: ChartLegendConfig | undefined, { show, custom, defaults }: BuildLegendOptions): AnyObject | undefined;
+/**
+ * Grid edges to move so a built-in legend and centred axis titles do not
+ * overlap the plot or its tick labels (`containLabel` only reserves room for
+ * tick labels). Returns a partial `grid` to spread over the default one, or
+ * nothing when no room is needed.
+ */
+declare function gridInset(legend: ChartLegendConfig | undefined, showLegend: boolean, xAxis?: AxisConfig, yAxis?: AxisConfig): AnyObject | undefined;
+/**
+ * Centre for a pie, donut or radar that leaves room for a built-in legend
+ */
+declare function legendCenter(config: ChartLegendConfig | undefined, show: boolean, fallback: [string, string]): [string, string];
+/**
+ * Re-anchor a centre graphic group (a donut's centre label) on a pie centre
+ * moved by `legendCenter`. `defaultCenter` is where the group's `left: 'center'`
+ * / `top` placement assumes the pie sits; the group is returned unchanged
+ * when the centre has not moved. A raw bounding positions the group by its
+ * origin, so children centred on x = 0 sit on the new centre.
+ */
+declare function anchorCenterGraphic(group: AnyObject, center: [string, string], defaultCenter: [string, string]): AnyObject;
+/**
+ * Legend entries with the colour the chart draws each in: an explicit
+ * override, else the theme palette by index
+ */
+declare function getLegendItems(names: string[], palette: string[], overrides: (string | undefined)[], visible: Record<string, boolean>): LegendItem[];
+/**
+ * Apply an axis customisation to a generated axis
+ */
+declare function buildAxis<T extends AnyObject>(base: T, config: AxisConfig | undefined): T;
+interface BuildDataLabelOptions {
+    /** Whether data labels are shown */
+    show: boolean;
+    /** The `labelFormatter` prop */
+    formatter?: ChartFormatter<LabelFormatterParams>;
+    /** Per-point label lookup, exposed to formatter functions as `label` */
+    getLabel?: PointLabelLookup;
+}
+/**
+ * Build a series `label` block. `base` is the block the chart shows by
+ * default; `hidden` is what it uses when labels are off.
+ */
+declare function buildDataLabel(base: AnyObject, hidden: AnyObject | undefined, { show, formatter, getLabel }: BuildDataLabelOptions): AnyObject | undefined;
+/**
+ * A per-data-item label override, for points with their own label text.
+ * When a formatter function is set it receives the text instead, so the
+ * item only switches its label on. `base` carries placement (e.g.
+ * `{ position: 'top' }`) for when the series' own labels are off.
+ */
+declare function pointLabel(text: string | null | undefined, formatter: ChartFormatter<LabelFormatterParams> | undefined, base?: AnyObject): AnyObject | undefined;
+/**
+ * Turn a plain value array into data items, attaching a label override to
+ * each point that has label text. Returns the values unchanged when none do.
+ */
+declare function withPointLabels<V>(values: V[], labels: (string | null | undefined)[] | undefined, formatter: ChartFormatter<LabelFormatterParams> | undefined, base?: AnyObject): (V | {
+    value: V;
+    label: AnyObject;
+})[];
+/**
+ * Lookup for series-based per-point labels
+ */
+declare function seriesLabelLookup(series: {
+    labels?: (string | null | undefined)[];
+}[]): PointLabelLookup;
+/**
+ * Lookup for item-based per-point labels (pie slices, funnel stages)
+ */
+declare function itemLabelLookup(items: {
+    label?: string;
+}[]): PointLabelLookup;
+/**
+ * Lookup for per-point labels keyed by name, for nodes whose data index does
+ * not follow the input order (treemap, sankey). Walks `children` recursively.
+ */
+declare function nameLabelLookup(nodes: {
+    name: string;
+    label?: string;
+    children?: unknown[];
+}[]): PointLabelLookup;
+/**
+ * Whether any series has per-point label text
+ */
+declare function hasPointLabels(series: {
+    labels?: (string | null | undefined)[];
+}[]): boolean;
+interface BuildTooltipOptions {
+    /** Whether the tooltip is shown */
+    show: boolean;
+    /** The `tooltipFormatter` prop */
+    formatter?: ChartFormatter<TooltipFormatterParams[]>;
+    /** The `tooltipValueFormatter` prop */
+    valueFormatter?: (value: number) => string;
+    /** Per-point label lookup, exposed to formatter functions as `label` */
+    getLabel?: PointLabelLookup;
+}
+/**
+ * Build the `tooltip` component. `base` is the chart's default tooltip.
+ */
+declare function buildTooltip(base: AnyObject, { show, formatter, valueFormatter, getLabel }: BuildTooltipOptions): AnyObject | undefined;
+/**
+ * Format a value with `tooltipValueFormatter`, for charts whose default
+ * tooltip is custom HTML (where ECharts' `valueFormatter` does not apply)
+ */
+declare function formatTooltipValue(value: unknown, valueFormatter: ((value: number) => string) | undefined): string;
+
+export { AxisConfig, BarChartData, type BuildDataLabelOptions, type BuildLegendOptions, type BuildTooltipOptions, ChartFormatter, ChartLegendConfig, LabelFormatterParams, LegendItem, LineChartData, PieSliceData, type PointLabelLookup, ScatterChartData, TooltipFormatterParams, abbreviateNumber, anchorCenterGraphic, buildAxis, buildDataLabel, buildLegend, buildTooltip, createTooltipFormatter, escapeHtml, formatCurrency, formatDate, formatNumber, formatPercent, formatTooltipValue, generateBarChartDescription, generateDataTable, generateLineChartDescription, generatePieChartDescription, generateScatterChartDescription, getLegendItems, getReplaceMerge, gridInset, hasPointLabels, itemLabelLookup, legendCenter, mergeChartOption, nameLabelLookup, pointLabel, seriesLabelLookup, withPointLabels };