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

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

@@ -4,32 +4,33 @@ import { ITypes } from '../type';
 import { ITransaction } from '../transaction';
 import { Tuple } from '../collections';
 import { IWorkbook } from '../workbook';
-import { IResourceCollection, IResource } from '../resource';
-import { IStringCollection } from '../string';
-import { IComment } from '../comment';
 import { IPrint } from '../print';
 import { IColor } from '../color';
 import { IListener } from '../listener';
 import { IHyperlink } from '../hyperlink';
-import { IMovable, IMovableCollection } from '../movable';
 import { IPicture } from '../picture';
 import { ICell, ICellHeader } from '../cell';
 import { ICellRange, ICellRanges, ICellRegions } from '../cellRange';
+import { IRangeSelection } from '../selection';
 import { IStyleCollection } from '../style';
-import { ITableCollection, ITable } from '../table';
-import { IDataValidationCollection, IDataValidation } from '../dataValidation';
-import { ISlicer } from '../slicer';
+import { IStringCollection } from '../string';
+import { IResource, IResourceCollection } from '../resource';
+import { IMovable, IMovableCollection } from '../movable';
+import { IPivotTable, IPivotTableCollection } from '../pivot';
+import { IComment, ICommentCollection } from '../comment';
+import { ITable, ITableCollection } from '../table';
+import { IDataValidation, IDataValidationCollection } from '../dataValidation';
+import { IConditionalFormat, IConditionalFormatCollection } from '../conditionalFormat';
+import { IProtectedRange, IProtectedRangeCollection } from '../protectedRange';
+import { IModule, IModuleCollection } from '../scripting';
+import { IChartCollection } from '../chart';
 import { INamedCollection } from '../named';
 import { ICalculation } from '../calculation';
-import { IRangeSelection } from '../selection';
 import { ISheetView } from '../sheetView';
 import { ISheetHeader } from '../sheetHeader';
 import { ISheetProtection } from '../sheetProtection';
+import { IOutline } from '../outline';
 import { ICellContainerOptions } from './ICellContainerOptions';
-import { IConditionalFormat } from '../conditionalFormat/IConditionalFormat';
-import { IConditionalFormatCollection } from '../conditionalFormat/IConditionalFormatCollection';
-import { IProtectedRange } from '../protectedRange/IProtectedRange';
-import { IProtectedRangeCollection } from '../protectedRange/IProtectedRangeCollection';
 /**
  * An `ISheet` represents a collection of elements (such as {@link ICellRange | ranges},
  * {@link ITable | tables}, etc) contained within and visualized through a {@link ISheetView | view}.
@@ -197,10 +198,26 @@ export interface ISheet extends ITransaction.ITransactional, IListener.ISource<I
      * {@link ISheetProtection.isLocked} is true.
      */
     getProtectedRanges(): IProtectedRangeCollection;
+    /**
+     * Returns the comments and notes on this sheet.
+     *
+     * @remarks
+     * One per cell. The workbook's {@link IWorkbook.getComments} walks every sheet's.
+     */
+    getComments(): ICommentCollection;
     /**
      * Returns a collection of movables that are embedded in this sheet.
      */
     getMovables(): IMovableCollection;
+    /**
+     * Returns the charts on this sheet.
+     *
+     * @remarks
+     * A view over {@link ISheet.getMovables}: every chart is the content of a movable, which is what
+     * places and names it. Read-only for now — a chart is added by adding a movable with chart
+     * content.
+     */
+    getCharts(): IChartCollection;
     /**
      * Returns the row headers managed by the sheet.
      */
@@ -225,6 +242,61 @@ export interface ISheet extends ITransaction.ITransactional, IListener.ISource<I
      * * The tab color is not used by the sheet but rather by the workbook.
      */
     setTabColor(color: IColor | string | null): this;
