@sheetxl/sdk 0.8.0-beta.10 → 0.8.0-beta.11

package/types/src/chart/layout/TextMeasurer.d.ts

@@ -0,0 +1,38 @@
+import { IFontCollection } from '../../font/IFontCollection';
+/**
+ * How chart layout measures text: one line's advance width and its height, in points.
+ *
+ * @remarks
+ * Excel lays chart text out with DirectWrite's numbers, not GDI's: advances unhinted and unkerned,
+ * and a line as tall as the font's ascent plus descent at the exact size, from the typo metrics
+ * when the font sets `USE_TYPO_METRICS` and from `usWinAscent`/`usWinDescent` otherwise (measured,
+ * DESIGN-CHART §4). Every host measures through this one interface, so a server and a browser lay
+ * a chart out alike.
+ */
+export interface TextMeasurer {
+    /** The advance width of `text` on one line, in pt. */
+    width(text: string, font: TextMeasurer.Font): number;
+    /** The height of one line, in pt. */
+    lineHeight(font: TextMeasurer.Font): number;
+}
+export declare namespace TextMeasurer {
+    interface Font {
+        family: string;
+        /** In pt. */
+        size: number;
+        bold?: boolean;
+        italic?: boolean;
+    }
+}
+/**
+ * Measures with the font tables of `fonts`: the family's own table, a related family's, or a
+ * built-in one (DESIGN-FONTS §3).
+ *
+ * @remarks
+ * A table keeps `usWinAscent`/`usWinDescent` only, so a family that sets `USE_TYPO_METRICS` and has
+ * typo metrics that differ from them measures taller than Excel draws it. Aptos Narrow, the default
+ * chart font, has no table: it is measured with Calibri's, whose width differs by up to 8% per
+ * string and whose line height (1.2207 em) is Aptos Narrow's.
+ */
+export declare function createTableMeasurer(fonts?: IFontCollection): TextMeasurer;
+//# sourceMappingURL=TextMeasurer.d.ts.map

package/types/src/chart/layout/_HitGeometry.d.ts

@@ -0,0 +1,50 @@
+import { Bounds, Point } from '@sheetxl/utils';
+/**
+ * Geometry for hit testing a layout: everything in px, as the layout speaks.
+ */
+/** How near a line a point may be and still hit it, in px. */
+export declare const LINE_TOLERANCE = 3;
+/** The least a point's box is across, so a marker-less point can be pressed, in px. */
+export declare const MIN_POINT_SIZE = 6;
+export declare const contains: (bounds: Bounds | null | undefined, point: Point) => boolean;
+/** `bounds` grown by `by` on every side. */
+export declare const grow: (bounds: Bounds, by: number) => Bounds;
+/** The box about `center`, `size` across. */
+export declare const boxAbout: (center: Point, size: number) => Bounds;
+/** The smallest box holding every one of `boxes`; `null` for none. */
+export declare const union: (boxes: readonly (Bounds | null | undefined)[]) => Bounds | null;
+/** The box about a run of points; `null` for none. */
+export declare const boundsOfPoints: (points: readonly (Point | null | undefined)[]) => Bounds | null;
+export declare const distance: (a: Point, b: Point) => number;
+/** The distance from `point` to the segment `from`–`to`. */
+export declare const distanceToSegment: (point: Point, from: Point, to: Point) => number;
+/**
+ * Whether `point` is within `tolerance` of a polyline through `points` (a `null` breaks it), and
+ * the index of the nearer end of the segment it is nearest to.
+ */
+export declare const nearPolyline: (point: Point, points: readonly (Point | null)[], tolerance: number, closed?: boolean) => {
+    index: number;
+    distance: number;
+} | null;
+/** Whether `point` is inside the polygon `polygon` (even-odd). */
+export declare const inPolygon: (point: Point, polygon: readonly Point[]) => boolean;
+/** The point `radius` from `center` at `angle` degrees clockwise from 12 o'clock. */
+export declare const pointAtAngle: (center: Point, radius: number, angle: number) => Point;
+/** An angle in degrees clockwise from 12 o'clock, in `[0, 360)`. */
+export declare const normalizeAngle: (angle: number) => number;
+/** The angle of `point` about `center`, in degrees clockwise from 12 o'clock. */
+export declare const angleOf: (center: Point, point: Point) => number;
+/** A ring sector: between two radii from `center`, from `startAngle` clockwise to `endAngle`. */
+export interface Sector {
+    center: Point;
+    innerRadius: number;
+    outerRadius: number;
+    /** Degrees clockwise from 12 o'clock. */
+    startAngle: number;
+    endAngle: number;
+}
+/** Whether `point` is in the sector. A sector of no span is hit by nothing. */
+export declare const inSector: (point: Point, sector: Sector) => boolean;
+/** The box about the sector. */
+export declare const sectorBounds: (sector: Sector) => Bounds;
+//# sourceMappingURL=_HitGeometry.d.ts.map

