@guiexpert/table 1.1.98 → 1.1.100

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

@@ -44,6 +44,12 @@ import { FillDirection } from './fill/fill-direction.type.js';
 import { FillMode } from './fill/fill-series.js';
 import { CellRange } from './data/common/cell-range.js';
 import { AriaTextsIf } from './aria/aria-texts.if.js';
+import { EditingOptionsIf } from './sheet-editing/editing-options.if.js';
+import { CellEditMode } from './sheet-editing/cell-editor.if.js';
+import { ClipboardService } from './clipboard/clipboard-service.js';
+import { UndoOptionsIf } from './undo/undo-options.if.js';
+import { UndoService } from './undo/undo-service.js';
+import { ShortcutActionIdMapping } from './action/shortcut-actionid-mapping.type.js';
 
 /**
  * Creates and runs one table in a host element – the core that every framework wrapper uses.
@@ -124,6 +130,20 @@ export declare class TableScope extends RenderScope implements OnActionTriggered
     private firstDraggingRendering;
     /** Last comparator passed to `sort()`; re-applied after filtering. Cleared by a header sort. */
     private lastSortCompareFn?;
+    /** Excel-style editing (`tableOptions.editing`), `undefined` = off. @since 1.1.99 */
+    private readonly editingOptions?;
+    /** Listeners of {@link TableApi.subscribe}. @since 1.1.99 */
+    private readonly subscribers;
+    /** Copy, cut and paste (`tableOptions.clipboard`), `undefined` = off. @since 1.1.99 */
+    private readonly clipboardOptions?;
+    /** Copy, cut and paste: with the option keys and events, otherwise created for the API. @since 1.1.99 */
+    clipboardService?: ClipboardService;
+    /** Undo and redo (`tableOptions.undo`), `undefined` = off. @since 1.1.99 */
+    private readonly undoOptions?;
+    /** Undo and redo: records the changes of the write path (only with the option). @since 1.1.99 */
+    undoService?: UndoService;
+    /** The key event the {@link ShortcutService} is handling right now (`undefined` for `triggerAction`). @since 1.1.99 */
+    shortcutKeyEvent?: KeyboardEvent;
     constructor(hostElement: HTMLDivElement, tableModel: TableModelIf, domService: DomServiceIf, tableOptions: TableOptionsIf, eventListener: EventListenerIf, copyService?: CopyServiceIf, excelService?: ExcelServiceIf);
     /**
      * The options of a nested table (master/detail `ctx.createTable()`): as given; without an own `direction` in a
@@ -159,6 +179,154 @@ export declare class TableScope extends RenderScope implements OnActionTriggered
      * @return {boolean} - Returns true if the action was triggered successfully, false otherwise.
      */
     onActionTriggered(actionId: ActionId): boolean;
