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

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

@@ -1,408 +1,44 @@
-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 { IPrint } from '../print';
-import { IColor } from '../color';
 import { IListener } from '../listener';
-import { IHyperlink } from '../hyperlink';
-import { IPicture } from '../picture';
-import { ICell, ICellHeader } from '../cell';
-import { ICellRange, ICellRanges, ICellRegions } from '../cellRange';
-import { IRangeSelection } from '../selection';
-import { IStyleCollection } from '../style';
-import { IStringCollection } from '../string';
-import { IResource, IResourceCollection } from '../resource';
-import { IMovable, IMovableCollection } from '../movable';
-import { IPivotTable, IPivotTableCollection } from '../pivot';
-import { IComment, ICommentCollection } from '../comment';
-import { ITable, ITableCollection } from '../table';
-import { IDataValidation, IDataValidationCollection } from '../dataValidation';
-import { IConditionalFormat, IConditionalFormatCollection } from '../conditionalFormat';
-import { IProtectedRange, IProtectedRangeCollection } from '../protectedRange';
-import { IModule, IModuleCollection } from '../scripting';
-import { IChartCollection } from '../chart';
-import { INamedCollection } from '../named';
-import { ICalculation } from '../calculation';
-import { ISheetView } from '../sheetView';
-import { ISheetHeader } from '../sheetHeader';
-import { ISheetProtection } from '../sheetProtection';
-import { IOutline } from '../outline';
-import { ICellContainerOptions } from './ICellContainerOptions';
+import { IColor } from '../color';
+import { IWorkbook } from '../workbook';
 /**
- * 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}.
+ * A tab in a {@link IWorkbook | workbook}: a {@link IWorksheet | worksheet}, or one of the sheet kinds
+ * that hold no cells.
  *
  * @remarks
- * While a {@link ISheet | sheet} can be used stand-alone it is typically used within the context of a {@link IWorkbook | workbook}.
+ * Every kind shares one name space, one tab order and one set of visibility rules, so the members
+ * here apply to all of them. What a sheet holds depends on its {@link getKind | kind}:
+ *
+ * * `'worksheet'` is the grid, {@link IWorksheet}.
+ * * `'chart'` is a chart sheet: one chart filling the tab.
+ * * `'macro'` is an Excel 4.0 macro sheet.
+ * * `'dialog'` is an Excel 5 dialog sheet.
  *
- * ### **Key Methods**
+ * The last three are {@link IOpaqueSheet | opaque}: they are carried as read and written back
+ * unchanged.
  *
- * * {@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`.
+ * Use {@link IWorkbook.getSheets} for every tab and {@link IWorkbook.getWorksheets} for the grids.
  */
