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

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

@@ -1,28 +1,30 @@
-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 { IComment, ICommentCollection } from '../comment';
+import { IRichText } from '../text';
 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 { ISheet } from '../sheet';
-import { ICell } from '../cell';
+import { ICellControl, ICellControlCollection } from '../cellControl';
 import { ICellRanges } from './ICellRanges';
 import { ICellRegions } from './ICellRegion';
 import { ICellHeaderRange } from './ICellHeaderRange';
 /**
- * A {@link ICellRange} represents a rectangular collection of {@link ICell} within an {@link ISheet}.
+ * A {@link ICellRange} represents a rectangular collection of {@link ICell} within an {@link IWorksheet}.
  *
  * **Naming Conventions:** Methods usually adhere to the following conventions except
  * when adhering to a idiomatic existing conventions of Typescript (for example `size` or 'length'):
@@ -90,11 +92,44 @@ export interface ICellRange {
      * pass `fullyContained` for the stricter question.
      *
      * The items are the sheet's — this is a scoped view of
-     * `getSheet().getConditionalFormats()`, not a copy — and each appears **once**, however many of
+     * `getWorksheet().getConditionalFormats()`, not a copy — and each appears **once**, however many of
      * its ranges the query hit. The range only says *which* items; ask an item where it lives with
      * {@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.
      *
@@ -116,7 +151,7 @@ export interface ICellRange {
      * range is the address.
      *
      * @remarks
-     * The items are the sheet's — a scoped view of `getSheet().getComments()`, not a copy. A
+     * The items are the sheet's — a scoped view of `getWorksheet().getComments()`, not a copy. A
      * comment is on one cell, so each appears once, in reading order.
      */
     getComments(options?: ICellRange.GetItemsOptions<ICommentCollection.GetItemsOptions>): IComment[];