+    /**
+     * The options of Excel-style editing ({@link TableOptionsIf.editing}), `undefined` if it is off.
+     *
+     * @returns {EditingOptionsIf | undefined} complete options
+     * @since 1.1.99
+     */
+    getEditingOptions(): EditingOptionsIf | undefined;
+    /**
+     * Shortcut layers of switched-on features, applied over the system mapping (see {@link ShortcutService}).
+     *
+     * @param {boolean} mac - macOS keys
+     * @returns {ShortcutActionIdMapping[]} the layers (none without Excel-style editing)
+     * @since 1.1.99
+     */
+    getShortcutLayers(mac: boolean): ShortcutActionIdMapping[];
+    /**
+     * Adds a listener next to the one given to the constructor (see {@link TableApi.subscribe}).
+     *
+     * @param {Partial<EventListenerIf>} listener - the events of interest
+     * @returns {() => void} removes the listener again
+     * @since 1.1.99
+     */
+    subscribe(listener: Partial<EventListenerIf>): () => void;
+    /**
+     * Opens the cell editor of a body cell: the editor above the cell (Excel-style editing) or – for columns with an
+     * own `getEditRenderer`, and without `tableOptions.editing` – the editor inside the cell.
+     *
+     * @param {number} rowIndex - display row index
+     * @param {number} columnIndex - model column index
+     * @param {CellEditMode} [mode="edit"] - "edit" (F2, Enter, double click) or "enter" (typing)
+     * @param {"all" | "end"} [textSelection] - select the text or put the caret at the end (default: the option)
+     * @returns {boolean} true if an editor is open
+     * @since 1.1.99
+     */
+    startEditing(rowIndex: number, columnIndex: number, mode?: CellEditMode, textSelection?: 'all' | 'end'): boolean;
+    /** True if a new editor may open now: no header focus, no blocking overlay, no running drag or fill. @since 1.1.99 */
+    canStartEditing(): boolean;
+    /**
+     * The value a body cell shows: a pending value of a batch edit, otherwise the model value – with cell formulas the
+     * input ({@link getCellInput}: the formula text for the editor).
+     *
+     * @param {number} rowIndex - display row index
+     * @param {number} columnIndex - model column index
+     * @returns {unknown} the value
+     * @since 1.1.99
+     */
+    getShownCellValue(rowIndex: number, columnIndex: number): unknown;
+    /** The body cell with the keyboard focus, `undefined` if there is none (or the header has the focus). @since 1.1.99 */
+    getActiveBodyCell(): [number, number] | undefined;
+    /**
+     * Builds the view again after rows or columns were inserted or deleted (filter and sorting applied again, new
+     * columns measured).
+     *
+     * @param {boolean} columns - true: the columns changed
+     * @since 1.1.99
+     */
+    refreshAfterStructureChange(columns: boolean): void;
+    /**
+     * The next shown column in a direction (hidden columns skipped; the same column at the edge).
+     *
+     * @param {number} columnIndex - model column index
+     * @param {number} direction - 1 or -1
+     * @returns {number} the column
+     * @since 1.1.99
+     */
+    nextShownColumn(columnIndex: number, direction: number): number;
+    /**
+     * True if there is a shown column (no row number column) next to `columnIndex` in that direction – Tab uses it:
+     * in the last column it leaves the table.
+     *
+     * @param {number} columnIndex - model column index
+     * @param {number} direction - 1 or -1
+     * @returns {boolean} true if Tab can move
+     * @since 1.1.99
+     */
+    hasShownColumnBeside(columnIndex: number, direction: number): boolean;
+    /**
+     * Moves the keyboard focus from a cell by rows/columns (Excel-style editing: Enter, Tab and arrow keys after
+     * committing); the selection follows with `collapseSelectionOnNavigate`.
+     *
+     * @param {number} rowIndex - start row
+     * @param {number} columnIndex - start column
+     * @param {number} dRow - rows
+     * @param {number} dColumn - columns (hidden columns are skipped)
+     * @returns {boolean} true if a focus model exists
+     * @since 1.1.99
+     */
+    moveActiveCell(rowIndex: number, columnIndex: number, dRow: number, dColumn: number): boolean;
+    /**
+     * The selected body cells (shown columns, inside the table) – `undefined` if there are more than `maxCells`.
+     *
+     * @param {number} maxCells - upper limit
+     * @returns {Array<[number, number]> | undefined} row and column per cell; none without selection
+     * @since 1.1.99
+     */
+    getSelectedBodyCells(maxCells: number): Array<[number, number]> | undefined;
+    /**
+     * The body cells of the selection (or of `given` ranges): clamped to the table, shown columns without row number
+     * column, each cell once – `undefined` if there are more than `maxCells` (checked before the cells are visited).
+     */
+    private collectSelectedBodyCells;
+    /**
+     * Clears body cells (Delete in Excel-style editing): editable cells get `ColumnDef.emptyValue` (default
+     * `EditingOptionsIf.emptyValue`, `""`), cells that are already empty are left alone; **one** `onModelChanged` with
+     * the source `"clear"`. Without `ranges`: the selected cells, or the focused cell.
+     *
+     * @param {CellRange[]} [ranges] - body ranges (display indices)
+     * @returns {number} the number of cleared cells; `-1` if more than `maxClearCells`
+     * @since 1.1.99
+     */
+    clearCells(ranges?: CellRange[]): number;
+    /**
+     * Writes the value of the editor above the cell (Excel-style editing): into one cell, or – Ctrl/⌘+Enter – into
+     * several; batch edit: marks it. Used by {@link CellEditorService}.
+     *
+     * @param {Array<[number, number]>} cells - display row and model column per cell
+     * @param {unknown} value - the editor value (it runs through `editInputPipe` and `validate`)
+     * @param {boolean} deferRepaint - repaint after the current mouse click
+     * @returns {{ written: number, invalid: number, message?: string }} what happened
+     * @since 1.1.99
+     */
+    commitCellEditor(cells: Array<[number, number]>, value: unknown, deferRepaint: boolean): {
+        written: number;
+        invalid: number;
+        message?: string;
+    };
+    /**
+     * Space on a cell with a `true`/`false` value (Excel-style editing): writes the opposite value.
+     *
+     * @param {number} rowIndex - display row index
+     * @param {number} columnIndex - model column index
+     * @since 1.1.99
+     */
+    toggleBooleanCell(rowIndex: number, columnIndex: number): void;
+    /** The texts of Excel-style editing (own functions of `tableOptions.ariaTexts`, otherwise English). @since 1.1.99 */
+    getSheetTexts(): Required<Pick<AriaTextsIf, 'editingStarted' | 'readOnlyCell' | 'cellsCleared' | 'clearTooLarge' | 'rangeSelected' | 'rowSelected' | 'columnSelected' | 'gridEditingHint' | 'cellsPasted' | 'pasteTooLarge' | 'copyTooLarge' | 'cutMarked' | 'copiedLastRangeOnly'>>;
+    /** The keys of Excel-style editing that are ActionIds (Tab, Shift+arrows, Ctrl+arrows, Delete …). */
+    private onSheetAction;
+    /** The moving corner of the selected range (Shift+arrows), the active cell if there is none. */
+    private getSelectionExtent;
+    /** The first shown column that is no row number column. */
+    private getFirstShownDataColumnIndex;
+    /** Ctrl+arrow: Excel's edge of the data block from a cell (shown columns, no row number column). */
+    private dataEdge;
+    /** Shift+arrows: the range from the anchor to `(row, column)`, scrolled into view and announced. */
+    private extendSelectionTo;
+    /** Shift+Space / Ctrl+Space: the rows (columns) of the last range or of the active cell. */
+    private selectWholeRowsOrColumns;
     /**
      * The event listener of this table (the one given to the constructor, or an empty {@link EventAdapter}).
      *
@@ -227,6 +395,8 @@ export declare class TableScope extends RenderScope implements OnActionTriggered
     getHeaderFocus(): [number, number] | undefined;
     /** Moves the body focus to a cell, scrolls it into view and repaints (also leaves the header). */
     private setFocusCell;