package/types/src/chart/layout/_HitTest.d.ts

@@ -0,0 +1,36 @@
+import { Bounds, Point } from '@sheetxl/utils';
+import { ChartLayout } from './ChartLayout';
+/**
+ * Hit testing a layout, painter-free: what element is drawn at a point, and the box an element is
+ * drawn in, both in px from the chart's top-left as the layout speaks. The chrome (title, legend,
+ * axes, labels, analysis lines, plot and chart area) is answered from the layout's own rects; each
+ * group's drawing through its kind's {@link ChartKind.hitTest} and {@link ChartKind.pointBounds}.
+ *
+ * The layout names its parts by ids (a series' `s<idx>`, an axis's `axId`, a group's and a legend
+ * entry's place); the chart supplies what each is called as an element path.
+ */
+/** What the layout's ids are as element paths, from the chart. */
+export interface HitNames {
+    /** The path of a series by its layout id (`series/<key>`). */
+    series: ReadonlyMap<string, string>;
+    /** The path of an axis by its id (`axes/primary/value`). */
+    axes: ReadonlyMap<number, string>;
+    /** The path of a group by its index in the layout's `groups` (`groups/<n>`). */
+    groups: ReadonlyMap<number, string>;
+    /** The path of a legend entry by its index in the layout's legend's `entries` (`legend/entries/<n>`). */
+    legendEntries: ReadonlyMap<number, string>;
+}
+/**
+ * The element drawn at `point`: the topmost of what the layout draws there, as Excel stacks them
+ * (title and legend over everything; then data labels, trendlines and error bars; the series;
+ * the lines under them; axis titles, axes and gridlines; the plot area; the chart area), or `null`
+ * outside the chart.
+ */
+export declare function hitTestLayout(layout: ChartLayout, point: Point, names: HitNames): string | null;
+/**
+ * The box the element at `path` is drawn in, or `null` where the layout draws nothing for it (a
+ * hidden part, a data table, a point not drawn). The chart area's is the whole chart's; the plot
+ * area's its outer box; an axis's its band of line and labels; a series' its points' together.
+ */
+export declare function elementBoundsOf(layout: ChartLayout, path: string, names: HitNames): Bounds | null;
+//# sourceMappingURL=_HitTest.d.ts.map

package/types/src/chart/layout/_Layout.d.ts

@@ -0,0 +1,25 @@
+import { ChartLayout } from './ChartLayout';
+import { TextMeasurer } from './TextMeasurer';
+import { ResolvedChart } from '../resolve/_ResolvedChart';
+/**
+ * Lays a resolved chart out at `size` px (unzoomed), measuring its text with `measurer`.
+ *
+ * @remarks
+ * Builds columns and horizontal bars (clustered, stacked and 100% stacked), lines and areas
+ * (standard, stacked and 100% stacked) on category axes, scatters on two value axes, and
+ * pies and doughnuts, with their axes and axis titles, title, legend, and the data labels of bars,
+ * lines, areas, scatters, pies and doughnuts. Category labels wrap, turn and are skipped as Excel
+ * fits them, and multi-level categories take a band per level with dividers between their groups;
+ * a date axis has a slot per day, month or year and labels its major ticks; a value axis may be
+ * logarithmic. Other groups are left out of the layout. Manual layouts are not built yet.
+ */
+/**
+ * The groups the layout lays out, in the chart's order: those with a registered kind that draws
+ * them. `ChartLayout.groups` has one entry per group here.
+ */
+export declare function drawnGroups(chart: ResolvedChart): ResolvedChart.Group[];
+export declare function layoutChart(chart: ResolvedChart, measurer: TextMeasurer, size: {
+    width: number;
+    height: number;
+}): ChartLayout;
+//# sourceMappingURL=_Layout.d.ts.map

