@sheetxl/sdk 0.7.27 → 0.7.28-beta.1

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

@@ -0,0 +1,362 @@
+import { IRange, Scalar, IRangeStats, InteropScalar } from '@sheetxl/primitives';
+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 { ITable, ITableCollection } from '../table';
+import { IMovable, IMovableCollection } from '../movable';
+import { IHyperlink } from '../hyperlink';
+import { ICondition } from '../condition';
+import { ISort } from '../sort';
+import { ICalculation } from '../calculation';
+import { IDataValidation, IDataValidationCollection } from '../dataValidation';
+import { IConditionalFormat } from '../conditionalFormat/IConditionalFormat';
+import { IConditionalFormatCollection } from '../conditionalFormat/IConditionalFormatCollection';
+import { ISheet } from './ISheet';
+import { ISheetInternal } from './Sheet';
+import { AutoFillProjection } from './_SheetMutations';
+/**
+ * The empty feature selection — the raw-value fast path.
+ * @internal
+ */
+export declare const _NoFeatures: readonly ICellRange.Feature[];
+export interface SheetRangeOptions {
+    readOnly?: string;
+    getOptions: ICellRange.GetRangeOptions;
+}
+export declare class SheetRange implements ICellRange {
+    protected _coords: Readonly<IRange.FixableCoords>;
+    protected _readOnly: string | null;
+    protected _options: SheetRangeOptions | undefined;
+    protected _internal: ISheetInternal;
+    constructor(coords: IRange.FixableCoords, internal: ISheetInternal, options?: SheetRangeOptions);
+    /**
+     * The read options this range carries — set at creation and merged through every derivation.
+     *
+     * @remarks
+     * Defaults, not locks: an option passed to an individual read wins for that call. See
+     * {@link ICellRange.GetRangeOptions}.
+     * @internal
+     */
+    protected _getStickyOptions(): ICellRange.GetRangeOptions | undefined;
+    /** {@inheritDoc ICellRange.getCoords} */
+    getCoords(): Readonly<IRange.FixableCoords>;
+    /** @internal */
+    protected _createRange(coords: Readonly<IRange.FixableCoords>, getOptions?: ICellRange.GetRangeOptions): this;
+    /**
+     * Carries this range's scope onto a coord derived from it.
+     *
+     * @remarks
+     * Absent scope means "the anchor", and for a derivation the anchor is whatever sheet this range
+     * is already on — so the qualifier has to be restated to survive `getAddress()`. A coord that
+     * names its own scope keeps it: an explicit qualifier is never overwritten.
+     * @internal
+     */
+    protected _scopeDerived<T extends IRange.Coords>(coords: T): T;
+    /** @internal */
+    protected _createRanges(coords: readonly IRange.FixableCoords[], getOptions?: ICellRange.GetRangeOptions): ICellRanges;
+    /**
+     * `createRanges` but with additional checks.
+     * @internal
+     */
+    protected _deriveRanges(getOptions?: ICellRange.GetRangeOptions, callback?: (origCoords: IRange.Coords) => readonly IRange.Coords[] | null): ICellRanges | null;
+    /**
+     * `createRange` but with additional checks.
+     * @internal
+     */
+    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;
+    /** {@inheritDoc ICellRange.entries} */
+    entries(options?: ICellRange.IteratorOptions): IterableIterator<ICellRange.Entry>;
+    /** {@inheritDoc ICellRange[Symbol.iterator]} */
+    [Symbol.iterator](): IterableIterator<Scalar>;
+    /** {@inheritDoc ICellRange.values} */
+    values(options?: ICellRange.IteratorOptions): IterableIterator<Scalar>;
+    /** {@inheritDoc ICellRange.forEach} */
+    forEach<T>(callback: ICellRange.ForEachCallback, optionsIterator?: ICellRange.IteratorOptions): T | void;
+    /** @internal */
+    protected _validateWrite(): void;
+    /** {@inheritDoc ICellRange.updateCells} */
+    updateCells(value: ICellRange.Update, options?: ICellRange.UpdateCellsOptions, updateCoords?: IRange.Coords): this;
+    /** {@inheritDoc ICellRange.setValues} */
+    setValues(value: ICellRange.ValuesUpdate, options?: ICellRange.SetValuesOptions): this;
+    /** {@inheritDoc ICellRange.setValue} */
+    setValue(value: ICellRange.ScalarUpdate, options?: ICellRange.SetValuesOptions): this;
+    /** {@inheritDoc ICellRange.setFormula} */
+    setFormula(value: ICellRange.ScalarUpdate, options?: ICellRange.SetValuesOptions): this;
+    /** @internal */
+    protected _setValueOrValues(value: ICellRange.ValuesUpdate, options?: ICellRange.SetValuesOptions): this;
+    /** {@inheritDoc ICellRange.getValues} */
+    getValues(options?: ICellRange.GetValuesOptions): Scalar[][];
+    /** {@inheritDoc ICellRange.getValuesRange} */
+    getValuesRange(): IRange;
+    /** @inheritdoc ICellRange.setComputedValues */
+    setComputedValues(callback: (range: IRange) => IRange, options?: ITransaction.OperationOptions): this;
+    /** {@inheritDoc ICellRange.getInteropValues} */
+    getInteropValues(options?: ICellRange.GetValuesOptions): InteropScalar[][];
+    /** {@inheritDoc ICellRange.getValue} */
+    getValue(): Scalar;
+    /** {@inheritDoc ICellRange.getInteropValue} */
+    getInteropValue(): InteropScalar;
+    /** {@inheritDoc ICellRange.calculate} */
+    calculate(full: boolean): this;
+    /** {@inheritDoc ICellRange.getCells} */
+    getCells(options?: ICellRange.GetValuesOptions): ICell[][];
+    /** {@inheritDoc ICellRange.getCell} */
+    getCell(address?: ICell.Address): ICell;
+    /** {@inheritDoc ICellRange.getFormula} */
+    getFormula(address?: ICell.Address): ICalculation.IFormula;
+    /** {@inheritDoc ICellRange.createFormula} */
+    createFormula(expression: string): ICalculation.IFormula;
+    /** {@inheritDoc ICellRange.addWatch} */
+    addWatch(formula: ICalculation.IFormula | string, callback: ICellRange.WatchCallback): IListener.Remove;
+    /**
+     * {@link addWatch}, plus the origin an area of a multi-area watch shares with its siblings.
+     *
+     * @param origin The cell the expression is authored at. Omitted — the public form — it is this
+     *               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.
+     *
+     * @remarks
+     * The fill lives here rather than on the public method deliberately: silently re-siting whatever
+     * it is handed is exactly how an area-two anchor bug stays invisible, and the only caller that
+     * legitimately wants it is the one that knows the areas belong to one rule.
+     * @internal
+     */
+    _addWatch(formula: ICalculation.IFormula | string, handlers: {
+        onValues?: ICellRange.WatchCallback;
+        onChange?: () => void;
+    }, origin?: IRange.CellCoords): IListener.Remove;
+    /** {@inheritDoc ICellRange.select} */
+    select(options?: ICellRange.SelectOptions): Promise<this>;
+    /** {@inheritDoc ICellRange.find} */
+    find(options: string | ICellRange.FindOptions): Iterator<ICell>;
+    /** {@inheritDoc ICellRange.getFixed} */
+    getFixed(options: ICellRange.GetFixedOptions): this;
+    /** {@inheritDoc ICellRange.getRangeAt} */
+    getRangeAt(rowStart: number, colStart: number, rowEnd?: number, colEnd?: number, options?: ICellRange.GetRangeOptions): this;
+    /** {@inheritDoc ICellRange.getRowAt} */
+    getRowAt(rowIndex: number, options?: ICellRange.GetRangeOptions): this;
+    /** {@inheritDoc ICellRange.getRowAfter} */
+    getRowAfter(options?: ICellRange.GetRangeOptions): this;
+    /** {@inheritDoc ICellRange.getRowBefore} */
+    getRowBefore(options?: ICellRange.GetRangeOptions): this;
+    /** {@inheritDoc ICellRange.getRowBy} */
+    getRowBy(rowDelta: number, options?: ICellRange.GetRangeOptions): this;
+    /** {@inheritDoc ICellRange.getColumnAt} */
+    getColumnAt(colIndex: number, options?: ICellRange.GetRangeOptions): this;
+    /** {@inheritDoc ICellRange.getColumnAfter} */
+    getColumnAfter(options?: ICellRange.GetRangeOptions): this;
+    /** {@inheritDoc ICellRange.getColumnBefore} */
+    getColumnBefore(options?: ICellRange.GetRangeOptions): this;
+    /** {@inheritDoc ICellRange.getColumnBy} */
+    getColumnBy(columnDelta: number, options?: ICellRange.GetRangeOptions): this;
+    /** {@inheritDoc ICellRange.getTopLeft} */
+    getTopLeft(options?: ICellRange.GetRangeOptions): this;
+    /** {@inheritDoc ICellRange.getBottomRight} */
+    getBottomRight(options?: ICellRange.GetRangeOptions): this;
+    /** {@inheritDoc ICellRange.getSurrounding} */
+    getSurrounding(options?: ICellRange.GetSurroundingOptions): this;
+    /** {@inheritDoc ICellRange.getExtended} */
+    getExtended(direction: IRange.Direction, cell?: ICell.Address): this;
+    /** {@inheritDoc ICellRange.getEntireRows} */
+    getEntireRows(shift?: boolean, options?: ICellRange.GetRangeOptions): this;
+    /** {@inheritDoc ICellRange.getEntireColumns} */
+    getEntireColumns(shift?: boolean, options?: ICellRange.GetRangeOptions): this;
+    /** {@inheritDoc ICellRange.getRowHeaders} */
+    getRowHeaders(options?: ICellHeaderRange.GetRangeOptions): ICellHeaderRange;
+    /** {@inheritDoc ICellRange.getColumnHeaders} */
+    getColumnHeaders(options?: ICellHeaderRange.GetRangeOptions): ICellHeaderRange;
+    /** {@inheritDoc ICellRange.getDifferences} */
+    getDifferences(address: ICellRange.Address, options?: ICellRange.GetRangeOptions): ICellRanges | null;
+    /** {@inheritDoc ICellRange.getIntersect} */
+    getIntersect(address?: ICellRange.Address, options?: ICellRange.GetRangeOptions): this | null;
+    /** {@inheritDoc ICellRange.getUnion} */
+    getUnion(address?: ICellRange.Address, options?: ICellRange.GetRangeOptions): this;
+    /** {@inheritDoc ICellRange.getResizeTo} */
+    getResizeTo(rowCount: number, colCount: number, options?: ICellRange.GetRangeOptions): this;
+    /** {@inheritDoc ICellRange.getResizeBy} */
+    getResizeBy(rowDelta: number, colDelta: number, options?: ICellRange.GetRangeOptions): this;
+    /** {@inheritDoc ICellRange.getOffsetTo} */
+    getOffsetTo(rowIndex: number, colIndex: number, options?: ICellRange.GetRangeOptions): this;
+    /** {@inheritDoc ICellRange.getOffsetBy} */
+    getOffsetBy(rowDelta: number, colDelta: number, options?: ICellRange.GetRangeOptions): this;
+    /** {@inheritDoc ICellRange.getUsedRange} */
+    getUsedRange(options?: ICellRange.GetRangeOptions): this | null;
+    /** {@inheritDoc ICellRange.isEmpty} */
+    isEmpty(): boolean;
+    /** {@inheritDoc ICellRange.getColumnStart} */
+    getColumnStart(): number;
+    /** {@inheritDoc ICellRange.getRowStart} */
+    getRowStart(): number;
+    /** {@inheritDoc ICellRange.getColumnEnd} */
+    getColumnEnd(): number;
+    /** {@inheritDoc ICellRange.getRowEnd} */
+    getRowEnd(): number;
+    /** {@inheritDoc ICellRange.getColumnCount} */
+    getColumnCount(): number;
+    /** {@inheritDoc ICellRange.getRowCount} */
+    getRowCount(): number;
+    /** {@inheritDoc ICellRange.getVisible} */
+    getVisible(options?: ICellRange.GetVisibleOptions): ICellRanges | null;
+    /** {@inheritDoc ICellRange.isContentful} */
+    isContentful(features?: ICellRange.Feature | readonly ICellRange.Feature[]): boolean;
+    /** {@inheritDoc ICellRange.getStats} */
+    getStats(options?: ICellRange.GetStatsOptions): IRangeStats;
+    /** {@inheritDoc ICellRange.getCounts} */
+    getCounts(features?: ICellRange.Feature | readonly ICellRange.Feature[]): ICellRange.Counts;
+    /** {@inheritDoc ICellRange.getDirectPrecedents} */
+    getDirectPrecedents(): ICellRanges | null;
+    /** {@inheritDoc ICellRange.getDirectDependents} */
+    getDirectDependents(): ICellRanges | null;
+    /** {@inheritDoc ICellRange.getPrecedents} */
+    getPrecedents(): ICellRanges | null;
+    /** {@inheritDoc ICellRange.getDependents} */
+    getDependents(): 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} */
+    isEntireColumns(): boolean;
+    /** {@inheritDoc ICellRange.isEntireRange} */
+    isEntireRange(): boolean;
+    /** {@inheritDoc ICellRange.isEntireRange} */
+    isSingleCell(): boolean;
+    /** {@inheritDoc ICellRange.isEqual} */
+    isEqual(address: ICellRange.Address, options?: ICellRange.GetRangeOptions): boolean;
+    /** {@inheritDoc ICellRange.size} */
+    get size(): number;
+    /** {@inheritDoc ICellRange.getBounds} */
+    getBounds(): import('@sheetxl/utils').Bounds;
+    /** {@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.getMerges} */
+    getMerges(): IRange.Coords[];
+    /**
+     * Scopes a collection `getItems` query to this range.
+     *
+     * @remarks
+     * The carried `ignoreHidden` is a default the caller's own options overwrite; `address` is
+     * always this range. See {@link ICellRange.GetItemsOptions}.
+     * @internal
+     */
+    protected _itemQuery<T extends {
+        ignoreHidden?: boolean;
+    }>(options?: T): T;
+    /** {@inheritDoc ICellRange.getConditionalFormats} */
+    getConditionalFormats(options?: ICellRange.GetItemsOptions<IConditionalFormatCollection.GetItemsOptions>): IConditionalFormat[];
+    /** {@inheritDoc ICellRange.getDataValidations} */
+    getDataValidations(options?: ICellRange.GetItemsOptions<IDataValidationCollection.GetItemsOptions>): IDataValidation[];
+    /** {@inheritDoc ICellRange.getTables} */
+    getTables(options?: ICellRange.GetItemsOptions<ITableCollection.GetItemsOptions>): ITable[];
+    /** {@inheritDoc ICellRange.getMovables} */
+    getMovables(options?: ICellRange.GetItemsOptions<IMovableCollection.GetItemsOptions>): IMovable[];
+    /** {@inheritDoc ICellRange.getSnapshot} */
+    getSnapshot(options?: ICellRange.CopyOptions): ICellRange.ISnapshot;
+    /** {@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;
+    /** {@inheritDoc ICellRange.autoFill} */
+    autoFill(destination: ICellRange.Address, options?: ICellRange.AutoFillOptions): this;
+    /** {@inheritDoc ICellRange.autoFit} */
+    autoFit(options?: ICellRange.AutoFitOptions): this;
+    /** {@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;
+    /** {@inheritDoc ICellRange.getStyle} */
+    getStyle(): IStyle;
+    /** {@inheritDoc ICellRange.merge} */
+    merge(options?: IRange.AxisSelection | ICellRange.MergeOptions): this;
+    /** {@inheritDoc ICellRange.unmerge} */
+    unmerge(options?: ITransaction.OperationOptions): this;
+    /** {@inheritDoc ICellRange.textToColumns} */
+    textToColumns(options?: ICellRange.TextToColumnsOptions | string): this;
+    /** {@inheritDoc ICellRange.removeDuplicates} */
+    removeDuplicates(options?: ICellRange.RemoveDuplicatesOptions): this;
+    /** {@inheritDoc ICellRange.insert} */
+    insert(options?: IRange.Axis | ICellRange.InsertOptions): this;
+    /**
+     * The `span` route of {@link insert}/{@link delete}: expand the shifted range to the enclosing
+     * region's extent across the shift axis — the enclosing table (routing to the TABLE ops, which own
+     * column state, undo labels and the no-body rule), else the entire sheet (a whole row/column
+     * shift). See {@link ICellRange.InsertOptions.span} for the boundary/validity contract.
+     */
+    protected _spanShift(options: ICellRange.InsertOptions | ICellRange.DeleteOptions, isInsert: boolean): void;
+    /** {@inheritDoc ICellRange.addAutoTable} */
+    addAutoTable(options?: ICellRange.AddAutoTableOptions): ITable;
+    /** {@inheritDoc ICellRange.addTable} */
+    addTable(options?: ITableCollection.AddOptions | boolean): ITable;
+    /** {@inheritDoc ICellRange.insertFrom} */
+    insertFrom(source: ICellRange.Address | ICellRange.ISnapshot, options?: ICellRange.InsertFromOptions): Promise<this | null>;
+    /** {@inheritDoc ICellRange.copyFrom} */
+    copyFrom(source: ICellRange.Address | ICellRange.ISnapshot, options?: ICellRange.CopyOptions): Promise<this | null>;
+    /** {@inheritDoc ICellRange.delete} */
+    delete(options?: IRange.Axis | ICellRange.DeleteOptions): this;
+    /** {@inheritDoc ICellRange.sort} */
+    sort(options?: boolean | ISort.Options[] | ISort.RangeOptions & ITransaction.OperationOptions): this;
+    /** {@inheritDoc ICellRange.sortAt} */
+    sortAt(index: number, reverse?: boolean, sortOn?: ISort.SortOn, options?: ITransaction.OperationOptions): this;
+    /** {@inheritDoc ICellRange.filter} */
+    filter(condition: ICondition.Input | ICondition.RangeOptions, options?: ITransaction.OperationOptions): Promise<this>;
+    /** {@inheritDoc ICellRange.doBatch} */
+    doBatch<R>(callback: (commit: ITransaction.ICommit) => R | Promise<R>, options?: string | ITransaction.OperationOptions): Promise<R> | R;
+    /** {@inheritDoc ICellRange.createSparseBuilder} */
+    createSparseBuilder(options?: ICellRange.SparseBuilderOptions): ICellRange.SparseBuilder;
+    /** {@inheritDoc ICellRange.getAddress} */
+    getAddress(r1c1?: boolean): string;
+    /** {@inheritDoc ICellRange.toString} */
+    toString(): string;
+    get [Symbol.toStringTag](): string;
+    /** {@inheritDoc ICellRange.isICellRange} */
+    get isICellRange(): true;
+}
+/**
+ * The range handed back by `autoFill` with {@link ICellRange.AutoFillOptions.preview}: the destination,
+ * with its cells projected from the fill that *would* run rather than read from the sheet.
+ *
+ * @remarks
+ * Read-only — the projection describes a hypothetical, so writing through it would be a lie about what
+ * the caller asked for. Every read that resolves cells is overridden; everything else (coords, address,
+ * derivation) is ordinary range behavior.
+ * @internal
+ */
+export declare class PreviewSheetRange extends SheetRange {
+    private readonly _projection;
+    constructor(coords: IRange.FixableCoords, internal: ISheetInternal, projection: AutoFillProjection, getOptions?: ICellRange.GetRangeOptions);
+    /** {@inheritDoc ICellRange.getCell} */
+    getCell(address?: ICell.Address): ICell;
+    /** {@inheritDoc ICellRange.getCells} */
+    getCells(options?: ICellRange.GetValuesOptions): ICell[][];
+    /** {@inheritDoc ICellRange.getValues} */
+    getValues(options?: ICellRange.GetValuesOptions): Scalar[][];
+    /** {@inheritDoc ICellRange.getInteropValues} */
+    getInteropValues(options?: ICellRange.GetValuesOptions): InteropScalar[][];
+    /**
+     * 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.
+     */
+    getValuesRange(): IRange;
+    /** Walk the destination row-major, projecting each cell. */
+    private _projectRows;
+    get [Symbol.toStringTag](): string;
+}
+//# sourceMappingURL=SheetRange.d.ts.map

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

