@guiexpert/table 1.1.97 → 1.1.99

package/lib/table/sheet-editing/formula-assist.d.ts

@@ -0,0 +1,103 @@
+import { TableScope } from '../table-scope.js';
+import { TableSheet } from '../sheet/table-sheet.js';
+import { CellEditMode } from './cell-editor.if.js';
+
+/**
+ * The formula input of the cell editor (prompt 013 stage 6, `tableOptions.cellFormulas`): pointing (arrow keys, Shift
+ * + arrow keys, a click or a drag insert references while the caret stands at an insertion point), F4 (`$`), colored
+ * references in the text (a mirror behind the transparent text of the input) with frames around the referenced cells,
+ * function suggestions (an ARIA combobox with a listbox) and the argument hint (a tooltip). Created by the
+ * {@link CellEditorService} for a text field in a formula column.
+ *
+ * @category Internals
+ * @since 1.1.99
+ */
+export declare class FormulaAssist {
+    private readonly scope;
+    private readonly sheet;
+    private readonly input;
+    private readonly editedCell;
+    private readonly changed;
+    private readonly mirror;
+    private readonly list;
+    private readonly hint;
+    private frames;
+    private suggestions;
+    private active;
+    /** Escape closed the list: it stays closed until the text changes. */
+    private listClosed;
+    private pointer?;
+    private cellCache?;
+    private composing;
+    private drag?;
+    private readonly abort;
+    private readonly ids;
+    private readonly functions;
+    constructor(scope: TableScope, sheet: TableSheet, input: HTMLInputElement, container: HTMLDivElement, editedCell: () => [number, number], changed: () => void, idPrefix: string);
+    /**
+     * A key in the editor: the suggestion list, F4 and pointing. True if it was used (the caller stops it).
+     *
+     * @param {KeyboardEvent} evt - the key
+     * @param {CellEditMode} mode - "enter" (typing) or "edit" (F2: arrow keys move the caret)
+     * @returns {boolean} true if handled
+     */
+    onKeyDown(evt: KeyboardEvent, mode: CellEditMode): boolean;
+    /**
+     * A pointer press outside the editor: while pointing is possible, a body cell is inserted as reference (Shift: a
+     * range from the last pointed cell) and dragging spans a range. True if it was used – the click then neither
+     * commits nor moves the selection.
+     *
+     * @param {PointerEvent} evt - the press
+     * @returns {boolean} true if handled
+     */
+    onPointerDown(evt: PointerEvent): boolean;
+    /** @returns {string[]} the ids of the suggestion list and the hint (owned by the edited cell, `aria-owns`) */
+    getOwnedIds(): string[];
+    /** Places the frames and the popups (after every render pass and on changes). */
+    update(): void;
+    /** Removes everything (the editor closes). */
+    destroy(): void;
+    private texts;
+    private onInput;
+    private caret;
+    private collapsed;
+    /** Pointing: right after an inserted reference, or (typing mode) at an insertion point. */
+    private canPoint;
+    /** The next cell in a direction: rows clamped, columns over shown data columns. */
+    private step;
+    /** The reference text of a pointed range: one cell or the bounding range (physical rows, data columns). */
+    private referenceText;
+    /** True if the display rows d1…d2 are exactly the physical rows p1…p2 (in any order). */
+    private isContiguous;
+    /** Inserts (or replaces the last pointed) reference at the caret. */
+    private point;
+    private startDrag;
+    /** F4: the next `$` form of the reference at (or right before) the caret. */
+    private toggleReferenceAtCaret;
+    private isListOpen;
+    /** Takes a suggestion: the typed name becomes `NAME(`. */
+    private accept;
+    /** The caret moved: list and hint follow (no new colors needed). */
+    private refreshCaret;
+    private refresh;
+    private syncScroll;
+    /** The colors of the references: by first occurrence, the same reference the same color. */
+    private colored;
+    private renderMirror;
+    /** One frame per referenced cell or range that is shown (a reference to a hidden row has none). */
+    private renderFrames;
+    /** The visible rectangle of a reference in host coordinates, `undefined` if nothing of it is shown. */
+    private frameRect;
+    /**
+     * The display rows and model columns of a reference's corners – cached while the text, the row count and the
+     * order stay (finding a display row may scan all rows of a sorted table; the frames are placed on every scroll).
+     */
+    private frameCells;
+    /** The number of physical rows (a range beyond them ends at the last one). */
+    private sheetRows;
+    private firstDataColumn;
+    private lastDataColumn;
+    /** The suggestion list (a function name is typed) or the argument hint (inside a call). */
+    private renderPopups;
+    private renderList;
+}

