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

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

@@ -5,6 +5,7 @@ import { INamedCollection } from '../named';
 import { IExternalBookCollection } from '../externalBook';
 import { NamedTableSource } from '../table/_NamedTableSource';
 import { IPivotTableCollection } from '../pivot';
+import { IEmbeddedPart } from '../io/IEmbeddedPart';
 import { PivotCache } from '../pivot/PivotCache';
 import { ICommentCollection } from '../comment';
 import { IPersonCollection } from '../person';
@@ -15,13 +16,15 @@ import { IResourceCollection } from '../resource';
 import { IStringCollection } from '../string';
 import { ITheme } from '../theme';
 import { ICell } from '../cell';
-import { ICellRange, ICellRanges } from '../cellRange';
+import { ICellRange, ICellRanges, ICellRegions } from '../cellRange';
 import { IStyleCollection } from '../style';
-import { ISheet, ISheetCollection } from '../sheet';
+import { ISheet, IWorksheet, IOpaqueSheet, IWorksheetCollection } from '../sheet';
 import { IWorkbookView } from '../workbookView';
 import { IWorkbookProtection } from '../workbookProtection';
 import { ListenerEmitter } from '../listener/ListenerEmitter';
 import { WorkbookProtection } from '../workbookProtection/WorkbookProtection';
+import { IDocumentProperties } from '../documentProperties';
+import { DocumentProperties } from '../documentProperties/DocumentProperties';
 import { NamedNodeInfo } from '../calculation/Types';
 import { IWorkbookIO } from '../io/IWorkbookIO';
 import { IWorkbook } from './IWorkbook';
