@classic-homes/charts-core 0.1.37 → 0.2.0

package/dist/index.cjs

@@ -475,10 +475,216 @@ function getReplaceMerge(prev, next, isComponentType) {
   }
   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;
@@ -488,6 +694,7 @@ exports.formatCurrency = formatCurrency;
 exports.formatDate = formatDate;
 exports.formatNumber = formatNumber;
 exports.formatPercent = formatPercent;
+exports.formatTooltipValue = formatTooltipValue;
 exports.generateBarChartDescription = generateBarChartDescription;
 exports.generateDarkTheme = generateDarkTheme;
 exports.generateDataTable = generateDataTable;
@@ -496,6 +703,16 @@ 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 { ChartSemanticColors, EChartsTheme, THEME_DARK, THEME_LIGHT, colorWithAlpha, darkChartColors, darkTheme, generateDarkTheme, generateLightTheme, getChartColors, lightChartColors, 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';
+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
@@ -90,5 +91,144 @@ declare function generateDataTable(headers: string[], rows: (string | number)[][
  * 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 { BarChartData, LineChartData, PieSliceData, ScatterChartData, abbreviateNumber, createTooltipFormatter, escapeHtml, formatCurrency, formatDate, formatNumber, formatPercent, generateBarChartDescription, generateDataTable, generateLineChartDescription, generatePieChartDescription, generateScatterChartDescription, getReplaceMerge };
+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 };

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 export { ChartSemanticColors, EChartsTheme, THEME_DARK, THEME_LIGHT, colorWithAlpha, darkChartColors, darkTheme, generateDarkTheme, generateLightTheme, getChartColors, lightChartColors, lightTheme } from './theme/index.js';
-import { BarChartData, LineChartData, PieSliceData, ScatterChartData } from './types/index.js';
-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.js';
+import { BarChartData, LineChartData, PieSliceData, ScatterChartData, ChartFormatter, LabelFormatterParams, TooltipFormatterParams, AxisConfig, ChartLegendConfig, LegendItem } from './types/index.js';
+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.js';
+import 'echarts';
 
 /**
  * Formatting utilities for chart values
@@ -90,5 +91,144 @@ declare function generateDataTable(headers: string[], rows: (string | number)[][
  * 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 { BarChartData, LineChartData, PieSliceData, ScatterChartData, abbreviateNumber, createTooltipFormatter, escapeHtml, formatCurrency, formatDate, formatNumber, formatPercent, generateBarChartDescription, generateDataTable, generateLineChartDescription, generatePieChartDescription, generateScatterChartDescription, getReplaceMerge };
+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 };