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

package/types/src/cellRange/ICellRanges.d.ts

@@ -150,11 +150,11 @@ export interface ICellRanges {
      * chain to find all contributing ranges; if `false` (the default) only the direct inputs
      * are returned.
      * @remarks
-     * Returns `null` if the ranges have no precedents.
+     * Resolves `null` if the ranges have no precedents.
      * @see
      * {@link ICellRanges.getDirectPrecedents} / {@link ICellRanges.getPrecedents} for the single-cell equivalents.
      */
-    getPrecedents(entireSet?: boolean): ICellRanges | null;
+    getPrecedents(entireSet?: boolean): Promise<ICellRanges | null>;
     /**
      * Returns the ranges whose formulas reference these ranges.
      *
@@ -162,11 +162,11 @@ export interface ICellRanges {
      * chain to find the total impact of a value change; if `false` (the default) only the
      * immediate consumers are returned.
      * @remarks
-     * Returns `null` if the ranges have no dependents.
+     * Resolves `null` if the ranges have no dependents.
      * @see
      * {@link ICellRanges.getDirectDependents} / {@link ICellRanges.getDependents} for the single-cell equivalents.
      */
-    getDependents(entireSet?: boolean): ICellRanges | null;
+    getDependents(entireSet?: boolean): Promise<ICellRanges | null>;
     /**
      * {@inheritDoc ICellRange.getVisible}
      */
@@ -334,8 +334,10 @@ export interface ICellRanges {
     /**
      * {@link ICellRange.addWatch} across every area, as ONE expression authored at a shared origin.
      *
-     * @param formula An expression, or a formula, authored at the FIRST area's top-left.
+     * @param formula An expression, or a formula, authored at the top-left of the bounding box of
+     *                every area — which need not be a cell of any area.
      * @param callback Receives each area's results separately, with the area's index and the area.
+     * @param options How each cell is evaluated; see {@link ICellRange.WatchOptions}.
      *
      * @returns A callback removing every area's watch.
      *
@@ -343,7 +345,7 @@ export interface ICellRanges {
      * This is the form a multi-area rule wants, and the reason it exists is the anchor. A
      * conditional format over `E5:F6 E10:F11` stores ONE formula, authored at the sqref origin
      * `E5` — so `E10` must evaluate that formula FILLED to `E10`, an anchor no cell in the second
-     * area carries. Compiling each area against its own top-left instead makes area two read area
+     * area carries. Over `E7:F7 B11:C11` the origin is `B7`: the areas' order does not matter. Compiling each area against its own top-left instead makes area two read area
      * one's cells: `E5>5` read from `E10` means "is the cell five rows up greater than 5".
      *
      * So the fill lives here, where the areas are known to belong to one rule, rather than on
@@ -353,7 +355,7 @@ export interface ICellRanges {
      * One watch per area — deliberately not pooled by expression. The callback therefore fires per
      * area, and an edit touching two of them delivers twice.
      */
-    addWatch(formula: ICalculation.IFormula | string, callback: ICellRanges.WatchCallback): IListener.Remove;
+    addWatch(formula: ICalculation.IFormula | string, callback: ICellRanges.WatchCallback, options?: ICellRange.WatchOptions): IListener.Remove;
     /**
      * Returns an iterator that allows you to iterate over the individual values within the range.
      *

package/types/src/chart/Chart.d.ts

@@ -1,5 +1,8 @@
 import { IResource, IResourceCollection } from '../resource';
 import { IModel, AbstractModel } from '../model';
+import { IMovable } from '../movable';
+import { ICellRange } from '../cellRange';
+import { IEmbeddedPart } from '../io';
 import { IChart } from './IChart';
 interface State extends AbstractModel.State {
     data?: any;
@@ -8,19 +11,56 @@ interface State extends AbstractModel.State {
  * Implementation for {@link IChart}.
  */
 export declare class Chart extends AbstractModel<State, IChart.JSON> implements IChart {
+    /**
+     * The chart's document part. Held beside {@link State.data} rather than in it because the
+     * resources it carries are model references, not JSON, and have to be re-persisted per save.
+     */
+    protected _part: IEmbeddedPart | null;
+    protected _getMovable: () => IMovable;
+    protected _getRange: ((address: string) => ICellRange | null) | null;
+    /** The markup `_facts` was read from. */
+    private _factsSource;
+    private _facts;
+    private _series;
+    private _axes;
+    /** The part's formulas as the engine holds them, by {@link ChartXmlFacts.slots} index. */
+    private _held;
     constructor(options: Chart.ConstructorOptions);
     /** {@inheritDoc IModel.getType} */
     getType(): string;
+    /** The captured part is read once, on first ask; most charts are never asked. */
+    private _getFacts;
+    /** The formula in `slot` as it is now: the engine's, and until it holds one the part's own. */
+    private _formulaAt;
+    private _formulaOf;
+    /** The cells the formula in `slot` names, when it is one plain reference. */
+    private _rangeAt;
+    /** Text read from a cell is the cell's text now; what the file cached answers where that cannot be read. */
+    private _textOf;
     /** {@inheritDoc IChart.getChartTitle} */
     getChartTitle(): string | null;
-    /** {@inheritDoc IChart.getChartTye} */
+    /** {@inheritDoc IChart.getChartType} */
     getChartType(): string;
+    /** {@inheritDoc IChart.getSeries} */
+    getSeries(): readonly IChart.ISeries[];
+    /** {@inheritDoc IChart.getAxes} */
+    getAxes(): readonly IChart.IAxis[];
+    /** {@inheritDoc IChart.getPivotSource} */
+    getPivotSource(): string | null;
     /** {@inheritDoc Movable.Content.getDescription} */
     getDescription(): string;
+    /** {@inheritDoc IChart.getMovable} */
+    getMovable(): IMovable;
+    /** {@inheritDoc IChart.getXML} */
+    getXML(): string | null;
     /** {@inheritDoc Movable.Content.toJSON} */
-    toJSON(_toResourceId?: (resource: IResource) => number | null): IChart.JSON | null;
+    toJSON(toResourceId?: (resource: IResource) => number | null): IChart.JSON | null;
     /** {@inheritDoc Movable.Content.getTypeDescription} */
     getTypeDescription(): string;
+    /** @internal */
+    protected _processDelete(): void;
+    /** {@inheritDoc IChart.isIChart} */
+    get isIChart(): true;
 }
 /**
  * Interfaces for creating `Chart` items.
@@ -47,6 +87,36 @@ export declare namespace Chart {
          * Allow for the default lock aspect ratio to be overwritten.
          */
         defaultLockAspectRatio?: boolean;
+        /**
+         * Resolves the movable this chart is the content of.
+         *
+         * @remarks
+         * Called when asked, not at construction — the content is built before its movable is.
+         */
+        getMovable: () => IMovable;
+        /**
+         * Resolves a sheet-qualified address in the chart's workbook.
+         */
+        getRange?: (address: string) => ICellRange | null;
+        /**
+         * Hands the chart's formulas to the calculation engine, which keeps their references on the
+         * cells they name through inserts, deletes, moves and sheet renames.
+         *
+         * @param getExpressions Asked once, when the engine can compile.
+         */
+        holdFormulas?: (getExpressions: () => readonly string[]) => Chart.HeldFormulas;
+    }
+    /**
+     * A chart's formulas as the calculation engine holds them.
+     */
+    interface HeldFormulas {
+        /**
+         * The formula at `index` as it reads now, or `null` while it reads as it was handed over:
+         * the engine does not hold it, or nothing has moved what it names.
+         */
+        getText(index: number): string | null;
+        /** Takes the formulas out of the engine, as part of the current operation. */
+        release(): void;
     }
 }
 export {};