+    /** Excel-style editing: the keyboard moved the active cell – it becomes the selection and the anchor. */
+    private afterActiveCellMoved;
     private getFirstShownColumnIndex;
     private getLastShownColumnIndex;
     /** Home, End, Ctrl+Home, Ctrl+End, Page Up/Down and Enter in the body; `undefined` = not such an action. */
@@ -273,7 +443,9 @@ export declare class TableScope extends RenderScope implements OnActionTriggered
      * @returns {CellChangeIf[]} the written (or, in a batch edit, newly pending) cells
      * @since 1.1.96
      */
-    applyCellChanges(changes: CellValueChangeIf[], source?: CellChangeSource): CellChangeIf[];
+    applyCellChanges(changes: CellValueChangeIf[], source?: CellChangeSource, opts?: {
+        undoable?: boolean;
+    }): CellChangeIf[];
     /**
      * Writes cell values directly (no batch edit) – used by {@link applyCellChanges} and the batch commit.
      *
@@ -293,6 +465,122 @@ export declare class TableScope extends RenderScope implements OnActionTriggered
         skipValidation?: boolean;
     }): CellChangeIf[];
     private writeCellsInternal;
+    /**
+     * Writes pasted cells (copy, cut and paste): like {@link applyCellChanges} – not editable cells skipped, `validate`,
+     * batch edit marks – with **one** `onModelChanged`; `raw` = values copied inside the table (no `editInputPipe`).
+     *
+     * @param {CellValueChangeIf[]} changes - target cells (and emptied cut cells)
+     * @param {CellChangeSource} source - `"paste"` or `"cut"`
+     * @param {boolean} raw - true: without `editInputPipe`
+     * @returns {CellChangeIf[]} the written (batch edit: newly pending) cells
+     * @since 1.1.99
+     */
+    writePastedCells(changes: CellValueChangeIf[], source: CellChangeSource, raw: boolean): CellChangeIf[];
+    /**
+     * Selects a body range (after pasting): its first cell becomes the active cell and the anchor.
+     *
+     * @param {CellRange} range - display rows, model columns
+     * @since 1.1.99
+     */
+    selectBodyRange(range: CellRange): void;
+    /**
+     * The message of the column's `validate` for a value that would be pasted, `undefined` if it is valid.
+     *
+     * @param {number} rowIndex - display row
+     * @param {number} columnIndex - model column
+     * @param {unknown} value - the value
+     * @param {boolean} raw - true: without `editInputPipe`
+     * @returns {string | undefined} the message
+     * @since 1.1.99
+     */
+    checkPastedValue(rowIndex: number, columnIndex: number, value: unknown, raw: boolean): string | undefined;
+    /**
+     * The input of a body cell – what was typed: the formula text of a cell formula (`"=B2*C2"`), otherwise the value
+     * ({@link AreaModelIf.getInputValueAt}). Editor, undo and the batch edit use it.
+     *
+     * @param {number} rowIndex - display row
+     * @param {number} columnIndex - model column
+     * @returns {unknown} the input
+     * @since 1.1.99
+     */
+    getCellInput(rowIndex: number, columnIndex: number): unknown;
+    /**
+     * The value of a body cell to choose an editor or convert pasted text by: the result of a formula cell (a number
+     * stays a number when overwritten), otherwise {@link getShownCellValue}.
+     *
+     * @param {number} rowIndex - display row
+     * @param {number} columnIndex - model column
+     * @returns {unknown} the value
+     * @since 1.1.99
+     */
+    getTypedCellValue(rowIndex: number, columnIndex: number): unknown;
+    /**
+     * The announcement of a stored formula with a syntax error (`AriaTextsIf.formulaError`).
+     *
+     * @param {string} message - the parser's message
+     * @returns {string} the text
+     * @since 1.1.99
+     */
+    getFormulaErrorText(message: string): string;
+    /** A syntax error of a formula refuses it only with `rejectInvalidFormulas` (otherwise it is stored: `#ERROR!`). */
+    private checkFormulaSyntax;
+    /**
+     * Resolves a formula copied inside the table for a target cell: its relative references move (Excel); a target
+     * without formulas gets the copied value. A cut formula moves unchanged.
+     *
+     * @param {unknown} value - a pasted value (maybe a {@link CopiedFormula})
+     * @param {number} rowIndex - display row of the target
+     * @param {number} columnIndex - model column of the target
+     * @param {boolean} cut - true: the formula moves (cut and paste)
+     * @returns {unknown} the value to write
+     * @since 1.1.99
+     */
+    resolvePastedValue(value: unknown, rowIndex: number, columnIndex: number, cut: boolean): unknown;
+    /**
+     * The value of a cell for a copy inside the table: a formula cell gives a {@link CopiedFormula}.
+     *
+     * @param {number} rowIndex - display row
+     * @param {number} columnIndex - model column
+     * @returns {unknown} the value
+     * @since 1.1.99
+     */
+    getCopyValue(rowIndex: number, columnIndex: number): unknown;
+    /** True while a batch edit collects changes. @since 1.1.99 */
+    isBatchEditActive(): boolean;
+    /** The options of undo and redo ({@link TableOptionsIf.undo}), `undefined` if it is off. @since 1.1.99 */
+    getUndoOptions(): UndoOptionsIf | undefined;
+    /**
+     * Writes the values of an undo or redo: without `editInputPipe` (the values were piped already) and validation, only
+     * editable cells; cells of hidden rows (`hidden`, written into their objects already) in the same event; no new
+     * step.
+     *
+     * @param {{ rowIndex: number, columnIndex: number, value: unknown }[]} cells - shown cells
+     * @param {CellChangeIf[]} hidden - cells of rows a filter hides
+     * @param {"undo" | "redo"} source - reported in the event
+     * @returns {CellChangeIf[]} the written cells (including `hidden`)
+     * @since 1.1.99
+     */
+    writeUndoCells(cells: {
+        rowIndex: number;
+        columnIndex: number;
+        value: unknown;
+    }[], hidden: CellChangeIf[], source: 'undo' | 'redo'): CellChangeIf[];
+    /** The texts of undo and redo (own functions of `tableOptions.ariaTexts`, otherwise English). @since 1.1.99 */
+    getUndoTexts(): Required<Pick<AriaTextsIf, 'undone' | 'redone' | 'nothingToUndo' | 'nothingToRedo' | 'undoSkipped' | 'undoHistoryCleared'>>;
+    /** True while an overlay blocks the table ("Loading…"). @since 1.1.99 */
+    isOverlayBlocking(): boolean;
+    /** Rows were added at the end of the body (pasting with `pasteAddsRows`): derived values are recomputed. @since 1.1.99 */
+    rowsAppended(): void;
+    /** True for a tree, a row grouping or a pivot table in the body (rows cannot simply be appended). @since 1.1.99 */
+    isRowGroupingOrTree(): boolean;
+    /**
+     * The clipboard service for the API ({@link TableApi.pasteText}, {@link TableApi.getSelectionAsText}): the one of
+     * the option, otherwise one with the defaults that does not listen to keys or events.
+     *
+     * @returns {ClipboardService} the service
+     * @since 1.1.99
+     */
+    getClipboardService(): ClipboardService;
     /** Marks values as pending (batch edit): pipe, validation, then the batch edit service. */
     private markPending;
     /**
@@ -326,6 +614,11 @@ export declare class TableScope extends RenderScope implements OnActionTriggered
      * @since 1.1.96
      */
     fillRange(source: CellRange, direction: FillDirection, count: number, mode?: FillMode, selectAfter?: CellRange): number;