@@ -151,6 +186,15 @@ export interface ICellRange {
      * {@link ICellRange.getCells}
      */
     getCell(address?: ICell.Address): ICell;
+    /**
+     * Exists to have api parity with Office Scripts: `row` and `column` are 0-based offsets from the
+     * range's top left.
+     *
+     * @deprecated Use {@link getCell}`('B3')`, or `getCell({ rowIndex, colIndex })` with sheet
+     * coordinates.
+     * @hidden
+     */
+    getCell(row: number, column: number): ICell;
     /**
      * Return a 2D array of {@link ICell | cells} in the shape of the range.
      *
@@ -171,6 +215,24 @@ export interface ICellRange {
      * {@link ICellRange.getValues}
      */
     getValue(): Scalar;
+    /**
+     * Returns the top left cell's value as displayed, with its number format applied.
+     *
+     * @remarks
+     * The same as `getCell().getText(options)`.
+     *
+     * @see
+     * {@link ICell.getText}
+     */
+    getText(options?: ICell.GetTextOptions): string;
+    /**
+     * Exists to have api parity with Office Scripts.
+     *
+     * @deprecated Use {@link getCells}`()` and each cell's `getText()`, or {@link getText} for the
+     * top left cell.
+     * @hidden
+     */
+    getTexts(): string[][];
     /**
      * Returns the value for the top left `InteropScalar`.
      *
@@ -189,6 +251,19 @@ export interface ICellRange {
      * set values work for the entire range.
      */
     getStyle(): ICellStyle;
+    /**
+     * Exists to have api parity with Office Scripts.
+     *
+     * @deprecated Use {@link getStyle}.
+     * @hidden
+     */
+    getFormat(): ICellStyle;
+    /**
+     * @deprecated Use {@link getStyle}`().update(style)`, or a setter on the style:
+     * `getStyle().getFont().setBold(true)`.
+     * @hidden
+     */
+    setStyle(style: ICellStyle.Update, options?: ICellStyle.UpdateOptions): this;
     /**
      * Returns the formula for the range.
      *
@@ -267,17 +342,17 @@ export interface ICellRange {
      *
      * @remarks
      * The anchored convenience form: equivalent to
-     * `getSheet().createFormula(expression, topLeftCoords)`, where the anchor is this
+     * `getWorksheet().createFormula(expression, topLeftCoords)`, where the anchor is this
      * range's top-left cell. Nothing is committed — the formula is not registered in the workbook
      * or the dependency graph.
      *
-     * Two behaviors follow from the sheet form (see {@link ISheet.createFormula}):
+     * Two behaviors follow from the sheet form (see {@link IWorksheet.createFormula}):
      *
      * - A bare reference (`A2`) resolves against THIS range's sheet, never the selected one.
      * - Relative references resolve **relative to the anchor cell**, so the expression reads
      *   exactly as it would if it were authored here.
      *
-     * @see {@link ISheet.createFormula}
+     * @see {@link IWorksheet.createFormula}
      * @see {@link ICalculation.createFormula}
      */
     createFormula(expression: string, options?: ICalculation.CreateFormulaOptions): ICalculation.IFormula;
@@ -326,6 +401,20 @@ export interface ICellRange {
      * @returns `ICellRange` at the repositioned range.
      */
     getEntireRows(shift?: boolean, options?: ICellRange.GetRangeOptions): this;
+    /**
+     * Exists to have api parity with Office Scripts.
+     *
+     * @deprecated Use {@link getEntireRows}.
+     * @hidden
+     */
+    getEntireRow(): this;
+    /**
+     * Exists to have api parity with Office Scripts.
+     *
+     * @deprecated Use {@link getEntireColumns}.
+     * @hidden
+     */
+    getEntireColumn(): this;
     /**
      * Returns a range that includes the current range up to a content edge boundary.
      *
@@ -658,6 +747,8 @@ export interface ICellRange {
      *
      * - Every public {@link ICellRange.Feature} appears as a key; features not requested, or not
      *   present, are an explicit `0` — the shape is stable and self-describing, never `null`.
+     *   `anomalies` is the exception: it is derived on read, so it is counted, and its key
+     *   present, only when requested by name.
      * - Each feature is counted **independently**. `getCounts([Fill, Border])` is two numbers,
      *   not the count of their refined intersection — the refined count *is* `getRegions`.
      * - Counts are cells, never regions: a region count would either disagree with the partition
@@ -709,6 +800,41 @@ export interface ICellRange {
      *   vocabulary at all — see {@link Feature}'s own remarks for where they went.
      */
     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 the named focus or by rank.
+     *
+     * @param options {@link ICellRange.GetAnomaliesOptions}
+     *
+     * @example
+     * ```ts
+     * // 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
+     * The regions are the ones {@link getRegions | getRegions('anomalies')} returns, with the same
+     * findings and ranks ({@link ICell.Anomaly}); only the order and the window differ. A region
+     * whose findings include the first named check lists first, highest rank of that check first;
+     * then the second check's; then every region no named check fires on, by its highest rank. A
+     * 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.
+     */
+    getAnomalies(options?: ICellRange.GetAnomaliesOptions): ICellRegions;
     /**
      * Returns a 2D array of {@link Scalar | values} in the shape of the range.
      *
@@ -737,8 +863,8 @@ export interface ICellRange {
      * @remarks
      * - `null` values will clear the corresponding cells.
      * - `undefined` values will be ignored, leaving the existing cell values unchanged.
-     * - If an array is passed the values will be in row-major order. An array smaller than the range writes only the cells it covers.
-     * - If a single value is passed in it will repeat the entire range.
+     * - The array is row-major. An array smaller than the range writes only the cells it covers.
+     * - A single value is {@link setValue}, which fills the range with it.
      */
     setValues(values: ICellRange.ValuesUpdate, options?: ICellRange.SetValuesOptions): this;
     /**
@@ -761,7 +887,7 @@ export interface ICellRange {
      * @see
      * {@link ICellRange.setValues}
      */
-    setValue(value: ICellRange.ValuesUpdateOrCallback, options?: ICellRange.SetValuesOptions): this;
+    setValue(value: ICellRange.ScalarUpdateOrCallback, options?: ICellRange.SetValuesOptions): this;
     /**
      * Set the formula for a range.
      *
@@ -774,7 +900,7 @@ export interface ICellRange {
      * @see
      * {@link ICellRange.setValue}
      */
-    setFormula(value: ICellRange.ValuesUpdateOrCallback, options?: ICellRange.SetValuesOptions): this;
+    setFormula(value: ICellRange.ScalarUpdateOrCallback, options?: ICellRange.SetValuesOptions): this;
     /**
      * Sets the formula of each cell in the range.
      *
@@ -841,7 +967,7 @@ export interface ICellRange {
      * @throws `Error` If a row or column in the range is already at the deepest level, `7`. Nothing is
      * grouped.
      *
-     * @see {@link ISheet.getOutline}
+     * @see {@link IWorksheet.getOutline}
      */
     group(axis?: IRange.Axis, options?: ITransaction.OperationOptions): this;
     /**
@@ -907,6 +1033,34 @@ export interface ICellRange {
      * To clear hyperlinks either set to `null` or call `clear(ICell.Content.Hyperlinks)`.
      */
     setHyperlink(hyperlink: IHyperlink.Update, options?: ITransaction.OperationOptions): this;
+    /**
+     * Sets the text of every cell in the range as formatted runs.
+     *
+     * @param runs The runs, or plain text for one run. A run's font records what it sets over the
+     * cell's font: `{ text: 'Bold', font: { bold: true } }` then `{ text: ' plain' }`.
+     * @returns The current `ICellRange`.
+     *
+     * @remarks
+     * The value becomes a `RichText`: text to calculation (`LEN`, `&`, `TYPE()` 2) and formatting
+     * to the renderer, carried whole by a reference. A later `setValue` replaces it, runs and all,
+     * as any value write does. Read it with {@link ICell.getRichText}.
+     */
+    setRichText(runs: IRichText.Update, options?: ITransaction.OperationOptions): this;
+    /**
+     * Ignores, or stops ignoring, one of Excel's error checks over the range: the green triangle's
+     * **Ignore Error**.
+     *
+     * @param check The check.
+     * @param ignored `false` to show the check's indicator again. Defaults to `true`.
+     * @returns The current `ICellRange`.
+     *
+     * @remarks
+     * SheetXL does not run the checks yet; the setting is kept for Excel. It follows the cells through
+     * inserts and deletes, is not copied, and is dropped from a cell that is written or cleared, as
+     * in Excel. Read it with {@link ICell.isErrorIgnored}; find it with {@link getRegions} and
+     * {@link Feature.IgnoredErrors}.
+     */
+    setErrorIgnored(check: ICell.ErrorCheck, ignored?: boolean, options?: ITransaction.OperationOptions): this;
     /**
      * Sets or clears the comment on the range's first cell.
      *
@@ -916,7 +1070,7 @@ export interface ICellRange {
      * @remarks
      * A comment is on one cell, so a value goes on the range's top-left cell — updating the comment
      * there if it has one, adding one otherwise — while `null` clears every comment within the
-     * range. The comment itself is the richer surface: `getSheet().getComments()` to add, and
+     * range. The comment itself is the richer surface: `getWorksheet().getComments()` to add, and
      * {@link ICell.getComments} to reach the one on a cell.
      */
     setComments(comments: IComment.Update, options?: ITransaction.OperationOptions): this;
@@ -1048,7 +1202,7 @@ export interface ICellRange {
      * @param options If a boolean then this indicates if headers are present.
      *
      * @remarks
-     * This behaves similarly to {@link ISheet.getTables.add} but uses the current range
+     * This behaves similarly to {@link IWorksheet.getTables.add} but uses the current range
      */
     addTable(options?: ITableCollection.AddOptions | boolean): ITable;
     /**
@@ -1126,12 +1280,17 @@ export interface ICellRange {
     /**
      * Perform a set of operations as a batch.
      *
-     * @param callback Function to perform the operations.
+     * @param callback Function to perform the operations. Handed the commit being written and
+     * `range`, this range bound to the batch.
      * @param options Description of the operation or additional options. This will be used for tracking undo/redo and history. @defaultValue 'Range Update'
      * @template R - The callback return type.
      * @returns The result of the callback.
+     *
+     * @remarks
+     * Work through `range` rather than this one: what is reached through it is part of the batch, as
+     * for {@link IWorkbook.doBatch}.
      */
-    doBatch<R>(callback: (commit: ITransaction.ICommit) => Promise<R> | R, options?: string | ITransaction.OperationOptions): Promise<R> | R;
+    doBatch<R>(callback: (commit: ITransaction.ICommit, range: this) => Promise<R> | R, options?: string | ITransaction.OperationOptions): Promise<R> | R;
     /**
      * Creates a `SparseBuilder` for efficiently updating sparsely populated cells in a streaming low memory way.
      *
@@ -1173,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;
     /**
@@ -1339,6 +1509,11 @@ export interface ICellRange {
      * @param r1c1 If unspecified returns the environment's default.
      */
     getAddress(r1c1?: boolean): string;
+    /**
+     * @deprecated Use {@link getAddress}.
+     * @hidden
+     */
+    getA1(): string;
     /**
      * Returns the column start.
      */
@@ -1376,7 +1551,7 @@ export interface ICellRange {
     /**
      * Returns the Sheet.
      */
-    getSheet(): ISheet;
+    getWorksheet(): IWorksheet;
     /**
      * The IRange.Coords.
      */
@@ -1434,10 +1609,16 @@ export interface INamedRange extends ICellRange {
 export declare namespace ICellRange {
     /**
      * This is either:
-     * 1. A string that can be parsed into a CellRange (e.g. 'A1:B2') or a named range.
+     * 1. A string that can be parsed into a CellRange (e.g. 'A1:B2'), a named range, or a
+     *    structured reference (e.g. `'Sales[[#Headers],[Qty]]'`).
      * 2. Another ICellRange
      * 3. An IRange
      * 4. Partial IRange.FixableCoords
+     *
+     * @remarks
+     * A structured reference is read from the active cell: one without a table name (`'[Qty]'`)
+     * refers to the table at the active cell, and `@` (`'Sales[@Qty]'`) to the active cell's row.
+     * References into another workbook are not supported.
      */
     type Address = string | ICellRange | IRange | Readonly<Partial<IRange.FixableCoords>> | ICell.Address | FormulaError.Ref;
     /**
@@ -1449,27 +1630,32 @@ 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.
      */
     type Update = ICell.Update | readonly ICell.Update[][];
     /**
-     * A union of either a Scalar and 2D array of Scalars or an IRange.
+     * A 2D array of scalars or an IRange. A single value is a {@link ScalarUpdateOrCallback}.
      */
-    type ValuesUpdate = InteropScalarUpdate | IRange | readonly InteropScalarUpdate[][];
+    type ValuesUpdate = IRange | readonly InteropScalarUpdate[][];
     /**
-     * Allows for Values to be set via a callback.
+     * A single value, or a callback that yields one per cell.
      */
-    type ValuesUpdateOrCallback<T = Scalar> = ValuesUpdate | ((row: number, column: number) => T | null);
+    type ScalarUpdateOrCallback<T = Scalar> = InteropScalarUpdate | ((row: number, column: number) => T | null);
     /**
      * The read options a range carries.
      *
@@ -1620,7 +1806,7 @@ export declare namespace ICellRange {
         replaceExisting?: boolean;
     }
     /**
-     * Options for `ICellRange.delete`.
+     * Options for `ICellRange.insert`.
      */
     interface InsertOptions extends ICellRange.OperationOptions {
         /**
@@ -1647,6 +1833,12 @@ export declare namespace ICellRange {
          * @defaultValue `false` (classic shift-cells)
          */
         span?: boolean;
+        /**
+         * Fit the inserted rows and columns to their content once the insert completes.
+         *
+         * @defaultValue `false` - inserted rows and columns take the default size.
+         */
+        autoFit?: boolean | ICellRange.AutoFitOptions;
     }
     /**
      * Options for `ICellRange.delete`.
@@ -1669,6 +1861,12 @@ export declare namespace ICellRange {
          * @defaultValue `false` (classic shift-cells)
          */
         span?: boolean;
+        /**
+         * Fit the rows and columns the remaining cells shift into once the delete completes.
+         *
+         * @defaultValue `false` - a delete moves rows and columns with the sizes they have.
+         */
+        autoFit?: boolean | ICellRange.AutoFitOptions;
     }
     /**
      * Options for configuring range coordinate reference types.
@@ -1954,7 +2152,7 @@ export declare namespace ICellRange {
         /**
          * Fit to what **formula view** displays rather than to the rendered values.
          *
-         * @defaultValue the sheet view's {@link ISheetView.isShowFormulas}
+         * @defaultValue the sheet view's {@link IWorksheetView.isShowFormulas}
          *
          * @remarks
          * In formula view a cell with a formula shows `=` + its formula text, and every other cell
@@ -2398,14 +2596,31 @@ export declare namespace ICellRange {
      * `ISnapshot` can be provided to `ICellRange.copyFrom`.
      */
     interface ISnapshot<T = any, J = any> {
+        /**
+         * Does the asynchronous work a paste needs, before {@link copyTo} is called.
+         *
+         * @remarks
+         * `ICellRange.copyFrom` calls this first, outside any transaction, and then `copyTo` inside
+         * the paste's transaction. Anything that has to wait - loading a kind of content, decoding an
+         * image - is done here, so that `copyTo` can complete synchronously. A snapshot with nothing
+         * to wait for leaves this out, or returns `void`; the paste then runs to its commit in the
+         * caller's synchronous extent.
+         *
+         * @param destination The `ICellRange` the snapshot will be copied to, as the caller gave it.
+         */
+        prepare?(destination: ICellRange, options?: ICellRange.CopyOptions): Promise<void> | void;
         /**
          * Copies the snapshot to the specified range.
          *
+         * @remarks
+         * The copy is made inside the paste's transaction, so it completes synchronously; anything
+         * that has to wait belongs in {@link prepare}.
+         *
          * @param destination The destination `ICellRange` where the snapshot will be copied.
          *
-         * @returns A promise that resolves when the copy is complete, or `void` if no asynchronous operation is required.
+         * @returns The coordinates the copy covered, or `null` when it placed no cells.
          */
-        copyTo(destination: ICellRange, options?: ICellRange.CopyOptions): Promise<IRange.Coords | null> | IRange.Coords | null;
+        copyTo(destination: ICellRange, options?: ICellRange.CopyOptions): IRange.Coords | null;
         /**
          * Return the options used when creating.
          * @remarks
@@ -2483,12 +2698,12 @@ export declare namespace ICellRange {
      * over the content-style map). `Notes` joins when the backing is implemented; a feature that
      * silently reports nothing is worse than a missing one.
      *
-     * `String`/`Number`/`Boolean` are deliberately absent, even though they are real `ScalarType`
-     * values. This vocabulary is for things with a spatial identity — a fill, a formula, an
-     * occupied cell — and a scalar kind has none: it is read straight off the value, which is
+     * `String`/`Number`/`Boolean` are deliberately absent as separate members, even though they are
+     * real `ScalarType` values. "How many numbers" is a count read straight off the values, which is
      * exactly the one pass `IRangeStats.getTypedCounts()` already makes, richer (it composes with
-     * aggregates and frequencies for free, in the same call). `getCounts`/`getRegions`/
-     * `isContentful` were never the right vocabulary for "how many numbers" — `range.getStats()` is.
+     * aggregates and frequencies for free, in the same call) — `range.getStats()` is the vocabulary
+     * for that. *Where* the numbers are is a partition, and that is the one {@link Feature.Kind}
+     * answers: a typed row inside a block of text is a region of its own.
      *
      * `Error` stays, for a reason unrelated to the above: it has real spatial identity of its own
      * (the reconciled error view) and partitions like any stored feature — it was never in the same
@@ -2506,6 +2721,34 @@ export declare namespace ICellRange {
          * Occupancy — splits on blank/non-blank, Excel `CurrentRegion` semantics.
          */
         readonly Contentful: "contentful";
+        /**
+         * What a cell holds: a number, a date, text, text that would enter as a number, a boolean, an
+         * error or rich data. A formula cell is the kind of its result.
+         *
+         * @remarks
+         * Regions group by kind, so a column of numbers with one text cell in it is three regions. A
+         * date is a number under a date or time format (the cell's `getInteropType()` is `date`).
+         * Text that a typed entry would read as a number (`'123`, a number imported as text) is a kind
+         * of its own, apart from other text: it is Excel's number stored as text. The anchor's
+         * `getInteropType()` names the kind of every other region.
+         *
+         * Derived from the values on first read and cached until the sheet changes.
+         */
+        readonly Kind: "kind";
+        /**
+         * A cell's job in the model ({@link ICell.Role}): a typed `label` or `input`, a `link` to
+         * another sheet, a `reference` on this sheet, a `computed` cell or an `output`, from what the
+         * cell reads and who reads it. The anchor's {@link ICell.getRole} is the payload.
+         *
+         * @remarks
+         * The kind layer refined by the formulas: a column of typed numbers a model reads is one
+         * `input` region, the links beside it another. Crossed with a format (`['role', 'font']`) it is
+         * the census a color convention is judged by, and what the `styleRole` check reads.
+         *
+         * Derived on first read (the formulas parsed once) and cached until the sheet changes, so
+         * {@link ICellRange.getCounts} counts it only when asked for by name, like `anomalies`.
+         */
+        readonly Role: "role";
         /**
          * Direct date-category number format — `yyyy-mm-dd`, `mm/dd/yyyy`, and the like.
          *
@@ -2531,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.
@@ -2562,6 +2813,11 @@ export declare namespace ICellRange {
         readonly AutoTable: "autoTable";
         /** Has a hyperlink. */
         readonly Hyperlink: "hyperlink";
+        /**
+         * Ignores one or more of Excel's error checks. Regions group by the set of checks ignored.
+         * @see {@link ICellRange.setErrorIgnored}
+         */
+        readonly IgnoredErrors: "ignoredErrors";
         /** Has comments. */
         readonly Comments: "comments";
         /**
@@ -2573,6 +2829,51 @@ 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
+         * cell's {@link ICell.getAnomalies} is the payload.
+         *
+         * @remarks
+         * Excel's background error checks, run over this vocabulary's own partitions rather than cell
+         * by cell: a formula region whose neighbors on both sides agree with each other and not with
+         * it (`formula`), a range that stops one number short (`formulaRange`), text that reads as a
+         * number (`numberStoredAsText`), a reference to an empty cell (`emptyCellReference`), a
+         * formula left unlocked (`unlockedFormula`). The first of these is one rule SheetXL runs on
+         * other layers too: a typed value in a run of formulas (`hardcodeInRun`), and an authored
+         * format that breaks the run around it (`styleBreak`); and a format part paired with the
+         * cell's role, a link left black where links are green (`styleRole`). Then SheetXL's own, read from what a
+         * formula says: a cell counted twice in one sum (`repeatedReference`), an aggregate of one cell
+         * or of typed numbers (`degenerateCall`), a sum holding its own subtotal (`sumIncludesSubtotal`),
+         * a total that also adds a cell outside its block (`misalignedReference`),
+         * a nearest-key lookup (`approximateMatch`), lookup arrays that do not line up (`lookupShape`),
+         * 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`); 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.
+         *
+         * The checks that read a formula need the calculation engine to have loaded its parser, and
+         * those that read its references need it to have compiled the formula; with the engine off
+         * they do not fire.
+         *
+         * Derived on first read and cached until the sheet changes, so {@link ICellRange.getCounts}
+         * counts it only when asked for by name; otherwise its key is absent, never `0`.
+         */
+        readonly Anomalies: "anomalies";
     };
     type Feature = typeof Feature[keyof typeof Feature];
     /**
@@ -2582,9 +2883,17 @@ export declare namespace ICellRange {
      * Total, not partial — every public {@link ICellRange.Feature} is present, absent features
      * as explicit zeros. A zero is a fact about the range; a missing key would be ambiguous.
      *
+     * The exceptions are `anomalies` and `role`: each is derived, not stored, so it is present only
+     * when it was requested by name. A count that was never taken is absent rather than a `0` that
+     * would read as "nothing fires here".
+     *
      * The brand is non-enumerable: `Object.keys`/`entries` yield exactly the feature keys.
      */
-    interface Counts extends Readonly<Record<ICellRange.Feature, number>> {
+    interface Counts extends Readonly<Record<Exclude<ICellRange.Feature, typeof Feature.Anomalies | typeof Feature.Role>, number>> {
+        /** Present only when `anomalies` was requested by name; see {@link Feature.Anomalies}. */
+        readonly anomalies?: number;
+        /** Present only when `role` was requested by name; see {@link Feature.Role}. */
+        readonly role?: number;
         /**
          * For runtime type checking.
          */
@@ -2617,6 +2926,65 @@ 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}.
+     */
+    interface GetAnomaliesOptions {
+        /**
+         * The checks to list first, in this order of priority; an unknown name throws.
+         *
+         * @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.
+         *
+         * @defaultValue every region
+         */
+        limit?: number;
+        /**
+         * Regions to skip first, so `{ limit: 25, offset: 25 }` is the window after `{ limit: 25 }`.
+         *
+         * @defaultValue 0
+         */
+        offset?: number;
+    }
     interface ScrollIntoViewOptions extends globalThis.ScrollIntoViewOptions {
         /**
          * If provided then will only scroll in the provided axis.
@@ -2756,86 +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 source of the event. This will be a readonly range.
+         * The range that was listened to, where it is now.
          *
          * @remarks
-         * This may change shape due to insert/delete/move of cells or sheets.
+         * 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.
-         */
-        getFrom(): ICellRanges;
-        /**
-         * Used for moves. Represents the new location of the data that has changed.
+         * A batch is one change: every range of it that reached the listener arrives in one event.
          */
-        getTo?(): ICellRange;
+        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
@@ -2881,29 +3264,61 @@ 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;
         /**
-        * If `true`, the listener will be treated as *transactional*. This has
-        * a few implications:
-        *
-        * 1. **Synchronous Execution:** The listener will be called *synchronously*
-        *    as part of the same transaction that triggered the event.  Any
-        *    side-effects of the listener will be included in the transaction's
-        *    commit history.
-        * 2. **No 'restore' Events:** Transactional listeners will *never* receive
-        *    'restore' events. They are only concerned with changes within the
-        *    current transaction.
-        *
-        * If `false` (the default), the listener will be called *asynchronously*
-        * after the transaction is complete. The listener's side-effects will
-        * *not* be part of the transaction's commit history.
-        *
-        * @defaultValue false
-        */
+         * 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.
+         *
+         * @defaultValue `true` when the listener is added through a range reached through the object a
+         * batch hands its callback ({@link IWorkbook.doBatch}, {@link IWorksheet.doBatch},
+         * {@link doBatch}), and `false` otherwise.
+         *
+         * @remarks
+         * A transactional listener (a participant):
+         * * added through a batch, is told as each operation of that batch is made, before the
+         *   operation returns, with what that operation changed. It is not told again when the batch
+         *   lands;
+         * * added any other way, is told once at the end of each operation, before it is committed;
+         * * writes into the same commit as the change it was told of, so one undo takes back both;
+         * * is never told of an undo or a redo, and is removed by undoing the operation that added it.
+         *   If its batch fails, it is told nothing more and goes with the batch.
+         *
+         * A non-transactional listener (an observer) is told once, after the operation has landed,
+         * with everything the operation changed in its range, and not at all if the operation is
+         * rolled back. What it writes is an operation of its own. It is told of an undo or a redo
+         * (`'restore'`), and it survives them.
+         *
+         * @example
+         * ```ts
+         * await workbook.doBatch(async (_commit, wb) => {
+         *   const total = wb.getSelectedWorksheet()!.getRange('B1');
+         *   const input = wb.getSelectedWorksheet()!.getRange('A1');
+         *   input.addListener(() => total.setValue((input.getValue() as number) * 2)); // a participant
+         *   input.setValue(21);
+         *   total.getValue(); // 42
+         * });
+         * ```
+         */
         transactional?: boolean;
         /**
          * If `true`, the listener will *not* be called when the data