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

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 ranking 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;
     /**
@@ -1363,10 +1417,13 @@ export interface ICellRange {
      *
      * This method is a more scalable alternative to `getValues` or `getCells` for large or sparse ranges,
      * as it:
-     * 1. Skips empty values by default.
+     * 1. Skips empty values by default, however much of the range is styled.
      * 2. Avoids creating large arrays.
      * 3. Allows for early termination.
-  
+     *
+     * To reach blank cells that have a feature, such as a fill or a hyperlink, name it in
+     * {@link ICellRange.IteratorOptions.features}.
+     *
      * @param callback A function that will be called for each non-empty cell in the range. The callback receives:
      *   - `value`: The `Scalar` at the current cell.
      *   - `context`: A `IteratorContext` object providing additional information and utilities for the cell.
@@ -1576,15 +1633,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.
      */
@@ -2150,8 +2212,8 @@ export declare namespace ICellRange {
          *
          * @remarks
          * The same lens {@link ICellRange.getCounts} and {@link ICellRange.getRegions} take, and it
-         * costs no extra scan: the range is split at the hidden runs first (off the header run
-         * structure, no per-cell probe) and the resulting pieces are measured as ONE population.
+         * costs no extra scan: the range is split at the hidden runs first and the resulting pieces
+         * are measured as ONE population.
          *
          * Optionally an {@link IRange.Axis} to skip on one axis only.
          */
@@ -2691,7 +2753,8 @@ export declare namespace ICellRange {
          */
         readonly Role: "role";
         /**
-         * Direct date-category number format — `yyyy-mm-dd`, `mm/dd/yyyy`, and the like.
+         * A date-category number format, given directly or by a named style — `yyyy-mm-dd`,
+         * `mm/dd/yyyy`, and the like.
          *
          * @remarks
          * A formatting predicate, not a value kind: a blank cell or a text cell formatted this way
@@ -2715,6 +2778,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.
@@ -2727,7 +2798,11 @@ export declare namespace ICellRange {
         readonly Fill: "fill";
         /** Direct borders. */
         readonly Borders: "borders";
-        /** Direct number format. Region payloads carry the format string and its category. */
+        /**
+         * A number format given directly or by a named style, not one left at Normal's. Region payloads
+         * carry the format string and its category, so a block with `0%` set directly and one with the
+         * `Percent` style are one region.
+         */
         readonly NumberFormat: "numberFormat";
         /** Direct alignment. */
         readonly Alignment: "alignment";
@@ -2744,7 +2819,7 @@ export declare namespace ICellRange {
         readonly Table: "table";
         /** Auto-table membership. */
         readonly AutoTable: "autoTable";
-        /** Has a hyperlink. */
+        /** Has a hyperlink. Regions group by what the link says, so the same link set twice is one region. */
         readonly Hyperlink: "hyperlink";
         /**
          * Ignores one or more of Excel's error checks. Regions group by the set of checks ignored.
@@ -2762,6 +2837,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 +2866,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 +2934,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 +2971,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 in 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.
          *
@@ -2947,9 +3070,12 @@ export declare namespace ICellRange {
         /**
          * The features the iteration resolves and visits.
          *
-         * @defaultValue all features
+         * @defaultValue all features are resolved, and only the cells with values are visited
          *
          * @remarks
+         * Naming a feature also visits the blank cells that have it: `features: 'hyperlink'` reaches a
+         * link on an empty cell, and `features: 'fill'` every cell of a filled column.
+         *
          * Two effects, both wins for a caller that does not need everything:
          * - The iterator only materializes the requested features' state onto the context — an
          *   excluded feature is never even looked up.
@@ -3009,85 +3135,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 +3275,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.
          *

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

@@ -72,14 +72,15 @@ export interface ICellRanges {
      * This is Excel's `Ctrl+Enter` fill: the same scalar is written to all selected cells — across every
      * discontiguous range — as a single {@link ICellRanges.doBatch} operation (one undo step). A formula
      * string (e.g. `"=A1+1"`) is coerced and its relative references adjust per cell, exactly as
-     * {@link ICellRange.setValue} does within one range.
+     * {@link ICellRange.setValue} does within one range. It takes what that does: a `Date`, or a rich
+     * value's JSON (`{ type, data }`), which each cell makes into its own value.
      *
      * Only the scalar-broadcast form exists (no `setValues`): a 2D shape has no coherent meaning spread
      * across discontiguous ranges of differing sizes.
      * @see
      * {@link ICellRange.setValue}
      */
-    setValue(value: ICellRange.ScalarUpdate, options?: ICellRange.SetValuesOptions): this;
+    setValue(value: ICellRange.InteropScalarUpdate, options?: ICellRange.SetValuesOptions): this;
     /**
      * {@inheritDoc ICellRange.merge}
      */
@@ -335,7 +336,7 @@ export interface ICellRanges {
     /**
      * {@inheritDoc ICellRange.addListener}
      */
-    addListener(listener: ICellRange.Listener, options?: ICellRange.ListenerOptions): IListener.Remove;
+    addListener(listener: ICellRange.Listener<ICellRanges>, options?: ICellRange.ListenerOptions): IListener.Remove;
     /**
      * {@link ICellRange.addWatch} across every area, as ONE expression authored at a shared origin.
      *

package/types/src/chart/Chart.d.ts

@@ -194,12 +194,6 @@ export declare class Chart extends AbstractMovableContent<State, IChart.JSON, IC
     private _readCells;
     /** A cell as its text: a number formatted by its own cell's format, the rest as Excel shows it. */
     private _cellText;
-    /**
-     * What the chart's cells hold now, for resolve (DESIGN-CHART §3.3): values, categories, names
-     * and the first cell's number format are read from the cells the engine's formulas name, in the
-     * order Excel reads a range (column by column, {@link inReadOrder}). Where the cells cannot be
-     * read, the model's cache answers.
-     */
     private _dataReader;
     /** How many listeners want `onLayoutChange`. */
     private _layoutListeners;
@@ -232,10 +226,6 @@ export declare class Chart extends AbstractMovableContent<State, IChart.JSON, IC
     private _syncDataListeners;
     /** {@inheritDoc ITransaction.ITransactional.close} */
     close(): void;
-    /**
-     * The cache `reference` holds when read now, as Excel writes it (DESIGN-CHART §3.3, measured
-     * 2026-10-16), or `null` where its cells cannot be read and the cache it has stands.
-     */
     private _cacheOf;
     /**
      * A multi-level category cache: one level per column, the innermost (the last) first, each
@@ -250,12 +240,6 @@ export declare class Chart extends AbstractMovableContent<State, IChart.JSON, IC
     /** {@inheritDoc IChart.isIChart} */
     get isIChart(): true;
 }
-/**
- * A number as Excel writes it into a chart cache (measured 2026-10-16, `probe-chart-values.ps1`
- * W3): its shortest digits when 15 or fewer say it, else 17; in exponent form (`1E-3`, `1E+16`)
- * below 0.01 and from 10^16 up. Excel sometimes writes 17 digits where fewer say the same number
- * (`1.0000000000000001E-5`); either reads back as the same number.
- */
 export declare const cacheNumberText: (value: number) => string;
 /**
  * Interfaces for creating `Chart` items.

package/types/src/chart/_ChartParts.d.ts

@@ -330,7 +330,6 @@ export declare class ChartAxis implements IChart.IAxis {
     setCustomDisplayUnit(unit: number, options?: ITransaction.OperationOptions): this;
     getShowDisplayUnitLabel(): boolean;
     setShowDisplayUnitLabel(show: boolean, options?: ITransaction.OperationOptions): this;
-    /** The axis crossing this one: where VBA's `Crosses` is written (DESIGN-CHART §3.6). */
     private _crossing;
     getCrosses(): IChart.AxisCrosses;
     setCrosses(crosses: IChart.AxisCrosses, options?: ITransaction.OperationOptions): this;
@@ -362,7 +361,6 @@ export declare class ChartAxis implements IChart.IAxis {
     setCategoryType(type: IChart.AxisCategoryType, options?: ITransaction.OperationOptions): this;
     /** The dates of the first series on the axis, as numbers; `null` where its categories are not all dates. */
     private _dates;
-    /** The base unit Excel chooses for the axis's dates (DESIGN-CHART §4.2), `days` without any. */
     private _automaticBaseUnit;
     /** The axis's categories from a setter's input. @throws ExpectedError where the axis has none. */
     private _categoriesEdit;
@@ -509,16 +507,6 @@ export declare class ChartSeries implements IChart.ISeries {
      * size (5-200).
      */
     private _groupOption;
-    /**
-     * The series given `type`, as one edit: moved to its group by `_Grouping`'s measured moves, and
-     * drawn as a series of the type is (`drawSeriesAsType`). Every series whose group changed type is
-     * drawn anew, as Excel does when bubble or 3-D types take the whole chart; one that stays in its
-     * group changes its markers, and a scatter its line, keeping its own fill and line otherwise. A
-     * series that becomes a scatter's states its categories and values as x and y values, and the
-     * other way round. No series can be given a stock type: Excel refuses one
-     * (`probe-chart-stock-refusals.ps1`); nor an of-pie, which is not measured; nor a 3-D form, a
-     * surface or a 2016 type, which take the whole chart (`IChart.setChartType`).
-     */
     private _typeEdit;
     private _axisGroupEdit;
     getFormula(): string;
@@ -546,11 +534,6 @@ export declare class ChartSeries implements IChart.ISeries {
      * plot order, the sizes for a bubble.
      */
     private _formulaEdits;
-    /**
-     * The categories set through this series: a scatter's or bubble's x values are its own; a
-     * category chart's categories are shared by every series on its axis, so each takes them, and
-     * `null` clears them all (measured 2026-10-18, `probe-chart-api.ps1` S01-S04).
-     */
     private _categoriesEdit;
     /** A dimension's source, from a setter's input. */
     private _source;
@@ -751,17 +734,7 @@ export declare class ChartErrorBars implements IChart.IErrorBars {
     edits(update: IChart.IErrorBars.Update): ModelEdit[];
     update(update: IChart.IErrorBars.Update, options?: ITransaction.OperationOptions): this;
 }
-/**
- * Whether Excel draws up/down bars and high-low lines for a group: a 2-D line or stock group
- * (`probe-chart-lines.ps1`; 3-D lines refused by belief).
- */
 export declare const takesUpDownBars: (group: ChartModel.Group) => boolean;
-/**
- * Whether Excel draws a group's lines of `kind` (`probe-chart-lines.ps1`): high-low lines on a line
- * or stock group; drop lines on a line, area or stock group (D09: COM takes them on a scatter and
- * writes none); series lines on stacked and 100% stacked bars and pie of pie (V06: COM takes them on
- * clustered columns and writes none). 3-D groups are refused by belief.
- */
 export declare const takesLines: (group: ChartModel.Group, kind: Edits.GroupLinesKind) => boolean;
 export declare class ChartGroupLines implements IChart.ILines {
     private readonly _host;
@@ -995,11 +968,6 @@ export declare class ChartGroup implements IChart.IChartGroup {
     getVaryByCategories(): boolean;
     setVaryByCategories(vary: boolean, options?: ITransaction.OperationOptions): this;
 }
-/**
- * Every series' data labels at once (Office Scripts' `chart.getDataLabels()`, VBA's
- * `ApplyDataLabels`, `probe-chart-api.ps1` L01): reads answer the first series', each setter sets
- * every series as one step.
- */
 export declare class ChartAllLabels implements IChart.IDataLabels {
     private readonly _host;
     private readonly _all;
@@ -1054,13 +1022,6 @@ export interface ChartElementParts {
     plotArea: ChartPlotArea;
     dataTable: ChartDataTable;
 }
-/**
- * The edits of a chart element (VBA's `SetElement`, measured 2026-10-18, `probe-chart-elements.ps1`):
- * each `msoElement…` as the setters above make it. A data label element sets every series; a
- * trendline, error bar, line or up/down bar element every series or group that takes one. What
- * Excel refuses (an element of axes the chart has none of, a label position its type has none of,
- * a trendline on a pie) throws `ExpectedError`.
- */
 export declare const elementEdits: (parts: ChartElementParts, element: IChart.Element) => ModelEdit[];
 export {};
 //# sourceMappingURL=_ChartParts.d.ts.map