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

package/types/src/scripting/Scripts.d.ts

@@ -12,6 +12,8 @@ export declare class Scripts implements IScript {
     private _modules;
     /** In-flight {@link start} run, so concurrent callers share one attempt (and one error). */
     private _startPromise?;
+    /** In-flight {@link _load} run, shared the same way. */
+    private _loadPromise?;
     protected _emitter: ListenerEmitter<IScript, IScript.IListeners>;
     constructor(options: Scripts.ConstructorOptions);
     protected _initState(): void;
@@ -49,7 +51,15 @@ export declare class Scripts implements IScript {
     searchFunctions(options?: IScript.SearchOptions): Promise<IFunction[]>;
     /** {@inheritDoc IScript.start} */
     start(): Promise<void>;
+    /**
+     * Builds the modules from the file without running anything in them: what the calculation's
+     * first pass needs (their formula functions), ahead of {@link start}, which also runs the
+     * `autoRun` functions and so belongs after it.
+     * @internal
+     */
+    _load(): Promise<void>;
     private _doStart;
+    private _doLoad;
     /** {@inheritDoc IListener.ISource.addListeners} */
     addListeners(listeners: IScript.IListeners, options?: IListener.Options): IListener.Remove;
     /** {@inheritDoc IScript.isReadOnly} */

package/types/src/scripting/TypedFunction.d.ts

@@ -205,6 +205,8 @@ export declare class TypedFunction implements IFunction {
      * parameter is the same thing to a body asking which parameter its argument landed in.
      */
     protected _va: number;
+    /** The declaration's `volatile`, read once: what the call frame carries for `defer`. */
+    protected _vol: boolean;
     /** Resolved {@link RepeatPlan} per argument count (`null` = an arity the declaration refuses). */
     protected _gc: Map<number, RepeatPlan | null> | null;
     /** The name's argument ceiling — {@link IFunction.IDeclaration.getMaxArguments}, cached. */

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

@@ -3,6 +3,7 @@ import { FunctionProvider } from '@sheetxl/scripting';
 import { ITransaction } from '../transaction';
 import { IResourceCollection } from '../resource';
 import { IStringCollection } from '../string';
+import { IRichDataCollection } from '../richData';
 import { ICellRange } from '../cellRange';
 import { INamedCollection } from '../named';
 import { IStyleCollection } from '../style';
@@ -33,6 +34,11 @@ export interface ICellContainerOptions {
      * Option to provide shared strings.
      */
     strings?: IStringCollection;
+    /**
+     * Option to provide shared rich values, the store cells hold rich data in by id, as they hold
+     * strings in {@link strings}.
+     */
+    richData?: IRichDataCollection;
     /**
      * Option to provide a shared StyleCollection. If not provided then a new StyleCollection with default theming will be used.
      */

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

@@ -1,4 +1,4 @@
-import { Scalar, IRange, IRangeStats, IRuntime } from '@sheetxl/primitives';
+import { Scalar, IRange, IRangeStats, IRichType, IRuntime } from '@sheetxl/primitives';
 import { Bounds, Size } from '@sheetxl/utils';
 import { ITypes } from '../type';
 import { ITransaction } from '../transaction';
@@ -14,15 +14,16 @@ import { ICellRange, ICellRanges, ICellRegions } from '../cellRange';
 import { IRangeSelection } from '../selection';
 import { IStyleCollection } from '../style';
 import { IStringCollection } from '../string';
+import { IRichDataCollection } from '../richData';
 import { IResource, IResourceCollection } from '../resource';
 import { IMovable, IMovableCollection } from '../movable';
 import { IPivotTable, IPivotTableCollection } from '../pivot';
-import { IDataTable, IDataTableCollection } from '../dataTable';
 import { IComment, ICommentCollection } from '../comment';
 import { ITable, ITableCollection } from '../table';
 import { IDataValidation, IDataValidationCollection } from '../dataValidation';
 import { IConditionalFormat, IConditionalFormatCollection } from '../conditionalFormat';
 import { IProtectedRange, IProtectedRangeCollection } from '../protectedRange';
+import { ICellControl, ICellControlCollection } from '../cellControl';
 import { IModule, IModuleCollection } from '../scripting';
 import { IChartCollection } from '../chart';
 import { INamedCollection } from '../named';
@@ -220,6 +221,14 @@ export interface IWorksheet extends ISheet, ITransaction.ITransactional, IListen
      * {@link IWorksheetProtection.isLocked} is true.
      */
     getProtectedRanges(): IProtectedRangeCollection;
+    /**
+     * Returns the cell controls on this sheet, such as checkboxes.
+     *
+     * @remarks
+     * Every entry, in drawing order. To put a control on cells or read what is there, use
+     * {@link ICellRange.setControl} and {@link ICellRange.getControls}.
+     */
+    getCellControls(): ICellControlCollection;
     /**
      * Returns the comments and notes on this sheet.
      *
@@ -677,14 +686,6 @@ export interface IWorksheet extends ISheet, ITransaction.ITransactional, IListen
      * workbook's {@link IWorkbook.getPivotTables} walks every sheet's.
      */
     getPivotTables(): IPivotTableCollection;
-    /**
-     * Returns the what-if data tables on this sheet, in the order they were read.
-     *
-     * @remarks
-     * Read-only for now: each table is carried as it was read, its results as the file held them.
-     * As in Excel, an edit to part of a table's results is refused.
-     */
-    getDataTables(): IDataTableCollection;
     /**
      * Set the picture interface for the entire sheet.
      * @param picture The picture interface to set for the sheet, or null to remove it.
@@ -976,6 +977,13 @@ export declare namespace IWorksheet {
          * Always accompanied by the coarse {@link onProtectionChange}.
          */
         onProtectedRangesChange?(source: IWorksheet): void;
+        /**
+         * Called when a cell control is added, removed, re-anchored or reordered.
+         *
+         * @remarks
+         * Always accompanied by the coarse {@link onStyleChange}: a control is a format.
+         */
+        onCellControlsChange?(source: IWorksheet): void;
         /**
          * Called when a comment is added, removed, edited, resolved, replied to or re-anchored.
          *
@@ -1340,7 +1348,7 @@ export declare namespace IWorksheet {
      * JSON representation of an `IWorksheet` used for serialization and deserialization.
      */
     interface JSON extends ISheet.JSON {
-        data?: Tuple.GridTuple<ICell.JSON>;
+        data?: Tuple.GridTuple<Scalar.JSON>;
         formulas?: IRange.JSONReferenceTuple<string>[];
         /**
          * The extent occupied by an array formula, and which of the three
@@ -1377,6 +1385,10 @@ export declare namespace IWorksheet {
         styles?: IStyleCollection.JSON;
         resources?: IResource.JSON[];
         strings?: string[];
+        /** The rich values cells name by id (`{ t: 'r', v: id }`), when the sheet owns its own. */
+        richData?: IRichDataCollection.JSON[];
+        /** The kinds {@link richData} names that are not registered in code (a kind read from a file). */
+        richTypes?: IRichType.JSON[];
         /**
          * Modules owned by this sheet, keyed by module name.
          *
@@ -1418,6 +1430,7 @@ export declare namespace IWorksheet {
          */
         validationSettings?: IDataValidationCollection.Settings;
         protectedRanges?: IRange.JSONReference<IProtectedRange.JSON>[];
+        cellControls?: IRange.JSONReference<ICellControl.JSON>[];
         movables?: IMovable.JSON[];
         /**
          * The sheet's VBA code name. Absent when it has none.
@@ -1475,12 +1488,6 @@ export declare namespace IWorksheet {
          * @see {@link IWorksheet.getPivotTables}
          */
         pivotTables?: IPivotTable.JSON[];
-        /**
-         * The sheet's what-if data tables.
-         *
-         * @see {@link IWorksheet.getDataTables}
-         */
-        dataTables?: IDataTable.JSON[];
         /**
          * The cells where Excel's error checks are ignored (the green triangle's **Ignore Error**):
          * each reference's value is the set of checks its cells ignore.

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

@@ -4,6 +4,7 @@ import { ITransaction } from '../transaction';
 import { IProperties, ITypes } from '../type';
 import { NumberFormat } from '../numFmt';
 import { ITextFrame, IRichText } from '../text';
+import { IRichDataKind } from '../richData/IRichDataKind';
 import { ITable } from '../table';
 import { IDataValidation } from '../dataValidation';
 import { IHyperlink } from '../hyperlink';
@@ -20,6 +21,7 @@ import { SpillEntry } from '../calculation/spatial';
 import { CellStyleUpdater } from './style/SheetCellStyle';
 import { ICalcGrid } from '../calculation/grid';
 import { IConditionalFormat } from '../conditionalFormat';
+import { ICellControl } from '../cellControl/ICellControl';
 /**
  * CellModifiers with all functions removed and all properties set and a type.
  */
@@ -53,7 +55,7 @@ interface Cache<K, V> {
  * // TODO - remove style dependency and see if we can remove it.
  */
 export declare function resolveCellModifiers(runtime: IRuntime, update: ICell.Update, optionsFromString?: ICell.ModifiersFromStringOptions | null, resolvedStringCache?: Map<string, ICell.Modifiers> | null, // assumes the same fromStringOptions is used
-isParsingCustom?: boolean, destination?: IRange.CellCoords | null, quotePrefixOnly?: boolean): ResolvedCellModifiers | undefined;
+isParsingCustom?: boolean, destination?: IRange.CellCoords | null, quotePrefixOnly?: boolean, richData?: IRichDataKind.Context | null): ResolvedCellModifiers | undefined;
 /**
  * The decorations (data bar, icon set) a cell's conditional rules draw — the walk behind
  * {@link SheetCell.getConditionalDecorations}, without a cell.
@@ -229,6 +231,8 @@ export declare class SheetCell implements ICell {
     getDataValidation(): IDataValidation | null;
     /** {@inheritDoc ICell.getConditionalDecorations} */
     getConditionalDecorations(): Readonly<IConditionalFormat.Decorations>;
+    /** {@inheritDoc ICell.getControl} */
+    getControl(): ICellControl | null;
     /** {@inheritDoc ICell.getProtection} */
     getProtection(): ICellProtection;
     /** {@inheritDoc ICell.getTextOverflow} */
@@ -301,6 +305,12 @@ export declare class SheetCell implements ICell {
     getValue(): Scalar;
     /** {@inheritDoc ICell.getType} */
     getType(): ScalarType;
+    /**
+     * The type the value lays out as: rich data as what it shows ({@link RichDataRegistry.layoutTypeOf}:
+     * a hyperlink, a rich text or an entity is text, so it aligns left under General and spills into
+     * empty neighbors), everything else as itself.
+     */
+    protected _layoutType(): ScalarType;
     /** {@inheritDoc ICell.getInteropValue} */
     getInteropValue(): InteropScalar;
     /** {@inheritDoc ICell.getInteropType} */
@@ -338,6 +348,12 @@ export declare class SheetCell implements ICell {
     getRole(): ICell.Role | null;
     /** {@inheritDoc ICell.getHyperlink} */
     getHyperlink(): IHyperlink | null;
+    /**
+     * The hyperlink set on the cell, never one its value presents: what a move or a copy carries
+     * to another cell (the value carries its own).
+     * @internal
+     */
+    getStoredHyperlink(): IHyperlink.Properties | null;
     /** {@inheritDoc ICell.getRichText} */
     getRichText(): IRichText.JSON | null;
     /** {@inheritDoc ICell.getErrors} */

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

@@ -19,6 +19,8 @@ import { IDataValidation, IDataValidationCollection } from '../dataValidation';
 import { IConditionalFormat } from '../conditionalFormat/IConditionalFormat';
 import { IConditionalFormatCollection } from '../conditionalFormat/IConditionalFormatCollection';
 import { IProtectedRange, IProtectedRangeCollection } from '../protectedRange';
+import { ICellControl } from '../cellControl/ICellControl';
+import { ICellControlCollection } from '../cellControl/ICellControlCollection';
 import { IWorksheet } from './IWorksheet';
 import { IWorksheetInternal } from './Worksheet';
 import { WatchAnchor } from './_WatchAnchor';
@@ -31,8 +33,8 @@ import { AutoFillProjection } from './_SheetAutoFillUtils';
 export declare const _NoFeatures: readonly ICellRange.Feature[];
 /**
  * A watch listens for the VALUE landing, not for the transaction that caused it — a recalculation
- * notifies its own ranges once the results are in (`trigger: 'calc'`), which is the moment a watch
- * has something new to report.
+ * notifies its own ranges once the results are in (a `'data'` event with no commit), which is the
+ * moment a watch has something new to report.
  */
 export interface SheetRangeOptions {
     readOnly?: string;
@@ -341,6 +343,10 @@ export declare class SheetRange implements ICellRange {
     getUnlocked(options?: ICellRange.GetItemsOptions<IProtectedRangeCollection.GetItemsOptions>): IProtectedRange[];
     /** {@inheritDoc ICellRange.getConditionalFormats} */
     getConditionalFormats(options?: ICellRange.GetItemsOptions<IConditionalFormatCollection.GetItemsOptions>): IConditionalFormat[];
+    /** {@inheritDoc ICellRange.getControls} */
+    getControls(options?: ICellRange.GetItemsOptions<ICellControlCollection.GetItemsOptions>): ICellControl[];
+    /** {@inheritDoc ICellRange.setControl} */
+    setControl(control: ICellControl.JSON | null, options?: ITransaction.OperationOptions): this;
     /** {@inheritDoc ICellRange.getDataValidations} */
     getDataValidations(options?: ICellRange.GetItemsOptions<IDataValidationCollection.GetItemsOptions>): IDataValidation[];
     /** {@inheritDoc ICellRange.getComments} */

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

@@ -98,7 +98,7 @@ export declare class SheetRanges implements ICellRanges {
     /** {@inheritDoc ICellRange.calculate} */
     calculate(): this;
     /** {@inheritDoc ICellRanges.addListener} */
-    addListener(listener: ICellRange.Listener, options?: ICellRange.ListenerOptions): IListener.Remove;
+    addListener(listener: ICellRange.Listener<ICellRanges>, options?: ICellRange.ListenerOptions): IListener.Remove;
     /** {@inheritDoc ICellRanges.addWatch} */
     addWatch(formula: ICalculation.IFormula | string, callback: ICellRanges.WatchCallback, options?: ICellRange.WatchOptions): IListener.Remove;
     /**
@@ -155,7 +155,7 @@ export declare class SheetRanges implements ICellRanges {
     /** {@inheritDoc ICellRanges.clear} */
     clear(applyTo?: ICell.Content, options?: ITransaction.OperationOptions): this;
     /** {@inheritDoc ICellRanges.setValue} */
-    setValue(value: ICellRange.ScalarUpdate, options?: ICellRange.SetValuesOptions): this;
+    setValue(value: ICellRange.InteropScalarUpdate, options?: ICellRange.SetValuesOptions): this;
     /** {@inheritDoc ICellRanges.getStyle} */
     getStyle(): ICellStyle;
     /** {@inheritDoc ICellRanges.merge} */

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

@@ -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';
@@ -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;
@@ -535,6 +551,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 +586,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 +665,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 +675,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 +890,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 +1097,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 +1122,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 +1286,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 +1329,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 +1341,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 +1628,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}.
@@ -1854,23 +1901,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 +1911,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} */
@@ -1922,7 +1954,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 +1994,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
      */
@@ -2106,6 +2155,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 +2164,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 +2228,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 +2253,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;
     /**