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

package/types/src/chart/resolve/_ResolvedChart.d.ts

@@ -0,0 +1,447 @@
+import { IFill } from '../../fill/IFill';
+import { IStroke } from '../../fill/IStroke';
+import { ChartModel } from '../model/ChartModel';
+import { HistogramBin } from '../math/Histogram';
+import { BoxStats, QuartileMethod } from '../math/BoxStats';
+import { TrendlineFit, TrendlineTextRun, TrendlineType } from '../math/Trendlines';
+/**
+ * A chart with every property concrete: what it states, else its style's, else Excel's default.
+ * Every color is concrete CSS (`#RRGGBB` or `rgba()`, `PaintUtils.toConcreteCSS`), in the fills and
+ * lines the model states: a gradient keeps its stops and a pattern its two colors. Lengths and font
+ * sizes are points, and labels are text.
+ *
+ * @remarks
+ * The input of layout. Values come from the model's caches.
+ */
+export interface ResolvedChart {
+    /** The chart's type, by Office Scripts' names: what `IChart.getChartType` answers. */
+    chartType: string;
+    /** A 2016 chart (`cx:chartSpace`): its chrome is that style's, not a classic chart's. */
+    chartEx?: boolean;
+    /** The chart's own text font: what text with no font of its own is drawn in. */
+    font: ResolvedChart.Font;
+    /**
+     * `fill` is `undefined` where the chart states none: it is drawn in the background of where it is
+     * drawn. `cornerRadius` in points: 0 for square corners.
+     */
+    chartArea: {
+        fill: IFill.JSON | null | undefined;
+        border: ResolvedChart.Stroke | null;
+        cornerRadius: number;
+    };
+    title: ResolvedChart.Text | null;
+    plotArea: {
+        fill: IFill.JSON | null;
+        border: ResolvedChart.Stroke | null;
+    };
+    /** In the chart's order. */
+    axes: ResolvedChart.Axis[];
+    /** In the chart's order. */
+    groups: ResolvedChart.Group[];
+    legend: ResolvedChart.Legend | null;
+    /** Dates are serials of the 1904 system. */
+    date1904: boolean;
+    /** Whether a line is drawn across a blank point rather than broken at it (`dispBlanksAs span`). */
+    spanBlanks: boolean;
+}
+export declare namespace ResolvedChart {
+    interface Font {
+        family: string;
+        /** In pt. */
+        size: number;
+        bold: boolean;
+        italic: boolean;
+        /** What the text is filled with: a solid color, or a gradient. */
+        color: IFill.JSON;
+    }
+    /** A line as the model states it, with its fill concrete and its width (in pt) stated. */
+    type Stroke = IStroke.JSON & {
+        fill: IFill.JSON;
+        width: number;
+    };
+    interface Text {
+        text: string;
+        font: Font;
+        fill: IFill.JSON | null;
+        border: Stroke | null;
+        overlay: boolean;
+        /** The text's angle in degrees counterclockwise: 90 reads up, as an axis title up a side does. */
+        rotation?: number;
+    }
+    /** Where a data label sits by its point: DrawingML's `dLblPos`. */
+    type LabelPosition = 'bestFit' | 'b' | 'ctr' | 'inBase' | 'inEnd' | 'l' | 'outEnd' | 'r' | 't';
+    /** The label of one point. */
+    interface DataLabel {
+        /** Its lines joined by `
+    `. */
+        text: string;
+        position: LabelPosition;
+        font: Font;
+        fill: IFill.JSON | null;
+        border: Stroke | null;
+    }
+    interface Axis {
+        id: number;
+        crossAx: number;
+        type: ChartModel.AxisType;
+        position: 'b' | 'l' | 'r' | 't';
+        deleted: boolean;
+        line: Stroke | null;
+        majorGridlines: Stroke | null;
+        minorGridlines: Stroke | null;
+        majorTickMark: ChartModel.TickMark;
+        minorTickMark: ChartModel.TickMark;
+        tickLblPos: 'high' | 'low' | 'nextTo' | 'none';
+        labelFont: Font;
+        /** The labels' stated angle, in degrees counterclockwise; absent when Excel chooses. */
+        labelRotation?: number;
+        /** A category axis: the stated interval between labels (`tickLblSkip`); absent when Excel chooses. */
+        labelSkip?: number;
+        /**
+         * A category axis over multi-level categories draws each level (`noMultiLvlLbl` off), rather
+         * than one label of all of a category's levels.
+         */
+        multiLevel: boolean;
+        /** The format the labels are written in: the axis's own, or its data's when linked to source. */
+        formatCode: string;
+        orientation: 'minMax' | 'maxMin';
+        /** Stated bounds and units; absent ones are automatic. */
+        min?: number;
+        max?: number;
+        majorUnit?: number;
+        minorUnit?: number;
+        logBase?: number;
+        /** A date axis: the stated unit of its slots, and the stated units of its major and minor ticks. */
+        baseTimeUnit?: ChartModel.TimeUnit;
+        majorTimeUnit?: ChartModel.TimeUnit;
+        minorTimeUnit?: ChartModel.TimeUnit;
+        crosses: 'autoZero' | 'max' | 'min';
+        crossesAt?: number;
+        /** A value axis: whether the axis crossing it lays its categories out between ticks or on them. */
+        crossBetween: 'between' | 'midCat';
+        /** A built-in unit's name or a divisor. */
+        displayUnit?: string | number;
+        /** The display unit's label, shown beside the axis; `null` when the values are not shown in a unit or it is hidden. */
+        displayUnitLabel: Text | null;
+        /** A category axis's `lblOffset`: the labels' distance from the axis as a percentage of the default, 100. */
+        labelOffset: number;
+        /** The labels are stacked letter over letter (`a:bodyPr vert="wordArtVert"`). */
+        labelVertical: boolean;
+        title: Text | null;
+    }
+    interface Marker {
+        symbol: 'circle' | 'square' | 'diamond' | 'triangle' | 'x' | 'star' | 'plus' | 'dot' | 'dash';
+        /** In pt. */
+        size: number;
+        fill: IFill.JSON | null;
+        stroke: Stroke | null;
+    }
+    interface Series {
+        /**
+         * `s` and the key the chart names the series by: its `idx`, or `#` and its place among the
+         * chart's series where it states none (a 2016 chart's).
+         */
+        id: string;
+        idx: number;
+        order: number;
+        name: string;
+        /** By point; `null` is blank. */
+        values: (number | null)[];
+        /** Scatter groups: the x of each point, `1..n` when the series states none. */
+        xValues?: (number | null)[];
+        /** Bubble groups: each point's bubble size; `null` is blank. */
+        bubbleSizes?: (number | null)[];
+        /** By point, as text: the innermost level of multi-level categories. */
+        categories: string[];
+        /**
+         * Multi-level categories: by level, the innermost first, each by point with `''` for a blank (a
+         * blank in an outer level continues the group before it). Absent for categories of one level.
+         */
+        categoryLevels?: string[][];
+        /** By point, as numbers, where the categories are numbers (dates): what a date axis places them by. */
+        categoryValues?: (number | null)[];
+        /** The values' format: the cache's. */
+        formatCode: string;
+        fill: IFill.JSON | null;
+        stroke: Stroke | null;
+        marker: Marker | null;
+        smooth: boolean;
+        /**
+         * Pie, doughnut, of-pie and waterfall groups: how each point is drawn, by point; an of-pie's has
+         * one more, its slice for the points of the second plot (Excel's "Other").
+         */
+        points?: PointStyle[];
+        /** By point, the label drawn by it; `null` for a point without one. Absent when no point has one. */
+        labels?: (DataLabel | null)[];
+        /** The marker's size in pt, stated or Excel's 5, whether or not a marker is drawn: a label keeps clear of it. */
+        markerSize: number;
+        /** The series' trendlines, in the order it lists them. Absent when it has none. */
+        trendlines?: Trendline[];
+        /** The series' error bars, in the order it lists them. Absent when it has none. */
+        errorBars?: ErrorBars[];
+        /** Histogram groups: the values as read, which the group's bins index, before they were counted into `values`. */
+        raw?: (number | null)[];
+        /** Box and whisker groups: by category, the statistics of the series' values there; `null` for a category with none. */
+        boxes?: (BoxStats | null)[];
+        /** Box and whisker groups: what of each box is drawn, and the line it is drawn with. */
+        box?: BoxOptions;
+    }
+    /** How a box and whisker series draws its boxes (DESIGN-CHART §4.17). */
+    interface BoxOptions {
+        quartileMethod: QuartileMethod;
+        /** An x at each box's mean. */
+        meanMarker: boolean;
+        /** A line from each box's mean to the next's. */
+        meanLine: boolean;
+        /** A dot at each value beyond the whiskers. */
+        outliers: boolean;
+        /** A dot at each value within the whiskers. */
+        innerPoints: boolean;
+        /** The box's outline, its median, its whiskers and its marks: the fill's darker shade. */
+        line: Stroke;
+    }
+    /** A series' error bars: a bar about each point, of an amount below and above. */
+    interface ErrorBars {
+        /** Which of the points' values the bars are of: `y`, along the value axis, or a scatter's `x`. */
+        direction: 'x' | 'y';
+        /** What the bars are about: each point's value, or (standard deviations) the series' mean. */
+        about: 'point' | number;
+        /** By point, how far below and above the bar runs; `null` for a point with no bar. */
+        amounts: ({
+            minus: number;
+            plus: number;
+        } | null)[];
+        /** The bar's far ends are capped: an end of no amount is not. */
+        cap: boolean;
+        stroke: Stroke | null;
+    }
+    /** A trendline of a series, fitted to the series' points. */
+    interface Trendline {
+        /** Its entry in the legend. */
+        name: string;
+        type: TrendlineType;
+        /** The fit; `null` for a moving average, or where the points allow none (nothing is drawn). */
+        fit: TrendlineFit | null;
+        /** A moving average's points, in the series' x. */
+        average?: {
+            x: number;
+            y: number;
+        }[];
+        /**
+         * The x the line runs over: the series' first and last point's, `backward` before and
+         * `forward` past them. On a category axis x is the category's number, from 1.
+         */
+        from: number;
+        to: number;
+        /** How far past the last point it runs: on a category axis, the categories it adds. */
+        forward: number;
+        stroke: Stroke | null;
+        label: TrendlineLabel | null;
+    }
+    /** A trendline's label: its equation and R², a line each. */
+    interface TrendlineLabel {
+        /** Each line's runs, an exponent raised. */
+        lines: TrendlineTextRun[][];
+        /**
+         * Where it was moved by hand (`c:manualLayout`): a fraction of the chart's width and height, by
+         * which it is moved from its own place (`factor`), or its position from the chart's top left
+         * (`edge`). Absent where it sits in its own place.
+         */
+        moved?: {
+            x: number;
+            y: number;
+            xEdge: boolean;
+            yEdge: boolean;
+        };
+        font: Font;
+        fill: IFill.JSON | null;
+        border: Stroke | null;
+    }
+    /** One point of a pie, doughnut or of-pie. */
+    interface PointStyle {
+        fill: IFill.JSON | null;
+        stroke: Stroke | null;
+        /** How far the slice is pulled out, as a percentage of the radius. */
+        explosion: number;
+        /** A waterfall's point that is a total: its bar runs from zero to its value, which the steps after it start from. */
+        total?: boolean;
+    }
+    interface Group {
+        type: ChartModel.GroupType;
+        /** A custom group's kind and options, as the model states them. */
+        custom?: ChartModel.CustomGroup;
+        barDir: 'bar' | 'col';
+        grouping: 'clustered' | 'stacked' | 'percentStacked' | 'standard';
+        /** Percent of a bar's width. */
+        gapWidth: number;
+        /** -100..100. */
+        overlap: number;
+        varyColors: boolean;
+        /** Pie and doughnut: where the first slice starts, in degrees clockwise from 12 o'clock. */
+        firstSliceAng: number;
+        /** Doughnut: the hole, as a percentage of the radius. */
+        holeSize: number;
+        axIds: number[];
+        /** In plot order. */
+        series: Series[];
+        /** Line and stock groups: a bar in each category from the first series' value to the last's. */
+        upDownBars?: UpDownBars;
+        /** Line and stock groups: a line in each category from its lowest value to its highest. */
+        hiLowLines?: Stroke | null;
+        /** Line, area and stock groups: a line from each category's values to the category axis. */
+        dropLines?: Stroke | null;
+        /** Stacked bar groups: a line joining each series' ends in neighboring categories; an of-pie's lines to its second plot. */
+        seriesLines?: Stroke | null;
+        /** Of-pie groups: the second plot and the points it takes. */
+        ofPie?: OfPie;
+        /** Surface groups: the value bands they are drawn in. */
+        surface?: Surface;
+        /** Radar groups: lines and markers, or filled. */
+        radarStyle?: 'standard' | 'marker' | 'filled';
+        /** Bubble groups: how the bubbles are sized. */
+        bubble?: Bubble;
+        /** Waterfall groups: how steps up, steps down and totals are drawn, and the lines between bars. */
+        waterfall?: Waterfall;
+        /** Sunburst and treemap groups: the colors of the hierarchy's branches and the line between its segments. */
+        hierarchy?: Hierarchy;
+        /** Histogram groups: the bins the values were counted in, and a pareto's line. */
+        histogram?: Histogram;
+        /** Treemap groups: how the top-level categories are labeled, the font their names are in, and a banner's fill. */
+        treemap?: {
+            parentLabels: 'none' | 'banner' | 'overlapping';
+            font: Font;
+            bannerFill: IFill.JSON | null;
+        };
+    }
+    /**
+     * How a histogram's values were counted (DESIGN-CHART §4.16): each series' `values` are its
+     * counts by bin and its `categories` the bins' labels; a pareto's are its sums by category,
+     * largest first, with a line of the running share on an axis of its own.
+     */
+    interface Histogram {
+        /** The first series' bins, each with the indexes of its `raw` values. */
+        bins: HistogramBin[];
+        intervalClosed: 'l' | 'r';
+        /** The values were summed by category (`aggregation`) rather than binned. */
+        byCategory: boolean;
+        /** A pareto's line: the series the chart lists it as, the axis it is drawn against, and its line. */
+        cumulative?: {
+            id: string;
+            name: string;
+            axisId: number;
+            stroke: Stroke | null;
+        };
+    }
+    /**
+     * How a hierarchy (a sunburst) is drawn: each top-level category, a branch, with everything under
+     * it in the branch's fill; every segment outlined in `border`.
+     */
+    interface Hierarchy {
+        branches: {
+            name: string;
+            fill: IFill.JSON | null;
+        }[];
+        border: Stroke | null;
+    }
+    /**
+     * How a waterfall draws its bars: a step up (a positive value), a step down (a negative one) and a
+     * total, each where the series and its points state nothing; the lines from each bar's end to the
+     * next bar, `null` where they are hidden.
+     */
+    interface Waterfall {
+        increase: {
+            fill: IFill.JSON | null;
+            stroke: Stroke | null;
+        };
+        decrease: {
+            fill: IFill.JSON | null;
+            stroke: Stroke | null;
+        };
+        total: {
+            fill: IFill.JSON | null;
+            stroke: Stroke | null;
+        };
+        connectorLines: Stroke | null;
+    }
+    /** How a bubble group sizes its bubbles. */
+    interface Bubble {
+        /** The largest bubble's size, as a percentage of Excel's default: 0 to 300. */
+        scale: number;
+        /** A bubble's size is its area's (`area`) or its width's (`w`). */
+        sizeRepresents: 'area' | 'w';
+        /** A negative size draws a bubble of its size's magnitude; else none. */
+        showNegative: boolean;
+    }
+    /**
+     * A surface's value bands: one between each major tick of its value axis and the next, each drawn in
+     * its own color, or its own line for a wireframe.
+     */
+    interface Surface {
+        wireframe: boolean;
+        /** A 3-D surface, which Excel draws in perspective; drawn flat from above. */
+        flat: boolean;
+        /** The value axis's scale. */
+        min: number;
+        max: number;
+        majorUnit: number;
+        bands: {
+            from: number;
+            to: number;
+            text: string;
+            fill: IFill.JSON | null;
+            stroke: Stroke | null;
+        }[];
+    }
+    /** A pie of pie or bar of pie's second plot. */
+    interface OfPie {
+        of: 'pie' | 'bar';
+        /** How the points of the second plot are chosen, and by what. */
+        splitType: 'auto' | 'cust' | 'percent' | 'pos' | 'val';
+        splitPos?: number;
+        /** `cust`: the indexes of the points in the second plot. */
+        custSplit: number[];
+        /** The second plot's size, as a percentage of the first pie's. */
+        secondSize: number;
+    }
+    /** A line or stock group's up/down bars. */
+    interface UpDownBars {
+        /** Percent of a bar's width. */
+        gapWidth: number;
+        /** Where the last series' value is above the first's. */
+        up: {
+            fill: IFill.JSON | null;
+            stroke: Stroke | null;
+        };
+        /** Where it is not: below or equal. */
+        down: {
+            fill: IFill.JSON | null;
+            stroke: Stroke | null;
+        };
+    }
+    interface LegendEntry {
+        seriesId: string;
+        /** An entry for one point of the series (a pie's slice), rather than for the series. */
+        pointIndex?: number;
+        /** An entry for the series' trendline of this index, rather than for the series. */
+        trendlineIndex?: number;
+        /** An entry for a surface's value band of this index, rather than for a series. */
+        bandIndex?: number;
+        text: string;
+        /** The kind of key the entry shows. */
+        key: 'bar' | 'line';
+        /** The key's colors, where they are not its series' (a waterfall's increase, decrease and total). */
+        swatch?: {
+            fill: IFill.JSON | null;
+            stroke: Stroke | null;
+        };
+    }
+    interface Legend {
+        position: 'b' | 'tr' | 'l' | 'r' | 't';
+        overlay: boolean;
+        font: Font;
+        fill: IFill.JSON | null;
+        border: Stroke | null;
+        entries: LegendEntry[];
+    }
+}
+//# sourceMappingURL=_ResolvedChart.d.ts.map