package/types/src/chart/layout/_LayoutUtils.d.ts

@@ -0,0 +1,97 @@
+import { Bounds } from '@sheetxl/utils';
+import { IStroke } from '../../fill/IStroke';
+import { IText } from '../../text/IText';
+import { ChartLayout } from './ChartLayout';
+import { ResolvedChart } from '../resolve/_ResolvedChart';
+import { AxisLimits } from '../math/UnitCalcs';
+import { TrendlineTextRun } from '../math/Trendlines';
+/**
+ * What the layout and the kinds share: the frame's units and the conversions to px, and the small
+ * questions every kind asks of an axis or a group.
+ *
+ * @remarks
+ * Lengths are points until the end, where they become px. Element positions are relative to a
+ * frame inset {@link FRAME_INSET} from the chart on every side: COM reports them in it, the title
+ * centers in it, and the margins are symmetric about it, at every chart size and border width
+ * probed (DESIGN-CHART §4, `probe-chart-layout.ps1`, Excel 16.0, 2026-10-16).
+ */
+export declare const FRAME_INSET = 4;
+export declare const PX_PER_PT: number;
+/** How far a value axis's end labels may reach past the plot area's outer rect. */
+export declare const LABEL_OVERHANG = 6;
+/**
+ * The band axis labels take beside the plot: the widest label (vertical value axis) or one line
+ * (horizontal axis) plus `perLine` lines, less 4.5 pt. Fit on Aptos Narrow from 6 to 28 pt to
+ * 0.012 pt; Calibri and Arial at 18 pt fall within 0.15 pt and 0.54 pt. A scatter's x axis takes the
+ * horizontal band too (`probe-chart-area-scatter.ps1` S0).
+ */
+export declare const VALUE_LABEL_BAND: {
+    perLine: number;
+    offset: number;
+};
+export declare const CATEGORY_LABEL_BAND: {
+    perLine: number;
+    offset: number;
+};
+/**
+ * How far a data label keeps from what it labels (D01-D36): 3 pt from a bar's end or base, inside or
+ * out; from a line's or a scatter's point, 3 pt from its marker's edge, a marker of the series' size
+ * (5 pt where none is drawn) whether or not one is drawn, at 9 and 14 pt.
+ */
+export declare const LABEL_GAP = 3;
+/** Where labels are drawn: their near edge this far from the axis, by font size. From the exported pictures, to ±0.75 pt. */
+export declare const valueLabelGap: (size: number) => number;
+export declare const categoryLabelGap: (size: number) => number;
+export declare const px: (pt: number) => number;
+/** A frame coordinate to px from the chart's top-left. */
+export declare const at: (pt: number) => number;
+export declare const rectPx: (x: number, y: number, width: number, height: number) => Bounds;
+/** A resolved font as the run a painter draws, its size in px. */
+export declare const fontPx: (font: ResolvedChart.Font) => IText.RunPropertiesJSON;
+/** A resolved line as a painter draws it, its width in px. */
+export declare const strokePx: (stroke: ResolvedChart.Stroke | null) => IStroke.JSON | null;
+export declare const markerPx: (marker: ResolvedChart.Marker | null) => ChartLayout.MarkerLayout | null;
+/** A rect in the frame, pt. */
+export interface Box {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** A value axis's scale: its limits, and the ticks and labels along it. */
+export interface ValueScale extends AxisLimits {
+    ticks: number[];
+    labels: string[];
+    /** A log axis's base. */
+    logBase?: number;
+    /** What the axis's label band is as wide as, when more than its labels. */
+    measured?: string[];
+}
+/** A slice as its label is placed about it, in pt: its middle in radians clockwise from 12 o'clock, and what it is drawn around. */
+export interface PieSlice {
+    middle: number;
+    center: {
+        x: number;
+        y: number;
+    };
+    innerRadius: number;
+    outerRadius: number;
+}
+/** A value's share of the way up a scale, `null` where a log scale has no place for it. */
+export declare const shareOf: (scale: ValueScale, value: number) => number | null;
+export declare const isStacked: (group: ResolvedChart.Group) => boolean;
+/** An axis along the bottom or top of the plot. */
+export declare const isHorizontal: (axis: ResolvedChart.Axis) => boolean;
+export declare const hasLabels: (axis: ResolvedChart.Axis) => boolean;
+export declare const POSITIONS: Readonly<Record<ResolvedChart.Axis['position'], ChartLayout.AxisPosition>>;
+/** A group's horizontal axis and vertical axis: a category and a value axis, or a scatter's two value axes. */
+export declare const pairOf: (group: ResolvedChart.Group, axes: ResolvedChart.Axis[]) => {
+    x: ResolvedChart.Axis;
+    y: ResolvedChart.Axis;
+} | null;
+/**
+ * A line of runs wrapped between words to `room`: each word kept whole, a word wider than the room
+ * on a line of its own, and the space a line breaks at dropped.
+ */
+export declare const wrapRuns: (runs: readonly TrendlineTextRun[], room: number, widthOf: (runs: readonly TrendlineTextRun[]) => number) => TrendlineTextRun[][];
+//# sourceMappingURL=_LayoutUtils.d.ts.map

package/types/src/chart/math/BoxStats.d.ts

@@ -0,0 +1,35 @@
+/**
+ * The statistics a box and whisker draws for one set of values, as Excel computes them (measured
+ * 2026-10-22, `probe-chart-2016-types.ps1` B01-B13 and `probe-chart-2016-types-reopen.ps1` B05-B07;
+ * DESIGN-CHART §4.17): quartiles by Excel's exclusive (`QUARTILE.EXC`) or inclusive
+ * (`QUARTILE.INC`) method, the median the same either way; whiskers to the furthest values within
+ * 1.5 interquartile ranges of the box, and the values beyond them outliers (B09: 60 beyond a box of
+ * 15..25).
+ */
+export type QuartileMethod = 'inclusive' | 'exclusive';
+export interface BoxStats {
+    count: number;
+    min: number;
+    max: number;
+    q1: number;
+    median: number;
+    q3: number;
+    mean: number;
+    /** The whiskers' ends: the furthest values within the fences. */
+    whiskerLow: number;
+    whiskerHigh: number;
+    /** The values beyond the fences, in their order. */
+    outliers: number[];
+    /** The values within the fences, in their order. */
+    inliers: number[];
+}
+/**
+ * The `p`th quantile of sorted values: at position `p·(n + 1)` from 1 (exclusive) or
+ * `1 + p·(n − 1)` (inclusive), interpolated between the values either side, and held to the ends
+ * where the position falls outside them (Excel's `QUARTILE.EXC` answers an error there; the chart
+ * draws the end value, by belief).
+ */
+export declare function quantile(sorted: readonly number[], p: number, method: QuartileMethod): number;
+/** The statistics of `values` (blanks left out); `null` where there are none. */
+export declare function boxStats(values: readonly (number | null)[], method: QuartileMethod): BoxStats | null;
+//# sourceMappingURL=BoxStats.d.ts.map

package/types/src/chart/math/DateUnitCalcs.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Excel's date axis (measured 2026-10-17, `probe-chart-dates.ps1` and `probe-chart-dates-units.ps1`,
+ * DESIGN-CHART §4.2). Dates are serials, in the 1900 or 1904 system; lengths are points.
+ *
+ * @remarks
+ * A date axis has one slot per base unit (a day, a month or a year) from its first date, snapped to
+ * the start of its unit, to its last; each point is drawn in the slot of its date, so a gap in the
+ * dates is a gap on the axis and two points of one date share a slot. Labels are drawn on the
+ * major ticks only, from the first slot on, in the axis's number format.
+ */
+export type TimeUnit = 'days' | 'months' | 'years';
+/** A length of time: `count` of `unit`. */
+export interface DateUnit {
+    count: number;
+    unit: TimeUnit;
+}
+/**
+ * `serial` moved back to the start of its `unit`: its day, the first of its month, or January 1st
+ * of its year. The time of day is dropped.
+ */
+export declare function toBaseUnit(serial: number, unit?: TimeUnit, date1904?: boolean): number;
+/** `serial` moved on by `count` of `unit`; months and years keep the day of the month where they can. */
+export declare function addUnits(serial: number, count: number, unit: TimeUnit, date1904?: boolean): number;
+/** How many whole `unit`s `to` is after `from`, counting the units they fall in: Jan 31 to Feb 1 is one month. */
+export declare function unitsBetween(from: number, to: number, unit: TimeUnit, date1904?: boolean): number;
+/**
+ * The base unit Excel chooses for `serials`: the largest unit no two different dates share. Two
+ * dates in one month make it days; two in one year, months; else years (measured: month starts
+ * and mid-month dates are months, dates a few months apart are months, a repeated date leaves it
+ * days).
+ */
+export declare function baseUnitOf(serials: readonly number[], date1904?: boolean): TimeUnit;
+/** A date axis's slots: its bounds and base unit. */
+export interface DateSlots {
+    /** The first slot's date: the first date snapped to the base unit, or the stated minimum. */
+    min: number;
+    /** The last slot's date. */
+    max: number;
+    baseUnit: TimeUnit;
+    /** How many base units the axis holds, both ends included. */
+    count: number;
+}
+/** The slots of a date axis over `serials`; stated bounds and base unit win. */
+export declare function dateSlots(serials: readonly number[], options?: {
+    min?: number;
+    max?: number;
+    baseUnit?: TimeUnit;
+    date1904?: boolean;
+}): DateSlots;
+/** The slot `serial` falls in, or `null` outside the axis. */
+export declare function slotOf(slots: DateSlots, serial: number, date1904?: boolean): number | null;
+/**
+ * Where `serial` falls along the slots, as a slot and the share of its base unit past the slot's
+ * date: a trendline's x on a date axis. Not bounded to the slots.
+ */
+export declare function slotAt(slots: DateSlots, serial: number, date1904?: boolean): number;
+/** The major ticks from the first slot on, every `major`: each its date and the slot it is in. */
+export declare function dateTicks(slots: DateSlots, major: DateUnit, date1904?: boolean): {
+    serial: number;
+    slot: number;
+}[];
+/**
+ * Along the bottom or top, each label of a date axis needs this many times its size of the axis,
+ * whatever its text (the same widths for `m/d/yyyy` and `mmm-yy`): all 58 moves between majors of
+ * one unit in 17 sweeps, at 9 and 14 pt, fall between 1.46443 and 1.46485, the axis being the
+ * width the plot area's labels share.
+ */
+export declare const DATE_LABEL_SPAN = 1.4648;
+/**
+ * The major unit Excel chooses for a date axis `length` long whose labels are `size` pt: the
+ * first candidate whose labels each get {@link DATE_LABEL_SPAN} × `size` of the axis, a weekly
+ * major on a daily axis only while the axis is long enough for it ({@link WEEKLY}). The last
+ * candidate when none fits.
+ *
+ * @remarks
+ * Measured along the bottom; up a side (horizontal bars) the same rule is believed. Below about
+ * 80 pt Excel moves on to multiples of 7 days on any daily axis; that is not followed.
+ */
+export declare function fitDateMajor(slots: DateSlots, length: number, size: number, date1904?: boolean): DateUnit;
+//# sourceMappingURL=DateUnitCalcs.d.ts.map

