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

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

@@ -16,22 +16,30 @@ import { Anchored } from '../anchored/Anchored';
 import { ColumnPropertiesState, SortPropertiesState, FilterPropertiesState } from './_TableUtils';
 import { ITableStyle } from './ITableStyle';
 import { ITable } from './ITable';
+import * as _Utils from './_TableUtils';
 /**
  * Implementation of {@link ITable}.
  */
-export declare class AnchoredTable extends AbstractAnchored<State, CommitView, ITable.Events> implements ITable {
+export declare class AnchoredTable extends AbstractAnchored<State, ITable.Events> implements ITable {
     protected _sheet: ISheet | undefined;
     private _styles;
     private _stylesRemoveListener;
     private _columnListener;
-    private _lastTransactionId;
     private _emptyColumnName;
     private _emptyColumnNamer;
-    private _autoExpandRemoveListener;
+    private _headerRemoveListener;
+    private _headerListenerCoords;
+    private _expandRemoveListener;
+    private _expandListenerCoords;
+    private _heldTotals;
+    private _heldCalculated;
     private _styleCache;
     private _stylePropsCache;
     private _processTableUpdate;
+    private _symbolsChanged;
     private _setContainerName;
+    private _releaseReferences;
+    private _refitBodyRows;
     private _names;
     private _namedItem;
     private _colHeadersSizeUnlistener;
@@ -44,14 +52,56 @@ export declare class AnchoredTable extends AbstractAnchored<State, CommitView, I
     private _createColumn;
     private _createSort;
     private _createFilter;
+    private _columnFacades;
+    private _sortFacades;
+    private _filterFacades;
+    /** What {@link _views} last derived, and the props it derived them from. */
+    private _columnViews;
     constructor(options: AnchoredTable.ConstructorOptions);
     protected _initializeOptions(options: AnchoredTable.ConstructorOptions): AnchoredTable.ConstructorOptions;
-    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 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, getTotals?: (id: number | string) => _Utils.ColumnTotals, getCalculated?: (id: number | string) => string | null): (id: number | string) => ITable.IColumn;
     protected initializeSortCreator(table: ITable, getProps: (id: number | string) => SortPropertiesState, getColumnProps: (id: number | string) => ColumnPropertiesState): (id: number | string) => ISort;
     protected initializeFilterCreator(table: ITable, getProps: (id: number | string) => FilterPropertiesState, getColumnProps: (id: number | string) => ColumnPropertiesState): (id: number | string) => IFilter;
     protected _initialize(options: AnchoredTable.ConstructorOptions): void;
     /** {@inheritDoc ITable.getNamed} */
     getNamed(): INamed | null;
+    /**
+     * The stored properties of one column, by id, or an empty set when this table has no such
+     * column - which is also what a table with no state in this snapshot answers.
+     *
+     * @remarks
+     * The three readers below are what the column, sort and filter facades are built on. Each is
+     * asked afresh on every read, so a facade handed out before an undo reads that undo rather than
+     * whatever it was holding.
+     */
+    private _columnPropsOf;
+    /**
+     * Everything the public getters answer with about the columns, derived from the props.
+     *
+     * @remarks
+     * State holds the props and nothing else, so there is no second copy to keep in step - which is
+     * what the old `sortsActive` / `filtersActive` / `mapColumnBy*` fields were, and what made a
+     * column rebuild able to leave a level behind pointing at a column that had gone.
+     *
+     * Rebuilt when the props are a different object, which is every write: they are frozen and
+     * replaced, never edited. So this is a cache with one entry and an exact test, not a guess.
+     */
+    private _views;
+    /** The facade for a column, made on first ask. */
+    private _columnOf;
+    /** {@link _columnOf} for a column's sort. A column that is not sorted still has one. */
+    private _sortOf;
+    /** {@link _columnOf} for a column's filter. A column that is not filtered still has one. */
+    private _filterOf;
+    /** {@link _columnPropsOf} for a column's sort, or an empty set when it is not sorted. */
+    private _sortPropsOf;
+    /** {@link _columnPropsOf} for a column's filter, or an empty set when it is not filtered. */
+    private _filterPropsOf;
+    /**
+     * A table style was added, changed or deleted, or the default changed: the style this table
+     * resolves to may differ even though nothing about the table did.
+     */
+    private _onTableStylesChange;
     /**
      * Recompute the derived visible state (`_visibleRange` and the visible flags), which depend on
      * the sheet's hidden rows/columns.
@@ -87,6 +137,180 @@ export declare class AnchoredTable extends AbstractAnchored<State, CommitView, I
     addRows(index: number, count?: number, options?: ITransaction.OperationOptions): this;
     /** {@inheritDoc ITable.deleteRowsAt} */
     deleteRowsAt(index: number, count?: number, options?: ITransaction.OperationOptions): this;
+    /**
+     * The one write path for a column's own properties.
+     *
+     * @remarks
+     * A key that is present is a change, whatever its value: an empty label or formula clears it.
+     * `null` resets the column to its name. A totals cell holds a label or a formula, never both, so
+     * the one being set replaces the other. The cell that shows the change - the header for a name,
+     * the totals cell for a label or a formula - is written in the same transaction.
+     *
+     * While the totals row is on the sheet the totals cell is ALL that is written: the props hold a
+     * column's totals only while there is no cell to hold them - see {@link _totalsOf}.
+     */
+    private _updateColumnProps;
+    /**
+     * Formula text as the table holds it: every structured reference with its table's name.
+     *
+     * @remarks
+     * A cell stores `SUM([Amount])` as `SUM(Table1[Amount])` when it is committed, and which
+     * references show without the name is decided when the text is displayed. Text the table is
+     * handed for a column - a totals formula for a row that is not showing, a calculated formula
+     * read from a cell the engine has not compiled yet - has been through no commit, so it is
+     * given the name here: compiled at the column's first body cell, which is inside the table an
+     * unqualified reference names, and imaged from there, which leaves an A1 reference as it is.
+     *
+     * As typed when it cannot be compiled: no sheet, no engine, or text that does not parse.
+     */
+    private _qualified;
+    /**
+     * Whether the totals row is a row of cells: it is shown, and there is a sheet to show it on.
+     */
+    private _isTotalsOnSheet;
+    /**
+     * What a column totals: its label or its formula.
+     *
+     * @remarks
+     * While the totals row is on the sheet this is read from the column's totals cell, every time.
+     * The cell is where the user edits it and where the engine keeps it right - through a column
+     * rename, a table rename, an insert - and a copy held beside it could only fall behind. The props
+     * hold a column's totals when there is no cell to: the row is hidden, or there is no sheet.
+     * {@link _holdTotalsFromCells} and {@link _showTotalsFromProps} carry them across.
+     */
+    private _totalsOf;
+    /**
+     * One column's cell in the totals row.
+     *
+     * @remarks
+     * Asked for cell by cell rather than by walking the row: a range iterator hands out the cell it
+     * had BEFORE a clear until the store settles (async mode), and these are read straight after one.
+     */
+    private _totalsCellAt;
+    /**
+     * A totals cell as a column's totals. A formula that is the built-in form for this column -
+     * `SUBTOTAL(109,[Name])` - reads as its function number, however it got there.
+     *
+     * @returns `null` for a cell that cannot say: protection hides its formula, and the value it
+     * shows instead is not what the column totals.
+     */
+    private _readTotalsCell;
+    /**
+     * Make a column's totals cell show `totals`, or empty it when there are none. Only while the
+     * totals row is on the sheet.
+     */
+    private _writeTotalsCellAt;
+    /**
+     * The totals row is about to leave the sheet: keep what each of its cells holds in that column's
+     * props, where {@link _showTotalsFromProps} finds it when the row comes back.
+     */
+    private _holdTotalsFromCells;
+    /**
+     * Keep every totals EXPRESSION a live formula while its row is hidden.
+     *
+     * @remarks
+     * Excel's held totals formulas are live (probed, T2): hidden, they follow a column rename, a table
+     * rename, a row inserted above and a row added to the table, A1 references included. Text in the
+     * props follows none of that. So while the row is hidden each expression is ALSO a watch - a
+     * formula the engine holds without a cell, which gets everything a cell formula gets - anchored
+     * on the row below the table, where the totals row was and will be again. It moves with that row
+     * on an insert, as the table's end does; when the table's end moves without one (a resize, an
+     * auto expansion) it is re-anchored with the text it has by then, which is a move and leaves its
+     * references where they were. Only the row matters: the text is A1, so it reads the same from
+     * any column, and a column shift inside the table is no reason to touch it.
+     *
+     * The props keep the text the watch was made from. They are what a snapshot can restore and what
+     * there is to read until the engine has registered the watch; {@link _readHeldTotal} prefers what
+     * the engine has. A function number needs none of this - it is spelled from the column's name
+     * when it is shown - and neither does a label.
+     *
+     * Derived from state, like the listeners, and called wherever they are re-derived.
+     */
+    private _syncHeldTotals;
+    /**
+     * A held expression as the model's grid holds it, or `null` when it holds none - not registered
+     * yet, or not in this snapshot.
+     */
+    private _readHeldTotal;
+    private _removeHeldTotals;
+    /**
+     * Keep every calculated column's formula a live formula.
+     *
+     * @remarks
+     * A calculated column remembers its formula apart from its cells - any of them may hold
+     * something else, the first included - and Excel's is live (probed, G5 of
+     * `probe-table-columnfill-edges.ps1`): it follows a sheet row inserted above the table, a column
+     * inserted inside it and a column rename, exceptions or not. It is the problem
+     * {@link _syncHeldTotals} solves and the same holder: the text in the column props, and a watch
+     * made from it, here on a body cell of the column.
+     *
+     * The text is always the formula as it reads in the FIRST body row, which is how a file stores
+     * it and what {@link _readHeldCalculated} images, wherever in the body the watch has been pushed
+     * to. So a watch is only made again when it has left the column's body, or when the props hold
+     * a different text.
+     */
+    private _syncHeldCalculated;
+    /**
+     * A calculated column's formula as the engine has it now, as it reads in the first body row, or
+     * `null` when it holds none - not registered yet, or not in this snapshot.
+     */
+    private _readHeldCalculated;
+    private _removeHeldCalculated;
+    /**
+     * The formula a column calculates its rows with, without its `=` and as it reads in the first
+     * body row, or `null` for a column that is not calculated.
+     */
+    private _calculatedOf;
+    /**
+     * A calculated column's formula as it reads in `rowIndex`, or `null` when it cannot be said.
+     *
+     * @remarks
+     * Asked BEFORE the rows it is for are made. Once a shift is part of the commit the engine has
+     * not re-imaged anything yet, and the text it hands out is from before the shift at a cell from
+     * after it.
+     */
+    private _calculatedTextAt;
+    /**
+     * What Excel gives a totals row the FIRST time it is shown, and never again: an aggregate in the
+     * last column, chosen by what the column holds. Held in the props, which is where
+     * {@link _showTotalsFromProps} is about to look.
+     *
+     * @remarks
+     * Probed (`probe-table-totals-firstshow.ps1`): `109` (sum) when every cell of the body that holds
+     * anything holds a number - a formula's result counts, and so does a currency or a percent
+     * format - and `103` (count) as soon as one is text, a boolean, an error, or a number shown as a
+     * date or a time, and for a column with nothing in it. A row shown a second time is given
+     * nothing, even when the aggregate was cleared in between, which is what `totalsRowShown` records.
+     * The `Total` label is the first column's from the day the table is made.
+     */
+    private _holdFirstShowTotals;
+    /**
+     * The region a bare cursor on this table traverses within, or `null` to leave the move alone.
+     *
+     * @remarks
+     * Tab wraps within the body, so a row of entries runs on to the next row of the table. Tab from
+     * the last visible body cell adds a row first, as its own step, and the wrap lands in it - when
+     * the table grows down (see {@link ITable.AutoExpand}). Enter is not the table's: it walks off
+     * the bottom as it does on the bare sheet.
+     *
+     * @internal
+     */
+    _getTraverseRegion(cell: IRange.CellCoords, axis: IRange.Axis, reverse: boolean): IRange.Coords | null;
+    /**
+     * The totals row has just arrived on the sheet: give each column's totals to its cell, and take
+     * them out of the props - from here the cell is the record.
+     *
+     * @remarks
+     * A cell that already holds something is left as it is. The row is blank when it is shown again
+     * after being hidden; it may not be when a resize lands it on cells that were already there, and
+     * what the user put in a cell is not the table's to replace.
+     *
+     * The sheet calls this for a table it has just made, once the table is registered: a totals
+     * formula names its table, and does not bind while the table cannot be found.
+     *
+     * @internal
+     */
+    _showTotalsFromProps(): void;
     protected _deleteColumn(id: number | string, options?: ITransaction.OperationOptions): void;
     /** {@inheritDoc ITable.addColumn} */
     addColumn(index?: number, values?: Scalar[], name?: string, options?: ITransaction.OperationOptions): ITable.IColumn;
@@ -98,6 +322,14 @@ export declare class AnchoredTable extends AbstractAnchored<State, CommitView, I
     getColumnById(id: string): ITable.IColumn | null;
     /** {@inheritDoc ITable.getColumns} */
     getColumnByName(name: string): ITable.IColumn | null;
+    /** {@inheritDoc ITable.delete} */
+    delete(options?: ITransaction.OperationOptions): void;
+    /**
+     * @internal
+     * Removes the table and leaves its cells as they are. `release` is what its references become;
+     * `null` leaves them, for a removal the table outlives (a cut re-adds it).
+     */
+    _remove(release?: 'error' | 'address' | null): void;
     /** {@inheritDoc ITable.convertToRange} */
     convertToRange(maxCells?: number, options?: ITransaction.OperationOptions): ICellRange;
     /** {@inheritDoc ITable.resizeTo} */
@@ -116,10 +348,35 @@ export declare class AnchoredTable extends AbstractAnchored<State, CommitView, I
     /** {@inheritDoc ITable.select} */
     select(options?: ICellRange.SelectOptions): Promise<ICellRange>;
     /** @internal */
-    protected _processRestoreOrRevert(state: State, view: CommitView, commit: ITransaction.ICommit): void;
+    protected _processRestoreOrRevert(state: State, commit: ITransaction.ICommit): void;
+    /**
+     * Bring the header and expand listeners in line with the anchor this snapshot holds.
+     *
+     * @remarks
+     * A restore lands on whatever references the snapshot's listener map carries, but the callbacks
+     * for them live on this instance, and only the ones registered most recently are still here. So
+     * the subscription is re-derived from the restored anchor: a listener whose coords are still the
+     * header's (or the ring's) is kept, any other is replaced. This is what keeps the subscription
+     * attached to the table rather than to the commit that registered it.
+     */
+    private _syncListenersToAnchor;
+    /**
+     * The sheet has moved this table whole, as a same-sheet cut does.
+     *
+     * @remarks
+     * The listener nodes the cut enclosed moved with it; the rest stayed where the table was, so the
+     * subscription is brought in line with the new anchor.
+     *
+     * @internal
+     */
+    _processAfterMove(): void;
     /** @internal */
     protected _processAnchorCoords(): void;
-    /** @internal */
+    /**
+     * A table is one rectangle and holds its anchor as one, where the base holds the container's list.
+     *
+     * @internal
+     */
     protected _processAfterContainerShift(before: IRange.Coords[], after: IRange.Coords[]): void;
     /** {@inheritDoc ITable.getDataRange} */
     getDataRange(): ICellRange;
@@ -162,26 +419,163 @@ export declare class AnchoredTable extends AbstractAnchored<State, CommitView, I
     isShowBandedRows(): boolean;
     /** {@inheritDoc ITable.setShowBandedRows} */
     setShowBandedRows(showBandedRows: boolean, options?: ITransaction.OperationOptions): this;
-    protected _setupAutoExpand(): void;
-    /** {@inheritDoc ITable.setDisabledAutoExpand} */
-    setDisabledAutoExpand(disabledAutoSize: boolean, options?: ITransaction.OperationOptions): this;
-    /** {@inheritDoc ITable.isDisabledAutoExpand} */
-    isDisabledAutoExpand(): boolean;
+    /**
+     * What the auto-expand listener watches: the table grown by one row and one column, clipped to
+     * the sheet. `null` when there is nothing to watch.
+     *
+     * @remarks
+     * The extra column is the right strip and the extra row is the bottom strip; content arriving in
+     * either grows the table. The cell the two share diagonally belongs to neither.
+     */
+    private _getExpandListenerCoords;
+    private _removeExpandListener;
+    /** @internal */
+    protected _processExpandListener(): void;
+    private _onExpandListenerEvent;
+    /**
+     * A formula has been entered in the row just below the table: that row becomes the totals row, in
+     * the one step of the expansion (Excel: `Table AutoExpansion`).
+     *
+     * @remarks
+     * Probed (`probe-table-autototals.ps1`). What was entered stays where it is and is its column's
+     * total from here on. The other columns total nothing - not the `Total` label a table is made
+     * with, not the aggregate a first showing gives - unless the table has shown a totals row before,
+     * whose totals then come back beside it as they would with the row toggled on.
+     */
+    private _takeRowBelowAsTotals;
+    /**
+     * What a commit that wrote into the body means for the columns it wrote to: a formula to fill
+     * down the column, a formula to remember, or one to forget.
+     *
+     * @remarks
+     * Probed (`probe-table-columnfill.ps1` and `-edges.ps1`). A formula written to ONE body cell is
+     * filled down its column when every other body cell of the column is blank, or when the column
+     * is calculated and every other body cell still holds one formula - so editing the formula of
+     * a calculated column edits the column, and a column holding an exception, a blank one
+     * included, is left alone. Nothing is asked about what the written cell held before. A write of
+     * two cells or more never fills, whatever it wrote. The fill is a commit of its own (Excel:
+     * `Fill`), recorded after the write it follows, so the first undo takes back the fill and
+     * leaves the formula that was typed. Hidden and filtered rows are filled like any other, and
+     * the totals row never is.
+     *
+     * A write that fills nothing can still change what the column remembers, and that is part of
+     * the write, not a step of its own: a formula written over the whole body in one write is
+     * remembered, and a column left with no formula in it at all remembers none.
+     *
+     * Everything here is asked of whole rectangles and of formula blocks - a filled column is one
+     * block - never cell by cell.
+     *
+     * @param changed Every range the commit changed, unclipped.
+     * @param bodyBefore The body as it was when the commit landed. A row the table has taken since
+     * is not one the write could have filled from: a formula written just below a table becomes a
+     * row of it and fills nothing.
+     */
+    private _processBodyWrite;
+    /**
+     * A table has just been made over cells that were already there: a column whose cells hold one
+     * formula is a calculated column from the start.
+     *
+     * @remarks
+     * Probed (`probe-table-columnfill-created.ps1`). Excel looks at the LAST five body rows and no
+     * further. The column remembers the formula of its last body cell when at most one of the other
+     * four holds anything else - another formula, a constant, a blank. So `aaaaaabbbb` remembers
+     * `b`, `baaaa` and `ab` remember `a` and `b`, and `aabbb`, `aaab` and `aaa_` remember nothing.
+     * It is not a majority, and nothing above the five rows is ever asked.
+     *
+     * The sheet calls this for a table it has just made, never for one it loads: a file says which
+     * of its columns are calculated, and a column of identical formulas is not one unless it does.
+     *
+     * @internal
+     */
+    _detectCalculatedColumns(): void;
+    /**
+     * Every calculated column's formula as it reads in `rowIndex`, by column index, or `null` when
+     * no column is calculated.
+     *
+     * @remarks
+     * For rows about to become rows of the table, and asked BEFORE they are made: once a shift is
+     * part of the commit the engine has re-imaged nothing yet, and the text it hands out is from
+     * before the shift at a cell from after it. The price is an absolute reference to a cell below
+     * an insert, which the new row names as it was before the insert moved it.
+     */
+    private _calculatedTextsAt;
+    /**
+     * Give new body rows each calculated column's formula (probed, F4: a row added to the table is
+     * given it whatever the column's other cells hold). A column whose new cells already hold
+     * something - the write the table expanded for - keeps it.
+     *
+     * @param texts From {@link _calculatedTextsAt}, for `rowStart`.
+     */
+    private _writeCalculatedRows;
+    /**
+     * Fill the formula in `from` down the body of its column, and have the column remember it.
+     */
+    private _fillColumn;
+    /**
+     * Write what columns remember as their formula. `null` forgets.
+     */
+    private _rememberCalculated;
+    /**
+     * The anchor a commit grows the table to, or `null` when it grows nothing.
+     *
+     * @remarks
+     * The strip is the one column right of the table, or the one row below it. The table takes it
+     * when the commit wrote something there and everything the table would take, OUTSIDE what that
+     * commit touched, is blank. Nothing is asked about what the written cells held before: typing
+     * over a value that sits beside a table expands it in Excel, and so does writing the same value
+     * again. So an update expands and a delete does not, for the same reason a format does not - the
+     * cell has to hold something afterwards.
+     *
+     * A block written across the edge is taken whole. A block that also runs past the table the
+     * other way - across its corner - is not beside the table, and takes nothing.
+     *
+     * @param changed Every range the commit changed, unclipped.
+     */
+    private _getAutoExpandCoords;
+    /** {@inheritDoc ITable.setAutoExpand} */
+    setAutoExpand(autoExpand: ITable.AutoExpand, options?: ITransaction.OperationOptions): this;
+    /** {@inheritDoc ITable.getAutoExpand} */
+    getAutoExpand(): ITable.AutoExpand;
+    /** {@inheritDoc ITable.setFormulaBelow} */
+    setFormulaBelow(formulaBelow: ITable.FormulaBelow, options?: ITransaction.OperationOptions): this;
+    /** {@inheritDoc ITable.getFormulaBelow} */
+    getFormulaBelow(): ITable.FormulaBelow;
+    /** {@inheritDoc ITable.setDisabledColumnFill} */
+    setDisabledColumnFill(disabledColumnFill: boolean, options?: ITransaction.OperationOptions): this;
+    /** {@inheritDoc ITable.isDisabledColumnFill} */
+    isDisabledColumnFill(): boolean;
+    /**
+     * The active levels as indexed conditions, in level order — what an apply re-runs.
+     *
+     * A level can outlive its condition (a column rebuild leaves the filter behind), and there is
+     * nothing to reapply for one that has none.
+     */
+    private _filterLevels;
     /** {@inheritDoc ITable.applyFilters} */
-    applyFilters(options?: ITransaction.OperationOptions): this;
+    applyFilters(options?: ITransaction.OperationOptions): Promise<this>;
     /** {@inheritDoc ITable.deleteFilters} */
-    deleteFilters(options?: ITransaction.OperationOptions): this;
+    deleteFilters(options?: ITransaction.OperationOptions): Promise<this>;
     /** {@inheritDoc ITable.getActiveFilters} */
     getActiveFilters(): readonly IFilter[];
     /** {@inheritDoc ITable.getFilterAt} */
     getFilterAt(index: number): IFilter | null;
-    protected _updateSorts(sorts: ISort.Options[] | undefined, originalSorts: readonly ISort[], orderedColumnsProps: ColumnPropertiesState[], mapColumnPropsById: Map<string | number, ColumnPropertiesState>): readonly ISort[];
-    protected _updateFilters(conditions: ICondition.Input[] | undefined, originalFilters: readonly IFilter[], orderedColumnsProps: ColumnPropertiesState[], mapColumnPropsById: Map<string | number, ColumnPropertiesState>): readonly IFilter[];
-    /** {@inheritDoc ITable.filter} */
     /**
-     * Perform filtering on the table.
+     * Replace every sort on the table with `sorts`, in `orderedColumnsProps`.
+     *
+     * @remarks
+     * The props are the only place a sort lives, so setting them IS the change - there is no list of
+     * active sorts to keep alongside. Levels are written by input order and made dense by
+     * {@link _renumberLevels} when the props are written, which is what covers an entry naming a
+     * column that is not there.
+     *
+     * Entries are replaced rather than edited: the array the caller built shares its entries with the
+     * props an undo restores, and writing through one would rewrite history in place.
      */
-    filter(conditions?: ICondition.Input | ICondition.RangeOptions, options?: ITransaction.OperationOptions): this;
+    protected _updateSorts(sorts: ISort.Options[] | undefined, orderedColumnsProps: ColumnPropertiesState[]): void;
+    /** {@link _updateSorts} for the filters. */
+    protected _updateFilters(conditions: ICondition.Input[] | undefined, orderedColumnsProps: ColumnPropertiesState[]): void;
+    /** {@inheritDoc ITable.filter} */
+    filter(conditions?: ICondition.Input | ICondition.RangeOptions, options?: ITransaction.OperationOptions): Promise<this>;
     /** {@inheritDoc ITable.sort} */
     sort(options?: ISort.RangeOptions & ITransaction.OperationOptions): this;
     /** {@inheritDoc ITable.applySorts} */
@@ -189,9 +583,9 @@ export declare class AnchoredTable extends AbstractAnchored<State, CommitView, I
     /** {@inheritDoc ITable.deleteSorts} */
     deleteSorts(options?: ITransaction.OperationOptions): this;
     /** {@inheritDoc ITable.applySortsAndFilters} */
-    applySortsAndFilters(options?: ITransaction.OperationOptions): this;
+    applySortsAndFilters(options?: ITransaction.OperationOptions): Promise<this>;
     /** {@inheritDoc ITable.deleteSortsAndFilters} */
-    deleteSortsAndFilters(options?: ITransaction.OperationOptions): this;
+    deleteSortsAndFilters(options?: ITransaction.OperationOptions): Promise<this>;
     /** {@inheritDoc ITable.getActiveSorts} */
     getActiveSorts(): readonly ISort[];
     /** {@inheritDoc ITable.getSortAt} */
@@ -204,8 +598,26 @@ export declare class AnchoredTable extends AbstractAnchored<State, CommitView, I
     setHiddenButtons(hidden: boolean): this;
     /** {@inheritDoc ITable.isHiddenButtons} */
     isHiddenButtons(): boolean;
-    /** @internal */
-    private _applyFilters;
+    /**
+     * The read-only half of a filter: the runs `conditions` settle over the header and body rows.
+     * `null` for a table with no sheet (a preview), which has no rows to hide.
+     *
+     * @remarks
+     * The header row is never evaluated or hidden, and neither is the totals row. `headerRowCount`
+     * decides the header, not `isShowHeaders()`: the sheet AutoFilter answers `false` to the band
+     * question yet has a header row.
+     */
+    private _evalFilter;
+    /** The write half of a filter: the rows, then the listeners. Inside the caller's transaction. */
+    private _applyFilterRuns;
+    /** The levels, then the rows ({@link _applyFilterRuns}). Inside the caller's transaction. */
+    private _writeFilters;
+    /**
+     * Take over an absorbed AutoFilter's criteria: the levels alone, never the rows. The table took
+     * the AutoFilter's own range, so the rows already sit as its criteria left them.
+     * @internal
+     */
+    _carryFilters(conditions: ICondition.Input[]): void;
     /** @internal */
     private _applySorts;
     /** {@inheritDoc ITable.getColumnAt} */
@@ -224,20 +636,18 @@ export declare class AnchoredTable extends AbstractAnchored<State, CommitView, I
      *
      * @internal
      */
-    protected _updateColumnsState(columnPropsNews: Partial<ColumnPropertiesState>[], options?: string | ITransaction.OperationOptions): ITable.IColumn[];
+    protected _updateColumnsState(columnPropsNews: Partial<ColumnPropertiesState>[], options?: string | ITransaction.OperationOptions): readonly ITable.IColumn[];
     /**
-     * Re-derives the active filter and sort levels from the column props.
+     * The one write path for the column props.
      *
      * @remarks
-     * A level is bound to a column id, but the column props are where a filter or sort actually
-     * lives. Rebuilding the columns (a delete, a sheet sync) can therefore take a column out from
-     * under its level, and a level that outlives its column reads back as unfiltered while its rows
-     * stay hidden. Deriving the levels from the props instead of carrying them alongside keeps the
-     * two from drifting, and closes the gap in `level` left by whatever was dropped.
+     * Levels are made dense here, whatever the caller did to the array - see
+     * {@link _renumberLevels}. Everything the getters answer with is derived from what this writes
+     * ({@link _views}), so there is nothing else to bring along.
      *
      * @internal
      */
-    private _rebuildActiveLevels;
+    private _writeColumnProps;
     /** {@inheritDoc ITable.getVisibleRefRangeCoords} */
     getVisibleRefRangeCoords(): IRange.Coords;
     /** {@inheritDoc ITable.getVisibleCellCoords} */
@@ -251,45 +661,157 @@ export declare class AnchoredTable extends AbstractAnchored<State, CommitView, I
     /** {@inheritDoc ITable.isLastColumnVisible} */
     isLastColumnVisible(): boolean;
     /**
-     * Builds columns from state and sheet (if available).
+     * Bring the header row and the column names back into step.
      *
      * @remarks
-     * The `converted` is true if the sheet is out of sync from the state.columns.
+     * `from: 'table'` writes the names to the header row. `from: 'sheet'` reads the header row into
+     * the names, and does nothing when the sheet already shows what the table holds. A header cell the
+     * table cannot take as it is - a number, a duplicate, a blank - is named for it, and that name is
+     * written back to the cell unless `write` is `false`.
+     *
+     * The totals row is not synced here: its cells are never mirrored into the columns - see
+     * {@link _totalsOf}.
      *
      * @internal
      */
-    protected _readSyncSheet(ignoreBlanks?: boolean, ignoreTotal?: boolean): {
-        columns: ITable.ColumnProperties[];
-        converted: boolean;
-    } | null;
+    protected _syncHeader(options: {
+        from: 'sheet' | 'table';
+        /** A blank header cell keeps the column's name, rather than being given a default one. */
+        keepNameOnBlank?: boolean;
+        description?: string;
+        /** `false` leaves a converted cell as it is on the sheet, for the caller to write. *default* `true`. */
+        write?: boolean;
+    }): void;
     /**
-     * This takes a list of columns headers and then validates them
-     * and if there is a sheet it will set the values back into the sheet.
-     *
-     * 1. They must be unique. (case insensitive)
-     * 2. They can't be blank.
-     * 3. They must be text
-     *
-     * @param isRemove If true we are removing so we don't update the sheet.
-     * @internal
+     * Builds columns from state and the header row of the sheet (if available). `converted` is true
+     * when a header cell had to be named for the table rather than taken as it is.
+     */
+    private _readHeader;
+    /**
+     * Writes the column names to the header row.
      */
-    protected _writeSyncSheet(isRemove?: boolean): void;
+    private _writeHeader;
     /** @internal */
     protected _processDelete(): void;
-    /** @internal */
-    protected _processFilterUpdate(): void;
+    /**
+     * Make a write to this table's own sheet, recorded as the table's - see {@link IntentTableOwnWrites}.
+     * The record and the write are one root commit, whether or not the caller has one open.
+     */
+    private _ownWrite;
+    /**
+     * The ranges of `changed` that this table did not write itself in the commit `commitId`, which
+     * is the root commit a sheet listener's event names.
+     */
+    private _notOwnWrites;
+    /**
+     * Asks for the A1 references that spanned the body to be re-fitted to `to` - see
+     * {@link AnchoredTable.ConstructorOptions.refitBodyRows}. Whatever part of it runs later runs only
+     * while the body is still `to`: an undo, or another edit that moved the table, ends it.
+     */
+    protected _refitBody(columns: {
+        colStart: number;
+        colEnd: number;
+    }, match: {
+        rowStart: number;
+        rowEnd: number;
+    }, headerRow: number | null, to: {
+        rowStart: number;
+        rowEnd: number;
+    }, afterShift: boolean): void;
     /** @internal */
     protected _processContainerShift(options: Anchored.ShiftOptions): IRange.Coords | null | void;
-    protected _beginCommit(options?: string | ITransaction.OperationOptions): ITransaction;
-    private _modifyTable;
+    /**
+     * Write the table's own properties: its name, its description, its style, its flags.
+     *
+     * @remarks
+     * Nothing here reaches the sheet. The bands and the anchor have writers of their own because
+     * they do - see {@link _setBands} and {@link _setAnchor}. Which of the three a public setter
+     * calls is fixed by the setter, never worked out from the keys it was handed.
+     */
+    private _setProps;
+    /**
+     * Show or hide the header row, the totals row, or both.
+     *
+     * @remarks
+     * A band is a row on the sheet, so showing one has to find the space for it and hiding one has
+     * to clear it - {@link _ensureHeightForHeaderTotals} does that, and moves the anchor when the
+     * table grew or shrank. A totals row takes what its cells hold with it when it goes
+     * ({@link _holdTotalsFromCells}) and gives it back to them when it returns
+     * ({@link _showTotalsFromProps}), all in this one transaction: Excel's `Toggle Total Row` is a
+     * single undo step, label and formulas together.
+     *
+     * @param headerRowCount `undefined` leaves the header as it is.
+     * @param totalsRowCount `undefined` leaves the totals row as it is.
+     */
+    private _setBands;
+    /**
+     * Move the table, or change what it covers.
+     *
+     * @remarks
+     * The columns follow the width ({@link _spliceColumnsToAnchor}), and the header row is then read
+     * back, so a column the table has just covered is named by the text that was already sitting in
+     * its header cell rather than by a generated one.
+     */
+    private _setAnchor;
+    /**
+     * Move the totals row to the row a resize ends the table on.
+     *
+     * @remarks
+     * Excel moves the row rather than rewriting it (probed, `probe-table-totals-refit.ps1`): what it
+     * passes on the way becomes body - growing over `70, 80` makes them the last two body rows, and
+     * shrinking leaves the body rows given up sitting below the totals - and nothing outside the
+     * table's columns or below the two rows involved ends up anywhere else.
+     *
+     * That is a rotation of the totals row past the rows between, done here with the sheet's own
+     * shifts - inserts and deletes of the table's columns - so that what names a cell follows it and
+     * nothing below the two rows is left anywhere else. A shift carries cells but cannot reorder
+     * them, so one side of the rotation has to be written again, and which side depends on what the
+     * totals row passes:
+     *
+     * - **Growing over blank rows**, the usual case, the blank rows are the side given up. Rows are
+     *   inserted above the totals row, which carries it down whole - its formats, its formulas and
+     *   every reference to its cells, exactly as Excel has them - and the blank rows it pushed out
+     *   below are deleted.
+     * - **Growing over content, and shrinking**, the rows between are the user's and have to travel,
+     *   so the totals row is the side written again: a blank row is opened where it is going, its
+     *   cells are written there - formula, value and the cell's own format - and the row they came
+     *   from is deleted, which closes the gap. Two divergences follow from writing rather than
+     *   moving. A reference to a totals CELL from elsewhere (`=C7`) becomes `#REF!` where Excel
+     *   re-points it; `Table[[#Totals],[Column]]` is unaffected. And, shrinking, an A1 reference
+     *   into the rows being given up is not pushed down with them (Excel: `SUM(C3:C5)` becomes
+     *   `SUM(C3:C6)`), because the engine re-images a formula for a shift once it has settled and
+     *   the text written here is from before; Excel's own result there is a circular reference,
+     *   the totals cell sitting inside that range.
+     *
+     * The table steps back above both rows first. A shift inside a table is the table's business
+     * ({@link _processContainerShift} would hide a totals row whose row is deleted); one below it is
+     * not.
+     *
+     * @param from The anchor the table has now, totals row included.
+     * @param rowEnd The row the totals row is going to.
+     */
+    private _moveTotalsRow;
+    /**
+     * Bring the column properties in line with a new width: a column taken in is appended (or
+     * prepended) and named, a column given up is dropped.
+     *
+     * @returns Whether the columns changed.
+     */
+    private _spliceColumnsToAnchor;
     /** {@inheritDoc IListener.ISource.addListeners} */
     addListeners(listeners: ITable.IListeners, options?: IListener.Options): IListener.Remove;
     /** @internal */
-    protected _processAfterStateChange(state: State, view: CommitView, commit: ITransaction.ICommit): void;
+    protected _processAfterStateChange(state: State, commit: ITransaction.ICommit): void;
     /** @internal */
-    protected _processHeaderListener(): void;
+    protected _isAnyChangeFromState(): boolean;
+    /**
+     * The row the header listener watches: the header row, or the first data row when there is no
+     * header, so a table without one still syncs its columns from the sheet.
+     */
+    private _getHeaderListenerCoords;
+    private _removeHeaderListener;
     /** @internal */
-    protected _processTotalsListener(): void;
+    protected _processHeaderListener(): void;
     get [Symbol.toStringTag](): string;
     /** {@inheritDoc ICellRanges.toString} */
     toString(): string;
@@ -302,6 +824,32 @@ export declare class AnchoredTable extends AbstractAnchored<State, CommitView, I
     private _fromJSON;
     /** {@inheritDoc ITable.close} */
     close(): void;
+    /**
+     * A table is deleted when its state says so - and when it has no state at all.
+     *
+     * @remarks
+     * Undoing the commit that created a table (an add, a paste, the re-add of a cut) removes its
+     * state but cannot close the instance: a redo brings the state back, and the sheet's table map
+     * hands out this same instance again. In between it is a deleted table.
+     */
+    isDeleted(): boolean;
+    /**
+     * The state of a table that can be worked on, or `null` for one that is deleted, closed, or has
+     * no state in the current snapshot. Callbacks registered on the sheet outlive the table and ask
+     * this first.
+     */
+    private _getLiveState;
+    /** {@link _getLiveState}, for a mutator: a table that is gone refuses the write. */
+    private _requireLive;
+    /**
+     * The sheet this table is on, for an operation that reaches cells.
+     *
+     * @remarks
+     * A preview table ({@link Table}) has none: it is a style rendered over coordinates, with no
+     * ranges behind it. Its getters answer an invalid range, as an unanchored table's do; anything
+     * that would read or write cells says so here rather than failing on a `null` range further in.
+     */
+    private _requireSheet;
     /** {@inheritDoc ITable.isITable} */
     get isITable(): true;
 }
