@sheetxl/sdk 0.7.21 → 0.7.23-beta.2

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

@@ -0,0 +1,714 @@
+import { IRange, Scalar } from '@sheetxl/primitives';
+import { Size, ReferenceableClipboard } from '@sheetxl/utils';
+import { ITransaction } from '../transaction';
+import { IProperties } from '../type';
+import { IListener } from '../listener';
+import { IHistory } from '../history';
+import { ICellRange } from '../cellRange';
+import { ISheet } from '../sheet';
+import { INamed } from '../named';
+import { ICondition } from '../condition';
+import { ISort } from '../sort';
+import { IFilter } from '../filter';
+import { IAnchored } from '../anchored';
+import { IStyle, IStyleCollection } from '../style';
+import { ITableCollection } from './ITableCollection';
+import { ITableStyle } from './ITableStyle';
+/**
+ * Capabilities for working with embedded tables.
+ *
+ * Tables offer structured data management and enhanced analysis features.
+ *
+ * Key features including:
+ * - Operating on data with named and typed columns.
+ * - Automatic filtering and sorting options.
+ * - Creating calculated columns with dynamic formulas.
+ * - Utilizing structured references for easier formula creation.
+ * - Applying table styles for visual organization and improved readability.
+ *
+ * @see
+ * ### **Interface**
+ *
+ * {@link ITable}
+ *
+ * **Additional Interfaces**
+ * * {@link ITableStyle}
+ * * {@link ITableCollection}
+ */
+export declare namespace ITable {
+    /**
+     * Returns a column for the table.
+     */
+    interface IColumn {
+        /**
+         * A string representing the unique caption of the table column.
+         * This is what shall be displayed in the header row in the UI, and is referenced through functions.
+         * This name shall be unique per table.
+         */
+        getName(): string;
+        /**
+         * Sets the name of the column.
+         * @param name
+         */
+        setName(name: string): this;
+        /**
+         * The unique id of the column.
+         *
+         * @remarks
+         * This will not change during the lifetime of the column.
+         */
+        getId(): string;
+        /**
+         * The index of the column within the table.
+         */
+        getIndex(): number;
+        /**
+         * A string representing a label in the totals row for the given column.
+         */
+        setTotalsRowLabel(label: string): this;
+        /**
+         * Returns a string representing a label in the totals row for the given column.
+         *
+         * @returns The label or `null` if there is none.
+         */
+        getTotalsRowLabel(): string | null;
+        /**
+         * This is either a number or a string.
+         *
+         * @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.
+         */
+        setTotalsRowFormula(formula: string | number | undefined): this;
+        /**
+         * Returns this is either a number or a string.
+         */
+        getTotalsRowFormula(): string | number | null;
+        /**
+         * Returns the sort field for this column.
+         */
+        getSort(): ISort | null;
+        /**
+         * Returns the filter for this column.
+         */
+        getFilter(): IFilter | null;
+        /**
+         * Returns whether the filter/sort button for this column is hidden.
+         */
+        isHiddenButton(): boolean;
+        /**
+         * Sets whether the filter/sort button for this column is hidden.
+         */
+        setHiddenButton(hidden: boolean): this;
+        /**
+         * Returns the table this column belongs to.
+         */
+        getTable(): ITable;
+        /**
+         * Returns the range of this column within the table.
+         * This includes the header and foot row if applicable.
+         */
+        getRange(options?: ICellRange.GetRangeOptions): ICellRange;
+        /**
+         * Removes the column from the table.
+         *
+         * @remarks
+         * This will cause the columns to shift left and their indexes to change. Any
+         * associated filters/sorts will also be removed.
+         */
+        delete(options?: ITransaction.OperationOptions): void;
+        /**
+         * @returns The current state as a JSON object or `null` if not serializable.
+         */
+        toJSON(): ITable.ColumnJSON | null;
+        /**
+         * For runtime type checking.
+         */
+        isIColumn: true;
+    }
+    interface ColumnJSON extends ColumnProperties {
+    }
+    interface ColumnProperties {
+        /**
+         * A string representing the unique caption of the table column.
+         * This is what shall be displayed in the header row in the UI, and is referenced through functions.
+         * This name shall be unique per table.
+         */
+        name: string;
+        /**
+         * The unique ID of the column.
+         */
+        id?: string;
+        /**
+         * A string representing a label in the totals row for the given column.
+         */
+        totalsRowLabel?: string;
+        /**
+         * This is either a number or a string.
+         *
+         * @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.
+         */
+        totalsRowFormula?: string | number;
+    }
+    /**
+     * A set of values that can be set on a ITable.
+     *
+     * @see
+     * {@link ITable}
+     */
+    interface Properties {
+        /**
+         * The unique name of the table.
+         */
+        name?: string;
+        /**
+         * Table column definitions.
+         *
+         * @remarks
+         * All tables must have columns.
+         */
+        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.
+         */
+        description?: string;
+        /**
+         * An integer representing the number of header rows showing at the top of the table.
+         * 0 means that the header row is not shown.
+         *
+         * @defaultValue 1
+         */
+        headerRowCount?: number;
+        /**
+         * An integer representing the number of totals rows that shall be shown at the bottom of the table.
+         *
+         * @defaultValue 0
+         */
+        totalsRowCount?: number;
+        /**
+         * 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.
+         */
+        disabledAutoExpand?: boolean;
+        /**
+         * A unique id for all tables in the workbook.
+         *
+         * @remarks
+         * This will never change.
+         */
+        id?: string;
+        /**
+         * Accessibility alt text for the table.
+         */
+        altText?: string;
+        /**
+         * Accessibility alt text summary for the table.
+         */
+        altTextSummary?: string;
+    }
+    /**
+     * Provides destination details for the Snapshot when using {@link IHistory.ISnapshot.copyTo}.
+     */
+    interface SnapshotDestination {
+        tables: ITableCollection;
+        range: IRange.Coords;
+    }
+    interface ISnapshot extends IHistory.ISnapshot<ITable.SnapshotDestination, ITable, IRange.Coords> {
+        /**
+         * Called when the table is copied to a new collection.
+         */
+        copyTo(destination: ITable.SnapshotDestination, options?: ReferenceableClipboard.CopyOptions): Promise<IRange.Coords>;
+    }
+    /**
+     * A JSON representation useful for persistence.
+     */
+    interface JSON extends Omit<Properties, 'style'> {
+        /**
+         * 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;
+        /**
+         * If the button is hidden.
+         *
+         * @remarks
+         * The button may be hidden for other reasons like there is no filter.
+         */
+        hiddenButtons?: boolean | number[];
+        /**
+         * **OOXML** - Not sure what it is used for.
+         */
+        showButtons?: boolean | number[];
+        /**
+         * The criterial for the filter field. If this is empty or null then
+         * this is treated as not having any criteria.
+         */
+        filter?: IFilter.JSON;
+        /**
+         * The criterial for the filter field. If this is empty or null then
+         * this is treated as not having any criteria.
+         */
+        sort?: ISort.JSON;
+    }
+    /**
+     * IListener for {@link ITable} events.
+     */
+    interface Events extends IAnchored.Events {
+        /**
+         * Called when the filter changes.
+         */
+        onFilterChange?(source: ITable): void;
+        /**
+         * Called when the sort changes.
+         */
+        onSortChange?(source: ITable): void;
+        /**
+         * Called when the hidden buttons change.
+         */
+        onHiddenButtonsChange?(source: ITable): void;
+        /**
+         * Called when any property changes.
+         */
+        onAnyChange?(source: ITable): void;
+        /**
+         * Called when the table is changed.
+         */
+        onStyleChange?(source: ITable): void;
+    }
+    interface IListeners extends IListener.Callbacks<ITable, ITable.Events> {
+    }
+    interface ConstructorOptions {
+        /**
+         * The sheet the table is associated with.
+         */
+        size?: Size;
+        /**
+         * Required if there is no sheet. For example when showing table Preview.
+         */
+        styles?: IStyleCollection;
+        /**
+         * JSON state to load.
+         */
+        json?: ITable.JSON;
+    }
+}
+/**
+ * A Table is an embedded table that allows for advanced capabilities.
+ *
+ * 1. Filtering
+ * 2. Dynamic Styling
+ * 3. External data
+ * 4. Structured formulas
+ */
+export interface ITable extends IAnchored {
+    /**
+     * Selects the current table.
+     *
+     * @returns An async boolean indicating the table was selected.
+     */
+    select(options?: ICellRange.SelectOptions): Promise<ICellRange>;
+    /**
+     * Add a single row to the table.
+     *
+     * @remarks
+     * This is a convenience method for {@link addRows(index, 1)}
+     */
+    addRow(index?: number, options?: ITransaction.OperationOptions): this;
+    /**
+     * Add a number of rows to a table.
+     *
+     * @remarks
+     * Not implemented
+     *
+     * @param index
+     * @param count
+     */
+    addRows(index: number, count?: number, options?: ITransaction.OperationOptions): ITable;
+    /**
+     * Delete the rows from the table.
+     *
+     * @remarks
+     * Not implemented
+     *
+     * @param index The index to clear from
+     * @param count
+     */
+    deleteRowsAt(index: number, count?: number, options?: ITransaction.OperationOptions): ITable;
+    /**
+     * Add a single column.
+     *
+     * @remarks
+     * Not implemented
+     * To remove columns use the resize
+     */
+    addColumn(index?: number, values?: Scalar[], name?: string, options?: ITransaction.OperationOptions): ITable.IColumn;
+    /**
+     * Returns the columns for this table.
+     */
+    getColumns(): readonly ITable.IColumn[];
+    /**
+     * Returns a column for the given name or ID.
+     *
+     * @param key The name of the column.
+     * @returns The column or `null` if not found.
+     */
+    getColumn(key: string): ITable.IColumn | null;
+    /**
+     * Returns a column for the given ID.
+     *
+     * @param id The id of the column.
+     * @returns The column or `null` if not found.
+     */
+    getColumnById(id: string): ITable.IColumn | null;
+    /**
+     * Returns a column for the given name.
+     *
+     * @param name The name of the column.
+     * @returns The column or `null` if not found.
+     */
+    getColumnByName(name: string): ITable.IColumn | null;
+    /**
+     * Returns an column for the given index.
+     *
+     * @param index The index of the column.
+     * @returns The column or `null` if not found.
+     */
+    getColumnAt(index: number): ITable.IColumn | null;
+    /**
+     * Convert the existing table to a range.
+     * This will remove the table but preserve the original
+     * data and formatting.
+     *
+     * @param maxCells The maximum number of convert.
+     *
+     * @remarks
+     * This can be an expensive operation.
+     */
+    convertToRange(maxCells?: number, options?: ITransaction.OperationOptions): ICellRange;
+    /**
+     * Resize the table.
+     * @param address The new size of the table.
+     *
+     * @remarks
+     * This will throw an exception if:
+     * 1. The top row changes.
+     * 2. If doesn't overlap with the original table.
+     * 3. If overlaps with another non-overlapping object (e.g. another table or a merge).
+     */
+    resize(address: ICellRange.Address, options?: ITransaction.OperationOptions): ICellRange;
+    /**
+     * Resizes the current range to the specified ending row and column indices.
+     *
+     * @param rowCount The new row count.
+     * @param colCount The new column count.
+     * @returns `ICellRange` with the resized range.
+     *
+     * @remarks
+     * This is slightly different that ICellRange.getSizeTo in that it is relative.
+     */
+    resizeTo(rowCount: number, colCount: number, options?: ITransaction.OperationOptions): ICellRange;
+    /**
+     * @see {@link setName}
+     */
+    getName(): string;
+    /**
+     * The unique id of the table.
+     *
+     * @remarks
+     * This will not change during the lifetime of the table.
+     */
+    getId(): string;
+    /**
+     * Set the name for a table object.
+     *
+     * @param name A unique name.
+     */
+    setName(name: string, options?: ITransaction.OperationOptions): ITable;
+    /**
+     * @see {@link setDescription}
+     */
+    getDescription(): string;
+    /**
+     * This is the alternative text use for assistive technologies.
+     *
+     * @param description A short human readable text. Default value `null`.
+     */
+    setDescription(description: string | null, options?: ITransaction.OperationOptions): ITable;
+    /**
+     * Returns the range for the entire table.
+     *
+     * @remarks
+     * A table occupies exactly one rectangle, which is why the singular is declared here rather than
+     * on {@link IAnchored}. Invalid, never `null`, once the table is no longer anchored.
+     */
+    getRange(): ICellRange;
+    /**
+     * Get the range between the header and the total.
+     *
+     * @remarks
+     * Excel calls this the getRangeBetweenHeaderAndTotal()
+     */
+    getDataRange(): ICellRange;
+    /**
+     * Get the header row range.
+     */
+    getHeaderRowRange(): ICellRange;
+    /**
+     * Get the total row range.
+     */
+    getTotalRowRange(): ICellRange;
+    /**
+     * Get the style info.
+     */
+    getStyleOptions(): ITableStyle.StyleOptions;
+    /**
+     * Updates the table StyleInfo.
+     *
+     * @param options Style options unique to the table.
+     *
+     * @remarks
+     * This will merge with the existing values.
+     * @deprecated
+     */
+    updateStyleOptions(options: ITableStyle.StyleOptions): ITable;
+    /**
+     * Returns the current `ITableStyle` used.
+     */
+    getStyle(): ITableStyle;
+    /**
+     * Returns the table style resolved against this table's geometry, as a per-cell
+     * properties provider.
+     *
+     * @remarks
+     * The instance is memoized per table (and invalidated on any table or table-styles
+     * 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>;
+    /**
+     * Returns a cell style for the given coords.
+     * @param coords The absolute coords.
+     *
+     * @remarks
+     * This will return a CellStyle rendered with the table styling but not any other styling.
+     *
+     * * This is used by the preview.
+     */
+    getStyleAt(coords: IRange.CellCoords): IStyle;
+    /**
+     * Specifies if totals are being shown for the table.
+     */
+    isShowTotals(): boolean;
+    /**
+     * Specifies if totals are being shown for the table.
+     */
+    setShowTotals(showTotals: boolean, options?: ITransaction.OperationOptions): this;
+    /**
+     * Specifies if headers are being shown for the table.
+     */
+    isShowHeaders(): boolean;
+    /**
+     * Specifies if headers are being shown for the table.
+     */
+    setShowHeaders(showHeaders: boolean, options?: ITransaction.OperationOptions): this;
+    /**
+     * Specifies if first column is being highlighted.
+     */
+    isShowHighlightFirstColumn(): boolean;
+    /**
+     * Specifies if first column is being highlighted.
+     */
+    setShowHighlightFirstColumn(showHighlightFirstColumn: boolean, options?: ITransaction.OperationOptions): this;
+    /**
+     * Specifies if last column is being highlighted.
+     */
+    isShowHighlightLastColumn(): boolean;
+    /**
+     * Specifies if last column is being highlighted.
+     */
+    setShowHighlightLastColumn(showHighlightLastColumn: boolean, options?: ITransaction.OperationOptions): this;
+    /**
+     * Specifies if banded columns is being applied.
+     */
+    isShowBandedColumns(): boolean;
+    /**
+     * Specifies if banded columns is being applied.
+     */
+    setShowBandedColumns(showBandedColumns: boolean, options?: ITransaction.OperationOptions): this;
+    /**
+     * Specifies if banded rows is being applied.
+     */
+    isShowBandedRows(): boolean;
+    /**
+     * Specifies if banded rows is being applied.
+     */
+    setShowBandedRows(showBandedRows: boolean, options?: ITransaction.OperationOptions): this;
+    /**
+     * If true the table will not auto expand.
+     */
+    setDisabledAutoExpand(disabledAutoSize: boolean, options?: ITransaction.OperationOptions): this;
+    /**
+     * Returns if the table is set to not auto expand.
+     */
+    isDisabledAutoExpand(): boolean;
+    /**
+     * Returns the bounds for the ref accounting for hidden headers.
+     *
+     * @remarks
+     * This is used for borders and drag areas that are based on visible edges.
+     * excluding hidden rows/columns (headers).
+     */
+    getVisibleRefRangeCoords(): IRange.Coords;
+    /**
+     * Returns the coords after any hidden values are applied.
+     * @param coords The absolute coords
+     */
+    getVisibleCellCoords(coords: IRange.CellCoords): IRange.CellCoords;
+    /**
+     * Returns a flag indicating if the header is visible due to hidden headers.
+     *
+     * @remarks
+     * To know if the header flag is set use {@link isShowHeaders}
+     */
+    isHeaderVisible(): boolean;
+    /**
+     * Returns a flag indicating if the footer is visible due to hidden headers.
+     */
+    isTotalVisible(): boolean;
+    /**
+     * Returns a flag indicating if the first column is visible due to hidden headers.
+     */
+    isFirstColumnVisible(): boolean;
+    /**
+     * Returns a flag indicating if the first column is visible due to hidden headers.
+     */
+    isLastColumnVisible(): boolean;
+    /**
+     * Returns a snapshot of the table that can be used for copying and archiving.
+     */
+    getSnapshot(options?: ReferenceableClipboard.CopyOptions): ITable.ISnapshot;
+    /**
+     * Applied all filters using the existing criteria.
+     *
+     * @remarks
+     * Does not change criteria; only recomputes which rows are visible.
+     */
+    applyFilters(options?: ITransaction.OperationOptions): this;
+    /**
+     * Clears all filters.
+     */
+    deleteFilters(options?: ITransaction.OperationOptions): this;
+    /**
+     * Returns the active filter entries as handle objects,
+     */
+    getActiveFilters(): readonly IFilter[];
+    /**
+     * Returns the filter at the specified index, or null if none.
+     */
+    getFilterAt(index: number): IFilter | null;
+    /**
+     * Perform filtering on the table.
+     */
+    filter(conditions?: ICondition.Input | ICondition.RangeOptions, options?: ITransaction.OperationOptions): this;
+    /**
+     * Replaces the sort chain.
+     *
+     * @param options
+     * - `undefined` or no `sorts` → clears existing sort levels.
+     * - `sorts: []` → explicitly clears all sort levels.
+     * - `sorts: [...]` → replaces the sort levels (primary → secondary → ...).
+     */
+    sort(options?: ISort.RangeOptions & ITransaction.OperationOptions): this;
+    /**
+     * Returns the sort at the specified index.
+     *
+     * @returns
+     * A sort object (which may have a null criteria) or `null` if the
+     * index is invalid or the table is closed.
+     */
+    getSortAt(index: number): ISort | null;
+    /**
+     * Applies all sorts using the existing criteria.
+     *
+     * @remarks
+     * Does not change criteria; only recomputes order.
+     */
+    applySorts(options?: ITransaction.OperationOptions): this;
+    /**
+     * Deletes all sorts.
+     */
+    deleteSorts(options?: ITransaction.OperationOptions): this;
+    /**
+     * Returns the active sorts ordered by priority.
+     *
+     * @remarks
+     * These are ordered by priority (primary → secondary → ...).
+     */
+    getActiveSorts(): readonly ISort[];
+    /**
+     * Applies both applySorts and applyFilters.
+     */
+    applySortsAndFilters(options?: ITransaction.OperationOptions): this;
+    /**
+     * Deletes both sorts and filters.
+     */
+    deleteSortsAndFilters(options?: ITransaction.OperationOptions): this;
+    /**
+     * Sets whether the filter/sort button at the specified index is hidden.
+     */
+    setHiddenButtonAt(index: number, hidden: boolean): this;
+    /**
+     * Returns whether the filter/sort button at the specified index is hidden.
+     * @param index
+     */
+    isHiddenButtonAt(index: number): boolean;
+    /**
+     * If `hidden` is `true` then all filter/sort buttons are hidden.
+     */
+    setHiddenButtons(hidden: boolean): this;
+    /**
+     * This will only return `true` if all buttons are hidden.
+     */
+    isHiddenButtons(): boolean;
+    /**
+     * Add Listeners.
+     *
+     * @see
+     * {@link IListener.ISource.addListeners}
+     */
+    addListeners(listeners: ITable.IListeners, options?: IListener.Options): IListener.Remove;
+    /**
+     * @returns The current state as a JSON object or `null` if the table is closed.
+     */
+    toJSON(): ITable.JSON | null;
+    /**
+     * Returns the sheet the table is associated with.
+     */
+    getSheet(): ISheet | null;
+    /**
+     * The table's entry in the workbook's names, or `null` if it is not named.
+     *
+     * @remarks
+     * A table's name is *derived* — it exists because the table does. The name collection reads this
+     * rather than being handed a copy, so a deleted table stops being named without anything having
+     * to remove it.
+     */
+    getNamed(): INamed | null;
+    /**
+     * For runtime type checking.
+     */
+    readonly isITable: true;
+}
+//# sourceMappingURL=ITable.d.ts.map