-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 the comments and notes on this sheet.
-     *
-     * @remarks
-     * One per cell. The workbook's {@link IWorkbook.getComments} walks every sheet's.
-     */
-    getComments(): ICommentCollection;
-    /**
-     * Returns a collection of movables that are embedded in this sheet.
-     */
-    getMovables(): IMovableCollection;
-    /**
-     * Returns the charts on this sheet.
-     *
-     * @remarks
-     * A view over {@link ISheet.getMovables}: every chart is the content of a movable, which is what
-     * places and names it. Read-only for now — a chart is added by adding a movable with chart
-     * content.
-     */
-    getCharts(): IChartCollection;
-    /**
-     * 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;
-    /**
-     * The sheet's VBA code name, or `null` if it has none.
-     *
-     * @defaultValue null
-     *
-     * @remarks
-     * The identifier VBA binds a sheet through — `Sheet1.Range("A1")` in a macro resolves by code
-     * name, never by tab name. It is a **second, independent identity** for the sheet: renaming the
-     * tab does not change it, and it is not the sheet's position. Excel's default happens to look
-     * positional (`Sheet1`, `Sheet2`, …) but drifts from position the moment sheets are reordered,
-     * inserted or deleted, so it can only be carried — never derived.
-     *
-     * Present on any workbook that has, or has ever had, a VBA project: it survives the project
-     * being stripped, so an `.xlsx` saved down from an `.xlsm` still carries code names. A workbook
-     * that never had one has none, and this is `null` throughout.
-     *
-     * **Read-only.** SheetXL preserves what a file declared and never mints one — a code name is
-     * assigned by the VBA editor, and inventing one would create a binding target no macro refers
-     * to. There is deliberately no `setCodeName`.
-     */
-    getCodeName(): string | null;
-    /**
-     * The row and column groups on this sheet, and how they are laid out.
-     */
-    getOutline(): IOutline;
-    /**
-     * Whether conditional formats on this sheet are recalculated as the sheet changes.
-     *
-     * @defaultValue true
-     *
-     * @remarks
-     * Excel exposes this only to VBA (`Worksheet.EnableFormatConditionsCalculation`). It is carried
-     * so a workbook that turned it off keeps it off when saved; SheetXL still evaluates conditional
-     * formats either way.
-     */
-    isConditionalFormatCalculationEnabled(): boolean;
-    /**
-     * Returns the modules this sheet owns.
-     *
-     * @remarks
-     * A sheet's modules are stored by the sheet rather than tagged with its name, so the state a
-     * tag would allow — a module left behind pointing at a sheet that no longer exists — cannot
-     * occur: delete the sheet and its modules go with it, which is also what Excel does.
-     *
-     * These modules are scoped to the sheet ({@link IModule.getScope}), and scope is a visibility
-     * rule: a function declared here is **not** callable from a cell formula, on this sheet or any
-     * other. Only globally scoped modules contribute to the formula namespace.
-     *
-     * The VBA document module for this sheet lands here, joined to it by
-     * {@link ISheet.getCodeName} — for a document module the module name *is* the code name.
-     *
-     * As with {@link IWorkbook.getScripts}, the collection filters to TypeScript unless asked
-     * otherwise; imported VBA is read with `getItems({ language: 'vba' })`.
-     */
-    getModules(): IModuleCollection;
+export interface ISheet extends IListener.ISource<ISheet, ISheet.IListeners> {
     /**
-     * Returns the sheet protection.
+     * What the sheet holds.
      */
-    getProtection(): ISheetProtection;
+    getKind(): ISheet.Kind;
     /**
-     * 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.
+     * The sheet's id: what formulas and operations identify it by. Unique among all in-memory sheets.
      */
-    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
-     * @param options How the update is read. See {@link ICell.CreateCellOptions}.
-     * @returns A detached ICell
-     *
-     * @remarks
-     * * Useful for previewing values such as tooltip, or what typed text would be entered as.
-     * * 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, options?: ICell.CreateCellOptions): 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.
-     * @param options Optional parse options; the expression is storage text unless `target` is `'display'`.
-     *
-     * @remarks
-     * This is a convenience method for `getCalculation().createFormula(expression, coords, options)`;
-     * 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>, options?: ICalculation.CreateFormulaOptions): ICalculation.IFormula;
-    /**
-     * Add Listeners.
-     *
-     * @see
-     * {@link IListener.ISource.addListeners}
-     */
-    addListeners(listeners: ISheet.IListeners, options?: IListener.Options): IListener.Remove;
+    getId(): string;
     /**
      * Returns the display name for the sheet.
      */
     getName(): string;
     /**
      * Set the display name for the sheet.
+     *
+     * @remarks
+     * Names are unique across every kind of sheet, ignoring case.
      */
     setName(name: string, options?: ITransaction.OperationOptions): this;
     /**
@@ -413,78 +49,41 @@ export interface ISheet extends ITransaction.ITransactional, IListener.ISource<I
      * 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.
+     * The last visible sheet, of any kind, cannot be hidden.
      */
-    getNames(): INamedCollection;
+    setVisibility(visibility?: ISheet.Visibility | boolean, options?: ITransaction.OperationOptions): ISheet;
     /**
-     * Returns the {@link ICalculation} **anchored to this sheet**.
+     * Returns the position of the sheet among every sheet in its workbook, hidden ones and every
+     * kind included.
      *
      * @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).
+     * Will return -1 if not in a workbook.
      */
-    getCalculation(): ICalculation;
+    getIndex(): number;
     /**
-     * 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.
+     * Moves the sheet in the tab order.
      *
      * @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.
+     * This is zero-based.
      */
-    calculate(full?: boolean): Promise<ICalculation.Status>;
+    setIndex(index: number): this;
     /**
-     * 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.
+     * Return a custom color or `null` if no custom color has been set.
      *
-     * @remarks
-     * This is similar convenience method for `getCalculation().createFormula(expression).evaluate(options)`.
+     * @defaultValue null
      */
