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

package/types/src/cellControl/CellControlRegistry.d.ts

@@ -0,0 +1,47 @@
+import { Scalar } from '@sheetxl/primitives';
+/**
+ * What a control type does to the cells it covers: which values it draws.
+ *
+ * @remarks
+ * The SDK half of a control type. How it looks and how it responds to the pointer and keys belong
+ * to the UI, which registers its own renderer under the same `type`.
+ */
+export interface ICellControlKind {
+    /**
+     * The type this kind is registered under, such as `'checkbox'`.
+     */
+    readonly type: string;
+    /**
+     * The kind's name where a UI lists the kinds that can be inserted, such as `'Rating'`. Plain
+     * text; the built-in checkbox takes its name from the command catalog instead.
+     */
+    readonly label?: string;
+    /**
+     * Whether the control draws a cell holding `value`. Any other value draws as text.
+     */
+    accepts(value: Scalar): boolean;
+}
+/**
+ * Excel's checkbox: draws a boolean or a blank cell, in place of its text.
+ */
+export declare const CheckboxKind: ICellControlKind;
+/**
+ * The control types a cell control can have, by type.
+ *
+ * @remarks
+ * The built-in types are registered before the registry is first used; a host registers its own
+ * the same way. A type nobody has registered still loads and saves, and accepts no value, so its
+ * cells draw as text.
+ */
+export declare namespace CellControlRegistry {
+    /**
+     * Registers a kind. A kind registered again under the same type replaces the earlier one,
+     * a built-in included.
+     */
+    function register(kind: ICellControlKind): void;
+    /** The kind registered for `type`, or `null`. */
+    function get(type: string): ICellControlKind | null;
+    /** The registered types. */
+    function getTypes(): string[];
+}
+//# sourceMappingURL=CellControlRegistry.d.ts.map

package/types/src/cellControl/ICellControl.d.ts

@@ -0,0 +1,99 @@
+import { Scalar } from '@sheetxl/primitives';
+import { IAnchored } from '../anchored';
+import { ICellRange } from '../cellRange';
+import { IListener } from '../listener';
+/**
+ * A control drawn in the cells of a range, such as a checkbox.
+ *
+ * @remarks
+ * A cell control decorates the cell's value; it never holds one. A checkbox draws `TRUE` as
+ * checked and `FALSE` or blank as unchecked, and a click writes the boolean into the cell, where
+ * formulas read it as any other value. Excel's model is the same: the checkbox is a cell
+ * *format*, and *Clear Formats* removes it while the value stays.
+ *
+ * * A cell has at most one control. One control covers any number of cells, and its ranges
+ *   shift, split, copy and fill with them.
+ * * A control draws only the values its type accepts ({@link isAccepted}). Any other value draws
+ *   as plain text: a checkbox over `2` or `"true"` draws `2` or `true`, as in Excel.
+ * * Most code never needs this interface: {@link ICellRange.setControl} and
+ *   {@link ICellRange.getControls} stand in for Office Scripts' `Range.setControl` /
+ *   `getControl`.
+ */
+export interface ICellControl extends IAnchored {
+    /**
+     * The control's type, such as `'checkbox'`.
+     *
+     * @remarks
+     * A type nobody has registered (`CellControlRegistry`) is kept and saved as it was read; it
+     * accepts no value, so its cells draw as text.
+     */
+    getType(): string;
+    /**
+     * Returns the first range the control covers.
+     *
+     * @remarks
+     * See {@link IAnchored.getRanges} for all of them. To change where a control is, use
+     * {@link ICellRange.setControl}.
+     */
+    getRange(): ICellRange;
+    /**
+     * Whether the control draws a cell holding `value`.
+     *
+     * @remarks
+     * A checkbox accepts a boolean or a blank cell. A value it does not accept draws as the cell
+     * would without the control.
+     */
+    isAccepted(value: Scalar): boolean;
+    /**
+     * Add Listeners.
+     *
+     * @see
+     * {@link IListener.ISource.addListeners}
+     */
+    addListeners(listeners: ICellControl.IListeners, options?: IListener.Options): IListener.Remove;
+    /**
+     * The control as JSON: its `type` and any properties of that type.
+     */
+    toJSON(): ICellControl.JSON;
+    /**
+     * For runtime type checking.
+     */
+    readonly isICellControl: true;
+}
+/**
+ * {@inheritDoc ICellControl}
+ * @see
+ * ### **Interface**
+ *
+ * {@link ICellControl}
+ *
+ * **Additional Interfaces**
+ * * {@link ICellControlCollection}
+ */
+export declare namespace ICellControl {
+    /**
+     * A control as JSON: its `type`, and any properties that type defines.
+     *
+     * @remarks
+     * Office Scripts' `CellControl`: `{ type: 'checkbox' }`. A checkbox has no other properties.
+     * Office Scripts' `EmptyCellControl` is `null` here.
+     */
+    interface JSON {
+        /**
+         * The control's type, such as `'checkbox'`.
+         */
+        type: string;
+        /**
+         * Properties of the type.
+         */
+        [property: string]: unknown;
+    }
+    /**
+     * IListener for {@link ICellControl} events.
+     */
+    interface Events extends IAnchored.Events<ICellControl> {
+    }
+    interface IListeners extends IListener.Callbacks<ICellControl, ICellControl.Events> {
+    }
+}
+//# sourceMappingURL=ICellControl.d.ts.map

