ooxml-core 0.19.0 → 0.21.0

package/dist/chart/axis-nice.d.ts

@@ -0,0 +1,97 @@
+/**
+ * PowerPoint's automatic value-axis scale.
+ *
+ * A chart that declares no `c:min` / `c:max` / `c:majorUnit` leaves the bounds
+ * to the application, and PowerPoint does NOT simply run the axis to the largest
+ * data point. It anchors the axis at zero, pads the data, then rounds out to a
+ * round number and labels it in round steps. The reporter's deck (issue #132)
+ * shows the difference plainly: a percentage chart whose bars top out at 52%
+ * gets `0% 20% 40% 60%` from PowerPoint and got `0% 10% 21% 31% 42% 52%` here,
+ * because the axis ran to the data maximum and was then divided into five.
+ *
+ * The rules, from Microsoft's documented automatic-scaling behaviour:
+ *
+ *  - **Zero anchor.** With all-positive data, the axis starts at zero unless the
+ *    smallest value is at least 5/6 of the largest, in which case the data
+ *    occupies a narrow band high up and a zero-anchored axis would flatten it.
+ *    All-negative data mirrors this, ending at zero.
+ *  - **Headroom.** The far end is pushed out by 5% of the data span so the
+ *    tallest bar does not touch the top of the plot.
+ *  - **Round steps.** The major unit is the first "nice" number (1, 2, 2.5 or 5
+ *    times a power of ten) at or above `span / targetIntervals`, and the bounds
+ *    are then snapped outwards to whole multiples of it.
+ *
+ * The snap is what makes the interval count differ from `targetIntervals`:
+ * rounding 0.544 up to a multiple of 0.2 lands on 0.6, which is three steps, not
+ * four. That is the intent, and it is why PowerPoint's axes read in round
+ * numbers while an evenly-divided one does not.
+ */
+/** A resolved automatic axis scale. */
+export interface NiceAxisBounds {
+    min: number;
+    max: number;
+    /** Step between major gridlines; `max - min` is always a whole multiple. */
+    majorUnit: number;
+}
+/**
+ * How many gridline intervals PowerPoint's automatic value-axis scale aims
+ * for, given the chart's plot-area height in the "px" unit `computePlotLayout`
+ * returns (96 px/inch; see `PX_PER_POINT` above).
+ *
+ * This is NOT a universal constant (see this module's original doc comment,
+ * which admitted as much: "matches the axes PowerPoint draws for a chart of
+ * ORDINARY height"): a short chart gets fewer, coarser gridlines than a tall
+ * one, up to a point, because PowerPoint only has room to label so many
+ * without the axis text crowding.
+ *
+ * Measured via PowerPoint COM automation (`New-Object -ComObject
+ * PowerPoint.Application`, `Shapes.AddChart2`, reading back
+ * `chart.Axes(2).MinimumScale/.MaximumScale/.MajorUnit`): building a fresh
+ * clustered-column chart at increasing shape heights with the SAME 8-point,
+ * single-category data (values 1.2-3.2, the exact case reported against this
+ * engine, which this engine rendered 0-4 while PowerPoint drew 0-3.5):
+ *
+ * | chart height | plot height | PowerPoint axis  | gridlines |
+ * |--------------|-------------|------------------|-----------|
+ * | 100pt        | ~33pt       | 0 to 5, unit 5   | 1         |
+ * | 150pt        | ~83pt       | 0 to 4, unit 1   | 4         |
+ * | 200pt        | ~133pt      | 0 to 3.5, unit 0.5 | 7       |
+ * | 300pt        | ~233pt      | 0 to 3.5, unit 0.5 | 7       |
+ * | 1000pt       | ~933pt      | 0 to 3.5, unit 0.5 | 7 (unchanged) |
+ *
+ * Cross-checked against two more datasets (0-52 and 0-9) at the same set of
+ * heights to separate "the target interval count" from "which nice-number
+ * bucket a particular span happens to round into": PowerPoint never asked for
+ * more than about 10 intervals even at a 1000pt-tall chart, it only asks for
+ * FEWER on a plot area too short to fit that many labels. That saturation
+ * (not a straight line) is why this is clamped at the top, not just scaled.
+ *
+ * Modelled as one gridline interval per ~20pt of plot height (roughly one
+ * axis-label line plus padding), clamped to `[1, 10]`. This will not be exact
+ * for every data range: the actual PowerPoint algorithm also nudges the count
+ * by how the span happens to snap to a nice number (see the module doc
+ * comment), which this simplified model does not attempt to reproduce. It is
+ * a large improvement over hard-coding the short-chart answer (4) for every
+ * chart regardless of size, which is the bug this was added to fix.
+ */
+export declare function axisTargetIntervals(plotHeightPx: number): number;
+/** The smallest nice step at or above `value`. */
+export declare function niceAxisStep(value: number): number;
+/**
+ * Resolve the automatic bounds and major unit for a value axis.
+ *
+ * @param dataMin Smallest plotted value.
+ * @param dataMax Largest plotted value.
+ * @param targetIntervals Roughly how many gridline steps to aim for. The snap to
+ *   a round unit means the result is usually one fewer. Defaults to 4 only
+ *   when the caller has no idea how tall the chart's plot area is; pass
+ *   {@link axisTargetIntervals}`(plotHeightPx)` instead whenever that height is
+ *   known; see that function's doc comment for why a fixed constant undershot
+ *   real PowerPoint on any chart of ordinary-or-larger size.
+ * @param headroom Fraction of the data span added beyond the far end. 2D
+ *   charts get PowerPoint's 5%; a right-angle-axes 3D bar chart gets none
+ *   (its axis on data topping out at exactly 5 ends at 5, see
+ *   `chart-3d-oblique-layout.ts`).
+ */
+export declare function niceValueAxisBounds(dataMin: number, dataMax: number, targetIntervals?: number, headroom?: number): NiceAxisBounds;
+//# sourceMappingURL=axis-nice.d.ts.map

