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

package/types/src/sheet/SheetCell.d.ts

@@ -9,7 +9,7 @@ import { IDataValidation } from '../dataValidation';
 import { IHyperlink } from '../hyperlink';
 import { ICalculation } from '../calculation';
 import { IComment } from '../comment';
-import { IStyle, IStyleCollection } from '../style';
+import { ICellStyle, IStyleCollection } from '../style';
 import { ICell, ICellProtection } from '../cell';
 import { ICellRanges, ICellRange } from '../cellRange';
 import { ISheetProtection } from '../sheetProtection';
@@ -26,8 +26,10 @@ import { IConditionalFormat } from '../conditionalFormat';
 export interface ResolvedCellModifiers {
     type: ScalarType | undefined;
     value: Scalar | null | undefined;
-    style: IStyle.Update | null | undefined;
+    style: ICellStyle.Update | null | undefined;
+    impliedStyle: ICellStyle.Update | undefined;
     hyperlink: IHyperlink.Update | undefined;
+    comments: IComment.Update | undefined;
     formula: string | null | undefined;
     stringToParse: string | null | undefined;
 }
@@ -51,20 +53,50 @@ interface Cache<K, V> {
  * // TODO - remove style dependency and see if we can remove it.
  */
 export declare function resolveCellModifiers(runtime: IRuntime, update: ICell.Update, optionsFromString?: ICell.ModifiersFromStringOptions | null, resolvedStringCache?: Map<string, ICell.Modifiers> | null, // assumes the same fromStringOptions is used
-isParsingCustom?: boolean): ResolvedCellModifiers | undefined;
-export declare function csOverflowable(type: ScalarType, style: IStyle, prev?: boolean, next?: boolean): boolean;
+isParsingCustom?: boolean, destination?: IRange.CellCoords | null): ResolvedCellModifiers | undefined;
+/**
+ * The decorations (data bar, icon set) a cell's conditional rules draw — the walk behind
+ * {@link SheetCell.getConditionalDecorations}, without a cell.
+ *
+ * @remarks
+ * `getStyle` is a thunk, not a style: only a matched icon set consults it (to drop the icon for
+ * rotated/stacked text), and resolving a style eagerly for every cell of a rule's range is exactly
+ * what the callers — the cell's own lazy resolution, and autoFit's per-cell scan — must not pay.
+ */
+export declare function csConditionalDecorations(conditionals: IConditionalFormat | IConditionalFormat[] | null | undefined, rowIndex: number, colIndex: number, value: Scalar, getStyle: () => ICellStyle): Readonly<IConditionalFormat.Decorations>;
+/**
+ * The leading-edge width an icon-set decoration reserves for a cell of this style.
+ *
+ * @remarks
+ * The icon is a square of the font box drawn at the leading inset — where the first glyph of
+ * left-aligned text would start — and the text resumes one leading inset after it. So the
+ * reservation is the icon plus that second inset, and both terms are font-sized: a larger font
+ * reserves proportionally more and gets a proportionally larger icon.
+ *
+ * Both terms are properties of the STYLE, never of the value, so the gutter cannot shift as the
+ * cell is edited — which is what lets whatever draws the icon place it from the same two numbers
+ * instead of being told where the gutter ended. Measured on the empty string because the measurer
+ * keeps THAT one globally, keyed by font: the line height is a font metric, and reading it this way
+ * outlives the styles it is read through (see {@link calcAccountingBottomInset}, same idiom).
+ *
+ * Free-standing rather than a `SheetCell` member because measurement reaches it from two directions:
+ * a resolved cell ({@link SheetCell.getInsets}), and autoFit's segment scan, which has a style and
+ * a decoration but never builds the cell.
+ */
+export declare const csIconGutter: (style: ICellStyle) => number;
+export declare function csOverflowable(type: ScalarType, style: ICellStyle, prev?: boolean, next?: boolean): boolean;
 /**
  * Updates the overflow calc and returns a range if overflowed
  * @internal
  */
-export declare function calcTextOverflow(rowIndex: number, colIndex: number, type: ScalarType, style: IStyle, value: Scalar, prev: IRange.CellCoords | null, next: IRange.CellCoords | null, continuousCoords: IRange.Coords | null, cellOptions: SheetCellOptions): ICell.HorizontalOverflow | null;
+export declare function calcTextOverflow(rowIndex: number, colIndex: number, type: ScalarType, style: ICellStyle, value: Scalar, prev: IRange.CellCoords | null, next: IRange.CellCoords | null, continuousCoords: IRange.Coords | null, cellOptions: SheetCellOptions): ICell.HorizontalOverflow | null;
 /** Guaranteed to never return null */
 export declare function csStyle(value: Scalar, range: IRange.Coords | null, intersection: RangeState.Intersection | null, options: SheetCellOptions, direct: boolean, 
 /**
  * The range the style was QUERIED for, when wider than `range` (which is the cell it
  * materializes at). Only the inner border rules read it — see `CreateCellStyleOptions.extent`.
  */
-extent?: IRange.Coords): IStyle;
+extent?: IRange.Coords): ICellStyle;
 /**
  * Is `coords` spilled INTO — covered by a spill but not the ANCHOR that owns it?
  *
@@ -101,8 +133,8 @@ export interface BestFitViewOptions {
      */
     formulaText?: string;
 }