package/types/src/collections/ISparseGrid.d.ts

@@ -43,8 +43,8 @@ export declare namespace ISparseGrid {
      */
     type RunIteratorResult<T = any> = IteratorResult<ISparseGrid.RunEntry<T>>;
     /**
-     * Run Iterator extends {@link IReadableList.IteratorOptions} but removes support for
-     * processSkip and downcasts reuseResult.
+     * Options for {@link ISparseGrid.getRuns}. Runs always follow the grid's own axis, in order;
+     * there is no reverse or skip.
      */
     interface RunIteratorOptions {
         /**
@@ -65,6 +65,15 @@ export declare namespace ISparseGrid {
          * This is used as a performance optimization for iterators that are reading gaps. (fillEmpty)
          */
         overflowRun?: boolean;
+        /**
+         * Returns the same iterator result from every `next`, with its entry rewritten.
+         *
+         * `true` reuses one result per iterator; an object reuses that object. This avoids an
+         * allocation per run, but a result must be read before the next call to `next`.
+         *
+         * @defaultValue false
+         */
+        reuseResult?: boolean | ISparseGrid.RunIteratorResult<any>;
     }
 }
 //# sourceMappingURL=ISparseGrid.d.ts.map

package/types/src/collections/MixedTypedArrayList.d.ts