package/dist/chart/axis-nice.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"axis-nice.d.ts","sourceRoot":"","sources":["../../src/chart/axis-nice.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,uCAAuC;AACvC,MAAM,WAAW,cAAc;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,4EAA4E;IAC5E,SAAS,EAAE,MAAM,CAAC;CAClB;AAwCD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,wBAAgB,mBAAmB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAOhE;AAED,kDAAkD;AAClD,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CASlD;AAUD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,mBAAmB,CAClC,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EACf,eAAe,SAA2B,EAC1C,QAAQ,SAAW,GACjB,cAAc,CA6ChB"}

package/dist/chart/histogram-binning.d.ts

@@ -0,0 +1,40 @@
+/** The `cx:layoutPr/cx:binning` properties that drive numeric binning. */
+export interface HistogramOptions {
+    binSize?: number | undefined;
+    binCount?: number | undefined;
+    intervalClosed?: 'l' | 'r' | undefined;
+    underflow?: number | 'auto' | undefined;
+    overflow?: number | 'auto' | undefined;
+}
+/** Formats a bin edge for a label. */
+export type HistogramValueFormatter = (value: number) => string;
+export interface HistogramBin {
+    value: number;
+    label: string;
+    sourceIndices: number[];
+}
+/**
+ * Excel/PowerPoint's automatic histogram bin count when the author specifies
+ * neither `binSize` nor `binCount` (Scott's normal reference rule: bin width
+ * = 3.49 * sample standard deviation * n^(-1/3), then the count needed to
+ * span the data at that width). COM-verified against charts-com.pptx slide
+ * 30 / chartEx5.xml: 76 raw values spanning 1-24 (sample sd ~4.898) gave
+ * PowerPoint's own 6 bins of width 4 each; Scott's rule on the same data
+ * gives a raw width of ~4.035, which needs exactly 6 bins to span the range,
+ * matching PowerPoint bin-for-bin. The previous `ceil(sqrt(n))` fallback
+ * gave 9 bins on the same data, visibly narrower than PowerPoint's own.
+ */
+export declare function scottBinCount(values: ReadonlyArray<number>, min: number, max: number): number;
+/** Bin raw observations according to ChartEx binning properties. */
+export declare function computeHistogramBins(values: ReadonlyArray<number>, options: HistogramOptions, format?: HistogramValueFormatter): HistogramBin[];
+/**
+ * Aggregate raw observations by their (repeated) category label instead of by
+ * numeric value range: `cx:layoutPr/cx:aggregation` (COM-verified against
+ * charts-com.pptx slide 31 / chartEx6.xml) means the source rows are
+ * CATEGORICAL, one row per occurrence, with the value column carrying a
+ * constant `1` so summing it counts occurrences per category. Summing
+ * (rather than literally counting rows) also does the right thing for a
+ * dataset that authors a real numeric measure per row instead of a bare `1`.
+ */
+export declare function aggregateByCategory(values: ReadonlyArray<number>, rawCategories: ReadonlyArray<string>): HistogramBin[];
+//# sourceMappingURL=histogram-binning.d.ts.map