package/types/src/chart/math/DisplayUnits.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Excel's built-in axis display units. `multi` is the divisor applied to a value before it is
+ * formatted for an axis label: 1,500,000 shows as 1.5 under `millions`.
+ */
+export declare const builtInDisplayUnits: {
+    readonly none: {
+        readonly description: "None";
+        readonly multi: 1;
+    };
+    readonly hundreds: {
+        readonly description: "Hundreds";
+        readonly multi: 100;
+    };
+    readonly thousands: {
+        readonly description: "Thousands";
+        readonly multi: 1000;
+    };
+    readonly tenThousands: {
+        readonly description: "10000";
+        readonly multi: 10000;
+    };
+    readonly hundredThousands: {
+        readonly description: "100000";
+        readonly multi: 100000;
+    };
+    readonly millions: {
+        readonly description: "Millions";
+        readonly multi: 1000000;
+    };
+    readonly tenMillions: {
+        readonly description: "10000000";
+        readonly multi: 10000000;
+    };
+    readonly hundredMillions: {
+        readonly description: "100000000";
+        readonly multi: 100000000;
+    };
+    readonly billions: {
+        readonly description: "Billions";
+        readonly multi: 1000000000;
+    };
+    readonly trillions: {
+        readonly description: "Trillions";
+        readonly multi: 1000000000000;
+    };
+};
+export type BuiltInDisplayUnit = keyof typeof builtInDisplayUnits;
+/**
+ * `value` scaled for display by a built-in unit's name (`c:builtInUnit`) or a divisor
+ * (`c:custUnit`).
+ */
+export declare function adjustForDisplayUnit(value: number, displayUnit?: BuiltInDisplayUnit | string | number | null): number;
+//# sourceMappingURL=DisplayUnits.d.ts.map