@@ -0,0 +1,225 @@
+import { IRange, IRangeStats, Scalar } from '@sheetxl/primitives';
+import { ITransaction } from '../transaction';
+import { IListener } from '../listener';
+import { ICell } from '../cell';
+import { ICellRanges, ICellRange, ICellHeaderRange, ICellHeaderRanges } from '../cellRange';
+import { ICalculation } from '../calculation';
+import { IStyle } from '../style';
+import { ISheet } from '../sheet';
+import { ISheetInternal } from './Sheet';
+import { SheetRange } from './SheetRange';
+export interface SheetRangesOptions {
+    readOnly?: string;
+    getOptions: ICellRange.GetRangeOptions;
+}
+/**
+ * A run of coords and the sheet that owns them. See {@link SheetRanges._byScope}.
+ * @internal
+ */
+interface ScopeGroup {
+    internal: ISheetInternal;
+    /** The group's coords, scope STRIPPED — bare is the group's own sheet, as everywhere else. */
+    coords: IRange.FixableCoords[];
+}
+export declare class SheetRanges implements ICellRanges {
+    protected _coords: readonly (IRange.FixableCoords | string | ICellRange)[];
+    protected _readOnly: string | null;
+    protected _options: SheetRangesOptions | undefined;
+    protected _internal: ISheetInternal;
+    protected _cacheRanges: ICellRange[];
+    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.
+     * @internal
+     */
+    protected _getStickyOptions(): ICellRange.GetRangeOptions | undefined;
+    protected _createRanges(coords: readonly (IRange.FixableCoords | string | ICellRange)[], getOptions?: ICellRange.GetRangeOptions): this;
+    protected _createRange(coords: Readonly<IRange.FixableCoords> | string, getOptions?: ICellRange.GetRangeOptions): ICellRange;
+    protected _validateWrite(): void;
+    /**
+     * The coords grouped by the sheet each one names, or `null` when they all belong to the anchor.
+     *
+     * @remarks
+     * A discontiguous set is allowed to span sheets (`sheet1.getRanges('B2,Sheet2!D5')`), so a bulk
+     * call cannot hand the whole array to the anchor's internal: that performs the operation on the
+     * ANCHOR at the foreign coordinates — the wrong cells, silently, and destructively for a write.
+     * The per-range path (`_createRange`) has resolved the owning sheet since the scope model
+     * landed; this is the same resolution for the array-shaped calls, once per sheet rather than
+     * once per range so a same-sheet set stays a single call.
+     *
+     * `null` for the all-anchor case (very nearly all of them) keeps that path running exactly the
+     * code it always ran, allocation-free. Coords whose scope names no sheet are DROPPED: an
+     * unresolvable scope is a `#REF!`, which has nothing to operate on — matching `_createRange`.
+     * @internal
+     */
+    protected _byScope(): ScopeGroup[] | null;
+    /**
+     * Runs a bulk write once per sheet the set names, as ONE undo step.
+     *
+     * @remarks
+     * Cross-sheet work inside a sheet's batch is a single commit (the transaction is the workbook's,
+     * not the sheet's), which is what lets the fan-out stay one operation from the user's side.
+     * @internal
+     */
+    protected _writeByScope(op: (internal: ISheetInternal, coords: IRange.FixableCoords[]) => void, options?: ITransaction.OperationOptions): void;
+    /**
+     * Runs a bulk read once per sheet and concatenates the coords, re-qualified against the anchor.
+     *
+     * @remarks
+     * Results come back bare-relative to the sheet that produced them; a coord leaving here has to
+     * say which sheet it is on, by the same rule the inputs follow.
+     * @internal
+     */
+    protected _readCoordsByScope(op: (internal: ISheetInternal, coords: IRange.FixableCoords[]) => readonly IRange.Coords[]): readonly IRange.Coords[];
+    /** {@inheritDoc ICellRanges.getCoords} */
+    getCoords(): readonly IRange.FixableCoords[];
+    private _resolveCoords;
+    /** {@inheritDoc ICellRange[Symbol.iterator]} */
+    [Symbol.iterator](): IterableIterator<Scalar>;
+    /** {@inheritDoc ICellRange.entries} */
+    entries(options?: ICellRange.IteratorOptions): IterableIterator<ICellRange.Entry>;
+    /** {@inheritDoc ICellRanges.select} */
+    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;
+    /**
+     * Registers one per-area watch of some kind, all sharing this set's origin.
+     * @internal
+     */
+    protected _addWatch(formula: ICalculation.IFormula | string, register: (area: SheetRange, index: number, origin: IRange.CellCoords) => IListener.Remove): IListener.Remove;
+    /**
+     * Registers with every sheet the set names and hands back one remove for all of them.
+     *
+     * @remarks
+     * A listener registered on the anchor for a coord on another sheet watches the wrong cells: it
+     * never fires for the edit the caller asked about, and does fire for one they did not.
+     * @internal
+     */
+    private _listenByScope;
+    /** {@inheritDoc ICellRanges.find} */
+    find(options: string | ICellRange.FindOptions): Iterator<ICell>;
+    /** {@inheritDoc ICellRanges.getFlattened} */
+    getFlattened(options?: ICellRange.GetFlattenOptions): this;
+    /** {@inheritDoc ICellRanges.getPrecedents} */
+    getPrecedents(entireSet?: boolean): ICellRanges | null;
+    /** {@inheritDoc ICellRanges.getDependents} */
+    getDependents(entireSet?: boolean): 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
+     * discontiguous ranges the results can still overlap).
+     *
+     * @remarks
+     * Deliberately routed through the per-range API rather than straight at the calc grid. Each
+     * range resolves its OWN sheet's grid — asking the anchor's for a coord on another sheet reads
+     * a different cell's graph entirely — and the answers come back already translated out of calc
+     * 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;
+    /**
+     * Re-expresses another collection's coords against THIS anchor.
+     *
+     * @remarks
+     * Scope is relative: a bare coord in a collection anchored to Sheet2 means Sheet2, and pasting
+     * it into a Sheet1-anchored collection unchanged silently re-homes it. So the source anchor is
+     * made explicit, then dropped again where it restates this one.
+     * @internal
+     */
+    private _rehome;
+    /** {@inheritDoc ICellRanges.getVisible} */
+    getVisible(options?: ICellRange.GetVisibleOptions): this | null;
+    /** {@inheritDoc ICellRanges.getFixed} */
+    getFixed(options: ICellRange.GetFixedOptions): this;
+    /** {@inheritDoc ICellRanges.autoFit} */
+    autoFit(options?: ICellRange.AutoFitOptions): this;
+    /** {@inheritDoc ICellRanges.clear} */
+    clear(applyTo?: ICell.Content, options?: ITransaction.OperationOptions): this;
+    /** {@inheritDoc ICellRanges.setValue} */
+    setValue(value: ICellRange.ScalarUpdate, options?: ICellRange.SetValuesOptions): this;
+    /** {@inheritDoc ICellRanges.getStyle} */
+    getStyle(): IStyle;
+    /** {@inheritDoc ICellRanges.merge} */
+    merge(options?: IRange.AxisSelection | ICellRange.MergeOptions): this;
+    /** {@inheritDoc ICellRanges.unmerge} */
+    unmerge(options?: ITransaction.OperationOptions): this;
+    /** {@inheritDoc ICellRanges.getMerges} */
+    getMerges(): IRange.Coords[];
+    /** {@inheritDoc ICellRanges.insert} */
+    insert(options?: IRange.Axis | ICellRange.InsertOptions): this;
+    /** {@inheritDoc ICellRanges.delete} */
+    delete(options?: IRange.Axis | ICellRange.DeleteOptions): this;
+    /** {@inheritDoc ICellRanges.insertFrom} */
+    insertFrom(source: ICellRange.Address | ICellRange.ISnapshot, options?: ICellRange.InsertFromOptions): Promise<this | null>;
+    /** {@inheritDoc ICellRanges.copyFrom} */
+    copyFrom(source: ICellRange.Address | ICellRange.ISnapshot, options?: ICellRange.CopyOptions): Promise<this | null>;
+    /** {@inheritDoc ICellRanges.isInvalidAny} */
+    isInvalidAny(): boolean;
+    /** {@inheritDoc ICellRanges.getSnapshot} */
+    getSnapshot(options?: ICellRange.CopyOptions): ICellRange.ISnapshot;
+    /** {@inheritDoc ICellRanges.getEntireRows} */
+    getEntireRows(shift?: boolean, options?: ICellRange.GetRangeOptions): this;
+    /** {@inheritDoc ICellRanges.getEntireColumns} */
+    getEntireColumns(shift?: boolean, options?: ICellRange.GetRangeOptions): this;
+    /** {@inheritDoc ICellRange.getRowHeaders} */
+    getRowHeaders(options?: ICellHeaderRange.GetRangeOptions): ICellHeaderRanges;
+    /** {@inheritDoc ICellRange.getColumnHeaders}*/
+    getColumnHeaders(options?: ICellHeaderRange.GetRangeOptions): ICellHeaderRanges;
+    /** {@inheritDoc ICellRanges.getDefaultShiftAxis} */
+    getDefaultShiftAxis(): IRange.Axis;
+    /** {@inheritDoc ICellRanges.getCount} */
+    getCount(): number;
+    /** {@inheritDoc ICellRanges.size} */
+    get size(): number;
+    /** {@inheritDoc ICellRanges.length} */
+    get length(): number;
+    /** {@inheritDoc ICellRanges.getStats} */
+    getStats(options?: ICellRange.GetStatsOptions): IRangeStats;
+    /** {@inheritDoc ICellRanges.getCounts} */
+    getCounts(features?: ICellRange.Feature | readonly ICellRange.Feature[]): ICellRange.Counts;
+    /** {@inheritDoc ICellRanges.isContentful} */
+    isContentful(features?: ICellRange.Feature | readonly ICellRange.Feature[]): boolean;
+    /** {@inheritDoc ICellRanges.getRowCount} */
+    getRowCount(): number;
+    /** {@inheritDoc ICellRanges.getColumnCount} */
+    getColumnCount(): number;
+    /** {@inheritDoc ICellRanges.isEntireRowsAny} */
+    isEntireRowsAny(): boolean;
+    /** {@inheritDoc ICellRanges.isEntireColumnsAny} */
+    isEntireColumnsAny(): boolean;
+    /** {@inheritDoc ICellRanges.isEntireRows} */
+    isEntireRows(): boolean;
+    /** {@inheritDoc ICellRanges.isEntireColumns} */
+    isEntireColumns(): boolean;
+    /** {@inheritDoc ICellRanges.isOverlapping} */
+    isOverlapping(): boolean;
+    /** {@inheritDoc ICellRange.isSingleCell} */
+    isSingleCell(): boolean;
+    /** {@inheritDoc ICellRange.isEqual} */
+    isEqual(address: ICellRange.Address, options?: ICellRange.GetRangeOptions): boolean;
+    /** {@inheritDoc ICellRanges.at} */
+    at(index: number): ICellRange;
+    /** {@inheritDoc ICellRanges.isReadOnly} */
+    isReadOnly(): boolean;
+    /** {@inheritDoc ICellRanges.isInvalid} */
+    isInvalid(): boolean;
+    /** {@inheritDoc ICellRanges.getAddress} */
+    getAddress(r1c1?: boolean): string;
+    /** {@inheritDoc ICellRanges.getSheet} */
+    getSheet(): ISheet;
+    /** {@inheritDoc ICellRanges.doBatch} */
+    doBatch<R>(callback: (commit: ITransaction.ICommit) => R | Promise<R>, options?: string | ITransaction.OperationOptions): R | Promise<R>;
+    get [Symbol.toStringTag](): string;
+    /** {@inheritDoc ICellRanges.toString} */
+    toString(): string;
+    /** {@inheritDoc ICellRanges.isICellRanges} */
+    get isICellRanges(): true;
+}
+export {};
+//# sourceMappingURL=SheetRanges.d.ts.map

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

