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

package/types/src/workbook/IWorkbook.d.ts

@@ -1,69 +1,134 @@
 import { Scalar, IRange, IRangeStats, IRuntime, LocaleProfileOverrides } from '@sheetxl/primitives';
-import { FunctionProvider } from '@sheetxl/scripting';
 import { ITransaction } from '../transaction';
 import { IListener } from '../listener';
 import { IResourceCollection, IResource } from '../resource';
 import { IStringCollection } from '../string';
 import { ICalculation } from '../calculation';
-import { IScript, IModule } from '../scripting';
+import { IFontCollection } from '../font';
+import { IScript, IModule, IModuleCollection } from '../scripting';
 import { ICell } from '../cell';
-import { ICellRange, ICellRanges } from '../cellRange';
-import { IComment } from '../comment';
+import { ICellRange, ICellRanges, ICellRegions } from '../cellRange';
+import { ICommentCollection } from '../comment';
+import { IPerson, IPersonCollection } from '../person';
 import { INamedCollection } from '../named';
 import { IExternalBook, IExternalBookCollection } from '../externalBook';
+import { IPivotTable, IPivotTableCollection } from '../pivot';
 import { ITheme } from '../theme';
 import { IStyleCollection } from '../style';
-import { ISheet, ISheetCollection, ICellContainerOptions } from '../sheet';
+import { ISheet, IOpaqueSheet, IWorksheet, IWorksheetCollection, ICellContainerOptions } from '../sheet';
 import { IWorkbookView } from '../workbookView';
 import { IWorkbookProtection } from '../workbookProtection';