+    /**
+     * The sheet's VBA code name, or `null` if it has none.
+     *
+     * @defaultValue null
+     *
+     * @remarks
+     * The identifier VBA binds a sheet through — `Sheet1.Range("A1")` in a macro resolves by code
+     * name, never by tab name. It is a **second, independent identity** for the sheet: renaming the
+     * tab does not change it, and it is not the sheet's position. Excel's default happens to look
+     * positional (`Sheet1`, `Sheet2`, …) but drifts from position the moment sheets are reordered,
+     * inserted or deleted, so it can only be carried — never derived.
+     *
+     * Present on any workbook that has, or has ever had, a VBA project: it survives the project
+     * being stripped, so an `.xlsx` saved down from an `.xlsm` still carries code names. A workbook
+     * that never had one has none, and this is `null` throughout.
+     *
+     * **Read-only.** SheetXL preserves what a file declared and never mints one — a code name is
+     * assigned by the VBA editor, and inventing one would create a binding target no macro refers
+     * to. There is deliberately no `setCodeName`.
+     */
+    getCodeName(): string | null;
+    /**
+     * The row and column groups on this sheet, and how they are laid out.
+     */
+    getOutline(): IOutline;
+    /**
+     * Whether conditional formats on this sheet are recalculated as the sheet changes.
+     *
+     * @defaultValue true
+     *
+     * @remarks
+     * Excel exposes this only to VBA (`Worksheet.EnableFormatConditionsCalculation`). It is carried
+     * so a workbook that turned it off keeps it off when saved; SheetXL still evaluates conditional
+     * formats either way.
+     */
+    isConditionalFormatCalculationEnabled(): boolean;
+    /**
+     * Returns the modules this sheet owns.
+     *
+     * @remarks
+     * A sheet's modules are stored by the sheet rather than tagged with its name, so the state a
+     * tag would allow — a module left behind pointing at a sheet that no longer exists — cannot
+     * occur: delete the sheet and its modules go with it, which is also what Excel does.
+     *
+     * These modules are scoped to the sheet ({@link IModule.getScope}), and scope is a visibility
+     * rule: a function declared here is **not** callable from a cell formula, on this sheet or any
+     * other. Only globally scoped modules contribute to the formula namespace.
+     *
+     * The VBA document module for this sheet lands here, joined to it by
+     * {@link ISheet.getCodeName} — for a document module the module name *is* the code name.
+     *
+     * As with {@link IWorkbook.getScripts}, the collection filters to TypeScript unless asked
+     * otherwise; imported VBA is read with `getItems({ language: 'vba' })`.
+     */
+    getModules(): IModuleCollection;
     /**
      * Returns the sheet protection.
      */
@@ -294,28 +366,30 @@ export interface ISheet extends ITransaction.ITransactional, IListener.ISource<I
      *
      * @param update Cell Update
      * @param coords Optional CellCoord
+     * @param options How the update is read. See {@link ICell.CreateCellOptions}.
      * @returns A detached ICell
      *
      * @remarks
-     * * Useful for previewing values such as tooltip.
+     * * Useful for previewing values such as tooltip, or what typed text would be entered as.
      * * Does not add to the sheet but provides a standalone ICell.
      * * If the coords are passed it will return disconnect cell update for that value.
      */
-    createCell(update: ICell.Update, coords?: IRange.FixableCellCoords): ICell;
+    createCell(update: ICell.Update, coords?: IRange.FixableCellCoords, options?: ICell.CreateCellOptions): ICell;
     /**
      * Parses a formula expression and returns a *transient* formula object anchored to this sheet.
      *
      * @param expression The formula expression to parse.
      * @param coords Optional anchor coordinates.
+     * @param options Optional parse options; the expression is storage text unless `target` is `'display'`.
      *
      * @remarks
-     * This is a convenience method for `getCalculation().createFormula(expression, coords)`;
+     * This is a convenience method for `getCalculation().createFormula(expression, coords, options)`;
      * like everything reached through the sheet's {@link getCalculation}, a bare reference (`A2`)
      * resolves against THIS sheet rather than the selected one.
      *
      * @see {@link ICalculation.createFormula}
      */
-    createFormula(expression: string, coords?: Partial<IRange.CellCoords>): ICalculation.IFormula;
+    createFormula(expression: string, coords?: Partial<IRange.CellCoords>, options?: ICalculation.CreateFormulaOptions): ICalculation.IFormula;
     /**
      * Add Listeners.
      *
@@ -400,12 +474,15 @@ export interface ISheet extends ITransaction.ITransactional, IListener.ISource<I
      * @remarks
      * This is similar convenience method for `getCalculation().createFormula(expression).evaluate(options)`.
      */