+    /**
+     * Cell formulas (since 1.1.99): a filled cell whose source cell (the source repeats) holds a formula gets the formula
+     * with moved references (Excel: `=B2*C2` → `=B3*C3`, `$B$1` stays) instead of a series value.
+     */
+    private moveFilledFormulas;
     /** The last selected range, clamped to the body (`undefined` without one). */
     getFillSourceRange(): CellRange | undefined;
     private normalizeRange;

package/lib/table/undo/cell-changes-undoable.d.ts

@@ -0,0 +1,34 @@
+import { TableScope } from '../table-scope.js';
+import { CellChangeIf, CellChangeSource } from '../batch-edit/cell-change.if.js';
+import { UndoableIf, UndoResultIf } from './undoable.if.js';
+
+/**
+ * A step of written cells (an edit, a fill, a paste …): undo writes the old values back, redo the new ones. The cells
+ * are found by row **object** and property – sorting and filtering in between don't matter; a row a filter hides is
+ * written directly into its object (reported in the same event), a row that left the model is skipped. A cell that
+ * no longer has the expected value is skipped (`onConflict: "skip"`) or overwritten.
+ *
+ * @category Spreadsheet
+ * @since 1.1.99
+ */
+export declare class CellChangesUndoable implements UndoableIf {
+    readonly label: string;
+    readonly source: CellChangeSource;
+    private readonly entries;
+    /**
+     * @param {string} label - for buttons and announcements
+     * @param {CellChangeSource} source - what started the step
+     * @param {CellChangeIf[]} changes - the written cells (`GeModelChangeEvent.changes`)
+     */
+    constructor(label: string, source: CellChangeSource, changes: CellChangeIf[]);
+    get cellCount(): number;
+    /**
+     * Adds cells written by the same user action (an `onModelChanged` handler that derives values) to this step.
+     *
+     * @param {CellChangeIf[]} changes - the written cells
+     */
+    append(changes: CellChangeIf[]): void;
+    undo(scope: TableScope): UndoResultIf;
+    redo(scope: TableScope): UndoResultIf;
+    private apply;
+}