package/types/src/cellControl/ICellControlCollection.d.ts

@@ -0,0 +1,67 @@
+import { ICellRange, ICellRanges } from '../cellRange';
+import { ICollection } from '../type';
+import { ITransaction } from '../transaction';
+import { ICellControl } from './ICellControl';
+/**
+ * Holds a sheet's {@link ICellControl}s.
+ *
+ * @remarks
+ * Most code reaches controls through the range instead: {@link ICellRange.setControl} puts a
+ * control on cells and {@link ICellRange.getControls} reads it back. The collection is for listing
+ * every control, as a task pane does.
+ */
+export interface ICellControlCollection extends ICollection<ICellControl> {
+    /**
+     * Puts a control on the cells of `address`, replacing their controls, and returns it.
+     *
+     * @param address The address of the cells. May name several discontiguous ranges.
+     * @param control The control, such as `{ type: 'checkbox' }`.
+     *
+     * @remarks
+     * The same write as {@link ICellRange.setControl}, over any address. A cell has at most one
+     * control, so the cells leave whatever control they had, and join a control of the same
+     * definition when the sheet already has one.
+     */
+    add(address: ICellRanges.Address, control: ICellControl.JSON, options?: ITransaction.OperationOptions): ICellControl;
+    /**
+     * Returns items that match the filter criteria.
+     *
+     * If no filter criteria is provided, all items will be returned.
+     *
+     * @param options {@link ICellControlCollection.GetItemsOptions}
+     */
+    getItems(options?: ICellControlCollection.GetItemsOptions): ICellControl[];
+    /** For runtime type checking. */
+    readonly isICellControlCollection: true;
+}
+/**
+ * {@inheritDoc ICellControlCollection}
+ * @see
+ * ### **Interface**
+ *
+ * {@link ICellControlCollection}
+ */
+export declare namespace ICellControlCollection {
+    /**
+     * Options for searching for {@link ICellControl}s.
+     */
+    interface GetItemsOptions extends ICollection.GetItemsOptions {
+        /**
+         * If provided, the search will be limited to items that intersect the range.
+         */
+        address?: ICellRange.Address;
+        /**
+         * Indicate if items that are in hidden headers or marked as hidden should be returned.
+         *
+         * @defaultValue false
+         */
+        ignoreHidden?: boolean;
+        /**
+         * Only return items that are completely contained with the search bounds.
+         *
+         * @defaultValue false
+         */
+        fullyContained?: boolean;
+    }
+}
+//# sourceMappingURL=ICellControlCollection.d.ts.map

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

@@ -0,0 +1,4 @@
+export * from './ICellControl';
+export * from './ICellControlCollection';
+export * from './CellControlRegistry';
+//# sourceMappingURL=index.d.ts.map

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

@@ -1,24 +1,25 @@
-import { FormulaError, IRange, Scalar, InteropScalar, IRangeStats } from '@sheetxl/primitives';
+import { FormulaError, IRange, Scalar, InteropScalar, IRangeStats, IRichData } from '@sheetxl/primitives';
 import { Bounds, Size, ReferenceableClipboard } from '@sheetxl/utils';
 import { ITypes } from '../type';
 import { IListener } from '../listener';
 import { ITransaction } from '../transaction';