package/dist/chart/histogram-binning.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"histogram-binning.d.ts","sourceRoot":"","sources":["../../src/chart/histogram-binning.ts"],"names":[],"mappings":"AASA,0EAA0E;AAC1E,MAAM,WAAW,gBAAgB;IAChC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,cAAc,CAAC,EAAE,GAAG,GAAG,GAAG,GAAG,SAAS,CAAC;IACvC,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;IACxC,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;CACvC;AAED,sCAAsC;AACtC,MAAM,MAAM,uBAAuB,GAAG,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC;AAEhE,MAAM,WAAW,YAAY;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,aAAa,EAAE,MAAM,EAAE,CAAC;CACxB;AAaD;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,aAAa,CAAC,MAAM,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAa7F;AAED,oEAAoE;AACpE,wBAAgB,oBAAoB,CACnC,MAAM,EAAE,aAAa,CAAC,MAAM,CAAC,EAC7B,OAAO,EAAE,gBAAgB,EACzB,MAAM,GAAE,uBAAgC,GACtC,YAAY,EAAE,CA8EhB;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAClC,MAAM,EAAE,aAAa,CAAC,MAAM,CAAC,EAC7B,aAAa,EAAE,aAAa,CAAC,MAAM,CAAC,GAClC,YAAY,EAAE,CAUhB"}

package/dist/chart/index.cjs

@@ -219,11 +219,178 @@ function computeStackedSeriesPlots(seriesValues, catCount, percent) {
   });
 }
 