package/lib/table/undo/model-rows.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The rows array of a body model (object array: `getAllRows`, row grouping: `getSourceRows`, array of arrays: `arr`,
+ * tree: its root rows) – another array means `setRows` replaced the data.
+ *
+ * @param {unknown} body - the body area model
+ * @returns {unknown[] | undefined} the array, `undefined` for models that can't tell
+ * @internal
+ */
+export declare function rowsArrayOf(body: unknown): unknown[] | undefined;
+/**
+ * All row objects of a body model, also filtered and collapsed ones (tree: the data of every node).
+ *
+ * @param {unknown} body - the body area model
+ * @returns {Set<unknown> | null} the rows, `null` for models that can't tell
+ * @internal
+ */
+export declare function allRowObjectsOf(body: unknown): Set<unknown> | null;

package/lib/table/undo/pending-changes-undoable.d.ts

@@ -0,0 +1,35 @@
+import { TableScope } from '../table-scope.js';
+import { CellChangeSource } from '../batch-edit/cell-change.if.js';
+import { PendingCellIf } from '../batch-edit/pending-cell-changes.js';
+import { UndoableIf, UndoResultIf } from './undoable.if.js';
+
+/** One cell of a batch edit step: its pending entry before and after (none = not pending). */
+export interface PendingSnapshotIf {
+    rowKey: unknown;
+    property: string;
+    before?: PendingCellIf;
+    after?: PendingCellIf;
+}
+/**
+ * A step of a batch edit (values marked, not written): undo restores the pending state before the step, redo the one
+ * after it. A cell whose pending value changed since then is skipped (`onConflict: "skip"`). Commit and cancel of the
+ * batch edit empty the history.
+ *
+ * @category Spreadsheet
+ * @since 1.1.99
+ */
+export declare class PendingChangesUndoable implements UndoableIf {
+    readonly label: string;
+    readonly source: CellChangeSource;
+    private readonly cells;
+    /**
+     * @param {string} label - for buttons and announcements
+     * @param {CellChangeSource} source - what started the step
+     * @param {PendingSnapshotIf[]} cells - the pending entries before and after
+     */
+    constructor(label: string, source: CellChangeSource, cells: PendingSnapshotIf[]);
+    get cellCount(): number;
+    undo(scope: TableScope): UndoResultIf;
+    redo(scope: TableScope): UndoResultIf;
+    private apply;
+}