package/lib/table/sheet-editing/formula-text.d.ts

@@ -0,0 +1,61 @@
+/** A reference in the formula text: position, text and the text without `$` in capitals (same reference = same color). */
+export interface FormulaTextRefIf {
+    readonly start: number;
+    readonly end: number;
+    readonly text: string;
+    readonly key: string;
+}
+/**
+ * The references of a formula text (outside strings and `[field]`s), in order.
+ *
+ * @param {string} text - the editor text (with `=`)
+ * @returns {FormulaTextRefIf[]} the references
+ */
+export declare function findReferences(text: string): FormulaTextRefIf[];
+/**
+ * True if a reference may be inserted at the caret: the text is a formula and the caret follows `=`, `(`, `,`, `;` or
+ * an operator (spaces allowed) – not inside a string.
+ *
+ * @param {string} text - the editor text
+ * @param {number} caret - the caret position
+ * @returns {boolean} whether pointing inserts here
+ */
+export declare function isInsertionPoint(text: string, caret: number): boolean;
+/**
+ * F4: the next `$` form of a reference – `A1` → `$A$1` → `A$1` → `$A1` → `A1`; a range changes both ends like its
+ * first one. Whole columns/rows toggle their one `$` part.
+ *
+ * @param {string} ref - e.g. `"B2"`, `"$B$2:$B$4"`
+ * @returns {string} the next form
+ */
+export declare function toggleAbsolute(ref: string): string;
+/**
+ * The beginning of a function name the caret stands behind (`=SU|` → `"SU"`), `undefined` if there is none: it must
+ * start at an insertion point, contain letters and not be a reference already followed by `(`.
+ *
+ * @param {string} text - the editor text
+ * @param {number} caret - the caret position
+ * @returns {{ start: number, prefix: string } | undefined} where the name starts and what was typed
+ */
+export declare function functionPrefixAt(text: string, caret: number): {
+    start: number;
+    prefix: string;
+} | undefined;
+/**
+ * The innermost function call the caret is in and the index of its argument (`=SUM(1,|` → `{ name: "SUM", argument: 1 }`).
+ *
+ * @param {string} text - the editor text
+ * @param {number} caret - the caret position
+ * @returns {{ name: string, argument: number } | undefined} the call
+ */
+export declare function callAt(text: string, caret: number): {
+    name: string;
+    argument: number;
+} | undefined;
+/**
+ * The arguments of a signature (`"SUM(number1, [number2], …)"` → `["number1", "[number2]", "…"]`).
+ *
+ * @param {string} signature - the signature
+ * @returns {string[]} the arguments
+ */
+export declare function signatureArguments(signature: string): string[];

