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

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

@@ -1,26 +1,26 @@
 import { IRange, Scalar, InteropScalar, IRangeStats, IRuntime } from '@sheetxl/primitives';
 import { CoordUtils, Size, Bounds, Point } from '@sheetxl/utils';
 import { ITypes, ICollection, IProperties } from '../type';
-import { IWorkbook } from '../workbook';
-import { IListener } from '../listener';
 import { ITransaction } from '../transaction';
-import { BatchHandle } from '../transaction/_BatchHandle';
+import { IListener } from '../listener';
 import { IResource, IResourceCollection } from '../resource';
 import { IStringCollection } from '../string';
 import { IProtection } from '../protection';
 import { IComment, ICommentCollection } from '../comment';
 import { IColor } from '../color';
 import { IHyperlink } from '../hyperlink';
+import { IWorkbook } from '../workbook';
 import { ISort } from '../sort';
 import { IAutoFill } from '../autoFill';
+import { ITable, ITableCollection } from '../table';
+import { INamedCollection } from '../named';
+import { IModuleCollection } from '../scripting';
+import { BatchHandle } from '../transaction/_BatchHandle';
 import { IAnchored } from '../anchored';
 import { Anchored } from '../anchored/Anchored';
 import { IAnchoredMap } from '../anchored/IAnchoredMap';
-import { ITable, ITableCollection } from '../table';
 import { NamedTableSource } from '../table/_NamedTableSource';
 import { AnchoredTable } from '../table/AnchoredTable';
-import { INamedCollection } from '../named';
-import { IModuleCollection } from '../scripting';
 import { ModuleCollection } from '../scripting/ModuleCollection';
 import { IMovable, IMovableCollection } from '../movable';
 import { Movable } from '../movable/Movable';
@@ -29,15 +29,17 @@ import { IChartCollection } from '../chart';
 import { IPicture } from '../picture';
 import { InsertableCollection } from '../movable/_InsertableCollection';
 import { IPivotTable, IPivotTableCollection } from '../pivot';
-import { IDataTable, IDataTableCollection } from '../dataTable';
-import { AnomalyFindings, AnomalySet, AnomalySource, RoleSource } from './_Anomalies';
+import { AnomalyFindings, AnomalySet, AnomalySource, RoleSource } from '../anomalies/_Anomalies';
 import { CellKind } from './_Kinds';
+import { IRichDataKind } from '../richData/IRichDataKind';
+import { IRichDataCollection } from '../richData/IRichDataCollection';
 import { ICell } from '../cell';
 import { ICellRange, ICellRegions, ICellRanges } from '../cellRange';
 import { ICellStyle, IStyleCollection } from '../style';
 import { IRangeSelection } from '../selection';
 import { IConditionalFormat, IConditionalFormatCollection } from '../conditionalFormat';
 import { IProtectedRange, IProtectedRangeCollection } from '../protectedRange';
+import { ICellControl, ICellControlCollection } from '../cellControl';
 import { Tuple, ISpatialMap, ISpatialQuery } from '../collections';
 import { ListenerEmitter } from '../listener/ListenerEmitter';
 import { ICondition } from '../condition';
@@ -45,6 +47,7 @@ import { ConditionalFormat } from '../conditionalFormat/ConditionalFormat';
 import { IDataValidationCollection, IDataValidation } from '../dataValidation';
 import { DataValidation } from '../dataValidation/DataValidation';
 import { ProtectedRange } from '../protectedRange/ProtectedRange';
+import { CellControl } from '../cellControl/CellControl';
 import { Comment } from '../comment/Comment';
 import { NoteMovable } from '../comment/NoteMovable';
 import { NoteLayout } from '../comment/_NoteBox';
@@ -72,9 +75,9 @@ import { ProtectionCheck } from './_SheetCoords';
 import { WorksheetProtection } from '../sheetProtection/WorksheetProtection';
 import { Outline } from '../outline/Outline';
 import { PageLayout } from '../print/PageLayout';
-import { SheetCellOptions } from './SheetCell';
 import { ICalculation } from '../calculation';
 import { ICalcGrid } from '../calculation/grid';
