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

package/types/src/table/AutoTable.d.ts

@@ -1,6 +1,7 @@
 import { Scalar } from '@sheetxl/primitives';
 import { ICellRange } from '../cellRange';
 import { ITransaction } from '../transaction';
+import { ISlicer } from '../slicer';
 import { Anchored } from '../anchored/Anchored';
 import { ColumnPropertiesState } from './_TableUtils';
 import { ITableStyle } from './ITableStyle';
@@ -10,7 +11,7 @@ import { AnchoredTable } from './AnchoredTable';
  * A special ITable that is created just for filter and sorting.
  *
  * It is used by:
- * - `ISheet.addAutoTable()` "AutoTable" (Excel AutoFilter region).
+ * - `IWorksheet.addAutoTable()` "AutoTable" (Excel AutoFilter region).
  * - ITable (named tables with column metadata, styles, etc).
  *
  * A sheet-level AutoTable is similar to ITable but does not have:
@@ -29,11 +30,7 @@ export declare class AutoTable extends AnchoredTable {
     protected _initialize(options: AnchoredTable.ConstructorOptions): void;
     protected initializeColumnCreator(table: ITable, getProps: (id: number | string) => ColumnPropertiesState, updateProps: (id: number | string, update: Partial<ITable.ColumnProperties> | null, options?: string | ITransaction.OperationOptions) => void, deleteColumn: (id: number | string, options?: ITransaction.OperationOptions) => void): (id: number | string) => ITable.IColumn;
     protected _processHeaderListener(): void;
-    protected _readSyncSheet(ignoreBlanks?: boolean): {
-        columns: ITable.ColumnProperties[];
-        converted: boolean;
-    } | null;
-    protected _writeSyncSheet(isRemove?: boolean): void;
+    protected _syncHeader(): void;
     protected _calcVisible(): void;
     isShowHeaders(): boolean;
     addRows(index: number, count?: number, options?: ITransaction.OperationOptions): this;
@@ -41,7 +38,12 @@ export declare class AutoTable extends AnchoredTable {
     deleteRowsAt(index: number, count?: number, options?: ITransaction.OperationOptions): this;
     getColumnByName(name: string): ITable.IColumn | null;
     convertToRange(maxCells?: number, options?: ITransaction.OperationOptions): ICellRange;
+    /**
+     * Removes the AutoFilter. Its cells are the sheet's data and are left as they are.
+     */
+    delete(_options?: ITransaction.OperationOptions): void;
     setName(name: string, options?: ITransaction.OperationOptions): this;
+    addSlicer(_column: ITable.IColumn | string, _options?: ISlicer.AddOptions): Promise<ISlicer>;
     setDescription(description: string, options?: ITransaction.OperationOptions): this;
     updateStyleOptions(options: ITableStyle.StyleOptions, description?: string): this;
     setShowTotals(showTotals: boolean, options?: ITransaction.OperationOptions): this;

package/types/src/table/ITable.d.ts

@@ -5,13 +5,14 @@ import { IProperties } from '../type';
 import { IListener } from '../listener';
 import { IHistory } from '../history';
 import { ICellRange } from '../cellRange';
-import { ISheet } from '../sheet';
+import { IWorksheet } from '../sheet';
 import { INamed } from '../named';
 import { ICondition } from '../condition';
 import { ISort } from '../sort';
 import { IFilter } from '../filter';
+import { ISlicer } from '../slicer';
 import { IAnchored } from '../anchored';
-import { IStyle, IStyleCollection } from '../style';
+import { ICellStyle, IStyleCollection } from '../style';
 import { ITableCollection } from './ITableCollection';
 import { ITableStyle } from './ITableStyle';
 /**
@@ -36,6 +37,59 @@ import { ITableStyle } from './ITableStyle';
  * * {@link ITableCollection}
  */
 export declare namespace ITable {
+    /**
+     * Which edges of a table grow when something is entered just beside it.
+     *
+     * @remarks
+     * A value entered in the column just right of the table makes a new column, and one entered in
+     * the row just below it makes a new row (or, for a formula, a totals row - see
+     * {@link ITable.FormulaBelow}). The table only grows over cells that are otherwise blank.
+     *
+     * Growing down also lets Tab from the last cell of the body add a row; without it, Tab wraps to
+     * the first cell of the body.
+     */
+    const AutoExpand: {
+        /**
+         * Grow right and down. The default.
+         */
+        readonly Both: "both";
+        /**
+         * Grow down only.
+         */
+        readonly Rows: "rows";
+        /**
+         * Grow right only.
+         */
+        readonly Columns: "columns";
+        /**
+         * Never grow.
+         */
+        readonly None: "none";
+    };
+    type AutoExpand = typeof AutoExpand[keyof typeof AutoExpand];
+    /**
+     * Where a formula entered in the row just below a table goes, when the table has no totals row
+     * showing and grows down (see {@link ITable.AutoExpand}).
+     *
+     * @remarks
+     * A value that is not a formula always makes a new row.
+     */
+    const FormulaBelow: {
+        /**
+         * The row becomes the table's totals row, and the formula its column's total. The other columns
+         * total nothing, unless the table held totals from a totals row shown earlier. The default.
+         */
+        readonly TotalsRow: "totalsRow";
+        /**
+         * The row becomes a row of the table, as a value would.
+         */
+        readonly InsideTable: "insideTable";
+        /**
+         * The formula stays below the table, which does not grow.
+         */
+        readonly BelowTable: "belowTable";
+    };
+    type FormulaBelow = typeof FormulaBelow[keyof typeof FormulaBelow];
     /**
      * Returns a column for the table.
      */
@@ -63,27 +117,75 @@ export declare namespace ITable {
          */
         getIndex(): number;
         /**
-         * A string representing a label in the totals row for the given column.
+         * Sets the text shown in the totals row for this column.
+         *
+         * @param label The text, or an empty string for none.
+         *
+         * @remarks
+         * A totals cell shows a label or a formula, never both: setting a label removes the column's
+         * totals formula. While the totals row is hidden the label is kept, and shown with the row.
          */
         setTotalsRowLabel(label: string): this;
         /**
-         * Returns a string representing a label in the totals row for the given column.
+         * Returns the text shown in the totals row for this column.
          *
          * @returns The label or `null` if there is none.
+         *
+         * @remarks
+         * While the totals row is shown this is what its cell holds, so text typed into the cell is
+         * the label.
          */
         getTotalsRowLabel(): string | null;
         /**
-         * This is either a number or a string.
+         * Sets what this column totals.
+         *
+         * @param formula A `SUBTOTAL` function number (`101` to `110`; `109` is sum, `101` average,
+         * `103` count), a formula with or without the leading `=`, or `undefined` for none. A function
+         * number totals this column: `109` is `=SUBTOTAL(109,[Column])`.
          *
          * @remarks
-         * If this is a custom formula then this is a string if it is a number then
-         * is is treated as the functionNum param to the SUBTOTAL function.
+         * A totals cell shows a label or a formula, never both: setting a formula removes the column's
+         * totals label. While the totals row is hidden the formula is kept, and shown with the row.
+         *
+         * @example
+         * ```ts
+         * table.setShowTotals(true);
+         * table.getColumnByName('Amount').setTotalsRowFormula(109);
+         * table.getColumnByName('Price').setTotalsRowFormula('=MAX([Price])-MIN([Price])');
+         * ```
          */
         setTotalsRowFormula(formula: string | number | undefined): this;
         /**
-         * Returns this is either a number or a string.
+         * Returns what this column totals.
+         *
+         * @returns A `SUBTOTAL` function number when the column is totaled by one over itself, the
+         * formula without its leading `=` for anything else, or `null` if there is none.
+         *
+         * @remarks
+         * While the totals row is shown this is what its cell holds, so a formula typed into the cell
+         * is returned here, and `=SUBTOTAL(109,[Column])` typed into it returns `109`.
          */
         getTotalsRowFormula(): string | number | null;
+        /**
+         * Returns the formula this column calculates its rows with.
+         *
+         * @returns The formula without its leading `=`, as it reads in the column's first body row, or
+         * `null` if this is not a calculated column.
+         *
+         * @remarks
+         * A column becomes calculated when a formula is entered into one of its cells and the rest of
+         * the column is empty: the formula is filled down the column, and every row added to the
+         * table afterwards is given it too. Entering a different formula into a calculated column
+         * replaces it for the whole column, unless the column already holds a cell that differs.
+         *
+         * @example
+         * ```ts
+         * sheet.getRange('D2').setFormula('=[@Price]*[@Qty]');
+         * // once the column has filled
+         * table.getColumnByName('Total').getCalculatedFormula(); // '[@Price]*[@Qty]'
+         * ```
+         */
+        getCalculatedFormula(): string | null;
         /**
          * Returns the sort field for this column.
          */
@@ -140,17 +242,24 @@ export declare namespace ITable {
          */
         id?: string;
         /**
-         * A string representing a label in the totals row for the given column.
+         * The text shown in the totals row for this column. A column with a
+         * {@link totalsRowFormula} shows that instead.
          */
         totalsRowLabel?: string;
         /**
-         * This is either a number or a string.
+         * What this column totals: a `SUBTOTAL` function number (`101` to `110`; `109` is sum) that
+         * totals this column, or a formula without its leading `=`.
          *
-         * @remarks
-         * If this is a custom formula then this is a string if it is a number then
-         * is is treated as the functionNum param to the SUBTOTAL function.
+         * @see {@link ITable.IColumn.setTotalsRowFormula}
          */
         totalsRowFormula?: string | number;
+        /**
+         * The formula a calculated column gives its rows, without its leading `=`, as it reads in the
+         * column's first body row.
+         *
+         * @see {@link ITable.IColumn.getCalculatedFormula}
+         */
+        calculatedColumnFormula?: string;
     }
     /**
      * A set of values that can be set on a ITable.
@@ -171,13 +280,7 @@ export declare namespace ITable {
          */
         columns?: (string | ITable.ColumnProperties)[];
         /**
-         * A string representing the name of the table. This is the name that shall be used in formula references,
-         * and displayed in the UI to the spreadsheet user.
-         * This name shall not have any spaces in it, and it must be unique amongst all other displayNames and
-         * definedNames in the names. The character lengths and restrictions are the same as for definedNames.
-         *
-         * @see
-         * See SpreadsheetML Reference - Workbook definedNames section for details.
+         * Free text describing the table, such as what it holds. Not used in formulas.
          */
         description?: string;
         /**
@@ -193,15 +296,38 @@ export declare namespace ITable {
          * @defaultValue 0
          */
         totalsRowCount?: number;
+        /**
+         * Whether the table has ever shown a totals row.
+         *
+         * @remarks
+         * The first time a totals row is shown the last column is given a total - a sum when the
+         * column holds only numbers, a count otherwise. A table that has already shown one keeps
+         * whatever its columns had when the row was hidden, including nothing.
+         *
+         * @defaultValue false
+         */
+        totalsRowShown?: boolean;
         /**
          * If not specified then the default table style is used
          * If the style name isn't valid then uses a 'none' style.
          */
         style?: ITableStyle.StyleOptions | string;
         /**
-         * If true the table will not auto expand.
+         * Which edges of the table grow when something is entered just beside it.
+         *
+         * @defaultValue {@link ITable.AutoExpand.Both}
+         */
+        autoExpand?: ITable.AutoExpand;
+        /**
+         * Where a formula entered in the row just below the table goes.
+         *
+         * @defaultValue {@link ITable.FormulaBelow.TotalsRow}
+         */
+        formulaBelow?: ITable.FormulaBelow;
+        /**
+         * If true a formula entered into a column is not filled down it.
          */
-        disabledAutoExpand?: boolean;
+        disabledColumnFill?: boolean;
         /**
          * A unique id for all tables in the workbook.
          *
@@ -223,13 +349,22 @@ export declare namespace ITable {
      */
     interface SnapshotDestination {
         tables: ITableCollection;
+        /** Where the table lands: its top-left is used, its size is the table's own. */
         range: IRange.Coords;
     }
     interface ISnapshot extends IHistory.ISnapshot<ITable.SnapshotDestination, ITable, IRange.Coords> {
         /**
-         * Called when the table is copied to a new collection.
+         * Copies, or moves, the table to the destination.
+         *
+         * @remarks
+         * The table's cells are expected at the destination already: the table takes its header,
+         * body and totals rows from what is there.
+         *
+         * With `isCut` the source table is moved. Within its own sheet it is the same table at a new
+         * place, so its name and the references to it stay as they are; anywhere else it is removed
+         * and added again under its name.
          */
-        copyTo(destination: ITable.SnapshotDestination, options?: ReferenceableClipboard.CopyOptions): Promise<IRange.Coords>;
+        copyTo(destination: ITable.SnapshotDestination, options?: ReferenceableClipboard.CopyOptions): IRange.Coords;
     }
     /**
      * A JSON representation useful for persistence.
@@ -247,6 +382,10 @@ export declare namespace ITable {
          * The button may be hidden for other reasons like there is no filter.
          */
         hiddenButtons?: boolean | number[];
+        /**
+         * If the grid's controls around the table are hidden. See {@link ITable.setHiddenDecorations}.
+         */
+        hiddenDecorations?: boolean;
         /**
          * **OOXML** - Not sure what it is used for.
          */
@@ -322,6 +461,9 @@ export interface ITable extends IAnchored {
     /**
      * Add a single row to the table.
      *
+     * @param index The body row the new row goes in before, `0` being the first. Omitted or `-1`,
+     * the row is added at the end.
+     *
      * @remarks
      * This is a convenience method for {@link addRows(index, 1)}
      */
@@ -329,21 +471,30 @@ export interface ITable extends IAnchored {
     /**
      * Add a number of rows to a table.
      *
+     * @param index The body row the new rows go in before, `0` being the first. `-1`, or an index at
+     * or past the number of body rows, adds them at the end, above the totals row if there is one.
+     * @param count The number of rows to add. Defaults to `1`.
+     *
      * @remarks
-     * Not implemented
+     * The rows are inserted across the table's columns only: cells below the table move down, and
+     * cells beside it stay where they are. A calculated column gives the new rows its formula.
      *
-     * @param index
-     * @param count
+     * @example
+     * ```ts
+     * table.addRows(0, 2); // two rows at the top of the body
+     * table.addRow();      // one at the end
+     * ```
      */
     addRows(index: number, count?: number, options?: ITransaction.OperationOptions): ITable;
     /**
-     * Delete the rows from the table.
+     * Delete rows from the table's body.
      *
-     * @remarks
-     * Not implemented
+     * @param index The first body row to delete, `0` being the first.
+     * @param count The number of rows to delete. Defaults to `1`.
      *
-     * @param index The index to clear from
-     * @param count
+     * @remarks
+     * The rows are deleted across the table's columns only: cells below the table move up, and cells
+     * beside it stay where they are.
      */
     deleteRowsAt(index: number, count?: number, options?: ITransaction.OperationOptions): ITable;
     /**
@@ -386,6 +537,15 @@ export interface ITable extends IAnchored {
      * @returns The column or `null` if not found.
      */
     getColumnAt(index: number): ITable.IColumn | null;
+    /**
+     * Deletes the table and clears its cells.
+     *
+     * @remarks
+     * A formula that references the table has each reference replaced by `#REF!`.
+     *
+     * @see {@link ITable.convertToRange} to remove the table and keep its cells.
+     */
+    delete(options?: ITransaction.OperationOptions): void;
     /**
      * Convert the existing table to a range.
      * This will remove the table but preserve the original
@@ -395,6 +555,9 @@ export interface ITable extends IAnchored {
      *
      * @remarks
      * This can be an expensive operation.
+     *
+     * A formula that references the table has each reference replaced by the absolute address it
+     * designated (`Sheet1!$A$2:$C$4`).
      */
     convertToRange(maxCells?: number, options?: ITransaction.OperationOptions): ICellRange;
     /**
@@ -496,7 +659,7 @@ export interface ITable extends IAnchored {
      * change), so it can cache per-cell resolutions. Prefer this over
      * `getStyle().getRanged(table)`, which allocates a fresh uncached instance.
      */
-    getRangedStyle(): IProperties.ICellRanged<IStyle.Properties>;
+    getRangedStyle(): IProperties.ICellRanged<ICellStyle.Properties>;
     /**
      * Returns a cell style for the given coords.
      * @param coords The absolute coords.
@@ -506,7 +669,7 @@ export interface ITable extends IAnchored {
      *
      * * This is used by the preview.
      */
-    getStyleAt(coords: IRange.CellCoords): IStyle;
+    getStyleAt(coords: IRange.CellCoords): ICellStyle;
     /**
      * Specifies if totals are being shown for the table.
      */
@@ -556,13 +719,42 @@ export interface ITable extends IAnchored {
      */
     setShowBandedRows(showBandedRows: boolean, options?: ITransaction.OperationOptions): this;
     /**
-     * If true the table will not auto expand.
+     * Set which edges of the table grow when something is entered just beside it.
+     *
+     * @remarks
+     * The growth is its own step, so the first undo takes back the growth and keeps what was entered.
+     */
+    setAutoExpand(autoExpand: ITable.AutoExpand, options?: ITransaction.OperationOptions): this;
+    /**
+     * Returns which edges of the table grow when something is entered just beside it.
+     */
+    getAutoExpand(): ITable.AutoExpand;
+    /**
+     * Set where a formula entered in the row just below the table goes.
+     *
+     * @example
+     * ```ts
+     * // formulas typed under the table become new rows, as values do
+     * table.setFormulaBelow(ITable.FormulaBelow.InsideTable);
+     * ```
      */
-    setDisabledAutoExpand(disabledAutoSize: boolean, options?: ITransaction.OperationOptions): this;
+    setFormulaBelow(formulaBelow: ITable.FormulaBelow, options?: ITransaction.OperationOptions): this;
     /**
-     * Returns if the table is set to not auto expand.
+     * Returns where a formula entered in the row just below the table goes.
      */
-    isDisabledAutoExpand(): boolean;
+    getFormulaBelow(): ITable.FormulaBelow;
+    /**
+     * If true a formula entered into one cell of an empty column is not filled down the column.
+     *
+     * @remarks
+     * A column that is already calculated keeps its formula, and rows added to the table are still
+     * given it.
+     */
+    setDisabledColumnFill(disabledColumnFill: boolean, options?: ITransaction.OperationOptions): this;
+    /**
+     * Returns if the table is set to not fill a formula down its column.
+     */
+    isDisabledColumnFill(): boolean;
     /**
      * Returns the bounds for the ref accounting for hidden headers.
      *
@@ -600,16 +792,19 @@ export interface ITable extends IAnchored {
      */
     getSnapshot(options?: ReferenceableClipboard.CopyOptions): ITable.ISnapshot;
     /**
-     * Applied all filters using the existing criteria.
+     * Applies all filters using the existing criteria.
      *
      * @remarks
      * Does not change criteria; only recomputes which rows are visible.
+     *
+     * @returns Resolves once the rows are hidden; one transaction, one undo step.
      */
-    applyFilters(options?: ITransaction.OperationOptions): this;
+    applyFilters(options?: ITransaction.OperationOptions): Promise<this>;
     /**
-     * Clears all filters.
+     * Clears all filters and shows every row of the table, as Excel's Clear does — a row hidden by
+     * hand inside the table comes back too. The header and totals rows are never touched.
      */
-    deleteFilters(options?: ITransaction.OperationOptions): this;
+    deleteFilters(options?: ITransaction.OperationOptions): Promise<this>;
     /**
      * Returns the active filter entries as handle objects,
      */
@@ -619,9 +814,40 @@ export interface ITable extends IAnchored {
      */
     getFilterAt(index: number): IFilter | null;
     /**
-     * Perform filtering on the table.
+     * Adds a slicer that filters one of the table's columns.
+     *
+     * @param column The column, or its name.
+     * @param options Where it goes and how it looks. Sized 192 × 280 pixels and centered in the
+     * view unless `bounds` says otherwise; placed on the table's sheet unless `sheet` says otherwise.
+     *
+     * @returns The slicer, named for the column (`Region`, then `Region 1`), unique in the workbook.
+     *
+     * @remarks
+     * Not offered on a sheet's AutoFilter, which has no name to refer to.
+     *
+     * @example
+     * ```ts
+     * const slicer = await table.addSlicer('Region', { bounds: { x: 400, y: 20 } });
+     * await slicer.selectItems(['East']);
+     * ```
+     */
+    addSlicer(column: ITable.IColumn | string, options?: ISlicer.AddOptions): Promise<ISlicer>;
+    /**
+     * Replaces the filter levels and hides the rows that fail them.
+     *
+     * @param conditions
+     * - `undefined` or `{ conditions: [] }` → clears every filter, as {@link deleteFilters}.
+     * - a bare `ICondition.Input` → one filter on the first column, as `ICellRange.filter`.
+     * - `{ conditions: [...] }` → one level per condition, on the column each `index` names
+     *   (its position in the array when omitted), in that order.
+     *
+     * @remarks
+     * Every row the table holds is judged, whatever hid it before (`includeHidden` defaults to
+     * `true` for a filter); the header and totals rows are never evaluated or hidden.
+     *
+     * @returns Resolves once the rows are hidden; one transaction, one undo step.
      */
-    filter(conditions?: ICondition.Input | ICondition.RangeOptions, options?: ITransaction.OperationOptions): this;
+    filter(conditions?: ICondition.Input | ICondition.RangeOptions, options?: ITransaction.OperationOptions): Promise<this>;
     /**
      * Replaces the sort chain.
      *
@@ -658,13 +884,13 @@ export interface ITable extends IAnchored {
      */
     getActiveSorts(): readonly ISort[];
     /**
-     * Applies both applySorts and applyFilters.
+     * Applies both applyFilters and applySorts, in that order, as one transaction.
      */
-    applySortsAndFilters(options?: ITransaction.OperationOptions): this;
+    applySortsAndFilters(options?: ITransaction.OperationOptions): Promise<this>;
     /**
-     * Deletes both sorts and filters.
+     * Deletes both sorts and filters as one transaction.
      */
-    deleteSortsAndFilters(options?: ITransaction.OperationOptions): this;
+    deleteSortsAndFilters(options?: ITransaction.OperationOptions): Promise<this>;
     /**
      * Sets whether the filter/sort button at the specified index is hidden.
      */
@@ -682,6 +908,20 @@ export interface ITable extends IAnchored {
      * This will only return `true` if all buttons are hidden.
      */
     isHiddenButtons(): boolean;
+    /**
+     * If `hidden` is `true`, the grid shows none of its controls around the table: the handle at its
+     * bottom-right corner that resizes it by dragging, and the toolbar that floats beside it on hover.
+     *
+     * @remarks
+     * For a table an app manages itself. Only the controls are hidden: the table still grows as
+     * content is typed next to it (see {@link setAutoExpand}), and its filter buttons are
+     * {@link setHiddenButtons}. Not saved to xlsx, which has no such setting.
+     */
+    setHiddenDecorations(hidden: boolean): this;
+    /**
+     * Whether the grid's controls around the table are hidden. See {@link setHiddenDecorations}.
+     */
+    isHiddenDecorations(): boolean;
     /**
      * Add Listeners.
      *
@@ -696,7 +936,7 @@ export interface ITable extends IAnchored {
     /**
      * Returns the sheet the table is associated with.
      */
-    getSheet(): ISheet | null;
+    getWorksheet(): IWorksheet | null;
     /**
      * The table's entry in the workbook's names, or `null` if it is not named.
      *

package/types/src/table/ITableCollection.d.ts

@@ -28,6 +28,8 @@ export interface ITableCollection extends ICollection<ITable> {
      * @param name The name to filter for This is case insensitive.
      */
     getByName(name: string): ITable | null;
+    /** For runtime type checking. */
+    readonly isITableCollection: true;
 }
 /**
  * {@inheritDoc ITableCollection}
@@ -51,8 +53,18 @@ export declare namespace ITableCollection {
          * A default value of false will create a new row.
          */
         hasHeader?: boolean;
+        /**
+         * Whether the range already ends with the totals row the `properties` ask for. The table then
+         * takes those cells as its totals row rather than adding one below the range.
+         *
+         * @defaultValue false
+         */
+        hasTotals?: boolean;
         /**
          * Properties to set on the table when created.
+         *
+         * @remarks
+         * With `headerRowCount: 0` the range has no header row: all of it is data.
          */
         properties?: ITable.Properties;
         /**