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

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

@@ -1,11 +1,5 @@
 import { ScalarType, FormulaError, IRange, IFunction, IFormulaContext } from '@sheetxl/primitives';
 import { FixedPackedArray } from '../primitives/PrimitiveUtils';
-/**
- * The per-call shape of a declaration that carries a repeating group, resolved from the ARGUMENT
- * COUNT alone (`Repeating<T>`; DESIGN-REPEATING §2). Excel is measured never to disambiguate by type —
- * `SORTBY(array, by1, by2, o2)` is refused where a type-directed parse would have read argument 2
- * as `by_array2` — so the arithmetic is the whole rule.
- */
 /**
  * What `_exec` needs to know about ONE parameter position, decided once per declaration (and
  * once per expanded {@link RepeatPlan}) rather than on every call: the normalized value types,
@@ -56,14 +50,6 @@ interface ParamSpec {
      * `#VALUE!`. Today that is the multi-area union; the body reads it through `getArgs`.
      */
     reportType: boolean;
-    /**
-     * `ReportType<NoLift<T>>` (either order): a multi-cell REFERENCE at this scalar slot neither
-     * lifts (`NoLift`) nor refuses (`ReportType`), it is handed to the body WHOLE, as one
-     * `IReferenceRange`; an array still lifts. Excel's `Boolean|Range` slot shape, no `Array` bit:
-     * LINEST/LOGEST `const`/`stats`, TREND/GROWTH `const` (DESIGN-LIFT-AND-DEMAND §1). One flag
-     * because the coercion loop and both lift walks ask the same question, and a slot carrying only
-     * one of the two markers changes nothing here.
-     */
     wholeReference: boolean;
     /** The effective policy and its `allowError` half — static per declaration. */
     policy: 'reject' | 'accept' | null;
@@ -139,15 +125,6 @@ export declare class TypedFunction implements IFunction {
     };
     protected _lc: boolean;
     protected _rlc: boolean;
-    /**
-     * Some parameter declares `NoLift<T>` — a multi-cell REFERENCE at that non-repeating scalar
-     * slot is `#VALUE!` rather than a broadcast, per parameter as Excel needs
-     * (`NETWORKDAYS.INTL` refuses a reference at its date slots and lifts at `weekend`,
-     * CALC-ISSUES 31; DESIGN-FUNCTION-ARGUMENTS §2.3, §6). A declaration bit and not a body
-     * concern, because the body never runs: without it the lift runs instead and answers one
-     * result per cell, so there is nothing for a body-facing API to express. Precomputed so the
-     * common call pays one boolean.
-     */
     protected _nl: boolean;
     /** Whether ANY parameter (or repeating slot) is `Lazy` — the guard on the wrapping below. */
     protected _lz: boolean;
