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

package/types/src/sheet/_SheetStateTypes.d.ts

@@ -1,27 +1,30 @@
 import { Scalar, IRange } from '@sheetxl/primitives';
+import { ListenerAnchor } from './_ListenerAnchor';
 import { IProperties } from '../type';
 import { ITable } from '../table';
 import { IComment } from '../comment';
 import { IHyperlink } from '../hyperlink';
-import { IStyle } from '../style';
+import { ICellStyle } from '../style';
 import { ICellRange } from '../cellRange';
-import { OverlappingRange, ISparseGrid, ISpatialMap } from '../collections';
+import { OverlappingRange, ISpatialMap } from '../collections';
 import { MergeEntry } from './spatial';
+import { FormulaEntry, ICalcGrid } from '../calculation/grid';
 import { SpillEntry, ContentfulSpatialValue, CircularEntry } from '../calculation/spatial';
 import { IConditionalFormat } from '../conditionalFormat';
 import { IDataValidation } from '../dataValidation';
 import { IProtectedRange } from '../protectedRange';
-import { IFormulaBlock } from '../calculation/formula';
+import { IPivotTable } from '../pivot';
+import { IDataTable } from '../dataTable';
+import { ICell } from '../cell';
+import { IgnoredErrors } from './_IgnoredErrors';
+import { CellKind } from './_Kinds';
 import { IAnchoredMap } from '../anchored/IAnchoredMap';
 import { Anchored } from '../anchored/Anchored';
-import { ICalcGrid } from '../calculation/grid';
 import { IUsedRangeSpatialMap } from './style/UsedRangeSpatialMap';
 import { SheetDirectStyle } from './style/SheetDirectStyle';
 import { IMovable } from '../movable';
 import { Movable } from '../movable/Movable';
 import { IPicture } from '../picture';
-import { IListener } from '../listener';
-import { RangesListener, RangesListenerEntry } from './listener';
 export declare const BreakTrue: Readonly<{
     break: true;
 }>;
