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

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

@@ -0,0 +1,28 @@
+/**
+ * How Excel tiles a treemap (measured 2026-10-22, `probe-chart-2016-types.ps1` T01-T11 and the
+ * 168 pictures of `probe-chart-treemap-sweep.ps1`; DESIGN-CHART §4.18). The children of a node,
+ * largest first, each take a strip of the rect left: a column of the rect's full height as wide
+ * as the child's share, unless the rect is taller than wide and a row of its full width would be no
+ * wider than {@link TREEMAP_ASPECT} times its height, when the child takes that row. The last child
+ * takes what is left.
+ *
+ * @remarks
+ * The rule is not squarified: two near-equal children of a rect 1.12 times taller than wide sit
+ * side by side (T01's Europe, T06), as a squarified layout never would, while children of 50 and
+ * 30 stack in a square (the sweep). Across the sweep's eight pairs the row's aspect at which the
+ * children turn from side by side to stacked lies between 1.587 and 1.639 for every pair: the
+ * golden ratio.
+ */
+export declare const TREEMAP_ASPECT = 1.618;
+export interface TreemapRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/**
+ * The rects of items of `sizes`, in the order given (largest first, as Excel orders them), tiling
+ * `rect`. An item of no positive size takes a rect of no width.
+ */
+export declare function tileTreemap(sizes: readonly number[], rect: TreemapRect): TreemapRect[];
+//# sourceMappingURL=Treemap.d.ts.map

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

@@ -0,0 +1,71 @@
+/**
+ * Excel's trendlines: the fits, their R², the moving average, and the label's equation.
+ *
+ * @remarks
+ * Measured against Excel 16.0 (DESIGN-CHART §4.5, `probe-chart-trendlines.ps1`): every coefficient
+ * of the nine types on a line chart and a scatter, a set intercept, and a sweep of numbers through
+ * the label's General format.
+ */
+export type TrendlineType = 'exp' | 'linear' | 'log' | 'movingAvg' | 'poly' | 'power';
+/** A fitted trendline. */
+export interface TrendlineFit {
+    type: Exclude<TrendlineType, 'movingAvg'>;
+    /**
+     * - `linear` and `poly`: the coefficients from x⁰ up, `[c0, c1, …]`;
+     * - `exp`: `[a, b]` of y = a·e^(b·x);
+     * - `log`: `[a, b]` of y = a·ln(x) + b;
+     * - `power`: `[a, b]` of y = a·x^b.
+     */
+    coefficients: number[];
+    /**
+     * The square of the correlation between the series' y and the fit's, at the series' x: Excel's
+     * R², for every type and a set intercept alike (an exponential's or power's in y, not ln y).
+     */
+    rSquared: number;
+    /** The fit's y at `x`. */
+    at(x: number): number;
+}
+export interface TrendlineOptions {
+    /** A polynomial's order, 2 to 6. */
+    order?: number;
+    /** The y the fit is held to at x = 0 (`linear`, `poly`, `exp`). */
+    intercept?: number;
+}
+/**
+ * The fit of a trendline to the points (x, y): `null` when the points do not allow it, as Excel
+ * offers no such trendline (an exponential over a y ≤ 0, a log or power over an x ≤ 0, fewer points
+ * than the fit has terms).
+ */
+export declare function fitTrendline(type: Exclude<TrendlineType, 'movingAvg'>, xs: readonly number[], ys: readonly number[], options?: TrendlineOptions): TrendlineFit | null;
+/**
+ * A moving average of `period` points: from the period-th point on, the mean of each point and the
+ * ones before it, at that point's x.
+ */
+export declare function movingAverage(xs: readonly number[], ys: readonly number[], period: number): {
+    x: number;
+    y: number;
+}[];
+/**
+ * A number as a trendline's label shows it under General: Excel's General at a width of six
+ * characters, its sign apart.
+ *
+ * @remarks
+ * The magnitude picks the form: a number whose first significant digit fits in six characters is
+ * rounded to the decimals left (5.9952, 18.148, 0.0001), else it is scientific with what fits
+ * (`3E-05`, `1E+06`). A number rounded past six digits becomes scientific too (999999.5 is
+ * `1E+06`). Trailing zeros go (2.1650 is 2.165). Rounding is of the binary value, as Excel's is.
+ */
+export declare function formatTrendlineNumber(value: number, width?: number): string;
+/** A run of a trendline label's text: an exponent is raised. */
+export interface TrendlineTextRun {
+    text: string;
+    superscript?: boolean;
+}
+/**
+ * The equation of a fit as its label shows it, in runs: `y = 1.0881x2 - 3.7976x + 7.1929`, with
+ * the powers raised. `format` writes a coefficient (the label's number format).
+ */
+export declare function trendlineEquation(fit: TrendlineFit, format: (value: number) => string): TrendlineTextRun[];
+/** A fit's R² as its label shows it: `R² = 0.8776`. */
+export declare function trendlineRSquared(fit: TrendlineFit, format: (value: number) => string): string;
+//# sourceMappingURL=Trendlines.d.ts.map

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

