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

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

@@ -4,8 +4,12 @@ import { IListener } from '../listener';
 import { INamedCollection } from '../named';
 import { IExternalBookCollection } from '../externalBook';
 import { NamedTableSource } from '../table/_NamedTableSource';
+import { IPivotTableCollection } from '../pivot';
+import { IEmbeddedPart } from '../io';
+import { ICommentCollection } from '../comment';
+import { IPersonCollection } from '../person';
 import { ICalculation } from '../calculation';
-import { IScript, IModule } from '../scripting';
+import { IScript, IModule, IModuleCollection } from '../scripting';
 import { IResourceCollection } from '../resource';
 import { IStringCollection } from '../string';
 import { ITheme } from '../theme';
@@ -17,7 +21,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 +32,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 +56,28 @@ 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: {
+        cacheId: number;
+        part: IEmbeddedPart | null;
+    }[];
+    /** 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;
@@ -67,6 +99,8 @@ export declare class Workbook implements IWorkbook {
     protected _activeSheetOffset: number;
     protected _sheets: ISheetCollection;
     protected _sheetOnNameChange: Map<number, () => void>;
+    /** `true` while a revert or a restore announces the sheet list it landed on. */
+    protected _restoringSheets: boolean;
     protected _sheetOnVisibilityChange: Map<number, () => void>;
     protected _sheetOnIndexChange: Map<number, () => void>;
     protected _protection: WorkbookProtection;
@@ -76,6 +110,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 +128,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 +167,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,6 +203,12 @@ 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 */
@@ -154,6 +219,23 @@ export declare class Workbook implements IWorkbook {
     protected _updateSheetRefStates(sheetRefs: SheetRef[]): 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 +278,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,18 +311,22 @@ 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.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} */
@@ -293,6 +379,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,6 +424,11 @@ 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.
      */

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

package/types/src/workbookView/IWorkbookView.d.ts

@@ -4,6 +4,16 @@ import { IListener } from '../listener';
  *
  */
 export interface IWorkbookView {
+    /**
+     * Identifies this view.
+     *
+     * @remarks
+     * Stable for the life of the view. A workbook can be shown through more than one view — each
+     * user in a shared workbook has their own — so anything recorded against a view (the active
+     * sheet an undo returns to, for example) names it by this id rather than holding the view
+     * itself.
+     */
+    getId(): string;
     /**
      * Shows the visibility of the formula bar.
      */
@@ -87,6 +97,8 @@ export interface IWorkbookView {
      * Saves the current state to JSON.
      */
     toJSON(): IWorkbookView.JSON | null;
+    /** For runtime type checking. */
+    readonly isIWorkbookView: true;
 }
 /**
  * {@inheritDoc IWorkbookView}

package/types/src/workbookView/WorkbookView.d.ts

@@ -5,9 +5,12 @@ import { ListenerEmitter } from '../listener/ListenerEmitter';
  * Default Workbook View.
  */
 export declare class WorkbookView implements IWorkbookView {
+    protected _id: string;
     private _state;
     protected _emitter: ListenerEmitter<IWorkbookView, IWorkbookView.IListeners>;
     constructor(options?: IWorkbookView.ConstructorOptions);
+    /** {@inheritDoc IWorkbookView.getId} */
+    getId(): string;
     /** {@inheritDoc IWorkbookView.isShowFormulaBar} */
     isShowFormulaBar(): boolean;
     /** {@inheritDoc IWorkbookView.setShowFormulaBar} */
@@ -45,5 +48,7 @@ export declare class WorkbookView implements IWorkbookView {
     update(view: Partial<IWorkbookView.Properties>, notify?: boolean): void;
     get [Symbol.toStringTag](): string;
     toString(): string;
+    /** {@inheritDoc IWorkbookView.isIWorkbookView} */
+    get isIWorkbookView(): true;
 }
 //# sourceMappingURL=WorkbookView.d.ts.map