package/lib/table/sheet-editing/sheet-navigation.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The target of Ctrl+arrow (⌘+arrow on macOS) in Excel-style editing – Excel's rule for jumping to the edge of the
+ * data: if the cell next to the start is empty, the next filled cell in that direction (or the last cell); if it is
+ * filled, the last filled cell of that block. Empty = `null`, `undefined` or `""` (not `0`, not `false`).
+ * DOM-free; hidden columns (`isShownColumn` → `false`) are skipped.
+ *
+ * @param {(row: number, column: number) => boolean} isEmpty - true for an empty cell
+ * @param {number} rowCount - rows (display order)
+ * @param {number} columnCount - columns (model indices)
+ * @param {number} row - start row
+ * @param {number} column - start column
+ * @param {number} dRow - -1, 0 or 1
+ * @param {number} dColumn - -1, 0 or 1
+ * @param {(column: number) => boolean} [isShownColumn] - false for a hidden column
+ * @returns {[number, number]} the target cell (the start if there is nothing to move to)
+ *
+ * @example
+ * const data = [[1], [2], [""], [""], [5]];
+ * const isEmpty = (r: number, c: number) => data[r][c] === "";
+ * findDataEdge(isEmpty, 5, 1, 0, 0, 1, 0);   // [1, 0] – end of the block 1, 2
+ * findDataEdge(isEmpty, 5, 1, 1, 0, 1, 0);   // [4, 0] – next filled cell
+ *
+ * @category Spreadsheet
+ * @since 1.1.99
+ */
+export declare function findDataEdge(isEmpty: (row: number, column: number) => boolean, rowCount: number, columnCount: number, row: number, column: number, dRow: number, dColumn: number, isShownColumn?: (column: number) => boolean): [number, number];

package/lib/table/spreadsheet/area-model-sheet.d.ts