package/lib/table/undo/undo-keymap.d.ts

@@ -0,0 +1,17 @@
+import { ShortcutActionIdMapping } from '../action/shortcut-actionid-mapping.type.js';
+
+/**
+ * The keys of undo and redo ({@link TableOptionsIf.undo}) – a layer over the system mapping that the table only uses
+ * with the option; `tableOptions.shortcutActionIdMapping` still overrides it. In an open editor the keys belong to
+ * the editor (the browser's text undo).
+ *
+ * @param {boolean} mac - macOS keys (⌘+Z, ⌘+Shift+Z)
+ * @returns {ShortcutActionIdMapping} the layer
+ *
+ * @example
+ * undoShortcutLayer(false)["ctrl+y"];   // "REDO"
+ *
+ * @category Spreadsheet
+ * @since 1.1.99
+ */
+export declare function undoShortcutLayer(mac: boolean): ShortcutActionIdMapping;

package/lib/table/undo/undo-options.d.ts

@@ -0,0 +1,26 @@
+import { UndoOptionsIf } from './undo-options.if.js';
+
+/**
+ * The defaults of {@link UndoOptionsIf} (undo and redo, {@link TableOptionsIf.undo}).
+ *
+ * @example
+ * const options = UndoOptions.create({ maxSteps: 20 });
+ * options?.onConflict;   // "skip"
+ *
+ * @category Spreadsheet
+ * @since 1.1.99
+ */
+export declare class UndoOptions implements UndoOptionsIf {
+    maxSteps: number;
+    maxCells: number;
+    onConflict: "skip" | "overwrite";
+    recordApiChanges: boolean;
+    /**
+     * The options of {@link TableOptionsIf.undo}: `undefined`/`false` = off, `true` = the defaults, an object = the
+     * defaults overridden by its values (`undefined` keeps the default).
+     *
+     * @param {boolean | Partial<UndoOptionsIf>} [option] - `tableOptions.undo`
+     * @returns {UndoOptionsIf | undefined} complete options, `undefined` if undo is off
+     */
+    static create(option?: boolean | Partial<UndoOptionsIf>): UndoOptionsIf | undefined;
+}