-    evaluate(formula: string, options?: ICalculation.EvaluateOptions & Partial<IRange.CellCoords> & ICalculation.CreateFormulaOptions): Promise<Scalar | IRange>;
+    getTabColor(): IColor;
     /**
-     * Returns when all calculations are complete and there are no pending calculations.
+     * Set the tab color for the sheet.
+     *
+     * @param color The color
      *
      * @remarks
-     * * Also waits for the load-time start: the pass {@link ICellContainerOptions.calcOnLoad} asks
-     *   for. This is the settle point after constructing from JSON.
-     * * Otherwise a convenience method for `getCalculation().ready()`, which starts the engine if
-     *   it has not been started.
+     * If set to `null` the color will revert to the default.
      */
-    whenCalculationReady(): Promise<ICalculation.Status>;
+    setTabColor(color: IColor | string | null): this;
     /**
      * Returns the {@link IWorkbook} for the sheet.
      *
@@ -493,83 +92,30 @@ export interface ISheet extends ITransaction.ITransactional, IListener.ISource<I
      */
     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`.
+     * Make the sheet the active tab.
      */
     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.
+     * Removes the sheet from its workbook.
      */
-    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;
-    /**
-     * Returns the pivot tables laid out on this sheet, in the order they were read.
-     *
-     * @remarks
-     * Read-only for now: each table is carried as it was read and written back unchanged. The
-     * workbook's {@link IWorkbook.getPivotTables} walks every sheet's.
-     */
-    getPivotTables(): IPivotTableCollection;
+    delete(): void;
     /**
-     * Set the picture interface for the entire sheet.
-     * @param picture The picture interface to set for the sheet, or null to remove it.
+     * Returns if the sheet has been deleted from its workbook.
      */
-    setPicture(picture: string | IResource | IResourceCollection.AddOptions | null, options?: ITransaction.OperationOptions): this;
+    isDeleted(): boolean;
     /**
-     * Returns a JSON representation of the sheet.
+     * Add Listeners.
      *
-     * @param options Options to control the JSON output.
+     * @see
+     * {@link IListener.ISource.addListeners}
      */
-    toJSON(options?: ISheet.ToJSONOptions): Promise<ISheet.JSON>;
+    addListeners(listeners: ISheet.IListeners, options?: IListener.Options): IListener.Remove;
     /**
      * 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
+     * Called by the workbook when it is closed. This is different than {@link delete}, which removes
+     * the sheet from the workbook.
      */
     close(): void;
     /**
@@ -587,47 +133,30 @@ export interface ISheet extends ITransaction.ITransactional, IListener.ISource<I
  * ### **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)
-     * ```
+     * What a sheet holds.
      */
-    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[];
+    const Kind: {
+        /**
+         * A grid of cells. See {@link IWorksheet}.
+         */
+        readonly Worksheet: "worksheet";
+        /**
+         * A chart filling the tab.
+         */
+        readonly Chart: "chart";
+        /**
+         * An Excel 4.0 macro sheet.
+         */
+        readonly Macro: "macro";
+        /**
+         * An Excel 5 dialog sheet.
+         */
+        readonly Dialog: "dialog";
+    };
+    type Kind = typeof Kind[keyof typeof Kind];
     /**
      * Indicates how a sheet should be available to the user.
      */
@@ -650,256 +179,34 @@ export declare namespace ISheet {
     };
     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}.
+     * Events for {@link ISheet}, shared by every kind.
      */
     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.