@@ -170,16 +147,6 @@ export declare class TypedFunction implements IFunction {
      * through the parameter's coercion.
      */
     protected _rs: ScalarType | null;
-    /**
-     * The reference half of the declared RETURN KIND pair (DESIGN-DECLARATION-SURFACE §3.1): may
-     * this call answer a REFERENCE? True for a declared `IReferenceRange` return (`r:'p'` —
-     * OFFSET/INDIRECT/XLOOKUP/TAKE/DROP) and for an UNTYPED return (`any` — the pass-through
-     * selectors IF/IFS/SWITCH/CHOOSE/INDEX, and any UDF that declares nothing). False for every
-     * provable value — a declared scalar (`'*'` included: IFERROR) or a ranged array producer.
-     *
-     * Read at the call exit (a value-declared function's reference result is demoted to its VALUE)
-     * and at the `*`-slot union pass-through.
-     */
     protected _rref: boolean;
     /**
      * The declared result kind is a SCALAR member of {@link ValueKind} — `ROW(A1)` is the number 3
@@ -195,16 +162,9 @@ export declare class TypedFunction implements IFunction {
     protected _ps: ParamSpec[];
     /** Index of the repeating-group parameter, or `-1`. */
     protected _gi: number;
-    /**
-     * Index of the one parameter that consumes a VARIABLE number of arguments — a repeating group or
-     * a trailing rest — or `-1`.
-     *
-     * `getArgs()` indexes by PARAMETER (DESIGN-FUNCTION-ARGUMENTS §3.3) and this is the single place
-     * parameter numbering and argument numbering part company, so it is resolved once here rather
-     * than re-derived per call. `_gi` cannot serve: it covers `Repeating<T>` only, and a plain rest
-     * 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. */
@@ -212,28 +172,6 @@ export declare class TypedFunction implements IFunction {
     constructor(json: IFunction.DeclarationJSON, fn: (...args: any) => any, getContext: () => IFormulaContext | null | undefined, desc?: IFunction.DescriptorJSON | ((locale?: string) => Promise<IFunction.DescriptorJSON>) | null, builtIn?: boolean);
     /** @inheritdoc IFunction.execute */
     execute<R = any>(...args: any[]): R;
-    /**
-     * Resolves this call's {@link RepeatPlan} from the argument count, or `null` when the count is
-     * one the declaration refuses.
-     *
-     * `n = (argc − prefix − suffix) / period` and a non-zero remainder is an error, with ONE
-     * exception: a group whose last slot is optional also accepts `period − 1` variable arguments,
-     * which is `n = 1` with that slot omitted. Those two rules produce SORTBY's measured arities
-     * exactly — 2 and 1+2n, with 4 refused (probe rows H7/H10).
-     *
-     * A trailing suffix may be OPTIONAL, so `suffix` is solved for alongside `n` rather than fixed.
-     * SWITCH is the case: `prefix 1, period 2, one optional suffix` yields argument parity as the
-     * whole rule — odd is pairs alone, even is pairs plus a default — and refuses argc 2, because
-     * dropping the suffix still leaves the group owing its one repetition. That matches Excel row
-     * for row (probe-switch-arity.ps1: 3/4/5/6 legal, 1 and 2 refused). The group's minimum stays
-     * 1 regardless of the suffix; nothing here ever resolves `n = 0`.
-     *
-     * Period 1 ends at one rest-marked slot instead — see {@link RepeatPlan.params}.
-     *
-     * Must stay in step with `CompilerUtils.resolveRepeat`, its COMPILE-TIME twin. That one decides
-     * `#PARSE!` and the per-argument binding, so a rule added only here is simply never reached: the
-     * formula is refused before it ever executes.
-     */
     protected _plan(argsLength: number): RepeatPlan | null;
     /**
      * Folds the flat, per-argument-position values back into the shape the BODY declares: the group
@@ -258,53 +196,8 @@ export declare class TypedFunction implements IFunction {
      * writes anything into it.
      */
     protected _exec<R = any>(argsEval: any[], argsLength: number): R;
-    /**
-     * `NoLift<T>`: is a multi-cell REFERENCE sitting at a non-repeating scalar parameter marked to
-     * refuse one? (DESIGN-FUNCTION-ARGUMENTS §2.3, §2.7 rule 3.)
-     *
-     * Three qualifications, each measured rather than assumed
-     * (`fn-battery/adhoc-container-at-slot{,2}`, Excel 16.0 build 20326):
-     *
-     * - **A REFERENCE, not an array.** `MROUND({3,4,5},5)` spills where `MROUND(A1:A3,5)` is
-     *   `#VALUE!`, so an array at the same slot still lifts. That is the whole reason this reads the
-     *   argument's shape rather than trusting the parameter: the engine hands a reference over as
-     *   COORDS and an array as an `IRange`.
-     * - **MULTI-CELL.** A 1×1 reference collapses to its member and is an ordinary argument
-     *   (`EFFECT(J1,4)` over a text cell is `0.0824…`).
-     * - **NON-REPEATING.** A repeating scalar slot ABSORBS a container as members whatever the
-     *   function's heritage — `GCD(C1:C3)` is 4, `MULTINOMIAL(A1:A3)` is 27720 — and those were the
-     *   rows that could have broken the rule and did not. Period-1 groups marshal through the rest
-     *   branch and are already excluded by `rest`; period 2+ expand to per-argument entries, so the
-     *   group's span is skipped explicitly.
-     *
-     * A multi-AREA union `(A1:A3,C1:C5)` arrives as an ARRAY of areas and is not treated as a
-     * reference here — unmeasured at these slots, and inventing a verdict for it would be the kind
-     * of unification §2.0 warns about.
-     */
     protected _refusesReferenceLift(params: IFunction.ParameterTypeJSON[] | null | undefined, paramLength: number, argsEval: any[], argsLength: number, plan: RepeatPlan | null): boolean;
-    /**
-     * The consumer half of the lift (CALC-ISSUES item 22 change 2). Each `refLifts` entry is a
-     * reference-only (r:'p') argument holding a producer lift's preserved per-element results.
-     * The function runs once per output cell through {@link _exec} — a full re-invocation, so
-     * every other argument re-coerces and the body re-runs per element (measured:
-     * `SUBTOTAL(9,OFFSET(A1,{0;1},0,1,1),B1:B2)` = 31|32 — the plain range is consumed WHOLE in
-     * each call). Shape rules are the scalar lift's: output dims = max over entries, dim-1 tiles,
-     * a shorter dim pads `#N/A` (probe-lift-member-coercion.ps1: 2×1 beside 1×2 → 2×2).
-     *
-     * An element that is not a reference (a plain value in a reference-only position) is not
-     * special-cased: the per-element coercion answers exactly as it would for the unlifted call
-     * (item 23b's `#PARSE!`), which becomes that member of the output.
-     */
     protected _refLift<R>(context: IFormulaContext, argsEval: any[], argsLength: number, refLifts: RefLiftEntry[], firstCell?: boolean): R;
-    /**
-     * @hidden
-     * Vends a NEW instance whose evaluation context comes from `getContext` — the public-API
-     * scope vend behind `IFunctionCollection.getByName(name, { sheet })` (CALC-ISSUES item 35).
-     * The registry instance is what the ENGINE holds and its evaluation path stays
-     * allocation-free; a vended instance additionally owns a private fast-path slot the engine
-     * never loads, so callers may hold it across awaits (or re-enter it) without racing the
-     * engine's synchronous argument hand-off.
-     */
     _withContext(getContext: () => IFormulaContext | null | undefined): TypedFunction;
     /** @inheritdoc IFunction.getName */
     getName(): string;

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.
@@ -783,7 +784,7 @@ export declare namespace IWorksheet {
     /**
      * The events that carry a {@link ChangeEvent}: what {@link ChangeEvent.getKind} names.
      */
-    type ChangeEventKey = 'onDataChange' | 'onStyleChange' | 'onLayoutChange' | 'onMergesChange' | 'onSpillsChange';
+    type ChangeEventKey = 'onDataChange' | 'onStyleChange' | 'onMergesChange' | 'onSpillsChange';
     /**
      * What a change event announces: where the change landed and what wrote 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.
          *
@@ -1016,11 +1024,8 @@ export declare namespace IWorksheet {
          * for "cell geometry moved".
          * * This can be be due to row/column sizes changes or changing the max rows columns.
          * * Zoom and viewport do not change the underlying layout.
-         *
-         * @param source The sheet.
-         * @param event The whole sheet: sizes are announced by the headers, which do not say where.
          */
-        onLayoutChange?(source: IWorksheet, event: IWorksheet.ChangeEvent): void;
+        onLayoutChange?(source: IWorksheet): void;
         /**
          * Called when which rows are hidden has changed.
          */
@@ -1340,7 +1345,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 +1382,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 +1427,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 +1485,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/NamedCellRange.d.ts

@@ -4,27 +4,6 @@ import { INamedFormulasCollection } from '../calculation/INamedFormulasCollectio
 import { NamedRange } from './NamedRange';
 import { IWorksheetInternal } from './Worksheet';
 import { SheetRangeOptions } from './SheetRange';
-/**
- * A defined name as a NODE in the calculation graph — an `INamedRange` whose coords are the
- * name's ANCHOR (its defining cell), not a target.
- *
- * @remarks
- * This is how a name rides inside an ordinary `ICellRanges` graph answer next to plain cell
- * ranges: the brand (`isINamedRange`) carries the identity, the coords carry the anchor, and the
- * four graph methods answer the NAME question rather than the cell question at those coords
- * (DESIGN-NAMED-FORMULAS.md §4). Contrast {@link NamedRange}, which `getRange('Revenue')` returns
- * over the name's *target* — same brand, different referent, and only this one exists for a value
- * name (`Doubled = Base*2`), which has no target at all.
- *
- * The anchor matters to precedents (relative references in the body resolve from it) and is only
- * a label for dependents (the symbol index is global). Lead with the name when displaying one —
- * two names authored from the same active cell share an anchor address, and the name is the fact.
- *
- * Built from a {@link NamedNodeInfo} — plain data — and answers its five name questions by
- * resolving the id against the collection when asked. It does NOT capture the name object: a name
- * can be redefined or deleted while a graph answer is still held, and re-resolving means the
- * answer follows the definition rather than a snapshot of it. A name that is gone answers `null`.
- */
 export declare class NamedCellRange extends NamedRange {
     private readonly _info;
     private readonly _namedFormulas;

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.
@@ -221,6 +223,12 @@ export declare class SheetCell implements ICell {
     getWorksheet(): IWorksheet;
     /** {@inheritDoc ICell.select} */
     select(options?: ITypes.SelectOptions): Promise<boolean>;
+    /**
+     * Follows an address as this cell's sheet follows a link: what a link beside the cells (a picture's)
+     * opens with.
+     * @internal
+     */
+    _openAddress(address: string, options: ITypes.SelectOptions | null, target?: string, features?: string): Promise<boolean>;
     /** {@inheritDoc ICell.getColumn} */
     getColumn(): ITable.IColumn | null;
     /** {@inheritDoc ICell.getTable} */
@@ -229,6 +237,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 +311,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 +354,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} */
@@ -355,8 +377,8 @@ export declare class SheetCell implements ICell {
     /** {@inheritDoc ICell.getSpillKind} */
     getSpillKind(): ITypes.FormulaArrayKind | null;
     /**
-     * The spill entry this cell answers for: the first live one, else a blocked one so the UI can
-     * still show the range it would have taken.
+     * The spill entry this cell answers for: a live one, else a blocked one, so the UI can show the
+     * range it would have taken. Where blocked ones overlap, the one anchored here, else the first.
      */
     protected _getSpillEntry(): SpillEntry | null;
     /** {@inheritDoc ICell.isSpillOverflow} */

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} */