@@ -331,9 +879,41 @@ export declare namespace AnchoredTable {
          */
         syncSheet?: boolean;
         processTableUpdate?: () => void;
+        /**
+         * Called, inside the operation, when the table's name or its columns are set - and once when
+         * it is created - for whoever keeps a copy of them (the calculation's replica).
+         */
+        symbolsChanged?: (table: ITable) => void;
+        /**
+         * Called before {@link ITable.delete} (`'error'`) or {@link ITable.convertToRange} (`'address'`)
+         * removes the table, while it still exists, so the formulas that reference it can be rewritten.
+         */
+        releaseReferences?: (table: ITable, release: 'error' | 'address') => void;
+        /**
+         * Called when the body's rows have changed in a way a shift does not carry a reference through:
+         * rows taken or given up at its end, or a row inserted at its first row. The A1 references
+         * that spanned the body are re-fitted to it - see `Calculation._refitTableRows`.
+         *
+         * @param columns The table's columns.
+         * @param match The rows a reference spans now, if it spanned the body before.
+         * @param headerRow The header's row, when a reference from it to `match.rowEnd` counts too.
+         * @param to The body's rows now.
+         * @param afterShift `match` is where a shift this edit makes WILL put the reference.
+         * @param isCurrent Whether the table is still as this change left it; a re-fit that runs later
+         * does nothing once it is not.
+         */
+        refitBodyRows?: (columns: {
+            colStart: number;
+            colEnd: number;
+        }, match: {
+            rowStart: number;
+            rowEnd: number;
+        }, headerRow: number | null, to: {
+            rowStart: number;
+            rowEnd: number;
+        }, afterShift: boolean, isCurrent: () => boolean) => void;
     }
 }
