@sheetxl/sdk 0.7.21 → 0.7.23-beta.2

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

@@ -0,0 +1,1074 @@
+import { Scalar, IRange, IRangeStats, IRuntime } from '@sheetxl/primitives';
+import { Bounds, Size } from '@sheetxl/utils';
+import { ITypes } from '../type';
+import { ITransaction } from '../transaction';
+import { Tuple } from '../collections';
+import { IWorkbook } from '../workbook';
+import { IResourceCollection, IResource } from '../resource';
+import { IStringCollection } from '../string';
+import { IComment } from '../comment';
+import { IPrint } from '../print';
+import { IColor } from '../color';
+import { IListener } from '../listener';
+import { IHyperlink } from '../hyperlink';
+import { IMovable, IMovableCollection } from '../movable';
+import { IPicture } from '../picture';
+import { ICell, ICellHeader } from '../cell';
+import { ICellRange, ICellRanges, ICellRegions } from '../cellRange';
+import { IStyleCollection } from '../style';
+import { ITableCollection, ITable } from '../table';
+import { IDataValidationCollection, IDataValidation } from '../dataValidation';
+import { ISlicer } from '../slicer';
+import { INamedCollection } from '../named';
+import { ICalculation } from '../calculation';
+import { IRangeSelection } from '../selection';
+import { ISheetView } from '../sheetView';
+import { ISheetHeader } from '../sheetHeader';
+import { ISheetProtection } from '../sheetProtection';
+import { ICellContainerOptions } from './ICellContainerOptions';
+import { IConditionalFormat } from '../conditionalFormat/IConditionalFormat';
+import { IConditionalFormatCollection } from '../conditionalFormat/IConditionalFormatCollection';
+import { IProtectedRange } from '../protectedRange/IProtectedRange';
+import { IProtectedRangeCollection } from '../protectedRange/IProtectedRangeCollection';
+/**
+ * An `ISheet` represents a collection of elements (such as {@link ICellRange | ranges},
+ * {@link ITable | tables}, etc) contained within and visualized through a {@link ISheetView | view}.
+ *
+ * This interface provides methods for accessing its elements and event handling.
+ *
+ * Most interactions with a {@link ISheet | sheet} are done using either a {@link ICellRange | range} or {@link ICellRanges | ranges}.
+ *
+ * @remarks
+ * While a {@link ISheet | sheet} can be used stand-alone it is typically used within the context of a {@link IWorkbook | workbook}.
+ *
+ * ### **Key Methods**
+ *
+ * * {@link ISheet.getRange} - For interacting with {@link ICell | cells} and {@link Scalar | values} and formatting.
+ * * {@link ISheet.getTables} - For managing {@link ITable | tables}.
+ * * {@link ISheet.getView} - For non-data related properties such as selection or frozen headers.
+ * * {@link IWorkbook} - For working with collections of `ISheets`.
+ */
+export interface ISheet extends ITransaction.ITransactional, IListener.ISource<ISheet, ISheet.IListeners> {
+    /**
+     * Returns an {@link ICellRange} used to interact with a
+     * a rectangular 2D collection of cells at a specific range.
+     *
+     * @param address Address of the ranges. Omit for the selected range — selection is modeled
+     * by the SDK (not a UI mode), and many operations default to it. `getSelectedRange` remains
+     * the explicit form.
+     * @param options Options for the ranges.
+     */
+    getRange(address?: ICellRange.Address, options?: ICellRange.GetRangeOptions): ICellRange;
+    /**
+     * Returns a {@link ICell} at the specified address.
+     *
+     * @param address Address of the cell. Omit for the selected cell — selection is modeled
+     * by the SDK (not a UI mode), and many operations default to it. `getSelectedCell` remains
+     * the explicit form.
+     */
+    getCell(address?: ICell.Address): ICell;
+    /**
+     * Returns an {@link ICellRanges}. An {@link ICellRanges} is an ordered list of
+     * {@link ICellRange}s. These are used to interact with a set of contiguous 2D ranges.
+     *
+     * @param address Address of the ranges.
+     * @param options Options for the ranges.
+     */
+    getRanges(address: ICellRanges.Address, options?: ICellRange.GetRangeOptions): ICellRanges;
+    /**
+     * Returns the range for the entire sheet.
+     *
+     * @remarks
+     * This can be updated via {@link ISheet.setEntireSize}.
+     *
+     * @see
+     * {@link ICellRange}
+     */
+    getEntireRange(options?: ICellRange.GetRangeOptions): ICellRange;
+    /**
+     * Returns the coords for the entire sheet.
+     *
+     * @remarks
+     * This is a lightweight call to `ISheet.getEntireRange().getCoords()`.
+     */
+    getEntireCoords(): IRange.Coords;
+    /**
+     * Returns the smallest range within the sheet that contains any used cells.
+     *
+     * @see
+     * {@link ICellRange.getUsedRange}
+     */
+    getUsedRange(options?: ICellRange.GetRangeOptions): ICellRange | null;
+    /**
+     * Returns the statistics for the used cells of the sheet.
+     *
+     * @param options Iterator options the stats are created with — most usefully
+     * `{ onError: 'ignore' }` so aggregate reads degrade instead of faulting on error values.
+     *
+     * @remarks
+     * Equivalent to `getUsedRange().getStats(…)` except **null-safe** — an empty sheet returns
+     * empty statistics (`getSize() === 0`) rather than forcing the caller to branch on
+     * {@link getUsedRange} returning `null`.
+     *
+     * @see
+     * {@link ICellRange.getStats}
+     */
+    getStats(options?: ICellRange.GetStatsOptions): IRangeStats;
+    /**
+     * Returns the uniform regions for the requested features across the whole sheet.
+     *
+     * @remarks
+     * The partition operator belongs on the thing partitioned, and *"where are the blocks in this
+     * sheet"* is the question an agent actually has — the `ICellRange` flavor is how you
+     * **constrain** that query, not how you start it.
+     *
+     * Equivalent to `getEntireRange().getRegions(…)`: the partition reads the feature indexes, so
+     * it costs the used cells rather than the address space.
+     * @see
+     * {@link ICellRange.getRegions}
+     */
+    getRegions(features?: ICellRange.Feature | readonly ICellRange.Feature[], options?: ICellRange.GetRegionsOptions): ICellRegions;
+    /**
+     * Returns the current selection.
+     *
+     * @remarks
+     * This allows for listening to selection changes and advanced navigation.
+     */
+    getSelection(): IRangeSelection;
+    /**
+     * Returns the selected cell.
+     *
+     * @remarks
+     * This is a convenience method for 'getSelection().getCell()'.
+     */
+    getSelectedCell(): ICell;
+    /**
+     * Returns a range of cells for the current selection.
+     *
+     * @remarks
+     * This is a convenience method for 'getSelection().getRange()'.
+     */
+    getSelectedRange(options?: ICellRange.GetRangeOptions): ICellRange;
+    /**
+     * Returns ranges of cells for the current selection.
+     *
+     * @remarks
+     * This is a convenience method for 'getSelection().getRanges()'.
+     */
+    getSelectedRanges(options?: ICellRange.GetRangeOptions): ICellRanges;
+    /**
+     * Returns an iterator of ICells that match the results.
+     *
+     * @param options This is either a search string or {@link ICellRange.FindOptions}.
+     *
+     * @remarks
+     * This is the equivalent of `getEntireRange().find`.
+     * @see
+     * {@link ICellRange.find}
+     */
+    find(options: string | ICellRange.FindOptions): Iterator<ICell>;
+    /**
+     * Creates a 'light' table used for stateful filtering and sorting with-in a sheet.
+     *
+     * @see {@link ITable}
+     */
+    addAutoTable(address?: ICellRange, options?: ICellRange.AddAutoTableOptions): ITable;
+    /**
+     * Returns the {@link ITable} created using {@link addAutoTable}.
+     */
+    getAutoTable(): ITable | null;
+    /**
+     * Returns a collection of tables that are embedded in this sheet.
+     */
+    getTables(): ITableCollection;
+    /**
+     * Returns a collection of validations that are embedded in this sheet.
+     */
+    getDataValidations(): IDataValidationCollection;
+    /**
+     * Returns a collection of conditional formats that are embedded in this sheet.
+     */
+    getConditionalFormats(): IConditionalFormatCollection;
+    /**
+     * Returns a collection of ranges that stay editable while this sheet is protected.
+     *
+     * @remarks
+     * Excel's *Review → Allow Edit Ranges*. Only consulted while
+     * {@link ISheetProtection.isLocked} is true.
+     */
+    getProtectedRanges(): IProtectedRangeCollection;
+    /**
+     * Returns a collection of movables that are embedded in this sheet.
+     */
+    getMovables(): IMovableCollection;
+    /**
+     * Returns the row headers managed by the sheet.
+     */
+    getRowHeaders(): ISheetHeader;
+    /**
+     * Returns the column headers managed by the sheet.
+     */
+    getColumnHeaders(): ISheetHeader;
+    /**
+     * Return a custom color or `null` if no custom color has been set.
+     *
+     * @defaultValue null
+     */
+    getTabColor(): IColor;
+    /**
+     * See the tab color for the sheet.
+     *
+     * @param color The color
+     *
+     * @remarks
+     * * If set to `null` the color will revert to the default.
+     * * The tab color is not used by the sheet but rather by the workbook.
+     */
+    setTabColor(color: IColor | string | null): this;
+    /**
+     * Returns the sheet protection.
+     */
+    getProtection(): ISheetProtection;
+    /**
+     * Returns the current view settings
+     * View settings determine how the sheet is displayed and interacted with (e.g., frozen panes, zoom level, selection) but do not affect the underlying data itself.
+     *
+     * @returns The {@link ISheetView} object representing the current view settings.
+     */
+    getView(): ISheetView;
+    /**
+     * Set a specific view.
+     *
+     * @param view The view properties.
+     */
+    setView(view: ISheetView): this;
+    /**
+     * Returns `IStyleCollection` associated with this sheet.
+     */
+    getStyles(): IStyleCollection;
+    /**
+     * Returns the current shared resources.
+     */
+    getResources(): IResourceCollection;
+    /**
+     * Returns the current shared resources.
+     */
+    getStrings(): IStringCollection;
+    /**
+     * Returns the current shared resources.
+     */
+    getTransactions(): ITransaction.IStore;
+    /**
+     * Returns the runtime used for this sheet.
+     *
+     * @remarks
+     * This can not be set on the `ISheet`. This is managed by the sheet's container.
+     */
+    getRuntime(): IRuntime;
+    /**
+     * Returns the column width as a font unit.
+     *
+     * This is used as an informative tooltip.
+     *
+     * @param pixelWidth
+     *
+     * @see
+     * * {@link https://docs.microsoft.com/en-us/office/troubleshoot/excel/determine-column-widths}
+     * * {@link https://www.ablebits.com/office-addins-blog/change-autofit-column-width-excel/}
+     */
+    getColumnWidthAsFontUnit(pixelWidth: number): number;
+    /**
+     * Returns the {@link ICellRange | range} for a given pixel bounds.
+     *
+     * @param bounds
+     */
+    getRangeAtBounds(bounds: Bounds, options?: ICellRange.GetRangeOptions): ICellRange;
+    /**
+     * Returns a 1×1 cell or an explicit range at the specified **absolute** sheet coordinates.
+     *
+     * @see {@link ICellRange.getRangeAt} for relative coordinates.
+     */
+    getRangeAt(rowStart: number, columnStart: number, rowEnd?: number, columnEnd?: number, options?: ICellRange.GetRangeOptions): ICellRange;
+    /**
+     * Creates a cell that is not including at a coordinate but adopts all rendering.
+     *
+     * @param update Cell Update
+     * @param coords Optional CellCoord
+     * @returns A detached ICell
+     *
+     * @remarks
+     * * Useful for previewing values such as tooltip.
+     * * Does not add to the sheet but provides a standalone ICell.
+     * * If the coords are passed it will return disconnect cell update for that value.
+     */
+    createCell(update: ICell.Update, coords?: IRange.FixableCellCoords): ICell;
+    /**
+     * Parses a formula expression and returns a *transient* formula object anchored to this sheet.
+     *
+     * @param expression The formula expression to parse.
+     * @param coords Optional anchor coordinates.
+     *
+     * @remarks
+     * This is a convenience method for `getCalculation().createFormula(expression, coords)`;
+     * like everything reached through the sheet's {@link getCalculation}, a bare reference (`A2`)
+     * resolves against THIS sheet rather than the selected one.
+     *
+     * @see {@link ICalculation.createFormula}
+     */
+    createFormula(expression: string, coords?: Partial<IRange.CellCoords>): ICalculation.IFormula;
+    /**
+     * Add Listeners.
+     *
+     * @see
+     * {@link IListener.ISource.addListeners}
+     */
+    addListeners(listeners: ISheet.IListeners, options?: IListener.Options): IListener.Remove;
+    /**
+     * Returns the display name for the sheet.
+     */
+    getName(): string;
+    /**
+     * Set the display name for the sheet.
+     */
+    setName(name: string, options?: ITransaction.OperationOptions): this;
+    /**
+     * Returns the visibility of the sheet.
+     */
+    getVisibility(): ISheet.Visibility;
+    /**
+     * Change the visibility of the sheet.
+     *
+     * @defaultValue ISheet.Visibility.Visible
+     */
+    setVisibility(visibility?: ISheet.Visibility | boolean, options?: ITransaction.OperationOptions): ISheet;
+    /**
+     * The {@link INamed}s **visible from this sheet** — what a formula written here can refer to.
+     *
+     * @remarks
+     * The global items (every table among them, since a table name is always global) plus this sheet's
+     * own scoped names, with shadowing resolved: where a sheet-scoped name and a global share a name,
+     * only this sheet's is returned, because that is the one a formula here resolves to. Another
+     * sheet's scoped names are never included.
+     *
+     * Everything is anchored to THIS sheet, not the selected one: `getByName` resolves against it, and
+     * `getByRanges` reads unqualified coords as being on it — which is what lets this sheet's own
+     * selection be passed straight in.
+     *
+     * Use {@link IWorkbook.getNames} for every name in the workbook (a name manager), and
+     * {@link ISheet.getTables} for the tables that LIVE on this sheet — scope here is visibility, never
+     * location, so a table anchored to another sheet is still visible from this one.
+     */
+    getNames(): INamedCollection;
+    /**
+     * Returns the {@link ICalculation} **anchored to this sheet**.
+     *
+     * @remarks
+     * The engine itself is workbook-wide; this is a view over it that supplies THIS sheet as the context
+     * whenever a caller doesn't name one. So an expression parsed or evaluated through it resolves a bare
+     * reference (`A2`) against this sheet — not against whichever sheet happens to be selected.
+     *
+     * That matters for anything anchored by coords alone, e.g.
+     * `sheet.getCalculation().createFormula('=A2+B2', cell.getCoords())`: reached through the
+     * workbook ({@link IWorkbook.getCalculation}) the same call has no sheet context and falls back to the
+     * active cell's sheet, which makes the parse depend on UI selection state. Pass an explicit
+     * `coords.scope` to override the anchor (a cross-sheet reference is unaffected either way — it names its
+     * own sheet).
+     */
+    getCalculation(): ICalculation;
+    /**
+     * Recalculates THIS sheet — Excel's "Calculate Sheet" (Shift+F9) / `Worksheet.Calculate`.
+     *
+     * @param full When `true`, recalculate every formula on the sheet. Otherwise only the ones whose
+     * inputs changed (plus volatiles), which is what Excel's Shift+F9 does.
+     *
+     * @remarks
+     * Distinct from `getEntireRange().calculate(full)`, which marks the range dirty first and is
+     * therefore always a FORCE for those cells. This is the dirty-respecting sheet-scoped pass.
+     *
+     * Only the SEED is scoped to this sheet: dependents on other sheets still recalculate, and
+     * volatiles are still workbook-wide. Excel leaves both stale; being more current is the safe
+     * direction, and the volatile registry is drained per pass, so skipping them would deregister
+     * them outright.
+     */
+    calculate(full?: boolean): Promise<ICalculation.Status>;
+    /**
+     * Evaluates a formula in the context of the sheet and returns the resulting value.
+     *
+     * @param formula The formula to evaluate.
+     * @param options Optional evaluation options.
+     *
+     * @remarks
+     * This is similar convenience method for `getCalculation().createFormula(expression).evaluate(options)`.
+     */
+    evaluate(formula: string, options?: ICalculation.EvaluateOptions & Partial<IRange.CellCoords>): Promise<Scalar | IRange>;
+    /**
+     * Returns when all calculations are complete and there are no pending calculations.
+     *
+     * @remarks
+     * * This is a convenience method `getCalculation().ready()`.
+     */
+    whenCalculationReady(): Promise<ICalculation.Status>;
+    /**
+     * Returns the {@link IWorkbook} for the sheet.
+     *
+     * @remarks
+     * This may be `null` if not created via a workbook.
+     */
+    getWorkbook(): IWorkbook | null;
+    /**
+     * Removes from a container. This is usually the `Workbook`. If this is being
+     * used standalone this operation will throw an exception.
+     */
+    delete(): void;
+    /**
+     * Returns if the sheet has been deleted from its container.
+     */
+    isDeleted(): boolean;
+    /**
+     * Select the `ISheet`.
+     */
+    select(options?: ITypes.SelectOptions): Promise<this>;
+    /**
+     * Attempt to scroll the range into view.
+     *
+     * @param coords The partial coords to scroll to.
+     * @param options {@link ISheet.ScrollToOptions}.
+     */
+    scrollTo(coords: Partial<IRange.Coords>, options: ISheet.ScrollToOptions): Promise<boolean>;
+    /**
+     * Returns a promise that will resolve to a copy of the current sheet.
+     */
+    duplicate(): Promise<this>;
+    /**
+     * Returns the current index of the `ISheet` within its container.
+     *
+     * @remarks
+     * Will return -1 if not in a Workbook or other sheet container.
+     */
+    getIndex(): number;
+    /**
+     * Reorders the `ISheet` with in the container. This is generally the tab order within an `IWorkbook` but may
+     * be the zIndex if the `ISheets` are movable. This only affects visual listings of the sheets (but selection doesn't change).
+     *
+     * @remarks
+     * This is zero-based.
+     */
+    setIndex(index: number): this;
+    /**
+     * Set the entire size of the sheet.
+     *
+     * @remarks
+     * Calling with a `null` size will reset the sheet size to the default.
+     */
+    setEntireSize(size?: Partial<Size> | null, options?: ITransaction.OperationOptions): this;
+    /**
+     * Returns the picture interface for the sheet.
+     */
+    getPicture(): IPicture | null;
+    /**
+     * Set the picture interface for the entire sheet.
+     * @param picture The picture interface to set for the sheet, or null to remove it.
+     */
+    setPicture(picture: string | IResource | IResourceCollection.AddOptions | null, options?: ITransaction.OperationOptions): this;
+    /**
+     * Returns a JSON representation of the sheet.
+     *
+     * @param options Options to control the JSON output.
+     */
+    toJSON(options?: ISheet.ToJSONOptions): Promise<ISheet.JSON>;
+    /**
+     * Free all resources associated with the sheet.
+     *
+     * @remarks
+     * * Called by workbooks when the workbook is is closed.
+     * * This is different than delete which removes the sheet from the workbook.
+     *
+     * @see
+     * {@link ISheet.addListeners} for closeEvent
+     */
+    close(): void;
+    /**
+     * Returns true if the sheet has been closed.
+     */
+    isClosed(): boolean;
+    /**
+     * For runtime type checking.
+     */
+    readonly isISheet: true;
+}
+/**
+ * {@inheritDoc ISheet}
+ * @see
+ * ### **Interface**
+ *
+ * {@link ISheet}
+ *
+ * ### **Implementation**
+ *
+ *  {@link Sheet}
+ */
+export declare namespace ISheet {
+    /**
+     * The different ways to identify a range within a sheet,
+     * supporting both relative and absolute (fixed) addressing.
+     *
+     * Accepts:
+     * - `ICellRange`
+     * - A parsable `string` representing a range address (e.g., A1 or $A$1 notation).
+     * - A partial `IRange.Coords` object (specifying at least some of the range boundaries),
+     *   optionally with a `$fixed` flag to indicate absolute addressing.
+     * - `ICellRange.Address` (representing a single cell within the sheet),
+     *   optionally with a `$fixed` flag to indicate absolute addressing.
+     *
+     * @example
+     * ```typescript
+     * const address1: Address = "A1:B2"; // Relative addressing (A1 notation)
+     * const address2: Address = "$A$1:$B$2"; // Absolute addressing (A1 notation)
+     * ```
+     */
+    type RangeAddress = ICellRange | string | Partial<IRange.FixableCoords> | ICell.Address;
+    /**
+     * Represents the different ways to identify multiple ranges within a sheet.
+     *
+     * Accepts:
+     * - `ICellRanges`
+     * - A parsable `string` containing multiple range addresses separated by commas (e.g., "A1:B2,C3:D4").
+     * - An array of `ICellRange.Address` objects, each representing a single range.
+     *
+     * @example
+     * ```typescript
+     * const address1: ICellRanges.Address = "A1:B2,C3:D4"; // String with multiple ranges.
+     * ```
+     * @remarks
+     * This extends {@link ICellRange.Address} to support multiple values.
+     */
+    type RangesAddress = ICellRanges | string | ICellRange.Address | ICellRange.Address[];
+    /**
+     * Indicates how a sheet should be available to the user.
+     */
+    const Visibility: {
+        /**
+         * Visible in all sheet displays.
+         * For example: Tabs, menus, and formulas)
+         */
+        readonly Visible: "visible";
+        /**
+         * Not visible in most menus but still available in
+         * user unhide options as well as available to formulas.
+         */
+        readonly Hidden: "hidden";
+        /**
+         * Completely hidden to the user but still available via
+         * apis.
+         */
+        readonly VeryHidden: "veryHidden";
+    };
+    type Visibility = typeof Visibility[keyof typeof Visibility];
+    /**
+     * Options for scrolling to a specific range.
+     */
+    interface ScrollToOptions {
+        /**
+         * The partial coords to scroll to.
+         */
+        coords?: Partial<IRange.Coords>;
+        /**
+         * Any pixel offsets
+         */
+        offsets?: Bounds;
+        /**
+         * The scrollTo options.
+         */
+        scroll?: globalThis.ScrollIntoViewOptions | boolean;
+    }
+    /**
+     * Events for {@link ISheet}.
+     */
+    interface Events {
+        /**
+         * Called when the UsedRange bounds changes.
+         *
+         * @remarks
+         * Useful when interested in knowing when the bounds of the area
+         * that is being used within the sheet changes; for example this is used
+         * by the scrollbars to adjust the size.
+         * @see
+         * {@link ISheet.getUsedRange}
+         */
+        onUsedRangeChange?(source: ISheet): void;
+        /**
+         * Called when any data has changed.
+         *
+         * @remarks
+         * This is a course event that indicates that data has changed.
+         * To listen for changes on data regions use {@link ICellRange.addListener}.
+         */
+        onDataChange?(source: ISheet): void;
+        /**
+         * Called when the sheet tab color changes.
+         */
+        onTabColorChange?(source: ISheet): void;
+        /**
+         * Called when any merges are added or removed.
+         */
+        onMergesChange?(source: ISheet): void;
+        /**
+         * Called if any spills occur.
+         */
+        onSpillsChange?(source: ISheet): void;
+        /**
+         * Called when any movables are added or removed.
+         */
+        onMovablesChange?(source: ISheet): void;
+        /**
+         * Called when any table are added or removed.
+         */
+        onTablesChange?(source: ISheet): void;
+        /**
+         * Called when any data validation is added, removed, re-anchored, or re-evaluates its results.
+         *
+         * @remarks
+         * Always accompanied by the coarse {@link onStyleChange}. Listen here only when reacting to
+         * the validations themselves (an editor panel, the alert indicators); renderers should listen
+         * to the class event instead.
+         */
+        onDataValidationsChange?(source: ISheet): void;
+        /**
+         * Called when any conditional format is added, removed, re-anchored, reordered, or finishes
+         * (re)evaluating — a rule's results land asynchronously, after the calculation engine answers.
+         *
+         * @remarks
+         * Always accompanied by the coarse {@link onStyleChange}. Listen here only when reacting to
+         * the rules themselves (an editor panel); renderers should listen to the class event instead.
+         */
+        onConditionalFormatsChange?(source: ISheet): void;
+        /**
+         * Called when protected ranges are added, removed, renamed, reordered or re-anchored.
+         *
+         * @remarks
+         * Always accompanied by the coarse {@link onProtectionChange}.
+         */
+        onProtectedRangesChange?(source: ISheet): void;
+        /**
+         * Called when the auto table is added or removed.
+         */
+        onAutoTableChange?(source: ISheet): void;
+        /**
+         * Called when anything that affects how cells PAINT (other than data or layout) changes.
+         *
+         * @remarks
+         * One of the three coarse class events (with {@link onLayoutChange} and
+         * {@link onProtectionChange}): a single subscription for "the sheet may render differently",
+         * meant for renderers so they never have to accumulate the finer-grained events. It fires
+         * alongside each of them — direct and named style edits, table styling
+         * ({@link onTablesChange}), conditional formatting results
+         * ({@link onConditionalFormatsChange}, including their asynchronous evaluation completing),
+         * and data validation visuals ({@link onDataValidationsChange}) all raise it. Listen to a
+         * finer event only when reacting to that specific collection.
+         */
+        onStyleChange?(source: ISheet): void;
+        /**
+         * Called when the sizes of the cells change.
+         *
+         * @remarks
+         * One of the three coarse class events (see {@link onStyleChange}): the single subscription
+         * for "cell geometry moved".
+         * * This can be be due to row/column sizes changes or changing the max rows columns.
+         * * Zoom and viewport do not change the underlying layout.
+         */
+        onLayoutChange?(source: ISheet): void;
+        /**
+         * Called when which rows are hidden has changed.
+         */
+        onRowsHiddenChange?(source: ISheet): void;
+        /**
+         * Called when which columns are hidden has changed.
+         */
+        onColumnsHiddenChange?(source: ISheet): void;
+        /**
+         * Called on any protection changes.
+         *
+         * @remarks
+         * One of the three coarse class events (see {@link onStyleChange}): the single subscription
+         * for "what the user may touch changed" — the sheet lock state, its allowed actions, and the
+         * protected ranges ({@link onProtectedRangesChange}) all raise it.
+         */
+        onProtectionChange?(source: ISheet): void;
+        /**
+         * Called before load. If any exception is thrown this
+         * exception will be returned to the client and delete will fail.
+         */
+        onBeforeLoad?(source: ISheet, json: ISheet.JSON): void;
+        /**
+         * Called after load.
+         */
+        onLoad?(source: ISheet): void;
+        /**
+         * Called before load. If any exception is thrown this
+         * exception will be returned to the client and delete will be aborted.
+         */
+        onBeforeSave?(source: ISheet): Promise<void> | void;
+        /**
+         * Called after save.
+         */
+        onSave?(source: ISheet, json: ISheet.JSON): void;
+        /**
+         * Called before delete. If any exception is thrown the
+         * exception will be returned to the client and delete will be aborted.
+         */
+        onBeforeDelete?(source: ISheet): void;
+        /**
+         * Request that the sheet become focused.
+         * @returns A promise indicating if the focus was honored.
+         *
+         * @remarks
+         * This should only be handled by one consumer.
+         */
+        onRequestScrollIntoView?(source: ISheet, options: ISheet.ScrollToOptions): Promise<boolean>;
+        /**
+         * Request that the sheet become focused.
+         * @returns A promise indicating if the focus was honored.
+         * @remarks
+         * This should only be handled by one consumer.
+         */
+        onRequestFocus?(source: ISheet): Promise<boolean>;
+        /**
+         * Request the visible viewport ("window") bounds in absolute sheet pixels — the one placement input the
+         * model can't derive itself. Used to center a bounds-less movable (e.g. a chart via
+         * {@link IMovableCollection.AddOptions.autoPlace}); when no consumer responds (headless) the add falls
+         * back to default cursor placement.
+         *
+         * @remarks
+         * This should only be handled by one consumer (the grid view).
+         */
+        onRequestViewport?(source: ISheet): Promise<Bounds | null>;
+        /**
+         * Called when the sheet is deleted.
+         */
+        onDelete?(source: ISheet): void;
+        /**
+         * Called when the `ISheetView` changes.
+         *
+         * This is not called when individual properties on the view change.
+         */
+        onViewChange?(source: ISheet): void;
+        /**
+         * Called when the topLeft changes.
+         *
+         * @remarks
+         * This is a delegated event from the `ISheetView`.
+         */
+        onTopLeftChange?(source: ISheet): void;
+        /**
+         * Called when the selection changes.
+         *
+         * @remarks
+         * This is a delegated event from the `ISheetView`.
+         */
+        onSelectionChange?(source: ISheet): void;
+        /**
+         * Called when freeze or split settings have changed.
+         *
+         * @remarks
+         * This is a delegated event from the `ISheetView`.
+         */
+        onFreezePaneChange?(source: ISheet): void;
+        /**
+         * Called when the zoom scale changes.
+         *
+         * @remarks
+         * This is a delegated event from the `ISheetView`.
+         */
+        onZoomScaleChange?(source: ISheet): void;
+        /**
+         * Called when the movable selection changes.
+         *
+         * @remarks
+         * This is a delegated event from the `ISheetView`.
+         */
+        onMovableSelectionChange?(source: ISheet): void;
+        /**
+         * Called when the view changes.
+         */
+        onViewChange?(source: ISheet): void;
+        /**
+         * Called when the name changes.
+         */
+        onNameChange?(source: ISheet): void;
+        /**
+         * Called when the visibility changes..
+         */
+        onVisibilityChange?(source: ISheet): void;
+        /**
+         * Called when the index changes.
+         */
+        onIndexChange?(source: ISheet): void;
+        /**
+         * Called when the state has been updated due to a undo/redo and a rerender is required.
+         */
+        onInvalidated?(source: ISheet): void;
+        /**
+         * Called when the sheet is closed.
+         */
+        onClose?(source: ISheet): void;
+    }
+    interface IListeners extends IListener.Callbacks<ISheet, ISheet.Events> {
+    }
+    interface ToJSONOptions {
+        /**
+         * If `true` the raw values will not be included in the JSON.
+         *
+         * @remarks
+         * When ignoring Data the strings will also not be included in the JSON.
+         */
+        ignoreData?: boolean;
+        /**
+         * If `true` the resources will not be included in the JSON.
+         *
+         * @remarks
+         * This is useful when exporting resources to another location and
+         * converting to base64 is not required.
+         */
+        ignoreResources?: boolean;
+        /**
+         * If `true` the resources will not include formatting.
+         *
+         * @remarks
+         * This will also ignore merges and hyperlinks styles
+         */
+        ignoreStyles?: boolean;
+        /**
+         * If `true` the formulas will not be included in the JSON.
+         */
+        ignoreFormulas?: boolean;
+        /**
+         * If `true` header styles will be included in the JSON.
+         *
+         * @remarks
+         * This is useful when exporting to formats such as ooxml that do not support
+         * ranged direct styles.
+         * * If ignoreStyles is true this is ignored
+         */
+        includeHeaderStyles?: boolean;
+        /**
+         * If `true` styled borders will be split into individual border elements in the JSON.
+         *
+         * @remarks
+         * This is useful when exporting to formats such as ooxml that do not support
+         * ranged border elements.
+         *
+         * Ignored if ignoreStyles is `true`.
+         */
+        splitDirectBorders?: boolean;
+        /**
+         * A structural transform applied to each formula as it serializes.
+         *
+         * @remarks
+         * Runs ONCE per formula block on the compiled AST (per-cell re-anchoring/re-imaging are
+         * unaffected); an all-`void` transform costs no recompile.
+         * Ignored if ignoreFormulas is `true`.
+         *
+         * @see {@link ICalculation.FormulaTransform}
+         */
+        formulaTransform?: ICalculation.FormulaTransform;
+    }
+    /**
+     * Optional values used in the construction of am {@link ISheet}.
+     *
+     * @remarks
+     * Changes to these options will be ignored after construction.
+     */
+    interface ConstructorOptions extends ICellContainerOptions {
+        /**
+         * When adding to another container.
+         */
+        container?: ISheet.ContainerOptions;
+        /**
+         * A unique identifier used for identifying this sheet during operations (i.e. copy/paste).
+         * This must be unique for all in-memory instances of a sheet.
+         *
+         * @returns A unique identifier for in memory operations. If not provided a default one will be used.
+         * @remarks
+         * This is not saved as part of the {@link ISheet.JSON} persisted model.
+         */
+        uid?: () => string;
+        /**
+         * Initial JSON.
+         */
+        json?: ISheet.JSON;
+        /**
+         * A structural transform applied once to each formula parsed from {@link json} — the READ
+         * half of the format-dialect hook (see `IWorkbook.ConstructorOptions.formulaTransform`).
+         * Load-time only; never applied to text typed or set after construction.
+         */
+        formulaTransform?: ICalculation.FormulaTransform;
+    }
+    /**
+     * Options needed for embedding a sheet into another container such as a workbook.
+     */
+    interface ContainerOptions {
+        /**
+         * Required to be called before from JSON.
+         * @param self -The Sheet
+         *
+         * @remarks
+         * This is needed to ensure the contain has access to the sheet reference so that
+         * it can resolve references.
+         */
+        beforeFromJSON?: (self: ISheet) => void;
+        /**
+         * Callback to provide a sheet with a logical name. This is used
+         * when a sheet name property is invoked.
+         *
+         * @remarks
+         * Sheets don't have a name by default but as a convenience we allow
+         * for the name to be called from the sheet.
+         */
+        getName: () => string | null;
+        setName?: (name: string | null, options?: ITransaction.OperationOptions) => void;
+        setNameChangeCallback?: (callback: () => void) => void;
+        /**
+         * Return the current index.
+         */
+        getIndex?: () => number | null;
+        /**
+         * Request that this moved.
+         *
+         * @param index The index to set to.
+         *
+         * @remarks
+         * For traditional workbooks with not docking tabs this will be the tab position.
+         */
+        setIndex?: (index: number, options?: ITransaction.OperationOptions) => boolean;
+        setIndexCallback?: (callback: () => void) => void;
+        /**
+         * Callback to provide a sheet with a visibility.
+         *
+         * @remarks
+         * Sheets don't manage this but as a convenience we allow
+         * for the visibility to be called from the sheet.
+         */
+        getVisibility?: () => ISheet.Visibility;
+        setVisibility?: (visibility: ISheet.Visibility, options?: ITransaction.OperationOptions) => void;
+        setVisibilityCallback?: (callback: () => void) => void;
+        /**
+         * Returns a copy of the sheet provided sheet.
+         */
+        duplicate?: () => Promise<ISheet>;
+        /**
+         * Request that the sheet become the active sheet.
+         *
+         * @returns A flag indicating that the sheet was brought to the front.
+         *
+         * @remarks
+         * In a workbook context there is only one active sheet at a time but other clients
+         * may treat this this differently.
+         */
+        requestSelect?: (options?: ITypes.SelectOptions) => Promise<boolean>;
+    }
+    /**
+     * A set of properties for `ISheet`.
+     */
+    interface PropertiesJSON {
+        custom?: Record<string, string>;
+        calc?: {
+            fullCalcOnLoad?: boolean;
+        };
+        ignoreErrors?: Record<string, string[]>;
+        /** {@inheritDoc IPrint.HeaderFooter} */
+        headerFooter?: IPrint.HeaderFooter;
+        /** {@inheritDoc IPrint.PageSetup} */
+        pageSetup?: IPrint.PageSetup;
+        /** {@inheritDoc IPrint.PageSetUpProperties} */
+        pageSetUpPr?: IPrint.PageSetUpProperties;
+        /** {@inheritDoc IPrint.PrintOptions} */
+        printOptions?: IPrint.PrintOptions;
+        /** {@inheritDoc IPrint.OutlineProperties} */
+        outlinePr?: IPrint.OutlineProperties;
+        rowBreaks?: IPrint.Break[];
+        colBreaks?: IPrint.Break[];
+        phoneticPr?: {
+            alignment?: string;
+            fontId?: number;
+            type: string;
+        };
+    }
+    /**
+     * JSON representation of an `ISheet` used for serialization and deserialization.
+     */
+    interface JSON {
+        data?: Tuple.GridTuple<ICell.JSON>;
+        formulas?: IRange.JSONReferenceTuple<string>[];
+        /**
+         * The extent occupied by an array formula, and which of the three
+         * {@link ITypes.FormulaArrayKind | kinds} of array formula it is.
+         *
+         * @remarks
+         * Every array formula earns an entry, degenerate 1x1 ones included - a 1x1 extent is not the
+         * same thing as no extent. Only the `kind` distinguishes a fixed one-cell block from a
+         * dynamic formula that happened not to spill; the extent cannot.
+         */
+        formulaArray?: IRange.JSONReferenceTuple<ITypes.FormulaArrayKind>[];
+        volatile?: IRange.Address[];
+        /**
+         * Column headers, each addressed as an entire-column run (`'E:E'`, `'E:H'`).
+         *
+         * @remarks
+         * Can be empty. The address carries the orientation, so a row address is read here too.
+         */
+        cols?: IRange.JSONReference<ICellHeader.JSON>[];
+        defaultColSize?: number;
+        outlineLevelCol?: number;
+        /**
+         * Row headers, each addressed as an entire-row run (`'5:5'`, `'5:12'`).
+         *
+         * @remarks
+         * Can be empty. The address carries the orientation, so a column address is read here too.
+         */
+        rows?: IRange.JSONReference<ICellHeader.JSON>[];
+        defaultRowSize?: number;
+        outlineLevelRow?: number;
+        styles?: IStyleCollection.JSON;
+        resources?: IResource.JSON[];
+        strings?: string[];
+        people?: IComment.PersonJSON[];
+        comments?: IRange.JSONReference<IComment.JSON>[];
+        hyperlinks?: IRange.JSONReference<IHyperlink.JSON>[];
+        /**
+         * A generalize solution for dynamic areas.
+         * This is used for externalData
+         *
+           "C5:G10": {
+           "type": "externalData",
+           "error": false,         // Or true if the last refresh failed
+           "source": "Query1",     // Example: Type-specific info
+           "overrides": {          // Object storing user edits within the region
+             "D6": "Manual Edit",  // Key = Cell Address within region
+             "F8": 123.45          // Value = User-entered value
+           }
+        }
+        */
+        /**
+         * Either an object with RangeAddress to style id or an array of RangeCoordValue to style id.
+         */
+        directStyles?: IRange.JSONReferenceTuple<number>[];
+        merges?: IRange.Address[];
+        autoTable?: IRange.JSONReference<ITable.JSON>;
+        tables?: IRange.JSONReference<ITable.JSON>[];
+        slicers?: Record<string, ISlicer.JSON>;
+        conditionals?: IRange.JSONReference<IConditionalFormat.JSON>[];
+        validations?: IRange.JSONReference<IDataValidation.JSON>[];
+        protectedRanges?: IRange.JSONReference<IProtectedRange.JSON>[];
+        movables?: IMovable.JSON[];
+        tabColor?: string;
+        picture?: IPicture.JSON;
+        protection?: ISheetProtection.JSON;
+        view?: ISheetView.JSON;
+        pageMargins?: Partial<IPrint.PageMargin>;
+        /**
+         * If specified this indicates the entire range of the sheet.
+         */
+        entireSize?: Partial<Size>;
+    }
+}
+//# sourceMappingURL=ISheet.d.ts.map