@@ -0,0 +1,33 @@
+import { IRange } from '@sheetxl/primitives';
+import { IMovable } from '../movable';
+import { ICellRange, ICellHeaderRange } from '../cellRange';
+import { ISheet } from './ISheet';
+import { Sheet } from './Sheet';
+/**
+ * The pasted images of `areas` (absolute ranges within the marked source `coordFrom`):
+ * each area's offset within the source, tiled across the fitted destination `rangeTo` with
+ * the source's period, transposed when the paste is, and clipped to the destination.
+ * Adjacent tile images coalesce into single rectangles.
+ *
+ * @remarks
+ * This is the anchored-model (conditional format / data validation) counterpart of the
+ * spatial maps' `createCopiedEntries` tiling: the destination `_copyFrom` hands to `copyTo`
+ * is already LCM-expanded or clipped, so tiling here is a pure function of the two ranges.
+ */
+export declare function tileMarkedAreas(areas: readonly IRange.Coords[], coordFrom: Readonly<IRange.Coords>, rangeTo: Readonly<IRange.Coords>, transpose?: boolean): IRange.Coords[];
+/**
+ * Converts a header snapshot to sheet.
+ */
+export declare function headerToSheetSnapshot(rangeMark: ICellHeaderRange, coordMark: IRange.Coords, optionsMark: ICellHeaderRange.CopyOptions): Partial<ICellRange.ISnapshot>;
+/**
+ * Wraps a copySheetTo function into a ISheet.ISnapshot.
+ * * This will error if snapshot is a cut and called a second.
+ * @internal
+ */
+export declare function callbackToSheetSnapshot(sheetFrom: ISheet, sheetMark: ISheet, coordsFrom: readonly IRange.Coords[], description: string, optionsMark: ICellRange.CopyOptions, copySheetTo: (sheetRange: ICellRange, options?: ICellRange.CopyOptions) => Promise<IRange.Coords> | IRange.Coords): ICellRange.ISnapshot;
+/**
+ * Converts an array of Snapshots into a single snapshot.
+ */
+export declare function arrToSheetSnapshot(snapshots: Partial<ICellRange.ISnapshot>[], sheet: ISheet, sheetMark: ISheet, coordsMark: IRange.Coords, optionsMark: ICellRange.CopyOptions, descriptionMark: string, snapshotNative?: ICellRange.ISnapshot | null): ICellRange.ISnapshot;
+export declare function movablesToSheetSnapshot(sheetMark: Sheet, coordsMark: readonly IRange.Coords[], movablesSelectionMark: readonly IMovable[], markOptions: ICellRange.CopyOptions): ICellRange.ISnapshot<ISheet> | null;
+//# sourceMappingURL=_CopyUtils.d.ts.map