+import { IDocumentProperties } from '../documentProperties';
 import { IWorkbookIO } from '../io';
 /**
- * An `IWorkbook` represents a collection of {@link ISheet | sheets}, along with shared resources.
+ * An `IWorkbook` represents a collection of {@link IWorksheet | sheets}, along with shared resources.
  *
  * This interface provides methods for accessing its elements and event handling.
  *
  * @remarks
- * Most interactions with a {@link IWorkbook | workbook} or {@link ISheet | sheet} are done through a
+ * Most interactions with a {@link IWorkbook | workbook} or {@link IWorksheet | sheet} are done through a
  * {@link ICellRange | workbook range}.
  *
  * @see
- * * {@link getRange} - For interacting with cell values and formatting on a single {@link ISheet | sheet}.
- * * {@link getSheets} - For managing {@link ISheet | sheet}.
+ * * {@link getRange} - For interacting with cell values and formatting on a single {@link IWorksheet | sheet}.
+ * * {@link getWorksheets} - For managing {@link IWorksheet | sheet}.
  * * {@link getNames} - For managing items with defined names.
  */
 export interface IWorkbook extends ITransaction.ITransactional, IListener.ISource<IWorkbook, IWorkbook.IListeners> {
     /**
-     * Returns the collection of sheets within the workbook.
+     * Returns every sheet in tab order, of every kind: worksheets, chart sheets, macro sheets and
+     * dialog sheets.
+     *
+     * @param options Which sheets to return; by default the visible ones.
+     *
+     * @remarks
+     * Use {@link getWorksheets} for the grids alone.
+     */
+    getSheets(options?: IWorkbook.GetSheetsOptions): ISheet[];
+    /**
+     * Returns the sheet of any kind with the given name, or the selected sheet when no name is
+     * given.
+     *
+     * @param name The name of the sheet, ignoring case.
+     *
+     * @remarks
+     * Throws when there is no sheet with that name. Use {@link getWorksheet} when the sheet must be a
+     * grid.
+     */
+    getSheet(name?: string): ISheet;
+    /**
+     * Returns the active tab, whatever its kind.
+     *
+     * @remarks
+     * Use {@link getSelectedWorksheet} for the active grid.
+     */
+    getSelectedSheet(): ISheet;
+    /**
+     * Returns the collection of worksheets within the workbook.
+     *
+     * @remarks
+     * Only the grids. Use {@link getSheets} for every tab, chart sheets included.
      */
-    getSheets(): ISheetCollection;
+    getWorksheets(): IWorksheetCollection;
     /**
      * Adds a new sheet to the workbook.
      *
      * @remarks
-     * This is a convenience method that wraps `{@link ISheetCollection.add}`.
+     * This is a convenience method that wraps `{@link IWorksheetCollection.add}`.
      */
-    addSheet(options?: ISheetCollection.AddOptions | string | number): ISheet;
+    addWorksheet(options?: IWorksheetCollection.AddOptions | string | number): IWorksheet;
     /**
-     * Returns the sheet at the given offset.
+     * Returns the worksheet at the given offset among the worksheets.
      *
-     * @param index A 0-based index of the sheet.
+     * @param index A 0-based index into the worksheets with the given visibility. Sheets of other
+     * kinds are not counted, so this is not the tab position ({@link ISheet.getIndex}).
      * @param visibility The visibility of the sheet.
      */
-    getSheetAt(index: number, visibility?: ISheet.Visibility): ISheet;
+    getWorksheetAt(index: number, visibility?: ISheet.Visibility): IWorksheet;
     /**
-     * Returns the sheet for the given name, or the selected sheet when no name is given.
+     * Returns the worksheet for the given name, or the selected worksheet when no name is given.
      *
      * @param name The name of the sheet. Omit for the selected sheet — "the sheet", unqualified,
-     * is the one the user (or agent) is looking at. `getSelectedSheet` remains the explicit form.
+     * is the one the user (or agent) is looking at. `getSelectedWorksheet` remains the explicit form.
      * @param visibility The visibility of the sheet.
+     *
+     * @remarks
+     * Throws when the sheet is not a worksheet: a chart sheet, say, or the selected tab when that is
+     * not a worksheet. Use {@link getSheet} for any kind.
      */
-    getSheet(name?: string, visibility?: ISheet.Visibility): ISheet;
+    getWorksheet(name?: string, visibility?: ISheet.Visibility): IWorksheet;
     /**
-     * Returns the currently active sheet within the workbook.
+     * Exists to have api parity with Office Scripts.
+     *
+     * @deprecated Use {@link getWorksheetAt}.
+     * @hidden
      */
-    getSelectedSheet(): ISheet;
+    getWorksheet(index: number, visibility?: ISheet.Visibility): IWorksheet;
+    /**
+     * Returns the active worksheet, or `null` when the active tab is not a worksheet.
+     *
+     * @remarks
+     * A chart sheet (or a macro or dialog sheet) can be the active tab, and then there is no active
+     * worksheet: like VBA's `ActiveCell`, this is `null` rather than some other worksheet.
+     * {@link getSelectedSheet} returns the active tab whatever its kind.
+     */
+    getSelectedWorksheet(): IWorksheet | null;
     /**
-     * Returns the currently active sheet index within the workbook.
+     * Exists to have api parity with Google Apps Script.
+     *
+     * @deprecated Use {@link getSelectedWorksheet}.
+     * @hidden
+     */
+    getActiveSheet(): IWorksheet | null;
+    /**
+     * Exists to have api parity with Office Scripts.
+     *
+     * @deprecated Use {@link getSelectedWorksheet}.
+     * @hidden
+     */
+    getActiveWorksheet(): IWorksheet | null;
+    /**
+     * Returns the position of the active tab among the visible sheets of every kind.
      */
     getSelectedSheetIndex(): number;
     /**
@@ -114,7 +179,7 @@ export interface IWorkbook extends ITransaction.ITransactional, IListener.ISourc
      * default `'throw'` policy treats one as a fault when aggregating.
      *
      * @remarks
-     * The workbook form of {@link ISheet.getStats}: every sheet's used range contributes,
+     * The workbook form of {@link IWorksheet.getStats}: every sheet's used range contributes,
      * including hidden and very-hidden sheets — visibility is a display concern, not a data
      * one. A workbook with no used cells returns empty statistics (`getSize() === 0`),
      * never `null`.
@@ -125,16 +190,40 @@ export interface IWorkbook extends ITransaction.ITransactional, IListener.ISourc
      * {@link ICellRange.getStats}
      */
     getStats(options?: ICellRange.GetStatsOptions): IRangeStats;
+    /**
+     * Returns the regions of the `anomalies` feature across every sheet, in reading order.
+     *
+     * @example
+     * ```ts
+     * wb.getAnomalies({ checks: ['linkLabelMismatch', 'styleRole'], limit: 25 });
+     * ```
+     *
+     * @remarks
+     * The workbook form of {@link ICellRange.getAnomalies}: every sheet contributes, hidden and
+     * very hidden included, in one order, and each region's address names its sheet. The listing
+     * spans sheets, so its {@link ICellRegions.getRange} is the selected sheet's; each region is
+     * clipped against its own sheet.
+     */
+    getAnomalies(options?: ICellRange.GetAnomaliesOptions): ICellRegions;
     /**
      * Returns a range of cells for the current selection.
+     *
+     * @remarks
+     * Throws when the active tab is not a worksheet.
      */
     getSelectedRange(options?: ICellRange.GetRangeOptions): ICellRange;
     /**
      * Returns ranges of cells for the current selection.
+     *
+     * @remarks
+     * Throws when the active tab is not a worksheet.
      */
     getSelectedRanges(options?: ICellRange.GetRangeOptions): ICellRanges;
     /**
      * Returns the selected cell.
+     *
+     * @remarks
+     * Throws when the active tab is not a worksheet.
      */
     getSelectedCell(): ICell;
     /**
@@ -157,14 +246,16 @@ export interface IWorkbook extends ITransaction.ITransactional, IListener.ISourc
      */
     replace(cells: Iterator<ICell>, replace: ICell.Update | ((original: ICell) => ICell.Update), options?: IWorkbook.ReplaceOptions): IWorkbook.ReplaceResults;
     /**
-     * Returns the next sheet in the sheets collection. If the last one it will return the first.
+     * Returns the next visible sheet, of any kind, after the given tab position. If the last one it
+     * will return the first.
      *
      * @remarks
      * If there is only 1 sheet this will return the current sheet.
      */
     getNextSheet(index: number): ISheet;
     /**
-     * Returns the previous sheet in the sheets collection. If the first one it will return the last.
+     * Returns the previous visible sheet, of any kind, before the given tab position. If the first
+     * one it will return the last.
      *
      * @remarks
      * If there is only 1 sheet this will return the current sheet.
@@ -208,6 +299,62 @@ export interface IWorkbook extends ITransaction.ITransactional, IListener.ISourc
      * Returns the current shared resources.
      */
     getTransactions(): ITransaction.IStore;
+    /**
+     * Performs a set of operations as one: one commit, one undo step, one round of events.
+     *
+     * @param callback Performs the operations. Handed the commit being written and `workbook`,
+     * this workbook bound to the batch.
+     * @param options Description of the operation or additional options. Used for undo/redo and
+     * history.
+     *
+     * @remarks
+     * Work through `workbook` rather than this one. Everything reached through it - sheets, ranges,
+     * tables - is part of the batch, and a listener added through it takes part in the batch by
+     * default ({@link IListener.Options.transactional}). A range listener added through it hears each
+     * operation as it is made, rather than once when the batch lands, and what it writes joins the
+     * batch ({@link ICellRange.ListenerOptions.transactional}). A listener added any other way, while
+     * the batch is open, is outside it.
+     *
+     * The objects reached through `workbook` are not `===` to the ones reached through this workbook,
+     * though the same object always compares equal to itself. They can be passed to any method of
+     * either.
+     *
+     * A batch that performs no writes is elided: the commit id is unchanged, no events fire, and
+     * nothing is added to the undo stack or commit log.
+     *
+     * @example
+     * ```ts
+     * await workbook.doBatch(async (_commit, wb) => {
+     *   const cell = wb.getSelectedWorksheet()!.getRange('A1');
+     *   cell.addListener(() => console.log('A1 changed'));
+     *   cell.setValue(1); // logs 'A1 changed' before the next line runs
+     * });
+     * ```
+     */
+    doBatch<R = any>(callback: (commit: ITransaction.ICommit, workbook: this) => R | Promise<R>, options?: string | ITransaction.OperationOptions): R | Promise<R>;
+    /**
+     * What a commit wrote: the {@link IWorksheet.ChangeEvent}s it announced, one for each sheet and
+     * {@link IWorksheet.ChangeEvent.getKind | kind} (data, formatting, merges, spills).
+     *
+     * @param commitId The commit to describe. Omit for the current one.
+     * @returns Empty for a commit that changed no cells (a view, a name, a chart).
+     *
+     * @remarks
+     * The same events the sheets announced when the commit landed, read afterwards: the
+     * previous commit is its parent, and an undo is reported as the commit it moved to, so
+     * {@link IWorksheet.ChangeEvent.isUndo} is always `false` here.
+     *
+     * @throws If the store no longer has the commit.
+     *
+     * @example
+     * ```ts
+     * for (const change of wb.getChanges()) {
+     *   if (change.getKind() !== 'onDataChange') continue; // values and formulas, not formatting
+     *   console.log(change.getSheet().getName(), change.getRanges()?.toString());
+     * }
+     * ```
+     */
+    getChanges(commitId?: string): IWorksheet.ChangeEvent[];
     /**
      * Get the current theme.
      */
@@ -230,19 +377,22 @@ export interface IWorkbook extends ITransaction.ITransactional, IListener.ISourc
      *
      * @remarks
      * A workbook has no intrinsic name (like Excel: a workbook's name *is* its file name). Display
-     * fallbacks (a localized "Untitled") are a UI concern. Renaming is an origin/document-level
-     * operation (see `WorkbookDocument.setName`), never a model edit — it is not undoable.
+     * fallbacks (a localized "Untitled") are a UI concern. Renaming is an origin-level operation
+     * (see {@link IWorkbookIO.Origin.setName}), never a model edit — it is not undoable.
      */
     getName(): string | null;
     /**
-     * Returns the workbook's {@link IWorkbookIO.Origin | origin} — the virtual file handle it maps to.
+     * Returns the workbook's {@link IWorkbookIO.Origin | origin} — the file handle it lives in.
      *
      * @remarks
-     * Read-only and always present: the *reference* is stable for the workbook's lifetime (a new
-     * in-memory workbook holds an *unbound* origin — `getPath()` `null`). The origin **object** is
-     * updated in place by its IO/store owner (e.g. a first save resolving a destination), like the
-     * DOM's `document.URL` — the model itself never mutates it, and it is not part of the persisted
-     * document ({@link toJSON}); a copy mints a fresh unbound origin.
+     * Always present: a new in-memory workbook holds an *unbound* origin (`getPath()` `null`). Like
+     * the DOM's `document.URL`, *which* origin can change — a save that resolves a new destination (a
+     * first save, a Save As) moves the workbook to the file it wrote, firing
+     * {@link IWorkbook.Events.onOriginChange | onOriginChange}. So read it when needed rather than
+     * holding it; to follow the current file, listen for `onOriginChange`.
+     *
+     * The model never mutates its origin, and the origin is not part of the persisted document
+     * ({@link toJSON}); a copy mints a fresh unbound origin.
      */
     getOrigin(): IWorkbookIO.Origin;
     /**
@@ -332,6 +482,22 @@ export interface IWorkbook extends ITransaction.ITransactional, IListener.ISourc
      * Returns the protection object for the workbook.
      */
     getProtection(): IWorkbookProtection;
+    /**
+     * The workbook's document properties: author, title, company and the like.
+     */
+    getProperties(): IDocumentProperties;
+    /**
+     * The workbook's VBA code name — conventionally `ThisWorkbook` — or `null` if it has none.
+     *
+     * @defaultValue null
+     *
+     * @remarks
+     * The workbook-level counterpart to {@link IWorksheet.getCodeName}: the identifier VBA binds the
+     * workbook's own document module through, where workbook event handlers such as `Workbook_Open`
+     * live. Like a sheet's, it is carried from the file and **read-only** — see
+     * {@link IWorksheet.getCodeName} for why SheetXL never mints one.
+     */
+    getCodeName(): string | null;
     /**
      * **Every** {@link INamed} in the workbook — global names, every sheet's scoped names, and every
      * table — sorted by type then by name.
@@ -339,7 +505,7 @@ export interface IWorkbook extends ITransaction.ITransactional, IListener.ISourc
      * @remarks
      * The name-manager view: what EXISTS, not what any one sheet can see. A global name and a
      * sheet-scoped name that share a name are two items here and both are returned; ask
-     * {@link ISheet.getNames} for the one a formula on that sheet would resolve to.
+     * {@link IWorksheet.getNames} for the one a formula on that sheet would resolve to.
      */
     getNames(): INamedCollection;
     /**
@@ -347,28 +513,78 @@ export interface IWorkbook extends ITransaction.ITransactional, IListener.ISourc
      * as `[n]Sheet1!$A$1`. In `[n]` order.
      *
      * @remarks
-     * Read-only for now: this phase reads and models the parts, nothing more. Formula text still
-     * carries `[n]` as opaque characters — this collection is not yet wired to it.
+     * A link is made by a formula — typing `'C:\path\[Budget.xlsx]Sheet1'!A1` adds a book here —
+     * and removed by breaking it ({@link IExternalBookCollection.breakLink}). Each book lists the
+     * formulas that cite it ({@link IExternalBook.getDependents}). The engine's collection, so
+     * available once the calculation is constructed, which is before any sheet is.
      */
     getExternalBooks(): IExternalBookCollection;
+    /**
+     * Returns the pivot tables on every sheet, in sheet order.
+     *
+     * @remarks
+     * A view over each sheet's {@link IWorksheet.getPivotTables}; `getByName` searches them all.
+     * Read-only for now: each table is carried as it was read and written back unchanged.
+     */
+    getPivotTables(): IPivotTableCollection;
+    /**
+     * Returns the comments and notes on every sheet, in sheet order.
+     *
+     * @remarks
+     * A view over each sheet's {@link IWorksheet.getComments}; `getById` and `getByReplyId` search
+     * them all. A comment is added on a sheet's collection.
+     */
+    getComments(): ICommentCollection;
+    /**
+     * Returns the people the workbook knows: the authors of its comments.
+     *
+     * @see {@link IComment.getAuthor}
+     */
+    getPeople(): IPersonCollection;
+    /**
+     * When the cached values of {@link getExternalBooks} should be re-read from their sources on
+     * open, or `null` where the source file said nothing (which Excel reads as `userSet`).
+     *
+     * @remarks
+     * Carried, not obeyed — SheetXL never refreshes a link, so every mode behaves as `never` until
+     * a resolver exists. Round-trips as `workbookPr@updateLinks`.
+     *
+     * The mode is {@link IExternalBookCollection.UpdateLinks}: it governs the books as a set, and no
+     * single book has one. It is read and written HERE because it is a property of the workbook in
+     * both Excel's object model and the file, not of the collection the books live in.
+     */
+    getUpdateLinks(): IExternalBookCollection.UpdateLinks | null;
+    /**
+     * Sets {@link getUpdateLinks}. `null` writes no attribute at all.
+     */
+    setUpdateLinks(updateLinks: IExternalBookCollection.UpdateLinks | null): this;
     /**
      * Returns the {@link ICalculation} for the workbook.
      */
     getCalculation(): ICalculation;
+    /**
+     * Returns the {@link IFontCollection} the workbook measures text with.
+     *
+     * @remarks
+     * Fonts are shared: every workbook returns the same collection, so a face loaded for one is
+     * loaded for all.
+     */
+    getFonts(): IFontCollection;
     /**
      * Parses a formula expression and returns a *transient* formula object.
      *
      * @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)`.
+     * This is a convenience method for `getCalculation().createFormula(expression, coords, options)`.
      * A bare reference (`A2`) resolves against the active cell's sheet; use
-     * {@link ISheet.createFormula} to anchor against a specific sheet.
+     * {@link IWorksheet.createFormula} to anchor against a specific sheet.
      *
      * @see {@link ICalculation.createFormula}
      */
-    createFormula(expression: string, coords?: Partial<IRange.CellCoords>): ICalculation.IFormula;
+    createFormula(expression: string, coords?: Partial<IRange.CellCoords>, options?: ICalculation.CreateFormulaOptions): ICalculation.IFormula;
     /**
      * Evaluates a formula in the context of the sheet and returns the resulting value.
      *
@@ -378,24 +594,60 @@ export interface IWorkbook extends ITransaction.ITransactional, IListener.ISourc
      * @remarks
      * This is similar convenience method for `getCalculation().createFormula(expression).evaluate(options)`.
      */
-    evaluate(formula: string, options?: number | ICalculation.EvaluateOptions & Partial<IRange.CellCoords>): Promise<Scalar | IRange>;
+    evaluate(formula: string, options?: number | ICalculation.EvaluateOptions & Partial<IRange.CellCoords> & ICalculation.CreateFormulaOptions): Promise<Scalar | IRange>;
     /**
      * Returns when all calculations are complete and there are no pending calculations.
      *
      * @remarks
-     * * This is a convenience method `getCalculation().ready()`.
+     * * Also waits for the load-time start: the pass {@link ICellContainerOptions.calcOnLoad} asks
+     *   for and the workbook's scripts. 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.
      */
     whenCalculationReady(): Promise<ICalculation.Status>;
+    /**
+     * Returns when every font the workbook measures with has loaded and every autofit that was
+     * taken with a stand-in meanwhile has been taken again.
+     *
+     * @remarks
+     * Measuring never waits: a style naming a face not yet loaded measures with a related or
+     * built-in one and the lookup starts the load, the way a browser paints with a fallback until
+     * a web font arrives. This is the point after which sizes are final. Fonts are shared, so this
+     * also waits for faces other workbooks started loading; a load that fails leaves its stand-in
+     * and still settles.
+     */
+    whenFontsReady(): Promise<void>;
+    /**
+     * Returns when the workbook is settled: {@link whenCalculationReady} and {@link whenFontsReady}
+     * both hold.
+     */
+    whenReady(): Promise<void>;
     /**
      * Returns any user defined functions stored with the workbook.
      */
     getScripts(): IScript;
+    /**
+     * Returns the modules this workbook owns.
+     *
+     * @remarks
+     * The workbook half of {@link IWorksheet.getModules}, and the same collection
+     * `getScripts().getModules()` answers with — modules belong to the model, whereas
+     * {@link IScript} is what runs them.
+     *
+     * Holds the globally scoped modules, whose functions ARE in the formula namespace, and the
+     * workbook-scoped ones, whose functions are not ({@link IModule.getScope}). A sheet's modules
+     * are not in here at all; they hang off the sheet.
+     *
+     * Like every module collection, this filters to TypeScript unless asked otherwise; imported VBA
+     * is read with `getItems({ language: 'vba' })`.
+     */
+    getModules(): IModuleCollection;
     /**
      * Serialize the workbook to a JSON.
      *
      * @param options Options to control the JSON output.
      */
-    toJSON(options?: ISheet.ToJSONOptions): Promise<IWorkbook.JSON>;
+    toJSON(options?: IWorksheet.ToJSONOptions): Promise<IWorkbook.JSON>;
     /**
      * Returns any custom workbook options that are provided in constructor.
      */
@@ -479,6 +731,18 @@ export declare namespace IWorkbook {
          * Called when the workbook theme has changed.
          */
         onThemeChange?(source: IWorkbook): void;
+        /**
+         * Called when a workbook setting that governs how values are PRESENTED has changed - the
+         * locale, its overrides, or the date system.
+         *
+         * @remarks
+         * Nothing a cell holds has moved; what it paints for what it holds has. A consumer that has
+         * measured rendered text - a fitted column width, a cached layout - has to re-derive it.
+         *
+         * The active UI language does the same thing from outside the workbook, and is announced by
+         * {@link DefaultLanguagePackService} rather than here.
+         */
+        onRegionalChange?(source: IWorkbook): void;
         /**
          * Called when the workbook protection has changed.
          *
@@ -511,10 +775,20 @@ export declare namespace IWorkbook {
          */
         onViewChange?(source: IWorkbook): void;
         /**
-         * Called when the display name changes — a convenience proxy of the origin's `onChange`
-         * (non-transactional; renames are not model edits and never enter the undo stack).
+         * Called when the display name changes — a rename of the origin, or a move to a new one (see
+         * {@link onOriginChange}). Non-transactional; renames are not model edits and never enter the
+         * undo stack.
          */
         onNameChange?(source: IWorkbook): void;
+        /**
+         * Called when the workbook moves to a different {@link IWorkbook.getOrigin | origin} — a save
+         * that resolved a new destination (a first save, a Save As). Non-transactional.
+         *
+         * @remarks
+         * Changes *within* the current origin (its size after a save, a rename) are that origin's own
+         * `onChange`; a listener on the old origin hears nothing further about this workbook.
+         */
+        onOriginChange?(source: IWorkbook): void;
         /**
          * Called when the scripts associated with the workbook have change.
          */
@@ -582,21 +856,54 @@ export declare namespace IWorkbook {
         last: ICell | null;
     }
     /**
-     * Used for persisting metadata about a `ISheet`.
+     * Options for {@link IWorkbook.getSheets}.
+     */
+    interface GetSheetsOptions {
+        /**
+         * The least visible sheets to include: `Hidden` includes the hidden sheets, `VeryHidden` every
+         * sheet.
+         *
+         * @defaultValue ISheet.Visibility.Visible
+         */
+        visibility?: ISheet.Visibility;
+    }
+    /**
+     * Used for persisting an {@link ISheet}: its tab, and its body as {@link SheetRefJSON.kind} says.
+     *
+     * @typeParam T The body: {@link IWorksheet.JSON} for a worksheet, {@link IOpaqueSheet.JSON} for
+     * the other kinds.
      */
-    interface SheetRefJSON {
+    interface SheetRefJSON<T extends ISheet.JSON = IWorksheet.JSON | IOpaqueSheet.JSON> {
         /**
          * A unique name for the sheet.
          */
         name: string;
+        /**
+         * The origin format's own identifier for this sheet, preserved so a round trip does not
+         * renumber it.
+         *
+         * @remarks
+         * Interop only — nothing in the model reads it and nothing references it by value. It is
+         * arbitrary and sparse (a workbook's edit history leaves gaps, so `Jan=3, Feb=28, Mar=29` is
+         * ordinary) and is **not** the sheet's position: `localSheetId` on a defined name is a
+         * position and is resolved separately. Absent for a sheet that was never loaded from a file;
+         * a writer assigns one in that case.
+         */
+        sheetId?: number;
         /**
          * @defaultValue ISheet.Visibility.Visible
          */
         visibility?: ISheet.Visibility;
         /**
-         * The actual sheet.
+         * What the sheet holds, and so what {@link sheet} is.
+         *
+         * @defaultValue ISheet.Kind.Worksheet
+         */
+        kind?: ISheet.Kind;
+        /**
+         * The sheet's body.
          */
-        sheet?: ISheet.JSON;
+        sheet?: T;
     }
     /**
      * JSON representation of an `IWorkbook` used for serialization and deserialization.
@@ -606,7 +913,12 @@ export declare namespace IWorkbook {
         styles?: IStyleCollection.JSON;
         resources?: IResource.JSON[];
         strings?: string[];
-        people?: IComment.PersonJSON[];
+        /**
+         * The people the workbook knows.
+         *
+         * @see {@link IWorkbook.getPeople}
+         */
+        people?: IPerson.JSON[];
         view?: IWorkbookView.JSON;
         theme?: ITheme.JSON;
         names?: INamedCollection.JSON;
@@ -616,10 +928,42 @@ export declare namespace IWorkbook {
          * position still counts, only the content does not.
          */
         externalBooks?: (IExternalBook.JSON | null)[];
-        scripts?: Record<string, IModule.JSON>;
+        /**
+         * What should happen to the cached values of {@link externalBooks} when the workbook is opened.
+         *
+         * @remarks
+         * Carried, not obeyed: SheetXL never refreshes a link, so every mode behaves as `never` today.
+         * Absent when the source said nothing, which Excel reads as `userSet`.
+         */
+        updateLinks?: IExternalBookCollection.UpdateLinks;
+        /**
+         * The workbook's pivot caches — the source snapshots its pivot tables summarize, each shared
+         * by every table that references its id.
+         *
+         * @remarks
+         * Carried, not modeled — see {@link IPivotTable.CacheJSON}. The tables that summarize a cache
+         * are the modeled side; a table names its cache by {@link IPivotTable.getCacheId}.
+         */
+        pivotCaches?: IPivotTable.CacheJSON[];
+        /**
+         * The workbook's own modules, keyed by module name.
+         *
+         * @see {@link IWorkbook.getModules}
+         */
+        modules?: Record<string, IModule.JSON>;
         calc?: ICalculation.JSON;
         protection?: IWorkbookProtection.JSON;
+        /**
+         * @see {@link IWorkbook.getProperties}
+         */
+        properties?: IDocumentProperties.JSON;
         date1904?: boolean;
+        /**
+         * The workbook's VBA code name. Absent when it has none.
+         *
+         * @see {@link IWorkbook.getCodeName}
+         */
+        codeName?: string;
         /**
          * The regional locale as a BCP 47 tag, e.g. `de-DE`.
          *
@@ -639,12 +983,12 @@ export declare namespace IWorkbook {
     /**
      * Callback to allow for custom `ISheets`. The Workbook provides a default implementation.
      */
-    interface CreateSheetCallback {
+    interface CreateWorksheetCallback {
         (
         /**
          * Options used for creating the Sheet instance.
          */
-        options: ISheet.ConstructorOptions, 
+        options: IWorksheet.ConstructorOptions, 
         /**
          * The name of the new  sheet.
          */
@@ -656,33 +1000,16 @@ export declare namespace IWorkbook {
         /**
          * @defaultValue ISheet.Visibility.Visible
          */
-        visibility: ISheet.Visibility): ISheet;
+        visibility: ISheet.Visibility): IWorksheet;
     }
     /**
      * Options available when creating an IWorkbook.
      */
     interface ConstructorOptions extends ICellContainerOptions {
-        /**
-         * Additional custom formula function providers, bound after the built-ins (so they override
-         * built-ins on name collision). Each provider is the `initialize` binder produced by the
-         * FormulaCompiler (`@sheetxl/scripting`) for a folder of formula sources.
-         *
-         * @see {@link FunctionProvider}
-         */
-        functions?: readonly FunctionProvider[];
-        /**
-         * A structural transform applied once to each formula parsed from `json` — cell formulas
-         * AND defined names. This is the READ half of the format-dialect hook: a format reader
-         * (e.g. xlsx) supplies its legacy unwrap here; it is a LOAD-time pass only and is never
-         * applied to text typed or set after construction.
-         *
-         * @see {@link ICalculation.FormulaTransform}
-         */
-        formulaTransform?: ICalculation.FormulaTransform;
         /**
          * Hook to allow for custom sheet creation.
          */
-        createSheetCallback?: CreateSheetCallback;
+        createWorksheetCallback?: CreateWorksheetCallback;
         /**
          * Returns a human readable sheet name given a 0-based index.
          *
@@ -695,9 +1022,13 @@ export declare namespace IWorkbook {
          * shorthand for an unbound origin with that display name.
          *
          * @remarks
-         * The reference is stable for the workbook's lifetime; see {@link IWorkbook.getOrigin}.
+         * The initial origin; a save that resolves a new destination replaces it (see
+         * {@link IWorkbook.getOrigin}).
+         *
+         * A host with its own save flow can pass an {@link IWorkbookIO.OriginProvider} instead and move
+         * it itself; the IO layer then leaves the workbook's origin to that host.
          */
-        origin?: IWorkbookIO.Origin | string | null;
+        origin?: IWorkbookIO.Origin | IWorkbookIO.OriginProvider | string | null;
         /**
          * A theme for the workbook.
          */