@@ -0,0 +1,170 @@
+import { AbstractAreaModel } from '../data/tablemodel/areamodel/abstract-area-model.js';
+import { AreaIdent } from '../data/tablemodel/area-ident.type.js';
+import { ColumnDefIf } from '../data/tablemodel/column/column-def.if.js';
+import { FilterFunction } from '../data/common/filter-function.js';
+import { SortItem } from '../data/common/sort-item.js';
+
+/**
+ * The body of a spreadsheet ({@link SpreadsheetFactory}): **sparse** – only rows with content exist (a sheet with a
+ * million empty rows costs nothing), row `n` = physical row `n` (cell formulas), sorting and filtering as a
+ * permutation (display → physical) only while they apply. Cells are stored by data column (`A` = 0); the model columns
+ * in front (row numbers) are left out with `columnOffset`.
+ *
+ * @example
+ * const body = new AreaModelSheet("body", [["Laptop", 1299], ["Mouse", 25]], 100, 26, 30, columnDefs, 1);
+ * body.getSheetData();   // [["Laptop", 1299], ["Mouse", 25]]
+ *
+ * @category Spreadsheet
+ * @since 1.1.99
+ */
+export declare class AreaModelSheet extends AbstractAreaModel<unknown[]> {
+    private rowCount;
+    private columnCount;
+    readonly columnOffset: number;
+    /** Increases with every structural change (rows/columns inserted or deleted, data replaced). */
+    version: number;
+    private rows;
+    private physicalOfArray;
+    private perm?;
+    private inverse?;
+    constructor(areaIdent: AreaIdent, data: unknown[][], rowCount: number, columnCount: number, defaultRowHeight: number, columnDefs?: ColumnDefIf[], columnOffset?: number);
+    /**
+     * Replaces all cells (sorting and filters end).
+     *
+     * @param {unknown[][]} data - rows × data columns
+     * @param {number} [rowCount] - at least the rows of `data`
+     * @param {number} [columnCount] - at least the longest row
+     */
+    setSheetData(data: unknown[][], rowCount?: number, columnCount?: number): void;
+    /**
+     * The cells as rows × columns, up to the last row and column with content (empty cells `""`) – e.g. to save them.
+     *
+     * @returns {unknown[][]} the data
+     */
+    getSheetData(): unknown[][];
+    /** @returns {unknown} the input of a cell by physical row and data column (`undefined` if empty) */
+    getCell(row: number, col: number): unknown;
+    /**
+     * Writes the input of a cell by physical row and data column (the row is created on demand).
+     *
+     * @param {number} row - physical row
+     * @param {number} col - data column
+     * @param {unknown} value - the input
+     */
+    setCell(row: number, col: number, value: unknown): void;
+    /** @returns {unknown[] | undefined} the row array of a physical row (`undefined` for an empty row) */
+    getRowArray(row: number): unknown[] | undefined;
+    /** Calls `fn` for every stored cell (the sparse rows only). */
+    forEachCell(fn: (row: number, col: number, value: unknown) => void): void;
+    /** @returns {number | undefined} the physical row of a row array of this model */
+    getPhysicalRowOfArray(row: unknown): number | undefined;
+    /** @returns {number} the number of data columns */
+    getSheetColumnCount(): number;
+    /**
+     * New column definitions (inserted or deleted columns).
+     *
+     * @param {ColumnDefIf[]} columnDefs - all columns of the table
+     */
+    setColumnDefs(columnDefs: ColumnDefIf[]): void;
+    getRowCount(): number;
+    /** @returns {number} all rows, without sorting and filters */
+    getUnfilteredRowCount(): number;
+    /**
+     * The physical row (= row number − 1) of a display row – row numbers in `"original"` mode and cell formulas use it.
+     *
+     * @param {number} rowIndex - display index
+     * @returns {number} the physical row
+     */
+    getPhysicalRowIndex(rowIndex: number): number;
+    /**
+     * The display row of a physical row, `-1` if a filter hides it.
+     *
+     * @param {number} physicalRow - the physical row
+     * @returns {number} the display index
+     */
+    getDisplayRowIndex(physicalRow: number): number;
+    getValueAt(rowIndex: number, columnIndex: number): any;
+    /**
+     * The input of a cell – the formula text of a formula, otherwise the value (`""` for an empty cell).
+     *
+     * @param {number} rowIndex - display index
+     * @param {number} columnIndex - model column
+     * @returns {unknown} the input
+     */
+    getInputValueAt(rowIndex: number, columnIndex: number): unknown;
+    getTextValueAt(rowIndex: number, columnIndex: number): string;
+    setValue(rowIndex: number, columnIndex: number, value: any): boolean;
+    /** The row array of a display row – `undefined` for an empty row (no object is created by reading). */
+    getRowByIndex(rowIndex: number): any;
+    getRowHeight(_rowIndex: number): number;
+    /** @returns {number | undefined} the constant row height */
+    getConstantRowHeight(): number | undefined;
+    /**
+     * A sheet has no merged cells: the table skips the span scan (rows × columns calls on every init).
+     *
+     * @returns {number} 1
+     */
+    getMaxColspan(): number;
+    /** @returns {number} 1 – no merged cells (see {@link getMaxColspan}) */
+    getMaxRowspan(): number;
+    /** A filter: the predicate gets the row as array of inputs (`[]` for an empty row). */
+    externalFilterChanged(predictFn: FilterFunction<any>): void;
+    /** Sorts the shown rows by the values of columns (empty cells last). */
+    doSort(sortItems: SortItem[]): boolean;
+    /**
+     * Inserts empty rows before a physical row (sorting and filters end).
+     *
+     * @param {number} at - physical row
+     * @param {number} count - rows
+     */
+    insertRows(at: number, count: number): void;
+    /**
+     * Deletes rows (sorting and filters end).
+     *
+     * @param {number} at - first physical row
+     * @param {number} count - rows
+     * @returns {Array<[number, unknown[]]>} the deleted rows with content (offset from `at`, the row array) – for undo
+     */
+    deleteRows(at: number, count: number): Array<[number, unknown[]]>;
+    /**
+     * Inserts rows again that {@link deleteRows} removed (undo): the same row arrays at their places.
+     *
+     * @param {number} at - first physical row
+     * @param {number} count - rows
+     * @param {Array<[number, unknown[]]>} removed - what `deleteRows` returned
+     */
+    restoreRows(at: number, count: number, removed: ReadonlyArray<readonly [number, unknown[]]>): void;
+    /**
+     * Inserts empty data columns before a data column.
+     *
+     * @param {number} at - data column
+     * @param {number} count - columns
+     */
+    insertColumns(at: number, count: number): void;
+    /**
+     * Deletes data columns.
+     *
+     * @param {number} at - first data column
+     * @param {number} count - columns
+     * @returns {Array<[unknown[], unknown[]]>} per row with content in the columns: the row array and its removed cells
+     */
+    deleteColumns(at: number, count: number): Array<[unknown[], unknown[]]>;
+    /**
+     * Inserts columns again that {@link deleteColumns} removed (undo).
+     *
+     * @param {number} at - first data column
+     * @param {number} count - columns
+     * @param {Array<[unknown[], unknown[]]>} removed - what `deleteColumns` returned
+     */
+    restoreColumns(at: number, count: number, removed: ReadonlyArray<readonly [unknown[], unknown[]]>): void;
+    /**
+     * The extent of the content in the current view: the last display row and model column with a value (the Excel
+     * export leaves out the empty rest). `[-1, -1]` for an empty sheet.
+     *
+     * @returns {[number, number]} last display row and last model column
+     */
+    getContentExtent(): [number, number];
+    private valueOfPhysical;
+    private shiftRows;
+    private changed;
+}

