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

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

@@ -0,0 +1,444 @@
+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;
+    /** `cornerRadius` in points: 0 for square corners. */
+    chartArea: {
+        fill: IFill.JSON | null;
+        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/ArraysGrid.d.ts

@@ -23,7 +23,7 @@ export declare class ArraysGrid<T = any> implements IGrid<T> {
     getCoords(): RangeCoords | null;
     /** {@inheritDoc IGrid.setValues} */
     setValues(_values: Tuple.GridTuple): this;
-    getValues(coords?: RangeCoords): Tuple.BoundedTuples<T> | null;
+    getValues(coords?: RangeCoords): Tuple.Region<T> | null;
     /** {@inheritDoc IGrid.getAxis} */
     getAxis(): RangeAxis;
     /** {@inheritDoc IGrid.delete} */

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

@@ -42,7 +42,7 @@ export interface IGrid<T = any> {
      * * Results `null` if there are no values
      * * If `coords` is not provided then all values will be retrieved.
      */
-    getValues(coords?: RangeCoords): Tuple.BoundedTuples<T> | null;
+    getValues(coords?: RangeCoords): Tuple.Region<T> | null;
     /**
      * Returns an iterator for traversing entries in the IGrid.
      *

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

@@ -12,6 +12,15 @@ export interface ISparseGrid<T = any> extends IGrid<T> {
      * Sparse grids are stored as virtual tuples of [major, minor, value].
      */
     getRuns(options?: ISparseGrid.RunIteratorOptions): ISparseGrid.RunIterableIterator<T>;
+    /**
+     * `true` when the grid reports which cells are read.
+     *
+     * @remarks
+     * A consumer that could answer from a structure derived off the stored runs — an index that
+     * opens no cell — must instead read the cells it stands for, so that the report stays exact.
+     * The calculation sets this on the grid a formula reads while its reads decide circularity.
+     */
+    readonly observesReads?: boolean;
 }
 /**
  * {@inheritDoc ISparseGrid}

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

@@ -55,14 +55,21 @@ export interface ISpatialMap<T = any> extends ISpatialQuery<T> {
      */
     insertNonOverlapping(entry: ISpatialMap.Entry<T>, options?: ISpatialMap.InsertNonOverlappingOptions<T>): this;
     /**
-     * TODO - remove this.
+     * {@link insertNonOverlapping} for several entries, merging once for all of them.
      *
-     * @param entries the entries to manage together
-     * @param uuid A unique identifier for the group.
+     * @param entries The entries to add, applied in order.
+     * @param options Options for adding non overlapping options.
+     *
+     * @remarks
+     * Equivalent to calling {@link insertNonOverlapping} for each entry in turn - a later entry wins
+     * over an earlier one where they overlap - but the merge pass runs once over the entries' union
+     * rather than once per entry. Each merge pass searches the entries' neighborhood, so this is
+     * worth reaching for when the entries are near one another, as the pieces of one region are.
      *
-     * @deprecated Use AnchorMap instead
+     * * As with {@link insertNonOverlapping}, `load` is far cheaper when the entries are known not to
+     *   overlap anything already in the map.
      */
-    insertGroup(entries: ISpatialMap.Entry[], uuid: string): this;
+    insertAllNonOverlapping(entries: readonly ISpatialMap.Entry<T>[], options?: ISpatialMap.InsertNonOverlappingOptions<T>): this;
     /**
      * Returns a set of non overlapping inserts and removes that would represent a copy.
      *
@@ -141,10 +148,6 @@ export declare namespace ISpatialMap {
     interface Entry<T = any> extends RangeCoords {
         value?: T;
         uuid?: string;
-        /**
-         * If the entry is the results of a split or a merge.
-         */
-        lastId?: string;
     }
     /**
      * Optional interface for spatial map values that need custom behavior
@@ -330,13 +333,6 @@ export declare namespace ISpatialMap {
          * Called when a group of ranges are merged together.
          */
         onMerged?(onMerges: ISpatialMap.Entry<T>[]): void;
-        /**
-         * Called when a group is updated.
-         *
-         * @param entries All entries in the group.
-         * @param uuid Any params argument passed a modification option.
-         */
-        onGroupUpdate?(entries: ISpatialMap.Entry<T>[], uuid?: string): void;
         /**
          * Called after structure has been updated with for any reason with all
          * inserts and removes.
@@ -355,14 +351,42 @@ export declare namespace ISpatialMap {
          */
         isTrailingEdge?: boolean;
         /**
-         * Indicates if the entries should split when the range is expanding.
+         * Whether an insert that lands INSIDE an entry cuts it in two rather than growing it.
          *
-         * @defaultValue `false`
+         * @defaultValue `false` - the entry expands to cover the inserted cells.
          *
          * @remarks
-         * Examples include formula, comments, and conditional formatting
+         * Insert a column at `B` under an entry on `A1:C3`: `true` leaves `A1:A3` and `C1:D3`, `false`
+         * leaves `A1:D3`. A comment or a hyperlink is per-cell and cuts; a table grows, which is what
+         * a spreadsheet does when you insert a column inside one.
+         *
+         * Only asked of an entry that {@link isSplittable}, and only of an insert.
          */
         isSplitOnExpand?: boolean;
+        /**
+         * Whether an entry may be cut into pieces at all.
+         *
+         * @defaultValue `true`
+         *
+         * @remarks
+         * A property of what the entries ARE, not of any one operation. `false` says this entry is
+         * indivisible: it moves, it grows and it dies, but it never becomes two.
+         *
+         * It decides what a PARTIAL shift does. Insert one cell at `A1`, shifting down, under an entry
+         * on `A1:C3` - only the cells in the band moved, so:
+         *
+         * * splittable, the entry fragments into the part that moved and the part that did not:
+         *   `$A$2:$A$4,$B$1:$C$3`. A style, a comment, a conditional format's applies-to.
+         * * indivisible, the whole entry moves, per axis: `A2:C4`. That is what a formula precedent
+         *   does, and a range listener's anchor is the same kind of thing.
+         *
+         * Both shift. The difference is only whether the entry can come apart.
+         *
+         * TODO - the shift path is the only one that asks. A partial CLEAR fragments an entry through
+         * the model's own `setCoords` without ever reaching here, so an indivisible entry is only
+         * indivisible under a shift.
+         */
+        isSplittable?: boolean;
         /**
          * If `true` then after shift any shift entries will attempt to be merged to their nearest neighbors.
          *
@@ -421,10 +445,15 @@ export declare namespace ISpatialMap {
      */
     interface InsertNonOverlappingOptions<T> {
         /**
-         * Callback function that will be be called on insert.
+         * Decides what each piece of the insert becomes, against what was there.
          *
          * @remarks
-         * If see this will be called for each new entry creation with the original entry.
+         * Called for EVERY piece the insert is cut into, not only the intersecting ones: `orig` is the
+         * entry the piece lands on, or the piece itself with a `null` value where nothing was there.
+         * `adj` is the piece with the inserted value. The returned entry is what the map keeps at
+         * that piece; a `null` value (or `null`) culls it. So a callback that keeps the existing value
+         * must supply one where there is none - `orig.value ?? adj.value` - or the insert silently
+         * lands nowhere. The default replaces the value and keeps the piece.
          */
         onIntersect?: (orig: ISpatialMap.Entry<T>, adj: ISpatialMap.Entry<T>) => ISpatialMap.Entry<T>;
         onUpdates?(inserts: ISpatialMap.Entry<T>[], removes: ISpatialMap.Entry<T>[], spatial: ISpatialMap): void;
@@ -477,12 +506,21 @@ export declare namespace ISpatialMap {
     interface IConflatingEntries<T = any> {
         /**
          * Append a major minor value with an optional value. The value can be left empty if the value is not needed or can be derived from the major and minor.
+         *
+         * Appends are ordered. The last cell may be appended again only if the entries were made to
+         * combine its values; it then leaves the run it was conflated into.
          */
         append: (major: number, minor: number, value?: T) => void;
         /**
          * Returns the conflated entries. If `merge` is `true` then adjacent entries will be merged into a single entry with a range that covers both entries. If `false` then each entry will be returned as-is.
          */
         done: (merge?: boolean) => ISpatialMap.Entry<T>[];
+        /**
+         * The entry appended so far that covers a position, before {@link done}.
+         *
+         * @returns `undefined` if nothing was appended there.
+         */
+        find: (major: number, minor: number) => ISpatialMap.Entry<T> | undefined;
     }
 }
 export interface ISpatialQuery<T = any> {

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

@@ -23,6 +23,8 @@ export declare class ImmutableList<T> implements IReadableList<T> {
     private _length;
     /** Single-entry cache of the last-accessed run, to skip binary search on sequential reads. */
     private _runCache;
+    /** See {@link getUniformRuns}. `undefined` = not looked yet, `null` = looked, there are none. */
+    private _uniform;
     constructor(values?: T[] | IListLike<T>);
     /**
      * Returns the value at a given index.
@@ -42,6 +44,32 @@ export declare class ImmutableList<T> implements IReadableList<T> {
     /** {@inheritDoc IReadableList.length} */
     get length(): number;
     [Symbol.iterator](): IterableIterator<T>;
+    /**
+     * The stretches of this list that hold ONE value throughout, as `[from, to, value]` triples in
+     * index order, or `null` when there are none.
+     *
+     * @remarks
+     * A stretch is a period-1 `RepeatingList` (`isIRepeatingList`, the house brand convention)
+     * backing the whole list or one of its slices: a run written as "this value, this many times"
+     * stays recognizable after the list has been sliced or merged with its neighbors, so a reader
+     * can act on the stretch once instead of asking `at` for every position. Anything else — an
+     * array, a cyclic repeat — is not a stretch and is read per position. Computed once and held:
+     * the list is immutable.
+     */
+    getUniformRuns(): readonly (readonly [from: number, to: number, value: T])[] | null;
+    /**
+     * Calls `fn` for each stretch of `list` that one leaf list backs, in index order, over
+     * `[from, to]` (inclusive). In a stretch `[stretchFrom, stretchTo]`, the value at list index `i`
+     * is `leaf.at(leafFrom + i - stretchFrom)`. Anything that is not an `ImmutableList` is its own
+     * leaf.
+     *
+     * @remarks
+     * For a reader that can do better with a leaf than ask `at` of the wrapper: a typed leaf's
+     * buffer, a repeat's one value.
+     */
+    static forEachLeaf<T>(list: IListLike<T>, fn: (leaf: IListLike<T>, leafFrom: number, stretchFrom: number, stretchTo: number) => void, from?: number, to?: number): void;
+    /** {@link forEachLeaf} over `[from, to]` of `list`, reported `shift` further on. */
+    private static _forEachLeaf;
     /** {@inheritDoc IReadableList.isIReadableList} */
     get isIReadableList(): true;
     /** {@inheritDoc IList.isIList} */