-/** @internal */
 interface State extends AbstractAnchored.State {
     /** Single rectangle — this type is never anchored to more than one range. */
     anchorCoords: IRange.Coords;
@@ -341,25 +921,21 @@ interface State extends AbstractAnchored.State {
     description: string;
     headerRowCount: number;
     totalsRowCount: number;
+    /** Whether a totals row has EVER been shown. The first show is given defaults; no other is. */
+    totalsRowShown: boolean;
     style: ITableStyle.StyleOptions;
-    disabledAutoExpand: boolean;
-    mapColumnById: Map<string | number, ITable.IColumn>;
-    mapColumnByIndex: Map<number, ITable.IColumn>;
-    mapColumnByName: Map<string, ITable.IColumn>;
-    orderedColumns: readonly ITable.IColumn[];
-    mapColumnPropsById: Map<string | number, ColumnPropertiesState>;
+    autoExpand: ITable.AutoExpand;
+    formulaBelow: ITable.FormulaBelow;
+    disabledColumnFill: boolean;
+    /**
+     * The columns, and everything about them: their names, their sort and their filter. The only
+     * record of any of it - what the getters answer with is derived from this, never stored beside
+     * it. See {@link AnchoredTable._views}.
+     */
     orderedColumnsProps: readonly ColumnPropertiesState[];
-    sortsActive: readonly ISort[];
-    filtersActive: readonly IFilter[];
     hiddenButtons: boolean;
     mapHiddenButtons: Map<number, boolean>;
-    headerRemoveListener: IListener.Remove | null;
-    totalsRemoveListener: IListener.Remove | null;
     lastColId: number;
-    shownTotalsRow: boolean;
-}
-/** @internal */
-interface CommitView extends AbstractAnchored.CommitView {
 }
 export {};
 //# sourceMappingURL=AnchoredTable.d.ts.map