@@ -123,7 +126,7 @@ export declare namespace RangeState {
     /**
      * Shorthand type.
      */
-    type Iterator = WellKnownIterator<RangeState.Entry, RangeState.Entry, IRange.Coords>;
+    type Iterator = WellKnownIterator<RangeState.Entry, RangeState.Entry, IRange.CellCoords>;
     /**
      * Dynamic state. These are values associated to a range of cells that
      * get realized at time of cell iterator.
@@ -152,18 +155,36 @@ export declare namespace RangeState {
         conditionals?: IConditionalFormat | IConditionalFormat[];
         /**
          * The per-feature direct styles for a collection of cells (SHEET-STYLE-SPLIT). These are the
-         * user-authored style, kept DISCRETE — `borderStyle` carries `border`, `fillStyle` carries `fill`,
-         * `contentStyle` carries font / numberFormat / alignment / quotePrefix / named / insets.
+         * user-authored style, kept DISCRETE — `borderStyle` carries `borders`, `fillStyle` carries `fill`,
+         * `contentStyle` carries font / numberFormat / alignment / quotePrefix / protection / named /
+         * insets.
          * `CompositeRangedStyle` bag-merges the three; single-category consumers read just one.
-         * Public API should use IStyle.
+         * Public API should use ICellStyle.
          */
-        borderStyle?: IProperties.ICellRanged<IStyle.Properties>;
-        fillStyle?: IProperties.ICellRanged<IStyle.Properties>;
-        contentStyle?: IProperties.ICellRanged<IStyle.Properties>;
+        borderStyle?: IProperties.ICellRanged<ICellStyle.Properties>;
+        fillStyle?: IProperties.ICellRanged<ICellStyle.Properties>;
+        contentStyle?: IProperties.ICellRanged<ICellStyle.Properties>;
         /**
          * The hyperlink.
          */
         hyperlink?: IHyperlink.Properties;
+        /**
+         * The error checks the cells ignore (`ICellRange.setErrorIgnored`). One interned set per
+         * distinct combination, so equal sets are one object.
+         */
+        ignoredErrors?: readonly ICell.ErrorCheck[];
+        /**
+         * The error checks that fire, with their evidence. One interned list per distinct set of
+         * findings, so equal findings are one object and a region's identity is its payload.
+         */
+        anomalies?: readonly ICell.Anomaly[];
+        /**
+         * What the cell holds (`ICellRange.Feature.Kind`): number, date, text, text that reads as a
+         * number, boolean, error or rich data; a formula by its result.
+         */
+        kind?: CellKind;
+        /** The cell's job (`ICellRange.Feature.Role`): label, input, link, reference, computed or output. */
+        role?: ICell.Role;
         /**
          * Directives for unlocking a range. (Only applies if the sheet is protected).
          *
@@ -189,18 +210,19 @@ export declare namespace RangeState {
          * * These are just copies of directStyle for fast lookup.
          * * A continuous alignment is an alignment that spans multiple horizontal cells.
          */
-        continuous?: IProperties.ICellRanged<IStyle.Properties>;
+        continuous?: IProperties.ICellRanged<ICellStyle.Properties>;
         /**
-         * The comments.
+         * The comment on the cell.
          *
          * @remarks
-         * A block of comments for the range.
+         * The model that owns the cell, the way the other anchored entries answer.
          */
-        comments?: IComment.Properties;
+        comments?: IComment;
         /**
-         * A block of R1C1 formulas.
+         * The formula run this cell belongs to: the sheet's entry, which answers as a block over its
+         * own text whether or not the engine has vended one (see {@link FormulaEntry}).
          */
-        formula?: IFormulaBlock;
+        formula?: FormulaEntry;
         /**
          * Spills.
          *
@@ -256,6 +278,7 @@ export declare namespace RangeState {
         readonly DataValidations: "dataValidations";
         readonly Merge: "merge";
         readonly Hyperlink: "hyperlink";
+        readonly IgnoredErrors: "ignoredErrors";
         readonly Comments: "comments";
         readonly Unlock: "unlock";
         readonly Contentful: "contentful";
@@ -273,11 +296,27 @@ export declare namespace RangeState {
         readonly Circular: "circular";
         /**
          * Error VALUES (the `Error` scalar kind). Backed by the RECONCILED view
-         * (`SheetReadContext.getErrorSpatial`), not `state.errorSpatial` directly — resolving it may
+         * (`ICalcGrid.getErrorValues`), not the grid's write-path index directly — resolving it may
          * lazily build (a value scan, cached per state version), so it is opt-in only: never part of
          * {@link AllRangeTypes} / the all-types sweep.
          */
         readonly Error: "error";
+        /**
+         * Where an error check fires (`ICell.getAnomalies`). Backed by a map derived from the other
+         * features on first read and cached per sheet state and value epoch, so like {@link Error}
+         * it is opt-in only: never part of {@link AllRangeTypes} / the all-types sweep.
+         */
+        readonly Anomalies: "anomalies";
+        /**
+         * What each cell holds, by kind. Backed by a map derived from the values on first read and
+         * cached per sheet state and value epoch, so like {@link Error} it is opt-in only.
+         */
+        readonly Kind: "kind";
+        /**
+         * Each cell's job, by role. Backed by a map derived from the kinds and the formulas on first
+         * read and cached per sheet state and value epoch, so like {@link Error} it is opt-in only.
+         */
+        readonly Role: "role";
         readonly Validation: "dataValidation";
     };
     type Type = typeof Type[keyof typeof Type];