package/lib/table/spreadsheet/formula-bar.d.ts

@@ -0,0 +1,53 @@
+import { TableApi } from '../table-api.js';
+
+/**
+ * Options of the {@link FormulaBar}.
+ *
+ * @category Spreadsheet
+ * @since 1.1.99
+ */
+export interface FormulaBarOptionsIf {
+    /** Show the address box (`B3`; typing `D10` or `B2:C5` + Enter goes there). Default `true`. */
+    addressBox: boolean;
+    /** The name of the input of the formula bar. Default `"Formula"`. */
+    ariaLabel: string;
+    /** The name of the address box. Default `"Cell address"`. */
+    addressAriaLabel: string;
+}
+/**
+ * The formula bar of a spreadsheet: an address box (`B3`) and the input of the active cell (the formula text, not
+ * its result). Typing there and Enter/Tab writes the cell (`TableApi.setCellInput`) and moves like the table, Escape
+ * restores it; while the cell editor is open the bar shows its text live. Plain DOM, no dependency – works with every
+ * wrapper (pass the `TableApi` of `tableReady`). Colors: `--ge-table-formula-bar-*`.
+ *
+ * @example
+ * const bar = new FormulaBar(document.querySelector<HTMLElement>(".formula-bar")!, tableApi);
+ * // later: bar.destroy();
+ *
+ * @category Spreadsheet
+ * @since 1.1.99
+ */
+export declare class FormulaBar {
+    private readonly api;
+    readonly element: HTMLDivElement;
+    readonly addressInput: HTMLInputElement;
+    readonly input: HTMLInputElement;
+    private readonly options;
+    private readonly unsubscribe;
+    private readonly abort;
+    /** The cell the input belongs to (fixed while typing in the bar). */
+    private cell?;
+    private original;
+    constructor(container: HTMLElement, api: TableApi, options?: Partial<FormulaBarOptionsIf>);
+    /** Removes the bar and its listeners. */
+    destroy(): void;
+    /** Shows the active cell: its address and input (not while typing in the bar). */
+    show(): void;
+    private onEditing;
+    private beginInput;
+    /** Writes the input (if changed); `false` keeps the bar's text otherwise. */
+    private endInput;
+    private onInputKey;
+    private onAddressKey;
+    private focusTable;
+}

package/lib/table/spreadsheet/spreadsheet-factory.d.ts

