@guiexpert/table 1.1.107 → 1.1.108

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

@@ -28,6 +28,7 @@ import { EventListenerIf } from './event-listener.if.js';
 import { ExcelExportOptionsIf } from './service/excel-export-options.if.js';
 import { SheetEngine } from './sheet/sheet-engine.js';
 import { ScrollPositionIf } from './data/common/scroll-position.if.js';
+import { AppendRowsOptionsIf, AppendRowsResultIf, RowsAppendedOptionsIf } from './live-append/append-rows-options.if.js';
 
 /**
  * The public API of one table – everything you do with a table after it has been created:
@@ -201,7 +202,7 @@ export declare class TableApi {
      * };
      *
      * // Initialize your table with these options
-     * const tableApi = new TableApi(tableScope);
+     * const tableApi = tableScope.getApi();
      *
      * // Later, when filter criteria change (e.g., in a search input handler)
      * function onFilterTextChanged() {
@@ -433,7 +434,7 @@ export declare class TableApi {
      *
      * @example
      * // Update data and repaint the table
-     * const tableApi = new TableApi(tableScope);
+     * const tableApi = tableScope.getApi();
      * tableApi.setRows(newData);
      * tableApi.repaint();
      *
@@ -905,7 +906,7 @@ export declare class TableApi {
      *
      * @example
      * // Access the TableScope to perform a custom operation
-     * const tableApi = new TableApi(myTableScope);
+     * const tableApi = myTableScope.getApi();
      * const tableScope = tableApi.getTableScope();
      *
      * // Example: Manually trigger a context menu at a specific location
@@ -1040,6 +1041,8 @@ export declare class TableApi {
      * Only works with an {@link AreaModelObjectArray} body – logs a console warning otherwise.
      * Does **not** repaint and resets filtering and sorting of the body: afterwards call
      * {@link externalFilterChanged} (if a filter function is set) and {@link repaintHard} (the row count changed).
+     * Copies all rows (O(n)) – for live data (rows arriving all the time) use {@link appendRows}: in place, filter and
+     * order only for the new rows, selection and position stay.
      *
      * @template T - The type of elements in the rows array
      * @param {T[]} rows - An array of data objects to append to the table's existing rows
@@ -1056,6 +1059,81 @@ export declare class TableApi {
      * tableApi.repaintHard();
      * tableApi.ensureRowIsVisible(tableApi.getDisplayedRowCount() - 1);
      */