+import { IAnchored } from '../anchored/IAnchored';
 import { IHyperlink } from '../hyperlink';
 import { IRichText } from '../text';
-import { IComment, ICommentCollection } from '../comment';
 import { ISort } from '../sort';
 import { ICondition } from '../condition';
 import { IAutoFill } from '../autoFill';
 import { ICellStyle } from '../style';
 import { ICalculation } from '../calculation';
+import { IWorksheet } from '../sheet';
+import { ICell } from '../cell';
+import { IComment, ICommentCollection } from '../comment';
 import { ITable, ITableCollection } from '../table';
 import { IMovable, IMovableCollection } from '../movable';
 import { IDataValidation, IDataValidationCollection } from '../dataValidation';
-import { IConditionalFormat } from '../conditionalFormat/IConditionalFormat';
-import { IConditionalFormatCollection } from '../conditionalFormat/IConditionalFormatCollection';
+import { IConditionalFormat, IConditionalFormatCollection } from '../conditionalFormat';
 import { IProtectedRange, IProtectedRangeCollection } from '../protectedRange';
-import { IWorksheet } from '../sheet';
-import { ICell } from '../cell';
+import { ICellControl, ICellControlCollection } from '../cellControl';
 import { ICellRanges } from './ICellRanges';
 import { ICellRegions } from './ICellRegion';
 import { ICellHeaderRange } from './ICellHeaderRange';