-export declare function csBestFit(type: ScalarType, style: IStyle, value: Scalar, options: SheetCellOptions, colWidth: number, isMinContent: boolean, isRowOnly: boolean, // if true we only measure the height
-customHash?: string | null, cache?: Cache<string, Readonly<Partial<Size>>>, view?: BestFitViewOptions): Readonly<Partial<Size>> | null;
+export declare function csBestFit(type: ScalarType, style: ICellStyle, value: Scalar, options: SheetCellOptions, colWidth: number, isMinContent: boolean, isRowOnly: boolean, // if true we only measure the height
+iconGutter?: number, customHash?: string | null, cache?: Cache<string, Readonly<Partial<Size>>>, view?: BestFitViewOptions): Readonly<Partial<Size>> | null;
 /**
  * A coords-keyed cache of resolved `ICell`s for hot read paths (rendering).
  *
@@ -111,6 +143,8 @@ customHash?: string | null, cache?: Cache<string, Readonly<Partial<Size>>>, view
  * (see `invalidateCaches` in `Sheet`). `LRUCache` satisfies this shape.
  */
 export interface RenderCellCache {
+    /** The number of cells cached. */
+    readonly size: number;
     get(key: number): ICell | undefined;
     set(key: number, value: ICell): void;
     clear(): void;
@@ -120,14 +154,16 @@ export interface SheetCellOptions {
     getRange(address: ICellRange.Address): ICellRange | null;
     getRanges: (address: ICellRanges.Address) => ICellRanges | null;
     getCalcGrid?(): ICalcGrid;
+    /** The engine's status; see `Formula.ConstructorOptions.getCalculationStatus`. */
+    getCalculationStatus?(): ICalculation.Status;
     /**
      * Calculation-graph neighbors — the same engine `ICellRange` uses, which is the point: the calc
      * grid answers in calc currency (grid stableIds, and virtual grids for named formulas) and it is
      * this seam that translates them to sheet names and drops what is not a sheet. Going at the grid
      * directly leaks a stableId into an address, where it prints as `#REF!`.
      */
-    dependencyRanges?(coords: IRange.Coords, kind: 'precedents' | 'dependents', direct: boolean): ICellRanges | null;
-    doBatchCalcGrid?(callback: (calcGrid: ICalcGrid) => IRange.Coords, options?: string | ITransaction.OperationOptions): void;
+    dependencyRanges?(coords: IRange.Coords, kind: 'precedents' | 'dependents', direct: boolean): Promise<ICellRanges | null>;
+    doBatchCalcGrid?(callback: (calcGrid: ICalcGrid) => Promise<IRange.Coords | null>, options?: string | ITransaction.OperationOptions): Promise<void>;
     /**
      * Resolve a sheet's internal stableId (rename-safe) to its display name, or `null`. Threaded into
      * {@link Formula.ConstructorOptions} so a committed formula's cross-sheet references resolve at the
@@ -146,7 +182,7 @@ export interface SheetCellOptions {
     createAt?(text: string, coords: IRange.CellCoords): ICalculation.IFormula | null;
     sheet: ISheet;
     styles: IStyleCollection;
-    normalStyleRanged: IProperties.ICellRanged<IStyle.Properties>;
+    normalStyleRanged: IProperties.ICellRanged<ICellStyle.Properties>;
     nextContentful(cell: IRange.CellCoords, limit: number, isLeft?: boolean): number;
     getProtection(): ISheetProtection;
     colHeaders?: ISheetHeader;
@@ -169,12 +205,23 @@ export declare class SheetCell implements ICell {
     protected _t: ScalarType;
     protected _v: Scalar;
     protected _d: Date | null | undefined;
+    protected _dfmt: string | null;
     protected _column: ITable.IColumn | null | undefined;
     protected _cd: Readonly<IConditionalFormat.Decorations> | undefined;
-    protected _s: IStyle | undefined;
-    protected _sd: IStyle | undefined;
+    protected _s: ICellStyle | undefined;
+    protected _sd: ICellStyle | undefined;
     constructor(options: SheetCellOptions, coords: IRange.CellCoords | null, type?: ScalarType, value?: Scalar, intersection?: RangeState.Intersection | null, p?: IRange.CellCoords | null, // prev
     n?: IRange.CellCoords | null);
+    /**
+     * The interop date, resolved on first ask. `null` when this cell isn't a date.
+     *
+     * @remarks
+     * The serial converted, gated on the format's category — which is all `NumberFormat.Parsed.asDate`
+     * is. Going through `getNumberFormat` would also resolve the cell's style and render its display
+     * text and runs, none of which the date is read from, and this is on `getInteropType`'s path: an
+     * interop scan pays it per cell.
+     */
+    protected _getDate(): Date | null;
     /** {@inheritDoc ICell.getRange} */
     getRange(): ICellRange;
     /** {@inheritDoc ICell.isEqual} */
@@ -216,29 +263,35 @@ export declare class SheetCell implements ICell {
     /** {@inheritDoc ICell.getInsets} */
     getInsets(): Rectangle;
     /**
-     * The leading-edge width an icon-set decoration reserves, or `0` for a cell without one.
+     * The leading-edge width this cell's icon-set decoration reserves, or `0` for a cell without one.
      *
      * @remarks
-     * The icon is a square of the cell's LINE HEIGHT drawn at the leading inset — where the first
-     * glyph of left-aligned text would start — and the text resumes one leading inset after it. So
-     * the reservation is the icon plus that second inset, and both terms are already font-sized: a
-     * larger font reserves proportionally more and gets a proportionally larger icon.
-     *
-     * Both are properties of the STYLE, never of the value, so the gutter cannot shift as the cell is
-     * edited — which is what lets whatever draws the icon place it from the same two numbers instead
-     * of being told where the gutter ended. Measured on the empty string because the measurer keeps
-     * THAT one globally, keyed by font: the line height is a font metric, and reading it this way
-     * outlives the styles it is read through (see {@link calcAccountingBottomInset}, same idiom).
+     * See {@link csIconGutter} for what the reservation is made of. Every measurement of the cell —
+     * insets, best-fit, the editor's caret — reads it from here, so they cannot disagree with the
+     * icon layer, which places the icon from the same two style numbers.
      */
     protected _iconGutter(): number;
     /** {@inheritDoc ICell.getTextFrame} */
     getTextFrame(showFormula?: boolean): ITextFrame | null;
     /** {@inheritDoc ICell.getTextPlacement} */
     getTextPlacement(size: Size, useFormula?: boolean): ICell.TextPlacement | null;
-    /** {@inheritDoc ICell.getFormula} */
+    /**
+     * {@inheritDoc ICell.getFormula}
+     *
+     * @remarks
+     * Answered from the sheet's own formula entry, in every engine state: the text is there the
+     * moment it is set, the compiled block when the engine vends it. The handle reads the entry, so
+     * one taken before the vend is fully functional after it (`IFormula.isCompiled`).
+     */
     getFormula(): ICalculation.IFormula | null;
     /** {@inheritDoc ICell.getFormulaText} */
     getFormulaText(options?: ICalculation.FormulaTextOptions): string | null;
+    /**
+     * The formula's stored text, without the leading `=` — {@link ICalculation.IFormula.getExpression}
+     * without building the formula.
+     * @internal
+     */
+    getExpressionText(options?: ICalculation.FormulaTextOptions): string | null;
     /** {@inheritDoc ICell.getCalculationStatus} */
     getCalculationStatus(): ICalculation.ResultStatus;
     /**
@@ -250,13 +303,13 @@ export declare class SheetCell implements ICell {
      */
     private _dependencyRanges;
     /** {@inheritDoc ICell.getDirectDependents} */
-    getDirectDependents(): ICellRanges;
+    getDirectDependents(): Promise<ICellRanges | null>;
     /** {@inheritDoc ICell.getDirectPrecedents} */
-    getDirectPrecedents(): ICellRanges;
+    getDirectPrecedents(): Promise<ICellRanges | null>;
     /** {@inheritDoc ICell.getDependents} */
-    getDependents(): ICellRanges;
+    getDependents(): Promise<ICellRanges | null>;
     /** {@inheritDoc ICell.getPrecedents} */
-    getPrecedents(): ICellRanges;
+    getPrecedents(): Promise<ICellRanges | null>;
     /** {@inheritDoc ICell.getValue} */
     getValue(): Scalar;
     /** {@inheritDoc ICell.getType} */
@@ -266,9 +319,9 @@ export declare class SheetCell implements ICell {
     /** {@inheritDoc ICell.getInteropType} */
     getInteropType(): InteropScalarType;
     /** {@inheritDoc ICell.getStyle} */
-    getStyle(direct?: boolean): IStyle;
+    getStyle(direct?: boolean): ICellStyle;
     /** {@inheritDoc ICell.createCell} */
-    createCell(update: ICell.Update): ICell;
+    createCell(update: ICell.Update, options?: ICell.CreateCellOptions): ICell;
     /**
      * A copy of this cell that reports `coords` as its merge.
      *
@@ -287,7 +340,7 @@ export declare class SheetCell implements ICell {
     /** {@inheritDoc ICell.getText} */
     getText(options?: ICell.GetTextOptions): string;
     /** {@inheritDoc ICell.getComments} */
-    getComments(): Readonly<IComment.Properties>;
+    getComments(): IComment | null;
     /** {@inheritDoc ICell.getHyperlink} */
     getHyperlink(): IHyperlink | null;
     /** {@inheritDoc ICell.getErrors} */
@@ -302,6 +355,13 @@ export declare class SheetCell implements ICell {
     isTopLeft(): boolean;
     /** {@inheritDoc ICell.getSpill} */
     getSpill(): ICellRange | null;
+    /** {@inheritDoc ICell.getSpillKind} */
+    getSpillKind(): ITypes.FormulaArrayKind | null;
+    /**
+     * The spill entry this cell answers for: the first live one, else a blocked one so the UI can
+     * still show the range it would have taken.
+     */
+    protected _getSpillEntry(): SpillEntry | null;
     /** {@inheritDoc ICell.isSpillOverflow} */
     isSpillOverflow(): boolean;
     get [Symbol.toStringTag](): string;

package/types/src/sheet/SheetCollection.d.ts

@@ -1,18 +1,29 @@
+import { ICollection, AbstractCollection } from '../type';
+import { IListener } from '../listener';
 import { ISheetCollection } from './ISheetCollection';
 import { ISheet } from './ISheet';
-export declare class SheetCollection implements ISheetCollection {
+/**
+ * Implementation for {@link ISheetCollection}.
+ *
+ * @remarks
+ * A front over the workbook's own sheet state — the workbook keeps the store and the events,
+ * this class keeps the API. `onCollectionChange` is the workbook's `onSheetsChange`, forwarded
+ * with this collection as the source.
+ */
+export declare class SheetCollection extends AbstractCollection<ISheet, ISheetCollection.GetItemsOptions> implements ISheetCollection {
     private _add;
     private _get;
-    constructor(add: (options: ISheetCollection.AddOptions | string | number) => ISheet, get: (name?: string, visibility?: ISheet.Visibility) => ISheet[]);
+    private _addListeners;
+    constructor(add: (options: ISheetCollection.AddOptions | string | number) => ISheet, get: (name?: string, visibility?: ISheet.Visibility) => ISheet[], addListeners: (listeners: ICollection.IListeners, options?: IListener.Options) => IListener.Remove);
     /** {@inheritDoc ISheetCollection.add} */
     add(options?: ISheetCollection.AddOptions | string | number): ISheet;
-    /** {@inheritDoc ICollection.[Symbol.iterator]} */
-    [Symbol.iterator](): IterableIterator<ISheet>;
-    /** {@inheritDoc ISheetCollection.getItems} */
-    getItems(options?: ISheetCollection.GetItemsOptions): ISheet[];
+    /** {@inheritDoc AbstractCollection._getItems} */
+    protected _getItems(options?: ISheetCollection.GetItemsOptions): ISheet[];
     /** {@inheritDoc ISheetCollection.getByName} */
     getByName(name: string): ISheet;
-    /** {@inheritDoc ISheetCollection.getCount} */
-    getCount(): number;
+    /** {@inheritDoc ICollection.addListeners} */
+    addListeners(listeners: ICollection.IListeners, options?: IListener.Options): IListener.Remove;
+    /** {@inheritDoc ISheetCollection.isISheetCollection} */
+    get isISheetCollection(): true;
 }
 //# sourceMappingURL=SheetCollection.d.ts.map

package/types/src/sheet/SheetRange.d.ts

@@ -1,27 +1,37 @@
 import { IRange, Scalar, IRangeStats, InteropScalar } from '@sheetxl/primitives';
+import { Size, RunCoords } from '@sheetxl/utils';
 import { ITransaction } from '../transaction';
 import { IListener } from '../listener';
 import { ICell } from '../cell';
 import { ICellRange, ICellRegions, ICellRanges, ICellHeaderRange } from '../cellRange';
-import { IComment } from '../comment';
-import { IStyle } from '../style';
+import { IComment, ICommentCollection } from '../comment';
+import { ICellStyle } from '../style';
 import { ITable, ITableCollection } from '../table';
 import { IMovable, IMovableCollection } from '../movable';
 import { IHyperlink } from '../hyperlink';
 import { ICondition } from '../condition';
 import { ISort } from '../sort';
+import { IAutoFill } from '../autoFill';
 import { ICalculation } from '../calculation';
+import { FormulaHost } from '../calculation/grid';
 import { IDataValidation, IDataValidationCollection } from '../dataValidation';
 import { IConditionalFormat } from '../conditionalFormat/IConditionalFormat';
 import { IConditionalFormatCollection } from '../conditionalFormat/IConditionalFormatCollection';
+import { IProtectedRange, IProtectedRangeCollection } from '../protectedRange';
 import { ISheet } from './ISheet';
 import { ISheetInternal } from './Sheet';
-import { AutoFillProjection } from './_SheetMutations';
+import { Outline } from '../outline/Outline';
+import { AutoFillProjection } from './_SheetAutoFillUtils';
 /**
  * The empty feature selection — the raw-value fast path.
  * @internal
  */
 export declare const _NoFeatures: readonly ICellRange.Feature[];
+/**
+ * A watch listens for the VALUE landing, not for the transaction that caused it — a recalculation
+ * notifies its own ranges once the results are in (`trigger: 'calc'`), which is the moment a watch
+ * has something new to report.
+ */
 export interface SheetRangeOptions {
     readOnly?: string;
     getOptions: ICellRange.GetRangeOptions;
@@ -41,7 +51,16 @@ export declare class SheetRange implements ICellRange {
      * @internal
      */
     protected _getStickyOptions(): ICellRange.GetRangeOptions | undefined;
-    /** {@inheritDoc ICellRange.getCoords} */
+    /**
+     * {@inheritDoc ICellRange.getCoords}
+     *
+     * @remarks
+     * A `scope` is the sheet's display name, and a range that carries one is bound to the sheet
+     * INSTANCE it names, so the name is read from the sheet rather than from the address the range
+     * was parsed from. A rename leaves the cells where they are; only the qualifier changes, and it
+     * changes here, the same as a formula that references the sheet re-images with the new name. A
+     * bare range has no qualifier and nothing to re-read.
+     */
     getCoords(): Readonly<IRange.FixableCoords>;
     /** @internal */
     protected _createRange(coords: Readonly<IRange.FixableCoords>, getOptions?: ICellRange.GetRangeOptions): this;
@@ -69,6 +88,14 @@ export declare class SheetRange implements ICellRange {
     protected _deriveRange(address?: ICellRange.Address, options?: ICellRange.GetRangeOptions, callback?: (newCoords: IRange.Coords, origCoords: IRange.Coords) => IRange.Coords | null): this | null;
     /** @internal */
     protected _validateMaxSize(maxSize?: number): void;
+    /**
+     * The read of a one-cell range, answered from the cell the way `getValue()` / `getCell()` answer
+     * it: no used range and no iterator, so a read made while writes are held does not make them.
+     *
+     * @returns `undefined` if the range is more than one cell or an option can change the answer.
+     * @internal
+     */
+    protected _readSingleCell<T>(options: ICellRange.GetValuesOptions | undefined, read: (rowIndex: number, colIndex: number) => T): T[][] | undefined;
     /** {@inheritDoc ICellRange.entries} */
     entries(options?: ICellRange.IteratorOptions): IterableIterator<ICellRange.Entry>;
     /** {@inheritDoc ICellRange[Symbol.iterator]} */
@@ -109,10 +136,32 @@ export declare class SheetRange implements ICellRange {
     getCell(address?: ICell.Address): ICell;
     /** {@inheritDoc ICellRange.getFormula} */
     getFormula(address?: ICell.Address): ICalculation.IFormula;
+    /** {@inheritDoc ICellRange.getFormulas} */
+    getFormulas(): string[][];
+    /** {@inheritDoc ICellRange.setFormulas} */
+    setFormulas(formulas: readonly string[][], options?: ICellRange.SetValuesOptions): this;
+    /** {@inheritDoc ICellRange.getNumberFormat} */
+    getNumberFormat(): string;
+    /** {@inheritDoc ICellRange.getNumberFormats} */
+    getNumberFormats(): string[][];
+    /** {@inheritDoc ICellRange.setNumberFormat} */
+    setNumberFormat(numFmt: string | null, options?: ICellStyle.UpdateOptions): this;
+    /** {@inheritDoc ICellRange.setNumberFormats} */
+    setNumberFormats(formats: readonly string[][], options?: ICellRange.UpdateCellsOptions): this;
+    /**
+     * Throws if the whole range is larger than a dense read allows.
+     * @internal
+     */
+    protected _validateDenseSize(): void;
+    /**
+     * A row-major array in the shape of the range with every cell set to `fill`.
+     * @internal
+     */
+    protected _createDense<T>(fill: T): T[][];
     /** {@inheritDoc ICellRange.createFormula} */
-    createFormula(expression: string): ICalculation.IFormula;
+    createFormula(expression: string, options?: ICalculation.CreateFormulaOptions): ICalculation.IFormula;
     /** {@inheritDoc ICellRange.addWatch} */
-    addWatch(formula: ICalculation.IFormula | string, callback: ICellRange.WatchCallback): IListener.Remove;
+    addWatch(formula: ICalculation.IFormula | string, callback: ICellRange.WatchCallback, options?: ICellRange.WatchOptions): IListener.Remove;
     /**
      * {@link addWatch}, plus the origin an area of a multi-area watch shares with its siblings.
      *
@@ -120,6 +169,7 @@ export declare class SheetRange implements ICellRange {
      *               range's own top-left, and a formula anchored anywhere else is an error. Supplied
      *               by {@link ICellRanges.addWatch}, it is the shared origin, and the formula is
      *               FILLED from there to this range instead.
+     * @param options See {@link ICellRange.WatchOptions}.
      *
      * @remarks
      * The fill lives here rather than on the public method deliberately: silently re-siting whatever
@@ -130,7 +180,8 @@ export declare class SheetRange implements ICellRange {
     _addWatch(formula: ICalculation.IFormula | string, handlers: {
         onValues?: ICellRange.WatchCallback;
         onChange?: () => void;
-    }, origin?: IRange.CellCoords): IListener.Remove;
+        onRegistered?: (host: FormulaHost) => void;
+    }, origin?: IRange.CellCoords, options?: ICellRange.WatchOptions): IListener.Remove;
     /** {@inheritDoc ICellRange.select} */
     select(options?: ICellRange.SelectOptions): Promise<this>;
     /** {@inheritDoc ICellRange.find} */
@@ -221,17 +272,15 @@ export declare class SheetRange implements ICellRange {
     /** {@inheritDoc ICellRange.getCounts} */
     getCounts(features?: ICellRange.Feature | readonly ICellRange.Feature[]): ICellRange.Counts;
     /** {@inheritDoc ICellRange.getDirectPrecedents} */
-    getDirectPrecedents(): ICellRanges | null;
+    getDirectPrecedents(): Promise<ICellRanges | null>;
     /** {@inheritDoc ICellRange.getDirectDependents} */
-    getDirectDependents(): ICellRanges | null;
+    getDirectDependents(): Promise<ICellRanges | null>;
     /** {@inheritDoc ICellRange.getPrecedents} */
-    getPrecedents(): ICellRanges | null;
+    getPrecedents(): Promise<ICellRanges | null>;
     /** {@inheritDoc ICellRange.getDependents} */
-    getDependents(): ICellRanges | null;
+    getDependents(): Promise<ICellRanges | null>;
     /** {@inheritDoc ICellRange.getRegions} */
     getRegions(features?: ICellRange.Feature | readonly ICellRange.Feature[], options?: ICellRange.GetRegionsOptions): ICellRegions;
-    /** {@inheritDoc ICellRange.getCount} */
-    getCount(type?: ICell.Content): number;
     /** {@inheritDoc ICellRange.isEntireRows} */
     isEntireRows(): boolean;
     /** {@inheritDoc ICellRange.isEntireColumns} */
@@ -246,12 +295,16 @@ export declare class SheetRange implements ICellRange {
     get size(): number;
     /** {@inheritDoc ICellRange.getBounds} */
     getBounds(): import('@sheetxl/utils').Bounds;
+    /** {@inheritDoc ICellRange.getBestFit} */
+    getBestFit(options?: ICellRange.BestFitOptions): Size;
     /** {@inheritDoc ICellRange.isInvalid} */
     isInvalid(): boolean;
     /** {@inheritDoc ICellRange.getDefaultShiftAxis} */
     getDefaultShiftAxis(): IRange.Axis;
     /** {@inheritDoc ICellRange.getDefaultSortCriteria} */
     getDefaultSortCriteria(axis?: IRange.Axis, cell?: ICell.Address): ISort.DefaultSortCriteria | null;
+    /** {@inheritDoc ICellRange.getDefaultAutoFillCriteria} */
+    getDefaultAutoFillCriteria(direction?: IRange.Direction, destination?: ICellRange.Address): IAutoFill.DefaultCriteria | null;
     /** {@inheritDoc ICellRange.getMerges} */
     getMerges(): IRange.Coords[];
     /**
@@ -265,10 +318,14 @@ export declare class SheetRange implements ICellRange {
     protected _itemQuery<T extends {
         ignoreHidden?: boolean;
     }>(options?: T): T;
+    /** {@inheritDoc ICellRange.getUnlocked} */
+    getUnlocked(options?: ICellRange.GetItemsOptions<IProtectedRangeCollection.GetItemsOptions>): IProtectedRange[];
     /** {@inheritDoc ICellRange.getConditionalFormats} */
     getConditionalFormats(options?: ICellRange.GetItemsOptions<IConditionalFormatCollection.GetItemsOptions>): IConditionalFormat[];
     /** {@inheritDoc ICellRange.getDataValidations} */
     getDataValidations(options?: ICellRange.GetItemsOptions<IDataValidationCollection.GetItemsOptions>): IDataValidation[];
+    /** {@inheritDoc ICellRange.getComments} */
+    getComments(options?: ICellRange.GetItemsOptions<ICommentCollection.GetItemsOptions>): IComment[];
     /** {@inheritDoc ICellRange.getTables} */
     getTables(options?: ICellRange.GetItemsOptions<ITableCollection.GetItemsOptions>): ITable[];
     /** {@inheritDoc ICellRange.getMovables} */
@@ -278,8 +335,6 @@ export declare class SheetRange implements ICellRange {
     /** {@inheritDoc ICellRange.isReadOnly} */
     isReadOnly(): boolean;
     /** {@inheritDoc ICellRange.addListener} */
-    addListener2(listener: ICellRange.Listener, options?: ICellRange.ListenerOptions): IListener.Remove;
-    /** {@inheritDoc ICellRange.addListener} */
     addListener(listener: ICellRange.Listener, options?: ICellRange.ListenerOptions): IListener.Remove;
     /** {@inheritDoc ICellRange.getSheet} */
     getSheet(): ISheet;
@@ -287,14 +342,28 @@ export declare class SheetRange implements ICellRange {
     autoFill(destination: ICellRange.Address, options?: ICellRange.AutoFillOptions): this;
     /** {@inheritDoc ICellRange.autoFit} */
     autoFit(options?: ICellRange.AutoFitOptions): this;
+    /** {@inheritDoc ICellRange.group} */
+    group(axis?: IRange.Axis, options?: ITransaction.OperationOptions): this;
+    /** {@inheritDoc ICellRange.ungroup} */
+    ungroup(axis?: IRange.Axis, options?: ITransaction.OperationOptions): this;
+    protected _changeOutlineLevels(axis: IRange.Axis | undefined, delta: 1 | -1, options?: ITransaction.OperationOptions): void;
+    /** {@inheritDoc ICellRange.showGroupDetails} */
+    showGroupDetails(axis?: IRange.Axis, options?: ITransaction.OperationOptions): this;
+    /** {@inheritDoc ICellRange.hideGroupDetails} */
+    hideGroupDetails(axis?: IRange.Axis, options?: ITransaction.OperationOptions): this;
+    /** {@inheritDoc ICellRange.clearGroups} */
+    clearGroups(axes?: IRange.AxisSelection, options?: ITransaction.OperationOptions): this;
+    protected _getOutline(): Outline;
+    protected _getRun(axis: IRange.Axis): RunCoords;
+    protected _resolveOutlineAxis(axis: IRange.Axis | undefined): IRange.Axis;
     /** {@inheritDoc ICellRange.clear} */
     clear(applyTo?: ICell.Content, options?: ITransaction.OperationOptions): this;
     /** {@inheritDoc ICellRange.setHyperlink} */
     setHyperlink(hyperlink: IHyperlink.Update, options?: ITransaction.OperationOptions): this;
     /** {@inheritDoc ICellRange.setComments} */
-    setComments(comments: IComment.Properties, options?: ITransaction.OperationOptions): this;
+    setComments(comments: IComment.Update, options?: ITransaction.OperationOptions): this;
     /** {@inheritDoc ICellRange.getStyle} */
-    getStyle(): IStyle;
+    getStyle(): ICellStyle;
     /** {@inheritDoc ICellRange.merge} */
     merge(options?: IRange.AxisSelection | ICellRange.MergeOptions): this;
     /** {@inheritDoc ICellRange.unmerge} */
@@ -318,6 +387,8 @@ export declare class SheetRange implements ICellRange {
     addTable(options?: ITableCollection.AddOptions | boolean): ITable;
     /** {@inheritDoc ICellRange.insertFrom} */
     insertFrom(source: ICellRange.Address | ICellRange.ISnapshot, options?: ICellRange.InsertFromOptions): Promise<this | null>;
+    /** {@inheritDoc ICellRange.canInsertFrom} */
+    canInsertFrom(source: ICellRange.Address | ICellRange.ISnapshot, options?: ICellRange.InsertFromOptions): boolean;
     /** {@inheritDoc ICellRange.copyFrom} */
     copyFrom(source: ICellRange.Address | ICellRange.ISnapshot, options?: ICellRange.CopyOptions): Promise<this | null>;
     /** {@inheritDoc ICellRange.delete} */
@@ -361,6 +432,10 @@ export declare class PreviewSheetRange extends SheetRange {
     getValues(options?: ICellRange.GetValuesOptions): Scalar[][];
     /** {@inheritDoc ICellRange.getInteropValues} */
     getInteropValues(options?: ICellRange.GetValuesOptions): InteropScalar[][];
+    /** {@inheritDoc ICellRange.getFormulas} */
+    getFormulas(): string[][];
+    /** {@inheritDoc ICellRange.getNumberFormats} */
+    getNumberFormats(): string[][];
     /**
      * A `getValuesRange` on a projection would have to materialize every cell, defeating the point of
      * computing on demand — and it vends a live grid view, which a hypothetical has none of.

package/types/src/sheet/SheetRanges.d.ts

@@ -4,7 +4,7 @@ import { IListener } from '../listener';
 import { ICell } from '../cell';
 import { ICellRanges, ICellRange, ICellHeaderRange, ICellHeaderRanges } from '../cellRange';
 import { ICalculation } from '../calculation';
-import { IStyle } from '../style';
+import { ICellStyle } from '../style';
 import { ISheet } from '../sheet';
 import { ISheetInternal } from './Sheet';
 import { SheetRange } from './SheetRange';
@@ -27,6 +27,12 @@ export declare class SheetRanges implements ICellRanges {
     protected _options: SheetRangesOptions | undefined;
     protected _internal: ISheetInternal;
     protected _cacheRanges: ICellRange[];
+    /**
+     * The sheet each scoped coord named when this set was built, by member index; `null` when no
+     * member is scoped. A string member or a range instance answers live on its own, and a bare
+     * coord is the anchor's.
+     */
+    protected _memberSheets: readonly (ISheet | null)[] | null;
     constructor(coords: readonly (IRange.FixableCoords | string | ICellRange)[], internal: ISheetInternal, options?: SheetRangesOptions);
     /**
      * The read options these ranges carry — set at creation and merged through every derivation.
@@ -71,8 +77,17 @@ export declare class SheetRanges implements ICellRanges {
      * @internal
      */
     protected _readCoordsByScope(op: (internal: ISheetInternal, coords: IRange.FixableCoords[]) => readonly IRange.Coords[]): readonly IRange.Coords[];
-    /** {@inheritDoc ICellRanges.getCoords} */
+    /**
+     * {@inheritDoc ICellRanges.getCoords}
+     *
+     * @remarks
+     * A member's `scope` is its sheet's display name, read from the sheet the member was bound to
+     * when the set was built, so a renamed sheet is spelled by its current name — see
+     * {@link SheetRange.getCoords}.
+     */
     getCoords(): readonly IRange.FixableCoords[];
+    /** Re-stamps every bound member whose sheet no longer goes by the name the coord carries. */
+    private _refreshScopes;
     private _resolveCoords;
     /** {@inheritDoc ICellRange[Symbol.iterator]} */
     [Symbol.iterator](): IterableIterator<Scalar>;
@@ -82,12 +97,10 @@ export declare class SheetRanges implements ICellRanges {
     select(options?: ICellRange.SelectOptions): Promise<this>;
     /** {@inheritDoc ICellRange.calculate} */
     calculate(): this;
-    /** {@inheritDoc ICellRange.addListener} */
-    addListener2(listener: ICellRange.Listener, options?: ICellRange.ListenerOptions): IListener.Remove;
     /** {@inheritDoc ICellRanges.addListener} */
     addListener(listener: ICellRange.Listener, options?: ICellRange.ListenerOptions): IListener.Remove;
     /** {@inheritDoc ICellRanges.addWatch} */
-    addWatch(formula: ICalculation.IFormula | string, callback: ICellRanges.WatchCallback): IListener.Remove;
+    addWatch(formula: ICalculation.IFormula | string, callback: ICellRanges.WatchCallback, options?: ICellRange.WatchOptions): IListener.Remove;
     /**
      * Registers one per-area watch of some kind, all sharing this set's origin.
      * @internal
@@ -107,9 +120,9 @@ export declare class SheetRanges implements ICellRanges {
     /** {@inheritDoc ICellRanges.getFlattened} */
     getFlattened(options?: ICellRange.GetFlattenOptions): this;
     /** {@inheritDoc ICellRanges.getPrecedents} */
-    getPrecedents(entireSet?: boolean): ICellRanges | null;
+    getPrecedents(entireSet?: boolean): Promise<ICellRanges | null>;
     /** {@inheritDoc ICellRanges.getDependents} */
-    getDependents(entireSet?: boolean): ICellRanges | null;
+    getDependents(entireSet?: boolean): Promise<ICellRanges | null>;
     /**
      * Shared walk for {@link getPrecedents} / {@link getDependents}: ask each contiguous range for
      * its own neighbors and flatten the union (the grid dedupes within a single query; across
@@ -122,7 +135,7 @@ export declare class SheetRanges implements ICellRanges {
      * currency, which a direct `calcGrid` call does not do (a stableId reaching the address layer
      * prints as `#REF!`).
      */
-    protected _trace(dependents: boolean, entireSet: boolean): ICellRanges | null;
+    protected _trace(dependents: boolean, entireSet: boolean): Promise<ICellRanges | null>;
     /**
      * Re-expresses another collection's coords against THIS anchor.
      *
@@ -144,7 +157,7 @@ export declare class SheetRanges implements ICellRanges {
     /** {@inheritDoc ICellRanges.setValue} */
     setValue(value: ICellRange.ScalarUpdate, options?: ICellRange.SetValuesOptions): this;
     /** {@inheritDoc ICellRanges.getStyle} */
-    getStyle(): IStyle;
+    getStyle(): ICellStyle;
     /** {@inheritDoc ICellRanges.merge} */
     merge(options?: IRange.AxisSelection | ICellRange.MergeOptions): this;
     /** {@inheritDoc ICellRanges.unmerge} */