+// src/chart/axis-nice.ts
+var NICE_STEPS = [1, 2, 2.5, 5, 10];
+var HEADROOM = 0.05;
+var POINTS_PER_GRIDLINE = 20;
+var MIN_TARGET_INTERVALS = 1;
+var MAX_TARGET_INTERVALS = 10;
+var PX_PER_POINT = 4 / 3;
+var DEFAULT_TARGET_INTERVALS = 4;
+var ZERO_ANCHOR_RATIO = 5 / 6;
+function axisTargetIntervals(plotHeightPx) {
+  if (!Number.isFinite(plotHeightPx) || plotHeightPx <= 0) {
+    return DEFAULT_TARGET_INTERVALS;
+  }
+  const plotHeightPt = plotHeightPx / PX_PER_POINT;
+  const raw = Math.round(plotHeightPt / POINTS_PER_GRIDLINE);
+  return Math.min(MAX_TARGET_INTERVALS, Math.max(MIN_TARGET_INTERVALS, raw));
+}
+function niceAxisStep(value) {
+  if (!Number.isFinite(value) || value <= 0) {
+    return 1;
+  }
+  const exponent = Math.floor(Math.log10(value));
+  const power = 10 ** exponent;
+  const mantissa = value / power;
+  const step = NICE_STEPS.find((candidate) => mantissa <= candidate + 1e-12) ?? 10;
+  return step * power;
+}
+function snap(value, unit, direction) {
+  const scaled = value / unit;
+  const rounded = direction === "up" ? Math.ceil(scaled - 1e-9) : Math.floor(scaled + 1e-9);
+  return rounded * unit;
+}
+function niceValueAxisBounds(dataMin, dataMax, targetIntervals = DEFAULT_TARGET_INTERVALS, headroom = HEADROOM) {
+  if (!Number.isFinite(dataMin) || !Number.isFinite(dataMax)) {
+    return { min: 0, max: 1, majorUnit: 0.5 };
+  }
+  const low = Math.min(dataMin, dataMax);
+  const high = Math.max(dataMin, dataMax);
+  const intervals = Math.max(1, Math.round(targetIntervals));
+  if (low === high) {
+    if (low === 0) {
+      return { min: 0, max: 1, majorUnit: 1 / intervals };
+    }
+    const unit2 = niceAxisStep(Math.abs(low) / intervals);
+    return low > 0 ? { min: 0, max: snap(low, unit2, "up") || unit2, majorUnit: unit2 } : { min: snap(low, unit2, "down"), max: 0, majorUnit: unit2 };
+  }
+  const dataSpan = high - low;
+  const padding = dataSpan * headroom;
+  let paddedMin;
+  let paddedMax;
+  if (low >= 0) {
+    paddedMin = low < high * ZERO_ANCHOR_RATIO ? 0 : low - padding;
+    paddedMax = high + padding;
+  } else if (high <= 0) {
+    paddedMax = high > low * ZERO_ANCHOR_RATIO ? 0 : high + padding;
+    paddedMin = low - padding;
+  } else {
+    paddedMin = low - padding;
+    paddedMax = high + padding;
+  }
+  const unit = niceAxisStep((paddedMax - paddedMin) / intervals);
+  const min = paddedMin === 0 ? 0 : snap(paddedMin, unit, "down");
+  let max = paddedMax === 0 ? 0 : snap(paddedMax, unit, "up");
+  if (max <= min) {
+    max = min + unit;
+  }
+  return { min, max, majorUnit: unit };
+}
+
+// src/chart/histogram-binning.ts
+function binLabel(lower, upper, closed, format) {
+  return closed === "r" ? `(${format(lower)}, ${format(upper)}]` : `[${format(lower)}, ${format(upper)})`;
+}
+function scottBinCount(values, min, max) {
+  if (values.length < 2 || max <= min) {
+    return 1;
+  }
+  const mean = values.reduce((sum, value) => sum + value, 0) / values.length;
+  const variance = values.reduce((sum, value) => sum + (value - mean) ** 2, 0) / (values.length - 1);
+  const sd = Math.sqrt(variance);
+  if (!(sd > 0)) {
+    return 1;
+  }
+  const width = 3.49 * sd * values.length ** (-1 / 3);
+  return Math.max(1, Math.ceil((max - min) / width));
+}
+function computeHistogramBins(values, options, format = String) {
+  const closed = options.intervalClosed ?? "l";
+  const finite = values.map((value, sourceIndex) => ({ value, sourceIndex })).filter((item) => Number.isFinite(item.value));
+  if (finite.length === 0) {
+    return [];
+  }
+  const underflow = typeof options.underflow === "number" ? options.underflow : void 0;
+  const overflow = typeof options.overflow === "number" ? options.overflow : void 0;
+  const under = underflow === void 0 ? [] : finite.filter(
+    (item) => closed === "r" ? item.value <= underflow : item.value < underflow
+  );
+  const over = overflow === void 0 ? [] : finite.filter((item) => closed === "l" ? item.value >= overflow : item.value > overflow);
+  const regular = finite.filter((item) => !under.includes(item) && !over.includes(item));
+  const result = [];
+  if (underflow !== void 0) {
+    result.push({
+      value: under.length,
+      label: `${closed === "r" ? "\u2264" : "<"} ${format(underflow)}`,
+      sourceIndices: under.map((item) => item.sourceIndex)
+    });
+  }
+  if (regular.length > 0) {
+    const min = Math.min(...regular.map((item) => item.value));
+    const max = Math.max(...regular.map((item) => item.value));
+    const requestedSize = options.binSize && options.binSize > 0 ? options.binSize : void 0;
+    const requestedCount = options.binCount && options.binCount > 0 ? options.binCount : void 0;
+    const start = requestedSize ? Math.floor(min / requestedSize) * requestedSize : min;
+    const count = requestedSize ? Math.max(
+      closed === "l" ? Math.floor((max - start) / requestedSize) + 1 : Math.ceil((max - start) / requestedSize),
+      1
+    ) : Math.max(
+      requestedCount ?? scottBinCount(
+        regular.map((item) => item.value),
+        min,
+        max
+      ),
+      1
+    );
+    const width = requestedSize ?? Math.max((max - start) / count, 1);
+    const bins = Array.from({ length: count }, (_, index) => ({
+      value: 0,
+      label: binLabel(start + index * width, start + (index + 1) * width, closed, format),
+      sourceIndices: []
+    }));
+    for (const item of regular) {
+      const rawIndex = closed === "r" ? Math.ceil((item.value - start) / width) - 1 : Math.floor((item.value - start) / width);
+      const index = Math.max(0, Math.min(rawIndex, bins.length - 1));
+      const bin = bins[index];
+      if (!bin) continue;
+      bin.value += 1;
+      bin.sourceIndices.push(item.sourceIndex);
+    }
+    result.push(...bins);
+  }
+  if (overflow !== void 0) {
+    result.push({
+      value: over.length,
+      label: `${closed === "l" ? "\u2265" : ">"} ${format(overflow)}`,
+      sourceIndices: over.map((item) => item.sourceIndex)
+    });
+  }
+  return result;
+}
+function aggregateByCategory(values, rawCategories) {
+  const { uniqueCategories, rowIndexesByCategory } = groupRowsByCategory(rawCategories);
+  return uniqueCategories.map((label) => {
+    const rows = rowIndexesByCategory.get(label) ?? [];
+    return {
+      value: rows.reduce((sum, row) => sum + (values[row] ?? 0), 0),
+      label,
+      sourceIndices: rows
+    };
+  });
+}
+
+exports.aggregateByCategory = aggregateByCategory;
+exports.axisTargetIntervals = axisTargetIntervals;
 exports.computeBoxStats = computeBoxStats;
