@guiexpert/table 1.1.94 → 1.1.96

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

@@ -13,6 +13,15 @@ import { AreaModelIf } from './data/tablemodel/areamodel/area-model.if.js';
 import { PivotConfigIf } from './pivot/pivot-config.if.js';
 import { RowGroupField } from './rowgroup/row-group-field.type.js';
 import { SelectionAggregatesIf } from './aggregation/selection-aggregates.if.js';
+import { ShowValuesAsConfig } from './calc/show-values-as.type.js';
+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 { 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';
 
 /**
  * The public API of one table – everything you do with a table after it has been created:
@@ -37,7 +46,8 @@ import { SelectionAggregatesIf } from './aggregation/selection-aggregates.if.js'
  * | sort | {@link sortByColumn}, {@link sort}, {@link reSort} |
  * | filter | {@link externalFilterChanged} (with {@link TableOptionsIf.externalFilterFunction}) |
  * | export | {@link copyToClipboard}, {@link downloadExcel} |
- * | change data | {@link updateCells}, {@link setRows}, {@link addRows}, {@link updateRows}, {@link removeRows} |
+ * | change data | {@link updateCells}, {@link setRows}, {@link addRows}, {@link updateRows}, {@link removeRows}, {@link applyCellChanges} |
+ * | fill, batch edit | {@link fillRange}, {@link startBatchEdit}, {@link getPendingChanges}, {@link commitBatchEdit}, {@link cancelBatchEdit} |
  * | redraw | {@link repaint} (same row count), {@link repaintHard} (row count or heights changed) |
  * | columns | {@link autoResizeColumns}, {@link setColumnWidth}, {@link recalcColumnWidths}, {@link getColumnIndex} |
  * | tree | {@link expandAll}, {@link collapseAll}, {@link setRowExpanded} |
@@ -529,7 +539,7 @@ export declare class TableApi {
      * @param {ActionId} actionId - The ID of the action to trigger.
      * @return {void}
      */
-    triggerAction(actionId: ActionId): void;
+    triggerAction(actionId: ActionId): boolean;
     /**
      * Retrieves the shortcut action mapping from the table's shortcut service.
      *
@@ -1297,6 +1307,69 @@ export declare class TableApi {
      * @since 1.1.94
      */
     getPivotConfig(): PivotConfigIf | undefined;
+    /**
+     * The value of a column for a row object – computed for a calculated column (`valueGetter`, `formula`), otherwise
+     * the property (path). Use it in the external filter to filter by calculated values; a `TreeRow` is unwrapped.
+     *
+     * @param {any} row - a row object (or the `TreeRow` a tree filter gets)
+     * @param {string} property - the property of the column
+     * @returns {unknown} the value (a {@link FormulaError} for a formula error)
+     *
+     * @example
+     * tableOptions.externalFilterFunction = (row: Item) => Number(tableApi.getRowValue(row, "total")) > 500;
+     * tableApi.externalFilterChanged();
+     *
+     * @since 1.1.95
+     */
+    getRowValue(row: any, property: string): unknown;
+    /**
+     * „Show values as“: shows the numbers of a column differently – share of the column total, running total, rank …
+     * (see {@link ShowValuesAs}) – or normal again (`undefined`). No new model: the table repaints.
+     *
+     * @param {string} property - the property of the column
+     * @param {ShowValuesAsConfig | undefined} showValuesAs - the mode (with options) or `undefined` for the values
+     * @returns {boolean} false if there is no such column or the mode is unknown
+     *
+     * @example
+     * select.addEventListener("change", () =>
+     *   tableApi.setShowValuesAs("total", select.value ? select.value as ShowValuesAs : undefined));
+     *
+     * @since 1.1.95
+     */
+    setShowValuesAs(property: string, showValuesAs: ShowValuesAsConfig | undefined): boolean;
+    /**
+     * „Show values as“ of a column.
+     *
+     * @param {string} property - the property of the column
+     * @returns {ShowValuesAsConfig | undefined} the configuration, `undefined` for none
+     *
+     * @example
+     * const mode = tableApi.getShowValuesAs("total");   // "percentOfColumnTotal"
+     *
+     * @since 1.1.95
+     */
+    getShowValuesAs(property: string): ShowValuesAsConfig | undefined;
+    /**
+     * Sets (or replaces) the formula of a column – e.g. from an input field of your app. The formula is compiled
+     * once; an invalid formula is set anyway (the cells show `#ERROR!` / `#NAME?`) and its error is returned, so you can
+     * show the message next to the input. No code is ever executed (no `eval`). The table repaints; totals, sorting
+     * and filter see the new values after `repaint`, `reSort()` resp. `externalFilterChanged()`.
+     *
+     * @param {string} property - the property of the column (it becomes a calculated column)
+     * @param {string} formula - the formula, e.g. `"[price] * [quantity] * 1.19"`
+     * @param {FormulaOptionsIf} [options] - own functions
+     * @returns {FormulaError | undefined} the error of the formula itself, `undefined` if it is valid
+     *   (`#NAME?` also if there is no such column)
+     *
+     * @example
+     * input.addEventListener("change", () => {
+     *   const error = tableApi.setColumnFormula("custom", input.value);
+     *   hint.textContent = error ? `${error.code} ${error.message}` : "";
+     * });
+     *
+     * @since 1.1.95
+     */
+    setColumnFormula(property: string, formula: string, options?: FormulaOptionsIf): FormulaError | undefined;
     /**
      * Sorts the table data using a custom comparison function.
      *
@@ -1347,6 +1420,208 @@ export declare class TableApi {
      * tableApi.sort((a: TreeRowIf<OrderNode>, b: TreeRowIf<OrderNode>) => b.data.total - a.data.total);
      */
     sort(compareFn: (a: any, b: any) => number): void;
+    /**
+     * Moves body rows – the code way to do what row drag does (e.g. "up"/"down" buttons, the pointer alternative of
+     * WCAG 2.5.7, or after the server confirmed an unmanaged drag). The body model must support it
+     * ({@link AreaModelIf.moveRows}: object arrays, arrays of arrays, trees); no filter may hide rows and no column may be
+     * sorted (asc/desc – a sorted view has no order of its own). Focus and a multi-row selection follow the rows; screen
+     * readers hear "Row moved to position 7 of 20". No row drag events. `false` if nothing moved (also for a target
+     * where the rows already are).
+     *
+     * @param {number[] | number} rowIndices - display index or indices of the rows to move
+     * @param {RowDropTargetIf | number} target - drop target; a number = in front of that display index
+     *        (`getDisplayedRowCount()` = behind the last row)
+     * @returns {boolean} true if the rows were moved
+     *
+     * @example
+     * tableApi.moveRows(2, { rowIndex: 6, position: "after" });   // row 3 becomes row 7
+     * tableApi.moveRows([0, 1], tableApi.getDisplayedRowCount());   // the first two rows to the end
+     *
+     * @example
+     * // unmanaged drag: the server decides, then the table moves the rows
+     * const listener = new EventAdapter();
+     * listener.onRowDragEnd = async (evt: GeRowDragEvent) => {
+     *   if (evt.type === "end" && evt.target && (await fetch("/api/move", { method: "POST" })).ok) {
+     *     tableApi.moveRows(evt.rowIndices, evt.target);
+     *   }
+     * };
+     *
+     * @since 1.1.95
+     */
+    moveRows(rowIndices: number[] | number, target: RowDropTargetIf | number): boolean;
+    /**
+     * True while rows are dragged with the pointer (mouse, touch, pen).
+     *
+     * @returns {boolean} true during a row drag
+     *
+     * @example
+     * if (!tableApi.isRowDragging()) {
+     *   tableApi.updateCells([], true);   // e.g. live data: wait until the drag is done
+     * }
+     *
+     * @since 1.1.95
+     */
+    isRowDragging(): boolean;
+    /**
+     * Cancels a running row drag (like Escape): nothing is moved, `onRowDragEnd` gets the type `"cancel"`.
+     *
+     * @example
+     * tableApi.cancelRowDrag();   // e.g. new data arrived from the server
+     *
+     * @since 1.1.95
+     */
+    cancelRowDrag(): void;
+    /**
+     * Writes values into body cells like the cell editor does – the one way the table changes cells (editor, fill
+     * handle and batch commit use it too): cells that are not editable are skipped (`editable`, calculated columns
+     * without `valueSetter`, group and pivot rows), values run through `editInputPipe` and {@link ColumnDefIf.validate}
+     * (invalid ones are not written), totals and calculated columns follow, and **one** `onModelChanged` reports all
+     * cells with old and new values. In a batch edit the values are marked as pending instead.
+     *
+     * Paste from the clipboard and undo/redo can be built on it: a {@link CellChangeIf} has the old and the new value.
+     *
+     * @param {CellValueChangeIf[]} changes - display row index, column (index or property) and value per cell
+     * @param {CellChangeSource} [source="api"] - reported in {@link GeModelChangeEvent.source}
+     * @returns {CellChangeIf[]} the written (batch edit: newly pending) cells
+     *
+     * @example
+     * tableApi.applyCellChanges([
+     *   { rowIndex: 0, column: "price", value: 9.9 },
+     *   { rowIndex: 1, column: "price", value: 12 },
+     * ]);
+     *
+     * @example
+     * // undo the last change set (from onModelChanged)
+     * const undo = (changes: CellChangeIf[]) => tableApi.applyCellChanges(
+     *   changes.map(c => ({ rowIndex: c.rowIndex, column: c.property, value: c.oldValue })));
+     *
+     * @since 1.1.96
+     */
+    applyCellChanges(changes: CellValueChangeIf[], source?: CellChangeSource): 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
+     * {@link applyCellChanges} (one `onModelChanged`, source `"fill"`) and selects source and filled cells.
+     *
+     * @param {CellRange} source - the source range (body display indices)
+     * @param {FillDirection} direction - `"down"`, `"up"`, `"right"` or `"left"`
+     * @param {number} count - rows or columns to fill (clamped to the table)
+     * @param {FillMode} [mode="auto"] - `"auto"`, `"alternate"` (like ⌥/Alt while dragging) or `"copy"`
+     * @returns {number} the number of filled cells (batch edit: marked); `-1` if more than `maxCells`
+     *
+     * @example
+     * // rows 0 and 1 of column 2 hold 1 and 2: rows 2…9 get 3…10
+     * tableApi.fillRange(new CellRange(0, 2, 1, 2), "down", 8);
+     *
+     * @since 1.1.96
+     */
+    fillRange(source: CellRange, direction: FillDirection, count: number, mode?: FillMode): number;
+    /**
+     * True while the fill handle is dragged.
+     *
+     * @returns {boolean} true during a fill
+     *
+     * @example
+     * if (!tableApi.isFilling()) {
+     *   tableApi.updateCells([], true);   // e.g. live data: wait until the fill is done
+     * }
+     *
+     * @since 1.1.96
+     */
+    isFilling(): boolean;
+    /**
+     * Cancels a running fill (like Escape): nothing is changed.
+     *
+     * @example
+     * tableApi.cancelFill();
+     *
+     * @since 1.1.96
+     */
+    cancelFill(): void;
+    /**
+     * Starts a batch edit: from now on edited and filled values are **collected** – shown in the cells (class
+     * `ge-table-cell-pending`), but not written into your rows – until {@link commitBatchEdit} or
+     * {@link cancelBatchEdit}. Sorting, filtering, totals, copy and Excel use the written data. For a batch edit that is
+     * always on use {@link TableOptionsIf.batchEdit}.
+     *
+     * @returns {boolean} false if a batch edit is already running
+     *
+     * @example
+     * editButton.onclick = () => tableApi.startBatchEdit();
+     * saveButton.onclick = () => tableApi.commitBatchEdit();
+     * discardButton.onclick = () => tableApi.cancelBatchEdit();
+     *
+     * @since 1.1.96
+     */
+    startBatchEdit(): boolean;
+    /**
+     * True while values are collected (after {@link startBatchEdit}, or always with {@link TableOptionsIf.batchEdit}).
+     *
+     * @returns {boolean} whether a batch edit runs
+     *
+     * @example
+     * saveButton.hidden = !tableApi.isBatchEditing();
+     *
+     * @since 1.1.96
+     */
+    isBatchEditing(): boolean;
+    /**
+     * True if a batch edit has values that are not written yet.
+     *
+     * @returns {boolean} whether there are pending changes
+     *
+     * @example
+     * window.addEventListener("beforeunload", evt => {
+     *   if (tableApi.hasPendingChanges()) evt.preventDefault();   // "Leave site? Changes may not be saved."
+     * });
+     *
+     * @since 1.1.96
+     */
+    hasPendingChanges(): boolean;
+    /**
+     * The values of a batch edit that are not written yet: row object, property, old and new value, the current display
+     * index (`-1` while a filter hides the row) and the message of an invalid value. The changes belong to the rows, not
+     * to their positions – sorting and filtering don't mix them up.
+     *
+     * @returns {CellChangeIf[]} the pending cells
+     *
+     * @example
+     * saveButton.onclick = async () => {
+     *   const changes = tableApi.getPendingChanges()
+     *     .map(c => ({ id: (c.row as { id: number }).id, field: c.property, value: c.newValue }));
+     *   const response = await fetch("/api/prices", { method: "PATCH", body: JSON.stringify(changes) });
+     *   if (response.ok) tableApi.commitBatchEdit();
+     * };
+     *
+     * @since 1.1.96
+     */
+    getPendingChanges(): CellChangeIf[];
+    /**
+     * Writes the pending values of a batch edit into the rows (through `setValue`, like the editor) and ends a batch edit
+     * started with {@link startBatchEdit}: **one** `onModelChanged` (source `"commit"`) with all cells, then
+     * `onBatchEditChanged` with the type `"commit"`. While a value is invalid ({@link ColumnDefIf.validate}) nothing is
+     * written and the result is `false` (unless {@link BatchEditOptionsIf.blockCommitOnInvalid} is `false`).
+     *
+     * @returns {boolean} true if written
+     *
+     * @example
+     * if (!tableApi.commitBatchEdit()) {
+     *   alert("Please fix the marked cells first.");
+     * }
+     *
+     * @since 1.1.96
+     */
+    commitBatchEdit(): boolean;
+    /**
+     * Discards the pending values of a batch edit (the cells show the data again) and ends a batch edit started with
+     * {@link startBatchEdit}.
+     *
+     * @example
+     * discardButton.onclick = () => tableApi.cancelBatchEdit();
+     *
+     * @since 1.1.96
+     */
+    cancelBatchEdit(): void;
     /**
      * Ensures that a specific row is visible in the viewport by scrolling if necessary.
      * This method checks if the target row is within the currently visible range and

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

@@ -36,6 +36,13 @@ import { ResizeHandler } from './resize-handler.js';
 import { ExcelServiceIf } from './service/excel-service.if.js';
 import { ColumnDefIf } from './data/tablemodel/column/column-def.if.js';
 import { LiveAnnouncer } from './aria/live-announcer.js';
+import { FillHandleOptionsIf } from './fill/fill-handle-options.if.js';
+import { CellChangeIf, CellChangeSource } from './batch-edit/cell-change.if.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 { AriaTextsIf } from './aria/aria-texts.if.js';
 
 /**
  * Creates and runs one table in a host element – the core that every framework wrapper uses.
@@ -146,6 +153,21 @@ 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 event listener of this table (the one given to the constructor, or an empty {@link EventAdapter}).
+     *
+     * @returns {EventListenerIf} the listener
+     * @since 1.1.95
+     */
+    getEventListener(): EventListenerIf;
+    /**
+     * Called after rows were moved in the body model (row drag, {@link TableApi.moveRows}): drops derived values
+     * (totals, „Show values as“) and forgets a sort function of `tableApi.sort(fn)` – the moved order wins.
+     * The caller repaints.
+     *
+     * @since 1.1.95
+     */
+    afterRowsMoved(): void;
     /**
      * Speaks a message to screen reader users (polite live region, see {@link LiveAnnouncer}).
      *
@@ -223,7 +245,106 @@ export declare class TableScope extends RenderScope implements OnActionTriggered
      *        first, so the blur caused by closing does not commit the typed text ("change" event)
      */
     cancelEditing(editor?: HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement): void;
+    /**
+     * Writes the text of a cell editor (called by the input handler on "change"). Batch edit: the value is marked as
+     * pending instead. Uses {@link applyCellChanges} – one `onModelChanged` per edit, as before.
+     *
+     * @param {AreaIdent} areaIdent - only `"body"` is edited
+     * @param {number} rowIndex - display index
+     * @param {number} columnIndex - model index
+     * @param {string} value - the text of the editor
+     */
     updateModelValueAfterEdit(areaIdent: AreaIdent, rowIndex: number, columnIndex: number, value: string): void;
+    /**
+     * The one place that changes body cells (editor, fill handle, batch commit, {@link TableApi.applyCellChanges}):
+     * skips cells that are not editable (`editable`, calculated columns without `valueSetter`, group/pivot rows),
+     * applies `editInputPipe` and {@link ColumnDefIf.validate}, then writes – or, in a batch edit, marks the values as
+     * pending. Writing reports **one** `onModelChanged` with all cells; derived values (totals, calculated columns) are
+     * recomputed and the table repaints.
+     *
+     * @param {CellValueChangeIf[]} changes - cells and values (column as index or property)
+     * @param {CellChangeSource} [source="api"] - reported in the event
+     * @returns {CellChangeIf[]} the written (or, in a batch edit, newly pending) cells
+     * @since 1.1.96
+     */
+    applyCellChanges(changes: CellValueChangeIf[], source?: CellChangeSource): CellChangeIf[];
+    /**
+     * Writes cell values directly (no batch edit) – used by {@link applyCellChanges} and the batch commit.
+     *
+     * @param {{ rowIndex: number, columnIndex: number, value: unknown }[]} cells - resolved cells (display/model indices)
+     * @param {CellChangeSource} source - reported in the event
+     * @param {{ extraChanges?: CellChangeIf[], skipValidation?: boolean }} [opts] - changes written elsewhere (reported
+     *        in the same event), no validation (commit: already checked)
+     * @returns {CellChangeIf[]} the written cells (including `extraChanges`)
+     * @since 1.1.96
+     */
+    writeCells(cells: {
+        rowIndex: number;
+        columnIndex: number;
+        value: unknown;
+    }[], source: CellChangeSource, opts?: {
+        extraChanges?: CellChangeIf[];
+        skipValidation?: boolean;
+    }): CellChangeIf[];
+    private writeCellsInternal;
+    /** Marks values as pending (batch edit): pipe, validation, then the batch edit service. */
+    private markPending;
+    /**
+     * Column property → index, range check, editable check (not for the editor: it was opened on an editable cell).
+     */
+    private resolveCellChanges;
+    /** The value after the column's `editInputPipe` (as `setValue` will store it). */
+    private pipeCellValue;
+    /** The message of {@link ColumnDefIf.validate} – `undefined` if valid or without validator. */
+    private validateCellValue;
+    /** The row object of a body row for events: the data of a `TreeRow`, `undefined` without objects. */
+    private rowObjectOf;
+    /**
+     * The options of the fill handle, `undefined` if it is off ({@link TableOptionsIf.fillHandle}).
+     *
+     * @returns {FillHandleOptionsIf | undefined} complete options
+     * @since 1.1.96
+     */
+    getFillHandleOptions(): FillHandleOptionsIf | undefined;
+    /**
+     * Fills cells next to a range (fill handle, Ctrl/⌘+D, {@link TableApi.fillRange}): computes the values
+     * ({@link computeFillChanges}, shown values – a batch edit's pending values count), writes them with
+     * {@link applyCellChanges} and selects source and filled cells.
+     *
+     * @param {CellRange} source - the source range (body display indices)
+     * @param {FillDirection} direction - down, up, right or left
+     * @param {number} count - rows or columns to fill (clamped to the table)
+     * @param {FillMode} [mode="auto"] - series or copy
+     * @param {CellRange} [selectAfter] - the selection afterwards (default: source and filled cells)
+     * @returns {number} the number of filled (or, in a batch edit, marked) cells; `-1` if refused (too many cells)
+     * @since 1.1.96
+     */
+    fillRange(source: CellRange, direction: FillDirection, count: number, mode?: FillMode, selectAfter?: CellRange): number;
+    /** The last selected range, clamped to the body (`undefined` without one). */
+    getFillSourceRange(): CellRange | undefined;
+    private normalizeRange;
+    /**
+     * Ctrl/⌘+D (down) and Ctrl/⌘+R (right): the first row (column) of the selected range is copied into the rest; a
+     * range of one row (column) gets the cell above (left of) it – like a spreadsheet.
+     *
+     * @param {"down" | "right"} direction - the key
+     * @returns {boolean} true if the key was used (the browser's own action – bookmark, reload – is prevented then)
+     */
+    private fillByKeyboard;
+    /**
+     * Sets `aria-keyshortcuts` of the host (the fill handle's keyboard alternative); removed again by {@link destroy}.
+     *
+     * @param {string | undefined} value - e.g. `"Control+D Control+R"`; `undefined` restores the value before
+     * @since 1.1.96
+     */
+    setHostKeyShortcuts(value: string | undefined): void;
+    /**
+     * The texts of fill and batch edit with defaults (an own {@link AriaTextsIf} implementation may lack them).
+     *
+     * @returns the texts
+     * @since 1.1.96
+     */
+    getEditTexts(): Required<Pick<AriaTextsIf, 'cellsFilled' | 'fillTooLarge' | 'pendingChanges' | 'changesCommitted' | 'changesDiscarded' | 'commitBlocked' | 'invalidValue'>>;
     /**
      * Retrieves the TableApi object.
      *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guiexpert/table",
-  "version": "1.1.94",
+  "version": "1.1.96",
   "license": "MIT",
   "author": "Dr. Marc Kronberg <info@gui.expert> (https://gui.expert)",
   "repository": {