@@ -95,7 +98,7 @@ export declare class Workbook implements IWorkbook {
     protected _ownCalculation: boolean;
     protected _view: IWorkbookView;
     protected _activeSheetOffset: number;
-    protected _sheets: ISheetCollection;
+    protected _sheets: IWorksheetCollection;
     protected _sheetOnNameChange: Map<number, () => void>;
     protected _sheetOnVisibilityChange: Map<number, () => void>;
     protected _sheetOnIndexChange: Map<number, () => void>;
@@ -110,13 +113,15 @@ export declare class Workbook implements IWorkbook {
     protected _codeName: string | null;
     /** Carried, not obeyed — see {@link IWorkbook.JSON.updateLinks}. `null` when the source said nothing. */
     protected _updateLinks: IExternalBookCollection.UpdateLinks | null;
+    /** See {@link IWorkbook.getProperties}. */
+    protected _documentProperties: DocumentProperties;
     /** `null` follows the environment locale. */
     protected _locale: string | null;
     /** Literal patch over the derived {@link LocaleProfile} (regional-override escape hatch); `null` = none. */
     protected _localeOverrides: LocaleProfileOverrides | null;
     constructor(options?: IWorkbook.ConstructorOptions | string);
     protected _initState(): void;
-    /** {@inheritDoc ISheet.getId} */
+    /** {@inheritDoc IWorksheet.getId} */
     getId(): string;
     /** {@inheritDoc ITransaction.ITransactional.getVersionId} */
     getVersionId(): number;
@@ -159,6 +164,8 @@ export declare class Workbook implements IWorkbook {
     getResources(): IResourceCollection;
     /** {@inheritDoc IWorkbook.getTransactions} */
     getTransactions(): ITransaction.IStore;
+    /** {@inheritDoc IWorkbook.getChanges} */
+    getChanges(commitId?: string): IWorksheet.ChangeEvent[];
     /** {@inheritDoc IWorkbook.getStrings} */
     getStrings(): IStringCollection;
     /** {@inheritDoc IWorkbook.getExternalBooks} */
@@ -181,15 +188,38 @@ export declare class Workbook implements IWorkbook {
     getSelectedSheetIndex(): number;
     /** {@inheritDoc IWorkbook.getSelectedSheet} */
     getSelectedSheet(): ISheet;
-    /** {@inheritDoc IWorkbook.getSheet} */
-    getSheet(name?: string, visibility?: ISheet.Visibility): ISheet;
-    /** {@inheritDoc IWorkbook.getSheetAt} */
-    getSheetAt(index: number, visibility?: ISheet.Visibility): ISheet;
+    /** {@inheritDoc IWorkbook.getSelectedWorksheet} */
+    getSelectedWorksheet(): IWorksheet | null;
+    /** {@inheritDoc IWorkbook.getActiveSheet} */
+    getActiveSheet(): IWorksheet | null;
+    /** {@inheritDoc IWorkbook.getActiveWorksheet} */
+    getActiveWorksheet(): IWorksheet | null;
     /** {@inheritDoc IWorkbook.getSheets} */
-    getSheets(): ISheetCollection;
-    /** {@inheritDoc IWorkbook.addSheet} */
-    addSheet(options?: ISheetCollection.AddOptions | string | number): ISheet;
-    protected _getSheets(visibility?: ISheet.Visibility): ISheet[];
+    getSheets(options?: IWorkbook.GetSheetsOptions): ISheet[];
+    /** {@inheritDoc IWorkbook.getSheet} */
+    getSheet(name?: string): ISheet;
+    /** {@inheritDoc IWorkbook.getWorksheet} */
+    getWorksheet(name?: string | number, visibility?: ISheet.Visibility): IWorksheet;
+    /** {@inheritDoc IWorkbook.getWorksheetAt} */
+    getWorksheetAt(index: number, visibility?: ISheet.Visibility): IWorksheet;
+    /**
+     * The selected worksheet, or a throw naming the selected tab when that is another kind: for the
+     * callers that act on "the sheet" unqualified, where `null` has nowhere to go.
+     * @internal
+     */
+    protected _requireSelectedWorksheet(): IWorksheet;
+    /**
+     * The worksheet that internal plumbing anchors unqualified coords to: the selected one, or else
+     * the first in tab order, or `null` when the workbook has none.
+     * @internal
+     */
+    protected _anchorWorksheet(): IWorksheet | null;
+    /** {@inheritDoc IWorkbook.getWorksheets} */
+    getWorksheets(): IWorksheetCollection;
+    /** {@inheritDoc IWorkbook.addWorksheet} */
+    addWorksheet(options?: IWorksheetCollection.AddOptions | string | number): IWorksheet;
+    /** The worksheets in tab order, no other kind. */
+    protected _getWorksheets(visibility?: ISheet.Visibility): IWorksheet[];
     protected _getSheetRefs(visibility?: ISheet.Visibility): SheetRef[];
     /** @internal */
     protected _getSheetRef(key: SheetKey | null | undefined, visibility?: ISheet.Visibility): SheetRef | null | undefined;
@@ -206,11 +236,22 @@ export declare class Workbook implements IWorkbook {
      */
     _isStructureProtected(): boolean;
     /** @internal */
-    protected _addSheetOptions(options?: ISheetCollection.AddOptions | string | number): ISheet;
+    protected _addSheetOptions(options?: IWorksheetCollection.AddOptions | string | number): IWorksheet;
     /** @internal */
     protected _nextSheetName(sheetName?: string | null | undefined): string;
     /** @internal */
-    protected _addSheet(notify: boolean, sheetName?: string | null, index?: number | null, uid?: string): ISheet;
+    protected _addSheet(notify: boolean, sheetName?: string | null, index?: number | null, uid?: string): IWorksheet;
+    /**
+     * Builds a sheet that is carried rather than modeled and adds its ref, as `_createSheet` does
+     * for a worksheet.
+     * @internal
+     */
+    protected _createOpaqueSheet(id: number, name: string, visibility: ISheet.Visibility, index: number | null, sheetId: number | undefined, kind: IOpaqueSheet.Kind, part: IEmbeddedPart, tabColor: string | null, uid?: string): IOpaqueSheet;
+    /**
+     * Makes `sheet` the active tab and asks the host to bring it to the front.
+     * @internal
+     */
+    protected _requestSelect(sheet: ISheet): Promise<boolean>;
     /** @internal */
     protected _updateSheetRefStates(sheetRefs: SheetRef[]): void;
     /**
@@ -257,12 +298,18 @@ export declare class Workbook implements IWorkbook {
     protected _nextSheetIndex(index: number, refs?: SheetRef[]): number;
     /** @internal */
     protected _prevSheetIndex(index: number, refs?: SheetRef[]): number;
+    /**
+     * The position in `worksheets` of the visible tab at `tabOffset`, or of the first worksheet after
+     * it when that tab is another kind.
+     * @internal
+     */
+    protected _worksheetOffsetFrom(tabOffset: number, worksheets: readonly IWorksheet[]): number;
     /** {@inheritDoc IWorkbook.getNextSheet} */
     getNextSheet(index: number): ISheet;
     /** {@inheritDoc IWorkbook.getPreviousSheet} */
     getPreviousSheet(index: number): ISheet;
     /** @internal */
-    protected _duplicateSheet(key?: SheetKey | null): Promise<ISheet | null>;
+    protected _duplicateSheet(key?: SheetKey | null): Promise<IWorksheet | null>;
     /** @internal */
     protected _createRange(coords: IRange.FixableCoords, getOptions?: ICellRange.GetRangeOptions): ICellRange;
     /** @internal */
@@ -284,6 +331,8 @@ export declare class Workbook implements IWorkbook {
      * anchor its body was compiled against. Names lead, cells follow — the name is the heavier fact.
      */
     protected _createGraphRanges(cells: readonly IRange.Coords[], names: readonly NamedNodeInfo[]): ICellRanges | null;
+    /** {@inheritDoc IWorkbook.getAnomalies} */
+    getAnomalies(options?: ICellRange.GetAnomaliesOptions): ICellRegions;
     /** {@inheritDoc IWorkbook.getStats} */
     getStats(options?: ICellRange.GetStatsOptions): IRangeStats;
     /** @internal */
@@ -316,6 +365,8 @@ export declare class Workbook implements IWorkbook {
     protected _setSelectedSheet(key: SheetKey | null): ISheet;
     /** {@inheritDoc IWorkbook.getProtection} */
     getProtection(): IWorkbookProtection;
+    /** {@inheritDoc IWorkbook.getProperties} */
+    getProperties(): IDocumentProperties;
     /** {@inheritDoc IWorkbook.getCodeName} */
     getCodeName(): string | null;
     /** {@inheritDoc IWorkbook.getNames} */
@@ -330,6 +381,10 @@ export declare class Workbook implements IWorkbook {
     evaluate(expression: string, options?: number | ICalculation.EvaluateOptions & Partial<IRange.CellCoords> & ICalculation.CreateFormulaOptions): Promise<Scalar | IRange>;
     /** {@inheritDoc IWorkbook.whenCalculationReady} */
     whenCalculationReady(): Promise<ICalculation.Status>;
+    /** {@inheritDoc IWorkbook.whenFontsReady} */
+    whenFontsReady(): Promise<void>;
+    /** {@inheritDoc IWorkbook.whenReady} */
+    whenReady(): Promise<void>;
     /** {@inheritDoc IWorkbook.getScripts} */
     getScripts(): IScript;
     /** {@inheritDoc IWorkbook.getModules} */
@@ -351,15 +406,15 @@ export declare class Workbook implements IWorkbook {
     /** @internal */
     protected _createScripts(json?: Record<string, IModule.JSON>): IScript;
     /** {@inheritDoc IWorkbook.toJSON} */
-    toJSON(options?: ISheet.ToJSONOptions): Promise<IWorkbook.JSON>;
+    toJSON(options?: IWorksheet.ToJSONOptions): Promise<IWorkbook.JSON>;
     /** {@inheritDoc IWorkbook.isClosed} */
     isClosed(): boolean;
     /** {@inheritDoc IWorkbook.close} */
     close(): void;
     /** {@inheritDoc ITransaction.ITransactional.beginCommit} */
     beginCommit(options?: string | ITransaction.OperationOptions): ITransaction;
-    /** {@inheritDoc ITransaction.ITransactional.doBatch} */
-    doBatch<R>(callback: (commit: ITransaction.ICommit) => R | Promise<R>, options?: string | ITransaction.OperationOptions): R | Promise<R>;
+    /** {@inheritDoc IWorkbook.doBatch} */
+    doBatch<R>(callback: (commit: ITransaction.ICommit, workbook: this) => R | Promise<R>, options?: string | ITransaction.OperationOptions): R | Promise<R>;
     /** @internal */
     protected _beginCommit(options?: string | ITransaction.OperationOptions): ITransaction;
     /** @internal */
@@ -398,7 +453,7 @@ interface SheetRef {
      */
     sheetId?: number;
     /**
-     * The sheet model
+     * The sheet model, of any kind.
      */
     sheet: ISheet;
 }
@@ -445,11 +500,11 @@ interface InternalCreateSheet {
     /**
      * The JSON representation of the sheet.
      */
-    json: ISheet.JSON | null | undefined, 
+    json: IWorksheet.JSON | null | undefined, 
     /**
-     * The sheet's id ({@link ISheet.getId}), when the workbook named it before building it.
+     * The sheet's id ({@link IWorksheet.getId}), when the workbook named it before building it.
      */
-    uid?: string): ISheet;
+    uid?: string): IWorksheet;
 }
 export {};
 //# sourceMappingURL=Workbook.d.ts.map

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

@@ -3,7 +3,7 @@ import { IListener } from '../listener';
 import { ICellRange, ICellRanges } from '../cellRange';
 import { IWorkbook } from './IWorkbook';
 import { SheetRange, SheetRangeOptions } from '../sheet/SheetRange';
-import { ISheetInternal } from '../sheet/Sheet';
+import { IWorksheetInternal } from '../sheet/Worksheet';
 export interface WorkbookRangeOptions extends SheetRangeOptions {
 }
 /**
@@ -11,7 +11,7 @@ export interface WorkbookRangeOptions extends SheetRangeOptions {
  */
 export declare class WorkbookRange extends SheetRange implements ICellRange {
     protected _workbook: IWorkbook;
-    constructor(coords: IRange.FixableCoords, internal: ISheetInternal, workbook: IWorkbook, options: WorkbookRangeOptions | null | undefined);
+    constructor(coords: IRange.FixableCoords, internal: IWorksheetInternal, workbook: IWorkbook, options: WorkbookRangeOptions | null | undefined);
     protected _createRanges(coords: readonly IRange.FixableCoords[], getOptions?: ICellRange.GetRangeOptions): ICellRanges;
     protected _createRange(coords: Readonly<IRange.FixableCoords>, getOptions?: ICellRange.GetRangeOptions): this;
     /** {@inheritDoc ICellRange.addListener} */

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

@@ -3,7 +3,7 @@ import { IListener } from '../listener';
 import { ICellRange, ICellRanges } from '../cellRange';
 import { IWorkbook } from './IWorkbook';
 import { SheetRanges, SheetRangesOptions } from '../sheet/SheetRanges';
-import { ISheetInternal } from '../sheet/Sheet';
+import { IWorksheetInternal } from '../sheet/Worksheet';
 export interface WorkbookRangesOptions extends SheetRangesOptions {
 }
 /**
@@ -11,7 +11,7 @@ export interface WorkbookRangesOptions extends SheetRangesOptions {
  */
 export declare class WorkbookRanges extends SheetRanges implements ICellRanges {
     protected _workbook: IWorkbook;
-    constructor(coords: readonly (IRange.FixableCoords | ICellRange)[], internal: ISheetInternal, workbook: IWorkbook, options: WorkbookRangesOptions | null | undefined);
+    constructor(coords: readonly (IRange.FixableCoords | ICellRange)[], internal: IWorksheetInternal, workbook: IWorkbook, options: WorkbookRangesOptions | null | undefined);
     /** {@inheritDoc ICellRange.getSource} */
     getSource<S>(): S;
     protected _createRanges(coords: readonly IRange.Coords[], getOptions?: ICellRange.GetRangeOptions): this;

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

@@ -28,9 +28,9 @@ export interface ActiveSheetIntent {
      * 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. */
+    /** {@link IWorksheet.getId} of the sheet that was active when the operation began. */
     before?: number | null;
-    /** {@link ISheet.getId} of the sheet the operation leaves active. */
+    /** {@link IWorksheet.getId} of the sheet the operation leaves active. */
     after?: number | null;
 }
 //# sourceMappingURL=_WorkbookIntents.d.ts.map

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

@@ -5,4 +5,9 @@ export declare function ERROR_DELETE_KEY(key: string): string;
 export declare function ERROR_SHEET_NAME_NOT_FOUND(sheetName: string): string;
 export declare function ERROR_SHEET_INDEX_NOT_FOUND(index: number): string;
 export declare function ERROR_SHEET_NAME_INVALID_CHARS(sheetName?: string): string;
+/** A named sheet that is not a worksheet, where a worksheet is required. */
+export declare function ERROR_SHEET_NOT_WORKSHEET(sheetName: string, kind: string): string;
+/** The selected tab is not a worksheet, where "the sheet" unqualified must be one. */
+export declare function ERROR_SELECTED_NOT_WORKSHEET(sheetName: string, kind: string): string;
+export declare function ERROR_SHEET_NOT_DUPLICABLE(sheetName: string): string;
 //# sourceMappingURL=_WorkbookMessages.d.ts.map

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

@@ -74,6 +74,57 @@ export interface IWorkbookView {
      * @see {@link IWorkbookView.setShowStatusBar}
      */
     isShowStatusBar(): boolean;
+    /**
+     * The first sheet tab shown in the tab strip, by sheet index: how far the tabs are scrolled.
+     *
+     * @defaultValue 0
+     */
+    setFirstTab(newValue: number): this;
+    /**
+     * @see {@link IWorkbookView.setFirstTab}
+     */
+    getFirstTab(): number;
+    /**
+     * Where the workbook's window sits on the screen, in twips (a twentieth of a point).
+     *
+     * @defaultValue `null` (the application places it)
+     */
+    setWindowBounds(newValue: IWorkbookView.WindowBounds | null): this;
+    /**
+     * @see {@link IWorkbookView.setWindowBounds}
+     */
+    getWindowBounds(): IWorkbookView.WindowBounds | null;
+    /**
+     * Whether the workbook's window is minimized.
+     *
+     * @defaultValue false
+     */
+    setMinimized(newValue: boolean): this;
+    /**
+     * @see {@link IWorkbookView.setMinimized}
+     */
+    isMinimized(): boolean;
+    /**
+     * Whether the workbook's window is shown. A hidden window is how Excel keeps a workbook open
+     * out of sight, as its personal macro workbook does.
+     *
+     * @defaultValue {@link IWorkbookView.Visibility.Visible}
+     */
+    setVisibility(newValue: IWorkbookView.Visibility): this;
+    /**
+     * @see {@link IWorkbookView.setVisibility}
+     */
+    getVisibility(): IWorkbookView.Visibility;
+    /**
+     * Whether a filter's list groups dates by year, month and day.
+     *
+     * @defaultValue true
+     */
+    setAutoFilterDateGrouping(newValue: boolean): this;
+    /**
+     * @see {@link IWorkbookView.setAutoFilterDateGrouping}
+     */
+    isAutoFilterDateGrouping(): boolean;
     /**
      * The id of of the activeSheet.
      *
@@ -139,7 +190,38 @@ export declare namespace IWorkbookView {
         showStatusBar?: boolean;
         /** {@inheritDoc IWorkbookView.setActiveSheetId} */
         activeSheetId?: number | null;
+        /** {@inheritDoc IWorkbookView.setFirstTab} */
+        firstTab?: number;
+        /** {@inheritDoc IWorkbookView.setWindowBounds} */
+        windowBounds?: IWorkbookView.WindowBounds | null;
+        /** {@inheritDoc IWorkbookView.setMinimized} */
+        minimized?: boolean;
+        /** {@inheritDoc IWorkbookView.setVisibility} */
+        visibility?: IWorkbookView.Visibility;
+        /** {@inheritDoc IWorkbookView.setAutoFilterDateGrouping} */
+        autoFilterDateGrouping?: boolean;
     }
+    /**
+     * A window's position and size, in twips (a twentieth of a point).
+     */
+    interface WindowBounds {
+        left: number;
+        top: number;
+        width: number;
+        height: number;
+    }
+    /**
+     * Whether a workbook's window is shown.
+     */
+    const Visibility: {
+        /** Shown. */
+        readonly Visible: "visible";
+        /** Hidden; the user can unhide it. */
+        readonly Hidden: "hidden";
+        /** Hidden, and not offered to the user to unhide. */
+        readonly VeryHidden: "veryHidden";
+    };
+    type Visibility = typeof Visibility[keyof typeof Visibility];
     interface JSON extends Properties {
     }
 }

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

@@ -39,6 +39,27 @@ export declare class WorkbookView implements IWorkbookView {
     getActiveSheetId(): number | null;
     /** {@inheritDoc IWorkbookView.setActiveSheetId} */
     setActiveSheetId(newValue: number | null): this;
+    /** {@inheritDoc IWorkbookView.getFirstTab} */
+    getFirstTab(): number;
+    /** {@inheritDoc IWorkbookView.setFirstTab} */
+    setFirstTab(newValue: number): this;
+    /** {@inheritDoc IWorkbookView.getWindowBounds} */
+    getWindowBounds(): IWorkbookView.WindowBounds | null;
+    /** {@inheritDoc IWorkbookView.setWindowBounds} */
+    setWindowBounds(newValue: IWorkbookView.WindowBounds | null): this;
+    /** {@inheritDoc IWorkbookView.isMinimized} */
+    isMinimized(): boolean;
+    /** {@inheritDoc IWorkbookView.setMinimized} */
+    setMinimized(newValue: boolean): this;
+    /** {@inheritDoc IWorkbookView.getVisibility} */
+    getVisibility(): IWorkbookView.Visibility;
+    /** {@inheritDoc IWorkbookView.setVisibility} */
+    setVisibility(newValue: IWorkbookView.Visibility): this;
+    /** {@inheritDoc IWorkbookView.isAutoFilterDateGrouping} */
+    isAutoFilterDateGrouping(): boolean;
+    /** {@inheritDoc IWorkbookView.setAutoFilterDateGrouping} */
+    setAutoFilterDateGrouping(newValue: boolean): this;
+    private _set;
     /** {@inheritDoc IWorkbookView.addListeners} */
     addListeners(listeners: IWorkbookView.IListeners, options?: IListener.Options): IListener.Remove;
     /** {@inheritDoc IWorkbookView.toJSON} */