-    evaluate(formula: string, options?: ICalculation.EvaluateOptions & Partial<IRange.CellCoords>): Promise<Scalar | IRange>;
+    evaluate(formula: string, options?: 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. 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>;
     /**
@@ -465,6 +542,14 @@ export interface ISheet extends ITransaction.ITransactional, IListener.ISource<I
      * Returns the picture interface for the sheet.
      */
     getPicture(): IPicture | null;
+    /**
+     * Returns the pivot tables laid out on this sheet, in the order they were read.
+     *
+     * @remarks
+     * Read-only for now: each table is carried as it was read and written back unchanged. The
+     * workbook's {@link IWorkbook.getPivotTables} walks every sheet's.
+     */
+    getPivotTables(): IPivotTableCollection;
     /**
      * Set the picture interface for the entire sheet.
      * @param picture The picture interface to set for the sheet, or null to remove it.
@@ -649,6 +734,14 @@ export declare namespace ISheet {
          * Always accompanied by the coarse {@link onProtectionChange}.
          */
         onProtectedRangesChange?(source: ISheet): void;
+        /**
+         * Called when a comment is added, removed, edited, resolved, replied to or re-anchored.
+         *
+         * @remarks
+         * Always accompanied by the coarse {@link onStyleChange}, since a cell paints its comment
+         * indicator.
+         */
+        onCommentsChange?(source: ISheet): void;
         /**
          * Called when the auto table is added or removed.
          */
@@ -823,13 +916,17 @@ export declare namespace ISheet {
          */
         ignoreData?: boolean;
         /**
-         * If `true` the resources will not be included in the JSON.
+         * How resources — images and the other binaries the sheet references — are written.
          *
-         * @remarks
-         * This is useful when exporting resources to another location and
-         * converting to base64 is not required.
+         * * `'embed'` serializes each one into the JSON, base64 encoded.
+         * * `'ignore'` writes every id as `0` and no resources.
+         * * An {@link IResource.Writer} puts each one wherever the caller wants and records what it
+         *   returns, so resources can be stored outside the JSON — uploaded and referenced by `uri`,
+         *   or emitted as parts of another format and referenced by id alone.
+         *
+         * @defaultValue 'embed'
          */
-        ignoreResources?: boolean;
+        resources?: 'embed' | 'ignore' | IResource.Writer;
         /**
          * If `true` the resources will not include formatting.
          *
@@ -860,17 +957,6 @@ export declare namespace ISheet {
          * Ignored if ignoreStyles is `true`.
          */
         splitDirectBorders?: boolean;
-        /**
-         * A structural transform applied to each formula as it serializes.
-         *
-         * @remarks
-         * Runs ONCE per formula block on the compiled AST (per-cell re-anchoring/re-imaging are
-         * unaffected); an all-`void` transform costs no recompile.
-         * Ignored if ignoreFormulas is `true`.
-         *
-         * @see {@link ICalculation.FormulaTransform}
-         */
-        formulaTransform?: ICalculation.FormulaTransform;
     }
     /**
      * Optional values used in the construction of am {@link ISheet}.
@@ -884,24 +970,19 @@ export declare namespace ISheet {
          */
         container?: ISheet.ContainerOptions;
         /**
-         * A unique identifier used for identifying this sheet during operations (i.e. copy/paste).
-         * This must be unique for all in-memory instances of a sheet.
+         * The sheet's id ({@link ISheet.getId}): what formulas and operations (copy/paste) identify it
+         * by. Must be unique among all in-memory sheets.
          *
-         * @returns A unique identifier for in memory operations. If not provided a default one will be used.
+         * @returns The id. If not provided a new one is made.
          * @remarks
-         * This is not saved as part of the {@link ISheet.JSON} persisted model.
+         * Not saved as part of the {@link ISheet.JSON} persisted model. A container that names its
+         * sheets before it builds them (a workbook loading its sheets) supplies it.
          */
         uid?: () => string;
         /**
          * Initial JSON.
          */
         json?: ISheet.JSON;
-        /**
-         * A structural transform applied once to each formula parsed from {@link json} — the READ
-         * half of the format-dialect hook (see `IWorkbook.ConstructorOptions.formulaTransform`).
-         * Load-time only; never applied to text typed or set after construction.
-         */
-        formulaTransform?: ICalculation.FormulaTransform;
     }
     /**
      * Options needed for embedding a sheet into another container such as a workbook.
@@ -983,8 +1064,6 @@ export declare namespace ISheet {
         pageSetUpPr?: IPrint.PageSetUpProperties;
         /** {@inheritDoc IPrint.PrintOptions} */
         printOptions?: IPrint.PrintOptions;
