@rowsncolumns/charts 28.1.7 → 28.1.10

package/dist/esm/utils/bubble.d.ts

@@ -1,6 +1,33 @@
 export declare const toLabelString: (value: unknown) => string;
 export declare const toNumericValue: (value: unknown) => number | null;
-export declare const createBubbleSizeScale: (values: number[]) => (value: number) => number;
+export type BubbleSizeOptions = {
+    /**
+     * Whether a size value sets the bubble's area (Excel's default,
+     * diameter ∝ √value) or its width (diameter ∝ value).
+     */
+    sizeRepresents?: "area" | "width" | null;
+    /** Percent of the default size, 0-300 (Excel's `<c:bubbleScale>`). */
+    bubbleScale?: number | null;
+    /**
+     * The plot area's smaller side in pixels — the largest bubble's
+     * diameter is a fraction of it, so bubbles grow with the chart.
+     */
+    plotMinSide?: number | null;
+};
+/** The largest bubble's diameter at bubbleScale 100: a quarter of the plot area's smaller side. */
+export declare const BUBBLE_MAX_DIAMETER_FRACTION = 0.25;
+/**
+ * Pixel diameter per size value, scaled from ZERO like Excel: the largest
+ * absolute value gets the maximum diameter and every other bubble's area
+ * (or width) is its share of that value. Scaling from the minimum value
+ * instead made the ratio between bubbles depend on the spread of the
+ * data (100 and 101 drew as the smallest and largest bubble), and a
+ * linear diameter made the perceived area grow with the square of the
+ * value (rowsncolumns/spreadsheet#1068).
+ */
+export declare const createBubbleSizeScale: (values: number[], options?: BubbleSizeOptions) => (value: number) => number;
+/** The diameter of the largest bubble for these options. */
+export declare const bubbleMaxDiameter: (options?: BubbleSizeOptions) => number;
 export type BubbleSeriesInput = {
     name?: string | null;
     values: (string | number | boolean | null | undefined)[];
@@ -23,6 +50,12 @@ export type BubbleSeriesPoint = {
     value: [number, number, number];
     name: string;
     xLabel?: string;
+    /**
+     * The point's row in the source ranges. Points with no Y are skipped,
+     * so this is not the point's position in the series — per-point
+     * colours (`dataPointColors[].idx`) key on it.
+     */
+    index: number;
 };
 export type PreparedBubbleSeries = {
     name: string;

package/dist/esm/utils/bubble.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bubble.d.ts","sourceRoot":"","sources":["../../../utils/bubble.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,aAAa,GAAI,OAAO,OAAO,KAAG,MACU,CAAC;AAE1D,eAAO,MAAM,cAAc,GAAI,OAAO,OAAO,KAAG,MAAM,GAAG,IAYxD,CAAC;AAEF,eAAO,MAAM,qBAAqB,GAAI,QAAQ,MAAM,EAAE,aAQrC,MAAM,WAOtB,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,MAAM,EAAE,CAAC,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,GAAG,SAAS,CAAC,EAAE,CAAC;IACzD;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,CAAC,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,GAAG,SAAS,CAAC,EAAE,CAAC;IAC3D;;;OAGG;IACH,UAAU,CAAC,EAAE,CAAC,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,GAAG,SAAS,CAAC,EAAE,CAAC;CAC/D,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,iBAAiB,EAAE,CAAC;CAC7B,CAAC;AAEF,MAAM,MAAM,uBAAuB,GAAG;IACpC;;;;;OAKG;IACH,OAAO,EAAE,CAAC,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,GAAG,SAAS,CAAC,EAAE,CAAC;IAC1D,WAAW,EAAE,CAAC,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,GAAG,SAAS,CAAC,EAAE,CAAC;IAC9D;;OAEG;IACH,UAAU,EAAE,CAAC,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,GAAG,SAAS,CAAC,EAAE,CAAC;IAC7D,MAAM,EAAE,iBAAiB,EAAE,CAAC;CAC7B,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG;IAC/B,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,MAAM,EAAE,oBAAoB,EAAE,CAAC;IAC/B,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB,CAAC;AAwCF,eAAO,MAAM,uBAAuB,GAAI,+CAKrC,uBAAuB,KAAG,kBAsF5B,CAAC"}
+{"version":3,"file":"bubble.d.ts","sourceRoot":"","sources":["../../../utils/bubble.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,aAAa,GAAI,OAAO,OAAO,KAAG,MACU,CAAC;AAE1D,eAAO,MAAM,cAAc,GAAI,OAAO,OAAO,KAAG,MAAM,GAAG,IAYxD,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG;IAC9B;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC;IACzC,sEAAsE;IACtE,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B,CAAC;AAEF,mGAAmG;AACnG,eAAO,MAAM,4BAA4B,OAAO,CAAC;AAMjD;;;;;;;;GAQG;AACH,eAAO,MAAM,qBAAqB,GAChC,QAAQ,MAAM,EAAE,EAChB,UAAS,iBAAsB,MAMvB,OAAO,MAAM,WAQtB,CAAC;AAEF,4DAA4D;AAC5D,eAAO,MAAM,iBAAiB,GAAI,UAAS,iBAAsB,WAUhE,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,MAAM,EAAE,CAAC,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,GAAG,SAAS,CAAC,EAAE,CAAC;IACzD;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,CAAC,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,GAAG,SAAS,CAAC,EAAE,CAAC;IAC3D;;;OAGG;IACH,UAAU,CAAC,EAAE,CAAC,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,GAAG,SAAS,CAAC,EAAE,CAAC;CAC/D,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,KAAK,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,iBAAiB,EAAE,CAAC;CAC7B,CAAC;AAEF,MAAM,MAAM,uBAAuB,GAAG;IACpC;;;;;OAKG;IACH,OAAO,EAAE,CAAC,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,GAAG,SAAS,CAAC,EAAE,CAAC;IAC1D,WAAW,EAAE,CAAC,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,GAAG,SAAS,CAAC,EAAE,CAAC;IAC9D;;OAEG;IACH,UAAU,EAAE,CAAC,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,GAAG,SAAS,CAAC,EAAE,CAAC;IAC7D,MAAM,EAAE,iBAAiB,EAAE,CAAC;CAC7B,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG;IAC/B,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,MAAM,EAAE,oBAAoB,EAAE,CAAC;IAC/B,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB,CAAC;AAwCF,eAAO,MAAM,uBAAuB,GAAI,+CAKrC,uBAAuB,KAAG,kBAuF5B,CAAC"}

package/dist/esm/utils/bubble.js

@@ -12,22 +12,45 @@ export const toNumericValue = (value) => {
     }
     return null;
 };
-export const createBubbleSizeScale = (values) => {
+/** The largest bubble's diameter at bubbleScale 100: a quarter of the plot area's smaller side. */
+export const BUBBLE_MAX_DIAMETER_FRACTION = 0.25;
+/** Fallback plot side when the chart has no measured size yet. */
+const DEFAULT_PLOT_MIN_SIDE = 240;
+/** A positive size never collapses below this diameter. */
+const MIN_BUBBLE_DIAMETER = 2;
+/**
+ * Pixel diameter per size value, scaled from ZERO like Excel: the largest
+ * absolute value gets the maximum diameter and every other bubble's area
+ * (or width) is its share of that value. Scaling from the minimum value
+ * instead made the ratio between bubbles depend on the spread of the
+ * data (100 and 101 drew as the smallest and largest bubble), and a
+ * linear diameter made the perceived area grow with the square of the
+ * value (rowsncolumns/spreadsheet#1068).
+ */
+export const createBubbleSizeScale = (values, options = {}) => {
+    const maxDiameter = bubbleMaxDiameter(options);
     const valid = values.filter((value) => Number.isFinite(value));
-    if (valid.length === 0) {
-        return () => 24;
-    }
-    const min = Math.min(...valid);
-    const max = Math.max(...valid);
-    const range = max - min || 1;
+    const maxAbs = valid.reduce((max, value) => Math.max(max, Math.abs(value)), 0);
+    const byWidth = options.sizeRepresents === "width";
     return (value) => {
-        if (!Number.isFinite(value)) {
-            return 24;
+        if (!Number.isFinite(value) || maxAbs === 0) {
+            return maxDiameter;
         }
-        const ratio = (value - min) / range;
-        return 12 + ratio * 42;
+        const share = Math.abs(value) / maxAbs;
+        const diameter = maxDiameter * (byWidth ? share : Math.sqrt(share));
+        return share > 0 ? Math.max(MIN_BUBBLE_DIAMETER, diameter) : 0;
     };
 };
+/** The diameter of the largest bubble for these options. */
+export const bubbleMaxDiameter = (options = {}) => {
+    const plotMinSide = typeof options.plotMinSide === "number" && options.plotMinSide > 0
+        ? options.plotMinSide
+        : DEFAULT_PLOT_MIN_SIDE;
+    const scale = typeof options.bubbleScale === "number" && Number.isFinite(options.bubbleScale)
+        ? Math.min(300, Math.max(0, options.bubbleScale)) / 100
+        : 1;
+    return plotMinSide * BUBBLE_MAX_DIAMETER_FRACTION * scale;
+};
 /**
  * Build the X-coordinate index for a series. Numeric values map to
  * their own coordinate; string values become categorical (deduped into
@@ -107,6 +130,7 @@ export const prepareBubbleSeriesData = ({ xValues, labelValues, sizeValues, seri
                 value: [coordinate.coordinate, y, sizeValue],
                 name: label,
                 xLabel: coordinateLabel,
+                index: i,
             });
         }
         const name = serie.name && serie.name.trim()

package/dist/esm/utils/doughnut.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Doughnut geometry shared by the renderers (rowsncolumns/spreadsheet#1064,
+ * #1065). Every fraction here is of the doughnut's OUTER radius — Excel's
+ * `<c:holeSize val="75"/>` is 0.75 of the outer edge, whatever the chart
+ * draws that edge at (echarts: 75% of the chart; plotly: the trace domain).
+ */
+/** `doughnutHoleSize` clamped to Excel's 0-90% range; 0.5 when unset. */
+export declare const clampDoughnutHole: (hole: unknown) => number;
+export type DoughnutRing = {
+    inner: number;
+    outer: number;
+};
+/**
+ * Excel draws a doughnut's series as concentric rings, nested from the hole
+ * outwards — series 0 innermost — splitting the band between the hole and
+ * the outer edge evenly. One ring (the whole band) for a single series.
+ */
+export declare const doughnutRings: (hole: number, count: number) => DoughnutRing[];
+//# sourceMappingURL=doughnut.d.ts.map

package/dist/esm/utils/doughnut.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"doughnut.d.ts","sourceRoot":"","sources":["../../../utils/doughnut.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,yEAAyE;AACzE,eAAO,MAAM,iBAAiB,GAAI,MAAM,OAAO,KAAG,MACiB,CAAC;AAEpE,MAAM,MAAM,YAAY,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAE5D;;;;GAIG;AACH,eAAO,MAAM,aAAa,GAAI,MAAM,MAAM,EAAE,OAAO,MAAM,KAAG,YAAY,EAOvE,CAAC"}

package/dist/esm/utils/doughnut.js

@@ -0,0 +1,21 @@
+/**
+ * Doughnut geometry shared by the renderers (rowsncolumns/spreadsheet#1064,
+ * #1065). Every fraction here is of the doughnut's OUTER radius — Excel's
+ * `<c:holeSize val="75"/>` is 0.75 of the outer edge, whatever the chart
+ * draws that edge at (echarts: 75% of the chart; plotly: the trace domain).
+ */
+/** `doughnutHoleSize` clamped to Excel's 0-90% range; 0.5 when unset. */
+export const clampDoughnutHole = (hole) => typeof hole === "number" ? Math.max(0, Math.min(0.9, hole)) : 0.5;
+/**
+ * Excel draws a doughnut's series as concentric rings, nested from the hole
+ * outwards — series 0 innermost — splitting the band between the hole and
+ * the outer edge evenly. One ring (the whole band) for a single series.
+ */
+export const doughnutRings = (hole, count) => {
+    const n = Math.max(1, Math.floor(count));
+    const band = 1 - hole;
+    return Array.from({ length: n }, (_, k) => ({
+        inner: hole + (band * k) / n,
+        outer: hole + (band * (k + 1)) / n,
+    }));
+};

package/dist/esm/utils/echarts-overlays.d.ts

@@ -0,0 +1,46 @@
+type OverlaySeriesSpec = {
+    color?: string | null;
+    useSecondaryAxis?: boolean | null;
+    trendlines?: Array<{
+        type?: any;
+        order?: number | null;
+        period?: number | null;
+        name?: string | null;
+        color?: string | null;
+        forecastForward?: number | null;
+        forecastBackward?: number | null;
+    }> | null;
+    errorBars?: {
+        direction?: "x" | "y" | null;
+        barType?: "both" | "plus" | "minus" | null;
+        valueType?: any;
+        value?: number | null;
+        noEndCap?: boolean | null;
+        plusRange?: any;
+        minusRange?: any;
+    } | null;
+};
+export type EchartsOverlayOptions<TRange = unknown> = {
+    series: OverlaySeriesSpec;
+    /** The series' values (Y on an XY chart), index-aligned with `xValues`. */
+    values: (number | null | undefined)[];
+    /**
+     * Scatter / bubble: the real X coordinate per point. Omitted for a
+     * category chart, where the point index is the category coordinate.
+     */
+    xValues?: (number | null | undefined)[] | null;
+    /** Horizontal bar: the category index is the y coordinate. */
+    horizontal?: boolean;
+    dataLabel: string;
+    /** The data series' own colour — overlays default to it. */
+    seriesColor: string;
+    /** Reads a custom error bar's plus / minus range. */
+    resolveRange: (range: TRange) => unknown[] | null | undefined;
+};
+/**
+ * Build the overlay series for one data series. Returns an empty array
+ * when the series has neither trendlines nor error bars.
+ */
+export declare const buildEchartsOverlaySeries: <TRange = unknown>({ series, values, xValues, horizontal, dataLabel, seriesColor, resolveRange, }: EchartsOverlayOptions<TRange>) => any[];
+export {};
+//# sourceMappingURL=echarts-overlays.d.ts.map

package/dist/esm/utils/echarts-overlays.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"echarts-overlays.d.ts","sourceRoot":"","sources":["../../../utils/echarts-overlays.ts"],"names":[],"mappings":"AAkBA,KAAK,iBAAiB,GAAG;IACvB,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,gBAAgB,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IAClC,UAAU,CAAC,EACP,KAAK,CAAC;QACJ,IAAI,CAAC,EAAE,GAAG,CAAC;QACX,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QACtB,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QACvB,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QACrB,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QACtB,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QAChC,gBAAgB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;KAClC,CAAC,GACF,IAAI,CAAC;IACT,SAAS,CAAC,EAAE;QACV,SAAS,CAAC,EAAE,GAAG,GAAG,GAAG,GAAG,IAAI,CAAC;QAC7B,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC;QAC3C,SAAS,CAAC,EAAE,GAAG,CAAC;QAChB,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QACtB,QAAQ,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;QAC1B,SAAS,CAAC,EAAE,GAAG,CAAC;QAChB,UAAU,CAAC,EAAE,GAAG,CAAC;KAClB,GAAG,IAAI,CAAC;CACV,CAAC;AAEF,MAAM,MAAM,qBAAqB,CAAC,MAAM,GAAG,OAAO,IAAI;IACpD,MAAM,EAAE,iBAAiB,CAAC;IAC1B,2EAA2E;IAC3E,MAAM,EAAE,CAAC,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,EAAE,CAAC;IACtC;;;OAGG;IACH,OAAO,CAAC,EAAE,CAAC,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,EAAE,GAAG,IAAI,CAAC;IAC/C,8DAA8D;IAC9D,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,4DAA4D;IAC5D,WAAW,EAAE,MAAM,CAAC;IACpB,qDAAqD;IACrD,YAAY,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,EAAE,GAAG,IAAI,GAAG,SAAS,CAAC;CAC/D,CAAC;AAIF;;;GAGG;AACH,eAAO,MAAM,yBAAyB,GAAI,MAAM,GAAG,OAAO,EAAE,gFAQzD,qBAAqB,CAAC,MAAM,CAAC,KAAG,GAAG,EA4HrC,CAAC"}

package/dist/esm/utils/echarts-overlays.js

@@ -0,0 +1,135 @@
+/**
+ * Trendline and error-bar overlay series for the echarts renderer.
+ *
+ * One data series may carry trendlines (`<c:trendline>`) and error bars
+ * (`<c:errBars>`); both are drawn as extra echarts series appended after
+ * the data series. The same builder serves every cartesian layout:
+ *
+ *   - category charts (line / column / area): the point index is the
+ *     category coordinate, values sit on the value axis;
+ *   - horizontal bars: the same, with the axes swapped — the category
+ *     index is the y coordinate (rowsncolumns/spreadsheet#1061 drew the
+ *     overlays on the swapped axes, outside the plot);
+ *   - scatter / bubble: real (x, y) coordinates per point, and the
+ *     trendline is a regression of Y on X (#1067).
+ */
+import { computeErrorBars, resolveCustomErrorBarValues } from "./error-bars";
+import { computeTrendline } from "./trendline";
+const ERROR_BAR_CAP_HALF = 5;
+/**
+ * Build the overlay series for one data series. Returns an empty array
+ * when the series has neither trendlines nor error bars.
+ */
+export const buildEchartsOverlaySeries = ({ series, values, xValues, horizontal = false, dataLabel, seriesColor, resolveRange, }) => {
+    if (values.length === 0)
+        return [];
+    const overlays = [];
+    const isXY = Array.isArray(xValues);
+    const useSecondary = series.useSecondaryAxis ? { yAxisIndex: 1 } : {};
+    // Trendlines — one overlay line series per spec.
+    for (const tl of series.trendlines ?? []) {
+        const result = computeTrendline(values, {
+            type: tl.type,
+            order: tl.order,
+            period: tl.period,
+            forecastForward: tl.forecastForward,
+            forecastBackward: tl.forecastBackward,
+        }, isXY ? xValues : undefined);
+        if (!result || result.points.length < 2)
+            continue;
+        const tlName = tl.name ??
+            `${dataLabel ? dataLabel + " " : ""}${tl.type ?? "linear"} trend`;
+        overlays.push({
+            type: "line",
+            name: tlName,
+            // On a category chart the index x overlays the category axis even
+            // when forecasting extends beyond the data range; a horizontal bar
+            // keeps its categories on y.
+            data: result.points.map((p) => (horizontal ? [p.y, p.x] : [p.x, p.y])),
+            showSymbol: false,
+            smooth: tl.type === "poly",
+            lineStyle: {
+                color: tl.color ?? seriesColor,
+                type: "dashed",
+                width: 2,
+            },
+            itemStyle: { color: tl.color ?? seriesColor },
+            tooltip: { show: false },
+            z: 5,
+            ...useSecondary,
+        });
+    }
+    // Error bars — a custom series of whiskers. valueType "custom" reads
+    // per-point magnitudes from the spec's plus/minus ranges, resolved
+    // through the same extractor the series values use.
+    if (series.errorBars) {
+        const direction = series.errorBars.direction ?? "y";
+        // An X error bar on an XY chart sizes from the X values (a percentage
+        // or deviation of X); a category chart has only value-axis bars, so a
+        // horizontal bar's whisker runs along x whatever the direction says.
+        const alongX = isXY ? direction === "x" : horizontal || direction === "x";
+        const magnitudeSource = isXY && alongX ? xValues : values;
+        const magnitudes = computeErrorBars(magnitudeSource, resolveCustomErrorBarValues(series.errorBars, resolveRange));
+        if (magnitudes) {
+            const noEndCap = series.errorBars.noEndCap ?? false;
+            const errorData = [];
+            for (let i = 0; i < values.length; i++) {
+                const v = values[i];
+                const y = typeof v === "number" && Number.isFinite(v) ? v : null;
+                const x = isXY ? xValues?.[i] : i;
+                if (y === null || typeof x !== "number" || !Number.isFinite(x)) {
+                    continue;
+                }
+                // [a, b] is the point's (x, y) data coordinate; a horizontal bar
+                // keeps its value on x and its category on y.
+                const [a, b] = !isXY && horizontal ? [y, x] : [x, y];
+                errorData.push([a, b, magnitudes.plus[i] ?? 0, magnitudes.minus[i] ?? 0]);
+            }
+            overlays.push({
+                type: "custom",
+                name: `${dataLabel ? dataLabel + " " : ""}error`,
+                data: errorData,
+                z: 6,
+                tooltip: { show: false },
+                ...useSecondary,
+                renderItem: (_params, api) => {
+                    const a = api.value(0);
+                    const b = api.value(1);
+                    const plus = api.value(2);
+                    const minus = api.value(3);
+                    const center = api.coord([a, b]);
+                    const hi = alongX ? api.coord([a + plus, b]) : api.coord([a, b + plus]);
+                    const lo = alongX ? api.coord([a - minus, b]) : api.coord([a, b - minus]);
+                    const stroke = { stroke: seriesColor, lineWidth: 1 };
+                    const children = [
+                        {
+                            type: "line",
+                            shape: alongX
+                                ? { x1: lo[0], y1: center[1], x2: hi[0], y2: center[1] }
+                                : { x1: center[0], y1: lo[1], x2: center[0], y2: hi[1] },
+                            style: stroke,
+                        },
+                    ];
+                    if (!noEndCap) {
+                        const cap = ERROR_BAR_CAP_HALF;
+                        children.push({
+                            type: "line",
+                            shape: alongX
+                                ? { x1: hi[0], y1: center[1] - cap, x2: hi[0], y2: center[1] + cap }
+                                : { x1: center[0] - cap, y1: hi[1], x2: center[0] + cap, y2: hi[1] },
+                            style: stroke,
+                        }, {
+                            type: "line",
+                            shape: alongX
+                                ? { x1: lo[0], y1: center[1] - cap, x2: lo[0], y2: center[1] + cap }
+                                : { x1: center[0] - cap, y1: lo[1], x2: center[0] + cap, y2: lo[1] },
+                            style: stroke,
+                        });
+                    }
+                    return { type: "group", children };
+                },
+            });
+        }
+    }
+    return overlays;
+};

package/dist/esm/utils/hierarchy.d.ts

@@ -1,12 +1,21 @@
 import type { ChartSpec, SheetRange, TreemapChart } from "@rowsncolumns/spreadsheet";
 type Extractor = (range: SheetRange, hiddenStrategy?: ChartSpec["hiddenDimensionStrategy"]) => (string | number | boolean | null | undefined)[];
 export type HierarchyRow = {
+    /** The node this row defines — the innermost filled level cell. */
     label: string;
+    /** The immediate parent (the last entry of `path`), null for a root. */
     parent: string | null;
     value: number | null;
+    /**
+     * The level names above the node, top level first, after Excel's
+     * fill-down of blank level cells. Absent on a legacy adjacency row
+     * (`parent` alone, naming another row's label).
+     */
+    path?: string[];
 };
 export type HierarchyNode = {
     name: string;
+    /** Unique within the tree: the node's path joined with "/". */
     id?: string;
     value?: number | null;
     children?: HierarchyNode[];
@@ -19,10 +28,23 @@ type ExtractOptions = {
 export declare const getHierarchyHeaderTitle: (spec: TreemapChart, options: ExtractOptions) => string | undefined;
 export declare const extractHierarchyRows: (spec: TreemapChart, options: ExtractOptions) => HierarchyRow[];
 export declare const buildHierarchyTree: (rows: HierarchyRow[]) => HierarchyNode[];
-export declare const toPlotlyHierarchy: (rows: HierarchyRow[]) => {
+export type PlotlyHierarchy = {
+    /** Node names, as drawn. */
     labels: string[];
+    /** Unique node ids (the path joined with "/"); `parents` reference these. */
+    ids: string[];
+    /** Parent id per node, "" for a root. */
     parents: string[];
     values: number[];
+    /** Depth per node, 0 for a root. */
+    depths: number[];
 };
+export declare const toPlotlyHierarchy: (rows: HierarchyRow[]) => PlotlyHierarchy;
+/**
+ * One solid colour per top-level category, inherited by every descendant
+ * (Excel colours a treemap / sunburst by its first level), in tree order.
+ * Returns the colour per node of `toPlotlyHierarchy`'s flat arrays.
+ */
+export declare const hierarchyNodeColors: (hierarchy: Pick<PlotlyHierarchy, "ids" | "parents">, palette: string[]) => string[];
 export {};
 //# sourceMappingURL=hierarchy.d.ts.map

package/dist/esm/utils/hierarchy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hierarchy.d.ts","sourceRoot":"","sources":["../../../utils/hierarchy.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAEV,SAAS,EACT,UAAU,EACV,YAAY,EACb,MAAM,2BAA2B,CAAC;AAEnC,KAAK,SAAS,GAAG,CACf,KAAK,EAAE,UAAU,EACjB,cAAc,CAAC,EAAE,SAAS,CAAC,yBAAyB,CAAC,KAClD,CAAC,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,GAAG,SAAS,CAAC,EAAE,CAAC;AAEtD,MAAM,MAAM,YAAY,GAAG;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,QAAQ,CAAC,EAAE,aAAa,EAAE,CAAC;CAC5B,CAAC;AAEF,KAAK,cAAc,GAAG;IACpB,wBAAwB,EAAE,SAAS,CAAC;IACpC,wBAAwB,EAAE,SAAS,CAAC;IACpC,uBAAuB,CAAC,EAAE,SAAS,CAAC,yBAAyB,CAAC,CAAC;CAChE,CAAC;AA+CF,eAAO,MAAM,uBAAuB,GAClC,MAAM,YAAY,EAClB,SAAS,cAAc,KACtB,MAAM,GAAG,SAgBX,CAAC;AAEF,eAAO,MAAM,oBAAoB,GAC/B,MAAM,YAAY,EAClB,SAAS,cAAc,KACtB,YAAY,EAyCd,CAAC;AAyBF,eAAO,MAAM,kBAAkB,GAAI,MAAM,YAAY,EAAE,KAAG,aAAa,EAoDtE,CAAC;AAEF,eAAO,MAAM,iBAAiB,GAAI,MAAM,YAAY,EAAE;;;;CAoBrD,CAAC"}
+{"version":3,"file":"hierarchy.d.ts","sourceRoot":"","sources":["../../../utils/hierarchy.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAEV,SAAS,EACT,UAAU,EACV,YAAY,EACb,MAAM,2BAA2B,CAAC;AAEnC,KAAK,SAAS,GAAG,CACf,KAAK,EAAE,UAAU,EACjB,cAAc,CAAC,EAAE,SAAS,CAAC,yBAAyB,CAAC,KAClD,CAAC,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,GAAG,SAAS,CAAC,EAAE,CAAC;AAEtD,MAAM,MAAM,YAAY,GAAG;IACzB,mEAAmE;IACnE,KAAK,EAAE,MAAM,CAAC;IACd,wEAAwE;IACxE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,+DAA+D;IAC/D,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,QAAQ,CAAC,EAAE,aAAa,EAAE,CAAC;CAC5B,CAAC;AAEF,KAAK,cAAc,GAAG;IACpB,wBAAwB,EAAE,SAAS,CAAC;IACpC,wBAAwB,EAAE,SAAS,CAAC;IACpC,uBAAuB,CAAC,EAAE,SAAS,CAAC,yBAAyB,CAAC,CAAC;CAChE,CAAC;AA0CF,eAAO,MAAM,uBAAuB,GAClC,MAAM,YAAY,EAClB,SAAS,cAAc,KACtB,MAAM,GAAG,SAgBX,CAAC;AAyCF,eAAO,MAAM,oBAAoB,GAC/B,MAAM,YAAY,EAClB,SAAS,cAAc,KACtB,YAAY,EAiFd,CAAC;AAiDF,eAAO,MAAM,kBAAkB,GAAI,MAAM,YAAY,EAAE,KAAG,aAAa,EAmDtE,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG;IAC5B,4BAA4B;IAC5B,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,6EAA6E;IAC7E,GAAG,EAAE,MAAM,EAAE,CAAC;IACd,yCAAyC;IACzC,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,oCAAoC;IACpC,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB,CAAC;AAEF,eAAO,MAAM,iBAAiB,GAAI,MAAM,YAAY,EAAE,KAAG,eAwBxD,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,GAC9B,WAAW,IAAI,CAAC,eAAe,EAAE,KAAK,GAAG,SAAS,CAAC,EACnD,SAAS,MAAM,EAAE,KAChB,MAAM,EAYR,CAAC"}