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

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

@@ -4,6 +4,7 @@ import { ITypes } from '../type';
 import { IListener } from '../listener';
 import { ITransaction } from '../transaction';
 import { IHyperlink } from '../hyperlink';
+import { IRichText } from '../text';
 import { IComment, ICommentCollection } from '../comment';
 import { ISort } from '../sort';
 import { ICondition } from '../condition';
@@ -16,13 +17,13 @@ import { IDataValidation, IDataValidationCollection } from '../dataValidation';
 import { IConditionalFormat } from '../conditionalFormat/IConditionalFormat';
 import { IConditionalFormatCollection } from '../conditionalFormat/IConditionalFormatCollection';
 import { IProtectedRange, IProtectedRangeCollection } from '../protectedRange';
-import { ISheet } from '../sheet';
+import { IWorksheet } from '../sheet';
 import { ICell } from '../cell';
 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,7 +91,7 @@ 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}.
      */
@@ -116,7 +117,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 +152,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 +181,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 +217,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 +308,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 +367,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 +713,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 +766,32 @@ 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 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 });
+     * ```
+     *
+     * @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.
+     *
+     * `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 +820,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 +844,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 +857,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 +924,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 +990,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 +1027,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 +1159,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 +1237,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.
      *
@@ -1339,6 +1455,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 +1497,7 @@ export interface ICellRange {
     /**
      * Returns the Sheet.
      */
-    getSheet(): ISheet;
+    getWorksheet(): IWorksheet;
     /**
      * The IRange.Coords.
      */
@@ -1434,10 +1555,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;
     /**
@@ -1463,13 +1590,13 @@ export declare namespace ICellRange {
      */
     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 +1747,7 @@ export declare namespace ICellRange {
         replaceExisting?: boolean;
     }
     /**
-     * Options for `ICellRange.delete`.
+     * Options for `ICellRange.insert`.
      */
     interface InsertOptions extends ICellRange.OperationOptions {
         /**
@@ -1647,6 +1774,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 +1802,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 +2093,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 +2537,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 +2639,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 +2662,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.
          *
@@ -2562,6 +2746,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 +2762,39 @@ export declare namespace ICellRange {
         readonly Conditionals: "conditionals";
         /** Cells under data-validation rules. */
         readonly DataValidations: "dataValidations";
+        /**
+         * 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`). 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 +2804,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 +2847,29 @@ export declare namespace ICellRange {
          */
         containment?: 'intersects' | 'fullyContained';
     }
+    /**
+     * 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[];
+        /**
+         * 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.
@@ -2758,10 +3011,13 @@ export declare namespace ICellRange {
     }
     interface Event {
         /**
-         * 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 a `'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.
          */
         getSource<T = ICellRange | ICellRanges>(): T;
         /**
@@ -2771,10 +3027,6 @@ export declare namespace ICellRange {
          * 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.
-         */
-        getTo?(): ICellRange;
         /**
          * 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.
          */
@@ -2887,23 +3139,38 @@ export declare namespace ICellRange {
          */
         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
-        */
+         * 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