+    /**
+     * **Live data** (a log tail, a ticker – since 1.1.108): appends rows to the body and shows them in **one** render
+     * pass – O(k) for k new rows, not O(n).
+     *
+     * - **In place**: the rows are pushed to your array (`getAllRows()`), nothing is copied.
+     * - **Filter and order** (`externalFilterFunction`, a sorted column or `sort(fn)`) apply to the new rows only:
+     *   filtered rows are kept but not shown, sorted rows are merged in (O(n + k), behind equal rows).
+     * - **Selection, focus, anchor, checked rows** stay at their rows (the indices move along; no `onSelectionChanged`
+     *   unless a selected row was removed).
+     * - **Position**: `follow: "auto"` (default) stays at the end if the view was at the end ("tail -f"), otherwise the
+     *   first visible row stays; `true` = always the end, `false` = always keep the row ("freeze scroll"). While the
+     *   mouse button is held in the table, `"auto"` keeps the row.
+     * - **Ring buffer**: `maxRows` removes the oldest rows from the start.
+     * - Rows behind the visible ones (a reader in the middle of the log): the cells are not rebuilt – only scroll height
+     *   and scroll bar change.
+     *
+     * Works with an {@link AreaModelObjectArray} body (`TableFactory.createTableModel({ rows, … })`) without cell
+     * formulas; a tree, row grouping, pivot or spreadsheet → `false` and a console warning. Own area model:
+     * {@link rowsAppended}.
+     *
+     * @param {T[]} rows - the new rows (appended in this order)
+     * @param {AppendRowsOptionsIf} [options] - `follow` ("auto" | true | false), `maxRows`
+     * @returns {AppendRowsResultIf | false} `{ added, shown, removed, following }`, or false
+     *
+     * @example
+     * // a log viewer: new lines every animation frame, at most one million
+     * const result = tableApi.appendRows(newLines, { follow: "auto", maxRows: 1_000_000 });
+     * if (result && !result.following) {
+     *   console.log(`+${result.shown} new lines below`);
+     * }
+     *
+     * @example
+     * // "Freeze scroll" / "Scroll to end" buttons of the app
+     * let frozen = false;
+     * function onLines(lines: { time: string; text: string }[]) {
+     *   tableApi.appendRows(lines, { follow: frozen ? false : "auto" });
+     * }
+     * function scrollToEnd() {
+     *   frozen = false;
+     *   tableApi.repaintHard({ py: Number.MAX_SAFE_INTEGER });
+     * }
+     *
+     * @since 1.1.108
+     */
+    appendRows<T>(rows: T[], options?: AppendRowsOptionsIf): AppendRowsResultIf | false;
+    /**
+     * **Live data with an own area model** (since 1.1.108): your model appended `count` rows at the end (and maybe
+     * removed `removedAtStart` rows at the start) – the table moves selection, focus and anchor along, keeps the first
+     * visible row or follows the end (`follow` as in {@link appendRows}) and renders once (not at all if only rows behind
+     * the visible ones came in). Filtering and sorting are up to your model.
+     *
+     * @param {number} count - rows appended at the end
+     * @param {RowsAppendedOptionsIf} [options] - `follow`, `removedAtStart`
+     * @returns {AppendRowsResultIf} `{ added, shown, removed, following }`
+     *
+     * @example
+     * class LogBody extends AreaModel {
+     *   readonly lines: string[] = [];
+     *   override getRowCount(): number { return this.lines.length; }
+     *   override getRowHeight(): number { return 20; }
+     *   override getConstantRowHeight(): number { return 20; }
+     *   override getValueAt(row: number): string { return this.lines[row]; }
+     * }
+     * const body = new LogBody();
+     *
+     * function onNewLines(newLines: string[]) {
+     *   for (const line of newLines) body.lines.push(line);      // a loop: push(...lines) overflows above ~100,000
+     *   const dropped = Math.max(0, body.lines.length - 1_000_000);
+     *   body.lines.splice(0, dropped);                            // the app's own ring buffer
+     *   tableApi.rowsAppended(newLines.length, { follow: "auto", removedAtStart: dropped });
+     * }
+     *
+     * @since 1.1.108
+     */
+    rowsAppended(count: number, options?: RowsAppendedOptionsIf): AppendRowsResultIf;
     addRows<T>(rows: T[]): void;
     /**
      * Inserts new rows at a specific position in the table body.
@@ -2342,7 +2420,7 @@ export declare class TableApi {
      * @example
      * ```typescript
      * // Get the first visible row index
-     * const tableApi = new TableApi(tableScope);
+     * const tableApi = tableScope.getApi();
      * const firstVisibleIndex = tableApi.getFirstVisibleRowIndex();
      *
      * // Use the index for scroll position calculations

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

@@ -2,6 +2,7 @@ import { TableOverlayChange } from './overlay/table-overlay.js';
 import { GeOverlayKind } from './overlay/ge-overlay-kind.type.js';
 import { TableModelIf } from './data/tablemodel/table-model.if.js';
 import { AreaIdent } from './data/tablemodel/area-ident.type.js';
+import { SideIdent } from './data/side-ident.type.js';
 import { GeMouseEvent } from './data/common/event/ge-mouse-event.js';
 import { DomServiceIf } from './service/dom-service.if.js';
 import { TableOptionsIf } from './data/options/table-options.if.js';
@@ -50,6 +51,7 @@ 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';
+import { AppendRowsOptionsIf, AppendRowsResultIf, RowsAppendedOptionsIf } from './live-append/append-rows-options.if.js';
 
 /**
  * Creates and runs one table in a host element – the core that every framework wrapper uses.
@@ -130,6 +132,8 @@ 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?;
+    /** Live data: the content position held while the mouse button was down in a view that followed the end. */
+    private followHeldAt?;
     /** Excel-style editing (`tableOptions.editing`), `undefined` = off. @since 1.1.99 */
     private readonly editingOptions?;
     /** Listeners of {@link TableApi.subscribe}. @since 1.1.99 */