package/types/src/chart/ChartCollection.d.ts

@@ -0,0 +1,26 @@
+import { ICollection, AbstractCollection } from '../type';
+import { IListener } from '../listener';
+import { IMovableCollection } from '../movable';
+import { IChart } from './IChart';
+import { IChartCollection } from './IChartCollection';
+/**
+ * Implementation for {@link IChartCollection}.
+ *
+ * @remarks
+ * A live view over the movables — no store of its own and no event of its own. The movables'
+ * `onCollectionChange` is forwarded as this collection's, with this collection as the source;
+ * deleting the movable is deleting the chart.
+ */
+export declare class ChartCollection extends AbstractCollection<IChart> implements IChartCollection {
+    private _movables;
+    constructor(movables: IMovableCollection);
+    /** {@inheritDoc AbstractCollection._getItems} */
+    protected _getItems(): IChart[];
+    /** {@inheritDoc IChartCollection.getByName} */
+    getByName(name: string): IChart | null;
+    /** {@inheritDoc ICollection.addListeners} */
+    addListeners(listeners: ICollection.IListeners, options?: IListener.Options): IListener.Remove;
+    /** {@inheritDoc IChartCollection.isIChartCollection} */
+    get isIChartCollection(): true;
+}
+//# sourceMappingURL=ChartCollection.d.ts.map