+exports.computeHistogramBins = computeHistogramBins;
 exports.computeLinearRegression = computeLinearRegression;
 exports.computeRSquared = computeRSquared;
 exports.computeStackedSeriesPlots = computeStackedSeriesPlots;
 exports.fitPolynomial = fitPolynomial;
 exports.groupRowsByCategory = groupRowsByCategory;
+exports.niceAxisStep = niceAxisStep;
+exports.niceValueAxisBounds = niceValueAxisBounds;
 exports.resolveBlankDisplay = resolveBlankDisplay;
+exports.scottBinCount = scottBinCount;
 exports.visibleRuns = visibleRuns;

package/dist/chart/index.d.ts

@@ -3,4 +3,6 @@ export * from './regression.js';
 export * from './box-stats.js';
 export * from './blank-display.js';
 export * from './stacked-series.js';
+export * from './axis-nice.js';
+export * from './histogram-binning.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/chart/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/chart/index.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,cAAc,iBAAiB,CAAC;AAChC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/chart/index.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,cAAc,iBAAiB,CAAC;AAChC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,wBAAwB,CAAC"}

package/dist/chart/index.mjs

@@ -217,4 +217,165 @@ function computeStackedSeriesPlots(seriesValues, catCount, percent) {
   });
 }
 
-export { computeBoxStats, computeLinearRegression, computeRSquared, computeStackedSeriesPlots, fitPolynomial, groupRowsByCategory, resolveBlankDisplay, visibleRuns };
+// src/chart/axis-nice.ts
+var NICE_STEPS = [1, 2, 2.5, 5, 10];
+var HEADROOM = 0.05;
+var POINTS_PER_GRIDLINE = 20;
+var MIN_TARGET_INTERVALS = 1;
+var MAX_TARGET_INTERVALS = 10;
+var PX_PER_POINT = 4 / 3;
+var DEFAULT_TARGET_INTERVALS = 4;
+var ZERO_ANCHOR_RATIO = 5 / 6;
+function axisTargetIntervals(plotHeightPx) {
+  if (!Number.isFinite(plotHeightPx) || plotHeightPx <= 0) {
+    return DEFAULT_TARGET_INTERVALS;
+  }
+  const plotHeightPt = plotHeightPx / PX_PER_POINT;
+  const raw = Math.round(plotHeightPt / POINTS_PER_GRIDLINE);
+  return Math.min(MAX_TARGET_INTERVALS, Math.max(MIN_TARGET_INTERVALS, raw));
+}
+function niceAxisStep(value) {
+  if (!Number.isFinite(value) || value <= 0) {
+    return 1;
+  }
+  const exponent = Math.floor(Math.log10(value));
+  const power = 10 ** exponent;
+  const mantissa = value / power;
+  const step = NICE_STEPS.find((candidate) => mantissa <= candidate + 1e-12) ?? 10;
+  return step * power;
+}
+function snap(value, unit, direction) {
+  const scaled = value / unit;
+  const rounded = direction === "up" ? Math.ceil(scaled - 1e-9) : Math.floor(scaled + 1e-9);
+  return rounded * unit;
+}
+function niceValueAxisBounds(dataMin, dataMax, targetIntervals = DEFAULT_TARGET_INTERVALS, headroom = HEADROOM) {
+  if (!Number.isFinite(dataMin) || !Number.isFinite(dataMax)) {
+    return { min: 0, max: 1, majorUnit: 0.5 };
+  }
+  const low = Math.min(dataMin, dataMax);
+  const high = Math.max(dataMin, dataMax);
+  const intervals = Math.max(1, Math.round(targetIntervals));
+  if (low === high) {
+    if (low === 0) {
+      return { min: 0, max: 1, majorUnit: 1 / intervals };
+    }
+    const unit2 = niceAxisStep(Math.abs(low) / intervals);
+    return low > 0 ? { min: 0, max: snap(low, unit2, "up") || unit2, majorUnit: unit2 } : { min: snap(low, unit2, "down"), max: 0, majorUnit: unit2 };
+  }
+  const dataSpan = high - low;
+  const padding = dataSpan * headroom;
+  let paddedMin;
+  let paddedMax;
+  if (low >= 0) {
+    paddedMin = low < high * ZERO_ANCHOR_RATIO ? 0 : low - padding;
+    paddedMax = high + padding;
+  } else if (high <= 0) {
+    paddedMax = high > low * ZERO_ANCHOR_RATIO ? 0 : high + padding;
+    paddedMin = low - padding;
+  } else {
+    paddedMin = low - padding;
+    paddedMax = high + padding;
+  }
+  const unit = niceAxisStep((paddedMax - paddedMin) / intervals);
+  const min = paddedMin === 0 ? 0 : snap(paddedMin, unit, "down");
+  let max = paddedMax === 0 ? 0 : snap(paddedMax, unit, "up");
+  if (max <= min) {
+    max = min + unit;
+  }
+  return { min, max, majorUnit: unit };
+}
+
+// src/chart/histogram-binning.ts
+function binLabel(lower, upper, closed, format) {
+  return closed === "r" ? `(${format(lower)}, ${format(upper)}]` : `[${format(lower)}, ${format(upper)})`;
+}
+function scottBinCount(values, min, max) {
+  if (values.length < 2 || max <= min) {
+    return 1;
+  }
+  const mean = values.reduce((sum, value) => sum + value, 0) / values.length;
+  const variance = values.reduce((sum, value) => sum + (value - mean) ** 2, 0) / (values.length - 1);
+  const sd = Math.sqrt(variance);
+  if (!(sd > 0)) {
+    return 1;
+  }
+  const width = 3.49 * sd * values.length ** (-1 / 3);
+  return Math.max(1, Math.ceil((max - min) / width));
+}
+function computeHistogramBins(values, options, format = String) {
+  const closed = options.intervalClosed ?? "l";
+  const finite = values.map((value, sourceIndex) => ({ value, sourceIndex })).filter((item) => Number.isFinite(item.value));
+  if (finite.length === 0) {
+    return [];
+  }
+  const underflow = typeof options.underflow === "number" ? options.underflow : void 0;
+  const overflow = typeof options.overflow === "number" ? options.overflow : void 0;
+  const under = underflow === void 0 ? [] : finite.filter(
+    (item) => closed === "r" ? item.value <= underflow : item.value < underflow
+  );
+  const over = overflow === void 0 ? [] : finite.filter((item) => closed === "l" ? item.value >= overflow : item.value > overflow);
+  const regular = finite.filter((item) => !under.includes(item) && !over.includes(item));
+  const result = [];
+  if (underflow !== void 0) {
+    result.push({
+      value: under.length,
+      label: `${closed === "r" ? "\u2264" : "<"} ${format(underflow)}`,
+      sourceIndices: under.map((item) => item.sourceIndex)
+    });
+  }
+  if (regular.length > 0) {
+    const min = Math.min(...regular.map((item) => item.value));
+    const max = Math.max(...regular.map((item) => item.value));
+    const requestedSize = options.binSize && options.binSize > 0 ? options.binSize : void 0;
+    const requestedCount = options.binCount && options.binCount > 0 ? options.binCount : void 0;
+    const start = requestedSize ? Math.floor(min / requestedSize) * requestedSize : min;
+    const count = requestedSize ? Math.max(
+      closed === "l" ? Math.floor((max - start) / requestedSize) + 1 : Math.ceil((max - start) / requestedSize),
+      1
+    ) : Math.max(
+      requestedCount ?? scottBinCount(
+        regular.map((item) => item.value),
+        min,
+        max
+      ),
+      1
+    );
+    const width = requestedSize ?? Math.max((max - start) / count, 1);
+    const bins = Array.from({ length: count }, (_, index) => ({
+      value: 0,
+      label: binLabel(start + index * width, start + (index + 1) * width, closed, format),
+      sourceIndices: []
+    }));
+    for (const item of regular) {
+      const rawIndex = closed === "r" ? Math.ceil((item.value - start) / width) - 1 : Math.floor((item.value - start) / width);
+      const index = Math.max(0, Math.min(rawIndex, bins.length - 1));
+      const bin = bins[index];
+      if (!bin) continue;
+      bin.value += 1;
+      bin.sourceIndices.push(item.sourceIndex);
+    }
+    result.push(...bins);
+  }
+  if (overflow !== void 0) {
+    result.push({
+      value: over.length,
+      label: `${closed === "l" ? "\u2265" : ">"} ${format(overflow)}`,
+      sourceIndices: over.map((item) => item.sourceIndex)
+    });
+  }
+  return result;
+}
+function aggregateByCategory(values, rawCategories) {
+  const { uniqueCategories, rowIndexesByCategory } = groupRowsByCategory(rawCategories);
+  return uniqueCategories.map((label) => {
+    const rows = rowIndexesByCategory.get(label) ?? [];
+    return {
+      value: rows.reduce((sum, row) => sum + (values[row] ?? 0), 0),
+      label,
+      sourceIndices: rows
+    };
+  });
+}
+
+export { aggregateByCategory, axisTargetIntervals, computeBoxStats, computeHistogramBins, computeLinearRegression, computeRSquared, computeStackedSeriesPlots, fitPolynomial, groupRowsByCategory, niceAxisStep, niceValueAxisBounds, resolveBlankDisplay, scottBinCount, visibleRuns };