@@ -750,6 +754,22 @@ export declare class TableScope extends RenderScope implements OnActionTriggered
      * @return {GeMouseEvent} - The created GeMouseEvent object.
      */
     createGeMouseEvent(mouseEvent: MouseEvent): GeMouseEvent;
+    /**
+     * Creates a GeMouseEvent for a given cell – used when the cell element of a mouse event is gone (a render replaced
+     * it between mousedown and mouseup, see {@link MouseHandler}) and the cell is known from the mousedown.
+     *
+     * @param mouseEvent - the original browser event
+     * @param cell - area, side, row and column of the cell, and the action of the pressed element
+     * @returns the event with row/column positions of the cell
+     * @since 1.1.108
+     */
+    createGeMouseEventForCell(mouseEvent: MouseEvent, cell: {
+        areaIdent?: AreaIdent;
+        sideIdent?: SideIdent;
+        rowIndex: number;
+        columnIndex: number;
+        action: string | null;
+    }): GeMouseEvent;
     /**
      * The element a mouse event belongs to – usually `evt.target`. The scroll viewport lies above the footer areas (its
      * horizontal scroll bar must stay usable), so a mouse event on a footer cell arrives at the viewport: then the footer
@@ -1039,6 +1059,37 @@ export declare class TableScope extends RenderScope implements OnActionTriggered
     private setAreaVisible;
     autoResizeColumns(recalcWrappers?: boolean): void;
     recalcWrappers(): void;
+    /**
+     * Live data (since 1.1.108): appends rows to an {@link AreaModelObjectArray} body in place – filter and sort order
+     * only for the new rows, optional ring buffer – moves selection, focus and anchor along, keeps the first visible row
+     * or follows the end, and renders once (not at all if only rows behind the visible ones came in).
+     * See {@link TableApi.appendRows}.
+     *
+     * @param {T[]} rows - the new rows
+     * @param {AppendRowsOptionsIf} [options] - follow mode, ring buffer
+     * @returns {AppendRowsResultIf | false} what changed; false (with a warning) for other bodies (tree, row groups,
+     *   pivot, spreadsheet, cell formulas)
+     */
+    appendRows<T>(rows: T[], options?: AppendRowsOptionsIf): AppendRowsResultIf | false;
+    /**
+     * Live data (since 1.1.108): an own area model appended `count` rows at the end (and maybe removed some at the
+     * start) – moves selection, focus and anchor along, keeps the first visible row or follows the end, renders once.
+     * See {@link TableApi.rowsAppended}.
+     *
+     * @param {number} count - rows the model appended at the end (display order)
+     * @param {RowsAppendedOptionsIf} [options] - follow mode, rows removed at the start
+     * @returns {AppendRowsResultIf} what changed
+     */
+    notifyRowsAppended(count: number, options?: RowsAppendedOptionsIf): AppendRowsResultIf;
+    /** The order new rows are sorted in: the last `sort(fn)`, otherwise the columns with a sort state. */
+    protected getActiveSortComparator(): ((a: unknown, b: unknown) => number) | undefined;
+    /** Moves the index-based state along, chooses the position and renders once (or only updates the row count). */
+    private afterRowsAppended;
+    /**
+     * True if nothing else on the screen depends on the row count: no row number column (its width may grow), no
+     * totals footer, no calculated/„show values as“ columns, no open detail rows.
+     */
+    private canKeepDrawnRows;
     reSort(): void;
     sort(compareFn: (a: any, b: any) => number): void;
     /**