@guiexpert/table 1.1.98 → 1.1.99

package/lib/table/action/action-id.type.d.ts

@@ -5,7 +5,7 @@
  *
  * @category Keyboard
  */
-export declare const actionIds: readonly ["COPY_2_CLIPBOARD", "START_EDITING", "TOGGLE_SELECTION", "SELECT_ALL", "DESELECT_ALL", "NAVIGATE_LEFT", "NAVIGATE_RIGHT", "NAVIGATE_UP", "NAVIGATE_DOWN", "NAVIGATE_ROW_START", "NAVIGATE_ROW_END", "NAVIGATE_FIRST_CELL", "NAVIGATE_LAST_CELL", "NAVIGATE_PAGE_UP", "NAVIGATE_PAGE_DOWN", "ACTIVATE_CELL", "MOVE_ROW_UP", "MOVE_ROW_DOWN", "FILL_DOWN", "FILL_RIGHT"];
+export declare const actionIds: readonly ["COPY_2_CLIPBOARD", "START_EDITING", "TOGGLE_SELECTION", "SELECT_ALL", "DESELECT_ALL", "NAVIGATE_LEFT", "NAVIGATE_RIGHT", "NAVIGATE_UP", "NAVIGATE_DOWN", "NAVIGATE_ROW_START", "NAVIGATE_ROW_END", "NAVIGATE_FIRST_CELL", "NAVIGATE_LAST_CELL", "NAVIGATE_PAGE_UP", "NAVIGATE_PAGE_DOWN", "ACTIVATE_CELL", "MOVE_ROW_UP", "MOVE_ROW_DOWN", "FILL_DOWN", "FILL_RIGHT", "NAVIGATE_NEXT_CELL", "NAVIGATE_PREVIOUS_CELL", "EXTEND_SELECTION_UP", "EXTEND_SELECTION_DOWN", "EXTEND_SELECTION_LEFT", "EXTEND_SELECTION_RIGHT", "EXTEND_SELECTION_ROW_START", "EXTEND_SELECTION_ROW_END", "EXTEND_SELECTION_PAGE_UP", "EXTEND_SELECTION_PAGE_DOWN", "NAVIGATE_DATA_EDGE_UP", "NAVIGATE_DATA_EDGE_DOWN", "NAVIGATE_DATA_EDGE_LEFT", "NAVIGATE_DATA_EDGE_RIGHT", "EXTEND_TO_DATA_EDGE_UP", "EXTEND_TO_DATA_EDGE_DOWN", "EXTEND_TO_DATA_EDGE_LEFT", "EXTEND_TO_DATA_EDGE_RIGHT", "SELECT_ROW", "SELECT_COLUMN", "CLEAR_CELLS", "CLEAR_AND_EDIT", "CUT_2_CLIPBOARD", "PASTE_FROM_CLIPBOARD", "UNDO", "REDO"];
 /**
  * Represents an action ID.
  *

package/lib/table/action/shortcut.service.d.ts

@@ -9,6 +9,10 @@ import { OnActionTriggeredIf } from './on-action-triggered.if.js';
  */
 export declare class ShortcutService {
     protected tableScope: TableScope;
+    /**
+     * The mapping as written: system, feature layers, then the app's mapping – one entry per key (a later spelling of
+     * the same key replaces the earlier one). See {@link getShortcutActionMapping}.
+     */
     private shortcutActionIdMapping;
     private listener;
     constructor(tableScope: TableScope);
@@ -25,6 +29,11 @@ export declare class ShortcutService {
      */
     init(): void;
     private assignPredefinedSystemShortcutMappings;
+    /**
+     * Adds a mapping under harmonized keys: a later mapping replaces an earlier one even if it spells the key
+     * differently ("meta+arrowleft" replaces "meta+left"; before 1.1.99 the first spelling silently won).
+     */
+    private assignMapping;
     private isMacintosh;
     private isDebug;
     private isLocalhost;

package/lib/table/aria/aria-texts.d.ts

@@ -44,4 +44,30 @@ export declare class AriaTexts implements AriaTextsIf {
     changesDiscarded(): string;
     commitBlocked(invalidCount: number): string;
     invalidValue(message: string): string;
+    editingStarted(columnLabel: string): string;
+    readOnlyCell(): string;
+    cellsCleared(cellCount: number): string;
+    clearTooLarge(maxCells: number): string;
+    rangeSelected(rowCount: number, columnCount: number): string;
+    rowSelected(rowCount: number): string;
+    columnSelected(columnCount: number): string;
+    gridEditingHint(): string;
+    cellsPasted(cellCount: number, skippedCount: number): string;
+    pasteTooLarge(maxCells: number): string;
+    copyTooLarge(maxCells: number): string;
+    cutMarked(cellCount: number): string;
+    copiedLastRangeOnly(): string;
+    undone(label: string, cellCount: number): string;
+    redone(label: string, cellCount: number): string;
+    nothingToUndo(): string;
+    nothingToRedo(): string;
+    undoSkipped(cellCount: number): string;
+    undoHistoryCleared(maxCells: number): string;
+    formulaError(message: string): string;
+    functionSuggestions(): string;
+    referenceInserted(reference: string): string;
+    rowsInserted(count: number): string;
+    rowsDeleted(count: number): string;
+    columnsInserted(count: number): string;
+    columnsDeleted(count: number): string;
 }

package/lib/table/aria/aria-texts.if.d.ts

@@ -186,4 +186,200 @@ export interface AriaTextsIf {
      * @since 1.1.97
      */
     detailCollapsed?(): string;
+    /**
+     * Announced when the cell editor opens (Excel-style editing).
+     *
+     * @param {string} columnLabel - the column label
+     * @returns {string} default: `"Editing Price"`
+     * @since 1.1.99
+     */
+    editingStarted?(columnLabel: string): string;
+    /**
+     * Announced when a key is typed on a cell that cannot be edited (Excel-style editing).
+     *
+     * @returns {string} default: `"Read only"`
+     * @since 1.1.99
+     */
+    readOnlyCell?(): string;
+    /**
+     * Announced after Delete/Backspace cleared cells.
+     *
+     * @param {number} cellCount - the number of cleared cells
+     * @returns {string} default: `"8 cells cleared"`
+     * @since 1.1.99
+     */
+    cellsCleared?(cellCount: number): string;
+    /**
+     * Announced when more cells should be cleared than `EditingOptionsIf.maxClearCells` allows.
+     *
+     * @param {number} maxCells - the limit
+     * @returns {string} default: `"Too many cells to clear (at most 1000000)"`
+     * @since 1.1.99
+     */
+    clearTooLarge?(maxCells: number): string;
+    /**
+     * Announced when Shift+arrows change the selected range (the focus stays on the active cell).
+     *
+     * @param {number} rowCount - rows of the range
+     * @param {number} columnCount - shown columns of the range
+     * @returns {string} default: `"3 rows, 2 columns selected"`
+     * @since 1.1.99
+     */
+    rangeSelected?(rowCount: number, columnCount: number): string;
+    /**
+     * Announced after Shift+Space selected the rows of the active cell.
+     *
+     * @param {number} rowCount - number of selected rows
+     * @returns {string} default: `"Row selected"`
+     * @since 1.1.99
+     */
+    rowSelected?(rowCount: number): string;
+    /**
+     * Announced after Ctrl+Space selected the columns of the active cell.
+     *
+     * @param {number} columnCount - number of selected columns
+     * @returns {string} default: `"Column selected"`
+     * @since 1.1.99
+     */
+    columnSelected?(columnCount: number): string;
+    /**
+     * The description of the grid with Excel-style editing (`aria-description` of the host): how it is used.
+     *
+     * @returns {string} default: `"Type to edit a cell, Enter to edit or commit, Escape to cancel. Tab in the last column leaves the table."`
+     * @since 1.1.99
+     */
+    gridEditingHint?(): string;
+    /**
+     * Announced after Ctrl/⌘+V (copy, cut and paste, `tableOptions.clipboard`).
+     *
+     * @param {number} cellCount - the number of pasted cells
+     * @param {number} skippedCount - cells left out (read only, invalid, cut off at the last column)
+     * @returns {string} default: `"6 cells pasted"`, `"4 cells pasted, 2 skipped"`
+     * @since 1.1.99
+     */
+    cellsPasted?(cellCount: number, skippedCount: number): string;
+    /**
+     * Announced when more cells should be pasted than `ClipboardOptionsIf.maxPasteCells` allows.
+     *
+     * @param {number} maxCells - the limit
+     * @returns {string} default: `"Too many cells to paste (at most 1000000)"`
+     * @since 1.1.99
+     */
+    pasteTooLarge?(maxCells: number): string;
+    /**
+     * Announced when more cells should be copied than `CopyService.maxCopyCells` allows.
+     *
+     * @param {number} maxCells - the limit
+     * @returns {string} default: `"Too many cells to copy (at most 1000000)"`
+     * @since 1.1.99
+     */
+    copyTooLarge?(maxCells: number): string;
+    /**
+     * Announced after Ctrl/⌘+X: the cells are marked and move on the next paste.
+     *
+     * @param {number} cellCount - the number of cut cells
+     * @returns {string} default: `"6 cells cut, paste to move them"`
+     * @since 1.1.99
+     */
+    cutMarked?(cellCount: number): string;
+    /**
+     * Announced when several ranges are selected and only the last one is copied (like Google Sheets).
+     *
+     * @returns {string} default: `"Only the last selected range was copied"`
+     * @since 1.1.99
+     */
+    copiedLastRangeOnly?(): string;
+    /**
+     * Announced after Ctrl/⌘+Z (undo and redo, `tableOptions.undo`).
+     *
+     * @param {string} label - the step: `"Edit"`, `"Paste"`, `"Fill"` …
+     * @param {number} cellCount - cells written back
+     * @returns {string} default: `"Undo Paste, 6 cells"`
+     * @since 1.1.99
+     */
+    undone?(label: string, cellCount: number): string;
+    /**
+     * Announced after Ctrl+Y / Ctrl/⌘+Shift+Z.
+     *
+     * @param {string} label - the step
+     * @param {number} cellCount - cells written again
+     * @returns {string} default: `"Redo Paste, 6 cells"`
+     * @since 1.1.99
+     */
+    redone?(label: string, cellCount: number): string;
+    /** @returns {string} default: `"Nothing to undo"` @since 1.1.99 */
+    nothingToUndo?(): string;
+    /** @returns {string} default: `"Nothing to redo"` @since 1.1.99 */
+    nothingToRedo?(): string;
+    /**
+     * Added to the undo/redo announcement when cells were left out (changed meanwhile, row gone, read only).
+     *
+     * @param {number} cellCount - cells left out
+     * @returns {string} default: `"2 cells skipped"`
+     * @since 1.1.99
+     */
+    undoSkipped?(cellCount: number): string;
+    /**
+     * Announced when one change has more cells than `UndoOptionsIf.maxCells`: the history is emptied.
+     *
+     * @param {number} maxCells - the limit
+     * @returns {string} default: `"This change cannot be undone (more than 1000000 cells)"`
+     * @since 1.1.99
+     */
+    undoHistoryCleared?(maxCells: number): string;
+    /**
+     * Announced when a cell formula with a syntax error is stored (it shows `#ERROR!`, `tableOptions.cellFormulas`).
+     *
+     * @param {string} message - the parser's message
+     * @returns {string} default: `"Formula error: <message>"`
+     * @since 1.1.99
+     */
+    formulaError?(message: string): string;
+    /**
+     * The label of the list of function suggestions while a cell formula is typed.
+     *
+     * @returns {string} default: `"Functions"`
+     * @since 1.1.99
+     */
+    functionSuggestions?(): string;
+    /**
+     * Announced when a reference is inserted by pointing (arrow keys or a click while typing a formula).
+     *
+     * @param {string} reference - e.g. `"B2"` or `"B2:B4"`
+     * @returns {string} default: the reference
+     * @since 1.1.99
+     */
+    referenceInserted?(reference: string): string;
+    /**
+     * Announced after rows were inserted (`TableApi.insertRows`).
+     *
+     * @param {number} count - the rows
+     * @returns {string} default: `"3 rows inserted"`
+     * @since 1.1.99
+     */
+    rowsInserted?(count: number): string;
+    /**
+     * Announced after rows were deleted (`TableApi.deleteRows`).
+     *
+     * @param {number} count - the rows
+     * @returns {string} default: `"3 rows deleted"`
+     * @since 1.1.99
+     */
+    rowsDeleted?(count: number): string;
+    /**
+     * Announced after columns were inserted (`TableApi.insertColumns`).
+     *
+     * @param {number} count - the columns
+     * @returns {string} default: `"2 columns inserted"`
+     * @since 1.1.99
+     */
+    columnsInserted?(count: number): string;
+    /**
+     * Announced after columns were deleted (`TableApi.deleteColumns`).
+     *
+     * @param {number} count - the columns
+     * @returns {string} default: `"2 columns deleted"`
+     * @since 1.1.99
+     */
+    columnsDeleted?(count: number): string;
 }

package/lib/table/batch-edit/batch-edit-service.d.ts

@@ -70,6 +70,28 @@ export declare class BatchEditService {
      * @returns {CellChangeIf[]} the cells whose pending state changed
      */
     addPending(inputs: PendingInputIf[]): CellChangeIf[];
+    /**
+     * The pending entry of a cell by row key and property (undo of a batch edit step).
+     *
+     * @param {unknown} rowKey - row object (index for models without objects)
+     * @param {string} property - the property of the column
+     * @returns {PendingCellIf | undefined} the entry
+     * @since 1.1.99
+     */
+    getPendingEntry(rowKey: unknown, property: string): PendingCellIf | undefined;
+    /**
+     * Puts pending entries back (undo/redo of a batch edit step): an entry is set as it was, none removes the cell's
+     * pending value. Reports `onBatchEditChanged` "change"; the caller repaints.
+     *
+     * @param {{ rowKey: unknown, property: string, entry?: PendingCellIf }[]} cells - the cells
+     * @returns {CellChangeIf[]} the cells with their display index (`-1` if not shown)
+     * @since 1.1.99
+     */
+    restorePending(cells: {
+        rowKey: unknown;
+        property: string;
+        entry?: PendingCellIf;
+    }[], announce?: boolean): CellChangeIf[];
     /**
      * All pending changes with the current display indices (one scan of the shown rows).
      *

package/lib/table/batch-edit/cell-change.if.d.ts

@@ -1,11 +1,15 @@
 /**
  * What started a change of cells: `"edit"` (cell editor), `"fill"` (fill handle, Ctrl/⌘+D, Ctrl/⌘+R),
- * `"commit"` ({@link TableApi.commitBatchEdit}) or `"api"` ({@link TableApi.applyCellChanges}).
+ * `"commit"` ({@link TableApi.commitBatchEdit}), `"api"` ({@link TableApi.applyCellChanges}) or – since 1.1.99 –
+ * `"clear"` (Delete/Backspace in Excel-style editing, {@link TableApi.clearCells}), `"paste"` (Ctrl/⌘+V,
+ * {@link TableApi.pasteText}), `"cut"` (pasting cut cells: target and emptied source in one change set), `"undo"` and
+ * `"redo"` ({@link TableApi.undo}, {@link TableApi.redo}), `"structure"` (rows or columns inserted or deleted,
+ * {@link TableApi.insertRows} – the changes are the formulas whose references were adjusted).
  *
  * @category Fill handle & batch edit
  * @since 1.1.96
  */
-export type CellChangeSource = "edit" | "fill" | "commit" | "api";
+export type CellChangeSource = "edit" | "fill" | "commit" | "api" | "clear" | "paste" | "cut" | "undo" | "redo" | "structure";
 /**
  * One changed cell: row, column, old and new value – the unit of a change set ({@link GeModelChangeEvent.changes},
  * {@link TableApi.getPendingChanges}). With old **and** new value it is enough for undo and redo.

package/lib/table/batch-edit/pending-cell-changes.d.ts

@@ -73,6 +73,13 @@ export declare class PendingCellChanges {
      * @returns {PendingChangeResult} what happened
      */
     set(rowKey: unknown, property: string, oldValue: unknown, newValue: unknown, rawValue: unknown, error?: string): PendingChangeResult;
+    /**
+     * Puts an entry back as it was (undo/redo of a batch edit step) – without comparing it with the old value.
+     *
+     * @param {PendingCellIf} entry - the entry
+     * @since 1.1.99
+     */
+    put(entry: PendingCellIf): void;
     /**
      * The pending entry of a cell.
      *

package/lib/table/batch-edit/write-row-value.d.ts

@@ -0,0 +1,14 @@
+import { ColumnDefIf } from '../data/tablemodel/column/column-def.if.js';
+
+/**
+ * Writes a value directly into a row object – for a commit of a row that a filter hides (no display index, so no
+ * `setValue`). The value has passed the `editInputPipe` already.
+ *
+ * @param {unknown} row - the row object (or array)
+ * @param {ColumnDefIf | undefined} columnDef - the column
+ * @param {number} columnIndex - its index (arrays)
+ * @param {unknown} value - the value
+ * @returns {boolean} true if written
+ * @internal
+ */
+export declare function writeRowValue(row: unknown, columnDef: ColumnDefIf | undefined, columnIndex: number, value: unknown): boolean;

package/lib/table/calc/column-values.d.ts

@@ -16,6 +16,8 @@ export interface ColumnValuesOwner {
         length: number;
         rows: () => ArrayLike<unknown>;
     };
+    /** True if the property holds cell formulas (since 1.1.99): formulas read it through `readPath`, not the object. */
+    isSheetFormula?(property: string): boolean;
 }
 /**
  * Resolves `valueGetter`s by property, detects cycles (`#CIRC!`), caches column aggregates.

package/lib/table/clipboard/clipboard-html.d.ts

@@ -0,0 +1,41 @@
+/**
+ * One cell for {@link toHtmlTable}: the shown text and – for numbers and dates – the number Excel and LibreOffice
+ * take instead of the formatted text (`x:num`).
+ *
+ * @category Spreadsheet
+ * @since 1.1.99
+ */
+export interface HtmlTableCellIf {
+    text: string;
+    num?: number;
+}
+/**
+ * A cell matrix as HTML `<table>` for the clipboard (`text/html`): every text escaped, line breaks as `<br>`,
+ * numbers with `x:num` (Excel keeps the number although the cell shows formatted text). DOM-free.
+ *
+ * @param {ReadonlyArray<ReadonlyArray<HtmlTableCellIf>>} matrix - rows of cells
+ * @returns {string} the HTML
+ *
+ * @example
+ * toHtmlTable([[{ text: "1,234.50 €", num: 1234.5 }]]);
+ * // '<meta charset="utf-8"><table><tbody><tr><td x:num="1234.5">1,234.50 €</td></tr></tbody></table>'
+ *
+ * @category Spreadsheet
+ * @since 1.1.99
+ */
+export declare function toHtmlTable(matrix: ReadonlyArray<ReadonlyArray<HtmlTableCellIf>>): string;
+/**
+ * The cell texts of the first `<table>` in clipboard HTML (Excel, Google Sheets). Parsed with `DOMParser` into an
+ * inert document – no element of it is ever put into the page, no script runs, images do not load; only the text
+ * of the cells is read (`<br>` = line break, `colspan` = empty cells, scripts and styles left out). Without a table or without `DOMParser`: `[]`.
+ *
+ * @param {string} html - the `text/html` content
+ * @returns {string[][]} rows of cell texts, all of the same length
+ *
+ * @example
+ * parseHtmlTable("<table><tr><td>a</td><td>1</td></tr></table>");   // [["a", "1"]]
+ *
+ * @category Spreadsheet
+ * @since 1.1.99
+ */
+export declare function parseHtmlTable(html: string): string[][];

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

@@ -0,0 +1,18 @@
+import { ShortcutActionIdMapping } from '../action/shortcut-actionid-mapping.type.js';
+
+/**
+ * The keys of copy, cut and paste ({@link TableOptionsIf.clipboard}) – a layer over the system mapping that the table
+ * only uses with the option; `tableOptions.shortcutActionIdMapping` still overrides it. Ctrl/⌘+X cuts (in the system
+ * mapping it is `DESELECT_ALL`, which stays on Ctrl/⌘+Shift+A); Windows also knows Ctrl+Insert, Shift+Delete and
+ * Shift+Insert.
+ *
+ * @param {boolean} mac - macOS keys (⌘)
+ * @returns {ShortcutActionIdMapping} the layer
+ *
+ * @example
+ * clipboardShortcutLayer(false)["ctrl+v"];   // "PASTE_FROM_CLIPBOARD"
+ *
+ * @category Spreadsheet
+ * @since 1.1.99
+ */
+export declare function clipboardShortcutLayer(mac: boolean): ShortcutActionIdMapping;

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

@@ -0,0 +1,30 @@
+import { ClipboardOptionsIf, CopyContextIf, PasteContextIf } from './clipboard-options.if.js';
+
+/**
+ * The defaults of {@link ClipboardOptionsIf} (copy, cut and paste, {@link TableOptionsIf.clipboard}).
+ *
+ * @example
+ * const options = ClipboardOptions.create({ copyHeaders: true });
+ * options?.html;   // true
+ *
+ * @category Spreadsheet
+ * @since 1.1.99
+ */
+export declare class ClipboardOptions implements ClipboardOptionsIf {
+    copyHeaders: boolean;
+    copyValue: "text" | "raw";
+    html: boolean;
+    pasteAddsRows: boolean;
+    createRow?: (index: number) => unknown;
+    maxPasteCells: number;
+    processCopy?: (ctx: CopyContextIf) => string[][] | void;
+    processPaste?: (ctx: PasteContextIf) => unknown[][] | false | void;
+    /**
+     * The options of {@link TableOptionsIf.clipboard}: `undefined`/`false` = off, `true` = the defaults, an object = the
+     * defaults overridden by its values (`undefined` keeps the default).
+     *
+     * @param {boolean | Partial<ClipboardOptionsIf>} [option] - `tableOptions.clipboard`
+     * @returns {ClipboardOptionsIf | undefined} complete options, `undefined` if the option is off
+     */
+    static create(option?: boolean | Partial<ClipboardOptionsIf>): ClipboardOptionsIf | undefined;
+}

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

@@ -0,0 +1,67 @@
+import { CellRange } from '../data/common/cell-range.js';
+
+/**
+ * What the table copies ({@link ClipboardOptionsIf.processCopy}).
+ *
+ * @category Spreadsheet
+ * @since 1.1.99
+ */
+export interface CopyContextIf {
+    /** The copied range (body display rows, model columns) – with several selected ranges the last one. */
+    readonly ranges: readonly CellRange[];
+    /** Text per cell (rows × shown columns): as shown, or the value with `copyValue: "raw"`. */
+    readonly matrix: string[][];
+    /** True for Ctrl/⌘+X. */
+    readonly cut: boolean;
+}
+/**
+ * What is pasted ({@link ClipboardOptionsIf.processPaste}).
+ *
+ * @category Spreadsheet
+ * @since 1.1.99
+ */
+export interface PasteContextIf {
+    /** The `text/plain` content (`""` if there is only HTML). */
+    readonly text: string;
+    /** The `text/html` content, if any. */
+    readonly html?: string;
+    /** The parsed cells (rows of texts). */
+    readonly matrix: string[][];
+    /** The target before tiling and cutting off: anchor cell (display row, model column) and the matrix size. */
+    readonly target: CellRange;
+    /** True if the content was copied from this table (the values are pasted, not the shown texts). */
+    readonly internal: boolean;
+}
+/**
+ * Copy, cut and paste like Excel ({@link TableOptionsIf.clipboard}). `clipboard: true` uses the defaults of
+ * {@link ClipboardOptions}; an object overrides single values.
+ *
+ * @example
+ * const tableOptions: TableOptionsIf = {
+ *   ...new TableOptions(),
+ *   getSelectionModel: () => new SelectionModel("range", "multi"),
+ *   editing: true,
+ *   clipboard: { pasteAddsRows: true, createRow: () => ({ name: "", qty: 0 }) },
+ * };
+ *
+ * @category Spreadsheet
+ * @since 1.1.99
+ */
+export interface ClipboardOptionsIf {
+    /** Copy the header labels as first row. Default `false`. */
+    copyHeaders: boolean;
+    /** `"text"`: the text as shown (default); `"raw"`: the value (a number without group separators, ISO dates). */
+    copyValue: "text" | "raw";
+    /** Also put an HTML `<table>` into the clipboard (`text/html`, numbers keep their value in Excel). Default `true`. */
+    html: boolean;
+    /** Pasting over the last row adds rows (`createRow` is needed for arrays of objects). Default `false`. */
+    pasteAddsRows: boolean;
+    /** Creates a new row for `pasteAddsRows` (the index is the display index it gets). */
+    createRow?: (index: number) => unknown;
+    /** Upper limit of pasted cells (after tiling); more are refused and announced. Default `1_000_000`. */
+    maxPasteCells: number;
+    /** Changes the copied cells (return a new matrix) – or only reads them. */
+    processCopy?: (ctx: CopyContextIf) => string[][] | void;
+    /** Changes the pasted cells (return new values), refuses the paste (`false`) – or only reads them. */
+    processPaste?: (ctx: PasteContextIf) => unknown[][] | false | void;
+}

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

@@ -0,0 +1,122 @@
+import { TableScope } from '../table-scope.js';
+import { ClipboardOptionsIf } from './clipboard-options.if.js';
+import { CellChangeIf } from '../batch-edit/cell-change.if.js';
+
+/**
+ * A clipboard action of the keyboard.
+ *
+ * @category Internals
+ * @since 1.1.99
+ */
+export type ClipboardKind = "copy" | "cut" | "paste";
+/**
+ * Copy, cut and paste like Excel ({@link TableOptionsIf.clipboard}): the `copy`, `cut` and `paste` events of the
+ * browser (synchronous, no permission prompt). The keys (Ctrl/⌘+C, X, V) focus a hidden text field for the moment of
+ * the key press, so that every browser – also Safari, which sends no clipboard events to a focused `div` – fires the
+ * event; the focus returns to the table right after it. The Edit menu of the browser works on the focused table, too.
+ * Created by {@link TableScope}: with the option (`tableScope.clipboardService`, keys and events), otherwise on
+ * demand for the API ({@link TableApi.pasteText}, {@link TableApi.getSelectionAsText}).
+ *
+ * @category Internals
+ * @since 1.1.99
+ */
+export declare class ClipboardService {
+    private readonly tableScope;
+    readonly options: ClipboardOptionsIf;
+    private proxy?;
+    private memory?;
+    private cutFrame?;
+    private restoreTimer?;
+    private armedKind?;
+    /**
+     * @param {TableScope} tableScope - the table
+     * @param {ClipboardOptionsIf} options - complete options
+     * @param {boolean} listen - true: keys and clipboard events (the option is on); false: only the API
+     */
+    constructor(tableScope: TableScope, options: ClipboardOptionsIf, listen: boolean);
+    /** True while cut cells are marked (dashed frame). */
+    isCutMarked(): boolean;
+    /**
+     * Ctrl/⌘+C, X or V (from the shortcut mapping): focuses the hidden text field so that the browser fires its
+     * clipboard event there. The key must not be consumed (`preventDefault`) – the caller returns `false`.
+     *
+     * @param {ClipboardKind} kind - the key
+     * @returns {boolean} true if the event will be handled; false: not here (the editor is open, header focus, an own
+     *          `CopyServiceIf` for copying)
+     */
+    arm(kind: ClipboardKind): boolean;
+    /**
+     * The selected cells as tab-separated text, as Ctrl/⌘+C copies them (see {@link TableApi.getSelectionAsText}).
+     *
+     * @returns {string} the text; `""` without cells or with more than `CopyService.maxCopyCells`
+     */
+    getSelectionAsText(): string;
+    /**
+     * Copies (or cuts) the selected cells with the asynchronous clipboard API (`text/plain` and `text/html` with
+     * `ClipboardItem`, otherwise `writeText`) – for buttons and menus (see {@link TableApi.copySelection}).
+     *
+     * @param {boolean} cut - true: mark the cells, they move on the next paste
+     * @returns {Promise<void>} resolves when the clipboard was written
+     */
+    writeSelection(cut: boolean): Promise<void>;
+    /**
+     * Copy, cut or paste without a key (an `ActionId` from {@link TableApi.triggerAction}, e.g. a context menu): the
+     * asynchronous clipboard API – the browser may ask for permission.
+     *
+     * @param {ClipboardKind} kind - what to do
+     * @returns {Promise<void>} resolves when done (a refused permission is ignored)
+     */
+    runWithoutKey(kind: ClipboardKind): Promise<void>;
+    /**
+     * Pastes text (see {@link TableApi.pasteText}): parsed like the clipboard, from `target` or the selection.
+     *
+     * @param {string} text - tab-separated text
+     * @param {string} [html] - `text/html` (used only without text)
+     * @param {[number, number]} [target] - display row and model column of the first cell (no tiling)
+     * @returns {CellChangeIf[]} the written (batch edit: newly pending) cells
+     */
+    paste(text: string, html?: string, target?: [number, number]): CellChangeIf[];
+    /** Removes the mark of cut cells (Escape, another change, {@link TableApi.cancelCut}); the clipboard keeps the text. */
+    cancelCut(): void;
+    /** Places the dashed frame of cut cells (after every render pass); removes it if the cut rows moved. */
+    update(): void;
+    /** Removes the hidden text field and the frame (table destroyed). */
+    destroy(): void;
+    private onClipboardEvent;
+    private restoreFocus;
+    private ensureProxy;
+    /** Stores the copy (pasting the same text pastes the values) and announces it; a cut gets its frame. */
+    private remember;
+    /** The cells of a copy: the last selected range (everything: the body), without selection the active cell. */
+    private buildCopy;
+    /** The visible data columns in display order (hidden and row number columns are skipped). */
+    private getPasteColumns;
+    /** Anchor (first row, first column) and the selected size (rows × shown columns) of a paste. */
+    private getPasteAnchor;
+    /**
+     * External text into a column without `editInputPipe`: converted like the editor of Excel-style editing – a
+     * number into a number cell (or `editor: "number"`), `TRUE`/`FALSE` into a `true`/`false` cell, an ISO date into a
+     * `Date` cell (or `editor: "date"` on a `Date`); everything else stays text. With a pipe the pipe converts.
+     */
+    private convertPastedText;
+    /**
+     * The cut cells whose values arrived (`moved`: row and column offsets in the cut range) and that are not pasted over
+     * themselves: emptied – where their rows are now (sorting, filter).
+     */
+    private cutSourceChanges;
+    /**
+     * The display index of the i-th cut row: at its old place – or, if the rows were sorted or filtered meanwhile,
+     * looked up once by row object (models without row objects: the old place).
+     */
+    private rowIndexLookup;
+    /** True for the table's own `CopyService` (an own `CopyServiceIf` or a subclass keeps the asynchronous way). */
+    private hasBuiltInCopyService;
+    private rowObjectAt;
+    private rowObjectsOf;
+    /** Rows can be added: an array of objects or arrays without grouping, tree or pivot (`getAllRows`). */
+    private canAppendRows;
+    /** Adds `count` rows from `createRow` at the end (also at the end of the displayed rows). */
+    private appendRows;
+    private showCutFrame;
+    private removeCutFrame;
+}