-        /** {@inheritDoc IPrint.OutlineProperties} */
-        outlinePr?: IPrint.OutlineProperties;
         rowBreaks?: IPrint.Break[];
         colBreaks?: IPrint.Break[];
         phoneticPr?: {
@@ -993,6 +1072,28 @@ export declare namespace ISheet {
             type: string;
         };
     }
+    /**
+     * A drawing whose shapes are described in the origin format's own legacy vector markup rather
+     * than through {@link IMovable | movables}.
+     *
+     * @remarks
+     * A carrier, not a concept: what a spreadsheet keeps out of its main drawing — the box a note is
+     * displayed in, a form control's shape, and the pictures placed in a header or footer — held as
+     * one unit and put back on save, so a document that has them survives a round trip. Each piece
+     * folds into its own model as that lands (the note's box onto the note, the control's shape onto
+     * the control, the pictures onto the print header), and the carrier goes with the last of them.
+     *
+     * The markup is opaque: it is held as it was read and replayed unchanged, which also means the
+     * positions in it do not follow rows and columns that are inserted or deleted. Its images are
+     * carried by {@link IResource} id, each under the id the markup references it by.
+     */
+    interface LegacyDrawingJSON {
+        xml: string;
+        images?: {
+            id: string;
+            resId: number;
+        }[];
+    }
     /**
      * JSON representation of an `ISheet` used for serialization and deserialization.
      */