@@ -2,8 +2,8 @@ import { IList, IListLike } from './IList';
 /**
  * An immutable run of mixed scalar values in ONE `ArrayBuffer` or `SharedArrayBuffer`.
  *
- * Numbers, booleans and blanks are stored natively; strings and errors as `int32` ids that a
- * {@link MixedTypedArrayList.Codec} resolves. The buffer is the whole list: another thread that
+ * Numbers, booleans and blanks are stored natively; strings, errors and rich values as `int32`
+ * ids that a {@link MixedTypedArrayList.Codec} resolves. The buffer is the whole list: another thread that
  * receives its {@link MixedTypedArrayList.Handle} (and has the same codec) reads it without a copy.
  *
  * @remarks
@@ -150,6 +150,12 @@ export declare namespace MixedTypedArrayList {
         encodeError(value: T): number;
         /** The error for a code. */
         decodeError(code: number): T;
+        /** Whether `value` is a rich value {@link encodeRich} stores. Omitted, none is. */
+        isRich?(value: object): boolean;
+        /** The id of a rich value. */
+        encodeRich?(value: T): number;
+        /** The rich value an id names. */
+        decodeRich?(id: number): T;
     }
     /**
      * What rebuilds a list over its buffer. Passes through `structuredClone` and `postMessage`.