package/types/src/chart/math/Histogram.d.ts

@@ -0,0 +1,48 @@
+/**
+ * How a histogram bins its values, as Excel does (measured 2026-10-22,
+ * `probe-chart-2016-types.ps1` H01-H16 and `probe-chart-2016-types-reopen.ps1` H04-H07, H13;
+ * DESIGN-CHART §4.16).
+ *
+ * - The automatic bin width is Scott's rule, 3.5·s/∛n for the sample standard deviation s, rounded
+ *   to two significant digits (27.32 → 27, 14.75 → 15, 18.88 → 19, 0.4001 → 0.40, 81.32 → 81);
+ *   {@link REPEATED_VALUE_WIDTH} when every value is the same (H15: one value, [7, 12]).
+ * - A stated bin count divides the values' range into that many bins (H05: 81/5 = 16.2).
+ * - The bins start at the minimum, or at the underflow bound where one is stated, and run up by
+ *   the width until they reach the maximum, or the overflow bound, where the last bin is cut
+ *   (H06: (30, 57], (57, 60]; H07: [12, 39], (39, 60]). An underflow bin takes the values at or
+ *   below its bound, an overflow bin those above (`intervalClosed r`), or below and at or above
+ *   (`l`).
+ * - Closed on the right, the first bin takes its lower bound too, `[12, 39]`, the others `(39, 66]`;
+ *   closed on the left, every bin is `[30, 40)` (H13), and a value at the maximum has a bin of its own.
+ */
+/** The bin width when the values have no spread: belief, from one value repeated (H15). */
+export declare const REPEATED_VALUE_WIDTH = 5;
+export interface HistogramOptions {
+    /** Which end of a bin takes a value on its bound. */
+    intervalClosed: 'l' | 'r';
+    binSize?: number;
+    binCount?: number;
+    /** Values at or below (closed right) or below (closed left) this go in a bin of their own. */
+    underflow?: number;
+    /** Values above (closed right) or at or above (closed left) this go in a bin of their own. */
+    overflow?: number;
+}
+export interface HistogramBin {
+    kind: 'underflow' | 'bin' | 'overflow';
+    /** The bin's lower bound; `null` for an underflow bin. */
+    from: number | null;
+    /** The bin's upper bound; `null` for an overflow bin. */
+    to: number | null;
+    /** The indexes of the values in the bin, in their order. */
+    points: number[];
+}
+/** Scott's bin width for `values`, rounded as Excel rounds it. */
+export declare function automaticBinWidth(values: number[]): number;
+/** The bins of `values` (a blank, `null`, is in none), each with the values that fall in it. */
+export declare function histogramBins(values: readonly (number | null)[], options: HistogramOptions): HistogramBin[];
+/**
+ * A bin's label: `[12, 39]` for the first bin closed on the right and `(39, 66]` for the next,
+ * `[30, 40)` closed on the left; `≤ 30` or `< 30` for an underflow bin, `> 60` or `≥ 60` for an overflow.
+ */
+export declare function histogramBinLabel(bins: readonly HistogramBin[], index: number, intervalClosed: 'l' | 'r', format: (value: number) => string): string;
+//# sourceMappingURL=Histogram.d.ts.map

