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

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

@@ -1,16 +1,18 @@
 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 { 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';
@@ -230,19 +232,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 +337,18 @@ export interface IWorkbook extends ITransaction.ITransactional, IListener.ISourc
      * Returns the protection object for the workbook.
      */
     getProtection(): IWorkbookProtection;
+    /**
+     * The workbook's VBA code name — conventionally `ThisWorkbook` — or `null` if it has none.
+     *
+     * @defaultValue null
+     *
+     * @remarks
+     * The workbook-level counterpart to {@link ISheet.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 ISheet.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.
@@ -347,28 +364,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 ISheet.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 ISheet.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.
      *
      * @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,18 +445,37 @@ 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 any user defined functions stored with the workbook.
      */
     getScripts(): IScript;
+    /**
+     * Returns the modules this workbook owns.
+     *
+     * @remarks
+     * The workbook half of {@link ISheet.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.
      *
@@ -479,6 +565,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 +609,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.
          */
@@ -589,6 +697,18 @@ export declare namespace IWorkbook {
          * 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
          */
@@ -606,7 +726,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 +741,38 @@ 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;
         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`.
          *
@@ -662,23 +815,6 @@ export declare namespace IWorkbook {
      * 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.
          */
@@ -695,9 +831,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.
          */

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

@@ -4,8 +4,13 @@ import { IListener } from '../listener';
 import { INamedCollection } from '../named';
 import { IExternalBookCollection } from '../externalBook';
 import { NamedTableSource } from '../table/_NamedTableSource';
+import { IPivotTableCollection } from '../pivot';
+import { PivotCache } from '../pivot/PivotCache';
+import { ICommentCollection } from '../comment';
+import { IPersonCollection } from '../person';
 import { ICalculation } from '../calculation';
-import { IScript, IModule } from '../scripting';
+import { IFontCollection } from '../font/IFontCollection';
+import { IScript, IModule, IModuleCollection } from '../scripting';
 import { IResourceCollection } from '../resource';
 import { IStringCollection } from '../string';
 import { ITheme } from '../theme';
@@ -17,7 +22,7 @@ import { IWorkbookView } from '../workbookView';
 import { IWorkbookProtection } from '../workbookProtection';
 import { ListenerEmitter } from '../listener/ListenerEmitter';
 import { WorkbookProtection } from '../workbookProtection/WorkbookProtection';
-import { _NamedGraphNode } from '../cellRange/_GraphNode';
+import { NamedNodeInfo } from '../calculation/Types';
 import { IWorkbookIO } from '../io/IWorkbookIO';
 import { IWorkbook } from './IWorkbook';
 /**
@@ -28,13 +33,20 @@ export declare class Workbook implements IWorkbook {
     protected _id: string;
     protected _createSheet: InternalCreateSheet;
     protected _createSheetName: (id: number) => string;
+    /** `true` while the sheets of the constructor's `json` are being created. */
+    protected _isLoadingSheets: boolean;
     protected _transactions: ITransaction.IStore;
     protected _ownTransactions: boolean;
     protected _transactionsRemoveListener: IListener.Remove;
     protected _lastTransactionUUID: string | null;
     protected _starting: Promise<void> | null;
     protected _closed: boolean;
-    /** Stable, read-only reference to the IO-owned origin handle. See {@link IWorkbook.getOrigin}. */
+    /** Supplies the origin the workbook lives in now. See {@link IWorkbook.getOrigin}. */
+    protected _originProvider: IWorkbookIO.OriginProvider;
+    /** `true` when the workbook made its provider (and so releases it on close); `false` for a host's. */
+    protected _ownOriginProvider: boolean;
+    protected _listenerOriginProvider: IListener.Remove | null;
+    /** The origin currently followed for renames — the provider's, as of its last change. */
     protected _origin: IWorkbookIO.Origin;
     protected _listenerOrigin: IListener.Remove | null;
     /** Last derived display name, so stat-style origin changes (size) don't fire onNameChange. */
@@ -45,7 +57,25 @@ export declare class Workbook implements IWorkbook {
     protected _theme: ITheme;
     protected _strings: IStringCollection;
     protected _ownStrings: boolean;
-    protected _externalBooks: IExternalBookCollection;
+    /**
+     * The pivot caches, held as read until they have a model of their own. Not workbook state:
+     * nothing edits them, so they neither transact nor notify.
+     */
+    /**
+     * The workbook's pivot caches, by the id its tables reference them by.
+     *
+     * @remarks
+     * Carried, not modeled — see {@link IPivotTable.CacheJSON}. Held in part form rather than as
+     * the JSON it was read from because the resources a part can carry are model references, and
+     * their ids are assigned per save.
+     */
+    protected _pivotCaches: PivotCache[];
+    /** Every sheet's pivot tables, in sheet order — a walk, not a second store. */
+    protected _pivotTableCollection: IPivotTableCollection;
+    /** The people the workbook knows — comment authors. Not workbook state: never undone. */
+    protected _people: IPersonCollection;
+    /** Every sheet's comments, in sheet order — a walk, not a second store. */
+    protected _commentCollection: ICommentCollection;
     protected _styles: IStyleCollection;
     protected _ownStyles: boolean;
     protected _resources: IResourceCollection;
@@ -76,6 +106,10 @@ export declare class Workbook implements IWorkbook {
     protected _listenerLanguage: IListener.Remove;
     protected _runtime: IRuntime;
     protected _isDate1904: boolean;
+    /** VBA binding identity; carried from the file, never minted. See {@link IWorkbook.getCodeName}. */
+    protected _codeName: string | null;
+    /** Carried, not obeyed — see {@link IWorkbook.JSON.updateLinks}. `null` when the source said nothing. */
+    protected _updateLinks: IExternalBookCollection.UpdateLinks | null;
     /** `null` follows the environment locale. */
     protected _locale: string | null;
     /** Literal patch over the derived {@link LocaleProfile} (regional-override escape hatch); `null` = none. */
@@ -90,6 +124,17 @@ export declare class Workbook implements IWorkbook {
     getName(): string | null;
     /** {@inheritDoc IWorkbook.getOrigin} */
     getOrigin(): IWorkbookIO.Origin;
+    /**
+     * The provider moved the workbook to another origin: follow the new one instead of the old, and
+     * say so. Non-transactional — where a workbook lives is not a model edit.
+     */
+    private _onOriginChange;
+    /**
+     * Holds `origin` and follows it: the display name derives from the origin, so a change to it (a
+     * rename) IS a name change — but only when the *derived name* changed, since the handle also
+     * updates on stat-style changes (size on every save) that must not fire spurious name events.
+     */
+    private _bindOrigin;
     /** {@inheritDoc IWorkbook.getView} */
     getView(): IWorkbookView;
     /** {@inheritDoc IWorkbook.setView} */
@@ -118,6 +163,16 @@ export declare class Workbook implements IWorkbook {
     getStrings(): IStringCollection;
     /** {@inheritDoc IWorkbook.getExternalBooks} */
     getExternalBooks(): IExternalBookCollection;
+    /** {@inheritDoc IWorkbook.getUpdateLinks} */
+    getUpdateLinks(): IExternalBookCollection.UpdateLinks | null;
+    /** {@inheritDoc IWorkbook.setUpdateLinks} */
+    setUpdateLinks(updateLinks: IExternalBookCollection.UpdateLinks | null): this;
+    /** {@inheritDoc IWorkbook.getPivotTables} */
+    getPivotTables(): IPivotTableCollection;
+    /** {@inheritDoc IWorkbook.getComments} */
+    getComments(): ICommentCollection;
+    /** {@inheritDoc IWorkbook.getPeople} */
+    getPeople(): IPersonCollection;
     /** {@inheritDoc IWorkbook.getTheme} */
     getTheme(): ITheme;
     /** {@inheritDoc IWorkbook.setTheme} */
@@ -144,16 +199,48 @@ export declare class Workbook implements IWorkbook {
     findValidSheetName(str: string): string;
     /** {@inheritDoc IWorkbook.isValidSheetNameCharacter} */
     isValidSheetNameCharacter(character: string): boolean;
+    /**
+     * Whether structure protection refuses an edit now. Never while loading: opening a protected
+     * workbook is not an edit.
+     * @internal
+     */
+    _isStructureProtected(): boolean;
     /** @internal */
     protected _addSheetOptions(options?: ISheetCollection.AddOptions | string | number): ISheet;
     /** @internal */
     protected _nextSheetName(sheetName?: string | null | undefined): string;
     /** @internal */
-    protected _addSheet(notify: boolean, sheetName?: string | null, index?: number | null): ISheet;
+    protected _addSheet(notify: boolean, sheetName?: string | null, index?: number | null, uid?: string): ISheet;
     /** @internal */
     protected _updateSheetRefStates(sheetRefs: SheetRef[]): void;
+    /**
+     * Tells the calculation the sheet list as it is: every sheet, hidden ones included, in tab
+     * order. Called where an operation on the list completes - beside its `onSheetsChange`, or in
+     * `_updateSheetRef` for a ref replaced - and, for a sheet being added, once its ref is in, before
+     * its grid seeds. Never on a restore: the calculation's copy is restored with this one. A load
+     * tells the whole list before its first sheet, so a part of it is not told while the load builds
+     * them.
+     */
+    protected _tellSheets(): void;
     /** @internal */
     protected _addSheetRef(sheetRefAdd: SheetRef, index?: number | null): SheetRef;
+    /**
+     * Record which sheet was active before the operation and which it leaves active. See
+     * {@link ActiveSheetIntent} for how a batch merges the pair.
+     *
+     * @internal
+     */
+    protected _recordActiveSheet(trans: ITransaction, before: number | null, after: number | null): void;
+    /**
+     * Point the view at `targetId`, or, when `state` no longer shows that sheet, at the sheet
+     * now in the active sheet's place (the last one when it was at the end).
+     *
+     * @remarks
+     * The view listener recomputes the offset when the id changes; when it does not, the sheet
+     * may still have moved, so the offset is recomputed here.
+     * @internal
+     */
+    protected _resyncActiveSheet(targetId: number | null | undefined, state: State): void;
     /** @internal */
     protected _adjustRemoveSelectionIfRequired(indexRemove: number, id: number | null | undefined): void;
     /** @internal */
@@ -196,7 +283,7 @@ export declare class Workbook implements IWorkbook {
      * resolved falls back to the selected sheet, which is the same self-consistent-but-arbitrary
      * anchor its body was compiled against. Names lead, cells follow — the name is the heavier fact.
      */
-    protected _createGraphRanges(cells: readonly IRange.Coords[], names: readonly _NamedGraphNode[]): ICellRanges | null;
+    protected _createGraphRanges(cells: readonly IRange.Coords[], names: readonly NamedNodeInfo[]): ICellRanges | null;
     /** {@inheritDoc IWorkbook.getStats} */
     getStats(options?: ICellRange.GetStatsOptions): IRangeStats;
     /** @internal */
@@ -229,26 +316,38 @@ export declare class Workbook implements IWorkbook {
     protected _setSelectedSheet(key: SheetKey | null): ISheet;
     /** {@inheritDoc IWorkbook.getProtection} */
     getProtection(): IWorkbookProtection;
+    /** {@inheritDoc IWorkbook.getCodeName} */
+    getCodeName(): string | null;
     /** {@inheritDoc IWorkbook.getNames} */
     getNames(): INamedCollection;
     /** {@inheritDoc IWorkbook.getCalculation} */
     getCalculation(): ICalculation;
+    /** {@inheritDoc IWorkbook.getFonts} */
+    getFonts(): IFontCollection;
     /** {@inheritDoc IWorkbook.createFormula} */
-    createFormula(expression: string, coords?: Partial<IRange.CellCoords>): ICalculation.IFormula;
+    createFormula(expression: string, coords?: Partial<IRange.CellCoords>, options?: ICalculation.CreateFormulaOptions): ICalculation.IFormula;
     /** {@inheritDoc IWorkbook.evaluate} */
-    evaluate(expression: string, options?: number | ICalculation.EvaluateOptions & Partial<IRange.CellCoords>): Promise<Scalar | IRange>;
+    evaluate(expression: string, options?: number | ICalculation.EvaluateOptions & Partial<IRange.CellCoords> & ICalculation.CreateFormulaOptions): Promise<Scalar | IRange>;
     /** {@inheritDoc IWorkbook.whenCalculationReady} */
     whenCalculationReady(): Promise<ICalculation.Status>;
     /** {@inheritDoc IWorkbook.getScripts} */
     getScripts(): IScript;
+    /** {@inheritDoc IWorkbook.getModules} */
+    getModules(): IModuleCollection;
     /** @internal */
     protected _notifyAllChange(): void;
     /** {@inheritDoc IWorkbook.addListeners} */
     addListeners(listeners: IWorkbook.IListeners, options?: IListener.Options): IListener.Remove;
     /** @internal */
     protected _sheetToWBEvent(listenerWB: ICellRange.Listener): ICellRange.Listener;
+    /**
+     * Each pivot cache's source is held through the sheet it names, once the sheets exist, so an
+     * insert above the source moves it (see `PivotCache`).
+     * @internal
+     */
+    protected _holdPivotCaches(): void;
     /** @internal */
-    protected _fromJSON(json: IWorkbook.JSON): void;
+    protected _fromJSON(json: IWorkbook.JSON, uids?: readonly string[]): void;
     /** @internal */
     protected _createScripts(json?: Record<string, IModule.JSON>): IScript;
     /** {@inheritDoc IWorkbook.toJSON} */
@@ -293,6 +392,11 @@ interface SheetRef {
      * @defaultValue ISheet.Visibility.Visible
      */
     visibility: ISheet.Visibility;
+    /**
+     * The origin format's identifier for the sheet, carried through untouched.
+     * See {@link IWorkbook.SheetRefJSON.sheetId} — interop only, never {@link SheetRef.id}.
+     */
+    sheetId?: number;
     /**
      * The sheet model
      */
@@ -333,10 +437,19 @@ interface InternalCreateSheet {
      * @defaultValue - End of sheets
      */
     index: number | null, 
+    /**
+     * The origin format's identifier for the sheet, if it came from one.
+     * @internal
+     */
+    sheetId: number | undefined, 
     /**
      * The JSON representation of the sheet.
      */
-    json: ISheet.JSON | null | undefined): ISheet;
+    json: ISheet.JSON | null | undefined, 
+    /**
+     * The sheet's id ({@link ISheet.getId}), when the workbook named it before building it.
+     */
+    uid?: string): ISheet;
 }
 export {};
 //# sourceMappingURL=Workbook.d.ts.map

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

@@ -0,0 +1,36 @@
+/**
+ * Directives a workbook operation records on its transaction: something to do once the operation
+ * completes, rather than a change the operation makes.
+ *
+ * @remarks
+ * Ids and options - no workbook, sheet or view instances. See `_SheetIntents` for the sheet's
+ * half of the same model.
+ *
+ * @internal
+ */
+/** Key for the {@link ActiveSheetIntent}. */
+export declare const IntentActiveSheet = "workbook.activeSheet";
+/**
+ * Which sheet is active before and after the operation.
+ *
+ * @remarks
+ * The view is not transactional, so a landed state and the view can disagree about the active
+ * sheet: adding a sheet selects it, and an undo has to put the user back on the one they were on.
+ * Merged the way the sheet's pairs are - `before` first-writer-wins, `after` last-writer-wins -
+ * so a batch undoes to the sheet it began on and redoes to the one it ended on.
+ */
+export interface ActiveSheetIntent {
+    /**
+     * {@link IWorkbookView.getId} of the view the operation was made against.
+     *
+     * @remarks
+     * A workbook can be shown through more than one view - each user in a shared workbook has their
+     * own - and only the view that made the change is moved by undoing it.
+     */
+    viewId: string;
+    /** {@link ISheet.getId} of the sheet that was active when the operation began. */
+    before?: number | null;
+    /** {@link ISheet.getId} of the sheet the operation leaves active. */
+    after?: number | null;
+}
+//# sourceMappingURL=_WorkbookIntents.d.ts.map

package/types/src/workbookProtection/IWorkbookProtection.d.ts

@@ -26,6 +26,8 @@ export interface IWorkbookProtection extends IProtection<IWorkbookProtection, IW
      * @returns `true` if revisions are locked, `false` otherwise.
      */
     isRevisionAllowed(): boolean;
+    /** For runtime type checking. */
+    readonly isIWorkbookProtection: true;
 }
 /**
  * {@inheritDoc IWorkbookProtection}
@@ -48,6 +50,11 @@ export declare namespace IWorkbookProtection {
         revision?: boolean;
     }
     interface JSON extends IProtection.JSON {
+        /**
+         * `true` when the whole workbook stays allowed: it is not protected, and keeps its options for
+         * the next lock. Absent, the workbook is protected.
+         */
+        workbook?: boolean;
         revisionsPassword?: Partial<IProtection.EncryptedPassword>;
         structure?: boolean;
         windows?: boolean;

package/types/src/workbookProtection/WorkbookProtection.d.ts

@@ -7,8 +7,11 @@ export declare class WorkbookProtection extends DefaultProtection<IWorkbookProte
     isRevisionAllowed(): boolean;
     /** {@inheritDoc IWorkbookProtection.isStructureAllowed} */
     isStructureAllowed(): boolean;
+    protected _getAllowedKey(): string;
     protected _fromJSON(json: IWorkbookProtection.JSON | null): void;
     protected _toJSON(json: IWorkbookProtection.JSON): IWorkbookProtection.JSON;
     get [Symbol.toStringTag](): string;
+    /** {@inheritDoc IWorkbookProtection.isIWorkbookProtection} */
+    get isIWorkbookProtection(): true;
 }
 //# sourceMappingURL=WorkbookProtection.d.ts.map