@guiexpert/table 1.1.98 → 1.1.99

package/lib/table/spreadsheet/structure-edit.d.ts

@@ -0,0 +1,35 @@
+import { TableScope } from '../table-scope.js';
+import { CellChangeSource } from '../batch-edit/cell-change.if.js';
+
+/**
+ * Rows or columns inserted or deleted at a **physical** position (row number − 1, column letter index).
+ *
+ * @category Spreadsheet
+ * @since 1.1.99
+ */
+export interface StructureEditIf {
+    readonly kind: "insertRows" | "deleteRows" | "insertColumns" | "deleteColumns";
+    readonly at: number;
+    readonly count: number;
+}
+/**
+ * Inserts or deletes rows or columns with adjusted cell formulas (`=SUM(D2:D4)` → `=SUM(D2:D5)` after inserting a row
+ * inside, a deleted reference → `#REF!`), as **one** undo step and one `onModelChanged` (source `"structure"`).
+ * Rows: a spreadsheet, object rows (new objects from `clipboard.createRow`, otherwise `{}`; the app's array changes
+ * **in place**) and arrays; columns: a spreadsheet only. Not while a batch edit collects changes. Sorting and filters
+ * stay (the view is built again); the active cell stays inside the table.
+ *
+ * @param {TableScope} scope - the table
+ * @param {StructureEditIf} edit - what to change
+ * @param {{ record?: boolean, rows?: unknown[], source?: CellChangeSource }} [opts] - `record: false` = no undo step;
+ *        `rows`: the rows to insert (redo); `source` of the event
+ * @returns {boolean} true if changed
+ *
+ * @category Internals
+ * @since 1.1.99
+ */
+export declare function applyStructureEdit(scope: TableScope, edit: StructureEditIf, opts?: {
+    record?: boolean;
+    rows?: unknown[];
+    source?: CellChangeSource;
+}): boolean;

package/lib/table/table-api.d.ts

@@ -19,10 +19,14 @@ import { FormulaOptionsIf } from './formula/formula-options.if.js';
 import { FormulaError } from './formula/formula-error.js';
 import { RowDropTargetIf } from './row-drag/row-drop-target.if.js';
 import { CellChangeIf, CellChangeSource } from './batch-edit/cell-change.if.js';
+import { GeUndoEvent } from './data/common/event/ge-undo-event.js';
 import { CellValueChangeIf } from './batch-edit/cell-value-change.if.js';
 import { FillDirection } from './fill/fill-direction.type.js';
 import { FillMode } from './fill/fill-series.js';
 import { CellRange } from './data/common/cell-range.js';
+import { EventListenerIf } from './event-listener.if.js';
+import { ExcelExportOptionsIf } from './service/excel-export-options.if.js';
+import { SheetEngine } from './sheet/sheet-engine.js';
 
 /**
  * The public API of one table – everything you do with a table after it has been created:
@@ -839,8 +843,19 @@ export declare class TableApi {
      * @example
      * // Download table data with custom filename only
      * tableApi.downloadExcel('quarterly-data.xlsx');
+     *
+     * @example
+     * // cell formulas as Excel formulas (since 1.1.99, tableOptions.cellFormulas)
+     * tableApi.downloadExcel('budget.xlsx', '', { cellFormulas: true });
+     */
+    downloadExcel(fileName?: string, author?: string, exportOptions?: Partial<ExcelExportOptionsIf>): Promise<void>;
+    /**
+     * Where the data of a sheet start in the Excel file (rows above, columns in front) – `undefined` with a warning if
+     * the export is not the sheet: no cell formulas, a filter, sorting, a hidden data column or no formula support.
      */
-    downloadExcel(fileName?: string, author?: string): Promise<void>;
+    private getExcelFormulaOffset;
+    /** A body cell with a cell formula as Excel formula cell (`undefined` for other cells). */
+    private getExcelFormulaCell;
     /** The value of a cell for the Excel export – the shown number in a row number column (body; footer empty). */
     private getExportValue;
     /**
@@ -1502,6 +1517,8 @@ export declare class TableApi {
      *
      * @param {CellValueChangeIf[]} changes - display row index, column (index or property) and value per cell
      * @param {CellChangeSource} [source="api"] - reported in {@link GeModelChangeEvent.source}
+     * @param {{ undoable?: boolean }} [opts] - `undoable`: record the change for undo ({@link TableOptionsIf.undo}) – default:
+     *        `UndoOptionsIf.recordApiChanges` for `"api"`, recorded for the other sources (since 1.1.99)
      * @returns {CellChangeIf[]} the written (batch edit: newly pending) cells
      *
      * @example
@@ -1517,7 +1534,9 @@ export declare class TableApi {
      *
      * @since 1.1.96
      */