@@ -96,6 +97,39 @@ export interface ICellRange {
      * {@link IConditionalFormat.getRanges}.
      */
     getConditionalFormats(options?: ICellRange.GetItemsOptions<IConditionalFormatCollection.GetItemsOptions>): IConditionalFormat[];
+    /**
+     * Returns the {@link ICellControl}s on cells within the range, such as checkboxes.
+     *
+     * @param options The filters of {@link ICellControlCollection.getItems} without `address` —
+     * this range is the address.
+     *
+     * @remarks
+     * See {@link getConditionalFormats} for the overlap and one-entry-per-item rules, which are the
+     * same for every ranged item lookup. A cell has at most one control; ask a cell for its own with
+     * {@link ICell.getControl}.
+     *
+     * Office Scripts' `Range.getControl()` answers one `CellControl` for the whole range; here
+     * `getControls()[0]?.getType()` reads a single cell's, and `toJSON()` gives the
+     * `{ type: 'checkbox' }` shape. A control is about the cell, not its value: a checkbox cell
+     * holding `2` still has one, though it draws `2` ({@link ICellControl.isAccepted}). A type
+     * SheetXL does not know answers with its own name, where Excel answers `unknown`.
+     */
+    getControls(options?: ICellRange.GetItemsOptions<ICellControlCollection.GetItemsOptions>): ICellControl[];
+    /**
+     * Puts `control` on every cell of the range, replacing the control each had; `null` removes
+     * them.
+     *
+     * @param control The control, such as `{ type: 'checkbox' }`, or `null`.
+     *
+     * @remarks
+     * Office Scripts' `Range.setControl`, with `null` for its `{ type: 'empty' }`. A cell has at most
+     * one control. The values stay as they are: a checkbox draws `TRUE` as checked and `FALSE` or a
+     * blank cell as unchecked, and any other value as text.
+     *
+     * A control is a format: refused on a protected sheet unless formatting cells is allowed, removed
+     * by {@link clear} of formats, and carried by a paste of formats.
+     */
+    setControl(control: ICellControl.JSON | null, options?: ITransaction.OperationOptions): this;
     /**
      * Returns the {@link IDataValidation}s that overlap the range.
      *
@@ -768,7 +802,7 @@ export interface ICellRange {
     getRegions(features?: ICellRange.Feature | readonly ICellRange.Feature[], options?: ICellRange.GetRegionsOptions): ICellRegions;
     /**
      * Returns the regions of the `anomalies` feature in reading order: the named checks first, then
-     * the rest, each by rank.
+     * the rest, each by the named focus or by rank.
      *
      * @param options {@link ICellRange.GetAnomaliesOptions}
      *
@@ -777,6 +811,8 @@ export interface ICellRange {
      * // Hunting an embedded hardcode: read its checks' findings first, 25 regions at a time.
      * sheet.getAnomalies({ checks: ['hardcodeInRun', 'styleRole'], limit: 25 });
      * sheet.getAnomalies({ checks: ['hardcodeInRun', 'styleRole'], limit: 25, offset: 25 });
+     * // Or name the kind of defect and let the measured order decide.
+     * sheet.getAnomalies({ focus: 'unitMismatch', limit: 25 });
      * ```
      *
      * @remarks
@@ -787,6 +823,13 @@ export interface ICellRange {
      * region two named checks fire on lists once, under the first. An ignored check
      * ({@link setErrorIgnored}) is not there to list.
      *
+     * `focus` names the kind of defect being looked for ({@link ICellRange.AnomalyFocus}). Each
+     * finding then weighs as the share of findings like it — the same check, the same kind of
+     * evidence, about as often repeated in the listing — that were that kind of defect in audited
+     * models, and a region lists by its best finding, by rank where that is equal. Several kinds
+     * merge into one order by the best of them. It reorders; it neither adds nor drops a region, and
+     * the findings' own ranks are unchanged.
+     *
      * `offset` and `limit` page through that one order, so successive windows neither skip nor
      * repeat a region; a window shorter than `limit` is the last. `getRegions('anomalies').getCount()`
      * is the length of the whole list.
@@ -1289,12 +1332,23 @@ export interface ICellRange {
      */
     select(options?: ICellRange.SelectOptions): Promise<this>;
     /**
-     * Add a listener to the range.
+     * Listen for changes at this range: its cells written, recalculated or undone, and the range
+     * itself moved by rows or columns inserted or deleted around it.
      *
-     * @returns A callback to remove. {@link IListener.Remove}
+     * @returns A callback that removes the listener. {@link IListener.Remove}
      *
      * @remarks
-     * If the range becomes invalid through a delete this will auto remove.
+     * The listener is handed an {@link ICellRange.Event} whose source is the listened range where
+     * it is now. Which events it hears, how it follows inserts and deletes, and whether it takes
+     * part in the change or observes it afterwards are {@link ICellRange.ListenerOptions}.
+     *
+     * @example
+     * ```ts
+     * const remove = sheet.getRange('A1:C3').addListener((event) => {
+     *   if (event.getTrigger() === 'data') console.log('changed:', event.getRanges()!.getAddress());
+     *   else console.log('now at:', event.getSource().getAddress());
+     * });
+     * ```
      */
     addListener(listener: ICellRange.Listener, options?: ICellRange.ListenerOptions): IListener.Remove;
     /**
@@ -1576,15 +1630,20 @@ export declare namespace ICellRange {
      */
     type ScalarUpdate = Scalar | null | undefined;
     /**
-     * Represents an update to a cell's value in JavaScript, allowing `Date` and `null`.
+     * Represents an update to a cell's value in JavaScript, allowing `Date`, a rich value's JSON
+     * and `null`.
      *
      * @remarks
      * This type allows for updating a cell's value, including `Date` for convenience.
      * As with `ScalarUpdate`, `null` can be used to clear the cell's value.
      *
+     * A rich value may be given as its JSON (`{ type, data }`, what {@link IRichData.toJSON}
+     * returns); it is made by the kind registered for `type`, and an unregistered type is kept
+     * as it was given.
+     *
      * * See {@link InteropScalar} for more details on JavaScript scalar values.
      */
-    type InteropScalarUpdate = InteropScalar | null | undefined;
+    type InteropScalarUpdate = InteropScalar | IRichData.JSON | null | undefined;
     /**
      * Single or 2D.
      */
@@ -2715,6 +2774,14 @@ export declare namespace ICellRange {
          * failure — its cells evaluate, to `0` — and is {@link Feature.Circular}.
          */
         readonly CalcError: "calcError";
+        /**
+         * Evaluated state: cells whose result has not settled. Regions group by status — a cell whose
+         * own function has not answered yet ({@link ICalculation.ResultStatus.Pending}), or one
+         * calculated from such a value and calculated again when it arrives
+         * ({@link ICalculation.ResultStatus.Waiting}). The anchor's `getCalculationStatus()` is the
+         * payload. Empty once every answer has landed.
+         */
+        readonly CalcStatus: "calcStatus";
         /**
          * Evaluated state: cells in a reference cycle, or downstream of one. Both evaluate to `0`
          * (Excel, iterative calculation off) with nothing else to show for it — this is the marker.
@@ -2762,6 +2829,14 @@ export declare namespace ICellRange {
         readonly Conditionals: "conditionals";
         /** Cells under data-validation rules. */
         readonly DataValidations: "dataValidations";
+        /**
+         * Cells under a cell control ({@link ICellRange.setControl}). Regions group by the control's
+         * definition (its type and properties), so adjacent checkboxes set in two strokes are one
+         * region and a checkbox beside a rating are two; the anchor cell's {@link ICell.getControl} is
+         * the payload. Whether a cell draws its control depends on its value, which is a `Kind`
+         * question: ask for both to split a column of checkboxes from the text cells among them.
+         */
+        readonly CellControl: "cellControl";
         /**
          * Cells where an error check fires — what breaks the pattern around it. Regions group by the
          * check and its evidence, so a filled row that breaks the same way is one region; the anchor
@@ -2783,7 +2858,11 @@ export declare namespace ICellRange {
          * a reference outside the workbook (`externalReference`); and from labels: a link whose target
          * row is labeled otherwise (`linkLabelMismatch`), a lookup key that is not the row's or
          * column's label (`keyLabelMismatch`), a link with the other sign from its siblings
-         * (`signVsSiblings`). An ignored check ({@link ICellRange.setErrorIgnored}) does not fire.
+         * (`signVsSiblings`); and from the numbers: a typed number in a formula equal to an input
+         * nothing reads (`literalMatchesInput`), twin formulas that differ in a unit literal or a sign
+         * (`twinBlockDivergence`), a percent typed as a whole number (`scaleOutlier`), every constant a
+         * formula types with how often the workbook types it (`constantFrequency`). An ignored check
+         * ({@link ICellRange.setErrorIgnored}) does not fire.
          *
          * Regions list highest rank first ({@link ICell.Anomaly.rank}), unless an `axis` is asked for.
          *
@@ -2847,6 +2926,33 @@ export declare namespace ICellRange {
          */
         containment?: 'intersects' | 'fullyContained';
     }
+    /**
+     * A kind of defect a reader is looking for, which {@link ICellRange.getAnomalies} can order its
+     * findings by ({@link GetAnomaliesOptions.focus}).
+     */
+    const AnomalyFocus: {
+        /** A cell or a subtotal counted twice in a sum. */
+        readonly DoubleCounting: "doubleCounting";
+        /** A typed number where a reference belongs. */
+        readonly EmbeddedHardcode: "embeddedHardcode";
+        /** A cell whose font color is not its role's (inputs, links, calculations). */
+        readonly ColorCoding: "colorCoding";
+        /** An average over the wrong cells. */
+        readonly Average: "average";
+        /** A link to another sheet that reads the wrong row or column. */
+        readonly CrossSheetReference: "crossSheetReference";
+        /** A term added that should be taken away, or the reverse. */
+        readonly SignConvention: "signConvention";
+        /** A lookup that matches approximately, or reads arrays that do not line up. */
+        readonly Lookup: "lookup";
+        /** A reference relative where it should be absolute, or the reverse. */
+        readonly ReferenceAnchoring: "referenceAnchoring";
+        /** A value in the wrong unit: a monthly figure in a daily formula, a percent typed as a whole number. */
+        readonly UnitMismatch: "unitMismatch";
+        /** Rows deleted from a model, which leaves references shifted and `#REF!`. */
+        readonly DeletedRows: "deletedRows";
+    };
+    type AnomalyFocus = typeof AnomalyFocus[keyof typeof AnomalyFocus];
     /**
      * Options for {@link ICellRange.getAnomalies}.
      */
@@ -2857,6 +2963,15 @@ export declare namespace ICellRange {
          * @defaultValue none — every region by rank
          */
         checks?: readonly ICell.ErrorCheck[];
+        /**
+         * The kind of defect being looked for, or several: regions are ordered by how often findings
+         * like theirs have been that kind of defect, measured on audited models, and by rank where
+         * that is equal. With `checks` too, the named checks still list first and `focus` orders
+         * within each. An unknown name throws.
+         *
+         * @defaultValue none — by rank
+         */
+        focus?: AnomalyFocus | readonly AnomalyFocus[];
         /**
          * At most this many regions.
          *
@@ -3009,85 +3124,101 @@ export declare namespace ICellRange {
          */
         injectReferences?: IRange.JSONReference<any>[][];
     }
-    interface Event {
+    /**
+     * What a range listener is told. See {@link ICellRange.addListener}.
+     *
+     * @typeParam S The source the listener registered on: an `ICellRange` from
+     * {@link ICellRange.addListener}, an `ICellRanges` from {@link ICellRanges.addListener}.
+     */
+    interface Event<S extends ICellRange | ICellRanges = ICellRange> {
         /**
          * The range that was listened to, where it is now.
          *
          * @remarks
-         * After a `'address'` or `'restore'` event this is the range at its new address or extent: rows
+         * After an `'address'` or `'restore'` event this is the range at its new address or extent: rows
          * or columns inserted or deleted around it, or an undo that moved it back. The range
          * `addListener` was called on keeps the address it was made with, so this is where to read
          * the range from.
+         *
+         * A range whose cells were deleted is invalid ({@link ICellRange.isInvalid}) and spells
+         * `#REF!`; one restored to a revision from before the listener was added is invalid and
+         * spells `#N/A`.
          */
-        getSource<T = ICellRange | ICellRanges>(): T;
+        getSource(): S;
         /**
-         * This is the range of data that has been changed.
+         * The cells that changed within the source, for a `'data'` event; `null` for any other.
          *
          * @remarks
-         * This is different than the source range as that is the entire range area that was listened to.
+         * A batch is one change: every range of it that reached the listener arrives in one event.
          */
-        getFrom(): ICellRanges;
+        getRanges(): ICellRanges | null;
         /**
-         * Returns a list of updates that occurred during the event. This is only available for data change events and will be `null` for address or restore events.
+         * Where the source was before an `'address'` event moved it; `null` for any other event, and
+         * for a sheet rename, which moves no cells.
+         *
+         * @remarks
+         * An address rather than a range, because the cells at it now are other cells.
          */
+        getPreviousAddress(): string | null;
         /**
-         * Indicates the type of change that triggered the event.
+         * What happened to the range.
          *
          * @remarks
-         * * `'data'`: Data within the range has changed.
-         *   The range's address and dimensions remain the same.
-         * * `'address'`: The range's *address* or *dimensions* have changed. This
-         *   occurs due to row/column insertions, deletions, or move operations — and, for a
-         *   sheet-qualified range (one from {@link IWorkbook.getRange}, or a sheet's range naming
-         *   another sheet), when the sheet it names is renamed. A bare range on its own sheet has no
-         *   qualifier, so a rename is not a change to it.
-         * * `'restore'`: The range has been restored to a different revision
-         *   (undo/redo). The 'restore' trigger is not available for transactional listeners.
+         * * `'data'`: Cells within the range changed: written, recalculated, or undone. The range's
+         *   address and extent are as they were. {@link getCommit} is `null` for a recalculation,
+         *   which belongs to no commit; {@link isUndo} tells an undo from a write.
+         * * `'address'`: The range's address or extent changed: rows or columns inserted or deleted,
+         *   cells moved, its cells deleted (the source spells `#REF!`), or, for a sheet-qualified
+         *   range (one from {@link IWorkbook.getRange}, or a sheet's range naming another sheet), a
+         *   rename of the sheet it names. A bare range on its own sheet has no qualifier, so a rename
+         *   is not a change to it. A listener anchored {@link IAnchored.Type.Absolute} never moves and
+         *   never has one.
+         * * `'restore'`: The workbook was restored to a revision from before the listener was added,
+         *   so the range is not in it (the source spells `#N/A`). Never delivered to a transactional
+         *   listener.
          */
-        readonly trigger2?: 'data' | 'address' | 'restore';
-        readonly trigger: string;
+        getTrigger(): Event.Trigger;
         /**
-         * Indicates if the event is being fired from an undo event.
+         * `true` when the change is an undo. A redo is not an undo: it is told as the forward change
+         * was.
          */
-        readonly isUndo?: boolean;
+        isUndo(): boolean;
         /**
-         * Returns the transaction Id if the event is occurring in a transaction otherwise `null`.
+         * The commit that made the change, or `null` when none did: a recalculation landing.
          *
-         * @see
-         * {@link ListenerOptions.getTransactionId}
+         * @remarks
+         * A transactional listener is told before the commit is sealed, so this is the commit it is
+         * writing into ({@link ListenerOptions.transactional}).
          */
-        getTransactionId(): string | null;
+        getCommit(): ITransaction.ICommit | null;
         /**
-         * Indicates if the event is being fired due to a cell value change.
-         *
-         * @see
-         * {@link ListenerOptions.ignoreDataChanges}
+         * The trigger and the source, for logging.
          */
-        readonly isDataChange?: boolean;
+        toString(): string;
         /**
-         * To string the event.
+         * When the event was made, in milliseconds since the epoch.
          */
-        toString(): string;
+        getTimeStamp(): number;
+    }
+    namespace Event {
         /**
-         * The timestamp of the event.
+         * What happened to a listened range. See {@link ICellRange.Event.getTrigger}.
          */
-        readonly timeStamp: number;
+        type Trigger = 'data' | 'address' | 'restore';
     }
     /**
-     * Represents a listen for a range. The listener will be called when the range's
-     * data, address, or restore state changes, subject to the provided options.
+     * Called with what changed at a listened range. See {@link ICellRange.addListener}.
      *
-     * @remarks
-     * If the range is deleted (rows/columns removed), the trigger will be `'address'`
-     * `trigger` of `'address'` and `getRange().getError()`
-     * returning `"#REF!"`.
+     * @typeParam S The source the listener registered on; see {@link ICellRange.Event}.
      *
-     * If the ranges is restored to a revision *before* the listener was
-     * added, the listener will receive event with a `trigger` of `'restore'`
-     * and `getRange().getError()` returning `"#N/A"`.
+     * @remarks
+     * Read the range from {@link Event.getSource}, which is where the listened cells are now. It is
+     * invalid ({@link ICellRange.isInvalid}) when the cells were deleted (`#REF!`) or the workbook
+     * was restored to a revision from before the listener was added (`#N/A`); the listener stays
+     * registered through both, and hears the range come back.
      */
-    interface Listener {
-        (event: ICellRange.Event): void;
+    interface Listener<S extends ICellRange | ICellRanges = ICellRange> {
+        (event: ICellRange.Event<S>): void;
     }
     /**
      * Receives a watch's results — one value per cell of the watched range, read with LOCAL
@@ -3133,11 +3264,28 @@ export declare namespace ICellRange {
         /**
          * If `true`, the listener will *not* be called when the range's
          * address changes (due to row/column insert/delete, moves, or a rename of
-         * the sheet a qualified range names)
+         * the sheet a qualified range names). The range still follows its cells; see {@link anchor}
+         * for a range that should not.
          *
          * @defaultValue false
          */
         ignoreAddressChanges?: boolean;
+        /**
+         * How the listened range follows rows and columns inserted or deleted around it.
+         *
+         * @defaultValue {@link IAnchored.Type.TwoCell}
+         *
+         * @remarks
+         * * `TwoCell`: the range follows its cells, as a formula reference does. An insert above it
+         *   moves it down, a delete inside it shrinks it, and deleting all of its cells makes it
+         *   `#REF!`. Each move is an `'address'` event.
+         * * `OneCell`: the top-left follows its cell and the extent is kept, as a picture anchored to
+         *   one cell. Deleting the top-left cell leaves the range where it is.
+         * * `Absolute`: the range never moves. It names the same addresses whatever is inserted or
+         *   deleted, so it never has an `'address'` event. This is what a view listening to the rows
+         *   it shows wants: the cells on screen, not the cells that were there when it subscribed.
+         */
+        anchor?: IAnchored.Type;
         /**
          * Whether the listener takes part in the operations that change its range.
          *