@classic-homes/charts-core 0.3.1 → 0.4.0

package/dist/index.cjs

@@ -624,6 +624,237 @@ function mergeChartOption(generated, override) {
   return merged;
 }
 
+// src/utils/stats.ts
+var isFiniteNumber = (value) => typeof value === "number" && Number.isFinite(value);
+var clean = (value) => Number(value.toPrecision(12));
+function niceStep(rough) {
+  if (!(rough > 0) || !Number.isFinite(rough)) return 1;
+  const power = 10 ** Math.floor(Math.log10(rough));
+  const fraction = rough / power;
+  const nice = fraction <= 1 ? 1 : fraction <= 2 ? 2 : fraction <= 2.5 ? 2.5 : fraction <= 5 ? 5 : 10;
+  return clean(nice * power);
+}
+function bucketLabel(start, end, format) {
+  const text = (value) => formatValue(value, format);
+  if (start === -Infinity && end === Infinity) return "All";
+  if (start === -Infinity) return `< ${text(end)}`;
+  if (end === Infinity) return `${text(start)}+`;
+  return `${text(start)}\u2013${text(end)}`;
+}
+function binValues(values, options = {}) {
+  const { bins, binWidth, format } = options;
+  const finite = values.filter(isFiniteNumber);
+  let edges;
+  if (Array.isArray(bins)) {
+    edges = bins.map((bin) => ({
+      start: bin.start ?? -Infinity,
+      end: bin.end ?? Infinity,
+      label: bin.label
+    }));
+  } else {
+    if (!finite.length) return [];
+    let min = Infinity;
+    let max = -Infinity;
+    for (const value of finite) {
+      if (value < min) min = value;
+      if (value > max) max = value;
+    }
+    if (min === max) {
+      edges = [{ start: min, end: max }];
+    } else {
+      let step;
+      let start;
+      if (binWidth && binWidth > 0) {
+        step = binWidth;
+        start = Math.floor(min / step) * step;
+      } else if (typeof bins === "number" && bins > 0) {
+        step = (max - min) / Math.floor(bins);
+        start = min;
+      } else {
+        const sturges = Math.ceil(Math.log2(finite.length) + 1);
+        step = niceStep((max - min) / sturges);
+        start = Math.floor(min / step) * step;
+      }
+      const count = Math.max(1, Math.ceil(clean((max - start) / step)));
+      edges = Array.from({ length: count }, (_, index) => ({
+        start: clean(start + index * step),
+        end: clean(start + (index + 1) * step)
+      }));
+    }
+  }
+  const buckets = edges.map(({ start, end, label }) => ({
+    label: label ?? bucketLabel(start, end, format),
+    start,
+    end,
+    count: 0
+  }));
+  const last = buckets.length - 1;
+  for (const value of finite) {
+    const index = buckets.findIndex(
+      (bucket, i) => value >= bucket.start && (value < bucket.end || i === last && value <= bucket.end)
+    );
+    if (index !== -1) buckets[index].count++;
+  }
+  return buckets;
+}
+function quantile(sorted, q) {
+  if (!sorted.length) return NaN;
+  const position = (sorted.length - 1) * q;
+  const lower = Math.floor(position);
+  const upper = Math.ceil(position);
+  if (lower === upper) return sorted[lower];
+  return sorted[lower] + (sorted[upper] - sorted[lower]) * (position - lower);
+}
+function boxplotStats(values) {
+  const sorted = values.filter(isFiniteNumber).sort((a, b) => a - b);
+  if (!sorted.length) return null;
+  const q1 = quantile(sorted, 0.25);
+  const median = quantile(sorted, 0.5);
+  const q3 = quantile(sorted, 0.75);
+  const iqr = q3 - q1;
+  const lowFence = q1 - 1.5 * iqr;
+  const highFence = q3 + 1.5 * iqr;
+  const inside = sorted.filter((value) => value >= lowFence && value <= highFence);
+  const outliers = sorted.filter((value) => value < lowFence || value > highFence);
+  return {
+    low: inside[0] ?? q1,
+    q1,
+    median,
+    q3,
+    high: inside[inside.length - 1] ?? q3,
+    outliers,
+    count: sorted.length,
+    mean: sorted.reduce((sum, value) => sum + value, 0) / sorted.length
+  };
+}
+function waterfallLayout(steps) {
+  let running = 0;
+  return steps.map((step) => {
+    let start;
+    let end;
+    let kind;
+    if (step.isTotal === "value") {
+      start = 0;
+      end = isFiniteNumber(step.value) ? step.value : running;
+      kind = "total";
+    } else if (step.isTotal) {
+      start = 0;
+      end = running;
+      kind = "total";
+    } else {
+      const change = isFiniteNumber(step.value) ? step.value : 0;
+      start = running;
+      end = running + change;
+      kind = change < 0 ? "decrease" : "increase";
+    }
+    running = end;
+    const low = Math.min(start, end);
+    const high = Math.max(start, end);
+    let base = 0;
+    let positive = 0;
+    let negative = 0;
+    if (low >= 0) {
+      base = low;
+      positive = high - low;
+    } else if (high <= 0) {
+      base = high;
+      negative = low - high;
+    } else {
+      positive = high;
+      negative = low;
+    }
+    return {
+      start,
+      end,
+      value: kind === "total" ? end : end - start,
+      kind,
+      base: clean(base),
+      positive: clean(positive),
+      negative: clean(negative)
+    };
+  });
+}
+function toPercentStack(series) {
+  const length = Math.max(0, ...series.map((s) => s.data.length));
+  const totals = Array.from(
+    { length },
+    (_, index) => series.reduce((sum, s) => {
+      const value = s.data[index];
+      return sum + (isFiniteNumber(value) ? Math.abs(value) : 0);
+    }, 0)
+  );
+  return series.map((s) => ({
+    ...s,
+    data: s.data.map((value, index) => {
+      if (!isFiniteNumber(value)) return null;
+      return totals[index] === 0 ? 0 : clean(value / totals[index] * 100);
+    })
+  }));
+}
+function stackTotals(series, stacked) {
+  const length = Math.max(0, ...series.map((s) => s.data.length));
+  const totals = /* @__PURE__ */ new Map();
+  for (const s of series) {
+    const stack = s.stack ?? (stacked ? "Total" : void 0);
+    if (stack === void 0) continue;
+    const sums = totals.get(stack) ?? Array.from({ length }, () => null);
+    s.data.forEach((value, index) => {
+      if (isFiniteNumber(value)) sums[index] = clean((sums[index] ?? 0) + value);
+    });
+    totals.set(stack, sums);
+  }
+  return totals;
+}
+function pairWithCategories(categories, values, axisType) {
+  if (axisType !== "time" && axisType !== "value") return values;
+  return values.map((value, index) => [categories[index], value]);
+}
+function resolveChartHeight(height, rows, { rowHeight = 28, chrome = 56, minHeight = 160, maxHeight } = {}) {
+  if (height !== "auto") return height;
+  let value = Math.max(minHeight, chrome + Math.max(rows, 1) * rowHeight);
+  if (maxHeight !== void 0) value = Math.min(value, maxHeight);
+  return value;
+}
+function allSeriesEmpty(series) {
+  return !series?.length || series.every((s) => !s.data?.some((value) => value != null));
+}
+function trendLine(points) {
+  const finite = points.filter(([x, y]) => isFiniteNumber(x) && isFiniteNumber(y));
+  const n = finite.length;
+  if (n < 2) return null;
+  let sumX = 0;
+  let sumY = 0;
+  let sumXY = 0;
+  let sumX2 = 0;
+  let minX = Infinity;
+  let maxX = -Infinity;
+  for (const [x, y] of finite) {
+    sumX += x;
+    sumY += y;
+    sumXY += x * y;
+    sumX2 += x * x;
+    if (x < minX) minX = x;
+    if (x > maxX) maxX = x;
+  }
+  const denominator = n * sumX2 - sumX * sumX;
+  if (minX === maxX || denominator === 0) return null;
+  const slope = (n * sumXY - sumX * sumY) / denominator;
+  const intercept = (sumY - slope * sumX) / n;
+  return [
+    [minX, slope * minX + intercept],
+    [maxX, slope * maxX + intercept]
+  ];
+}
+function computeDelta(current, previous) {
+  if (!isFiniteNumber(current) || !isFiniteNumber(previous)) return null;
+  const change = clean(current - previous);
+  return {
+    change,
+    ratio: previous === 0 ? null : change / Math.abs(previous),
+    direction: change > 0 ? "up" : change < 0 ? "down" : "flat"
+  };
+}
+
 // src/utils/options.ts
 function toParams(raw, getLabel) {
   const seriesIndex = raw.seriesIndex ?? 0;
@@ -908,222 +1139,34 @@ function withZoomInset(inset, mode, axis) {
   const current = typeof inset?.[edge] === "number" ? inset[edge] : 12;
   return { ...inset, [edge]: current + 36 };
 }
-
-// src/utils/stats.ts
-var isFiniteNumber = (value) => typeof value === "number" && Number.isFinite(value);
-var clean = (value) => Number(value.toPrecision(12));
-function niceStep(rough) {
-  if (!(rough > 0) || !Number.isFinite(rough)) return 1;
-  const power = 10 ** Math.floor(Math.log10(rough));
-  const fraction = rough / power;
-  const nice = fraction <= 1 ? 1 : fraction <= 2 ? 2 : fraction <= 2.5 ? 2.5 : fraction <= 5 ? 5 : 10;
-  return clean(nice * power);
-}
-function bucketLabel(start, end, format) {
-  const text = (value) => formatValue(value, format);
-  if (start === -Infinity && end === Infinity) return "All";
-  if (start === -Infinity) return `< ${text(end)}`;
-  if (end === Infinity) return `${text(start)}+`;
-  return `${text(start)}\u2013${text(end)}`;
-}
-function binValues(values, options = {}) {
-  const { bins, binWidth, format } = options;
-  const finite = values.filter(isFiniteNumber);
-  let edges;
-  if (Array.isArray(bins)) {
-    edges = bins.map((bin) => ({
-      start: bin.start ?? -Infinity,
-      end: bin.end ?? Infinity,
-      label: bin.label
-    }));
-  } else {
-    if (!finite.length) return [];
-    let min = Infinity;
-    let max = -Infinity;
-    for (const value of finite) {
-      if (value < min) min = value;
-      if (value > max) max = value;
-    }
-    if (min === max) {
-      edges = [{ start: min, end: max }];
-    } else {
-      let step;
-      let start;
-      if (binWidth && binWidth > 0) {
-        step = binWidth;
-        start = Math.floor(min / step) * step;
-      } else if (typeof bins === "number" && bins > 0) {
-        step = (max - min) / Math.floor(bins);
-        start = min;
-      } else {
-        const sturges = Math.ceil(Math.log2(finite.length) + 1);
-        step = niceStep((max - min) / sturges);
-        start = Math.floor(min / step) * step;
-      }
-      const count = Math.max(1, Math.ceil(clean((max - start) / step)));
-      edges = Array.from({ length: count }, (_, index) => ({
-        start: clean(start + index * step),
-        end: clean(start + (index + 1) * step)
-      }));
-    }
-  }
-  const buckets = edges.map(({ start, end, label }) => ({
-    label: label ?? bucketLabel(start, end, format),
-    start,
-    end,
-    count: 0
-  }));
-  const last = buckets.length - 1;
-  for (const value of finite) {
-    const index = buckets.findIndex(
-      (bucket, i) => value >= bucket.start && (value < bucket.end || i === last && value <= bucket.end)
-    );
-    if (index !== -1) buckets[index].count++;
-  }
-  return buckets;
-}
-function quantile(sorted, q) {
-  if (!sorted.length) return NaN;
-  const position = (sorted.length - 1) * q;
-  const lower = Math.floor(position);
-  const upper = Math.ceil(position);
-  if (lower === upper) return sorted[lower];
-  return sorted[lower] + (sorted[upper] - sorted[lower]) * (position - lower);
-}
-function boxplotStats(values) {
-  const sorted = values.filter(isFiniteNumber).sort((a, b) => a - b);
-  if (!sorted.length) return null;
-  const q1 = quantile(sorted, 0.25);
-  const median = quantile(sorted, 0.5);
-  const q3 = quantile(sorted, 0.75);
-  const iqr = q3 - q1;
-  const lowFence = q1 - 1.5 * iqr;
-  const highFence = q3 + 1.5 * iqr;
-  const inside = sorted.filter((value) => value >= lowFence && value <= highFence);
-  const outliers = sorted.filter((value) => value < lowFence || value > highFence);
-  return {
-    low: inside[0] ?? q1,
-    q1,
-    median,
-    q3,
-    high: inside[inside.length - 1] ?? q3,
-    outliers,
-    count: sorted.length,
-    mean: sorted.reduce((sum, value) => sum + value, 0) / sorted.length
-  };
-}
-function waterfallLayout(steps) {
-  let running = 0;
-  return steps.map((step) => {
-    let start;
-    let end;
-    let kind;
-    if (step.isTotal === "value") {
-      start = 0;
-      end = isFiniteNumber(step.value) ? step.value : running;
-      kind = "total";
-    } else if (step.isTotal) {
-      start = 0;
-      end = running;
-      kind = "total";
-    } else {
-      const change = isFiniteNumber(step.value) ? step.value : 0;
-      start = running;
-      end = running + change;
-      kind = change < 0 ? "decrease" : "increase";
-    }
-    running = end;
-    const low = Math.min(start, end);
-    const high = Math.max(start, end);
-    let base = 0;
-    let positive = 0;
-    let negative = 0;
-    if (low >= 0) {
-      base = low;
-      positive = high - low;
-    } else if (high <= 0) {
-      base = high;
-      negative = low - high;
-    } else {
-      positive = high;
-      negative = low;
+function buildStackTotalSeries(categories, series, { stacked, position, format, axisType }) {
+  return [...stackTotals(series, stacked)].map(([stack, totals]) => ({
+    id: `__total:${stack}`,
+    type: "bar",
+    stack,
+    data: pairWithCategories(
+      categories,
+      totals.map((total) => total === null ? null : 0),
+      axisType
+    ),
+    silent: true,
+    legendHoverLink: false,
+    tooltip: { show: false },
+    itemStyle: { color: "transparent" },
+    emphasis: { disabled: true },
+    label: {
+      show: true,
+      position,
+      fontWeight: "bold",
+      formatter: (params) => formatValue(totals[params.dataIndex], format)
     }
-    return {
-      start,
-      end,
-      value: kind === "total" ? end : end - start,
-      kind,
-      base: clean(base),
-      positive: clean(positive),
-      negative: clean(negative)
-    };
-  });
-}
-function toPercentStack(series) {
-  const length = Math.max(0, ...series.map((s) => s.data.length));
-  const totals = Array.from(
-    { length },
-    (_, index) => series.reduce((sum, s) => {
-      const value = s.data[index];
-      return sum + (isFiniteNumber(value) ? Math.abs(value) : 0);
-    }, 0)
-  );
-  return series.map((s) => ({
-    ...s,
-    data: s.data.map((value, index) => {
-      if (!isFiniteNumber(value)) return null;
-      return totals[index] === 0 ? 0 : clean(value / totals[index] * 100);
-    })
   }));
 }
-function pairWithCategories(categories, values, axisType) {
-  if (axisType !== "time" && axisType !== "value") return values;
-  return values.map((value, index) => [categories[index], value]);
-}
-function resolveChartHeight(height, rows, { rowHeight = 28, chrome = 56, minHeight = 160, maxHeight } = {}) {
-  if (height !== "auto") return height;
-  let value = Math.max(minHeight, chrome + Math.max(rows, 1) * rowHeight);
-  if (maxHeight !== void 0) value = Math.min(value, maxHeight);
-  return value;
-}
-function allSeriesEmpty(series) {
-  return !series?.length || series.every((s) => !s.data?.some((value) => value != null));
-}
-function trendLine(points) {
-  const finite = points.filter(([x, y]) => isFiniteNumber(x) && isFiniteNumber(y));
-  const n = finite.length;
-  if (n < 2) return null;
-  let sumX = 0;
-  let sumY = 0;
-  let sumXY = 0;
-  let sumX2 = 0;
-  let minX = Infinity;
-  let maxX = -Infinity;
-  for (const [x, y] of finite) {
-    sumX += x;
-    sumY += y;
-    sumXY += x * y;
-    sumX2 += x * x;
-    if (x < minX) minX = x;
-    if (x > maxX) maxX = x;
-  }
-  const denominator = n * sumX2 - sumX * sumX;
-  if (minX === maxX || denominator === 0) return null;
-  const slope = (n * sumXY - sumX * sumY) / denominator;
-  const intercept = (sumY - slope * sumX) / n;
-  return [
-    [minX, slope * minX + intercept],
-    [maxX, slope * maxX + intercept]
-  ];
-}
-function computeDelta(current, previous) {
-  if (!isFiniteNumber(current) || !isFiniteNumber(previous)) return null;
-  const change = clean(current - previous);
-  return {
-    change,
-    ratio: previous === 0 ? null : change / Math.abs(previous),
-    direction: change > 0 ? "up" : change < 0 ? "down" : "flat"
-  };
+function withEndLabelInset(inset, labels) {
+  const longest = Math.max(0, ...labels.map((label) => label.length));
+  if (longest === 0) return inset;
+  const current = typeof inset?.right === "number" ? inset.right : 0;
+  return { ...inset, right: current + longest * 7 + 16 };
 }
 
 // src/utils/records.ts
@@ -1290,10 +1333,11 @@ function toSliceData(rows, options) {
     nullLabel = "Unknown",
     colors: colors3
   } = options;
+  const effective = value === void 0 ? "count" : aggregate;
   const { categories, series } = fromRecords(rows, {
     category: name,
     value,
-    aggregate: value === void 0 ? "count" : aggregate,
+    aggregate: effective,
     nullLabel
   });
   const values = series[0]?.data ?? [];
@@ -1307,7 +1351,12 @@ function toSliceData(rows, options) {
     const rest = slices.slice(topN);
     slices = slices.slice(0, topN);
     if (otherLabel !== void 0) {
-      slices.push({ name: otherLabel, value: rest.reduce((sum, slice) => sum + slice.value, 0) });
+      const folded = new Set(rest.map((slice) => slice.name));
+      const other = fromRecords(
+        (rows ?? []).filter((row) => folded.has(toLabel(read(row, name), nullLabel))),
+        { category: () => otherLabel, value, aggregate: effective }
+      ).series[0]?.data[0];
+      slices.push({ name: otherLabel, value: other ?? 0 });
     }
   }
   return slices.map(
@@ -1468,15 +1517,17 @@ function formatTableCell(table, cell, column, format) {
       return formatValue(cell, format);
   }
 }
-function csvCell(cell) {
+var FORMULA_START = /^[=+\-@\t\r]/;
+function csvCell(cell, raw = cell) {
   if (cell == null) return "";
-  const text = String(cell);
+  let text = String(cell);
+  if (typeof raw === "string" && FORMULA_START.test(text)) text = `'${text}`;
   return /[",\r\n]/.test(text) ? `"${text.replace(/"/g, '""')}"` : text;
 }
 function tableToCsv(table, format) {
   const lines = [table.headers, ...table.rows].map(
     (row, rowIndex) => row.map(
-      (cell, column) => csvCell(rowIndex > 0 && format ? formatTableCell(table, cell, column, format) : cell)
+      (cell, column) => csvCell(rowIndex > 0 && format ? formatTableCell(table, cell, column, format) : cell, cell)
     ).join(",")
   );
   return lines.join("\r\n");
@@ -1519,6 +1570,7 @@ exports.buildDataZoom = buildDataZoom;
 exports.buildLegend = buildLegend;
 exports.buildMarkArea = buildMarkArea;
 exports.buildMarkLine = buildMarkLine;
+exports.buildStackTotalSeries = buildStackTotalSeries;
 exports.buildTooltip = buildTooltip;
 exports.bulletTable = bulletTable;
 exports.candlestickTable = candlestickTable;
@@ -1579,6 +1631,7 @@ exports.sankeyTable = sankeyTable;
 exports.scatterTable = scatterTable;
 exports.seriesLabelLookup = seriesLabelLookup;
 exports.sliceTable = sliceTable;
+exports.stackTotals = stackTotals;
 exports.tableToCsv = tableToCsv;
 exports.toPercentStack = toPercentStack;
 exports.toSliceData = toSliceData;
@@ -1588,6 +1641,7 @@ exports.valueAxisConfig = valueAxisConfig;
 exports.valueLabelFormatter = valueLabelFormatter;
 exports.waterfallLayout = waterfallLayout;
 exports.waterfallTable = waterfallTable;
+exports.withEndLabelInset = withEndLabelInset;
 exports.withPointLabels = withPointLabels;
 exports.withReferenceMarks = withReferenceMarks;
 exports.withZoomInset = withZoomInset;

package/dist/index.d.cts

@@ -350,6 +350,32 @@ bottomOffset?: number): AnyObject[] | undefined;
  * Grid room for a data zoom slider, added to a `gridInset` result
  */
 declare function withZoomInset(inset: AnyObject | undefined, mode: boolean | 'inside' | 'slider' | undefined, axis: 'x' | 'y'): AnyObject | undefined;
+interface StackTotalOptions {
+    /** The chart's `stacked` prop */
+    stacked: boolean | 'percent' | undefined;
+    /** Where the label sits: 'right' for horizontal bars, 'top' for vertical ones */
+    position: 'right' | 'top';
+    /** Formats each total (the resolved value format) */
+    format?: (value: number) => string;
+    /** The category axis type, for time or value axes that read [x, y] points */
+    axisType?: string;
+}
+/**
+ * Invisible series that label each stack's total at the end of the bar: a
+ * zero-height bar on top of every stack, carrying the total as its label.
+ * They are silent and left out of the tooltip; the legend lists only the
+ * real series.
+ */
+declare function buildStackTotalSeries(categories: (string | number)[], series: {
+    data: (number | null)[];
+    stack?: string;
+}[], { stacked, position, format, axisType }: StackTotalOptions): AnyObject[];
+/**
+ * Widen the grid's right edge for labels drawn past the end of horizontal
+ * bars, which `containLabel` does not reserve room for. Width is estimated
+ * from the longest label.
+ */
+declare function withEndLabelInset(inset: AnyObject | undefined, labels: string[]): AnyObject | undefined;
 
 /**
  * Data preparation for distribution, waterfall and stacked charts, and
@@ -417,6 +443,16 @@ declare function waterfallLayout(steps: WaterfallStep[]): WaterfallBar[];
 declare function toPercentStack<S extends {
     data: (number | null)[];
 }>(series: S[]): S[];
+/**
+ * Each stack's total by category, keyed by stack id. A series stacks under
+ * its own `stack` id, or 'Total' when `stacked` is set; unstacked series are
+ * left out. Totals are the raw values, also for percent stacks. A category
+ * with no values in a stack gets `null`.
+ */
+declare function stackTotals(series: {
+    data: (number | null)[];
+    stack?: string;
+}[], stacked: boolean | 'percent' | undefined): Map<string, (number | null)[]>;
 /**
  * Pair category labels with values for a time or value x-axis, which reads
  * [x, y] points rather than values by category index
@@ -536,7 +572,11 @@ interface ToSliceDataOptions<T> {
     sort?: 'desc' | 'asc' | 'none';
     /** Keep only the largest N slices */
     topN?: number;
-    /** Fold slices beyond `topN` into one with this label; omit to drop them */
+    /**
+     * Fold slices beyond `topN` into one with this label; omit to drop them.
+     * The folded slice aggregates the folded records, so with 'avg' it is their
+     * average rather than a sum of averages.
+     */
     otherLabel?: string;
     /** Label for a missing name (defaults to 'Unknown') */
     nullLabel?: string;
@@ -627,4 +667,4 @@ declare function downloadFile(content: string, filename: string, mimeType?: stri
  */
 declare function downloadCsv(table: ChartDataTable, filename: string): void;
 
-export { type Accessor, type Aggregate, type AutoHeightOptions, AxisConfig, BarChartData, type BinValuesOptions, BoxPlotStats, type BuildDataLabelOptions, type BuildLegendOptions, type BuildTooltipOptions, BulletItem, CandlestickData, CategoryChartData, CategorySeriesData, ChartDataTable, ChartFormatter, type ChartFormatterOptions, type ChartFormatters, ChartLegendConfig, type Delta, type FromRecordsOptions, HeatmapData, HistogramBin, HistogramBucket, LabelFormatterParams, LegendItem, LineChartData, PieSliceData, type PointLabelLookup, RadarChartData, RadarIndicator, ReferenceBand, ReferenceLine, type ReferenceMarkOptions, SankeyData, ScatterChartData, type ToSliceDataOptions, TooltipFormatterParams, TreemapNode, ValueFormat, type WaterfallBar, WaterfallStep, abbreviateNumber, allSeriesEmpty, anchorCenterGraphic, binValues, boxPlotTable, boxplotStats, buildAxis, buildDataLabel, buildDataZoom, buildLegend, buildMarkArea, buildMarkLine, buildTooltip, bulletTable, candlestickTable, categoryTable, chartFilename, chartFormatters, computeDelta, createTooltipFormatter, downloadCsv, downloadFile, escapeHtml, formatCurrency, formatDate, formatNumber, formatPercent, formatTableCell, formatTooltipValue, formatValue, fromRecords, generateAreaChartDescription, generateBarChartDescription, generateBoxPlotDescription, generateBulletDescription, generateComboChartDescription, generateDataTable, generateDotPlotDescription, generateHistogramDescription, generateLineChartDescription, generatePieChartDescription, generateScatterChartDescription, generateWaterfallDescription, getLegendItems, getReplaceMerge, gridInset, hasPointLabels, heatmapTable, histogramTable, itemLabelLookup, legendCenter, mergeChartOption, nameLabelLookup, niceStep, pairWithCategories, pointLabel, quantile, radarTable, resolveChartHeight, resolveValueFormatter, sankeyTable, scatterTable, seriesLabelLookup, sliceTable, tableToCsv, toPercentStack, toSliceData, treemapTable, trendLine, valueAxisConfig, valueLabelFormatter, waterfallLayout, waterfallTable, withPointLabels, withReferenceMarks, withZoomInset };
+export { type Accessor, type Aggregate, type AutoHeightOptions, AxisConfig, BarChartData, type BinValuesOptions, BoxPlotStats, type BuildDataLabelOptions, type BuildLegendOptions, type BuildTooltipOptions, BulletItem, CandlestickData, CategoryChartData, CategorySeriesData, ChartDataTable, ChartFormatter, type ChartFormatterOptions, type ChartFormatters, ChartLegendConfig, type Delta, type FromRecordsOptions, HeatmapData, HistogramBin, HistogramBucket, LabelFormatterParams, LegendItem, LineChartData, PieSliceData, type PointLabelLookup, RadarChartData, RadarIndicator, ReferenceBand, ReferenceLine, type ReferenceMarkOptions, SankeyData, ScatterChartData, type StackTotalOptions, type ToSliceDataOptions, TooltipFormatterParams, TreemapNode, ValueFormat, type WaterfallBar, WaterfallStep, abbreviateNumber, allSeriesEmpty, anchorCenterGraphic, binValues, boxPlotTable, boxplotStats, buildAxis, buildDataLabel, buildDataZoom, buildLegend, buildMarkArea, buildMarkLine, buildStackTotalSeries, buildTooltip, bulletTable, candlestickTable, categoryTable, chartFilename, chartFormatters, computeDelta, createTooltipFormatter, downloadCsv, downloadFile, escapeHtml, formatCurrency, formatDate, formatNumber, formatPercent, formatTableCell, formatTooltipValue, formatValue, fromRecords, generateAreaChartDescription, generateBarChartDescription, generateBoxPlotDescription, generateBulletDescription, generateComboChartDescription, generateDataTable, generateDotPlotDescription, generateHistogramDescription, generateLineChartDescription, generatePieChartDescription, generateScatterChartDescription, generateWaterfallDescription, getLegendItems, getReplaceMerge, gridInset, hasPointLabels, heatmapTable, histogramTable, itemLabelLookup, legendCenter, mergeChartOption, nameLabelLookup, niceStep, pairWithCategories, pointLabel, quantile, radarTable, resolveChartHeight, resolveValueFormatter, sankeyTable, scatterTable, seriesLabelLookup, sliceTable, stackTotals, tableToCsv, toPercentStack, toSliceData, treemapTable, trendLine, valueAxisConfig, valueLabelFormatter, waterfallLayout, waterfallTable, withEndLabelInset, withPointLabels, withReferenceMarks, withZoomInset };

package/dist/index.d.ts

@@ -350,6 +350,32 @@ bottomOffset?: number): AnyObject[] | undefined;
  * Grid room for a data zoom slider, added to a `gridInset` result
  */
 declare function withZoomInset(inset: AnyObject | undefined, mode: boolean | 'inside' | 'slider' | undefined, axis: 'x' | 'y'): AnyObject | undefined;
+interface StackTotalOptions {
+    /** The chart's `stacked` prop */
+    stacked: boolean | 'percent' | undefined;
+    /** Where the label sits: 'right' for horizontal bars, 'top' for vertical ones */
+    position: 'right' | 'top';
+    /** Formats each total (the resolved value format) */
+    format?: (value: number) => string;
+    /** The category axis type, for time or value axes that read [x, y] points */
+    axisType?: string;
+}
+/**
+ * Invisible series that label each stack's total at the end of the bar: a
+ * zero-height bar on top of every stack, carrying the total as its label.
+ * They are silent and left out of the tooltip; the legend lists only the
+ * real series.
+ */
+declare function buildStackTotalSeries(categories: (string | number)[], series: {
+    data: (number | null)[];
+    stack?: string;
+}[], { stacked, position, format, axisType }: StackTotalOptions): AnyObject[];
+/**
+ * Widen the grid's right edge for labels drawn past the end of horizontal
+ * bars, which `containLabel` does not reserve room for. Width is estimated
+ * from the longest label.
+ */
+declare function withEndLabelInset(inset: AnyObject | undefined, labels: string[]): AnyObject | undefined;
 
 /**
  * Data preparation for distribution, waterfall and stacked charts, and
@@ -417,6 +443,16 @@ declare function waterfallLayout(steps: WaterfallStep[]): WaterfallBar[];
 declare function toPercentStack<S extends {
     data: (number | null)[];
 }>(series: S[]): S[];
+/**
+ * Each stack's total by category, keyed by stack id. A series stacks under
+ * its own `stack` id, or 'Total' when `stacked` is set; unstacked series are
+ * left out. Totals are the raw values, also for percent stacks. A category
+ * with no values in a stack gets `null`.
+ */
+declare function stackTotals(series: {
+    data: (number | null)[];
+    stack?: string;
+}[], stacked: boolean | 'percent' | undefined): Map<string, (number | null)[]>;
 /**
  * Pair category labels with values for a time or value x-axis, which reads
  * [x, y] points rather than values by category index
@@ -536,7 +572,11 @@ interface ToSliceDataOptions<T> {
     sort?: 'desc' | 'asc' | 'none';
     /** Keep only the largest N slices */
     topN?: number;
-    /** Fold slices beyond `topN` into one with this label; omit to drop them */
+    /**
+     * Fold slices beyond `topN` into one with this label; omit to drop them.
+     * The folded slice aggregates the folded records, so with 'avg' it is their
+     * average rather than a sum of averages.
+     */
     otherLabel?: string;
     /** Label for a missing name (defaults to 'Unknown') */
     nullLabel?: string;
@@ -627,4 +667,4 @@ declare function downloadFile(content: string, filename: string, mimeType?: stri
  */
 declare function downloadCsv(table: ChartDataTable, filename: string): void;
 
-export { type Accessor, type Aggregate, type AutoHeightOptions, AxisConfig, BarChartData, type BinValuesOptions, BoxPlotStats, type BuildDataLabelOptions, type BuildLegendOptions, type BuildTooltipOptions, BulletItem, CandlestickData, CategoryChartData, CategorySeriesData, ChartDataTable, ChartFormatter, type ChartFormatterOptions, type ChartFormatters, ChartLegendConfig, type Delta, type FromRecordsOptions, HeatmapData, HistogramBin, HistogramBucket, LabelFormatterParams, LegendItem, LineChartData, PieSliceData, type PointLabelLookup, RadarChartData, RadarIndicator, ReferenceBand, ReferenceLine, type ReferenceMarkOptions, SankeyData, ScatterChartData, type ToSliceDataOptions, TooltipFormatterParams, TreemapNode, ValueFormat, type WaterfallBar, WaterfallStep, abbreviateNumber, allSeriesEmpty, anchorCenterGraphic, binValues, boxPlotTable, boxplotStats, buildAxis, buildDataLabel, buildDataZoom, buildLegend, buildMarkArea, buildMarkLine, buildTooltip, bulletTable, candlestickTable, categoryTable, chartFilename, chartFormatters, computeDelta, createTooltipFormatter, downloadCsv, downloadFile, escapeHtml, formatCurrency, formatDate, formatNumber, formatPercent, formatTableCell, formatTooltipValue, formatValue, fromRecords, generateAreaChartDescription, generateBarChartDescription, generateBoxPlotDescription, generateBulletDescription, generateComboChartDescription, generateDataTable, generateDotPlotDescription, generateHistogramDescription, generateLineChartDescription, generatePieChartDescription, generateScatterChartDescription, generateWaterfallDescription, getLegendItems, getReplaceMerge, gridInset, hasPointLabels, heatmapTable, histogramTable, itemLabelLookup, legendCenter, mergeChartOption, nameLabelLookup, niceStep, pairWithCategories, pointLabel, quantile, radarTable, resolveChartHeight, resolveValueFormatter, sankeyTable, scatterTable, seriesLabelLookup, sliceTable, tableToCsv, toPercentStack, toSliceData, treemapTable, trendLine, valueAxisConfig, valueLabelFormatter, waterfallLayout, waterfallTable, withPointLabels, withReferenceMarks, withZoomInset };
+export { type Accessor, type Aggregate, type AutoHeightOptions, AxisConfig, BarChartData, type BinValuesOptions, BoxPlotStats, type BuildDataLabelOptions, type BuildLegendOptions, type BuildTooltipOptions, BulletItem, CandlestickData, CategoryChartData, CategorySeriesData, ChartDataTable, ChartFormatter, type ChartFormatterOptions, type ChartFormatters, ChartLegendConfig, type Delta, type FromRecordsOptions, HeatmapData, HistogramBin, HistogramBucket, LabelFormatterParams, LegendItem, LineChartData, PieSliceData, type PointLabelLookup, RadarChartData, RadarIndicator, ReferenceBand, ReferenceLine, type ReferenceMarkOptions, SankeyData, ScatterChartData, type StackTotalOptions, type ToSliceDataOptions, TooltipFormatterParams, TreemapNode, ValueFormat, type WaterfallBar, WaterfallStep, abbreviateNumber, allSeriesEmpty, anchorCenterGraphic, binValues, boxPlotTable, boxplotStats, buildAxis, buildDataLabel, buildDataZoom, buildLegend, buildMarkArea, buildMarkLine, buildStackTotalSeries, buildTooltip, bulletTable, candlestickTable, categoryTable, chartFilename, chartFormatters, computeDelta, createTooltipFormatter, downloadCsv, downloadFile, escapeHtml, formatCurrency, formatDate, formatNumber, formatPercent, formatTableCell, formatTooltipValue, formatValue, fromRecords, generateAreaChartDescription, generateBarChartDescription, generateBoxPlotDescription, generateBulletDescription, generateComboChartDescription, generateDataTable, generateDotPlotDescription, generateHistogramDescription, generateLineChartDescription, generatePieChartDescription, generateScatterChartDescription, generateWaterfallDescription, getLegendItems, getReplaceMerge, gridInset, hasPointLabels, heatmapTable, histogramTable, itemLabelLookup, legendCenter, mergeChartOption, nameLabelLookup, niceStep, pairWithCategories, pointLabel, quantile, radarTable, resolveChartHeight, resolveValueFormatter, sankeyTable, scatterTable, seriesLabelLookup, sliceTable, stackTotals, tableToCsv, toPercentStack, toSliceData, treemapTable, trendLine, valueAxisConfig, valueLabelFormatter, waterfallLayout, waterfallTable, withEndLabelInset, withPointLabels, withReferenceMarks, withZoomInset };

package/dist/index.js

@@ -303,6 +303,237 @@ function mergeChartOption(generated, override) {
   return merged;
 }
 
+// src/utils/stats.ts
+var isFiniteNumber = (value) => typeof value === "number" && Number.isFinite(value);
+var clean = (value) => Number(value.toPrecision(12));
+function niceStep(rough) {
+  if (!(rough > 0) || !Number.isFinite(rough)) return 1;
+  const power = 10 ** Math.floor(Math.log10(rough));
+  const fraction = rough / power;
+  const nice = fraction <= 1 ? 1 : fraction <= 2 ? 2 : fraction <= 2.5 ? 2.5 : fraction <= 5 ? 5 : 10;
+  return clean(nice * power);
+}
+function bucketLabel(start, end, format) {
+  const text = (value) => formatValue(value, format);
+  if (start === -Infinity && end === Infinity) return "All";
+  if (start === -Infinity) return `< ${text(end)}`;
+  if (end === Infinity) return `${text(start)}+`;
+  return `${text(start)}\u2013${text(end)}`;
+}
+function binValues(values, options = {}) {
+  const { bins, binWidth, format } = options;
+  const finite = values.filter(isFiniteNumber);
+  let edges;
+  if (Array.isArray(bins)) {
+    edges = bins.map((bin) => ({
+      start: bin.start ?? -Infinity,
+      end: bin.end ?? Infinity,
+      label: bin.label
+    }));
+  } else {
+    if (!finite.length) return [];
+    let min = Infinity;
+    let max = -Infinity;
+    for (const value of finite) {
+      if (value < min) min = value;
+      if (value > max) max = value;
+    }
+    if (min === max) {
+      edges = [{ start: min, end: max }];
+    } else {
+      let step;
+      let start;
+      if (binWidth && binWidth > 0) {
+        step = binWidth;
+        start = Math.floor(min / step) * step;
+      } else if (typeof bins === "number" && bins > 0) {
+        step = (max - min) / Math.floor(bins);
+        start = min;
+      } else {
+        const sturges = Math.ceil(Math.log2(finite.length) + 1);
+        step = niceStep((max - min) / sturges);
+        start = Math.floor(min / step) * step;
+      }
+      const count = Math.max(1, Math.ceil(clean((max - start) / step)));
+      edges = Array.from({ length: count }, (_, index) => ({
+        start: clean(start + index * step),
+        end: clean(start + (index + 1) * step)
+      }));
+    }
+  }
+  const buckets = edges.map(({ start, end, label }) => ({
+    label: label ?? bucketLabel(start, end, format),
+    start,
+    end,
+    count: 0
+  }));
+  const last = buckets.length - 1;
+  for (const value of finite) {
+    const index = buckets.findIndex(
+      (bucket, i) => value >= bucket.start && (value < bucket.end || i === last && value <= bucket.end)
+    );
+    if (index !== -1) buckets[index].count++;
+  }
+  return buckets;
+}
+function quantile(sorted, q) {
+  if (!sorted.length) return NaN;
+  const position = (sorted.length - 1) * q;
+  const lower = Math.floor(position);
+  const upper = Math.ceil(position);
+  if (lower === upper) return sorted[lower];
+  return sorted[lower] + (sorted[upper] - sorted[lower]) * (position - lower);
+}
+function boxplotStats(values) {
+  const sorted = values.filter(isFiniteNumber).sort((a, b) => a - b);
+  if (!sorted.length) return null;
+  const q1 = quantile(sorted, 0.25);
+  const median = quantile(sorted, 0.5);
+  const q3 = quantile(sorted, 0.75);
+  const iqr = q3 - q1;
+  const lowFence = q1 - 1.5 * iqr;
+  const highFence = q3 + 1.5 * iqr;
+  const inside = sorted.filter((value) => value >= lowFence && value <= highFence);
+  const outliers = sorted.filter((value) => value < lowFence || value > highFence);
+  return {
+    low: inside[0] ?? q1,
+    q1,
+    median,
+    q3,
+    high: inside[inside.length - 1] ?? q3,
+    outliers,
+    count: sorted.length,
+    mean: sorted.reduce((sum, value) => sum + value, 0) / sorted.length
+  };
+}
+function waterfallLayout(steps) {
+  let running = 0;
+  return steps.map((step) => {
+    let start;
+    let end;
+    let kind;
+    if (step.isTotal === "value") {
+      start = 0;
+      end = isFiniteNumber(step.value) ? step.value : running;
+      kind = "total";
+    } else if (step.isTotal) {
+      start = 0;
+      end = running;
+      kind = "total";
+    } else {
+      const change = isFiniteNumber(step.value) ? step.value : 0;
+      start = running;
+      end = running + change;
+      kind = change < 0 ? "decrease" : "increase";
+    }
+    running = end;
+    const low = Math.min(start, end);
+    const high = Math.max(start, end);
+    let base = 0;
+    let positive = 0;
+    let negative = 0;
+    if (low >= 0) {
+      base = low;
+      positive = high - low;
+    } else if (high <= 0) {
+      base = high;
+      negative = low - high;
+    } else {
+      positive = high;
+      negative = low;
+    }
+    return {
+      start,
+      end,
+      value: kind === "total" ? end : end - start,
+      kind,
+      base: clean(base),
+      positive: clean(positive),
+      negative: clean(negative)
+    };
+  });
+}
+function toPercentStack(series) {
+  const length = Math.max(0, ...series.map((s) => s.data.length));
+  const totals = Array.from(
+    { length },
+    (_, index) => series.reduce((sum, s) => {
+      const value = s.data[index];
+      return sum + (isFiniteNumber(value) ? Math.abs(value) : 0);
+    }, 0)
+  );
+  return series.map((s) => ({
+    ...s,
+    data: s.data.map((value, index) => {
+      if (!isFiniteNumber(value)) return null;
+      return totals[index] === 0 ? 0 : clean(value / totals[index] * 100);
+    })
+  }));
+}
+function stackTotals(series, stacked) {
+  const length = Math.max(0, ...series.map((s) => s.data.length));
+  const totals = /* @__PURE__ */ new Map();
+  for (const s of series) {
+    const stack = s.stack ?? (stacked ? "Total" : void 0);
+    if (stack === void 0) continue;
+    const sums = totals.get(stack) ?? Array.from({ length }, () => null);
+    s.data.forEach((value, index) => {
+      if (isFiniteNumber(value)) sums[index] = clean((sums[index] ?? 0) + value);
+    });
+    totals.set(stack, sums);
+  }
+  return totals;
+}
+function pairWithCategories(categories, values, axisType) {
+  if (axisType !== "time" && axisType !== "value") return values;
+  return values.map((value, index) => [categories[index], value]);
+}
+function resolveChartHeight(height, rows, { rowHeight = 28, chrome = 56, minHeight = 160, maxHeight } = {}) {
+  if (height !== "auto") return height;
+  let value = Math.max(minHeight, chrome + Math.max(rows, 1) * rowHeight);
+  if (maxHeight !== void 0) value = Math.min(value, maxHeight);
+  return value;
+}
+function allSeriesEmpty(series) {
+  return !series?.length || series.every((s) => !s.data?.some((value) => value != null));
+}
+function trendLine(points) {
+  const finite = points.filter(([x, y]) => isFiniteNumber(x) && isFiniteNumber(y));
+  const n = finite.length;
+  if (n < 2) return null;
+  let sumX = 0;
+  let sumY = 0;
+  let sumXY = 0;
+  let sumX2 = 0;
+  let minX = Infinity;
+  let maxX = -Infinity;
+  for (const [x, y] of finite) {
+    sumX += x;
+    sumY += y;
+    sumXY += x * y;
+    sumX2 += x * x;
+    if (x < minX) minX = x;
+    if (x > maxX) maxX = x;
+  }
+  const denominator = n * sumX2 - sumX * sumX;
+  if (minX === maxX || denominator === 0) return null;
+  const slope = (n * sumXY - sumX * sumY) / denominator;
+  const intercept = (sumY - slope * sumX) / n;
+  return [
+    [minX, slope * minX + intercept],
+    [maxX, slope * maxX + intercept]
+  ];
+}
+function computeDelta(current, previous) {
+  if (!isFiniteNumber(current) || !isFiniteNumber(previous)) return null;
+  const change = clean(current - previous);
+  return {
+    change,
+    ratio: previous === 0 ? null : change / Math.abs(previous),
+    direction: change > 0 ? "up" : change < 0 ? "down" : "flat"
+  };
+}
+
 // src/utils/options.ts
 function toParams(raw, getLabel) {
   const seriesIndex = raw.seriesIndex ?? 0;
@@ -587,222 +818,34 @@ function withZoomInset(inset, mode, axis) {
   const current = typeof inset?.[edge] === "number" ? inset[edge] : 12;
   return { ...inset, [edge]: current + 36 };
 }
-
-// src/utils/stats.ts
-var isFiniteNumber = (value) => typeof value === "number" && Number.isFinite(value);
-var clean = (value) => Number(value.toPrecision(12));
-function niceStep(rough) {
-  if (!(rough > 0) || !Number.isFinite(rough)) return 1;
-  const power = 10 ** Math.floor(Math.log10(rough));
-  const fraction = rough / power;
-  const nice = fraction <= 1 ? 1 : fraction <= 2 ? 2 : fraction <= 2.5 ? 2.5 : fraction <= 5 ? 5 : 10;
-  return clean(nice * power);
-}
-function bucketLabel(start, end, format) {
-  const text = (value) => formatValue(value, format);
-  if (start === -Infinity && end === Infinity) return "All";
-  if (start === -Infinity) return `< ${text(end)}`;
-  if (end === Infinity) return `${text(start)}+`;
-  return `${text(start)}\u2013${text(end)}`;
-}
-function binValues(values, options = {}) {
-  const { bins, binWidth, format } = options;
-  const finite = values.filter(isFiniteNumber);
-  let edges;
-  if (Array.isArray(bins)) {
-    edges = bins.map((bin) => ({
-      start: bin.start ?? -Infinity,
-      end: bin.end ?? Infinity,
-      label: bin.label
-    }));
-  } else {
-    if (!finite.length) return [];
-    let min = Infinity;
-    let max = -Infinity;
-    for (const value of finite) {
-      if (value < min) min = value;
-      if (value > max) max = value;
-    }
-    if (min === max) {
-      edges = [{ start: min, end: max }];
-    } else {
-      let step;
-      let start;
-      if (binWidth && binWidth > 0) {
-        step = binWidth;
-        start = Math.floor(min / step) * step;
-      } else if (typeof bins === "number" && bins > 0) {
-        step = (max - min) / Math.floor(bins);
-        start = min;
-      } else {
-        const sturges = Math.ceil(Math.log2(finite.length) + 1);
-        step = niceStep((max - min) / sturges);
-        start = Math.floor(min / step) * step;
-      }
-      const count = Math.max(1, Math.ceil(clean((max - start) / step)));
-      edges = Array.from({ length: count }, (_, index) => ({
-        start: clean(start + index * step),
-        end: clean(start + (index + 1) * step)
-      }));
-    }
-  }
-  const buckets = edges.map(({ start, end, label }) => ({
-    label: label ?? bucketLabel(start, end, format),
-    start,
-    end,
-    count: 0
-  }));
-  const last = buckets.length - 1;
-  for (const value of finite) {
-    const index = buckets.findIndex(
-      (bucket, i) => value >= bucket.start && (value < bucket.end || i === last && value <= bucket.end)
-    );
-    if (index !== -1) buckets[index].count++;
-  }
-  return buckets;
-}
-function quantile(sorted, q) {
-  if (!sorted.length) return NaN;
-  const position = (sorted.length - 1) * q;
-  const lower = Math.floor(position);
-  const upper = Math.ceil(position);
-  if (lower === upper) return sorted[lower];
-  return sorted[lower] + (sorted[upper] - sorted[lower]) * (position - lower);
-}
-function boxplotStats(values) {
-  const sorted = values.filter(isFiniteNumber).sort((a, b) => a - b);
-  if (!sorted.length) return null;
-  const q1 = quantile(sorted, 0.25);
-  const median = quantile(sorted, 0.5);
-  const q3 = quantile(sorted, 0.75);
-  const iqr = q3 - q1;
-  const lowFence = q1 - 1.5 * iqr;
-  const highFence = q3 + 1.5 * iqr;
-  const inside = sorted.filter((value) => value >= lowFence && value <= highFence);
-  const outliers = sorted.filter((value) => value < lowFence || value > highFence);
-  return {
-    low: inside[0] ?? q1,
-    q1,
-    median,
-    q3,
-    high: inside[inside.length - 1] ?? q3,
-    outliers,
-    count: sorted.length,
-    mean: sorted.reduce((sum, value) => sum + value, 0) / sorted.length
-  };
-}
-function waterfallLayout(steps) {
-  let running = 0;
-  return steps.map((step) => {
-    let start;
-    let end;
-    let kind;
-    if (step.isTotal === "value") {
-      start = 0;
-      end = isFiniteNumber(step.value) ? step.value : running;
-      kind = "total";
-    } else if (step.isTotal) {
-      start = 0;
-      end = running;
-      kind = "total";
-    } else {
-      const change = isFiniteNumber(step.value) ? step.value : 0;
-      start = running;
-      end = running + change;
-      kind = change < 0 ? "decrease" : "increase";
-    }
-    running = end;
-    const low = Math.min(start, end);
-    const high = Math.max(start, end);
-    let base = 0;
-    let positive = 0;
-    let negative = 0;
-    if (low >= 0) {
-      base = low;
-      positive = high - low;
-    } else if (high <= 0) {
-      base = high;
-      negative = low - high;
-    } else {
-      positive = high;
-      negative = low;
+function buildStackTotalSeries(categories, series, { stacked, position, format, axisType }) {
+  return [...stackTotals(series, stacked)].map(([stack, totals]) => ({
+    id: `__total:${stack}`,
+    type: "bar",
+    stack,
+    data: pairWithCategories(
+      categories,
+      totals.map((total) => total === null ? null : 0),
+      axisType
+    ),
+    silent: true,
+    legendHoverLink: false,
+    tooltip: { show: false },
+    itemStyle: { color: "transparent" },
+    emphasis: { disabled: true },
+    label: {
+      show: true,
+      position,
+      fontWeight: "bold",
+      formatter: (params) => formatValue(totals[params.dataIndex], format)
     }
-    return {
-      start,
-      end,
-      value: kind === "total" ? end : end - start,
-      kind,
-      base: clean(base),
-      positive: clean(positive),
-      negative: clean(negative)
-    };
-  });
-}
-function toPercentStack(series) {
-  const length = Math.max(0, ...series.map((s) => s.data.length));
-  const totals = Array.from(
-    { length },
-    (_, index) => series.reduce((sum, s) => {
-      const value = s.data[index];
-      return sum + (isFiniteNumber(value) ? Math.abs(value) : 0);
-    }, 0)
-  );
-  return series.map((s) => ({
-    ...s,
-    data: s.data.map((value, index) => {
-      if (!isFiniteNumber(value)) return null;
-      return totals[index] === 0 ? 0 : clean(value / totals[index] * 100);
-    })
   }));
 }
-function pairWithCategories(categories, values, axisType) {
-  if (axisType !== "time" && axisType !== "value") return values;
-  return values.map((value, index) => [categories[index], value]);
-}
-function resolveChartHeight(height, rows, { rowHeight = 28, chrome = 56, minHeight = 160, maxHeight } = {}) {
-  if (height !== "auto") return height;
-  let value = Math.max(minHeight, chrome + Math.max(rows, 1) * rowHeight);
-  if (maxHeight !== void 0) value = Math.min(value, maxHeight);
-  return value;
-}
-function allSeriesEmpty(series) {
-  return !series?.length || series.every((s) => !s.data?.some((value) => value != null));
-}
-function trendLine(points) {
-  const finite = points.filter(([x, y]) => isFiniteNumber(x) && isFiniteNumber(y));
-  const n = finite.length;
-  if (n < 2) return null;
-  let sumX = 0;
-  let sumY = 0;
-  let sumXY = 0;
-  let sumX2 = 0;
-  let minX = Infinity;
-  let maxX = -Infinity;
-  for (const [x, y] of finite) {
-    sumX += x;
-    sumY += y;
-    sumXY += x * y;
-    sumX2 += x * x;
-    if (x < minX) minX = x;
-    if (x > maxX) maxX = x;
-  }
-  const denominator = n * sumX2 - sumX * sumX;
-  if (minX === maxX || denominator === 0) return null;
-  const slope = (n * sumXY - sumX * sumY) / denominator;
-  const intercept = (sumY - slope * sumX) / n;
-  return [
-    [minX, slope * minX + intercept],
-    [maxX, slope * maxX + intercept]
-  ];
-}
-function computeDelta(current, previous) {
-  if (!isFiniteNumber(current) || !isFiniteNumber(previous)) return null;
-  const change = clean(current - previous);
-  return {
-    change,
-    ratio: previous === 0 ? null : change / Math.abs(previous),
-    direction: change > 0 ? "up" : change < 0 ? "down" : "flat"
-  };
+function withEndLabelInset(inset, labels) {
+  const longest = Math.max(0, ...labels.map((label) => label.length));
+  if (longest === 0) return inset;
+  const current = typeof inset?.right === "number" ? inset.right : 0;
+  return { ...inset, right: current + longest * 7 + 16 };
 }
 
 // src/utils/records.ts
@@ -969,10 +1012,11 @@ function toSliceData(rows, options) {
     nullLabel = "Unknown",
     colors
   } = options;
+  const effective = value === void 0 ? "count" : aggregate;
   const { categories, series } = fromRecords(rows, {
     category: name,
     value,
-    aggregate: value === void 0 ? "count" : aggregate,
+    aggregate: effective,
     nullLabel
   });
   const values = series[0]?.data ?? [];
@@ -986,7 +1030,12 @@ function toSliceData(rows, options) {
     const rest = slices.slice(topN);
     slices = slices.slice(0, topN);
     if (otherLabel !== void 0) {
-      slices.push({ name: otherLabel, value: rest.reduce((sum, slice) => sum + slice.value, 0) });
+      const folded = new Set(rest.map((slice) => slice.name));
+      const other = fromRecords(
+        (rows ?? []).filter((row) => folded.has(toLabel(read(row, name), nullLabel))),
+        { category: () => otherLabel, value, aggregate: effective }
+      ).series[0]?.data[0];
+      slices.push({ name: otherLabel, value: other ?? 0 });
     }
   }
   return slices.map(
@@ -1147,15 +1196,17 @@ function formatTableCell(table, cell, column, format) {
       return formatValue(cell, format);
   }
 }
-function csvCell(cell) {
+var FORMULA_START = /^[=+\-@\t\r]/;
+function csvCell(cell, raw = cell) {
   if (cell == null) return "";
-  const text = String(cell);
+  let text = String(cell);
+  if (typeof raw === "string" && FORMULA_START.test(text)) text = `'${text}`;
   return /[",\r\n]/.test(text) ? `"${text.replace(/"/g, '""')}"` : text;
 }
 function tableToCsv(table, format) {
   const lines = [table.headers, ...table.rows].map(
     (row, rowIndex) => row.map(
-      (cell, column) => csvCell(rowIndex > 0 && format ? formatTableCell(table, cell, column, format) : cell)
+      (cell, column) => csvCell(rowIndex > 0 && format ? formatTableCell(table, cell, column, format) : cell, cell)
     ).join(",")
   );
   return lines.join("\r\n");
@@ -1184,4 +1235,4 @@ function downloadCsv(table, filename) {
   );
 }
 
-export { abbreviateNumber, allSeriesEmpty, anchorCenterGraphic, binValues, boxPlotTable, boxplotStats, buildAxis, buildDataLabel, buildDataZoom, buildLegend, buildMarkArea, buildMarkLine, buildTooltip, bulletTable, candlestickTable, categoryTable, chartFilename, chartFormatters, computeDelta, createTooltipFormatter, downloadCsv, downloadFile, escapeHtml, formatCurrency, formatDate, formatNumber, formatPercent, formatTableCell, formatTooltipValue, formatValue, fromRecords, generateAreaChartDescription, generateBarChartDescription, generateBoxPlotDescription, generateBulletDescription, generateComboChartDescription, generateDataTable, generateDotPlotDescription, generateHistogramDescription, generateLineChartDescription, generatePieChartDescription, generateScatterChartDescription, generateWaterfallDescription, getLegendItems, getReplaceMerge, gridInset, hasPointLabels, heatmapTable, histogramTable, itemLabelLookup, legendCenter, mergeChartOption, nameLabelLookup, niceStep, pairWithCategories, pointLabel, quantile, radarTable, resolveChartHeight, resolveValueFormatter, sankeyTable, scatterTable, seriesLabelLookup, sliceTable, tableToCsv, toPercentStack, toSliceData, treemapTable, trendLine, valueAxisConfig, valueLabelFormatter, waterfallLayout, waterfallTable, withPointLabels, withReferenceMarks, withZoomInset };
+export { abbreviateNumber, allSeriesEmpty, anchorCenterGraphic, binValues, boxPlotTable, boxplotStats, buildAxis, buildDataLabel, buildDataZoom, buildLegend, buildMarkArea, buildMarkLine, buildStackTotalSeries, buildTooltip, bulletTable, candlestickTable, categoryTable, chartFilename, chartFormatters, computeDelta, createTooltipFormatter, downloadCsv, downloadFile, escapeHtml, formatCurrency, formatDate, formatNumber, formatPercent, formatTableCell, formatTooltipValue, formatValue, fromRecords, generateAreaChartDescription, generateBarChartDescription, generateBoxPlotDescription, generateBulletDescription, generateComboChartDescription, generateDataTable, generateDotPlotDescription, generateHistogramDescription, generateLineChartDescription, generatePieChartDescription, generateScatterChartDescription, generateWaterfallDescription, getLegendItems, getReplaceMerge, gridInset, hasPointLabels, heatmapTable, histogramTable, itemLabelLookup, legendCenter, mergeChartOption, nameLabelLookup, niceStep, pairWithCategories, pointLabel, quantile, radarTable, resolveChartHeight, resolveValueFormatter, sankeyTable, scatterTable, seriesLabelLookup, sliceTable, stackTotals, tableToCsv, toPercentStack, toSliceData, treemapTable, trendLine, valueAxisConfig, valueLabelFormatter, waterfallLayout, waterfallTable, withEndLabelInset, withPointLabels, withReferenceMarks, withZoomInset };

package/dist/types/index.d.cts

@@ -816,6 +816,12 @@ interface BarChartProps extends BaseChartProps, LegendChartProps, LabelChartProp
     stacked?: boolean | 'percent';
     /** Show value labels on bars */
     showValues?: boolean;
+    /**
+     * Label each stack's total at the end of the bar, formatted with
+     * `valueFormat`. Applies to stacked series (`stacked` or a series `stack`
+     * id); percent stacks show the raw total.
+     */
+    showTotal?: boolean;
     /** Click event handler */
     onClick?: (params: DataPointEventParams) => void;
     /** Hover event handler */

package/dist/types/index.d.ts

@@ -816,6 +816,12 @@ interface BarChartProps extends BaseChartProps, LegendChartProps, LabelChartProp
     stacked?: boolean | 'percent';
     /** Show value labels on bars */
     showValues?: boolean;
+    /**
+     * Label each stack's total at the end of the bar, formatted with
+     * `valueFormat`. Applies to stacked series (`stacked` or a series `stack`
+     * id); percent stacks show the raw total.
+     */
+    showTotal?: boolean;
     /** Click event handler */
     onClick?: (params: DataPointEventParams) => void;
     /** Hover event handler */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classic-homes/charts-core",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Core utilities and theme for Classic Theme charts",
   "type": "module",
   "main": "dist/index.cjs",