package/dist/diagram/index.cjs

@@ -151,7 +151,8 @@ function parseXml(xml, options = {}) {
     }).parseFromString(xml, "application/xml");
   } catch (error) {
     throw new Error(
-      `Invalid ${label} XML: ${error instanceof Error ? error.message : String(error)}`
+      `Invalid ${label} XML: ${error instanceof Error ? error.message : String(error)}`,
+      { cause: error }
     );
   }
   if (parseError || !parsed.documentElement)

package/dist/diagram/index.mjs

@@ -149,7 +149,8 @@ function parseXml(xml, options = {}) {
     }).parseFromString(xml, "application/xml");
   } catch (error) {
     throw new Error(
-      `Invalid ${label} XML: ${error instanceof Error ? error.message : String(error)}`
+      `Invalid ${label} XML: ${error instanceof Error ? error.message : String(error)}`,
+      { cause: error }
     );
   }
   if (parseError || !parsed.documentElement)

package/dist/docx/attr-units.d.ts

@@ -0,0 +1,11 @@
+import { type SignedTwips, type Twips } from '../units/units.js';
+import type { Paragraph } from './model-paragraph.js';
+/** A non-negative twip attribute as `Twips`, or undefined when absent or not a valid length. */
+export declare function twipsAttr(value: unknown): Twips | undefined;
+/** A possibly negative twip attribute as `SignedTwips`, or undefined when absent or not finite. */
+export declare function signedTwipsAttr(value: unknown): SignedTwips | undefined;
+type ParagraphTwips = Pick<Paragraph, 'spacingBeforeTwips' | 'spacingAfterTwips' | 'lineSpacingTwips' | 'indentLeftTwips' | 'indentRightTwips' | 'indentStartTwips' | 'indentEndTwips' | 'firstLineTwips' | 'hangingTwips'>;
+/** The paragraph's direct spacing and indent attributes as model fields; absent ones are omitted. */
+export declare function paragraphTwipsFromAttrs(attrs: Record<string, unknown>): ParagraphTwips;
+export {};
+//# sourceMappingURL=attr-units.d.ts.map