@@ -0,0 +1,111 @@
+import { TableModel } from '../data/tablemodel/table-model.js';
+import { TableModelIf } from '../data/tablemodel/table-model.if.js';
+import { ColumnDefIf } from '../data/tablemodel/column/column-def.if.js';
+import { AreaModelArrayOfArrays } from '../data/tablemodel/areamodel/area-model-array-of-arrays.js';
+import { RowNumberColumnDef } from '../data/common/row-number-column-def.js';
+import { TableOptionsIf } from '../data/options/table-options.if.js';
+import { FormulaFunction } from '../formula/formula-options.if.js';
+import { AreaModelSheet } from './area-model-sheet.js';
+import { editInputPipe } from '../renderer/edit/edit-input-pipe.if.js';
+
+/**
+ * The parameters of {@link SpreadsheetFactory.create}. All optional.
+ *
+ * @category Spreadsheet
+ * @since 1.1.99
+ */
+export interface SpreadsheetParamIf {
+    /** Rows × columns of inputs; formulas as `"=…"`. Default: empty. */
+    data: unknown[][];
+    /** Rows of the sheet. Default `max(data.length, 100)`. */
+    rowCount: number;
+    /** Columns of the sheet. Default `max(longest row, 26)` (A–Z). */
+    columnCount: number;
+    /** Width of a column in px. Default 100. */
+    columnWidth: number;
+    /** Height of a row in px. Default 30. */
+    rowHeight: number;
+    /** Row numbers in front (they count the rows of the sheet, also when sorted). Default `true`. */
+    rowNumbers: boolean;
+    /** Merged over the options of the factory (selection, focus, the spreadsheet preset). */
+    tableOptions: Partial<TableOptionsIf>;
+    /** Own functions of the cell formulas. */
+    functions: Record<string, FormulaFunction>;
+    /**
+     * The locale of typed and pasted values (`sheetInputPipe`): `"1,5"` is 1.5 in `"de-DE"`. Default: the browser's
+     * locale. Formulas always use `.` and English function names.
+     */
+    locale: string;
+}
+/**
+ * The header of a spreadsheet: one row with the column letters `A, B, …` (`isColumnLetterRow(0)` – a click selects the
+ * column).
+ *
+ * @category Spreadsheet
+ * @since 1.1.99
+ */
+export declare class AreaModelSheetHeader extends AreaModelArrayOfArrays<string> {
+    /** The number of header rows with column letters (from the top). */
+    readonly columnLetterRows = 1;
+    /**
+     * @param {number} rowIndex - a header row
+     * @returns {boolean} true for the row of column letters
+     */
+    isColumnLetterRow(rowIndex: number): boolean;
+    /**
+     * New columns (insert/delete columns).
+     *
+     * @param {ColumnDefIf[]} columnDefs - all columns
+     */
+    setColumns(columnDefs: ColumnDefIf[]): void;
+}
+/**
+ * The table model of a spreadsheet ({@link SpreadsheetFactory}): its data columns can be inserted and deleted
+ * (`TableApi.insertColumns`).
+ *
+ * @category Spreadsheet
+ * @since 1.1.99
+ */
+export declare class SpreadsheetTableModel extends TableModel {
+    readonly sheetBody: AreaModelSheet;
+    private readonly rowNumberColumn;
+    private readonly columnWidth;
+    private readonly inputPipe;
+    constructor(header: AreaModelSheetHeader, sheetBody: AreaModelSheet, rowNumberColumn: RowNumberColumnDef | undefined, columnDefs: ColumnDefIf[], rowHeight: number, columnWidth: number, inputPipe?: editInputPipe);
+    /**
+     * Sets the data columns: `A…` with the given widths (insert/delete columns keep the widths of the moved columns).
+     *
+     * @param {number} count - data columns
+     * @param {number[]} [widths] - width per data column in px (missing: the default width)
+     */
+    setDataColumns(count: number, widths?: number[]): void;
+    /** @returns {number[]} the widths of the data columns in px */
+    getDataColumnWidths(): number[];
+}
+/**
+ * Builds an empty (or filled) spreadsheet in one call: column letters, row numbers, a sparse body (a million rows cost
+ * only their filled cells) and the options of the spreadsheet preset – Excel-style editing, copy and paste, undo,
+ * cell formulas, the fill handle and a range selection with the active cell on A1.
+ *
+ * @example
+ * const { tableModel, tableOptions } = SpreadsheetFactory.create({
+ *   data: [["Product", "Price", "Qty", "Total"], ["Laptop", 1299, 2, "=B2*C2"]],
+ * });
+ *
+ * @category Spreadsheet
+ * @since 1.1.99
+ */
+export declare class SpreadsheetFactory {
+    /**
+     * Model and options of a spreadsheet.
+     *
+     * @param {Partial<SpreadsheetParamIf>} [param] - data, size, row numbers, options
+     * @returns {{ tableModel: SpreadsheetTableModel, tableOptions: TableOptionsIf }} for the table or a wrapper
+     */
+    static create(param?: Partial<SpreadsheetParamIf>): {
+        tableModel: SpreadsheetTableModel;
+        tableOptions: TableOptionsIf;
+    };
+}
+/** @returns {boolean} true for the model of a {@link SpreadsheetFactory} sheet */
+export declare function isSpreadsheetTableModel(model: TableModelIf): model is SpreadsheetTableModel;

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