+import { SheetCellOptions } from './SheetCell';
 import * as _SheetFilterUtils from './_SheetFilterUtils';
 /** The font colors a workbook writes its roles in, and a key that compares by content. */
 interface WorkbookRoleColors {
@@ -153,7 +156,14 @@ export declare class Worksheet implements IWorksheet {
     protected _strings: IStringCollection;
     /** Makes the lists cell values are stored as, over `_strings`. */
     protected _lists: ScalarListFactory;
+    /** What rich values written to or loaded into this sheet are made for. */
+    protected _richData: IRichDataKind.Context;
+    /** The resource ids of the file being read; unset outside a read. */
+    protected _readingResources: IResourceCollection.IPersistScope<IResource.JSON> | null;
     protected _ownStrings: boolean;
+    /** The rich values the sheet's runs hold by id: the workbook's, or the sheet's own. */
+    protected _richValues: IRichDataCollection;
+    protected _ownRichValues: boolean;
     protected _styles: IStyleCollection;
     protected _ownStyles: boolean;
     protected _stylesRemoveListener: IListener.Remove;
@@ -187,8 +197,6 @@ export declare class Worksheet implements IWorksheet {
     protected _legacyDrawingHF: LegacyDrawing | null;
     /** The sheet's pivot tables, held as read for the same reason. */
     protected _pivotTableCollection: IPivotTableCollection;
-    /** The sheet's data tables, carried as read. */
-    protected _dataTableCollection: IDataTableCollection;
     /**
      * Anchored items whose delete this sheet announced itself.
      *
@@ -216,6 +224,7 @@ export declare class Worksheet implements IWorksheet {
     protected _conditionals: IConditionalFormatCollection;
     protected _dataValidations: IDataValidationCollection;
     protected _protectedRanges: IProtectedRangeCollection;
+    protected _cellControls: ICellControlCollection;
     protected _comments: ICommentCollection;
     protected _movables: IMovableCollection;
     protected _charts: IChartCollection;
@@ -253,6 +262,12 @@ export declare class Worksheet implements IWorksheet {
         coords: IRange.Coords | null;
         range: ICellRange | null;
     };
+    /**
+     * Set while a cut on a protected sheet moves its cells, which it ruled on before it began (see
+     * `_copyFromNow`): the move's own steps (its clears, the rules it re-anchors) do not rule again,
+     * since the first of them changes the cells the next would read. Synchronous, like the move.
+     */
+    protected _isMoveRuled: boolean;
     protected _lastRangeRead: {
         address: ICellRange.Address | null;
         range: ICellRange | null;
@@ -374,7 +389,7 @@ export declare class Worksheet implements IWorksheet {
         autoFit: (ranges: readonly IRange.Coords[], options?: ICellRange.AutoFitOptions, holdWhileLoading?: boolean) => void;
         getBestFit: (range: IRange.Coords, options?: ICellRange.BestFitOptions) => Size;
         invalidateRendering: (axes?: IRange.AxisSelection | null) => void;
-        addListenerNode: (ranges: readonly IRange.Coords[], listener: ICellRange.Listener, options?: ICellRange.ListenerOptions) => IListener.Remove;
+        addListenerNode: (ranges: readonly IRange.Coords[], listener: ICellRange.Listener<any>, options?: ICellRange.ListenerOptions, collection?: boolean) => IListener.Remove;
         addWatch: (coords: IRange.Coords, formula: ICalculation.IFormula | string, handlers: WatchAnchor.Handlers, origin?: IRange.CellCoords, options?: WatchAnchor.Options) => IListener.Remove;
         surroundingRegion: (range: IRange.Coords, options?: ICellRange.GetSurroundingOptions) => IRange.Coords;
         getTraverseRegion: (cell: IRange.CellCoords, axis: IRange.Axis, reverse: boolean) => IRange.Coords | null;
@@ -384,6 +399,7 @@ export declare class Worksheet implements IWorksheet {
         applyFilterRuns: (runs: _SheetFilterUtils.FilterRuns, options?: ITransaction.OperationOptions) => void;
         filteredTables: () => ITable[];
         setHyperlinks: (ranges: readonly ISpatialMap.Entry<IHyperlink.Update>[], defaultUpdate?: IHyperlink.Update, options?: ITransaction.OperationOptions) => void;
+        setCellControl: (address: ICellRanges.Address, control: ICellControl.JSON | null, options?: ITransaction.OperationOptions) => ICellControl | null;
         setErrorIgnored: (ranges: readonly IRange.Coords[], check: ICell.ErrorCheck, ignored: boolean, options?: ITransaction.OperationOptions) => void;
         setComments: (ranges: readonly ISpatialMap.Entry<IComment.Update>[], comments?: IComment.Update | IComment.JSON, options?: ITransaction.OperationOptions) => void;
         getBoundsAtCoords: (coords: IRange.Coords) => Bounds;
@@ -492,19 +508,6 @@ export declare class Worksheet implements IWorksheet {
      * @internal
      */
     protected _getKinds(): ISpatialMap<CellKind>;
-    /**
-     * The sheet's grid: the synchronous half of the calculation service for this sheet
-     * (DESIGN-CALC-SERVICE §13.23, §13.24), holding everything a cell contains - the formulas, the
-     * values and the indexes over them - and forwarding every verb to its backend.
-     *
-     * @remarks
-     * A plain field, NOT part of `State` (§13.24 a): one grid serves every version of the sheet, so
-     * a versioned slot would answer with the CURRENT maps from a historic record - which the sheet
-     * reads (`_resolveInheritedFormats`, the snapshot sheets). What the grid HOLDS versions, in its
-     * own record; its reads take the transaction to answer for. Opened by `_fromJSON`, so it is
-     * absent until then; a snapshot sheet is handed the source's grid by `_clone`.
-     * @internal
-     */
     protected _calcGrid: ICalcGrid;
     /** `false` for a snapshot sheet, which holds its source's grid and must not close it. */
     protected _ownsCalcGrid: boolean;
@@ -535,6 +538,8 @@ export declare class Worksheet implements IWorksheet {
         invalidateUsedCoords: () => void;
         validateCoords: (coords: IRange.Coords, oobMessage?: string, allowOutOfBounds?: boolean) => void;
         protectionCheck: (check?: ProtectionCheck | null, coords?: Readonly<IRange.Coords> | readonly IRange.Coords[] | null, action?: string | null) => void;
+        assertContentEditable: (ranges: readonly IRange.Coords[], viaRanges?: boolean) => boolean;
+        isMoveRuled: () => boolean;
         getDefaultShiftAxis: (coords?: IRange.Coords) => IRange.Axis;
         processLayoutChange: () => void;
         /** The movables' by-model index as a shift left it, or `null` if the shift moved none. */
@@ -568,6 +573,7 @@ export declare class Worksheet implements IWorksheet {
         readonly isDataColumn: boolean;
         readonly strings: IStringCollection;
         readonly lists: ScalarListFactory;
+        readonly richData: IRichDataKind.Context;
         readonly cellOptions: SheetCellOptions;
         readonly runtime: IRuntime;
         getProtection: () => IWorksheetProtection;
@@ -646,7 +652,7 @@ export declare class Worksheet implements IWorksheet {
             autoFit: (ranges: readonly IRange.Coords[], options?: ICellRange.AutoFitOptions, holdWhileLoading?: boolean) => void;
             getBestFit: (range: IRange.Coords, options?: ICellRange.BestFitOptions) => Size;
             invalidateRendering: (axes?: IRange.AxisSelection | null) => void;
-            addListenerNode: (ranges: readonly IRange.Coords[], listener: ICellRange.Listener, options?: ICellRange.ListenerOptions) => IListener.Remove;
+            addListenerNode: (ranges: readonly IRange.Coords[], listener: ICellRange.Listener<any>, options?: ICellRange.ListenerOptions, collection?: boolean) => IListener.Remove;
             addWatch: (coords: IRange.Coords, formula: ICalculation.IFormula | string, handlers: WatchAnchor.Handlers, origin?: IRange.CellCoords, options?: WatchAnchor.Options) => IListener.Remove;
             surroundingRegion: (range: IRange.Coords, options?: ICellRange.GetSurroundingOptions) => IRange.Coords;
             getTraverseRegion: (cell: IRange.CellCoords, axis: IRange.Axis, reverse: boolean) => IRange.Coords | null;
@@ -656,6 +662,7 @@ export declare class Worksheet implements IWorksheet {
             applyFilterRuns: (runs: _SheetFilterUtils.FilterRuns, options?: ITransaction.OperationOptions) => void;
             filteredTables: () => ITable[];
             setHyperlinks: (ranges: readonly ISpatialMap.Entry<IHyperlink.Update>[], defaultUpdate?: IHyperlink.Update, options?: ITransaction.OperationOptions) => void;
+            setCellControl: (address: ICellRanges.Address, control: ICellControl.JSON | null, options?: ITransaction.OperationOptions) => ICellControl | null;
             setErrorIgnored: (ranges: readonly IRange.Coords[], check: ICell.ErrorCheck, ignored: boolean, options?: ITransaction.OperationOptions) => void;
             setComments: (ranges: readonly ISpatialMap.Entry<IComment.Update>[], comments?: IComment.Update | IComment.JSON, options?: ITransaction.OperationOptions) => void;
             getBoundsAtCoords: (coords: IRange.Coords) => Bounds;
@@ -870,7 +877,7 @@ export declare class Worksheet implements IWorksheet {
     protected _realizeCalcedValues(results: ICalcGrid.Results): void;
     /**
      * Tell listener nodes what calculation passes realized. A pass belongs to no commit, so the
-     * event carries no transaction id.
+     * event carries none: a `'data'` change with a `null` commit.
      * @internal
      */
     protected _notifyPassToListenerNodes(ranges: readonly IRange.Coords[]): void;
@@ -1077,8 +1084,17 @@ export declare class Worksheet implements IWorksheet {
      * @internal
      */
     protected _getBestFit(range: IRange.Coords, options?: ICellRange.BestFitOptions): Size;
-    /** @internal */
-    protected _createRangeEvent(coords: (readonly IRange.FixableCoords[]) | IRange.FixableCoords, options: NotifierOptions, coordsFrom?: (readonly IRange.FixableCoords[]) | IRange.FixableCoords): ICellRange.Event;
+    /**
+     * The event one delivery hands a listener.
+     *
+     * @param coords Where the node is now; `null` when this snapshot does not hold it.
+     * @param changed The cells a `'data'` change reached, for {@link ICellRange.Event.getRanges}.
+     * @param previous Where the node was before an `'address'` move, for
+     * {@link ICellRange.Event.getPreviousAddress}.
+     *
+     * @internal
+     */
+    protected _createRangeEvent(coords: readonly IRange.FixableCoords[] | null, options: RangeEventOptions, changed?: readonly IRange.FixableCoords[], previous?: readonly IRange.FixableCoords[] | null): ICellRange.Event<ICellRange | ICellRanges>;
     /**
      * Register a reference node for a range listener.
      *
@@ -1093,12 +1109,15 @@ export declare class Worksheet implements IWorksheet {
      *
      * @internal
      */
-    protected _addListenerNode(ranges: readonly IRange.Coords[], listener: ICellRange.Listener, options?: ICellRange.ListenerOptions): IListener.Remove;
+    protected _addListenerNode(ranges: readonly IRange.Coords[], listener: ICellRange.Listener<any>, options?: ICellRange.ListenerOptions, collection?: boolean): IListener.Remove;
     /**
      * {@link _addListenerNode}, also handing back the node, for a caller that reads its coords.
+     *
+     * @param collection The listener registered on an `ICellRanges`, and is handed one as its
+     * source; otherwise it registered on one range and is handed a range.
      * @internal
      */
-    protected _registerListenerNode(ranges: readonly IRange.Coords[], listener: ICellRange.Listener, options?: ICellRange.ListenerOptions, createNode?: (options: ListenerAnchor.ConstructorOptions) => ListenerAnchor): {
+    protected _registerListenerNode(ranges: readonly IRange.Coords[], listener: ICellRange.Listener<any>, options?: ICellRange.ListenerOptions, createNode?: (options: ListenerAnchor.ConstructorOptions) => ListenerAnchor, collection?: boolean): {
         node: ListenerAnchor;
         remove: IListener.Remove;
     };
@@ -1254,7 +1273,7 @@ export declare class Worksheet implements IWorksheet {
      *
      * @internal
      */
-    protected _deliverToNode(entry: ListenerNodeEntry, trigger: 'data' | 'address' | 'restore', notificationOptions: NotifierOptions, from?: readonly IRange.Coords[]): void;
+    protected _deliverToNode(entry: ListenerNodeEntry, trigger: ICellRange.Event.Trigger, notificationOptions: NotifierOptions, changed?: readonly IRange.Coords[], previous?: readonly IRange.Coords[] | null): void;
     /** @internal */
     protected _notifyUsedRangeChange(): void;
     /** @internal */
@@ -1297,6 +1316,8 @@ export declare class Worksheet implements IWorksheet {
     /** {@inheritDoc Sheet._notifyConditionalFormatsChange} @internal */
     protected _notifyProtectedRangesChange(): void;
     /** {@inheritDoc Sheet._notifyConditionalFormatsChange} @internal */
+    protected _notifyCellControlsChange(): void;
+    /** {@inheritDoc Sheet._notifyConditionalFormatsChange} @internal */
     protected _notifyCommentsChange(): void;
     /**
      * Presents one of the sheet's own events as a collection's `onCollectionChange`, and the
@@ -1307,7 +1328,7 @@ export declare class Worksheet implements IWorksheet {
      * it. Forwarding, rather than a second emitter, is what keeps the two from drifting apart.
      * @internal
      */
-    protected _forwardCollectionListeners(key: 'onTablesChange' | 'onConditionalFormatsChange' | 'onDataValidationsChange' | 'onProtectedRangesChange' | 'onCommentsChange', collection: () => ICollection<any>): (listeners: ICollection.IListeners, options?: IListener.Options) => IListener.Remove;
+    protected _forwardCollectionListeners(key: 'onTablesChange' | 'onConditionalFormatsChange' | 'onDataValidationsChange' | 'onProtectedRangesChange' | 'onCellControlsChange' | 'onCommentsChange', collection: () => ICollection<any>): (listeners: ICollection.IListeners, options?: IListener.Options) => IListener.Remove;
     /** {@inheritDoc IWorksheet.addListeners} */
     addListeners(listeners: IWorksheet.IListeners, options?: IListener.Options): IListener.Remove;
     /** @internal */
@@ -1594,6 +1615,19 @@ export declare class Worksheet implements IWorksheet {
      * @internal
      */
     protected _isProtectionRuled(): boolean;
+    /**
+     * Refuse a content write on a locked sheet unless every cell of `ranges` is editable, by
+     * {@link ICell.isEditAllowed}'s rule: an always-unlocked style, or a covering protected range that
+     * is unlocked (a password-gated one only after `unlock`). Answered per stored block over the
+     * blocks {@link ICellRange.getRegions | getRegions(Unlock)} walks, never per cell.
+     *
+     * @param viaRanges Whether an unlocked protected range makes a cell editable. A cut asks for the
+     * cell's own style alone, as Excel does.
+     * @returns Whether the sheet is locked. A locked sheet's caller then writes content only (no
+     * formats) and stands the commit-time catch-all down, since this has ruled.
+     * @internal
+     */
+    protected _assertContentEditable(ranges: readonly IRange.Coords[], viaRanges?: boolean): boolean;
     /**
      * Record that this commit is a load of the sheet: not a user's write, so the protection check
      * stands down, and not an edit, so nothing it wrote is announced. See {@link IntentInitial}.
@@ -1730,14 +1764,6 @@ export declare class Worksheet implements IWorksheet {
     getRowHeaders(): ISheetHeader;
     /** {@inheritDoc IWorksheet.getColumnHeaders} */
     getColumnHeaders(): ISheetHeader;
-    /**
-     * The sheet's grid, whatever the calculation hands back (DESIGN-CALC-SERVICE §5): opened from
-     * `json` (§6.6), the file's formulas, array extents and cached values, trusted. What the engine
-     * makes of them arrives through the grid's `onComplete`, before this returns when the engine is
-     * `Running`. The grid holds every cell map, and answers an `Off` save and a start's seed itself.
-     * A snapshot sheet over another sheet's state (a copy) shares the grid: the owner answers, with
-     * the state as it is now.
-     */
     protected _openCalcGrid(json: ICalcGrid.JSON | undefined): ICalcGrid;
     /** {@inheritDoc IWorksheet.toJSON} */
     toJSON(options?: IWorksheet.ToJSONOptions): Promise<IWorksheet.JSON>;
@@ -1854,23 +1880,6 @@ export declare class Worksheet implements IWorksheet {
     setPicture(picture: string | IResource | IResourceCollection.AddOptions | null, options?: ITransaction.OperationOptions): this;
     /** {@inheritDoc IWorksheet.getPicture} */
     getPicture(): IPicture | null;
-    /** {@inheritDoc IWorksheet.getDataTables} */
-    getDataTables(): IDataTableCollection;
-    /**
-     * An edit to cell data, here or on any sheet, can change what every data table in the workbook
-     * would calculate, and nothing recalculates their results. Marks each to be recalculated by Excel
-     * when it opens the file ({@link IDataTable.JSON.calculateAlways}).
-     *
-     * TODO - A stand-in until the engine evaluates `TABLE`. A data table is a calculation: each result
-     * is the table's formula evaluated with that cell's row and column values put in the input cells.
-     * The engine should own it like an array block, its dependencies being the formula's plus the
-     * input cells and the row and column values, and recalculate it when one changes. Its results
-     * are then never stale, `calculateAlways` stays as read, and this method and
-     * `DataTable._markStale` go. Until then it marks every table on any data edit, because which
-     * cells the formula depends on is only known to the engine.
-     * @internal
-     */
-    protected _markDataTablesStale(): void;
     /** {@inheritDoc IWorksheet.getPivotTables} */
     getPivotTables(): IPivotTableCollection;
     /** {@inheritDoc IWorksheet.getTables} */
@@ -1881,6 +1890,8 @@ export declare class Worksheet implements IWorksheet {
     getConditionalFormats(): IConditionalFormatCollection;
     /** {@inheritDoc IWorksheet.getProtectedRanges} */
     getProtectedRanges(): IProtectedRangeCollection;
+    /** {@inheritDoc IWorksheet.getCellControls} */
+    getCellControls(): ICellControlCollection;
     /** {@inheritDoc IWorksheet.getComments} */
     getComments(): ICommentCollection;
     /** @deprecated Use {@link IWorksheet.getConditionalFormats} */
@@ -1891,16 +1902,6 @@ export declare class Worksheet implements IWorksheet {
     getCharts(): IChartCollection;
     /** @internal */
     protected _validateOrRemoveOverlaps(rangeCoords: IRange.Coords, type: string, table?: ITable | null, removeIfContains?: boolean, absorbAutoTable?: boolean): void;
-    /**
-     * The filter and sort criteria a sheet AutoFilter hands over to a table built in its place.
-     *
-     * @remarks
-     * Read BEFORE `_validateOrRemoveOverlaps` absorbs the AutoFilter and replayed once the table
-     * exists. Excel moves them across only when the table takes EXACTLY the AutoFilter's range —
-     * probed: one extra row or column, or a shifted start, and the new table starts clean. Answers
-     * `null` when there is nothing to carry, which is the common case.
-     * @internal
-     */
     protected _getAutoTableCarryOver(rangeCoords: IRange.Coords): {
         conditions: ICondition.Input[];
         sorts: ISort.Options[];
@@ -1922,7 +1923,7 @@ export declare class Worksheet implements IWorksheet {
         toJSON(): J | null;
     }, J extends object>(add: ICellRanges.Address | T | null | undefined, options: (IAnchored.AddOptions & J) | undefined, spec: {
         /** The sheet-state slot the collection lives in. */
-        key: 'conditionalFormats' | 'dataValidations' | 'protectedRanges' | 'comments';
+        key: 'conditionalFormats' | 'dataValidations' | 'protectedRanges' | 'cellControls' | 'comments';
         /**
          * The sheet-protection allowances the add needs. Empty when no option allows it, so the add is
          * refused whenever the sheet is locked.
@@ -1962,6 +1963,23 @@ export declare class Worksheet implements IWorksheet {
      * @internal
      */
     protected _addProtectedRange(add: ICellRanges.Address | IProtectedRange, options?: IProtectedRangeCollection.AddOptions): IProtectedRange;
+    /**
+     * @internal
+     */
+    protected _addCellControl(address: ICellRanges.Address, control: ICellControl.JSON, options?: ITransaction.OperationOptions): ICellControl;
+    /**
+     * Makes `control` the control of every cell of `address`, or removes the cells' controls when
+     * it is `null`. The write behind `ICellRange.setControl` and `ICellControlCollection.add`.
+     *
+     * @returns The control placed, or `null` for a removal.
+     *
+     * @remarks
+     * A cell has at most one control, so the cells leave whatever control they had. They join a
+     * control of the same definition when the sheet already has one, so repeated writes do not mint
+     * a control each.
+     * @internal
+     */
+    protected _setCellControl(address: ICellRanges.Address, control: ICellControl.JSON | null, options?: ITransaction.OperationOptions): ICellControl | null;
     /**
      * @internal
      */
@@ -2051,16 +2069,6 @@ export declare class Worksheet implements IWorksheet {
     protected _getStyle(ranges: IRange.Coords[], anchor?: IRangeSelection.Coords, updateStyles?: (update: ICellStyle.Update, options?: ICellStyle.UpdateOptions) => void): ICellStyle;
     /** @internal */
     protected _initHeadersState(jsonColumns?: ISheetHeader.JSON, jsonRows?: ISheetHeader.JSON): void;
-    /**
-     * Tells the grid which rows or columns are hidden now, from inside the operation that changed
-     * them: the formulas that skip hidden cells recalculate under that operation.
-     *
-     * @remarks
-     * A restore is heard here too, with no operation open, and is not told: the grid's record of
-     * the set is restored with the sheet's, and the engine's with its own history
-     * (DESIGN-CALC-SERVICE §7.5). Telling it as well would land the restored set under the snapshot
-     * being left.
-     */
     protected _tellHidden(axis: IRange.Axis): void;
     /**
      * Drop every read-through cache that a data change can invalidate.
@@ -2106,6 +2114,8 @@ export declare class Worksheet implements IWorksheet {
     protected _createConditionalFormats(conditionalFormats: IAnchoredMap<IConditionalFormat, IConditionalFormat.JSON>, key: keyof State, refs: IRange.JSONReference<IConditionalFormat.JSON>[], createModel: (options: ConditionalFormat.ConstructorOptions) => IConditionalFormat, addListeners?: (model: IConditionalFormat) => IListener.Remove): IAnchoredMap<IConditionalFormat, IConditionalFormat.JSON>;
     /** @internal */
     protected _createProtectedRanges(protectedRanges: IAnchoredMap<IProtectedRange, IProtectedRange.JSON>, key: keyof State, refs: IRange.JSONReference<IProtectedRange.JSON>[], createModel: (options: ProtectedRange.ConstructorOptions) => IProtectedRange, addListeners?: (model: IProtectedRange) => IListener.Remove): IAnchoredMap<IProtectedRange, IProtectedRange.JSON>;
+    /** @internal */
+    protected _createCellControls(cellControls: IAnchoredMap<ICellControl, ICellControl.JSON>, key: keyof State, refs: IRange.JSONReference<ICellControl.JSON>[], createModel: (options: CellControl.ConstructorOptions) => ICellControl): IAnchoredMap<ICellControl, ICellControl.JSON>;
     /**
      * Loads the pivot tables into their anchored map, each anchored where its part says it sits.
      * The map moves and deletes them with structural edits; the table itself rules on the edit
@@ -2113,13 +2123,6 @@ export declare class Worksheet implements IWorksheet {
      * @internal
      */
     protected _createPivotTables(pivotTables: IAnchoredMap<IPivotTable, IPivotTable.JSON>, key: keyof State, refs: IRange.JSONReference<IPivotTable.JSON>[], fromResourceId?: (resourceId: number) => IResource): IAnchoredMap<IPivotTable, IPivotTable.JSON>;
-    /**
-     * Loads the data tables into their anchored map, each anchored on its result cells, its input
-     * cells held in the engine. The table rules on structural edits itself
-     * (`DataTable._processContainerShift`).
-     * @internal
-     */
-    protected _createDataTables(dataTables: IAnchoredMap<IDataTable, IDataTable.JSON>, key: keyof State, refs: IRange.JSONReference<IDataTable.JSON>[]): IAnchoredMap<IDataTable, IDataTable.JSON>;
     /** @internal */
     protected _createComments(comments: IAnchoredMap<IComment, IComment.JSON>, key: keyof State, refs: IRange.JSONReference<IComment.JSON>[], createModel: (options: Comment.ConstructorOptions) => IComment, addListeners?: (model: IComment) => IListener.Remove): IAnchoredMap<IComment, IComment.JSON>;
     /**
@@ -2184,26 +2187,16 @@ export declare class Worksheet implements IWorksheet {
  */
 export declare function createCellRangeCounts(counts: Readonly<Record<ICellRange.Feature, number>>): ICellRange.Counts;
 /**
- * Used for signalling tupleUpdate was called via private apis.
- * This allows use to 'avoid side effects' and skip validation checks.
+ * The change a round of listener deliveries reports; what each delivery adds is
+ * {@link RangeEventOptions}.
  * @internal
  */
 interface NotifierOptions {
-    /**
-     * Which error an invalid source reports - `#REF!` when the cells were deleted, `#N/A` when the
-     * world predates the listener.
-     *
-     * @defaultValue `#REF!`
-     */
-    invalidError?: string;
-    isDataChange?: boolean;
-    getTransactionId: () => string;
+    /** The commit that made the change; `null` for a calculation pass, which belongs to none. */
+    commit: ITransaction.ICommit | null;
+    /** The change is an undo. */
     isUndo?: boolean;
-    isRestoreOrRevert?: boolean;
-    trigger?: string;
-    /** Spell the source with its sheet qualifier (a workbook range), as the listener registered it. */
-    qualified?: boolean;
-    from?: ICellRanges;
+    /** When the change was made; now, when omitted. */
     timeStamp?: number;
 }
 interface TableColumnHeaders {
@@ -2219,11 +2212,31 @@ interface TableColumnHeaders {
  * A live range listener: its node in the versioned map, and the callback the map must never hold.
  * @internal
  */
+/**
+ * What one delivery adds to the change it reports.
+ * @internal
+ */
+interface RangeEventOptions extends NotifierOptions {
+    trigger: ICellRange.Event.Trigger;
+    /** Spell the source with its sheet qualifier (a workbook range), as the listener registered it. */
+    qualified?: boolean;
+    /** Hand the source as an `ICellRanges`, as the listener registered on one. */
+    collection?: boolean;
+    /**
+     * Which error an invalid source reports - `#REF!` when the cells were deleted, `#N/A` when the
+     * world predates the listener.
+     *
+     * @defaultValue `#REF!`
+     */
+    invalidError?: string;
+}
 interface ListenerNodeEntry {
     node: ListenerAnchor;
-    handler: ICellRange.Listener | null;
-    handlerW: WeakRef<ICellRange.Listener> | null;
+    handler: ICellRange.Listener<any> | null;
+    handlerW: WeakRef<ICellRange.Listener<any>> | null;
     options: ICellRange.ListenerOptions;
+    /** Registered on an `ICellRanges`: the source is handed as one. */
+    collection: boolean;
     /** The coords last delivered, so a restore can tell whether the reference moved. */
     lastCoords: IRange.Coords[] | null;
     /**

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

@@ -0,0 +1,13 @@
+import { IFormulaContext, IRuntime, Scalar } from '@sheetxl/primitives';
+/**
+ * Reads delimited text into rows of values, each field read as typed entry: what
+ * `IDeferContext.parseText` answers, and what a CSV import writes.
+ *
+ * @remarks
+ * Empty fields are blank. A last line with nothing on it is the file's closing newline, not a row.
+ * Rows are padded with blanks to the widest.
+ *
+ * @internal
+ */
+export declare const parseDelimitedText: (runtime: IRuntime, text: string, options?: IFormulaContext.IDeferContext.ParseTextOptions) => Promise<Scalar[][]>;
+//# sourceMappingURL=_DelimitedText.d.ts.map

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

@@ -11,18 +11,6 @@ import { IWorksheet } from './IWorksheet';
 export type ErrorCheckSet = readonly ICell.ErrorCheck[];
 /** The interned set of `checks`; `null` for none (an unknown name is dropped). */
 export declare function internChecks(checks: Iterable<ICell.ErrorCheck>): ErrorCheckSet | null;
-/**
- * The cells where Excel's error checks are ignored: one spatial map whose payload is the set of
- * checks a cell ignores. Presence is the ignore; an entry goes when its set empties. Immutable;
- * each change returns a new holder.
- *
- * @remarks
- * Excel's rules (`openpy-parity/probe-ignored-errors.ps1`, 2026-10-18): the regions move with
- * structural edits like cell content, an insert inside one splitting it; they are never copied
- * (copy, paste, fill, the destination of a cut); and writing or clearing a cell, contents or
- * formats, removes its ignores.
- * @internal
- */
 export declare class IgnoredErrors {
     static readonly Empty: IgnoredErrors;
     private readonly _map;

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

@@ -92,12 +92,18 @@ export declare namespace ListenerAnchor {
      * applies that when it writes a reference out (`TokenUtils`: an endpoint outside the sheet's
      * bounds is written as `#REF!`); the node applies it here, to the same effect.
      *
+     * That is the `TwoCell` rule, the default. The other anchor types are the movable's
+     * ({@link IAnchored.Type}): `OneCell` shifts the top-left as a one-cell reference and keeps the
+     * extent, staying put when that cell is deleted; `Absolute` never moves, so a view listening to
+     * the rows it shows keeps hearing about those rows.
+     *
      * Handed to the map as {@link IAnchoredMap.ConstructorOptions.shiftEntry}.
      *
      * @param details The shift, as the map describes it.
      * @param entire The bounds of the sheet the node is on.
+     * @param anchor How the node follows the shift. Defaults to `TwoCell`.
      */
-    function shiftReference(details: ISpatialMap.ShiftDetails, entire: IRange.Coords): IRange.Coords | null;
+    function shiftReference(details: ISpatialMap.ShiftDetails, entire: IRange.Coords, anchor?: IAnchored.Type): IRange.Coords | null;
     /** The container hooks a node registers; see {@link Anchored.ContainerCallbacks}. */
     type Callbacks = Anchored.ContainerCallbacks;
 }

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

@@ -1,29 +1,24 @@
-import { Scalar } from '@sheetxl/primitives';
+import { Scalar, IRichData } from '@sheetxl/primitives';
 import { IStringCollection } from '../string';
-import { ICell } from '../cell';
+import { IRichDataKind, IRichDataCollection } from '../richData';
 import { IListLike } from '../collections';
 import { MixedTypedArrayList } from '../collections/MixedTypedArrayList';
-/**
- * Makes the list a run of cell values is stored as, over the sheet's string collection.
- *
- * The representation is chosen from what the writer saw ({@link Tuple.Hint}) and the run's length,
- * never by looking at the values again:
- * - shorter than {@link ScalarListFactory.TypedThreshold}: a plain array (a typed list costs
- *   more than its values below that, measured at 64 on Node);
- * - one value throughout: a `RepeatingList` of period 1, which the engine reads once;
- * - holding rich data: a plain array (no pool for it yet);
- * - otherwise a {@link MixedTypedArrayList}, strings and errors by id.
- *
- * @internal
- */
 export declare class ScalarListFactory {
     /** Below this length a run is a plain array. */
     static readonly TypedThreshold = 64;
     readonly codec: MixedTypedArrayList.Codec<Scalar>;
     private readonly _strings;
+    private readonly _richData;
+    private readonly _richValues;
     private _codes;
     private _nums;
-    constructor(strings: IStringCollection);
+    /**
+     * @param richData What rich values loaded through this factory are made for; omitted, made
+     * outside any workbook.
+     * @param richValues Where a run stores its rich values by id; omitted, a run holding one is a
+     * plain array.
+     */
+    constructor(strings: IStringCollection, richData?: () => IRichDataKind.Context, richValues?: IRichDataCollection);
     /**
      * The list for a run a builder collected. Passed to `Tuple.Builder` as its `createList`.
      *
@@ -43,8 +38,42 @@ export declare class ScalarListFactory {
      *
      * @param values The run's JSON values. Never empty.
      * @param onError Called with the offset of every error value, for the error index.
+     * @param richAt The rich value a saved id names (the file's rich data table). A value saved
+     *   inline, as older files hold them, needs none.
+     */
+    fromJSONRun(values: readonly Scalar.JSON[], onError?: (offset: number) => void, richAt?: (id: number) => IRichData | null): IListLike<Scalar>;
+    /**
+     * One value as a file holds it, decoded on its own. {@link fromJSONRun} is the same decoding for
+     * a whole run, into a typed list.
+     *
+     * @param json The value. `null` and `undefined` are blank.
+     * @param decodeString Resolves a string id. Omitted, a string is the literal text (as an
+     * external link's cache holds it).
+     * @param richData What a rich value is made for; omitted, made outside any workbook.
+     */
+    static fromJSONValue(json: Scalar.JSON | null | undefined, decodeString?: (id: number) => string, richData?: IRichDataKind.Context): Scalar;
+    /**
+     * A run as a file holds it (`IWorksheet.JSON` data): the inverse of {@link fromJSONRun}.
+     *
+     * @param run A run as the grid stores it (a blank ends a run, so it holds none).
+     * @param addString Returns the persisted id for a string.
+     * @param toResourceId Returns the persisted id for a resource a rich value holds.
+     * @param addRich Returns the persisted id for a rich value; omitted, a rich value is written
+     *   inline.
+     */
+    static toJSONRun(run: IListLike<Scalar>, addString: (value: string) => number, toResourceId?: IRichData.ToResourceId, addRich?: (value: IRichData) => number): Scalar.JSON[];
+    /**
+     * One value as a run holds it in a file: the encoding {@link toJSONRun} applies to each. Numbers and
+     * booleans as they are, strings as their id (as a string), errors and rich data typed.
+     *
+     * @param value The value to encode. Never `null`.
+     * @param addString Returns the persisted id for a string.
+     * @param toResourceId Returns the persisted id for a resource a rich value holds.
+     * @param addRich Returns the persisted id for a rich value; omitted, a rich value is written
+     *   inline.
+     * @returns `undefined` for a value with no encoding.
      */
-    fromJSONRun(values: readonly ICell.JSON[], onError?: (offset: number) => void): IListLike<Scalar>;
+    static toJSONValue(value: Scalar, addString: (value: string) => number, toResourceId?: IRichData.ToResourceId, addRich?: (value: IRichData) => number): Scalar.JSON | undefined;
     /**
      * The list for a run whose values are already codes and numbers, as a file holds them: string
      * ids, error codes, ints and doubles. Nothing is resolved for a typed run; a short run is

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

@@ -3,13 +3,6 @@ import { ICell } from '../cell';
 import { ICellRange, ICellRanges } from '../cellRange';
 import { IWorksheetProtection } from '../sheetProtection';
 import { SheetCoordContext } from './Worksheet';
-/**
- * Coordinate/address resolution for a {@link Sheet}: parses addresses into coords, validates bounds,
- * runs protection checks, and constructs the `ICellRange`/`ICellRanges` handles. Functions take a
- * {@link SheetCoordContext} (the caches/options/collections they read) rather than the sheet
- * instance; `Sheet` keeps thin delegators. See `private-assets/design/SHEET-SPLIT-DESIGN.md` §5.
- * @internal
- */
 /**
  * A callback that, given the parsed coords of an operation, returns the protection keys the operation
  * requires. Passed to {@link rangesToCoords} / {@link rangeToCoords} / {@link protectionCheck} so the