@@ -0,0 +1,98 @@
+/**
+ * Excel's automatic axis scales: bounds, major and minor units, and ticks for linear, logarithmic
+ * and percent value axes.
+ *
+ * @remarks
+ * Rescued from exhibit-master and typed. The linear rules are KB 214075's (the 16.667% zero rule,
+ * 5% headroom, the straddling cases), checked by `unitCalcs.test.ts` against values observed in
+ * Excel. Label fitting ({@link fitMajorUnitLinear}) follows the probe in DESIGN-CHART §4.
+ */
+/** `undefined` and `null` both mean "not stated". */
+type Maybe = number | null | undefined;
+/** The scale of one axis. */
+export interface AxisLimits {
+    min: number;
+    max: number;
+    majorUnits: number;
+    minorUnits: number;
+    /** Where a crossing axis set to `autoZero` crosses. */
+    autoZero: number;
+}
+/** The scale of a log axis, with its ticks. */
+export interface LogAxisLimits extends AxisLimits {
+    majorTicks?: number[];
+    minorTicks?: number[];
+    ticks?: number[];
+    labelTicks?: number[];
+}
+/** Excel's major unit for a value range: 1, 2 or 5 times a power of ten. */
+export declare function calcMajorUnitValue(range: number): number;
+export declare function calcMinorUnitValue(majorUnit: number): number;
+/**
+ * The next major unit on Excel's 1, 2, 5 ladder: 50 → 100 → 200 → 500, 0.1 → 0.2 → 0.5.
+ */
+export declare function nextMajorUnit(unit: number): number;
+export declare function buildLogTicks(units: number, explicitUnits: Maybe, minAxisValue: number, maxAxisValue: number): number[];
+export declare function buildMinorLogTicks(unitsMinor: number, unitsMinorExplicit: Maybe, minAxisValue: number, maxAxisValue: number): number[];
+/**
+ * The smallest power of the log base whose ticks fit: a label is `labelDistance` long and the
+ * axis `axisDistance`.
+ */
+export declare function fitMajorUnitLog(limits: LogAxisLimits & {
+    logBase: number;
+    explicitMajorUnits?: Maybe;
+}, labelDistance: number, axisDistance: number, minTicks?: number): number;
+/**
+ * Bounds and units of a log axis. `minIn` and `maxIn` are the data, not their logs.
+ */
+export declare function calcAxisLimitsLog(minIn?: number, maxIn?: number, explicitMin?: Maybe, explicitMax?: Maybe, explicitMinorUnits?: Maybe, explicitMajorUnits?: Maybe, baseUnits?: number, generateTicks?: boolean): LogAxisLimits;
+/**
+ * Bounds and units of a linear value axis over data from `minIn` to `maxIn`.
+ *
+ * @remarks
+ * Excel's rules (KB 214075; Peltier, "How Excel calculates automatic chart axis limits"):
+ * - both ends positive: the axis starts at zero unless the range is under 16.667% of the max;
+ * - 5% of the range is added beyond the data;
+ * - the major unit comes from the padded range ({@link calcMajorUnitValue});
+ * - the bounds snap outward to whole major units.
+ */
+export declare function calcAxisLimitsLinear(minIn: Maybe, maxIn: Maybe, explicitMin?: Maybe, explicitMax?: Maybe, explicitMinorUnits?: Maybe, explicitMajorUnits?: Maybe, isScatterOrBubble?: boolean, headroom?: number, majorHeadroom?: number): AxisLimits;
+/**
+ * The major unit at which the labels of a linear axis fit: the automatic unit, else the next on
+ * Excel's 1, 2, 5 ladder ({@link nextMajorUnit}), until `fits` accepts the ticks.
+ *
+ * @param majorUnit The automatic major unit.
+ * @param boundsAt The axis's bounds at a major unit: they snap to it.
+ * @param fits Whether labels at these tick values fit along the axis.
+ *
+ * @remarks
+ * Measured (DESIGN-CHART §4): at 16 pt the K1 secondary axis goes from 0.1 to 0.2; at 28 pt the
+ * primary goes 50 → 100 → 200 and the secondary 0.1 → 0.2 → 0.5. A unit that leaves two ticks or
+ * fewer is the last one tried.
+ */
+export declare function fitMajorUnitLinear(majorUnit: number, boundsAt: (unit: number) => {
+    min: number;
+    max: number;
+}, fits: (ticks: number[]) => boolean): number;
+/**
+ * Bounds and units of a 100% stacked axis: the data are fractions.
+ */
+export declare function calcAxisLimitsPercent(minIn: number, maxIn: number, explicitMin?: Maybe, explicitMax?: Maybe, explicitMinorUnits?: Maybe, explicitMajorUnits?: Maybe): AxisLimits;
+/** Where an `autoZero` crossing lands: zero, or the end of the scale nearest it. */
+export declare function autoZero(min: number, max: number): number;
+/**
+ * The major ticks from `minAxis` to `maxAxis`, snapped outward to whole units; an explicit bound
+ * is kept as it is and ticks run from it.
+ */
+export declare function buildLinearTicks(explicitMin: Maybe, explicitMax: Maybe, majorUnits: number, minIn?: Maybe, maxIn?: Maybe, minAxis?: Maybe, maxAxis?: Maybe): number[];
+export declare function generateMajorOrdTicks(start: number, end: number, interval?: number): number[];
+export declare function logX(num: number, logBase: number): number;
+/**
+ * How much of an axis a label `width` by `height` takes when rotated by `deg` degrees: the extent
+ * of the rotated box along the axis line through its center.
+ */
+export declare function calcDistanceNeededAtAxis(width: number, height: number, deg: number): number;
+/** How many labels of this size fit in `totalWidth` at a rotation. */
+export declare function calcMaxLabels(totalWidth: number, labelWidth: number, labelHeight: number, labelRotation?: number): number;
+export {};
+//# sourceMappingURL=UnitCalcs.d.ts.map