@@ -1018,7 +1119,6 @@ export declare namespace ISheet {
          */
         cols?: IRange.JSONReference<ICellHeader.JSON>[];
         defaultColSize?: number;
-        outlineLevelCol?: number;
         /**
          * Row headers, each addressed as an entire-row run (`'5:5'`, `'5:12'`).
          *
@@ -1027,11 +1127,20 @@ export declare namespace ISheet {
          */
         rows?: IRange.JSONReference<ICellHeader.JSON>[];
         defaultRowSize?: number;
-        outlineLevelRow?: number;
         styles?: IStyleCollection.JSON;
         resources?: IResource.JSON[];
         strings?: string[];
-        people?: IComment.PersonJSON[];
+        /**
+         * Modules owned by this sheet, keyed by module name.
+         *
+         * @see {@link ISheet.getModules}
+         */
+        modules?: Record<string, IModule.JSON>;
+        /**
+         * The comments and notes, one per cell, each thread with its replies.
+         *
+         * @see {@link ISheet.getComments}
+         */
         comments?: IRange.JSONReference<IComment.JSON>[];
         hyperlinks?: IRange.JSONReference<IHyperlink.JSON>[];
         /**
@@ -1055,13 +1164,51 @@ export declare namespace ISheet {
         merges?: IRange.Address[];
         autoTable?: IRange.JSONReference<ITable.JSON>;
         tables?: IRange.JSONReference<ITable.JSON>[];
-        slicers?: Record<string, ISlicer.JSON>;
         conditionals?: IRange.JSONReference<IConditionalFormat.JSON>[];
         validations?: IRange.JSONReference<IDataValidation.JSON>[];
         protectedRanges?: IRange.JSONReference<IProtectedRange.JSON>[];
         movables?: IMovable.JSON[];
         tabColor?: string;
+        /**
+         * The sheet's VBA code name. Absent when it has none.
+         *
+         * @see {@link ISheet.getCodeName}
+         */
+        codeName?: string;
+        /**
+         * The outline settings that differ from their defaults.
+         *
+         * @see {@link ISheet.getOutline}
+         */
+        outline?: IOutline.JSON;
+        /**
+         * Present, as `false`, only when conditional format calculation is turned off.
+         *
+         * @see {@link ISheet.isConditionalFormatCalculationEnabled}
+         */
+        conditionalFormatCalculation?: boolean;
+        /**
+         * The sheet's picture.
+         */
         picture?: IPicture.JSON;
+        /**
+         * The sheet's legacy drawing: note boxes and form control shapes.
+         *
+         * @see {@link ISheet.LegacyDrawingJSON}
+         */
+        legacyDrawing?: LegacyDrawingJSON;
+        /**
+         * The legacy drawing for the sheet's header and footer, which holds their pictures.
+         *
+         * @see {@link ISheet.LegacyDrawingJSON}
+         */
+        legacyDrawingHF?: LegacyDrawingJSON;
+        /**
+         * The sheet's pivot tables.
+         *
+         * @see {@link ISheet.getPivotTables}
+         */
+        pivotTables?: IPivotTable.JSON[];
         protection?: ISheetProtection.JSON;
         view?: ISheetView.JSON;
         pageMargins?: Partial<IPrint.PageMargin>;

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

@@ -17,11 +17,6 @@ export interface ISheetCollection extends ICollection<ISheet> {
      * @param options {@link ISheetCollection.GetItemsOptions}
      */
     getItems(options?: ISheetCollection.GetItemsOptions): ISheet[];
-    /**
-     * Returns the sheet at the given index.
-     * @param index
-     * @returns
-     */
     /**
      * Convenience method for filtering by name. This is
      * functionally equivalent to getItems({ name });
@@ -29,6 +24,8 @@ export interface ISheetCollection extends ICollection<ISheet> {
      * @param name The name to search for This is case insensitive.
      */
     getByName(name: string): ISheet | null;
+    /** For runtime type checking. */
+    readonly isISheetCollection: true;
 }
 /**
  * {@inheritDoc ISheetCollection}

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

@@ -1,5 +1,6 @@
 import { ICellRanges } from '../cellRange';
-import { _NamedGraphNode } from '../cellRange/_GraphNode';
+import { NamedNodeInfo } from '../calculation/Types';
+import { INamedFormulasCollection } from '../calculation/INamedFormulasCollection';
 import { NamedRange } from './NamedRange';
 import { ISheetInternal } from './Sheet';
 import { SheetRangeOptions } from './SheetRange';
@@ -18,10 +19,18 @@ import { SheetRangeOptions } from './SheetRange';
  * The anchor matters to precedents (relative references in the body resolve from it) and is only
  * a label for dependents (the symbol index is global). Lead with the name when displaying one —
  * two names authored from the same active cell share an anchor address, and the name is the fact.
+ *
+ * Built from a {@link NamedNodeInfo} — plain data — and answers its five name questions by
+ * resolving the id against the collection when asked. It does NOT capture the name object: a name
+ * can be redefined or deleted while a graph answer is still held, and re-resolving means the
+ * answer follows the definition rather than a snapshot of it. A name that is gone answers `null`.
  */
 export declare class NamedCellRange extends NamedRange {
-    private readonly _node;
-    constructor(node: _NamedGraphNode, internal: ISheetInternal, options: SheetRangeOptions | null);
+    private readonly _info;
+    private readonly _namedFormulas;
+    constructor(info: NamedNodeInfo, namedFormulas: INamedFormulasCollection | null, internal: ISheetInternal, options: SheetRangeOptions | null);
+    /** The name this node stands for, or `null` if it no longer exists. @internal */
+    private _named;
     /**
      * {@inheritDoc INamedRange.getRanges}
      *
@@ -33,13 +42,13 @@ export declare class NamedCellRange extends NamedRange {
      */
     getRanges(): ICellRanges | null;
     /** {@inheritDoc ICellRange.getDirectPrecedents} */
-    getDirectPrecedents(): ICellRanges | null;
+    getDirectPrecedents(): Promise<ICellRanges | null>;
     /** {@inheritDoc ICellRange.getPrecedents} */
-    getPrecedents(): ICellRanges | null;
+    getPrecedents(): Promise<ICellRanges | null>;
     /** {@inheritDoc ICellRange.getDirectDependents} */
-    getDirectDependents(): ICellRanges | null;
+    getDirectDependents(): Promise<ICellRanges | null>;
     /** {@inheritDoc ICellRange.getDependents} */
-    getDependents(): ICellRanges | null;
+    getDependents(): Promise<ICellRanges | null>;
     get [Symbol.toStringTag](): string;
 }
 //# sourceMappingURL=NamedCellRange.d.ts.map

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

@@ -9,6 +9,14 @@ export declare class NamedRange extends SheetRange implements INamedRange {
     /** The name's OWN extent resolver — see {@link getRanges}. */
     private _rangesResolver;
     constructor(id: string, name: string, coords: IRange.FixableCoords, internal: ISheetInternal, options: SheetRangeOptions, getRanges?: (() => ICellRanges | null) | null);
+    /**
+     * {@inheritDoc ICellRange.getCoords}
+     *
+     * @remarks
+     * The coords are the NAME's (its first area, wherever that is) while the bound sheet is the one
+     * that asked, so a scope here is not the bound sheet's name and is handed back as resolved.
+     */
+    getCoords(): Readonly<IRange.FixableCoords>;
     /** {@inheritDoc INamedRange.getId} */
     getId(): string;
     /** {@inheritDoc INamedRange.getName} */