package/lib/table/undo/undo-options.if.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Undo and redo ({@link TableOptionsIf.undo}). `undo: true` uses the defaults of {@link UndoOptions}; an object
+ * overrides single values.
+ *
+ * @example
+ * const tableOptions: TableOptionsIf = {
+ *   ...new TableOptions(),
+ *   editing: true,
+ *   undo: { maxSteps: 50, onConflict: "overwrite" },
+ * };
+ *
+ * @category Spreadsheet
+ * @since 1.1.99
+ */
+export interface UndoOptionsIf {
+    /** Steps kept; the oldest is dropped. Default `100`. */
+    maxSteps: number;
+    /**
+     * Cells kept over all steps (the oldest steps are dropped). A single change with more cells empties the history
+     * and is announced – it cannot be undone. Default `1_000_000`.
+     */
+    maxCells: number;
+    /**
+     * A cell changed by something else since the step (live data, `updateCells`): `"skip"` leaves it and announces it
+     * (default, safe), `"overwrite"` writes anyway.
+     */
+    onConflict: "skip" | "overwrite";
+    /** Record `api.applyCellChanges(…)` with source `"api"` too. Default `false` (per call: `{ undoable: true }`). */
+    recordApiChanges: boolean;
+}

package/lib/table/undo/undo-service.d.ts

@@ -0,0 +1,103 @@
+import { TableScope } from '../table-scope.js';
+import { UndoOptionsIf } from './undo-options.if.js';
+import { UndoableIf } from './undoable.if.js';
+import { CellChangeIf, CellChangeSource } from '../batch-edit/cell-change.if.js';
+import { PendingSnapshotIf } from './pending-changes-undoable.js';
+import { GeUndoEvent } from '../data/common/event/ge-undo-event.js';
+
+/**
+ * Undo and redo ({@link TableOptionsIf.undo}, `tableScope.undoService`, only with the option): records every change
+ * that goes through the table's one write path (editor, fill handle, paste, cut, Delete; `api.applyCellChanges` only
+ * with `recordApiChanges` or `{ undoable: true }`) as one step, and marked values of a batch edit. Not recorded:
+ * `updateCells`, `setRows` (the history is emptied when the rows array is replaced), sorting, filter, row drag.
+ *
+ * @category Internals
+ * @since 1.1.99
+ */
+export declare class UndoService {
+    private readonly tableScope;
+    readonly options: UndoOptionsIf;
+    private readonly stack;
+    private group?;
+    /** An undo or redo is running: its writes (also of event handlers) are not recorded. */
+    private running;
+    /** The step whose `onModelChanged` is being reported: writes of handlers are added to it. */
+    private folding?;
+    private foldDepth;
+    /** The rows array when the first step was recorded – another array (`setRows`) empties the history. */
+    private rowsRef?;
+    /**
+     * @param {TableScope} tableScope - the table
+     * @param {UndoOptionsIf} options - complete options
+     */
+    constructor(tableScope: TableScope, options: UndoOptionsIf);
+    /**
+     * Records an own step (e.g. inserting rows) – not while an undo or redo runs.
+     *
+     * @param {UndoableIf} step - the step
+     * @since 1.1.99
+     */
+    addStep(step: UndoableIf): void;
+    /**
+     * Records written cells as a step (called by the table's write path).
+     *
+     * @param {CellChangeIf[]} changes - the written cells
+     * @param {CellChangeSource} source - what wrote them
+     * @param {boolean} [undoable] - `api.applyCellChanges(…, { undoable })`: overrides `recordApiChanges`
+     */
+    record(changes: CellChangeIf[], source: CellChangeSource, undoable?: boolean): void;
+    /** The step recorded last (for {@link beginFold}). */
+    private lastRecorded?;
+    /**
+     * The table reports the write that was just recorded (`onModelChanged`): writes of handlers until {@link endFold}
+     * belong to the same step.
+     */
+    beginFold(): void;
+    /** End of {@link beginFold}. */
+    endFold(): void;
+    /**
+     * Records marked values of a batch edit as a step (called by the table).
+     *
+     * @param {PendingSnapshotIf[]} cells - pending entries before and after
+     * @param {CellChangeSource} source - what marked them
+     * @param {boolean} [undoable] - as in {@link record}
+     */
+    recordPending(cells: PendingSnapshotIf[], source: CellChangeSource, undoable?: boolean): void;
+    /**
+     * Records everything `fn` changes as one step (see {@link TableApi.batchUndoable}).
+     *
+     * @param {string} label - the label of the step
+     * @param {() => T} fn - the changes
+     * @returns {T} what `fn` returns
+     */
+    batch<T>(label: string, fn: () => T): T;
+    /**
+     * Undoes the last step: writes the old values back (source `"undo"`), selects the cells, announces it.
+     *
+     * @returns {boolean} true if a step was undone
+     */
+    undo(): boolean;
+    /**
+     * Redoes the last undone step (source `"redo"`).
+     *
+     * @returns {boolean} true if a step was redone
+     */
+    redo(): boolean;
+    /** @returns {boolean} true if there is a step to undo */
+    canUndo(): boolean;
+    /** @returns {boolean} true if there is a step to redo */
+    canRedo(): boolean;
+    /** @returns {GeUndoEvent} the state of the history (for buttons) */
+    getState(): GeUndoEvent;
+    /** Empties the history (batch commit/cancel, {@link TableApi.clearUndoHistory}). */
+    clear(silent?: boolean): void;
+    private add;
+    private run;
+    /**
+     * `setRows` (or `api.addRows`/`removeRows`, which build a new array) replaced the rows array: the steps point to rows
+     * that may be gone – the history is emptied (silently when asked by a getter; the next change reports it).
+     */
+    private checkRows;
+    private currentRows;
+    private fire;
+}