@@ -293,7 +332,9 @@ export declare namespace RangeState {
  * - `null` = no backing index at all — nothing left in the public vocabulary hits this today.
  *   `String`/`Number`/`Boolean` used to (scalar kinds count from values, not state); they were
  *   retired from the vocabulary entirely rather than kept as a permanent `null` — a stats scan
- *   already answers the same question, richer.
+ *   already answers the same question, richer. The value kind came back as one feature, `Kind`,
+ *   backed by a derived map, because a check needs it as a partition (a typed row is a region),
+ *   not as a count.
  * - `DateFormat` and `Error` are both real, directly indexed state now — `DateFormat` off its own
  *   spatial map (`dateFormatSpatial`, no longer internal-only), `Error` off the reconciled error
  *   view. Neither needs the value-scan special-casing the old derived `Date` feature did.
@@ -332,7 +373,7 @@ export declare function cellFeaturesToSearchTypes(features?: ICellRange.Feature
  * themselves.
  * @internal
  */
-export declare function featureToUsedCoords(state: State, feature: ICellRange.Feature): IRange.Coords | null;
+export declare function featureToUsedCoords(state: State, calcGrid: ICalcGrid, feature: ICellRange.Feature): IRange.Coords | null;
 export declare const AllRangeTypes: RangeState.SearchTypes;
 export declare const CellStateRangeTypes: RangeState.SearchTypes;
 /**
@@ -351,6 +392,14 @@ export declare const NoMergeRangeTypes: RangeState.SearchTypes;
  * @internal
  */
 export declare const OverflowsRangeTypes: RangeState.SearchTypes;
+/**
+ * Which axes of the sheet's entire size end where its content does. See `IWorksheet.setEntireSize`.
+ * @internal
+ */
+export interface EntireFit {
+    width: boolean;
+    height: boolean;
+}
 /**
  * A movable's spatial entry (anchor + container callbacks + z-order).
  * @internal
@@ -359,24 +408,17 @@ export interface MovableEntry extends Anchored.Entry<IMovable> {
     callbacks: Movable.ContainerCallbacks;
     zIndex: number;
 }
-/** @internal */
-export interface ICellRangeListenerEntry {
-    id: number;
-    offset: number;
-    options: ICellRange.ListenerOptions;
-}
-/** @internal */
-export interface ICellRangesListenerEntry {
-    id: number;
-    /**
-     * We have to track the range because we can't use the node coords
-     * as shift/split can change the coords. and our range has fixed dimensions.
-     */
-    ranges: (Readonly<IRange.FixableCoords> | null)[];
-    handler: ICellRange.Listener | null;
-    handlerW: WeakRef<ICellRange.Listener> | null;
-    removeListener: IListener.Remove;
-    options: ICellRange.ListenerOptions;
+/**
+ * One of the sheet's movable indexes: the placed movables, or the note boxes. Names the state
+ * keys the index lives under, what its z-order starts above, and what it builds.
+ * @internal
+ */
+export interface MovableIndex {
+    spatial: 'movableSpatial' | 'noteSpatial';
+    byModel: 'movableMapModel' | 'noteMapModel';
+    /** What the index's lowest movable is drawn above. */
+    zIndexBase: () => number;
+    create: (options: Movable.ConstructorOptions) => Movable;
 }
 /**
  * The versioned per-sheet state record held in the transaction store (see `Sheet._getState`).
@@ -385,30 +427,6 @@ export interface ICellRangesListenerEntry {
  * @internal
  */
 export interface State {
-    cellValuesGrid: ISparseGrid<Scalar>;
-    contentfulSpatial: ISpatialMap<ContentfulSpatialValue>;
-    calcGrid: ICalcGrid;
-    spillSpatial: ISpatialMap<SpillEntry>;
-    pendingSpatial: ISpatialMap<boolean>;
-    calcErrorsSpatial: ISpatialMap<string>;
-    /**
-     * Cells in a reference cycle or downstream of one, by cycle (DESIGN-CIRCULAR-CALC.md §7.2).
-     * Maintained by calc realize from the executor's deltas, like {@link pendingSpatial}.
-     */
-    circularSpatial: ISpatialMap<CircularEntry>;
-    /**
-     * Error VALUES (`#DIV/0!`, `#N/A`, …) — the `Error` scalar kind, NOT engine failures
-     * (those are {@link calcErrorsSpatial} / `CalcError`). Deliberately not per-type: `true`
-     * means "an error value lives here".
-     *
-     * WRITE-PATH ONLY (merge-on-READ): maintained on load, `updateTuples`, content clears and
-     * structural shifts — calc realize NEVER touches it, so it is STALE for formula cells after
-     * a recalc (a fixed formula stays flagged; a new computed error is absent). Do not query it
-     * directly — the reconciled, state-version-cached view (`Sheet._getErrorSpatialReconciled`)
-     * is the only reader. It becomes fully fresh (and the reconcile scan retires) when the calc
-     * executor emits error deltas for realize to apply, O(errors) like `calcErrorsSpatial`.
-     */
-    errorSpatial: ISpatialMap<boolean>;
     borderSpatial: IUsedRangeSpatialMap<SheetDirectStyle>;
     fillSpatial: IUsedRangeSpatialMap<SheetDirectStyle>;
     contentSpatial: IUsedRangeSpatialMap<SheetDirectStyle>;
@@ -416,9 +434,16 @@ export interface State {
     continuousFillSpatial: ISpatialMap<SheetDirectStyle>;
     dateFormatSpatial: ISpatialMap<string>;
     hyperlinkSpatial: ISpatialMap<IHyperlink.Properties>;
-    commentsSpatial: ISpatialMap<IComment.Properties>;
+    /** Where Excel's error checks are ignored, by check. */
+    ignoredErrors: IgnoredErrors;
     movableSpatial: ISpatialMap<MovableEntry>;
     movableMapModel: Map<IMovable, ISpatialMap.Entry<MovableEntry>>;
+    /**
+     * The boxes of the sheet's notes: movables whose content is a comment, kept apart from the
+     * placed ones so they draw above them and are saved with their comments, not as movables.
+     */
+    noteSpatial: ISpatialMap<MovableEntry>;
+    noteMapModel: Map<IMovable, ISpatialMap.Entry<MovableEntry>>;
     picture?: IPicture | null;
     autoTables: IAnchoredMap<ITable, ITable.JSON>;
     tables: IAnchoredMap<ITable, ITable.JSON>;
@@ -431,29 +456,68 @@ export interface State {
      * Read through `RangeState.Type.Unlock` — see {@link RangeState.Intersection.unlock}.
      */
     protectedRanges: IAnchoredMap<IProtectedRange, IProtectedRange.JSON>;
-    rangesListenerSpatial2: ISpatialMap<RangesListenerEntry>;
-    rangesListenerMap2: Map<string, RangesListener>;
-    rangeListenerSpatial: ISpatialMap<ICellRangeListenerEntry>;
-    rangesListenerMap: Map<number, ICellRangesListenerEntry>;
+    /**
+     * The comments and notes, one per cell.
+     *
+     * @remarks
+     * Read through `RangeState.Type.Comments` — see {@link RangeState.Intersection.comments}.
+     */
+    comments: IAnchoredMap<IComment, IComment.JSON>;
+    /**
+     * The reference each range listener watches.
+     *
+     * @remarks
+     * Beside the other anchored maps, and versioned like them: a listener's reference shifts, splits
+     * and goes `#REF!` with the cells it watches, and comes back on undo. A snapshot from before a
+     * listener registered simply holds no entry for it, which is what reports `#N/A`.
+     *
+     * The callbacks are NOT here - they live on the sheet instance, keyed by node id.
+     */
+    listeners: IAnchoredMap<ListenerAnchor, never>;
+    /** The pivot tables laid out on the sheet, anchored at their locations as tables are. */
+    pivotTables: IAnchoredMap<IPivotTable, IPivotTable.JSON>;
+    /** The data tables on the sheet, anchored at their result cells. */
+    dataTables: IAnchoredMap<IDataTable, IDataTable.JSON>;
+    /**
+     * The grid's inputs this record pairs with, as the grid named them when the model last wrote
+     * this sheet's cells (`ICalcGrid.Events.onInputsWritten`); `null` before any write.
+     *
+     * @remarks
+     * The cells are the grid's record, so a write of cell content alone writes nothing else of the
+     * sheet's; this is the sheet's own record of it, and what brings the sheet's state listener to
+     * the commit. What the engine calculates never changes it. Two records with the same id hold
+     * the same cell content.
+     */
+    inputsCommitId: string | null;
     entireCoords: IRange.Coords;
+    /** `null` when neither axis fits. */
+    entireFit: EntireFit | null;
     deleted: boolean;
 }
-/**
- * Tracks a range listener's before/after state for the undo stack when the change is not part of the
- * transaction (non-transactional listeners).
- * @internal
- */
-export interface BeforeAfterRange {
-    beforeState: ICellRangesListenerEntry;
-    afterState: ICellRangesListenerEntry | null;
-}
 /**
  * Internal flags threaded through the cell-update path (`updateTuples` / `createSparseBuilder`) to
- * mark the origin of the update (a full cell paste, or a hyperlink display-text write).
+ * mark the origin of the update (a full cell paste, a hyperlink display-text write, one value
+ * broadcast over a range).
  * @internal
  */
 export interface InternalTupleUpdate {
     isCell?: boolean;
     isHyperlink?: boolean;
+    /**
+     * The tuples repeat ONE value over the whole range (`setValue`/`setFormula` on a multi-cell
+     * range). A formula is then that formula FILLED — one block anchored at the top-left, its
+     * references relative from there — not the same text entered in every cell.
+     */
+    isBroadcast?: boolean;
+    /**
+     * The tuples array-enter ONE formula over this extent (`setFormula` with `arrayFixed`): the
+     * formula at the top-left, every other cell cleared. The calc node is minted fixed to it.
+     */
+    arrayFixed?: IRange.Coords;
+    /**
+     * A table's calculated column, filled into body rows the table has just taken in. Those rows came
+     * from an operation that has ruled on the sheet's protection, so locked cells do not refuse it.
+     */
+    isCalculatedFill?: boolean;
 }
 //# sourceMappingURL=_SheetStateTypes.d.ts.map

package/types/src/sheet/_SheetUtils.d.ts

@@ -3,15 +3,14 @@ import { RunCoords } from '@sheetxl/utils';
 import { ITypes } from '../type';
 import { IStringCollection } from '../string';
 import { ISort } from '../sort';
-import { IStyle, IStyleCollection } from '../style';
-import { ICell, ICellHeader } from '../cell';
+import { ICellStyle, IStyleCollection } from '../style';
+import { ICell } from '../cell';
 import { ICellRange, ICellRanges } from '../cellRange';
 import { ISheetHeader } from '../sheetHeader';
-import { ISheet } from './ISheet';
-import { ISheetInternal } from './Sheet';
-import { Tuple, ISpatialMap, IListLike, ISpatialQuery } from '../collections';
+import { IWorksheet } from './IWorksheet';
+import { IWorksheetInternal } from './Worksheet';
+import { ISpatialMap, ISpatialQuery } from '../collections';
 import { MergeEntry } from './spatial';
-import { ContentfulSpatialValue } from '../calculation/spatial';
 import { RangeState, CellState } from './_SheetStateTypes';
 import { SheetDirectStyle } from './style/SheetDirectStyle';
 import { SheetCellOptions } from './SheetCell';
@@ -19,8 +18,16 @@ import { SheetCellOptions } from './SheetCell';
  * Selects max coords in an axis.
  */
 export declare function expandRanges<CT extends IRange.Coords = IRange.Coords>(ranges: readonly CT[], maxRange: IRange.Coords, axis: IRange.Axis, after?: boolean): CT[];
-export declare function isEntireRows(coords: readonly IRange.Coords[], maxCoords: IRange.Coords, all: boolean): boolean;
-export declare function isEntireCols(coords: readonly IRange.Coords[], maxCoords: IRange.Coords, all: boolean): boolean;
+/**
+ * Whether the ranges span every row (whole columns, such as `B:D`): all of them, or any when `all`
+ * is `false`.
+ */
+export declare function spansAllRows(coords: readonly IRange.Coords[], maxCoords: IRange.Coords, all: boolean): boolean;
+/**
+ * Whether the ranges span every column (whole rows, such as `2:4`): all of them, or any when `all`
+ * is `false`.
+ */
+export declare function spansAllColumns(coords: readonly IRange.Coords[], maxCoords: IRange.Coords, all: boolean): boolean;
 export declare function countSpans(coords: readonly IRange.Coords[], axis?: IRange.Axis): number;
 /**
  * Defaults to IRange.Axis.Row if the bounds are the same size.
@@ -35,15 +42,15 @@ export declare function getDefaultShiftAxis(range: IRange.Coords, entireRange: I
  */
 export declare function toAbsRangeCoords(rowIndex: number, colIndex: number, relative: IRange.Coords): IRange.Coords;
 /**
- * Bridge from the public {@link ISheet} to the internal capability object its ranges are built on.
+ * Bridge from the public {@link IWorksheet} to the internal capability object its ranges are built on.
  *
  * @remarks
- * `Sheet` is the only implementation of `ISheet`, so this is total in practice. It exists as a
- * helper (rather than a member of `ISheet`) to keep `_getInternal` off the published interface —
- * `Workbook` holds sheets as `ISheet` and is the only caller that needs to cross the boundary.
+ * `Sheet` is the only implementation of `IWorksheet`, so this is total in practice. It exists as a
+ * helper (rather than a member of `IWorksheet`) to keep `_getInternal` off the published interface —
+ * `Workbook` holds sheets as `IWorksheet` and is the only caller that needs to cross the boundary.
  * @internal
  */
-export declare function getInternal(sheet: ISheet): ISheetInternal;
+export declare function getInternal(sheet: IWorksheet): IWorksheetInternal;
 /**
  * The internals a scoped coord actually addresses — the sheet named by `scope`, not the anchor.
  *
@@ -62,7 +69,7 @@ export declare function getInternal(sheet: ISheet): ISheetInternal;
  * see `WorkbookRanges._createRange`.
  * @internal
  */
-export declare function resolveScopedInternal(internal: ISheetInternal, scope: string | null | undefined): ISheetInternal | null;
+export declare function resolveScopedInternal(internal: IWorksheetInternal, scope: string | null | undefined): IWorksheetInternal | null;
 /**
  * Drops a coord's `scope` when it merely restates the anchor.
  *
@@ -77,12 +84,18 @@ export declare function resolveScopedInternal(internal: ISheetInternal, scope: s
  * redundant with, and stay fully qualified.
  * @internal
  */
-export declare function normalizeScope<T extends IRange.Coords>(coords: T, anchor: ISheet): T;
+export declare function normalizeScope<T extends IRange.Coords>(coords: T, anchor: IWorksheet): T;
 /** {@link normalizeScope} over a set, allocating only when something is actually redundant. @internal */
-export declare function normalizeScopes<T>(coords: readonly T[], anchor: ISheet): readonly T[];
+export declare function normalizeScopes<T>(coords: readonly T[], anchor: IWorksheet): readonly T[];
 /** @internal */
-export declare function createInvalidRange(sheet: ISheet | null, maxRange?: IRange.Coords | null, range?: IRange.Coords | null, errorType?: string): ICellRange;
-export declare function createInvalidRanges(sheet: ISheet): ICellRanges;
+export declare function createInvalidRange(sheet: IWorksheet | null, maxRange?: IRange.Coords | null, range?: IRange.Coords | null, errorType?: string): ICellRange;
+export declare function createInvalidRanges(sheet: IWorksheet): ICellRanges;
+/**
+ * The number `strValue` would enter as if typed, or `null`: the entry parser's number half, so a
+ * date or a time is not a number here.
+ * @internal
+ */
+export declare function parseNumberInput(runtime: IRuntime, strValue: string): number | null;
 /**
  * Implementation of date/number/currency parsing
  *
@@ -97,9 +110,24 @@ export declare function createCellModifiersFromString(runtime: IRuntime, strValu
  * Calculates the bottom inset based on accounting rules
  * @internal
  */
-export declare function calcAccountingBottomInset(style: IStyle): number;
+export declare function calcAccountingBottomInset(style: ICellStyle): number;
 /** @internal */
-export declare function getHiddenRuns(header: ISheetHeader): RunCoords[];
+export declare function getHiddenRuns(header: ISheetHeader): readonly RunCoords[];
+/**
+ * A skip (`IRange.IteratorOptions.processRowSkip` / `processColumnSkip`) over the indexes the
+ * header hides, asked with sheet indexes; `null` when none of `min..max` is hidden.
+ *
+ * @remarks
+ * One per hidden set, kept: the statistics cache their zones by the skip they were walked under,
+ * and a set that changed is a new array and so a new skip.
+ * @internal
+ */
+export declare function getHiddenSkip(header: ISheetHeader, min: number, max: number): ((index: number, reverse?: boolean) => number) | null;
+/**
+ * One skip that leaves out what either does; `hidden` itself when the caller brought none.
+ * @internal
+ */
+export declare function composeSkips(own: ((index: number, reverse?: boolean) => number) | undefined, hidden: (index: number, reverse?: boolean) => number): (index: number, reverse?: boolean) => number;
 /**
  * Merges an array of rangeStateIntersections into a single RangeStateIntersection.
  *
@@ -167,7 +195,7 @@ export declare function rangeTopLeft(range: IRange.Coords): IRange.Coords;
  * Given a selection, find the 'natural' bounding area to sort.
  * When checking for header and default sort criteria this is the axis to use. @default IRange.Axis.Row
  */
-export declare function getDefaultSortCriteria(sheet: ISheet, rangeCoords: IRange.Coords, cellCoords?: IRange.CellCoords, axis?: IRange.Axis): ISort.DefaultSortCriteria;
+export declare function getDefaultSortCriteria(sheet: IWorksheet, rangeCoords: IRange.Coords, cellCoords?: IRange.CellCoords, axis?: IRange.Axis): ISort.DefaultSortCriteria;
 /**
  * Search all spatials expanding the range until no immediate bounding rectangles.
  */
@@ -175,34 +203,24 @@ export declare function findSurroundingRegion(range: IRange.Coords, spatials: IS
 export declare function findExtendedRegion(direction: IRange.Direction, coords: IRange.CellCoords, asRange: IRange.Coords, // TODO - merge this into coords?
 searchSpatials: (range: IRange.Coords) => IRange.Coords[], entireCoords: IRange.Coords): IRange.Coords;
 /**
- * Internal representation of a Scalar.
- */
-export type TypeAndValue = [v: Scalar, t: string];
-/**
- * Converts TypeAndValue to a value appropriate for storing in the grid.
+ * The smallest range containing `range` that cuts through no merge: grown over every merge it
+ * touches, repeatedly, since growing over one merge can reach into the next.
  *
- * @param values an array of Scalar.
- * @returns An `IListLike` of values
- */
-export declare function toListLike(values: Scalar[], strings: IStringCollection, internal?: TypeAndValue[] | null): IListLike<Scalar>;
-/**
- * Wraps each value in a ContentfulSpatialValue
+ * A range spanning every row (whole columns) never widens and one spanning every column (whole rows)
+ * never deepens — `A:A` stays `A:A` with `A1:C1` merged. Returns `range` itself when nothing grows.
+ *
+ * @param getMerges The merges intersecting a range.
  */
-export declare function tuplesToContentfulEntries(gridTuple: Tuple.GridTuple<Scalar>, isColumn: boolean): ISpatialMap.Entry<ContentfulSpatialValue>[];
+export declare function closeOverMerges<T extends IRange.Coords>(range: T, getMerges: (range: IRange.Coords) => readonly IRange.Coords[], entireCoords: IRange.Coords): T;
 /**
- * Expands ranges to include merges.
+ * Expands ranges to include merges. See {@link closeOverMerges}.
  */
 export declare function expandToIncludeMerges(ranges: readonly IRange.Coords[], mergeSpatial: ISpatialMap<MergeEntry>, entireCoords: IRange.Coords): IRange.Coords[];
-export type OrientedStyled = {
-    axes: IRange.AxisSelection;
-    index: number;
-};
-export declare function headerToRangedStyles(headers: IRange.JSONReference<ICellHeader.JSON>[], axis: IRange.Axis, entireCoords: IRange.Coords): ITypes.RangeCoordValue<OrientedStyled>[] | null;
 export declare function shiftFrozen(coords: IRange.CellCoords, range: IRange.Coords, isColumn: boolean, shiftAmount: number, // we could get from range but already have it in caller
 entireRange: IRange.Coords): IRange.CellCoords;
 export declare function flattenRanges(coords: readonly IRange.Coords[], axes?: IRange.AxisSelection): IRange.Coords[];
-export declare function createDirectStyleUpdater(styles: IStyleCollection): ((prev: SheetDirectStyle, update: IStyle.Update, keepNulls?: boolean) => SheetDirectStyle);
-export declare function clearAdjacentBorderEdge(asInsert: SheetDirectStyle, rangeStyle: IRange.Coords, directStylesByRangeWrite: ISpatialMap<SheetDirectStyle>, styleUpdater: (prev: SheetDirectStyle, update: IStyle.Update) => SheetDirectStyle, entireCoords: IRange.Coords): void;
+export declare function createDirectStyleUpdater(styles: IStyleCollection): ((prev: SheetDirectStyle, update: ICellStyle.Update, keepNulls?: boolean) => SheetDirectStyle);
+export declare function clearAdjacentBorderEdge(asInsert: SheetDirectStyle, rangeStyle: IRange.Coords, directStylesByRangeWrite: ISpatialMap<SheetDirectStyle>, styleUpdater: (prev: SheetDirectStyle, update: ICellStyle.Update) => SheetDirectStyle, entireCoords: IRange.Coords): void;
 /**
  * SHEET-STYLE-SPLIT: re-derive the border/fill/content maps over `region` from the authoritative
  * merged `directStyleWrite` blob.

package/types/src/sheet/_WatchAnchor.d.ts

@@ -0,0 +1,106 @@
+import { Scalar } from '@sheetxl/primitives';
+import { ISparseGrid } from '../collections';
+import { ICellRange } from '../cellRange';
+import { ICalcGrid, FormulaHost } from '../calculation/grid';
+import { ListenerAnchor } from './_ListenerAnchor';
+/**
+ * A listener node that owns a formula: the location of a watch.
+ *
+ * @remarks
+ * A watch is a range listener that fires on formula evaluation. Its LOCATION has the semantics of
+ * a reference - it grows when a row is inserted inside it, travels with a cut that encloses it,
+ * goes `#REF!` when its cells are deleted and comes back on undo - which is exactly what a node in
+ * the sheet's anchored `listeners` map gets, so that is what this is. Its BODY is one formula block
+ * in a grid of its own that shadows the sheet (see {@link FormulaHost}), written at the watched
+ * cells as if it had been typed there, and from then on the graph does for it everything a cell
+ * formula gets: precedents, dirty marking, the reference rewrite a structural change does, `#REF!`.
+ *
+ * The body FOLLOWS the node, by one rule ({@link reconcile}): whenever the node's address changes,
+ * the body is re-imaged at the node's coords; when the node has no coords, the body is cleared.
+ * The body's grid is never shifted geometrically.
+ *
+ * The node is shared by every snapshot that holds it (as a listener node is: `delete`/`undelete`
+ * mark the instance), so what is here is what is true of the watch regardless of snapshot: the
+ * host, a handle that resolves its grid by id, and what was last delivered. The callbacks are NOT
+ * here - they live on the sheet instance keyed by node id, as every listener's do, and an entry
+ * that is gone is what makes a node left behind in an older snapshot inert.
+ *
+ * @internal
+ */
+export declare class WatchAnchor extends ListenerAnchor {
+    /** Holds the body. */
+    readonly host: FormulaHost;
+    /** The grid's values as of the last delivery, so a pass that changed nothing is not re-delivered. */
+    protected _lastValues: ISparseGrid<Scalar> | null;
+    /** The body's blank region as of the last delivery - the part of the answer the grid does not hold. */
+    protected _lastBlank: ICalcGrid.BlankRegion | null;
+    constructor(options: WatchAnchor.ConstructorOptions);
+    /**
+     * Hand the body's values to the watch after a pass, when something inside the location changed.
+     *
+     * @remarks
+     * The values go out as a VIEW over the grid's own sparse values at the location, `(0, 0)` at its
+     * top-left - nothing is materialized, however large the body; the caller reads what it reads.
+     *
+     * Delivered only when something inside the location is different from the last delivery: a
+     * restore runs more than one pass today and every pass reports the body, and a pass that
+     * recomputed a cell to the value it already had is not a change the caller was promised. The
+     * previous values are gone by the time the pass reports, so the compare is against a
+     * copy-on-write clone of the values taken at the last delivery (`SparseGrid.clone` shares its
+     * storage until the grid writes), and it is bounded by what the pass WROTE (`results.bounds`)
+     * intersected with the location. It walks what either grid STORES there rather than every cell
+     * of the window: the body's blank region is not stored at all (its one answer is on the block,
+     * compared as one value), so a rule over an entire sheet compares its touched cells and a value.
+     *
+     * @param results What the pass wrote to the body's grid.
+     * @param handlers Where to deliver; `onChange` alone is told of every pass that wrote the body.
+     */
+    deliver(results: ICalcGrid.Results, handlers: WatchAnchor.Handlers): void;
+    /**
+     * Bring the body to the location.
+     *
+     * @remarks
+     * Read against the map the sheet is currently at, so a split or a drop the map did is covered
+     * by the same rule as a move. The body is re-imaged from its OWN top-left: the engine's shift of
+     * the sheet has already rewritten the body's references to follow the cells they name (the body
+     * is a formula on another grid to that shift), so the text at the block's top-left already reads
+     * the right cells, and writing that text at the new location keeps it on them - which is
+     * Excel's rule for a cut formula, and for an insert it is the same rule with the references
+     * having moved by the same amount as the location.
+     *
+     * An insert INSIDE the location is the case a formula block does not handle on its own (a cell
+     * formula does not fill a new row): the node grew, the block did not, and the re-image over the
+     * node's extent is what fills the new cells.
+     */
+    reconcile(): void;
+}
+/** @internal */
+export declare namespace WatchAnchor {
+    interface ConstructorOptions extends ListenerAnchor.ConstructorOptions {
+        host: FormulaHost;
+    }
+    /** {@link ICellRange.WatchOptions}, and what only an owner inside the sdk asks for. */
+    interface Options extends ICellRange.WatchOptions {
+        /**
+         * Evaluate the body's blank region a tile at a time, when its answer there depends on the
+         * position: see `CalcGridBackend.ConstructorOptions.paged`. The owner asks for what it reads
+         * through {@link FormulaHost.request}; a cell it has not asked for holds nothing.
+         */
+        paged?: boolean;
+    }
+    /** What a watch is told. Held by the sheet, never by the node. */
+    interface Handlers {
+        /** The body's values after every pass that changed them. */
+        onValues?: ICellRange.WatchCallback;
+        /** That a pass evaluated the body, without the values. */
+        onChange?: () => void;
+        /** The body's host, once registered — for an owner that reads the body back. */
+        onRegistered?: (host: FormulaHost) => void;
+        /**
+         * The registration was undone by a rollback of the operation it was made in: the node and the
+         * body are gone, and nothing will deliver. An owner waiting on a delivery must stop waiting.
+         */
+        onRemoved?: () => void;
+    }
+}
+//# sourceMappingURL=_WatchAnchor.d.ts.map