package/types/src/chart/math/OrdUnitCalcs.d.ts

@@ -0,0 +1,166 @@
+import { TextMeasurer } from '../layout/TextMeasurer';
+/**
+ * Excel's fit of category axis labels: as they are, wrapped, turned to 45 and then 90 degrees, and
+ * then only every nth one shown (measured 2026-10-17, `probe-chart-categories.ps1`, DESIGN-CHART
+ * §4.1). Lengths are points.
+ *
+ * @remarks
+ * Rescued from exhibit-master's `OrdUnitCalcs.js` and typed over {@link TextMeasurer}: the same
+ * order of trials, with the spacing each angle needs taken from {@link calcDistanceNeededAtAxis}
+ * of the labels' own width, and the label interval from how many labels the axis holds.
+ */
+/** What is drawn for a label cut short. */
+export declare const LABEL_ELLIPSIS = "\u2026";
+/** How to fit one axis's labels. */
+export interface CategoryFitOptions {
+    /**
+     * The length the categories share. Along the bottom or top: the plot area's outer width less the
+     * value axes' label bands, before any label reaches past an end. Up a side: the inside height.
+     */
+    length: number;
+    /**
+     * The axis runs along the bottom or top. Its labels may wrap, turn and be cut. A side axis's
+     * labels stay level and wrap to {@link maxWidth}.
+     */
+    horizontal: boolean;
+    /** The stated angle, in degrees counterclockwise; absent when Excel chooses. */
+    rotation?: number;
+    /** The stated interval between labels (`tickLblSkip`); absent when Excel chooses. */
+    skip?: number;
+    /** Along the bottom or top: how far the labels may reach from the axis. */
+    maxDepth?: number;
+    /** Up a side: how wide a line may be. */
+    maxWidth?: number;
+    /** The last category comes first along the axis. */
+    reversed?: boolean;
+    /** The labels are stacked letter over letter (`vert="wordArtVert"`). */
+    vertical?: boolean;
+    /**
+     * The labels are the innermost level of multi-level categories. Excel then turns them straight
+     * to 90 degrees when it chooses, never 45 (measured 2026-10-17, `probe-chart-multilevel.ps1`: every
+     * turn of four sweeps, where 45 degrees would have fit; a stated 45 is kept).
+     */
+    innermost?: boolean;
+}
+/** An axis's labels as fitted. */
+export interface CategoryLabelFit {
+    /** Every `skip`th category has a label, starting with the first. */
+    skip: number;
+    /** In degrees counterclockwise. */
+    rotation: number;
+    /** The labels are stacked: each label's columns joined by `\t`, their letters by `\n`. */
+    vertical?: boolean;
+    /** One per category: the text drawn, its lines joined by `\n`; `null` for a category with no label. */
+    labels: (string | null)[];
+    /**
+     * How far the labels reach away from the axis: their lines' height when level, the extent of the
+     * turned box when turned; up a side, the widest line.
+     */
+    depth: number;
+    /**
+     * How far the labels reach along the axis past the end categories' centers: `start` before the
+     * first category along the axis (its left, or its bottom up a side), `end` after the last.
+     */
+    reach: {
+        start: number;
+        end: number;
+    };
+}
+/** The width of the widest word of `text`. */
+export declare function findLargestWord(text: string, measure: (text: string) => number): number;
+/**
+ * `text` broken into lines no wider than `width`: at its own line breaks, between words, and inside
+ * a word too wide for a line of its own when `breakWords` is set (such a word otherwise keeps its
+ * line).
+ */
+export declare function wrapLabel(text: string, width: number, measure: (text: string) => number, breakWords?: boolean): string[];
+/**
+ * Stacked labels (`vert="wordArtVert"`, measured 2026-10-22, `probe-chart-axes.ps1` V01-V09): each
+ * letter on its own line, {@link STACKED_LETTER_PITCH} lines apart (12.82 pt at 9 pt, fitted there
+ * and held within 0.2 pt at 6, 14 and 18 pt); along the bottom a label taller than half the plot's
+ * outer height breaks into columns of as many letters as fit, {@link STACKED_COLUMN_PITCH} font
+ * sizes apart (from the pictures at 9 and 14 pt), centered on the category. The last label reaches
+ * past its category along the axis by {@link STACKED_REACH} of its own column's height, the
+ * letters' drawn pitch (V01, V02, V06, V07, V09: 0.939 to 0.940 at 9, 14 and 18 pt); the first
+ * reaches nowhere (V02, V06, V09: two columns over the value axis's band, which stays).
+ * Up a side, a label is one column as deep as a letter's pitch, whatever its letters (V03, V04 at
+ * 9 pt: 12.82 pt for "Jan".."Jun" and for "0".."30").
+ */
+export declare const STACKED_LETTER_PITCH: number;
+export declare const STACKED_COLUMN_PITCH = 0.95;
+/**
+ * Fits `texts`, one per category, to an axis.
+ *
+ * @remarks
+ * Along the bottom or top, the interval is the smallest that lets the labels fit. Excel takes it
+ * from how many labels the axis holds at the most compact angle tried (90 degrees when it
+ * chooses), so 12 categories go from every 4th to every 6th label. At that interval the first
+ * angle that fits is taken. Level labels fit when every word is no wider than the labels' share
+ * of the axis, and wrap between words to it. A turned label needs its line's height over the
+ * sine of the angle. A label longer than its room ({@link CategoryFitOptions.maxDepth}, the axis's
+ * length along it, or {@link CategoryFitOptions.maxWidth} up a side) is cut, or at 90 degrees and up
+ * a side wrapped in the lines its category holds and the last cut.
+ */
+export declare function fitCategoryLabels(texts: string[], font: TextMeasurer.Font, measurer: TextMeasurer, options: CategoryFitOptions): CategoryLabelFit;
+/** A run of categories that one label of an outer level of multi-level categories spans. */
+export interface CategoryGroup {
+    first: number;
+    last: number;
+    /** The label; `null` for the blanks before a level's first label, a group with none. */
+    text: string | null;
+}
+/**
+ * The groups of each level of multi-level categories beyond the innermost, the nearest the axis
+ * first. `levels` are by level, the innermost first, each by category with `''` for a blank. A
+ * label starts a group, and a blank continues the one before it; blanks before a level's first
+ * label are a group with no label (measured 2026-10-17, `probe-chart-multilevel.ps1` L21). A group
+ * also ends where a group of a level further out does (believed).
+ */
+export declare function groupCategories(levels: readonly (readonly string[])[], count: number): CategoryGroup[][];
+/** How to fit one outer level of multi-level categories. */
+export interface LevelFitOptions {
+    /** The length the categories share, as for {@link CategoryFitOptions.length}. */
+    length: number;
+    /** How many categories share it. */
+    count: number;
+    /** The axis runs along the bottom or top; up a side, the labels are turned to read up. */
+    horizontal: boolean;
+    /** The stated interval between the innermost labels (`tickLblSkip`). */
+    skip?: number;
+}
+/** One outer level of multi-level categories as fitted. */
+export interface LevelFit {
+    /** Each group, with its label's lines; `null` for a group whose label is not shown. */
+    groups: (CategoryGroup & {
+        lines: string[] | null;
+    })[];
+    /** How far the level's labels reach away from the axis: their lines' height. */
+    depth: number;
+}
+/**
+ * Fits the labels of one outer level of multi-level categories to their groups, a group having its
+ * categories' share of the axis (measured 2026-10-17, `probe-chart-multilevel.ps1`):
+ * - Along the bottom, each label wraps between words to its group's share, its lines centered,
+ *   when every word of the level fits its group; else every label of the level wraps to
+ *   {@link OVERRUN_WRAP} of the axis and may overrun its group (the long outer sweep).
+ * - Up a side, the labels are turned to read up and wrap to their group's share, inside words too
+ *   (L16, the bar height sweep).
+ * - A stated interval shows a group's label only where its first category's label is shown (L27,
+ *   L38-L41); Excel's own interval leaves every outer label shown (L4).
+ */
+export declare function fitCategoryLevel(groups: readonly CategoryGroup[], font: TextMeasurer.Font, measurer: TextMeasurer, options: LevelFitOptions): LevelFit;
+/** How to fit a date axis's labels. */
+export interface DateFitOptions extends Omit<CategoryFitOptions, 'skip'> {
+    /** A wide date in the axis's format (December 13th, 2000): what Excel measures to decide whether labels stay level. */
+    sample: string;
+}
+/**
+ * Fits a date axis's labels, `texts` one per slot and `null` for a slot with no major tick
+ * (measured 2026-10-17, `probe-chart-dates.ps1`), by the room the labels have: level
+ * when each has room for {@link DATE_LEVEL}, at 45 degrees when two ticks are √2 × {@link DATE_LABEL_SPAN}
+ * × the size apart, else at 90 degrees, which needs the span the major unit is fit to (every move between
+ * 45 and 90 degrees in the sweeps within 0.2 pt). A level label stays on one line (believed). Up a
+ * side the labels stay level.
+ */
+export declare function fitDateLabels(texts: readonly (string | null)[], font: TextMeasurer.Font, measurer: TextMeasurer, options: DateFitOptions): CategoryLabelFit;
+//# sourceMappingURL=OrdUnitCalcs.d.ts.map