reamkit 1.32.0 → 1.33.0

package/dist/esm/core/drawingml/chart-geometry.d.ts

@@ -20,10 +20,14 @@ export interface ChartPolyline {
     readonly strokeHex: string;
     readonly widthPt: number;
 }
-/** A closed, filled polygon (area-chart bands). Drawn before strokes/labels. */
+/**
+ * A closed polygon: area-chart bands, the faces of 3-D bars, a 3-D chart's
+ * walls. Drawn before rectangles, strokes and labels; one without a fill is
+ * its outline alone.
+ */
 export interface ChartPolygon {
     readonly points: ReadonlyArray<readonly [number, number]>;
-    readonly fillHex: string;
+    readonly fillHex?: string;
     readonly strokeHex?: string;
     readonly widthPt?: number;
 }
@@ -44,7 +48,7 @@ export interface ChartWedge {
 /** How a {@link ChartLabel} sits horizontally relative to its anchor point. */
 export type LabelAlign = 'left' | 'center' | 'right';
 /** A text label (title, axis tick, category, data value, legend entry). */
-export interface ChartLabel {
+export interface ChartLabel extends ChartFont {
     readonly text: string;
     /** Anchor point; `align` says how text sits relative to it. */
     readonly x: number;
@@ -80,6 +84,11 @@ export interface ChartScene {
      * frame and under the gridlines.
      */
     readonly plotBackground?: ChartRect;
+    /**
+     * §21.2.2.69/§21.2.2.11/§21.2.2.191 — a 3-D chart's floor and walls, drawn
+     * over the plot's own fill and under its gridlines.
+     */
+    readonly walls?: ReadonlyArray<ChartPolygon>;
     /**
      * Major gridlines, drawn UNDER the plotted data. Kept apart from the other
      * polylines because z-order is the whole point: gridlines over the bars strip
@@ -88,12 +97,21 @@ export interface ChartScene {
      */
     readonly gridlines?: ReadonlyArray<ChartPolyline>;
 }
+/**
+ * The face a chart's text is set in beyond its size: the family the chart
+ * names (absent — the document's own) and its weight and slant.
+ */
+export interface ChartFont {
+    readonly family?: string;
+    readonly bold?: boolean;
+    readonly italic?: boolean;
+}
 /**
  * Injected text-width measurer: the rendered advance width (points) of `text` at
- * `sizePt`. Keeps this module free of any font/PDF dependency, so it is
- * unit-testable in isolation.
+ * `sizePt`, in `font` when the chart names one. Keeps this module free of any
+ * font/PDF dependency, so it is unit-testable in isolation.
  */
-export type MeasureText = (text: string, sizePt: number) => number;
+export type MeasureText = (text: string, sizePt: number, font?: ChartFont) => number;
 /** Font size (points) for axis ticks, category/data labels and legend text. */
 export declare const CHART_LABEL_PT = 9;
 /** Font size (points) for the chart title. */
@@ -119,22 +137,25 @@ export interface Scale {
 }
 /**
  * The scale Excel gives a value axis it is left to choose, measured against
- * Excel's own PDF of eight column charts (2026-10-01):
+ * Excel's own PDF of its column charts (2026-10-01 and -02):
  *
  *  - the ends: values all of one sign put the axis's near end at zero —
  *    unless their spread is under a sixth of the largest of them, when it
  *    stops half a spread short of the nearest (93…97 runs from 91) — and the
- *    far end, like both ends of a range across zero, takes 5% of the spread
- *    beyond the data before it is rounded out to the step;
+ *    far end takes 5% of its reach from that near end before it is rounded
+ *    out to the step. 70…96 reaches 100.8 and runs 0…120 by 20, where 5% of
+ *    the data's own spread stopped at 97.3 and ran it 0…100 by 10. Both ends
+ *    of a range across zero take 5% of the spread;
  *  - the step: the smallest 1, 2 or 5 × 10ⁿ that leaves at most ten intervals
  *    (`maxIntervals`), whatever the chart's height — 3 750 runs 0…4 000 by 500
  *    on a 150pt chart as on a 400pt one. Only an axis too short to hold the
  *    labels asks for fewer, and the caller says so.
  *
- * Every case of the probe lands where Excel puts it: −1…1.2 on −1.5…1.5 by
+ * Every case of the probes lands where Excel puts it: −1…1.2 on −1.5…1.5 by
  * 0.5, 0.3…4.7 on 0…5 by 0.5, 120…950 on 0…1 000 by 100, 0.012…0.047 on
- * 0…0.05 by 0.005. Heckbert's nice numbers with a budget of ticks by height
- * stepped the budget chart by 1 000 and started 93…97 at zero.
+ * 0…0.05 by 0.005, 1E-150…3E-150 on 0…3.5E-150. Heckbert's nice numbers with
+ * a budget of ticks by height stepped the budget chart by 1 000 and started
+ * 93…97 at zero.
  *
  * @param dataMin      The smallest value to cover.
  * @param dataMax      The largest value to cover.
@@ -143,14 +164,21 @@ export interface Scale {
  */
 export declare function niceScale(dataMin: number, dataMax: number, maxIntervals?: number): Scale;
 /**
- * Format an axis tick value, choosing decimal places from the tick `step` so
- * `0.25`-spaced ticks read `0.25` while integer steps drop the fraction.
+ * A value-axis tick as Excel labels it under General. An axis is not a cell:
+ * its General gives every label nine characters, the sign among them, on an
+ * axis 150pt or 500pt long, upright or lying alike — Excel's own PDF of 44
+ * axes (2026-10-01 and -02). Within them it is the cells' rule
+ * ({@link generalRenderings}): the number as it is where it fits (0.25 — we
+ * wrote 0.3 on an axis stepped by 0.25 — 500000000, −50000000, 0.0000003),
+ * else the finest of it rounded or in scientific notation (0.1234568,
+ * −0.123457, 123456771, 1E+09, 1.235E+09, −1.23E+09, 1.235E-05, 5E-151).
+ * Places counted from the step and written by `toFixed` threw past a hundred
+ * of them, which a step of 1E-150 asked for.
  *
- * @param v    The tick value.
- * @param step The tick spacing (from {@link niceScale}).
+ * @param v The tick value.
  * @returns The label text.
  */
-export declare function formatTick(v: number, step: number): string;
+export declare function formatTick(v: number): string;
 export declare function buildBarScene(chart: Chart, wPt: number, hPt: number, measure: MeasureText): ChartScene;
 /**
  * The name a series shows in the legend: its own `c:tx`, or Excel's positional