@sheetxl/sdk 0.7.28-beta.4 → 0.8.0-beta.2

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

@@ -1,10 +1,10 @@
 import { FormulaError, IRange, Scalar, InteropScalar, IRangeStats } from '@sheetxl/primitives';
-import { Bounds, ReferenceableClipboard } from '@sheetxl/utils';
+import { Bounds, Size, ReferenceableClipboard } from '@sheetxl/utils';
 import { ITypes } from '../type';
 import { IListener } from '../listener';
 import { ITransaction } from '../transaction';
 import { IHyperlink } from '../hyperlink';
-import { IComment } from '../comment';
+import { IComment, ICommentCollection } from '../comment';
 import { ISort } from '../sort';
 import { ICondition } from '../condition';
 import { IAutoFill } from '../autoFill';
@@ -15,6 +15,7 @@ import { IMovable, IMovableCollection } from '../movable';
 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 { ICell } from '../cell';
 import { ICellRanges } from './ICellRanges';
@@ -66,6 +67,18 @@ export interface ICellRange {
      * * @returns An array of 'IRange.Coords` that contain merges.
      */
     getMerges(): IRange.Coords[];
+    /**
+     * Returns the unlocked ranges (Excel's *Allow Edit Ranges*) that overlap the range.
+     *
+     * @param options The filters of {@link IProtectedRangeCollection.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 can also be unlocked by its style
+     * (`IStyle.getProtection()`); {@link ICell.isEditAllowed} answers for both.
+     */
+    getUnlocked(options?: ICellRange.GetItemsOptions<IProtectedRangeCollection.GetItemsOptions>): IProtectedRange[];
     /**
      * Returns the {@link IConditionalFormat}s that overlap the range.
      *
@@ -96,6 +109,17 @@ export interface ICellRange {
      * same for every ranged item lookup.
      */
     getDataValidations(options?: ICellRange.GetItemsOptions<IDataValidationCollection.GetItemsOptions>): IDataValidation[];
+    /**
+     * Returns the {@link IComment}s on cells within the range.
+     *
+     * @param options The filters of {@link ICommentCollection.getItems} without `address` — this
+     * range is the address.
+     *
+     * @remarks
+     * The items are the sheet's — a scoped view of `getSheet().getComments()`, not a copy. A
+     * comment is on one cell, so each appears once, in reading order.
+     */
+    getComments(options?: ICellRange.GetItemsOptions<ICommentCollection.GetItemsOptions>): IComment[];
     /**
      * Returns the {@link ITable}s that overlap the range.
      *
@@ -173,13 +197,73 @@ export interface ICellRange {
      * @remarks
      * When querying the formula this will always be for the top left. However the
      * set values work for the entire range.
+     *
+     * Returns the formula object, or `null` for a cell without one. For formula text across the
+     * whole range use {@link ICellRange.getFormulas}, which reads `''` for cells without a formula.
      */
     getFormula(address?: ICell.Address): ICalculation.IFormula;
+    /**
+     * Returns the formula text of every cell in the range.
+     *
+     * @returns A row-major 2D array in the shape of the range.
+     *
+     * @remarks
+     * - Each formula reads as entered, with its leading `=` (`'=SUM(A1:A3)'`), so the result can be
+     *   passed straight back to {@link ICellRange.setFormulas}.
+     * - A cell without a formula reads as an empty string `''`, not `null`. This differs from
+     *   {@link ICell.getFormulaText} and {@link ICellRange.getFormula}, which return `null`.
+     * - Throws if the range holds more than `10000` cells, like {@link ICellRange.getValues}.
+     *
+     * @see {@link ICellRange.getFormula}
+     */
+    getFormulas(): string[][];
+    /**
+     * Returns the number format of the top-left cell.
+     *
+     * @remarks
+     * Reads the top-left cell, the same contract as {@link ICellRange.getValue} and
+     * {@link ICellRange.getStyle}. A cell without an authored format reads `'General'`.
+     *
+     * @see {@link IStyle.getNumberFormat}
+     */
+    getNumberFormat(): string;
+    /**
+     * Returns the number format of every cell in the range.
+     *
+     * @returns A row-major 2D array in the shape of the range.
+     *
+     * @remarks
+     * - A cell without an authored format reads `'General'`.
+     * - Throws if the range holds more than `10000` cells, like {@link ICellRange.getValues}.
+     *
+     * @see {@link IStyle.getNumberFormat}
+     */
+    getNumberFormats(): string[][];
+    /**
+     * Sets one number format on every cell in the range.
+     *
+     * @param numFmt The format code, or `null` to clear it.
+     *
+     * @see {@link IStyle.setNumberFormat}
+     */
+    setNumberFormat(numFmt: string | null, options?: IStyle.UpdateOptions): this;
+    /**
+     * Sets the number format of each cell in the range.
+     *
+     * @param formats Format codes in row-major order.
+     *
+     * @remarks
+     * An array smaller than the range writes only the cells it covers, as {@link ICellRange.setValues} does.
+     *
+     * @see {@link ICellRange.setNumberFormat}
+     */
+    setNumberFormats(formats: readonly string[][], options?: ICellRange.UpdateCellsOptions): this;
     /**
      * Parses a formula expression and returns a *transient* formula object anchored at this range's
      * top-left cell.
      *
      * @param expression The formula expression to parse.
+     * @param options Optional parse options; the expression is storage text unless `target` is `'display'`.
      *
      * @remarks
      * The anchored convenience form: equivalent to
@@ -196,7 +280,7 @@ export interface ICellRange {
      * @see {@link ISheet.createFormula}
      * @see {@link ICalculation.createFormula}
      */
-    createFormula(expression: string): ICalculation.IFormula;
+    createFormula(expression: string, options?: ICalculation.CreateFormulaOptions): ICalculation.IFormula;
     /**
      * Returns the intersection of the current range and the specified range.
      *
@@ -486,6 +570,27 @@ export interface ICellRange {
      * merges.
      */
     getDefaultSortCriteria(axis?: IRange.Axis, cell?: ICell.Address): ISort.DefaultSortCriteria | null;
+    /**
+     * Returns the fill this range implies — which cells it would read, which it would cover, the
+     * fill types that can be offered for it, and the one to open on.
+     *
+     * @param direction Which way the series runs. Defaults to the range's own shape: a single row
+     * runs `Right`, anything else runs `Down` — or, with a `destination`, to the way it extends.
+     * @param destination Fill the range as it is to here — the fill handle's drag. The template is
+     * then the WHOLE range, blanks included, rather than its leading run, and `destination` must
+     * extend it on exactly one edge as {@link autoFill} requires.
+     * @returns `IAutoFill.DefaultCriteria`, or `null` where there is nowhere to fill: the range is
+     * one cell deep along `direction`, or `destination` does not extend it — which is also how a
+     * surface learns that a direction is not on offer at all.
+     * @throws `Error` If `destination` does not share three edges with the range, or `direction` is
+     * not the way it extends.
+     *
+     * @remarks
+     * Useful for displaying options to the ui — a Series dialog, or a fill menu deciding what to
+     * grey. Nothing is filled and nothing is committed; see {@link autoFill} to run one, and
+     * {@link AutoFill.toFillOptions} for the options a chosen {@link IAutoFill.Preset} amounts to.
+     */
+    getDefaultAutoFillCriteria(direction?: IRange.Direction, destination?: ICellRange.Address): IAutoFill.DefaultCriteria | null;
     /**
      * Returns the ranges immediately referenced by the formulas in this range.
      *
@@ -494,39 +599,39 @@ export interface ICellRange {
      * rather than a fan-out — the calculation graph is indexed by range, so the cell form is this
      * one over a 1×1.
      *
-     * - Returns `null` when there are none.
+     * - Resolves `null` when there are none; see {@link ICell.getDirectPrecedents} for when it resolves.
      * - **Not filtered against the range itself.** A block containing both a formula and its input
      *   lists that input; "what does this block read" and "what does it read from outside" are
      *   different questions, and the second is {@link getDifferences} away.
      */
-    getDirectPrecedents(): ICellRanges | null;
+    getDirectPrecedents(): Promise<ICellRanges | null>;
     /**
      * Returns the cells that directly reference any cell in this range.
      *
      * @remarks
      * The range form of {@link ICell.getDirectDependents} — the immediate consumers of anything
-     * this range produces. Returns `null` when there are none.
+     * this range produces. Resolves `null` when there are none.
      */
-    getDirectDependents(): ICellRanges | null;
+    getDirectDependents(): Promise<ICellRanges | null>;
     /**
      * Returns all ranges contributing to this range's values, through the full calculation chain.
      *
      * @remarks
      * The range form of {@link ICell.getPrecedents}: a recursive walk upstream to the root data
-     * sources. Returns `null` when there are none.
+     * sources. Resolves `null` when there are none.
      *
      * **Reach for this before editing.** The precedents of a block are what its values depend on,
      * so they are what a change to it can be wrong about.
      */
-    getPrecedents(): ICellRanges | null;
+    getPrecedents(): Promise<ICellRanges | null>;
     /**
      * Returns all cells eventually affected by this range, through the full calculation chain.
      *
      * @remarks
      * The range form of {@link ICell.getDependents}: a recursive walk downstream giving the total
-     * blast radius of a write here. Returns `null` when there are none.
+     * blast radius of a write here. Resolves `null` when there are none.
      */
-    getDependents(): ICellRanges | null;
+    getDependents(): Promise<ICellRanges | null>;
     /**
      * Returns the statistics for the range.
      *
@@ -541,12 +646,6 @@ export interface ICellRange {
      * indexes) — they do not overlap.
      */
     getStats(options?: ICellRange.GetStatsOptions): IRangeStats;
-    /**
-     * Returns a count for of values.
-     *
-     * @deprecated Use `getStats`.
-     */
-    getCount(): number;
     /**
      * Returns per-feature cell counts for the range.
      *
@@ -595,13 +694,15 @@ export interface ICellRange {
      *   feature-bearing side of the partition.
      * - **Nothing is computed until the result is iterated or counted.** The returned
      *   {@link ICellRegions} is a lazily backed handle, so building the query costs nothing.
-     * - **`Contentful` regions are maximal rectangles.** Every other feature's stored blocks stand
-     *   for a payload two adjacent blocks can disagree about — a fill's color, a formula's
-     *   expression — so distinct blocks stay distinct or the region stops being uniform. Occupancy
-     *   is a boolean: any two occupied rectangles agree, so its blocks carry no information and are
-     *   coalesced. A solid `A1:D4` is one region, not the four column strips it is stored as.
-     *   Refinement is unaffected — `[Contentful, Fill]` still partitions by fill and still excludes
-     *   unoccupied cells.
+     * - **Regions follow the payload, not how it was written.** A solid `A1:D4` is one
+     *   `Contentful` region, and a number format applied in three strokes (or loaded from a file
+     *   that stored it in pieces) is one `NumberFormat` region. The same holds for `Fill` and the
+     *   other content-style features (`Font`, `Alignment`, `Protection`), and each of those splits
+     *   only on its own part: a bold column inside a uniform number format does not split the
+     *   `NumberFormat` region. `Borders` is the exception — a border's edges belong to the block
+     *   it was applied to, so two equal boxes side by side are two regions. Refinement is
+     *   unaffected — `[Contentful, Fill]` still partitions by fill and still excludes unoccupied
+     *   cells.
      * - Every {@link Feature} partitions — there is no throwing member left. `DateFormat` splits by
      *   format string, the same way `Fill` splits by color; `Error` splits by error value, backed
      *   by the reconciled error index. Scalar kinds (`String`/`Number`/`Boolean`) are not in this
@@ -636,7 +737,7 @@ 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 and will repeat if the range is larger than the array
+     * - 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.
      */
     setValues(values: ICellRange.ValuesUpdate, options?: ICellRange.SetValuesOptions): this;
@@ -668,11 +769,24 @@ export interface ICellRange {
      * @returns The current `ICellRange`.
      *
      * @remarks
-     * Identical behavior to setValue. Exists for ergonomics
+     * Identical behavior to setValue. Exists for ergonomics.
+     *
      * @see
      * {@link ICellRange.setValue}
      */
     setFormula(value: ICellRange.ValuesUpdateOrCallback, options?: ICellRange.SetValuesOptions): this;
+    /**
+     * Sets the formula of each cell in the range.
+     *
+     * @param formulas Formula text in row-major order, each with a leading `=`.
+     *
+     * @remarks
+     * The same write as {@link ICellRange.setValues}: text with a leading `=` is entered as a
+     * formula, and an array smaller than the range writes only the cells it covers.
+     *
+     * @see {@link ICellRange.getFormulas}
+     */
+    setFormulas(formulas: readonly string[][], options?: ICellRange.SetValuesOptions): this;
     /**
      * Re-evaluates and formulas within the range.
      *
@@ -721,7 +835,7 @@ export interface ICellRange {
     /**
      * Clear the range.
      *
-     * @param applyTo The type of content to clear. Default `ICell.Content.Values`
+     * @param applyTo The type of content to clear. Defaults to all`
      * @returns The current `ICellRange`.
      */
     clear(applyTo?: ICell.Content, options?: ITransaction.OperationOptions): this;
@@ -736,15 +850,18 @@ export interface ICellRange {
      */
     setHyperlink(hyperlink: IHyperlink.Update, options?: ITransaction.OperationOptions): this;
     /**
-     * Update the comments for the range.
+     * Sets or clears the comment on the range's first cell.
      *
-     * @param comments Comment properties
+     * @param comments Comment modifiers, a plain string as the content, or `null` to remove.
      * @returns The current `ICellRange`.
      *
      * @remarks
-     * **NOT FINISHED**
+     * 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
+     * {@link ICell.getComments} to reach the one on a cell.
      */
-    setComments(comments: IComment.Properties, options?: ITransaction.OperationOptions): this;
+    setComments(comments: IComment.Update, options?: ITransaction.OperationOptions): this;
     /**
      * Merges all cells within the selection ranges.
      *
@@ -908,6 +1025,24 @@ export interface ICellRange {
      * * Will return `null` if nothing was inserted or the source doesn't have a range.
      */
     insertFrom(source: ICellRange.Address | ICellRange.ISnapshot, options?: ICellRange.InsertFromOptions): Promise<this | null>;
+    /**
+     * Whether {@link insertFrom} would go through, asked without performing it.
+     *
+     * @param source The source that would be inserted - the same argument `insertFrom` takes.
+     * @param options The same options `insertFrom` would be given; `axis` and `isCut` both change the
+     *   answer, so pass the ones the real call will use.
+     * @returns `false` when `insertFrom` would refuse, `true` otherwise.
+     *
+     * @remarks
+     * A drop can be refused for reasons the caller cannot see: a cut whose gap the insert would only
+     * half close, a merge the shift would tear or land inside of, a table it would split. This answers
+     * the same question `insertFrom` asks itself before it commits, which is what lets an interactive
+     * drag show a drop as refused BEFORE the user commits to it, rather than reporting an error after.
+     *
+     * It reports only what can be known up front. A refusal raised deeper in the operation (protection,
+     * or content pushed off the end of the sheet) still surfaces as a thrown error.
+     */
+    canInsertFrom(source: ICellRange.Address | ICellRange.ISnapshot, options?: ICellRange.InsertFromOptions): boolean;
     /**
      * Copies (or cuts) data and formatting from a specified source to the current range.
      *
@@ -1018,11 +1153,17 @@ export interface ICellRange {
      * caller did not ask. To watch a formula belonging to a multi-area rule, fill it first — or use
      * {@link ICellRanges.addWatch}, which does that for every area.
      *
-     * Known limits, both from watching the formula's *written* references: a range discovered at
-     * evaluation time (`INDIRECT`, `OFFSET`) is not watched, and a volatile formula (`NOW`, `RAND`)
-     * has nothing to watch at all. Neither re-fires.
+     * The formula is held by the calculation engine like a formula in a cell: its references follow
+     * row and column inserts and deletes, a reference to deleted cells reads `#REF!`, and undo
+     * restores it. A range the formula discovers at evaluation time (`INDIRECT`, `OFFSET`) is watched
+     * too. A volatile formula (`NOW`, `RAND`) re-evaluates with the engine's pass and does not re-fire
+     * on its own.
+     *
+     * With {@link ICellRange.WatchOptions.arrayFirstCell} each cell is evaluated the way a
+     * conditional-format or data-validation rule evaluates its formula: as an array-entered formula
+     * whose extent is that one cell.
      */
-    addWatch(formula: ICalculation.IFormula | string, callback: ICellRange.WatchCallback): IListener.Remove;
+    addWatch(formula: ICalculation.IFormula | string, callback: ICellRange.WatchCallback, options?: ICellRange.WatchOptions): IListener.Remove;
     /**
      * Returns an iterator that allows you to iterate over the individual values within the range.
      *
@@ -1102,6 +1243,22 @@ export interface ICellRange {
      * Returns the absolute bounds for the range.
      */
     getBounds(): Bounds;
+    /**
+     * The size this range's content needs — what {@link getBounds} would report if the range had
+     * been {@link autoFit}. A pure query: nothing is measured onto the model and nothing is committed.
+     *
+     * @param options Measurement options. Default `{ axes: IRange.AxisSelection.Both }`.
+     *
+     * @remarks
+     * - The width is the sum of the per-column best fits and the height the sum of the per-row best
+     *   fits, so a single-column range answers "how wide must this list be" directly.
+     * - An axis left out of {@link BestFitOptions.axes} reports its current size.
+     * - Only the range's own content is measured, so the answer never depends on cells outside it.
+     *   (`autoFit` also scans outside the range, to prove a shrink is safe.)
+     * - Sheet protection is not consulted: reading a size cannot violate it, and a protected sheet
+     *   answers the same as an unprotected one.
+     */
+    getBestFit(options?: ICellRange.BestFitOptions): Size;
     /**
      * Indicates if the range is readonly only.
      *
@@ -1146,7 +1303,7 @@ export interface ICellRange {
      * Checks if the ranges is empty, meaning it has no values or formatting.
      *
      * @remarks
-     * Convenience ```getUsedRange() !== null``` or `getCount() === 0`.
+     * Convenience ```getUsedRange() === null```.
      *
      * @see
      * {@link ICellRange.getUsedRange}
@@ -1306,10 +1463,70 @@ export declare namespace ICellRange {
      * dropped because the range **is** the address — a second one would be a contradictory scope.
      */
     type GetItemsOptions<T> = Omit<T, 'address'>;
+    /**
+     * Options shared by every operation on a range.
+     *
+     * @remarks
+     * `autoSelect` and `autoFit` are *directives*: they name something to do once the operation
+     * completes rather than a change the operation makes. Both are resolved once, for the whole
+     * operation, and neither adds an undo entry of its own - a batch that sets values and fits
+     * the columns is one undo step that puts both back.
+     */
+    interface OperationOptions extends ITransaction.OperationOptions {
+        /**
+         * Select the affected range once the operation completes.
+         *
+         * @defaultValue `false` - the selection is left alone.
+         *
+         * @remarks
+         * The selection is applied once, after the whole operation - within a batch, the last
+         * operation to ask for one wins. It is applied only if the selection is still where it was
+         * when the operation began: a user who moved while it ran keeps where they went.
+         *
+         * Pass it for an edit the user made. A script that passes neither this nor
+         * {@link autoSelectRestore} never moves the user, whether it runs, is undone or is redone.
+         */
+        autoSelect?: boolean | ICellRange.SelectOptions;
+        /**
+         * Select the affected range when the operation is undone or redone.
+         *
+         * @defaultValue {@link autoSelect}
+         *
+         * @remarks
+         * An undo lands where the operation began - for most operations the range they affected, for
+         * an auto-fill the template it was dragged from - and a redo where it left the user. Within a
+         * batch an undo lands where the first operation to ask says, a redo where the last one does.
+         *
+         * For an edit made from where the user already is, pass this without {@link autoSelect}: a
+         * value typed into a cell of a selected block leaves the block selected, and undoing it
+         * selects the cell.
+         */
+        autoSelectRestore?: boolean | ICellRange.SelectOptions;
+        /**
+         * Fit the affected columns and rows to their content once the operation completes.
+         *
+         * @defaultValue `false` - sizes are left alone.
+         *
+         * @remarks
+         * The fit runs once, as the last write of the operation, so it measures the finished
+         * content and its sizes belong to the same undo entry - one undo puts both the content
+         * and the widths back.
+         *
+         * If set to `true` then autoFit will mimic the UI with the following options:
+    ```
+    {
+      skipCustomSize: true,
+      expandOnly: true,
+      minContent: true
+    }
+    ```
+         */
+        autoFit?: boolean | ICellRange.AutoFitOptions;
+    }
     /**
      * Options for adding an auto table to a range.
      */
-    interface AddAutoTableOptions extends ITransaction.OperationOptions {
+    interface AddAutoTableOptions extends ICellRange.OperationOptions {
         /**
          * Include sort options.
          */
@@ -1326,7 +1543,7 @@ export declare namespace ICellRange {
     /**
      * Options for `ICellRange.delete`.
      */
-    interface InsertOptions extends ITransaction.OperationOptions {
+    interface InsertOptions extends ICellRange.OperationOptions {
         /**
          * The direction in which to shift existing cells.
          *
@@ -1355,7 +1572,7 @@ export declare namespace ICellRange {
     /**
      * Options for `ICellRange.delete`.
      */
-    interface DeleteOptions extends ITransaction.OperationOptions {
+    interface DeleteOptions extends ICellRange.OperationOptions {
         /**
          * The direction in which to shift existing cells.
          *
@@ -1458,8 +1675,9 @@ export declare namespace ICellRange {
          * @defaultValue false
          *
          * @remarks
-         * If `true` then tables and sheet boundaries will be ignored mimicking the behavior
-         * of 'Ctrl+Shift+*'.
+         * If `true`, the region is the contiguous block of content around the range (Excel's
+         * 'Ctrl+Shift+*' current region): tables are not treated as regions of their own, and a range
+         * with no content nearby returns itself rather than the entire sheet.
          */
         contentOnly?: boolean;
     }
@@ -1475,7 +1693,7 @@ export declare namespace ICellRange {
     /**
      * Options for {@link ICellRange.ISnapshot.copyTo}.
      */
-    interface CopyOptions extends ITransaction.OperationOptions, ReferenceableClipboard.CopyOptions {
+    interface CopyOptions extends ICellRange.OperationOptions, ReferenceableClipboard.CopyOptions {
         /**
          * When pasting from a smaller range to a larger range copy will repeat or 'wallpaper' the
          * source values.
@@ -1530,7 +1748,7 @@ export declare namespace ICellRange {
     /**
      * Options for {@link ICellRange.setValues}.
      */
-    interface SetValuesOptions extends ITransaction.OperationOptions {
+    interface SetValuesOptions extends ICellRange.OperationOptions {
         /**
          * By default setValue will attempt to parse text values into a native type.
          * This can be disabled or customized using the parseText flag.
@@ -1546,21 +1764,6 @@ export declare namespace ICellRange {
          * Both {@link SetValuesOptions} and {@link GetValuesOptions} allow for {@link IRange.Axis}s.
          */
         axis?: IRange.Axis;
-        /**
-         * Convenience method that calls autoFit after the setValues.
-         * @defaultValue `none` - No autofit.
-         *
-         * @remarks
-         * If set to `true` then autoFit will mimic the UI with the following options:
-    ```
-    {
-      skipCustomSize: true,
-      expandOnly: true,
-      minContent: true
-    }
-    ```
-         */
-        autoFit?: boolean | ICellRange.AutoFitOptions;
         /**
          * Skip the bounds check when setting values.
          *
@@ -1571,6 +1774,43 @@ export declare namespace ICellRange {
          * size requires processing the entire dataset.
          */
         skipBoundsCheck?: boolean;
+        /**
+         * Enter a single formula as an array formula (Excel's Ctrl+Shift+Enter) over the whole range.
+         *
+         * @defaultValue `false`
+         *
+         * @remarks
+         * The range is the block's extent and the formula sits at its top-left; the result is fitted
+         * to the extent rather than spilling from it - a dimension of 1 broadcasts, a longer one is
+         * clipped, a shorter one is padded with `#N/A` - and the block never resizes. Its cells can
+         * only be changed as a whole: overwriting, clearing, or inserting/deleting through part of a
+         * block is refused ("You can't change part of an array"); rewriting it through this option
+         * with the same range replaces it.
+         *
+         * Only meaningful for {@link ICellRange.setFormula} with one formula.
+         */
+        arrayFixed?: boolean;
+        /**
+         * Give each entered formula the number format of the first cell it reads that has one, or
+         * failing that the format its result carries, once it has been calculated.
+         *
+         * @defaultValue `false` - the cell keeps the format it has.
+         *
+         * @remarks
+         * What typing a formula into a cell does: `=A1*2` shows currency when `A1` does, `=NOW()`
+         * shows a date, `=DATE(2024,1,15)` a short date. A cell the formula reads ranks ahead of a
+         * function's format (`=A1+TODAY()` is currency when `A1` is); references are taken in the
+         * order written, a range stands for its top-left cell, and a reference a function only
+         * points at (`=ROW(A1)`, `=OFFSET(A1,0,0)`) does not count. The format becomes the cell's
+         * own, exactly as if set by hand, so it stays when the formula is replaced by a value and is
+         * part of the same undo entry as the formula. A format the cell already had wins.
+         *
+         * Only the formulas this operation enters are formatted, and only when they are first
+         * compiled and calculated - a later recalculation of the same cell changes nothing, and
+         * neither does formatting a cell it reads. Pair with {@link OperationOptions.autoFit} to also
+         * widen a column the formatted result no longer fits.
+         */
+        autoFormat?: boolean;
     }
     /**
      * Options for {@link ICellRange.getValues}.
@@ -1613,9 +1853,9 @@ export declare namespace ICellRange {
         includeMergeOverflow?: boolean;
     }
     /**
-     * Options for {@link ICellRange.autoFit}.
+     * Options for {@link ICellRange.getBestFit} — measurement only.
      */
-    interface AutoFitOptions extends ITransaction.OperationOptions {
+    interface BestFitOptions {
         /**
          * Best fit using the minimum amount of space required.
          *
@@ -1626,21 +1866,6 @@ export declare namespace ICellRange {
          * For example allowing numbers to round or use scientific notation.
          */
         minContent?: boolean;
-        /**
-         * Restricts autoFit to only grow, never shrink.
-         *
-         * @defaultValue false - adjust in both directions.
-         *
-         * @remarks
-         * This is useful when adjusting fonts and wan the columns to resize but not the rows.
-         */
-        expandOnly?: boolean | IRange.Axis;
-        /**
-         * If this is set to `true` then any headers that have custom sizes will be ignored.
-         *
-         * @defaultValue false
-         */
-        skipCustomSize?: boolean;
         /**
          * The axes to autoFit.
          *
@@ -1662,6 +1887,26 @@ export declare namespace ICellRange {
          */
         formulaView?: boolean;
     }
+    /**
+     * Options for {@link ICellRange.autoFit}.
+     */
+    interface AutoFitOptions extends BestFitOptions, ITransaction.OperationOptions {
+        /**
+         * Restricts autoFit to only grow, never shrink.
+         *
+         * @defaultValue false - adjust in both directions.
+         *
+         * @remarks
+         * This is useful when adjusting fonts and wan the columns to resize but not the rows.
+         */
+        expandOnly?: boolean | IRange.Axis;
+        /**
+         * If this is set to `true` then any headers that have custom sizes will be ignored.
+         *
+         * @defaultValue false
+         */
+        skipCustomSize?: boolean;
+    }
     /**
      * Options for {@link ICellRanges.getFlattened}.
      */
@@ -1708,7 +1953,7 @@ export declare namespace ICellRange {
     /**
      * Options for {@link ICellRange.autoFill}.
      */
-    interface AutoFillOptions extends ITransaction.OperationOptions {
+    interface AutoFillOptions extends ICellRange.OperationOptions {
         /**
          * Provide custom fillers.
          *
@@ -1722,11 +1967,21 @@ export declare namespace ICellRange {
          */
         fillerOptions?: IAutoFill.Options;
         /**
-         * If `true` then will only copy values and not formatting.
+         * Which part of the cells the fill carries — the same selector {@link CopyOptions.type} takes.
+         *
+         * @defaultValue Everything: values, formulas and formatting.
          *
-         * @defaultValue false (unless starting within a table)
+         * @remarks
+         * * {@link ICell.Content.Formats} is Excel's *Fill Formatting Only*: the template's formatting
+         *   (styles, number formats, merges, conditional formats and validations) is tiled into the
+         *   destination and the values already there are left alone. The `filler` is not consulted.
+         * * {@link ICell.Content.Values} is *Fill Without Formatting*: the series is written and the
+         *   destination keeps its own formatting — a date series lands as plain serials in a cell that
+         *   has no date format of its own.
+         * * On a shrinking destination the vacated cells lose only the selected part.
+         * * Any other member throws — a fill has no notion of copying just hyperlinks or comments.
          */
-        contentsOnly?: boolean;
+        type?: ICell.Content;
         /**
          * Compute the fill but commit nothing — the returned range is a projection of the result.
          *
@@ -1853,7 +2108,7 @@ export declare namespace ICellRange {
     /**
      * Options for {@link ICellRange.textToColumns}.
      */
-    interface TextToColumnsOptions extends ITransaction.OperationOptions {
+    interface TextToColumnsOptions extends ICellRange.OperationOptions {
         /**
          * The character used to split the text.
          *
@@ -1919,7 +2174,7 @@ export declare namespace ICellRange {
     /**
      * Options for {@link ICellRange.removeDuplicates}.
      */
-    interface RemoveDuplicatesOptions extends ITransaction.OperationOptions {
+    interface RemoveDuplicatesOptions extends ICellRange.OperationOptions {
         /**
          * Indicates if the range has a header row.
          *
@@ -2208,13 +2463,18 @@ export declare namespace ICellRange {
         /** Direct fill. */
         readonly Fill: "fill";
         /** Direct borders. */
-        readonly Border: "border";
+        readonly Borders: "borders";
         /** Direct number format. Region payloads carry the format string and its category. */
         readonly NumberFormat: "numberFormat";
         /** Direct alignment. */
         readonly Alignment: "alignment";
         /** Direct font. */
         readonly Font: "font";
+        /**
+         * Direct cell protection format (`IStyle.getProtection()`): always unlocked, show formulas.
+         * A cell with none of its own reads its named style's, then Normal's.
+         */
+        readonly Protection: "protection";
         /** Merged spans. */
         readonly Merge: "merge";
         /** Table membership. */
@@ -2225,7 +2485,10 @@ export declare namespace ICellRange {
         readonly Hyperlink: "hyperlink";
         /** Has comments. */
         readonly Comments: "comments";
-        /** Explicitly unlocked cells — *can I write here* is a precondition, not a detail. */
+        /**
+         * Unlocked cells — covered by an unlocked range, or with an always-unlocked style. *Can I write
+         * here* is a precondition, not a detail.
+         */
         readonly Unlock: "unlock";
         /** Cells under conditional-format rules. */
         readonly Conditionals: "conditionals";
@@ -2505,19 +2768,34 @@ export declare namespace ICellRange {
     interface WatchCallback {
         (values: IRange): void;
     }
+    /**
+     * Options for {@link ICellRange.addWatch}.
+     */
+    interface WatchOptions {
+        /**
+         * Evaluate each cell of the range as an array-entered formula whose extent is that one cell.
+         *
+         * @remarks
+         * This is how a conditional-format or data-validation formula is evaluated. Nothing
+         * implicitly intersects — a range reads as the whole array wherever it appears — and each
+         * cell keeps the top-left value of its own result, the way an array-entered formula fits its
+         * result to its extent. So `$J$1:$J$9="x"` answers `J1="x"` in every cell, while
+         * `SUM(IF($J$1:$J$9="x",1,0))>1` still sums the whole array. A relative range moves with the
+         * cell, so `$J1:$J9="x"` answers each row's own `J` cell.
+         *
+         * By default a cell whose result is an array spills, as a formula filled across the range
+         * would.
+         *
+         * @defaultValue `false`
+         */
+        arrayFirstCell?: boolean;
+    }
     /**
      * Options to control which events trigger a listener. By default, all
      * event types will trigger the listener. Setting any of these options to
      * `true` will *prevent* the listener from being called for that event type.
      */
     interface ListenerOptions {
-        /**
-         * The actual range can also change due to insert/removes or delete of a sheet.
-         * Setting absoluteCoords to `true` will ignore shifts in the range.
-         *
-         * @defaultValue false
-         */
-        ignoreShifts?: boolean;
         /**
          * If `true`, the listener will *not* be called when the range's
          * address changes (due to row/column insert/delete, or moves)