package/dist/docx/attr-units.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"attr-units.d.ts","sourceRoot":"","sources":["../../src/docx/attr-units.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgC,KAAK,WAAW,EAAE,KAAK,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAC/F,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAKtD,gGAAgG;AAChG,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,GAAG,SAAS,CAI3D;AACD,mGAAmG;AACnG,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,WAAW,GAAG,SAAS,CAEvE;AAED,KAAK,cAAc,GAAG,IAAI,CACzB,SAAS,EACP,oBAAoB,GACpB,mBAAmB,GACnB,kBAAkB,GAClB,iBAAiB,GACjB,kBAAkB,GAClB,kBAAkB,GAClB,gBAAgB,GAChB,gBAAgB,GAChB,cAAc,CAChB,CAAC;AACF,qGAAqG;AACrG,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,cAAc,CAqBtF"}

package/dist/docx/block-parser.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"block-parser.d.ts","sourceRoot":"","sources":["../../src/docx/block-parser.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,KAAK,EAAE,SAAS,EAAY,KAAK,EAAsB,MAAM,YAAY,CAAC;AACxF,OAAO,EAON,KAAK,UAAU,EAEf,MAAM,UAAU,CAAC;AAKlB,OAAO,EAAgB,KAAK,cAAc,EAAE,MAAM,cAAc,CAAC;AAsIjE,iBAAS,cAAc,CAAC,IAAI,EAAE,UAAU,EAAE,EAAE,EAAE,MAAM,GAAG,SAAS,CA0G/D;AAED,iBAAS,UAAU,CAAC,IAAI,EAAE,UAAU,EAAE,EAAE,EAAE,MAAM,GAAG,KAAK,CAEvD;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CACvC,SAAS,EAAE,UAAU,EACrB,QAAQ,SAAK,EACb,OAAO,CAAC,EAAE,cAAc,GACtB,KAAK,EAAE,CAcT;AAYD,OAAO,EAAE,cAAc,EAAE,UAAU,EAAE,CAAC"}
+{"version":3,"file":"block-parser.d.ts","sourceRoot":"","sources":["../../src/docx/block-parser.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,KAAK,EAAE,SAAS,EAAY,KAAK,EAAW,MAAM,YAAY,CAAC;AAC7E,OAAO,EAMN,KAAK,UAAU,EACf,MAAM,UAAU,CAAC;AAIlB,OAAO,EAAgB,KAAK,cAAc,EAAE,MAAM,cAAc,CAAC;AAsIjE,iBAAS,cAAc,CAAC,IAAI,EAAE,UAAU,EAAE,EAAE,EAAE,MAAM,GAAG,SAAS,CA0G/D;AAED,iBAAS,UAAU,CAAC,IAAI,EAAE,UAAU,EAAE,EAAE,EAAE,MAAM,GAAG,KAAK,CAEvD;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CACvC,SAAS,EAAE,UAAU,EACrB,QAAQ,SAAK,EACb,OAAO,CAAC,EAAE,cAAc,GACtB,KAAK,EAAE,CAcT;AAYD,OAAO,EAAE,cAAc,EAAE,UAAU,EAAE,CAAC"}

package/dist/docx/case-transform.d.ts

@@ -0,0 +1,9 @@
+export type CaseMode = 'sentence' | 'lower' | 'upper' | 'title' | 'toggle';
+/** Characters that make up a word, shared with the editor's caret-word lookup. */
+export declare const WORD: RegExp;
+/**
+ * Applies a Word "Change Case" mode to `text`. `atSentenceStart` says whether the text begins a
+ * sentence; it matters only for sentence case, which capitalises the first letter after `. ! ?`.
+ */
+export declare function transformCase(text: string, mode: CaseMode, atSentenceStart?: boolean): string;
+//# sourceMappingURL=case-transform.d.ts.map

package/dist/docx/case-transform.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"case-transform.d.ts","sourceRoot":"","sources":["../../src/docx/case-transform.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,QAAQ,GAAG,UAAU,GAAG,OAAO,GAAG,OAAO,GAAG,OAAO,GAAG,QAAQ,CAAC;AAE3E,kFAAkF;AAClF,eAAO,MAAM,IAAI,QAAoB,CAAC;AAOtC;;;GAGG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,eAAe,UAAO,GAAG,MAAM,CAsB1F"}

package/dist/docx/embedded.cjs

@@ -37,7 +37,8 @@ function parseXml(xml, options = {}) {
     }).parseFromString(xml, "application/xml");
   } catch (error) {
     throw new Error(
-      `Invalid ${label} XML: ${error instanceof Error ? error.message : String(error)}`
+      `Invalid ${label} XML: ${error instanceof Error ? error.message : String(error)}`,
+      { cause: error }
     );
   }
   if (parseError || !parsed.documentElement)

package/dist/docx/embedded.mjs

@@ -31,7 +31,8 @@ function parseXml(xml, options = {}) {
     }).parseFromString(xml, "application/xml");
   } catch (error) {
     throw new Error(
-      `Invalid ${label} XML: ${error instanceof Error ? error.message : String(error)}`
+      `Invalid ${label} XML: ${error instanceof Error ? error.message : String(error)}`,
+      { cause: error }
     );
   }
   if (parseError || !parsed.documentElement)