@@ -0,0 +1,28 @@
+import { EditingOptionsIf } from '../sheet-editing/editing-options.if.js';
+import { ClipboardOptionsIf } from '../clipboard/clipboard-options.if.js';
+import { UndoOptionsIf } from '../undo/undo-options.if.js';
+import { CellFormulaOptionsIf } from '../sheet/cell-formula-options.if.js';
+import { FillHandleOptionsIf } from '../fill/fill-handle-options.if.js';
+
+/**
+ * The preset `tableOptions.spreadsheet` ({@link TableOptionsIf.spreadsheet}): which parts it switches on. Each part
+ * is `true` by default; `false` leaves it off, an object configures it. Options the table options set themselves win.
+ *
+ * @example
+ * const tableOptions: TableOptionsIf = { ...new TableOptions(), spreadsheet: { cellFormulas: { columns: ["total"] } } };
+ *
+ * @category Spreadsheet
+ * @since 1.1.99
+ */
+export interface SpreadsheetOptionsIf {
+    /** Excel-style editing – the preset sets `defaultEditable: true` (columns without own `editable` are editable). */
+    editing: boolean | Partial<EditingOptionsIf>;
+    /** Copy, cut and paste. */
+    clipboard: boolean | Partial<ClipboardOptionsIf>;
+    /** Undo and redo. */
+    undo: boolean | Partial<UndoOptionsIf>;
+    /** Cell formulas (`=B2*C2`). */
+    cellFormulas: boolean | Partial<CellFormulaOptionsIf>;
+    /** The fill handle. */
+    fillHandle: boolean | Partial<FillHandleOptionsIf>;
+}

package/lib/table/spreadsheet/spreadsheet-preset.d.ts

@@ -0,0 +1,37 @@
+import { TableOptionsIf } from '../data/options/table-options.if.js';
+import { SpreadsheetOptionsIf } from './spreadsheet-options.if.js';
+
+type PresetKey = keyof SpreadsheetOptionsIf;
+/**
+ * The value of one part of the preset `tableOptions.spreadsheet` for a table: the option itself if the options set it,
+ * otherwise the preset's part (`true` by default, `editing` with `defaultEditable: true`). Without the preset: the
+ * option. The options object is never changed (it may be shared by several tables or frozen).
+ *
+ * @param {TableOptionsIf} tableOptions - the options of a table
+ * @param {PresetKey} key - `editing`, `clipboard`, `undo`, `cellFormulas` or `fillHandle`
+ * @returns {unknown} the effective value
+ *
+ * @example
+ * spreadsheetOption({ ...new TableOptions(), spreadsheet: true }, "undo");   // true
+ *
+ * @category Spreadsheet
+ * @since 1.1.99
+ */
+export declare function spreadsheetOption<K extends PresetKey>(tableOptions: TableOptionsIf | undefined, key: K): TableOptionsIf[K];
+/**
+ * The options a table uses with the preset `tableOptions.spreadsheet`: a **copy** with every part of
+ * {@link SpreadsheetOptionsIf} the options don't set themselves (`editing`, `clipboard`, `undo`, `cellFormulas`,
+ * `fillHandle`). The table resolves the preset itself; use this to see the result.
+ *
+ * @param {TableOptionsIf} tableOptions - the options of a table
+ * @returns {TableOptionsIf} a copy (the same object without the preset)
+ *
+ * @example
+ * const options = applySpreadsheetPreset({ ...new TableOptions(), spreadsheet: true });
+ * options.undo;   // true
+ *
+ * @category Spreadsheet
+ * @since 1.1.99
+ */
+export declare function applySpreadsheetPreset(tableOptions: TableOptionsIf): TableOptionsIf;
+export {};

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;