package/lib/table/undo/undo-stack.d.ts

@@ -0,0 +1,62 @@
+/**
+ * The undo and redo stacks of steps (DOM-free): a new step clears the redo stack; at most `maxSteps` steps and
+ * `maxCells` cells (over both stacks) are kept – the oldest go first; a single step with more than `maxCells` cells
+ * empties the history and is not kept.
+ *
+ * @example
+ * const stack = new UndoStack<{ cellCount: number; label: string }>(100, 1_000_000);
+ * stack.push({ cellCount: 1, label: "Edit" });
+ * stack.undo()?.label;   // "Edit" – now on the redo stack
+ * stack.canRedo();       // true
+ *
+ * @category Spreadsheet
+ * @since 1.1.99
+ */
+export declare class UndoStack<T extends {
+    readonly cellCount: number;
+}> {
+    private readonly maxSteps;
+    private readonly maxCells;
+    private readonly undoSteps;
+    private readonly redoSteps;
+    private cells;
+    /**
+     * @param {number} maxSteps - steps kept on the undo stack
+     * @param {number} maxCells - cells kept over both stacks
+     */
+    constructor(maxSteps: number, maxCells: number);
+    /**
+     * Adds a step and clears the redo stack.
+     *
+     * @param {T} step - the new step
+     * @returns {boolean} false if the step was too large (the history is empty now)
+     */
+    push(step: T): boolean;
+    /**
+     * Takes the last step for undo (it moves to the redo stack).
+     *
+     * @returns {T | undefined} the step, `undefined` if there is none
+     */
+    undo(): T | undefined;
+    /**
+     * Takes the last undone step for redo (it moves back to the undo stack).
+     *
+     * @returns {T | undefined} the step, `undefined` if there is none
+     */
+    redo(): T | undefined;
+    /** @returns {T | undefined} the step the next undo takes */
+    peekUndo(): T | undefined;
+    /** @returns {T | undefined} the step the next redo takes */
+    peekRedo(): T | undefined;
+    /** @returns {boolean} true if there is a step to undo */
+    canUndo(): boolean;
+    /** @returns {boolean} true if there is a step to redo */
+    canRedo(): boolean;
+    /** @returns {number} steps on the undo stack */
+    size(): number;
+    /** @returns {number} cells kept over both stacks */
+    cellCount(): number;
+    /** Empties both stacks. */
+    clear(): void;
+    private clearRedo;
+}