-    applyCellChanges(changes: CellValueChangeIf[], source?: CellChangeSource): CellChangeIf[];
+    applyCellChanges(changes: CellValueChangeIf[], source?: CellChangeSource, opts?: {
+        undoable?: boolean;
+    }): CellChangeIf[];
     /**
      * Fills cells next to a range – what dragging the fill handle does ({@link TableOptionsIf.fillHandle} is not
      * needed for this call): continues series (1, 2 → 3, 4; dates; `Item 1` → `Item 2`) or copies, writes with
@@ -1558,6 +1577,496 @@ export declare class TableApi {
      * @since 1.1.96
      */
     cancelFill(): void;
+    /**
+     * Adds an event listener next to the one the table was created with – e.g. for a toolbar or an own formula bar
+     * that lives outside the component that created the table. Every `on…` method you give is called after the main
+     * listener's; a listener that throws is logged and does not stop the others.
+     *
+     * @param {Partial<EventListenerIf>} listener - the events of interest
+     * @returns {() => void} call it to remove the listener (the table also removes all on `destroy()`)
+     *
+     * @example
+     * const unsubscribe = tableApi.subscribe({
+     *   onEditingChanged: (evt: GeEditEvent) => { hint.textContent = evt.type === "input" ? evt.input ?? "" : ""; },
+     *   onModelChanged: (evt: GeModelChangeEvent) => console.log(`${evt.changes?.length ?? 0} cells changed`),
+     * });
+     * // later
+     * unsubscribe();
+     *
+     * @since 1.1.99
+     */
+    subscribe(listener: Partial<EventListenerIf>): () => void;
+    /**
+     * Opens the cell editor of a body cell – like F2 (caret at the end) or, with `typedText`, like typing that text.
+     * With Excel-style editing ({@link TableOptionsIf.editing}) the editor sits above the cell; otherwise (or for
+     * columns with an own `getEditRenderer`) it is rendered into the cell.
+     *
+     * @param {number} rowIndex - display row index of the body
+     * @param {number | string} column - model column index or property
+     * @param {string} [typedText] - starts in "enter" mode with this text (it replaces the content)
+     * @returns {boolean} true if an editor is open (`false` for a cell that cannot be edited)
+     *
+     * @example
+     * tableApi.startEditing(0, "price");          // edit the price of the first row
+     * tableApi.startEditing(4, "name", "Ad");     // as if "Ad" had been typed
+     *
+     * @since 1.1.99
+     */
+    startEditing(rowIndex: number, column: number | string, typedText?: string): boolean;
+    /**
+     * Closes an open cell editor: commits its input (like Enter without moving) or, with `cancel`, discards it (like
+     * Escape).
+     *
+     * @param {boolean} [cancel=false] - discard the input
+     * @returns {boolean} true if no editor is open afterwards (an invalid input keeps the editor open)
+     *
+     * @example
+     * saveButton.addEventListener("click", () => {
+     *   tableApi.stopEditing();   // the value being typed belongs to the data that is saved
+     * });
+     *
+     * @since 1.1.99
+     */
+    stopEditing(cancel?: boolean): boolean;
+    /**
+     * True while a cell editor is open.
+     *
+     * @returns {boolean} true while editing
+     *
+     * @example
+     * if (!tableApi.isEditing()) {
+     *   tableApi.updateCells([], true);   // live data: don't repaint under the user's input
+     * }
+     *
+     * @since 1.1.99
+     */
+    isEditing(): boolean;
+    /**
+     * The cell whose editor is open.
+     *
+     * @returns {[number, number] | undefined} display row and model column, `undefined` without editor
+     *
+     * @example
+     * const cell = tableApi.getEditingCell();
+     * if (cell) console.log(`editing row ${cell[0]}, column ${cell[1]}`);
+     *
+     * @since 1.1.99
+     */
+    getEditingCell(): [number, number] | undefined;
+    /**
+     * Clears body cells like Delete in Excel-style editing: editable cells get their empty value
+     * ({@link ColumnDefIf.emptyValue}, default `""`), **one** `onModelChanged` with the source `"clear"` (batch edit:
+     * marked). Works without {@link TableOptionsIf.editing} too.
+     *
+     * @param {CellRange[]} [ranges] - body ranges; default: the selected cells, or the focused cell
+     * @returns {number} the number of cleared cells, `-1` if there were too many (`EditingOptionsIf.maxClearCells`)
+     *
+     * @example
+     * tableApi.clearCells([new CellRange(0, 2, 9, 2)]);   // rows 0–9 of column 2
+     *
+     * @since 1.1.99
+     */
+    clearCells(ranges?: CellRange[]): number;
+    /**
+     * Copies the selected cells (the last selected range, everything after Ctrl/⌘+A, otherwise the focused cell) with
+     * the asynchronous clipboard API – for an own button or menu. Tab-separated text with Excel's quoting plus an HTML
+     * table (`ClipboardOptionsIf.html`); pasting it into this table pastes the values. The browser may ask for
+     * permission; Ctrl/⌘+C needs none ({@link TableOptionsIf.clipboard}). Works without the option (defaults).
+     *
+     * @returns {Promise<void>} resolves when the clipboard was written
+     *
+     * @example
+     * copyButton.addEventListener("click", () => tableApi.copySelection());
+     *
+     * @since 1.1.99
+     */
+    copySelection(): Promise<void>;
+    /**
+     * Like {@link copySelection}, and the cells are marked (dashed frame): the next paste of this content moves them –
+     * the cut cells are emptied in the same change (`source: "cut"`). Escape or another change removes the mark.
+     *
+     * @returns {Promise<void>} resolves when the clipboard was written
+     *
+     * @example
+     * cutButton.addEventListener("click", () => tableApi.cutSelection());
+     *
+     * @since 1.1.99
+     */
+    cutSelection(): Promise<void>;
+    /**
+     * Pastes tab-separated text like Ctrl/⌘+V – without clipboard permissions: from `target` (once), otherwise from the
+     * selection (tiled over a selected range that is an integer multiple, one value into every selected cell) or the
+     * focused cell. Hidden columns are skipped, read-only cells left out, the rest is cut off at the last column;
+     * **one** `onModelChanged` with `source: "paste"` (batch edit: marked). Works without {@link TableOptionsIf.clipboard}.
+     *
+     * @param {string} text - rows separated by line breaks, cells by tabs (quoted cells like Excel)
+     * @param {[number, number] | undefined} [target] - display row and model column of the first cell
+     * @returns {CellChangeIf[]} the written (batch edit: newly pending) cells
+     *
+     * @example
+     * tableApi.pasteText("a\tb\n1\t2", [0, 1]);   // A 2×2 block from row 0, column 1
+     *
+     * @since 1.1.99
+     */
+    pasteText(text: string, target?: [number, number]): CellChangeIf[];
+    /**
+     * The selected cells as tab-separated text, exactly as Ctrl/⌘+C copies them (Excel's quoting, `copyHeaders`,
+     * `copyValue`). `""` without cells or with more than `CopyService.maxCopyCells`.
+     *
+     * @returns {string} the text
+     *
+     * @example
+     * console.log(tableApi.getSelectionAsText());   // "a\tb\n1\t2"
+     *
+     * @since 1.1.99
+     */
+    getSelectionAsText(): string;
+    /**
+     * Removes the mark of cut cells (like Escape): the next paste copies instead of moving.
+     *
+     * @example
+     * tableApi.cancelCut();
+     *
+     * @since 1.1.99
+     */
+    cancelCut(): void;
+    /**
+     * Undoes the last change like Ctrl/⌘+Z ({@link TableOptionsIf.undo}): the old values are written back
+     * (`onModelChanged` with source `"undo"`), the cells are selected and scrolled into view. Not while the cell editor
+     * is open (it has its own text undo).
+     *
+     * @returns {boolean} true if a step was undone; false without the option or with nothing to undo
+     *
+     * @example
+     * undoButton.addEventListener("click", () => tableApi.undo());
+     *
+     * @since 1.1.99
+     */
+    undo(): boolean;
+    /**
+     * Redoes the last undone change like Ctrl+Y / Ctrl/⌘+Shift+Z (source `"redo"`).
+     *
+     * @returns {boolean} true if a step was redone
+     *
+     * @example
+     * redoButton.addEventListener("click", () => tableApi.redo());
+     *
+     * @since 1.1.99
+     */
+    redo(): boolean;
+    /**
+     * True if there is a change to undo – for buttons (or listen to `onUndoStackChanged`).
+     *
+     * @returns {boolean} true if {@link undo} would undo something
+     *
+     * @example
+     * undoButton.disabled = !tableApi.canUndo();
+     *
+     * @since 1.1.99
+     */
+    canUndo(): boolean;
+    /**
+     * True if there is an undone change to redo.
+     *
+     * @returns {boolean} true if {@link redo} would redo something
+     *
+     * @example
+     * redoButton.disabled = !tableApi.canRedo();
+     *
+     * @since 1.1.99
+     */
+    canRedo(): boolean;
+    /**
+     * Empties the undo history (e.g. after saving or loading new data).
+     *
+     * @example
+     * await save(rows);
+     * tableApi.clearUndoHistory();
+     *
+     * @since 1.1.99
+     */
+    clearUndoHistory(): void;
+    /**
+     * The state of the undo history (what `onUndoStackChanged` reports).
+     *
+     * @returns {GeUndoEvent | undefined} can undo/redo, labels, size; `undefined` without the option
+     *
+     * @example
+     * const state = tableApi.getUndoState();
+     * undoButton.title = state?.undoLabel ? `Undo ${state.undoLabel}` : "Undo";
+     *
+     * @since 1.1.99
+     */
+    getUndoState(): GeUndoEvent | undefined;
+    /**
+     * Records all changes `fn` makes (several {@link applyCellChanges} calls, a fill and a paste …) as **one** undo step.
+     * Without the option `fn` just runs.
+     *
+     * @param {string} label - the label of the step ("Undo Import")
+     * @param {() => T} fn - the changes
+     * @returns {T} what `fn` returns
+     *
+     * @example
+     * tableApi.batchUndoable("Import", () => {
+     *   tableApi.applyCellChanges(firstChanges, "api", { undoable: true });
+     *   tableApi.applyCellChanges(secondChanges, "api", { undoable: true });
+     * });
+     *
+     * @since 1.1.99
+     */
+    batchUndoable<T>(label: string, fn: () => T): T;
+    /**
+     * True if the table calculates cell formulas ({@link TableOptionsIf.cellFormulas}, flat body).
+     *
+     * @returns {boolean} whether cell formulas are on
+     *
+     * @example
+     * const showAddresses = tableApi.hasCellFormulas();
+     *
+     * @since 1.1.99
+     */
+    hasCellFormulas(): boolean;
+    /**
+     * The address of a body cell in cell formulas: `"B3"` = second data column, third row of `getAllRows()` (the
+     * physical row – sorting and filtering don't change it). `undefined` without cell formulas or for a row number or
+     * checkbox column.
+     *
+     * @param {number} rowIndex - display row
+     * @param {number | string} column - model column index or property
+     * @returns {string | undefined} the address
+     *
+     * @example
+     * tableApi.getCellAddress(1, "total");   // "D2" – the second row of getAllRows()
+     *
+     * @since 1.1.99
+     */
+    getCellAddress(rowIndex: number, column: number | string): string | undefined;
+    /**
+     * The body cell of an address (`"B3"`, `"$B$3"`): display row (`-1` if a filter hides it) and model column;
+     * `undefined` without cell formulas or for an address outside the data.
+     *
+     * @param {string} address - the address
+     * @returns {[number, number] | undefined} display row and model column
+     *
+     * @example
+     * const cell = tableApi.getCellByAddress("D5");
+     * if (cell && cell[0] >= 0) tableApi.scrollToIndex(cell[1], cell[0]);
+     *
+     * @since 1.1.99
+     */
+    getCellByAddress(address: string): [number, number] | undefined;
+    /**
+     * The input of a body cell – what was typed: the formula text of a cell formula (`"=B2*C2"`), otherwise the value.
+     *
+     * @param {number} rowIndex - display row
+     * @param {number | string} column - model column index or property
+     * @returns {unknown} the input
+     *
+     * @example
+     * tableApi.getCellInput(1, "total");   // "=B2*C2"
+     *
+     * @since 1.1.99
+     */
+    getCellInput(rowIndex: number, column: number | string): unknown;
+    /**
+     * The value of a body cell – the result of a cell formula (`2598`), otherwise the value (= `getValueAt`).
+     *
+     * @param {number} rowIndex - display row
+     * @param {number | string} column - model column index or property
+     * @returns {unknown} the value
+     *
+     * @example
+     * tableApi.getCellValue(1, "total");   // 2598
+     *
+     * @since 1.1.99
+     */
+    getCellValue(rowIndex: number, column: number | string): unknown;
+    /**
+     * Writes the input of a body cell (a value or a formula `"=B2*C2"`) like the editor: one {@link applyCellChanges}.
+     *
+     * @param {number} rowIndex - display row
+     * @param {number | string} column - model column index or property
+     * @param {unknown} input - the input
+     * @returns {boolean} true if written (or marked in a batch edit)
+     *
+     * @example
+     * tableApi.setCellInput(4, "total", "=SUM(D2:D4)");
+     *
+     * @since 1.1.99
+     */
+    setCellInput(rowIndex: number, column: number | string, input: unknown): boolean;
+    /**
+     * Calculates a formula once against the sheet (not stored), e.g. for a preview: `"=SUM(D2:D4)"`.
+     * `undefined` without cell formulas.
+     *
+     * @param {string} source - the formula (the `=` is optional)
+     * @returns {unknown} the result (a {@link FormulaError} for an error)
+     *
+     * @example
+     * tableApi.evaluateFormula("=SUM(D2:D4)");   // 3895
+     *
+     * @since 1.1.99
+     */
+    evaluateFormula(source: string): unknown;
+    /**
+     * The value of a cell by its address – also of a row a filter hides. `undefined` without cell formulas.
+     *
+     * @param {string} address - e.g. `"D5"`
+     * @returns {unknown} the value
+     *
+     * @example
+     * tableApi.getSheetValue("D5");   // 3895
+     *
+     * @since 1.1.99
+     */
+    getSheetValue(address: string): unknown;
+    /**
+     * Calculates all cell formulas again – after the app changed the data without the table ({@link updateCells},
+     * {@link applyCellChanges} and the editor recalculate by themselves; {@link repaint} does not). Also renews
+     * `TODAY()`, `NOW()` and `RAND()`.
+     *
+     * @example
+     * rows[3].price = 30;          // changed outside the table
+     * tableApi.recalculate();
+     *
+     * @since 1.1.99
+     */
+    recalculate(): void;
+    /**
+     * The cells and ranges a cell formula reads, as addresses.
+     *
+     * @param {number} rowIndex - display row
+     * @param {number | string} column - model column index or property
+     * @returns {string[]} e.g. `["B2", "C2"]` (empty for a value cell or without cell formulas)
+     *
+     * @example
+     * tableApi.getPrecedents(1, "total");   // ["B2", "C2"]
+     *
+     * @since 1.1.99
+     */
+    getPrecedents(rowIndex: number, column: number | string): string[];
+    /**
+     * The cells whose formulas read a cell directly (display row, model column; rows a filter hides are left out).
+     *
+     * @param {number} rowIndex - display row
+     * @param {number | string} column - model column index or property
+     * @returns {Array<[number, number]>} the dependent cells
+     *
+     * @example
+     * tableApi.getDependents(1, "price");   // [[1, 3]] – D2 reads B2
+     *
+     * @since 1.1.99
+     */
+    getDependents(rowIndex: number, column: number | string): Array<[number, number]>;
+    /**
+     * The formula engine of the cell formulas (`undefined` without them) – physical rows, data columns.
+     *
+     * @returns {SheetEngine | undefined} the engine
+     *
+     * @example
+     * tableApi.getSheetEngine()?.getFormulaCount();   // 4
+     *
+     * @since 1.1.99
+     */
+    getSheetEngine(): SheetEngine | undefined;
+    /**
+     * The active body cell (the focused cell), `undefined` if there is none or the header has the focus.
+     *
+     * @returns {[number, number] | undefined} display row and model column
+     *
+     * @example
+     * const cell = tableApi.getActiveCell();
+     * if (cell) console.log(tableApi.getCellAddress(cell[0], cell[1]));   // "B3"
+     *
+     * @since 1.1.99
+     */
+    getActiveCell(): [number, number] | undefined;
+    /**
+     * Goes to a cell or range of the sheet by its address (cell formulas): `"D10"` makes it the active cell, `"B2:C5"`
+     * selects the range (its first cell becomes active); the view scrolls to it. `false` for an invalid address, one
+     * outside the data or a row a filter hides.
+     *
+     * @param {string} address - e.g. `"D10"`, `"$B$2:C5"`
+     * @returns {boolean} true if it went there
+     *
+     * @example
+     * tableApi.goToAddress("B2:C5");
+     *
+     * @since 1.1.99
+     */
+    goToAddress(address: string): boolean;
+    /**
+     * Inserts empty rows before a row of the sheet (`at` = row number − 1, the physical row: also when sorted or
+     * filtered) and adjusts the cell formulas (`=SUM(D2:D4)` grows when rows are inserted inside). One undo step, one
+     * `onModelChanged` (source `"structure"`). Works for a spreadsheet ({@link SpreadsheetFactory}), object rows (new
+     * objects from `clipboard.createRow`, otherwise `{}` – the app's array changes in place) and arrays.
+     *
+     * @param {number} at - the physical row the new rows come before (row count = append)
+     * @param {number} [count=1] - rows
+     * @returns {boolean} true if inserted
+     *
+     * @example
+     * tableApi.insertRows(4, 2);   // two empty rows before row 5
+     *
+     * @since 1.1.99
+     */
+    insertRows(at: number, count?: number): boolean;
+    /**
+     * Deletes rows of the sheet (`at` = row number − 1) and adjusts the cell formulas (a deleted reference becomes
+     * `#REF!`). One undo step.
+     *
+     * @param {number} at - the first physical row
+     * @param {number} [count=1] - rows
+     * @returns {boolean} true if deleted
+     *
+     * @example
+     * tableApi.deleteRows(2);   // row 3
+     *
+     * @since 1.1.99
+     */
+    deleteRows(at: number, count?: number): boolean;
+    /**
+     * Inserts empty columns before a column of a spreadsheet ({@link SpreadsheetFactory}; `at` = letter index, A = 0)
+     * and adjusts the cell formulas. One undo step.
+     *
+     * @param {number} at - the data column the new columns come before
+     * @param {number} [count=1] - columns
+     * @returns {boolean} true if inserted (`false` for other models)
+     *
+     * @example
+     * tableApi.insertColumns(1);   // a new column B
+     *
+     * @since 1.1.99
+     */
+    insertColumns(at: number, count?: number): boolean;
+    /**
+     * Deletes columns of a spreadsheet (`at` = letter index, A = 0) and adjusts the cell formulas. One undo step.
+     *
+     * @param {number} at - the first data column
+     * @param {number} [count=1] - columns
+     * @returns {boolean} true if deleted (`false` for other models)
+     *
+     * @example
+     * tableApi.deleteColumns(2);   // column C
+     *
+     * @since 1.1.99
+     */
+    deleteColumns(at: number, count?: number): boolean;
+    /**
+     * The inputs of a spreadsheet ({@link SpreadsheetFactory}) as rows × columns – formulas as text, up to the last
+     * filled row and column (empty cells `""`). Save them; `SpreadsheetFactory.create({ data })` loads them again.
+     * `undefined` for other models (their data are the app's rows).
+     *
+     * @returns {unknown[][] | undefined} the data
+     *
+     * @example
+     * localStorage.setItem("sheet", JSON.stringify(tableApi.getSheetData()));
+     *
+     * @since 1.1.99
+     */
+    getSheetData(): unknown[][] | undefined;
+    /** A column index or property → index (`-1` if unknown). */
+    private toColumnIndex;
     /**
      * Expands or collapses the detail row of a master row (master/detail, {@link TableOptionsIf.masterDetail}). The
      * content is created when the detail row becomes visible; collapsing destroys it. Reports