package/types/src/chart/IChart.d.ts

@@ -1,16 +1,83 @@
 import { IListener } from '../listener';
 import { IResource } from '../resource';
 import { IModel } from '../model';
+import { IMovable } from '../movable';
+import { IEmbeddedPart } from '../io';
+import { ICellRange } from '../cellRange';
 /**
- * Interface for working with Charts.
+ * Interface for working with a chart.
  *
- * **PLACEHOLDER** - This is under development and not made public yet.
+ * @remarks
+ * A chart is the content of a movable, which places and names it — see {@link IChart.getMovable}.
+ * Until the chart is modeled it is carried as the markup it was read from and written back
+ * unchanged; {@link IChart.getXML} is the read-only view of that markup.
  */
 export interface IChart extends IModel {
-    toJSON(toResourceId?: (resource: IResource) => number | null): IChart.JSON | null;
+    /**
+     * Returns the chart's title, or `null` if it has none.
+     *
+     * @remarks
+     * A title that is a reference to a cell reads as that cell's text. A chart with no title of its
+     * own answers `null` even where an application would draw one for it — a single series' name,
+     * or a placeholder.
+     */
     getChartTitle(): string | null;
+    /**
+     * Returns the chart's type, or `'unknown'`.
+     *
+     * @remarks
+     * `'column'`, `'bar'`, `'line'`, `'area'`, `'pie'`, `'doughnut'`, `'scatter'`, `'bubble'`,
+     * `'radar'`, `'stock'`, `'surface'`, `'waterfall'`, `'funnel'`, `'treemap'`, `'sunburst'`,
+     * `'histogram'`, `'boxWhisker'` and so on. A stacked chart says so after the type —
+     * `'columnStacked'`, `'areaPercentStacked'`. A chart whose series are not all drawn the same way
+     * is `'combo'`, and {@link IChart.ISeries.getChartType} says how each one is drawn.
+     */
     getChartType(): string;
+    /**
+     * Returns the series the chart plots, in the order they are listed.
+     *
+     * @remarks
+     * What a series plots is stated as formulas, which follow the cells they name: inserting a row
+     * above the data moves them, and deleting the data leaves `#REF!`.
+     */
+    getSeries(): readonly IChart.ISeries[];
+    /**
+     * Returns the axes the chart shows. A pie has none.
+     */
+    getAxes(): readonly IChart.IAxis[];
+    /**
+     * Returns the name of the pivot table the chart draws, or `null` if it is not a pivot chart.
+     *
+     * @remarks
+     * A pivot chart's series are the pivot table's: they change with its layout, and the ranges its
+     * series name are wherever the table last put them.
+     */
+    getPivotSource(): string | null;
+    /**
+     * Returns a description for assistive technologies.
+     */
     getDescription(): string;
+    /**
+     * Returns the movable that places the chart on the sheet.
+     *
+     * @remarks
+     * The movable holds the chart's position, size and name; the chart keeps no copy of any of
+     * them. Deleting the movable deletes the chart.
+     */
+    getMovable(): IMovable;
+    /**
+     * Returns the chart's own markup, or `null` if none was captured.
+     *
+     * @remarks
+     * Read-only, and the one escape hatch for what the chart does not model yet: it is the
+     * `<c:chartSpace>` the chart was read from, not the parts that markup references, with its
+     * formulas as they are now. It will be removed when the chart is modeled.
+     */
+    getXML(): string | null;
+    /** @internal */
+    toJSON(toResourceId?: (resource: IResource) => number | null): IChart.JSON | null;
+    /** For runtime type checking. */
+    readonly isIChart: true;
 }
 /**
  * {@inheritDoc IChart}
@@ -20,6 +87,88 @@ export interface IChart extends IModel {
  * {@link IChart}
  */
 export declare namespace IChart {
+    /**
+     * One series of a chart: what it is called and the cells it plots.
+     *
+     * @remarks
+     * Each part of a series is stated as a formula — `Sales!$C$4:$C$15` — the way the file and a
+     * chart's own dialog state it. The formula is the contract: it is what can say `#REF!`, name a
+     * defined name, or point at another workbook. The `get…Range` forms resolve the plain case.
+     */
+    interface ISeries {
+        /**
+         * Returns the series' name, or `null` if it has none.
+         *
+         * @remarks
+         * A name that is a reference to a cell reads as that cell's text.
+         */
+        getName(): string | null;
+        /**
+         * Returns the formula naming the series — `Sales!$C$3` — or `null` when the name is written
+         * into the chart, or there is none.
+         */
+        getNameFormula(): string | null;
+        /**
+         * Returns the formula for the values plotted, or `null` if the series states none.
+         *
+         * @remarks
+         * Values written into the chart rather than read from cells are an array literal: `{1,2,3}`.
+         */
+        getValuesFormula(): string | null;
+        /**
+         * Returns the formula for the categories the values are plotted against — the x values of a
+         * scatter or bubble series — or `null` if the series states none.
+         */
+        getCategoriesFormula(): string | null;
+        /**
+         * Returns the cells {@link getNameFormula} names, or `null`.
+         *
+         * @see {@link getValuesRange} for when there are none to return.
+         */
+        getNameRange(): ICellRange | null;
+        /**
+         * Returns the cells {@link getValuesFormula} names.
+         *
+         * @returns `null` when the formula is not one plain reference into this workbook: an array
+         * literal, a defined name, several areas, another workbook, or `#REF!`.
+         */
+        getValuesRange(): ICellRange | null;
+        /**
+         * Returns the cells {@link getCategoriesFormula} names, or `null`.
+         *
+         * @see {@link getValuesRange} for when there are none to return.
+         */
+        getCategoriesRange(): ICellRange | null;
+        /**
+         * Returns how the series is drawn. The same as {@link IChart.getChartType} except in a combo.
+         */
+        getChartType(): string;
+        /**
+         * Returns `true` if the series is plotted against the secondary axes.
+         */
+        isSecondaryAxis(): boolean;
+    }
+    /**
+     * One axis of a chart.
+     */
+    interface IAxis {
+        /**
+         * Returns what the axis measures: categories, values, dates, or — on a surface or 3-D chart —
+         * the series themselves.
+         */
+        getKind(): 'category' | 'value' | 'date' | 'series';
+        /**
+         * Returns the axis title, or `null` if it has none.
+         *
+         * @remarks
+         * Often the only place the units of a chart are stated.
+         */
+        getTitle(): string | null;
+        /**
+         * Returns the number format of the axis labels, or `null` if the axis states none.
+         */
+        getNumberFormat(): string | null;
+    }
     interface JSON {
         /** Opaque source XML fragment, captured verbatim from the source file and replayed as-is on
          * save, for whatever this chart doesn't (yet) model structurally. */
@@ -27,12 +176,16 @@ export declare namespace IChart {
         /** Original `cNvPr` id from the captured source fragment, if any; used to avoid id collisions
          * with freshly-generated ids on write. */
         sourceId?: number;
-        /** The literal `r:id` referencing the chart part inside `xml`, rewritten to match on write —
-         * `DrawingEmitter` regenerates the drawing part's own rels, so the id `xml` was captured with
-         * is not guaranteed to still be free. */
-        chartRelId?: string;
-        /** The chart part's absolute OPC path (e.g. "xl/charts/chart1.xml"), used to re-link `chartRelId`. */
-        chartTargetPath?: string;
+        /**
+         * The chart's own document part, and the parts that part references.
+         *
+         * @remarks
+         * The chart is carried as the markup it was read from until it is modeled; this is that markup
+         * and everything it needs to stay valid — its style and color definitions, the shapes drawn
+         * over it, an embedded workbook holding its data. {@link IChart.getXML} is the readable view
+         * of the chart's own markup; the rest is for writing the chart back out.
+         */
+        part?: IEmbeddedPart.JSON;
     }
     interface Events extends IModel.Events {
     }

package/types/src/chart/IChartCollection.d.ts

@@ -0,0 +1,25 @@
+import { ICollection } from '../type';
+import { IChart } from './IChart';
+/**
+ * Holds the {@link IChart | charts} on a sheet.
+ *
+ * @remarks
+ * A view over the sheet's movables: a chart is the content of a movable, and the movable is what
+ * places, names and deletes it — see {@link IChart.getMovable}. Read-only for now; a chart is
+ * added by adding a movable with chart content.
+ */
+export interface IChartCollection extends ICollection<IChart> {
+    /**
+     * Returns the charts, in the order of their movables.
+     */
+    getItems(options?: ICollection.GetItemsOptions): IChart[];
+    /**
+     * Returns the chart whose movable has the given name, or `null` if there is none.
+     *
+     * @param name The name of the chart. This is case insensitive.
+     */
+    getByName(name: string): IChart | null;
+    /** For runtime type checking. */
+    readonly isIChartCollection: true;
+}
+//# sourceMappingURL=IChartCollection.d.ts.map

package/types/src/chart/_ChartXml.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Reads what a chart's captured part can answer without a chart model behind it: what it plots,
+ * what kind of chart it is, and what it and its axes are called.
+ *
+ * @remarks
+ * An imported chart is kept as the source's markup ({@link IChart.JSON.part}) and replayed on save.
+ * Both chart vocabularies are read — `c:chartSpace`, and `cx:chartSpace` for the chart types added
+ * after it (waterfall, funnel, treemap, sunburst, histogram, box and whisker).
+ *
+ * Every formula in the part is also located ({@link ChartXmlFacts.slots}), because a formula is
+ * the one thing in the part that is not replayed verbatim: see {@link writeChartFormulas}.
+ */
+/** One formula in the part: its text, and where that text is in the markup. */
+export interface ChartFormulaSlot {
+    /** The formula as the part states it, entities decoded. */
+    text: string;
+    start: number;
+    end: number;
+}
+/** A piece of chart text: written in the chart, or read from a cell. */
+export interface ChartTextFacts {
+    /** The literal text, or what the cell held when the file was saved. */
+    text: string | null;
+    /** The {@link ChartXmlFacts.slots} index of the formula naming the cell, or `null` for a literal. */
+    slot: number | null;
+}
+/** A series dimension: the cells it reads, or the values written into the chart. */
+export interface ChartSourceFacts {
+    slot: number | null;
+    /** `{1,2,3}` — a dimension with no cells behind it. */
+    literal: string | null;
+}
+export interface ChartSeriesFacts {
+    type: string;
+    name: ChartTextFacts;
+    values: ChartSourceFacts;
+    categories: ChartSourceFacts;
+    secondary: boolean;
+}
+export interface ChartAxisFacts {
+    kind: 'category' | 'value' | 'date' | 'series';
+    title: ChartTextFacts;
+    numberFormat: string | null;
+}
+/** What {@link readChartXml} answers with. */
+export interface ChartXmlFacts {
+    type: string;
+    title: ChartTextFacts;
+    series: ChartSeriesFacts[];
+    axes: ChartAxisFacts[];
+    /** `c:pivotSource/c:name` — the pivot table a pivot chart draws, as the part names it. */
+    pivotSource: string | null;
+    slots: ChartFormulaSlot[];
+}
+/**
+ * Reads a captured chart part.
+ *
+ * @param xml The part as captured on import.
+ * @returns `null` when `xml` holds no chart.
+ */
+export declare const readChartXml: (xml: string) => ChartXmlFacts | null;
+/**
+ * The part with its formulas restated.
+ *
+ * @param xml The part {@link readChartXml} read `slots` from.
+ * @param texts The formula for each slot, or `null` to leave what the part says.
+ * @returns `xml` itself when nothing is restated.
+ */
+export declare const writeChartFormulas: (xml: string, slots: readonly ChartFormulaSlot[], texts: readonly (string | null)[]) => string;
+//# sourceMappingURL=_ChartXml.d.ts.map

package/types/src/chart/index.d.ts

@@ -1,5 +1,3 @@
-/**
- * @hidden
- */
 export * from './IChart';
+export * from './IChartCollection';
 //# sourceMappingURL=index.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> {