+         * Called when the 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 a comment is added, removed, edited, resolved, replied to or re-anchored.
-         *
-         * @remarks
-         * Always accompanied by the coarse {@link onStyleChange}, since a cell paints its comment
-         * indicator.
-         */
-        onCommentsChange?(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.
+         * Called when the name changes.
          */
-        onLoad?(source: ISheet): void;
+        onNameChange?(source: ISheet): void;
         /**
-         * Called before load. If any exception is thrown this
-         * exception will be returned to the client and delete will be aborted.
+         * Called when the visibility changes.
          */
-        onBeforeSave?(source: ISheet): Promise<void> | void;
+        onVisibilityChange?(source: ISheet): void;
         /**
-         * Called after save.
+         * Called when the position in the tab order changes.
          */
-        onSave?(source: ISheet, json: ISheet.JSON): void;
+        onIndexChange?(source: ISheet): void;
         /**
-         * Called before delete. If any exception is thrown the
-         * exception will be returned to the client and delete will be aborted.
+         * Called before the sheet is deleted. If any exception is thrown the delete is aborted and the
+         * exception is returned to the caller.
          */
         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.
          */
@@ -907,315 +214,11 @@ export declare namespace ISheet {
     }
     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;
-        /**
-         * How resources — images and the other binaries the sheet references — are written.
-         *
-         * * `'embed'` serializes each one into the JSON, base64 encoded.
-         * * `'ignore'` writes every id as `0` and no resources.
-         * * An {@link IResource.Writer} puts each one wherever the caller wants and records what it
-         *   returns, so resources can be stored outside the JSON — uploaded and referenced by `uri`,
-         *   or emitted as parts of another format and referenced by id alone.
-         *
-         * @defaultValue 'embed'
-         */
-        resources?: 'embed' | 'ignore' | IResource.Writer;
-        /**
-         * 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;
-    }
-    /**
-     * 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;
-        /**
-         * The sheet's id ({@link ISheet.getId}): what formulas and operations (copy/paste) identify it
-         * by. Must be unique among all in-memory sheets.
-         *
-         * @returns The id. If not provided a new one is made.
-         * @remarks
-         * Not saved as part of the {@link ISheet.JSON} persisted model. A container that names its
-         * sheets before it builds them (a workbook loading its sheets) supplies it.
-         */
-        uid?: () => string;
-        /**
-         * Initial JSON.
-         */
-        json?: ISheet.JSON;
-    }
-    /**
-     * 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;
-        rowBreaks?: IPrint.Break[];
-        colBreaks?: IPrint.Break[];
-        phoneticPr?: {
-            alignment?: string;
-            fontId?: number;
-            type: string;
-        };
-    }
-    /**
-     * A drawing whose shapes are described in the origin format's own legacy vector markup rather
-     * than through {@link IMovable | movables}.
-     *
-     * @remarks
-     * A carrier, not a concept: what a spreadsheet keeps out of its main drawing — the box a note is
-     * displayed in, a form control's shape, and the pictures placed in a header or footer — held as
-     * one unit and put back on save, so a document that has them survives a round trip. Each piece
-     * folds into its own model as that lands (the note's box onto the note, the control's shape onto
-     * the control, the pictures onto the print header), and the carrier goes with the last of them.
-     *
-     * The markup is opaque: it is held as it was read and replayed unchanged, which also means the
-     * positions in it do not follow rows and columns that are inserted or deleted. Its images are
-     * carried by {@link IResource} id, each under the id the markup references it by.
-     */
-    interface LegacyDrawingJSON {
-        xml: string;
-        images?: {
-            id: string;
-            resId: number;
-        }[];
-    }
-    /**
-     * JSON representation of an `ISheet` used for serialization and deserialization.
+     * What the JSON of every kind of sheet has. Each kind adds its own body.
      */
     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;
-        /**
-         * 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;
-        styles?: IStyleCollection.JSON;
-        resources?: IResource.JSON[];
-        strings?: string[];
-        /**
-         * Modules owned by this sheet, keyed by module name.
-         *
-         * @see {@link ISheet.getModules}
-         */
-        modules?: Record<string, IModule.JSON>;
-        /**
-         * The comments and notes, one per cell, each thread with its replies.
-         *
-         * @see {@link ISheet.getComments}
-         */
-        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>[];
-        conditionals?: IRange.JSONReference<IConditionalFormat.JSON>[];
-        validations?: IRange.JSONReference<IDataValidation.JSON>[];
-        protectedRanges?: IRange.JSONReference<IProtectedRange.JSON>[];
-        movables?: IMovable.JSON[];
         tabColor?: string;
-        /**
-         * The sheet's VBA code name. Absent when it has none.
-         *
-         * @see {@link ISheet.getCodeName}
-         */
-        codeName?: string;
-        /**
-         * The outline settings that differ from their defaults.
-         *
-         * @see {@link ISheet.getOutline}
-         */
-        outline?: IOutline.JSON;
-        /**
-         * Present, as `false`, only when conditional format calculation is turned off.
-         *
-         * @see {@link ISheet.isConditionalFormatCalculationEnabled}
-         */
-        conditionalFormatCalculation?: boolean;
-        /**
-         * The sheet's picture.
-         */
-        picture?: IPicture.JSON;
-        /**
-         * The sheet's legacy drawing: note boxes and form control shapes.
-         *
-         * @see {@link ISheet.LegacyDrawingJSON}
-         */
-        legacyDrawing?: LegacyDrawingJSON;
-        /**
-         * The legacy drawing for the sheet's header and footer, which holds their pictures.
-         *
-         * @see {@link ISheet.LegacyDrawingJSON}
-         */
-        legacyDrawingHF?: LegacyDrawingJSON;
-        /**
-         * The sheet's pivot tables.
-         *
-         * @see {@link ISheet.getPivotTables}
-         */
-        pivotTables?: IPivotTable.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